@zvada/agent-server 0.2.0

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

@@ -0,0 +1,212 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import type {
+	AgentNotificationMethod,
+	AgentNotificationParamsByMethod,
+	AgentRequestMethod,
+	AgentRequestParamsByMethod,
+	AgentRequestResponsesByMethod,
+	ClientConnection,
+	RequestPermissionRequest,
+	RequestPermissionResponse,
+	SessionNotification,
+} from "@agentclientprotocol/sdk";
+
+/**
+ * How to start one ACP agent subprocess. Operator-level only — the wire never
+ * carries commands (same rule as `resolveCliPath`): an attacker who controls
+ * the launch command controls code execution on the host.
+ */
+export interface AcpLaunch {
+	command: string;
+	args?: string[];
+	/** Extra env layered onto the subprocess (over process.env). */
+	env?: Record<string, string>;
+}
+
+/**
+ * Parse an operator-supplied launch spec (`"npx -y pi-acp"`) into an AcpLaunch.
+ * Naive whitespace split — no shell quoting; env vars come from the caller.
+ * The canonical parser for `--acp-agent` flags / `$AGENT_SERVER_ACP_AGENT`.
+ */
+export function parseAcpLaunch(spec: string | undefined): AcpLaunch | undefined {
+	const [command, ...args] = spec?.trim().split(/\s+/).filter(Boolean) ?? [];
+	if (!command) return undefined;
+	return { command, ...(args.length && { args }) };
+}
+
+export type SessionUpdateHandler = (notification: SessionNotification) => void;
+
+/** Answers agent→client `session/request_permission`. Absent handler → cancelled. */
+export type AcpPermissionHandler = (
+	request: RequestPermissionRequest,
+) => Promise<RequestPermissionResponse>;
+
+export interface AcpClientOptions {
+	launch: AcpLaunch;
+	cwd: string;
+	/** Per-session env on top of the launch env (RunConfig.env). */
+	env?: Record<string, string>;
+	clientName?: string;
+}
+
+/**
+ * One ACP agent subprocess + its SDK connection. The engine talks to any
+ * ACP v1 agent through this: JSON-RPC framing, routing, and schema types come
+ * from `@agentclientprotocol/sdk` (dynamic-imported, optional peer dep);
+ * this wrapper owns the child process, close fan-out, and the mutable
+ * per-turn handlers (the SDK app's handlers are fixed at connect time, so
+ * they dispatch through this class's current fields — mirroring the
+ * codex-app-server client's `setRequestHandler` pattern).
+ */
+export class AcpClient {
+	private proc?: ChildProcess;
+	private connection?: ClientConnection;
+	private readonly updateHandlers = new Set<SessionUpdateHandler>();
+	private readonly closeHandlers = new Set<(error?: Error) => void>();
+	private permissionHandler?: AcpPermissionHandler;
+	private exited = false;
+
+	private constructor(private readonly opts: AcpClientOptions) {}
+
+	/** Spawn the agent and connect. Fails if `@agentclientprotocol/sdk` is absent. */
+	static async create(opts: AcpClientOptions): Promise<AcpClient> {
+		const client = new AcpClient(opts);
+		await client.start();
+		return client;
+	}
+
+	onSessionUpdate(handler: SessionUpdateHandler): () => void {
+		this.updateHandlers.add(handler);
+		return () => this.updateHandlers.delete(handler);
+	}
+
+	/** Install the answerer for permission round-trips (set once per session;
+	 * per-turn context lives inside the handler's own closure). */
+	setPermissionHandler(handler: AcpPermissionHandler | undefined): void {
+		this.permissionHandler = handler;
+	}
+
+	onClose(handler: (error?: Error) => void): () => void {
+		this.closeHandlers.add(handler);
+		return () => this.closeHandlers.delete(handler);
+	}
+
+	get closed(): boolean {
+		return this.exited;
+	}
+
+	/**
+	 * Send a request to the agent (`initialize`, `session/new`, `session/prompt`, …).
+	 * `timeoutMs` bounds the wait for handshake-style requests — a spawned-but-wedged
+	 * agent must not stall the turn forever. The SDK's `cancellationSignal` is
+	 * cooperative (the peer still decides when to respond), so the local race is
+	 * what actually enforces the deadline. Turn-long requests (`session/prompt`)
+	 * pass no timeout.
+	 */
+	async request<M extends AgentRequestMethod>(
+		method: M,
+		params: AgentRequestParamsByMethod[M],
+		timeoutMs?: number,
+	): Promise<AgentRequestResponsesByMethod[M]> {
+		if (!this.connection || this.exited) throw new Error("acp agent not running");
+		const agent = this.connection.agent;
+		if (!timeoutMs) return agent.request(method, params);
+		const abort = new AbortController();
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const deadline = new Promise<never>((_, reject) => {
+			timer = setTimeout(() => {
+				abort.abort();
+				reject(new Error(`acp agent '${method}' timed out after ${timeoutMs}ms`));
+			}, timeoutMs);
+			timer.unref?.();
+		});
+		try {
+			return await Promise.race([
+				agent.request(method, params, { cancellationSignal: abort.signal }),
+				deadline,
+			]);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}
+
+	/** Send a notification to the agent (`session/cancel`). */
+	async notify<M extends AgentNotificationMethod>(
+		method: M,
+		params: AgentNotificationParamsByMethod[M],
+	): Promise<void> {
+		if (!this.connection || this.exited) return;
+		await this.connection.agent.notify(method, params);
+	}
+
+	close(): void {
+		const proc = this.proc;
+		const wasOpen = !this.exited;
+		this.exited = true;
+		this.proc = undefined;
+		this.connection?.close();
+		this.connection = undefined;
+		if (proc && !proc.killed) proc.kill("SIGTERM");
+		if (wasOpen) this.notifyClosed();
+	}
+
+	private async start(): Promise<void> {
+		const acp = await import("@agentclientprotocol/sdk");
+		const { launch } = this.opts;
+		const proc = spawn(launch.command, launch.args ?? [], {
+			cwd: this.opts.cwd,
+			env: { ...process.env, ...launch.env, ...this.opts.env },
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+		this.proc = proc;
+		if (!proc.stdin || !proc.stdout) {
+			proc.kill("SIGTERM");
+			throw new Error("acp agent subprocess has no stdio");
+		}
+		// Drain stderr so the agent can't block on a full pipe; its logs are not ours.
+		proc.stderr?.on("data", () => {});
+		proc.on("error", (err) => this.onExit(err));
+		proc.on("exit", (code, signal) =>
+			this.onExit(new Error(`acp agent exited (code=${code} signal=${signal})`)),
+		);
+
+		const stream = acp.ndJsonStream(
+			Writable.toWeb(proc.stdin),
+			// Kept cast: embedders compile these sources under their own tsconfig,
+			// and older lib.dom types Readable.toWeb as ReadableStream<any>.
+			Readable.toWeb(proc.stdout) as unknown as ReadableStream<Uint8Array>,
+		);
+		this.connection = acp
+			.client({ name: this.opts.clientName ?? "agent-server" })
+			.onRequest("session/request_permission", async (ctx): Promise<RequestPermissionResponse> => {
+				const handler = this.permissionHandler;
+				if (!handler) return { outcome: { outcome: "cancelled" } };
+				return handler(ctx.params);
+			})
+			.onNotification("session/update", (ctx) => {
+				for (const handler of this.updateHandlers) handler(ctx.params);
+			})
+			.connect(stream);
+		// A closed connection without a process exit (stream error) still ends the
+		// client; a rejected `closed` must not become an unhandled rejection.
+		this.connection.closed.then(
+			() => this.onExit(new Error("acp connection closed")),
+			(err: unknown) =>
+				this.onExit(err instanceof Error ? err : new Error(`acp connection failed: ${err}`)),
+		);
+	}
+
+	private onExit(error: Error): void {
+		if (this.exited) return;
+		this.exited = true;
+		this.connection?.close(error);
+		this.connection = undefined;
+		this.notifyClosed(error);
+	}
+
+	private notifyClosed(error?: Error): void {
+		for (const handler of this.closeHandlers) handler(error);
+		this.closeHandlers.clear();
+	}
+}

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

@@ -0,0 +1,29 @@
+import { type AcpLaunch, parseAcpLaunch } from "./client.ts";
+
+/**
+ * Advisory catalog of well-known ACP agents — UX sugar, not wire vocabulary
+ * (like MODEL_CATALOG). On the wire the harness is always `acp`; these names
+ * let entry points offer "pi" or "gemini" as first-class choices and expand
+ * them to launch commands at the operator edge. Anything not listed here runs
+ * via an explicit launch command — any ACP-compatible agent works.
+ */
+export const KNOWN_ACP_AGENTS: Record<string, { label: string; launch: AcpLaunch }> = {
+	pi: {
+		label: "pi.dev (Pi coding agent, via the pi-acp adapter)",
+		launch: { command: "npx", args: ["-y", "pi-acp"] },
+	},
+	gemini: {
+		label: "Gemini CLI (native ACP mode)",
+		launch: { command: "gemini", args: ["--acp"] },
+	},
+};
+
+/**
+ * Resolve an operator spec that is either a known agent name (`"pi"`) or a
+ * raw launch command (`"npx -y pi-acp"`). The canonical resolver behind
+ * `--acp-agent` and `$AGENT_SERVER_ACP_AGENT`.
+ */
+export function resolveAcpLaunch(spec: string | undefined): AcpLaunch | undefined {
+	if (!spec) return undefined;
+	return KNOWN_ACP_AGENTS[spec.trim()]?.launch ?? parseAcpLaunch(spec);
+}

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

@@ -0,0 +1,136 @@
+import type {
+	ContentBlock,
+	McpServer,
+	PermissionOption,
+	RequestPermissionRequest,
+	RequestPermissionResponse,
+	ToolCallLocation,
+} from "@agentclientprotocol/sdk";
+import type {
+	AgentInput,
+	McpServerConfig,
+	PermissionMode,
+	PermissionToolCall,
+	ToolKind,
+	ToolLocation,
+} from "../../../protocol/index.ts";
+import { TOOL_KINDS } from "../../../protocol/index.ts";
+
+/**
+ * The single bridge between ACP's vocabulary and the engine's. Everything here
+ * is a pure conversion shared by the agent (outbound requests, permission
+ * round-trips) and the adapter (inbound session updates) — the harness
+ * seat's single bridge, so its two halves cannot drift. (The ACP *server*
+ * binding in packages/server/src/acp/ is the inverse direction, not a copy.)
+ */
+
+/** ACP's ToolKind strings are ours verbatim (DESIGN D2); narrow with a membership check. */
+export function toolKindOf(kind: string | null | undefined): ToolKind | undefined {
+	return kind && (TOOL_KINDS as readonly string[]).includes(kind) ? (kind as ToolKind) : undefined;
+}
+
+/** ACP `ToolCallLocation[]` → engine `ToolLocation[]` (drop null lines, empty → absent). */
+export function toToolLocations(
+	locations: ToolCallLocation[] | null | undefined,
+): ToolLocation[] | undefined {
+	if (!locations?.length) return undefined;
+	return locations.map((l) => ({ path: l.path, ...(l.line != null && { line: l.line }) }));
+}
+
+/** Engine MCP config map → ACP `McpServer[]` (names come from the record keys). */
+export function toAcpMcpServers(
+	mcpServers: Record<string, McpServerConfig> | undefined,
+): McpServer[] {
+	if (!mcpServers) return [];
+	return Object.entries(mcpServers).map(([name, config]): McpServer => {
+		if (config.type === "stdio") {
+			return {
+				name,
+				command: config.command,
+				args: config.args ?? [],
+				env: Object.entries(config.env ?? {}).map(([n, value]) => ({ name: n, value })),
+			};
+		}
+		return {
+			type: config.type,
+			name,
+			url: config.url,
+			headers: Object.entries(config.headers ?? {}).map(([n, value]) => ({ name: n, value })),
+		};
+	});
+}
+
+/** Engine turn input → ACP prompt content blocks (image blocks gated on agent capability). */
+export function toPromptBlocks(input: AgentInput, imagesSupported: boolean): ContentBlock[] {
+	if (typeof input === "string") return [{ type: "text", text: input }];
+	const blocks: ContentBlock[] = [];
+	for (const part of input) {
+		if (part.type === "text") {
+			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 });
+			} else if (part.url) {
+				blocks.push({ type: "resource_link", uri: part.url, name: part.url });
+			}
+		} else if (part.type === "file" && part.url) {
+			blocks.push({ type: "resource_link", uri: part.url, name: part.url });
+		}
+	}
+	return blocks.length ? blocks : [{ type: "text", text: "" }];
+}
+
+/** ACP permission request → the engine's PermissionToolCall (SDK-validated, no casts). */
+export function permissionToolCall(request: RequestPermissionRequest): PermissionToolCall {
+	const toolCall = request.toolCall;
+	const kind = toolKindOf(toolCall.kind);
+	const locations = toToolLocations(toolCall.locations);
+	return {
+		...(toolCall.toolCallId && { toolCallId: toolCall.toolCallId }),
+		toolName: toolCall.name ?? toolCall.title ?? toolCall.kind ?? "tool",
+		...(kind && { kind }),
+		...(toolCall.title && { title: toolCall.title }),
+		...(locations && { locations }),
+		...(isRecord(toolCall.rawInput) && { rawInput: toolCall.rawInput }),
+	};
+}
+
+export const CANCELLED_OUTCOME: RequestPermissionResponse = {
+	outcome: { outcome: "cancelled" },
+};
+
+/**
+ * Pick the option matching the decision: allow → first allow_once/allow_always,
+ * deny → first reject_once/reject_always; no matching option → cancelled.
+ */
+export function chooseOutcome(
+	options: PermissionOption[],
+	allow: boolean,
+): RequestPermissionResponse {
+	const kinds = allow ? ["allow_once", "allow_always"] : ["reject_once", "reject_always"];
+	for (const kind of kinds) {
+		const match = options.find((o) => o.kind === kind);
+		if (match) return { outcome: { outcome: "selected", optionId: match.optionId } };
+	}
+	return CANCELLED_OUTCOME;
+}
+
+/**
+ * Decide an ACP permission request without the engine broker: mirrors the
+ * codex posture where only `default` mode asks — every other mode auto-decides.
+ */
+export function autoDecide(
+	request: RequestPermissionRequest,
+	mode: PermissionMode | undefined,
+): RequestPermissionResponse {
+	const kind = request.toolCall.kind;
+	const allowed =
+		mode === "bypassPermissions" ||
+		(mode === "acceptEdits" && (kind === "edit" || kind === "read"));
+	return chooseOutcome(request.options, allowed);
+}
+
+/** The SDK types `rawInput`/`rawOutput` as `unknown`; the engine wants a record. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/core/agents/base.ts

@@ -0,0 +1,145 @@
+import type {
+	AgentCapabilities,
+	AgentHarness,
+	AgentInput,
+	McpServerConfig,
+	PermissionMode,
+	PermissionToolCall,
+	ThinkingLevel,
+} from "../../protocol/index.ts";
+
+/**
+ * What the engine tells a harness after brokering a permission round-trip.
+ * The harness maps this onto its native approval vocabulary (Claude
+ * `allow`/`deny`, codex `accept`/`decline`/`cancel`).
+ */
+export type PermissionDecision =
+	| { decision: "allow" }
+	| { decision: "deny"; reason?: string }
+	/** The turn is being cancelled — abort rather than merely skip the tool. */
+	| { decision: "cancel" };
+
+/**
+ * Provided by the engine; called by a harness when its backend blocks on an
+ * approval. The engine emits `permission.requested`, waits for
+ * `respondPermission` (or cancellation), and returns the decision. `signal`
+ * lets the harness abort the wait when its own backend gives up.
+ */
+export type PermissionRequestHandler = (
+	toolCall: PermissionToolCall,
+	opts?: { signal?: AbortSignal },
+) => Promise<PermissionDecision>;
+
+/**
+ * Everything a harness needs to run one turn. The engine builds this from a
+ * RunRequest. `sessionId` is our stable logical id (the session-manager key);
+ * `resumeSessionId` is the harness-native id to continue (from a prior
+ * `session.created`). A harness reports its discovered native id via
+ * `onNativeSession` so the engine can surface it for future resumes.
+ */
+export interface AgentExecuteOptions {
+	sessionId: string;
+	turnId: string;
+	cwd: string;
+	additionalDirectories?: string[];
+	model?: string;
+	thinkingLevel?: ThinkingLevel;
+	permissionMode?: PermissionMode;
+	maxTurns?: number;
+	systemPromptAppend?: string;
+	resumeSessionId?: string;
+	resumeSessionAt?: string;
+	mcpServers?: Record<string, McpServerConfig>;
+	env?: Record<string, string>;
+	apiKey?: string;
+	/** Disable all built-in tools for this turn (text-only). */
+	disableTools?: boolean;
+	signal?: AbortSignal;
+	/**
+	 * Called once with the harness-native session/thread id (for resume).
+	 * Pass the harness's honest `resumed` judgment unconditionally — the
+	 * runtime surfaces it only on turns that requested a resume (false =
+	 * fresh-session fallback).
+	 */
+	onNativeSession?: (nativeSessionId: string, info?: { resumed?: boolean }) => void;
+	/** Engine-brokered approval round-trip (see PermissionRequestHandler). */
+	onPermissionRequest?: PermissionRequestHandler;
+}
+
+/** Raw, harness-specific event. Adapters interpret it; the engine never does. */
+export type RawAgentEvent = unknown;
+
+/**
+ * A harness: a thin wrapper over one agent backend (Claude Code, Codex SDK,
+ * Codex app-server). `execute` yields raw backend events; normalization is the
+ * adapter's job. Harnesses own session reuse and cancellation.
+ */
+export interface Agent {
+	readonly harness: AgentHarness;
+	readonly capabilities: AgentCapabilities;
+	execute(input: AgentInput, options: AgentExecuteOptions): AsyncIterableIterator<RawAgentEvent>;
+	/** Cancel the in-flight turn for a logical session. */
+	cancel(sessionId: string): Promise<void>;
+	/** Release all harness-owned state for one idle logical session. */
+	release?(sessionId: string): Promise<void>;
+	/** Tear down every live session (process shutdown). */
+	terminateAll(): Promise<void>;
+}
+
+export abstract class BaseAgent implements Agent {
+	abstract readonly harness: AgentHarness;
+	abstract readonly capabilities: AgentCapabilities;
+
+	/**
+	 * In-flight turn controllers per logical sessionId. A set (not a single
+	 * controller) so overlapping turns on one session can't clobber each other's
+	 * cancellation — `cancel(sessionId)` aborts all of them, and `endTurn`
+	 * removes only the specific controller it created.
+	 */
+	protected readonly inflight = new Map<string, Set<AbortController>>();
+
+	abstract execute(
+		input: AgentInput,
+		options: AgentExecuteOptions,
+	): AsyncIterableIterator<RawAgentEvent>;
+
+	async cancel(sessionId: string): Promise<void> {
+		for (const controller of this.inflight.get(sessionId) ?? []) controller.abort();
+	}
+
+	async release(sessionId: string): Promise<void> {
+		await this.cancel(sessionId);
+		this.inflight.delete(sessionId);
+	}
+
+	async terminateAll(): Promise<void> {
+		for (const set of this.inflight.values()) {
+			for (const controller of set) controller.abort();
+		}
+		this.inflight.clear();
+	}
+
+	/** Create a per-turn controller bound to `sessionId`, optionally chained to an external signal. */
+	protected trackTurn(sessionId: string, external?: AbortSignal): AbortController {
+		const controller = new AbortController();
+		let set = this.inflight.get(sessionId);
+		if (!set) {
+			set = new Set();
+			this.inflight.set(sessionId, set);
+		}
+		set.add(controller);
+		if (external) {
+			if (external.aborted) controller.abort();
+			else external.addEventListener("abort", () => controller.abort(), { once: true });
+		}
+		return controller;
+	}
+
+	protected endTurn(sessionId: string, controller?: AbortController): void {
+		const set = this.inflight.get(sessionId);
+		if (!set) return;
+		if (controller) set.delete(controller);
+		else set.clear();
+		if (set.size === 0) this.inflight.delete(sessionId);
+	}
+}