@zvada/agent-server 0.2.0

package/src/core/agents/claude-code/generator-session.ts

@@ -0,0 +1,344 @@
+import type { Query as CCQuery, SDKMessage, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import type {
+	Options as CCOptions,
+	CanUseTool,
+	McpSetServersResult,
+	PermissionResult,
+} from "@anthropic-ai/claude-agent-sdk";
+import { AsyncQueue } from "../../../protocol/index.ts";
+import type { McpServerConfig } from "../../../protocol/index.ts";
+import type { PermissionRequestHandler } from "../base.ts";
+import { claudeToolMeta } from "../tool-meta.ts";
+import {
+	type ClaudeSdkOptionOverrides,
+	type ClaudeSessionConfig,
+	type SdkMcpServers,
+	buildClaudeOptions,
+} from "./options.ts";
+
+/**
+ * Pre-broker tool policy: the host's programmatic say on every tool call
+ * BEFORE the interactive permission broker. Returns the SDK's own
+ * `PermissionResult` (so hosts keep full native power: `updatedInput`,
+ * `updatedPermissions`) or undefined to fall through to the broker.
+ * Operator embed-tier only — never wire-sourced.
+ */
+export type ClaudeToolPolicy = (
+	toolName: string,
+	input: Record<string, unknown>,
+	ctx: { sessionId: string; toolUseId: string; agentId?: string },
+) => PermissionResult | undefined | Promise<PermissionResult | undefined>;
+
+/** SDK lifecycle hooks factory (decision-capable); runs once at session spawn. */
+export type ClaudeHooksFactory = (ctx: {
+	sessionId: string;
+	currentTurnId: () => string | undefined;
+}) => CCOptions["hooks"];
+
+/** Embed-tier extras threaded from ClaudeCodeAgentOptions into each session. */
+export interface ClaudeSessionExtras {
+	/** Factory for in-process MCP servers; invoked ONCE at session spawn. */
+	sdkMcpServers?: (ctx: {
+		sessionId: string;
+		cwd: string;
+	}) => SdkMcpServers | Promise<SdkMcpServers>;
+	toolPolicy?: ClaudeToolPolicy;
+	/** See ClaudeHooksFactory — a Stop hook may return `{decision: "block"}`. */
+	hooks?: ClaudeHooksFactory;
+	/**
+	 * Operator escape hatch: raw SDK option overrides merged over the engine's
+	 * options at session spawn (embed-tier only — never wire-sourced). The
+	 * ClaudeSdkOptionOverrides type excludes engine-wired fields.
+	 */
+	sdkOptions?: (ctx: {
+		sessionId: string;
+		cwd: string;
+	}) => ClaudeSdkOptionOverrides | Promise<ClaudeSdkOptionOverrides>;
+}
+
+type SessionState = "starting" | "idle" | "busy" | "terminated";
+type ClaudeContent = SDKUserMessage["message"]["content"];
+
+/** Per-turn handle: iterate `events` until the turn's `result` arrives (or the turn errors). */
+export interface ClaudeEventTap {
+	readonly events: AsyncIterable<SDKMessage>;
+	detach(): void;
+}
+
+/**
+ * Wraps one long-lived Claude `query()` call. The prompt input is an AsyncQueue
+ * that stays open across turns, so the same subprocess (and its context) is
+ * reused turn to turn. A background loop reads SDK output and routes it to the
+ * current turn's tap; the `result` event marks the turn boundary.
+ *
+ * Lifecycle: starting → idle ⇄ busy → terminated.
+ */
+export class ClaudeGeneratorSession {
+	private state: SessionState = "starting";
+	private config: ClaudeSessionConfig;
+
+	private readonly promptQueue = new AsyncQueue<SDKUserMessage>();
+	private query: CCQuery | null = null;
+	/** Set per turn (inside sendMessage, after the idle wait) for hook contexts. */
+	currentTurnId?: string;
+	/** Resolved once at spawn; re-merged into every hot-swap. */
+	private sdkServers?: SdkMcpServers;
+	private nativeSessionId: string | null = null;
+
+	private currentTap: AsyncQueue<SDKMessage> | null = null;
+	private readonly idleWaiters: Array<() => void> = [];
+
+	/**
+	 * The engine's permission broker for the CURRENT turn. Mutable because the
+	 * SDK's `canUseTool` is fixed at spawn while the handler changes per turn
+	 * (the long-lived query outlives any one run). Unset (e.g. a turn driven
+	 * outside the runtime) auto-allows — mode-level gating still applies.
+	 */
+	permissionHandler?: PermissionRequestHandler;
+
+	private idleTimer: ReturnType<typeof setTimeout> | null = null;
+	private readonly idleTimeoutMs: number;
+
+	constructor(
+		readonly id: string,
+		config: ClaudeSessionConfig,
+		private readonly onTerminated?: () => void,
+		private readonly extras?: ClaudeSessionExtras,
+	) {
+		this.config = { ...config };
+		this.idleTimeoutMs = config.idleTimeoutMs ?? 5 * 60_000;
+	}
+
+	get currentState(): SessionState {
+		return this.state;
+	}
+	get currentSessionId(): string | null {
+		return this.nativeSessionId;
+	}
+	get currentConfig(): Readonly<ClaudeSessionConfig> {
+		return this.config;
+	}
+
+	/** Hot-swap the model without losing context (Claude `setModel`). */
+	async setModel(model: string | undefined): Promise<void> {
+		if (this.state === "terminated" || !this.query) return;
+		await this.query.setModel(model);
+		this.config = { ...this.config, model };
+	}
+
+	/**
+	 * Hot-swap the wire-configured MCP servers on the LIVE session (no restart,
+	 * context intact). In-process servers are re-merged so a swap can never drop
+	 * the host's own tools; `currentConfig` is synced so the next turn's
+	 * hot-swap check doesn't re-apply.
+	 */
+	async setMcpServers(
+		servers: Record<string, McpServerConfig>,
+	): Promise<McpSetServersResult | undefined> {
+		if (this.state === "terminated" || !this.query) return undefined;
+		const result = await this.query.setMcpServers({ ...servers, ...this.sdkServers });
+		const failed = Object.entries(result.errors ?? {});
+		if (failed.length) {
+			// Do NOT sync config: the fingerprint stays different, so the next
+			// turn retries instead of reporting a failed set as attached.
+			throw new Error(
+				`mcp servers failed to connect: ${failed.map(([n, e]) => `${n} (${e})`).join(", ")}`,
+			);
+		}
+		this.config = { ...this.config, mcpServers: servers };
+		return result;
+	}
+
+	async start(): Promise<void> {
+		if (this.state !== "starting") throw new Error(`Cannot start in state: ${this.state}`);
+		const sdk = await import("@anthropic-ai/claude-agent-sdk");
+		this.sdkServers = await this.extras?.sdkMcpServers?.({
+			sessionId: this.id,
+			cwd: this.config.cwd,
+		});
+		const options = buildClaudeOptions(
+			this.config,
+			this.sdkServers,
+			await this.extras?.sdkOptions?.({ sessionId: this.id, cwd: this.config.cwd }),
+		);
+		if (this.extras?.hooks) {
+			options.hooks = this.extras.hooks({
+				sessionId: this.id,
+				currentTurnId: () => this.currentTurnId,
+			});
+		}
+		// Bridge the SDK's approval callback to the engine's permission broker.
+		// The closure reads the mutable per-turn handler set by the agent.
+		options.canUseTool = createCanUseTool({
+			sessionId: this.id,
+			policy: this.extras?.toolPolicy,
+			getBroker: () => this.permissionHandler,
+		});
+		this.query = sdk.query({
+			prompt: this.promptQueue as AsyncIterable<SDKUserMessage>,
+			options,
+		});
+		void this.consumeEvents();
+		this.state = "idle";
+		this.resetIdleTimer();
+	}
+
+	/** Push a user message; returns a tap that streams this turn's events. */
+	async sendMessage(content: ClaudeContent, turnId?: string): Promise<ClaudeEventTap> {
+		while (this.state !== "idle") {
+			if (this.state === "terminated") throw new Error("Session is terminated");
+			await this.waitForIdle();
+		}
+		this.clearIdleTimer();
+		this.state = "busy";
+		// After the idle wait, so a queued turn can't relabel the in-flight one.
+		this.currentTurnId = turnId;
+
+		const tap = new AsyncQueue<SDKMessage>();
+		this.currentTap = tap;
+		this.promptQueue.push({
+			type: "user",
+			message: { role: "user", content },
+			parent_tool_use_id: null,
+			...(this.nativeSessionId ? { session_id: this.nativeSessionId } : {}),
+		} as SDKUserMessage);
+
+		return {
+			events: tap,
+			detach: () => {
+				if (this.currentTap === tap) this.currentTap = null;
+				tap.end();
+			},
+		};
+	}
+
+	/** Stop the in-flight turn without killing the session. */
+	async interruptTurn(): Promise<void> {
+		if ((this.state !== "busy" && this.state !== "starting") || !this.query) return;
+		try {
+			await Promise.race([
+				this.query.interrupt(),
+				new Promise<never>((_, reject) =>
+					setTimeout(() => reject(new Error("interrupt timeout")), 2000),
+				),
+			]);
+		} catch {
+			// best-effort
+		}
+	}
+
+	async terminate(): Promise<void> {
+		if (this.state === "terminated") return;
+		this.clearIdleTimer();
+		this.state = "terminated";
+		const query = this.query;
+		this.query = null;
+		this.promptQueue.end();
+		this.currentTap?.end();
+		this.currentTap = null;
+		for (const w of this.idleWaiters) w();
+		this.idleWaiters.length = 0;
+		try {
+			// The SDK documents close() as the forceful subprocess/MCP cleanup path.
+			query?.close();
+		} finally {
+			this.onTerminated?.();
+		}
+	}
+
+	private async consumeEvents(): Promise<void> {
+		if (!this.query) return;
+		try {
+			for await (const event of this.query) {
+				if (event.type === "system" && event.subtype === "init" && event.session_id) {
+					this.nativeSessionId = event.session_id;
+				}
+				this.currentTap?.push(event);
+				if (event.type === "result") this.onTurnComplete();
+			}
+		} catch (err) {
+			this.currentTap?.fail(err);
+		} finally {
+			await this.terminate();
+		}
+	}
+
+	private onTurnComplete(): void {
+		this.currentTap?.end();
+		this.currentTap = null;
+		this.state = "idle";
+		this.resetIdleTimer();
+		this.idleWaiters.shift()?.();
+	}
+
+	private waitForIdle(timeoutMs = 60_000): Promise<void> {
+		return new Promise<void>((resolve, reject) => {
+			if (this.state === "idle") return resolve();
+			if (this.state === "terminated") return reject(new Error("terminated while waiting"));
+			const timer = setTimeout(() => {
+				const idx = this.idleWaiters.indexOf(onIdle);
+				if (idx >= 0) this.idleWaiters.splice(idx, 1);
+				reject(new Error("timeout waiting for idle"));
+			}, timeoutMs);
+			const onIdle = () => {
+				clearTimeout(timer);
+				resolve();
+			};
+			this.idleWaiters.push(onIdle);
+		});
+	}
+
+	private resetIdleTimer(): void {
+		this.clearIdleTimer();
+		if (this.idleTimeoutMs > 0) {
+			this.idleTimer = setTimeout(() => void this.terminate(), this.idleTimeoutMs);
+			this.idleTimer.unref?.();
+		}
+	}
+
+	private clearIdleTimer(): void {
+		if (this.idleTimer) {
+			clearTimeout(this.idleTimer);
+			this.idleTimer = null;
+		}
+	}
+}
+
+/**
+ * The SDK approval callback: host `toolPolicy` first (full native
+ * PermissionResult power), then the engine's interactive broker. The SDK
+ * passes a REAL `toolUseID` (>=0.2.138), so brokered requests correlate to
+ * their tool parts exactly.
+ */
+export function createCanUseTool(deps: {
+	sessionId: string;
+	policy?: ClaudeToolPolicy;
+	getBroker: () => PermissionRequestHandler | undefined;
+}): CanUseTool {
+	return async (toolName, input, { signal, toolUseID, agentID }) => {
+		const verdict = await deps.policy?.(toolName, input, {
+			sessionId: deps.sessionId,
+			toolUseId: toolUseID,
+			agentId: agentID,
+		});
+		if (verdict) return verdict;
+		const handler = deps.getBroker();
+		if (!handler) return { behavior: "allow", updatedInput: input };
+		const decision = await handler(
+			{
+				toolCallId: toolUseID,
+				toolName,
+				rawInput: input,
+				...claudeToolMeta(toolName, input),
+			},
+			{ signal },
+		);
+		return decision.decision === "allow"
+			? { behavior: "allow", updatedInput: input }
+			: {
+					behavior: "deny",
+					message: (decision.decision === "deny" && decision.reason) || "Denied by user",
+					interrupt: decision.decision === "cancel",
+				};
+	};
+}

package/src/core/agents/claude-code/options.ts

@@ -0,0 +1,161 @@
+import type {
+	Options as CCOptions,
+	McpSdkServerConfigWithInstance,
+} from "@anthropic-ai/claude-agent-sdk";
+import type { McpServerConfig, PermissionMode, ThinkingLevel } from "../../../protocol/index.ts";
+
+/**
+ * In-process MCP servers (the SDK's `createSdkMcpServer` output). Operator
+ * embed-tier only — instances can't travel a wire, so these never appear in
+ * RunConfig; they merge into the SDK's `mcpServers` beside the wire-configured
+ * ones and win name conflicts (the host owns its own tools).
+ */
+export type SdkMcpServers = Record<string, McpSdkServerConfigWithInstance>;
+
+/**
+ * Operator SDK-option overrides (embed-tier escape hatch for surface the
+ * engine does not model: disallowedTools, forwardSubagentText, extraArgs, ...).
+ * The Omit list is the engine's own wiring — fields whose silent clobber would
+ * desync session diffing (cwd/env/permissionMode/resume), break the adapter
+ * (includePartialMessages), or bypass engine merges (mcpServers, hooks,
+ * canUseTool) — so "cannot be overridden" is compiler-enforced.
+ */
+export type ClaudeSdkOptionOverrides = Partial<
+	Omit<
+		CCOptions,
+		| "canUseTool"
+		| "hooks"
+		| "mcpServers"
+		| "resume"
+		| "resumeSessionAt"
+		| "cwd"
+		| "env"
+		| "permissionMode"
+		| "includePartialMessages"
+		| "pathToClaudeCodeExecutable"
+	>
+>;
+
+/** Internal config for one live Claude session (a value the session manager keys/diffs on). */
+export interface ClaudeSessionConfig {
+	cwd: string;
+	additionalDirectories?: string[];
+	model?: string;
+	thinkingLevel?: ThinkingLevel;
+	permissionMode?: PermissionMode;
+	maxTurns?: number;
+	systemPromptAppend?: string;
+	resumeSessionId?: string;
+	resumeSessionAt?: string;
+	mcpServers?: Record<string, McpServerConfig>;
+	env?: Record<string, string>;
+	apiKey?: string;
+	idleTimeoutMs?: number;
+	/** Disable all built-in tools (used by text-only smoke runs). */
+	disableTools?: boolean;
+	/**
+	 * Explicit `claude` binary (from the provisioner / operator override).
+	 * Unset lets the SDK resolve its sibling platform package — which fails
+	 * inside compiled binaries, where this must be provided.
+	 */
+	cliPath?: string;
+}
+
+/**
+ * Map our permission posture onto the Claude SDK's. `bypassPermissions`
+ * auto-approves every tool and is dangerous outside a sandbox, so it must be
+ * requested explicitly — an unset/unknown mode falls back to the safe `default`.
+ */
+function toSdkPermissionMode(mode: PermissionMode | undefined): CCOptions["permissionMode"] {
+	switch (mode) {
+		case "bypassPermissions":
+			return "bypassPermissions";
+		case "plan":
+			return "plan";
+		case "acceptEdits":
+			return "acceptEdits";
+		case "dontAsk":
+			// Native SDK mode: never prompt, deny unapproved. Unlike
+			// bypassPermissions it needs no dangerous flag (and the CLI keeps
+			// extended thinking enabled, which bypass turns off).
+			return "dontAsk";
+		default:
+			return "default";
+	}
+}
+
+/**
+ * Build the env handed to the Claude subprocess. The SDK REPLACES the child env
+ * entirely when `env` is set, so we must spread `process.env` to preserve PATH/
+ * HOME (and thus keychain/subscription auth). We only inject ANTHROPIC_API_KEY
+ * when an explicit key is supplied — otherwise the CLI's own auth is used.
+ */
+function buildEnv(config: ClaudeSessionConfig): Record<string, string | undefined> {
+	return {
+		...process.env,
+		...(config.apiKey ? { ANTHROPIC_API_KEY: config.apiKey } : {}),
+		...config.env,
+	};
+}
+
+export function buildClaudeOptions(
+	config: ClaudeSessionConfig,
+	sdkMcpServers?: SdkMcpServers,
+	overrides?: ClaudeSdkOptionOverrides,
+): CCOptions {
+	const mode = toSdkPermissionMode(config.permissionMode);
+
+	const options: CCOptions = {
+		cwd: config.cwd,
+		maxTurns: config.maxTurns ?? 100,
+		permissionMode: mode,
+		// Streaming input mode + partial messages give us token-level deltas.
+		includePartialMessages: true,
+		systemPrompt: config.systemPromptAppend
+			? { type: "preset", preset: "claude_code", append: config.systemPromptAppend }
+			: { type: "preset", preset: "claude_code" },
+		env: buildEnv(config),
+	};
+
+	if (config.cliPath) options.pathToClaudeCodeExecutable = config.cliPath;
+	if (config.model) options.model = config.model;
+	if (config.additionalDirectories?.length)
+		options.additionalDirectories = config.additionalDirectories;
+	if (mode === "bypassPermissions") options.allowDangerouslySkipPermissions = true;
+	if (config.thinkingLevel !== undefined) {
+		// Modern SDK vocabulary (maxThinkingTokens is deprecated): adaptive
+		// thinking with an effort level; `off` disables extended thinking.
+		if (config.thinkingLevel === "off") {
+			options.thinking = { type: "disabled" };
+		} else {
+			options.thinking = { type: "adaptive" };
+			options.effort = config.thinkingLevel;
+		}
+	}
+	if (config.resumeSessionId) {
+		options.resume = config.resumeSessionId;
+		// SDK contract: resumeSessionAt is only meaningful WITH resume — never
+		// pass it alone (the CLI would get a bare --resume-session-at).
+		if (config.resumeSessionAt) options.resumeSessionAt = config.resumeSessionAt;
+	}
+	if (config.disableTools) {
+		// Text-only. `tools: []` drops built-in tools, but ambient tools (LSP, MCP
+		// servers) are injected by the user's filesystem settings, which that alone
+		// doesn't suppress — so also run in SDK isolation (`settingSources: []`) and
+		// honor only explicitly-passed MCP servers (none).
+		options.tools = [];
+		options.settingSources = [];
+		options.strictMcpConfig = true;
+	} else if (config.mcpServers || sdkMcpServers) {
+		// Our McpServerConfig is structurally assignable to the SDK's stdio/http/sse
+		// shapes; in-process servers merge beside them (operator wins conflicts).
+		options.mcpServers = { ...config.mcpServers, ...sdkMcpServers };
+	}
+
+	// Operator overrides land last; the engine wires hooks/canUseTool after
+	// this function returns, so those can never be clobbered (and the
+	// ClaudeSdkOptionOverrides type excludes them anyway).
+	if (overrides) Object.assign(options, overrides);
+
+	return options;
+}

package/src/core/agents/claude-code/session-manager.ts

@@ -0,0 +1,159 @@
+import type { McpSetServersResult } from "@anthropic-ai/claude-agent-sdk";
+import type { McpServerConfig } from "../../../protocol/index.ts";
+import { configFingerprint } from "../config-fingerprint.ts";
+import { ClaudeGeneratorSession } from "./generator-session.ts";
+import type { ClaudeSessionExtras } from "./generator-session.ts";
+import type { ClaudeSessionConfig } from "./options.ts";
+
+/** Directory-set identity: order and duplicates don't change the sandbox surface. */
+function directoriesFingerprint(dirs: string[] | undefined): string {
+	return configFingerprint([...new Set(dirs ?? [])].sort());
+}
+
+/** Whether immutable Claude subprocess config changed and requires a restart. */
+export function claudeSessionNeedsRestart(
+	prev: ClaudeSessionConfig,
+	next: ClaudeSessionConfig,
+): boolean {
+	return (
+		prev.cwd !== next.cwd ||
+		(prev.cliPath ?? "") !== (next.cliPath ?? "") ||
+		(prev.permissionMode ?? "") !== (next.permissionMode ?? "") ||
+		// thinking/effort are fixed at spawn in the modern SDK vocabulary (the
+		// old setMaxThinkingTokens hot-swap is deprecated and effort-blind), so
+		// a level change restarts — context survives via claudeRestartConfig.
+		(prev.thinkingLevel ?? "") !== (next.thinkingLevel ?? "") ||
+		(prev.systemPromptAppend ?? "") !== (next.systemPromptAppend ?? "") ||
+		// A rewind (resumeSessionAt) is applied by the SDK only at spawn, so a
+		// warm session cannot honor it — any change forces a restart. The
+		// symmetric diff deliberately also restarts on set->unset: it keeps the
+		// gate correct even if the stored config lags a reused turn, at the
+		// cost of one extra (context-preserving) respawn after a revert.
+		(prev.resumeSessionAt ?? "") !== (next.resumeSessionAt ?? "") ||
+		directoriesFingerprint(prev.additionalDirectories) !==
+			directoriesFingerprint(next.additionalDirectories) ||
+		(prev.apiKey ?? "") !== (next.apiKey ?? "") ||
+		(prev.maxTurns ?? 100) !== (next.maxTurns ?? 100) ||
+		(prev.idleTimeoutMs ?? 5 * 60_000) !== (next.idleTimeoutMs ?? 5 * 60_000) ||
+		Boolean(prev.disableTools) !== Boolean(next.disableTools) ||
+		configFingerprint(prev.env) !== configFingerprint(next.env)
+		// mcpServers deliberately absent: MCP changes hot-swap on the live
+		// session (`setMcpServers`) instead of restarting the subprocess.
+	);
+}
+
+/** Preserve context within the same cwd/credential boundary; explicit resume always wins. */
+export function claudeRestartConfig(
+	previous: ClaudeSessionConfig,
+	next: ClaudeSessionConfig,
+	nativeSessionId: string | null,
+): ClaudeSessionConfig {
+	if (next.resumeSessionId || !nativeSessionId) return next;
+	const sameResumeBoundary =
+		previous.cwd === next.cwd &&
+		(previous.apiKey ?? "") === (next.apiKey ?? "") &&
+		configFingerprint(previous.env) === configFingerprint(next.env);
+	return sameResumeBoundary ? { ...next, resumeSessionId: nativeSessionId } : next;
+}
+
+/**
+ * One live `ClaudeGeneratorSession` per logical session id. Decides, per turn,
+ * whether the existing session can be reused (hot-swapping model/mcp) or must
+ * be torn down and recreated (cwd / permission / thinking / system-prompt
+ * changes alter the subprocess in ways the live query can't). `resumeSessionId`
+ * is read only at spawn — it never forces a restart on a warm session.
+ */
+export class ClaudeSessionManager {
+	private readonly sessions = new Map<string, ClaudeGeneratorSession>();
+
+	async getOrCreate(
+		sessionId: string,
+		config: ClaudeSessionConfig,
+		extras?: ClaudeSessionExtras,
+	): Promise<ClaudeGeneratorSession> {
+		let startConfig = config;
+		const existing = this.sessions.get(sessionId);
+		if (existing && existing.currentState !== "terminated") {
+			if (this.needsRestart(existing.currentConfig, config)) {
+				startConfig = claudeRestartConfig(
+					existing.currentConfig,
+					config,
+					existing.currentSessionId,
+				);
+				await existing.terminate();
+				this.sessions.delete(sessionId);
+			} else {
+				await this.hotSwapIfNeeded(existing, config);
+				return existing;
+			}
+		}
+
+		const session = new ClaudeGeneratorSession(
+			sessionId,
+			startConfig,
+			() => {
+				if (this.sessions.get(sessionId) === session) this.sessions.delete(sessionId);
+			},
+			extras,
+		);
+		this.sessions.set(sessionId, session);
+		try {
+			await session.start();
+		} catch (err) {
+			// Don't leave a half-started session in the map — it could never serve a turn.
+			this.sessions.delete(sessionId);
+			throw err;
+		}
+		return session;
+	}
+
+	get(sessionId: string): ClaudeGeneratorSession | undefined {
+		return this.sessions.get(sessionId);
+	}
+
+	async terminate(sessionId: string): Promise<void> {
+		const session = this.sessions.get(sessionId);
+		if (!session) return;
+		await session.terminate();
+		if (this.sessions.get(sessionId) === session) this.sessions.delete(sessionId);
+	}
+
+	async terminateAll(): Promise<void> {
+		await Promise.all([...this.sessions.values()].map((s) => s.terminate()));
+		this.sessions.clear();
+	}
+
+	private needsRestart(prev: ClaudeSessionConfig, next: ClaudeSessionConfig): boolean {
+		return claudeSessionNeedsRestart(prev, next);
+	}
+
+	private async hotSwapIfNeeded(
+		session: ClaudeGeneratorSession,
+		next: ClaudeSessionConfig,
+	): Promise<void> {
+		if (next.model !== session.currentConfig.model) {
+			await session.setModel(next.model);
+		}
+		if (
+			configFingerprint(next.mcpServers ?? {}) !==
+			configFingerprint(session.currentConfig.mcpServers ?? {})
+		) {
+			await session.setMcpServers(next.mcpServers ?? {});
+		}
+	}
+
+	/**
+	 * Explicit live MCP swap (e.g. mid-conversation app registration). NOTE:
+	 * this syncs the session's config, so the NEXT turn's wire config (if it
+	 * still carries the old server set) will swap back — explicit swappers
+	 * must keep their per-turn `mcpServers` in step.
+	 */
+	async setMcpServers(
+		sessionId: string,
+		servers: Record<string, McpServerConfig>,
+	): Promise<McpSetServersResult | undefined> {
+		const session = this.sessions.get(sessionId);
+		if (!session || session.currentState === "terminated") return undefined;
+		return session.setMcpServers(servers);
+	}
+}