@zvada/agent-server 0.2.1 → 0.3.0

package/src/protocol/verify.ts

@@ -0,0 +1,440 @@
+import { isUnknownEvent } from "./guards.ts";
+import {
+	type DecodedLifecycleEvent,
+	type UnknownEvent,
+	decodeLifecycleEvent,
+} from "./lifecycle.ts";
+import { conversationMessages, emptyConversation, reduceConversation } from "./reduce.ts";
+
+/**
+ * Machine-checkable stream-contract verifier (DeepSeek-harness style: replay
+ * the log, validate the projection, fail nonzero on disagreement).
+ *
+ * `verifyStreamContract` takes one session's ordered event stream and returns
+ * every violation of the PROTOCOL §7 ordering/delivery contract it can detect,
+ * plus a projection check: the reducer's final state must agree with the
+ * authoritative part snapshots (snapshots-beat-deltas made testable).
+ *
+ * Pure and consumer-grade: the CLI's `--verify` flag, the live tests, and any
+ * product pipeline (an agnt DO, deus's cli:backend) can all run it over a
+ * recorded stream.
+ *
+ * The ordering bookkeeping below (turns, open messages, part addresses,
+ * pending permissions) deliberately does NOT read `ConversationState`, even
+ * though the fold at the bottom computes lookalikes of most of it: a checker
+ * derived from the reducer can only ever confirm that the reducer agrees with
+ * itself. The duplication is the independence that makes `projection-agrees`
+ * and the re-delivery probe able to fail.
+ */
+
+export interface ContractViolation {
+	/** Stable rule id, e.g. "echo-first" — grep-able and assertable in tests. */
+	rule: string;
+	/** Index into the supplied event array (-1 for stream-level violations). */
+	index: number;
+	message: string;
+}
+
+export interface VerifyOptions {
+	/**
+	 * The engine always echoes the user message first (spec §7.2). Disable only
+	 * for partial/legacy captures that begin mid-turn.
+	 */
+	expectEcho?: boolean;
+	/** Per-session seq values aligned with `events` (from wire envelopes). */
+	seqs?: number[];
+}
+
+export function verifyStreamContract(
+	events: Array<DecodedLifecycleEvent | UnknownEvent>,
+	options: VerifyOptions = {},
+): ContractViolation[] {
+	const expectEcho = options.expectEcho ?? true;
+	const violations: ContractViolation[] = [];
+	const report = (rule: string, index: number, message: string) => {
+		violations.push({ rule, index, message });
+	};
+
+	// -- validity: every event decodes ------------------------------------------
+	// Via the Law-6 decoder, not the closed union: an unknown event type (or an
+	// unknown part inside a known event) is forward-compat, not a violation —
+	// only a KNOWN type with a malformed body is.
+	events.forEach((event, i) => {
+		try {
+			decodeLifecycleEvent(event);
+		} catch (err) {
+			report(
+				"schema-valid",
+				i,
+				`event ${i} (${String((event as { type?: unknown }).type)}) fails schema: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+		const ts = (event as { timestamp?: unknown }).timestamp;
+		if (typeof ts === "number" && (!Number.isSafeInteger(ts) || ts < 0 || Object.is(ts, -0))) {
+			report("timestamp-valid", i, `event ${i} timestamp ${ts} is not a non-negative safe integer`);
+		}
+	});
+
+	// -- seq monotonicity (when envelopes were supplied) ------------------------
+	if (options.seqs) {
+		for (let i = 1; i < options.seqs.length; i++) {
+			const prev = options.seqs[i - 1] as number;
+			const next = options.seqs[i] as number;
+			if (next <= prev) {
+				report("seq-monotonic", i, `seq ${next} at event ${i} does not increase past ${prev}`);
+			}
+		}
+	}
+
+	// -- turn / message / part bookkeeping --------------------------------------
+	interface TurnState {
+		startedIndex: number;
+		endedIndex?: number;
+		firstMessageChecked: boolean;
+		openMessages: Map<string, number>; // messageId -> started index
+		endedMessages: Set<string>;
+		lastOutputIndex: number;
+	}
+	const turns = new Map<string, TurnState>();
+	/** part.id -> its fixed wire address (message/indices are upsert-stable). */
+	const partAddress = new Map<string, { messageId: string; partIndex: number }>();
+	const messageRole = new Map<string, "user" | "assistant">();
+	const pendingPermissions = new Map<string, number>();
+	const resolvedPermissions = new Set<string>();
+	/**
+	 * Scoped PER TURN, not per stream: the engine re-announces the harness
+	 * session on every turn's first yield (`session.created` is where the native
+	 * id — and `resumed` — becomes knowable), so a multi-turn session legally
+	 * carries one per turn. Two within a single turn is the real violation.
+	 */
+	let sessionCreatedInTurn = 0;
+
+	events.forEach((event, i) => {
+		// Unknown types carry no contract obligations we can check — they are
+		// preserved, not interpreted.
+		if (isUnknownEvent(event)) return;
+		switch (event.type) {
+			case "session.created":
+				sessionCreatedInTurn++;
+				if (sessionCreatedInTurn > 1) {
+					report("session-created-once", i, "session.created emitted twice within one turn");
+				}
+				return;
+			case "turn.started": {
+				sessionCreatedInTurn = 0;
+				if (turns.has(event.turnId)) {
+					report("turn-started-once", i, `turn.started repeated for ${event.turnId}`);
+					return;
+				}
+				turns.set(event.turnId, {
+					startedIndex: i,
+					firstMessageChecked: false,
+					openMessages: new Map(),
+					endedMessages: new Set(),
+					lastOutputIndex: -1,
+				});
+				return;
+			}
+			case "message.started": {
+				const turn = turns.get(event.turnId);
+				if (!turn) {
+					report("message-in-turn", i, `message.started for unknown turn ${event.turnId}`);
+					return;
+				}
+				if (turn.endedIndex !== undefined) {
+					report(
+						"no-messages-after-turn-end",
+						i,
+						`message.started after turn.ended (${event.turnId})`,
+					);
+				}
+				if (!turn.firstMessageChecked) {
+					turn.firstMessageChecked = true;
+					if (expectEcho && (event.role !== "user" || event.outputIndex !== 0)) {
+						report(
+							"echo-first",
+							i,
+							`first message of turn ${event.turnId} is role=${event.role} outputIndex=${event.outputIndex}; expected the user echo at outputIndex 0`,
+						);
+					}
+				}
+				if (event.outputIndex <= turn.lastOutputIndex) {
+					report(
+						"output-index-increases",
+						i,
+						`outputIndex ${event.outputIndex} does not increase past ${turn.lastOutputIndex}`,
+					);
+				}
+				turn.lastOutputIndex = Math.max(turn.lastOutputIndex, event.outputIndex);
+				turn.openMessages.set(event.messageId, i);
+				messageRole.set(event.messageId, event.role);
+				return;
+			}
+			case "message.part": {
+				const known = partAddress.get(event.part.id);
+				if (known) {
+					if (known.messageId !== event.messageId || known.partIndex !== event.partIndex) {
+						report(
+							"part-address-stable",
+							i,
+							`part ${event.part.id} moved from ${known.messageId}#${known.partIndex} to ${event.messageId}#${event.partIndex} — upsert addresses are fixed at first emission`,
+						);
+					}
+				} else {
+					partAddress.set(event.part.id, {
+						messageId: event.messageId,
+						partIndex: event.partIndex,
+					});
+				}
+				// Two distinct failures, two distinct messages: an unaddressable part
+				// and a part that disagrees with its event are different bugs, and a
+				// shared message sends the reader hunting the wrong one.
+				if (event.part.id === "") {
+					report("part-self-describing", i, "part carries an empty id — nothing to upsert by");
+				} else if (event.part.messageId !== event.messageId) {
+					report(
+						"part-self-describing",
+						i,
+						`part ${event.part.id} carries messageId ${event.part.messageId} but the event says ${event.messageId}`,
+					);
+				}
+				// An unknown part type is preserved, never interpreted: the rules
+				// below read a part's KNOWN shape, so they simply don't apply to it.
+				const part = event.part;
+				if ("raw" in part) return;
+				const turn = turns.get(event.turnId);
+				if (turn?.endedIndex !== undefined) {
+					const lateOk =
+						part.type === "tool" &&
+						(part.state.status === "completed" ||
+							part.state.status === "failed" ||
+							part.state.status === "cancelled");
+					if (!lateOk) {
+						report(
+							"late-parts-are-terminal-tools",
+							i,
+							`non-terminal ${part.type} snapshot after turn.ended`,
+						);
+					}
+				}
+				if (
+					expectEcho &&
+					messageRole.get(event.messageId) === "user" &&
+					(part.type === "text" || part.type === "reasoning") &&
+					part.state !== "done"
+				) {
+					report("echo-parts-done", i, "user echo part is not state done");
+				}
+				return;
+			}
+			case "message.part.delta": {
+				if (!partAddress.has(event.partId)) {
+					report(
+						"delta-follows-snapshot",
+						i,
+						`delta for part ${event.partId} arrived before any message.part snapshot`,
+					);
+				}
+				return;
+			}
+			case "message.ended": {
+				const turn = turns.get(event.turnId);
+				if (turn) {
+					if (!turn.openMessages.has(event.messageId) && !turn.endedMessages.has(event.messageId)) {
+						report("bracket-pairing", i, `message.ended for unknown message ${event.messageId}`);
+					}
+					turn.openMessages.delete(event.messageId);
+					turn.endedMessages.add(event.messageId);
+				}
+				return;
+			}
+			case "turn.ended": {
+				const turn = turns.get(event.turnId);
+				if (!turn) {
+					report("turn-ended-pairs", i, `turn.ended for unknown turn ${event.turnId}`);
+					return;
+				}
+				if (turn.endedIndex !== undefined) {
+					report("turn-ended-once", i, `turn.ended repeated for ${event.turnId}`);
+					return;
+				}
+				turn.endedIndex = i;
+				if (turn.openMessages.size > 0) {
+					report(
+						"messages-closed-by-turn-end",
+						i,
+						`turn.ended with ${turn.openMessages.size} unclosed message(s)`,
+					);
+				}
+				if (event.stopReason === "error" && event.error === undefined) {
+					report("error-carries-info", i, "turn.ended stopReason=error without error info");
+				}
+				return;
+			}
+			case "permission.requested":
+				pendingPermissions.set(event.requestId, i);
+				return;
+			case "permission.resolved":
+				if (resolvedPermissions.has(event.requestId)) {
+					report("permission-resolves-once", i, `permission ${event.requestId} resolved twice`);
+				}
+				resolvedPermissions.add(event.requestId);
+				pendingPermissions.delete(event.requestId);
+				return;
+			default:
+				return;
+		}
+	});
+
+	for (const [turnId, turn] of turns) {
+		if (turn.endedIndex === undefined) {
+			report("turn-ended-pairs", turn.startedIndex, `turn ${turnId} never ended`);
+		}
+	}
+	for (const [requestId, index] of pendingPermissions) {
+		report("permission-resolves-once", index, `permission ${requestId} never resolved`);
+	}
+
+	// -- projection agreement: reducer state ≡ authoritative snapshots ----------
+	// (DeepSeek's "projection and storage must not disagree", for our fold.)
+	/** part.id -> its last full snapshot and where in the stream it landed. */
+	const lastSnapshot = new Map<
+		string,
+		{ event: DecodedLifecycleEvent & { type: "message.part" }; index: number }
+	>();
+	/** part.id -> index of the last text/reasoning delta (tool_input never folds into text). */
+	const lastTextDelta = new Map<string, number>();
+	events.forEach((event, i) => {
+		if (isUnknownEvent(event)) return;
+		if (event.type === "message.part") lastSnapshot.set(event.part.id, { event, index: i });
+		else if (event.type === "message.part.delta" && event.delta.type !== "tool_input") {
+			lastTextDelta.set(event.partId, i);
+		}
+	});
+	let state = emptyConversation();
+	try {
+		for (const event of events) state = reduceConversation(state, event);
+	} catch (err) {
+		report(
+			"reducer-total",
+			-1,
+			`reduceConversation threw: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		return violations;
+	}
+	// The fold closes in-flight tools on EVERY terminal turn.ended (not only
+	// cancels): an ended turn's dangling tool legitimately reduces to
+	// `cancelled` with no snapshot saying so.
+	const endedTurns = new Set(state.turns.filter((t) => t.status === "ended").map((t) => t.turnId));
+	for (const message of conversationMessages(state)) {
+		for (const part of message.parts) {
+			if ("raw" in part) continue;
+			const source = lastSnapshot.get(part.id);
+			const snapshot = source?.event.part;
+			if (!snapshot) {
+				report("projection-agrees", -1, `reduced part ${part.id} has no source snapshot`);
+				continue;
+			}
+			if ("raw" in snapshot) continue; // preserved, not interpreted (Law 6)
+			if (
+				(part.type === "text" || part.type === "reasoning") &&
+				(snapshot.type === "text" || snapshot.type === "reasoning")
+			) {
+				// Deltas that arrive AFTER the last snapshot legitimately extend it —
+				// that is the shipped fold ("appends later deltas onto the replacement
+				// snapshot"), and it is how EVERY cancelled turn ends: trailing deltas
+				// with no closing `content_block_stop` to snapshot them. Authority
+				// still bites: the snapshot must be a PREFIX of what the fold holds.
+				const extended = (lastTextDelta.get(part.id) ?? -1) > (source?.index ?? -1);
+				const agrees = extended ? part.text.startsWith(snapshot.text) : part.text === snapshot.text;
+				if (!agrees) {
+					report(
+						"projection-agrees",
+						-1,
+						extended
+							? `part ${part.id} reduced text (${part.text.length} chars) does not extend its last snapshot (${snapshot.text.length} chars) — later deltas may only append`
+							: `part ${part.id} reduced text (${part.text.length} chars) != last snapshot (${snapshot.text.length} chars) — snapshots must be authoritative`,
+					);
+				}
+			}
+			if (part.type === "tool" && snapshot.type === "tool") {
+				const closedByTurnEnd =
+					endedTurns.has(message.turnId) &&
+					part.state.status === "cancelled" &&
+					(snapshot.state.status === "pending" || snapshot.state.status === "in_progress");
+				if (part.state.status !== snapshot.state.status && !closedByTurnEnd) {
+					report(
+						"projection-agrees",
+						-1,
+						`tool ${part.id} reduced status ${part.state.status} != snapshot ${snapshot.state.status}`,
+					);
+				}
+			}
+		}
+	}
+
+	// -- re-delivery idempotency ------------------------------------------------
+	// The wire redelivers: a replay overlap or a reconnect resync hands the same
+	// event to the fold twice. Folding a stream in which every event WITH
+	// history is duplicated must land on the same state as folding it once —
+	// otherwise a reconnect silently doubles a part, a token bill, or an answer.
+	// (Refolding the identical sequence, which this check used to do, cannot
+	// fail: the reducer is a pure function of its arguments.)
+	const withDuplicates: Array<DecodedLifecycleEvent | UnknownEvent> = [];
+	for (const event of events) {
+		withDuplicates.push(event);
+		if (
+			event.type === "message.part" ||
+			event.type === "turn.ended" ||
+			event.type === "permission.resolved"
+		) {
+			withDuplicates.push(event);
+		}
+	}
+	let redelivered = emptyConversation();
+	try {
+		for (const event of withDuplicates) redelivered = reduceConversation(redelivered, event);
+	} catch (err) {
+		report(
+			"reducer-total",
+			-1,
+			`reduceConversation threw on re-delivery: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		return violations;
+	}
+	const partCounts = (s: typeof state) =>
+		new Map(conversationMessages(s).map((m) => [m.messageId, m.parts.length] as const));
+	const outcomes = (s: typeof state) =>
+		new Map(s.permissions.map((p) => [p.requestId, JSON.stringify(p.outcome)] as const));
+	const idempotent = (message: string) => report("reducer-idempotent", -1, message);
+	if (redelivered.timeline.length !== state.timeline.length) {
+		idempotent(
+			`re-delivering upserts changed the timeline (${state.timeline.length} -> ${redelivered.timeline.length} entries)`,
+		);
+	}
+	const once = partCounts(state);
+	for (const [messageId, count] of partCounts(redelivered)) {
+		if (once.get(messageId) !== count) {
+			idempotent(
+				`re-delivering upserts changed message ${messageId}'s part count (${once.get(messageId)} -> ${count})`,
+			);
+		}
+	}
+	const resolvedOnce = outcomes(state);
+	for (const [requestId, outcome] of outcomes(redelivered)) {
+		if (resolvedOnce.get(requestId) !== outcome) {
+			idempotent(`re-delivering changed permission ${requestId}'s outcome`);
+		}
+	}
+	if (JSON.stringify(redelivered.totals) !== JSON.stringify(state.totals)) {
+		idempotent("re-delivering turn.ended double-counted the billing totals");
+	}
+
+	return violations;
+}
+
+/** Render violations for terminal output; empty string when clean. */
+export function formatViolations(violations: ContractViolation[]): string {
+	if (violations.length === 0) return "";
+	return violations.map((v) => `  [${v.rule}] #${v.index}: ${v.message}`).join("\n");
+}

