@zvada/agent-server 0.2.0

package/src/server/agent-server.ts

@@ -0,0 +1,357 @@
+import { type AgentRuntime, callbackSink } from "../core/index.ts";
+import {
+	type AgentCapabilities,
+	type AgentHarness,
+	EventsReplayParamsSchema,
+	InitializeParamsSchema,
+	type InitializeResult,
+	type JsonRpcId,
+	PermissionRespondParamsSchema,
+	type RunRequest,
+	SessionCloseParamsSchema,
+	TurnCancelParamsSchema,
+	TurnStartParamsSchema,
+	WIRE_ERROR_CODES,
+	WIRE_METHODS,
+	WIRE_PROTOCOL_VERSION,
+	type WireEventEnvelope,
+	type WireImplementationInfo,
+	type WireTransport,
+	decodeWireMessage,
+	encodeErrorResponse,
+	encodeNotification,
+	encodeResponse,
+	generateUUIDv7,
+} from "../protocol/index.ts";
+import { DEFAULT_BUFFER_SIZE, SessionLog } from "./session-log.ts";
+
+/** Structural slice of a ZodError — keeps zod out of this package's deps. */
+interface ValidationError {
+	issues: ReadonlyArray<{ path: ReadonlyArray<PropertyKey>; message: string }>;
+}
+
+export interface AgentServerOptions {
+	/** Replay ring-buffer size per session (envelopes). */
+	bufferSize?: number;
+	/** Reported in the `initialize` result. */
+	info?: WireImplementationInfo;
+	/** Called once a `shutdown` request has been acked and the runtime drained. */
+	onShutdown?: () => void;
+}
+
+/**
+ * The wire binding (phase 2): serves the engine over JSON-RPC 2.0 on any
+ * number of attached transports. Requests flow client -> server only; every
+ * lifecycle event is stamped with a per-session monotonic `seq`, buffered for
+ * `events/replay`, and broadcast to all attached transports as an `event`
+ * notification. `turn/start` is quick-ack: the response only accepts the turn;
+ * completion is the `turn.ended` event. One active turn per session.
+ */
+export class AgentServer {
+	private readonly transports = new Set<WireTransport>();
+	private readonly sessions = new Map<string, SessionLog>();
+	private readonly activeTurns = new Map<string, { turnId: string; harness: AgentHarness }>();
+	private readonly closingSessions = new Set<string>();
+	/** Last assigned seq of closed sessions, so a reused id continues
+	 * monotonically. Memory: one number per closed-and-never-reused session id —
+	 * unbounded only across a server lifetime with unbounded distinct ids, the
+	 * same order of growth already accepted for `sessions`. */
+	private readonly retiredSeqs = new Map<string, number>();
+	private shuttingDown = false;
+
+	constructor(
+		private readonly runtime: AgentRuntime,
+		private readonly options: AgentServerOptions = {},
+	) {}
+
+	/** Serve the wire on a transport; returns a detach function. */
+	attach(transport: WireTransport): () => void {
+		this.transports.add(transport);
+		const offLine = transport.onLine((line) => void this.handleLine(transport, line));
+		const detach = () => {
+			offLine();
+			this.transports.delete(transport);
+		};
+		transport.onClose(detach);
+		return detach;
+	}
+
+	/** Cancel all turns, terminate harnesses, and close every transport. */
+	async shutdown(): Promise<void> {
+		if (this.shuttingDown) return;
+		this.shuttingDown = true;
+		// Drain first so cancelled turns still broadcast their turn.ended.
+		await this.runtime.shutdown();
+		for (const transport of [...this.transports]) transport.close();
+		this.options.onShutdown?.();
+	}
+
+	private async handleLine(transport: WireTransport, line: string): Promise<void> {
+		if (!line.trim()) return;
+		const msg = decodeWireMessage(line);
+		if (msg.kind === "invalid") {
+			transport.send(encodeErrorResponse(null, WIRE_ERROR_CODES.parseError, msg.error));
+			return;
+		}
+		// Clients only send requests on this wire; stray notifications/responses
+		// are tolerated and dropped.
+		if (msg.kind !== "request") return;
+		try {
+			await this.handleRequest(transport, msg.id, msg.method, msg.params);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			transport.send(encodeErrorResponse(msg.id, WIRE_ERROR_CODES.internalError, message));
+		}
+	}
+
+	private async handleRequest(
+		transport: WireTransport,
+		id: JsonRpcId,
+		method: string,
+		params: unknown,
+	): Promise<void> {
+		switch (method) {
+			case WIRE_METHODS.initialize: {
+				const parsed = InitializeParamsSchema.safeParse(params ?? {});
+				if (!parsed.success) return this.invalidParams(transport, id, parsed.error);
+				if (parsed.data.protocolVersion !== WIRE_PROTOCOL_VERSION) {
+					return transport.send(
+						encodeErrorResponse(
+							id,
+							WIRE_ERROR_CODES.protocolVersionMismatch,
+							`unsupported protocol version: ${parsed.data.protocolVersion}`,
+							{ supported: [WIRE_PROTOCOL_VERSION] },
+						),
+					);
+				}
+				const harnesses: Record<string, AgentCapabilities> = {};
+				for (const harness of this.runtime.harnesses) {
+					harnesses[harness] = this.runtime.capabilities(harness);
+				}
+				const result: InitializeResult = {
+					protocolVersion: WIRE_PROTOCOL_VERSION,
+					server: this.options.info ?? { name: "agent-server" },
+					harnesses,
+				};
+				return transport.send(encodeResponse(id, result));
+			}
+
+			case WIRE_METHODS.turnStart: {
+				const parsed = TurnStartParamsSchema.safeParse(params);
+				if (!parsed.success) return this.invalidParams(transport, id, parsed.error);
+				if (this.shuttingDown) {
+					return transport.send(
+						encodeErrorResponse(id, WIRE_ERROR_CODES.shuttingDown, "server is shutting down"),
+					);
+				}
+				const { config, input } = parsed.data;
+				if (!this.runtime.harnesses.includes(config.harness)) {
+					return transport.send(
+						encodeErrorResponse(
+							id,
+							WIRE_ERROR_CODES.harnessNotAvailable,
+							`harness not available: ${config.harness}`,
+							{ available: this.runtime.harnesses },
+						),
+					);
+				}
+				const sessionId = parsed.data.sessionId ?? generateUUIDv7();
+				const turnId = parsed.data.turnId ?? generateUUIDv7();
+				if (this.closingSessions.has(sessionId)) {
+					return transport.send(
+						encodeErrorResponse(
+							id,
+							WIRE_ERROR_CODES.sessionClosing,
+							`session ${sessionId} is closing`,
+						),
+					);
+				}
+				const existing = this.sessions.get(sessionId);
+				if (existing && existing.harness !== config.harness) {
+					return transport.send(
+						encodeErrorResponse(
+							id,
+							WIRE_ERROR_CODES.invalidParams,
+							`session ${sessionId} is bound to harness ${existing.harness}`,
+						),
+					);
+				}
+				if (this.activeTurns.has(sessionId)) {
+					return transport.send(
+						encodeErrorResponse(
+							id,
+							WIRE_ERROR_CODES.turnActive,
+							`session ${sessionId} already has an active turn`,
+							{ turnId: this.activeTurns.get(sessionId)?.turnId },
+						),
+					);
+				}
+				const log =
+					existing ??
+					new SessionLog(
+						sessionId,
+						config.harness,
+						this.options.bufferSize ?? DEFAULT_BUFFER_SIZE,
+						(this.retiredSeqs.get(sessionId) ?? 0) + 1,
+					);
+				this.retiredSeqs.delete(sessionId);
+				this.sessions.set(sessionId, log);
+				this.activeTurns.set(sessionId, { turnId, harness: config.harness });
+				// Quick-ack before the first event can possibly be emitted.
+				transport.send(encodeResponse(id, { sessionId, turnId }));
+				void this.executeTurn({ sessionId, turnId, input, config }, log);
+				return;
+			}
+
+			case WIRE_METHODS.turnCancel: {
+				const parsed = TurnCancelParamsSchema.safeParse(params);
+				if (!parsed.success) return this.invalidParams(transport, id, parsed.error);
+				const active = this.activeTurns.get(parsed.data.sessionId);
+				if (!active) return transport.send(encodeResponse(id, { cancelled: false }));
+				await this.runtime.cancel(active.harness, parsed.data.sessionId);
+				return transport.send(encodeResponse(id, { cancelled: true }));
+			}
+
+			case WIRE_METHODS.sessionClose: {
+				const parsed = SessionCloseParamsSchema.safeParse(params);
+				if (!parsed.success) return this.invalidParams(transport, id, parsed.error);
+				const { sessionId } = parsed.data;
+				if (this.closingSessions.has(sessionId)) {
+					return transport.send(
+						encodeErrorResponse(
+							id,
+							WIRE_ERROR_CODES.sessionClosing,
+							`session ${sessionId} is closing`,
+						),
+					);
+				}
+				const active = this.activeTurns.get(sessionId);
+				if (active) {
+					return transport.send(
+						encodeErrorResponse(
+							id,
+							WIRE_ERROR_CODES.turnActive,
+							`session ${sessionId} has an active turn`,
+							{ turnId: active.turnId },
+						),
+					);
+				}
+				const log = this.sessions.get(sessionId);
+				if (!log) return transport.send(encodeResponse(id, { closed: false }));
+				this.closingSessions.add(sessionId);
+				try {
+					await this.runtime.closeSession(log.harness, sessionId);
+					if (log.latestSeq !== null) this.retiredSeqs.set(sessionId, log.latestSeq);
+					if (this.sessions.get(sessionId) === log) this.sessions.delete(sessionId);
+					return transport.send(encodeResponse(id, { closed: true }));
+				} finally {
+					this.closingSessions.delete(sessionId);
+				}
+			}
+
+			case WIRE_METHODS.permissionRespond: {
+				const parsed = PermissionRespondParamsSchema.safeParse(params);
+				if (!parsed.success) return this.invalidParams(transport, id, parsed.error);
+				const accepted = this.runtime.respondPermission(
+					parsed.data.sessionId,
+					parsed.data.requestId,
+					parsed.data.outcome,
+				);
+				return transport.send(encodeResponse(id, { accepted }));
+			}
+
+			case WIRE_METHODS.eventsReplay: {
+				const parsed = EventsReplayParamsSchema.safeParse(params);
+				if (!parsed.success) return this.invalidParams(transport, id, parsed.error);
+				const log = this.sessions.get(parsed.data.sessionId);
+				if (!log) {
+					return transport.send(
+						encodeErrorResponse(
+							id,
+							WIRE_ERROR_CODES.unknownSession,
+							`unknown session: ${parsed.data.sessionId}`,
+						),
+					);
+				}
+				return transport.send(
+					encodeResponse(id, {
+						events: log.replay(parsed.data.fromSeq),
+						firstAvailableSeq: log.firstAvailableSeq,
+						latestSeq: log.latestSeq,
+					}),
+				);
+			}
+
+			case WIRE_METHODS.shutdown: {
+				transport.send(encodeResponse(id, {}));
+				await this.shutdown();
+				return;
+			}
+
+			default:
+				return transport.send(
+					encodeErrorResponse(id, WIRE_ERROR_CODES.methodNotFound, `unknown method: ${method}`),
+				);
+		}
+	}
+
+	private async executeTurn(request: RunRequest, log: SessionLog): Promise<void> {
+		// Only release the busy mark if it still belongs to THIS turn — a newer
+		// turn may have been accepted between our turn.ended broadcast and run()
+		// settling, and its lock must survive our cleanup.
+		const releaseTurn = () => {
+			if (this.activeTurns.get(request.sessionId)?.turnId === request.turnId) {
+				this.activeTurns.delete(request.sessionId);
+			}
+		};
+		const sink = callbackSink((event) => {
+			// Once turn.ended is on the wire the session is idle — clear the busy
+			// mark here (not when run() settles) so clients acting on the event
+			// never race the bookkeeping.
+			if (event.type === "turn.ended") releaseTurn();
+			this.broadcast(log.append(event));
+		});
+		try {
+			await this.runtime.run(request, sink);
+		} catch (err) {
+			// runtime.run reports errors via events; a throw means it died before
+			// emitting turn.ended — synthesize one so clients are never left hanging.
+			const message = err instanceof Error ? err.message : String(err);
+			this.broadcast(
+				log.append({
+					type: "turn.ended",
+					sessionId: request.sessionId,
+					turnId: request.turnId,
+					stopReason: "error",
+					error: { name: err instanceof Error ? err.name : "Error", message },
+					timestamp: Date.now(),
+				}),
+			);
+		} finally {
+			releaseTurn();
+		}
+	}
+
+	private broadcast(envelope: WireEventEnvelope): void {
+		const line = encodeNotification(WIRE_METHODS.event, envelope);
+		for (const transport of this.transports) {
+			try {
+				transport.send(line);
+			} catch {
+				// One faulty transport must not starve the others; the event is
+				// already in the session log, so the client heals via replay.
+			}
+		}
+	}
+
+	private invalidParams(transport: WireTransport, id: JsonRpcId, error: ValidationError): void {
+		transport.send(
+			encodeErrorResponse(
+				id,
+				WIRE_ERROR_CODES.invalidParams,
+				"invalid params",
+				error.issues.map((i) => ({ path: i.path.join("."), message: i.message })),
+			),
+		);
+	}
+}

