@zvada/agent-server 0.2.2 → 0.3.1

package/docs/deploy.md

@@ -0,0 +1,80 @@
+# Deploying agent-server
+
+## CLI provisioning (deterministic agents)
+
+The native harnesses spawn real CLIs (`claude` ~220 MB, `codex` ~300 MB
+unpacked). Instead of trusting whatever version a host happens to have, the
+engine can **download the pinned, engine-tested builds** from the npm registry
+into a local cache — sha512-verified, installed atomically, shared across
+processes. Three modes (`--provision`, `$AGENT_SERVER_PROVISION`, or
+`createAgentRuntime({ provision })`):
+
+- **`auto`** (default): explicit override → host install → managed cache →
+  download. Zero-config: uses what the machine has, self-heals on bare ones.
+- **`pinned`**: override → cache → download. Never trusts host installs —
+  every process in a fleet runs the exact tested build.
+- **`system`**: override → host install only. Never downloads (air-gapped).
+
+"Host install" means the build the installed SDK itself would run — claude's
+sibling platform package, codex's vendored `@openai/codex` tree (the JS ↔ CLI
+pair from your lockfile) — with PATH as codex's fallback. Overrides are
+operator-level only — `$CLAUDE_CLI_PATH` / `$CODEX_CLI_PATH` (or
+`provision.overrides`), never wire config: a remote client must not choose the
+executable a server spawns. Auth stays host-side either way: managed CLIs read
+the same `~/.claude` / `~/.codex` (or per-turn `config.apiKey` BYOK) as your
+own installs. Every resolution logs one stderr line
+(`claude CLI: … (cache 0.3.168)`) so runs are diagnosable.
+
+Pins live in `src/core/provision/pins.ts`: the claude pin tracks the
+lockfile's `@anthropic-ai/claude-agent-sdk` version (test-enforced); the codex
+pin is the version the app-server adapter's protocol was verified against.
+
+## Single binary & sandbox cold starts
+
+The server compiles to a self-contained executable — no bun, node, or
+node_modules on the target:
+
+```sh
+bun build --compile packages/agent-server/src/server/bin.ts --outfile dist/agent-server
+# cross-compile from any machine:
+#   --target=bun-darwin-arm64 | bun-darwin-x64 | bun-linux-x64 | bun-linux-arm64
+#   | bun-linux-x64-musl (Alpine) | bun-linux-arm64-musl
+```
+
+Inside a compiled binary the Claude SDK can't reach its platform package, so
+provisioning is what makes the binary *work*: first turn on a bare machine
+downloads the pinned CLIs (~7 s on datacenter bandwidth, parallel), every
+later boot resolves from cache instantly.
+
+For sandboxes (E2B, Modal, Fly, plain Docker), erase even that first-turn cost
+by prefetching **at image build time**:
+
+```dockerfile
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y ca-certificates tar && rm -rf /var/lib/apt/lists/*
+COPY dist/agent-server /usr/local/bin/agent-server
+# bake the pinned CLIs into the image → zero downloads at runtime
+RUN agent-server install
+ENV ANTHROPIC_API_KEY=""            # or mount ~/.claude / ~/.codex at runtime
+ENTRYPOINT ["agent-server", "--provision", "pinned", "--listen", "0.0.0.0:4747"]
+```
+
+`agent-server install` respects `--harness a,b` (only fetch what you run) and
+`$AGENT_SERVER_CACHE_DIR` (e.g. point it at a persistent volume instead of
+baking). The cache layout is version-keyed
+(`<cache>/claude/0.3.168-darwin-arm64/…`), so image layers and shared volumes
+dedupe naturally and concurrent cold starts converge on one copy. The cache
+root is created `0o700` and must be owned by the running user — a foreign or
+symlinked root is refused (predictable install paths must not be plantable).
+
+Measured in a live E2B sandbox (x86_64 Ubuntu, 2026-07): sandbox create 0.7 s,
+`install --harness claude-code` 3.0 s (71 MB, verified), first real Claude
+turn over the wire (BYOK `config.apiKey`) **2.0 s**. With the CLIs baked into
+the template, boot-to-first-token is effectively sandbox-create + turn time.
+
+## Trust boundary
+
+The WebSocket wire carries no built-in authentication or TLS termination.
+Keep it on a trusted channel — localhost, sandbox-internal, or behind your own
+authenticated transport boundary. The stdio wire inherits the trust of
+whoever spawned the process.

