@genesislcap/ai-assistant 14.434.0 → 14.436.0

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

@@ -10,7 +10,12 @@ import type {
   SubAgentRequestOptions,
 } from '@genesislcap/foundation-ai';
 import { MalformedFunctionCallError } from '@genesislcap/foundation-ai';
-import type { AgentConfig } from '../../config/config';
+import type {
+  AgentConfig,
+  SystemPromptContext,
+  SystemPromptInput,
+  ToolDefinitionsInput,
+} from '../../config/config';
 import { applyHistoryCap } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import { TOOL_FOLD_SYMBOL, type ToolFold } from '../../utils/tool-fold';
@@ -18,6 +23,7 @@ import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
 
 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;
@@ -37,6 +43,31 @@ const HANDOFF_TOOL_RESULT_PLACEHOLDER =
  */
 export type ChatHistoryUpdatedEvent = CustomEvent<ReadonlyArray<ChatMessage>>;
 
+/**
+ * One captured frame of what the LLM saw on a single tool-loop iteration.
+ * The driver records these as a ring buffer (cap: configurable via
+ * `chatConfig.agent.maxTurnSnapshots`, default 40) so the export log can show,
+ * per turn: which agent was active, the resolved system prompt, the tool names
+ * visible to the LLM, and any agent-supplied debug snapshot (e.g. machine
+ * state for stateful agents).
+ *
+ * @beta
+ */
+export interface TurnSnapshot {
+  /** Monotonic counter across the driver's lifetime (does not reset on agent swap). */
+  turnIndex: number;
+  /** ISO timestamp captured just before the LLM call. */
+  timestamp: string;
+  /** Name of the agent active when this LLM call ran. */
+  agentName?: string;
+  /** Final system prompt sent to the LLM (post-fold-suffix, post-retry hint). */
+  systemPrompt?: string;
+  /** Tool names sent to the LLM, in order — definitions are static per name so names alone suffice. */
+  toolNames: string[];
+  /** Agent-supplied snapshot — machine state/context for stateful agents, undefined otherwise. */
+  agentSnapshot?: unknown;
+}
+
 interface FoldStackFrame {
   foldName: string;
   previousDefinitions: ChatToolDefinition[];
@@ -61,8 +92,22 @@ export class ChatDriver extends EventTarget implements AiDriver {
     { resolve: (value: any) => void; reject: (reason?: any) => void }
   >();
 
-  private systemPrompt?: string;
+  private systemPrompt?: SystemPromptInput;
+  /**
+   * Resolved tool definitions visible to the LLM. Folds mutate this in place
+   * (push/pop on open/close). When `toolDefinitionsFactory` is set, this is
+   * overwritten each tool-loop iteration with the factory's output.
+   */
   private toolDefinitions: ChatToolDefinition[];
+  /**
+   * Optional dynamic-tools source. When set, called each tool-loop iteration
+   * to recompute `toolDefinitions` before the LLM call. `defineStatefulAgent`
+   * forbids folds when this is set, so the fold-mutation path is unreachable
+   * in that case.
+   */
+  private toolDefinitionsFactory?: (
+    ctx: SystemPromptContext,
+  ) => ChatToolDefinition[] | Promise<ChatToolDefinition[]>;
   private toolHandlers: ChatToolHandlers;
   private primerHistory?: ChatMessage[];
   private activeAgentName?: string;
@@ -96,22 +141,51 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * `undefined` means the loop has not been stopped early.
    */
   private subAgentCompletion: { result: unknown } | undefined;
+  /**
+   * 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.
+   */
+  private 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.
+   */
+  private turnSnapshots: TurnSnapshot[] = [];
+  /** Monotonic counter that survives agent swaps — useful for cross-referencing with history. */
+  private globalTurnIndex = 0;
+  /** Captured from `applyAgent` so we don't store the whole `AgentConfig`. */
+  private debugSnapshotter?: () => unknown;
+  private readonly maxTurnSnapshots: number;
 
   constructor(
     private readonly aiProvider: AIProvider,
     toolHandlers: ChatToolHandlers = {},
-    toolDefinitions: ChatToolDefinition[] = [],
-    systemPrompt?: string,
+    toolDefinitions: ToolDefinitionsInput = [],
+    systemPrompt?: SystemPromptInput,
     primerHistory?: ChatMessage[],
     private readonly maxToolIterations: number = DEFAULT_MAX_TOOL_ITERATIONS,
     maxFoldOperations: number = DEFAULT_MAX_FOLD_OPERATIONS,
+    maxTurnSnapshots: number = DEFAULT_MAX_TURN_SNAPSHOTS,
   ) {
     super();
     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;
   }
 
   /**
@@ -120,10 +194,19 @@ export class ChatDriver extends EventTarget implements AiDriver {
    */
   applyAgent(config: AgentConfig): void {
     this.systemPrompt = config.systemPrompt;
-    this.toolDefinitions = config.toolDefinitions ?? [];
+    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 = config.toolDefinitions ?? [];
+    }
     this.toolHandlers = config.toolHandlers ?? {};
     this.primerHistory = config.primerHistory;
     this.activeAgentName = config.name;
+    this.debugSnapshotter = config.getDebugSnapshot;
     this.subAgentsMap = new Map((config.subAgents ?? []).map((s) => [s.name, s]));
     // Reset fold state when agent changes — each specialist starts fresh
     this.foldStack = [];
@@ -138,6 +221,57 @@ export class ChatDriver extends EventTarget implements AiDriver {
     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(): boolean {
+    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(): ReadonlyArray<TurnSnapshot> {
+    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.
+   */
+  private recordTurnSnapshot(resolvedSystemPrompt: string | undefined): void {
+    let agentSnapshot: unknown;
+    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.
@@ -340,6 +474,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
 
     this.busy = true;
     this.subAgentCompletion = undefined;
+    this.agentReleaseRequested = false;
     this.appendToHistory({ role: 'user', content: userInput, attachments });
 
     try {
@@ -385,6 +520,15 @@ export class ChatDriver extends EventTarget implements AiDriver {
         }
         this.subAgentCompletion = { result };
       },
+      releaseAgent: (): void => {
+        if (this.agentReleaseRequested) {
+          logger.warn(
+            `ChatDriver(${this.activeAgentName ?? 'unknown'}): releaseAgent called more than once — ignoring`,
+          );
+          return;
+        }
+        this.agentReleaseRequested = true;
+      },
     };
   }
 
@@ -681,9 +825,33 @@ export class ChatDriver extends EventTarget implements AiDriver {
     while (iterations < this.maxToolIterations) {
       iterations += 1;
 
+      const promptCtx: SystemPromptContext = {
+        agentName: this.activeAgentName ?? '',
+        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 = await this.toolDefinitionsFactory(promptCtx);
+      }
+
+      const resolvedSystemPrompt =
+        typeof this.systemPrompt === 'function'
+          ? // eslint-disable-next-line no-await-in-loop
+            await 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 = [...(this.primerHistory ?? []), ...(transientPrimer ?? [])];
@@ -701,6 +869,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
             ? `${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 —

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

@@ -5,11 +5,21 @@ import type {
   ChatMessage,
   ChatRequestOptions,
 } from '@genesislcap/foundation-ai';
-import type { AgentConfig, FallbackAgentConfig, SpecialistAgentConfig } from '../../config/config';
+import type {
+  AgentConfig,
+  FallbackAgentConfig,
+  SpecialistAgentConfig,
+  SystemPromptContext,
+  SystemPromptInput,
+} from '../../config/config';
 import { transformHistoryForAgent } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
-import { ChatDriver, REQUEST_CONTINUATION_TOOL } from '../chat-driver/chat-driver';
+import {
+  ChatDriver,
+  REQUEST_CONTINUATION_TOOL,
+  type TurnSnapshot,
+} from '../chat-driver/chat-driver';
 
 const DEFAULT_MAX_HANDOFFS = 3;
 const DEFAULT_CLASSIFIER_HISTORY_LENGTH = 4;
@@ -47,11 +57,17 @@ function isFallback(agent: AgentConfig): agent is FallbackAgentConfig {
 function buildFallbackSystemPrompt(
   fallback: FallbackAgentConfig,
   specialists: SpecialistAgentConfig[],
-): string {
+): SystemPromptInput | undefined {
   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.`;
 }
 
@@ -69,6 +85,12 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
   private readonly maxHandoffs: number;
   private readonly classifierHistoryLength: number;
   private readonly classifierRetries: number;
+  private readonly sessionKey: string;
+  /**
+   * Aborted on driver disposal. Threaded into `AgentLifecycleContext.signal`
+   * so long-running `onActivate` work can bail if the session disconnects.
+   */
+  private readonly lifecycleAbortController = new AbortController();
   private pinnedAgentName: string | null = null;
 
   activeAgent?: AgentConfig;
@@ -77,20 +99,25 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
     private readonly aiProvider: AIProvider,
     private readonly agents: AgentConfig[],
     options: {
+      sessionKey?: string;
       maxHandoffs?: number;
       classifierHistoryLength?: number;
       classifierRetries?: number;
       maxToolIterations?: number;
       maxFoldOperations?: number;
+      maxTurnSnapshots?: number;
     } = {},
   ) {
     super();
+    this.sessionKey = options.sessionKey ?? '';
     this.maxHandoffs = options.maxHandoffs ?? DEFAULT_MAX_HANDOFFS;
     this.classifierHistoryLength =
       options.classifierHistoryLength ?? DEFAULT_CLASSIFIER_HISTORY_LENGTH;
     this.classifierRetries = options.classifierRetries ?? DEFAULT_CLASSIFIER_RETRIES;
 
-    this.specialists = agents.filter(isSpecialist);
+    // 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(
@@ -111,6 +138,7 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
       undefined,
       options.maxToolIterations,
       options.maxFoldOperations,
+      options.maxTurnSnapshots,
     );
 
     // Proxy events from the shared driver
@@ -156,6 +184,11 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
     return this.chatDriver.getHistory();
   }
 
+  /** Delegates to the inner {@link ChatDriver} — turns are captured there. */
+  getTurnSnapshots(): ReadonlyArray<TurnSnapshot> {
+    return this.chatDriver.getTurnSnapshots();
+  }
+
   async getSuggestions(
     history: ChatMessage[],
     prompt: string,
@@ -169,7 +202,10 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
     const agentInfo = candidates.map((s) => ({
       name: s.name,
       description: s.description,
-      tools: s.toolDefinitions ?? [],
+      // 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);
   }
@@ -194,7 +230,8 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
     let remainingTask = '';
 
     while (true) {
-      this.applyAgent(currentAgent);
+      // eslint-disable-next-line no-await-in-loop
+      await this.applyAgent(currentAgent);
 
       let result: ChatDriverResult;
       if (isHandoff) {
@@ -208,6 +245,16 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
         result = await 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
+        await 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) {
@@ -239,17 +286,74 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
     return this.chatDriver.continueFromHistory(transientPrimer);
   }
 
-  private applyAgent(agent: AgentConfig): void {
-    // Fallback and pinned agents are terminal — neither should hand off.
-    const isTerminal = isFallback(agent) || this.pinnedAgentName !== null;
-    const agentToApply = isTerminal
-      ? agent
-      : {
-          ...agent,
-          toolDefinitions: [...(agent.toolDefinitions ?? []), REQUEST_CONTINUATION_DEFINITION],
-        };
-
+  private async applyAgent(agent: AgentConfig): Promise<void> {
     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?.onDeactivate) {
+      try {
+        await 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 {
+        await agent.onActivate({
+          agentName: agent.name,
+          sessionKey: this.sessionKey,
+          previousAgentName: 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: AgentConfig = agent;
+    if (!isTerminal) {
+      const declaredTools = agent.toolDefinitions;
+      agentToApply = {
+        ...agent,
+        toolDefinitions:
+          typeof declaredTools === 'function'
+            ? async (ctx: SystemPromptContext) => [
+                ...(await declaredTools(ctx)),
+                REQUEST_CONTINUATION_DEFINITION,
+              ]
+            : [...(declaredTools ?? []), REQUEST_CONTINUATION_DEFINITION],
+      };
+    }
+
     if (previousAgent && previousAgent.name !== agent.name) {
       const rawHistory = this.chatDriver.getHistory() as ChatMessage[];
       this.chatDriver.loadHistory([...rawHistory, { role: 'system-event', content: agent.name }]);
@@ -262,12 +366,82 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
     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`.
+   */
+  private async releaseActiveAgent(): Promise<void> {
+    const agent = this.activeAgent;
+    if (!agent) return;
+    if (agent.onDeactivate) {
+      try {
+        await 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.
+   */
+  async dispose(): Promise<void> {
+    const previousAgent = this.activeAgent;
+    if (previousAgent?.onDeactivate) {
+      try {
+        await 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;
+  }
+
   private async classify(
     input: string,
     history: ChatMessage[],
     contextAgent?: AgentConfig,
   ): Promise<AgentConfig> {
+    // 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 this.fallback ?? { name: 'Assistant', fallback: true };
     }