@zvada/agent-server 0.3.9 → 0.3.10

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.3.10
+
+- Support Codex app-server per-turn stdio and Streamable HTTP MCP configuration
+  in an explicitly isolated `CODEX_HOME`. Reuse unchanged connections, apply
+  credential changes before prompt submission, and remove omitted servers.
+  Verify effective settings before reload so repository overrides cannot
+  redirect supplied credentials; fail setup when requested tools are unavailable.
+- Add the interactive CLI's explicit `--codex-home` path and preserve it for
+  continuation. Release the old logical session before `/new` reuses its home.
+  The ACP server binding rejects supplied Codex MCP configuration explicitly;
+  it has no session-specific home resource seam.
+- Snapshot Claude MCP configuration so reusing and mutating a caller's server
+  map cannot hide credential changes or alter a queued configuration update.
+- After host suspension, replace Claude and Codex app-server subprocesses
+  before the next prompt and strictly resume saved conversations. MCP reset
+  and unchanged-config reload can retain dead remote connections. Preserve
+  turn-admission receipts; ordinary warm turns still reuse the process.
+  CLI-owned stdio MCP processes and Claude host MCP instances are recreated.
+- Fail closed when Claude, Codex, or ACP cannot resume saved context. Remove
+  automatic fresh-conversation retries, retain native targets across process
+  eviction and failed setup, and report missing context as `resume_failed`.
+  Starting a fresh conversation now requires an explicit new/closed session.
+- Honor a different explicit Claude resume target on warm sessions; reject
+  mismatched Codex resume responses before accepting the replacement ID.
+- Reject empty resume IDs. Share turn ownership and conversation preparation
+  across all built-in harnesses: overlapping turns on one logical session fail
+  before native setup or changes to saved context. Different sessions remain
+  parallel; custom harnesses retain their existing execution contract.
+- Detach completed turns' cancellation signals so a late abort cannot interrupt
+  the next warm turn. Retain ownership until native cleanup finishes.
+- Prevent Claude from creating an orphan query when release or shutdown occurs
+  during asynchronous startup configuration.
+- Reject direct execution on built-in agents as soon as shutdown begins, before
+  starting native setup or creating another session.
+- Preserve classified errors from the runtime in terminal events and client
+  results, including resume failures and overlapping turns. Cancellation cleanup
+  diagnostics no longer appear as terminal failures.
+- Verify external MCP readiness on initial attachment and configuration changes,
+  including OAuth `needs-auth` states. Preserve early Claude resume errors when
+  startup MCP controls fail, and allow lazily initialized in-process SDK tools.
+
 ## 0.3.9
 
 - Recover transient Claude MCP setup failures by reattaching with the current

package/docs/consuming.md

@@ -187,11 +187,25 @@ data disappears. A known type with a malformed body still fails loudly.
 
 Store `state.nativeSessionId` (from `session.created`) keyed by your logical
 `sessionId`, and pass it back as `config.resumeSessionId` to continue a
-conversation later — across processes and machines. Check
-`session.created.resumed` on resume turns: `false` means the harness fell
-back to a fresh session (context lost) — surface that, never swallow it.
-Compare with the flag, not ids: a successful Claude resume mints a NEW native
-id.
+conversation later — across processes and machines where its native history is
+available. Built-in harnesses fail the turn if the requested conversation is
+missing, unsupported, or resolves to the wrong Codex thread. They never replay
+the prompt on a new conversation. Missing or unsupported history reports
+`error.category: "resume_failed"`; authentication and transport failures keep
+their existing error categories.
+
+Keep the saved ID when a turn fails. To retry after fixing the cause, submit a
+new `turnId` with the same resume target. To deliberately start fresh, use a new
+logical `sessionId`, or explicitly close the old session first. Do not overwrite
+a saved native ID with an absent ID from a failed turn.
+
+Within one engine, conversation identity survives process exit, idle eviction,
+and failed setup. Changing the working directory or credential environment on
+that logical session requires an explicit `resumeSessionId` or a new session.
+Across engine restarts, callers still need to supply the persisted native ID.
+A successful Claude resume can mint a new native ID; use the reported `resumed`
+flag rather than comparing Claude IDs. The `resumed: false` wire value remains
+readable for older engines and custom harnesses.
 
 ## Retry safely
 