package/src/server/bin.ts

@@ -0,0 +1,174 @@
+#!/usr/bin/env bun
+// agent-server — run the engine as a standalone wire server.
+//
+//   agent-server                      # NDJSON JSON-RPC over stdio (default)
+//   agent-server --listen 4747       # accept WebSocket clients on a port
+//   agent-server --dial ws://host/p  # dial out to a consumer and reconnect
+//   agent-server --harness a,b       # restrict registered harnesses
+//   agent-server --acp-agent "npx -y pi-acp"  # enable the acp harness
+//   agent-server --acp --harness claude-code  # BE an ACP agent on stdio (for Zed etc.)
+//   agent-server --buffer 8192       # replay buffer size per session
+//   agent-server install             # prefetch the pinned agent CLIs
+//
+// All logs go to stderr; stdout is reserved for the wire in stdio mode.
+import {
+	KNOWN_ACP_AGENTS,
+	type ProvisionMode,
+	createAgentRuntime,
+	resolveAcpLaunch,
+} from "../core/index.ts";
+import { isAgentHarness } from "../protocol/index.ts";
+import { AgentServer } from "./agent-server.ts";
+import { runInstall } from "./install.ts";
+import { dial, listen, stdioTransport } from "./transports.ts";
+
+const VERSION = "0.1.0";
+
+interface Args {
+	command: "serve" | "install";
+	mode: "stdio" | "listen" | "dial" | "acp";
+	listen?: { hostname?: string; port: number };
+	dialUrl?: string;
+	harnesses?: string[];
+	acpAgent?: string;
+	bufferSize?: number;
+	provisionMode?: ProvisionMode;
+}
+
+function usage(exitCode: number): never {
+	console.error(
+		[
+			"usage: agent-server [install] [--listen [host:]port | --dial <ws-url>] [options]",
+			"",
+			"  (default)              serve NDJSON JSON-RPC on stdio",
+			"  --acp                  speak ACP v1 on stdio instead (be the agent)",
+			"  install                download the pinned agent CLIs into the managed cache",
+			"                         (always downloads — run at image build time to erase",
+			"                         sandbox cold starts; --provision applies to serving only)",
+			"  --listen [host:]port   accept WebSocket clients",
+			"  --dial <ws-url>        dial out to a consumer (auto-reconnect)",
+			"  --harness <a,b>        restrict harnesses (default: all installed)",
+			"  --provision <mode>     CLI provisioning: auto | pinned | system (default auto)",
+			"  --buffer <n>           replay buffer size per session (default 4096)",
+			"  --version, --help",
+			"",
+			"env: CLAUDE_CLI_PATH / CODEX_CLI_PATH (explicit binaries),",
+			"     AGENT_SERVER_PROVISION, AGENT_SERVER_CACHE_DIR, AGENT_SERVER_NPM_REGISTRY",
+		].join("\n"),
+	);
+	process.exit(exitCode);
+}
+
+function parseArgs(argv: string[]): Args {
+	const args: Args = { command: "serve", mode: "stdio" };
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i] as string;
+		const next = () => {
+			const v = argv[++i];
+			if (v === undefined) usage(1);
+			return v;
+		};
+		if (arg === "install" && i === 0) args.command = "install";
+		else if (arg === "--stdio") args.mode = "stdio";
+		else if (arg === "--acp") args.mode = "acp";
+		else if (arg === "--listen") {
+			args.mode = "listen";
+			const [a, b] = next().split(":");
+			args.listen = b !== undefined ? { hostname: a, port: Number(b) } : { port: Number(a) };
+			if (!Number.isInteger(args.listen.port)) usage(1);
+		} else if (arg === "--dial") {
+			args.mode = "dial";
+			args.dialUrl = next();
+		} else if (arg === "--harness") args.harnesses = next().split(",").filter(Boolean);
+		else if (arg === "--provision") {
+			const mode = next();
+			if (mode !== "auto" && mode !== "pinned" && mode !== "system") usage(1);
+			args.provisionMode = mode;
+		} else if (arg === "--buffer") {
+			args.bufferSize = Number(next());
+			if (!Number.isInteger(args.bufferSize) || args.bufferSize <= 0) usage(1);
+		} else if (arg === "--version") {
+			console.log(VERSION);
+			process.exit(0);
+		} else if (arg === "--help") usage(0);
+		else usage(1);
+	}
+	return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+const harnesses = args.harnesses?.map((h) => {
+	if (isAgentHarness(h)) return h;
+	if (KNOWN_ACP_AGENTS[h]) {
+		// Friendly ACP agent names ("pi", "gemini") ride the acp harness.
+		args.acpAgent ??= h;
+		return "acp" as const;
+	}
+	console.error(`unknown harness: ${h}`);
+	process.exit(1);
+});
+const provision = args.provisionMode ? { mode: args.provisionMode } : {};
+const acpLaunch = resolveAcpLaunch(args.acpAgent ?? process.env.AGENT_SERVER_ACP_AGENT);
+if (harnesses?.includes("acp") && !acpLaunch) {
+	console.error('the acp harness needs an agent: --harness pi|gemini or --acp-agent "<spec>"');
+	process.exit(1);
+}
+
+if (args.command === "install") {
+	try {
+		// install always downloads to the managed cache; --provision (a serving
+		// concern) is deliberately not forwarded.
+		const results = await runInstall({ harnesses });
+		for (const { tool, cli } of results) {
+			console.error(`${tool} ${cli.version ?? ""} ready: ${cli.path} (${cli.source})`);
+		}
+		process.exit(0);
+	} catch (error) {
+		console.error(`install failed: ${error instanceof Error ? error.message : String(error)}`);
+		process.exit(1);
+	}
+}
+
+const runtime = createAgentRuntime({
+	...(harnesses ? { harnesses } : {}),
+	...(acpLaunch ? { acp: { resolveLaunch: () => acpLaunch } } : {}),
+	provision,
+});
+
+let shutdown: () => void;
+if (args.mode === "acp") {
+	// Speak ACP v1 on stdio: this process IS the agent (Zed-spawnable).
+	const { serveAcpStdio } = await import("./acp/binding.ts");
+	const frontedHarness = harnesses?.[0] ?? "claude-code";
+	const connection = await serveAcpStdio({ runtime, harness: frontedHarness, version: VERSION });
+	console.error(`agent-server ${VERSION} speaking ACP v1 on stdio (harness: ${frontedHarness})`);
+	shutdown = () => void runtime.shutdown().then(() => process.exit(0));
+	// Client hung up — shut down cleanly (mirrors the stdio wire transport).
+	void connection.closed.then(() => shutdown());
+} else {
+	const server = new AgentServer(runtime, {
+		bufferSize: args.bufferSize,
+		info: { name: "agent-server", version: VERSION },
+		onShutdown: () => process.exit(0),
+	});
+	shutdown = () => void server.shutdown();
+
+	if (args.mode === "listen") {
+		const bound = listen(server, args.listen);
+		console.error(`agent-server ${VERSION} listening on ${bound.url}`);
+	} else if (args.mode === "dial") {
+		dial(server, args.dialUrl as string, {
+			onStateChange: (state) => console.error(`agent-server dial ${args.dialUrl}: ${state}`),
+		});
+	} else {
+		const transport = stdioTransport();
+		server.attach(transport);
+		// Parent hung up — shut down cleanly.
+		transport.onClose(() => shutdown());
+	}
+}
+
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+	process.on(signal, () => shutdown());
+}

