@genesislcap/ai-assistant 15.10.6 → 15.12.0

package/dist/esm/config/define-stateful-agent.js

@@ -199,6 +199,16 @@ export function defineStatefulAgent(opts) {
             return opts.cachePolicy(Object.assign(Object.assign({}, ctx), { state }));
         })
         : opts.cachePolicy;
+    // Unlike the resolvers above, a pre-init call returns `undefined` rather than throwing: that is
+    // this option's "model default" state, so degrading to it costs a turn its thinking preference
+    // instead of breaking the turn outright.
+    const wrappedThinkingPolicy = typeof opts.thinkingPolicy === 'function'
+        ? (ctx) => __awaiter(this, void 0, void 0, function* () {
+            if (!state)
+                return undefined;
+            return opts.thinkingPolicy(Object.assign(Object.assign({}, ctx), { state }));
+        })
+        : opts.thinkingPolicy;
     const wrappedTailContext = typeof opts.tailContext === 'function'
         ? (ctx) => __awaiter(this, void 0, void 0, function* () {
             if (!state) {
@@ -249,6 +259,7 @@ export function defineStatefulAgent(opts) {
         temperature: wrappedTemperature,
         toolChoice: wrappedToolChoice,
         cachePolicy: wrappedCachePolicy,
+        thinkingPolicy: wrappedThinkingPolicy,
         tailContext: wrappedTailContext,
         onUnresolvedTool: wrappedOnUnresolvedTool,
         resumable: wrappedResumable,

package/dist/esm/main/blocked-state.test.js

@@ -219,6 +219,7 @@ Suite('a wall with figures snaps the vendor meter at latch time', () => {
     reachable(el, 'anthropic', 'gemini');
     latch(el, 'budget-exhausted', { vendorLabel: 'Anthropic', budgetUsd: 20, spentUsd: 20.1 });
     assert.equal(storedBudgets(el)['anthropic'], { budgetUsd: 20, spentUsd: 20.1 });
+    assert.ok(typeof el.budgetMeterLastFedAt === 'number', 'the wall feed stamps freshness too');
     // A later 402 for the same (already-walled) vendor carries fresher spend —
     // the feed is deliberately outside the idempotence guard, like the sweep.
     latch(el, 'budget-exhausted', { vendorLabel: 'Anthropic', budgetUsd: 20, spentUsd: 21.5 });

package/dist/esm/main/budget-meter.test.js

@@ -314,4 +314,46 @@ Suite('figures alone are enough to surface the AI Model Settings section', () =>
     el.chatConfig = { ui: { showBudgetUsage: false } };
     assert.is(el.settingsModelSectionVisible, false, 'and the config flag takes it back out');
 });
+// ── Freshness stamp + refresh request (GENC-1464 refresh affordance) ─────────
+Suite('every feed stamps budgetMeterLastFedAt — identical figures included', () => {
+    const el = element();
+    assert.is(el.budgetMeterLastFedAt, null, 'null before any feed');
+    assert.is(el.settingsBudgetUpdatedLabel, undefined, 'no label before any feed');
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 10 });
+    const first = el.budgetMeterLastFedAt;
+    assert.ok(typeof first === 'number', 'stamped on feed');
+    assert.ok(el.settingsBudgetUpdatedLabel.startsWith('Updated '), 'label renders');
+    // The store is idempotent by value, but a refresh that CONFIRMS the same
+    // dollars is still a refresh — the stamp must move even when the rows don't.
+    el.budgetMeterLastFedAt = first - 5000; // age it so a same-ms re-feed still differs
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 10 });
+    assert.ok(el.budgetMeterLastFedAt > first - 5000, 'identical re-feed still stamps');
+    // Clearing figures is not a refresh — the label describes shown figures.
+    const before = el.budgetMeterLastFedAt;
+    el.setVendorBudget('anthropic', null);
+    assert.is(el.budgetMeterLastFedAt, before, 'a clear does not stamp');
+});
+Suite('requestBudgetRefresh emits budget-refresh-requested, and settings open asks too', () => {
+    const el = element();
+    let fired = 0;
+    el.addEventListener('budget-refresh-requested', () => {
+        fired += 1;
+    });
+    el.requestBudgetRefresh();
+    assert.is(fired, 1, 'the button path emits');
+    // The element cannot fetch — the event is the whole contract. Hosts without
+    // a listener simply keep the per-turn cadence, so firing is unconditional.
+    //
+    // The modal stub is load-bearing: openSettingsModal's `show` closure
+    // re-queues itself via DOM.queueUpdate until `settingsModal` exists, and on
+    // an unconnected element that is never — an infinite queue that keeps the
+    // test runner alive (this file's documented hang class). `open: true` makes
+    // the first queued run return immediately.
+    el.settingsModal = {
+        open: true,
+        show() { },
+    };
+    el.openSettingsModal();
+    assert.is(fired, 2, 'opening settings requests fresh figures');
+});
 Suite.run();

package/dist/esm/main/main.js

@@ -265,6 +265,17 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
          * repeat the same warning on every send for the life of the page.
          */
         this.vendorBudgetWarningIssued = false;
+        /**
+         * When budget figures last arrived — from the host's {@link FoundationAiAssistant.setVendorBudget}
+         * or the wall latch's own feed — as epoch ms; `null` until the first feed.
+         *
+         * ELEMENT state, not slice state, on purpose: the reducer is idempotent by
+         * value (an unchanged re-feed must not re-render the meter rows), but "when
+         * was this fetched" must move on every feed, changed figures or not — a
+         * refresh that confirms the same dollars is still a refresh. Only the
+         * toolbar label observes this, so a stamp re-renders one span, not the rows.
+         */
+        this.budgetMeterLastFedAt = null;
         // ---- Transient UI state (stays as @observable on the component) ----
         this._suggestionsGeneration = 0;
         this.attachments = [];
@@ -982,8 +993,36 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             // must not adopt (and potentially freeze) state the host still owns.
             figures: figures == null ? null : { budgetUsd: figures.budgetUsd, spentUsd: figures.spentUsd },
         });
