@genesislcap/ai-assistant 15.12.0 → 15.13.1

package/src/state/persistence/diagnostics.test.ts

@@ -1,5 +1,10 @@
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { assembleDebugLog, diagnosticsMessageKey, type DiagnosticEntry } from './diagnostics';
+import {
+  assembleDebugLog,
+  diagnosticsMessageKey,
+  type DiagnosticEntry,
+  withFreshMetaSnapshot,
+} from './diagnostics';
 
 // GENC-1351 §5.8: `assembleDebugLog` reassembles the forward-only diagnostics
 // stream back into the `{ readme, timeline, meta }` debug-log shape — timeline
@@ -92,8 +97,210 @@ Suite('collapses exact-duplicate entries but keeps genuinely-distinct ones', ()
   );
 });
 
+Suite('lifts the newest snapshot’s session usage to the top of the log', () => {
+  // The four buckets + USD are the headline of a cost investigation, and `meta` is a
+  // large block to go digging in — so they surface at the top level. Same object, not a
+  // second derivation, and taken from the SAME snapshot that becomes `meta`.
+  const usage = {
+    costUsd: 1.25,
+    uncachedInputTokens: 1000,
+    cacheReadTokens: 9000,
+    cacheWriteTokens: 500,
+    outputTokens: 300,
+  };
+  const entries: DiagnosticEntry[] = [
+    {
+      kind: 'meta-snapshot',
+      timestamp: '2026-01-01T00:00:01.000Z',
+      meta: { context: { sessionUsage: { ...usage, costUsd: 0.01 } } },
+    },
+    {
+      kind: 'meta-snapshot',
+      timestamp: '2026-01-01T00:00:09.000Z',
+      meta: { context: { sessionUsage: usage } },
+    },
+  ];
+  assert.equal(assembleDebugLog(entries, README).sessionUsage, usage);
+});
+
+Suite('leaves session usage undefined when no snapshot carries it', () => {
+  // A stream with no meta-snapshot, or one written before the field existed. Absent
+  // rather than zeroed: "not recorded" must not read as "this session spent nothing".
+  assert.is(assembleDebugLog([], README).sessionUsage, undefined);
+  const noContext: DiagnosticEntry[] = [
+    { kind: 'meta-snapshot', timestamp: '2026-01-01T00:00:01.000Z', meta: { host: 'localhost' } },
+  ];
+  assert.is(assembleDebugLog(noContext, README).sessionUsage, undefined);
+});
+
+Suite('collapses the turn pair even when its rendered systemPrompt differs', () => {
+  // The pair is produced by two separate flushes, and `buildTimelineEntries` renders
+  // `systemPrompt` relative to the preceding snapshots — so if the snapshot holding the
+  // full prompt is evicted from the ring buffer between the two, the surviving turn
+  // renders its prompt in full where the earlier copy had the '<repeated>' marker. Any
+  // identity derived from the serialized entry breaks here and the log shows one model
+  // call as two turns, one unpriced. Identity is turnIndex + timestamp + agentName.
+  const unpriced: DiagnosticEntry = {
+    kind: 'turn',
+    turnIndex: '7',
+    timestamp: '2026-01-01T00:00:01.000Z',
+    agentName: 'Trade Operations',
+    systemPrompt: '<repeated — identical to turn 0>',
+    toolNames: [],
+  };
+  const priced: DiagnosticEntry = {
+    ...unpriced,
+    systemPrompt: 'the full prompt, now that turn 0 has been evicted',
+    usage: {
+      costUsd: 0.5,
+      uncachedInputTokens: 100,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      outputTokens: 20,
+    },
+  };
+  const turns = assembleDebugLog([unpriced, priced], README).timeline.filter(
+    (e) => e.kind === 'turn',
+  );
+  assert.is(turns.length, 1, 'still one model call');
+  assert.equal(turns[0].usage, priced.usage, 'and it is the priced copy');
+});
+
+Suite('keeps same-index turns from different loads and different sub-agents apart', () => {
+  // `turnIndex` restarts at '0' on every page load, so a lifetime log holds one turn '0'
+  // per load; two sub-agents invoked in one parent turn share the index prefix and are
+  // separated by `agentName` (see `forwardSubAgentSnapshots`).
+  const load1: DiagnosticEntry = {
+    kind: 'turn',
+    turnIndex: '0',
+    timestamp: '2026-01-01T00:00:01.000Z',
+    agentName: 'Booker',
+    toolNames: [],
+  };
+  const load2: DiagnosticEntry = { ...load1, timestamp: '2026-01-02T09:00:00.000Z' };
+  const sibling: DiagnosticEntry = { ...load1, turnIndex: '3-1', agentName: 'Planner' };
+  const cousin: DiagnosticEntry = { ...sibling, agentName: 'Grounding' };
+  const turns = assembleDebugLog([load1, load2, sibling, cousin], README).timeline.filter(
+    (e) => e.kind === 'turn',
+  );
+  assert.is(turns.length, 4, 'four distinct calls, none collapsed');
+});
+
+Suite('collapses the unpriced and priced copies of one turn onto the priced one', () => {
+  // A turn entry is persisted when it is created (before its model call) and again once
+  // `usage` is back-filled, so a stitched stream carries both. They are ONE model call
+  // and must read as one — with the cost, or the re-emit gained nothing.
+  const unpriced: DiagnosticEntry = {
+    kind: 'turn',
+    turnIndex: '0',
+    timestamp: '2026-01-01T00:00:01.000Z',
+    toolNames: [],
+  };
+  const priced: DiagnosticEntry = {
+    ...unpriced,
+    usage: {
+      costUsd: 0.5,
+      uncachedInputTokens: 100,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      outputTokens: 20,
+    },
+  };
+  for (const order of [
+    [unpriced, priced],
+    [priced, unpriced],
+  ]) {
+    const turns = assembleDebugLog(order, README).timeline.filter((e) => e.kind === 'turn');
+    assert.is(turns.length, 1, 'one turn, not two');
+    assert.equal(turns[0].usage, priced.usage, 'the priced copy wins regardless of stream order');
+  }
+});
+
+Suite('keeps two genuinely-different turns that differ only in usage', () => {
+  // The collapse keys on everything EXCEPT usage, so distinct calls stay distinct — they
+  // differ in timestamp (and turnIndex) whatever else they share.
+  const a: DiagnosticEntry = {
+    kind: 'turn',
+    turnIndex: '0',
+    timestamp: '2026-01-01T00:00:01.000Z',
+    toolNames: [],
+  };
+  const b: DiagnosticEntry = { ...a, turnIndex: '1', timestamp: '2026-01-01T00:00:02.000Z' };
+  const turns = assembleDebugLog([a, b], README).timeline.filter((e) => e.kind === 'turn');
+  assert.is(turns.length, 2);
+});
+
 Suite.run();
 