package/src/protocol/vocabulary.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+/**
+ * Law 3 — an OPEN vocabulary. The schema accepts values this build does not
+ * know (a newer engine's `stopReason`, an adapter's `_`-prefixed extension),
+ * because rejecting them is exactly how a forward-compatible wire turns into a
+ * compatibility break — the failure ACP moved to v2 to escape. The cast keeps
+ * the TypeScript side as `"a" | "b" | (string & {})`, so the canonical members
+ * still autocomplete and still get checked by the casing test (Law 9), while
+ * the runtime lets an unknown value through to be preserved.
+ *
+ * Blank is the one thing every open vocabulary rejects: `""` and `"   "` are
+ * not values a consumer can switch on, render, or persist — they are a
+ * producer bug, and accepting them silently is how it reaches a UI.
+ */
+export function openVocabulary<T extends string>(): z.ZodType<T> {
+	return z.string().min(1).regex(/\S/, "must not be blank") as unknown as z.ZodType<T>;
+}

package/src/protocol/wire.ts

@@ -1,7 +1,13 @@
 import { z } from "zod";
 import { RunConfigSchema } from "./config.ts";
 import { AgentCapabilitiesSchema } from "./harness.ts";
-import { LifecycleEventSchema, PermissionOutcomeSchema } from "./lifecycle.ts";
+import {
+	type DecodedLifecycleEvent,
+	LifecycleEventSchema,
+	PermissionOutcomeSchema,
+	type UnknownEvent,
+	decodeLifecycleEvent,
+} from "./lifecycle.ts";
 import { AgentInputSchema } from "./part-input.ts";
 
 /**
@@ -12,7 +18,7 @@ import { AgentInputSchema } from "./part-input.ts";
  * via the `turn.ended` lifecycle event, mirroring the engine's event-driven
  * model (and ACP v2's prompt lifecycle).
  */
