@genesislcap/ai-assistant 15.11.0 → 15.12.0

package/dist/esm/components/chat-driver/chat-driver.js

@@ -584,6 +584,7 @@ export class ChatDriver extends EventTarget {
         this.activeTemperatureInput = config.temperature;
         this.activeToolChoiceInput = config.toolChoice;
         this.activeCachePolicyInput = config.cachePolicy;
+        this.activeThinkingPolicyInput = config.thinkingPolicy;
         this.activeTailContextInput = config.tailContext;
         this.activeResponseSchemaInput = config.responseSchema;
         this.activeFallbacks = config.fallbacks;
@@ -1403,15 +1404,29 @@ export class ChatDriver extends EventTarget {
      *   `condenseWhen` can register against the right call (it stamps the clocks
      *   straight off the driver). Absent for dispatch paths with no addressable tool
      *   call (e.g. the fold-close handler), where `condenseWhen` is a no-op.
-     * @param traceCapture - Optional per-invocation slot. When provided, the trace
-     *   from any sub-agent call is written here rather than to shared instance state,
-     *   so parallel tool calls each capture their own trace independently.
+     * @param traceCapture - Optional per-tool-call accumulator. When provided, every
+     *   sub-agent call's trace is **appended** here rather than written to shared
+     *   instance state, so parallel tool calls each capture their own traces
+     *   independently.
+     *
+     *   Deliberately a list of traces, not one slot. A single handler may call
+     *   `requestSubAgent` more than once — a code-driven scheduler dispatching a
+     *   dependency graph, a retry of a timed-out child, any fan-out helper — and a
+     *   single slot kept only the last, so every other child ran, was billed by the
+     *   provider, and then vanished from history. The loss was silent in the worst
+     *   way: `sumUsage` and `usageRows` both recurse into the trace, so they summed a
+     *   truncated input and still agreed with each other. Measured at 1 of 7 traces
+     *   kept on a seven-way fan-out, reporting ~2.3x under the real cost, with the
+     *   error growing as the fan-out widens.
      */
     buildHandlerContext(activeToolCallId, traceCapture) {
         return Object.assign(Object.assign({ requestInteraction: (componentName, data, options) => this.requestInteraction(componentName, data, options) }, (this.subAgentsMap.size > 0 && {
             requestSubAgent: (name, options) => this.invokeSubAgent(name, options).then(({ outcome, trace }) => {
-                if (traceCapture)
-                    traceCapture.trace = trace;
+                // Append, never assign: see `traceCapture` on `buildHandlerContext`. Order
+                // is completion order, which is fine — every message carries its own
+                // timestamp and the timeline sorts on that.
+                if (traceCapture && trace)
+                    traceCapture.traces.push(trace);
                 return outcome;
             }),
         })), { completeSubAgent: (result) => {
@@ -1908,6 +1923,18 @@ export class ChatDriver extends EventTarget {
             // `iterations` because fold operations decrement iterations, which would incorrectly
             // re-trigger the slice on subsequent calls after a fold open/close.
             let firstLlmCall = !!currentInput;
+            // Thinking posture for this WHOLE turn, resolved on the first model call and then held.
+            //
+            // Unlike temperature or toolChoice, this one cannot vary per iteration: a tool-use loop is
+            // a single assistant turn, and Anthropic requires one thinking mode for its duration.
+            // Toggling mid-loop does not error — the API silently disables thinking for that request
+            // and strips blocks that would leave the turn structure invalid, so an `'auto' -> 'off'`
+            // switch loses the reasoning continuity the opening call established while an
+            // `'off' -> 'auto'` switch simply does not deliver the reasoning asked for. It also
+            // invalidates the prompt cache, which costs more than the reasoning it was meant to save.
+            // Resolved per USER turn instead, which is where the docs say to choose it.
+            let pinnedThinkingPolicy;
+            let thinkingPolicyPinned = false;
             while (iterations < this.maxToolIterations) {
                 iterations += 1;
                 // Monotonic across the driver's life — the age clock. Unlike `iterations`,
@@ -2071,7 +2098,7 @@ export class ChatDriver extends EventTarget {
                 // provider is resolved — static value or a function of the turn context
                 // (which carries the live state for stateful agents). Resolved before the
                 // snapshot so the debug log records the exact request config the model saw.
-                const [resolvedTemperature, resolvedToolChoice, resolvedCachePolicy, resolvedTailContext, resolvedResponseSchema,] = 
+                const [resolvedTemperature, resolvedToolChoice, resolvedCachePolicy, resolvedTailContext, resolvedResponseSchema, firstResolvedThinkingPolicy,] = 
                 // oxlint-disable-next-line no-await-in-loop
                 yield Promise.all([
                     this.resolveTurnInput(this.activeTemperatureInput, promptCtx),
@@ -2079,7 +2106,16 @@ export class ChatDriver extends EventTarget {
                     this.resolveTurnInput(this.activeCachePolicyInput, promptCtx),
                     this.resolveTurnInput(this.activeTailContextInput, promptCtx),
                     this.resolveTurnInput(this.activeResponseSchemaInput, promptCtx),
+                    // Only consulted on the first iteration (see `pinnedThinkingPolicy`); resolved
+                    // alongside the others so a resolver still sees the same turn context.
+                    thinkingPolicyPinned
+                        ? Promise.resolve(undefined)
+                        : this.resolveTurnInput(this.activeThinkingPolicyInput, promptCtx),
                 ]);
+                if (!thinkingPolicyPinned) {
+                    pinnedThinkingPolicy = firstResolvedThinkingPolicy;
+                    thinkingPolicyPinned = true;
+                }
                 // The system prompt is always just the agent's resolved prompt — byte-stable, so it can be
                 // cached. The framework's volatile additions (fold suffix, retry nudge) and the agent's tail
                 // context all go to the framed tail: one uniform channel, no cache-scope branch. On a normal
@@ -2124,6 +2160,12 @@ export class ChatDriver extends EventTarget {
                     // Prompt-cache policy for this turn (Anthropic places breakpoints per scope; Gemini
                     // caches implicitly regardless). Undefined → no caching requested.
                     cachePolicy: resolvedCachePolicy,
+                    // Extended-thinking posture, pinned for the whole tool loop (one assistant turn) rather
+                    // than re-resolved per iteration — see `pinnedThinkingPolicy`. Undefined — unset, or the
+                    // resolver's answer for this turn — is NOT "off": it leaves the model on its own default,
+                    // so agents that never set this are priced exactly as before. Transports clamp models
+                    // that can't honour it.
+                    thinkingPolicy: pinnedThinkingPolicy,
                     // Framed volatile context injected at the message tail (never stored). Undefined → none.
                     tailContext,
                     // Structured-output schema for this turn (agent/state-resolved). When set, the transport
@@ -2303,8 +2345,15 @@ export class ChatDriver extends EventTarget {
                 // leaves the key off entirely rather than carrying it as `undefined`.
                 // JSON.stringify already drops undefined from the exported log, so this is
                 // chiefly about keeping the in-memory message shape honest.
-                if (this.lastResolvedModel !== undefined)
+                // Fill, never overwrite — but still only when there is something to fill with.
+                // A transport that already stamped a model knows something the driver does not:
+                // `lastResolvedModel` is the model we ASKED for, so overwriting would relabel a
+                // fallback-served turn as the requested model and misattribute its spend.
+                // Written as a guard rather than `??=` because `??=` ASSIGNS undefined, which
+                // would create the key and break the omit-when-unresolved contract above.
+                if (response.model === undefined && this.lastResolvedModel !== undefined) {
                     response.model = this.lastResolvedModel;
+                }
                 if (this.lastResolvedProvider !== undefined)
                     response.provider = this.lastResolvedProvider;
                 if (this.lastResolvedProviderName !== undefined) {
@@ -2517,15 +2566,26 @@ export class ChatDriver extends EventTarget {
                             }
                             return;
                         }
-                        // Real tool execution
+                        // Real tool execution.
+                        //
+                        // The accumulator is declared OUTSIDE the try so the catch can attach it
+                        // too: a handler that ran sub-agents and then threw (post-processing their
+                        // results failed, say) has already spent real money on children that
+                        // completed. Losing their traces on the error path would under-report the
+                        // run exactly as the single-slot bug did — and just as silently, since
+                        // `sumUsage` and `usageRows` would still agree with each other.
+                        const traceCapture = { traces: [] };
+                        const capturedTrace = () => traceCapture.traces.length ? traceCapture.traces.flat() : undefined;
                         try {
-                            const traceCapture = {};
                             const result = yield handler(tc.args, this.buildHandlerContext(tc.id, traceCapture));
                             const content = typeof result === 'string' ? result : JSON.stringify(result);
                             executedById.set(tc.id, {
                                 toolCallId: tc.id,
                                 content,
-                                subAgentTrace: traceCapture.trace,
+                                // Concatenated when a handler invoked several children, so none is lost.
+                                // Stays `undefined` when nothing was captured — readers key off presence,
+                                // and an empty array is a different claim from "no sub-agent ran".
+                                subAgentTrace: capturedTrace(),
                             });
                             anyRealToolExecuted = true;
                         }
@@ -2541,6 +2601,9 @@ export class ChatDriver extends EventTarget {
                                 // Structured recovery hint so the model retries or routes around a tool
                                 // failure instead of apologising and giving up.
                                 content: `Tool error: ${e.message}\nRECOVERY: this tool failed once — you may retry it, or take a different valid action to make progress. Do NOT abandon the task, ask the user to rephrase, or claim you cannot make changes. If a planning tool failed, retry it or proceed with the information you already have.`,
+                                // Children that completed before the throw were still billed — keep
+                                // their traces so the run's cost stays whole.
+                                subAgentTrace: capturedTrace(),
                             });
                             anyRealToolExecuted = true; // treat errors as real work for fold op counting
                         }

package/dist/esm/components/chat-driver/chat-driver.thinking-policy.test.js

@@ -0,0 +1,137 @@
+import { __awaiter } from "tslib";
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+// Side-effect import — MUST come before `./chat-driver` so the driver subclasses
+// jsdom's EventTarget rather than Node's native one. Mirrors chat-driver.test.ts.
+import './align-event-globals';
+import { ChatDriver } from './chat-driver';
+// ---------------------------------------------------------------------------
+// Per-turn `thinkingPolicy` resolution.
+//
+// The cost case for this option is the SHAPE of a tool loop, not a single call: the
+// opening turn is a real decision and worth reasoning over, while the iterations that
+// follow mostly pick the next tool from a narrow set — and on a thinking model each of
+// those bills reasoning at the full output rate. That saving only exists if the
+// resolver runs per iteration, so these tests assert the sequence across a loop, not
+// just that one value arrives.
+//
+// The other half is the undefined case. Every agent written before this option leaves
+// it unset, and a resolver may answer `undefined` on any given turn; both must reach
+// the transport as `undefined` so the model keeps its own default. `undefined` reaching
+// the wire as `'off'` would be a silent capability regression, and as `'auto'` a silent
+// bill increase — so it is asserted explicitly rather than assumed.
+// ---------------------------------------------------------------------------
+/** Captures the policy seen on each model call; calls one tool, then finishes. */
+const capturingProvider = () => {
+    const seen = [];
+    let turns = 0;
+    return {
+        seen,
+        chat: (_history, _userMessage, options) => __awaiter(void 0, void 0, void 0, function* () {
+            seen.push(options === null || options === void 0 ? void 0 : options.thinkingPolicy);
+            turns += 1;
+            // Two tool calls, so the loop runs three model calls in total — enough for a
+            // per-turn resolver to say something different on the later ones.
+            if (turns <= 2) {
+                return {
+                    role: 'assistant',
+                    content: '',
+                    toolCalls: [{ id: `t${turns}`, name: 'step', args: {} }],
+                };
+            }
+            return { role: 'assistant', content: 'done' };
+        }),
+    };
+};
+const makeRegistry = (provider) => ({
+    get: () => provider,
+    default: () => provider,
+    defaultName: () => 'test',
+    names: () => ['test'],
+    getStatus: () => __awaiter(void 0, void 0, void 0, function* () { return null; }),
+    listStatuses: () => __awaiter(void 0, void 0, void 0, function* () { return []; }),
+});
+const agent = (overrides) => (Object.assign({ name: 'worker', description: 'test agent', toolDefinitions: [
+        { name: 'step', description: 'step', parameters: { type: 'object', properties: {} } },
+    ], toolHandlers: { step: () => __awaiter(void 0, void 0, void 0, function* () { return 'stepped'; }) } }, overrides));
+/** Run one user turn through a driver carrying `config`, and return the policies seen. */
+const policiesFor = (config) => __awaiter(void 0, void 0, void 0, function* () {
+    const provider = capturingProvider();
+    const driver = new ChatDriver(makeRegistry(provider), {
+        maxToolIterations: 10,
+        maxFoldOperations: 5,
+        sessionKey: '',
+    });
+    driver.applyAgent(agent(config));
+    yield driver.sendMessage('go');
+    return provider.seen;
+});
+const suite = createLogicSuite('ChatDriver thinkingPolicy');
+suite('leaves the policy undefined when the agent does not set one', () => __awaiter(void 0, void 0, void 0, function* () {
+    // The compatibility case: every existing agent. Undefined must reach the transport
+    // as undefined so each model keeps its own default posture — not silently coerced
+    // to 'off' (a capability regression) or 'auto' (a bill increase).
+    const seen = yield policiesFor({});
+    assert.ok(seen.length >= 3, `expected a multi-call loop, got ${seen.length}`);
+    assert.equal(seen.filter((p) => p !== undefined), [], 'no turn invents a policy');
+}));
+suite('applies a static policy to every turn of the loop', () => __awaiter(void 0, void 0, void 0, function* () {
+    const seen = yield policiesFor({ thinkingPolicy: 'off' });
+    assert.ok(seen.length >= 3);
+    assert.equal([...new Set(seen)], ['off'], 'a static value is not just a first-turn setting');
+}));
+suite('pins the resolved policy for the whole tool loop', () => __awaiter(void 0, void 0, void 0, function* () {
+    // A tool-use loop is ONE assistant turn and Anthropic requires a single thinking mode
+    // for its duration. Toggling part-way does not error — the API silently disables
+    // thinking for that request and strips blocks that would leave the turn structure
+    // invalid, so an 'auto' -> 'off' switch loses the continuity the opening call
+    // established and 'off' -> 'auto' never delivers the reasoning asked for. It also
+    // invalidates the prompt cache, costing more than the reasoning it meant to save.
+    //
+    // So a resolver that changes its mind mid-loop must NOT be honoured mid-loop. This
+    // asserts the opposite of what it looks like it should: the later values are ignored.
+    let call = 0;
+    const seen = yield policiesFor({
+        thinkingPolicy: () => {
+            call += 1;
+            return call === 1 ? 'auto' : 'off';
+        },
+    });
+    assert.ok(seen.length >= 3, `expected a multi-call loop, got ${seen.length}`);
+    assert.equal([...new Set(seen)], ['auto'], 'the first call decides; later resolutions do not take effect until the next user turn');
+}));
+suite('re-resolves on the next user turn', () => __awaiter(void 0, void 0, void 0, function* () {
+    // The flip side: pinning is per turn, not for the driver's lifetime, so a state change
+    // between turns still lands.
+    const provider = capturingProvider();
+    const driver = new ChatDriver(makeRegistry(provider), {
+        maxToolIterations: 10,
+        maxFoldOperations: 5,
+        sessionKey: '',
+    });
+    let turn = 0;
+    driver.applyAgent(agent({
+        thinkingPolicy: () => (turn === 0 ? 'auto' : 'off'),
+    }));
+    yield driver.sendMessage('go');
+    const firstTurn = [...provider.seen];
+    turn = 1;
+    yield driver.sendMessage('again');
+    const secondTurn = provider.seen.slice(firstTurn.length);
+    assert.equal([...new Set(firstTurn)], ['auto'], 'turn one holds its posture');
+    assert.equal([...new Set(secondTurn)], ['off'], 'turn two picks up the new one');
+}));
+suite('passes undefined through when the resolver declines to choose', () => __awaiter(void 0, void 0, void 0, function* () {
+    // A resolver may answer on some turns and not others. `undefined` is its third answer —
+    // "leave this model alone" — and must not be normalised into a value. Asserted across
+    // the whole loop because the first call's answer is the one that gets pinned.
+    const seen = yield policiesFor({ thinkingPolicy: () => undefined });
+    assert.ok(seen.length >= 3);
+    assert.equal(seen.filter((p) => p !== undefined), [], 'declining is not the same as choosing');
+}));
+suite('awaits an async resolver', () => __awaiter(void 0, void 0, void 0, function* () {
+    const seen = yield policiesFor({
+        thinkingPolicy: () => __awaiter(void 0, void 0, void 0, function* () { return 'off'; }),
+    });
+    assert.equal([...new Set(seen)], ['off'], 'a promise is resolved, not passed through');
+}));
+suite.run();

package/dist/esm/components/chat-driver/chat-driver.trace-capture.test.js

@@ -0,0 +1,200 @@
+import { __awaiter } from "tslib";
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import { sumUsage } from '../../utils/sum-usage';
+import { usageRows } from '../../utils/usage-rows';
+// Side-effect import — MUST come before `./chat-driver` so the driver subclasses
+// jsdom's EventTarget rather than Node's native one. Mirrors chat-driver.test.ts.
+import './align-event-globals';
+import { ChatDriver } from './chat-driver';
+// ---------------------------------------------------------------------------
+// Sub-agent trace capture when ONE tool call invokes SEVERAL sub-agents.
+//
+// The capture slot used to be a single `{ trace?: ChatMessage[] }` per tool call,
+// assigned by each `requestSubAgent`. That covers N tool calls × 1 sub-agent — the
+// case its docblock named — but not 1 tool call × N sub-agents, which is what a
+// code-driven scheduler or a retry produces. All but the last trace was dropped, so
+// those children ran, were billed, and then had no record in history.
+//
+// The failure was invisible to every existing check: `sumUsage` and `usageRows` both
+// recurse into `subAgentTrace`, so they summed a truncated input and still reconciled
+// with each other perfectly. Measured at 1 of 7 traces kept on a seven-way fan-out,
+// ~2.3x under the true cost.
+//
+// These tests assert the traces SURVIVE, which is upstream of any cost assertion.
+// ---------------------------------------------------------------------------
+/** Answers by rule: concurrent children under one turn make a FIFO queue nondeterministic. */
+const ruleProvider = () => {
+    let parentTurns = 0;
+    return {
+        chat: (_history, _userMessage, options) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            const tools = ((_a = options === null || options === void 0 ? void 0 : options.tools) !== null && _a !== void 0 ? _a : []).map((t) => t.name);
+            // Child turn: finishes via its completion tool, and reports usage so the
+            // reconciliation assertions have something to add up.
+            if (tools.includes('work')) {
+                return {
+                    role: 'assistant',
+                    content: '',
+                    model: 'claude-sonnet-5',
+                    cost: 0.01,
+                    inputTokens: 100,
+                    outputTokens: 20,
+                    toolCalls: [{ id: 'w1', name: 'work', args: {} }],
+                };
+            }
+            if (tools.includes('delegate') && parentTurns === 0) {
+                parentTurns += 1;
+                return {
+                    role: 'assistant',
+                    content: '',
+                    model: 'claude-sonnet-5',
+                    cost: 0.02,
+                    inputTokens: 200,
+                    outputTokens: 30,
+                    toolCalls: [{ id: 'd0', name: 'delegate', args: {} }],
+                };
+            }
+            return { role: 'assistant', content: 'done', model: 'claude-sonnet-5' };
+        }),
+    };
+};
+const makeRegistry = (provider) => ({
+    get: () => provider,
+    default: () => provider,
+    defaultName: () => 'test',
+    names: () => ['test'],
+    getStatus: () => __awaiter(void 0, void 0, void 0, function* () { return null; }),
+    listStatuses: () => __awaiter(void 0, void 0, void 0, function* () { return []; }),
+});
+const agent = (overrides) => (Object.assign({ description: 'test agent' }, overrides));
+/** A child that reports one unit of usage and completes. */
+const worker = (name) => agent({
+    name,
+    toolDefinitions: [
+        { name: 'work', description: 'work', parameters: { type: 'object', properties: {} } },
+    ],
+    toolHandlers: {
+        work: (_args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            (_a = ctx.completeSubAgent) === null || _a === void 0 ? void 0 : _a.call(ctx, { ok: true });
+            return 'worked';
+        }),
+    },
+});
+/**
+ * A parent whose single `delegate` tool call invokes `names` in turn — the shape a
+ * code-driven scheduler produces, and the one the old single slot truncated.
+ */
+const boss = (children, invoke) => agent({
+    name: 'boss',
+    subAgents: children,
+    toolDefinitions: [
+        { name: 'delegate', description: 'delegate', parameters: { type: 'object', properties: {} } },
+    ],
+    toolHandlers: {
+        delegate: (_args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+            yield Promise.all(invoke.map((n) => ctx.requestSubAgent(n, { task: 'go' })));
+            return 'delegated';
+        }),
+    },
+});
+const run = (config) => __awaiter(void 0, void 0, void 0, function* () {
+    const driver = new ChatDriver(makeRegistry(ruleProvider()), {
+        maxToolIterations: 20,
+        maxFoldOperations: 5,
+        sessionKey: '',
+    });
+    driver.applyAgent(config);
+    yield driver.sendMessage('go');
+    return driver.getHistory();
+});
+const tracesIn = (history) => history.flatMap((m) => { var _a; return ((_a = m.toolCalls) !== null && _a !== void 0 ? _a : []).flatMap((tc) => (tc.subAgentTrace ? [tc.subAgentTrace] : [])); });
+const suite = createLogicSuite('ChatDriver sub-agent trace capture');
+// ---------------------------------------------------------------------------
+suite('keeps every trace when one tool call invokes three sub-agents', () => __awaiter(void 0, void 0, void 0, function* () {
+    const names = ['gen_a', 'gen_b', 'gen_c'];
+    const history = yield run(boss(names.map(worker), names));
+    const traces = tracesIn(history);
+    assert.is(traces.length, 1, 'one tool call, so one concatenated trace');
+    // Each child contributes at least its own assistant turn. Before the fix this was
+    // one child's worth regardless of how many ran.
+    const seen = new Set(traces[0].map((m) => m.agentName).filter(Boolean));
+    assert.equal([...seen].sort(), names, `every invoked child must appear — got ${JSON.stringify([...seen])}`);
+}));
+suite('prices every child — usageRows emits a row per child and reconciles', () => __awaiter(void 0, void 0, void 0, function* () {
+    // The reconciliation test extended to a fan-out. The single-child version passed
+    // before the fix AND after it, which is exactly why it did not catch this.
+    const names = ['gen_a', 'gen_b', 'gen_c'];
+    const history = yield run(boss(names.map(worker), names));
+    const rows = usageRows(history);
+    const childRows = rows.filter((r) => r.subAgentDepth === 1);
+    assert.is(childRows.length, names.length, 'one row per child that ran');
+    const rowTotal = 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(rowTotal - sumUsage(history).costUsd) < 1e-12, `rows ${rowTotal} vs sumUsage ${sumUsage(history).costUsd}`);
+    // Parent turn ($0.02) + three children ($0.01 each). Asserted as a number so a
+    // regression that silently drops a child fails here rather than only in the
+    // reconciliation above, which would still agree with a truncated input.
+    assert.ok(Math.abs(rowTotal - 0.05) < 1e-12, `expected 0.05, got ${rowTotal}`);
+}));
+suite('keeps both traces when the same sub-agent is invoked twice (a retry)', () => __awaiter(void 0, void 0, void 0, function* () {
+    // The retry shape: one handler, one child name, two invocations. Under the old slot
+    // the first attempt's trace was overwritten by the second.
+    const history = yield run(boss([worker('gen_a')], ['gen_a', 'gen_a']));
+    const traces = tracesIn(history);
+    assert.is(traces.length, 1);
+    const childTurns = traces[0].filter((m) => m.agentName === 'gen_a' && m.cost != null);
+    assert.is(childTurns.length, 2, 'both attempts survive, not just the last');
+    const rows = usageRows(history).filter((r) => r.subAgentDepth === 1);
+    assert.is(rows.length, 2, 'and both are priced');
+}));
+suite('keeps child traces when the parent handler throws after they ran', () => __awaiter(void 0, void 0, void 0, function* () {
+    // Children that completed were billed by the provider. If the error path drops
+    // their traces, the run under-reports exactly as the single-slot bug did — and
+    // just as silently, since `sumUsage` and `usageRows` would still agree with each
+    // other over the truncated input. PR review.
+    const names = ['gen_a', 'gen_b'];
+    const parent = agent({
+        name: 'boss',
+        subAgents: names.map(worker),
+        toolDefinitions: [
+            { name: 'delegate', description: 'delegate', parameters: { type: 'object', properties: {} } },
+        ],
+        toolHandlers: {
+            delegate: (_args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+                yield Promise.all(names.map((n) => ctx.requestSubAgent(n, { task: 'go' })));
+                throw new Error('post-processing the children failed');
+            }),
+        },
+    });
+    const history = yield run(parent);
+    const traces = tracesIn(history);
+    assert.is(traces.length, 1, 'the failed tool call still carries its trace');
+    const seen = [...new Set(traces[0].map((m) => m.agentName).filter(Boolean))].sort();
+    assert.equal(seen, names, 'both children survive the throw');
+    const childRows = usageRows(history).filter((r) => r.subAgentDepth === 1);
+    assert.is(childRows.length, 2, 'and both are still priced');
+}));
+suite('leaves subAgentTrace undefined when no sub-agent ran', () => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    // Presence is the signal readers key off (`usage-rows.ts`, the UI's `when(...)`),
+    // so an empty array would be a different and wrong claim.
+    const history = yield run(agent({
+        name: 'boss',
+        subAgents: [worker('gen_a')],
+        toolDefinitions: [
+            {
+                name: 'delegate',
+                description: 'delegate',
+                parameters: { type: 'object', properties: {} },
+            },
+        ],
+        toolHandlers: { delegate: () => __awaiter(void 0, void 0, void 0, function* () { return 'did it myself'; }) },
+    }));
+    for (const m of history) {
+        for (const tc of (_a = m.toolCalls) !== null && _a !== void 0 ? _a : []) {
+            assert.is(tc.subAgentTrace, undefined, 'not an empty array');
+        }
+    }
+    assert.equal(usageRows(history).filter((r) => r.subAgentDepth === 1), [], 'no child rows');
+}));
+suite.run();

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/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();