+// The download path's swap: a stored stream's `meta-snapshot`s replaced by an export-time
+// one. This is the fix for a SILENT bug — the persisted stream only re-appends that block
+// when the config signature changes, so a stitched lifetime log reported the totals frozen
+// at the session's first flush (near-zero spend against a transcript full of priced
+// messages) and nothing about it looked wrong.
+const FreshSuite = createLogicSuite('withFreshMetaSnapshot');
+
+const storedStream: DiagnosticEntry[] = [
+  {
+    kind: 'meta-snapshot',
+    timestamp: '2026-01-01T00:00:00.000Z',
+    meta: { context: { sessionUsage: { costUsd: 0.01 } } },
+    dedupSignature: 'cfg-1',
+  },
+  { kind: 'message', timestamp: '2026-01-01T00:00:01.000Z', role: 'user', content: 'hi' },
+  { kind: 'turn', turnIndex: '0', timestamp: '2026-01-01T00:00:02.000Z', toolNames: [] },
+  { kind: 'event', index: 0, timestamp: '2026-01-01T00:00:03.000Z', type: 'turn.end' },
+];
+
+const freshSnapshot: DiagnosticEntry = {
+  kind: 'meta-snapshot',
+  timestamp: '2026-01-01T02:00:00.000Z',
+  meta: {
+    context: {
+      sessionUsage: {
+        costUsd: 1.25,
+        uncachedInputTokens: 1000,
+        cacheReadTokens: 9000,
+        cacheWriteTokens: 500,
+        outputTokens: 300,
+      },
+    },
+  },
+  dedupSignature: 'cfg-1',
+};
+
+FreshSuite('reports the export-time totals, not the frozen stored ones', () => {
+  const log = assembleDebugLog(withFreshMetaSnapshot(storedStream, freshSnapshot), README);
+  assert.is(log.sessionUsage?.costUsd, 1.25, 'the fresh snapshot supplies the totals');
+  assert.is(log.sessionUsage?.cacheReadTokens, 9000);
+  assert.equal(log.meta, freshSnapshot.meta, 'and the whole meta block is the fresh one');
+});
+
+FreshSuite('keeps every non-snapshot entry', () => {
+  const timeline = assembleDebugLog(
+    withFreshMetaSnapshot(storedStream, freshSnapshot),
+    README,
+  ).timeline;
+  assert.equal(
+    timeline.map((e) => e.kind),
+    ['message', 'turn', 'event'],
+    'the conversation is untouched — only the snapshots are swapped',
+  );
+});
+
+FreshSuite('wins even when the stored snapshot claims a later time', () => {
+  // A stream written on another machine can carry a skewed clock, and reassembly keeps
+  // whichever snapshot claims the later timestamp — so the stale one must be REMOVED
+  // rather than out-timestamped.
+  const skewed: DiagnosticEntry[] = [
+    { ...storedStream[0], timestamp: '2099-01-01T00:00:00.000Z' },
+    ...storedStream.slice(1),
+  ];
+  const log = assembleDebugLog(withFreshMetaSnapshot(skewed, freshSnapshot), README);
+  assert.is(log.sessionUsage?.costUsd, 1.25);
+});
+
+FreshSuite.run();
+
 // GENC-1461: the reasoning/narration/answer split (GENC-1411) emits several messages from ONE model
 // response, so they share `timestamp` + `role` + `subAgentOf`. The message identity key must still
 // tell them apart — otherwise the forward-capture dedup treats them as one and drops all but the