-export const WIRE_PROTOCOL_VERSION = 1;
+export const WIRE_PROTOCOL_VERSION = 2;
 
 // ---- JSON-RPC 2.0 envelopes --------------------------------------------------
 
@@ -45,6 +51,8 @@ export const WIRE_ERROR_CODES = {
 	protocolVersionMismatch: -32004,
 	/** A session/close for this session is still in flight; retry after it settles. */
 	sessionClosing: -32005,
+	/** A turn with this turnId already ran (or is running) with DIFFERENT input. */
+	turnConflict: -32006,
 } as const;
 
 // ---- methods -----------------------------------------------------------------
@@ -77,6 +85,14 @@ export type InitializeParams = z.infer<typeof InitializeParamsSchema>;
 export const InitializeResultSchema = z.object({
 	protocolVersion: z.number().int().positive(),
 	server: WireImplementationInfoSchema,
+	/**
+	 * Minted once per server PROCESS. A reconnecting client re-initializes and
+	 * compares: a changed id means every session log it was tracking belongs to
+	 * a dead process — adopt the fresh logs (reset cursors, resync) instead of
+	 * inferring the restart from seq patterns. The handshake STATES the one
+	 * fact four downstream heuristics used to guess.
+	 */
+	instanceId: z.string(),
 	/** Capabilities per registered harness — only available harnesses appear. */
 	harnesses: z.record(z.string(), AgentCapabilitiesSchema),
 });
