@zvada/agent-server 0.3.9 → 0.3.10

package/src/core/agents/session-agent.ts

@@ -0,0 +1,91 @@
+import type { AgentInput } from "../../protocol/index.ts";
+import { SessionResumeError, TurnActiveError } from "../utils/errors.ts";
+import { type AgentExecuteOptions, BaseAgent, type RawAgentEvent } from "./base.ts";
+import { configFingerprint } from "./config-fingerprint.ts";
+
+/**
+ * Shared execution lifecycle for built-in harnesses. One turn owns a logical
+ * session from preparation through native cleanup. BaseAgent remains available
+ * to custom harnesses with their own execution/concurrency contract.
+ */
+export abstract class SessionAgent extends BaseAgent {
+	private terminated = false;
+	/** Cancel/release can return before execution drains; only finally relinquishes ownership. */
+	private readonly activeSessions = new Set<string>();
+	/** Conversation identity outlives subprocess eviction and failed startup. */
+	private readonly conversations = new Map<string, { id: string | undefined; boundary: string }>();
+
+	override async *execute(
+		input: AgentInput,
+		options: AgentExecuteOptions,
+	): AsyncIterableIterator<RawAgentEvent> {
+		const { sessionId } = options;
+		if (this.terminated) throw new Error("Agent has been terminated");
+		if (this.activeSessions.has(sessionId)) throw new TurnActiveError(sessionId);
+		this.activeSessions.add(sessionId);
+		const controller = this.trackTurn(sessionId, options.signal);
+		try {
+			// The adapter still produces its native cancellation result for an
+			// already-aborted turn. It must not select a conversation or do setup.
+			const prepared = controller.signal.aborted ? options : this.prepareSessionOptions(options);
+			yield* this.executeTurn(input, prepared, controller);
+		} finally {
+			this.endTurn(sessionId, controller);
+			this.activeSessions.delete(sessionId);
+		}
+	}
+
+	/** Native protocol execution; options are prepared and the session is exclusively owned. */
+	protected abstract executeTurn(
+		input: AgentInput,
+		options: AgentExecuteOptions,
+		controller: AbortController,
+	): AsyncIterableIterator<RawAgentEvent>;
+
+	private prepareSessionOptions(options: AgentExecuteOptions): AgentExecuteOptions {
+		if (options.resumeSessionId === "") {
+			throw new Error("Invalid request: resumeSessionId must not be empty");
+		}
+		const boundary = configFingerprint({
+			cwd: options.cwd,
+			env: options.env,
+			apiKey: options.apiKey,
+		});
+		const previous = this.conversations.get(options.sessionId);
+		if (!options.resumeSessionId && previous?.id && previous.boundary !== boundary) {
+			throw new SessionResumeError(
+				previous.id,
+				"working directory or credentials changed; explicitly provide resumeSessionId to continue, or use a new sessionId for a new conversation",
+			);
+		}
+		const resumeSessionId = options.resumeSessionId ?? previous?.id;
+		// Remember intent before setup: a failed retry must keep targeting the same history.
+		const selection = { id: resumeSessionId, boundary };
+		this.conversations.set(options.sessionId, selection);
+		return {
+			...options,
+			resumeSessionId,
+			onNativeSession: (id, info) => {
+				if (this.conversations.get(options.sessionId) !== selection) {
+					throw new SessionResumeError(
+						resumeSessionId ?? id,
+						"session was released while this turn was preparing",
+					);
+				}
+				selection.id = id;
+				options.onNativeSession?.(id, info);
+			},
+		};
+	}
+
+	override async release(sessionId: string): Promise<void> {
+		this.conversations.delete(sessionId);
+		await super.release(sessionId);
+	}
+
+	override async terminateAll(): Promise<void> {
+		this.terminated = true;
+		this.conversations.clear();
+		await super.terminateAll();
+	}
+}

package/src/core/agents/session-store.ts

@@ -51,6 +51,12 @@ export class SessionStore<S extends StoredSession> {
 		return this.sessions.values();
 	}
 
