@genesislcap/ai-assistant 15.4.1 → 15.6.0

package/dist/esm/utils/cost-session-history.test.js

@@ -1,32 +1,174 @@
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { appendCostSessionRecord, clearCostSessionHistory, costHistoryStorageKey, formatCostSessionDate, loadCostSessionHistory, removeCostSessionRecord, saveCostSessionHistory, } from './cost-session-history';
+import { clearCostSessionHistory, costHistoryStorageKey, formatCostSessionDate, loadCostSessionHistory, resolveBankedUsage, saveCostSessionHistory, sortRecordsByRecency, upsertRecord, } from './cost-session-history';
+import { emptyUsage } from './sum-usage';
 const scope = `test-${Date.now()}`;
-const sampleRecord = (overrides = {}) => (Object.assign({ id: 'rec-1', title: 'Equity Options Pricer', endedAt: '2026-06-14T12:00:00.000Z', costUsd: 1.86, tokensConsumed: 1400000, models: [{ model: 'claude-sonnet-4-6', provider: 'anthropic' }] }, overrides));
+const usage = (costUsd) => ({
+    costUsd,
+    uncachedInputTokens: 100000,
+    cacheReadTokens: 1200000,
+    cacheWriteTokens: 60000,
+    outputTokens: 40000,
+});
+const sampleRecord = (overrides = {}) => (Object.assign({ id: 'rec-1', projectKey: 'proj-1', title: 'Equity Options Pricer', 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));
 const suite = createLogicSuite('costSessionHistory');
 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', () => {
+    var _a, _b;
+    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((_a = both[0]) === null || _a === void 0 ? void 0 : _a.id, 'b', 'most recently added is prepended');
+    assert.is((_b = both[1]) === null || _b === void 0 ? void 0 : _b.id, 'a');
+});
+suite('upsertRecord replaces a project in place rather than stacking a second row', () => {
     var _a, _b;
+    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((_a = next[1]) === null || _a === void 0 ? void 0 : _a.projectKey, 'a');
+    assert.is((_b = next[1]) === null || _b === void 0 ? void 0 : _b.usage.costUsd, 9.5);
+    assert.is(next.reduce((sum, r) => sum + r.usage.costUsd, 0), 11.5);
+});
+suite('round-trips records through storage', () => {
+    var _a, _b, _c, _d;
+    clearCostSessionHistory(scope);
+    const records = upsertRecord([], sampleRecord({ id: 'a', projectKey: 'a', usage: usage(3.5) }));
+    saveCostSessionHistory(scope, records);
+    const loaded = loadCostSessionHistory(scope);
+    assert.is(loaded.length, 1);
+    assert.is((_a = loaded[0]) === null || _a === void 0 ? void 0 : _a.usage.costUsd, 3.5);
+    assert.is((_b = loaded[0]) === null || _b === void 0 ? void 0 : _b.usage.cacheReadTokens, 1200000, 'buckets survive serialization');
+    assert.is((_d = (_c = loaded[0]) === null || _c === void 0 ? void 0 : _c.banked) === null || _d === void 0 ? void 0 : _d.costUsd, 0.5, 'banked survives serialization');
+    clearCostSessionHistory(scope);
+});
+suite('discards legacy rows that predate the per-project key', () => {
+    var _a;
     clearCostSessionHistory(scope);
-    appendCostSessionRecord(scope, sampleRecord({ id: 'a', title: 'First' }));
-    appendCostSessionRecord(scope, sampleRecord({ id: 'b', title: 'Second' }));
+    const legacy = sampleRecord({ id: 'old' });
+    delete legacy.projectKey;
+    saveCostSessionHistory(scope, [legacy, sampleRecord({ id: 'new' })]);
     const loaded = loadCostSessionHistory(scope);
-    assert.is(loaded.length, 2);
-    assert.is((_a = loaded[0]) === null || _a === void 0 ? void 0 : _a.id, 'b');
-    assert.is((_b = loaded[1]) === null || _b === void 0 ? void 0 : _b.id, 'a');
+    // 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((_a = loaded[0]) === null || _a === void 0 ? void 0 : _a.id, 'new');
     clearCostSessionHistory(scope);
 });
