@matatbread/matbot-core 0.4.1 → 0.4.3

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.1",
+  "version": "0.4.3",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@matatbread/matbot-plugin-api": "^0.4.1"
+    "@matatbread/matbot-plugin-api": "^0.4.3"
   },
   "devDependencies": {
     "typescript": "^6.0.3"

package/src/index.ts

@@ -29,10 +29,12 @@ export {
   createBroadcaster, subscribable, createNotifier, scopedNotifier,
   installPrincipalCarrier, enterPrincipal, createConstantPrincipalCarrier,
   contextSwitch, onContextQuiesce, flushIfQuiescent,
-  installUsageCarrier, createSerialUsageCarrier, recordUsage, currentUsageSink, withUsageScope,
+  installUsageCarrier, createSerialUsageCarrier, recordUsage, recordSpan, currentUsageSink,
+  currentUsageScope, currentUsageSite, withUsageScope, withUsageSite,
 } from '@matatbread/matbot-plugin-api/host';
 export type {
   Subscribable, Broadcaster, Routed, RoutedFilter, SwapFn, MountTable, PrincipalCarrier, UsageCarrier,
+  UsageScope,
 } from '@matatbread/matbot-plugin-api/host';
 export * from './session.js';
 export * from './usage.js';

package/src/registry.ts

@@ -1,4 +1,4 @@
-import type { Tool, ToolRegistry, Hook, PromptFn, FormField, FrontendInfo, ProviderAdapter, ProviderConfig } from './types.js';
+import type { Tool, ToolRegistry, Hook, PromptFn, FormField, FrontendInfo, ProviderAdapter, ProviderConfig, FailedPlugin } from './types.js';
 import { RegistryChangeKind } from '@matatbread/matbot-plugin-api';
 import { scopedNotifier } from '@matatbread/matbot-plugin-api/host';
 import type {
@@ -11,14 +11,8 @@ import type { SettingsDoc } from './settings.js';
 
 // ── Internal state ────────────────────────────────────────────────────────────
 
-/**
- * A plugin the loader could not bring up — an incompatible runtime, an import that rejected, a
- * module that is not plugin-shaped, or a setup() throw. Recorded (not discarded) so the failure is
- * *graceful but not silent*: the `plugin` tool and web UI can show which configured plugins failed
- * and why, instead of the failure vanishing into a boot-time console line. `error` is pre-stringified
- * (sidesteps the `unknown` catch-var); `name` is present only when known before the failure.
- */
-export type FailedPlugin = { specifier: string; name?: string; error: string };
+// `FailedPlugin` now lives in plugin-api: `plugin list` reports it, so it is part of that tool's
+// contract, and the contract has to be declarable from a package this one can reach.
 
 // Mutable arrays/maps held in a single object to make _resetRegistry() simple.
 const state = {

package/src/runner.ts

@@ -1,16 +1,33 @@
 import type {
-  Session, Message, MessageContent, ModelContent, Usage, ProviderMeta, TruncatedToolResult,
+  Session, Message, MessageContent, ModelContent, Usage, UsageSite, ProviderMeta, TruncatedToolResult,
   TurnEvent, RunConfig, ProviderAdapter, ProviderConfig,
   Tool, ToolRegistry, ToolContext, Store, FileStore, SystemContextRegistry, Vault, PromptFn, FormField,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
 import type { ToolPresenter } from '@matatbread/matbot-plugin-api';
-import { currentUsageSink } from '@matatbread/matbot-plugin-api/host';
+import { recordSpan, recordUsage, withUsageSite } from '@matatbread/matbot-plugin-api/host';
 import { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
 import { foldOntoUserTurn, bindPluginOps } from '@matatbread/matbot-plugin-api';
 import { addUsage } from './usage.js';
 
+// Establish a usage call site across an async iteration. Wrapping the *loop* would not work: this
+// runner is itself an async generator, so it suspends at every `yield` and resumes under the consumer's
+// context, losing any scope entered around the loop body. Scoping each `next()` instead means the
+// tool's body — and anything it kicks off while running — always resumes under its own site.
+function siteScoped<T>(site: UsageSite, src: AsyncIterable<T>): AsyncIterable<T> {
+  return {
+    [Symbol.asyncIterator]: () => {
+      const it = src[Symbol.asyncIterator]();
+      return {
+        next:  ()  => withUsageSite(site, () => it.next()),
+        ...(it.return ? { return: (v?: never) => withUsageSite(site, () => it.return!(v)) } : {}),
+        ...(it.throw  ? { throw:  (e?: unknown) => withUsageSite(site, () => it.throw!(e))  } : {}),
+      };
+    },
+  };
+}
+
 // Substituted for an errored tool result when the turn was aborted (e.g. a mid-turn steer interrupt):
 // the tool was cut off, not genuinely faulty, and the raw abort reason ("Error: steer") is a leaked
 // internal token that reads as a real failure. A steer's continuation turn is the one place a model
@@ -239,6 +256,22 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     const assistantParts: MessageContent[] = [];
     let textAcc = '';
     let turnUsage: Usage | undefined;
+    // The round's bracket — set where the provider call is actually issued, below, so it measures the
+    // call rather than the screen/contribute work that precedes it.
+    let roundStartedAt = Date.now();
+    // Book the round's own spend as an entry the moment the stream settles — including when the response
+    // is then thrown away (an in-situ restart) or the call died part-way. The tokens were billed either
+    // way; tying the record to whether the *answer* survived is what made a restarted round free. Clears
+    // as it books, so no exit path can double-count it.
+    const bookRound = (): void => {
+      const u = turnUsage;
+      if (u === undefined) return;
+      turnUsage = undefined;
+      withUsageSite({ kind: 'round', round }, () => recordUsage(config.provider, u, {
+        startedAt:  new Date(roundStartedAt).toISOString(),
+        durationMs: Date.now() - roundStartedAt,
+      }));
+    };
     let truncation: { reason: 'max-tokens' | 'stream-end'; raw?: string } | undefined;
     // Set if a raced verdict fires mid-generation: discard this response and re-run the loop (below).
     let restart = false;
@@ -264,14 +297,18 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     // Tools advertised for THIS call. A presenter (optional) may present a subset of the snapshot and
     // grow it across iterations as the model discovers tools; absent ⇒ the whole snapshot. Withheld
     // tools stay callable — execution resolves against the live registry (opts.toolRegistry), not this.
+    // Scoped to the round: a presenter may itself run completions (deriving a tool's search terms), and
+    // that spend belongs to the round that asked for it — it is neither a tool call nor a hook.
     const advertised = opts.toolPresenter
-      ? await opts.toolPresenter.present([...tools.values()], { session, provider: config.provider })
+      ? await withUsageSite({ kind: 'round', round },
+          () => opts.toolPresenter!.present([...tools.values()], { session, provider: config.provider }))
       : [...tools.values()];
     // Per-call signal linked to the turn signal: an in-situ restart aborts THIS provider call (callAc)
     // to cancel the in-flight request and stop backend generation, without aborting the whole turn.
     const callAc = new AbortController();
     const callSignal = AbortSignal.any([signal, callAc.signal]);
     try {
+      roundStartedAt = Date.now();
       for await (const ev of provider.complete(outgoing, providerConfig, advertised, callSignal)) {
         // A raced verdict firing mid-generation changes the premise: discard this doomed response and
         // restart the loop with the correction folded in. Polled BEFORE the event is emitted, so a
@@ -308,9 +345,9 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
           case 'usage':
             turnUsage = addUsage(turnUsage, ev);
             yield { type: 'usage', inputTokens: ev.inputTokens, outputTokens: ev.outputTokens, traceId,
-              ...(ev.costUsd              !== undefined ? { costUsd:              ev.costUsd              } : {}),
               ...(ev.cacheReadTokens     !== undefined ? { cacheReadTokens:     ev.cacheReadTokens     } : {}),
-              ...(ev.cacheCreationTokens !== undefined ? { cacheCreationTokens: ev.cacheCreationTokens } : {}) };
+              ...(ev.cacheCreationTokens !== undefined ? { cacheCreationTokens: ev.cacheCreationTokens } : {}),
+              ...(ev.reported            !== undefined ? { reported:            ev.reported            } : {}) };
             break;
           case 'done':
             break;
@@ -322,12 +359,12 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
       if (restart || (callAc.signal.aborted && !signal.aborted)) {
         restart = true;
       } else if (signal.aborted) {
+        bookRound();
         // Save whatever the LLM streamed before the abort hit.
         if (textAcc) assistantParts.push({ type: 'text', text: textAcc });
         if (assistantParts.length > 0) {
           session = appendMessage(session, createMessage({
             role: 'assistant', content: assistantParts, traceId, providerName: config.provider,
-            ...(turnUsage !== undefined ? { usage: turnUsage } : {}),
           }));
         }
         yield* end({ type: 'aborted', reason: abortReason(signal), session, traceId });
@@ -343,10 +380,12 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
         // belong to the call that failed, and the model never finished the thought. The `error` event
         // carries no session (a failure is not a transcript), so this yields the terminal itself rather
         // than the session — but it commits first, exactly like every other exit.
+        bookRound();
         yield* end({ type: 'error', error: String(e) + (('cause' in e && e.cause) ? ' ('+String(e.cause)+')' : '' ), traceId });
         return;
       }
     }
+    bookRound();
 
     // In-situ restart: discard this iteration's (uncommitted) response and re-run the loop with the
     // raced correction now folded into `ephemeral`. No store write, no retraction marker — the clean
@@ -370,7 +409,6 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
         content:      assistantParts,
         traceId,
         providerName: config.provider,
-        ...(turnUsage !== undefined ? { usage: turnUsage } : {}),
       });
       session = appendMessage(session, assistantMsg);
     }
@@ -487,9 +525,10 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
       let result: unknown;
       let isError = false;
       // Token accounting for completions this tool runs (via singleTurn/complete) accrues into the
-      // ambient turn sink; slice off whatever it appends during *this* call to attribute it here.
-      const usageSink = currentUsageSink();
-      const usageMark = usageSink?.length ?? 0;
+      // ambient turn scope, stamped with the site established below — never attached to this message.
+      // A tool message is popped wholesale by a retract-and-rerun, which would take its accounting
+      // somewhere no reduction over the session can reach; the entry lives on the turn head instead.
+      const site: UsageSite = { kind: 'tool', callId: tc.id, tool: tc.name };
       const startedAt = Date.now();
 
       const toolCtx: ToolContext = {
@@ -503,7 +542,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
       };
 
       try {
-        for await (const toolEv of tool.executor.execute(tc.input, toolCtx)) {
+        for await (const toolEv of siteScoped(site, tool.executor.execute(tc.input, toolCtx))) {
           switch (toolEv.type) {
             case 'stdout':   yield { type: 'tool:stdout', callId: tc.id, chunk: toolEv.chunk, traceId }; break;
             case 'stderr':   yield { type: 'tool:stderr', callId: tc.id, chunk: toolEv.chunk, traceId }; break;
@@ -534,16 +573,23 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
 
       // toolresult — last chance to transform the result before it's recorded/yielded (hard redaction),
       // or to observe it (auditing: args + result + timing). Owns the LLM-facing + persisted surfaces.
+      const durationMs = Date.now() - startedAt;
+
+      // The bracket, recorded for EVERY tool call — not just the ones that spent tokens. Most tools
+      // (bash, http, workspace) run no completion at all, so hanging duration off an accounting record
+      // would capture it precisely for the tools that happen to call an LLM and lose it for the rest.
+      // Previously this number was computed, handed to the `toolresult` hook, and then discarded, so a
+      // consumer had to re-derive it — less accurately — from event arrival times.
+      recordSpan(site, new Date(startedAt).toISOString(), durationMs);
+
       result = await hookReg.runToolResult({
         session, config, signal,
         toolCall: { id: tc.id, name: tc.name, input: tc.input },
-        tool, result, isError, durationMs: Date.now() - startedAt,
+        tool, result, isError, durationMs,
       });
 
-      const callUsage = usageSink ? usageSink.slice(usageMark) : [];
-      toolResults.push({ type: 'tool-result', id: tc.id, result, isError,
-        ...(callUsage.length > 0 ? { usage: callUsage } : {}) });
-      yield { type: 'tool:end', callId: tc.id, result, isError, traceId };
+      toolResults.push({ type: 'tool-result', id: tc.id, result, isError });
+      yield { type: 'tool:end', callId: tc.id, result, isError, durationMs, traceId };
     }
 
     // Add tool results message, then loop for the next provider call.

package/src/session-runner.ts

@@ -2,7 +2,7 @@ import type {
   Session, Message, MessageContent, Principal, PromptFn, PipelineEvent,
   Store, ToolRegistry, SystemContextRegistry, Vault, FileStore, Tool,
   ProviderAdapter, ProviderConfig, SessionRunner, SessionView, OpenOpts, SubmitOpenOpts,
-  SteeringPolicy, SteeringDecision,
+  SteeringPolicy, SteeringDecision, TurnEntry,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
 import type { HookRegistry } from './hooks.js';
@@ -103,6 +103,11 @@ interface SessionState {
   // Events of the *current* turn, replayed to a subscriber that joins mid-turn. Cleared at each
   // turn boundary — committed history comes from the store, not from here.
   replay:      PipelineEvent[];
+  // Accounting entries awaiting a flush, held BY REFERENCE to each turn's usage scope. A completion
+  // can be recorded after its turn commits — a detached trigger classifier, a `followup` hook — and it
+  // appends to the very array captured here, so a late arrival needs no coordination: whatever is in
+  // these arrays at the flush is what gets written, and each entry says which turn caused it.
+  pendingUsage: TurnEntry[][];
 }
 
 interface Sink {
@@ -163,7 +168,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
   const stateFor = (id: string): SessionState => {
     let s = states.get(id);
     if (s === undefined) {
-      s = { queue: [], running: false, runningTraceId: undefined, ac: undefined, subscribers: new Set(), replay: [] };
+      s = { queue: [], running: false, runningTraceId: undefined, ac: undefined, subscribers: new Set(), replay: [], pendingUsage: [] };
       states.set(id, s);
     }
     return s;
@@ -190,6 +195,63 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
   // How many submissions sit ahead of the item at queue index `i` (the running turn counts as one).
   const aheadOf = (s: SessionState, i: number): number => (s.running ? 1 : 0) + i;
 
+  /**
+   * Write whatever accounting has accrued onto the turn heads that caused it, then clear it.
+   *
+   * Entries are drained by SPLICING each pending array, so an entry appended after this point (a
+   * classifier still in flight) accumulates afresh and lands on the next flush rather than being
+   * written twice. That is the whole concurrency story: no marks, no coordination, and eventual
+   * delivery — which is all a log needs, since each entry names the turn that caused it.
+   *
+   * Anchored on the turn's head (its user message) because that is the message a retract-and-rerun
+   * keeps; assistant and tool messages are popped into a retraction marker where no reduction over
+   * `session.messages` would find them again. An entry whose turn head has since gone (a session
+   * edit, a compaction) is dropped rather than orphaned onto an unrelated message.
+   */
+  const flushUsage = async (id: string, s: SessionState): Promise<void> => {
+    // Splice each array in place and KEEP the references. Dropping a drained array is the obvious
+    // tidy-up and it silently loses exactly the case this exists for: a classifier that settles after
+    // the flush appends to the array its scope captured, so if the pump has stopped holding it, the
+    // write goes nowhere observable. They are left registered for the life of the session state, at a
+    // cost of one empty array per turn.
+    //
+    // The limit of that: `maybeCleanup` disposes the state once the session is quiet and unsubscribed,
+    // so a completion still in flight at THAT point is lost. This is the carrier's stated best-effort
+    // contract rather than a hole to plug — nothing can know what is still pending — and it is bounded
+    // in practice, since the two channels that settle late (a `followup` hook, a user-phase classifier
+    // the runner polls) are both awaited inside the pump iteration this scope wraps.
+    const drained = s.pendingUsage.flatMap(entries => entries.splice(0));
+    if (drained.length === 0) return;
+
+    const session = await deps.store.get(id);
+    if (!session) return;
+
+    // Anchor on the entry's own turn head when it has one, and on its ROOT's otherwise. A
+    // retract-and-rerun re-runs an existing user turn under a fresh traceId and introduces no user
+    // message, so its entries have no head of their own — and the root is the honest home anyway, since
+    // a retry's cost belongs to the turn being retried. Without this the redo's spend was dropped
+    // outright, which is the very under-report anchoring on the turn head exists to prevent.
+    const heads = new Set(session.messages.filter(m => m.role === 'user').map(m => m.traceId));
+    const byTrace = new Map<string, TurnEntry[]>();
+    for (const e of drained) {
+      const anchor = e.traceId !== undefined && heads.has(e.traceId) ? e.traceId : e.rootTraceId;
+      if (anchor === undefined || !heads.has(anchor)) continue;
+      const list = byTrace.get(anchor);
+      if (list) list.push(e); else byTrace.set(anchor, [e]);
+    }
+
+    let changed = false;
+    const messages = session.messages.map(m => {
+      const add = m.role === 'user' ? byTrace.get(m.traceId) : undefined;
+      if (add === undefined) return m;
+      byTrace.delete(m.traceId);
+      changed = true;
+      return { ...m, activity: [...(m.activity ?? []), ...add] };
+    });
+    if (!changed) return;
+    await deps.store.set(id, { ...session, messages });
+  };
+
   const pump = async (id: string, s: SessionState): Promise<void> => {
     if (s.running) return;
     s.running = true;
@@ -298,7 +360,14 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
           // budget. Tracked here rather than inferred from `ac.signal`, which only knows about the two
           // signal-driven aborts and not the policy ones.
           let terminal: PipelineEvent['type'] | undefined;
-          await contextSwitch(head.principal, () => withUsageScope(async () => {
+          // One usage scope per pump ITERATION rather than per turn. `followup` is post-commit by
+          // definition and a detached classifier settles whenever it settles, so a scope that ended at
+          // the turn's commit would drop precisely the spend that is hardest to account for otherwise.
+          // The entries array is registered for flush before any work starts, so a late arrival lands
+          // in something already tracked and needs no coordination of its own.
+          await withUsageScope(async usage => {
+          s.pendingUsage.push(usage.entries);
+          await contextSwitch(head.principal, async () => {
             for await (const ev of runSession({
               session,
               config:         { provider: head.provider, traceId: head.traceId },
@@ -323,7 +392,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
               if (ev.type === 'done' || ev.type === 'aborted' || ev.type === 'error') terminal = ev.type;
               emit(s, ev);
             }
-          }));
+          });
 
           // followup — post-commit, in the queue owner. A hook reads the just-committed turn and may
           // head-enqueue a robo follow-up (its own real turn, running next). Runs only for a turn that
@@ -439,6 +508,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
               }
             }
           }
+          }, { traceId: head.traceId, rootTraceId: head.rootTraceId });
         } catch (e) {
           emit(s, { type: 'error', error: String(e), traceId: head.traceId });
         } finally {
@@ -449,6 +519,11 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
       s.running = false;
       s.runningTraceId = undefined;
       s.replay  = [];
+      // Accounting is flushed HERE — at the drained queue, not at a turn boundary. "The end of a turn"
+      // is not a well-defined moment to total anything at: steers terminate and resume, a retract
+      // re-enqueues the turn it just popped, followup enqueues resubmissions, and a detached classifier
+      // settles whenever it settles. The queue draining is unambiguous, and it is after all of them.
+      await flushUsage(id, s);
       // Deterministic busy→idle signal: running is now false, so any subscriber draining the stream
       // (a frontend's status tracker) reads an authoritative idle the moment it sees this — no racing
       // the microtask on which `running` flipped. Not in `replay` (transient lifecycle, not history).

package/src/session.ts

@@ -1,4 +1,4 @@
-import type { Session, Message, MessageContent, MessageRole, Usage } from './types.js';
+import type { Session, Message, MessageContent, MessageRole } from './types.js';
 
 export interface CreateSessionOpts {
   title?:                string;
@@ -37,7 +37,6 @@ export function createMessage(opts: {
   content:        MessageContent[];
   traceId:        string;
   providerName?:  string;
-  usage?:         Usage;
   metadata?:      Record<string, unknown>;
 }): Message {
   return {
@@ -47,7 +46,6 @@ export function createMessage(opts: {
     createdAt: new Date().toISOString(),
     traceId:   opts.traceId,
     ...(opts.providerName !== undefined ? { providerName: opts.providerName } : {}),
-    ...(opts.usage        !== undefined ? { usage:        opts.usage        } : {}),
     ...(opts.metadata     !== undefined ? { metadata:     opts.metadata     } : {}),
   };
 }

package/src/storage-base/query/execute.ts

@@ -47,9 +47,12 @@ export function executeQuery<T extends { id: string; version: string }>(docs: T[
   const slice = ordered.slice(page.offset, end);
   const next  = page.offset + slice.length;
 
+  // `limit: 0` is the count form: the filter runs, `total` answers, no document is materialised. It
+  // gets no cursor — a zero-length page never advances `offset`, so one would page forever on the
+  // same empty slice.
   return {
     items: slice,
     total,
-    ...(next < total ? { cursor: encodeCursor({ ...page, offset: next }) } : {}),
+    ...(page.limit !== 0 && next < total ? { cursor: encodeCursor({ ...page, offset: next }) } : {}),
   };
 }

package/src/usage.ts

@@ -1,6 +1,13 @@
-import type { Message, Usage } from './types.js';
+import type { Message, TurnEntry, Usage, UsageRecord } from './types.js';
 
-/** Fold one usage tally into a running total; optional fields are summed only when either side has them. */
+/**
+ * Fold one usage tally into a running total; optional fields are summed only when either side has them.
+ *
+ * `reported` sums **numeric values key-wise** and drops the rest: a total `service_tier` is meaningless
+ * and a summed `latency_checkpoint` is nonsense, so non-numeric retained values stay per-call facts that
+ * a consumer reads off the entries. Callers must fold only within ONE provider — `usageByProvider` does,
+ * by grouping first — since the same key means different things under different protocols.
+ */
 export function addUsage(acc: Usage | undefined, next: Usage): Usage {
   const a = acc ?? { inputTokens: 0, outputTokens: 0 };
   const add = (x: number | undefined, y: number | undefined): number | undefined =>
@@ -8,29 +15,71 @@ export function addUsage(acc: Usage | undefined, next: Usage): Usage {
   return {
     inputTokens:  a.inputTokens  + next.inputTokens,
     outputTokens: a.outputTokens + next.outputTokens,
-    ...(((c) => c !== undefined ? { costUsd:             c } : {}))(add(a.costUsd,             next.costUsd)),
     ...(((c) => c !== undefined ? { cacheReadTokens:     c } : {}))(add(a.cacheReadTokens,     next.cacheReadTokens)),
     ...(((c) => c !== undefined ? { cacheCreationTokens: c } : {}))(add(a.cacheCreationTokens, next.cacheCreationTokens)),
+    ...(((r) => r !== undefined ? { reported: r } : {}))(addReported(a.reported, next.reported)),
   };
 }
 
+function addReported(
+  a: Record<string, unknown> | undefined,
+  b: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  const out: Record<string, unknown> = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    const prev = out[k];
+    out[k] = typeof v === 'number' && typeof prev === 'number' ? prev + v : v;
+  }
+  return out;
+}
+
 /**
- * Aggregate the token accounting recorded on a set of messages, keyed by the provider billed: an
- * assistant turn's own `Message.usage` (billed to its `providerName`) plus every `tool-result` block's
- * `usage` records (each provider-tagged — a tool may run completions against several). Pass a single
- * turn's messages (filtered by `traceId`) for a per-turn breakdown, or a whole session for its total.
+ * Everything a set of messages records about what happened — provider calls and the brackets around
+ * them — in message order.
+ *
+ * Entries are anchored on turn heads and are self-describing (`site`, `traceId`), so this is a flat
+ * read with no correlation to do: filter it for whatever question is being asked — one turn
+ * (`traceId`), one tool call (`site`), one session (pass the lot) — and the same one fact set answers
+ * "what did this tool cost", "what did this user cost" and "how long did that take".
  */
-export function usageByProvider(messages: Iterable<Message>): Map<string, Usage> {
-  const out = new Map<string, Usage>();
+export function turnActivity(messages: Iterable<Message>): TurnEntry[] {
+  const out: TurnEntry[] = [];
   for (const m of messages) {
-    if (m.usage !== undefined && m.providerName !== undefined) {
-      out.set(m.providerName, addUsage(out.get(m.providerName), m.usage));
+    if (m.activity !== undefined) out.push(...m.activity);
+
+    // Sessions written before accounting moved onto the turn head: an assistant message's own `usage`
+    // object, and a `tool-result`'s `usage` array. Neither shape is written any more.
+    const legacyOwn = (m as { usage?: Usage }).usage;
+    if (legacyOwn !== undefined && m.providerName !== undefined) {
+      out.push({ kind: 'call', provider: m.providerName, usage: legacyOwn, traceId: m.traceId });
     }
     for (const c of m.content) {
-      if (c.type === 'tool-result' && c.usage !== undefined) {
-        for (const r of c.usage) out.set(r.provider, addUsage(out.get(r.provider), r.usage));
-      }
+      const legacy = c.type === 'tool-result' ? (c as { usage?: UsageRecord[] }).usage : undefined;
+      if (legacy !== undefined) out.push(...legacy.map((r): TurnEntry => ({ kind: 'call', ...r })));
     }
   }
   return out;
 }
+
+/** The provider calls in a set of messages — `turnActivity` less the spans. */
+export function usageEntries(messages: Iterable<Message>): UsageRecord[] {
+  return turnActivity(messages).filter((e): e is { kind: 'call' } & UsageRecord => e.kind === 'call');
+}
+
+/**
+ * Aggregate the token accounting on a set of messages, keyed by the provider billed. Pass a single
+ * turn's messages (filtered by `traceId`) for a per-turn breakdown, or a whole session for its total.
+ *
+ * Note what this deliberately does NOT do: sum a provider's `reported` fields across providers. The
+ * same key means different things under different protocols (`prompt_tokens` includes cache hits,
+ * `input_tokens` does not), so only the normalised counters are comparable across a mixed turn.
+ */
+export function usageByProvider(messages: Iterable<Message>): Map<string, Usage> {
+  const out = new Map<string, Usage>();
+  for (const r of usageEntries(messages)) {
+    out.set(r.provider, addUsage(out.get(r.provider), r.usage));
+  }
+  return out;
+}