@genesislcap/ai-assistant 15.4.1 → 15.5.0

package/src/utils/cost-session-history.ts

@@ -1,31 +1,89 @@
-import type { AIProviderType } from '@genesislcap/foundation-ai';
+import type { AggregateUsage, AIProviderType } from '@genesislcap/foundation-ai';
+import { emptyUsage } from './sum-usage';
 
-/** A model used during a finalized cost session. */
+/** A model used during a recorded cost session. */
 export interface CostSessionModelEntry {
   model: string;
   /** Vendor id from `getStatus()` (e.g. `'anthropic'`, `'gemini'`). */
   provider?: AIProviderType;
 }
 
-/** Persisted snapshot of a completed assistant cost session. */
+/** Persisted usage record for one project's assistant work. */
 export interface CostSessionRecord {
   id: string;
+  /**
+   * Stable identity of the work this row stands for — the assistant's session key
+   * (a project id, for hosts that key sessions per project). The upsert key: a row
+   * is one project's lifetime usage, so re-reporting the same key REPLACES the row
+   * rather than adding another.
+   */
+  projectKey: string;
   title: string;
-  /** ISO-8601 timestamp when the session was finalized. */
-  endedAt: string;
-  costUsd: number;
-  tokensConsumed: number;
+  /**
+   * ISO-8601 timestamp of the most recent usage recorded for this row.
+   *
+   * Named for what it is: the row is upserted as spend accrues, so this moves. It is
+   * NOT an end time — a row has no terminal state, because a project can always be
+   * worked on again.
+   */
+  updatedAt: string;
+  /**
+   * Cost plus the four token buckets — the same shape the live session tile renders, so
+   * a history row can show the identical breakdown instead of a lone merged total that
+   * cannot explain a large token count at a small cost.
+   *
+   * This is the project's **lifetime** usage: `banked` plus whatever the live transcript
+   * currently proves.
+   */
+  usage: AggregateUsage;
+  /**
+   * Spend that predates the current transcript, and so cannot be re-derived from it.
+   *
+   * Without this a row could only ever report what the open transcript proves. That is
+   * fine when the transcript is restored on load (it *is* the project's history), but
+   * where it starts empty every refresh the row would be rewritten downwards on the next
+   * turn and the project's earlier spend lost. Banking it keeps `usage` a lifetime figure
+   * in both cases.
+   *
+   * Deliberately part of the row rather than element state: two assistant instances (a
+   * docked bubble and a popped-out panel) share one session, and both write this row. A
+   * value derived from the row keeps every write idempotent, whereas an element-held
+   * accumulator would be applied once per instance.
+   *
+   * Optional: rows written before this existed have none, which reads as "nothing banked".
+   */
+  banked?: AggregateUsage;
   models: CostSessionModelEntry[];
 }
 
 const STORAGE_PREFIX = 'genesis-ai-assistant:cost-history:';
 
+/**
+ * Every bucket must be a number before a row is trusted. Checked per field rather than
+ * just testing for an object, because a partially-shaped `usage` would sum as `NaN` and
+ * silently poison every total on the Usage tab.
+ */
+function isAggregateUsage(value: unknown): value is AggregateUsage {
+  if (typeof value !== 'object' || value == null) return false;
+  const u = value as AggregateUsage;
+  return (
+    typeof u.costUsd === 'number' &&
+    typeof u.uncachedInputTokens === 'number' &&
+    typeof u.cacheReadTokens === 'number' &&
+    typeof u.cacheWriteTokens === 'number' &&
+    typeof u.outputTokens === 'number'
+  );
+}
+
 /** localStorage key for a host-scoped cost history list. */
 export function costHistoryStorageKey(scope: string): string {
   return `${STORAGE_PREFIX}${scope}`;
 }
 
-/** Load persisted cost sessions for a scope (newest first). */
+/**
+ * Load persisted cost sessions for a scope, in whatever order they were stored — this applies no
+ * ordering of its own. Display order is the caller's business; see `sortRecordsByRecency`.
+ */
 export function loadCostSessionHistory(scope: string): CostSessionRecord[] {
   if (typeof localStorage === 'undefined') return [];
   try {
@@ -49,21 +107,69 @@ export function saveCostSessionHistory(scope: string, records: CostSessionRecord
   }
 }
 
-/** Prepend a record and persist. Returns the updated list. */
-export function appendCostSessionRecord(
-  scope: string,
+/**
+ * Pure upsert — `records` with `record` replacing any row sharing its `projectKey`, or
+ * prepended when there is none.
+ *
+ * An upsert, not an append, because a row stands for a **project's lifetime usage** rather
+ * than a visit to it. Appending cut a fresh row per page-hide, so one project accumulated
+ * a stack of near-identical rows and its spend was counted once per refresh by anything
+ * summing the list.
+ *
+ * The resulting array order is incidental — it is insertion order, so a project returned to
+ * stays where it first landed. Do not read it as recency; `sortRecordsByRecency` is what the
+ * Usage tab renders through.
+ *
+ * Storage-agnostic on purpose: the same merge serves the synchronous `localStorage` path
+ * and the async provider-backed one, so the two can never drift on what "upsert" means.
+ * The caller owns persistence — see the assistant's `persistCostHistory`.
+ */
+export function upsertRecord(
+  records: readonly CostSessionRecord[],
   record: CostSessionRecord,
 ): CostSessionRecord[] {
-  const records = [record, ...loadCostSessionHistory(scope)];
-  saveCostSessionHistory(scope, records);
-  return records;
+  const at = records.findIndex((r) => r.projectKey === record.projectKey);
+  return at === -1 ? [record, ...records] : records.map((r, i) => (i === at ? record : r));
+}
+
+/**
+ * Rows most-recently-worked-on first, as a new array.
+ *
+ * Applied at read time rather than baked into the stored order, so it covers rows that came from
+ * a host provider as well as from `localStorage`, and so no write path has to maintain it.
+ *
+ * `updatedAt` is ISO-8601, which sorts lexicographically — no date parsing, and no dependence on
+ * the strings being valid dates. Sorting by it rather than by insertion order is what makes the
+ * list track use: the active project moves to the top on its first upsert and stays there, since
+ * its row is rewritten on every transcript change.
+ */
+export function sortRecordsByRecency(records: readonly CostSessionRecord[]): CostSessionRecord[] {
+  return [...records].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
 }
 
-/** Remove one record by id. Returns the updated list. */
-export function removeCostSessionRecord(scope: string, id: string): CostSessionRecord[] {
-  const records = loadCostSessionHistory(scope).filter((r) => r.id !== id);
-  saveCostSessionHistory(scope, records);
-  return records;
+/**
+ * The spend a project's next row must carry over from before its current transcript.
+ *
+ * `transcriptIsAuthoritative` means the open transcript already accounts for this project's
+ * history — true exactly when a session snapshot is restored on load. The two branches are
+ * not interchangeable, and picking the wrong one is silently destructive:
+ *
+ * - Authoritative: carry the previous row's own `banked` forward. Taking `usage` instead would
+ *   re-add the restored history on every reload, the compounding double-count this replaced.
+ * - Not authoritative: the whole previous total becomes banked, because nothing in the fresh
+ *   transcript accounts for it. Taking `banked` instead would rewrite the row down to the
+ *   current page-load and drop the project's earlier spend.
+ *
+ * Note both branches are idempotent — the result never includes the current transcript — which
+ * is what lets two assistant instances sharing a session write the same row.
+ */
+export function resolveBankedUsage(
+  existing: CostSessionRecord | undefined,
+  transcriptIsAuthoritative: boolean,
+): AggregateUsage {
+  if (!existing) return emptyUsage();
+  const carried = transcriptIsAuthoritative ? existing.banked : existing.usage;
+  return carried ?? emptyUsage();
 }
 
 /** Clear all persisted records for a scope. */
@@ -85,15 +191,28 @@ export function formatCostSessionDate(iso: string): string {
   }).format(new Date(iso));
 }
 
-function isCostSessionRecord(value: unknown): value is CostSessionRecord {
+/**
+ * Whether a value is a usable row. Exported because rows arrive by two routes and BOTH need it:
+ * `loadCostSessionHistory` filters the `localStorage` path here, and the assistant filters what a
+ * host provider returns. A row that skips this check is not merely ignored downstream — a
+ * half-shaped `usage` sums to `NaN` through every total, and a missing `updatedAt` throws inside
+ * the sort that orders the list, during render.
+ */
+export function isCostSessionRecord(value: unknown): value is CostSessionRecord {
   if (typeof value !== 'object' || value == null) return false;
   const r = value as CostSessionRecord;
   return (
     typeof r.id === 'string' &&
+    // Rows written before the upsert model have no `projectKey` and cannot be keyed
+    // to a project, so they are discarded on load rather than silently pooled with
+    // the new per-project rows (where they would double-count that project).
+    typeof r.projectKey === 'string' &&
     typeof r.title === 'string' &&
-    typeof r.endedAt === 'string' &&
-    typeof r.costUsd === 'number' &&
-    typeof r.tokensConsumed === 'number' &&
+    typeof r.updatedAt === 'string' &&
+    isAggregateUsage(r.usage) &&
+    // Absent is valid (nothing banked / pre-dates the field); present must be whole, since
+    // a half-shaped `banked` would poison the lifetime total exactly as a bad `usage` would.
+    (r.banked === undefined || isAggregateUsage(r.banked)) &&
     Array.isArray(r.models)
   );
 }

package/src/utils/resolve-cost-history-config.ts

@@ -8,12 +8,18 @@ export interface ResolvedCostHistoryConfig {
   title?: string;
   /** `localStorage` scope key; falls back to element `id` then `'default'`. */
   scope?: string;
-  /** Show running session USD on the Cost tab. Default: `true`. */
+  /** Show running session USD on the Usage tab. Default: `true`. */
   showCost: boolean;
-  /** Show cumulative session tokens on the Cost tab. Default: `true`. */
+  /** Show cumulative session tokens on the Usage tab. Default: `true`. */
   showTokens: boolean;
-  /** Live-session badge label on the Cost tab summary. */
+  /** Live-session badge label on the Usage tab summary. */
   badgeLabel: string;
+  /**
+   * Host-supplied disclosure line for the Usage tab. Stays optional — unlike
+   * `badgeLabel` there is no default, because only the host knows what its `scope`
+   * spans, and the library must not assert it.
+   */
+  summaryHint?: string;
 }
 
 /** Resolve `chatConfig.costHistory` with defaults applied. */
@@ -27,5 +33,6 @@ export function resolveCostHistoryConfig(chatConfig: ChatConfig): ResolvedCostHi
     showCost: cost?.showCost !== false,
     showTokens: cost?.showTokens !== false,
     badgeLabel: cost?.badgeLabel ?? 'Currently building',
+    summaryHint: cost?.summaryHint?.trim() || undefined,
   };
 }

package/src/utils/sum-costs.ts

@@ -1,4 +1,5 @@
 import type { ChatMessage } from '@genesislcap/foundation-ai';
+import { sumUsage } from './sum-usage';
 
 /**
  * Sum cost across a message list: each message's provider-reported LLM `cost`
@@ -13,13 +14,5 @@ import type { ChatMessage } from '@genesislcap/foundation-ai';
  * @internal
  */
 export function sumCosts(messages: readonly ChatMessage[]): number {
-  let total = 0;
-  for (const m of messages) {
-    if (m.cost != null) total += m.cost;
-    if (m.externalCostUsd != null) total += m.externalCostUsd;
-    for (const tc of m.toolCalls ?? []) {
-      if (tc.subAgentTrace) total += sumCosts(tc.subAgentTrace);
-    }
-  }
-  return total;
+  return sumUsage(messages).costUsd;
 }

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

@@ -1,11 +1,6 @@
 import type { ChatMessage } from '@genesislcap/foundation-ai';
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import {
-  formatCompactTokenCount,
-  formatCompactTokenCountPlain,
-  formatCompactTokenCountSafe,
-  sumTokens,
-} from './sum-tokens';
+import { formatCompactTokenCount, formatCompactTokenCountSafe, sumTokens } from './sum-tokens';
 
 const assistantMsg = (overrides: Partial<ChatMessage> = {}): ChatMessage => ({
   role: 'assistant',
@@ -94,10 +89,5 @@ formatSuite('safe formatter preserves compact markup', () => {
   );
 });
 
-formatSuite('plain formatter returns compact text', () => {
-  assert.is(formatCompactTokenCountPlain(1_400_000), '1.4M');
-  assert.is(formatCompactTokenCountPlain(842), '842');
-});
-
 suite.run();
 formatSuite.run();

package/src/utils/sum-tokens.ts

@@ -1,26 +1,23 @@
 import type { ChatMessage } from '@genesislcap/foundation-ai';
 import DOMPurify from 'dompurify';
-
-/** Per-message token usage when the provider reports it. */
-const messageTokenUsage = (m: ChatMessage): number => (m.inputTokens ?? 0) + (m.outputTokens ?? 0);
+import { sumUsage, totalTokens } from './sum-usage';
 
 /**
- * Sum input + output tokens across a message list, recursing into each tool
- * call's `subAgentTrace` so sub-agent LLM usage contributes to the total.
+ * Total tokens across a message list — the headline figure, with the per-bucket
+ * split available from {@link sumUsage} for anything that needs to show *why* a
+ * large token count cost little.
+ *
+ * Identical arithmetic to the old per-message `inputTokens + outputTokens` sum:
+ * the three input buckets partition `inputTokens`, so they re-add to it exactly.
+ * It does now additionally count usage banked by a compaction, which is the point
+ * — that spend used to vanish when the summarised turns left the transcript.
  *
  * Returns 0 when no message carries token metadata.
  *
  * @internal
  */
 export function sumTokens(messages: readonly ChatMessage[]): number {
-  let total = 0;
-  for (const m of messages) {
-    total += messageTokenUsage(m);
-    for (const tc of m.toolCalls ?? []) {
-      if (tc.subAgentTrace) total += sumTokens(tc.subAgentTrace);
-    }
-  }
-  return total;
+  return totalTokens(sumUsage(messages));
 }
 
 const TOKEN_SCALE_DECIMAL_FACTOR = 10;
@@ -53,19 +50,6 @@ const scaledNumericValue = (tokens: number): number | undefined => {
   return roundScaled(tokens / TOKENS_PER_THOUSAND);
 };
 
-/**
- * Compact plain-text token count (e.g. 1_400_000 → "1.4M").
- *
- * @internal
- */
-export function formatCompactTokenCountPlain(tokens: number): string {
-  const suffix = scaledSuffixLabel(tokens);
-  if (!suffix) return tokens.toLocaleString();
-  const rounded = scaledNumericValue(tokens)!;
-  const value = Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
-  return `${value}${suffix}`;
-}
-
 /**
  * Compact display for large token counts (e.g. 1_400_000 → value "1.4" + suffix "M").
  * Returns HTML markup so the suffix can be styled separately in the settings modal.

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

@@ -0,0 +1,140 @@
+import type { ChatMessage } from '@genesislcap/foundation-ai';
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import { addUsage, emptyUsage, sumUsage, totalTokens } from './sum-usage';
+
+const suite = createLogicSuite('sumUsage');
+
+const msg = (over: Partial<ChatMessage> = {}): ChatMessage =>
+  ({ role: 'assistant', content: '', ...over }) as ChatMessage;
+
+suite('returns zeroes when no message carries usage', () => {
+  const usage = sumUsage([msg({ role: 'user', content: 'hi' })]);
+  assert.equal(usage, emptyUsage());
+  assert.is(totalTokens(usage), 0);
+});
+
+suite('splits the prompt into three disjoint input buckets', () => {
+  // `inputTokens` is the WHOLE prompt; the cache fields break it down. So uncached is
+  // the remainder, and the three must re-add to the prompt exactly — that identity is
+  // what stops the buckets double-counting the prompt when summed.
+  const usage = sumUsage([
+    msg({ inputTokens: 1000, cacheReadTokens: 700, cacheWriteTokens: 200, outputTokens: 50 }),
+  ]);
+  assert.is(usage.uncachedInputTokens, 100);
+  assert.is(usage.cacheReadTokens, 700);
+  assert.is(usage.cacheWriteTokens, 200);
+  assert.is(usage.outputTokens, 50);
+  assert.is(
+    usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens,
+    1000,
+    'input buckets re-add to the prompt total',
+  );
+  assert.is(totalTokens(usage), 1050);
+});
+
+suite('treats the whole prompt as uncached when no cache split is reported', () => {
+  // Providers that report no cache breakdown (and messages persisted before the fields
+  // existed) must still contribute their full prompt, not drop it.
+  const usage = sumUsage([msg({ inputTokens: 400, outputTokens: 60 })]);
+  assert.is(usage.uncachedInputTokens, 400);
+  assert.is(usage.cacheReadTokens, 0);
+  assert.is(usage.cacheWriteTokens, 0);
+  assert.is(totalTokens(usage), 460);
+});
+
+suite('clamps uncached input at zero when buckets exceed the prompt total', () => {
+  // Malformed or hand-edited history must not be able to drive a cost display negative.
+  const usage = sumUsage([
+    msg({ inputTokens: 100, cacheReadTokens: 90, cacheWriteTokens: 90, outputTokens: 0 }),
+  ]);
+  assert.is(usage.uncachedInputTokens, 0);
+});
+
+suite('sums LLM cost and widget-reported external cost', () => {
+  const usage = sumUsage([msg({ cost: 0.25 }), msg({ externalCostUsd: 0.1, cost: 0.05 })]);
+  assert.is(Math.round(usage.costUsd * 100) / 100, 0.4);
+});
+
+suite('recurses into sub-agent traces', () => {
+  // A sub-agent's whole conversation is embedded in the parent's tool call, so this is
+  // the only place its spend is visible to a host total.
+  const usage = sumUsage([
+    msg({
+      toolCalls: [
+        {
+          id: 'tc-1',
+          name: 'delegate',
+          args: {},
+          subAgentTrace: [
+            msg({ cost: 0.2, inputTokens: 300, cacheReadTokens: 100, outputTokens: 40 }),
+          ],
+        },
+      ],
+    }),
+  ]);
+  assert.is(usage.costUsd, 0.2);
+  assert.is(usage.uncachedInputTokens, 200);
+  assert.is(usage.cacheReadTokens, 100);
+  assert.is(usage.outputTokens, 40);
+});
+
+suite('counts usage banked onto a compaction summary', () => {
+  // Compaction destroys the messages it summarises. Without the banked rollup, a total
+  // re-derived from the transcript would fall by whatever those turns had spent.
+  const before = sumUsage([
+    msg({ cost: 0.5, inputTokens: 1000, cacheReadTokens: 400, outputTokens: 100 }),
+    msg({ cost: 0.3, inputTokens: 500, outputTokens: 50 }),
+  ]);
+  const afterCompaction = sumUsage([
+    msg({
+      role: 'compacted-summary',
+      content: 'summary of the above',
+      compaction: {
+        compactedCount: 2,
+        createdAt: '2026-06-14T12:00:00.000Z',
+        rolledUpUsage: before,
+      },
+    }),
+  ]);
+  assert.equal(afterCompaction, before, 'compaction preserves the running total');
+});
+
+suite('ignores tokensBefore, which is a context reading rather than spend', () => {
+  // `tokensBefore` is one turn's context-window size. Counting it as cumulative spend
+  // would silently inflate the session total on every compaction.
+  const usage = sumUsage([
+    msg({
+      role: 'compacted-summary',
+      content: 'summary',
+      compaction: {
+        compactedCount: 3,
+        createdAt: '2026-06-14T12:00:00.000Z',
+        tokensBefore: 90_000,
+      },
+    }),
+  ]);
+  assert.is(totalTokens(usage), 0);
+});
+
+suite('addUsage adds every bucket and mutates neither operand', () => {
+  const a = { ...emptyUsage(), costUsd: 1.5, uncachedInputTokens: 100, outputTokens: 10 };
+  const b = { ...emptyUsage(), costUsd: 0.25, cacheReadTokens: 900, outputTokens: 5 };
+  const sum = addUsage(a, b);
+
+  assert.is(sum.costUsd, 1.75);
+  assert.is(sum.uncachedInputTokens, 100);
+  assert.is(sum.cacheReadTokens, 900);
+  assert.is(sum.outputTokens, 15);
+  // Both operands are live state (a row's banked figure and the session total), so a
+  // caller must be able to add without either being altered underneath it.
+  assert.is(a.costUsd, 1.5);
+  assert.is(b.cacheReadTokens, 900);
+});
+
+suite('addUsage with an empty operand is the identity', () => {
+  const a = { ...emptyUsage(), costUsd: 3, cacheWriteTokens: 42 };
+  assert.equal(addUsage(a, emptyUsage()), a);
+  assert.equal(addUsage(emptyUsage(), a), a);
+});
+
+suite.run();

package/src/utils/sum-usage.ts

@@ -0,0 +1,130 @@
+import type { AggregateUsage, ChatMessage } from '@genesislcap/foundation-ai';
+
+/**
+ * Zeroed {@link AggregateUsage}. A factory, not a shared const, because callers
+ * accumulate into the returned object.
+ *
+ * @internal
+ */
+export function emptyUsage(): AggregateUsage {
+  return {
+    costUsd: 0,
+    uncachedInputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    outputTokens: 0,
+  };
+}
+
+/**
+ * Total tokens processed — the four buckets added up. Safe to sum because the
+ * buckets are disjoint (see {@link AggregateUsage}); the equivalent sum over
+ * per-message fields would double-count the prompt.
+ *
+ * Bear in mind what this number is: because every turn resends the conversation,
+ * a turn's prompt is counted again in the next turn's. It is billed throughput,
+ * NOT the count of distinct tokens in the conversation, so it grows
+ * super-linearly with turn count and is expected to dwarf the context size.
+ *
+ * @internal
+ */
+export function totalTokens(usage: AggregateUsage): number {
+  return (
+    usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens + usage.outputTokens
+  );
+}
+
+/**
+ * `a + b`, per bucket, as a new object.
+ *
+ * Used to lay a row's banked (pre-transcript) spend over what the live transcript
+ * proves. Pure rather than in-place because both operands are live state a caller
+ * must not mutate.
+ *
+ * @internal
+ */
+export function addUsage(a: AggregateUsage, b: AggregateUsage): AggregateUsage {
+  return {
+    costUsd: a.costUsd + b.costUsd,
+    uncachedInputTokens: a.uncachedInputTokens + b.uncachedInputTokens,
+    cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+    cacheWriteTokens: a.cacheWriteTokens + b.cacheWriteTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+  };
+}
+
+/**
+ * Sum cost and per-bucket token usage across a message list.
+ *
+ * One walk produces everything a usage display needs, replacing separate cost and
+ * token passes over the same (potentially deep) transcript. Recurses into each
+ * tool call's `subAgentTrace`, so LLM work a sub-agent did — possibly on another
+ * provider at other rates — lands in the total; the driver embeds a whole
+ * sub-agent conversation in the parent's tool result, so this is the only place
+ * that spend is visible.
+ *
+ * Splitting the prompt into buckets is the point: `cost` already has the cache
+ * discount applied, but a single token total cannot show that a session was cheap
+ * because most of its prompt was a cache hit. The three input buckets are derived
+ * from the per-message fields, where `inputTokens` is the whole prompt and the
+ * cache fields break it down — so uncached input is the remainder, never an
+ * addition.
+ *
+ * Also counts `compaction.rolledUpUsage`: compaction destroys the messages it
+ * summarises, and without their banked usage every total re-derived from the
+ * transcript would drop by whatever those turns had already spent.
+ *
+ * Returns a zeroed total when no message carries usage — providers that report
+ * none (e.g. Chrome built-in) are skipped silently rather than guessed at.
+ *
+ * @internal
+ */
+export function sumUsage(messages: readonly ChatMessage[]): AggregateUsage {
+  const total = emptyUsage();
+  accumulate(messages, total);
+  return total;
+}
+
+/** Add `from` into `into`, in place. */
+function addInto(into: AggregateUsage, from: AggregateUsage): void {
+  into.costUsd += from.costUsd;
+  into.uncachedInputTokens += from.uncachedInputTokens;
+  into.cacheReadTokens += from.cacheReadTokens;
+  into.cacheWriteTokens += from.cacheWriteTokens;
+  into.outputTokens += from.outputTokens;
+}
+
+/**
+ * Walk `messages`, accumulating into `into`. Mutates a single accumulator rather
+ * than merging returned objects — this runs on every transcript change, so the
+ * per-message allocation is worth avoiding.
+ */
+function accumulate(messages: readonly ChatMessage[], into: AggregateUsage): void {
+  for (const m of messages) {
+    // Provider/LLM cost plus any non-LLM cost a widget reported for its own
+    // external service calls. Both are real spend on this session.
+    if (m.cost != null) into.costUsd += m.cost;
+    if (m.externalCostUsd != null) into.costUsd += m.externalCostUsd;
+
+    const cacheRead = m.cacheReadTokens ?? 0;
+    const cacheWrite = m.cacheWriteTokens ?? 0;
+    into.cacheReadTokens += cacheRead;
+    into.cacheWriteTokens += cacheWrite;
+    // The uncached remainder of the prompt. Clamped at zero so malformed or
+    // hand-edited history whose buckets exceed the prompt total can't drive the
+    // session total negative — a wrong-but-plausible number is worse than a
+    // conservative one here, since this feeds a cost display.
+    into.uncachedInputTokens += Math.max(0, (m.inputTokens ?? 0) - cacheRead - cacheWrite);
+    into.outputTokens += m.outputTokens ?? 0;
+
+    // Spend banked by a compaction on this summary's behalf. NOTE: deliberately
+    // not `compaction.tokensBefore` — that is a one-turn context-window reading,
+    // not cumulative spend, and counting it here would inflate the total.
+    const rolled = m.compaction?.rolledUpUsage;
+    if (rolled) addInto(into, rolled);
+
+    for (const tc of m.toolCalls ?? []) {
+      if (tc.subAgentTrace) accumulate(tc.subAgentTrace, into);
+    }
+  }
+}