@genesislcap/ai-assistant 15.12.0 → 15.13.1

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

@@ -46,6 +46,49 @@ export function addUsage(a, b) {
         outputTokens: a.outputTokens + b.outputTokens,
     };
 }
+/**
+ * The four buckets plus USD for ONE message — the per-message fields projected into
+ * the disjoint, addable shape, or `undefined` when the message reports no usage at
+ * all (a user turn, a display-only reasoning/narration split, a provider that
+ * reports none).
+ *
+ * Shallow by design: it does NOT recurse into `toolCalls[].subAgentTrace` and does
+ * NOT count `compaction.rolledUpUsage`, so it answers "what did this one request
+ * cost" rather than "what did this message and everything under it cost". Use
+ * {@link sumUsage} for the latter — passing a whole transcript through this one
+ * message at a time would silently drop both.
+ *
+ * `costUsd` folds in `externalCostUsd` (non-LLM spend a widget reported), matching
+ * `sumUsage`. It is `0` when the provider priced nothing, which is NOT a claim that
+ * the call was free — see {@link AggregateUsage}; `UsageRow.costUsd` is the
+ * shape that keeps unpriced distinguishable, and is the right tool for a ledger.
+ *
+ * @beta
+ */
+export function messageUsage(m) {
+    var _a, _b, _c, _d, _e, _f;
+    if (m.cost == null &&
+        m.externalCostUsd == null &&
+        m.inputTokens == null &&
+        m.outputTokens == null &&
+        m.cacheReadTokens == null &&
+        m.cacheWriteTokens == null) {
+        return undefined;
+    }
+    const cacheReadTokens = (_a = m.cacheReadTokens) !== null && _a !== void 0 ? _a : 0;
+    const cacheWriteTokens = (_b = m.cacheWriteTokens) !== null && _b !== void 0 ? _b : 0;
+    return {
+        costUsd: ((_c = m.cost) !== null && _c !== void 0 ? _c : 0) + ((_d = m.externalCostUsd) !== null && _d !== void 0 ? _d : 0),
+        // The uncached REMAINDER, clamped — the same arithmetic `accumulate` below applies,
+        // for the same reasons. The two are deliberately separate implementations (that walk
+        // mutates one accumulator rather than allocating per message) and must agree;
+        // `sum-usage.test.ts` pins them together.
+        uncachedInputTokens: Math.max(0, ((_e = m.inputTokens) !== null && _e !== void 0 ? _e : 0) - cacheReadTokens - cacheWriteTokens),
+        cacheReadTokens,
+        cacheWriteTokens,
+        outputTokens: (_f = m.outputTokens) !== null && _f !== void 0 ? _f : 0,
+    };
+}
 /**
  * Sum cost and per-bucket token usage across a message list.
  *

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

@@ -1,5 +1,5 @@
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { addUsage, emptyUsage, sumUsage, totalTokens } from './sum-usage';
+import { addUsage, emptyUsage, messageUsage, sumUsage, totalTokens } from './sum-usage';
 const suite = createLogicSuite('sumUsage');
 const msg = (over = {}) => (Object.assign({ role: 'assistant', content: '' }, over));
 suite('returns zeroes when no message carries usage', () => {
@@ -117,4 +117,48 @@ suite('addUsage with an empty operand is the identity', () => {
     assert.equal(addUsage(a, emptyUsage()), a);
     assert.equal(addUsage(emptyUsage(), a), a);
 });
+suite('messageUsage is undefined for a message reporting nothing', () => {
+    // A user turn, or a display-only reasoning/narration split. Distinct from a zeroed
+    // usage: "this call reported nothing" is not "this call cost nothing".
+    assert.is(messageUsage(msg({ role: 'user', content: 'hi' })), undefined);
+    assert.is(messageUsage(msg({ content: 'thinking…', category: 'reasoning' })), undefined);
+});
+suite('messageUsage agrees with sumUsage over the same single message', () => {
+    // The two derivations are deliberately separate — `accumulate` mutates one
+    // accumulator rather than allocating per message — so pin them together. A drift
+    // here would put one figure on a turn entry and a different one in the session
+    // total, both looking plausible.
+    const cases = [
+        { inputTokens: 1000, cacheReadTokens: 700, cacheWriteTokens: 200, outputTokens: 50, cost: 0.4 },
+        { inputTokens: 400, outputTokens: 60 },
+        { inputTokens: 100, cacheReadTokens: 90, cacheWriteTokens: 90 },
+        { cost: 0.01, externalCostUsd: 0.02 },
+    ];
+    for (const over of cases) {
+        const m = msg(over);
+        assert.equal(messageUsage(m), sumUsage([m]), `messageUsage must match sumUsage for ${JSON.stringify(over)}`);
+    }
+});
+suite('messageUsage is shallow — it prices the one request, not the tree', () => {
+    // Deliberately blind to sub-agent traces and banked compaction usage: it answers
+    // "what did this call cost", which is what a turn snapshot needs. `sumUsage` is the
+    // function that walks everything underneath.
+    const m = msg({
+        inputTokens: 100,
+        outputTokens: 10,
+        cost: 0.05,
+        toolCalls: [
+            {
+                id: 't1',
+                name: 'delegate',
+                args: {},
+                subAgentTrace: [msg({ inputTokens: 900, outputTokens: 90, cost: 0.5 })],
+            },
+        ],
+    });
+    const usage = messageUsage(m);
+    assert.is(usage.costUsd, 0.05, 'the child conversation is not folded in');
+    assert.is(usage.uncachedInputTokens, 100);
+    assert.ok(sumUsage([m]).costUsd > usage.costUsd, 'sumUsage does fold it in');
+});
 suite.run();

package/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.invocation-scope.test.ts","../src/components/chat-driver/chat-driver.test.ts","../src/components/chat-driver/chat-driver.thinking-policy.test.ts","../src/components/chat-driver/chat-driver.trace-capture.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.budget.test.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.test.ts","../src/components/settings-modal/settings-modal.styles.ts","../src/components/settings-modal/settings-modal.template.test.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/blocked-state.test.ts","../src/main/budget-meter.test.ts","../src/main/cost-session-banking.test.ts","../src/main/index.ts","../src/main/main.styles.test.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/banked-usage-baselines.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/format-usd.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/usage-rows.test.ts","../src/utils/usage-rows.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.invocation-scope.test.ts","../src/components/chat-driver/chat-driver.test.ts","../src/components/chat-driver/chat-driver.thinking-policy.test.ts","../src/components/chat-driver/chat-driver.trace-capture.test.ts","../src/components/chat-driver/chat-driver.ts","../src/components/chat-driver/chat-driver.turn-usage.test.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.budget.test.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.test.ts","../src/components/settings-modal/settings-modal.styles.ts","../src/components/settings-modal/settings-modal.template.test.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/blocked-state.test.ts","../src/main/budget-meter.test.ts","../src/main/cost-session-banking.test.ts","../src/main/index.ts","../src/main/main.styles.test.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/banked-usage-baselines.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/format-usd.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/usage-rows.test.ts","../src/utils/usage-rows.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.12.0",
+  "version": "15.13.1",
   "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.12.0",
-    "@genesislcap/genx": "15.12.0",
-    "@genesislcap/rollup-builder": "15.12.0",
-    "@genesislcap/ts-builder": "15.12.0",
-    "@genesislcap/uvu-playwright-builder": "15.12.0",
-    "@genesislcap/vite-builder": "15.12.0",
-    "@genesislcap/webpack-builder": "15.12.0",
+    "@genesislcap/foundation-testing": "15.13.1",
+    "@genesislcap/genx": "15.13.1",
+    "@genesislcap/rollup-builder": "15.13.1",
+    "@genesislcap/ts-builder": "15.13.1",
+    "@genesislcap/uvu-playwright-builder": "15.13.1",
+    "@genesislcap/vite-builder": "15.13.1",
+    "@genesislcap/webpack-builder": "15.13.1",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2",
     "esbuild": "0.25.12"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "15.12.0",
-    "@genesislcap/foundation-logger": "15.12.0",
-    "@genesislcap/foundation-notifications": "15.12.0",
-    "@genesislcap/foundation-redux": "15.12.0",
-    "@genesislcap/foundation-ui": "15.12.0",
-    "@genesislcap/foundation-utils": "15.12.0",
-    "@genesislcap/rapid-design-system": "15.12.0",
-    "@genesislcap/web-core": "15.12.0",
+    "@genesislcap/foundation-ai": "15.13.1",
+    "@genesislcap/foundation-logger": "15.13.1",
+    "@genesislcap/foundation-notifications": "15.13.1",
+    "@genesislcap/foundation-redux": "15.13.1",
+    "@genesislcap/foundation-ui": "15.13.1",
+    "@genesislcap/foundation-utils": "15.13.1",
+    "@genesislcap/rapid-design-system": "15.13.1",
+    "@genesislcap/web-core": "15.13.1",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -105,5 +105,5 @@
     "access": "public"
   },
   "customElements": "dist/custom-elements.json",
-  "gitHead": "06f5ab51086c6616c6b96a7a1aebccddb3af7881"
+  "gitHead": "4ac0cfb22051b17da81586baf5166c9b605fae10"
 }

package/src/chat-driver-node.ts

@@ -105,7 +105,13 @@ export type {
 // `addUsage`/`emptyUsage` are the composition primitives for a conversation that CONTINUES across
 // rounds — see the guidance on `sumUsage` itself. `totalTokens` exists because the four buckets of
 // an `AggregateUsage` are disjoint and safe to add, which the per-message fields are NOT.
-export { addUsage, emptyUsage, sumUsage, totalTokens } from './utils/sum-usage';
+//
+// `messageUsage` is the single-message projection of the same arithmetic — what ONE request
+// cost, in the same four-bucket shape. It is what prices a turn snapshot (see
+// `TurnSnapshot.usage`), and the reason a consumer needs it separately is that the response
+// to a *failed* attempt never reaches history, so `sumUsage` over the transcript cannot see
+// that spend at all.
+export { addUsage, emptyUsage, messageUsage, sumUsage, totalTokens } from './utils/sum-usage';
 
 // Per-call projection, for the cases an aggregate cannot serve: usage rows for
 // per-project attribution, a cost dashboard, or auditing which turns came back
@@ -128,5 +134,9 @@ export { clearSession, getMetaEvents } from './state/debug-event-log';
 export type { MetaEvent } from './state/debug-event-log';
 export { buildTimelineEntries } from './state/persistence/build-timeline-entries';
 export type { TurnSnapshotLike } from './state/persistence/build-timeline-entries';
-export { assembleDebugLog } from './state/persistence/diagnostics';
+// `withFreshMetaSnapshot` matters to a headless consumer that stitches a STORED stream: the
+// newest stored `meta-snapshot` is frozen at the last config-signature change, so its context
+// and cost figures are as old as that. Pass a fresh snapshot of your own through this before
+// `assembleDebugLog`, or state in your own output that the totals are historical.
+export { assembleDebugLog, withFreshMetaSnapshot } from './state/persistence/diagnostics';
 export type { DebugLog, DiagnosticEntry } from './state/persistence/diagnostics';

package/src/components/chat-driver/chat-driver.ts

@@ -1,4 +1,5 @@
 import type {
+  AggregateUsage,
   AIProvider,
   AIProviderRegistry,
   AIProviderType,
@@ -70,7 +71,7 @@ import {
   normalizeForProvider,
 } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
-import { sumUsage } from '../../utils/sum-usage';
+import { messageUsage, sumUsage } from '../../utils/sum-usage';
 import { TOOL_FOLD_SYMBOL, type ToolFold } from '../../utils/tool-fold';
 import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
 
@@ -241,6 +242,46 @@ export interface TurnSnapshot {
   agentLabel?: string;
   /** Agent-supplied snapshot — machine state/context for stateful agents, undefined otherwise. */
   agentSnapshot?: unknown;
