[stats] Per-agent Stats tab — declarative card schema over a closed, owner-scoped source vocabulary

[serge-ivo]

Scoped 2026-08-07 after review. Two changes, detailed in the comment below:

1. The platform-default cards are dropped. /v1/usage, the Activity tab, the Board and
   /v1/dashboard already cover tokens, cost, events and board counts. Re-rendering them per
   agent is polish. The value is the agent-declared domain metrics — "leads by suburb over
   time", "runs by outcome" — which nothing shows today.
2. Trend cards are served from a daily rollup ([stats] Daily rollup — the only way to get a series for agent-defined collections (and a gap is not a zero) #313), not live aggregates. For agent-defined
   collections a snapshot is the only way to get a series at all, so this is load-bearing rather
   than an optimisation. Cards split into trend (rollup) and point-in-time (live).

The "Platform defaults" and "Cost" sections below are superseded by those two points; everything
else — cards as data, the closed source vocabulary, and the ownership rule — stands unchanged.

---

Each agent gets a Stats tab: graphs and the numbers that matter for that agent, configurable
by the subscriber, by MCP, or by the agent itself on request.

This is the core: the data model, the source vocabulary, and the resolver. Console rendering is
#(B), configuration surfaces are #(C).

Design principle — cards are data, not code

The house pattern is already established and should not be re-invented here: surfaces come from
capabilities.surfaces, tools from capabilities.tools + the registry, subscriber settings from
settingsSchema (sanitizeSettingsSchema, capped at MAX_SETTINGS_FIELDS), board columns from
capabilities.boardColumns, character from BEHAVIOUR_FIELDS.

A stats page built as a hardcoded dashboard would be the same mistake as the technicality heuristic
and the tmux prose: behaviour asserted in code that drifts from what the agent actually is.

So: statsSchema is a table of card definitions, sanitized and capped, resolved the same way
behaviour is — creator default (agents.config.statsSchema) merged per card under the
subscriber's override (agent_instances.config.stats). Unset is a first-class state; an agent that
declares nothing still gets the platform defaults below.

The security boundary: a closed source vocabulary

A card names a source from a registry. It never carries a query.

{ id: "leads_by_suburb", title: "Leads by suburb", kind: "bar",
  source: "collection.group_by", params: { collection: "leads", field: "suburb", limit: 10 } }

Each source is a hand-written, owner-scoped aggregate — the same shape as the connector registry
({id,label,auth,scopes,tools}) and the step registry:

source	backed by
usage.tokens / usage.cost	ai_usage
runs.count / runs.outcome	agent_loop_runs
pipeline.runs	pipeline_runs
board.by_column	instance_runtime_tasks
events.by_type	agent_events
triggers.fires	agent_trigger_events
collection.count / collection.group_by	the instance's own collections

Every source bakes in WHERE instance_id = ? AND user_id = ?. The card supplies which view, never
whose data.

This is the sentence that makes agent-authored stats safe: the schema says WHAT to show, never
WHOSE data. Same discipline as #224 — an agent may add a card, exactly as it may set its tone; it
may not widen scope, exactly as it may not widen a guardrail. A prompt-injected Repo Coder can at
worst produce a useless card.

Anything resembling free-form SQL in a card is out of scope and should stay out.

Platform defaults, so the tab is useful before anyone configures it

Every instance already has usage, events, runs and a board. The default set (shown when nothing is
declared) should be roughly: tokens + cost over the window, runs by outcome, activity by type,
board items by column. An agent's declared cards then add domain meaning on top — the lead-finder's
116-record leads collection is the obvious first real example.

Cost is a design constraint, not an afterthought

These are aggregates over the busiest tables in the product. The Usage page already meets this
problem. Requirements:

• One page-level time window (7d / 30d / 90d), not per card — so a view is one query set.
• Bounded cards (cap the count, cap limit per card) — cf. [bug] slice with an unparseable limit silently drops every record, and the run still reports success #243, where an unparseable limit
  silently dropped every record; parse windows and limits with Number.isFinite, and treat absent
  and unparseable differently.
• Indexes checked per source before it ships, and a cached response. A stats tab must not become
  the most expensive query in the platform, especially on a per-agent page someone leaves open.

Verification

• A card naming an unknown source is rejected at save time, by name (cf. validateConnectionFilter,
  which rejects a never-matching filter up front rather than letting it fail silently forever).
• No source can be made to read another user's or another instance's rows, including via params.
• An agent with no statsSchema sees the platform defaults; declaring one adds to them.
• Each source has a measured query plan against a realistic row count.

[serge-ivo]

Two design changes after review

1. Scope down — drop the platform-default cards

I proposed defaults (tokens, cost, runs, board, events) so the tab is useful before configuration.
On reflection most of that already exists elsewhere: /v1/usage is token/cost across agents,
the Activity tab is the event timeline, the Board is tasks by column, /v1/dashboard aggregates.
Re-rendering them per agent as charts is polish, and #250 just labelled ten tickets
deferred: no demand on that reasoning.

The value is the agent-declared domain metrics — "leads by suburb over time" for the
lead-finder, "runs by outcome" for a Coder. Nothing shows that today. Recommend building the
declared half and adding defaults only if the tab looks empty in practice.

2. Daily rollup, and it is load-bearing rather than a perf trick

For agent-defined collections a rollup is the only way to get a time series at all. leads
has 116 rows under a schema the agent defined; you can count them now, but "leads per day"
requires either a timestamp you control on every record (you do not) or a daily snapshot.

agent_stats_daily (
  instance_id, user_id, card_id, day,      -- PK (instance_id, card_id, day)
  value_json, computed_at
)

• The cron is * * * * * (per-minute, one entry). Guard on the UTC day with an
  INSERT … WHERE NOT EXISTS on (instance, card, day) — the same single-flight shape
  claimDelivery and runDueTriggers already use, rather than a second cron.
• Only roll up instances with activity that day, which bounds the work as asked.

The detail that must not be got wrong

A missing day is not a zero. If an agent did not run, there is no row — and the chart must
render a gap, not 0. Conflating them tells the user "you found 0 leads on Tuesday" when the
truth is "nothing ran on Tuesday". Same class as #243 (an unparseable limit silently meaning
"drop everything") and #252 (idle rendered over live work): a plausible-looking value standing in
for absent information.