package/src/state/persistence/diagnostics.ts

@@ -2,19 +2,21 @@
  * Server-saved diagnostics (GENC-1351 §5.8) — the forward-only stream that lets
  * the debug log persist across a whole session lifetime, not just the current
  * page load. This module owns the *pure* pieces: the entry type and the
- * reassembly back into the `{ readme, timeline, meta }` debug-log shape. The
- * element owns capture/cadence; the provider owns storage layout.
+ * reassembly back into the `{ readme, sessionUsage, timeline, meta }` debug-log
+ * shape. The element owns capture/cadence; the provider owns storage layout.
  *
  * @packageDocumentation
  */
 
+import type { AggregateUsage } from '@genesislcap/foundation-ai';
+
 /**
  * One entry in the diagnostics stream — the debug-log timeline-entry union
  * (`message` / `turn` / `event`, as `getDebugLog()` builds) plus a point-in-time
  * **`meta-snapshot`** carrying the export-time `meta` block (agent summary,
  * context, active debug snapshot, …). Kept permissive: a provider stores and
  * returns these opaquely, and reassembly reads only `kind`, `timestamp` (for
- * ordering), and `meta` (on a snapshot).
+ * ordering), `usage` (on a turn) and `meta` (on a snapshot).
  *
  * @public
  */
