Skip to content

feat(sight): add unified summary command#796

Open
jfeng18 wants to merge 1 commit into
alibaba:mainfrom
jfeng18:feat/agentsight-summary
Open

feat(sight): add unified summary command#796
jfeng18 wants to merge 1 commit into
alibaba:mainfrom
jfeng18:feat/agentsight-summary

Conversation

@jfeng18

@jfeng18 jfeng18 commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

What

Adds agentsight summary — one command that rolls up the headline numbers from the three observability streams agentsight + tokenless already record, into a single glanceable report:

AgentSight Summary (last 24h)

Sessions      6
  Tokens      145 in / 114 out / 259 total

Interruptions 8
  critical    0
  high        4
  medium      4
  low         0

Tokenless     83% saved (121.0K -> 20.6K, 43 ops)
  • --last N (hours, default 24) and --json. Text and JSON report identical numbers for the same data.
  • Each data source degrades independently: a missing / unreadable / wrong-schema database contributes zeros (tokenless: an explicit "not available" note) rather than aborting the whole report. The command always exits 0, so it is safe to run on a fresh box.

Why

The three streams (sessions+tokens, interruptions, tokenless savings) each live behind their own subcommand and database. There was no single "how are my agents doing right now" view; tokenless savings in particular were effectively invisible. summary surfaces all of it at a glance.

How

  • New bin/cli/summary.rs (SummaryCommand).
  • New TokenlessStatsStore::summary_in_window: aggregates stats.db savings over a time window. stats.db stores RFC3339 text timestamps, so it normalises each row to UTC epoch seconds via strftime('%s', ...) — robust to the stored timezone offset rather than relying on lexicographic string comparison.
  • Wires the subcommand into agentsight.rs / cli/mod.rs and re-exports the new type from storage/sqlite/mod.rs.

No changes to BPF probes, the collection pipeline, other subcommands, or the tokenless crate.

Testing

E2E on a host with a live collector + real databases (cross-checked against direct SQL — exact match):

  • 24h / 168h text + --json: sessions, interruptions-by-severity, and tokenless totals all match raw SQL.
  • Window discrimination: tokenless data outside 24h is excluded, included at 168h.
  • Graceful degradation: stats.db absent → "not available"; --last 0 empty window; --help.
  • --last u64::MAX: degrades to "everything", no overflow/inverted window.
  • Negative-token (corrupt synthetic stats.db): text and JSON both clamp to 0 — consistent.
  • Concurrency: 30 rapid runs while the collector was actively writing → 0 spurious zeros.

Unit tests (the live collector holds the real genai/interruption DBs open, so the missing/corrupt cases for those are covered by path-injection unit tests rather than by moving production data):

  • summary_in_window: timezone normalisation, empty window, missing-table degradation.
  • build_json: clamp contract (negative → 0, identical to text).
  • time_range_ns: saturating math (no inversion for absurd --last).
  • Independent degradation matrix: each of the three sources, missing-file and wrong-schema → zeros, no panic.

Verification status

  • E2E: all of the above on a real host
  • Unit: 9 discriminating tests (cargo test, local + on the host)
  • cargo clippy clean on the new code (note: agentsight's CI runs cargo test, not clippy/fmt)

Known limitation (tracked separately)

Under heavy write contention summary (like every agentsight DB reader) could transiently report zeros, because the shared create_connection sets no busy_timeout. This pre-dates this change and affects all readers, so it's deferred to its own focused PR rather than bundled here. Not observed in 30/30 live runs.

🤖 Generated with Claude Code

@jfeng18 jfeng18 requested a review from chengshuyi as a code owner June 9, 2026 06:09
@github-actions github-actions Bot added the component:sight src/agentsight/ label Jun 9, 2026
`agentsight summary` rolls up the headline numbers from the three
observability streams agentsight + tokenless already record into one
glanceable report:

  * Sessions & token usage    (genai_events.db)
  * Interruptions by severity (interruption_events.db)
  * Tokenless savings         (~/.tokenless/stats.db)

Each data source degrades independently: a missing/unreadable/wrong-schema
database contributes zeros (tokenless: an explicit "not available" note)
rather than aborting the whole report, so the command always exits 0.

Supports `--last N` (hours, default 24) and `--json`. The text and JSON
views report identical numbers for the same data (both clamp).

Adds TokenlessStatsStore::summary_in_window, which aggregates stats.db
savings over a time window. stats.db stores RFC3339 text timestamps, so
it normalises each row to UTC epoch seconds via strftime('%s', ...) —
robust to the stored timezone offset rather than relying on lexicographic
string comparison.

Tested: unit tests for the windowed aggregate (timezone normalisation,
graceful degradation), the JSON/text clamp contract, the independent
degradation matrix (each source missing or wrong-schema), and saturating
window math for absurd --last; end-to-end on a host with a live collector,
cross-checked against direct SQL.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@jfeng18 jfeng18 force-pushed the feat/agentsight-summary branch from f9ed28b to c41b51c Compare June 10, 2026 03:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component:sight src/agentsight/

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant