@genesislcap/ai-assistant 15.4.1 → 15.6.0

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

@@ -1,23 +1,36 @@
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
 import type { CostSessionRecord } from './cost-session-history';
 import {
-  appendCostSessionRecord,
   clearCostSessionHistory,
   costHistoryStorageKey,
   formatCostSessionDate,
   loadCostSessionHistory,
-  removeCostSessionRecord,
+  resolveBankedUsage,
   saveCostSessionHistory,
+  sortRecordsByRecency,
+  upsertRecord,
 } from './cost-session-history';
+import { emptyUsage } from './sum-usage';
 
 const scope = `test-${Date.now()}`;
 
+const usage = (costUsd: number): CostSessionRecord['usage'] => ({
+  costUsd,
+  uncachedInputTokens: 100_000,
+  cacheReadTokens: 1_200_000,
+  cacheWriteTokens: 60_000,
+  outputTokens: 40_000,
+});
+
 const sampleRecord = (overrides: Partial<CostSessionRecord> = {}): CostSessionRecord => ({
   id: 'rec-1',
+  projectKey: 'proj-1',
   title: 'Equity Options Pricer',
-  endedAt: '2026-06-14T12:00:00.000Z',
-  costUsd: 1.86,
-  tokensConsumed: 1_400_000,
+  updatedAt: '2026-06-14T12:00:00.000Z',
+  usage: usage(1.86),
+  // Present by default so `delete record.banked` in the legacy-row cases actually removes
+  // something, and so the storage round-trip covers it.
+  banked: usage(0.5),
   models: [{ model: 'claude-sonnet-4-6', provider: 'anthropic' }],
   ...overrides,
 });
@@ -28,23 +41,90 @@ suite('uses a scoped storage key', () => {
   assert.is(costHistoryStorageKey('my-app'), 'genesis-ai-assistant:cost-history:my-app');
 });
 
-suite('persists and loads records newest-first via append', () => {
+suite('upsertRecord prepends a project it has not seen', () => {
+  const first = upsertRecord([], sampleRecord({ id: 'a', projectKey: 'a', title: 'First' }));
+  const both = upsertRecord(first, sampleRecord({ id: 'b', projectKey: 'b', title: 'Second' }));
+  assert.is(both.length, 2);
+  // Insertion order, not recency — display ordering is sortRecordsByRecency's job.
+  assert.is(both[0]?.id, 'b', 'most recently added is prepended');
+  assert.is(both[1]?.id, 'a');
+});
+
+suite('upsertRecord replaces a project in place rather than stacking a second row', () => {
+  const seeded = [
+    sampleRecord({ id: 'b', projectKey: 'b', usage: usage(2) }),
+    sampleRecord({ id: 'a', projectKey: 'a', usage: usage(1) }),
+  ];
+  // Re-reporting a project must REPLACE its row. Appending here is what made a single
+  // project's spend count once per refresh in any total summed over the list.
+  const next = upsertRecord(seeded, sampleRecord({ id: 'a', projectKey: 'a', usage: usage(9.5) }));
+  assert.is(next.length, 2);
+  // Replaced in place rather than moved — the stored array is not a recency ordering.
+  assert.is(next[1]?.projectKey, 'a');
+  assert.is(next[1]?.usage.costUsd, 9.5);
+  assert.is(
+    next.reduce((sum, r) => sum + r.usage.costUsd, 0),
+    11.5,
+  );
+});
+
+suite('round-trips records through storage', () => {
   clearCostSessionHistory(scope);
-  appendCostSessionRecord(scope, sampleRecord({ id: 'a', title: 'First' }));
-  appendCostSessionRecord(scope, sampleRecord({ id: 'b', title: 'Second' }));
+  const records = upsertRecord([], sampleRecord({ id: 'a', projectKey: 'a', usage: usage(3.5) }));
+  saveCostSessionHistory(scope, records);
   const loaded = loadCostSessionHistory(scope);
-  assert.is(loaded.length, 2);
-  assert.is(loaded[0]?.id, 'b');
-  assert.is(loaded[1]?.id, 'a');
+  assert.is(loaded.length, 1);
+  assert.is(loaded[0]?.usage.costUsd, 3.5);
+  assert.is(loaded[0]?.usage.cacheReadTokens, 1_200_000, 'buckets survive serialization');
+  assert.is(loaded[0]?.banked?.costUsd, 0.5, 'banked survives serialization');
   clearCostSessionHistory(scope);
 });
 
-suite('removes one record by id', () => {
+suite('discards legacy rows that predate the per-project key', () => {
   clearCostSessionHistory(scope);
-  saveCostSessionHistory(scope, [sampleRecord({ id: 'keep' }), sampleRecord({ id: 'drop' })]);
-  const remaining = removeCostSessionRecord(scope, 'drop');
-  assert.is(remaining.length, 1);
-  assert.is(remaining[0]?.id, 'keep');
+  const legacy = sampleRecord({ id: 'old' }) as Partial<CostSessionRecord>;
+  delete legacy.projectKey;
+  saveCostSessionHistory(scope, [legacy as CostSessionRecord, sampleRecord({ id: 'new' })]);
+  const loaded = loadCostSessionHistory(scope);
+  // A keyless row can never be matched to a project, so pooling it with the new rows
+  // would permanently double-count whichever project it came from.
+  assert.is(loaded.length, 1);
+  assert.is(loaded[0]?.id, 'new');
+  clearCostSessionHistory(scope);
+});
+
+suite('discards rows whose usage is not fully numeric', () => {
+  clearCostSessionHistory(scope);
+  const broken = sampleRecord({ id: 'broken' });
+  // A half-shaped `usage` is worse than a missing row: it sums as NaN and poisons every
+  // total on the Usage tab, with no clue where the NaN came from.
+  delete (broken.usage as Partial<CostSessionRecord['usage']>).outputTokens;
+  saveCostSessionHistory(scope, [broken, sampleRecord({ id: 'ok', projectKey: 'ok' })]);
+  const loaded = loadCostSessionHistory(scope);
+  assert.is(loaded.length, 1);
+  assert.is(loaded[0]?.id, 'ok');
+  clearCostSessionHistory(scope);
+});
+
+suite('discards rows whose banked figure is half-shaped', () => {
+  clearCostSessionHistory(scope);
+  const broken = sampleRecord({ id: 'broken', banked: { ...usage(2) } });
+  // A malformed `banked` poisons the lifetime total exactly as a malformed `usage` does,
+  // since the two are added together to produce it.
+  delete (broken.banked as Partial<CostSessionRecord['usage']>).cacheWriteTokens;
+  saveCostSessionHistory(scope, [broken, sampleRecord({ id: 'ok', projectKey: 'ok' })]);
+  const loaded = loadCostSessionHistory(scope);
+  assert.is(loaded.length, 1);
+  assert.is(loaded[0]?.id, 'ok');
+  clearCostSessionHistory(scope);
+});
+
+suite('keeps a row whose banked figure is absent', () => {
+  clearCostSessionHistory(scope);
+  const legacy = sampleRecord({ id: 'legacy' });
+  delete legacy.banked;
+  saveCostSessionHistory(scope, [legacy]);
+  assert.is(loadCostSessionHistory(scope).length, 1, 'absent is valid, unlike half-shaped');
   clearCostSessionHistory(scope);
 });
 
@@ -52,4 +132,95 @@ suite('formats session dates for display', () => {
   assert.is(formatCostSessionDate('2026-06-14T12:00:00.000Z'), 'Jun 14, 2026');
 });
 
+suite('sortRecordsByRecency puts the most recently worked-on project first', () => {
+  const records = [
+    sampleRecord({ id: 'old', projectKey: 'old', updatedAt: '2026-01-01T00:00:00.000Z' }),
+    sampleRecord({ id: 'newest', projectKey: 'newest', updatedAt: '2026-08-04T09:00:00.000Z' }),
+    sampleRecord({ id: 'mid', projectKey: 'mid', updatedAt: '2026-05-01T00:00:00.000Z' }),
+  ];
+  const sorted = sortRecordsByRecency(records);
+  assert.equal(
+    sorted.map((r) => r.id),
+    ['newest', 'mid', 'old'],
+  );
+  // Read-time ordering, so the caller's array must be left alone.
+  assert.equal(
+    records.map((r) => r.id),
+    ['old', 'newest', 'mid'],
+    'input not mutated',
+  );
+});
+
+suite('sortRecordsByRecency overrides insertion order, which upsert leaves alone', () => {
+  // The behaviour this fixes: revisiting a project replaces its row IN PLACE, so insertion order
+  // strands it wherever it was first seen. Display order must come from updatedAt instead.
+  let records = upsertRecord(
+    [],
+    sampleRecord({ id: 'a', projectKey: 'a', updatedAt: '2026-01-01T00:00:00.000Z' }),
+  );
+  records = upsertRecord(
+    records,
+    sampleRecord({ id: 'b', projectKey: 'b', updatedAt: '2026-02-01T00:00:00.000Z' }),
+  );
+  // Work on 'a' again — newer than 'b', but upsert keeps it in slot 1.
+  records = upsertRecord(
+    records,
+    sampleRecord({ id: 'a', projectKey: 'a', updatedAt: '2026-03-01T00:00:00.000Z' }),
+  );
+  assert.is(records[1]?.id, 'a', 'stored order is unchanged by the revisit');
+  assert.is(sortRecordsByRecency(records)[0]?.id, 'a', 'display order tracks the revisit');
+});
+
+suite('banks nothing for a project with no prior row', () => {
+  assert.equal(resolveBankedUsage(undefined, true), emptyUsage());
+  assert.equal(resolveBankedUsage(undefined, false), emptyUsage());
+});
+
+suite('carries the prior banked figure forward when the transcript is authoritative', () => {
+  // Restored transcript: it already re-proves everything after the row's own banked figure,
+  // so only that figure carries over. Taking `usage` here is the compounding double-count.
+  const prior = sampleRecord({ usage: usage(10), banked: { ...usage(4) } });
+  assert.is(resolveBankedUsage(prior, true).costUsd, 4);
+});
+
+suite('banks the whole prior total when the transcript starts empty', () => {
+  // Nothing on screen accounts for the previous total, so all of it must carry over or the
+  // next turn rewrites the row down to just that turn.
+  const prior = sampleRecord({ usage: usage(10), banked: { ...usage(4) } });
+  assert.is(resolveBankedUsage(prior, false).costUsd, 10);
+});
+
+suite('treats a row predating the banked field as nothing banked', () => {
+  const legacy = sampleRecord({ usage: usage(7) });
+  delete legacy.banked;
+  assert.equal(resolveBankedUsage(legacy, true), emptyUsage());
+  // Without persistence the legacy total still carries, so upgrading loses no spend.
+  assert.is(resolveBankedUsage(legacy, false).costUsd, 7);
+});
+
+suite('is stable across repeated reloads — the regression this guards', () => {
+  // Simulate the reload cycle: usage = banked + whatever the transcript proves. With a
+  // restored transcript (worth 6 on top of 4 banked) the row must land on 10 every time,
+  // not 10 → 14 → 18 as it did when a reload re-banked the restored history.
+  const transcript = 6;
+  let row = sampleRecord({ usage: usage(10), banked: { ...usage(4) } });
+  for (let reload = 0; reload < 3; reload += 1) {
+    const banked = resolveBankedUsage(row, true);
+    row = { ...row, banked, usage: { ...usage(banked.costUsd + transcript) } };
+    assert.is(row.usage.costUsd, 10, `reload ${reload}`);
+  }
+});
+
+suite('accumulates across reloads when the transcript does not persist', () => {
+  // The mirror case: each page-load starts from an empty transcript, so the row must grow by
+  // whatever that load spends rather than being overwritten by it.
+  let row = sampleRecord({ usage: usage(10), banked: { ...usage(4) } });
+  for (const spend of [2, 3]) {
+    const banked = resolveBankedUsage(row, false);
+    row = { ...row, banked, usage: { ...usage(banked.costUsd + spend) } };
+  }
+  // 10 banked, +2 → 12; then 12 banked, +3 → 15. Never decreases.
+  assert.is(row.usage.costUsd, 15);
+});
+
 suite.run();

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.