package/docs/harnesses.md

@@ -0,0 +1,64 @@
+# Harness support matrix
+
+Four harnesses, one event stream. The lifecycle event *structure* is identical
+across harnesses (one generic `EventProcessor` drives it); payloads and config
+support differ only where the backends genuinely do.
+
+| Harness | Backend | Streaming | Resume | Model switch |
+| --- | --- | --- | --- | --- |
+| `claude-code` | `@anthropic-ai/claude-agent-sdk` (claude CLI) | token-level | yes (`resume`) | in-session (`setModel`) |
+| `codex-sdk` | `@openai/codex-sdk` (codex CLI exec) | item-level (deltas synthesized) | yes (`resumeThread`) | restart-session |
+| `codex-app-server` | `codex app-server` (JSON-RPC subprocess) | token-level | yes (`thread/resume`) | in-session (per-turn) |
+| `acp` | any ACP v1 agent via `@agentclientprotocol/sdk` | per-agent | yes (`session/resume`) | per-agent |
+
+The `acp` harness is opt-in (an operator-supplied launch command, never
+wire-sourced): well-known agents run by name (`--harness=pi`,
+`--harness=gemini`); anything else via `--acp-agent="<launch command>"` /
+`$AGENT_SERVER_ACP_AGENT`, or `CreateRegistryOptions.acp.resolveLaunch` when
+embedding.
+
+All harnesses share: one stable logical `sessionId` you assign, a
+harness-native id surfaced via `session.created` (persist it to resume later),
+warm multi-turn reuse, a unified `ThinkingLevel`, and normalized token usage.
+
+## `RunConfig` support per harness
+
+| `RunConfig` field | claude-code | codex-sdk | codex-app-server |
+| --- | --- | --- | --- |
+| `model` | ✅ + hot-swap | ✅ (restart on change) | ✅ (per-turn) |
+| `thinkingLevel` | ✅ | ✅ | ✅ |
+| `permissionMode` | ✅ | ✅ → sandbox | ✅ → sandbox |
+| `resumeSessionId` | ✅ | ✅ | ✅ |
+| `systemPromptAppend` | ✅ | ❌ (SDK has no field) | ✅ (`developerInstructions`) |
+| `maxTurns` | ✅ | ❌ | ❌ |
+| `mcpServers` | ✅ | ❌ (capability=false) | ❌ (capability=false) |
+| `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` | ✅ | ✅ | ✅ |
+
+Consult `runtime.capabilities(harness)` before relying on a capability.
+
+## Payload notes
+
+- A turn ends with a normalized `stopReason`
+  (`end_turn | max_tokens | max_turn_requests | refusal | cancelled | error`);
+  the raw provider string travels in `finishReason`.
+- `cost` is reported only by Claude; `reasoning` tokens only by Codex.
+- Tool names are provider-native for Claude (`Bash`, `Read`) and normalized
+  for Codex (`shell`, `apply_patch`, …) — but the tool `kind`
+  (`read`/`edit`/`execute`/…) is normalized for all.
+- `raw` events are an opt-in (`config.includeRaw`) passthrough of the
+  harness's unparsed event, for migration/debugging/fixture-recording. `data`
+  has **no stability guarantees** and is off by default.
+
+## Known limitations (roadmap)
+
+- **MCP servers** are wired for Claude only; Codex MCP passthrough is pending
+  an upstream protocol re-verification.
+- 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
+  embed tier only (`hooks` factory); there is no wire-level hook surface yet.
+- The WebSocket wire has no built-in auth — see
+  [deploy.md](deploy.md#trust-boundary).

package/docs/rfds/0001-deterministic-echo-ids.md

@@ -0,0 +1,44 @@
+# RFD 0001 — Deterministic echo ids
+
+**Status: adopted** (0.3.0, unpublished — shipped with the consumer-machinery batch).
+
+## Change
+
+The user echo's ids are **derived from the turn id** instead of minted as UUIDv7:
+
+- echo message id: `echo-<turnId>`
+- echo part ids: `echo-<turnId>-<index>`
+
+Exported as `echoMessageId(turnId)` / `echoPartId(turnId, index)`;
+`createUserEchoParts(input, turnId)` stamps them. This is a **documented
+exception to Law 8** (engine-minted UUIDv7).
+
+## Why
+
+The echo is not new information — it is the caller's own input played back, and
+one turn has exactly one echo message. Every consumer that renders an
+optimistic prompt bubble was reconciling a look-alike against the echo by
+`turnId` (spec §7.2's old rule) — a swap with visible failure modes (deus lost
+file parts in the swap; agnt double-echoed). With derived ids, a consumer that
+minted the `turnId` predicts the echo **byte-for-byte**: the optimistic bubble
+IS the echo, and it upserts onto itself. Retried turns converge the same way
+(turn admission is idempotent on `{sessionId, turnId}`).
+
+## What ids still are
+
+Opaque to peers. Derivation is a producer rule matched by exported consumer
+helpers — not a licence to parse structure out of ids anywhere else.
+
+## Costs (documented, accepted)
+
+- Echo ids do not time-sort against UUIDv7 ids. Never order by id; order by
+  `outputIndex`/`seq` (which the spec already mandates — Law 5).
+- Echo ids fail UUID-shaped derivations: uuid-typed columns and
+  `createdAtFromUUID7`-style timestamp extraction (returns 0). Derive the
+  echo's time from the **`turnId` field** the event/row already carries (it is
+  UUIDv7) — never by parsing the echo id string; ids stay opaque.
+
+## Spec delta
+
+PROTOCOL.md §7.2 (echo reconciliation) and Law 8 (id minting) carry the
+amendment; `docs/consuming.md` describes prediction instead of reconciliation.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zvada/agent-server",
-	"version": "0.2.2",
+	"version": "0.3.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",
@@ -25,7 +25,7 @@
 	"engines": {
 		"bun": ">=1.2.0"
 	},
