@genesislcap/ai-assistant 15.4.1 → 15.5.0

package/dist/esm/state/ai-assistant-slice.js

@@ -1,4 +1,5 @@
 import { createSlice } from '@genesislcap/foundation-redux';
+import { emptyUsage, sumUsage } from '../utils/sum-usage';
 /**
  * Build a fresh default session state. A factory (not just a shared const) so
  * each call returns independent collections — `resetSession` can hand back a
@@ -16,8 +17,7 @@ export function createDefaultSessionState() {
         suggestionsState: { status: 'idle' },
         contextTokens: undefined,
         contextLimit: undefined,
-        sessionCostUsd: 0,
-        sessionTokensConsumed: 0,
+        sessionUsage: emptyUsage(),
         activeModel: undefined,
         activeProviderName: undefined,
         providerStatuses: [],
@@ -70,11 +70,8 @@ export const aiAssistantSlice = createSlice({
         setContextLimit(state, action) {
             state.contextLimit = action.payload;
         },
-        setSessionCostUsd(state, action) {
-            state.sessionCostUsd = action.payload;
-        },
-        setSessionTokensConsumed(state, action) {
-            state.sessionTokensConsumed = action.payload;
+        setSessionUsage(state, action) {
+            state.sessionUsage = action.payload;
         },
         setActiveModel(state, action) {
             state.activeModel = action.payload;
@@ -135,7 +132,13 @@ export const aiAssistantSlice = createSlice({
             state.messages = p.messages;
             state.pinnedAgentName = p.pinnedAgentName;
             state.flowOwnerAgentName = p.flowOwnerAgentName;
-            state.sessionCostUsd = p.sessionCostUsd;
+            // Derive the totals from the restored transcript rather than trusting a stored
+            // counter. Restore dispatches this action directly, bypassing the host's
+            // `messages` setter — the thing that normally recomputes — so a stored total
+            // would sit stale (historically at 0) until the next turn arrived. The
+            // transcript is the source of truth: per-message usage survives the snapshot,
+            // and a compacted summary carries the usage of the turns it replaced.
+            state.sessionUsage = sumUsage(p.messages);
             state.contextTokens = p.contextTokens;
             state.contextLimit = p.contextLimit;
             state.activeModel = p.activeModel;

package/dist/esm/state/ai-assistant-slice.test.js

@@ -8,10 +8,14 @@ Suite('loadSession hydrates the restorable fields and forces idle', () => {
     let start = createDefaultSessionState();
     start = reduce(start, setState('loading')); // prove it overrides any prior state
     const payload = {
-        messages: [{ role: 'user', content: 'hi' }],
+        // Usage rides on the message: `loadSession` derives the session totals from the
+        // restored transcript rather than from a stored counter, so the cost has to be in
+        // the messages for the assertion below to see it.
+        messages: [
+            { role: 'user', content: 'hi', cost: 1.25, inputTokens: 100, outputTokens: 20 },
+        ],
         pinnedAgentName: 'Guided Booking',
         flowOwnerAgentName: 'Guided Booking',
-        sessionCostUsd: 1.25,
         contextTokens: 1200,
         contextLimit: 200000,
         activeModel: 'claude-sonnet-4-6',
@@ -21,7 +25,11 @@ Suite('loadSession hydrates the restorable fields and forces idle', () => {
     assert.is(next.messages.length, 1);
     assert.is(next.pinnedAgentName, 'Guided Booking');
     assert.is(next.flowOwnerAgentName, 'Guided Booking');
-    assert.is(next.sessionCostUsd, 1.25);
+    assert.is(next.sessionUsage.costUsd, 1.25);
+    // Derived from the same walk: 100 prompt tokens with no cache split reported, so all
+    // of it is uncached input, plus the 20 generated.
+    assert.is(next.sessionUsage.uncachedInputTokens, 100);
+    assert.is(next.sessionUsage.outputTokens, 20);
     assert.is(next.contextTokens, 1200);
     assert.is(next.contextLimit, 200000);
     assert.is(next.activeModel, 'claude-sonnet-4-6');
@@ -35,7 +43,6 @@ Suite('resetSession wipes back to a fresh default', () => {
         messages: [],
         pinnedAgentName: 'A',
         flowOwnerAgentName: 'A',
-        sessionCostUsd: 9,
         contextTokens: 5,
         contextLimit: 10,
         activeModel: 'm',
@@ -43,7 +50,7 @@ Suite('resetSession wipes back to a fresh default', () => {
     }));
     const cleared = reduce(state, resetSession());
     assert.is(cleared.messages.length, 0);
-    assert.is(cleared.sessionCostUsd, 0);
+    assert.is(cleared.sessionUsage.costUsd, 0);
     assert.is(cleared.pinnedAgentName, null);
     assert.is(cleared.flowOwnerAgentName, null);
     assert.is(cleared.contextTokens, undefined);

package/dist/esm/state/debug-event-log.js

@@ -195,8 +195,8 @@ export const DEBUG_LOG_README = [
     'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',
     '`timeline` is the entire session as one array, already sorted chronologically by `timestamp` (ISO 8601). Every entry has a `kind`.',
     'Timestamps are millisecond-resolution; entries that share the same millisecond are ordered by a fixed kind rank (event, then turn, then message), which is a heuristic and may not reflect exact causal order within that millisecond — e.g. a user message and the turn it triggered, or a final assistant message and its turn.end event, can appear in either order depending on whether they landed in the same millisecond. Read the logical structure of a turn rather than over-interpreting the micro-ordering of co-timestamped entries of different kinds.',
-    "kind:'message' — the conversation. `role` is user/assistant/tool/system-event/synthetic-user; `agentName` says which agent produced it; `toolCalls`/`toolResult`/`interaction` carry tool and widget activity; `inputTokens`/`outputTokens`/`cost` are per-message LLM usage, and `externalCostUsd` is any non-LLM cost a widget reported for its own external service calls (folded into the session cost total alongside `cost`). On model-produced assistant messages, `model` is the concrete model id that generated it (e.g. 'gemini-2.5-flash-lite') and `providerName` is the registry slot it resolved under (e.g. a tier name like 'high'/'low', or the default); together they attribute the message — and any tool calls it carries — to an exact model even across a mid-session vendor/tier switch, where one slot name can map to different models before and after the switch. Both are undefined on any entry that is NOT an LLM response: non-assistant roles (user/tool/system-event) and 'synthetic-user' echoes; assistant interaction/widget entries (empty content carrying an `interaction` — a rendered widget, not a model turn); driver-authored assistant fallbacks (the timeout, repeated-malformed-call, and empty-response apology messages); and messages restored from a session persisted before these fields existed. One partial case: on a genuine model turn whose provider exposes no `getStatus` (or reports no model), `providerName` is still set but `model` alone is undefined. A 'synthetic-user' message is a display-only echo of an interaction outcome (e.g. the answer a widget reported): it renders on the user's side of the chat and `agentName` is the agent that created it, but it is never sent to the LLM — so it has no matching 'turn' and the model learns the outcome only from the corresponding tool result.",
-    "Sub-agent messages appear inline. When a tool delegates to a sub-agent (via `requestSubAgent`), the sub-agent's whole conversation — its own assistant/tool messages, each with their own `content`/`thinking`/`toolCalls`/`toolResult` and per-message `model`/`providerName`/`inputTokens`/`outputTokens`/`cost` — is hoisted into the timeline as ordinary kind:'message' entries, interleaved by timestamp right after the tool call that spawned them (so you read the delegation top-to-bottom). A hoisted entry is marked: `subAgentDepth` is its delegation depth (1 for a sub-agent, 2 for a sub-agent's sub-agent, …), `subAgentOf` is the id of the parent tool call that spawned it (correlates it back even when two sub-agents run in one parent turn), `subAgentName` is the sub-agent's own name, and `agentName` is rewritten to a `\"<parent> › <sub-agent>\"` breadcrumb (composing when nested, e.g. `\"UI Builder › Planner › Grounding\"`). The sub-agent's per-LLM-call snapshots also surface as kind:'turn' entries with an N-M `turnIndex`, and subagent.started/completed (or subagent.failed) events bracket the run. Per-message `cost` on hoisted entries is already part of the session total (it is summed from the un-flattened history), so summing the top-level timeline does NOT double-count.",
+    "kind:'message' — the conversation. `role` is user/assistant/tool/system-event/synthetic-user; `agentName` says which agent produced it; `toolCalls`/`toolResult`/`interaction` carry tool and widget activity; `inputTokens`/`outputTokens`/`cost` are per-message LLM usage, where `inputTokens` is the WHOLE prompt for that request and `cacheReadTokens`/`cacheWriteTokens` BREAK IT DOWN rather than add to it — uncached input is `inputTokens` minus those two, and adding the cache fields to `inputTokens` counts the prompt twice. The cache fields are absent on providers that report no cache split (Gemini reports reads only, since implicit caching bills no write) and on messages persisted before they existed, so read them as 0 when missing. Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a large token count at a small cost means the prompt was mostly cache hits. `externalCostUsd` is any non-LLM cost a widget reported for its own external service calls (folded into the session cost total alongside `cost`). On model-produced assistant messages, `model` is the concrete model id that generated it (e.g. 'gemini-2.5-flash-lite') and `providerName` is the registry slot it resolved under (e.g. a tier name like 'high'/'low', or the default); together they attribute the message — and any tool calls it carries — to an exact model even across a mid-session vendor/tier switch, where one slot name can map to different models before and after the switch. Both are undefined on any entry that is NOT an LLM response: non-assistant roles (user/tool/system-event) and 'synthetic-user' echoes; assistant interaction/widget entries (empty content carrying an `interaction` — a rendered widget, not a model turn); driver-authored assistant fallbacks (the timeout, repeated-malformed-call, and empty-response apology messages); and messages restored from a session persisted before these fields existed. One partial case: on a genuine model turn whose provider exposes no `getStatus` (or reports no model), `providerName` is still set but `model` alone is undefined. A 'synthetic-user' message is a display-only echo of an interaction outcome (e.g. the answer a widget reported): it renders on the user's side of the chat and `agentName` is the agent that created it, but it is never sent to the LLM — so it has no matching 'turn' and the model learns the outcome only from the corresponding tool result.",
+    "Sub-agent messages appear inline. When a tool delegates to a sub-agent (via `requestSubAgent`), the sub-agent's whole conversation — its own assistant/tool messages, each with their own `content`/`thinking`/`toolCalls`/`toolResult` and per-message `model`/`providerName`/`inputTokens`/`outputTokens`/`cacheReadTokens`/`cacheWriteTokens`/`cost` — is hoisted into the timeline as ordinary kind:'message' entries, interleaved by timestamp right after the tool call that spawned them (so you read the delegation top-to-bottom). A hoisted entry is marked: `subAgentDepth` is its delegation depth (1 for a sub-agent, 2 for a sub-agent's sub-agent, …), `subAgentOf` is the id of the parent tool call that spawned it (correlates it back even when two sub-agents run in one parent turn), `subAgentName` is the sub-agent's own name, and `agentName` is rewritten to a `\"<parent> › <sub-agent>\"` breadcrumb (composing when nested, e.g. `\"UI Builder › Planner › Grounding\"`). The sub-agent's per-LLM-call snapshots also surface as kind:'turn' entries with an N-M `turnIndex`, and subagent.started/completed (or subagent.failed) events bracket the run. Per-message `cost` on hoisted entries is already part of the session total (it is summed from the un-flattened history), so summing the top-level timeline does NOT double-count.",
     "kind:'turn' — one LLM call. `turnIndex` is a string: a top-level turn is the bare counter ('0', '1', …); a sub-agent's turns are numbered under the parent turn that activated them ('3-1', '3-2', …, and a nested sub-agent contributes '3-2-1', …), and `agentName` names the agent that ran the turn. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.",
     "kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.",
     "kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.",

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

@@ -61,7 +61,11 @@ Suite('save → reload → restore brings back messages, selection, counters', (
     const restored = reduce(freshStore, loadSession(toLoadSessionPayload(snapshot)));
     assert.is(restored.messages.length, 2);
     assert.is(restored.pinnedAgentName, 'Guided Booking');
-    assert.is(restored.sessionCostUsd, 0.5);
+    // Cost comes from the restored transcript, NOT the snapshot's stored counter — so it
+    // is whatever the messages actually carry. Computed independently here rather than
+    // by calling the summing helper under test.
+    const expectedCost = restored.messages.reduce((sum, m) => { var _a, _b; return sum + ((_a = m.cost) !== null && _a !== void 0 ? _a : 0) + ((_b = m.externalCostUsd) !== null && _b !== void 0 ? _b : 0); }, 0);
+    assert.is(restored.sessionUsage.costUsd, expectedCost);
     assert.is(restored.contextTokens, 800);
     assert.is(restored.contextLimit, 200000);
     assert.is(restored.activeModel, 'claude-sonnet-4-6');

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

@@ -225,7 +225,7 @@ export class SessionPersister {
                     activeAgentName: (_d = s.activeAgent) === null || _d === void 0 ? void 0 : _d.name,
                     pinnedAgentName: s.pinnedAgentName,
                     flowOwnerAgentName: null,
-                    sessionCostUsd: s.sessionCostUsd,
+                    sessionCostUsd: s.sessionUsage.costUsd,
                     contextTokens: s.contextTokens,
                     contextLimit: s.contextLimit,
                     activeModel: s.activeModel,
@@ -256,7 +256,7 @@ export class SessionPersister {
                 activeAgentName: (_f = s.activeAgent) === null || _f === void 0 ? void 0 : _f.name,
                 pinnedAgentName: s.pinnedAgentName,
                 flowOwnerAgentName: s.flowOwnerAgentName,
-                sessionCostUsd: s.sessionCostUsd,
+                sessionCostUsd: s.sessionUsage.costUsd,
                 contextTokens: s.contextTokens,
                 contextLimit: s.contextLimit,
                 activeModel: s.activeModel,

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

@@ -44,7 +44,16 @@ function makePersister(over = {}) {
                 flowActivationPrompt: null,
                 activeAgent: undefined,
                 pinnedAgentName: null,
-                sessionCostUsd: 0,
+                // Inline rather than via `emptyUsage()` to keep this mock self-contained. The
+                // shape matters: the persister reads `sessionUsage.costUsd`, so a mock missing
+                // the object crashes the autosave timer rather than failing an assertion.
+                sessionUsage: {
+                    costUsd: 0,
+                    uncachedInputTokens: 0,
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
+                    outputTokens: 0,
+                },
                 get restoring() {
                     return f.restoring;
                 },

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

@@ -92,12 +92,16 @@ export function isRestorableSession(value, opts) {
  * @internal
  */
 export function toLoadSessionPayload(s) {
-    var _a, _b, _c;
+    var _a, _b;
     return {
         messages: s.messages,
         pinnedAgentName: (_a = s.pinnedAgentName) !== null && _a !== void 0 ? _a : null,
         flowOwnerAgentName: (_b = s.flowOwnerAgentName) !== null && _b !== void 0 ? _b : null,
-        sessionCostUsd: (_c = s.sessionCostUsd) !== null && _c !== void 0 ? _c : 0,
+        // `sessionCostUsd` is deliberately NOT projected: the slice re-derives cost and
+        // token totals from `messages` on load. The snapshot field is still written (its
+        // shape is public, and it is a useful cross-check in a saved blob), but it is no
+        // longer authoritative — a snapshot saved mid-reset could hold a zeroed total
+        // while its transcript still shows the spend.
         contextTokens: s.contextTokens,
         contextLimit: s.contextLimit,
         activeModel: s.activeModel,

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

@@ -49,7 +49,10 @@ Suite('toLoadSessionPayload projects only the redux-restorable fields', () => {
     const p = toLoadSessionPayload(base());
     assert.is(p.pinnedAgentName, 'A');
     assert.is(p.flowOwnerAgentName, null);
-    assert.is(p.sessionCostUsd, 2);
+    // Cost is deliberately NOT projected — the slice re-derives it (and the token
+    // buckets) from `messages`, so a stored counter would be a second, divergeable
+    // source of truth.
+    assert.is(p.sessionCostUsd, undefined);
     assert.is(p.contextTokens, 10);
     assert.is(p.contextLimit, 100);
     assert.is(p.activeModel, 'm');

package/dist/esm/state/persistence/stateful-restore.e2e.test.js

@@ -55,7 +55,16 @@ function makeMemoryProvider() {
 function makeStoreFake(over = {}) {
     return {
         store: {
-            aiAssistant: Object.assign({ messages: [], flowOwnerAgentName: null, flowActivationPrompt: null, activeAgent: undefined, pinnedAgentName: null, sessionCostUsd: 0, contextTokens: 0, contextLimit: 0, activeModel: undefined, activeProviderName: undefined, restoring: false }, over),
+            aiAssistant: Object.assign({ messages: [], flowOwnerAgentName: null, flowActivationPrompt: null, activeAgent: undefined, pinnedAgentName: null, 
+                // The persister reads `sessionUsage.costUsd` when building a snapshot, so this
+                // has to be the object rather than a bare cost scalar.
+                sessionUsage: {
+                    costUsd: 0,
+                    uncachedInputTokens: 0,
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
+                    outputTokens: 0,
+                }, contextTokens: 0, contextLimit: 0, activeModel: undefined, activeProviderName: undefined, restoring: false }, over),
         },
         actions: {
             aiAssistant: {

package/dist/esm/styles/settings-section.js

@@ -0,0 +1,39 @@
+import { css } from '@genesislcap/web-core';
+/**
+ * Heading style for a settings-modal section, published so a host can title its own section.
+ *
+ * The assistant renders no heading for the `settings-app` slot — no text and no icon — because
+ * only the host knows what that section is. The consequence is that a host supplying one has to
+ * reproduce the styling of the built-in headings beside it, and a copied rule drifts the moment
+ * either side changes. So the declarations live here, are applied by the assistant's own
+ * headings, and are exported for the host to apply to its.
+ *
+ * Compose it into a component's styles and put `ai-settings-section-title` on the heading:
+ *
+ * ```ts
+ * import { assistantSettingsSectionTitleStyles } from '@genesislcap/ai-assistant';
+ *
+ * const styles = css`
+ *   ${assistantSettingsSectionTitleStyles}
+ *   :host { display: block; }
+ * `;
+ * ```
+ *
+ * Carries no margin on purpose: spacing belongs to the surrounding layout, which differs
+ * between the assistant's own sections and a slotted one, and is the single declaration hosts
+ * had to diverge on when they copied this rule.
+ *
+ * @beta
+ */
+export const assistantSettingsSectionTitleStyles = css `
+  .ai-settings-section-title {
+    display: flex;
+    align-items: center;
+    gap: calc(var(--design-unit) * 2px);
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--neutral-foreground-hint);
+  }
+`;

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

@@ -1,9 +1,28 @@
+import { emptyUsage } from './sum-usage';
 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) {
+    if (typeof value !== 'object' || value == null)
+        return false;
+    const u = value;
+    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) {
     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) {
     if (typeof localStorage === 'undefined')
         return [];
@@ -31,17 +50,62 @@ export function saveCostSessionHistory(scope, records) {
         // Quota exceeded or private browsing — non-fatal.
     }
 }
-/** Prepend a record and persist. Returns the updated list. */
-export function appendCostSessionRecord(scope, record) {
-    const records = [record, ...loadCostSessionHistory(scope)];
-    saveCostSessionHistory(scope, records);
-    return records;
+/**
+ * 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, record) {
+    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) {
+    return [...records].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
 }
-/** Remove one record by id. Returns the updated list. */
-export function removeCostSessionRecord(scope, id) {
-    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, transcriptIsAuthoritative) {
+    if (!existing)
+        return emptyUsage();
+    const carried = transcriptIsAuthoritative ? existing.banked : existing.usage;
+    return carried !== null && carried !== void 0 ? carried : emptyUsage();
 }
 /** Clear all persisted records for a scope. */
 export function clearCostSessionHistory(scope) {
@@ -62,14 +126,27 @@ export function formatCostSessionDate(iso) {
         year: 'numeric',
     }).format(new Date(iso));
 }
-function isCostSessionRecord(value) {
+/**
+ * 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) {
     if (typeof value !== 'object' || value == null)
         return false;
     const r = value;
     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/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;
 }