@@ -203,9 +217,19 @@ identical request converges on the original execution — the wire acks it with
 `TurnConflictError`). This is what makes at-least-once RPC layers (Durable
 Object retries, queue redelivery) safe over the engine.
 
+Built-in harnesses allow one active turn per logical session, including setup
+and cancellation cleanup. Different sessions can run in parallel. Wait for the
+current turn to end before starting another. Direct `agent.execute` rejects
+overlap with `TurnActiveError`; embedded `runtime.run` completes the second
+turn with `error.category: "invalid_request"` without starting native work or
+changing its saved conversation. That result is memoized like other completed
+turns, so retry after the first turn ends with a **new `turnId`**. The wire
+rejects earlier with `turnActive`, before admission, so its rejected request
+can reuse its turn ID. Custom harnesses retain their own concurrency contract.
+
 ## Cancel honestly
 
-`turn/cancel` (and `runtime.cancel`) accept a `turnId` stamp — always pass
+`turn/cancel` accepts a `turnId` stamp — always pass
 the id of the turn you mean, so a late cancel can never kill its successor
 (a stale stamp returns `{outcome: "no_active_turn", activeTurnId}`). The
 result is a single-outcome union: `cancelled` means the harness confirmed the
@@ -214,6 +238,10 @@ the `turn/start` quick-ack and the harness registering its abortable turn —
 and the agent may still be running. On `unconfirmed`, report "stopping…" and
 treat `turn.ended` as the source of truth, not the cancel response.
 
+Embedded `runtime.cancel(harness, sessionId)` cancels the session's active
+turn without a turn ID check. Prefer a per-turn `AbortSignal` when cancellation
+can arrive late; a completed turn's signal is detached before the next turn.
+
 ## Verify the stream
 
 `verifyStreamContract(events, {seqs?})` machine-checks a recorded stream
@@ -235,14 +263,77 @@ and unknown event/part types are forward-compat rather than violations. Pass
 
 ## Own your session resources
 
+### Configure MCP between turns
+
+For Claude and Codex app-server, `RunConfig.mcpServers` is the complete set of wire-configured
+servers for that turn, not an incremental patch. Repeating an unchanged set
+reuses the running process and its MCP connections. Changed entries are
+applied through the harness's native configuration API before the prompt;
+finishing a turn does not restart the agent or its servers. Omitting the map
+on a later turn removes the previous wire-configured set, just like `{}`.
+Claude's host `sdkMcpServers` remain attached. The native CLI may also load MCP servers
+from settings or plugins; this map is not an exclusive tool allowlist.
+
+The engine snapshots the supplied wire configuration, including headers,
+before asynchronous setup. Credential rotation therefore works even if the
+caller reuses and mutates its server map between turns. Apply changes between
+turns and supply the current complete map on each turn. The explicit live
+`setMcpServers` control does not establish separate persistent defaults: the
+next turn's map takes precedence. External MCP servers enforce credential
+expiry; ending a turn does not itself revoke an attached credential.
+
+Codex supports stdio and Streamable HTTP servers; legacy SSE is rejected. Its
+per-turn MCP configuration requires an existing, absolute, session-specific
+`config.env.CODEX_HOME` directory. Create it with mode `0700`, retain it while
+the conversation may resume, and delete it when that logical session is
+released. It contains conversation history and MCP credentials. Never share
+it between sessions or use the operator's normal Codex home. AGNT supplies
+and owns these directories for its callers.
+
+The repository's interactive CLI accepts `--codex-home=/absolute/private/path`
+and remembers the path for `--continue`; the operator supplies and authenticates
+that existing home. The ACP **server binding** (`createAcpAgentApp` /
+`agent-server --acp --harness codex-app-server`) has no per-session environment
+resource seam in this release. It rejects supplied Codex MCP servers explicitly
+at `session/new` or `session/resume`. Use the engine or standard JSON-RPC API
+with `config.env.CODEX_HOME` for that combination. This limitation is separate
+from the engine's ACP **harness**, which forwards MCP to other ACP agents.
+
+An explicitly supplied `CODEX_HOME` gives the engine ownership of that home's
+user-layer `mcp_servers` table: each turn replaces that table, including
+clearing it when the map is omitted. Without an explicit home or a per-turn
+map, native Codex configuration continues to work normally. Repository and
+plugin servers remain separate, but a higher-priority setting that changes a
+requested server fails preparation before reload. Codex's `codex_apps` name
+is reserved.
+
+Codex writes changed configuration without reloading, verifies its effective
+settings, then reloads MCP and checks readiness before submitting the prompt.
+Servers still starting are awaited through native startup notifications, with
+a bounded deadline; unavailable or failed servers fail preparation immediately.
+Unchanged configuration is checked without reloading. A failed setup fails
+the turn; an explicitly submitted next turn reapplies the configuration so a
+previously failed native client can reconnect. No model turn or tool call is
+automatically replayed.
+
 ### 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.
