@zvada/agent-server 0.2.0

package/src/protocol/wire.ts

@@ -0,0 +1,313 @@
+import { z } from "zod";
+import { RunConfigSchema } from "./config.ts";
+import { AgentCapabilitiesSchema } from "./harness.ts";
+import { LifecycleEventSchema, PermissionOutcomeSchema } from "./lifecycle.ts";
+import { AgentInputSchema } from "./part-input.ts";
+
+/**
+ * The standard wire (phase 2): JSON-RPC 2.0 over a newline-delimited JSON
+ * stream (stdio, WebSocket, or any duplex byte channel). Requests flow
+ * client -> server only; the server pushes `event` notifications. Turns are
+ * quick-ack: `turn/start` acknowledges immediately and completion is observed
+ * 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;
+
+// ---- JSON-RPC 2.0 envelopes --------------------------------------------------
+
+export const JsonRpcIdSchema = z.union([z.string(), z.number()]);
+export type JsonRpcId = z.infer<typeof JsonRpcIdSchema>;
+
+export const JsonRpcErrorSchema = z.object({
+	code: z.number().int(),
+	message: z.string(),
+	data: z.unknown().optional(),
+});
+export type JsonRpcError = z.infer<typeof JsonRpcErrorSchema>;
+
+/** JSON-RPC error codes used on this wire (standard + implementation range). */
+export const WIRE_ERROR_CODES = {
+	parseError: -32700,
+	invalidRequest: -32600,
+	methodNotFound: -32601,
+	invalidParams: -32602,
+	internalError: -32603,
+	/** `config.harness` is not registered/available in this server process. */
+	harnessNotAvailable: -32000,
+	/** The sessionId is unknown to this server process (e.g. it restarted). */
+	unknownSession: -32001,
+	/** The session already has an active turn — one turn per session at a time. */
+	turnActive: -32002,
+	/** The server is shutting down and no longer accepts turns. */
+	shuttingDown: -32003,
+	/** The peer requested a wire version this implementation cannot speak. */
+	protocolVersionMismatch: -32004,
+	/** A session/close for this session is still in flight; retry after it settles. */
+	sessionClosing: -32005,
+} as const;
+
+// ---- methods -----------------------------------------------------------------
+
+export const WIRE_METHODS = {
+	initialize: "initialize",
+	turnStart: "turn/start",
+	turnCancel: "turn/cancel",
+	sessionClose: "session/close",
+	permissionRespond: "permission/respond",
+	eventsReplay: "events/replay",
+	shutdown: "shutdown",
+	/** Server -> client notification carrying one sequenced lifecycle event. */
+	event: "event",
+} as const;
+export type WireMethod = (typeof WIRE_METHODS)[keyof typeof WIRE_METHODS];
+
+export const WireImplementationInfoSchema = z.object({
+	name: z.string(),
+	version: z.string().optional(),
+});
+export type WireImplementationInfo = z.infer<typeof WireImplementationInfoSchema>;
+
+export const InitializeParamsSchema = z.object({
+	protocolVersion: z.number().int().positive(),
+	client: WireImplementationInfoSchema.optional(),
+});
+export type InitializeParams = z.infer<typeof InitializeParamsSchema>;
+
+export const InitializeResultSchema = z.object({
+	protocolVersion: z.number().int().positive(),
+	server: WireImplementationInfoSchema,
+	/** Capabilities per registered harness — only available harnesses appear. */
+	harnesses: z.record(z.string(), AgentCapabilitiesSchema),
+});
+export type InitializeResult = z.infer<typeof InitializeResultSchema>;
+
+/**
+ * `turn/start` params are a RunRequest whose ids may be omitted — the server
+ * mints UUIDv7s for missing ones and echoes the effective ids in the ack.
+ * (The bundled client always mints ids itself so it can route events that
+ * arrive before the ack's promise continuation runs.)
+ */
+export const TurnStartParamsSchema = z.object({
+	sessionId: z.string().optional(),
+	turnId: z.string().optional(),
+	input: AgentInputSchema,
+	config: RunConfigSchema,
+});
+export type TurnStartParams = z.infer<typeof TurnStartParamsSchema>;
+
+/** Quick-ack: the turn is accepted and running; completion = `turn.ended`. */
+export const TurnStartResultSchema = z.object({
+	sessionId: z.string(),
+	turnId: z.string(),
+});
+export type TurnStartResult = z.infer<typeof TurnStartResultSchema>;
+
+export const TurnCancelParamsSchema = z.object({ sessionId: z.string() });
+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() });
+export type TurnCancelResult = z.infer<typeof TurnCancelResultSchema>;
+
+export const SessionCloseParamsSchema = z.object({ sessionId: z.string() });
+export type SessionCloseParams = z.infer<typeof SessionCloseParamsSchema>;
+
+/** `closed: false` means the server did not know the session (idempotent). */
+export const SessionCloseResultSchema = z.object({ closed: z.boolean() });
+export type SessionCloseResult = z.infer<typeof SessionCloseResultSchema>;
+
+export const PermissionRespondParamsSchema = z.object({
+	sessionId: z.string(),
+	requestId: z.string(),
+	outcome: PermissionOutcomeSchema,
+});
+export type PermissionRespondParams = z.infer<typeof PermissionRespondParamsSchema>;
+
+/** `accepted: false` means the request was unknown or already resolved. */
+export const PermissionRespondResultSchema = z.object({ accepted: z.boolean() });
+export type PermissionRespondResult = z.infer<typeof PermissionRespondResultSchema>;
+
+/**
+ * One sequenced event as broadcast on the wire. `seq` is per-session,
+ * monotonic, and starts at 1 — a client that has seen nothing replays from 1.
+ * The envelope duplicates `sessionId` so consumers can route without parsing
+ * the event body.
+ */
+export const WireEventEnvelopeSchema = z.object({
+	sessionId: z.string(),
+	seq: z.number().int().positive(),
+	event: LifecycleEventSchema,
+});
+export type WireEventEnvelope = z.infer<typeof WireEventEnvelopeSchema>;
+
+export const EventsReplayParamsSchema = z.object({
+	sessionId: z.string(),
+	/** Replay buffered events with `seq >= fromSeq`. */
+	fromSeq: z.number().int().positive(),
+});
+export type EventsReplayParams = z.infer<typeof EventsReplayParamsSchema>;
+
+/**
+ * Replay is served from a bounded per-session ring buffer. When
+ * `firstAvailableSeq > fromSeq`, the requested prefix was evicted and the gap
+ * is unfillable — the consumer must treat its local view as stale.
+ */
+export const EventsReplayResultSchema = z.object({
+	events: z.array(WireEventEnvelopeSchema),
+	firstAvailableSeq: z.number().int().positive().nullable(),
+	latestSeq: z.number().int().positive().nullable(),
+});
+export type EventsReplayResult = z.infer<typeof EventsReplayResultSchema>;
+
+export const ShutdownParamsSchema = z.object({}).optional();
+export const ShutdownResultSchema = z.object({});
+
+// ---- codec -------------------------------------------------------------------
+
+/** A decoded incoming wire line, discriminated for dispatch. */
+export type WireMessage =
+	| { kind: "request"; id: JsonRpcId; method: string; params?: unknown }
+	| { kind: "notification"; method: string; params?: unknown }
+	/** `id` is null on protocol-level errors answering unparseable requests. */
+	| { kind: "response"; id: JsonRpcId | null; result?: unknown; error?: JsonRpcError }
+	| { kind: "invalid"; error: string };
+
+/** Decode one NDJSON line into a JSON-RPC message (never throws). */
+export function decodeWireMessage(line: string): WireMessage {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(line);
+	} catch {
+		return { kind: "invalid", error: "not valid JSON" };
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		return { kind: "invalid", error: "not a JSON-RPC object" };
+	}
+	const msg = raw as Record<string, unknown>;
+	if (msg.jsonrpc !== "2.0") return { kind: "invalid", error: "missing jsonrpc: '2.0'" };
+	const id = JsonRpcIdSchema.safeParse(msg.id);
+	if (typeof msg.method === "string") {
+		return id.success
+			? { kind: "request", id: id.data, method: msg.method, params: msg.params }
+			: { kind: "notification", method: msg.method, params: msg.params };
+	}
+	if ((id.success || msg.id === null) && ("result" in msg || "error" in msg)) {
+		const error = JsonRpcErrorSchema.safeParse(msg.error);
+		return {
+			kind: "response",
+			id: id.success ? id.data : null,
+			result: msg.result,
+			error: error.success ? error.data : undefined,
+		};
+	}
+	return { kind: "invalid", error: "neither request, notification, nor response" };
+}
+
+export function encodeRequest(id: JsonRpcId, method: string, params?: unknown): string {
+	return JSON.stringify({ jsonrpc: "2.0", id, method, params });
+}
+
+export function encodeNotification(method: string, params?: unknown): string {
+	return JSON.stringify({ jsonrpc: "2.0", method, params });
+}
+
+export function encodeResponse(id: JsonRpcId, result: unknown): string {
+	return JSON.stringify({ jsonrpc: "2.0", id, result });
+}
+
+export function encodeErrorResponse(
+	id: JsonRpcId | null,
+	code: number,
+	message: string,
+	data?: unknown,
+): string {
+	return JSON.stringify({ jsonrpc: "2.0", id, error: { code, message, data } });
+}
+
+// ---- transport port ----------------------------------------------------------
+
+/**
+ * A duplex line channel the wire runs over. Implementations exist for stdio,
+ * WebSocket, and in-memory pairs (tests). Handlers registered after close are
+ * never called; `send` after close is a silent no-op.
+ */
+export interface WireTransport {
+	send(line: string): void;
+	/** Register a line handler; returns an unsubscribe function. */
+	onLine(handler: (line: string) => void): () => void;
+	/** Register a close handler; returns an unsubscribe function. */
+	onClose(handler: (reason?: string) => void): () => void;
+	close(): void;
+	readonly closed: boolean;
+}
+
+/**
+ * Split an inbound transport message into NDJSON lines, defensively: peers
+ * may batch several lines per frame, and WebSocket implementations deliver
+ * text, Uint8Array, or ArrayBuffer depending on runtime. Blank lines are
+ * skipped.
+ */
+export function pushNdjsonLines(push: (line: string) => void, data: unknown): void {
+	let text: string;
+	if (typeof data === "string") text = data;
+	else if (data instanceof Uint8Array) text = new TextDecoder().decode(data);
+	else if (data instanceof ArrayBuffer) text = new TextDecoder().decode(new Uint8Array(data));
+	else text = String(data);
+	for (const line of text.split("\n")) if (line.trim()) push(line);
+}
+
+/**
+ * Build a WireTransport from a raw byte-channel binding: the caller supplies
+ * the outbound `send`/`close`, and pushes inbound lines / close through the
+ * returned handles. Every concrete transport (stdio, WebSocket, memory pair)
+ * is this bridge plus platform wiring.
+ */
+export function channelTransport(io: { send(line: string): void; close?(): void }): {
+	transport: WireTransport;
+	push(line: string): void;
+	end(reason?: string): void;
+} {
+	const lineHandlers = new Set<(line: string) => void>();
+	const closeHandlers = new Set<(reason?: string) => void>();
+	let closed = false;
+
+	const end = (reason?: string) => {
+		if (closed) return;
+		closed = true;
+		for (const handler of [...closeHandlers]) handler(reason);
+		lineHandlers.clear();
+		closeHandlers.clear();
+	};
+
+	const transport: WireTransport = {
+		send(line) {
+			if (!closed) io.send(line);
+		},
+		onLine(handler) {
+			lineHandlers.add(handler);
+			return () => lineHandlers.delete(handler);
+		},
+		onClose(handler) {
+			closeHandlers.add(handler);
+			return () => closeHandlers.delete(handler);
+		},
+		close() {
+			if (closed) return;
+			io.close?.();
+			end("closed locally");
+		},
+		get closed() {
+			return closed;
+		},
+	};
+
+	return {
+		transport,
+		push(line) {
+			if (closed) return;
+			for (const handler of [...lineHandlers]) handler(line);
+		},
+		end,
+	};
+}