@@ -89,8 +105,8 @@ export type InitializeResult = z.infer<typeof InitializeResultSchema>;
  * arrive before the ack's promise continuation runs.)
  */
 export const TurnStartParamsSchema = z.object({
-	sessionId: z.string().optional(),
-	turnId: z.string().optional(),
+	sessionId: z.string().min(1).optional(),
+	turnId: z.string().min(1).optional(),
 	input: AgentInputSchema,
 	config: RunConfigSchema,
 });
@@ -100,14 +116,42 @@ export type TurnStartParams = z.infer<typeof TurnStartParamsSchema>;
 export const TurnStartResultSchema = z.object({
 	sessionId: z.string(),
 	turnId: z.string(),
+	/**
+	 * The request converged onto an already-admitted turn with the same turnId
+	 * and identical input (a retried `turn/start` after a lost ack). No second
+	 * execution happened; catch up on its events via `events/replay`.
+	 */
+	deduplicated: z.boolean().optional(),
 });
 export type TurnStartResult = z.infer<typeof TurnStartResultSchema>;
 
-export const TurnCancelParamsSchema = z.object({ sessionId: z.string() });
+export const TurnCancelParamsSchema = z.object({
+	sessionId: z.string().min(1),
+	/**
+	 * Cancel only if THIS turn is the active one — a late cancel meant for a
+	 * finished turn must not kill its successor. Omitted = session-scoped
+	 * cancel of whatever is active (legacy behavior). Empty ids are rejected
+	 * rather than silently treated as unstamped.
+	 */
+	turnId: z.string().min(1).optional(),
+});
 export type TurnCancelParams = z.infer<typeof TurnCancelParamsSchema>;
 