-	"files": ["src", "README.md", "AGENTS.md", "LICENSE"],
+	"files": ["src", "docs", "README.md", "CHANGELOG.md", "LICENSE"],
 	"publishConfig": {
 		"access": "public"
 	},
@@ -41,6 +41,26 @@
 			"types": "./src/protocol/index.ts",
 			"default": "./src/protocol/index.ts"
 		},
+		"./protocol/factories": {
+			"types": "./src/protocol/factories.ts",
+			"default": "./src/protocol/factories.ts"
+		},
+		"./protocol/guards": {
+			"types": "./src/protocol/guards.ts",
+			"default": "./src/protocol/guards.ts"
+		},
+		"./protocol/stop-reasons": {
+			"types": "./src/protocol/stop-reasons.ts",
+			"default": "./src/protocol/stop-reasons.ts"
+		},
+		"./protocol/seq-cursor": {
+			"types": "./src/protocol/seq-cursor.ts",
+			"default": "./src/protocol/seq-cursor.ts"
+		},
+		"./protocol/selectors": {
+			"types": "./src/protocol/selectors.ts",
+			"default": "./src/protocol/selectors.ts"
+		},
 		"./core": {
 			"types": "./src/core/index.ts",
 			"default": "./src/core/index.ts"
@@ -80,7 +100,7 @@
 	},
 	"devDependencies": {
 		"@agentclientprotocol/sdk": "^1.2.1",
-		"@anthropic-ai/claude-agent-sdk": "^0.3.168",
+		"@anthropic-ai/claude-agent-sdk": "0.3.220",
 		"@openai/codex-sdk": "^0.146.1",
 		"@types/bun": "^1.2.0"
 	}

package/src/client/client.ts