package/src/server/index.ts

@@ -0,0 +1,24 @@
+// @zvada/agent-server/server — the standard wire (phase 2).
+// JSON-RPC 2.0 over stdio/WebSocket: quick-ack turns, per-session sequenced
+// events, bounded replay, engine-brokered permissions.
+
+export { AgentServer, type AgentServerOptions } from "./agent-server.ts";
+export {
+	type InstallOptions,
+	type InstallResult,
+	runInstall,
+	toolsFor,
+} from "./install.ts";
+export { DEFAULT_BUFFER_SIZE, SessionLog } from "./session-log.ts";
+export {
+	dial,
+	type DialOptions,
+	listen,
+	type ListenOptions,
+	stdioTransport,
+} from "./transports.ts";
+export {
+	type AcpBindingOptions,
+	createAcpAgentApp,
+	serveAcpStdio,
+} from "./acp/binding.ts";

package/src/server/install.ts

@@ -0,0 +1,51 @@
+import {
+	CLI_TOOLS,
+	CliProvisioner,
+	type CliTool,
+	type ProvisionOptions,
+	type ResolvedCli,
+	toolForHarness,
+} from "../core/index.ts";
+import type { AgentHarness } from "../protocol/index.ts";
+
+export interface InstallOptions {
+	/** Restrict to the CLIs these harnesses need. Defaults to every tool. */
+	harnesses?: AgentHarness[];
+	provision?: ProvisionOptions;
+	/** Injectable provisioner boundary for tests. */
+	createProvisioner?: (options: ProvisionOptions) => Pick<CliProvisioner, "install">;
+}
+
+export interface InstallResult {
+	tool: CliTool;
+	cli: ResolvedCli;
+}
+
+/** Which managed CLIs a set of harnesses needs (deduped, stable order). */
+export function toolsFor(harnesses: AgentHarness[] | undefined): CliTool[] {
+	if (!harnesses) return [...CLI_TOOLS];
+	// Unmanaged harnesses (acp) resolve to undefined — nothing to prefetch.
+	const needed = new Set(
+		harnesses.map(toolForHarness).filter((t): t is CliTool => t !== undefined),
+	);
+	return CLI_TOOLS.filter((tool) => needed.has(tool));
+}
+
+/**
+ * Prefetch the pinned CLI builds into the managed cache — the cold-start
+ * eraser: run it while building a container/sandbox image and runtime turns
+ * never download. Downloads run in parallel; failures reject with the first
+ * error after all settle (so one flaky download doesn't hide the others).
+ */
+export async function runInstall(options: InstallOptions = {}): Promise<InstallResult[]> {
+	const provision = options.provision ?? {};
+	const provisioner = options.createProvisioner?.(provision) ?? new CliProvisioner(provision);
+	const tools = toolsFor(options.harnesses);
+	const settled = await Promise.allSettled(tools.map((tool) => provisioner.install(tool)));
+	const failure = settled.find((result) => result.status === "rejected");
+	if (failure) throw failure.reason;
+	return settled.map((result, i) => ({
+		tool: tools[i] as CliTool,
+		cli: (result as PromiseFulfilledResult<ResolvedCli>).value,
+	}));
+}