+        if (figures != null)
+            this.budgetMeterLastFedAt = Date.now();
         return true;
     }
+    /** "Updated HH:MM:SS" for the meter toolbar, or `undefined` before any feed. */
+    get settingsBudgetUpdatedLabel() {
+        if (this.budgetMeterLastFedAt == null)
+            return undefined;
+        return `Updated ${new Date(this.budgetMeterLastFedAt).toLocaleTimeString()}`;
+    }
+    /**
+     * Ask the host to re-fetch budget figures now (GENC-1464 refresh affordance).
+     *
+     * The element cannot fetch — the meter is host-fed by design — so this emits
+     * `budget-refresh-requested` and the host answers with the same fetch that
+     * already feeds {@link FoundationAiAssistant.setVendorBudget} (Create's handler coalesces in-flight
+     * fetches, so a spammed button costs one request). Fired by the meter's
+     * refresh button and on settings-modal open, so the figures are fresh exactly
+     * when someone is looking at them. Fires unconditionally: a host without a
+     * listener simply keeps the per-turn cadence.
+     */
+    requestBudgetRefresh() {
+        // Plain dispatchEvent, not FAST's $emit: $emit silently no-ops while the
+        // element is disconnected, and this must stay observable in headless/test
+        // harnesses that never connect (and in any odd pop-out lifecycle moment).
+        // bubbles + composed, matching this class's other events (SessionCleared
+        // et al): the element lives inside host shadow roots (Create nests it in
+        // gc-assistant's), and a delegation-based host must still see the request.
+        this.dispatchEvent(new CustomEvent('budget-refresh-requested', { bubbles: true, composed: true }));
+    }
     /** Whether this vendor's wall came from the sweep alone — see the slice's `sweptVendors`. */
     isVendorSwept(vendor) {
         var _a, _b;
@@ -1201,6 +1240,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                 vendor,
                 figures: { budgetUsd: budget.budgetUsd, spentUsd: budget.spentUsd },
             });
