Description
Coding Agent Usage Analytics derives structured evidence about which reusable assets and workflows appear in imported coding-agent conversations. It scans the persisted conversation envelope for typed usage signals, groups repeated occurrences, resolves recognizable assets against a supplied roster, and stores a versioned aggregate in Conversation metadata. New imports derive the aggregate inline, while a bounded backfill upgrades older Conversations.
The design keeps the transcript as the source of truth. Usage entries point to their evidence and source type instead of becoming a separate speculative event store. A derivation version makes rule changes explicit: older metadata can be found and recomputed once without disturbing unrelated Conversation metadata such as total token usage or import signatures.
Selling Points
- Turns conversation histories into measurable adoption evidence for tools and workflows.
- Retains typed evidence instead of reducing every mention to an unqualified counter.
- Resolves known assets to durable references while preserving unresolved observations honestly.
- Versions the derivation so analytics rules can evolve without silent semantic drift.
- Backfills existing histories under a hard scan ceiling.
User Story
As a product operator, I want to understand which skills, commands, and reusable assets actually appear in agent-assisted work. Dots derives that signal from imported Conversations and can link recognized usage to the current roster, giving me evidence-backed adoption data without asking users to tag sessions manually.
Extension Surface
The rating is extensible because packages/ingestion/src/coding-agent/usage/derive.ts consumes a structural asset resolver seam, and packages/ingestion/src/coding-agent/usage/resolver.ts supplies a roster-backed implementation. A composition root can provide another authoritative resolver without rewriting extraction. The emitted usage entry types and derivation version remain governed contracts.
Capabilities & Limits
Capabilities include transcript-envelope validation, typed signal extraction, occurrence grouping, roster resolution, version stamps, inline import derivation, and bounded historical backfill. Metadata updates preserve sibling keys. Limits are explicit: plain text or malformed envelopes produce no aggregate, unresolved asset names remain unresolved rather than receiving guessed identities, and the analytics report observed transcript evidence—not proof that an external tool completed successfully.
Implementation Map
packages/ingestion/src/coding-agent/usage/derive.tspackages/ingestion/src/coding-agent/usage/resolver.tspackages/ingestion/src/coding-agent/usage/backfill.tspackages/ingestion/src/coding-agent/backfill/transcript-session.ts