@@ -24,6 +26,16 @@ export interface DiagnosticEntry {
   timestamp?: string;
   /** Present on `meta-snapshot` entries: the export-time `meta` block. */
   meta?: unknown;
+  /**
+   * Present on a `turn` entry once its model call has returned and reported usage —
+   * the four token buckets plus USD for that one call (`TurnSnapshot.usage`).
+   *
+   * Read by the forward-capture delta as well as by readers: the turn entry is
+   * created *before* the call, so a flush that lands mid-call persists it without
+   * usage, and the delta re-emits it once (see `collectDiagnosticsDelta`) so the
+   * priced copy reaches the stream. {@link assembleDebugLog} then collapses the pair.
+   */
+  usage?: AggregateUsage;
   /**
    * Present on `meta-snapshot` entries: a stable signature of the near-static config
    * (excludes volatile timestamp/context/debug-snapshot), used by the forward-capture
@@ -37,6 +49,27 @@ export interface DiagnosticEntry {
 /** The reassembled debug log — the exact shape `getDebugLog()` returns. @public */
 export interface DebugLog {
   readme: readonly string[];
+  /**
+   * Session usage — the four token buckets plus USD cost — lifted out of the newest
+   * `meta-snapshot`'s `meta.context.sessionUsage` so the headline spend figures sit at
+   * the top of an exported log rather than buried under the (large) `meta` block. The
+   * same object, not a second derivation.
+   *
+   * `undefined` when the stream carries no `meta-snapshot`, or one written before the
+   * field existed. Never re-derived from the timeline: the per-request costs the
+   * transports stamped are authoritative, and a ring-buffered timeline can have lost
+   * entries the total still legitimately counts.
+   *
+   * **As current as the snapshot it came from, which is not automatically "now".** The
+   * forward-capture delta only re-appends a `meta-snapshot` when the near-static config
+   * signature changes, so the newest STORED snapshot of a session whose config never
+   * changed is its first — with the totals frozen there. A caller reassembling a stored
+   * stream on its own therefore gets stale figures unless it appends an export-time
+   * snapshot first: see {@link withFreshMetaSnapshot}, which is what the assistant's own
+   * download path does. `meta.timestamp` against the newest timeline entry tells you
+   * which case you are holding.
+   */
+  sessionUsage?: AggregateUsage;
   timeline: DiagnosticEntry[];
   meta: unknown;
 }
@@ -65,6 +98,28 @@ export function diagnosticsMessageKey(entry: DiagnosticEntry): string | null {
     : null;
 }
 
+/**
+ * Identity of a `turn` entry — `turnIndex::timestamp::agentName`.
+ *
+ * Deliberately NOT the serialized entry, which two copies of the same call do not always
+ * share. `buildTimelineEntries` renders `systemPrompt` *relative to the preceding
+ * snapshots* (collapsing it to `<repeated — identical to turn N>` when it matches the
+ * previous full prompt), so if the snapshot holding that full prompt is evicted from the
+ * ring buffer between the unpriced flush and the priced one, the surviving turn renders
+ * its prompt differently and the two serializations diverge. Both copies are in the
+ * stream by then, so nothing would collapse them — and the log whose purpose is per-call
+ * cost would show one model call as two turns, one of them unpriced.
+ *
+ * All three components are fixed when the snapshot is created and never re-derived.
+ * `turnIndex` alone is not enough: it restarts at `'0'` on each page load, and a lifetime
+ * log legitimately holds one turn `'0'` per load. `agentName` separates two sub-agents
+ * invoked in the same parent turn, which share a `turnIndex` prefix by construction (see
+ * `forwardSubAgentSnapshots`).
+ */
+function turnIdentity(entry: DiagnosticEntry): string {
+  return `turn::${String(entry.turnIndex ?? '')}::${entry.timestamp ?? ''}::${String(entry.agentName ?? '')}`;
+}
+
 // Tie-break co-timestamped entries by cause → call → output (event, turn, message),
 // matching the original in-place `getDebugLog` sort.
 const KIND_RANK: Record<string, number> = { event: 0, turn: 1, message: 2 };
@@ -73,16 +128,23 @@ const KIND_RANK: Record<string, number> = { event: 0, turn: 1, message: 2 };
 const UNKNOWN_KIND_RANK = 99;
 
 /**
- * Reassemble diagnostic entries into the `{ readme, timeline, meta }` debug-log
- * shape (GENC-1351 §5.8). `timeline` = the `message`/`turn`/`event` entries sorted
+ * Reassemble diagnostic entries into the `{ readme, sessionUsage, timeline, meta }`
+ * debug-log shape (GENC-1351 §5.8). `timeline` = the `message`/`turn`/`event` entries sorted
  * by ISO `timestamp` (kind-rank tie-break). `meta` = the **newest** `meta-snapshot`'s
  * block only — a "state at export" photo, matching the single-page log. The older
  * snapshots are intentionally dropped: the per-turn evolution they would show is
  * already in the timeline (`turn.agentSnapshot` + `context.updated` events), so
  * keeping them would just repeat the bulky, near-static `agentSummary`. `readme` =
- * the passed (current) constant. Pure — reused for both the live current-page log
- * and the reassembled lifetime log stitched from the persisted stream, so both
- * come out shape-identical.
+ * the passed (current) constant. `sessionUsage` = that same newest snapshot's
+ * `meta.context.sessionUsage`, lifted to the top level. Pure — reused for both the
+ * live current-page log and the reassembled lifetime log stitched from the persisted
+ * stream, so both come out shape-identical.
+ *
+ * NOTE for a caller stitching a STORED stream (a headless consumer harvesting its own
+ * lifetime log, say): the newest stored `meta-snapshot` is frozen at the last
+ * config-signature change, so `meta` and `sessionUsage` are as old as that unless you
+ * pass a fresh snapshot of your own — {@link withFreshMetaSnapshot} does exactly that,
+ * and the element's download path goes through it.
  */
 export function assembleDebugLog(entries: DiagnosticEntry[], readme: readonly string[]): DebugLog {
   // Safety net for exact-duplicate entries: two element instances sharing one
@@ -92,20 +154,31 @@ export function assembleDebugLog(entries: DiagnosticEntry[], readme: readonly st
   // (e.g. two real `assistant.connected` from two instances) differ in index /
   // placement and are kept. (The shared cursor store prevents most of this at
   // write time; this guards the read path regardless of what's in the stream.)
-  const seen = new Set<string>();
+  //
+  // A `turn` is identified by `turnIndex` + `timestamp` + `agentName` instead (see
+  // `turnIdentity`), so the unpriced copy a mid-call flush persisted and the priced copy
+  // that follows it collapse into ONE turn — the priced one — rather than reading as two
+  // model calls.
+  const seenAt = new Map<string, number>();
   let latestMeta: DiagnosticEntry | undefined;
   const timeline: DiagnosticEntry[] = [];
   for (const entry of entries) {
-    const id = JSON.stringify(entry);
-    if (seen.has(id)) continue;
-    seen.add(id);
     if (entry.kind === 'meta-snapshot') {
       if (!latestMeta || (entry.timestamp ?? '') >= (latestMeta.timestamp ?? '')) {
         latestMeta = entry;
       }
-    } else {
-      timeline.push(entry);
+      continue;
+    }
+    const id = entry.kind === 'turn' ? turnIdentity(entry) : JSON.stringify(entry);
+    const at = seenAt.get(id);
+    if (at !== undefined) {
+      // Same entry seen twice — keep the richer copy. `usage` on a turn is the only
+      // field that can arrive late, so it is the only upgrade there is to make.
+      if (entry.usage && !timeline[at].usage) timeline[at] = entry;
+      continue;
     }
+    seenAt.set(id, timeline.length);
+    timeline.push(entry);
   }
   timeline.sort((a, b) => {
     const ta = a.timestamp ?? '';
@@ -114,5 +187,34 @@ export function assembleDebugLog(entries: DiagnosticEntry[], readme: readonly st
     if (ta > tb) return 1;
     return (KIND_RANK[a.kind] ?? UNKNOWN_KIND_RANK) - (KIND_RANK[b.kind] ?? UNKNOWN_KIND_RANK);
   });
-  return { readme, timeline, meta: latestMeta?.meta };
+  // The session totals live inside the newest snapshot's `meta`, which is `unknown` by
+  // design (a provider stores these opaquely) — so this narrows just the one path it
+  // reads rather than typing the whole block.
+  const context = (latestMeta?.meta as { context?: { sessionUsage?: AggregateUsage } } | undefined)
+    ?.context;
+  return { readme, sessionUsage: context?.sessionUsage, timeline, meta: latestMeta?.meta };
+}
+
+/**
+ * A stored diagnostics stream with its `meta-snapshot`s replaced by `fresh` — what to
+ * pass {@link assembleDebugLog} when reassembling a persisted stream for export.
+ *
+ * The stored snapshots are dropped rather than out-timestamped. `assembleDebugLog` keeps
+ * whichever claims the later time, and a stream written on another machine can carry a
+ * skewed clock; `fresh` is built from live state and so is the more current by
+ * construction. Only one snapshot ever survives reassembly, so the count is unchanged —
+ * though a snapshot taken while the driver is unwired (mid-popout) can leave
+ * `activeFoldStack`/`activeDebugSnapshot` unset where a stored one had them. The figures
+ * this exists for — the context block and `sessionUsage` — read the session store and
+ * element props, which survive an unwire.
+ *
+ * Pure, and separate from the element for that reason: the swap it performs is the fix
+ * for a silent bug (a lifetime log reporting near-zero spend against a transcript full of
+ * priced messages), so it needs to be testable without mounting anything.
+ */
+export function withFreshMetaSnapshot(
+  stored: readonly DiagnosticEntry[],
+  fresh: DiagnosticEntry,
+): DiagnosticEntry[] {
+  return [...stored.filter((e) => e.kind !== 'meta-snapshot'), fresh];
 }

package/src/state/persistence/index.ts

@@ -6,5 +6,5 @@ export type {
   SessionPersistenceConfig,
   SessionPreferences,
 } from './session-persistence-provider';
-export { assembleDebugLog } from './diagnostics';
+export { assembleDebugLog, withFreshMetaSnapshot } from './diagnostics';
 export type { DiagnosticEntry, DebugLog } from './diagnostics';

package/src/state/persistence/session-persister.test.ts

@@ -465,6 +465,43 @@ Suite(
   },
 );
 
+Suite('flushDiagnostics() re-emits a turn once its per-call usage lands', async () => {
+  // A turn entry is created BEFORE its model call and priced when the response returns,
+  // so a flush landing in between persists it unpriced. Emitting it exactly once more —
+  // when `usage` is there — is what keeps per-call cost in a stitched lifetime log;
+  // `assembleDebugLog` collapses the pair back onto the priced copy.
+  const inFlight: DiagnosticEntry = {
+    kind: 'turn',
+    turnIndex: '0',
+    timestamp: '2026-01-01T00:00:01.000Z',
+    toolNames: [],
+  };
+  const { p, f } = makePersister({ diagnosticEntries: [inFlight] });
+  await p.flushDiagnostics();
+  assert.is(f.appended.length, 1, 'the unpriced turn is captured');
+  assert.is(f.appended[0][0].usage, undefined);
+
+  const priced: DiagnosticEntry = {
+    ...inFlight,
+    usage: {
+      costUsd: 0.25,
+      uncachedInputTokens: 100,
+      cacheReadTokens: 900,
+      cacheWriteTokens: 0,
+      outputTokens: 40,
+    },
+  };
+  f.diagnosticEntries = [priced];
+  await p.flushDiagnostics();
+  assert.is(f.appended.length, 2, 'the priced copy is appended');
+  assert.equal(f.appended[1][0].usage, priced.usage);
+
+  // ...and only once. A throttled flush runs on every transcript change, so a turn that
+  // re-emitted per flush would multiply the biggest entries in the stream.
+  await p.flushDiagnostics();
+  assert.is(f.appended.length, 2, 'no further re-append of the priced turn');
+});
+
 Suite(
   'flushDiagnostics() still dedups a genuine re-append of the same message across flushes',
   async () => {

package/src/state/persistence/session-persister.ts

@@ -635,9 +635,10 @@ export class SessionPersister {
 
   /**
    * The diagnostic entries not yet appended this load — the forward-capture delta
-   * (§5.8). Skips messages present at restore or already appended; emits each turn
-   * (by turn-index) and meta-event (by index) once; appends a `meta-snapshot` only
-   * when the block changed. Advances the shared per-session cursors as it goes.
+   * (§5.8). Skips messages present at restore or already appended; emits each meta-event
+   * (by index) once and each turn (by turn-index) once unpriced plus once more when its
+   * per-call `usage` lands; appends a `meta-snapshot` only when the block changed.
+   * Advances the shared per-session cursors as it goes.
    *
    * TODO(GENC-1461, longer-term): this whole delta step exists only because the element *pulls* the
    * ENTIRE debug log on every throttled flush (`getDiagnosticEntries()` returns the full timeline),
@@ -663,9 +664,16 @@ export class SessionPersister {
         }
         delta.push(entry);
       } else if (entry.kind === 'turn') {
+        // A turn entry is created BEFORE its model call and priced when the response
+        // lands, so a flush that falls in between persists it unpriced. Emit it a second
+        // time once `usage` is there — keyed separately so it happens at most once per
+        // turn — and let `assembleDebugLog` collapse the pair onto the priced copy.
+        // Without this the stitched lifetime log silently loses per-call cost for any
+        // turn that outlived a flush, which is most of the slow ones.
         const key = String(entry.turnIndex ?? '');
-        if (cursors.emittedTurnKeys.has(key)) continue;
-        cursors.emittedTurnKeys.add(key);
+        const emitKey = entry.usage ? `${key}::usage` : key;
+        if (cursors.emittedTurnKeys.has(emitKey)) continue;
+        cursors.emittedTurnKeys.add(emitKey);
         delta.push(entry);
       } else if (entry.kind === 'event') {
         const index = typeof entry.index === 'number' ? entry.index : -1;

package/src/utils/sum-usage.test.ts

@@ -1,6 +1,6 @@
 import type { ChatMessage } from '@genesislcap/foundation-ai';
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { addUsage, emptyUsage, sumUsage, totalTokens } from './sum-usage';
+import { addUsage, emptyUsage, messageUsage, sumUsage, totalTokens } from './sum-usage';
 
 const suite = createLogicSuite('sumUsage');
 
@@ -137,4 +137,55 @@ suite('addUsage with an empty operand is the identity', () => {
   assert.equal(addUsage(emptyUsage(), a), a);
 });
 
+suite('messageUsage is undefined for a message reporting nothing', () => {
+  // A user turn, or a display-only reasoning/narration split. Distinct from a zeroed
+  // usage: "this call reported nothing" is not "this call cost nothing".
+  assert.is(messageUsage(msg({ role: 'user', content: 'hi' })), undefined);
+  assert.is(messageUsage(msg({ content: 'thinking…', category: 'reasoning' })), undefined);
+});
+
+suite('messageUsage agrees with sumUsage over the same single message', () => {
+  // The two derivations are deliberately separate — `accumulate` mutates one
+  // accumulator rather than allocating per message — so pin them together. A drift
+  // here would put one figure on a turn entry and a different one in the session
+  // total, both looking plausible.
+  const cases: Partial<ChatMessage>[] = [
+    { inputTokens: 1000, cacheReadTokens: 700, cacheWriteTokens: 200, outputTokens: 50, cost: 0.4 },
+    { inputTokens: 400, outputTokens: 60 },
+    { inputTokens: 100, cacheReadTokens: 90, cacheWriteTokens: 90 },
+    { cost: 0.01, externalCostUsd: 0.02 },
+  ];
+  for (const over of cases) {
+    const m = msg(over);
+    assert.equal(
+      messageUsage(m),
+      sumUsage([m]),
+      `messageUsage must match sumUsage for ${JSON.stringify(over)}`,
+    );
+  }
+});
+
+suite('messageUsage is shallow — it prices the one request, not the tree', () => {
+  // Deliberately blind to sub-agent traces and banked compaction usage: it answers
+  // "what did this call cost", which is what a turn snapshot needs. `sumUsage` is the
+  // function that walks everything underneath.
+  const m = msg({
+    inputTokens: 100,
+    outputTokens: 10,
+    cost: 0.05,
+    toolCalls: [
+      {
+        id: 't1',
+        name: 'delegate',
+        args: {},
+        subAgentTrace: [msg({ inputTokens: 900, outputTokens: 90, cost: 0.5 })],
+      },
+    ],
+  });
+  const usage = messageUsage(m)!;
+  assert.is(usage.costUsd, 0.05, 'the child conversation is not folded in');
+  assert.is(usage.uncachedInputTokens, 100);
+  assert.ok(sumUsage([m]).costUsd > usage.costUsd, 'sumUsage does fold it in');
+});
+
 suite.run();

package/src/utils/sum-usage.ts

@@ -53,6 +53,51 @@ export function addUsage(a: AggregateUsage, b: AggregateUsage): AggregateUsage {
   };
 }
 
+/**
+ * The four buckets plus USD for ONE message — the per-message fields projected into
+ * the disjoint, addable shape, or `undefined` when the message reports no usage at
+ * all (a user turn, a display-only reasoning/narration split, a provider that
+ * reports none).
+ *
+ * Shallow by design: it does NOT recurse into `toolCalls[].subAgentTrace` and does
+ * NOT count `compaction.rolledUpUsage`, so it answers "what did this one request
+ * cost" rather than "what did this message and everything under it cost". Use
+ * {@link sumUsage} for the latter — passing a whole transcript through this one
+ * message at a time would silently drop both.
+ *
+ * `costUsd` folds in `externalCostUsd` (non-LLM spend a widget reported), matching
+ * `sumUsage`. It is `0` when the provider priced nothing, which is NOT a claim that
+ * the call was free — see {@link AggregateUsage}; `UsageRow.costUsd` is the
+ * shape that keeps unpriced distinguishable, and is the right tool for a ledger.
+ *
+ * @beta
+ */
+export function messageUsage(m: ChatMessage): AggregateUsage | undefined {
+  if (
+    m.cost == null &&
+    m.externalCostUsd == null &&
+    m.inputTokens == null &&
+    m.outputTokens == null &&
+    m.cacheReadTokens == null &&
+    m.cacheWriteTokens == null
+  ) {
+    return undefined;
+  }
+  const cacheReadTokens = m.cacheReadTokens ?? 0;
+  const cacheWriteTokens = m.cacheWriteTokens ?? 0;
+  return {
+    costUsd: (m.cost ?? 0) + (m.externalCostUsd ?? 0),
+    // The uncached REMAINDER, clamped — the same arithmetic `accumulate` below applies,
+    // for the same reasons. The two are deliberately separate implementations (that walk
+    // mutates one accumulator rather than allocating per message) and must agree;
+    // `sum-usage.test.ts` pins them together.
+    uncachedInputTokens: Math.max(0, (m.inputTokens ?? 0) - cacheReadTokens - cacheWriteTokens),
+    cacheReadTokens,
+    cacheWriteTokens,
+    outputTokens: m.outputTokens ?? 0,
+  };
+}
+
 /**
  * Sum cost and per-bucket token usage across a message list.
  *