package/src/server/session-log.ts

@@ -0,0 +1,66 @@
+import type { AgentHarness, LifecycleEvent, WireEventEnvelope } from "../protocol/index.ts";
+
+export const DEFAULT_BUFFER_SIZE = 4096;
+
+/**
+ * Per-session monotonic sequence + bounded replay buffer (DESIGN D7). Every
+ * outbound event is stamped with `seq` (starting at 1) and kept in a ring
+ * buffer so a reconnecting client can `events/replay({fromSeq})`. Eviction is
+ * visible to clients via `firstAvailableSeq`.
+ *
+ * Eviction advances a head index (O(1) amortized) instead of shifting the
+ * array; the dead prefix is compacted away once it reaches one full capacity,
+ * bounding memory at ~2x `maxBuffer` envelopes.
+ */
+export class SessionLog {
+	private buffer: WireEventEnvelope[] = [];
+	private head = 0;
+	private nextSeq: number;
+	private readonly maxBuffer: number;
+
+	constructor(
+		readonly sessionId: string,
+		/** The harness this session is bound to (first turn wins). */
+		readonly harness: AgentHarness,
+		maxBuffer = DEFAULT_BUFFER_SIZE,
+		/** First seq to assign — a session reused after `session/close` continues
+		 * where its previous incarnation stopped, so peers never see seq go
+		 * backwards (a backwards seq reads as a duplicate and masks event loss). */
+		startSeq = 1,
+	) {
+		// A NaN or non-positive cap would silently disable eviction and grow
+		// the buffer without bound — normalize rather than trust the caller.
+		this.maxBuffer = Number.isInteger(maxBuffer) && maxBuffer > 0 ? maxBuffer : DEFAULT_BUFFER_SIZE;
+		this.nextSeq = Number.isInteger(startSeq) && startSeq > 0 ? startSeq : 1;
+	}
+
+	append(event: LifecycleEvent): WireEventEnvelope {
+		const envelope: WireEventEnvelope = { sessionId: this.sessionId, seq: this.nextSeq++, event };
+		this.buffer.push(envelope);
+		if (this.buffer.length - this.head > this.maxBuffer) {
+			this.head += 1;
+			if (this.head >= this.maxBuffer) {
+				this.buffer = this.buffer.slice(this.head);
+				this.head = 0;
+			}
+		}
+		return envelope;
+	}
+
+	/** Buffered envelopes with `seq >= fromSeq` (seq is contiguous — index math). */
+	replay(fromSeq: number): WireEventEnvelope[] {
+		const first = this.firstAvailableSeq;
+		if (first === null) return [];
+		return this.buffer.slice(this.head + Math.max(0, fromSeq - first));
+	}
+
+	/** Oldest seq still buffered, or null when nothing has been emitted. */
+	get firstAvailableSeq(): number | null {
+		return this.buffer[this.head]?.seq ?? null;
+	}
+
+	/** Newest seq assigned, or null when nothing has been emitted. */
+	get latestSeq(): number | null {
+		return this.nextSeq > 1 ? this.nextSeq - 1 : null;
+	}
+}