+	/** Native clients include both retained sessions and unfinished initialization. */
+	*clients(): IterableIterator<S["client"]> {
+		for (const session of this.sessions.values()) yield session.client;
+		for (const clients of this.pending.values()) yield* clients;
+	}
+
 	/** Self-heal: drop the mapping when this exact client closed underneath us. */
 	dropIfCurrent(sessionId: string, client: S["client"]): void {
 		const current = this.sessions.get(sessionId);

package/src/core/diagnostics.ts

@@ -11,19 +11,12 @@
  * the `(string & {})` arm keeps the union open without losing autocomplete):
  *  - `interruptTimeout` — a cancel's SDK interrupt round-trip timed out
  *    (the turn was reported `confirmed: false`; the agent may still run).
- *  - `resumeFallback` — a requested resume failed and the turn re-ran on a
- *    fresh session (also visible as `session.created.resumed: false`).
  *  - `sinkError` — an EventSink emit threw; the event was dropped for that
  *    sink and the turn continued.
  *  - `proxyUpstreamAuth` — the BYOK proxy's upstream rejected the real key
  *    (401/403): the stored key is invalid/expired, not the placeholder.
  */
-export type DiagnosticKind =
-	| "interruptTimeout"
-	| "resumeFallback"
-	| "sinkError"
-	| "proxyUpstreamAuth"
-	| (string & {});
+export type DiagnosticKind = "interruptTimeout" | "sinkError" | "proxyUpstreamAuth" | (string & {});
 
 export interface EngineDiagnostic {
 	type: DiagnosticKind;

package/src/core/index.ts

@@ -111,10 +111,12 @@ export {
 export {
 	AgentServerError,
 	AgentExecutionError,
+	SessionResumeError,
 	CliNotFoundError,
 	CliProvisionError,
 	HarnessNotFoundError,
 	TurnConflictError,
+	TurnActiveError,
 } from "./utils/errors.ts";
 
 // Re-export the wire contract for convenience.

package/src/core/presets.ts

@@ -40,7 +40,7 @@ export interface CreateRegistryOptions {
 	codexAppServer?: Omit<CodexAppServerAgentOptions, "resolveCliPath">;
 	/**
 	 * Operational diagnostics port (see `EngineDiagnostic`): interrupt
-	 * timeouts, resume fallbacks, sink failures — signals the engine must not
+	 * timeouts and sink failures — signals the engine must not
 	 * fail a turn over, surfaced for the host to log/metric. Applied to the
 	 * runtime and every harness that emits them; a harness-level
 	 * `claudeCode.onDiagnostic` overrides for that harness.

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

@@ -1,5 +1,5 @@
 import {
-	type ErrorCategory,
+	type ErrorInfo,
 	classifyError,
 	isCancellation,
 	isRecoverable,
@@ -39,7 +39,7 @@ export interface RunSummary {
 	stopReason: StopReason;
 	finishReason?: string;
 	cost?: number;
-	error?: { category: ErrorCategory; message: string };
+	error?: ErrorInfo;
 	cancelled: boolean;
 }
 
@@ -406,8 +406,7 @@ export class AgentRuntime {
 			disableTools: config.disableTools,
 			signal: opts.signal,
 			onNativeSession: (id, info) => {
-				// Agents report exactly once per turn (the claude fallback defers its
-				// report until the surviving session is known); guard against a
+				// Agents report once the native conversation is confirmed; guard against a
 				// misbehaving harness re-reporting after emission. Agents always pass
 				// their honest `resumed` judgment — the runtime surfaces it only when
 				// this turn actually REQUESTED a resume.
@@ -419,7 +418,7 @@ export class AgentRuntime {
 		};
 
 		let cancelled = false;
-		let errored: { category: ErrorCategory; message: string } | undefined;
+		let errored: ErrorInfo | undefined;
 
 		try {
 			for await (const raw of agent.execute(input, options)) {
@@ -470,9 +469,7 @@ export class AgentRuntime {
 			: errored
 				? "error"
 				: (result.stopReason ?? "end_turn");
-		const terminalResult =
-			errored && !result.error ? { ...result, error: errored.message } : result;
-		for (const le of processor.finish(terminalResult, stopReason)) await emit(le);
+		for (const le of processor.finish(result, stopReason, errored)) await emit(le);
 
 		return {
 			sessionId,
@@ -510,8 +507,9 @@ export class AgentRuntime {
 
 	/**
 	 * 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.
+	 * Retains conversations and admission receipts. Claude and Codex app-server
+	 * replace retained subprocesses before the next prompt and strictly resume
+	 * saved history. Their MCP reset/reload controls can retain dead connections.
 	 */
 	invalidateMcpConnections(): void {
 		for (const harness of this.registry.list()) {

package/src/core/runtime/event-processor.ts

@@ -7,6 +7,7 @@ import {
 import type {
 	AgentInput,
 	Delta,
+	ErrorInfo,
 	LifecycleEvent,
 	Part,
 	StopReason,
@@ -122,7 +123,14 @@ export class EventProcessor {
 		}
 	}
 
-	*finish(result: TransformResult, stopReason: StopReason): Generator<LifecycleEvent> {
+	/** Preserve the runtime's classified error; standalone callers can use the adapter text. */
+	*finish(
+		result: TransformResult,
+		stopReason: StopReason,
+		error: ErrorInfo | undefined = result.error && !result.cancelled && stopReason !== "cancelled"
+			? { category: classifyError(result.error), message: result.error }
+			: undefined,
+	): Generator<LifecycleEvent> {
 		yield* this.closeMessage();
 		yield {
 			type: "turn.ended",
@@ -138,10 +146,7 @@ export class EventProcessor {
 					...(result.reportedModels && { reportedModels: result.reportedModels }),
 				},
 			}),
-			error:
-				result.error && !result.cancelled
-					? { category: classifyError(result.error), message: result.error }
-					: undefined,
+			error,
 			timestamp: Date.now(),
 		};
 	}

package/src/core/utils/errors.ts

@@ -47,6 +47,14 @@ export class TurnConflictError extends AgentServerError {
 	}
 }
 
+/** A built-in harness already has a turn preparing, running, or draining on this session. */
+export class TurnActiveError extends AgentServerError {
+	constructor(readonly sessionId: string) {
+		super(`Session ${sessionId} already has an active turn; wait for it to end`, "TURN_ACTIVE");
+		this.name = "TurnActiveError";
+	}
+}
+
 export class AgentExecutionError extends AgentServerError {
 	constructor(message: string, options?: { cause?: unknown }) {
 		super(message, "AGENT_EXECUTION_ERROR");
@@ -55,6 +63,19 @@ export class AgentExecutionError extends AgentServerError {
 	}
 }
 
+/** The requested conversation could not be loaded. Never replay its prompt on a fresh one. */
+export class SessionResumeError extends AgentServerError {
+	constructor(
+		readonly nativeSessionId: string,
+		reason: string,
+		options?: { cause?: unknown },
+	) {
+		super(`Cannot resume conversation ${nativeSessionId}: ${reason}`, "SESSION_RESUME_FAILED");
+		this.name = "SessionResumeError";
+		if (options?.cause !== undefined) this.cause = options.cause;
+	}
+}
+
 export class CliNotFoundError extends AgentServerError {
 	constructor(name: string, hint?: string) {
 		super(

package/src/protocol/config.ts

@@ -62,7 +62,7 @@ export const RunConfigSchema = z.object({
 	 * Native session/thread id to resume (from a prior `session.created`). When
 	 * set, the harness continues that conversation instead of starting fresh.
 	 */
-	resumeSessionId: z.string().optional(),
+	resumeSessionId: z.string().min(1).optional(),
 	/**
 	 * Resume from a specific historical message within the resumed session
 	 * (branch/retry flows). Claude-only today; other harnesses ignore it.

package/src/protocol/errors.ts

@@ -20,6 +20,7 @@ export const ERROR_CATEGORIES = [
 	"abort",
 	"invalid_request",
 	"process_exit",
+	"resume_failed",
 	"internal",
 ] as const;
 export type ErrorCategory = (typeof ERROR_CATEGORIES)[number] | (string & {});
@@ -38,6 +39,7 @@ export type ErrorInfo = z.infer<typeof ErrorInfoSchema>;
  * classifier; lives in /protocol because categories are vocabulary.
  */
 const RULES: ReadonlyArray<[ErrorCategory, readonly string[]]> = [
+	["resume_failed", ["no conversation found with session id", "no rollout found for thread id"]],
 	["abort", ["aborted", "aborterror", "cancelled", "canceled", "interrupted", "sigint"]],
 	[
 		"auth",
@@ -76,6 +78,15 @@ const RULES: ReadonlyArray<[ErrorCategory, readonly string[]]> = [
 ];
 
 export function classifyError(error: unknown): ErrorCategory {
+	if (error instanceof Error && "code" in error && error.code === "TURN_ACTIVE")
+		return "invalid_request";
+	if (error instanceof Error && "code" in error && error.code === "SESSION_RESUME_FAILED") {
+		if (error.cause !== undefined) {
+			const category = classifyError(error.cause);
+			if (category !== "internal") return category;
+		}
+		return "resume_failed";
+	}
 	const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
 	for (const [category, needles] of RULES) {
 		if (needles.some((n) => message.includes(n))) return category;

package/src/protocol/lifecycle.ts

@@ -94,7 +94,8 @@ export const SessionCreatedEventSchema = z.object({
 	 * actually continued that conversation. `false` = it fell back to a fresh
 	 * session (context lost) — surface this, never swallow it. Compare with
 	 * this flag, not ids: some harnesses mint a NEW nativeSessionId on a
-	 * successful resume (Claude).
+	 * successful resume (Claude). Built-in harnesses fail instead of starting
+	 * fresh; `false` remains readable for older engines and custom harnesses.
 	 */
 	resumed: z.boolean().optional(),
 	timestamp: EpochMsSchema,

package/src/server/acp/binding.ts

@@ -48,6 +48,16 @@ export async function createAcpAgentApp(options: AcpBindingOptions): Promise<Age
 	const acp = await import("@agentclientprotocol/sdk");
 	const { runtime, harness } = options;
 	const sessions = new Map<string, BoundSession>();
+	const checkMcpSupport = (servers: readonly unknown[] | undefined): void => {
+		if (harness === "codex-app-server" && servers?.length) {
+			// ACP supplies MCP entries, but has no session-specific CODEX_HOME
+			// field. Never write those credentials into the operator's user home.
+			throw acp.RequestError.invalidParams(
+				undefined,
+				"Codex MCP is not supported by this ACP binding; use the engine or JSON-RPC API with a session-specific env.CODEX_HOME",
+			);
+		}
+	};
 
 	const requireSession = (sessionId: string): BoundSession => {
 		const session = sessions.get(sessionId);
@@ -67,6 +77,7 @@ export async function createAcpAgentApp(options: AcpBindingOptions): Promise<Age
 			authMethods: [],
 		}))
 		.onRequest("session/new", (ctx) => {
+			checkMcpSupport(ctx.params.mcpServers);
 			const sessionId = generateUUIDv7();
 			sessions.set(sessionId, {
 				cwd: ctx.params.cwd,
@@ -76,6 +87,7 @@ export async function createAcpAgentApp(options: AcpBindingOptions): Promise<Age
 		})
 		.onRequest("session/resume", (ctx) => {
 			const session = requireSession(ctx.params.sessionId);
+			checkMcpSupport(ctx.params.mcpServers);
 			session.cwd = ctx.params.cwd;
 			if (ctx.params.mcpServers) session.mcpServers = fromAcpMcpServers(ctx.params.mcpServers);
 			return {};