@genesislcap/ai-assistant 14.434.0 → 14.436.0

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

@@ -5,6 +5,7 @@ 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_TURN_SNAPSHOTS = 40;
 const DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5;
 const MAX_MALFORMED_RETRIES = 2;
 const MAX_EMPTY_RESPONSE_RETRIES = 3;
@@ -24,7 +25,7 @@ const HANDOFF_TOOL_RESULT_PLACEHOLDER = 'Handoff to another specialist — routi
  * @beta
  */
 export class ChatDriver extends EventTarget {
-    constructor(aiProvider, toolHandlers = {}, toolDefinitions = [], systemPrompt, primerHistory, maxToolIterations = DEFAULT_MAX_TOOL_ITERATIONS, maxFoldOperations = DEFAULT_MAX_FOLD_OPERATIONS) {
+    constructor(aiProvider, toolHandlers = {}, toolDefinitions = [], systemPrompt, primerHistory, maxToolIterations = DEFAULT_MAX_TOOL_ITERATIONS, maxFoldOperations = DEFAULT_MAX_FOLD_OPERATIONS, maxTurnSnapshots = DEFAULT_MAX_TURN_SNAPSHOTS) {
         super();
         this.aiProvider = aiProvider;
         this.maxToolIterations = maxToolIterations;
@@ -39,11 +40,37 @@ export class ChatDriver extends EventTarget {
         this.consecutiveUnknownToolCalls = 0;
         /** Sub-agents declared on the active agent config, keyed by name. */
         this.subAgentsMap = new Map();
+        /**
+         * Set by `releaseAgent` inside a top-level tool handler — typically a stateful
+         * agent's terminal-state handler signalling that its flow is complete and the
+         * auto-pin lock can release. Checked by the orchestrator after `sendMessage`
+         * returns; the orchestrator fires `onDeactivate` and clears the pin.
+         *
+         * Reset at the start of each `sendMessage` so a release from a previous turn
+         * doesn't leak forward.
+         */
+        this.agentReleaseRequested = false;
+        /**
+         * Ring buffer of per-LLM-call snapshots. Cap is configurable via
+         * `chatConfig.agent.maxTurnSnapshots`; older entries drop off as new ones
+         * arrive. See {@link TurnSnapshot} for the captured shape.
+         */
+        this.turnSnapshots = [];
+        /** Monotonic counter that survives agent swaps — useful for cross-referencing with history. */
+        this.globalTurnIndex = 0;
         this.toolHandlers = toolHandlers;
-        this.toolDefinitions = toolDefinitions;
+        if (typeof toolDefinitions === 'function') {
+            this.toolDefinitionsFactory = toolDefinitions;
+            this.toolDefinitions = [];
+        }
+        else {
+            this.toolDefinitionsFactory = undefined;
+            this.toolDefinitions = toolDefinitions;
+        }
         this.systemPrompt = systemPrompt;
         this.primerHistory = primerHistory;
         this.maxFoldOperations = maxFoldOperations;
+        this.maxTurnSnapshots = maxTurnSnapshots;
     }
     /**
      * Swap in a new agent's configuration. Called by OrchestratingDriver before
@@ -52,10 +79,20 @@ export class ChatDriver extends EventTarget {
     applyAgent(config) {
         var _a, _b, _c;
         this.systemPrompt = config.systemPrompt;
-        this.toolDefinitions = (_a = config.toolDefinitions) !== null && _a !== void 0 ? _a : [];
+        if (typeof config.toolDefinitions === 'function') {
+            this.toolDefinitionsFactory = config.toolDefinitions;
+            // Cleared each turn by the factory in runToolLoop; empty is safe in the
+            // meantime (no LLM call happens before resolution).
+            this.toolDefinitions = [];
+        }
+        else {
+            this.toolDefinitionsFactory = undefined;
+            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;
+        this.debugSnapshotter = config.getDebugSnapshot;
         this.subAgentsMap = new Map(((_c = config.subAgents) !== null && _c !== void 0 ? _c : []).map((s) => [s.name, s]));
         // Reset fold state when agent changes — each specialist starts fresh
         this.foldStack = [];
@@ -68,6 +105,55 @@ export class ChatDriver extends EventTarget {
     getSubAgentCompletion() {
         return this.subAgentCompletion;
     }
+    /**
+     * Returns true if `releaseAgent` was called during the most recent turn.
+     * Consumed by the orchestrator to trigger the auto-pin release path.
+     */
+    getAgentReleaseRequested() {
+        return this.agentReleaseRequested;
+    }
+    /**
+     * 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
+     * surface, and agent-supplied state (e.g. a machine snapshot).
+     *
+     * Ring-buffered at `MAX_TURN_SNAPSHOTS`; older entries are dropped.
+     */
+    getTurnSnapshots() {
+        return this.turnSnapshots;
+    }
+    /**
+     * Push one snapshot to the ring buffer. Called inside `runToolLoop` just
+     * before each LLM call — that's the latest point where the prompt, tool
+     * surface, and agent state line up with what the model is about to see.
+     */
+    recordTurnSnapshot(resolvedSystemPrompt) {
+        let agentSnapshot;
+        if (this.debugSnapshotter) {
+            try {
+                agentSnapshot = this.debugSnapshotter();
+            }
+            catch (e) {
+                // A snapshotter throwing must not derail the LLM call — capture the
+                // error string in place of the snapshot so the export still shows
+                // *something* happened.
+                agentSnapshot = `<getDebugSnapshot threw: ${e instanceof Error ? e.message : String(e)}>`;
+            }
+        }
+        const turnIndex = this.globalTurnIndex;
+        this.globalTurnIndex += 1;
+        this.turnSnapshots.push({
+            turnIndex,
+            timestamp: new Date().toISOString(),
+            agentName: this.activeAgentName,
+            systemPrompt: resolvedSystemPrompt,
+            toolNames: this.toolDefinitions.map((t) => t.name),
+            agentSnapshot,
+        });
+        if (this.turnSnapshots.length > this.maxTurnSnapshots) {
+            this.turnSnapshots.shift();
+        }
+    }
     /**
      * Optional transform applied to conversation history immediately before each LLM request.
      * Cleared when `undefined`. Does not alter stored history.
@@ -249,6 +335,7 @@ export class ChatDriver extends EventTarget {
             }
             this.busy = true;
             this.subAgentCompletion = undefined;
+            this.agentReleaseRequested = false;
             this.appendToHistory({ role: 'user', content: userInput, attachments });
             try {
                 return yield this.runToolLoop(userInput, attachments);
@@ -286,6 +373,13 @@ export class ChatDriver extends EventTarget {
                     return;
                 }
                 this.subAgentCompletion = { result };
+            }, releaseAgent: () => {
+                var _a;
+                if (this.agentReleaseRequested) {
+                    logger.warn(`ChatDriver(${(_a = this.activeAgentName) !== null && _a !== void 0 ? _a : 'unknown'}): releaseAgent called more than once — ignoring`);
+                    return;
+                }
+                this.agentReleaseRequested = true;
             } });
     }
     /**
@@ -516,7 +610,7 @@ export class ChatDriver extends EventTarget {
     // ---------------------------------------------------------------------------
     runToolLoop(userInput, attachments, transientPrimer) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f;
+            var _a, _b, _c, _d, _e, _f, _g;
             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.');
             }
@@ -532,11 +626,31 @@ export class ChatDriver extends EventTarget {
             let firstLlmCall = !!currentInput;
             while (iterations < this.maxToolIterations) {
                 iterations += 1;
+                const promptCtx = {
+                    agentName: (_a = this.activeAgentName) !== null && _a !== void 0 ? _a : '',
+                    history: this.history,
+                    turnIndex: iterations - 1,
+                    signal: new AbortController().signal,
+                };
+                // Re-resolve dynamic tool definitions before each LLM call. The static
+                // case is a no-op (factory is undefined and `this.toolDefinitions` was
+                // set by applyAgent). Folds operate on `this.toolDefinitions` and are
+                // forbidden when a factory is set, so the array form is always valid.
+                // Sequential await is required — each iteration must see fresh values
+                // before constructing the LLM request.
+                if (this.toolDefinitionsFactory) {
+                    // eslint-disable-next-line no-await-in-loop
+                    this.toolDefinitions = yield this.toolDefinitionsFactory(promptCtx);
+                }
+                const resolvedSystemPrompt = typeof this.systemPrompt === 'function'
+                    ? // eslint-disable-next-line no-await-in-loop
+                        yield this.systemPrompt(promptCtx)
+                    : this.systemPrompt;
                 const foldSuffix = this.buildFoldSystemPromptSuffix();
-                const baseSystemPrompt = this.systemPrompt
-                    ? `${this.systemPrompt}${foldSuffix}`
+                const baseSystemPrompt = resolvedSystemPrompt
+                    ? `${resolvedSystemPrompt}${foldSuffix}`
                     : foldSuffix || undefined;
-                const primer = [...((_a = this.primerHistory) !== null && _a !== void 0 ? _a : []), ...(transientPrimer !== null && transientPrimer !== void 0 ? transientPrimer : [])];
+                const primer = [...((_b = this.primerHistory) !== null && _b !== void 0 ? _b : []), ...(transientPrimer !== null && transientPrimer !== void 0 ? transientPrimer : [])];
                 const baseHistory = firstLlmCall ? this.history.slice(0, -1) : this.history;
                 firstLlmCall = false;
                 const historyForProvider = this.providerHistoryTransform
@@ -548,6 +662,7 @@ export class ChatDriver extends EventTarget {
                     : emptyResponseAttempts > 0
                         ? `${baseSystemPrompt !== null && baseSystemPrompt !== void 0 ? baseSystemPrompt : ''}\n\nIMPORTANT: You must respond to the user's message. Call the appropriate tool or provide a text response — do not return an empty response.`
                         : baseSystemPrompt;
+                this.recordTurnSnapshot(systemPrompt);
                 // Capture the pending user input, then clear the slots BEFORE the chat
                 // call. `sendMessage` already appended the user message to `this.history`,
                 // so on retries (empty / malformed) we must rely on history alone —
@@ -586,8 +701,8 @@ export class ChatDriver extends EventTarget {
                     }
                     throw e;
                 }
-                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);
+                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);
                 if (isEmptyResponse) {
                     emptyResponseAttempts += 1;
                     if (emptyResponseAttempts < MAX_EMPTY_RESPONSE_RETRIES) {
@@ -609,7 +724,7 @@ export class ChatDriver extends EventTarget {
                 else {
                     this.appendToHistory(response);
                 }
-                if (!((_e = response.toolCalls) === null || _e === void 0 ? void 0 : _e.length)) {
+                if (!((_f = response.toolCalls) === null || _f === void 0 ? void 0 : _f.length)) {
                     break;
                 }
                 const [toolCalls, systemCalls] = response.toolCalls.reduce((acc, tc) => {
@@ -734,7 +849,7 @@ export class ChatDriver extends EventTarget {
                 // 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)) {
+                    if (this.history[i].role === 'assistant' && ((_g = this.history[i].toolCalls) === null || _g === void 0 ? void 0 : _g.length)) {
                         tcMsgIdx = i;
                         break;
                     }

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

@@ -1,7 +1,7 @@
 import { __awaiter } from "tslib";
 import { transformHistoryForAgent } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
-import { ChatDriver, REQUEST_CONTINUATION_TOOL } from '../chat-driver/chat-driver';
+import { ChatDriver, REQUEST_CONTINUATION_TOOL, } from '../chat-driver/chat-driver';
 const DEFAULT_MAX_HANDOFFS = 3;
 const DEFAULT_CLASSIFIER_HISTORY_LENGTH = 4;
 const DEFAULT_CLASSIFIER_RETRIES = 2;
@@ -31,9 +31,15 @@ function isFallback(agent) {
 }
 function buildFallbackSystemPrompt(fallback, specialists) {
     const agentList = specialists.map((s) => `- ${s.name}: ${s.description}`).join('\n');
-    if (fallback.systemPrompt) {
+    if (typeof fallback.systemPrompt === 'string') {
         return fallback.systemPrompt.replace('{{agents}}', agentList);
     }
+    if (typeof fallback.systemPrompt === 'function') {
+        // Function-form fallback prompt — pass through unchanged. The `{{agents}}`
+        // substitution is a string-template convenience; consumers using the
+        // function form can compose the agent list themselves if they want it.
+        return fallback.systemPrompt;
+    }
     return `You are a helpful assistant. You cannot directly help with the user's request, but the following specialists are available:\n\n${agentList}\n\nPolitely let the user know what you can help with and invite them to rephrase their request.`;
 }
 /**
@@ -45,16 +51,24 @@ function buildFallbackSystemPrompt(fallback, specialists) {
  */
 export class OrchestratingDriver extends EventTarget {
     constructor(aiProvider, agents, options = {}) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         super();
         this.aiProvider = aiProvider;
         this.agents = agents;
+        /**
+         * Aborted on driver disposal. Threaded into `AgentLifecycleContext.signal`
+         * so long-running `onActivate` work can bail if the session disconnects.
+         */
+        this.lifecycleAbortController = new AbortController();
         this.pinnedAgentName = null;
-        this.maxHandoffs = (_a = options.maxHandoffs) !== null && _a !== void 0 ? _a : DEFAULT_MAX_HANDOFFS;
+        this.sessionKey = (_a = options.sessionKey) !== null && _a !== void 0 ? _a : '';
+        this.maxHandoffs = (_b = options.maxHandoffs) !== null && _b !== void 0 ? _b : DEFAULT_MAX_HANDOFFS;
         this.classifierHistoryLength =
-            (_b = options.classifierHistoryLength) !== null && _b !== void 0 ? _b : DEFAULT_CLASSIFIER_HISTORY_LENGTH;
-        this.classifierRetries = (_c = options.classifierRetries) !== null && _c !== void 0 ? _c : DEFAULT_CLASSIFIER_RETRIES;
-        this.specialists = agents.filter(isSpecialist);
+            (_c = options.classifierHistoryLength) !== null && _c !== void 0 ? _c : DEFAULT_CLASSIFIER_HISTORY_LENGTH;
+        this.classifierRetries = (_d = options.classifierRetries) !== null && _d !== void 0 ? _d : DEFAULT_CLASSIFIER_RETRIES;
+        // Specialists drive the classifier. `excludeFromClassifier` agents are still
+        // resolvable by name (so manual pinning works) but never auto-routed.
+        this.specialists = agents.filter(isSpecialist).filter((a) => !a.excludeFromClassifier);
         const fallbacks = agents.filter(isFallback);
         if (fallbacks.length > 1) {
             logger.warn('OrchestratingDriver: multiple fallback agents found — only the first will be used.');
@@ -62,7 +76,7 @@ export class OrchestratingDriver extends EventTarget {
         const rawFallback = fallbacks[0];
         this.fallback = rawFallback
             ? Object.assign(Object.assign({}, rawFallback), { systemPrompt: buildFallbackSystemPrompt(rawFallback, this.specialists) }) : undefined;
-        this.chatDriver = new ChatDriver(aiProvider, {}, [], undefined, undefined, options.maxToolIterations, options.maxFoldOperations);
+        this.chatDriver = new ChatDriver(aiProvider, {}, [], undefined, undefined, options.maxToolIterations, options.maxFoldOperations, options.maxTurnSnapshots);
         // Proxy events from the shared driver
         this.chatDriver.addEventListener('history-updated', (e) => {
             this.dispatchEvent(new CustomEvent('history-updated', { detail: e.detail }));
@@ -98,20 +112,24 @@ export class OrchestratingDriver extends EventTarget {
     getRawHistory() {
         return this.chatDriver.getHistory();
     }
+    /** Delegates to the inner {@link ChatDriver} — turns are captured there. */
+    getTurnSnapshots() {
+        return this.chatDriver.getTurnSnapshots();
+    }
     getSuggestions(history, prompt, count, allAgentInfo) {
         return __awaiter(this, void 0, void 0, function* () {
             // When pinned to a specialist, scope suggestions to that agent so the
             // proposed prompts reflect the active routing instead of the full panel.
             const pinned = this.resolvePinnedAgent();
             const candidates = pinned && isSpecialist(pinned) ? [pinned] : this.specialists;
-            const agentInfo = candidates.map((s) => {
-                var _a;
-                return ({
-                    name: s.name,
-                    description: s.description,
-                    tools: (_a = s.toolDefinitions) !== null && _a !== void 0 ? _a : [],
-                });
-            });
+            const agentInfo = candidates.map((s) => ({
+                name: s.name,
+                description: s.description,
+                // Suggestions use tool names for prompt hints. Dynamic agents resolve
+                // their tools per-turn against a SystemPromptContext we don't have here
+                // — pass an empty list rather than invoke the factory with a fake one.
+                tools: Array.isArray(s.toolDefinitions) ? s.toolDefinitions : [],
+            }));
             return this.chatDriver.getSuggestions(history, prompt, count, agentInfo);
         });
     }
@@ -132,7 +150,8 @@ export class OrchestratingDriver extends EventTarget {
             let handoffSummary = '';
             let remainingTask = '';
             while (true) {
-                this.applyAgent(currentAgent);
+                // eslint-disable-next-line no-await-in-loop
+                yield this.applyAgent(currentAgent);
                 let result;
                 if (isHandoff) {
                     const contextPrimer = handoffSummary
@@ -145,6 +164,15 @@ export class OrchestratingDriver extends EventTarget {
                     // eslint-disable-next-line no-await-in-loop
                     result = yield this.chatDriver.sendMessage(input, attachments);
                 }
+                // Release check: a stateful agent called `releaseAgent` from a terminal
+                // tool handler. Fire onDeactivate, clear the pin, drop the user back to
+                // classifier-mode. The LLM has already emitted its final wrap-up message
+                // by the time we get here — release is purely a teardown.
+                if (this.chatDriver.getAgentReleaseRequested()) {
+                    // eslint-disable-next-line no-await-in-loop
+                    yield this.releaseActiveAgent();
+                    break;
+                }
                 // Pinned agents never hand off — the continuation tool is filtered out in
                 // applyAgent, but this guards against a model hallucinating a handoff result.
                 if (result.reason !== 'agent-handoff' || isFallback(currentAgent) || pinned) {
@@ -172,27 +200,158 @@ export class OrchestratingDriver extends EventTarget {
         });
     }
     applyAgent(agent) {
-        var _a;
-        // Fallback and pinned agents are terminal — neither should hand off.
-        const isTerminal = isFallback(agent) || this.pinnedAgentName !== null;
-        const agentToApply = isTerminal
-            ? agent
-            : Object.assign(Object.assign({}, agent), { toolDefinitions: [...((_a = agent.toolDefinitions) !== null && _a !== void 0 ? _a : []), REQUEST_CONTINUATION_DEFINITION] });
-        const previousAgent = this.activeAgent;
-        if (previousAgent && previousAgent.name !== agent.name) {
-            const rawHistory = this.chatDriver.getHistory();
-            this.chatDriver.loadHistory([...rawHistory, { role: 'system-event', content: agent.name }]);
-        }
-        this.chatDriver.setProviderHistoryTransform((h) => transformHistoryForAgent(h, agent.name));
-        this.chatDriver.applyAgent(agentToApply);
-        this.activeAgent = agent;
-        this.dispatchEvent(new CustomEvent('orchestrating-stop'));
-        this.dispatchEvent(new CustomEvent('agent-changed', { detail: agent }));
+        return __awaiter(this, void 0, void 0, function* () {
+            const previousAgent = this.activeAgent;
+            const isSwitch = !previousAgent || previousAgent.name !== agent.name;
+            // Fire lifecycle hooks around the swap — outgoing first, then incoming.
+            // Both are awaited so a heavy `onActivate` (e.g. machine restore) completes
+            // before the agent's first turn runs.
+            if (isSwitch && (previousAgent === null || previousAgent === void 0 ? void 0 : previousAgent.onDeactivate)) {
+                try {
+                    yield previousAgent.onDeactivate({
+                        agentName: previousAgent.name,
+                        sessionKey: this.sessionKey,
+                        signal: this.lifecycleAbortController.signal,
+                    });
+                }
+                catch (e) {
+                    logger.warn(`OrchestratingDriver: onDeactivate("${previousAgent.name}") threw:`, e);
+                }
+            }
+            if (isSwitch && agent.onActivate) {
+                try {
+                    yield agent.onActivate({
+                        agentName: agent.name,
+                        sessionKey: this.sessionKey,
+                        previousAgentName: previousAgent === null || previousAgent === void 0 ? void 0 : previousAgent.name,
+                        signal: this.lifecycleAbortController.signal,
+                    });
+                }
+                catch (e) {
+                    logger.warn(`OrchestratingDriver: onActivate("${agent.name}") threw:`, e);
+                }
+            }
+            const hasLifecycleHooks = !!(agent.onActivate || agent.onDeactivate);
+            // Stateful agents auto-pin on activation. The pin guarantees the machine
+            // survives subsequent turns (the classifier would otherwise be free to
+            // route away mid-flow, tearing the machine down). Release happens when the
+            // agent calls `releaseAgent` from a terminal-state tool handler — see the
+            // post-sendMessage check below.
+            if (isSwitch && hasLifecycleHooks && this.pinnedAgentName !== agent.name) {
+                this.pinnedAgentName = agent.name;
+                this.dispatchEvent(new CustomEvent('pinned-changed', { detail: agent.name }));
+            }
+            // Terminal agents do not get the cross-agent handoff tool. Three cases:
+            //   • fallback — already a leaf; handoff would loop
+            //   • pinned   — user explicitly selected this agent; do not auto-route away
+            //   • stateful — agents with lifecycle hooks own state for the duration of
+            //                their flow. Initiating a handoff mid-flow would abandon
+            //                that state with no clean exit and dump the user into the
+            //                classifier mid-machine. Capture the tool loop until the
+            //                user (or the agent itself, via `releaseAgent`) releases.
+            const isTerminal = isFallback(agent) || this.pinnedAgentName !== null || hasLifecycleHooks;
+            let agentToApply = agent;
+            if (!isTerminal) {
+                const declaredTools = agent.toolDefinitions;
+                agentToApply = Object.assign(Object.assign({}, agent), { toolDefinitions: typeof declaredTools === 'function'
+                        ? (ctx) => __awaiter(this, void 0, void 0, function* () {
+                            return [
+                                ...(yield declaredTools(ctx)),
+                                REQUEST_CONTINUATION_DEFINITION,
+                            ];
+                        })
+                        : [...(declaredTools !== null && declaredTools !== void 0 ? declaredTools : []), REQUEST_CONTINUATION_DEFINITION] });
+            }
+            if (previousAgent && previousAgent.name !== agent.name) {
+                const rawHistory = this.chatDriver.getHistory();
+                this.chatDriver.loadHistory([...rawHistory, { role: 'system-event', content: agent.name }]);
+            }
+            this.chatDriver.setProviderHistoryTransform((h) => transformHistoryForAgent(h, agent.name));
+            this.chatDriver.applyAgent(agentToApply);
+            this.activeAgent = agent;
+            this.dispatchEvent(new CustomEvent('orchestrating-stop'));
+            this.dispatchEvent(new CustomEvent('agent-changed', { detail: agent }));
+        });
+    }
+    /**
+     * Release the current stateful agent: fire `onDeactivate`, clear the pin,
+     * dispatch events so the host (and Redux) reflect the unpinned state. Called
+     * automatically when a tool handler invokes `context.releaseAgent`.
+     */
+    releaseActiveAgent() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const agent = this.activeAgent;
+            if (!agent)
+                return;
+            if (agent.onDeactivate) {
+                try {
+                    yield agent.onDeactivate({
+                        agentName: agent.name,
+                        sessionKey: this.sessionKey,
+                        signal: this.lifecycleAbortController.signal,
+                    });
+                }
+                catch (e) {
+                    logger.warn(`OrchestratingDriver: release onDeactivate("${agent.name}") threw:`, e);
+                }
+            }
+            this.activeAgent = undefined;
+            if (this.pinnedAgentName !== null) {
+                this.pinnedAgentName = null;
+                this.dispatchEvent(new CustomEvent('pinned-changed', { detail: null }));
+            }
+            this.dispatchEvent(new CustomEvent('agent-released', { detail: agent }));
+            this.dispatchEvent(new CustomEvent('agent-changed', { detail: undefined }));
+        });
+    }
+    /**
+     * Fire `onDeactivate` on the current active agent and abort any pending
+     * lifecycle work. Called by the host on session teardown so machines can
+     * release resources cleanly.
+     */
+    dispose() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const previousAgent = this.activeAgent;
+            if (previousAgent === null || previousAgent === void 0 ? void 0 : previousAgent.onDeactivate) {
+                try {
+                    yield previousAgent.onDeactivate({
+                        agentName: previousAgent.name,
+                        sessionKey: this.sessionKey,
+                        signal: this.lifecycleAbortController.signal,
+                    });
+                }
+                catch (e) {
+                    logger.warn(`OrchestratingDriver: dispose onDeactivate("${previousAgent.name}") threw:`, e);
+                }
+            }
+            this.lifecycleAbortController.abort();
+            this.activeAgent = undefined;
+        });
     }
     classify(input, history, contextAgent) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b;
+            // Single-candidate short-circuits. No point asking the LLM to route
+            // when there's only one viable choice. Skipped if a fallback is
+            // configured — that's an explicit "escape hatch" signal from the
+            // consumer, and we preserve the LLM's ability to send unrelated
+            // messages there by returning -1 from select_agent.
+            if (this.specialists.length === 1 && !this.fallback) {
+                return this.specialists[0];
+            }
             if (this.specialists.length === 0) {
+                // No classifier-eligible specialists. If exactly one non-fallback
+                // agent exists (typically a stateful agent flagged
+                // `excludeFromClassifier`) and there's no fallback to preserve as an
+                // escape hatch, route to it — this is what fixes the previously-
+                // silent single-stateful-agent case. Otherwise drop to the fallback;
+                // excluded specialists remain reachable via manual pin.
+                if (!this.fallback) {
+                    const routable = this.agents.filter((a) => !isFallback(a));
+                    if (routable.length === 1) {
+                        return routable[0];
+                    }
+                }
                 return (_a = this.fallback) !== null && _a !== void 0 ? _a : { name: 'Assistant', fallback: true };
             }
             const agentList = this.specialists