@genesislcap/ai-assistant 14.452.0 → 14.452.1

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

@@ -18,8 +18,19 @@ const DEFAULT_MAX_FOLD_OPERATIONS = 5;
 // cap reach thousands for full-session capture without the memory blowup.
 const DEFAULT_MAX_TURN_SNAPSHOTS = 400;
 const DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5;
-const MAX_MALFORMED_RETRIES = 2;
+// Stale tools (advertised in an earlier state, retired now) and fold-hidden tools are
+// self-correcting — the model drops them once guided — so they get a higher loop-protection
+// ceiling than hallucinated names: a few legitimate stale calls across state transitions must
+// not prematurely end the turn. Still bounded so a genuinely stuck loop terminates.
+const MAX_STALE_TOOL_CALLS = DEFAULT_MAX_UNKNOWN_TOOL_CALLS * 2;
+// Gemini in particular emits short bursts of MALFORMED_FUNCTION_CALL; allow more CONSECUTIVE
+// retries. These counters reset on any productive response, so this is a consecutive-failure
+// ceiling, not a per-turn total.
+const MAX_MALFORMED_RETRIES = 5;
 const MAX_EMPTY_RESPONSE_RETRIES = 3;
+// Transient throws while building the per-turn tool surface or calling the provider retry the
+// SAME iteration up to this many times before propagating, rather than tearing down the turn.
+const MAX_SETUP_TRANSPORT_RETRIES = 3;
 const SUGGESTIONS_HISTORY_WINDOW = 8;
 /** Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver. */
 export const REQUEST_CONTINUATION_TOOL = 'request_continuation';
