@zvada/agent-server 0.3.5 → 0.3.7-replay.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.3.7-replay.1
+
+- Add `AgentServerClient.onEventGap` for consumers using `startTurn` and `onEvent`.
+  Missing replay data and server restarts are reported before surviving events.
+  A gap describes incomplete delivery; native execution may still be running.
+- Track turns that disconnect before their first event and keep replay attempts
+  bound to the transport that started them. Preserve frames received during a
+  reconnect handshake even when they have already left the server's replay window.
+
+## 0.3.6
+
+- Unsupported Codex app-server requests now receive an explicit protocol error.
+  Previously, requests such as MCP elicitations were treated as file-edit
+  approvals and could leave a turn waiting in the permission broker. Command
+  and file approvals and host-managed credential refresh keep their existing behavior.
+
 ## 0.3.5
 
 - Switching Codex ChatGPT accounts or API keys now recreates the native process

package/docs/consuming.md

@@ -264,7 +264,19 @@ product that doesn't surface them debugs blind.
 and replays by default), `attach` (an accepted socket, e.g. the server dialed
 OUT to you via `--dial`). The client dedupes by per-session `seq` and heals
 gaps via `events/replay`; an unfillable gap raises `EventGapError` instead of
-silently losing events. The WebSocket wire itself carries no auth — keep it
+silently losing events. When using `startTurn` with `onEvent`, subscribe to
+`onEventGap` before starting work. It runs synchronously before any surviving
+suffix and returns an unsubscribe function. `runTurn().result` continues to
+reject on these same gaps.
+
+A gap describes incomplete delivery, not a successful stop. Keep the affected
+turn's output marked incomplete even if its native terminal says `end_turn`.
+`server_restarted` and `session_missing` mean the old terminal cannot arrive;
+`evicted`, `replay_failed`, and `log_reset` can require a turn-stamped
+`cancelTurn(sessionId, turnId)` to reconcile execution. Never cancel a successor
+by reading its ID after an asynchronous recovery operation.
+
+The WebSocket wire itself carries no auth — keep it
 on a trusted channel (localhost, sandbox-internal, or behind your own
 authenticated boundary).
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zvada/agent-server",
-	"version": "0.3.5",
+	"version": "0.3.7-replay.1",
 	"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/client/client.ts

@@ -62,6 +62,13 @@ export class EventGapError extends Error {
 	override readonly name = "EventGapError";
 }
 
+/** A delivery failure, reported before surviving events. Execution may continue. */
+export interface SessionEventGap {
+	sessionId: string;
+	reason: "evicted" | "replay_failed" | "session_missing" | "server_restarted" | "log_reset";
+	error: EventGapError;
+}
+
 /**
  * A running turn: consume `events` (ends after `turn.ended`) or await `result`.
  *
@@ -145,11 +152,16 @@ export class AgentServerClient {
 	private readonly pending = new Map<JsonRpcId, PendingRequest>();
 	/** Per-session seq discipline — the shared `/protocol` implementation. */
 	private readonly cursor = createSeqCursor();
-	private readonly heldBack = new Map<string, DecodedWireEventEnvelope[]>();
+	private readonly heldBack = new Map<
+		string,
+		Array<{ envelope: DecodedWireEventEnvelope; transport: WireTransport | null }>
+	>();
 	/** The server process behind the transport, learned at `initialize`. */
 	private serverInstanceId: string | undefined;
-	private readonly syncing = new Set<string>();
+	private readonly syncing = new Map<string, WireTransport>();
 	private readonly eventHandlers = new Set<(envelope: DecodedWireEventEnvelope) => void>();
+	private readonly gapHandlers = new Set<(gap: SessionEventGap) => void>();
+	private awaitingHandshake = false;
 	private readonly turnBySession = new Map<string, InternalTurn>();
 	private initializePromise: Promise<InitializeResult> | null = null;
 	private closed = false;