+            this.budgetMeterLastFedAt = Date.now();
         }
         if (!vendor || vendor === 'none') {
             if (!this.blocked) {
@@ -3459,6 +3499,9 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
     }
     openSettingsModal() {
         this.logMeta('panel.toggled', { panel: 'settings', open: true });
+        // The meter refreshes per turn, which a user staring at the modal cannot
+        // see — ask the host for fresh figures at the moment they start looking.
+        this.requestBudgetRefresh();
         this.settingsModalTab = 'settings';
         this.settingsOpen = true;
         const show = () => {
@@ -4375,6 +4418,12 @@ __decorate([
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "reachableVendors", null);
+__decorate([
+    observable
+], FoundationAiAssistant.prototype, "budgetMeterLastFedAt", void 0);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "settingsBudgetUpdatedLabel", null);
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "relevantBlockedVendors", null);

package/dist/esm/main/main.template.js

@@ -144,11 +144,30 @@ const subAgentToolResultTemplate = html `
 const subAgentMessageRowTemplate = html `
   ${when((m) => { var _a; return m.role === 'assistant' && !((_a = m.toolCalls) === null || _a === void 0 ? void 0 : _a.length) && !!m.content; }, subAgentAssistantTemplate)}${when((m) => { var _a; return !!((_a = m.toolCalls) === null || _a === void 0 ? void 0 : _a.length); }, subAgentToolCallTemplate)}${when((m) => { var _a; return m.role === 'tool' && !!((_a = m.toolResult) === null || _a === void 0 ? void 0 : _a.content); }, subAgentToolResultTemplate)}
 `;
+/**
+ * Label for a trace block: the distinct agents that appear in it.
+ *
+ * One tool call can invoke several sub-agents — a scheduler dispatching a dependency
+ * graph, or a retry — and their conversations arrive concatenated in one trace. Naming
+ * only `[0]` would then label a block "gen_A trace" while `gen_B`'s turns sit inside
+ * it. Two agents read as "gen_A, gen_B"; beyond that it degrades to a count rather
+ * than growing an unbounded summary line.
+ */
+const subAgentTraceLabel = (trace) => {
+    const names = [...new Set(trace.map((m) => m.agentName).filter(Boolean))];
+    if (names.length === 0)
+        return 'Sub-agent trace';
+    if (names.length <= 2)
+        return `${names.join(', ')} trace`;
+    // Owns the whole string rather than returning a fragment the template suffixes, so the noun
+    // agrees with the count — a shared ` trace` suffix rendered "3 sub-agents trace".
+    return `${names.length} sub-agent traces`;
+};
 /** Collapsed <details> trace shown inside a tool-call card once the sub-agent finishes. */
 const subAgentTraceTemplate = html `
   <details class="sub-agent-trace">
     <summary class="sub-agent-trace-summary">
-      ${(tc) => { var _a, _b; return (_b = (_a = tc.subAgentTrace[0]) === null || _a === void 0 ? void 0 : _a.agentName) !== null && _b !== void 0 ? _b : 'Sub-agent'; }} trace
+      ${(tc) => subAgentTraceLabel(tc.subAgentTrace)}
     </summary>
     ${repeat((tc) => tc.subAgentTrace.filter((m) => m.role !== 'user'), subAgentMessageRowTemplate)}
   </details>

package/dist/esm/utils/strip-agent-handlers.js

@@ -6,7 +6,7 @@
  *    `onDeactivate`, `getDebugSnapshot`, `onUnresolvedTool`) and the function
  *    form of the per-turn resolvers (`systemPrompt`, `toolDefinitions`,
  *    `displayName`, `provider`, `temperature`, `toolChoice`, `cachePolicy`,
- *    `toolHandlers`).
+ *    `thinkingPolicy`, `toolHandlers`).
  * 2. **Object "handler bags" whose *values* are functions** — `toolHandlers` in
  *    its object form is `{ name: handler }`, so `typeof` is `'object'`, not
  *    `'function'`. A by-value check on the field alone misses it, leaking a live

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

@@ -2,7 +2,7 @@
  * Zeroed {@link AggregateUsage}. A factory, not a shared const, because callers
  * accumulate into the returned object.
  *