package/src/server/acp/binding.ts

@@ -0,0 +1,163 @@
+import { Readable, Writable } from "node:stream";
+import type {
+	AgentApp,
+	AgentConnection,
+	RequestPermissionResponse,
+} from "@agentclientprotocol/sdk";
+import type { AgentRuntime, EventSink } from "../../core/index.ts";
+import { generateUUIDv7 } from "../../core/index.ts";
+import type {
+	AgentHarness,
+	LifecycleEvent,
+	PermissionMode,
+	PermissionOutcome,
+} from "../../protocol/index.ts";
+import { AcpUpdateTranslator, fromAcpMcpServers, fromPromptBlocks } from "./translate.ts";
+
+/** ACP protocol major version this binding speaks. */
+const PROTOCOL_VERSION = 1;
+
+export interface AcpBindingOptions {
+	runtime: AgentRuntime;
+	/** The harness this ACP agent fronts (operator-chosen at launch). */
+	harness: AgentHarness;
+	model?: string;
+	/** Defaults to `default` so tool approvals flow to the ACP client. */
+	permissionMode?: PermissionMode;
+	name?: string;
+	version?: string;
+}
+
+interface BoundSession {
+	cwd: string;
+	mcpServers?: ReturnType<typeof fromAcpMcpServers>;
+}
+
+/**
+ * The phase-3 ACP *server* binding: exposes the runtime as an Agent Client
+ * Protocol v1 agent, so anything that speaks ACP (Zed, another agent-server's
+ * `acp` harness, any product) can drive our harnesses with zero custom
+ * integration. `session/prompt` runs one engine turn; LifecycleEvents stream
+ * out as `session/update`; engine-brokered permissions become
+ * `session/request_permission` round-trips (identical option vocabulary).
+ * Resume is within-process: an ACP sessionId stays valid for the binding's
+ * lifetime (cross-process resume needs host persistence — not offered yet).
+ */
+export async function createAcpAgentApp(options: AcpBindingOptions): Promise<AgentApp> {
+	const acp = await import("@agentclientprotocol/sdk");
+	const { runtime, harness } = options;
+	const sessions = new Map<string, BoundSession>();
+
+	const requireSession = (sessionId: string): BoundSession => {
+		const session = sessions.get(sessionId);
+		if (!session) throw acp.RequestError.resourceNotFound(sessionId);
+		return session;
+	};
+
+	return acp
+		.agent({ name: options.name ?? "agent-server" })
+		.onRequest("initialize", (ctx) => ({
+			protocolVersion: Math.min(ctx.params.protocolVersion, PROTOCOL_VERSION),
+			agentInfo: { name: options.name ?? "agent-server", version: options.version ?? "0.0.0" },
+			agentCapabilities: {
+				promptCapabilities: { image: true },
+				sessionCapabilities: { resume: {}, close: {} },
+			},
+			authMethods: [],
+		}))
+		.onRequest("session/new", (ctx) => {
+			const sessionId = generateUUIDv7();
+			sessions.set(sessionId, {
+				cwd: ctx.params.cwd,
+				mcpServers: fromAcpMcpServers(ctx.params.mcpServers),
+			});
+			return { sessionId };
+		})
+		.onRequest("session/resume", (ctx) => {
+			const session = requireSession(ctx.params.sessionId);
+			session.cwd = ctx.params.cwd;
+			if (ctx.params.mcpServers) session.mcpServers = fromAcpMcpServers(ctx.params.mcpServers);
+			return {};
+		})
+		.onRequest("session/close", async (ctx) => {
+			requireSession(ctx.params.sessionId);
+			await runtime.closeSession(harness, ctx.params.sessionId);
+			sessions.delete(ctx.params.sessionId);
+			return {};
+		})
+		.onNotification("session/cancel", (ctx) => {
+			if (sessions.has(ctx.params.sessionId)) {
+				void runtime.cancel(harness, ctx.params.sessionId);
+			}
+		})
+		.onRequest("session/prompt", async (ctx) => {
+			const session = requireSession(ctx.params.sessionId);
+			const translator = new AcpUpdateTranslator();
+			const sink: EventSink = {
+				emit: async (event: LifecycleEvent) => {
+					if (event.type === "permission.requested") {
+						// Round-trip to the ACP client; its outcome shape matches ours.
+						let outcome: PermissionOutcome = { outcome: "cancelled" };
+						try {
+							const response: RequestPermissionResponse = await ctx.client.request(
+								"session/request_permission",
+								{
+									sessionId: ctx.params.sessionId,
+									toolCall: {
+										toolCallId: event.toolCall?.toolCallId ?? event.requestId,
+										title: event.title,
+										status: "pending",
+										...(event.toolCall?.kind && { kind: event.toolCall.kind }),
+										...(event.toolCall?.rawInput && { rawInput: event.toolCall.rawInput }),
+									},
+									options: event.options,
+								},
+							);
+							outcome = response.outcome;
+						} catch {
+							// Client refused/disconnected — fall through to cancelled.
+						}
+						runtime.respondPermission(ctx.params.sessionId, event.requestId, outcome);
+						return;
+					}
+					for (const update of translator.translate(event)) {
+						void ctx.client.notify("session/update", {
+							sessionId: ctx.params.sessionId,
+							update,
+						});
+					}
+				},
+			};
+			const summary = await runtime.run(
+				{
+					sessionId: ctx.params.sessionId,
+					turnId: generateUUIDv7(),
+					input: fromPromptBlocks(ctx.params.prompt),
+					config: {
+						harness,
+						cwd: session.cwd,
+						model: options.model,
+						permissionMode: options.permissionMode ?? "default",
+						mcpServers: session.mcpServers,
+					},
+				},
+				sink,
+			);
+			if (summary.stopReason === "error") {
+				throw new Error(summary.error?.message ?? "turn failed");
+			}
+			return { stopReason: summary.stopReason };
+		});
+}
+
+/** Serve the binding on this process's stdio (what an ACP client spawns). */
+export async function serveAcpStdio(options: AcpBindingOptions): Promise<AgentConnection> {
+	const acp = await import("@agentclientprotocol/sdk");
+	const app = await createAcpAgentApp(options);
+	return app.connect(
+		acp.ndJsonStream(
+			Writable.toWeb(process.stdout),
+			Readable.toWeb(process.stdin) as ReadableStream<Uint8Array>,
+		),
+	);
+}