-/** `cancelled: false` means the session had no active turn (idempotent). */
-export const TurnCancelResultSchema = z.object({ cancelled: z.boolean() });
+/**
+ * Single-outcome cancel result (replaces the 0.2 two-boolean shape whose
+ * combinations included illegal states):
+ *  - `cancelled`      — the harness confirmed the interrupt.
+ *  - `unconfirmed`    — best-effort dispatched but unacknowledged; the agent
+ *    process may still be running and the turn's `turn.ended` remains the
+ *    source of truth.
+ *  - `no_active_turn` — nothing to cancel: the session had no active turn, or
+ *    `turnId` was given and a DIFFERENT turn is active (see `activeTurnId`).
+ */
+export const TurnCancelResultSchema = z.discriminatedUnion("outcome", [
+	z.object({ outcome: z.literal("cancelled"), turnId: z.string() }),
+	z.object({ outcome: z.literal("unconfirmed"), turnId: z.string() }),
+	z.object({ outcome: z.literal("no_active_turn"), activeTurnId: z.string().optional() }),
+]);
 export type TurnCancelResult = z.infer<typeof TurnCancelResultSchema>;
 
 export const SessionCloseParamsSchema = z.object({ sessionId: z.string() });
@@ -141,6 +185,58 @@ export const WireEventEnvelopeSchema = z.object({
 });
 export type WireEventEnvelope = z.infer<typeof WireEventEnvelopeSchema>;
 