+new turns. Drain active turns before suspending the host. This embed-tier
+lifecycle signal retains conversation state and turn-admission receipts.
+Before the next prompt, the Claude and Codex app-server harnesses replace
+retained subprocesses and strictly resume their saved conversations, using
+that turn's current MCP credentials before reconnecting the tools.
+Missing history fails with `resume_failed`; it never silently starts an empty
+conversation. Ordinary warm turns still reuse the process.
+
+A resumed VM can retain dead TCP sockets in Claude's process-wide HTTP pool;
+recreating MCP clients does not clear that pool. Codex's MCP configuration
+reload also retains stale connections when configuration is unchanged.
+Process replacement recreates CLI-owned stdio MCP processes and invokes
+Claude's host MCP factory again, as idle eviction already does. Keep durable
+tool state outside those processes. Workspace files and external MCP servers
+are unaffected. 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
@@ -254,13 +345,18 @@ turn before prompt submission. Tool calls and model turns are never replayed.
 
 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
-restarted the subprocess — usually respawns immediately with context kept),
+effects. Reasons: `idle` (idle-timeout eviction), `replaced` (config change or
+host resume replaced the subprocess — usually respawns immediately with context kept),
 `released` (explicit close), `shutdown`. On the wire, call `session/close`
 when a logical session will not be resumed: it frees the replay buffer and
 the harness-native state (until then, memory cost ≈ `bufferSize` events per
 session).
 
+When embedding, close idle sessions with `runtime.closeSession` and await its
+completion before starting another turn on that ID. Await shutdown before
+disposing the runtime. Cancellation acknowledgement alone does not mean the
+old execution has finished cleaning up.
+
 `session/close` also broadcasts `session.ended {reason: "released"}` — but
 only to subscribers **connected at that moment**, because the replay log is
 retired in the same operation. A subscriber that was detached does not get the
@@ -271,7 +367,7 @@ Treat `unknownSession` on replay as "session over", not as an error to retry.
 ## Listen to the engine's diagnostics
 
 Pass `onDiagnostic` (registry/runtime/proxy options) and log what arrives:
-`interruptTimeout`, `resumeFallback`, `sinkError`, `proxyUpstreamAuth`.
+`interruptTimeout`, `sinkError`, `proxyUpstreamAuth`.
 These are the signals the engine deliberately does not fail turns over — a
 product that doesn't surface them debugs blind.
 

package/docs/harnesses.md

@@ -31,12 +31,16 @@ warm multi-turn reuse, a unified `ThinkingLevel`, and normalized token usage.
 | `resumeSessionId` | ✅ | ✅ | ✅ |
 | `systemPromptAppend` | ✅ | ❌ (SDK has no field) | ✅ (`developerInstructions`) |
 | `maxTurns` | ✅ | ❌ | ❌ |
-| `mcpServers` | ✅ | ❌ (capability=false) | ❌ (capability=false) |
+| `mcpServers` | ✅ | ❌ (capability=false) | ✅ (stdio / Streamable HTTP; isolated `CODEX_HOME`) |
 | `apiKey` / `env` | ✅ | ✅ | `env` ✅, `apiKey` via ambient CLI auth |
 | `disableTools` | ✅ | (use read-only sandbox) | (use read-only sandbox) |
 | `permissionRequests` | ✅ (`canUseTool`) | ❌ (sandbox is the gate) | ✅ (`on-request` approvals) |
 | `includeRaw` | ✅ | ✅ | ✅ |
 
+Codex per-turn MCP is supported through the engine/JSON-RPC API, AGNT, and the
+repository CLI with an explicit `--codex-home`. The ACP server binding cannot
+provide isolated homes and rejects this combination at session admission.
+
 Consult `runtime.capabilities(harness)` before relying on a capability.
 
 ## Host-managed Codex authentication
@@ -116,8 +120,9 @@ provide the cache breakdown without an additional native usage report.
 
 ## Known limitations (roadmap)
 
