docs: define token cross-filter protocol

[Wattenberger]

Summary

• document token usage cross-filter fields and totals
• define workspace event payload behavior for agent and model token breakdowns

Verification

• confirmed origin/main...HEAD changes only the two intended protocol documentation files

[augmentcode]

🤖 Augment PR Summary

Summary: Defines the intended agent × model token-usage cross-filter protocol.

• Adds optional sparse byAgentModel rows to TokenUsage.
• Specifies token, cost, and human/agent message-count aggregation rules.
• Defines provenance, legacy-snapshot, ordering, and model fallback behavior.
• Updates token-usage event semantics to describe full snapshot replacement.
• Expands RPC and event examples with cross-filter data and totals.

Technical Notes: The proposal requires durable write-time materialization and keeps reads off the transcript hydration path.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

[panghy]

Review summary

Reviewed 41b4bcb2e47651ceb00b61443f7ac4c9b0fadc0f against intentd #1719 at 296290cb3c6e485186619e384b58a4108bb0dd91 and frontend #2154 at 5ede402cdd8a7b84d9eb82566716eadbd432a90c.

Recommendation: needs author changes to align the stack's publication contract. This is a COMMENT review, not a GitHub approval or request-changes decision. Rollout also remains gated: intentd#1719 must land, and its automated monorepo pin advance must be present before or alongside these canonical docs. The frontend review has separate UI findings.

Should-fix before landing

The docs repeatedly state that transcript writes do not materialize or publish usage immediately. However, the paired daemon at the reviewed SHA now awaits recompute_workspace_token_usage(..., false) inside agent.appendMessage (crates/intent-services/src/agent_ops.rs:5050-5051), as well as replace/edit/delete paths. The recompute persists changed byAgentModel counts and publishes workspace:tokenUsage-changed before returning. A counted append without any ACP turn can therefore materialize and emit, directly contradicting methods/workspace.md:1436-1437, :1492-1495, and the updated event table. I independently checked the exact daemon source after the daemon reviewer identified this; see the paired daemon finding and intent#4442.

Agree on one intended publication cadence, align both documentation sections and the daemon, and add a WSS regression for a transcript-only mutation without an ACP turn. This is a mismatch against the new paired daemon, not a repeat of the resolved thread about the old pinned daemon.

Contract and convention checks

• The exact row keys and nesting match both implementations: byAgentModel?: { agentId, model, totals, humanMessages, agentMessages }[], with existing optional thoughtTokens and totals.cost semantics. Absent vs empty projection is handled by presence, not version or synthesized rows.
• Ordering/uniqueness, unknown-model fallback, message-only cells, and the committed replacement-snapshot event shape align with the reviewed daemon code. Publication trigger timing does not, as detailed above.
• No method or event name is added. The existing workspace.getTokenUsage entry remains unchanged, so the additive-response-field exception in docs/protocol/versioning.md applies: no catalog or numeric version bump is required. This PR adds no version note, so a version-note boundary check is not applicable. Optional discoverability improvement: record this presence-detected addition in the current-version narrative, following other additive fields.
• Both changed documents have balanced fences and their relative link targets resolve. The new external daemon PR link resolves through gh pr view.
• The JSON examples parse; independent reductions of all five token counters across workspace, agent, and model projections match, and documented message totals (6 human / 8 agent) match the rows. The message-only event example also parses and matches its counts.
• git diff --check HEAD~2 HEAD -- docs/protocol: passed. Conventional PR title passes inspection.

This checks documentation/wire shape, not a substitute for the separately assigned daemon persistence/performance review. No merge, pin edit, auto-merge, or queue action was taken. Keep the schema-migration exception: do not test this stack by installing a manual DMG against a normal user database.