@genesislcap/ai-assistant 14.419.2 → 14.421.0

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

@@ -1,16 +1,31 @@
 import type {
   AIProvider,
   ChatAttachment,
+  ChatDriverResult,
   ChatMessage,
   ChatRequestOptions,
+  ChatToolCall,
   ChatToolDefinition,
   ChatToolHandlers,
 } from '@genesislcap/foundation-ai';
 import { MalformedFunctionCallError } from '@genesislcap/foundation-ai';
+import type { AgentConfig } from '../../config/config';
 import { logger } from '../../utils/logger';
+import { TOOL_FOLD_SYMBOL, type ToolFold } from '../../utils/tool-fold';
+import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
 
 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.';
 
 /**
  * Event emitted when the chat history is updated (new message appended).
@@ -19,6 +34,12 @@ const MAX_MALFORMED_RETRIES = 2;
  */
 export type ChatHistoryUpdatedEvent = CustomEvent<ReadonlyArray<ChatMessage>>;
 
+interface FoldStackFrame {
+  foldName: string;
+  previousDefinitions: ChatToolDefinition[];
+  previousHandlers: ChatToolHandlers;
+}
+
 /**
  * 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`.
@@ -29,7 +50,7 @@ export type ChatHistoryUpdatedEvent = CustomEvent<ReadonlyArray<ChatMessage>>;
  *
  * @beta
  */
