[stats] Configure stats from MCP and from the agent itself — one validator, no privileged path

[serge-ivo]

The "configurable by MCP or by the agent itself on the user's request" half of #310.

Three writers, one schema, one validator

Who	Path	Scope
Creator	agents.config.statsSchema	the default every subscriber inherits
Subscriber	agent_instances.config.stats	their own override, merged per card
The agent	set_stats_card tool	writes the subscriber override, same as a human would

All three go through the same sanitizer and the same closed source vocabulary from #310. That
is the whole safety story: there is no privileged path that skips validation, so "the agent
configured it" and "the user configured it" cannot diverge in what they are allowed to express.

MCP tools — mirror the settings-schema pair that already exists

get_agent_settings_schema / set_agent_settings_schema are the precedent; follow it exactly:

• get_agent_stats_schema / set_agent_stats_schema — creator-side, on the agent.
• get_instance_stats / set_instance_stats — subscriber-side, on the instance.

Both mutating tools are write-scoped and go through the MCP write gate, like every other
mutation (call_instance_tool is already gated wholesale as write).

The agent's own tools

• get_stats — read the resolved cards and their current values. This is what makes the
  feature conversational: "how many leads did I find this week?" should be answerable from the same
  numbers the tab shows, not recomputed by the model from a collection dump.
• set_stats_card — add / edit / remove one card. Patch semantics, null clears, rejections
  reported rather than swallowed (the set_behaviour shape from Agent Behaviour: get_behaviour / set_behaviour, with guardrails excluded from self-writes #224 — a tool that half-applies a
  patch and returns success teaches the model it changed something it did not).

Both base-tier, for the same reason get_behaviour / set_behaviour are: any agent can be asked
"track this for me", and an agent with no proper place to put the answer invents one. That is
exactly how preference:response_style ended up in memory (#226) and how a Repo Coder invented a
pipeline named "coding".

What the agent may NOT do

• It cannot add a source. The vocabulary is code, reviewed, owner-scoped ([stats] Per-agent Stats tab — declarative card schema over a closed, owner-scoped source vocabulary #310).
• It cannot change scope, only view — the schema says what to show, never whose data.
• It cannot write the creator schema. A subscriber's agent editing the agent template would
  change what every other subscriber gets; set_stats_card writes the instance override only. This
  is the same boundary patchBehaviour already holds ("a subscriber changing their mind must not
  edit the agent every other subscriber gets").

Prompt awareness

If an agent has stats cards, agent-think should say so — briefly, and derived from the resolved
schema, not hardcoded prose. An agent that can answer "how many leads this week" but is never told
it has the tool will not use it. Same failure as #254, where the prompt asserted a capability the
tool set contradicted; derive the sentence from the resolved tools, do not write it.

Verification

• A card set by the agent is byte-identical to the same card set by a human through the API.
• set_stats_card naming an unknown source is refused, by name, and other cards in the patch still
  apply.
• The agent cannot write agents.config.statsSchema through any tool.
• get_stats returns the same numbers the Stats tab shows for the same window.
• An agent with no cards is not told it has any.

[serge-ivo]

Scope note from #310's review: cards are now agent-declared only (no platform defaults), which makes this ticket more central than it read — with no defaults, the configuration path is the feature. An agent or user who cannot add a card sees an empty tab.

Two additions to the tool contract:

• set_stats_card must accept the family (trend | point-in-time, per [stats] Daily rollup — the only way to get a series for agent-defined collections (and a gap is not a zero) #313). A trend card starts accumulating from the day it is created; the tool should say so in its result, because "add a chart of leads per day" produces an empty chart until tomorrow and that is surprising unless stated.
• get_stats returns value: number | null per day for trend cards. The tool description must be explicit that null means the agent did not run, not zero — otherwise the model will read a gap as a bad day and report it as one.

[serge-ivo]

Landed in fedc8a3.

Three writers, one validator. Creator (PUT /v1/agents/:id/stats-schema), subscriber
(PUT /v1/instances/:id/stats for a whole replace, POST …/stats/cards for a patch) and the agent
(set_stats_card) all go through lib/stats-store.ts → the one sanitizer in lib/stats-schema.ts.
No privileged path, so "the agent configured it" and "the user configured it" cannot diverge in what
they are allowed to express.

MCP tools — mirroring the settings-schema pair exactly: get_agent_stats_schema /
set_agent_stats_schema (creator) and get_instance_stats / set_instance_stats (subscriber). Both
mutators are write-scoped through requirePermission, support dry_run, and audit. They live in a
new workers/mcp/src/instance-tools/stats.ts group rather than in base.ts — that file is the
largest in the repo and pinned by the #302 ratchet, and these four are one feature with one
vocabulary. Count 126 → 130; workers/mcp/CLAUDE.md, README.md, platform-docs/mcp.md and
store/llms-full.txt updated, pnpm docs:drift green.

The agent's own tools, both base-tier alongside get_behaviour/set_behaviour:

• get_stats — resolved cards and their current values, through the same computeStats the
  route uses. That is what makes "the same numbers the tab shows" structurally true rather than a
  coincidence. describeStats renders a gap as the words "no run" and states that it is not
  zero, because a model handed a bare null reads it as a bad day and reports it as one.
• set_stats_card — patch semantics, card: null clears, refusals reported by name while the
  valid ops still apply. Its description says a new line card starts empty and fills in tomorrow,
  and the success message repeats it — "add a chart of leads per day" producing an empty chart is
  surprising unless stated.

Family turned out not to need declaring: it is derived from kind (line ⇒ trend, everything
else ⇒ point-in-time) in one place. set_stats_card still accepts family and refuses it by
name when it contradicts the kind, so a caller that sends one is neither punished nor silently
corrected. Detail in the #310 comment.

Prompt awareness is derived, not written: statsPromptBlock(resolveStatsCards(…)) in
agent-think.ts, at zero extra queries — instanceCfg/agentCfg were already in hand from the
existing join. An agent with no cards gets no block at all.

Verification:

• ✅ A card set by the agent is byte-identical to one set by a human — same validator, one path.
• ✅ set_stats_card naming an unknown source is refused by name (and told the valid ids); other
  cards in the patch still apply.
• ✅ The agent cannot write agents.config.statsSchema through any tool — asserted over the whole
  registry, not just the two new tools, so a later tool cannot quietly acquire the capability.
• ✅ get_stats returns the same numbers as the tab for the same window (shared computeStats).
• ✅ An agent with no cards is not told it has any.
• Also: card: null on an inherited card hides it rather than deleting it — a subscriber must not
  edit the template every other subscriber gets, and without the distinction "hide" would appear to
  work and silently come back on the next read.

CI is in a declared outage; no CI run verified this. Verified locally only (typecheck, 4157 unit
tests, biome unchanged from baseline, docs:drift, size:check).