@zvada/agent-server 0.3.8 → 0.3.9

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.9
+
+- Recover transient Claude MCP setup failures by reattaching with the current
+  credentials, preserving the process and conversation. Failed updates remain
+  dirty until recovery is verified; an identical SDK retry cannot silently
+  admit a turn with unavailable tools. Cancelling during preparation never
+  submits the prompt.
+- Add the embed-tier `runtime.invalidateMcpConnections()` lifecycle signal for
+  resumed hosts, including turns whose remote MCP configuration is unchanged.
+
 ## 0.3.8
 
 - Report each Claude turn's cost as the increase in the SDK's cumulative query cost. Preserve the native total in raw diagnostics, reset the baseline with a fresh query or conversation reset, and keep unknown cost distinct from reported zero.

package/docs/consuming.md

@@ -235,6 +235,23 @@ and unknown event/part types are forward-compat rather than violations. Pass
 
 ## Own your session resources
 
+### Resume a suspended host
+
+After thawing a VM, call `runtime.invalidateMcpConnections()` before admitting
+new turns. This embed-tier lifecycle signal retains conversation state and
+turn-admission receipts. The Claude harness reattaches remote MCP servers
+before the next prompt, using that turn's current `mcpServers` credentials,
+even when the configuration has not changed. It leaves in-process host tools
+attached. Other harnesses without this lifecycle hook are unaffected.
+
+Claude MCP updates also repair a transient socket setup failure once. Recovery
+removes and re-adds the affected connection: an identical SDK update can cache
+a failed client, and the SDK's reconnect-by-name command can restore startup
+credentials. Persistent connection failures and invalid credentials fail the
+turn before prompt submission. Tool calls and model turns are never replayed.
+
+### Release a session
+
 Register `onSessionEnd` (claude options) to release per-session resources —
 BYOK proxy keys, recorders — instead of re-deriving termination from side
 effects. Reasons: `idle` (idle-timeout eviction), `replaced` (config change

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zvada/agent-server",
-	"version": "0.3.8",
+	"version": "0.3.9",
 	"description": "Harness-agnostic agent execution engine: run Claude Code, Codex (SDK/CLI + app-server), and any ACP agent behind one interface with a normalized event stream, multi-turn sessions, and resume. Root export is the wire contract; /core, /server, /client are the seats.",
 	"license": "MIT",
 	"type": "module",

package/src/core/agents/base.ts

@@ -105,6 +105,8 @@ export interface Agent {
 	cancel(sessionId: string): Promise<CancelResult>;
 	/** Release all harness-owned state for one idle logical session. */
 	release?(sessionId: string): Promise<void>;
+	/** Mark retained MCP connections stale after host suspension; repair before the next turn. */
+	invalidateMcpConnections?(): void;
 	/** Tear down every live session (process shutdown). */
 	terminateAll(): Promise<void>;
 }

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

@@ -180,6 +180,8 @@ export class ClaudeCodeAgent extends BaseAgent {
 					},
 					this.sessionExtras(),
 				);
