@genesislcap/ai-assistant 15.24.1 → 15.25.1

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

@@ -4,13 +4,19 @@ import { NOOP_ACTIVITY_BUS } from '../../channel/ai-activity-bus';
 import { resolveChatProvider } from '../../config/validate-providers';
 import { clearSession, getMetaEvents, mergeMetaEvents, recordMetaEvent, recordTurnError, recordTurnRetry, } from '../../state/debug-event-log';
 import { createInteractionContext, } from '../../state/interaction-context';
+import { generateSuggestions } from '../../suggestions/generate-suggestions';
 import { applyCondensation, condenseForPersistence, } from '../../utils/condense-history';
 import { estimatePreambleTokens, estimateRequestTokens, } from '../../utils/context-tokens';
 import { applyHistoryCap, buildCompactionSummaryPrompt, planCompaction, normalizeForProvider, } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
+import { resolveTurnInput } from '../../utils/resolve-turn-input';
 import { messageUsage, sumUsage } from '../../utils/sum-usage';
-import { TOOL_FOLD_SYMBOL } from '../../utils/tool-fold';
-import { TURN_FAILURE_EXITS } from './turn-failures';
+import { AgentSession } from '../agent-session/agent-session';
+import { DEFAULT_MAX_FOLD_OPERATIONS, DEFAULT_MAX_TOOL_ITERATIONS, DEFAULT_MAX_TURN_SNAPSHOTS, DEFAULT_MAX_UNKNOWN_TOOL_CALLS, EMPTY_RESPONSE_NUDGE, HANDOFF_TOOL_RESULT_PLACEHOLDER, HARVESTED_SUBAGENT_EVENTS, MALFORMED_CALL_NUDGE, MAX_EMPTY_RESPONSE_RETRIES, MAX_MALFORMED_RETRIES, MAX_SETUP_TRANSPORT_RETRIES, MAX_STALE_TOOL_CALLS, REQUEST_CONTINUATION_TOOL, } from './chat-driver.constants';
+import { FoldController } from './fold-controller';
+import { TURN_FAILURE_EXITS, turnDone } from './turn-failures';
+/** Re-exported so `from './chat-driver'` keeps resolving these. */
+export { EMPTY_RESPONSE_NUDGE, MALFORMED_CALL_NUDGE, REQUEST_CONTINUATION_TOOL, } from './chat-driver.constants';
 /**
  * Lift the reportable facts off a {@link BudgetExhaustedError}, or `undefined`
  * when it carries none.
@@ -71,74 +77,6 @@ const budgetDetailOf = (e) => {
         return undefined;
     return Object.assign(Object.assign({ budgetUsd: e.budgetUsd, spentUsd: e.spentUsd, vendorLabel: e.vendorLabel }, (vendor ? { vendor } : {})), (e.otherVendorAvailable != null ? { otherVendorAvailable: e.otherVendorAvailable } : {}));
 };
-const DEFAULT_MAX_TOOL_ITERATIONS = 50;
-const DEFAULT_MAX_FOLD_OPERATIONS = 5;
-// TODO: dedup system prompts in-memory to allow raising this cap much higher.
-// Each TurnSnapshot stores the full resolved `systemPrompt`, so the buffer's
-// memory cost scales with cap × prompt size — a stable agent repeats a multi-KB
-// prompt every turn. `getDebugLog` already dedups identical consecutive prompts
-// at export time (`<repeated — identical to turn N>`); applying the same dedup
-// at capture time (store the prompt only when it changes, back-reference
-// otherwise) would make snapshots nearly as cheap as meta events and let this
-// cap reach thousands for full-session capture without the memory blowup.
-const DEFAULT_MAX_TURN_SNAPSHOTS = 400;
-const DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5;
-// 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;
-/**
- * Framed-tail nudge added to a retry after a MALFORMED tool call.
- *
- * Exported so tests can assert placement (framed tail, never the system prompt) without pinning
- * the wording — the copy is a prompt, and a prompt should be free to improve.
- *
- * @beta
- */
-export const MALFORMED_CALL_NUDGE = 'IMPORTANT: Use only the structured function-call API to invoke tools. Do not write Python code or use Python-style syntax to call tools.';
-/**
- * Framed-tail nudge added to a retry after an EMPTY response.
- *
- * Rewritten in GENC-1573. The previous copy ("You must respond to the user's message. Call the
- * appropriate tool or provide a text response") told a model that had just returned nothing to
- * respond, without naming the one exit available to an agent that genuinely cannot act: saying so.
- * Across nine failures in the measured session it changed nothing — all 29 attempts came back at
- * 8–9 output tokens — and most of those were on a tool-less agent, for which "call the appropriate
- * tool" is not an option at all. This version names the honest answer explicitly.
- *
- * @beta
- */
-export const EMPTY_RESPONSE_NUDGE = "IMPORTANT: Your previous attempt returned nothing at all, which is never a valid response. Answer the user's last message now, in prose — even if all you can honestly say is that you cannot help with it and why. If a tool is the right way to answer, call it. Do not return an empty response.";
-// 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;
-/**
- * Sub-agent meta events worth folding into the parent's debug timeline: the
- * per-attempt and per-failure signals that do NOT otherwise surface in the
- * sub-agent's (now hoisted) messages — a retried-away malformed/empty attempt
- * produces no message, and the stale-vs-hallucinated/streak diagnostics live only
- * on the event. High-volume, message-derivable events (turn.start/turn.end,
- * provider.selected, context.updated) are intentionally excluded: read the
- * sub-agent's hoisted messages for model/tokens/cost and turn-by-turn activity.
- * See `ChatDriver.invokeSubAgent`.
- */
-const HARVESTED_SUBAGENT_EVENTS = new Set([
-    'turn.retry',
-    'turn.error',
-    'tool.failed',
-    'tool.unresolved',
-]);
-/** 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.';
 export class ChatDriver extends EventTarget {
     constructor(providerRegistry, config = {}) {
         super();
@@ -201,10 +139,18 @@ export class ChatDriver extends EventTarget {
          * (`callPhaseEpoch < currentPhaseEpoch`), with an `agentEnd` backstop.
          */
         this.currentPhaseEpoch = 0;
