Description
Conversation Insights turn a normalized conversation body into a consistent metric record. The calculator counts user and assistant messages, tool calls, distinct tools, errors, retrieved rows, files read, searches, token splits, estimated cost, start time, and duration. These values back the Conversations foundational Dotabase's queryable properties and its seeded dashboard, allowing users to compare agent work without parsing provider-specific logs.
The metric contract follows an honest-null rule. Optional cache and reasoning splits remain null when the provider did not report them; unknown pricing remains null instead of being presented as free; retrieval outputs are counted only when agent-readable record envelopes expose real row identities. The full stored body is recomputed on each write, making the process idempotent and self-healing rather than incrementally double-counting prior totals.
Selling Points
- Users can compare conversations by workload, duration, tool activity, retrieval volume, and estimated spend from one normalized catalog.
- Provider-specific token splits become consistent fields while missing signals remain visibly unknown.
- Recomputing from the transcript protects dashboards from duplicated counters after retries, forks, or repaired imports.
- Retrieval-aware counting distinguishes “no rows retrieved” from “a retrieval happened but its output was not countable.”
- The same metrics work for live conversations and imported coding-agent sessions, supporting a unified operational picture.
User Story
An engineering manager opens the Conversation Insights dashboard to understand how agents are being used. They compare long-running sessions, see which conversations made heavy tool and search use, and identify expensive direct-model turns. When a provider did not expose reasoning tokens or a model has no pricing entry, those cells remain unknown instead of showing misleading zeros, so the manager can trust the comparison.
Extension Surface
This feature is fixed_core. packages/chat/src/metrics/conversation-metrics.ts implements the locked Conversations schema contract from the specification, including provider-aware retrieval classification and pricing semantics. Consumers can read the resulting properties and dashboards, but they cannot register arbitrary metric calculators or alter the canonical field meanings through configuration.
Capabilities & Limits
- It computes seventeen stored metrics plus inputs for schema formulas from the full message envelope.
- It recognizes Dots retrieval calls across MCP and shell forms and counts agent-readable row envelopes.
- It recomputes estimated cost when a provider reports the zero sentinel and a pricing row exists.
- Limit: files-read and search signals are exact only for providers whose normalized tool stream exposes them; absent provider signals stay null.
Implementation Map
packages/chat/src/metrics/conversation-metrics.tspackages/chat/src/session/total-usage-metadata.tspackages/chat/src/dispatch/pricing.tspackages/chat/src/types.ts