@zvada/agent-server 0.2.0

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

@@ -0,0 +1,322 @@
+import type {
+	InitializeResponse,
+	PromptRequest,
+	RequestPermissionRequest,
+	RequestPermissionResponse,
+} from "@agentclientprotocol/sdk";
+import type { AgentCapabilities, AgentInput, PermissionMode } from "../../../protocol/index.ts";
+import { AsyncQueue } from "../../../protocol/index.ts";
+import type { AgentExecuteOptions, PermissionRequestHandler, RawAgentEvent } from "../base.ts";
+import { BaseAgent } from "../base.ts";
+import { configFingerprint } from "../config-fingerprint.ts";
+import { SessionStore } from "../session-store.ts";
+import { AcpClient, type AcpClientOptions, type AcpLaunch } from "./client.ts";
+import {
+	CANCELLED_OUTCOME,
+	autoDecide,
+	chooseOutcome,
+	permissionToolCall,
+	toAcpMcpServers,
+	toPromptBlocks,
+} from "./mappings.ts";
+
+const CAPABILITIES: AgentCapabilities = {
+	multiTurn: true,
+	// The engine always *accepts* resumeSessionId; whether context actually
+	// survives depends on the target agent's `sessionCapabilities.resume`
+	// (falls back to a fresh session when unsupported).
+	sessionResume: true,
+	// v1 exposes model selection only through agent-defined config options;
+	// there is no portable model parameter to pass through yet.
+	modelSwitch: "unsupported",
+	thinkingLevels: false,
+	images: true,
+	mcpServers: true,
+	permissionRequests: true,
+};
+
+/** ACP protocol major version this harness speaks. */
+const PROTOCOL_VERSION = 1;
+
+/** Idle time before an unused agent subprocess is shut down. */
+const IDLE_TIMEOUT_MS = 5 * 60_000;
+
+/** How long a cancelled prompt may take to resolve before the turn is failed. */
+const CANCEL_GRACE_MS = 10_000;
+
+/** Deadline for `initialize` on a freshly spawned agent (mirrors codex startup). */
+const INITIALIZE_TIMEOUT_MS = 15_000;
+
+/** Deadline for session lifecycle requests (`session/new`, `session/resume`). */
+const SESSION_REQUEST_TIMEOUT_MS = 30_000;
+
+export interface AcpAgentOptions {
+	/**
+	 * Resolve the ACP agent subprocess to launch. Operator-level only — never
+	 * sourced from the wire (the command is arbitrary code execution).
+	 */
+	resolveLaunch: () => Promise<AcpLaunch | undefined> | AcpLaunch | undefined;
+	/** `clientInfo.name` advertised to agents. */
+	clientName?: string;
+	idleTimeoutMs?: number;
+	/** Grace period for a `session/cancel` to resolve the in-flight prompt. */
+	cancelGraceMs?: number;
+	/** Injectable client factory for deterministic tests. */
+	createClient?: (options: AcpClientOptions) => Promise<AcpClient>;
+}
+
+/** Permission context of the turn currently running on a session — set and
+ * cleared as ONE value so stale partial state (an authorization bypass) is
+ * unrepresentable. `undefined` between turns → the auto policy rejects. */
+interface TurnPermissions {
+	broker?: PermissionRequestHandler;
+	mode?: PermissionMode;
+	signal?: AbortSignal;
+}
+
+interface AcpSession {
+	client: AcpClient;
+	acpSessionId: string;
+	cwd: string;
+	envFingerprint: string;
+	mcpFingerprint: string;
+	launchFingerprint: string;
+	/** From `initialize`: whether the agent accepts image content blocks. */
+	imagesSupported: boolean;
+	turn?: TurnPermissions;
+	idleTimer?: ReturnType<typeof setTimeout>;
+}
+
+export function acpSessionCompatible(
+	existing: AcpSession | undefined,
+	options: AgentExecuteOptions,
+	launchFingerprint: string,
+): boolean {
+	return Boolean(
+		existing &&
+			!existing.client.closed &&
+			existing.cwd === options.cwd &&
+			existing.envFingerprint === configFingerprint(options.env) &&
+			existing.mcpFingerprint === configFingerprint(options.mcpServers) &&
+			existing.launchFingerprint === launchFingerprint &&
+			(!options.resumeSessionId || options.resumeSessionId === existing.acpSessionId),
+	);
+}
+
+/** Answer an agent permission request against the session's current turn. */
+export async function answerPermission(
+	session: AcpSession,
+	request: RequestPermissionRequest,
+): Promise<RequestPermissionResponse> {
+	if (request.sessionId !== session.acpSessionId) return CANCELLED_OUTCOME;
+	const turn = session.turn;
+	const asks = (turn?.mode ?? "default") === "default";
+	if (!turn?.broker || !asks) return autoDecide(request, turn?.mode);
+	const decision = await turn.broker(permissionToolCall(request), { signal: turn.signal });
+	if (decision.decision === "cancel") return CANCELLED_OUTCOME;
+	return chooseOutcome(request.options, decision.decision === "allow");
+}
+
+/**
+ * ACP harness: drives any Agent Client Protocol v1 agent as a long-lived
+ * subprocess (one per logical session, reused across turns). The launch
+ * command comes from the operator's `resolveLaunch`; `initialize` negotiates
+ * the protocol version and gates optional features (resume, images) on the
+ * agent's advertised capabilities. The turn's stopReason arrives as the
+ * `session/prompt` *response*, so `execute` re-injects it into the raw stream
+ * as a synthetic `session/prompt_result` event for the adapter.
+ */
+export class AcpAgent extends BaseAgent {
+	readonly harness = "acp" as const;
+	readonly capabilities = CAPABILITIES;
+	private readonly sessions = new SessionStore<AcpSession>();
+
+	constructor(private readonly agentOptions: AcpAgentOptions) {
+		super();
+	}
+
+	private async resolveSession(options: AgentExecuteOptions): Promise<AcpSession> {
+		const launch = await this.agentOptions.resolveLaunch();
+		if (!launch) {
+			throw new Error(
+				"acp harness is not configured: resolveLaunch returned no agent launch command",
+			);
+		}
+		const launchFingerprint = configFingerprint({
+			command: launch.command,
+			args: launch.args?.join(" ") ?? "",
+			...launch.env,
+		});
+
+		const existing = this.sessions.get(options.sessionId);
+		let resumeTarget = options.resumeSessionId;
+		if (existing && !existing.client.closed) {
+			if (acpSessionCompatible(existing, options, launchFingerprint)) {
+				this.sessions.clearIdle(existing);
+				return existing;
+			}
+			// Preserve context within the same cwd/env boundary when the agent can
+			// resume (mirrors the claude-code/codex restart policy).
+			if (
+				resumeTarget === undefined &&
+				existing.cwd === options.cwd &&
+				existing.envFingerprint === configFingerprint(options.env)
+			) {
+				resumeTarget = existing.acpSessionId;
+			}
+			this.sessions.close(options.sessionId);
+		}
+
+		const clientOptions: AcpClientOptions = {
+			launch,
+			cwd: options.cwd,
+			env: options.env,
+			clientName: this.agentOptions.clientName,
+		};
+		const client = this.agentOptions.createClient
+			? await this.agentOptions.createClient(clientOptions)
+			: await AcpClient.create(clientOptions);
+		client.onClose(() => this.sessions.dropIfCurrent(options.sessionId, client));
+
+		let init: InitializeResponse;
+		let acpSessionId: string | undefined;
+		try {
+			init = await client.request(
+				"initialize",
+				{ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} },
+				INITIALIZE_TIMEOUT_MS,
+			);
+			const mcpServers = toAcpMcpServers(options.mcpServers);
+			if (resumeTarget && init.agentCapabilities?.sessionCapabilities?.resume) {
+				try {
+					await client.request(
+						"session/resume",
+						{ sessionId: resumeTarget, cwd: options.cwd, mcpServers },
+						SESSION_REQUEST_TIMEOUT_MS,
+					);
+					acpSessionId = resumeTarget;
+				} catch {
+					// Unknown/expired session id — fall through to a fresh one.
+				}
+			}
+			if (!acpSessionId) {
+				const created = await client.request(
+					"session/new",
+					{ cwd: options.cwd, mcpServers },
+					SESSION_REQUEST_TIMEOUT_MS,
+				);
+				acpSessionId = created.sessionId;
+			}
+			if (!acpSessionId) throw new Error("acp agent returned no session id");
+		} catch (error) {
+			client.close();
+			throw error;
+		}
+
+		const session: AcpSession = {
+			client,
+			acpSessionId,
+			cwd: options.cwd,
+			envFingerprint: configFingerprint(options.env),
+			mcpFingerprint: configFingerprint(options.mcpServers),
+			launchFingerprint,
+			imagesSupported: Boolean(init.agentCapabilities?.promptCapabilities?.image),
+		};
+		client.setPermissionHandler((request) => answerPermission(session, request));
+		this.sessions.set(options.sessionId, session);
+		return session;
+	}
+
+	async *execute(
+		input: AgentInput,
+		options: AgentExecuteOptions,
+	): AsyncIterableIterator<RawAgentEvent> {
+		const controller = this.trackTurn(options.sessionId, options.signal);
+		const queue = new AsyncQueue<RawAgentEvent>();
+		const unsubscribe: Array<() => void> = [];
+		let cancelTimer: ReturnType<typeof setTimeout> | undefined;
+		let session: AcpSession | undefined;
+		try {
+			session = await this.resolveSession(options);
+			session.turn = {
+				broker: options.onPermissionRequest,
+				mode: options.permissionMode,
+				signal: controller.signal,
+			};
+			options.onNativeSession?.(session.acpSessionId, {
+				resumed: session.acpSessionId === options.resumeSessionId,
+			});
+			const { client, acpSessionId } = session;
+
+			unsubscribe.push(
+				client.onSessionUpdate((notification) => {
+					if (notification.sessionId !== acpSessionId) return;
+					queue.push({ method: "session/update", params: notification });
+				}),
+			);
+			unsubscribe.push(
+				client.onClose((err) => queue.fail(err ?? new Error("acp agent exited mid-turn"))),
+			);
+
+			const onAbort = () => {
+				// ACP semantics: session/cancel makes the in-flight prompt resolve
+				// with stopReason=cancelled. Bound the wait for misbehaving agents.
+				void client.notify("session/cancel", { sessionId: acpSessionId });
+				cancelTimer = setTimeout(
+					() => queue.fail(new Error("acp agent ignored session/cancel")),
+					this.agentOptions.cancelGraceMs ?? CANCEL_GRACE_MS,
+				);
+				cancelTimer.unref?.();
+			};
+
+			if (controller.signal.aborted) {
+				// Aborted while the session was being set up (a listener added now
+				// would never fire) — never start the prompt at all.
+				queue.push({ method: "session/prompt_result", params: { stopReason: "cancelled" } });
+				queue.end();
+			} else {
+				controller.signal.addEventListener("abort", onAbort, { once: true });
+				const prompt: PromptRequest = {
+					sessionId: acpSessionId,
+					prompt: toPromptBlocks(input, session.imagesSupported),
+				};
+				client.request("session/prompt", prompt).then(
+					(response) => {
+						queue.push({ method: "session/prompt_result", params: response });
+						queue.end();
+					},
+					(error: unknown) => {
+						queue.push({ method: "error", params: { message: String(error) } });
+						queue.end();
+					},
+				);
+			}
+
+			for await (const event of queue) {
+				yield event;
+			}
+		} finally {
+			if (cancelTimer) clearTimeout(cancelTimer);
+			for (const off of unsubscribe) off();
+			if (session) session.turn = undefined;
+			this.endTurn(options.sessionId, controller);
+			if (session && !session.client.closed) {
+				this.sessions.armIdle(
+					options.sessionId,
+					session,
+					this.agentOptions.idleTimeoutMs ?? IDLE_TIMEOUT_MS,
+				);
+			}
+		}
+	}
+
+	override async release(sessionId: string): Promise<void> {
+		await super.release(sessionId);
+		this.sessions.close(sessionId);
+	}
+
+	override async terminateAll(): Promise<void> {
+		await super.terminateAll();
+		this.sessions.closeAll();
+	}
+}

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

