@genesislcap/ai-assistant 15.12.0 → 15.13.0

package/dist/esm/state/persistence/diagnostics.js

@@ -2,8 +2,8 @@
  * 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
  */
@@ -31,6 +31,28 @@ export function diagnosticsMessageKey(entry) {
         ? `${entry.timestamp}::${(_a = entry.role) !== null && _a !== void 0 ? _a : ''}::${(_b = entry.subAgentOf) !== null && _b !== void 0 ? _b : ''}::${(_c = entry.category) !== null && _c !== void 0 ? _c : ''}`
         : 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) {
+    var _a, _b, _c;
+    return `turn::${String((_a = entry.turnIndex) !== null && _a !== void 0 ? _a : '')}::${(_b = entry.timestamp) !== null && _b !== void 0 ? _b : ''}::${String((_c = entry.agentName) !== null && _c !== void 0 ? _c : '')}`;
+}
 // Tie-break co-timestamped entries by cause → call → output (event, turn, message),
 // matching the original in-place `getDebugLog` sort.
 const KIND_RANK = { event: 0, turn: 1, message: 2 };
@@ -38,19 +60,26 @@ const KIND_RANK = { event: 0, turn: 1, message: 2 };
 // are filtered out first) sorts last.
 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, readme) {
-    var _a, _b;
+    var _a, _b, _c;
     // Safety net for exact-duplicate entries: two element instances sharing one
     // session (bubble + popped-out panel) can each append the same entry, and a
     // reload's second instance can re-append restored history. Such copies are
@@ -58,22 +87,32 @@ export function assembleDebugLog(entries, readme) {
     // (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();
+    //
+    // 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();
     let latestMeta;
     const timeline = [];
     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 || ((_a = entry.timestamp) !== null && _a !== void 0 ? _a : '') >= ((_b = latestMeta.timestamp) !== null && _b !== void 0 ? _b : '')) {
                 latestMeta = entry;
             }
+            continue;
         }
-        else {
-            timeline.push(entry);
+        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) => {
         var _a, _b, _c, _d;
@@ -85,5 +124,29 @@ export function assembleDebugLog(entries, readme) {
             return 1;
         return ((_c = KIND_RANK[a.kind]) !== null && _c !== void 0 ? _c : UNKNOWN_KIND_RANK) - ((_d = KIND_RANK[b.kind]) !== null && _d !== void 0 ? _d : UNKNOWN_KIND_RANK);
     });
-    return { readme, timeline, meta: latestMeta === null || latestMeta === void 0 ? void 0 : 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 = (_c = latestMeta === null || latestMeta === void 0 ? void 0 : latestMeta.meta) === null || _c === void 0 ? void 0 : _c.context;
+    return { readme, sessionUsage: context === null || context === void 0 ? void 0 : context.sessionUsage, timeline, meta: latestMeta === null || latestMeta === void 0 ? void 0 : 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, fresh) {
+    return [...stored.filter((e) => e.kind !== 'meta-snapshot'), fresh];
 }

package/dist/esm/state/persistence/diagnostics.test.js

@@ -1,5 +1,5 @@
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { assembleDebugLog, diagnosticsMessageKey } from './diagnostics';
+import { assembleDebugLog, diagnosticsMessageKey, withFreshMetaSnapshot, } from './diagnostics';
 // GENC-1351 §5.8: `assembleDebugLog` reassembles the forward-only diagnostics
 // stream back into the `{ readme, timeline, meta }` debug-log shape — timeline
 // sorted by timestamp, meta-snapshots pulled out with the latest winning.
@@ -69,7 +69,180 @@ Suite('collapses exact-duplicate entries but keeps genuinely-distinct ones', ()
     assert.is(timeline.filter((e) => e.kind === 'message').length, 1, 'identical message collapsed');
     assert.is(timeline.filter((e) => e.type === 'assistant.connected').length, 2, 'two distinct connects (different index) kept; the repeated connA collapsed');
 });