-        /** 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;
+        /** Tool folds: the open-fold stack, the no-progress counter, and the tool-surface swap. */
+        this.folds = new FoldController({
+            getDefinitions: () => this.toolDefinitions,
+            setDefinitions: (defs) => {
+                this.toolDefinitions = defs;
+            },
+            getHandlers: () => this.toolHandlers,
+            setHandlers: (handlers) => {
+                this.toolHandlers = handlers;
+            },
+            handlerContext: (activeToolCallId) => this.buildHandlerContext(activeToolCallId),
+        });
         /** Consecutive unknown-tool calls without a real tool call. Reset on real tool execution. */
         this.consecutiveUnknownToolCalls = 0;
         /**
@@ -304,6 +250,19 @@ export class ChatDriver extends EventTarget {
          * picked up on the next turn.
          */
         this.resolvedStatusCache = new Map();
+        /**
+         * The stateful-agent contract for this driver: active agent, user pin, flow lock, restored
+         * state, and the `onActivate` / `onDeactivate` hooks (§7.1).
+         *
+         * **Public because `OrchestratingDriver` reaches through to it.** The orchestrator decorates a
+         * config before installing it (the cross-agent continuation tool), so it cannot route through
+         * {@link ChatDriver.activateAgent} and must drive the session itself — and one shared session is
+         * the point: two would let `getActiveAgent()` disagree between the outer and inner driver.
+         * `@internal` rather than private so that reach is legal without six delegating one-liners.
+         *
+         * @internal
+         */
+        this.agentSession = new AgentSession({ sessionKey: () => this.sessionKey });
         /**
          * A provider refusal was observed this turn, so the tool loop must not call the model again
          * (GENC-1506).
@@ -330,10 +289,11 @@ export class ChatDriver extends EventTarget {
          * Reset per turn alongside `budgetWallDetail`.
          */
         this.budgetWallViaSubAgent = false;