- * @internal
+ * @beta
  */
 export function emptyUsage() {
     return {
@@ -23,7 +23,7 @@ export function emptyUsage() {
  * 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
+ * @beta
  */
 export function totalTokens(usage) {
     return (usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens + usage.outputTokens);
@@ -35,7 +35,7 @@ export function totalTokens(usage) {
  * proves. Pure rather than in-place because both operands are live state a caller
  * must not mutate.
  *
- * @internal
+ * @beta
  */
 export function addUsage(a, b) {
     return {
@@ -70,7 +70,40 @@ export function addUsage(a, b) {
  * 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
+ * @remarks
+ * This sums the WHOLE array, which is the right answer only when the array is the
+ * whole of the work being billed. A driver whose conversation **continues across
+ * rounds** opens its history with turns an earlier round already paid for, so
+ * summing it again bills them twice — and the session total then grows
+ * quadratically in the number of rounds while every individual figure in it stays
+ * correct. Nothing about the result looks wrong, which is why it is called out
+ * here rather than left to the caller to notice.
+ *
+ * Do NOT solve this with a "sum from this message onwards" marker. Compaction
+ * *replaces* the messages it summarises — and compaction is one of this function's
+ * own call sites — so the marker message can be absent from history by the time
+ * the sum runs, leaving the caller to either fail or silently sum everything,
+ * which is the double-count the marker was meant to prevent.
+ *
+ * Instead hold a **banked baseline**: spend that predates the current transcript,
+ * carried as a value, with `usage = banked + live` composed via {@link addUsage}.
+ * `resolveBankedUsage` in `utils/cost-session-history.ts` is the worked form, and
+ * the shape of its signature is the load-bearing part. It separates three cases:
+ *
+ * 1. no prior record — a genuine first round, so nothing is banked;
+ * 2. prior record, and the live transcript already accounts for it (a restored
+ *    session) — carry the prior record's own banked figure forward;
+ * 3. prior record, and the transcript starts empty — bank the prior record's
+ *    whole total, because nothing in the transcript can re-derive it.
+ *
+ * Case 1 and case 3 take the same arithmetic and mean opposite things, so the
+ * prior record must be a **required** input with no zero-defaulting path: a
+ * caller who carries a transcript and forgets its baseline reports the entire
+ * prior conversation as this round's spend. Distinguishing 2 from 3 is a separate
+ * decision, and getting it wrong is destructive in the other direction — it
+ * rewrites a total down to the current page-load and drops earlier spend.
+ *
+ * @beta
  */
 export function sumUsage(messages) {
     const total = emptyUsage();

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

@@ -0,0 +1,90 @@
+import { vendorOfModel } from '@genesislcap/foundation-ai';
+/** Whether a message carries anything a ledger would record. */
+function hasUsage(m) {
+    return (m.cost != null ||
+        m.externalCostUsd != null ||
+        m.inputTokens != null ||
+        m.outputTokens != null ||
+        m.cacheReadTokens != null ||
+        m.cacheWriteTokens != null);
+}
+/**
+ * Project a transcript into one row per billable unit of spend.
+ *
+ * @remarks
+ * Reads the messages and returns a table; it stores nothing, mutates nothing, and
+ * adds nothing to history. Use it where an **aggregate is not enough** — writing
+ * usage rows for per-project attribution, a cost dashboard, or auditing which turns
+ * came back unpriced. For a single total, `sumUsage` is the answer and this is the
+ * wrong tool.
+ *
+ * Walks the same shape `sumUsage` does, and is guaranteed to agree with it: summing
+ * `costUsd` and `externalCostUsd` across these rows equals `sumUsage(...).costUsd`
+ * over the same input, and the four token buckets reconcile likewise. That property
+ * is the point of the function — a per-call view that quietly disagrees with the
+ * total is worse than no per-call view, because both look right in isolation.
+ *
+ * Covers the two places spend hides:
+ *
+ * - **Sub-agent conversations.** A delegating tool call carries the child's entire
+ *   conversation on `toolCall.subAgentTrace`, so a walk of top-level messages alone
+ *   misses everything a delegating agent spent. A consumer that reimplemented this
+ *   and omitted the branch reported $0.106 on a run that cost $0.234.
+ * - **Compactions.** A compaction deletes the messages it summarises, banking their
+ *   spend on the summary. Those turns produce a single `source: 'compaction'` row.
+ *
+ * Messages carrying no usage at all (a user turn, a narration) produce no row.
+ *
+ * **Do not pass the result to `sumUsage`** — the types prevent it, and the reason is
+ * that both recurse, so a pre-flattened list would be counted twice. Both functions
+ * take raw history.
+ *
+ * @beta
+ */
+export function usageRows(messages) {
+    return collectRows(messages, 0, undefined);
+}
+/** Map an already-bucketed {@link AggregateUsage} onto a row's token fields. */
+function bucketsOf(usage) {
+    return {
+        uncachedInputTokens: usage.uncachedInputTokens,
+        cacheReadTokens: usage.cacheReadTokens,
+        cacheWriteTokens: usage.cacheWriteTokens,
+        outputTokens: usage.outputTokens,
+    };
+}
+function collectRows(messages, depth, subAgentOf) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const rows = [];
+    for (const m of messages) {
+        if (hasUsage(m)) {
+            const cacheReadTokens = (_a = m.cacheReadTokens) !== null && _a !== void 0 ? _a : 0;
+            const cacheWriteTokens = (_b = m.cacheWriteTokens) !== null && _b !== void 0 ? _b : 0;
+            rows.push(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ source: 'request', model: m.model, 
+                // The driver stamps `ChatMessage.provider` from the resolved provider's own
+                // status, so it is AUTHORITATIVE and covers vendors the model allowlists do
+                // not — a server-proxied `gpt-5` turn is `provider: 'openai'` on the message
+                // and unknown to `vendorOfModel`. Prefer it; fall back to resolving the model
+                // id only for messages persisted before the field existed. Still left
+                // undefined when neither knows, rather than guessed at.
+                provider: (_c = m.provider) !== null && _c !== void 0 ? _c : (m.model ? vendorOfModel(m.model) : undefined) }, (m.cost != null && { costUsd: m.cost })), (m.externalCostUsd != null && { externalCostUsd: m.externalCostUsd })), { 
+                // Uncached input is the REMAINDER, matching `sumUsage`: `inputTokens` is the
+                // whole prompt and the cache fields break it down. Clamped for the same
+                // reason — hand-edited history must not drive a total negative.
+                uncachedInputTokens: Math.max(0, ((_d = m.inputTokens) !== null && _d !== void 0 ? _d : 0) - cacheReadTokens - cacheWriteTokens), cacheReadTokens,
+                cacheWriteTokens, outputTokens: (_e = m.outputTokens) !== null && _e !== void 0 ? _e : 0 }), (m.agentName != null && { agentName: m.agentName })), { subAgentDepth: depth }), (subAgentOf != null && { subAgentOf })));
+        }
+        // Spend the compaction banked on this summary's behalf. Its buckets are already
+        // disjoint (it is an `AggregateUsage`), so they map across without the
+        // subtraction a per-message record needs.
+        const rolled = (_f = m.compaction) === null || _f === void 0 ? void 0 : _f.rolledUpUsage;
+        if (rolled) {
+            rows.push(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ source: 'compaction' }, (rolled.costUsd != null && { costUsd: rolled.costUsd })), bucketsOf(rolled)), (m.agentName != null && { agentName: m.agentName })), { subAgentDepth: depth }), (subAgentOf != null && { subAgentOf })));
+        }
+        for (const tc of (_g = m.toolCalls) !== null && _g !== void 0 ? _g : []) {
+            if (tc.subAgentTrace)
+                rows.push(...collectRows(tc.subAgentTrace, depth + 1, tc.id));
+        }
+    }
+    return rows;
+}

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