@@ -1,11 +1,11 @@
 import {
 	AsyncQueue,
-	type EventsReplayResult,
-	EventsReplayResultSchema,
+	type DecodedEventsReplayResult,
+	type DecodedLifecycleEvent,
+	type DecodedWireEventEnvelope,
 	type InitializeResult,
 	InitializeResultSchema,
 	type JsonRpcId,
-	type LifecycleEvent,
 	type PermissionOutcome,
 	PermissionRespondResultSchema,
 	SessionCloseResultSchema,
@@ -15,16 +15,19 @@ import {
 	type TurnEndedEvent,
 	type TurnStartParams,
 	TurnStartResultSchema,
+	type UnknownEvent,
 	WIRE_ERROR_CODES,
 	WIRE_METHODS,
 	WIRE_PROTOCOL_VERSION,
-	type WireEventEnvelope,
-	WireEventEnvelopeSchema,
 	type WireImplementationInfo,
 	type WireTransport,
+	createSeqCursor,
+	decodeEventsReplayResult,
+	decodeWireEventEnvelope,
 	decodeWireMessage,
 	encodeRequest,
 	generateUUIDv7,
+	isUnknownEvent,
 } from "../protocol/index.ts";
 import {
 	type SpawnServerOptions,
@@ -59,11 +62,18 @@ export class EventGapError extends Error {
 	override readonly name = "EventGapError";
 }
 
-/** A running turn: consume `events` (ends after `turn.ended`) or await `result`. */
+/**
+ * A running turn: consume `events` (ends after `turn.ended`) or await `result`.
+ *
+ * `events` yields `UnknownEvent`s too (Law 6): a newer server's event type is
+ * delivered in order rather than dropped, so consumers persist and forward it.
+ * Narrow with `isUnknownEvent` before switching on a known `type`;
+ * `reduceConversation` already accepts the union as-is.
+ */
 export interface TurnHandle {
 	sessionId: string;
 	turnId: string;
-	events: AsyncIterableIterator<LifecycleEvent>;
+	events: AsyncIterableIterator<DecodedLifecycleEvent | UnknownEvent>;
 	result: Promise<TurnEndedEvent>;
 }
 
@@ -94,7 +104,7 @@ interface PendingRequest {
 
 interface InternalTurn {
 	turnId: string;
-	queue: AsyncQueue<LifecycleEvent>;
+	queue: AsyncQueue<DecodedLifecycleEvent | UnknownEvent>;
 	resolveResult: (event: TurnEndedEvent) => void;
 	rejectResult: (error: unknown) => void;
 }
@@ -103,6 +113,22 @@ interface ResultSchema<T> {
 	safeParse(raw: unknown): { success: true; data: T } | { success: false };
 }
 
+/**
+ * `events/replay` decoded the Law-6 way. Using `EventsReplayResultSchema`
+ * here would embed the closed event union in the very path that heals a gap,
+ * so a single unknown event type in the buffer would fail the replay, retry,
+ * and take the turn handle down with an `EventGapError`.
+ */
+const REPLAY_RESULT: ResultSchema<DecodedEventsReplayResult> = {
+	safeParse(raw) {
+		try {
+			return { success: true, data: decodeEventsReplayResult(raw) };
+		} catch {
+			return { success: false };
+		}
+	},
+};
+
 type TransportFactory = () => Promise<WireTransport> | WireTransport;
 
 /**
@@ -117,10 +143,13 @@ export class AgentServerClient {
 	private transport: WireTransport | null = null;
 	private nextId = 1;
 	private readonly pending = new Map<JsonRpcId, PendingRequest>();
-	private readonly lastSeq = new Map<string, number>();
-	private readonly heldBack = new Map<string, WireEventEnvelope[]>();
+	/** Per-session seq discipline — the shared `/protocol` implementation. */
+	private readonly cursor = createSeqCursor();
+	private readonly heldBack = new Map<string, DecodedWireEventEnvelope[]>();
+	/** The server process behind the transport, learned at `initialize`. */
+	private serverInstanceId: string | undefined;
 	private readonly syncing = new Set<string>();
-	private readonly eventHandlers = new Set<(envelope: WireEventEnvelope) => void>();
+	private readonly eventHandlers = new Set<(envelope: DecodedWireEventEnvelope) => void>();
 	private readonly turnBySession = new Map<string, InternalTurn>();
 	private initializePromise: Promise<InitializeResult> | null = null;
 	private closed = false;
@@ -210,6 +239,13 @@ export class AgentServerClient {
 						{ supported: [WIRE_PROTOCOL_VERSION] },
 					);
 				}
+				// The restart question, answered by the handshake instead of
+				// inferred from seq patterns: a changed instanceId means every
+				// session log we were tracking belongs to a dead process.
+				if (this.serverInstanceId !== undefined && this.serverInstanceId !== result.instanceId) {
+					this.adoptFreshLogs();
+				}
+				this.serverInstanceId = result.instanceId;
 				return result;
 			})
 			.catch((err) => {
@@ -219,6 +255,29 @@ export class AgentServerClient {
 		return this.initializePromise;
 	}
 
+	/**
+	 * The server process we were talking to is gone; its logs died with it.
+	 * Drop every per-session cursor and queue so the reconnect resync replays
+	 * each fresh log from seq 1. Local views may be stale relative to the fresh
+	 * logs; consumers with durable state resnapshot on their side.
+	 */
+	private adoptFreshLogs(): void {
+		// Active turns first: their logs died with the old process, and no fresh
+		// 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(
+				sessionId,
+				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();
+	}
+
 	/**
 	 * Start a turn and stream it. Ids are minted client-side when omitted so
 	 * events arriving around the ack are never dropped.
@@ -230,7 +289,7 @@ export class AgentServerClient {
 		if (this.turnBySession.has(sessionId)) {
 			throw new Error(`session ${sessionId} already has an active turn`);
 		}
-		const queue = new AsyncQueue<LifecycleEvent>();
+		const queue = new AsyncQueue<DecodedLifecycleEvent | UnknownEvent>();
 		let resolveResult!: (event: TurnEndedEvent) => void;
 		let rejectResult!: (error: unknown) => void;
 		const result = new Promise<TurnEndedEvent>((resolve, reject) => {
@@ -278,10 +337,10 @@ export class AgentServerClient {
 	/**
 	 * Cancel the session's active turn; resolves once cancellation propagated.
 	 * Pass `turnId` to make the cancel turn-stamped: a late cancel meant for a
-	 * finished turn then returns `{cancelled: false, activeTurnId}` instead of
-	 * killing the turn that replaced it. `confirmed: false` on the result means
-	 * the harness did not acknowledge the interrupt — the agent may still be
-	 * running; `turn.ended` remains the source of truth.
+	 * finished turn then returns `{outcome: "no_active_turn", activeTurnId}`
+	 * instead of killing the turn that replaced it. `{outcome: "unconfirmed"}`
+	 * means the harness did not acknowledge the interrupt — the agent may still
+	 * be running; `turn.ended` remains the source of truth.
 	 */
 	cancelTurn(sessionId: string, turnId?: string): Promise<TurnCancelResult> {
 		return this.request(
@@ -311,16 +370,12 @@ export class AgentServerClient {
 	}
 
 	/** Fetch buffered events (`seq >= fromSeq`) without touching seq tracking. */
-	replay(sessionId: string, fromSeq: number): Promise<EventsReplayResult> {
-		return this.request(
-			WIRE_METHODS.eventsReplay,
-			{ sessionId, fromSeq },
-			EventsReplayResultSchema,
-		);
+	replay(sessionId: string, fromSeq: number): Promise<DecodedEventsReplayResult> {
+		return this.request(WIRE_METHODS.eventsReplay, { sessionId, fromSeq }, REPLAY_RESULT);
 	}
 
 	/** Firehose of sequenced events across all sessions (post-dedupe, in order). */
-	onEvent(handler: (envelope: WireEventEnvelope) => void): () => void {
+	onEvent(handler: (envelope: DecodedWireEventEnvelope) => void): () => void {
 		this.eventHandlers.add(handler);
 		return () => this.eventHandlers.delete(handler);
 	}
@@ -381,10 +436,17 @@ export class AgentServerClient {
 				try {
 					await this.openTransport();
 					if (this.closed || !this.transport) continue;
+					// Re-handshake: the transport may have reconnected to a DIFFERENT
+					// process (or a different build). A version mismatch fails loudly
+					// here instead of silently mixing dialects, and a changed
+					// instanceId adopts the fresh logs before any resync runs.
+					this.initializePromise = null;
+					await this.initialize();
+					if (this.closed || !this.transport) continue;
 					// 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.lastSeq.keys(), ...this.turnBySession.keys()]);
+					const sessionIds = new Set([...this.cursor.sessions(), ...this.turnBySession.keys()]);
 					for (const sessionId of sessionIds) void this.syncSession(sessionId);
 					if (!this.transport) continue;
 					return;
@@ -417,33 +479,55 @@ export class AgentServerClient {
 			return;
 		}
 		if (msg.kind === "notification" && msg.method === WIRE_METHODS.event) {
-			const parsed = WireEventEnvelopeSchema.safeParse(msg.params);
-			if (parsed.success) this.handleEnvelope(parsed.data);
+			try {
+				// Law 6: an unknown event TYPE is preserved and still advances seq.
+				// Only a malformed envelope or a malformed KNOWN event lands here —
+				// a server bug, which must not be papered over by advancing past it.
+				this.handleEnvelope(decodeWireEventEnvelope(msg.params));
+			} catch {
+				// undeliverable; the next event's seq gap raises it honestly
+			}
 		}
 	}
 
 	/**
 	 * Seq discipline: drop duplicates, deliver contiguous, hold back and heal
 	 * gaps via replay. Events are always delivered in seq order per session.
+	 * The verdicts come from the shared `SeqCursor`; this method owns only what
+	 * a client does about them (queue, replay, deliver).
 	 */
-	private handleEnvelope(envelope: WireEventEnvelope): void {
+	private handleEnvelope(envelope: DecodedWireEventEnvelope): void {
 		const sessionId = envelope.sessionId;
-		const last = this.lastSeq.get(sessionId) ?? 0;
-		if (envelope.seq <= last) return; // duplicate (e.g. replay overlap)
+		// 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)) {
 			this.holdBack(sessionId, envelope);
 			return;
 		}
-		if (envelope.seq === last + 1) {
-			this.deliver(envelope);
-			this.drainHeld(sessionId);
-		} else {
-			this.holdBack(sessionId, envelope);
-			void this.syncSession(sessionId);
+		switch (this.cursor.advance(sessionId, envelope.seq)) {
+			case "duplicate":
+				return; // e.g. a replay overlap
+			case "reset":
+				// Defense-in-depth. Real restarts are detected by the handshake
+				// (`instanceId` at re-initialize) before any envelope flows — this
+				// 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.heldBack.delete(sessionId);
+				this.deliver(envelope);
+				return;
+			case "deliver":
+				this.deliver(envelope);
+				this.drainHeld(sessionId);
+				return;
+			case "gap":
+				this.holdBack(sessionId, envelope);
+				void this.syncSession(sessionId);
+				return;
 		}
 	}
 
-	private holdBack(sessionId: string, envelope: WireEventEnvelope): void {
+	private holdBack(sessionId: string, envelope: DecodedWireEventEnvelope): void {
 		const held = this.heldBack.get(sessionId) ?? [];
 		held.push(envelope);
 		this.heldBack.set(sessionId, held);
@@ -454,13 +538,21 @@ export class AgentServerClient {
 		if (!held?.length) return;
 		held.sort((a, b) => a.seq - b.seq);
 		while (held.length) {
-			const next = held[0] as WireEventEnvelope;
-			const last = this.lastSeq.get(sessionId) ?? 0;
-			if (next.seq <= last) held.shift();
-			else if (next.seq === last + 1) {
-				held.shift();
+			const next = held[0] as DecodedWireEventEnvelope;
+			// `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);
+			if (verdict === "gap") break;
+			held.shift();
+			if (verdict === "reset") {
+				// Defense-in-depth only (see the reset arm in handleEnvelope):
+				// drop the queue, deliver the fresh frame, resync for its tail.
+				held.length = 0;
 				this.deliver(next);
-			} else break;
+				void this.syncSession(sessionId);
+				break;
+			}
+			if (verdict !== "duplicate") this.deliver(next);
 		}
 		if (!held.length) this.heldBack.delete(sessionId);
 	}
@@ -472,7 +564,7 @@ export class AgentServerClient {
 			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++) {
-				const fromSeq = (this.lastSeq.get(sessionId) ?? 0) + 1;
+				const fromSeq = this.cursor.last(sessionId) + 1;
 				try {
 					const replayed = await this.replay(sessionId, fromSeq);
 					if (replayed.firstAvailableSeq !== null && replayed.firstAvailableSeq > fromSeq) {
@@ -484,7 +576,7 @@ export class AgentServerClient {
 								`events ${fromSeq}..${replayed.firstAvailableSeq - 1} for session ${sessionId} were evicted`,
 							),
 						);
-						this.lastSeq.set(sessionId, replayed.firstAvailableSeq - 1);
+						this.cursor.seek(sessionId, replayed.firstAvailableSeq - 1);
 					}
 					for (const envelope of replayed.events) this.holdBack(sessionId, envelope);
 					break;
@@ -494,7 +586,7 @@ export class AgentServerClient {
 							sessionId,
 							new EventGapError(`session ${sessionId} is unknown to the server (restarted?)`),
 						);
-						this.lastSeq.delete(sessionId);
+						this.cursor.reset(sessionId);
 						this.heldBack.delete(sessionId);
 						break;
 					}
@@ -518,8 +610,8 @@ export class AgentServerClient {
 		this.drainHeld(sessionId);
 	}
 
-	private deliver(envelope: WireEventEnvelope): void {
-		this.lastSeq.set(envelope.sessionId, envelope.seq);
+	/** Dispatch an envelope the cursor already accepted (it owns the watermark). */
+	private deliver(envelope: DecodedWireEventEnvelope): void {
 		for (const handler of [...this.eventHandlers]) {
 			try {
 				handler(envelope);
@@ -529,10 +621,11 @@ export class AgentServerClient {
 		}
 		const turn = this.turnBySession.get(envelope.sessionId);
 		if (!turn) return;
-		turn.queue.push(envelope.event);
-		if (envelope.event.type === "turn.ended" && envelope.event.turnId === turn.turnId) {
+		const event = envelope.event;
+		turn.queue.push(event);
+		if (!isUnknownEvent(event) && event.type === "turn.ended" && event.turnId === turn.turnId) {
 			this.turnBySession.delete(envelope.sessionId);
-			turn.resolveResult(envelope.event);
+			turn.resolveResult(event);
 			turn.queue.end();
 		}
 	}

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

@@ -114,6 +114,15 @@ export async function answerPermission(
 	if (!turn?.broker || !asks) return autoDecide(request, turn?.mode);
 	const decision = await turn.broker(permissionToolCall(request), { signal: turn.signal });
 	if (decision.decision === "cancel") return CANCELLED_OUTCOME;
+	// `decision.updatedInput` is unrepresentable here: ACP v1's outcome carries
+	// an optionId and nothing else, so an edited input cannot be honoured — and
+	// silently running the ORIGINAL is exactly what the field exists to prevent.
+	// An edited approval therefore DENIES: the broker authorized a call this
+	// protocol cannot deliver. (The claude-code harness, via canUseTool, is the
+	// one that can execute the edit.)
+	if (decision.decision === "allow" && decision.updatedInput !== undefined) {
+		return chooseOutcome(request.options, false);
+	}
 	return chooseOutcome(request.options, decision.decision === "allow");
 }
 

package/src/core/agents/acp/mappings.ts

@@ -69,7 +69,7 @@ export function toPromptBlocks(input: AgentInput, imagesSupported: boolean): Con
 			blocks.push({ type: "text", text: part.text });
 		} else if (part.type === "image" && imagesSupported) {
 			if (part.data) {
-				blocks.push({ type: "image", data: part.data, mimeType: part.mediaType });
+				blocks.push({ type: "image", data: part.data, mimeType: part.mimeType });
 			} else if (part.url) {
 				blocks.push({ type: "resource_link", uri: part.url, name: part.url });
 			}
@@ -125,8 +125,8 @@ export function autoDecide(
 ): RequestPermissionResponse {
 	const kind = request.toolCall.kind;
 	const allowed =
-		mode === "bypassPermissions" ||
-		(mode === "acceptEdits" && (kind === "edit" || kind === "read"));
+		mode === "bypass_permissions" ||
+		(mode === "accept_edits" && (kind === "edit" || kind === "read"));
 	return chooseOutcome(request.options, allowed);
 }
 

package/src/core/agents/base.ts

@@ -14,7 +14,15 @@ import type {
  * `allow`/`deny`, codex `accept`/`decline`/`cancel`).
  */
 export type PermissionDecision =
-	| { decision: "allow" }
+	| {
+			decision: "allow";
+			/**
+			 * Allow-with-modified-input (`permission.resolved.outcome.updatedInput`):
+			 * the harness MUST execute this input, not the original — what was
+			 * approved is what runs. Absent = the original input was approved as-is.
+			 */
+			updatedInput?: Record<string, unknown>;
+	  }
 	| { decision: "deny"; reason?: string }
 	/** The turn is being cancelled — abort rather than merely skip the tool. */
 	| { decision: "cancel" };