-        const { toolHandlers = {}, toolDefinitions = [], systemPrompt, primerHistory, maxToolIterations = DEFAULT_MAX_TOOL_ITERATIONS, maxFoldOperations = DEFAULT_MAX_FOLD_OPERATIONS, condenseBatchCalls = 1, maxTurnSnapshots = DEFAULT_MAX_TURN_SNAPSHOTS, sessionKey = '', activityBus = NOOP_ACTIVITY_BUS, budgetExhaustedMessage, providerRefusedMessage, } = config;
+        const { toolHandlers = {}, toolDefinitions = [], systemPrompt, primerHistory, maxToolIterations = DEFAULT_MAX_TOOL_ITERATIONS, maxFoldOperations = DEFAULT_MAX_FOLD_OPERATIONS, condenseBatchCalls = 1, maxTurnSnapshots = DEFAULT_MAX_TURN_SNAPSHOTS, sessionKey = '', deferAgentRelease = false, activityBus = NOOP_ACTIVITY_BUS, budgetExhaustedMessage, providerRefusedMessage, } = config;
         this.maxToolIterations = maxToolIterations;
         this.condenseBatchCalls = condenseBatchCalls;
         this.sessionKey = sessionKey;
+        this.deferAgentRelease = deferAgentRelease;
         this.activityBus = activityBus;
         this.budgetExhaustedMessageOverride = budgetExhaustedMessage;
         this.providerRefusedMessageOverride = providerRefusedMessage;