@@ -0,0 +1,189 @@
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import { sumUsage } from './sum-usage';
+import { usageRows } from './usage-rows';
+const msg = (over) => (Object.assign({ role: 'assistant', content: '' }, over));
+const rolled = (over) => (Object.assign({ costUsd: 0, uncachedInputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, outputTokens: 0 }, over));
+/** Every place spend can hide, in one transcript: a delegation and a compaction. */
+const richHistory = () => [
+    msg({
+        role: 'compacted-summary',
+        content: 'summary',
+        compaction: {
+            compactedCount: 4,
+            rolledUpUsage: rolled({ costUsd: 0.05, uncachedInputTokens: 400, outputTokens: 60 }),
+            // The summariser's model — NOT what the banked spend ran on.
+            model: 'claude-haiku-4-5-20251001',
+        },
+    }),
+    msg({ role: 'user', content: 'go' }),
+    msg({
+        model: 'claude-sonnet-5',
+        agentName: 'boss',
+        cost: 0.01,
+        inputTokens: 1000,
+        cacheReadTokens: 900,
+        outputTokens: 50,
+        toolCalls: [
+            {
+                id: 'tc1',
+                name: 'delegate',
+                args: {},
+                subAgentTrace: [
+                    msg({
+                        model: 'gemini-2.5-flash',
+                        agentName: 'worker',
+                        cost: 0.12,
+                        inputTokens: 500,
+                        outputTokens: 200,
+                    }),
+                ],
+            },
+        ],
+    }),
+];
+const suite = createLogicSuite('usageRows');
+suite('reconciles exactly with sumUsage over the same input', () => {
+    // THE guarantee. A per-call view that disagrees with the total is worse than none,
+    // because both look right in isolation — which is how the consumer's own copy
+    // under-reported for a month.
+    const history = richHistory();
+    const rows = usageRows(history);
+    const total = sumUsage(history);
+    const rowCost = rows.reduce((n, r) => { var _a, _b; return n + ((_a = r.costUsd) !== null && _a !== void 0 ? _a : 0) + ((_b = r.externalCostUsd) !== null && _b !== void 0 ? _b : 0); }, 0);
+    assert.ok(Math.abs(rowCost - total.costUsd) < 1e-12, `${rowCost} vs ${total.costUsd}`);
+    const bucket = (k) => rows.reduce((n, r) => n + r[k], 0);
+    assert.is(bucket('uncachedInputTokens'), total.uncachedInputTokens, 'uncached input');
+    assert.is(bucket('cacheReadTokens'), total.cacheReadTokens, 'cache read');
+    assert.is(bucket('cacheWriteTokens'), total.cacheWriteTokens, 'cache write');
+    assert.is(bucket('outputTokens'), total.outputTokens, 'output');
+});
+suite('emits a compaction row so banked spend is not lost from a per-call view', () => {
+    // The shortfall this function exists to close: the summary message carries no
+    // `cost` and no token fields of its own, so a naive per-message walk drops the
+    // spend of every turn the compaction deleted.
+    const rows = usageRows(richHistory());
+    const compactionRows = rows.filter((r) => r.source === 'compaction');
+    assert.is(compactionRows.length, 1);
+    assert.is(compactionRows[0].costUsd, 0.05);
+    assert.is(compactionRows[0].uncachedInputTokens, 400);
+    assert.is(compactionRows[0].model, undefined, 'no model — the banked spend may span several, and compaction.model is the summariser');
+});
+suite('recurses into sub-agent traces, tagging depth and the spawning call', () => {
+    const rows = usageRows(richHistory());
+    const child = rows.find((r) => r.model === 'gemini-2.5-flash');
+    assert.ok(child, 'the sub-agent turn produced a row');
+    assert.is(child.subAgentDepth, 1);
+    assert.is(child.subAgentOf, 'tc1');
+    assert.is(child.agentName, 'worker');
+    const parent = rows.find((r) => r.model === 'claude-sonnet-5');
+    assert.is(parent.subAgentDepth, 0);
+    assert.is(parent.subAgentOf, undefined);
+});
+suite('prefers the provider the driver stamped over re-deriving it from the model', () => {
+    // `ChatMessage.provider` comes from the resolved provider's own status, so it is
+    // authoritative and knows vendors the model allowlists do not. Re-deriving from the
+    // model id alone drops attribution for a server-proxied turn — exactly the rows a
+    // usage ledger cares most about getting right. PR review.
+    const rows = usageRows([
+        msg({ model: 'gpt-5', provider: 'openai', cost: 1, inputTokens: 1 }),
+        // Stamped provider disagrees with what the model id would derive: the stamp still wins.
+        msg({
+            model: 'claude-sonnet-5',
+            provider: 'chrome',
+            cost: 1,
+            inputTokens: 1,
+        }),
+    ]);
+    assert.equal(rows.map((r) => r.provider), ['openai', 'chrome']);
+});
+suite('resolves the provider from the model, and leaves it unset when unknown', () => {
+    const rows = usageRows([
+        msg({ model: 'claude-sonnet-5', cost: 1, inputTokens: 1 }),
+        msg({ model: 'gemini-2.5-flash', cost: 1, inputTokens: 1 }),
+        msg({ model: 'gpt-5', cost: 1, inputTokens: 1 }),
+        msg({ cost: 1, inputTokens: 1 }),
+    ]);
+    assert.equal(rows.map((r) => r.provider), ['anthropic', 'gemini', undefined, undefined], 'an unrecognised or absent model leaves provider unset rather than guessing');
+});
+suite('splits the prompt into buckets the same way sumUsage does', () => {
+    const [row] = usageRows([
+        msg({
+            model: 'claude-sonnet-5',
+            inputTokens: 1000,
+            cacheReadTokens: 600,
+            cacheWriteTokens: 300,
+        }),
+    ]);
+    assert.is(row.uncachedInputTokens, 100, 'the remainder, not an addition');
+    assert.is(row.cacheReadTokens, 600);
+    assert.is(row.cacheWriteTokens, 300);
+});
+suite('clamps a prompt whose cache buckets exceed the total', () => {
+    const [row] = usageRows([msg({ inputTokens: 100, cacheReadTokens: 900 })]);
+    assert.is(row.uncachedInputTokens, 0, 'never negative');
+});
+suite('leaves costUsd undefined when nothing was reported, rather than zero', () => {
+    // What the "carried usage but no cost" audit keys off. A zero here would read as a
+    // free call and the alarm would never fire.
+    const [row] = usageRows([msg({ model: 'claude-sonnet-5', inputTokens: 500, outputTokens: 10 })]);
+    assert.is(row.costUsd, undefined);
+    assert.is(row.source, 'request');
+});
+suite('records external (non-LLM) cost and counts it in the reconciliation', () => {
+    const history = [msg({ externalCostUsd: 0.4 }), msg({ model: 'claude-sonnet-5', cost: 0.1 })];
+    const rows = usageRows(history);
+    assert.is(rows.find((r) => r.externalCostUsd != null).externalCostUsd, 0.4);
+    const rowCost = rows.reduce((n, r) => { var _a, _b; return n + ((_a = r.costUsd) !== null && _a !== void 0 ? _a : 0) + ((_b = r.externalCostUsd) !== null && _b !== void 0 ? _b : 0); }, 0);
+    assert.ok(Math.abs(rowCost - sumUsage(history).costUsd) < 1e-12);
+});
+suite('produces no row for a message carrying no usage', () => {
+    assert.equal(usageRows([
+        msg({ role: 'user', content: 'hello' }),
+        msg({ content: 'thinking out loud', category: 'reasoning' }),
+    ]), []);
+});
+suite('is empty for an empty transcript', () => {
+    assert.equal(usageRows([]), []);
+});
+suite('reconciles on a nested delegation two levels deep', () => {
+    const history = [
+        msg({
+            model: 'claude-sonnet-5',
+            cost: 0.01,
+            inputTokens: 100,
+            toolCalls: [
+                {
+                    id: 'a',
+                    name: 'delegate',
+                    args: {},
+                    subAgentTrace: [
+                        msg({
+                            model: 'claude-sonnet-5',
+                            cost: 0.02,
+                            inputTokens: 200,
+                            toolCalls: [
+                                {
+                                    id: 'b',
+                                    name: 'delegate',
+                                    args: {},
+                                    subAgentTrace: [msg({ model: 'gemini-2.5-flash', cost: 0.04, inputTokens: 400 })],
+                                },
+                            ],
+                        }),
+                    ],
+                },
+            ],
+        }),
+    ];
+    const rows = usageRows(history);
+    assert.equal(rows.map((r) => r.subAgentDepth), [0, 1, 2]);
+    const rowCost = rows.reduce((n, r) => { var _a; return n + ((_a = r.costUsd) !== null && _a !== void 0 ? _a : 0); }, 0);
+    assert.ok(Math.abs(rowCost - sumUsage(history).costUsd) < 1e-12, 'still reconciles');
+});
+suite('does not mutate the transcript', () => {
+    const history = richHistory();
+    const before = JSON.stringify(history);
+    usageRows(history);
+    assert.is(JSON.stringify(history), before, 'a projection, not a transform');
+});
+suite.run();