-- **MCP servers** are wired for Claude only; Codex MCP passthrough is pending
-  an upstream protocol re-verification.
+- **MCP servers** are supported by Claude and Codex app-server. Codex SDK
+  passthrough remains unsupported. See [MCP configuration](consuming.md#configure-mcp-between-turns)
+  for Codex home ownership, supported transports, and live-update behavior.
 - The **BYOK proxy** (`/core/proxy`) is a building block, not yet auto-wired
   into the harnesses (they use ambient/explicit keys today).
 - **Hook bridge** (PreToolUse/Stop decisions) is exposed for the claude

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zvada/agent-server",
-	"version": "0.3.9",
+	"version": "0.3.10",
 	"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/acp/acp-agent.ts

@@ -6,9 +6,10 @@ import type {
 } from "@agentclientprotocol/sdk";
 import type { AgentCapabilities, AgentInput, PermissionMode } from "../../../protocol/index.ts";
 import { AsyncQueue } from "../../../protocol/index.ts";
+import { SessionResumeError } from "../../utils/errors.ts";
 import type { AgentExecuteOptions, PermissionRequestHandler, RawAgentEvent } from "../base.ts";
-import { BaseAgent } from "../base.ts";
 import { configFingerprint } from "../config-fingerprint.ts";
+import { SessionAgent } from "../session-agent.ts";
 import { SessionStore } from "../session-store.ts";
 import { AcpClient, type AcpClientOptions, type AcpLaunch } from "./client.ts";
 import {
@@ -22,9 +23,7 @@ import {
 
 const CAPABILITIES: AgentCapabilities = {
 	multiTurn: true,
-	// The engine always *accepts* resumeSessionId; whether context actually
-	// survives depends on the target agent's `sessionCapabilities.resume`
-	// (falls back to a fresh session when unsupported).
+	// A requested resume fails if the target agent cannot load saved sessions.
 	sessionResume: true,
 	// v1 exposes model selection only through agent-defined config options;
 	// there is no portable model parameter to pass through yet.
@@ -135,7 +134,7 @@ export async function answerPermission(
  * `session/prompt` *response*, so `execute` re-injects it into the raw stream
  * as a synthetic `session/prompt_result` event for the adapter.
  */
-export class AcpAgent extends BaseAgent {
+export class AcpAgent extends SessionAgent {
 	readonly harness = "acp" as const;
 	readonly capabilities = CAPABILITIES;
 	private readonly sessions = new SessionStore<AcpSession>();
@@ -163,21 +162,13 @@ export class AcpAgent extends BaseAgent {
 		});
 
 		const existing = this.sessions.get(options.sessionId);
-		let resumeTarget = options.resumeSessionId;
+		const resumeTarget = options.resumeSessionId;
 		if (existing && !existing.client.closed) {
 			if (acpSessionCompatible(existing, options, launchFingerprint)) {
 				this.sessions.clearIdle(existing);
 				return existing;
 			}
-			// Preserve context within the same cwd/env boundary when the agent can
-			// resume (mirrors the claude-code/codex restart policy).
-			if (
-				resumeTarget === undefined &&
-				existing.cwd === options.cwd &&
-				existing.envFingerprint === configFingerprint(options.env)
-			) {
-				resumeTarget = existing.acpSessionId;
-			}
+
 			this.sessions.close(options.sessionId);
 		}
 
@@ -210,20 +201,28 @@ export class AcpAgent extends BaseAgent {
 			);
 			if (signal.aborted) throw new Error("turn aborted");
 			const mcpServers = toAcpMcpServers(options.mcpServers);
-			if (resumeTarget && init.agentCapabilities?.sessionCapabilities?.resume) {
-				try {
-					await client.request(
+			if (resumeTarget) {
+				if (!init.agentCapabilities?.sessionCapabilities?.resume) {
+					throw new SessionResumeError(
+						resumeTarget,
+						"the ACP agent does not support session/resume",
+					);
+				}
+				await client
+					.request(
 						"session/resume",
 						{ sessionId: resumeTarget, cwd: options.cwd, mcpServers },
 						SESSION_REQUEST_TIMEOUT_MS,
-					);
-					acpSessionId = resumeTarget;
-				} catch {
-					// Unknown/expired session id — fall through to a fresh one.
-				}
-			}
-			if (signal.aborted) throw new Error("turn aborted");
-			if (!acpSessionId) {
+					)
+					.catch((cause: unknown) => {
+						throw new SessionResumeError(
+							resumeTarget,
+							cause instanceof Error ? cause.message : String(cause),
+							{ cause },
+						);
+					});
+				acpSessionId = resumeTarget;
+			} else {
 				const created = await client.request(
 					"session/new",
 					{ cwd: options.cwd, mcpServers },
@@ -231,6 +230,7 @@ export class AcpAgent extends BaseAgent {
 				);
 				acpSessionId = created.sessionId;
 			}
+			signal.throwIfAborted();
 			if (!acpSessionId) throw new Error("acp agent returned no session id");
 
 			const session: AcpSession = {
@@ -254,16 +254,17 @@ export class AcpAgent extends BaseAgent {
 		}
 	}
 
-	async *execute(
+	protected override async *executeTurn(
 		input: AgentInput,
 		options: AgentExecuteOptions,
+		controller: AbortController,
 	): AsyncIterableIterator<RawAgentEvent> {
-		const controller = this.trackTurn(options.sessionId, options.signal);
 		const queue = new AsyncQueue<RawAgentEvent>();
 		const unsubscribe: Array<() => void> = [];
 		let cancelTimer: ReturnType<typeof setTimeout> | undefined;
 		let session: AcpSession | undefined;
 		try {
+			controller.signal.throwIfAborted();
 			session = await this.resolveSession(options, controller.signal);
 			session.turn = {
 				broker: options.onPermissionRequest,
@@ -341,7 +342,6 @@ export class AcpAgent extends BaseAgent {
 			if (cancelTimer) clearTimeout(cancelTimer);
 			for (const off of unsubscribe) off();
 			if (session) session.turn = undefined;
-			this.endTurn(options.sessionId, controller);
 			if (session && !session.client.closed) {
 				this.sessions.armIdle(
 					options.sessionId,

package/src/core/agents/base.ts

@@ -66,8 +66,8 @@ export interface AgentExecuteOptions {
 	/**
 	 * Called once with the harness-native session/thread id (for resume).
 	 * Pass the harness's honest `resumed` judgment unconditionally — the
-	 * runtime surfaces it only on turns that requested a resume (false =
-	 * fresh-session fallback).
+	 * runtime surfaces it only on turns that requested a resume. Built-in
+	 * harnesses throw if a requested conversation cannot be loaded.
 	 */
 	onNativeSession?: (nativeSessionId: string, info?: { resumed?: boolean }) => void;
 	/** Engine-brokered approval round-trip (see PermissionRequestHandler). */
@@ -107,7 +107,7 @@ export interface Agent {
 	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). */
+	/** Tear down every live session (process shutdown). Built-ins reject subsequent turns. */
 	terminateAll(): Promise<void>;
 }
 
@@ -122,6 +122,7 @@ export abstract class BaseAgent implements Agent {
 	 * removes only the specific controller it created.
 	 */
 	protected readonly inflight = new Map<string, Set<AbortController>>();
+	private readonly unlinkAbort = new WeakMap<AbortController, () => void>();
 
 	abstract execute(
 		input: AgentInput,
@@ -162,16 +163,24 @@ export abstract class BaseAgent implements Agent {
 		set.add(controller);
 		if (external) {
 			if (external.aborted) controller.abort();
-			else external.addEventListener("abort", () => controller.abort(), { once: true });
+			else {
+				const onAbort = () => controller.abort();
+				external.addEventListener("abort", onAbort, { once: true });
+				this.unlinkAbort.set(controller, () => external.removeEventListener("abort", onAbort));
+			}
 		}
 		return controller;
 	}
 
 	protected endTurn(sessionId: string, controller?: AbortController): void {
 		const set = this.inflight.get(sessionId);
-		if (!set) return;
-		if (controller) set.delete(controller);
-		else set.clear();
-		if (set.size === 0) this.inflight.delete(sessionId);
+		// release/terminateAll may already have removed the set while the turn
+		// was draining. Its external signal must still be detached on completion.
+		for (const turn of controller ? [controller] : (set ?? [])) {
+			this.unlinkAbort.get(turn)?.();
+			this.unlinkAbort.delete(turn);
+			set?.delete(turn);
+		}
+		if (set?.size === 0) this.inflight.delete(sessionId);
 	}
 }