@@ -393,20 +353,32 @@ export class ChatDriver extends EventTarget {
      * timeout), which also stamps history and reverts the chat-input override.
      */
     dispose() {
-        var _a;
-        this.lifecycleController.abort(new DOMException('AI assistant driver disposed', 'AbortError'));
-        // Drop any live interaction contexts (GENC-1390). Normally empty at teardown
-        // (a context is created and destroyed with its pending interaction, and dispose
-        // is not reached mid-interaction); disposed defensively so a stray context can
-        // never leak an open socket/timer.
-        for (const handle of this.interactionContexts.values())
-            handle.dispose();
-        this.interactionContexts.clear();
-        // Detach from the provider registry so the long-lived registry doesn't pin
-        // this driver (and its closure) after teardown. Guard-cleared so a second
-        // dispose is a no-op, matching this method's idempotent contract.
-        (_a = this.unsubscribeRegistry) === null || _a === void 0 ? void 0 : _a.call(this);
-        this.unsubscribeRegistry = undefined;
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            // Everything up to the `await` below runs SYNCHRONOUSLY on the call, and that is the
+            // contract: callers rely on `dispose()` having detached listeners by the time it returns —
+            // `chat-driver.test.ts`'s sub-agent listener-leak case asserts it directly, and the host
+            // fires this and forgets (`main.ts`, `void old.dispose()`). Awaiting anything first opened a
+            // window in which a disposed driver was still subscribed to the provider registry.
+            this.lifecycleController.abort(new DOMException('AI assistant driver disposed', 'AbortError'));
+            // Drop any live interaction contexts (GENC-1390). Normally empty at teardown
+            // (a context is created and destroyed with its pending interaction, and dispose
+            // is not reached mid-interaction); disposed defensively so a stray context can
+            // never leak an open socket/timer.
+            for (const handle of this.interactionContexts.values())
+                handle.dispose();
+            this.interactionContexts.clear();
+            // Detach from the provider registry so the long-lived registry doesn't pin
+            // this driver (and its closure) after teardown. Guard-cleared so a second
+            // dispose is a no-op, matching this method's idempotent contract.
+            (_a = this.unsubscribeRegistry) === null || _a === void 0 ? void 0 : _a.call(this);
+            this.unsubscribeRegistry = undefined;
+            // Lifecycle hooks last, and awaited so a caller can know they finished. Idempotent, so the
+            // orchestrated path — which fires them through the shared session BEFORE getting here, to
+            // keep the pre-GENC-1580 order where `onDeactivate` saw a live driver — costs a no-op.
+            // Returning a promise is within `AiDriver.dispose`'s declared `void | Promise<void>`.
+            yield this.agentSession.dispose();
+        });
     }
     /**
      * Stop the current turn (user "stop" button). Aborts the in-flight provider
@@ -458,21 +430,6 @@ export class ChatDriver extends EventTarget {
         }
         return { reason: 'done' };
     }
-    /**
-     * Build the `done` loop result, carrying the typed failure reason when the turn
-     * bailed (PTC-0). The discriminant stays `'done'` either way — the same value a
-     * clean turn returns — so consumers matching on `reason === 'done'` are unchanged;
-     * `failureReason` is simply present on a failure and absent on success. Omitted
-     * (rather than set to `undefined`) so a happy-path result stays byte-identical to
-     * the historical `{ reason: 'done' }`.
-     */
-    turnDone(failureReason, budget, providerRefused) {
-        if (!failureReason)
-            return { reason: 'done' };
-        // Both payloads are omitted rather than set to `undefined`, so a failure that carries neither has
-        // a shape unchanged for a consumer that structurally compares it.
-        return Object.assign(Object.assign({ reason: 'done', failureReason }, (budget ? { budget } : {})), (providerRefused ? { providerRefused } : {}));
-    }
     /**
      * End the turn on a terminal failure: fail upward when this driver is a sub-agent, speak
      * to the user when it is not, and hand the reason to the caller either way.
@@ -500,7 +457,7 @@ export class ChatDriver extends EventTarget {
         else {
             this.appendDriverNotice((_a = overrides === null || overrides === void 0 ? void 0 : overrides.copy) !== null && _a !== void 0 ? _a : exit.copy);
         }
-        return this.turnDone(exit.resultReason, overrides === null || overrides === void 0 ? void 0 : overrides.budget, overrides === null || overrides === void 0 ? void 0 : overrides.providerRefused);
+        return turnDone(exit.resultReason, overrides === null || overrides === void 0 ? void 0 : overrides.budget, overrides === null || overrides === void 0 ? void 0 : overrides.providerRefused);
     }
     /**
      * Terminal budget outcome for a wall hit **outside** the tool loop — today,
@@ -573,7 +530,7 @@ export class ChatDriver extends EventTarget {
             isSubAgent: this.isSubAgent,
         });
         this.appendDriverNotice(this.budgetExhaustedBubble(e));
-        return this.turnDone('budget-exhausted', budgetDetailOf(e));
+        return turnDone('budget-exhausted', budgetDetailOf(e));
     }
     /**
      * The sentence shown when the upstream provider refuses (GENC-1506).
@@ -630,8 +587,68 @@ export class ChatDriver extends EventTarget {
         return Object.assign(Object.assign({ failureReason }, (vendor ? { vendor } : {})), (budget ? { budget } : {}));
     }
     /**
-     * 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.
+     * Make `config` the active agent, firing its lifecycle hooks — `onDeactivate` on the outgoing
+     * agent, then `onActivate` on this one — before installing it.
+     *
+     * This is the entry point a host should use. {@link ChatDriver.applyAgent} installs a config
+     * *without* firing hooks, which is right for the two callers that need it (the orchestrator,
+     * which fires them through the shared session, and `invokeSubAgent`, where a child's config is
+     * not an activation) and wrong for everyone else.
+     *
+     * @beta
+     */
+    activateAgent(config) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.agentSession.activate(config);
+            this.applyAgent(config);
+        });
+    }
+    /**
+     * {@inheritDoc AiDriver.getActiveAgent}
+     *
+     * @beta
+     */
+    getActiveAgent() {
+        return this.agentSession.getActive();
+    }
+    /** {@inheritDoc AiDriver.primeRestoredAgentState} */
+    primeRestoredAgentState(snapshots) {
+        this.agentSession.primeRestoredStates(snapshots);
+    }
+    /**
+     * Record the sticky agent pin. See {@link AiDriver.setPinnedAgent} for the contract.
+     *
+     * Recorded, not acted on: this driver has one agent and nothing to route between, so a pin
+     * changes no behaviour here. It is still honoured as state, because the session outlives the
+     * question of which driver is holding it — a host that pins before an orchestrator is built
+     * would otherwise lose the pick.
+     *
+     * @beta
+     */
+    setPinnedAgent(name) {
+        this.agentSession.setPinned(name);
+    }
+    /**
+     * Record the transient flow lock. See {@link AiDriver.setFlowOwner} for the contract.
+     *
+     * Recorded, not acted on, for the same reason as {@link ChatDriver.setPinnedAgent}.
+     *
+     * @beta
+     */
+    setFlowOwner(name) {
+        this.agentSession.setFlowOwner(name);
+    }
+    /**
+     * Install `config` as the active agent **without firing lifecycle hooks**.
+     *
+     * Prefer {@link ChatDriver.activateAgent} unless you are deliberately skipping the hooks. Two
+     * callers are: `OrchestratingDriver`, which fires them through the shared
+     * {@link ChatDriver.agentSession} and then installs a decorated config, and `invokeSubAgent`,
+     * where the child driver's config is a tool surface rather than an activation.
+     *
+     * Renamed to `installAgent` in a follow-up (GENC-1580) — see `docs/migration-GENC-1580.md`.
+     * Until then the name says less than it should, so do not add a third caller to this path
+     * without checking which of the two above it resembles.
      */
     applyAgent(config) {
         var _a, _b, _c;
@@ -689,9 +706,10 @@ export class ChatDriver extends EventTarget {
         if (typeof config.provider === 'string') {
             this.resolveProviderByName(config.provider, config.name);
         }
-        // Reset fold state when agent changes — each specialist starts fresh
-        this.foldStack = [];
-        this.consecutiveFoldOps = 0;
+        // Reset fold state when agent changes — each specialist starts fresh, and an unclosed fold
+        // must not survive into the next agent: its frame holds the PREVIOUS agent's tool surface,
+        // which `close()` would restore over the incoming one.
+        this.folds.reset();
         // Forget the previous agent's tools — "previously available" is scoped to
         // the current activation, so a stateful agent accumulates its tools across
         // states while a swap to a different specialist starts clean.
@@ -827,20 +845,6 @@ export class ChatDriver extends EventTarget {
             return status;
         });
     }