+  /**
+   * Concrete model that ran this call (e.g. `'claude-sonnet-4-6'`) — the serving model
+   * where the provider reports one, else the model the resolved tier was configured
+   * with. Undefined when the provider exposes no `getStatus` and the transport stamped
+   * nothing.
+   *
+   * Recorded per call, so an agent whose `provider` selector varies by state (a tier
+   * switch between steps of a flow) has each step attributed to the model that actually
+   * ran it — without the reader having to join the turn to the message after it, which
+   * is impossible for a call that produced no message.
+   */
+  model?: string;
+  /**
+   * Registry slot the provider resolved under for this call — a tier name like
+   * `'high'`/`'low'`, or the registry default's name. Kept alongside {@link
+   * TurnSnapshot.model} because they answer different questions: the slot is what the
+   * agent asked for, the model is what served it, and repointing a slot at a new model
+   * mid-session is only visible when both are recorded.
+   */
+  providerName?: string;
+  /** Vendor behind the resolved slot (`'anthropic'`, `'gemini'`, …), when the provider reports it. */
+  provider?: AIProviderType;
+  /**
+   * What this one LLM call cost — the four disjoint token buckets plus USD, derived
+   * from the response's usage by `messageUsage`. Back-filled when the response lands
+   * (the rest of the snapshot is captured *before* the call), so it is `undefined`
+   * while the call is in flight, on providers that report no usage, and on a call that
+   * threw rather than returning — a malformed-call/truncation/402 error carries no usage
+   * block, so any tokens the provider billed for it are not recoverable here.
+   *
+   * A snapshot is one **model call**, not one user turn: every tool-loop iteration and
+   * every retried attempt records its own. That makes this the only record of spend on
+   * an attempt that produced no message — a blank or refused response is billed and
+   * then discarded (see the empty-response retries), so summing the transcript alone
+   * under-reports the turn.
+   *
+   * For a call that DID produce a message, this is the same money as that message's
+   * `cost`/token fields, not additional money — never add turn usage to message usage.
+   */
+  usage?: AggregateUsage;
 }
 
 interface FoldStackFrame {
@@ -1140,7 +1181,14 @@ export class ChatDriver extends EventTarget implements AiDriver {
     if (resolvedName !== this.lastDispatchedProviderName) {
       this.lastDispatchedProviderName = resolvedName;
       recordMetaEvent(this.sessionKey, 'provider.selected', {
+        // `provider` is the registry SLOT (a tier name like 'high'), kept under that key
+        // for compatibility; `model` and `vendor` are what it resolved to. Recording all
+        // three is the difference between "the agent switched to its high tier" and
+        // knowing which model that actually was — a tier can be repointed mid-session,
+        // and a slot name alone cannot distinguish anthropic from gemini.
         provider: resolvedName,
+        model: status.model,
+        vendor: status.provider,
         agent: this.activeAgentName,
       });
       this.dispatchEvent(
@@ -1304,13 +1352,17 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * Push one snapshot to the ring buffer. Called inside `runToolLoop` just
    * before each LLM call — that's the latest point where the prompt, tool
    * surface, and agent state line up with what the model is about to see.
+   *
+   * Returns the pushed object so the caller can back-fill what only the response
+   * knows (`usage`). Mutating it after the fact is safe whether or not the ring
+   * buffer has since evicted it — an evicted snapshot is simply no longer exported.
    */
   private recordTurnSnapshot(
     resolvedSystemPrompt: string | undefined,
     temperature: number | undefined,
     toolChoice: ChatToolChoice | undefined,
     tailContext: string | undefined,
-  ): void {
+  ): TurnSnapshot {
     let agentSnapshot: unknown;
     if (this.debugSnapshotter) {
       try {
@@ -1324,7 +1376,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
     }
     const turnIndex = String(this.globalTurnIndex);
     this.globalTurnIndex += 1;
-    this.turnSnapshots.push({
+    const snapshot: TurnSnapshot = {
       turnIndex,
       timestamp: new Date().toISOString(),
       agentName: this.activeAgentName,
@@ -1335,10 +1387,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
       temperature,
       toolChoice,
       agentSnapshot,
-    });
+    };
+    this.turnSnapshots.push(snapshot);
     if (this.turnSnapshots.length > this.maxTurnSnapshots) {
       this.turnSnapshots.shift();
     }
+    return snapshot;
   }
 
   /**
@@ -2759,7 +2813,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
       // force when no tools are advertised.)
       const effectiveToolChoice = resolvedToolChoice ?? (this.isSubAgent ? 'required' : undefined);
 
-      this.recordTurnSnapshot(systemPrompt, resolvedTemperature, effectiveToolChoice, tailContext);
+      const turnSnapshot = this.recordTurnSnapshot(
+        systemPrompt,
+        resolvedTemperature,
+        effectiveToolChoice,
+        tailContext,
+      );
 
       // Capture the pending user input, then clear the slots BEFORE the chat
       // call. `sendMessage` already appended the user message to `this.history`,
@@ -2809,6 +2868,20 @@ export class ChatDriver extends EventTarget implements AiDriver {
       // oxlint-disable-next-line no-await-in-loop
       const activeProvider = await this.resolveProviderForTurn(promptCtx);
 
+      // Attribute the turn to the tier/model it resolved. Stamped HERE, not inside
+      // `recordTurnSnapshot`: the snapshot is taken before this line runs, so reading
+      // `lastResolved*` there yields the PREVIOUS call's model — wrong on precisely the
+      // turn where an agent's per-state `provider` selector switches tier, which is the
+      // turn a reader is looking for. `model` is refined to the serving model once the
+      // response lands (see below); until then — and on a call that throws — it is the
+      // model we ASKED for, which is the only thing knowable at that point.
+      if (this.lastResolvedProviderName !== undefined) {
+        turnSnapshot.providerName = this.lastResolvedProviderName;
+      }
+      if (this.lastResolvedProvider !== undefined)
+        turnSnapshot.provider = this.lastResolvedProvider;
+      if (this.lastResolvedModel !== undefined) turnSnapshot.model = this.lastResolvedModel;
+
       let response: ChatMessage;
       try {
         // oxlint-disable-next-line no-await-in-loop
@@ -2995,6 +3068,19 @@ export class ChatDriver extends EventTarget implements AiDriver {
         response.providerName = this.lastResolvedProviderName;
       }
 
+      // Back-fill what this call cost onto the snapshot taken just before it, so the
+      // exported debug log prices each model call next to the prompt/tools/state that
+      // produced it (GENC-1480 follow-up). Stamped BEFORE the empty-response branch
+      // below deliberately: a blank or refused response is billed and then thrown away,
+      // so the snapshot is the only place that spend is ever recorded.
+      turnSnapshot.usage = messageUsage(response);
+      // Take the SERVING model over the requested one, now that it is known. `response.model`
+      // was just filled from `lastResolvedModel` if the transport left it unset, so this is
+      // the same rule the message gets — which is the point: a turn and the message it
+      // produced must never disagree about which model ran, including when a server-side
+      // fallback chain answered on a different model than the one we asked for.
+      if (response.model !== undefined) turnSnapshot.model = response.model;
+
       const isThinkingStep = response.content && response.toolCalls?.length;
       const isEmptyResponse = !response.content?.trim() && !response.toolCalls?.length;
       // A pre-output refusal (safety-classifier decline, e.g. Fable 5 `stop_reason: 'refusal'`)
@@ -3060,8 +3146,23 @@ export class ChatDriver extends EventTarget implements AiDriver {
         // `sumCosts`/`sumTokens` don't double-count and `contextTokens` reads it. Reasoning/narration are
         // display-only (usage undefined) and are skipped when building the provider request. `model` /
         // `provider` / `providerName` stay on every split message so each is still attributed.
+        //
+        // EVERY usage field has to be cleared here, not just the three the invariant was
+        // originally written against — keep this list in step with the usage fields on
+        // `ChatMessage`. The cache buckets arrived later (GENC-1475) and were left riding
+        // along on the copies, so a response carrying reasoning AND narration counted its
+        // cache read/write volume three times in `sumUsage`/`usageRows` — invisible in the
+        // cost total (which comes from `cost`) but wrong in every bucket display and in the
+        // exported log.
         const { reasoning, ...rest } = response;
-        const displayOnly = { cost: undefined, inputTokens: undefined, outputTokens: undefined };
+        const displayOnly = {
+          cost: undefined,
+          externalCostUsd: undefined,
+          inputTokens: undefined,
+          outputTokens: undefined,
+          cacheReadTokens: undefined,
+          cacheWriteTokens: undefined,
+        };
         if (reasoning) {
           this.appendToHistory({
             ...rest,