+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 = [
+        {
+            kind: 'meta-snapshot',
+            timestamp: '2026-01-01T00:00:01.000Z',
+            meta: { context: { sessionUsage: Object.assign(Object.assign({}, 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 = [
+        { 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 = {
+        kind: 'turn',
+        turnIndex: '7',
+        timestamp: '2026-01-01T00:00:01.000Z',
+        agentName: 'Trade Operations',
+        systemPrompt: '<repeated — identical to turn 0>',
+        toolNames: [],
+    };
+    const priced = Object.assign(Object.assign({}, 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 = {
+        kind: 'turn',
+        turnIndex: '0',
+        timestamp: '2026-01-01T00:00:01.000Z',
+        agentName: 'Booker',
+        toolNames: [],
+    };
+    const load2 = Object.assign(Object.assign({}, load1), { timestamp: '2026-01-02T09:00:00.000Z' });
+    const sibling = Object.assign(Object.assign({}, load1), { turnIndex: '3-1', agentName: 'Planner' });
+    const cousin = Object.assign(Object.assign({}, 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 = {
+        kind: 'turn',
+        turnIndex: '0',
+        timestamp: '2026-01-01T00:00:01.000Z',
+        toolNames: [],
+    };
+    const priced = Object.assign(Object.assign({}, 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 = {
+        kind: 'turn',
+        turnIndex: '0',
+        timestamp: '2026-01-01T00:00:01.000Z',
+        toolNames: [],
+    };
+    const b = Object.assign(Object.assign({}, 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 = [
+    {
+        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 = {
+    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', () => {
+    var _a, _b;
+    const log = assembleDebugLog(withFreshMetaSnapshot(storedStream, freshSnapshot), README);
+    assert.is((_a = log.sessionUsage) === null || _a === void 0 ? void 0 : _a.costUsd, 1.25, 'the fresh snapshot supplies the totals');
+    assert.is((_b = log.sessionUsage) === null || _b === void 0 ? void 0 : _b.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', () => {
+    var _a;
+    // 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 = [
+        Object.assign(Object.assign({}, storedStream[0]), { timestamp: '2099-01-01T00:00:00.000Z' }),
+        ...storedStream.slice(1),
+    ];
+    const log = assembleDebugLog(withFreshMetaSnapshot(skewed, freshSnapshot), README);
+    assert.is((_a = log.sessionUsage) === null || _a === void 0 ? void 0 : _a.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/dist/esm/state/persistence/index.js

@@ -1,3 +1,3 @@
 export { PERSISTED_SESSION_VERSION } from './session-snapshot';
 export { WebStorageSessionProvider } from './session-persistence-provider';
-export { assembleDebugLog } from './diagnostics';
+export { assembleDebugLog, withFreshMetaSnapshot } from './diagnostics';

package/dist/esm/state/persistence/session-persister.js

@@ -582,9 +582,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),
@@ -613,10 +614,17 @@ 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((_a = entry.turnIndex) !== null && _a !== void 0 ? _a : '');
-                if (cursors.emittedTurnKeys.has(key))
+                const emitKey = entry.usage ? `${key}::usage` : key;
+                if (cursors.emittedTurnKeys.has(emitKey))
                     continue;
-                cursors.emittedTurnKeys.add(key);
+                cursors.emittedTurnKeys.add(emitKey);
                 delta.push(entry);
             }
             else if (entry.kind === 'event') {

package/dist/esm/state/persistence/session-persister.test.js

@@ -336,6 +336,37 @@ Suite('flushDiagnostics() keeps co-timestamped split messages (reasoning + answe
     assert.is(f.appended.length, 1, 'one flush');
     assert.is(f.appended[0].length, 2, 'both the reasoning and the answer message are captured, not collapsed to one');
 }));
+Suite('flushDiagnostics() re-emits a turn once its per-call usage lands', () => __awaiter(void 0, void 0, void 0, function* () {
+    // 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 = {
+        kind: 'turn',
+        turnIndex: '0',
+        timestamp: '2026-01-01T00:00:01.000Z',
+        toolNames: [],
+    };
+    const { p, f } = makePersister({ diagnosticEntries: [inFlight] });
+    yield p.flushDiagnostics();
+    assert.is(f.appended.length, 1, 'the unpriced turn is captured');
+    assert.is(f.appended[0][0].usage, undefined);
+    const priced = Object.assign(Object.assign({}, inFlight), { usage: {
+            costUsd: 0.25,
+            uncachedInputTokens: 100,
+            cacheReadTokens: 900,
+            cacheWriteTokens: 0,
+            outputTokens: 40,
+        } });
+    f.diagnosticEntries = [priced];
+    yield 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.
+    yield 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', () => __awaiter(void 0, void 0, void 0, function* () {
     // The dedup must still stop the SAME message being re-appended on every throttled flush.
     const m = diagMsg({ category: 'reasoning', content: 'thinking…' });

package/dist/esm/utils/sum-usage.js

@@ -46,6 +46,49 @@ export function addUsage(a, b) {
         outputTokens: a.outputTokens + b.outputTokens,
     };
 }
+/**
+ * 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) {
+    var _a, _b, _c, _d, _e, _f;
+    if (m.cost == null &&
+        m.externalCostUsd == null &&
+        m.inputTokens == null &&
+        m.outputTokens == null &&
+        m.cacheReadTokens == null &&
+        m.cacheWriteTokens == null) {
+        return undefined;
+    }
+    const cacheReadTokens = (_a = m.cacheReadTokens) !== null && _a !== void 0 ? _a : 0;
+    const cacheWriteTokens = (_b = m.cacheWriteTokens) !== null && _b !== void 0 ? _b : 0;
+    return {
+        costUsd: ((_c = m.cost) !== null && _c !== void 0 ? _c : 0) + ((_d = m.externalCostUsd) !== null && _d !== void 0 ? _d : 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, ((_e = m.inputTokens) !== null && _e !== void 0 ? _e : 0) - cacheReadTokens - cacheWriteTokens),
+        cacheReadTokens,
+        cacheWriteTokens,
+        outputTokens: (_f = m.outputTokens) !== null && _f !== void 0 ? _f : 0,
+    };
+}
 /**
  * Sum cost and per-bucket token usage across a message list.
  *

package/dist/esm/utils/sum-usage.test.js

@@ -1,5 +1,5 @@
 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');
 const msg = (over = {}) => (Object.assign({ role: 'assistant', content: '' }, over));
 suite('returns zeroes when no message carries usage', () => {
@@ -117,4 +117,48 @@ suite('addUsage with an empty operand is the identity', () => {
     assert.equal(addUsage(a, emptyUsage()), a);
     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 = [
+        { 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/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/chat-driver-node.ts","../src/index.ts","../src/channel/ai-activity-bus.ts","../src/channel/ai-activity-channel.ts","../src/components/flowing-waves-indicator.ts","../src/components/halo-overlay.ts","../src/components/plasma-orb-indicator.ts","../src/components/waves-indicator.ts","../src/components/activity-halo/activity-halo.ts","../src/components/agent-picker/agent-picker.constants.ts","../src/components/agent-picker/agent-picker.styles.ts","../src/components/agent-picker/agent-picker.template.ts","../src/components/agent-picker/agent-picker.ts","../src/components/agent-picker/index.ts","../src/components/ai-driver/ai-driver.ts","../src/components/ai-driver/index.ts","../src/components/chat-bubble/chat-bubble.styles.ts","../src/components/chat-bubble/chat-bubble.template.ts","../src/components/chat-bubble/chat-bubble.ts","../src/components/chat-bubble/index.ts","../src/components/chat-driver/align-event-globals.ts","../src/components/chat-driver/chat-driver.compact.test.ts","../src/components/chat-driver/chat-driver.invocation-scope.test.ts","../src/components/chat-driver/chat-driver.test.ts","../src/components/chat-driver/chat-driver.thinking-policy.test.ts","../src/components/chat-driver/chat-driver.trace-capture.test.ts","../src/components/chat-driver/chat-driver.ts","../src/components/chat-driver/index.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.styles.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.template.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.test.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts","../src/components/chat-interaction-wrapper/index.ts","../src/components/chat-markdown/chat-markdown.ts","../src/components/chat-markdown/index.ts","../src/components/orchestrating-driver/index.ts","../src/components/orchestrating-driver/orchestrating-driver.budget.test.ts","../src/components/orchestrating-driver/orchestrating-driver.pin.test.ts","../src/components/orchestrating-driver/orchestrating-driver.ts","../src/components/popout-manager/index.ts","../src/components/popout-manager/popout-manager.ts","../src/components/settings-modal/index.ts","../src/components/settings-modal/settings-modal.styles.test.ts","../src/components/settings-modal/settings-modal.styles.ts","../src/components/settings-modal/settings-modal.template.test.ts","../src/components/settings-modal/settings-modal.template.ts","../src/config/config.ts","../src/config/define-stateful-agent.test.ts","../src/config/define-stateful-agent.ts","../src/config/fallback-agents.ts","../src/config/index.ts","../src/config/validate-providers.test.ts","../src/config/validate-providers.ts","../src/main/blocked-state.test.ts","../src/main/budget-meter.test.ts","../src/main/cost-session-banking.test.ts","../src/main/index.ts","../src/main/main.styles.test.ts","../src/main/main.styles.ts","../src/main/main.template.ts","../src/main/main.ts","../src/main/main.types.ts","../src/main/popout-interaction-gate.test.ts","../src/provider/ai-provider-switcher.ts","../src/provider/assistant-app-settings.ts","../src/state/ai-assistant-slice.test.ts","../src/state/ai-assistant-slice.ts","../src/state/debug-event-log.test.ts","../src/state/debug-event-log.ts","../src/state/driver-registry.test.ts","../src/state/driver-registry.ts","../src/state/interaction-context.test.ts","../src/state/interaction-context.ts","../src/state/session-store.ts","../src/state/persistence/build-timeline-entries.ts","../src/state/persistence/diagnostics-cursors.test.ts","../src/state/persistence/diagnostics-cursors.ts","../src/state/persistence/diagnostics.test.ts","../src/state/persistence/diagnostics.ts","../src/state/persistence/index.ts","../src/state/persistence/persister-registry.ts","../src/state/persistence/session-persistence-provider.test.ts","../src/state/persistence/session-persistence-provider.ts","../src/state/persistence/session-persistence.integration.test.ts","../src/state/persistence/session-persister.test.ts","../src/state/persistence/session-persister.ts","../src/state/persistence/session-snapshot.test.ts","../src/state/persistence/session-snapshot.ts","../src/state/persistence/stateful-restore.e2e.test.ts","../src/styles/ai-colours.ts","../src/styles/settings-section.ts","../src/suggestions/chat-suggestions.ts","../src/tags/index.ts","../src/types/ai-chat-widget.ts","../src/types/interaction-context.ts","../src/utils/animated-panel-toggle.ts","../src/utils/animation-exclusivity.test.ts","../src/utils/animation-exclusivity.ts","../src/utils/banked-usage-baselines.ts","../src/utils/collect-session-models.test.ts","../src/utils/collect-session-models.ts","../src/utils/condense-history.test.ts","../src/utils/condense-history.ts","../src/utils/cost-session-history.test.ts","../src/utils/cost-session-history.ts","../src/utils/derive-cost-session-title.test.ts","../src/utils/derive-cost-session-title.ts","../src/utils/flatten-sub-agent-messages.test.ts","../src/utils/flatten-sub-agent-messages.ts","../src/utils/format-usd.ts","../src/utils/history-transform.test.ts","../src/utils/history-transform.ts","../src/utils/index.ts","../src/utils/logger.ts","../src/utils/message-partition.test.ts","../src/utils/message-partition.ts","../src/utils/resolve-cost-history-config.test.ts","../src/utils/resolve-cost-history-config.ts","../src/utils/resolve-preference-baseline.test.ts","../src/utils/resolve-preference-baseline.ts","../src/utils/strip-agent-handlers.test.ts","../src/utils/strip-agent-handlers.ts","../src/utils/sum-costs.test.ts","../src/utils/sum-costs.ts","../src/utils/sum-tokens.test.ts","../src/utils/sum-tokens.ts","../src/utils/sum-usage.test.ts","../src/utils/sum-usage.ts","../src/utils/tool-fold.ts","../src/utils/usage-rows.test.ts","../src/utils/usage-rows.ts","../src/utils/with-timeout.ts"],"version":"5.9.2"}
+{"root":["../src/chat-driver-node.ts","../src/index.ts","../src/channel/ai-activity-bus.ts","../src/channel/ai-activity-channel.ts","../src/components/flowing-waves-indicator.ts","../src/components/halo-overlay.ts","../src/components/plasma-orb-indicator.ts","../src/components/waves-indicator.ts","../src/components/activity-halo/activity-halo.ts","../src/components/agent-picker/agent-picker.constants.ts","../src/components/agent-picker/agent-picker.styles.ts","../src/components/agent-picker/agent-picker.template.ts","../src/components/agent-picker/agent-picker.ts","../src/components/agent-picker/index.ts","../src/components/ai-driver/ai-driver.ts","../src/components/ai-driver/index.ts","../src/components/chat-bubble/chat-bubble.styles.ts","../src/components/chat-bubble/chat-bubble.template.ts","../src/components/chat-bubble/chat-bubble.ts","../src/components/chat-bubble/index.ts","../src/components/chat-driver/align-event-globals.ts","../src/components/chat-driver/chat-driver.compact.test.ts","../src/components/chat-driver/chat-driver.invocation-scope.test.ts","../src/components/chat-driver/chat-driver.test.ts","../src/components/chat-driver/chat-driver.thinking-policy.test.ts","../src/components/chat-driver/chat-driver.trace-capture.test.ts","../src/components/chat-driver/chat-driver.ts","../src/components/chat-driver/chat-driver.turn-usage.test.ts","../src/components/chat-driver/index.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.styles.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.template.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.test.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts","../src/components/chat-interaction-wrapper/index.ts","../src/components/chat-markdown/chat-markdown.ts","../src/components/chat-markdown/index.ts","../src/components/orchestrating-driver/index.ts","../src/components/orchestrating-driver/orchestrating-driver.budget.test.ts","../src/components/orchestrating-driver/orchestrating-driver.pin.test.ts","../src/components/orchestrating-driver/orchestrating-driver.ts","../src/components/popout-manager/index.ts","../src/components/popout-manager/popout-manager.ts","../src/components/settings-modal/index.ts","../src/components/settings-modal/settings-modal.styles.test.ts","../src/components/settings-modal/settings-modal.styles.ts","../src/components/settings-modal/settings-modal.template.test.ts","../src/components/settings-modal/settings-modal.template.ts","../src/config/config.ts","../src/config/define-stateful-agent.test.ts","../src/config/define-stateful-agent.ts","../src/config/fallback-agents.ts","../src/config/index.ts","../src/config/validate-providers.test.ts","../src/config/validate-providers.ts","../src/main/blocked-state.test.ts","../src/main/budget-meter.test.ts","../src/main/cost-session-banking.test.ts","../src/main/index.ts","../src/main/main.styles.test.ts","../src/main/main.styles.ts","../src/main/main.template.ts","../src/main/main.ts","../src/main/main.types.ts","../src/main/popout-interaction-gate.test.ts","../src/provider/ai-provider-switcher.ts","../src/provider/assistant-app-settings.ts","../src/state/ai-assistant-slice.test.ts","../src/state/ai-assistant-slice.ts","../src/state/debug-event-log.test.ts","../src/state/debug-event-log.ts","../src/state/driver-registry.test.ts","../src/state/driver-registry.ts","../src/state/interaction-context.test.ts","../src/state/interaction-context.ts","../src/state/session-store.ts","../src/state/persistence/build-timeline-entries.ts","../src/state/persistence/diagnostics-cursors.test.ts","../src/state/persistence/diagnostics-cursors.ts","../src/state/persistence/diagnostics.test.ts","../src/state/persistence/diagnostics.ts","../src/state/persistence/index.ts","../src/state/persistence/persister-registry.ts","../src/state/persistence/session-persistence-provider.test.ts","../src/state/persistence/session-persistence-provider.ts","../src/state/persistence/session-persistence.integration.test.ts","../src/state/persistence/session-persister.test.ts","../src/state/persistence/session-persister.ts","../src/state/persistence/session-snapshot.test.ts","../src/state/persistence/session-snapshot.ts","../src/state/persistence/stateful-restore.e2e.test.ts","../src/styles/ai-colours.ts","../src/styles/settings-section.ts","../src/suggestions/chat-suggestions.ts","../src/tags/index.ts","../src/types/ai-chat-widget.ts","../src/types/interaction-context.ts","../src/utils/animated-panel-toggle.ts","../src/utils/animation-exclusivity.test.ts","../src/utils/animation-exclusivity.ts","../src/utils/banked-usage-baselines.ts","../src/utils/collect-session-models.test.ts","../src/utils/collect-session-models.ts","../src/utils/condense-history.test.ts","../src/utils/condense-history.ts","../src/utils/cost-session-history.test.ts","../src/utils/cost-session-history.ts","../src/utils/derive-cost-session-title.test.ts","../src/utils/derive-cost-session-title.ts","../src/utils/flatten-sub-agent-messages.test.ts","../src/utils/flatten-sub-agent-messages.ts","../src/utils/format-usd.ts","../src/utils/history-transform.test.ts","../src/utils/history-transform.ts","../src/utils/index.ts","../src/utils/logger.ts","../src/utils/message-partition.test.ts","../src/utils/message-partition.ts","../src/utils/resolve-cost-history-config.test.ts","../src/utils/resolve-cost-history-config.ts","../src/utils/resolve-preference-baseline.test.ts","../src/utils/resolve-preference-baseline.ts","../src/utils/strip-agent-handlers.test.ts","../src/utils/strip-agent-handlers.ts","../src/utils/sum-costs.test.ts","../src/utils/sum-costs.ts","../src/utils/sum-tokens.test.ts","../src/utils/sum-tokens.ts","../src/utils/sum-usage.test.ts","../src/utils/sum-usage.ts","../src/utils/tool-fold.ts","../src/utils/usage-rows.test.ts","../src/utils/usage-rows.ts","../src/utils/with-timeout.ts"],"version":"5.9.2"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "15.12.0",
+  "version": "15.13.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -73,26 +73,26 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.12.0",
-    "@genesislcap/genx": "15.12.0",
-    "@genesislcap/rollup-builder": "15.12.0",
-    "@genesislcap/ts-builder": "15.12.0",
-    "@genesislcap/uvu-playwright-builder": "15.12.0",
-    "@genesislcap/vite-builder": "15.12.0",
-    "@genesislcap/webpack-builder": "15.12.0",
+    "@genesislcap/foundation-testing": "15.13.0",
+    "@genesislcap/genx": "15.13.0",
+    "@genesislcap/rollup-builder": "15.13.0",
+    "@genesislcap/ts-builder": "15.13.0",
+    "@genesislcap/uvu-playwright-builder": "15.13.0",
+    "@genesislcap/vite-builder": "15.13.0",
+    "@genesislcap/webpack-builder": "15.13.0",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2",
     "esbuild": "0.25.12"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "15.12.0",
-    "@genesislcap/foundation-logger": "15.12.0",
-    "@genesislcap/foundation-notifications": "15.12.0",
-    "@genesislcap/foundation-redux": "15.12.0",
-    "@genesislcap/foundation-ui": "15.12.0",
-    "@genesislcap/foundation-utils": "15.12.0",
-    "@genesislcap/rapid-design-system": "15.12.0",
-    "@genesislcap/web-core": "15.12.0",
+    "@genesislcap/foundation-ai": "15.13.0",
+    "@genesislcap/foundation-logger": "15.13.0",
+    "@genesislcap/foundation-notifications": "15.13.0",
+    "@genesislcap/foundation-redux": "15.13.0",
+    "@genesislcap/foundation-ui": "15.13.0",
+    "@genesislcap/foundation-utils": "15.13.0",
+    "@genesislcap/rapid-design-system": "15.13.0",
+    "@genesislcap/web-core": "15.13.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -105,5 +105,5 @@
     "access": "public"
   },
   "customElements": "dist/custom-elements.json",
-  "gitHead": "06f5ab51086c6616c6b96a7a1aebccddb3af7881"
+  "gitHead": "719ab9df50445af3dabf8f6fb9966d004e5ae524"
 }