@genesislcap/ai-assistant 15.24.2 → 15.26.0

package/dist/chat-driver.cjs

@@ -3854,6 +3854,77 @@ function createInteractionContext(interactionId) {
   };
 }
 
+// src/suggestions/generate-suggestions.ts
+var HISTORY_WINDOW = 8;
+function capabilities(ctx, allAgentInfo) {
+  let agentContext = "";
+  let toolContext = "";
+  if (allAgentInfo?.length) {
+    const agentDescriptions = allAgentInfo.map((agent) => {
+      const tools = agent.tools.map((t) => t.name).join(", ");
+      return `- ${agent.name} (${agent.description}): ${tools ? `(Tools: ${tools})` : "No tools"}`;
+    }).join("\n");
+    agentContext = `The assistant has the following capabilities:
+${agentDescriptions}`;
+    const allToolNames = [
+      ...new Set(allAgentInfo.flatMap((agent) => agent.tools.map((t) => t.name)))
+    ].join(", ");
+    toolContext = allToolNames ? `You have access to the following tools across all agents: ${allToolNames}.` : "";
+  } else if (ctx.activeAgentName) {
+    const toolNames = ctx.toolDefinitions.map((tool) => tool.name).join(", ");
+    agentContext = `You are currently acting as the "${ctx.activeAgentName}" agent.`;
+    toolContext = toolNames ? `You have access to the following tools: ${toolNames}.` : "";
+  }
+  return agentContext || toolContext ? `
+
+<capabilities>
+${[agentContext, toolContext].filter(Boolean).join(
+    "\n"
+  )}
+</capabilities>
+Suggestions must only cover what the agent is capable of. Do not suggest anything outside these capabilities.` : "";
+}
+var OUTPUT_FORMAT = (count) => `
+
+Output format (strict):
+- Exactly ${count} lines.
+- One suggestion per line.
+- No numbering, bullets, markdown, emojis, code blocks, or quotes around the suggestion.
+- No preamble, headings, summary, or commentary before or after the list.`;
+var SUGGESTIONS_SYSTEM_PROMPT = "You generate suggested prompts that a user could send to an AI assistant. You never continue the conversation or roleplay as the assistant.";
+function buildSuggestionsPrompt(ctx, history, prompt2, count, allAgentInfo) {
+  const capabilitiesBlock = capabilities(ctx, allAgentInfo);
+  const guidanceBlock = prompt2 ? `
+
+Additional guidance: "${prompt2}"` : "";
+  if (history.length === 0) {
+    return `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 \u2014 do not invent specific names, IDs, or data (e.g. prefer "Search for a trade" over "Find all trades with Client A").` + capabilitiesBlock + guidanceBlock + OUTPUT_FORMAT(count);
+  }
+  const conversationContext = history.filter(
+    (m) => (m.role === "user" || m.role === "assistant") && !m.toolCalls?.length && !m.thinking && !!m.content?.trim()
+  ).slice(-HISTORY_WINDOW).map((m) => `${m.role === "user" ? "User" : "Assistant"}: ${m.content}`).join("\n");
+  return `<conversation_history>
+${conversationContext}
+</conversation_history>
+
+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 + OUTPUT_FORMAT(count);
+}
+function parseSuggestions(text, count) {
+  return text.split("\n").map((s) => s.trim()).map((s) => s.replace(/^([-*•]|\d+[.)])\s+/, "")).map((s) => s.replace(/^[*_]{1,3}|[*_]{1,3}$/g, "").trim()).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);
+}
+async function generateSuggestions(ctx, history, prompt2, count, allAgentInfo) {
+  const defaultProvider = ctx.registry.default();
+  if (!defaultProvider.prompt) {
+    logger2.warn("ChatDriver: default AI provider does not implement prompt()");
+    return [];
+  }
+  const userMessage = buildSuggestionsPrompt(ctx, history, prompt2, count, allAgentInfo);
+  const text = await defaultProvider.prompt(userMessage, {
+    systemPrompt: SUGGESTIONS_SYSTEM_PROMPT
+  });
+  return parseSuggestions(text, count);
+}
+
 // src/utils/context-tokens.ts
 var APPROX_CHARS_PER_TOKEN = 4;
 var IMAGE_TOKEN_ESTIMATE = 1600;
@@ -4327,6 +4398,12 @@ The above summarizes earlier parts of this conversation that were compacted. Con
   });
 }
 
+// src/utils/resolve-turn-input.ts
+async function resolveTurnInput(input, ctx) {
+  if (input === void 0) return void 0;
+  return typeof input === "function" ? input(ctx) : input;
+}
+
 // src/utils/sum-usage.ts
 function emptyUsage() {
   return {
@@ -4397,9 +4474,358 @@ function accumulate(messages, into) {
   }
 }
 
+// src/components/agent-session/agent-session.ts
+var WARN_PREFIX = "AgentSession";
+var AgentSession = class {
+  constructor(deps) {
+    this.deps = deps;
+    /**
+     * Aborted on disposal. Threaded into `AgentLifecycleContext.signal` so long-running
+     * `onActivate` work can bail if the session disconnects.
+     */
+    this.lifecycleAbortController = new AbortController();
+    /**
+     * Sticky user pick from the picker (or the host's `setAgent` API). Only changes on explicit
+     * user action. Survives flow completion: when a stateful agent releases, the user-pin stays put
+     * and routing falls back to it on the next turn.
+     */
+    this.pinned = null;
+    /**
+     * Transient flow lock — set when a stateful agent activates, cleared on release. While
+     * non-null, routing precedence goes to this agent and the picker is locked. Independent of
+     * the user pin so completing a flow doesn't wipe the user's sticky choice.
+     */
+    this.flowOwner = null;
+    /**
+     * Per-agent restored state for a rehydrated session, keyed by agent name. Primed by the host on
+     * restore; each entry is passed to that agent's `onActivate` as `ctx.restored` on its next
+     * activation, then deleted so a later re-activation starts fresh.
+     */
+    this.restoredStates = {};
+  }
+  /** The active agent, or `undefined` before the first activation and after a release. */
+  getActive() {
+    return this.active;
+  }
+  /** The sticky user pin, or `null` for automatic routing. */
+  getPinned() {
+    return this.pinned;
+  }
+  /** The transient flow lock, or `null` when no flow holds routing. */
+  getFlowOwner() {
+    return this.flowOwner;
+  }
+  /**
+   * The name routing is locked to, flow lock first. A flow in progress outranks the user's
+   * sticky pick for the duration of the flow; neither being set means automatic routing.
+   */
+  getLockedName() {
+    return this.flowOwner ?? this.pinned;
+  }
+  /** Set the sticky user pin. `null` returns to automatic routing. */
+  setPinned(name) {
+    this.pinned = name;
+  }
+  /**
+   * Set the flow-owner lock directly — used to restore state on driver reconstruction
+   * (agents-array changes, pop-in/pop-out), not to steer routing. Writes without firing hooks or
+   * reporting a transition, because the flow it names is already running.
+   */
+  setFlowOwner(name) {
+    this.flowOwner = name;
+  }
+  /** Prime per-agent restored state for a rehydrated session. Replaces any pending entries. */
+  primeRestoredStates(snapshots) {
+    this.restoredStates = { ...snapshots };
+  }
+  /** Whether a restored snapshot is waiting for this agent's next activation. */
+  hasRestoredState(agentName) {
+    return this.restoredStates[agentName] !== void 0;
+  }
+  /**
+   * Make `agent` active, firing the lifecycle hooks around the swap: outgoing `onDeactivate`
+   * first, then incoming `onActivate`. Both are awaited so heavy activation work (a machine
+   * restore, say) completes before the agent's first turn runs, and a throw from either is logged
+   * rather than propagated — an agent whose hook fails still activates.
+   *
+   * Re-activating the same agent by name is not a switch: no hooks fire, no lock moves, and no
+   * handoff is recorded. That guard matters because a per-turn re-resolve calls through here.
+   */
+  async activate(agent) {
+    const previousAgent = this.active;
+    const switched = !previousAgent || previousAgent.name !== agent.name;
+    const transition = { previousAgent, switched };
+    if (switched) {
+      recordMetaEvent(this.deps.sessionKey(), "agent.handoff", {
+        from: previousAgent?.name ?? null,
+        to: agent.name,
+        // GENC-1351: was a restored snapshot waiting for this agent at activation?
+        restored: this.hasRestoredState(agent.name)
+      });
+    }
+    if (switched && previousAgent) await this.fireDeactivate(previousAgent, "switch");
+    if (switched && agent.onActivate) {
+      const restored = this.restoredStates[agent.name];
+      if (restored !== void 0) delete this.restoredStates[agent.name];
+      try {
+        await agent.onActivate({
+          agentName: agent.name,
+          sessionKey: this.deps.sessionKey(),
+          previousAgentName: previousAgent?.name,
+          signal: this.lifecycleAbortController.signal,
+          restored
+        });
+      } catch (e) {
+        logger2.warn(`${WARN_PREFIX}: onActivate("${agent.name}") threw:`, e);
+      }
+    }
+    const hasLifecycleHooks = !!(agent.onActivate || agent.onDeactivate);
+    if (switched && hasLifecycleHooks && this.flowOwner !== agent.name) {
+      this.flowOwner = agent.name;
+      transition.flowOwnerChangedTo = agent.name;
+    }
+    this.active = agent;
+    return transition;
+  }
+  /**
+   * Release the active agent: fire `onDeactivate` and drop the flow lock.
+   *
+   * The user pin is intentionally **not** cleared — someone who explicitly picked this agent
+   * should stay on it after the flow ends, so the next message starts a fresh flow on the same
+   * agent rather than routing through the classifier.
+   *
+   * Returns `undefined` when there was no active agent, so a caller can skip its events.
+   */
+  async release() {
+    const agent = this.active;
+    if (!agent) return void 0;
+    await this.fireDeactivate(agent, "release");
+    this.active = void 0;
+    const transition = { previousAgent: agent, switched: true };
+    if (this.flowOwner !== null) {
+      this.flowOwner = null;
+      transition.flowOwnerChangedTo = null;
+    }
+    return transition;
+  }
+  /**
+   * Fire `onDeactivate` on the active agent and abort pending lifecycle work, for session
+   * teardown, so machines release resources cleanly. The session is not reusable afterwards: the
+   * abort signal stays aborted, so a later `activate` would hand its hook a dead signal.
+   *
+   * `onDeactivate` runs **before** the abort, deliberately: teardown that needs to flush state
+   * would otherwise be handed an already-aborted signal and have to skip its own work. The cost is
+   * that an `onActivate` still in flight keeps running until `onDeactivate` finishes — both hold
+   * the same signal. Acceptable because the two are sequenced by `activate`, so overlap only
+   * happens if a hook resolves before the work it started; a hook that must stop immediately
+   * should own its own cancellation.
+   */
+  async dispose() {
+    const agent = this.active;
+    if (agent) await this.fireDeactivate(agent, "dispose");
+    this.lifecycleAbortController.abort();
+    this.active = void 0;
+  }
+  /**
+   * The one place `onDeactivate` is invoked. `reason` only reaches the warning text, which is what
+   * tells a log reader which path fired.
+   */
+  async fireDeactivate(agent, reason) {
+    if (!agent.onDeactivate) return;
+    const label = reason === "switch" ? "" : `${reason} `;
+    try {
+      await agent.onDeactivate({
+        agentName: agent.name,
+        sessionKey: this.deps.sessionKey(),
+        signal: this.lifecycleAbortController.signal
+      });
+    } catch (e) {
+      logger2.warn(`${WARN_PREFIX}: ${label}onDeactivate("${agent.name}") threw:`, e);
+    }
+  }
+};
+
+// src/components/chat-driver/chat-driver.constants.ts
+var DEFAULT_MAX_TOOL_ITERATIONS = 50;
+var DEFAULT_MAX_FOLD_OPERATIONS = 5;
+var DEFAULT_MAX_TURN_SNAPSHOTS = 400;
+var DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5;
+var MAX_STALE_TOOL_CALLS = DEFAULT_MAX_UNKNOWN_TOOL_CALLS * 2;
+var MAX_MALFORMED_RETRIES = 5;
+var MAX_EMPTY_RESPONSE_RETRIES = 3;
+var 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.";
+var 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 \u2014 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.";
+var MAX_SETUP_TRANSPORT_RETRIES = 3;
+var HARVESTED_SUBAGENT_EVENTS = /* @__PURE__ */ new Set([
+  "turn.retry",
+  "turn.error",
+  "tool.failed",
+  "tool.unresolved"
+]);
+var REQUEST_CONTINUATION_TOOL = "request_continuation";
+var HANDOFF_TOOL_RESULT_PLACEHOLDER = "Handoff to another specialist \u2014 routing continues on the next turn.";
+
 // src/utils/tool-fold.ts
 var TOOL_FOLD_SYMBOL = Symbol("toolFold");
 
+// src/components/chat-driver/fold-controller.ts
+var foldOf = (handler) => handler ? handler[TOOL_FOLD_SYMBOL] : void 0;
+var FoldController = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.stack = [];
+    /**
+     * Consecutive fold opens/closes with no tool call between them. A model that only opens and
+     * closes is making no progress, and the loop breaks out past a ceiling.
+     */
+    this.consecutiveOps = 0;
+  }
+  /** Drop all fold state. Called on an agent swap — each agent starts outside every fold. */
+  reset() {
+    this.stack = [];
+    this.consecutiveOps = 0;
+  }
+  /** Names of the currently open folds, outermost first. */
+  activeNames() {
+    return this.stack.map((f) => f.foldName);
+  }
+  get depth() {
+    return this.stack.length;
+  }
+  /** The innermost open fold's name, or `undefined` when none is open. */
+  get topName() {
+    return this.stack[this.stack.length - 1]?.foldName;
+  }
+  /** Count one fold operation and return the new consecutive total. */
+  noteOp() {
+    this.consecutiveOps += 1;
+    return this.consecutiveOps;
+  }
+  /** Real work happened, so the no-progress streak restarts. */
+  clearOps() {
+    this.consecutiveOps = 0;
+  }
+  /** Fold metadata for a tool name, or `undefined` if it is not a fold facade. */
+  foldFor(toolName) {
+    return foldOf(this.deps.getHandlers()[toolName]);
+  }
+  /**
+   * Which fold to **open** to reach `toolName`, or `null` if no registered fold contains it.
+   *
+   * Returns the outermost *registered* ancestor, not the innermost fold holding the tool — the one
+   * consumer uses the answer to tell the model what to call next, and a nested fold cannot be
+   * opened before its parent. The recursion therefore only descends through closed folds: once a
+   * fold is open its children are top-level in the live handler map and match directly.
+   */
+  findContaining(toolName, handlers) {
+    const source = handlers ?? this.deps.getHandlers();
+    for (const handler of Object.values(source)) {
+      const fold = foldOf(handler);
+      if (!fold) continue;
+      if (fold.handlers[toolName]) return fold.name;
+      if (this.findContaining(toolName, fold.handlers)) return fold.name;
+    }
+    return null;
+  }
+  /**
+   * If an open fold is hiding a previously-available tool, the fold to close to start getting it
+   * back, else `null`.
+   *
+   * Only exclusive folds hide tools — they replace the tool set on open rather than extending it —
+   * so a base tool that was visible beforehand sits in a frame's `previousHandlers` but not in the
+   * live map. Only the top fold's `close_` tool is active, so that is always the actionable step:
+   * closing repeatedly walks back to a tool further down the stack.
+   */
+  hidingTool(toolName) {
+    if (this.stack.length === 0) return null;
+    const hidden = this.stack.some((f) => f.previousHandlers[toolName]);
+    return hidden ? this.topName : null;
+  }
+  /** Open a fold: push a frame, swap the tool set, and return the response for the model. */
+  open(foldName, fold, args, activeToolCallId) {
+    for (const key of Object.keys(args)) {
+      const innerHandler = fold.handlers[key];
+      if (innerHandler) {
+        logger2.debug(`ChatDriver: fold shortcut dispatch "${foldName}" \u2192 "${key}"`);
+        this.pushFrame(foldName);
+        this.applyToolSet(fold, foldName);
+        this.clearOps();
+        const innerArgs = typeof args[key] === "object" && args[key] !== null ? args[key] : {};
+        return innerHandler(innerArgs, this.deps.handlerContext(activeToolCallId)).then(
+          (r) => typeof r === "string" ? r : JSON.stringify(r)
+        );
+      }
+    }
+    this.pushFrame(foldName);
+    this.applyToolSet(fold, foldName);
+    const closeToolName = `close_${foldName}`;
+    const innerToolNames = fold.tools.map((t) => t.name);
+    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);
+  }
+  /** Close the top fold: pop the frame, restore the tool set it captured. */
+  close() {
+    const frame = this.stack.pop();
+    if (!frame) return "No fold is currently open.";
+    this.deps.setDefinitions(frame.previousDefinitions);
+    this.deps.setHandlers(frame.previousHandlers);
+    const toolNames = frame.previousDefinitions.map((t) => t.name);
+    return `Fold closed: ${frame.foldName}. Tools now available: ${toolNames.join(", ")}.`;
+  }
+  /** The fold-awareness suffix appended to the system prompt on each LLM call. */
+  systemPromptSuffix() {
+    const activeFolds = Object.values(this.deps.getHandlers()).map(foldOf).filter((f) => !!f);
+    if (activeFolds.length === 0 && this.stack.length === 0) return "";
+    const parts = [
+      "\n\n--- Tool Folds ---",
+      "Some tools are grouped into folds. You may see tool calls in the conversation history for tools that are not currently available \u2014 they are inside a fold. To access them, invoke the fold tool first."
+    ];
+    if (this.topName) {
+      parts.push(
+        `You are currently inside the "${this.topName}" fold. Call close_${this.topName} when you are done with these tools.`
+      );
+    }
+    for (const fold of activeFolds) parts.push(`\u2022 ${fold.name}: ${fold.description}`);
+    return parts.join("\n");
+  }
+  pushFrame(foldName) {
+    this.stack.push({
+      foldName,
+      previousDefinitions: [...this.deps.getDefinitions()],
+      previousHandlers: { ...this.deps.getHandlers() }
+    });
+  }
+  /**
+   * Install the fold's inner tool set, replacing it (exclusive) or extending it (non-exclusive),
+   * and inject the close tool. Does not touch the stack.
+   */
+  applyToolSet(fold, foldName) {
+    const closeToolName = `close_${foldName}`;
+    const newDefs = [];
+    const newHandlers = {};
+    if (!fold.exclusive) {
+      for (const def of this.deps.getDefinitions()) {
+        if (def.name !== foldName) newDefs.push(def);
+      }
+      for (const [name, handler] of Object.entries(this.deps.getHandlers())) {
+        if (name !== foldName) newHandlers[name] = handler;
+      }
+    }
+    newDefs.push(...fold.tools);
+    Object.assign(newHandlers, fold.handlers);
+    newDefs.push({
+      name: closeToolName,
+      description: `Close the ${foldName} fold and return to the previous set of tools.`,
+      parameters: { type: "object", properties: {} }
+    });
+    newHandlers[closeToolName] = async () => this.close();
+    this.deps.setDefinitions(newDefs);
+    this.deps.setHandlers(newHandlers);
+  }
+};
+
 // src/components/chat-driver/turn-failures.ts
 var TURN_FAILURE_EXITS = {
   contextGuard: {
@@ -4471,6 +4897,15 @@ var TURN_FAILURE_EXITS = {
   // `TurnFailureReason` and cost the literal types that let `turn-failures.test.ts` pin the
   // two deliberate divergences at compile time instead of at runtime.
 };
+function turnDone(failureReason, budget, providerRefused) {
+  if (!failureReason) return { reason: "done" };
+  return {
+    reason: "done",
+    failureReason,
+    ...budget ? { budget } : {},
+    ...providerRefused ? { providerRefused } : {}
+  };
+}
 
 // src/components/chat-driver/chat-driver.ts
 var toolResultImages = (result) => {
@@ -4501,25 +4936,6 @@ var budgetDetailOf = (e) => {
     ...e.otherVendorAvailable != null ? { otherVendorAvailable: e.otherVendorAvailable } : {}
   };
 };
-var DEFAULT_MAX_TOOL_ITERATIONS = 50;
-var DEFAULT_MAX_FOLD_OPERATIONS = 5;
-var DEFAULT_MAX_TURN_SNAPSHOTS = 400;
-var DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5;
-var MAX_STALE_TOOL_CALLS = DEFAULT_MAX_UNKNOWN_TOOL_CALLS * 2;
-var MAX_MALFORMED_RETRIES = 5;
-var MAX_EMPTY_RESPONSE_RETRIES = 3;
-var 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.";
-var 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 \u2014 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.";
-var MAX_SETUP_TRANSPORT_RETRIES = 3;
-var SUGGESTIONS_HISTORY_WINDOW = 8;
-var HARVESTED_SUBAGENT_EVENTS = /* @__PURE__ */ new Set([
-  "turn.retry",
-  "turn.error",
-  "tool.failed",
-  "tool.unresolved"
-]);
-var REQUEST_CONTINUATION_TOOL = "request_continuation";
-var HANDOFF_TOOL_RESULT_PLACEHOLDER = "Handoff to another specialist \u2014 routing continues on the next turn.";
 var ChatDriver = class _ChatDriver extends EventTarget {
   constructor(providerRegistry, config = {}) {
     super();
@@ -4582,10 +4998,18 @@ var ChatDriver = 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;
     /**
@@ -4685,6 +5109,19 @@ var ChatDriver = class _ChatDriver extends EventTarget {
      * picked up on the next turn.
      */
     this.resolvedStatusCache = /* @__PURE__ */ 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).
@@ -4721,6 +5158,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
       condenseBatchCalls = 1,
       maxTurnSnapshots = DEFAULT_MAX_TURN_SNAPSHOTS,
       sessionKey = "",
+      deferAgentRelease = false,
       activityBus = NOOP_ACTIVITY_BUS,
       budgetExhaustedMessage,
       providerRefusedMessage
@@ -4728,6 +5166,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     this.maxToolIterations = maxToolIterations;
     this.condenseBatchCalls = condenseBatchCalls;
     this.sessionKey = sessionKey;
+    this.deferAgentRelease = deferAgentRelease;
     this.activityBus = activityBus;
     this.budgetExhaustedMessageOverride = budgetExhaustedMessage;
     this.providerRefusedMessageOverride = providerRefusedMessage;
@@ -4775,12 +5214,13 @@ var ChatDriver = class _ChatDriver extends EventTarget {
    * interaction is instead settled by `resolveInteraction` (user response or
    * timeout), which also stamps history and reverts the chat-input override.
    */
-  dispose() {
+  async dispose() {
     this.lifecycleController.abort(new DOMException("AI assistant driver disposed", "AbortError"));
     for (const handle of this.interactionContexts.values()) handle.dispose();
     this.interactionContexts.clear();
     this.unsubscribeRegistry?.();
     this.unsubscribeRegistry = void 0;
+    await this.agentSession.dispose();
   }
   /**
    * Stop the current turn (user "stop" button). Aborts the in-flight provider
@@ -4829,23 +5269,6 @@ var ChatDriver = 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" };
-    return {
-      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.
@@ -4871,7 +5294,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     } else {
       this.appendDriverNotice(overrides?.copy ?? exit.copy);
     }
-    return this.turnDone(exit.resultReason, overrides?.budget, overrides?.providerRefused);
+    return turnDone(exit.resultReason, overrides?.budget, overrides?.providerRefused);
   }
   /**
    * Terminal budget outcome for a wall hit **outside** the tool loop — today,
@@ -4924,7 +5347,7 @@ var ChatDriver = 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).
@@ -4969,8 +5392,66 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     };
   }
   /**
-   * 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
+   */
+  async activateAgent(config) {
+    await 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) {
     if (config.name !== this.activeAgentName) this.currentActivation += 1;
@@ -5009,8 +5490,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     if (typeof config.provider === "string") {
       this.resolveProviderByName(config.provider, config.name);
     }
-    this.foldStack = [];
-    this.consecutiveFoldOps = 0;
+    this.folds.reset();
     this.everSeenToolNames.clear();
   }
   /**
@@ -5127,15 +5607,6 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     this.resolvedStatusCache.set(name, status);
     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.
-   */
-  async resolveTurnInput(input, ctx) {
-    if (input === void 0) return void 0;
-    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.
@@ -5182,6 +5653,19 @@ var ChatDriver = 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.
+   */
+  async releaseIfRequested() {
+    if (this.deferAgentRelease || !this.agentReleaseRequested) return;
+    this.agentReleaseRequested = false;
+    await 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
@@ -5329,7 +5813,7 @@ var ChatDriver = 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
@@ -5351,65 +5835,23 @@ var ChatDriver = class _ChatDriver extends EventTarget {
   getHistoryForPersistence() {
     return condenseForPersistence([...this.history], this.condensePolicies);
   }
+  /**
+   * {@inheritDoc AiDriver.getSuggestions}
+   *
+   * @beta
+   */
   async getSuggestions(history, prompt2, count, allAgentInfo) {
-    const defaultProvider = this.providerRegistry.default();
-    if (!defaultProvider.prompt) {
-      logger2.warn("ChatDriver: default AI provider does not implement prompt()");
-      return [];
-    }
-    let agentContext = "";
-    let toolContext = "";
-    if (allAgentInfo?.length) {
-      const agentDescriptions = allAgentInfo.map((agent) => {
-        const tools = agent.tools.map((t) => t.name).join(", ");
-        return `- ${agent.name} (${agent.description}): ${tools ? `(Tools: ${tools})` : "No tools"}`;
-      }).join("\n");
-      agentContext = `The assistant has the following capabilities:
-${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}.` : "";
-    }
-    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 ? `
-
-<capabilities>
-${[agentContext, toolContext].filter(Boolean).join("\n")}
-</capabilities>
-Suggestions must only cover what the agent is capable of. Do not suggest anything outside these capabilities.` : "";
-    const guidanceBlock = prompt2 ? `
-
-Additional guidance: "${prompt2}"` : "";
-    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 \u2014 do not invent specific names, IDs, or data (e.g. prefer "Search for a trade" over "Find all trades with Client A").` + capabilitiesBlock + guidanceBlock + `
-
-Output format (strict):
-- Exactly ${count} lines.
-- One suggestion per line.
-- No numbering, bullets, markdown, emojis, code blocks, or quotes around the suggestion.
-- No preamble, headings, summary, or commentary before or after the list.`;
-    } else {
-      const conversationContext = history.filter(
-        (m) => (m.role === "user" || m.role === "assistant") && !m.toolCalls?.length && !m.thinking && !!m.content?.trim()
-      ).slice(-SUGGESTIONS_HISTORY_WINDOW).map((m) => `${m.role === "user" ? "User" : "Assistant"}: ${m.content}`).join("\n");
-      userMessage = `<conversation_history>
-${conversationContext}
-</conversation_history>
-
-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 + `
-
-Output format (strict):
-- Exactly ${count} lines.
-- One suggestion per line.
-- No numbering, bullets, markdown, emojis, code blocks, or quotes around the suggestion.
-- No preamble, headings, summary, or commentary before or after the list.`;
-    }
-    const text = await defaultProvider.prompt(userMessage, { systemPrompt });
-    return text.split("\n").map((s) => s.trim()).map((s) => s.replace(/^([-*•]|\d+[.)])\s+/, "")).map((s) => s.replace(/^[*_]{1,3}|[*_]{1,3}$/g, "").trim()).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,
+      prompt2,
+      count,
+      allAgentInfo
+    );
   }
   /**
    * Whether `compact()` would do anything right now — a summarizable run of older
@@ -5787,7 +6229,7 @@ Output format (strict):
       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 {
       recordMetaEvent(this.sessionKey, "turn.end", {
@@ -5798,6 +6240,7 @@ Output format (strict):
       this.busy = false;
       this.endTurn();
       this.activityBus.publish("tool-loop-end", this.loopEndDetail(result));
+      await this.releaseIfRequested();
     }
   }
   /**
@@ -6051,7 +6494,7 @@ Output format (strict):
       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 {
       recordMetaEvent(this.sessionKey, "turn.end", {
@@ -6062,136 +6505,10 @@ Output format (strict):
       this.busy = false;
       this.endTurn();
       this.activityBus.publish("tool-loop-end", this.loopEndDetail(result));
+      await 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] : void 0;
-  }
-  /**
-   * 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 ?? this.toolHandlers;
-    for (const [, handler] of Object.entries(source)) {
-      const fold = handler[TOOL_FOLD_SYMBOL];
-      if (!fold) continue;
-      if (fold.handlers[toolName]) return fold.name;
-      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) {
-      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;
-      }
-    }
-    newDefs.push(...fold.tools);
-    Object.assign(newHandlers, fold.handlers);
-    newDefs.push({
-      name: closeToolName,
-      description: `Close the ${foldName} fold and return to the previous set of tools.`,
-      parameters: { type: "object", properties: {} }
-    });
-    newHandlers[closeToolName] = async () => 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) {
-    for (const key of Object.keys(args)) {
-      const innerHandler = fold.handlers[key];
-      if (innerHandler) {
-        logger2.debug(`ChatDriver: fold shortcut dispatch "${foldName}" \u2192 "${key}"`);
-        this.pushFoldFrame(foldName);
-        this.applyFoldToolSet(fold, foldName);
-        this.consecutiveFoldOps = 0;
-        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)
-        );
-      }
-    }
-    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: { ...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() {
-    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 \u2014 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(`\u2022 ${fold.name}: ${fold.description}`);
-    }
-    return parts.join("\n");
-  }
   // ---------------------------------------------------------------------------
   // Tool loop
   // ---------------------------------------------------------------------------
@@ -6286,7 +6603,7 @@ Output format (strict):
       if (typeof this.displayName === "function") {
         this.activeAgentLabel = await this.displayName(promptCtx);
       }
-      const foldSuffix = this.buildFoldSystemPromptSuffix();
+      const foldSuffix = this.folds.systemPromptSuffix();
       const retryNudge = malformedAttempts > 0 ? `
 
 ${MALFORMED_CALL_NUDGE}` : emptyResponseAttempts > 0 ? `
@@ -6328,14 +6645,14 @@ ${EMPTY_RESPONSE_NUDGE}` : "";
       ] = (
         // oxlint-disable-next-line no-await-in-loop
         await 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(void 0) : this.resolveTurnInput(
+          thinkingPolicyPinned ? Promise.resolve(void 0) : resolveTurnInput(
             this.activeThinkingPolicyInput,
             promptCtx
           )
@@ -6511,7 +6828,7 @@ ${tailBody}
               isSubAgent: true
             });
             this.failSubAgent("budget_exhausted", this.budgetWallDetail);
-            return this.turnDone("budget-exhausted", this.budgetWallDetail);
+            return turnDone("budget-exhausted", this.budgetWallDetail);
           }
           return this.reportBudgetExhausted(e);
         }
@@ -6644,36 +6961,36 @@ ${tailBody}
       if (toolCalls.length > 0) {
         await Promise.all(
           toolCalls.map(async (tc) => {
-            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) {
                 logger2.warn(
                   `ChatDriver: fold operation limit (${this.maxFoldOperations}) reached \u2014 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 = await this.openFold(tc.name, fold, tc.args, tc.id);
+              const content = await this.folds.open(tc.name, fold, tc.args, tc.id);
               executedById.set(tc.id, { toolCallId: tc.id, content });
               iterations -= 1;
               return;
             }