+				// A cancel during connection repair must never submit the prompt.
+				if (controller.signal.aborted) break;
 
 				let reported = false;
 				const report = (id: string) => {
@@ -242,6 +244,9 @@ export class ClaudeCodeAgent extends BaseAgent {
 			// result shape (error_during_execution, null stop_reason). Only the
 			// agent knows whether an interrupt was actually requested.
 			if (controller.signal.aborted) yield { type: "turn_interrupted" };
+		} catch (error) {
+			if (!controller.signal.aborted) throw error;
+			yield { type: "turn_interrupted" };
 		} finally {
 			this.endTurn(options.sessionId, controller);
 		}
@@ -259,6 +264,11 @@ export class ClaudeCodeAgent extends BaseAgent {
 		return this.manager.setMcpServers(sessionId, servers);
 	}
 
+	/** Reattach remote MCP servers before the next turn after a host resumes. */
+	invalidateMcpConnections(): void {
+		this.manager.invalidateMcpConnections();
+	}
+
 	override async cancel(sessionId: string): Promise<CancelResult> {
 		// Abort FIRST: the controller ends the engine's execute loop, so this
 		// turn classifies as cancelled even when the generator drains to a

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

@@ -75,6 +75,31 @@ export interface ClaudeSessionExtras {
 type SessionState = "starting" | "idle" | "busy" | "terminated";
 type ClaudeContent = SDKUserMessage["message"]["content"];
 
+function remoteMcpServer(server: McpServerConfig): boolean {
+	return server.type === "http" || server.type === "sse";
+}
+
+/** Connection setup only: never retry a model turn or a tool invocation. */
+function transientMcpFailure(errors: Record<string, string>): boolean {
+	return (
+		Object.keys(errors).length > 0 &&
+		Object.values(errors).every((error) =>
+			/socket connection was closed unexpectedly|\bECONNRESET\b|\bEPIPE\b|\bETIMEDOUT\b/i.test(
+				error,
+			),
+		)
+	);
+}
+
+function assertMcpConnected(errors: Record<string, string>): void {
+	const failed = Object.entries(errors);
+	if (failed.length) {
+		throw new Error(
+			`mcp servers failed to connect: ${failed.map(([name, error]) => `${name} (${error})`).join(", ")}`,
+		);
+	}
+}
+
 /** Per-turn handle: iterate `events` until the turn's `result` arrives (or the turn errors). */
 export interface ClaudeEventTap {
 	readonly events: AsyncIterable<SDKMessage>;
@@ -99,6 +124,11 @@ export class ClaudeGeneratorSession {
 	currentTurnId?: string;
 	/** Resolved once at spawn; re-merged into every hot-swap. */
 	private sdkServers?: SdkMcpServers;
+	private mcpUpdate = Promise.resolve();
+	private mcpUpdateFailed = false;
+	private readonly failedMcpServers = new Set<string>();
+	private mcpConnectionGeneration = 0;
+	private connectedMcpGeneration = 0;
 	private nativeSessionId: string | null = null;
 	/** SDK cost is cumulative within this query; token usage is already per turn. */
 	private cumulativeCost: number | undefined = 0;
@@ -136,6 +166,20 @@ export class ClaudeGeneratorSession {
 	get currentConfig(): Readonly<ClaudeSessionConfig> {
 		return this.config;
 	}
+	get mcpConnectionsStale(): boolean {
+		return (
+			this.mcpUpdateFailed ||
+			(this.mcpConnectionGeneration !== this.connectedMcpGeneration &&
+				Object.values(this.config.mcpServers ?? {}).some(remoteMcpServer))
+		);
+	}
+
+	/** A thawed VM can retain clients whose sockets still appear connected. */
+	invalidateMcpConnections(): void {
+		// Also retain a signal that lands while the first remote server is
+		// being attached and currentConfig still has no remote servers.
+		this.mcpConnectionGeneration++;
+	}
 
 	/** Hot-swap the model without losing context (Claude `setModel`). */
 	async setModel(model: string | undefined): Promise<void> {
@@ -152,19 +196,95 @@ export class ClaudeGeneratorSession {
 	 */
 	async setMcpServers(
 		servers: Record<string, McpServerConfig>,
+	): Promise<McpSetServersResult | undefined> {
+		// Explicit swaps and turn preparation share the same control channel.
+		const update = this.mcpUpdate.then(() => this.updateMcpServers(servers));
+		this.mcpUpdate = update.then(
+			() => {},
+			() => {},
+		);
+		return update;
+	}
+
+	private async updateMcpServers(
+		servers: Record<string, McpServerConfig>,
 	): Promise<McpSetServersResult | undefined> {
 		if (this.config.disableTools || 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(", ")}`,
+		const query = this.query;
+		const reconnect = this.mcpConnectionsStale;
+		const generation = this.mcpConnectionGeneration;
+		const resetNames = Object.keys(servers).filter(
+			(name) =>
+				this.failedMcpServers.has(name) ||
+				(generation !== this.connectedMcpGeneration && remoteMcpServer(servers[name]!)),
+		);
+		const desired = { ...servers, ...this.sdkServers };
+		const added = new Set<string>();
+		const removed = new Set<string>();
+		const applyDesired = async () => {
+			const result = await query.setMcpServers(desired);
+			for (const name of result.added) added.add(name);
+			for (const name of result.removed) removed.add(name);
+			return result;
+		};
+		// A failed SDK update is not transactional: it can cache the new config
+		// with a failed client, then return errors:{} for the identical retry.
+		// Keep that uncertainty until a verified reattachment succeeds.
+		this.mcpUpdateFailed = true;
+		const check = (errors: Record<string, string>) => {
+			for (const name of Object.keys(errors)) this.failedMcpServers.add(name);
+			assertMcpConnected(errors);
+		};
+		const reattach = async (names: string[]) => {
+			const detached = { ...desired };
+			for (const name of names) {
+				if (!this.sdkServers?.[name]) delete detached[name];
+			}
+			check((await query.setMcpServers(detached)).errors ?? {});
+			return applyDesired();
+		};
+		let result = await applyDesired();
+		let retried = false;
+		if (reconnect) {
+			if (!transientMcpFailure(result.errors ?? {})) check(result.errors ?? {});
+			retried = Object.keys(result.errors ?? {}).length > 0;
+			result = await reattach([...new Set([...resetNames, ...Object.keys(result.errors ?? {})])]);
+		}
+		const failed = Object.keys(result.errors ?? {});
+		const retry =
+			!retried &&
+			transientMcpFailure(result.errors ?? {}) &&
+			failed.every(
+				(name) => servers[name] && remoteMcpServer(servers[name]!) && !this.sdkServers?.[name],
+			);
+		if (retry) {
+			// reconnectMcpServer(name) can restore the CLI's STARTUP credentials.
+			// Removing and adding uses this turn's exact configuration instead.
+			result = await reattach(failed);
+		}
+		check(result.errors ?? {});
+		if (reconnect || retry) {
+			const statuses = await query.mcpServerStatus();
+			check(
+				Object.fromEntries(
+					Object.keys(desired).flatMap((name) => {
+						const status = statuses.find((entry) => entry.name === name);
+						return status?.status === "connected"
+							? []
+							: [[name, status?.error ?? `server is ${status?.status ?? "missing"}`]];
+					}),
+				),
 			);
 		}
 		this.config = { ...this.config, mcpServers: servers };
-		return result;
+		this.mcpUpdateFailed = false;
+		this.failedMcpServers.clear();
+		this.connectedMcpGeneration = generation;
+		return {
+			added: [...added],
+			removed: [...removed],
+			errors: result.errors,
+		};
 	}
 
 	async start(): Promise<void> {
@@ -175,7 +295,10 @@ export class ClaudeGeneratorSession {
 			cwd: this.config.cwd,
 		});
 		const options = buildClaudeOptions(
-			this.config,
+			// CLI startup MCP entries can survive the first dynamic removal and
+			// reconnect-by-name can reuse their original credentials. Give every
+			// wire server one owner: register it dynamically before the first turn.
+			{ ...this.config, mcpServers: {} },
 			this.sdkServers,
 			await this.extras?.sdkOptions?.({ sessionId: this.id, cwd: this.config.cwd }),
 		);
@@ -197,6 +320,10 @@ export class ClaudeGeneratorSession {
 			options,
 		});
 		void this.consumeEvents();
+		if (!this.config.disableTools && Object.keys(this.config.mcpServers ?? {}).length) {
+			await this.setMcpServers(this.config.mcpServers!);
+		}
+		if (this.currentState === "terminated") throw new Error("Session terminated during startup");
 		this.state = "idle";
 		this.resetIdleTimer();
 	}

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

@@ -113,7 +113,8 @@ export class ClaudeSessionManager {
 			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);
+			await session.terminate();
+			if (this.sessions.get(sessionId) === session) this.sessions.delete(sessionId);
 			throw err;
 		}
 		// Whether THIS spawn carried a `resumeSessionId`: an explicit caller resume
@@ -137,6 +138,10 @@ export class ClaudeSessionManager {
 		this.sessions.clear();
 	}
 
+	invalidateMcpConnections(): void {
+		for (const session of this.sessions.values()) session.invalidateMcpConnections();
+	}
+
 	private needsRestart(prev: ClaudeSessionConfig, next: ClaudeSessionConfig): boolean {
 		return claudeSessionNeedsRestart(prev, next);
 	}
@@ -151,8 +156,9 @@ export class ClaudeSessionManager {
 		// Text-only sessions must stay tool-free when the MCP configuration changes.
 		if (
 			!next.disableTools &&
-			configFingerprint(next.mcpServers ?? {}) !==
-				configFingerprint(session.currentConfig.mcpServers ?? {})
+			(session.mcpConnectionsStale ||
+				configFingerprint(next.mcpServers ?? {}) !==
+					configFingerprint(session.currentConfig.mcpServers ?? {}))
 		) {
 			await session.setMcpServers(next.mcpServers ?? {});
 		}

package/src/core/runtime/agent-runtime.ts

@@ -508,6 +508,17 @@ export class AgentRuntime {
 		return await this.registry.getAgent(harness).cancel(sessionId);
 	}
 
+	/**
+	 * Call after the host resumes from suspension, before admitting new turns.
+	 * Retains conversations and admission receipts; supported harnesses repair
+	 * remote MCP connections lazily with the next turn's current credentials.
+	 */
+	invalidateMcpConnections(): void {
+		for (const harness of this.registry.list()) {
+			this.registry.getAgent(harness).invalidateMcpConnections?.();
+		}
+	}
+
 	/** Dispose one idle logical session and its harness-native resources. */
 	async closeSession(harness: AgentHarness, sessionId: string): Promise<void> {
 		this.completedTurns.delete(sessionId);