So the series type is Array<{ day: string; value: number | null }>, and a null value renders as a
break in the line.

Consequences

• Two card families, declared in the schema: point-in-time (current board counts, collection
  size now) read live; trend cards read rollups. Only the second needs history.
• The cost section above mostly dissolves for trend cards — they become a keyed read, not an
  aggregate. Point-in-time cards still need the bounded-window discipline.
• No backfill. History starts the day it ships; the tab should say so rather than showing a
  short series as though it were the whole story.
• Retention cap (say 400 days) so the table stays bounded.

[serge-ivo]

Landed in fedc8a3.

The card vocabulary, and why it is closed. workers/api/src/lib/stats-schema.ts is a pure
table in the shape of BEHAVIOUR_FIELDS: 10 sources — usage.tokens, usage.cost,
runs.count, runs.outcome, pipeline.runs, board.by_column, events.by_type,
triggers.fires, collection.count, collection.group_by — 4 kinds (number · line ·
bar · table), per-source param specs, and a caveat string on every source. A card names a
source and never carries a query; lib/stats-sources.ts binds instance_id = ?1 AND user_id = ?2
into each executor itself, so the card supplies which view, never whose data. A test asserts
every declared source has an executor and vice versa, so a descriptor with no query fails the build
rather than 500ing at read time.

One deviation from the issue, deliberate: family is DERIVED, not stored. line ⇒ trend,
number/bar/table ⇒ point-in-time, via familyForKind in one place. A separately-stored family
can contradict the kind — a card declared trend and drawn as a bar has no series to draw — which
is the #254 shape, the prompt asserting what the tool set denies. Writers may still send family
(set_stats_card accepts it); it is checked against the kind and refused by name on mismatch
rather than silently ignored.

Verification, against your list:

• ✅ Unknown source rejected at save time by name, and the message lists the valid ids so an LLM
  caller can retry. Same for an unsupported kind, a missing required param, a bad collection name,
  and a duplicate card id.
• ✅ No source can be made to read another user's or instance's rows: a test drives every D1-backed
  source and asserts instance_id = ?1 / user_id = ?2 are in the SQL, with the bound values
  in positions 1–2, plus a test that no card param is ever interpolated into SQL text. Undeclared
  params are dropped, not carried through.
• ✅ Per your scope note, there are no platform-default cards — declared-only.
• ⚠️ Not done: measured query plans against a realistic row count. Every source hits an existing
  index by shape (idx_ai_usage_instance, idx_agent_loop_runs_instance,
  idx_pipeline_runs_instance, idx_instance_runtime_tasks_instance,
  idx_agent_events_instance_ts, idx_agent_trigger_events_instance), all of which lead on
  instance_id with the time column second — but that is reasoning, not measurement. Worth a real
  EXPLAIN QUERY PLAN pass against prod-shaped data before anyone leaves the tab open on a busy
  instance.

Cost discipline: one page-level window (7/30/90, parseStatsWindow — absent and unparseable
both fall back to 30 and the response echoes what was used); MAX_STATS_CARDS = 12;
MAX_CARD_LIMIT = 25; COLLECTION_SCAN_CAP = 500 with the answer flagged partial when it bit.
Per #243, an absent limit takes the declared default and an unparseable one is an error the
caller is told about — the two are never collapsed. No response cache yet (trend cards became a
keyed read, which removed most of the pressure); if the tab turns out to be hot, that is the next
lever.

Sitting on top: GET /v1/stats/sources (public, serves the caveats so a surface cannot show a
number without what it excludes), GET /v1/instances/:id/stats[?window=],
GET …/stats/schema, PUT …/stats, POST …/stats/cards, GET|PUT /v1/agents/:id/stats-schema —
all seven documented in store/openapi.yaml under a new Stats tag.

CI is in a declared outage; no CI run verified this. Locally: pnpm typecheck,
npx vitest run --project unit (4157 tests), npx biome check (unchanged from the pre-change
baseline), pnpm docs:drift, pnpm size:check — all green.