@genesislcap/ai-assistant 14.419.2 → 14.421.0

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

@@ -1,8 +1,16 @@
 import { __awaiter } from "tslib";
 import { MalformedFunctionCallError } from '@genesislcap/foundation-ai';
 import { logger } from '../../utils/logger';
+import { TOOL_FOLD_SYMBOL } from '../../utils/tool-fold';
 const DEFAULT_MAX_TOOL_ITERATIONS = 50;
+const DEFAULT_MAX_FOLD_OPERATIONS = 5;
+const DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5;
 const MAX_MALFORMED_RETRIES = 2;
+const SUGGESTIONS_HISTORY_WINDOW = 8;
+/** Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver. */
+export const REQUEST_CONTINUATION_TOOL = 'request_continuation';
+/** Paired in history for each `request_continuation` so tool_calls stay balanced for the provider. */
+const HANDOFF_TOOL_RESULT_PLACEHOLDER = 'Handoff to another specialist — routing continues on the next turn.';
 /**
  * Plain TS class that drives a multi-turn chat conversation, including the tool-call loop.
  * Owned by `FoundationAiAssistant` — created in `connectedCallback`, torn down in `disconnectedCallback`.
@@ -14,24 +22,133 @@ const MAX_MALFORMED_RETRIES = 2;
  * @beta
  */
 export class ChatDriver extends EventTarget {
-    constructor(aiProvider, toolHandlers = {}, toolDefinitions = [], systemPrompt, primerHistory, maxToolIterations = DEFAULT_MAX_TOOL_ITERATIONS) {
+    constructor(aiProvider, toolHandlers = {}, toolDefinitions = [], systemPrompt, primerHistory, maxToolIterations = DEFAULT_MAX_TOOL_ITERATIONS, maxFoldOperations = DEFAULT_MAX_FOLD_OPERATIONS) {
         super();
         this.aiProvider = aiProvider;
-        this.toolHandlers = toolHandlers;
-        this.toolDefinitions = toolDefinitions;
-        this.systemPrompt = systemPrompt;
-        this.primerHistory = primerHistory;
         this.maxToolIterations = maxToolIterations;
         this.history = [];
         this.busy = false;
         this.pendingInteractions = new Map();
-        if (!systemPrompt) {
-            logger.error('ChatDriver: no systemPrompt provided. The assistant will have no instructions — set the systemPrompt property on foundation-ai-assistant.');
-        }
+        /** Stack of fold frames — grows when a fold opens, shrinks when it closes. */
+        this.foldStack = [];
+        /** Consecutive fold open/close ops without a real tool call. Reset on real tool execution. */
+        this.consecutiveFoldOps = 0;
+        /** Consecutive unknown-tool calls without a real tool call. Reset on real tool execution. */
+        this.consecutiveUnknownToolCalls = 0;
+        this.toolHandlers = toolHandlers;
+        this.toolDefinitions = toolDefinitions;
+        this.systemPrompt = systemPrompt;
+        this.primerHistory = primerHistory;
+        this.maxFoldOperations = maxFoldOperations;
+    }
+    /**
+     * Swap in a new agent's configuration. Called by OrchestratingDriver before
+     * each specialist turn so the shared driver runs with the right tools and prompt.
+     */
+    applyAgent(config) {
+        var _a, _b;
+        this.systemPrompt = config.systemPrompt;
+        this.toolDefinitions = (_a = config.toolDefinitions) !== null && _a !== void 0 ? _a : [];
+        this.toolHandlers = (_b = config.toolHandlers) !== null && _b !== void 0 ? _b : {};
+        this.primerHistory = config.primerHistory;
+        this.activeAgentName = config.name;
+        // Reset fold state when agent changes — each specialist starts fresh
+        this.foldStack = [];
+        this.consecutiveFoldOps = 0;
+    }
+    /**
+     * Optional transform applied to conversation history immediately before each LLM request.
+     * Cleared when `undefined`. Does not alter stored history.
+     */
+    setProviderHistoryTransform(transform) {
+        this.providerHistoryTransform = transform;
     }
     getHistory() {
         return this.history;
     }
+    getRawHistory() {
+        return this.history;
+    }
+    /** Returns the current fold stack names for debugging. */
+    getActiveFoldNames() {
+        return this.foldStack.map((f) => f.foldName);
+    }
+    getSuggestions(history, prompt, count, allAgentInfo) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.aiProvider.prompt) {
+                logger.warn('ChatDriver: AIProvider does not implement prompt()');
+                return [];
+            }
+            let agentContext = '';
+            let toolContext = '';
+            if (allAgentInfo === null || allAgentInfo === void 0 ? void 0 : allAgentInfo.length) {
+                const agentDescriptions = allAgentInfo
+                    .map((agent) => {
+                    const tools = agent.tools.map((t) => t.name).join(', ');
+                    return `- ${agent.name} (${agent.description}): ${tools ? `(Tools: ${tools})` : 'No tools'}`;
+                })
+                    .join('\n');
+                agentContext = `The assistant has the following capabilities:\n${agentDescriptions}`;
+                const allToolNames = allAgentInfo
+                    .flatMap((agent) => agent.tools.map((t) => t.name))
+                    .filter((value, index, self) => self.indexOf(value) === index)
+                    .join(', ');
+                toolContext = allToolNames
+                    ? `You have access to the following tools across all agents: ${allToolNames}.`
+                    : '';
+            }
+            else if (this.activeAgentName) {
+                const toolNames = this.toolDefinitions.map((tool) => tool.name).join(', ');
+                agentContext = `You are currently acting as the "${this.activeAgentName}" agent.`;
+                toolContext = toolNames ? `You have access to the following tools: ${toolNames}.` : '';
+            }
+            let systemPrompt;
+            if (history.length === 0) {
+                systemPrompt = `You are generating short, simple starter prompts to show a user what an AI assistant can do. Generate exactly ${count} brief suggestions phrased as the user would write them. Keep them short and generic — do not invent specific names, IDs, or data (e.g. prefer "Search for a trade" over "Find all trades with Client A").`;
+                if (agentContext || toolContext) {
+                    systemPrompt += " Base suggestions only on the agent's actual capabilities.";
+                    if (agentContext)
+                        systemPrompt += ` ${agentContext}`;
+                    if (toolContext)
+                        systemPrompt += ` ${toolContext}`;
+                    systemPrompt += ' Do not suggest anything outside these capabilities.';
+                }
+            }
+            else {
+                systemPrompt = `You are generating suggested follow-up prompts that a user could send to an AI assistant. Generate exactly ${count} suggestions phrased as the user would write them — first-person requests or questions directed at the agent. The first ${Math.max(0, count - 1)} should be natural follow-ups to the last turn of conversation. Do not invent specific names, IDs, or data values that do not appear in the conversation history.`;
+                if (agentContext || toolContext) {
+                    systemPrompt += ' Suggestions must only cover what the agent is capable of.';
+                    if (agentContext)
+                        systemPrompt += ` ${agentContext}`;
+                    if (toolContext)
+                        systemPrompt += ` ${toolContext}`;
+                    systemPrompt += ' Do not suggest anything outside these capabilities.';
+                }
+            }
+            if (prompt) {
+                systemPrompt += ` Additional guidance: "${prompt}"`;
+            }
+            systemPrompt +=
+                ' Output only the suggestions — one per line, no numbering, no bullets, no commentary, no preamble. Do not describe or explain the suggestions.';
+            const conversationContext = history
+                .filter((m) => {
+                var _a, _b;
+                return (m.role === 'user' || m.role === 'assistant') &&
+                    !((_a = m.toolCalls) === null || _a === void 0 ? void 0 : _a.length) &&
+                    !m.thinking &&
+                    !!((_b = m.content) === null || _b === void 0 ? void 0 : _b.trim());
+            })
+                .slice(-SUGGESTIONS_HISTORY_WINDOW)
+                .map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`)
+                .join('\n');
+            const message = conversationContext || 'The conversation has not started yet.';
+            const text = yield this.aiProvider.prompt(message, { systemPrompt });
+            return text
+                .split('\n')
+                .map((s) => s.trim())
+                .filter(Boolean);
+        });
+    }
     isBusy() {
         return this.busy;
     }
@@ -62,11 +179,9 @@ export class ChatDriver extends EventTarget {
     resolveInteraction(interactionId, result) {
         const interaction = this.pendingInteractions.get(interactionId);
         if (interaction) {
-            // Mark the message as resolved before resolving the promise so the next
-            // history-updated event carries the updated flag.
-            const msg = this.history.find((m) => { var _a; return ((_a = m.interaction) === null || _a === void 0 ? void 0 : _a.interactionId) === interactionId; });
-            if (msg === null || msg === void 0 ? void 0 : msg.interaction) {
-                msg.interaction.resolved = true;
+            const idx = this.history.findIndex((m) => { var _a; return ((_a = m.interaction) === null || _a === void 0 ? void 0 : _a.interactionId) === interactionId; });
+            if (idx !== -1) {
+                this.history[idx] = Object.assign(Object.assign({}, this.history[idx]), { interaction: Object.assign(Object.assign({}, this.history[idx].interaction), { resolved: result }) });
                 this.dispatchEvent(new CustomEvent('history-updated', {
                     detail: this.history,
                 }));
@@ -84,57 +199,224 @@ export class ChatDriver extends EventTarget {
      */
     loadHistory(messages) {
         this.history = [...messages];
+        this.dispatchEvent(new CustomEvent('history-updated', {
+            detail: this.history,
+        }));
     }
     sendMessage(userInput, attachments) {
         return __awaiter(this, void 0, void 0, function* () {
             if (this.busy || (!userInput.trim() && !(attachments === null || attachments === void 0 ? void 0 : attachments.length)))
-                return;
+                return { reason: 'done' };
             if (!this.aiProvider.chat) {
                 logger.warn('ChatDriver: AIProvider does not implement chat()');
-                return;
+                return { reason: 'done' };
             }
             this.busy = true;
             this.appendToHistory({ role: 'user', content: userInput, attachments });
             try {
-                yield this.runToolLoop(userInput, attachments);
+                return yield this.runToolLoop(userInput, attachments);
+            }
+            catch (e) {
+                logger.error('ChatDriver error:', e);
+                this.appendToHistory({ role: 'assistant', content: 'Sorry, something went wrong.' });
+                return { reason: 'done' };
+            }
+            finally {
+                this.busy = false;
+            }
+        });
+    }
+    /**
+     * Continue the tool loop from current history without appending a new user message.
+     * Used by OrchestratingDriver after an agent handoff.
+     */
+    continueFromHistory(transientPrimer) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.busy)
+                return { reason: 'done' };
+            if (!this.aiProvider.chat) {
+                logger.warn('ChatDriver: AIProvider does not implement chat()');
+                return { reason: 'done' };
+            }
+            this.busy = true;
+            try {
+                return yield this.runToolLoop('', undefined, transientPrimer);
             }
             catch (e) {
                 logger.error('ChatDriver error:', e);
                 this.appendToHistory({ role: 'assistant', content: 'Sorry, something went wrong.' });
+                return { reason: 'done' };
             }
             finally {
                 this.busy = false;
             }
         });
     }
-    runToolLoop(userInput, attachments) {
+    // ---------------------------------------------------------------------------
+    // Fold mechanics
+    // ---------------------------------------------------------------------------
+    /** Extract ToolFold metadata from a handler, or undefined if it isn't a fold facade. */
+    getFold(toolName) {
+        const handler = this.toolHandlers[toolName];
+        return handler ? handler[TOOL_FOLD_SYMBOL] : undefined;
+    }
+    /**
+     * Search all currently registered fold facades (and their nested folds recursively)
+     * to find which fold contains a given tool name. Returns the immediate parent fold name.
+     */
+    findFoldContaining(toolName, handlers) {
+        const source = handlers !== null && handlers !== void 0 ? handlers : this.toolHandlers;
+        for (const [, handler] of Object.entries(source)) {
+            const fold = handler[TOOL_FOLD_SYMBOL];
+            if (!fold)
+                continue;
+            // Direct inner tool match
+            if (fold.handlers[toolName])
+                return fold.name;
+            // Recurse into nested folds
+            const nested = this.findFoldContaining(toolName, fold.handlers);
+            if (nested)
+                return fold.name;
+        }
+        return null;
+    }
+    /**
+     * Install the fold's inner tool set, replacing (exclusive) or extending (non-exclusive)
+     * the current tool set. Also injects the close tool. Does NOT touch the fold stack.
+     */
+    applyFoldToolSet(fold, foldName) {
+        const closeToolName = `close_${foldName}`;
+        const newDefs = [];
+        const newHandlers = {};
+        if (!fold.exclusive) {
+            // Non-exclusive: keep existing tools minus the facade we just opened
+            for (const def of this.toolDefinitions) {
+                if (def.name !== foldName)
+                    newDefs.push(def);
+            }
+            for (const [name, handler] of Object.entries(this.toolHandlers)) {
+                if (name !== foldName)
+                    newHandlers[name] = handler;
+            }
+        }
+        // Install inner tools from fold metadata
+        newDefs.push(...fold.tools);
+        Object.assign(newHandlers, fold.handlers);
+        // Inject the close tool
+        newDefs.push({
+            name: closeToolName,
+            description: `Close the ${foldName} fold and return to the previous set of tools.`,
+            parameters: { type: 'object', properties: {} },
+        });
+        newHandlers[closeToolName] = () => __awaiter(this, void 0, void 0, function* () { return this.closeFold(); });
+        this.toolDefinitions = newDefs;
+        this.toolHandlers = newHandlers;
+    }
+    /** Open a fold: push a stack frame, swap the tool set, return the response message. */
+    openFold(foldName, fold, args) {
+        // Shortcut dispatch: model passed inner tool args directly, e.g.
+        // trading_tools({ search_trades: { side: "BUY" } })
+        for (const key of Object.keys(args)) {
+            const innerHandler = fold.handlers[key];
+            if (innerHandler) {
+                logger.debug(`ChatDriver: fold shortcut dispatch "${foldName}" → "${key}"`);
+                // Open the fold first so the tool set is correct for subsequent calls
+                this.pushFoldFrame(foldName);
+                this.applyFoldToolSet(fold, foldName);
+                this.consecutiveFoldOps = 0; // shortcut dispatch counts as real work
+                const innerArgs = typeof args[key] === 'object' && args[key] !== null
+                    ? args[key]
+                    : {};
+                return innerHandler(innerArgs, {
+                    requestInteraction: (c, d) => this.requestInteraction(c, d),
+                }).then((r) => (typeof r === 'string' ? r : JSON.stringify(r)));
+            }
+        }
+        // Normal two-step open
+        this.pushFoldFrame(foldName);
+        this.applyFoldToolSet(fold, foldName);
+        const innerToolNames = fold.tools.map((t) => t.name);
+        const closeToolName = `close_${foldName}`;
+        let message = `Fold opened: ${foldName}. Tools now available: ${[...innerToolNames, closeToolName].join(', ')}.`;
+        if (fold.usageNotes)
+            message += ` Notes: ${fold.usageNotes}`;
+        message += ` Call ${closeToolName} when done to return to the previous tools.`;
+        return Promise.resolve(message);
+    }
+    pushFoldFrame(foldName) {
+        this.foldStack.push({
+            foldName,
+            previousDefinitions: [...this.toolDefinitions],
+            previousHandlers: Object.assign({}, this.toolHandlers),
+        });
+    }
+    /** Close the top fold: pop the stack frame, restore the previous tool set. */
+    closeFold() {
+        const frame = this.foldStack.pop();
+        if (!frame)
+            return 'No fold is currently open.';
+        this.toolDefinitions = frame.previousDefinitions;
+        this.toolHandlers = frame.previousHandlers;
+        const toolNames = this.toolDefinitions.map((t) => t.name);
+        return `Fold closed: ${frame.foldName}. Tools now available: ${toolNames.join(', ')}.`;
+    }
+    /** Build the fold-awareness suffix appended to the system prompt each LLM call. */
+    buildFoldSystemPromptSuffix() {
+        // Collect fold facades from the current handler map
+        const activeFolds = [];
+        for (const handler of Object.values(this.toolHandlers)) {
+            const fold = handler[TOOL_FOLD_SYMBOL];
+            if (fold)
+                activeFolds.push(fold);
+        }
+        if (activeFolds.length === 0 && this.foldStack.length === 0)
+            return '';
+        const parts = ['\n\n--- Tool Folds ---'];
+        parts.push('Some tools are grouped into folds. You may see tool calls in the conversation history for tools that are not currently available — they are inside a fold. To access them, invoke the fold tool first.');
+        if (this.foldStack.length > 0) {
+            const current = this.foldStack[this.foldStack.length - 1];
+            parts.push(`You are currently inside the "${current.foldName}" fold. Call close_${current.foldName} when you are done with these tools.`);
+        }
+        for (const fold of activeFolds) {
+            parts.push(`• ${fold.name}: ${fold.description}`);
+        }
+        return parts.join('\n');
+    }
+    // ---------------------------------------------------------------------------
+    // Tool loop
+    // ---------------------------------------------------------------------------
+    runToolLoop(userInput, attachments, transientPrimer) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d, _e, _f;
-            const baseOptions = {
-                systemPrompt: this.systemPrompt,
-                tools: this.toolDefinitions.length ? this.toolDefinitions : undefined,
-            };
-            // History has the user message at the end — pass everything before it as history,
-            // and the user input as the userMessage argument.
+            if (!this.systemPrompt) {
+                logger.warn('ChatDriver: no systemPrompt set. The assistant will have no instructions — provide a systemPrompt via agents config or the foundation-ai-assistant property.');
+            }
             let currentInput = userInput;
             let currentAttachments = attachments;
             let iterations = 0;
             let malformedAttempts = 0;
+            const startIteration = currentInput ? 1 : 0;
             while (iterations < this.maxToolIterations) {
                 iterations += 1;
-                // On the first iteration, the last item in history is the user message which is
-                // passed separately as currentInput — exclude it. On subsequent iterations, the
-                // full history (including tool results) should be sent and currentInput is empty.
-                // primerHistory (if provided) is prepended to every call but never stored in
-                // this.history and never shown in the UI.
-                const primer = (_a = this.primerHistory) !== null && _a !== void 0 ? _a : [];
-                const historyForCall = iterations === 1 ? [...primer, ...this.history.slice(0, -1)] : [...primer, ...this.history];
-                // On malformed-call retries, augment the system prompt to steer the model
-                // away from generating Python-style batched function call syntax.
+                const foldSuffix = this.buildFoldSystemPromptSuffix();
+                const baseSystemPrompt = this.systemPrompt
+                    ? `${this.systemPrompt}${foldSuffix}`
+                    : foldSuffix || undefined;
+                const primer = [...((_a = this.primerHistory) !== null && _a !== void 0 ? _a : []), ...(transientPrimer !== null && transientPrimer !== void 0 ? transientPrimer : [])];
+                const baseHistory = iterations === startIteration ? this.history.slice(0, -1) : this.history;
+                const historyForProvider = this.providerHistoryTransform
+                    ? this.providerHistoryTransform([...baseHistory])
+                    : baseHistory;
+                const historyForCall = [...primer, ...historyForProvider];
                 const systemPrompt = malformedAttempts > 0
-                    ? `${(_b = baseOptions.systemPrompt) !== null && _b !== void 0 ? _b : ''}\n\nIMPORTANT: Use only the structured function-call API to invoke tools. Do not write Python code or use Python-style syntax to call tools.`
-                    : baseOptions.systemPrompt;
-                const options = Object.assign(Object.assign({}, baseOptions), { systemPrompt, attachments: currentAttachments });
+                    ? `${baseSystemPrompt !== null && baseSystemPrompt !== void 0 ? baseSystemPrompt : ''}\n\nIMPORTANT: Use only the structured function-call API to invoke tools. Do not write Python code or use Python-style syntax to call tools.`
+                    : baseSystemPrompt;
+                const options = {
+                    systemPrompt,
+                    // Strip fold-only properties (foldEvent, foldPath) before sending to provider
+                    tools: this.toolDefinitions.length ? this.toolDefinitions : undefined,
+                    attachments: currentAttachments,
+                };
                 let response;
                 try {
                     // eslint-disable-next-line no-await-in-loop
@@ -145,7 +427,7 @@ export class ChatDriver extends EventTarget {
                         malformedAttempts += 1;
                         if (malformedAttempts < MAX_MALFORMED_RETRIES) {
                             logger.warn(`ChatDriver: MALFORMED_FUNCTION_CALL, retrying (${malformedAttempts}/${MAX_MALFORMED_RETRIES})`);
-                            iterations -= 1; // don't consume an iteration budget slot for a failed attempt
+                            iterations -= 1;
                             continue;
                         }
                         logger.error('ChatDriver: MALFORMED_FUNCTION_CALL, max retries reached');
@@ -153,65 +435,215 @@ export class ChatDriver extends EventTarget {
                             role: 'assistant',
                             content: "I'm sorry, I wasn't able to complete that request. Please try rephrasing or breaking it into smaller steps.",
                         });
-                        return;
+                        return { reason: 'done' };
                     }
                     throw e;
                 }
-                currentAttachments = undefined; // attachments only sent on first call
-                const isThinkingStep = response.content && ((_c = response.toolCalls) === null || _c === void 0 ? void 0 : _c.length);
-                const isEmptyResponse = !((_d = response.content) === null || _d === void 0 ? void 0 : _d.trim()) && !((_e = response.toolCalls) === null || _e === void 0 ? void 0 : _e.length);
+                currentAttachments = undefined;
+                const isThinkingStep = response.content && ((_b = response.toolCalls) === null || _b === void 0 ? void 0 : _b.length);
+                const isEmptyResponse = !((_c = response.content) === null || _c === void 0 ? void 0 : _c.trim()) && !((_d = response.toolCalls) === null || _d === void 0 ? void 0 : _d.length);
                 if (isEmptyResponse) {
-                    // Do nothing, discard empty/whitespace-only responses
+                    malformedAttempts += 1;
+                    if (malformedAttempts < MAX_MALFORMED_RETRIES) {
+                        logger.warn(`ChatDriver: empty model response, retrying (${malformedAttempts}/${MAX_MALFORMED_RETRIES})`);
+                        iterations -= 1;
+                        continue;
+                    }
+                    logger.error('ChatDriver: empty model response after all retries');
+                    this.appendToHistory({
+                        role: 'assistant',
+                        content: 'Remote agent returned no response.',
+                    });
+                    return { reason: 'done' };
                 }
                 else if (isThinkingStep) {
-                    // Separate thinking message and tool call message
                     this.appendToHistory(Object.assign(Object.assign({}, response), { toolCalls: undefined, thinking: true }));
                     this.appendToHistory(Object.assign(Object.assign({}, response), { content: '' }));
                 }
                 else {
                     this.appendToHistory(response);
                 }
-                if (!((_f = response.toolCalls) === null || _f === void 0 ? void 0 : _f.length)) {
-                    // Terminal text response — done
+                if (!((_e = response.toolCalls) === null || _e === void 0 ? void 0 : _e.length)) {
                     break;
                 }
-                // Execute all tool calls for this iteration concurrently, then append results in order
-                // eslint-disable-next-line no-await-in-loop
-                const toolResults = yield Promise.all(response.toolCalls.map((tc) => __awaiter(this, void 0, void 0, function* () {
-                    const handler = this.toolHandlers[tc.name];
-                    if (!handler) {
-                        logger.warn(`ChatDriver: no handler registered for tool "${tc.name}"`);
-                        return { toolCallId: tc.id, content: `Unknown tool: ${tc.name}` };
-                    }
-                    try {
-                        const result = yield handler(tc.args, {
-                            requestInteraction: (componentName, data) => this.requestInteraction(componentName, data),
+                const [toolCalls, systemCalls] = response.toolCalls.reduce((acc, tc) => {
+                    if (tc.name === REQUEST_CONTINUATION_TOOL)
+                        acc[1].push(tc);
+                    else
+                        acc[0].push(tc);
+                    return acc;
+                }, [[], []]);
+                const executedById = new Map();
+                const unknownToolIds = new Set();
+                let anyRealToolExecuted = false;
+                let hitUnknownToolLimit = false;
+                if (toolCalls.length > 0) {
+                    // eslint-disable-next-line no-await-in-loop
+                    yield Promise.all(toolCalls.map((tc) => __awaiter(this, void 0, void 0, function* () {
+                        // Check for fold facade
+                        const fold = this.getFold(tc.name);
+                        if (fold) {
+                            this.consecutiveFoldOps += 1;
+                            if (this.consecutiveFoldOps > this.maxFoldOperations) {
+                                logger.warn(`ChatDriver: fold operation limit (${this.maxFoldOperations}) reached — injecting guidance`);
+                                executedById.set(tc.id, {
+                                    toolCallId: tc.id,
+                                    content: `You have opened and closed folds ${this.consecutiveFoldOps} times without calling any tools. Please call a specific tool to make progress, or respond to the user.`,
+                                });
+                                return;
+                            }
+                            const content = yield this.openFold(tc.name, fold, tc.args);
+                            executedById.set(tc.id, { toolCallId: tc.id, content });
+                            // Fold open/close does NOT count as a real iteration — decrement to compensate
+                            iterations -= 1;
+                            return;
+                        }
+                        // Check for close-fold tool
+                        if (tc.name.startsWith('close_') && this.foldStack.length > 0) {
+                            const topFoldName = this.foldStack[this.foldStack.length - 1].foldName;
+                            if (tc.name === `close_${topFoldName}`) {
+                                this.consecutiveFoldOps += 1;
+                                if (this.consecutiveFoldOps > this.maxFoldOperations) {
+                                    executedById.set(tc.id, {
+                                        toolCallId: tc.id,
+                                        content: `You have opened and closed folds ${this.consecutiveFoldOps} times without calling any tools. Please call a specific tool to make progress, or respond to the user.`,
+                                    });
+                                    return;
+                                }
+                                const content = this.closeFold();
+                                executedById.set(tc.id, { toolCallId: tc.id, content });
+                                iterations -= 1;
+                                return;
+                            }
+                        }
+                        // Regular tool — check if it's inside a fold and guide the model
+                        const handler = this.toolHandlers[tc.name];
+                        if (!handler) {
+                            const containingFold = this.findFoldContaining(tc.name);
+                            if (containingFold) {
+                                logger.debug(`ChatDriver: model called folded tool "${tc.name}" — guiding to open "${containingFold}"`);
+                                executedById.set(tc.id, {
+                                    toolCallId: tc.id,
+                                    content: `"${tc.name}" is not directly available. It is inside the "${containingFold}" fold. Call ${containingFold} first to access it.`,
+                                });
+                                // Guidance does not count as a real iteration or fold op
+                                iterations -= 1;
+                            }
+                            else {
+                                this.consecutiveUnknownToolCalls += 1;
+                                logger.warn(`ChatDriver: no handler registered for tool "${tc.name}" (${this.consecutiveUnknownToolCalls}/${DEFAULT_MAX_UNKNOWN_TOOL_CALLS}). Available tools: ${Object.keys(this.toolHandlers).join(', ') || '(none)'}`);
+                                executedById.set(tc.id, { toolCallId: tc.id, content: `Unknown tool: ${tc.name}` });
+                                unknownToolIds.add(tc.id);
+                                if (this.consecutiveUnknownToolCalls >= DEFAULT_MAX_UNKNOWN_TOOL_CALLS) {
+                                    hitUnknownToolLimit = true;
+                                }
+                            }
+                            return;
+                        }
+                        // Real tool execution
+                        try {
+                            const result = yield handler(tc.args, {
+                                requestInteraction: (componentName, data) => this.requestInteraction(componentName, data),
+                            });
+                            const content = typeof result === 'string' ? result : JSON.stringify(result);
+                            executedById.set(tc.id, { toolCallId: tc.id, content });
+                            anyRealToolExecuted = true;
+                        }
+                        catch (e) {
+                            logger.error(`ChatDriver tool "${tc.name}" failed:`, e);
+                            executedById.set(tc.id, {
+                                toolCallId: tc.id,
+                                content: `Tool error: ${e.message}`,
+                            });
+                            anyRealToolExecuted = true; // treat errors as real work for fold op counting
+                        }
+                    })));
+                }
+                // Reset counters whenever a real tool executes
+                if (anyRealToolExecuted) {
+                    this.consecutiveFoldOps = 0;
+                    this.consecutiveUnknownToolCalls = 0;
+                }
+                // Tag tool calls with fold UI metadata before appending results
+                const foldPath = this.foldStack.map((f) => f.foldName);
+                for (const tc of response.toolCalls) {
+                    if (tc.name === REQUEST_CONTINUATION_TOOL) {
+                        this.appendToHistory({
+                            role: 'tool',
+                            content: '',
+                            toolResult: { toolCallId: tc.id, content: HANDOFF_TOOL_RESULT_PLACEHOLDER },
                         });
-                        const content = typeof result === 'string' ? result : JSON.stringify(result);
-                        return { toolCallId: tc.id, content };
                     }
-                    catch (e) {
-                        logger.error(`ChatDriver tool "${tc.name}" failed:`, e);
-                        return { toolCallId: tc.id, content: `Tool error: ${e.message}` };
+                    else {
+                        const r = executedById.get(tc.id);
+                        if (r) {
+                            this.appendToHistory({ role: 'tool', content: '', toolResult: r });
+                        }
+                    }
+                }
+                // Back-patch foldEvent and foldPath onto the tool call message we just appended.
+                // The response was appended before execution — find it and annotate.
+                let tcMsgIdx = -1;
+                for (let i = this.history.length - 1; i >= 0; i -= 1) {
+                    if (this.history[i].role === 'assistant' && ((_f = this.history[i].toolCalls) === null || _f === void 0 ? void 0 : _f.length)) {
+                        tcMsgIdx = i;
+                        break;
                     }
-                })));
-                for (const result of toolResults) {
+                }
+                if (tcMsgIdx !== -1) {
+                    const tcMsg = this.history[tcMsgIdx];
+                    const availableToolNames = Object.keys(this.toolHandlers);
+                    const annotatedCalls = tcMsg.toolCalls.map((tc) => {
+                        var _a, _b, _c, _d;
+                        const isFoldOpen = !!this.getFold(tc.name) ||
+                            (
+                            // Was a fold facade at time of the call (now the tool set has changed)
+                            // — detect by checking if the result message indicated a fold open
+                            (_b = (_a = executedById.get(tc.id)) === null || _a === void 0 ? void 0 : _a.content) === null || _b === void 0 ? void 0 : _b.startsWith('Fold opened:'));
+                        const isFoldClose = (_d = (_c = executedById.get(tc.id)) === null || _c === void 0 ? void 0 : _c.content) === null || _d === void 0 ? void 0 : _d.startsWith('Fold closed:');
+                        const isUnknown = unknownToolIds.has(tc.id);
+                        return Object.assign(Object.assign({}, tc), { foldEvent: isFoldOpen
+                                ? 'open'
+                                : isFoldClose
+                                    ? 'close'
+                                    : undefined, 
+                            // Use the fold path that was active at the START of this iteration (before any opens/closes)
+                            foldPath: !isFoldOpen && !isFoldClose && foldPath.length > 0 ? foldPath : undefined, unknown: isUnknown || undefined, availableTools: isUnknown ? availableToolNames : undefined });
+                    });
+                    this.history[tcMsgIdx] = Object.assign(Object.assign({}, tcMsg), { toolCalls: annotatedCalls });
+                    this.dispatchEvent(new CustomEvent('history-updated', {
+                        detail: this.history,
+                    }));
+                }
+                if (hitUnknownToolLimit) {
+                    logger.error(`ChatDriver: unknown-tool limit (${DEFAULT_MAX_UNKNOWN_TOOL_CALLS}) reached — stopping`);
                     this.appendToHistory({
-                        role: 'tool',
-                        content: '',
-                        toolResult: result,
+                        role: 'assistant',
+                        content: "I'm sorry, I repeatedly tried to use tools that don't exist. Please check your agent configuration or try rephrasing your request.",
                     });
+                    return { reason: 'done' };
+                }
+                const firstContinuation = systemCalls[0];
+                if (firstContinuation) {
+                    const { summary, remaining_task: remainingTask } = firstContinuation.args;
+                    return { reason: 'agent-handoff', summary, remainingTask };
                 }
-                // Next iteration sends an empty string — the tool results are in history
                 currentInput = '';
             }
             if (iterations >= this.maxToolIterations) {
                 logger.warn('ChatDriver: reached max tool iterations, stopping');
+                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' };
         });
     }
     appendToHistory(message) {
-        this.history = [...this.history, message];
+        const tagged = this.activeAgentName
+            ? Object.assign(Object.assign({}, message), { agentName: this.activeAgentName }) : message;
+        this.history = [...this.history, tagged];
         this.dispatchEvent(new CustomEvent('history-updated', {
             detail: this.history,
         }));