@genesislcap/ai-assistant 15.12.0 → 15.13.0

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.
  *