-export class ChatDriver extends EventTarget {
+export class ChatDriver extends EventTarget implements AiDriver {
   private history: ChatMessage[] = [];
   private busy = false;
   private pendingInteractions = new Map<
@@ -37,26 +58,159 @@ export class ChatDriver extends EventTarget {
     { resolve: (value: any) => void; reject: (reason?: any) => void }
   >();
 
+  private systemPrompt?: string;
+  private toolDefinitions: ChatToolDefinition[];
+  private toolHandlers: ChatToolHandlers;
+  private primerHistory?: ChatMessage[];
+  private activeAgentName?: string;
+  /**
+   * When set (e.g. by OrchestratingDriver), applied only to the conversation slice
+   * sent to the model — stored `history` stays unchanged for UI and logging.
+   */
+  private providerHistoryTransform?: (history: ChatMessage[]) => ChatMessage[];
+
+  /** Stack of fold frames — grows when a fold opens, shrinks when it closes. */
+  private foldStack: FoldStackFrame[] = [];
+  /** Consecutive fold open/close ops without a real tool call. Reset on real tool execution. */
+  private consecutiveFoldOps = 0;
+  /** Consecutive unknown-tool calls without a real tool call. Reset on real tool execution. */
+  private consecutiveUnknownToolCalls = 0;
+  private readonly maxFoldOperations: number;
+
   constructor(
     private readonly aiProvider: AIProvider,
-    private readonly toolHandlers: ChatToolHandlers = {},
-    private readonly toolDefinitions: ChatToolDefinition[] = [],
-    private readonly systemPrompt?: string,
-    private readonly primerHistory?: ChatMessage[],
+    toolHandlers: ChatToolHandlers = {},
+    toolDefinitions: ChatToolDefinition[] = [],
+    systemPrompt?: string,
+    primerHistory?: ChatMessage[],
     private readonly maxToolIterations: number = DEFAULT_MAX_TOOL_ITERATIONS,
+    maxFoldOperations: number = DEFAULT_MAX_FOLD_OPERATIONS,
   ) {
     super();
-    if (!systemPrompt) {
-      logger.error(
-        'ChatDriver: no systemPrompt provided. The assistant will have no instructions — set the systemPrompt property on foundation-ai-assistant.',
-      );
-    }
+    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: AgentConfig): void {
+    this.systemPrompt = config.systemPrompt;
+    this.toolDefinitions = config.toolDefinitions ?? [];
+    this.toolHandlers = config.toolHandlers ?? {};
+    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?: (history: ChatMessage[]) => ChatMessage[]): void {
+    this.providerHistoryTransform = transform;
   }
 
   getHistory(): ReadonlyArray<ChatMessage> {
     return this.history;
   }
 
+  getRawHistory(): readonly ChatMessage[] {
+    return this.history;
+  }
+
+  /** Returns the current fold stack names for debugging. */
+  getActiveFoldNames(): string[] {
+    return this.foldStack.map((f) => f.foldName);
+  }
+
+  async getSuggestions(
+    history: ChatMessage[],
+    prompt: string,
+    count: number,
+    allAgentInfo?: AllAgentSummary[],
+  ): Promise<string[]> {
+    if (!this.aiProvider.prompt) {
+      logger.warn('ChatDriver: AIProvider does not implement prompt()');
+      return [];
+    }
+
+    let agentContext = '';
+    let toolContext = '';
+
+    if (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: string;
+    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) =>
+          (m.role === 'user' || m.role === 'assistant') &&
+          !m.toolCalls?.length &&
+          !m.thinking &&
+          !!m.content?.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 = await this.aiProvider.prompt!(message, { systemPrompt });
+    return text
+      .split('\n')
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+
   isBusy(): boolean {
     return this.busy;
   }
@@ -87,11 +241,12 @@ export class ChatDriver extends EventTarget {
   public resolveInteraction(interactionId: string, result: any): void {
     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) => m.interaction?.interactionId === interactionId);
-      if (msg?.interaction) {
-        msg.interaction.resolved = true;
+      const idx = this.history.findIndex((m) => m.interaction?.interactionId === interactionId);
+      if (idx !== -1) {
+        this.history[idx] = {
+          ...this.history[idx],
+          interaction: { ...this.history[idx].interaction!, resolved: result },
+        };
         this.dispatchEvent(
           new CustomEvent<ReadonlyArray<ChatMessage>>('history-updated', {
             detail: this.history,
@@ -111,63 +266,253 @@ export class ChatDriver extends EventTarget {
    */
   public loadHistory(messages: ChatMessage[]): void {
     this.history = [...messages];
+    this.dispatchEvent(
+      new CustomEvent<ReadonlyArray<ChatMessage>>('history-updated', {
+        detail: this.history,
+      }),
+    );
   }
 
-  async sendMessage(userInput: string, attachments?: ChatAttachment[]): Promise<void> {
-    if (this.busy || (!userInput.trim() && !attachments?.length)) return;
+  async sendMessage(userInput: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult> {
+    if (this.busy || (!userInput.trim() && !attachments?.length)) 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 {
-      await this.runToolLoop(userInput, attachments);
+      return await 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;
     }
   }
 
-  private async runToolLoop(userInput: string, attachments?: ChatAttachment[]): Promise<void> {
-    const baseOptions: ChatRequestOptions = {
-      systemPrompt: this.systemPrompt,
-      tools: this.toolDefinitions.length ? this.toolDefinitions : undefined,
-    };
+  /**
+   * Continue the tool loop from current history without appending a new user message.
+   * Used by OrchestratingDriver after an agent handoff.
+   */
+  async continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult> {
+    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 await 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;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Fold mechanics
+  // ---------------------------------------------------------------------------
+
+  /** Extract ToolFold metadata from a handler, or undefined if it isn't a fold facade. */
+  private getFold(toolName: string): ToolFold | undefined {
+    const handler = this.toolHandlers[toolName];
+    return handler ? ((handler as any)[TOOL_FOLD_SYMBOL] as ToolFold | undefined) : 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.
+   */
+  private findFoldContaining(toolName: string, handlers?: ChatToolHandlers): string | null {
+    const source = handlers ?? this.toolHandlers;
+    for (const [, handler] of Object.entries(source)) {
+      const fold = (handler as any)[TOOL_FOLD_SYMBOL] as ToolFold | undefined;
+      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.
+   */
+  private applyFoldToolSet(fold: ToolFold, foldName: string): void {
+    const closeToolName = `close_${foldName}`;
+    const newDefs: ChatToolDefinition[] = [];
+    const newHandlers: ChatToolHandlers = {};
+
+    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] = async (): Promise<string> => this.closeFold();
+
+    this.toolDefinitions = newDefs;
+    this.toolHandlers = newHandlers;
+  }
+
+  /** Open a fold: push a stack frame, swap the tool set, return the response message. */
+  private openFold(
+    foldName: string,
+    fold: ToolFold,
+    args: Record<string, unknown>,
+  ): Promise<string> {
+    // 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] as Record<string, unknown>)
+            : {};
+        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);
+  }
+
+  private pushFoldFrame(foldName: string): void {
+    this.foldStack.push({
+      foldName,
+      previousDefinitions: [...this.toolDefinitions],
+      previousHandlers: { ...this.toolHandlers },
+    });
+  }
+
+  /** Close the top fold: pop the stack frame, restore the previous tool set. */
+  private closeFold(): string {
+    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. */
+  private buildFoldSystemPromptSuffix(): string {
+    // Collect fold facades from the current handler map
+    const activeFolds: ToolFold[] = [];
+    for (const handler of Object.values(this.toolHandlers)) {
+      const fold = (handler as any)[TOOL_FOLD_SYMBOL] as ToolFold | undefined;
+      if (fold) activeFolds.push(fold);
+    }
+
+    if (activeFolds.length === 0 && this.foldStack.length === 0) return '';
+
+    const parts: string[] = ['\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
+  // ---------------------------------------------------------------------------
+
+  private async runToolLoop(
+    userInput: string,
+    attachments?: ChatAttachment[],
+    transientPrimer?: ChatMessage[],
+  ): Promise<ChatDriverResult> {
+    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.',
+      );
+    }
 
-    // History has the user message at the end — pass everything before it as history,
-    // and the user input as the userMessage argument.
     let currentInput = userInput;
     let currentAttachments: ChatAttachment[] | undefined = 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 = this.primerHistory ?? [];
-      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 = [...(this.primerHistory ?? []), ...(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
-          ? `${baseOptions.systemPrompt ?? ''}\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;
+          ? `${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: ChatRequestOptions = {
-        ...baseOptions,
         systemPrompt,
+        // Strip fold-only properties (foldEvent, foldPath) before sending to provider
+        tools: this.toolDefinitions.length ? this.toolDefinitions : undefined,
         attachments: currentAttachments,
       };
 
@@ -182,7 +527,7 @@ export class ChatDriver extends EventTarget {
             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');
@@ -191,20 +536,32 @@ export class ChatDriver extends EventTarget {
             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
+      currentAttachments = undefined;
 
       const isThinkingStep = response.content && response.toolCalls?.length;
       const isEmptyResponse = !response.content?.trim() && !response.toolCalls?.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({ ...response, toolCalls: undefined, thinking: true });
         this.appendToHistory({ ...response, content: '' });
       } else {
@@ -212,52 +569,222 @@ export class ChatDriver extends EventTarget {
       }
 
       if (!response.toolCalls?.length) {
-        // Terminal text response — done
         break;
       }
 
-      // Execute all tool calls for this iteration concurrently, then append results in order
-      // eslint-disable-next-line no-await-in-loop
-      const toolResults = await Promise.all(
-        response.toolCalls.map(async (tc) => {
-          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 = await handler(tc.args, {
-              requestInteraction: (componentName, data) =>
-                this.requestInteraction(componentName, data),
-            });
-            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 as Error).message}` };
-          }
-        }),
+      const [toolCalls, systemCalls] = response.toolCalls.reduce<[ChatToolCall[], ChatToolCall[]]>(
+        (acc, tc) => {
+          if (tc.name === REQUEST_CONTINUATION_TOOL) acc[1].push(tc);
+          else acc[0].push(tc);
+          return acc;
+        },
+        [[], []],
       );
 
-      for (const result of toolResults) {
+      const executedById = new Map<string, { toolCallId: string; content: string }>();
+      const unknownToolIds = new Set<string>();
+      let anyRealToolExecuted = false;
+      let hitUnknownToolLimit = false;
+
+      if (toolCalls.length > 0) {
+        // eslint-disable-next-line no-await-in-loop
+        await Promise.all(
+          toolCalls.map(async (tc) => {
+            // 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 = await 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 = await 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 as Error).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 },
+          });
+        } 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' && this.history[i].toolCalls?.length) {
+          tcMsgIdx = i;
+          break;
+        }
+      }
+      if (tcMsgIdx !== -1) {
+        const tcMsg = this.history[tcMsgIdx];
+        const availableToolNames = Object.keys(this.toolHandlers);
+        const annotatedCalls = tcMsg.toolCalls!.map((tc) => {
+          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
+            executedById.get(tc.id)?.content?.startsWith('Fold opened:');
+          const isFoldClose = executedById.get(tc.id)?.content?.startsWith('Fold closed:');
+          const isUnknown = unknownToolIds.has(tc.id);
+          return {
+            ...tc,
+            foldEvent: isFoldOpen
+              ? ('open' as const)
+              : isFoldClose
+                ? ('close' as const)
+                : 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] = { ...tcMsg, toolCalls: annotatedCalls };
+        this.dispatchEvent(
+          new CustomEvent<ReadonlyArray<ChatMessage>>('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 as {
+          summary: string;
+          remaining_task: string;
+        };
+        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' };
   }
 
   private appendToHistory(message: ChatMessage): void {
-    this.history = [...this.history, message];
+    const tagged: ChatMessage = this.activeAgentName
+      ? { ...message, agentName: this.activeAgentName }
+      : message;
+    this.history = [...this.history, tagged];
     this.dispatchEvent(
       new CustomEvent<ReadonlyArray<ChatMessage>>('history-updated', {
         detail: this.history,