package/dist/react.cjs

@@ -49,8 +49,10 @@ const AiWavesIndicator = React.forwardRef(function AiWavesIndicator(props, ref)
 });
 
 const FoundationAiAssistant = React.forwardRef(function FoundationAiAssistant(props, ref) {
-  const { onChatHeaderMousedown, onSessionCleared, children, ...rest } = props;
+  const { onBudgetRefreshRequested, onChatHeaderMousedown, onSessionCleared, children, ...rest } = props;
   const _innerRef = React.useRef(null);
+  const _onBudgetRefreshRequestedRef = React.useRef(onBudgetRefreshRequested);
+  _onBudgetRefreshRequestedRef.current = onBudgetRefreshRequested;
   const _onChatHeaderMousedownRef = React.useRef(onChatHeaderMousedown);
   _onChatHeaderMousedownRef.current = onChatHeaderMousedown;
   const _onSessionClearedRef = React.useRef(onSessionCleared);
@@ -58,11 +60,14 @@ const FoundationAiAssistant = React.forwardRef(function FoundationAiAssistant(pr
   React.useLayoutEffect(() => {
     const el = _innerRef.current;
     if (!el) return;
+    const _onBudgetRefreshRequestedFn = (e) => _onBudgetRefreshRequestedRef.current?.(e);
+    el.addEventListener('budget-refresh-requested', _onBudgetRefreshRequestedFn);
     const _onChatHeaderMousedownFn = (e) => _onChatHeaderMousedownRef.current?.(e);
     el.addEventListener('chat-header-mousedown', _onChatHeaderMousedownFn);
     const _onSessionClearedFn = (e) => _onSessionClearedRef.current?.(e);
     el.addEventListener('session-cleared', _onSessionClearedFn);
     return () => {
+      el.removeEventListener('budget-refresh-requested', _onBudgetRefreshRequestedFn);
       el.removeEventListener('chat-header-mousedown', _onChatHeaderMousedownFn);
       el.removeEventListener('session-cleared', _onSessionClearedFn);
     };
@@ -124,14 +129,14 @@ const AiChatInteractionWrapper = React.forwardRef(function AiChatInteractionWrap
   return React.createElement(customElements.getName(AiChatInteractionWrapperWC) ?? 'ai-chat-interaction-wrapper', { ...rest, ref: _mergeRefs(_innerRef, ref) }, children);
 });
 
-const FoundationAiPopoutManager = React.forwardRef(function FoundationAiPopoutManager(props, ref) {
+const AiChatMarkdown = React.forwardRef(function AiChatMarkdown(props, ref) {
   const { children, ...rest } = props;
-  return React.createElement(customElements.getName(FoundationAiPopoutManagerWC) ?? 'foundation-ai-popout-manager', { ...rest, ref }, children);
+  return React.createElement(customElements.getName(AiChatMarkdownWC) ?? 'ai-chat-markdown', { ...rest, ref }, children);
 });
 
-const AiChatMarkdown = React.forwardRef(function AiChatMarkdown(props, ref) {
+const FoundationAiPopoutManager = React.forwardRef(function FoundationAiPopoutManager(props, ref) {
   const { children, ...rest } = props;
-  return React.createElement(customElements.getName(AiChatMarkdownWC) ?? 'ai-chat-markdown', { ...rest, ref }, children);
+  return React.createElement(customElements.getName(FoundationAiPopoutManagerWC) ?? 'foundation-ai-popout-manager', { ...rest, ref }, children);
 });
 
 module.exports = {
@@ -145,6 +150,6 @@ module.exports = {
   AgentPicker,
   AiChatBubble,
   AiChatInteractionWrapper,
-  FoundationAiPopoutManager,
   AiChatMarkdown,
+  FoundationAiPopoutManager,
 };

package/dist/react.mjs

@@ -47,8 +47,10 @@ export const AiWavesIndicator = React.forwardRef(function AiWavesIndicator(props
 });
 
 export const FoundationAiAssistant = React.forwardRef(function FoundationAiAssistant(props, ref) {
-  const { onChatHeaderMousedown, onSessionCleared, children, ...rest } = props;
+  const { onBudgetRefreshRequested, onChatHeaderMousedown, onSessionCleared, children, ...rest } = props;
   const _innerRef = React.useRef(null);
+  const _onBudgetRefreshRequestedRef = React.useRef(onBudgetRefreshRequested);
+  _onBudgetRefreshRequestedRef.current = onBudgetRefreshRequested;
   const _onChatHeaderMousedownRef = React.useRef(onChatHeaderMousedown);
   _onChatHeaderMousedownRef.current = onChatHeaderMousedown;
   const _onSessionClearedRef = React.useRef(onSessionCleared);
@@ -56,11 +58,14 @@ export const FoundationAiAssistant = React.forwardRef(function FoundationAiAssis
   React.useLayoutEffect(() => {
     const el = _innerRef.current;
     if (!el) return;
+    const _onBudgetRefreshRequestedFn = (e) => _onBudgetRefreshRequestedRef.current?.(e);
+    el.addEventListener('budget-refresh-requested', _onBudgetRefreshRequestedFn);
     const _onChatHeaderMousedownFn = (e) => _onChatHeaderMousedownRef.current?.(e);
     el.addEventListener('chat-header-mousedown', _onChatHeaderMousedownFn);
     const _onSessionClearedFn = (e) => _onSessionClearedRef.current?.(e);
     el.addEventListener('session-cleared', _onSessionClearedFn);
     return () => {
+      el.removeEventListener('budget-refresh-requested', _onBudgetRefreshRequestedFn);
       el.removeEventListener('chat-header-mousedown', _onChatHeaderMousedownFn);
       el.removeEventListener('session-cleared', _onSessionClearedFn);
     };
@@ -122,12 +127,12 @@ export const AiChatInteractionWrapper = React.forwardRef(function AiChatInteract
   return React.createElement(customElements.getName(AiChatInteractionWrapperWC) ?? 'ai-chat-interaction-wrapper', { ...rest, ref: _mergeRefs(_innerRef, ref) }, children);
 });
 
-export const FoundationAiPopoutManager = React.forwardRef(function FoundationAiPopoutManager(props, ref) {
+export const AiChatMarkdown = React.forwardRef(function AiChatMarkdown(props, ref) {
   const { children, ...rest } = props;
-  return React.createElement(customElements.getName(FoundationAiPopoutManagerWC) ?? 'foundation-ai-popout-manager', { ...rest, ref }, children);
+  return React.createElement(customElements.getName(AiChatMarkdownWC) ?? 'ai-chat-markdown', { ...rest, ref }, children);
 });
 
-export const AiChatMarkdown = React.forwardRef(function AiChatMarkdown(props, ref) {
+export const FoundationAiPopoutManager = React.forwardRef(function FoundationAiPopoutManager(props, ref) {
   const { children, ...rest } = props;
-  return React.createElement(customElements.getName(AiChatMarkdownWC) ?? 'ai-chat-markdown', { ...rest, ref }, children);
+  return React.createElement(customElements.getName(FoundationAiPopoutManagerWC) ?? 'foundation-ai-popout-manager', { ...rest, ref }, children);
 });