package/src/server/acp/translate.ts

@@ -0,0 +1,160 @@
+import type { ContentBlock, McpServer, SessionUpdate } from "@agentclientprotocol/sdk";
+import type { LifecycleEvent, McpServerConfig, PartInput, ToolPart } from "../../protocol/index.ts";
+
+/**
+ * Per-prompt translator from the engine's LifecycleEvents to ACP v1
+ * `session/update` payloads — the exact inverse of the acp harness adapter
+ * (the vocabularies were aligned for this: ToolKind, tool status, and
+ * permission shapes pass through unchanged).
+ *
+ * Deliberate v1 gaps: sub-agent parts (`parentToolUseId`) have no ACP slot
+ * and are dropped (the parent tool's result carries the outcome);
+ * `session.compacted` has no v1 equivalent; `usage_update` requires `size`,
+ * so gauges without a window size are skipped.
+ */
+export class AcpUpdateTranslator {
+	/** toolCallIds already announced via `tool_call`. */
+	private readonly openedTools = new Set<string>();
+	/** Text/reasoning characters already emitted per part (dedupe snapshots vs deltas). */
+	private readonly sentByPart = new Map<string, number>();
+
+	translate(event: LifecycleEvent): SessionUpdate[] {
+		switch (event.type) {
+			case "message.part.delta": {
+				if (event.parentToolUseId) return [];
+				const { delta } = event;
+				if (delta.type === "tool-input-delta") return []; // covered by part snapshots
+				this.sentByPart.set(
+					event.partId,
+					(this.sentByPart.get(event.partId) ?? 0) + delta.text.length,
+				);
+				return [
+					chunk(
+						delta.type === "text-delta" ? "agent_message_chunk" : "agent_thought_chunk",
+						delta.text,
+						event.messageId,
+					),
+				];
+			}
+			case "message.part": {
+				const part = event.part;
+				if (part.parentToolUseId) return [];
+				if (part.type === "tool") return this.toolUpdate(part);
+				// While a part is still streaming, its snapshots mirror the deltas
+				// (adapters mutate in place, so an early snapshot can already carry
+				// delta text — emitting both doubles it). Only the final `done`
+				// snapshot may contribute an unseen suffix, which is also how fully
+				// non-streamed parts (no deltas at all) get emitted exactly once.
+				if (part.state !== "done") return [];
+				const sent = this.sentByPart.get(part.id) ?? 0;
+				if (part.text.length <= sent) return [];
+				this.sentByPart.set(part.id, part.text.length);
+				return [
+					chunk(
+						part.type === "text" ? "agent_message_chunk" : "agent_thought_chunk",
+						part.text.slice(sent),
+						event.messageId,
+					),
+				];
+			}
+			case "session.usage":
+				if (event.size === undefined) return [];
+				return [
+					{
+						sessionUpdate: "usage_update",
+						used: event.used,
+						size: event.size,
+						...(event.cost !== undefined && {
+							cost: { amount: event.cost, currency: "USD" },
+						}),
+					},
+				];
+			default:
+				return [];
+		}
+	}
+
+	private toolUpdate(part: ToolPart): SessionUpdate[] {
+		// Statuses and ToolKind are the SDK's own vocabulary (DESIGN D2) — no
+		// re-narrowing, no casts.
+		const status = part.state.status;
+		if (!this.openedTools.has(part.toolCallId)) {
+			this.openedTools.add(part.toolCallId);
+			return [
+				{
+					sessionUpdate: "tool_call",
+					toolCallId: part.toolCallId,
+					title: part.title ?? part.toolName,
+					name: part.toolName,
+					...(part.kind && { kind: part.kind }),
+					status,
+					...(part.locations?.length && { locations: part.locations }),
+					...(status !== "pending" && { rawInput: part.state.input }),
+				},
+			];
+		}
+		const output =
+			part.state.status === "failed"
+				? part.state.error
+				: part.state.status === "completed"
+					? part.state.output
+					: undefined;
+		return [
+			{
+				sessionUpdate: "tool_call_update",
+				toolCallId: part.toolCallId,
+				status,
+				...(output && {
+					content: [{ type: "content", content: { type: "text", text: output } }],
+				}),
+			},
+		];
+	}
+}
+
+function chunk(
+	kind: "agent_message_chunk" | "agent_thought_chunk",
+	text: string,
+	messageId: string,
+): SessionUpdate {
+	return { sessionUpdate: kind, content: { type: "text", text }, messageId };
+}
+
+/** ACP prompt content → engine input (text + base64 images; the rest is dropped). */
+export function fromPromptBlocks(prompt: ContentBlock[]): string | PartInput[] {
+	const parts: PartInput[] = [];
+	for (const block of prompt) {
+		if (block.type === "text" && block.text) parts.push({ type: "text", text: block.text });
+		else if (block.type === "image" && block.data) {
+			parts.push({ type: "image", data: block.data, mediaType: block.mimeType });
+		}
+	}
+	if (parts.length === 1 && parts[0]?.type === "text") return parts[0].text;
+	return parts.length ? parts : "";
+}
+
+/** ACP `McpServer[]` → engine MCP config map (inverse of the harness-side mapping). */
+export function fromAcpMcpServers(
+	servers: McpServer[] | undefined,
+): Record<string, McpServerConfig> | undefined {
+	if (!servers?.length) return undefined;
+	const out: Record<string, McpServerConfig> = {};
+	// Note: the SDK's `type: "acp"` nested-agent variant is silently dropped.
+	for (const server of servers) {
+		if ("command" in server) {
+			out[server.name] = {
+				type: "stdio",
+				command: server.command,
+				args: server.args,
+				env: Object.fromEntries((server.env ?? []).map((e) => [e.name, e.value])),
+			};
+		} else if ("url" in server && (server.type === "http" || server.type === "sse")) {
+			out[server.name] = {
+				type: server.type,
+				url: server.url,
+				headers: Object.fromEntries((server.headers ?? []).map((h) => [h.name, h.value])),
+			};
+		}
+	}
+	return Object.keys(out).length ? out : undefined;
+}