@@ -0,0 +1,260 @@
+import type {
+	ContentBlock,
+	PromptResponse,
+	SessionNotification,
+	SessionUpdate,
+	ToolCallContent,
+	ToolCallUpdate,
+} from "@agentclientprotocol/sdk";
+import {
+	DEFAULT_TOKEN_USAGE,
+	type ReasoningPart,
+	STOP_REASONS,
+	type StopReason,
+	type StreamContext,
+	type TextPart,
+	type ToolPart,
+	completeToolPart,
+	createReasoningPart,
+	createTextPart,
+	createToolPart,
+	setToolMeta,
+	startToolPart,
+} from "../../../protocol/index.ts";
+import type { AdapterEvent, EventTransformer, TransformResult } from "../types.ts";
+import { isRecord, toToolLocations, toolKindOf } from "./mappings.ts";
+
+/**
+ * Parses ACP v1 raw events into AdapterEvents. The mapping is nearly identity:
+ * our part vocabulary (ToolKind, tool status, locations) was aligned to ACP up
+ * front (DESIGN D2), so chunks append to text/reasoning parts and
+ * `tool_call`/`tool_call_update` upsert tool parts by `toolCallId`. Everything
+ * arrives through the SDK connection, which zod-validates inbound payloads —
+ * so the SDK's own types ARE the raw shapes (no defensive re-modelling).
+ *
+ * Raw events are the shapes AcpAgent yields:
+ *  - `{method: "session/update", params: SessionNotification}`
+ *  - `{method: "session/prompt_result", params: PromptResponse}` (synthetic —
+ *    ACP returns the turn's stopReason as the prompt *response*, not as a
+ *    notification, so the agent re-injects it into the event stream)
+ *  - `{method: "error", params: {message}}` (synthetic, prompt failure)
+ *
+ * v1 `messageId` on chunks is optional: when present, a change opens a new
+ * wire message; when absent the whole turn is one message (the processor
+ * synthesizes the boundary).
+ */
+type RawEvent =
+	| { method: "session/update"; params: SessionNotification }
+	| { method: "session/prompt_result"; params: Partial<PromptResponse> }
+	| { method: "error"; params: { message?: string } };
+
+function stopReasonOf(value: string | undefined): StopReason | undefined {
+	return value && (STOP_REASONS as readonly string[]).includes(value)
+		? (value as StopReason)
+		: undefined;
+}
+
+/** Flatten a tool call's content blocks (plus rawOutput) into one output string. */
+function toolOutput(content: ToolCallContent[] | null | undefined, rawOutput: unknown): string {
+	const texts = (content ?? [])
+		.map((item) =>
+			item.type === "content" && item.content.type === "text" ? item.content.text : "",
+		)
+		.filter(Boolean);
+	if (texts.length) return texts.join("\n");
+	return rawOutput !== undefined && rawOutput !== null ? JSON.stringify(rawOutput) : "";
+}
+
+type StreamSlot = "text" | "reasoning";
+
+export class AcpTransformer implements EventTransformer<unknown> {
+	private readonly ctx: StreamContext;
+	private readonly toolParts = new Map<string, ToolPart>();
+	private readonly streamParts = new Map<StreamSlot, TextPart | ReasoningPart>();
+	/** messageId of the currently open wire message (undefined = implicit single message). */
+	private currentMessageId?: string;
+	private messageOpen = false;
+
+	private stopReason?: StopReason;
+	private finishReason?: string;
+	private error?: string;
+
+	constructor(ctx: { sessionId: string }) {
+		this.ctx = { sessionId: ctx.sessionId, messageId: "" };
+	}
+
+	process(raw: unknown): AdapterEvent[] {
+		const event = raw as RawEvent;
+		switch (event.method) {
+			case "session/update":
+				return this.onUpdate(event.params.update);
+			case "session/prompt_result":
+				this.stopReason = stopReasonOf(event.params.stopReason);
+				this.finishReason = event.params.stopReason;
+				return this.finalizeStreamingParts();
+			case "error":
+				this.error = event.params.message ?? "acp agent error";
+				this.finishReason = "error";
+				// A failed prompt still closes any parts left streaming.
+				return this.finalizeStreamingParts();
+			default:
+				return [];
+		}
+	}
+
+	finish(): TransformResult {
+		// ACP v1 has no per-turn token usage (the end-turn-token-usage RFD is
+		// still draft); `usage_update` is a context-window gauge, not a bill.
+		return {
+			usage: { ...DEFAULT_TOKEN_USAGE },
+			stopReason: this.stopReason,
+			finishReason: this.finishReason,
+			error: this.error,
+		};
+	}
+
+	private onUpdate(update: SessionUpdate): AdapterEvent[] {
+		switch (update.sessionUpdate) {
+			case "agent_message_chunk":
+				return this.chunk("text", update.content, update.messageId);
+			case "agent_thought_chunk":
+				return this.chunk("reasoning", update.content, update.messageId);
+			case "tool_call":
+				return this.toolCall(update);
+			case "tool_call_update":
+				return this.toolCallUpdate(update);
+			case "usage_update": {
+				// ACP's stable context gauge maps 1:1 onto session.usage. ACP cost is
+				// {amount, currency}; ours is a bare USD number — map USD only.
+				const usd = update.cost?.currency === "USD" ? update.cost.amount : undefined;
+				return [
+					{
+						kind: "usage",
+						used: update.used,
+						size: update.size,
+						...(usd !== undefined && { cost: usd }),
+					},
+				];
+			}
+			default:
+				// plan / available_commands / current_mode / config_option /
+				// session_info / usage updates have no part representation yet;
+				// `includeRaw` consumers still see them.
+				return [];
+		}
+	}
+
+	private chunk(
+		slot: StreamSlot,
+		content: ContentBlock,
+		messageId: string | null | undefined,
+	): AdapterEvent[] {
+		if (content.type !== "text" || !content.text) return [];
+		const events: AdapterEvent[] = [...this.rolloverMessage(messageId ?? undefined)];
+		let part = this.streamParts.get(slot);
+		if (!part) {
+			part =
+				slot === "text"
+					? createTextPart(this.ctx, "", true)
+					: createReasoningPart(this.ctx, "", true);
+			this.streamParts.set(slot, part);
+			events.push({ kind: "part-open", part });
+		}
+		part.text += content.text;
+		events.push(
+			slot === "text"
+				? { kind: "text-delta", partId: part.id, text: content.text }
+				: { kind: "reasoning-delta", partId: part.id, text: content.text },
+		);
+		return events;
+	}
+
+	private toolCall(update: ToolCallUpdate): AdapterEvent[] {
+		if (this.toolParts.has(update.toolCallId)) return this.toolCallUpdate(update); // duplicate open
+		const part = this.openTool(update);
+		const events: AdapterEvent[] = [{ kind: "part-open", part }];
+		if (this.applyToolUpdate(part, update)) events.push({ kind: "part-update", part });
+		return events;
+	}
+
+	private toolCallUpdate(update: ToolCallUpdate): AdapterEvent[] {
+		// Update before (or without) its tool_call — open a part so nothing is lost.
+		const part = this.toolParts.get(update.toolCallId) ?? this.openTool(update);
+		this.applyToolUpdate(part, update);
+		return [{ kind: "part-update", part }];
+	}
+
+	private openTool(update: ToolCallUpdate): ToolPart {
+		const part = createToolPart(
+			this.ctx,
+			update.toolCallId,
+			update.name ?? update.title ?? "tool",
+			isRecord(update.rawInput) ? update.rawInput : {},
+			{
+				kind: toolKindOf(update.kind),
+				title: update.title ?? undefined,
+				locations: toToolLocations(update.locations),
+			},
+		);
+		this.toolParts.set(update.toolCallId, part);
+		return part;
+	}
+
+	/** Fold an update's meta/input/status into the part; true when it just completed. */
+	private applyToolUpdate(part: ToolPart, update: ToolCallUpdate): boolean {
+		setToolMeta(part, {
+			kind: toolKindOf(update.kind),
+			title: update.title ?? undefined,
+			locations: toToolLocations(update.locations),
+		});
+		const terminal = part.state.status === "completed" || part.state.status === "failed";
+		if (terminal) return false;
+		if (isRecord(update.rawInput)) {
+			if (part.state.status === "pending") startToolPart(part, update.rawInput);
+			else part.state.input = update.rawInput;
+		}
+		if (update.status !== "completed" && update.status !== "failed") return false;
+		completeToolPart(part, {
+			output: toolOutput(update.content, update.rawOutput),
+			isError: update.status === "failed",
+		});
+		return true;
+	}
+
+	/** A new v1 `messageId` closes the current wire message and opens the next. */
+	private rolloverMessage(messageId: string | undefined): AdapterEvent[] {
+		if (!messageId) {
+			// No id: everything belongs to one implicit message; open it lazily so
+			// the assistant role is explicit (parts still work without it).
+			if (this.messageOpen) return [];
+			this.messageOpen = true;
+			return [{ kind: "message-start", role: "assistant" }];
+		}
+		if (messageId === this.currentMessageId) return [];
+		const events: AdapterEvent[] = [];
+		if (this.messageOpen) {
+			events.push(...this.finalizeStreamingParts(), { kind: "message-end" });
+		}
+		this.currentMessageId = messageId;
+		this.messageOpen = true;
+		this.streamParts.clear();
+		events.push({ kind: "message-start", role: "assistant" });
+		return events;
+	}
+
+	/** Mark still-streaming text/reasoning parts done (turn or message boundary). */
+	private finalizeStreamingParts(): AdapterEvent[] {
+		const events: AdapterEvent[] = [];
+		for (const part of this.streamParts.values()) {
+			if (part.state === "streaming") {
+				part.state = "done";
+				events.push({ kind: "part-update", part });
+			}
+		}
+		return events;
+	}
+}
+
+export function createAcpTransformer(ctx: { sessionId: string }): EventTransformer {
+	return new AcpTransformer(ctx);
+}