@@ -77,6 +88,14 @@ export class ChatDriver extends EventTarget {
         this.recentStaleToolNames = new Set();
         /** Sub-agents declared on the active agent config, keyed by name. */
         this.subAgentsMap = new Map();
+        /**
+         * True when this driver runs as a child sub-agent (created by a parent
+         * driver's `invokeSubAgent`). Sub-agents force tool use every turn so a turn
+         * can only end via their completion tool, and on any non-completion exit they
+         * record a typed `SubAgentFailureReason` instead of appending a
+         * user-facing message — the parent decides how to surface the failure.
+         */
+        this.isSubAgent = false;
         /**
          * Set by `releaseAgent` inside a top-level tool handler — typically a stateful
          * agent's terminal-state handler signalling that its flow is complete and the
@@ -239,6 +258,35 @@ export class ChatDriver extends EventTarget {
     getSubAgentCompletion() {
         return this.subAgentCompletion;
     }
+    /**
+     * Mark this driver as running as a sub-agent. Called by a parent driver's
+     * `invokeSubAgent` immediately after construction, before the first turn.
+     * Enables forced tool use and typed failure reporting (see `isSubAgent`).
+     */
+    markAsSubAgent() {
+        this.isSubAgent = true;
+    }
+    /**
+     * Returns the typed failure recorded when a sub-agent run ended without
+     * `completeSubAgent`, if any. Called by a parent `ChatDriver` after running
+     * this instance as a sub-agent.
+     */
+    getSubAgentFailure() {
+        return this.subAgentFailure;
+    }
+    /**
+     * Record a sub-agent failure reason (first one wins). No-op for top-level
+     * agents, so loop-exit sites can call it unconditionally. The parent reads
+     * this via `getSubAgentFailure()` and emits the `subagent.failed` meta event
+     * under its *own* session — see `invokeSubAgent`. (A child sub-agent runs
+     * under a separate session key, so recording here would orphan the event off
+     * the user-visible debug-log timeline.)
+     */
+    failSubAgent(reason) {
+        if (!this.isSubAgent || this.subAgentFailure)
+            return;
+        this.subAgentFailure = { reason };
+    }
     /**
      * Returns true if `releaseAgent` was called during the most recent turn.
      * Consumed by the orchestrator to trigger the auto-pin release path.
@@ -256,6 +304,47 @@ export class ChatDriver extends EventTarget {
     getTurnSnapshots() {
         return this.turnSnapshots;
     }
+    /**
+     * Merge a sub-agent's turn snapshots into this driver's buffer so they surface
+     * as `kind:'turn'` entries in the exported debug log. The child runs as a
+     * separate, discarded driver, so its snapshots would otherwise be lost. Each is
+     * re-labelled under the parent turn that activated the sub-agent: the child's
+     * own (numeric) turns become `"<parentTurn>-1"`, `"-2"`, … (1-based, in order);
+     * any already-forwarded grand-child labels (strings) have their leading segment
+     * remapped the same way, so nesting composes (`"5-2"` → `"5-2-1"`).
+     *
+     * Note: two sub-agents invoked in the *same* parent turn share the prefix, so
+     * their labels can repeat — `agentName` on each snapshot disambiguates them.
+     */
+    forwardSubAgentSnapshots(childSnapshots) {
+        var _a;
+        if (childSnapshots.length === 0)
+            return;
+        // The activating parent turn = the most recent snapshot this driver recorded
+        // before entering the tool handler that invoked the sub-agent.
+        const parentTurn = Math.max(0, this.globalTurnIndex - 1);
+        const ownTurnLabel = new Map();
+        let ownPos = 0;
+        for (const snap of childSnapshots) {
+            let turnIndex;
+            if (!snap.turnIndex.includes('-')) {
+                // The child's own turn (a bare counter) → number it under the parent turn.
+                ownPos += 1;
+                turnIndex = `${parentTurn}-${ownPos}`;
+                ownTurnLabel.set(snap.turnIndex, turnIndex);
+            }
+            else {
+                // An already-forwarded grand-child label — remap its leading segment.
+                const [lead, ...rest] = snap.turnIndex.split('-');
+                const leadLabel = (_a = ownTurnLabel.get(lead)) !== null && _a !== void 0 ? _a : `${parentTurn}-${lead}`;
+                turnIndex = [leadLabel, ...rest].join('-');
+            }
+            this.turnSnapshots.push(Object.assign(Object.assign({}, snap), { turnIndex }));
+        }
+        while (this.turnSnapshots.length > this.maxTurnSnapshots) {
+            this.turnSnapshots.shift();
+        }
+    }
     /**
      * Push one snapshot to the ring buffer. Called inside `runToolLoop` just
      * before each LLM call — that's the latest point where the prompt, tool
@@ -274,7 +363,7 @@ export class ChatDriver extends EventTarget {
                 agentSnapshot = `<getDebugSnapshot threw: ${e instanceof Error ? e.message : String(e)}>`;
             }
         }
-        const turnIndex = this.globalTurnIndex;
+        const turnIndex = String(this.globalTurnIndex);
         this.globalTurnIndex += 1;
         this.turnSnapshots.push({
             turnIndex,
@@ -514,6 +603,7 @@ export class ChatDriver extends EventTarget {
                 return { reason: 'done' };
             this.busy = true;
             this.subAgentCompletion = undefined;
+            this.subAgentFailure = undefined;
             this.agentReleaseRequested = false;
             this.appendToHistory({ role: 'user', content: userInput, attachments });
             this.turnStartedAt = Date.now();
@@ -562,10 +652,10 @@ export class ChatDriver extends EventTarget {
      */
     buildHandlerContext(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(({ result, trace }) => {
+            requestSubAgent: (name, options) => this.invokeSubAgent(name, options).then(({ outcome, trace }) => {
                 if (traceCapture)
                     traceCapture.trace = trace;
-                return result;
+                return outcome;
             }),
         })), { completeSubAgent: (result) => {
                 var _a;
@@ -591,7 +681,7 @@ export class ChatDriver extends EventTarget {
      */
     invokeSubAgent(name, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             const subConfig = this.subAgentsMap.get(name);
             if (!subConfig) {
                 const available = [...this.subAgentsMap.keys()].join(', ') || '(none)';
@@ -615,6 +705,9 @@ export class ChatDriver extends EventTarget {
                 ...((_b = subConfig.primerHistory) !== null && _b !== void 0 ? _b : []),
             ];
             const child = new ChatDriver(this.providerRegistry);
+            // Mark before the first turn so the child forces tool use and reports a
+            // typed failure (rather than user-facing text) if it never completes.
+            child.markAsSubAgent();
             child.applyAgent(Object.assign(Object.assign({}, subConfig), { primerHistory: effectivePrimer }));
             // Route interactions back through this driver so widgets render in the
             // parent's (ultimately the root's) history and resolve via the same
@@ -650,14 +743,28 @@ export class ChatDriver extends EventTarget {
                 this.dispatchEvent(new CustomEvent('sub-agent-stop', { detail: lifecycleDetail }));
             }
             const trace = child.getHistory();
+            // Forward the child's per-LLM-call snapshots onto this (parent) driver's
+            // buffer so they show as `kind:'turn'` entries in the exported debug log,
+            // re-numbered under the activating parent turn. Runs for both success and
+            // failure so the sub-agent's turns are always visible.
+            this.forwardSubAgentSnapshots(child.getTurnSnapshots());
             const completion = child.getSubAgentCompletion();
             if (completion) {
-                return { result: completion.result, trace };
+                return { outcome: { ok: true, result: completion.result }, trace };
             }
-            const finalMsg = [...trace]
-                .reverse()
-                .find((m) => { var _a, _b; return m.role === 'assistant' && !((_a = m.toolCalls) === null || _a === void 0 ? void 0 : _a.length) && ((_b = m.content) === null || _b === void 0 ? void 0 : _b.trim()); });
-            return { result: ((_c = finalMsg === null || finalMsg === void 0 ? void 0 : finalMsg.content) !== null && _c !== void 0 ? _c : ''), trace };
+            // No completion → the sub-agent's loop ended without calling its completion
+            // tool. Surface the typed reason it recorded; default to 'max_iterations'
+            // for the defensive case where the loop ended with no reason set (e.g. a
+            // provider ignored forced tool use and returned text). The previous
+            // final-text fallback is intentionally gone — sub-agents return a
+            // structured outcome only, and the parent handler decides how to recover.
+            const reason = (_d = (_c = child.getSubAgentFailure()) === null || _c === void 0 ? void 0 : _c.reason) !== null && _d !== void 0 ? _d : 'max_iterations';
+            // Record under THIS (parent) driver's session so the failure lands on the
+            // user-visible debug-log timeline — the child ran under its own session key.
+            // This is also the only telemetry for the defensive default above, where the
+            // child's loop ended without recording an explicit failure reason.
+            recordMetaEvent(this.sessionKey, 'subagent.failed', { agent: name, reason });
+            return { outcome: { ok: false, reason }, trace };
         });
     }
     /**
@@ -670,6 +777,7 @@ export class ChatDriver extends EventTarget {
                 return { reason: 'done' };
             this.busy = true;
             this.subAgentCompletion = undefined;
+            this.subAgentFailure = undefined;
             this.turnStartedAt = Date.now();
             recordMetaEvent(this.sessionKey, 'turn.start', {
                 phase: 'continueFromHistory',
@@ -864,6 +972,10 @@ export class ChatDriver extends EventTarget {
             let iterations = 0;
             let malformedAttempts = 0;
             let emptyResponseAttempts = 0;
+            // Bounded retries for transient throws while resolving the per-turn tool surface or
+            // calling the provider. Without this, a single transient throw tears down the whole turn
+            // and strands the agent's unflushed work behind an opaque error.
+            let setupTransportAttempts = 0;
             // True only for the very first LLM call. Used to exclude the pending user message
             // from history (it is passed separately as currentInput). Must not be derived from
             // `iterations` because fold operations decrement iterations, which would incorrectly
@@ -883,17 +995,30 @@ export class ChatDriver extends EventTarget {
                 // forbidden when a factory is set, so the array form is always valid.
                 // Sequential await is required — each iteration must see fresh values
                 // before constructing the LLM request.
-                if (this.toolDefinitionsFactory) {
-                    // oxlint-disable-next-line no-await-in-loop
-                    this.toolDefinitions = yield this.toolDefinitionsFactory(promptCtx);
+                // A transient throw while building the tool surface should retry the iteration, not
+                // tear down the whole turn and strand the agent's unflushed buffer behind an opaque
+                // error. The handler-map factory re-resolves in lockstep so dispatch sees only the
+                // handlers valid for the current state, in step with the tool definitions exposed
+                // above. Folds are forbidden when either factory is set, so the fold-mutation paths
+                // on `this.toolDefinitions` / `this.toolHandlers` are unreachable.
+                try {
+                    if (this.toolDefinitionsFactory) {
+                        // oxlint-disable-next-line no-await-in-loop
+                        this.toolDefinitions = yield this.toolDefinitionsFactory(promptCtx);
+                    }
+                    if (this.toolHandlersFactory) {
+                        // oxlint-disable-next-line no-await-in-loop
+                        this.toolHandlers = yield this.toolHandlersFactory(promptCtx);
+                    }
                 }
-                // Same story for the handler-map factory: re-resolve so dispatch sees
-                // only the handlers valid for the current state, in lockstep with the
-                // tool definitions exposed above. Folds are forbidden when this is set,
-                // so the fold-mutation paths on `this.toolHandlers` are unreachable.
-                if (this.toolHandlersFactory) {
-                    // oxlint-disable-next-line no-await-in-loop
-                    this.toolHandlers = yield this.toolHandlersFactory(promptCtx);
+                catch (e) {
+                    setupTransportAttempts += 1;
+                    if (setupTransportAttempts < MAX_SETUP_TRANSPORT_RETRIES) {
+                        logger.warn(`ChatDriver: tool-surface resolution failed, retrying (${setupTransportAttempts}/${MAX_SETUP_TRANSPORT_RETRIES})`);
+                        iterations -= 1;
+                        continue;
+                    }
+                    throw e;
                 }
                 // Record everything advertised this turn so the unknown-tool path can tell
                 // a stale tool (real earlier, retired now) from a hallucinated one. Runs
@@ -945,6 +1070,11 @@ export class ChatDriver extends EventTarget {
                     // Strip fold-only properties (foldEvent, foldPath) before sending to provider
                     tools: this.toolDefinitions.length ? this.toolDefinitions : undefined,
                     attachments: attachmentsForCall,
+                    // Sub-agents must finish by calling a tool (their completion tool), never
+                    // by emitting a free-text turn — force tool use so the provider can't
+                    // return a bare text answer. Top-level agents stay on the default 'auto'.
+                    // (Transports no-op the force when no tools are advertised.)
+                    toolChoice: this.isSubAgent ? 'required' : undefined,
                 };
                 // Resolve the active provider for this turn. Static names were validated
                 // in `applyAgent`; function-form names are validated on first resolution
@@ -977,13 +1107,29 @@ export class ChatDriver extends EventTarget {
                             provider: this.lastResolvedProviderName,
                             attempts: malformedAttempts,
                             finishMessage: e.finishMessage,
+                            isSubAgent: this.isSubAgent,
                         });
-                        this.appendToHistory({
-                            role: 'assistant',
-                            content: 'While working on your request, I repeatedly called my tools incorrectly. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
-                        });
+                        if (this.isSubAgent) {
+                            // Bubble a typed failure to the parent instead of speaking to the user.
+                            this.failSubAgent('malformed_tool_call');
+                        }
+                        else {
+                            this.appendToHistory({
+                                role: 'assistant',
+                                content: 'While working on your request, I repeatedly called my tools incorrectly. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
+                            });
+                        }
                         return { reason: 'done' };
                     }
+                    // A transient provider/transport error should retry the SAME iteration a bounded
+                    // number of times rather than tearing down the whole turn (which strands the
+                    // agent's unflushed buffer behind an opaque error message).
+                    setupTransportAttempts += 1;
+                    if (setupTransportAttempts < MAX_SETUP_TRANSPORT_RETRIES) {
+                        logger.warn(`ChatDriver: provider/transport error, retrying (${setupTransportAttempts}/${MAX_SETUP_TRANSPORT_RETRIES})`);
+                        iterations -= 1;
+                        continue;
+                    }
                     throw e;
                 }
                 const isThinkingStep = response.content && ((_c = response.toolCalls) === null || _c === void 0 ? void 0 : _c.length);
@@ -1006,11 +1152,17 @@ export class ChatDriver extends EventTarget {
                         agent: this.activeAgentName,
                         provider: this.lastResolvedProviderName,
                         attempts: emptyResponseAttempts,
+                        isSubAgent: this.isSubAgent,
                     });
-                    this.appendToHistory({
-                        role: 'assistant',
-                        content: 'While working on your request, I repeatedly generated a blank response. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
-                    });
+                    if (this.isSubAgent) {
+                        this.failSubAgent('empty_response');
+                    }
+                    else {
+                        this.appendToHistory({
+                            role: 'assistant',
+                            content: 'While working on your request, I repeatedly generated a blank response. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
+                        });
+                    }
                     return { reason: 'done' };
                 }
                 else if (isThinkingStep) {
@@ -1020,6 +1172,11 @@ export class ChatDriver extends EventTarget {
                 else {
                     this.appendToHistory(response);
                 }
+                // Reset retry budgets on any productive (non-empty) response, so the caps mean
+                // "N CONSECUTIVE failures" not "N total per turn".
+                emptyResponseAttempts = 0;
+                malformedAttempts = 0;
+                setupTransportAttempts = 0;
                 if (!((_f = response.toolCalls) === null || _f === void 0 ? void 0 : _f.length)) {
                     break;
                 }
@@ -1101,19 +1258,20 @@ export class ChatDriver extends EventTarget {
                             // or an exclusive fold is hiding it) rather than hallucinated — a
                             // distinction worth making, because the model should stop retrying
                             // a retired tool rather than treat the failure as a typo. Stale
-                            // calls still count toward the same unknown-tool limit (loop
-                            // protection); only the guidance and telemetry differ.
+                            // calls still trip loop protection, but at a higher ceiling than
+                            // hallucinated tools (see below) — they are self-correcting, so the
+                            // guidance, telemetry, and limit differ.
                             if (this.everSeenToolNames.has(tc.name)) {
                                 this.consecutiveUnknownToolCalls += 1;
                                 const hidingFold = this.foldHidingTool(tc.name);
                                 let content;
                                 if (hidingFold) {
                                     content = `"${tc.name}" is not available while the "${hidingFold}" fold is open. Call close_${hidingFold} to return to the previous set of tools, then call ${tc.name}.`;
-                                    logger.warn(`ChatDriver: tool "${tc.name}" is hidden behind open fold "${hidingFold}" (${this.consecutiveUnknownToolCalls}/${DEFAULT_MAX_UNKNOWN_TOOL_CALLS})`);
+                                    logger.warn(`ChatDriver: tool "${tc.name}" is hidden behind open fold "${hidingFold}" (${this.consecutiveUnknownToolCalls}/${MAX_STALE_TOOL_CALLS})`);
                                 }
                                 else {
                                     content = `"${tc.name}" was available earlier but is not part of the current step — that step is complete, so do not call it again. Continue with the tools available now: ${Object.keys(this.toolHandlers).join(', ') || '(none)'}.`;
-                                    logger.warn(`ChatDriver: stale tool "${tc.name}" — advertised earlier this activation but retired in the current state (${this.consecutiveUnknownToolCalls}/${DEFAULT_MAX_UNKNOWN_TOOL_CALLS})`);
+                                    logger.warn(`ChatDriver: stale tool "${tc.name}" — advertised earlier this activation but retired in the current state (${this.consecutiveUnknownToolCalls}/${MAX_STALE_TOOL_CALLS})`);
                                 }
                                 recordMetaEvent(this.sessionKey, 'tool.unresolved', {
                                     tool: tc.name,
@@ -1121,14 +1279,14 @@ export class ChatDriver extends EventTarget {
                                     kind: hidingFold ? 'fold-hidden' : 'stale',
                                     fold: hidingFold !== null && hidingFold !== void 0 ? hidingFold : undefined,
                                     consecutive: this.consecutiveUnknownToolCalls,
-                                    max: DEFAULT_MAX_UNKNOWN_TOOL_CALLS,
+                                    max: MAX_STALE_TOOL_CALLS,
                                 });
                                 executedById.set(tc.id, { toolCallId: tc.id, content });
                                 unknownToolIds.add(tc.id);
                                 staleToolIds.add(tc.id);
                                 this.recentUnknownToolNames.add(tc.name);
                                 this.recentStaleToolNames.add(tc.name);
-                                if (this.consecutiveUnknownToolCalls >= DEFAULT_MAX_UNKNOWN_TOOL_CALLS) {
+                                if (this.consecutiveUnknownToolCalls >= MAX_STALE_TOOL_CALLS) {
                                     hitUnknownToolLimit = true;
                                 }
                                 return;
@@ -1173,7 +1331,9 @@ export class ChatDriver extends EventTarget {
                             });
                             executedById.set(tc.id, {
                                 toolCallId: tc.id,
-                                content: `Tool error: ${e.message}`,
+                                // 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.`,
                             });
                             anyRealToolExecuted = true; // treat errors as real work for fold op counting
                         }
@@ -1270,11 +1430,17 @@ export class ChatDriver extends EventTarget {
                         staleTools,
                         hallucinatedTools,
                         availableTools: Object.keys(this.toolHandlers),
+                        isSubAgent: this.isSubAgent,
                     });
-                    this.appendToHistory({
-                        role: 'assistant',
-                        content: "I'm sorry, I repeatedly tried to use tools that aren't available to me, so I couldn't complete that. If a 'Download agent log' option appears in the Settings (cog) menu, you can download the log and share it with whoever set up this assistant to help fix the issue.",
-                    });
+                    if (this.isSubAgent) {
+                        this.failSubAgent('unknown_tool_limit');
+                    }
+                    else {
+                        this.appendToHistory({
+                            role: 'assistant',
+                            content: "I'm sorry, I repeatedly tried to use tools that aren't available to me, so I couldn't complete that. If a 'Download agent log' option appears in the Settings (cog) menu, you can download the log and share it with whoever set up this assistant to help fix the issue.",
+                        });
+                    }
                     return { reason: 'done' };
                 }
                 const firstContinuation = systemCalls[0];
@@ -1295,11 +1461,17 @@ export class ChatDriver extends EventTarget {
                     provider: this.lastResolvedProviderName,
                     iterations,
                     limit: this.maxToolIterations,
+                    isSubAgent: this.isSubAgent,
                 });
-                this.appendToHistory({
-                    role: 'assistant',
-                    content: "I've reached my limit for this response. You can ask me to continue and I'll pick up where I left off.",
-                });
+                if (this.isSubAgent) {
+                    this.failSubAgent('max_iterations');
+                }
+                else {
+                    this.appendToHistory({
+                        role: 'assistant',
+                        content: "I've reached my limit for this response. You can ask me to continue and I'll pick up where I left off.",
+                    });
+                }
             }
             return { reason: 'done' };
         });

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

@@ -12,11 +12,14 @@ import { ChatDriver } from './chat-driver';
 const scriptedProvider = (responses) => {
     const queue = [...responses];
     const advertisedPerCall = [];
+    const toolChoicePerCall = [];
     return {
         advertisedPerCall,
+        toolChoicePerCall,
         chat: (_history, _userMessage, options) => __awaiter(void 0, void 0, void 0, function* () {
             var _a, _b;
             advertisedPerCall.push(((_a = options === null || options === void 0 ? void 0 : options.tools) !== null && _a !== void 0 ? _a : []).map((t) => t.name));
+            toolChoicePerCall.push(options === null || options === void 0 ? void 0 : options.toolChoice);
             // Once the script is exhausted, end the turn with a plain text reply.
             return (_b = queue.shift()) !== null && _b !== void 0 ? _b : { role: 'assistant', content: 'done' };
         }),
@@ -173,11 +176,11 @@ stale('splits stale vs hallucinated tools on the unknown-tool-limit error', () =
             }
             : { tool_b: () => __awaiter(void 0, void 0, void 0, function* () { return 'b done'; }) },
     });
-    // One real call to advance to B, then 5 consecutive stale calls — the 5th
-    // trips DEFAULT_MAX_UNKNOWN_TOOL_CALLS and ends the turn.
+    // One real call to advance to B, then 10 consecutive stale calls — the 10th
+    // trips the stale ceiling (MAX_STALE_TOOL_CALLS, 2x the hallucination limit) and ends the turn.
     const provider = scriptedProvider([
         callsTool('tool_a', 'real'),
-        ...Array.from({ length: 5 }, (_unused, i) => callsTool('tool_a', `stale-${i}`)),
+        ...Array.from({ length: 10 }, (_unused, i) => callsTool('tool_a', `stale-${i}`)),
     ]);
     const driver = makeDriver(config, provider, sessionKey);
     const result = yield driver.sendMessage('go');
@@ -188,9 +191,136 @@ stale('splits stale vs hallucinated tools on the unknown-tool-limit error', () =
     assert.equal(detail.staleTools, ['tool_a'], 'tool_a should be classified as stale');
     assert.equal(detail.hallucinatedTools, [], 'nothing was hallucinated');
     // Every stale attempt — not just the final limit error — is in the download log.
-    assert.is(unresolvedEvents(sessionKey).filter((d) => d.kind === 'stale').length, 5, 'each stale attempt should be recorded as its own tool.unresolved event');
+    assert.is(unresolvedEvents(sessionKey).filter((d) => d.kind === 'stale').length, 10, 'each stale attempt should be recorded as its own tool.unresolved event');
     // The user-facing turn ends with the apology, not a crash.
     const last = driver.getHistory().at(-1);
     assert.ok((last === null || last === void 0 ? void 0 : last.role) === 'assistant' && last.content.startsWith("I'm sorry"));
 }));
 stale.run();
+// ---------------------------------------------------------------------------
+// sub-agents — forced tool use + typed completion/failure union (GENC-1312)
+//
+// A child sub-agent driver shares the parent's provider registry, so one
+// scripted queue drives both: script the parent's delegating turn, then the
+// worker's turn(s), in order.
+// ---------------------------------------------------------------------------
+const subagent = createLogicSuite('ChatDriver sub-agents');
+subagent.after(() => {
+    // Safe to call again even if `stale` already closed it — close() is
+    // idempotent and cross-tab publishes are guarded by `&& this.channel`.
+    agenticActivityBus.close();
+});
+/** A sub-agent named `worker` that finishes by calling `completeSubAgent`. */
+const completingWorker = (result) => agent({
+    name: 'worker',
+    toolDefinitions: [def('finish')],
+    toolHandlers: {
+        finish: (_args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            (_a = ctx.completeSubAgent) === null || _a === void 0 ? void 0 : _a.call(ctx, result);
+            return 'finished';
+        }),
+    },
+});
+/** A parent that delegates to `worker` and reports the outcome via `capture`. */
+const delegatingParent = (sub, capture) => agent({
+    name: 'boss',
+    subAgents: [sub],
+    toolDefinitions: [def('delegate')],
+    toolHandlers: {
+        delegate: (_args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+            const outcome = yield ctx.requestSubAgent('worker', { task: 'do it' });
+            capture(outcome);
+            return outcome.ok ? 'sub-agent completed' : `sub-agent failed: ${outcome.reason}`;
+        }),
+    },
+});
+subagent('resolves { ok: true, result } when the sub-agent calls completeSubAgent', () => __awaiter(void 0, void 0, void 0, function* () {
+    let outcome;
+    const parent = delegatingParent(completingWorker({ value: 42 }), (o) => {
+        outcome = o;
+    });
+    const provider = scriptedProvider([
+        callsTool('delegate', 'd1'), // parent delegates to the worker
+        callsTool('finish', 'f1'), //   worker completes
+    ]);
+    yield makeDriver(parent, provider).sendMessage('go');
+    assert.equal(outcome, { ok: true, result: { value: 42 } });
+}));
+subagent('forces tool use on the sub-agent turn but not the parent turn', () => __awaiter(void 0, void 0, void 0, function* () {
+    const parent = delegatingParent(completingWorker({ done: true }), () => { });
+    const provider = scriptedProvider([callsTool('delegate', 'd1'), callsTool('finish', 'f1')]);
+    yield makeDriver(parent, provider).sendMessage('go');
+    // Call 0 is the parent's turn (may-call); call 1 is the worker's turn (must-call).
+    assert.is(provider.toolChoicePerCall[0], undefined, 'parent turn is not forced');
+    assert.is(provider.toolChoicePerCall[1], 'required', 'sub-agent turn forces a tool call');
+    assert.ok(provider.advertisedPerCall[1].includes('finish'), 'the worker advertised its completion tool');
+}));
+subagent('resolves { ok: false, reason } and records telemetry when the sub-agent never completes', () => __awaiter(void 0, void 0, void 0, function* () {
+    const sessionKey = 'subagent-unknown-tool-test';
+    clearMetaEventRegistry();
+    let outcome;
+    const worker = agent({
+        name: 'worker',
+        toolDefinitions: [def('real')],
+        toolHandlers: { real: () => __awaiter(void 0, void 0, void 0, function* () { return 'ok'; }) },
+    });
+    const parent = delegatingParent(worker, (o) => {
+        outcome = o;
+    });
+    // The worker repeatedly calls a tool it was never given, tripping the
+    // unknown-tool limit (DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5) without completing.
+    const provider = scriptedProvider([
+        callsTool('delegate', 'd1'),
+        ...Array.from({ length: 5 }, (_unused, i) => callsTool('made_up', `u${i}`)),
+    ]);
+    yield makeDriver(parent, provider, sessionKey).sendMessage('go');
+    assert.equal(outcome, { ok: false, reason: 'unknown_tool_limit' });
+    // The failure surfaces as a high-importance `subagent.failed` meta event,
+    // recorded under the PARENT driver's session so it lands on the user-visible
+    // debug-log timeline — not orphaned in the child's own session bucket.
+    assert.ok(getMetaEvents(sessionKey).some((e) => {
+        var _a, _b;
+        return e.type === 'subagent.failed' &&
+            ((_a = e.detail) === null || _a === void 0 ? void 0 : _a.agent) === 'worker' &&
+            ((_b = e.detail) === null || _b === void 0 ? void 0 : _b.reason) === 'unknown_tool_limit';
+    }), 'a subagent.failed meta event should be recorded under the parent session');
+    assert.not.ok(getMetaEvents('').some((e) => e.type === 'subagent.failed'), 'the failure must not be orphaned in the child default session bucket');
+}));
+subagent('defaults to { ok: false, reason: "max_iterations" } when the sub-agent ends without completing', () => __awaiter(void 0, void 0, void 0, function* () {
+    const sessionKey = 'subagent-default-fail-test';
+    clearMetaEventRegistry();
+    let outcome;
+    const worker = agent({
+        name: 'worker',
+        toolDefinitions: [def('noop')],
+        toolHandlers: { noop: () => __awaiter(void 0, void 0, void 0, function* () { return 'ok'; }) },
+    });
+    const parent = delegatingParent(worker, (o) => {
+        outcome = o;
+    });
+    // No script for the worker turn → it returns a plain-text reply and ends
+    // without ever calling a completion tool (the child records no explicit
+    // failure reason).
+    const provider = scriptedProvider([callsTool('delegate', 'd1')]);
+    yield makeDriver(parent, provider, sessionKey).sendMessage('go');
+    assert.equal(outcome, { ok: false, reason: 'max_iterations' });
+    // Even the defensive default is reported to the parent session — this is the
+    // only telemetry path when the child recorded no explicit failure.
+    assert.ok(getMetaEvents(sessionKey).some((e) => { var _a; return e.type === 'subagent.failed' && ((_a = e.detail) === null || _a === void 0 ? void 0 : _a.reason) === 'max_iterations'; }), 'the default failure should still record a subagent.failed meta event');
+}));
+subagent("forwards the sub-agent's turns onto the parent timeline, numbered under the activating turn", () => __awaiter(void 0, void 0, void 0, function* () {
+    const parent = delegatingParent(completingWorker({ done: true }), () => { });
+    const provider = scriptedProvider([callsTool('delegate', 'd1'), callsTool('finish', 'f1')]);
+    const driver = makeDriver(parent, provider);
+    yield driver.sendMessage('go');
+    const snaps = driver.getTurnSnapshots();
+    // Parent turn 0 activated the sub-agent, so the worker's single turn is "0-1".
+    const childSnap = snaps.find((s) => s.turnIndex === '0-1');
+    assert.ok(childSnap, 'the sub-agent\'s turn should be forwarded as "0-1"');
+    assert.is(childSnap.agentName, 'worker', 'the forwarded snapshot keeps the sub-agent name');
+    assert.ok(childSnap.toolNames.includes('finish'), 'and records the tools the sub-agent saw');
+    // The parent's own turns stay numeric.
+    assert.ok(snaps.some((s) => s.turnIndex === '0'), 'the activating parent turn is present as a bare string counter');
+}));
+subagent.run();

package/dist/esm/main/main.js

@@ -1293,7 +1293,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         // prompt is still shown in full whenever it changes, so prompt evolution
         // stays visible.
         let lastFullPrompt;
-        let lastFullIndex = -1;
+        let lastFullIndex = '';
         const turns = ((_e = (_d = (_c = this.driver) === null || _c === void 0 ? void 0 : _c.getTurnSnapshots) === null || _d === void 0 ? void 0 : _d.call(_c)) !== null && _e !== void 0 ? _e : []).map((t) => {
             let { systemPrompt } = t;
             if (systemPrompt != null && systemPrompt === lastFullPrompt) {

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

@@ -36,6 +36,7 @@
 export const META_EVENT_IMPORTANCE = {
     'turn.error': 'high',
     'tool.failed': 'high',
+    'subagent.failed': 'high',
     'file.read-failed': 'high',
     'suggestions.failed': 'high',
     'context.threshold-crossed': 'high',
@@ -135,7 +136,7 @@ export const DEBUG_LOG_README = [
     'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',
     '`timeline` is the entire session as one array, already sorted chronologically by `timestamp` (ISO 8601). Every entry has a `kind`.',
     "kind:'message' — the conversation. `role` is user/assistant/tool/system-event; `agentName` says which agent produced it; `toolCalls`/`toolResult`/`interaction` carry tool and widget activity; `inputTokens`/`outputTokens`/`cost` are per-message usage.",
-    "kind:'turn' — one LLM call. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.",
+    "kind:'turn' — one LLM call. `turnIndex` is a string: a top-level turn is the bare counter ('0', '1', …); a sub-agent's turns are numbered under the parent turn that activated them ('3-1', '3-2', …, and a nested sub-agent contributes '3-2-1', …), and `agentName` names the agent that ran the turn. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.",
     "kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.",
     "kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.",
     "Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. 'message' and 'turn' entries carry no importance — they are the substance, always read them.",