-suite('removes one record by id', () => {
+suite('discards rows whose usage is not fully numeric', () => {
     var _a;
     clearCostSessionHistory(scope);
-    saveCostSessionHistory(scope, [sampleRecord({ id: 'keep' }), sampleRecord({ id: 'drop' })]);
-    const remaining = removeCostSessionRecord(scope, 'drop');
-    assert.is(remaining.length, 1);
-    assert.is((_a = remaining[0]) === null || _a === void 0 ? void 0 : _a.id, 'keep');
+    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.outputTokens;
+    saveCostSessionHistory(scope, [broken, sampleRecord({ id: 'ok', projectKey: 'ok' })]);
+    const loaded = loadCostSessionHistory(scope);
+    assert.is(loaded.length, 1);
+    assert.is((_a = loaded[0]) === null || _a === void 0 ? void 0 : _a.id, 'ok');
+    clearCostSessionHistory(scope);
+});
+suite('discards rows whose banked figure is half-shaped', () => {
+    var _a;
+    clearCostSessionHistory(scope);
+    const broken = sampleRecord({ id: 'broken', banked: Object.assign({}, 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.cacheWriteTokens;
+    saveCostSessionHistory(scope, [broken, sampleRecord({ id: 'ok', projectKey: 'ok' })]);
+    const loaded = loadCostSessionHistory(scope);
+    assert.is(loaded.length, 1);
+    assert.is((_a = loaded[0]) === null || _a === void 0 ? void 0 : _a.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);
 });
 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', () => {
+    var _a, _b;
+    // 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((_a = records[1]) === null || _a === void 0 ? void 0 : _a.id, 'a', 'stored order is unchanged by the revisit');
+    assert.is((_b = sortRecordsByRecency(records)[0]) === null || _b === void 0 ? void 0 : _b.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: Object.assign({}, 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: Object.assign({}, 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: Object.assign({}, usage(4)) });
+    for (let reload = 0; reload < 3; reload += 1) {
+        const banked = resolveBankedUsage(row, true);
+        row = Object.assign(Object.assign({}, row), { banked, usage: Object.assign({}, 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: Object.assign({}, usage(4)) });
+    for (const spend of [2, 3]) {
+        const banked = resolveBankedUsage(row, false);
+        row = Object.assign(Object.assign({}, row), { banked, usage: Object.assign({}, usage(banked.costUsd + spend)) });
+    }
+    // 10 banked, +2 → 12; then 12 banked, +3 → 15. Never decreases.
+    assert.is(row.usage.costUsd, 15);
+});
 suite.run();

package/dist/esm/utils/resolve-cost-history-config.js

@@ -1,6 +1,6 @@
 /** Resolve `chatConfig.costHistory` with defaults applied. */
 export function resolveCostHistoryConfig(chatConfig) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d;
     const cost = chatConfig.costHistory;
     return {
         enabled: (cost === null || cost === void 0 ? void 0 : cost.enabled) === true,
@@ -9,5 +9,6 @@ export function resolveCostHistoryConfig(chatConfig) {
         showCost: (cost === null || cost === void 0 ? void 0 : cost.showCost) !== false,
         showTokens: (cost === null || cost === void 0 ? void 0 : cost.showTokens) !== false,
         badgeLabel: (_c = cost === null || cost === void 0 ? void 0 : cost.badgeLabel) !== null && _c !== void 0 ? _c : 'Currently building',
+        summaryHint: ((_d = cost === null || cost === void 0 ? void 0 : cost.summaryHint) === null || _d === void 0 ? void 0 : _d.trim()) || undefined,
     };
 }

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

@@ -1,3 +1,4 @@
+import { sumUsage } from './sum-usage';
 /**
  * Sum cost across a message list: each message's provider-reported LLM `cost`
  * plus any `externalCostUsd` a widget reported for its own external service
@@ -11,17 +12,5 @@
  * @internal
  */
 export function sumCosts(messages) {
-    var _a;
-    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 (_a = m.toolCalls) !== null && _a !== void 0 ? _a : []) {
-            if (tc.subAgentTrace)
-                total += sumCosts(tc.subAgentTrace);
-        }
-    }
-    return total;
+    return sumUsage(messages).costUsd;
 }

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

@@ -1,25 +1,21 @@
 import DOMPurify from 'dompurify';
-/** Per-message token usage when the provider reports it. */
-const messageTokenUsage = (m) => { var _a, _b; return ((_a = m.inputTokens) !== null && _a !== void 0 ? _a : 0) + ((_b = m.outputTokens) !== null && _b !== void 0 ? _b : 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) {
-    var _a;
-    let total = 0;
-    for (const m of messages) {
-        total += messageTokenUsage(m);
-        for (const tc of (_a = m.toolCalls) !== null && _a !== void 0 ? _a : []) {
-            if (tc.subAgentTrace)
-                total += sumTokens(tc.subAgentTrace);
-        }
-    }
-    return total;
+    return totalTokens(sumUsage(messages));
 }
 const TOKEN_SCALE_DECIMAL_FACTOR = 10;
 const TOKENS_PER_MILLION = 1000000;
@@ -49,19 +45,6 @@ const scaledNumericValue = (tokens) => {
         return roundScaled(tokens / TOKENS_PER_MILLION);
     return roundScaled(tokens / TOKENS_PER_THOUSAND);
 };
-/**
- * Compact plain-text token count (e.g. 1_400_000 → "1.4M").
- *
- * @internal
- */
-export function formatCompactTokenCountPlain(tokens) {
-    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/dist/esm/utils/sum-tokens.test.js

@@ -1,5 +1,5 @@
 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 = {}) => (Object.assign({ role: 'assistant', content: '' }, overrides));
 const suite = createLogicSuite('sumTokens');
 suite('returns 0 for an empty message list', () => {
@@ -47,9 +47,5 @@ formatSuite('rolls K suffix up to M when rounding would yield 1000K', () => {
 formatSuite('safe formatter preserves compact markup', () => {
     assert.is(formatCompactTokenCountSafe(1400000), '<span class="value">1.4</span><span class="suffix">M</span>');
 });
-formatSuite('plain formatter returns compact text', () => {
-    assert.is(formatCompactTokenCountPlain(1400000), '1.4M');
-    assert.is(formatCompactTokenCountPlain(842), '842');
-});
 suite.run();
 formatSuite.run();

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

@@ -0,0 +1,123 @@
+/**
+ * Zeroed {@link AggregateUsage}. A factory, not a shared const, because callers
+ * accumulate into the returned object.
+ *
+ * @internal
+ */
+export function emptyUsage() {
+    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) {
+    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, b) {
+    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) {
+    const total = emptyUsage();
+    accumulate(messages, total);
+    return total;
+}
+/** Add `from` into `into`, in place. */
+function addInto(into, from) {
+    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, into) {
+    var _a, _b, _c, _d, _e, _f;
+    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 = (_a = m.cacheReadTokens) !== null && _a !== void 0 ? _a : 0;
+        const cacheWrite = (_b = m.cacheWriteTokens) !== null && _b !== void 0 ? _b : 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, ((_c = m.inputTokens) !== null && _c !== void 0 ? _c : 0) - cacheRead - cacheWrite);
+        into.outputTokens += (_d = m.outputTokens) !== null && _d !== void 0 ? _d : 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 = (_e = m.compaction) === null || _e === void 0 ? void 0 : _e.rolledUpUsage;
+        if (rolled)
+            addInto(into, rolled);
+        for (const tc of (_f = m.toolCalls) !== null && _f !== void 0 ? _f : []) {
+            if (tc.subAgentTrace)
+                accumulate(tc.subAgentTrace, into);
+        }
+    }
+}

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

@@ -0,0 +1,120 @@
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import { addUsage, emptyUsage, 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', () => {
+    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: 90000,
+            },
+        }),
+    ]);
+    assert.is(totalTokens(usage), 0);
+});
+suite('addUsage adds every bucket and mutates neither operand', () => {
+    const a = Object.assign(Object.assign({}, emptyUsage()), { costUsd: 1.5, uncachedInputTokens: 100, outputTokens: 10 });
+    const b = Object.assign(Object.assign({}, 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 = Object.assign(Object.assign({}, emptyUsage()), { costUsd: 3, cacheWriteTokens: 42 });
+    assert.equal(addUsage(a, emptyUsage()), a);
+    assert.equal(addUsage(emptyUsage(), a), a);
+});
+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.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.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.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/index.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/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/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/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/tool-fold.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.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.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.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/cost-session-banking.test.ts","../src/main/index.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/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/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/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.4.1",
+  "version": "15.6.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.4.1",
-    "@genesislcap/genx": "15.4.1",
-    "@genesislcap/rollup-builder": "15.4.1",
-    "@genesislcap/ts-builder": "15.4.1",
-    "@genesislcap/uvu-playwright-builder": "15.4.1",
-    "@genesislcap/vite-builder": "15.4.1",
-    "@genesislcap/webpack-builder": "15.4.1",
+    "@genesislcap/foundation-testing": "15.6.0",
+    "@genesislcap/genx": "15.6.0",
+    "@genesislcap/rollup-builder": "15.6.0",
+    "@genesislcap/ts-builder": "15.6.0",
+    "@genesislcap/uvu-playwright-builder": "15.6.0",
+    "@genesislcap/vite-builder": "15.6.0",
+    "@genesislcap/webpack-builder": "15.6.0",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2",
     "esbuild": "0.25.12"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "15.4.1",
-    "@genesislcap/foundation-logger": "15.4.1",
-    "@genesislcap/foundation-notifications": "15.4.1",
-    "@genesislcap/foundation-redux": "15.4.1",
-    "@genesislcap/foundation-ui": "15.4.1",
-    "@genesislcap/foundation-utils": "15.4.1",
-    "@genesislcap/rapid-design-system": "15.4.1",
-    "@genesislcap/web-core": "15.4.1",
+    "@genesislcap/foundation-ai": "15.6.0",
+    "@genesislcap/foundation-logger": "15.6.0",
+    "@genesislcap/foundation-notifications": "15.6.0",
+    "@genesislcap/foundation-redux": "15.6.0",
+    "@genesislcap/foundation-ui": "15.6.0",
+    "@genesislcap/foundation-utils": "15.6.0",
+    "@genesislcap/rapid-design-system": "15.6.0",
+    "@genesislcap/web-core": "15.6.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -105,5 +105,5 @@
     "access": "public"
   },
   "customElements": "dist/custom-elements.json",
-  "gitHead": "984a77280362d69ba3eab6256dbb7fe03b8c76b3"
+  "gitHead": "dbf070bac8a4bfc2a178e335b1faffb130e8f761"
 }