-    /**
-     * Resolve a per-turn config input that is either a static value or a function
-     * of the turn context — the value-or-resolver shape shared by `provider`,
-     * `temperature`, and `toolChoice`. Returns undefined when the input is unset.
-     */
-    resolveTurnInput(input, ctx) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (input === undefined)
-                return undefined;
-            return typeof input === 'function'
-                ? input(ctx)
-                : input;
-        });
-    }
     /**
      * Returns the early-stop result set by `completeSubAgent`, if any.
      * Called by a parent `ChatDriver` after running this instance as a sub-agent.
@@ -886,6 +890,22 @@ export class ChatDriver extends EventTarget {
     getAgentReleaseRequested() {
         return this.agentReleaseRequested;
     }
+    /**
+     * Act on a `releaseAgent` call from a tool handler: fire `onDeactivate` and drop the flow lock,
+     * so the next turn starts clean and the persister does not serialize a flow that is over.
+     *
+     * No-op when the owner handles release ({@link ChatDriverConfig.deferAgentRelease}). The flag is
+     * cleared here rather than only at the next `sendMessage`, so the signal cannot be acted on twice
+     * and release a later agent that never asked.
+     */
+    releaseIfRequested() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.deferAgentRelease || !this.agentReleaseRequested)
+                return;
+            this.agentReleaseRequested = false;
+            yield this.agentSession.release();
+        });
+    }
     /**
      * Return the per-turn snapshots captured so far. Used by the host's debug
      * log exporter to show what the LLM saw on each turn — system prompt, tool
@@ -1065,7 +1085,7 @@ export class ChatDriver extends EventTarget {
     }
     /** Returns the current fold stack names for debugging. */
     getActiveFoldNames() {
-        return this.foldStack.map((f) => f.foldName);
+        return this.folds.activeNames();
     }
     /**
      * The transcript as it should be **stored**: every tool payload the model has already stopped
@@ -1087,106 +1107,18 @@ export class ChatDriver extends EventTarget {
     getHistoryForPersistence() {
         return condenseForPersistence([...this.history], this.condensePolicies);
     }
+    /**
+     * {@inheritDoc AiDriver.getSuggestions}
+     *
+     * @beta
+     */
     getSuggestions(history, prompt, count, allAgentInfo) {
         return __awaiter(this, void 0, void 0, function* () {
-            // Suggestions are an out-of-turn UI helper, not bound to any single agent —
-            // always run against the registry default. Best-effort: a default with no
-            // `prompt()` just means no suggestions, not a hard error.
-            const defaultProvider = this.providerRegistry.default();
-            if (!defaultProvider.prompt) {
-                logger.warn('ChatDriver: default AI provider 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}.` : '';
-            }
-            // System prompt is intentionally short: it sets the role only. Concrete
-            // instructions live in the user message *after* the transcript so the
-            // immediately-preceding context for the model is "here is data, now do X"
-            // rather than "here is a dialogue, continue it". This matters for Anthropic
-            // — without it, Claude reads the transcript as an in-progress conversation
-            // and produces a normal assistant turn instead of a list of suggestions.
-            const systemPrompt = 'You generate suggested prompts that a user could send to an AI assistant. ' +
-                'You never continue the conversation or roleplay as the assistant.';
-            const capabilitiesBlock = agentContext || toolContext
-                ? `\n\n<capabilities>\n${[agentContext, toolContext].filter(Boolean).join('\n')}\n</capabilities>\nSuggestions must only cover what the agent is capable of. Do not suggest anything outside these capabilities.`
-                : '';
-            const guidanceBlock = prompt ? `\n\nAdditional guidance: "${prompt}"` : '';
-            let userMessage;
-            if (history.length === 0) {
-                userMessage =
-                    `Generate exactly ${count} brief starter prompts to show a user what an AI assistant can do. ` +
-                        `Phrase each one as the user would write it. 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").` +
-                        capabilitiesBlock +
-                        guidanceBlock +
-                        `\n\nOutput format (strict):\n` +
-                        `- Exactly ${count} lines.\n` +
-                        `- One suggestion per line.\n` +
-                        `- No numbering, bullets, markdown, emojis, code blocks, or quotes around the suggestion.\n` +
-                        `- No preamble, headings, summary, or commentary before or after the list.`;
-            }
-            else {
-                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');
-                userMessage =
-                    `<conversation_history>\n${conversationContext}\n</conversation_history>\n\n` +
-                        `The conversation above has ended. Do not continue it or respond as the assistant. ` +
-                        `Generate exactly ${count} follow-up prompts the *user* might send next, phrased in first person as the user would write them. ` +
-                        `The first ${Math.max(0, count - 1)} should be natural follow-ups to the last turn. ` +
-                        `Do not invent specific names, IDs, or data values that do not appear in <conversation_history>.` +
-                        capabilitiesBlock +
-                        guidanceBlock +
-                        `\n\nOutput format (strict):\n` +
-                        `- Exactly ${count} lines.\n` +
-                        `- One suggestion per line.\n` +
-                        `- No numbering, bullets, markdown, emojis, code blocks, or quotes around the suggestion.\n` +
-                        `- No preamble, headings, summary, or commentary before or after the list.`;
-            }
-            const text = yield defaultProvider.prompt(userMessage, { systemPrompt });
-            // Lenient parsing as a defensive backstop: even with the strict prompt,
-            // models occasionally slip in numbering, bullets, or surrounding markdown.
-            return (text
-                .split('\n')
-                .map((s) => s.trim())
-                // strip leading bullets/numbers ("- ", "* ", "• ", "1. ", "1) ")
-                .map((s) => s.replace(/^([-*•]|\d+[.)])\s+/, ''))
-                // strip surrounding bold/italic markers
-                .map((s) => s.replace(/^[*_]{1,3}|[*_]{1,3}$/g, '').trim())
-                // drop empty lines, separators, and obvious preamble lines
-                .filter((s) => s.length > 0)
-                .filter((s) => !/^[-=]{2,}$/.test(s))
-                .filter((s) => !/^here (are|is) /i.test(s))
-                .filter((s) => !s.endsWith(':'))
-                .slice(0, count));
+            return generateSuggestions({
+                registry: this.providerRegistry,
+                activeAgentName: this.activeAgentName,
+                toolDefinitions: this.toolDefinitions,
+            }, history, prompt, count, allAgentInfo);
         });
     }
     /**
@@ -1668,7 +1600,7 @@ export class ChatDriver extends EventTarget {
                     message: e instanceof Error ? e.message : String(e),
                 });
                 this.appendDriverNotice('Sorry, something went wrong on my end. Please try again in a moment.');
-                result = this.turnDone('exception');
+                result = turnDone('exception');
                 return result;
             }
             finally {
@@ -1680,6 +1612,9 @@ export class ChatDriver extends EventTarget {
                 this.busy = false;
                 this.endTurn();
                 this.activityBus.publish('tool-loop-end', this.loopEndDetail(result));
+                // In `finally` rather than on the success path: the agent asked to be released, and a turn
+                // that later threw does not make its flow any less finished.
+                yield this.releaseIfRequested();
             }
         });
     }
@@ -2046,7 +1981,7 @@ export class ChatDriver extends EventTarget {
                     message: e instanceof Error ? e.message : String(e),
                 });
                 this.appendDriverNotice('Sorry, something went wrong on my end. Please try again in a moment.');
-                result = this.turnDone('exception');
+                result = turnDone('exception');
                 return result;
             }
             finally {
@@ -2058,153 +1993,13 @@ export class ChatDriver extends EventTarget {
                 this.busy = false;
                 this.endTurn();
                 this.activityBus.publish('tool-loop-end', this.loopEndDetail(result));
+                // In `finally` rather than on the success path: the agent asked to be released, and a turn
+                // that later threw does not make its flow any less finished.
+                yield this.releaseIfRequested();
             }
         });
     }
     // ---------------------------------------------------------------------------
-    // 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;
-    }
-    /**
-     * If an open fold is hiding a previously-available tool, return the name of
-     * the fold to close to start getting it back. Only exclusive folds hide tools
-     * (they replace the tool set on open rather than extending it), so a base tool
-     * that was visible before the fold opened now sits in a fold-stack frame's
-     * `previousHandlers` but not in the live handler map. Only the top fold's
-     * `close_` tool is active, so that's always the actionable next step — even
-     * when the tool lives further down the stack, closing repeatedly walks back to
-     * it. Returns null when no open fold accounts for the tool.
-     */
-    foldHidingTool(toolName) {
-        if (this.foldStack.length === 0)
-            return null;
-        const hidden = this.foldStack.some((f) => f.previousHandlers[toolName]);
-        return hidden ? this.foldStack[this.foldStack.length - 1].foldName : 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, activeToolCallId) {
-        // 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, this.buildHandlerContext(activeToolCallId)).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
     // ---------------------------------------------------------------------------
@@ -2375,7 +2170,7 @@ export class ChatDriver extends EventTarget {
                 // retry nudge — that would otherwise destabilize a cached system prompt. They are routed to
                 // the framed tail (below), never appended to the system string, so the system prompt stays
                 // byte-stable for every agent.
-                const foldSuffix = this.buildFoldSystemPromptSuffix();
+                const foldSuffix = this.folds.systemPromptSuffix();
                 const retryNudge = malformedAttempts > 0
                     ? `\n\n${MALFORMED_CALL_NUDGE}`
                     : emptyResponseAttempts > 0
@@ -2423,16 +2218,16 @@ export class ChatDriver extends EventTarget {
                 const [resolvedTemperature, resolvedToolChoice, resolvedCachePolicy, resolvedTailContext, resolvedResponseSchema, firstResolvedThinkingPolicy,] = 
                 // oxlint-disable-next-line no-await-in-loop
                 yield Promise.all([
-                    this.resolveTurnInput(this.activeTemperatureInput, promptCtx),
-                    this.resolveTurnInput(this.activeToolChoiceInput, promptCtx),
-                    this.resolveTurnInput(this.activeCachePolicyInput, promptCtx),
-                    this.resolveTurnInput(this.activeTailContextInput, promptCtx),
-                    this.resolveTurnInput(this.activeResponseSchemaInput, promptCtx),
+                    resolveTurnInput(this.activeTemperatureInput, promptCtx),
+                    resolveTurnInput(this.activeToolChoiceInput, promptCtx),
+                    resolveTurnInput(this.activeCachePolicyInput, promptCtx),
+                    resolveTurnInput(this.activeTailContextInput, promptCtx),
+                    resolveTurnInput(this.activeResponseSchemaInput, promptCtx),
                     // Only consulted on the first iteration (see `pinnedThinkingPolicy`); resolved
                     // alongside the others so a resolver still sees the same turn context.
                     thinkingPolicyPinned
                         ? Promise.resolve(undefined)
-                        : this.resolveTurnInput(this.activeThinkingPolicyInput, promptCtx),
+                        : resolveTurnInput(this.activeThinkingPolicyInput, promptCtx),
                 ]);
                 if (!thinkingPolicyPinned) {
                     pinnedThinkingPolicy = firstResolvedThinkingPolicy;
@@ -2696,7 +2491,7 @@ export class ChatDriver extends EventTarget {
                             // user, carrying the attribution so the parent walls the vendor that
                             // actually refused rather than its own.
                             this.failSubAgent('budget_exhausted', this.budgetWallDetail);
-                            return this.turnDone('budget-exhausted', this.budgetWallDetail);
+                            return turnDone('budget-exhausted', this.budgetWallDetail);
                         }
                         return this.reportBudgetExhausted(e);
                     }
@@ -2876,36 +2671,36 @@ export class ChatDriver extends EventTarget {
                     // oxlint-disable-next-line no-await-in-loop -- Promise.all is correct parallelism, not sequential loop awaiting
                     yield Promise.all(toolCalls.map((tc) => __awaiter(this, void 0, void 0, function* () {
                         // Check for fold facade
-                        const fold = this.getFold(tc.name);
+                        const fold = this.folds.foldFor(tc.name);
                         if (fold) {
-                            this.consecutiveFoldOps += 1;
-                            if (this.consecutiveFoldOps > this.maxFoldOperations) {
+                            const foldOps = this.folds.noteOp();
+                            if (foldOps > 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.`,
+                                    content: `You have opened and closed folds ${foldOps} 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, tc.id);
+                            const content = yield this.folds.open(tc.name, fold, tc.args, tc.id);
                             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.startsWith('close_') && this.folds.depth > 0) {
+                            const topFoldName = this.folds.topName;
                             if (tc.name === `close_${topFoldName}`) {
-                                this.consecutiveFoldOps += 1;
-                                if (this.consecutiveFoldOps > this.maxFoldOperations) {
+                                const foldOps = this.folds.noteOp();
+                                if (foldOps > 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.`,
+                                        content: `You have opened and closed folds ${foldOps} times without calling any tools. Please call a specific tool to make progress, or respond to the user.`,
                                     });
                                     return;
                                 }
-                                const content = this.closeFold();
+                                const content = this.folds.close();
                                 executedById.set(tc.id, { toolCallId: tc.id, content });
                                 iterations -= 1;
                                 return;
@@ -2914,7 +2709,7 @@ export class ChatDriver extends EventTarget {
                         // 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);
+                            const containingFold = this.folds.findContaining(tc.name);
                             if (containingFold) {
                                 logger.debug(`ChatDriver: model called folded tool "${tc.name}" — guiding to open "${containingFold}"`);
                                 recordMetaEvent(this.sessionKey, 'tool.unresolved', {
@@ -2941,7 +2736,7 @@ export class ChatDriver extends EventTarget {
                             // guidance, telemetry, and limit differ.
                             if (this.everSeenToolNames.has(tc.name)) {
                                 this.consecutiveUnknownToolCalls += 1;
-                                const hidingFold = this.foldHidingTool(tc.name);
+                                const hidingFold = this.folds.hidingTool(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}.`;
@@ -3050,13 +2845,13 @@ export class ChatDriver extends EventTarget {
                 }
                 // Reset counters whenever a real tool executes
                 if (anyRealToolExecuted) {
-                    this.consecutiveFoldOps = 0;
+                    this.folds.clearOps();
                     this.consecutiveUnknownToolCalls = 0;
                     this.recentUnknownToolNames.clear();
                     this.recentStaleToolNames.clear();
                 }
                 // Tag tool calls with fold UI metadata before appending results
-                const foldPath = this.foldStack.map((f) => f.foldName);
+                const foldPath = this.folds.activeNames();
                 for (const tc of response.toolCalls) {
                     if (tc.name === REQUEST_CONTINUATION_TOOL) {
                         this.appendToHistory({
@@ -3095,7 +2890,7 @@ export class ChatDriver extends EventTarget {
                     const availableToolNames = Object.keys(this.toolHandlers);
                     const annotatedCalls = tcMsg.toolCalls.map((tc) => {
                         var _a, _b, _c, _d, _e;
-                        const isFoldOpen = !!this.getFold(tc.name) ||
+                        const isFoldOpen = !!this.folds.foldFor(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
@@ -3160,7 +2955,7 @@ export class ChatDriver extends EventTarget {
                 // Sub-agent early exit — checked here so the exit point mirrors the
                 // system-call pattern above. Set by completeSubAgent() in a tool handler.
                 if (this.subAgentCompletion) {
-                    return this.turnDone();
+                    return turnDone();
                 }
             }
             // The loop fell through: either it hit the iteration cap (a failure) or it
@@ -3176,7 +2971,7 @@ export class ChatDriver extends EventTarget {
                 });
                 return this.endTurnWithFailure(TURN_FAILURE_EXITS.maxIterations);
             }
-            return this.turnDone();
+            return turnDone();
         });
     }
     /**