+/** The routing fields of an envelope — strict, because the wire owns them. */
+const WireEventEnvelopeHeaderSchema = z.object({
+	sessionId: z.string(),
+	seq: z.number().int().positive(),
+});
+
+/** An envelope whose event was decoded the Law-6 way (unknowns preserved). */
+export interface DecodedWireEventEnvelope {
+	sessionId: string;
+	seq: number;
+	event: DecodedLifecycleEvent | UnknownEvent;
+}
+
+/**
+ * Decode one `event` notification: envelope strict, event lenient. A consumer
+ * that instead drops an unknown event type does not degrade gracefully — it
+ * leaves a hole where a `seq` was, and every seq-tracking client then reads
+ * the next event as an unfillable gap.
+ */
+export function decodeWireEventEnvelope(value: unknown): DecodedWireEventEnvelope {
+	const header = WireEventEnvelopeHeaderSchema.parse(value);
+	return {
+		sessionId: header.sessionId,
+		seq: header.seq,
+		event: decodeLifecycleEvent((value as { event?: unknown }).event),
+	};
+}
+
+/** `events/replay` with its envelopes decoded leniently. */
+export interface DecodedEventsReplayResult {
+	events: DecodedWireEventEnvelope[];
+	firstAvailableSeq: number | null;
+	latestSeq: number | null;
+}
+
+/**
+ * The replay result, decoded envelope-by-envelope. `EventsReplayResultSchema`
+ * embeds the CLOSED event union, so parsing a buffer with it makes one unknown
+ * event type poison the whole replay — the healing path for a gap must not be
+ * the thing that cannot survive an unknown.
+ */
+export function decodeEventsReplayResult(value: unknown): DecodedEventsReplayResult {
+	const parsed = z
+		.object({
+			events: z.array(z.unknown()),
+			firstAvailableSeq: z.number().int().positive().nullable(),
+			latestSeq: z.number().int().positive().nullable(),
+		})
+		.parse(value);
+	return { ...parsed, events: parsed.events.map((event) => decodeWireEventEnvelope(event)) };
+}
+
 export const EventsReplayParamsSchema = z.object({
 	sessionId: z.string(),
 	/** Replay buffered events with `seq >= fromSeq`. */

package/src/server/acp/binding.ts

@@ -2,6 +2,7 @@ import { Readable, Writable } from "node:stream";
 import type {
 	AgentApp,
 	AgentConnection,
+	PromptResponse,
 	RequestPermissionResponse,
 } from "@agentclientprotocol/sdk";
 import type { AgentRuntime, EventSink } from "../../core/index.ts";
@@ -143,10 +144,30 @@ export async function createAcpAgentApp(options: AcpBindingOptions): Promise<Age
 				},
 				sink,
 			);
+			// ACP v1's StopReason set is closed and has no `error` member. Map our
+			// open stopReason onto it: `error` reports as an ended turn with the
+			// failure in `_meta` (an ACP client must see a stop, not a JSON-RPC
+			// failure), and extension/unknown values fall back to `end_turn`.
+			const acpStopReasons = new Set([
+				"end_turn",
+				"max_tokens",
+				"max_turn_requests",
+				"refusal",
+				"cancelled",
+			]);
 			if (summary.stopReason === "error") {
-				throw new Error(summary.error?.message ?? "turn failed");
+				return {
+					stopReason: "end_turn",
+					_meta: {
+						"zvada.dev/error": summary.error ?? { category: "internal", message: "turn failed" },
+					},
+				} as PromptResponse;
 			}
-			return { stopReason: summary.stopReason };
+			return {
+				stopReason: (acpStopReasons.has(summary.stopReason)
+					? summary.stopReason
+					: "end_turn") as PromptResponse["stopReason"],
+			};
 		});
 }