@@ -266,16 +278,26 @@ export class AgentServerClient {
 		// log will ever emit THEIR turn.ended — an un-failed handle hangs forever
 		// (a session id the fresh process happens to reuse would even feed it
 		// someone else's events).
-		for (const sessionId of [...this.turnBySession.keys()]) {
-			this.failTurn(
+		const sessionIds = new Set([...this.cursor.sessions(), ...this.turnBySession.keys()]);
+		for (const sessionId of sessionIds) {
+			this.reportEventGap(
 				sessionId,
+				"server_restarted",
 				new EventGapError(
 					`server instance changed; the turn's session log died with the old process`,
 				),
 			);
 		}
 		for (const sessionId of this.cursor.sessions()) this.cursor.reset(sessionId);
-		this.heldBack.clear();
+		// Keep frames actually received from the fresh process: they may already
+		// have left its bounded replay window. Only old transport entries die.
+		for (const [sessionId, held] of this.heldBack) {
+			const fresh = held.filter((entry) => entry.transport === this.transport);
+			if (fresh.length) {
+				this.heldBack.set(sessionId, fresh);
+				this.cursor.seek(sessionId, 0);
+			} else this.heldBack.delete(sessionId);
+		}
 	}
 
 	/**
@@ -317,7 +339,14 @@ export class AgentServerClient {
 	/** Quick-ack only — observe the turn via `onEvent` / `replay`. */
 	async startTurn(params: TurnStartParams): Promise<{ sessionId: string; turnId: string }> {
 		await this.initialize();
-		return this.request(WIRE_METHODS.turnStart, params, TurnStartResultSchema);
+		const sessionId = params.sessionId ?? generateUUIDv7();
+		const turnId = params.turnId ?? generateUUIDv7();
+		this.cursor.seek(sessionId, this.cursor.last(sessionId));
+		return this.request(
+			WIRE_METHODS.turnStart,
+			{ ...params, sessionId, turnId },
+			TurnStartResultSchema,
+		);
 	}
 
 	/** Answer a `permission.requested` event. */
@@ -380,6 +409,12 @@ export class AgentServerClient {
 		return () => this.eventHandlers.delete(handler);
 	}
 
+	/** Observe unrecoverable delivery gaps even when using startTurn without a handle. */
+	onEventGap(handler: (gap: SessionEventGap) => void): () => void {
+		this.gapHandlers.add(handler);
+		return () => this.gapHandlers.delete(handler);
+	}
+
 	/** Ask the server to shut down, then close this client. */
 	async shutdownServer(): Promise<void> {
 		await this.request(WIRE_METHODS.shutdown, {}, ShutdownResultSchema).catch(() => undefined);
@@ -406,7 +441,10 @@ export class AgentServerClient {
 		}
 		if (transport.closed) throw new ConnectionClosedError("transport opened already closed");
 		this.transport = transport;
-		transport.onLine((line) => this.handleLine(line));
+		this.awaitingHandshake = this.reconnecting;
+		transport.onLine((line) => {
+			if (this.transport === transport) this.handleLine(line);
+		});
 		transport.onClose((reason) => this.handleTransportClose(transport, reason));
 	}
 
@@ -443,10 +481,15 @@ export class AgentServerClient {
 					this.initializePromise = null;
 					await this.initialize();
 					if (this.closed || !this.transport) continue;
+					this.awaitingHandshake = false;
 					// Heal every tracked session — including turns that saw no event
 					// before the drop (or none after it): without a resync they would
 					// never receive their turn.ended and would hang forever.
-					const sessionIds = new Set([...this.cursor.sessions(), ...this.turnBySession.keys()]);
+					const sessionIds = new Set([
+						...this.cursor.sessions(),
+						...this.turnBySession.keys(),
+						...this.heldBack.keys(),
+					]);
 					for (const sessionId of sessionIds) void this.syncSession(sessionId);
 					if (!this.transport) continue;
 					return;
@@ -500,7 +543,7 @@ export class AgentServerClient {
 		const sessionId = envelope.sessionId;
 		// While a replay is in flight, every envelope queues: the drain re-runs
 		// the cursor over the merged (replayed + live) backlog in seq order.
-		if (this.syncing.has(sessionId)) {
+		if (this.awaitingHandshake || this.syncing.get(sessionId) === this.transport) {
 			this.holdBack(sessionId, envelope);
 			return;
 		}
@@ -513,6 +556,11 @@ export class AgentServerClient {
 				// arm fires only if a fresh log appears with NO transport drop,
 				// which no current topology produces. If it does: the queue is
 				// dead-log state, the fresh frame is authoritative.
+				this.reportEventGap(
+					sessionId,
+					"log_reset",
+					new EventGapError(`session ${sessionId} log reset`),
+				);
 				this.heldBack.delete(sessionId);
 				this.deliver(envelope);
 				return;
@@ -529,16 +577,17 @@ export class AgentServerClient {
 
 	private holdBack(sessionId: string, envelope: DecodedWireEventEnvelope): void {
 		const held = this.heldBack.get(sessionId) ?? [];
-		held.push(envelope);
+		held.push({ envelope, transport: this.transport });
 		this.heldBack.set(sessionId, held);
 	}
 
 	private drainHeld(sessionId: string): void {
+		if (this.awaitingHandshake) return;
 		const held = this.heldBack.get(sessionId);
 		if (!held?.length) return;
-		held.sort((a, b) => a.seq - b.seq);
+		held.sort((a, b) => a.envelope.seq - b.envelope.seq);
 		while (held.length) {
-			const next = held[0] as DecodedWireEventEnvelope;
+			const next = held[0]!.envelope;
 			// `gap` leaves the cursor untouched, so breaking here is safe: the
 			// envelope stays queued for the replay that fills the hole.
 			const verdict = this.cursor.advance(sessionId, next.seq);
@@ -547,9 +596,15 @@ export class AgentServerClient {
 			if (verdict === "reset") {
 				// Defense-in-depth only (see the reset arm in handleEnvelope):
 				// drop the queue, deliver the fresh frame, resync for its tail.
+				this.reportEventGap(
+					sessionId,
+					"log_reset",
+					new EventGapError(`session ${sessionId} log reset`),
+				);
 				held.length = 0;
 				this.deliver(next);
-				void this.syncSession(sessionId);
+				// Let any replay owning this drain release its transport first.
+				queueMicrotask(() => void this.syncSession(sessionId));
 				break;
 			}
 			if (verdict !== "duplicate") this.deliver(next);
@@ -558,32 +613,48 @@ export class AgentServerClient {
 	}
 
 	private async syncSession(sessionId: string): Promise<void> {
-		if (this.syncing.has(sessionId) || this.closed || !this.transport) return;
-		this.syncing.add(sessionId);
+		const transport = this.transport;
+		if (
+			!transport ||
+			this.awaitingHandshake ||
+			this.closed ||
+			this.syncing.get(sessionId) === transport
+		)
+			return;
+		this.syncing.set(sessionId, transport);
+		const isCurrent = () => !this.closed && !this.awaitingHandshake && this.transport === transport;
 		try {
 			const maxAttempts = Math.max(1, this.options.maxReplayAttempts ?? 3);
 			const retryDelay = this.options.replayRetryDelayMs ?? this.options.reconnectDelayMs ?? 250;
-			for (let attempt = 1; attempt <= maxAttempts && !this.closed && this.transport; attempt++) {
+			for (let attempt = 1; attempt <= maxAttempts && isCurrent(); attempt++) {
+				this.drainHeld(sessionId);
+				if (!isCurrent()) return;
 				const fromSeq = this.cursor.last(sessionId) + 1;
 				try {
 					const replayed = await this.replay(sessionId, fromSeq);
-					if (replayed.firstAvailableSeq !== null && replayed.firstAvailableSeq > fromSeq) {
+					if (!isCurrent()) return;
+					for (const envelope of replayed.events) this.holdBack(sessionId, envelope);
+					this.drainHeld(sessionId);
+					const missingFrom = this.cursor.last(sessionId) + 1;
+					if (replayed.firstAvailableSeq !== null && replayed.firstAvailableSeq > missingFrom) {
 						// The prefix was evicted — the gap is unfillable. Fail the turn
 						// handle (its part reconstruction is broken) and jump forward.
-						this.failTurn(
+						this.reportEventGap(
 							sessionId,
+							"evicted",
 							new EventGapError(
-								`events ${fromSeq}..${replayed.firstAvailableSeq - 1} for session ${sessionId} were evicted`,
+								`events ${missingFrom}..${replayed.firstAvailableSeq - 1} for session ${sessionId} were evicted`,
 							),
 						);
 						this.cursor.seek(sessionId, replayed.firstAvailableSeq - 1);
 					}
-					for (const envelope of replayed.events) this.holdBack(sessionId, envelope);
 					break;
 				} catch (err) {
+					if (!isCurrent()) return;
 					if (err instanceof WireRequestError && err.code === WIRE_ERROR_CODES.unknownSession) {
-						this.failTurn(
+						this.reportEventGap(
 							sessionId,
+							"session_missing",
 							new EventGapError(`session ${sessionId} is unknown to the server (restarted?)`),
 						);
 						this.cursor.reset(sessionId);
@@ -592,8 +663,9 @@ export class AgentServerClient {
 					}
 					if (!this.transport || this.closed) break; // reconnect performs a fresh resync
 					if (attempt === maxAttempts) {
-						this.failTurn(
+						this.reportEventGap(
 							sessionId,
+							"replay_failed",
 							new EventGapError(
 								`failed to replay events from ${fromSeq} for session ${sessionId} after ${maxAttempts} attempts`,
 							),
@@ -605,9 +677,9 @@ export class AgentServerClient {
 				}
 			}
 		} finally {
-			this.syncing.delete(sessionId);
+			if (this.syncing.get(sessionId) === transport) this.syncing.delete(sessionId);
 		}
-		this.drainHeld(sessionId);
+		if (isCurrent()) this.drainHeld(sessionId);
 	}
 
 	/** Dispatch an envelope the cursor already accepted (it owns the watermark). */
@@ -630,6 +702,21 @@ export class AgentServerClient {
 		}
 	}
 
+	private reportEventGap(
+		sessionId: string,
+		reason: SessionEventGap["reason"],
+		error: EventGapError,
+	): void {
+		this.failTurn(sessionId, error);
+		for (const handler of [...this.gapHandlers]) {
+			try {
+				handler({ sessionId, reason, error });
+			} catch {
+				// A consumer callback cannot interrupt replay or other subscribers.
+			}
+		}
+	}
+
 	private failTurn(sessionId: string, error: Error): void {
 		const turn = this.turnBySession.get(sessionId);
 		if (!turn) return;

package/src/client/index.ts

@@ -6,6 +6,7 @@ export {
 	type AgentServerClientOptions,
 	ConnectionClosedError,
 	EventGapError,
+	type SessionEventGap,
 	type TurnHandle,
 	WireRequestError,
 } from "./client.ts";

package/src/core/agents/codex-app-server/codex-app-server-agent.ts

@@ -395,6 +395,16 @@ export class CodexAppServerAgent extends BaseAgent {
 					chatgptPlanType: tokens.chatgptPlanType ?? null,
 				};
 			}
+			// Elicitations and other server requests have their own response shapes.
+			// Sending them to the approval broker can leave a turn waiting forever.
+			if (
+				method !== "item/commandExecution/requestApproval" &&
+				method !== "item/fileChange/requestApproval" &&
+				method !== "execCommandApproval" &&
+				method !== "applyPatchApproval"
+			) {
+				throw new Error(`Unsupported Codex server request: ${method}`);
+			}
 			const requestThread = params.threadId ?? params.conversationId;
 			const v2 = method.startsWith("item/");
 			const decline = v2 ? { decision: "decline" } : { decision: "denied" };