-            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;
@@ -6681,7 +6998,7 @@ ${tailBody}
             }
             const handler = this.toolHandlers[tc.name];
             if (!handler) {
-              const containingFold = this.findFoldContaining(tc.name);
+              const containingFold = this.folds.findContaining(tc.name);
               if (containingFold) {
                 logger2.debug(
                   `ChatDriver: model called folded tool "${tc.name}" \u2014 guiding to open "${containingFold}"`
@@ -6701,7 +7018,7 @@ ${tailBody}
               }
               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}.`;
@@ -6797,12 +7114,12 @@ RECOVERY: this tool failed once \u2014 you may retry it, or take a different val
         );
       }
       if (anyRealToolExecuted) {
-        this.consecutiveFoldOps = 0;
+        this.folds.clearOps();
         this.consecutiveUnknownToolCalls = 0;
         this.recentUnknownToolNames.clear();
         this.recentStaleToolNames.clear();
       }
-      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({
@@ -6839,7 +7156,7 @@ RECOVERY: this tool failed once \u2014 you may retry it, or take a different val
         const tcMsg = this.history[tcMsgIdx];
         const availableToolNames = Object.keys(this.toolHandlers);
         const annotatedCalls = tcMsg.toolCalls.map((tc) => {
-          const isFoldOpen = !!this.getFold(tc.name) || // Was a fold facade at time of the call (now the tool set has changed)
+          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
           executedById.get(tc.id)?.content?.startsWith("Fold opened:");
           const isFoldClose = executedById.get(tc.id)?.content?.startsWith("Fold closed:");
@@ -6898,7 +7215,7 @@ RECOVERY: this tool failed once \u2014 you may retry it, or take a different val
         return { reason: "agent-handoff", summary, remainingTask };
       }
       if (this.subAgentCompletion) {
-        return this.turnDone();
+        return turnDone();
       }
     }
     if (iterations >= this.maxToolIterations) {
@@ -6912,7 +7229,7 @@ RECOVERY: this tool failed once \u2014 you may retry it, or take a different val
       });
       return this.endTurnWithFailure(TURN_FAILURE_EXITS.maxIterations);
     }
-    return this.turnDone();
+    return turnDone();
   }
   /**
    * Append prose the DRIVER wrote rather than the model — a failure notice, a limit explanation,
@@ -7020,11 +7337,6 @@ var OrchestratingDriver = class extends EventTarget {
     super();
     this.providerRegistry = providerRegistry;
     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();
     /**
      * Set by `cancel()` for the duration of a `sendMessage` run. Breaks the
      * handoff loop so we don't classify or start another agent turn after the
@@ -7042,28 +7354,6 @@ var OrchestratingDriver = class extends EventTarget {
      * made it vanish. Reset at the top of each `runOrchestratedTurn`.
      */
     this.userMessageAppended = false;
-    /**
-     * Sticky user pick from the picker (or the host's `setAgent` API). Only
-     * changes on explicit user action. Survives flow completion: when a stateful
-     * agent releases, the user-pin stays put and routing falls back to it on
-     * the next turn.
-     */
-    this.pinnedAgentName = null;
-    /**
-     * Transient flow lock — set when a stateful agent's `onActivate` fires,
-     * cleared by `releaseActiveAgent`. While non-null, routing precedence goes
-     * to this agent and the picker is locked. Independent of
-     * `pinnedAgentName` so completing a flow doesn't wipe the user's sticky
-     * choice.
-     */
-    this.flowOwnerAgentName = null;
-    /**
-     * Per-agent restored state for a rehydrated session, keyed by agent name.
-     * Primed by the host on restore; each entry is passed to that agent's
-     * `onActivate` as `ctx.restored` on its next activation, then deleted so a
-     * later re-activation starts fresh.
-     */
-    this.restoredAgentStates = {};
     this.sessionKey = options.sessionKey ?? "";
     this.maxHandoffs = options.maxHandoffs ?? DEFAULT_MAX_HANDOFFS;
     this.classifierHistoryLength = options.classifierHistoryLength ?? DEFAULT_CLASSIFIER_HISTORY_LENGTH;
@@ -7084,7 +7374,9 @@ var OrchestratingDriver = class extends EventTarget {
       maxTurnSnapshots: options.maxTurnSnapshots,
       sessionKey: this.sessionKey,
       activityBus: options.activityBus,
-      budgetExhaustedMessage: options.budgetExhaustedMessage
+      budgetExhaustedMessage: options.budgetExhaustedMessage,
+      // This driver releases after the turn so it can fire the host-facing events; see the option.
+      deferAgentRelease: true
     });
     this.chatDriver.addEventListener("history-updated", (e) => {
       this.dispatchEvent(new CustomEvent("history-updated", { detail: e.detail }));
@@ -7121,6 +7413,28 @@ var OrchestratingDriver = class extends EventTarget {
       );
     });
   }
+  /**
+   * The stateful-agent contract (§7.1): active agent, user pin, flow lock, restored state, and
+   * the `onActivate` / `onDeactivate` hooks.
+   *
+   * **The inner driver's session, not one of our own.** One session is the invariant: two would
+   * let the outer and inner driver disagree about which agent is active, and the inner one would
+   * never be activated at all, because this driver installs a *decorated* config through
+   * `applyAgent` rather than going via `ChatDriver.activateAgent`. This driver keeps the routing
+   * decisions; the session owns the lifecycle.
+   */
+  get agentSession() {
+    return this.chatDriver.agentSession;
+  }
+  /**
+   * The active agent, or `undefined` before the first activation and after a release.
+   *
+   * Kept as an accessor over `agentSession` rather than removed: it is a public member of an
+   * exported class, so nothing in this package reading it is not the same as nothing reading it.
+   */
+  get activeAgent() {
+    return this.agentSession.getActive();
+  }
   resolveInteraction(interactionId, result) {
     this.chatDriver.resolveInteraction(interactionId, result);
   }
@@ -7146,7 +7460,7 @@ var OrchestratingDriver = class extends EventTarget {
    * return to automatic routing.
    */
   setPinnedAgent(name) {
-    this.pinnedAgentName = name;
+    this.agentSession.setPinned(name);
   }
   /**
    * Set the flow-owner lock — used to restore state from Redux on driver
@@ -7155,7 +7469,7 @@ var OrchestratingDriver = class extends EventTarget {
    * for.
    */
   setFlowOwner(name) {
-    this.flowOwnerAgentName = name;
+    this.agentSession.setFlowOwner(name);
   }
   loadHistory(messages) {
     this.chatDriver.loadHistory(messages);
@@ -7314,7 +7628,7 @@ var OrchestratingDriver = class extends EventTarget {
   }
   /** {@inheritDoc AiDriver.primeRestoredAgentState} */
   primeRestoredAgentState(snapshots) {
-    this.restoredAgentStates = { ...snapshots };
+    this.agentSession.primeRestoredStates(snapshots);
   }
   /**
    * {@inheritDoc AiDriver.getContextReserve}
@@ -7344,51 +7658,14 @@ var OrchestratingDriver = class extends EventTarget {
   }
   /** {@inheritDoc AiDriver.getActiveAgent} */
   getActiveAgent() {
-    return this.activeAgent;
+    return this.agentSession.getActive();
   }
   async applyAgent(agent) {
-    const previousAgent = this.activeAgent;
-    const isSwitch = !previousAgent || previousAgent.name !== agent.name;
-    if (isSwitch) {
-      recordMetaEvent(this.sessionKey, "agent.handoff", {
-        from: previousAgent?.name ?? null,
-        to: agent.name,
-        // GENC-1351: was a restored snapshot waiting for this agent at activation?
-        restored: this.restoredAgentStates[agent.name] !== void 0
-      });
+    const { previousAgent, flowOwnerChangedTo } = await this.agentSession.activate(agent);
+    if (flowOwnerChangedTo !== void 0) {
+      this.dispatchEvent(new CustomEvent("flow-owner-changed", { detail: flowOwnerChangedTo }));
     }
-    if (isSwitch && previousAgent?.onDeactivate) {
-      try {
-        await previousAgent.onDeactivate({
-          agentName: previousAgent.name,
-          sessionKey: this.sessionKey,
-          signal: this.lifecycleAbortController.signal
-        });
-      } catch (e) {
-        logger2.warn(`OrchestratingDriver: onDeactivate("${previousAgent.name}") threw:`, e);
-      }
-    }
-    if (isSwitch && agent.onActivate) {
-      const restored = this.restoredAgentStates[agent.name];
-      if (restored !== void 0) delete this.restoredAgentStates[agent.name];
-      try {
-        await agent.onActivate({
-          agentName: agent.name,
-          sessionKey: this.sessionKey,
-          previousAgentName: previousAgent?.name,
-          signal: this.lifecycleAbortController.signal,
-          restored
-        });
-      } catch (e) {
-        logger2.warn(`OrchestratingDriver: onActivate("${agent.name}") threw:`, e);
-      }
-    }
-    const hasLifecycleHooks = !!(agent.onActivate || agent.onDeactivate);
-    if (isSwitch && hasLifecycleHooks && this.flowOwnerAgentName !== agent.name) {
-      this.flowOwnerAgentName = agent.name;
-      this.dispatchEvent(new CustomEvent("flow-owner-changed", { detail: agent.name }));
-    }
-    const isTerminal = isFallback(agent) || this.pinnedAgentName !== null || this.flowOwnerAgentName !== null || hasLifecycleHooks;
+    const isTerminal = isFallback(agent) || this.agentSession.getPinned() !== null || this.agentSession.getFlowOwner() !== null || !!(agent.onActivate || agent.onDeactivate);
     let agentToApply = agent;
     if (!isTerminal) {
       const declaredTools = agent.toolDefinitions;
@@ -7409,7 +7686,6 @@ var OrchestratingDriver = class extends EventTarget {
     }
     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 }));
   }
@@ -7425,25 +7701,14 @@ var OrchestratingDriver = class extends EventTarget {
    * routing through the classifier.
    */
   async releaseActiveAgent() {
-    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) {
-        logger2.warn(`OrchestratingDriver: release onDeactivate("${agent.name}") threw:`, e);
-      }
-    }
-    this.activeAgent = void 0;
-    if (this.flowOwnerAgentName !== null) {
-      this.flowOwnerAgentName = null;
-      this.dispatchEvent(new CustomEvent("flow-owner-changed", { detail: null }));
+    const released = await this.agentSession.release();
+    if (!released) return;
+    if (released.flowOwnerChangedTo !== void 0) {
+      this.dispatchEvent(
+        new CustomEvent("flow-owner-changed", { detail: released.flowOwnerChangedTo })
+      );
     }
-    this.dispatchEvent(new CustomEvent("agent-released", { detail: agent }));
+    this.dispatchEvent(new CustomEvent("agent-released", { detail: released.previousAgent }));
     this.dispatchEvent(new CustomEvent("agent-changed", { detail: void 0 }));
   }
   /**
@@ -7461,21 +7726,8 @@ var OrchestratingDriver = class extends EventTarget {
    * release resources cleanly.
    */
   async dispose() {
-    const previousAgent = this.activeAgent;
-    if (previousAgent?.onDeactivate) {
-      try {
-        await previousAgent.onDeactivate({
-          agentName: previousAgent.name,
-          sessionKey: this.sessionKey,
-          signal: this.lifecycleAbortController.signal
-        });
-      } catch (e) {
-        logger2.warn(`OrchestratingDriver: dispose onDeactivate("${previousAgent.name}") threw:`, e);
-      }
-    }
-    this.lifecycleAbortController.abort();
-    this.chatDriver.dispose();
-    this.activeAgent = void 0;
+    await this.agentSession.dispose();
+    await this.chatDriver.dispose();
   }
   /**
    * Record one routing decision on the debug timeline — what was chosen, why, what it cost, and
@@ -7663,7 +7915,7 @@ ${recentMessages}` : ""}`;
    * — protects against stale state after an agents-array reassignment.
    */
   resolvePinnedAgent() {
-    const name = this.flowOwnerAgentName ?? this.pinnedAgentName;
+    const name = this.agentSession.getLockedName();
     if (name === null) return void 0;
     const match = this.agents.find((a) => a.name === name);
     if (!match) {