@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/engine/acp/transport.ts

@@ -0,0 +1,654 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import type { Readable, Writable } from "node:stream";
+import { MAX_TIMER_DELAY_MS } from "../../core/timers.js";
+import { AcpProcessError, AcpProtocolError, AcpTimeoutError } from "./errors.js";
+import type { AcpJsonRpcFailure, AcpJsonRpcMessage, AcpJsonRpcSuccess } from "./types.js";
+
+type NotificationHandler = (params: unknown) => void;
+type RequestHandler = (params: unknown) => Promise<unknown> | unknown;
+type StderrHandler = (chunk: string) => void;
+type CloseHandler = () => void;
+
+interface PendingRequest {
+	resolve(value: unknown): void;
+	reject(reason: unknown): void;
+	timer?: ReturnType<typeof setTimeout>;
+	method: string;
+}
+
+export interface AcpJsonRpcTransport {
+	readonly closed: boolean;
+	readonly pid: number | null;
+	/**
+	 * Scope owned by this transport's force-termination path. POSIX transports
+	 * own a dedicated process group and cover descendants that remain in that
+	 * group. Descendants that create a new session/process group are outside the
+	 * owned scope. Windows can signal only the direct child.
+	 */
+	readonly terminationScope: AcpTerminationScope;
+	request<T>(method: string, params?: unknown, timeoutMs?: number): Promise<T>;
+	notify(method: string, params?: unknown): void;
+	onNotification(method: string, handler: NotificationHandler): () => void;
+	onRequest(method: string, handler: RequestHandler): () => void;
+	onStderr(handler: StderrHandler): () => void;
+	/** Close the JSON-RPC channel cooperatively by ending stdin. Sends no signal. */
+	close(): void;
+	/** Observe owned process/stdio closure for a bounded interval without signalling. */
+	waitForExit(timeoutMs: number): Promise<boolean>;
+	/** End the channel and send one SIGTERM without waiting or escalating. */
+	terminate(): void;
+	/** SIGTERM, bounded grace, SIGKILL fallback, then a bounded exit observation. */
+	forceTerminate(): Promise<AcpForceTerminationResult>;
+}
+
+export type AcpTerminationScope = "process-group" | "child";
+
+export interface AcpForceTerminationResult {
+	/** True only when the owned process scope and the direct child's stdio handles were observed closed. */
+	exited: boolean;
+	/** True when the SIGTERM grace expired and SIGKILL was sent. */
+	escalated: boolean;
+	/** Exact scope the implementation was able to signal. */
+	scope: AcpTerminationScope;
+}
+
+export interface AcpJsonRpcPeerTransport {
+	readonly closed: boolean;
+	request<T>(method: string, params?: unknown, timeoutMs?: number): Promise<T>;
+	notify(method: string, params?: unknown): void;
+	onNotification(method: string, handler: NotificationHandler): () => void;
+	onRequest(method: string, handler: RequestHandler): () => void;
+	onClose(handler: CloseHandler): () => void;
+	close(): void;
+}
+
+export interface StdioTransportOptions {
+	cwd?: string;
+	env?: Record<string, string>;
+	/** SIGTERM grace before SIGKILL. Defaults to 500ms. */
+	terminationGraceMs?: number;
+	/** Maximum post-SIGKILL wait for process/handle closure. Defaults to 2s. */
+	terminationWaitMs?: number;
+}
+
+export interface StdioServerTransportOptions {
+	input?: Readable;
+	output?: Writable;
+	write?: (chunk: string) => void;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isSuccess(value: Record<string, unknown>): value is Record<string, unknown> & AcpJsonRpcSuccess {
+	return "id" in value && "result" in value;
+}
+
+function isFailure(value: Record<string, unknown>): value is Record<string, unknown> & AcpJsonRpcFailure {
+	return "id" in value && isRecord(value.error);
+}
+
+function errorMessage(value: unknown): string {
+	return value instanceof Error ? value.message : String(value);
+}
+
+function errorCode(value: unknown): string | undefined {
+	return isRecord(value) && typeof value.code === "string" ? value.code : undefined;
+}
+
+function boundedMilliseconds(value: number | undefined, fallback: number): number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+/**
+ * An omitted low-level timeout remains available for lifecycle calls whose
+ * owner supplies another bound. An explicit timeout, however, must be a real
+ * bound; accepting zero here previously turned valid application settings
+ * into requests that could wait forever.
+ */
+function validateRequestTimeout(method: string, timeoutMs: number | undefined): number | undefined {
+	if (timeoutMs === undefined) return undefined;
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_TIMER_DELAY_MS) {
+		throw new AcpTimeoutError(`ACP request timeout must be between 1 and ${MAX_TIMER_DELAY_MS} ms: ${method}`);
+	}
+	return timeoutMs;
+}
+
+function jsonRpcError(id: string | number | null, code: number, message: string, data?: unknown): AcpJsonRpcFailure {
+	return {
+		jsonrpc: "2.0",
+		id,
+		error: data === undefined ? { code, message } : { code, message, data },
+	};
+}
+
+class StdioJsonRpcTransport implements AcpJsonRpcTransport {
+	readonly child: ChildProcessWithoutNullStreams;
+	readonly terminationScope: AcpTerminationScope = process.platform === "win32" ? "child" : "process-group";
+	private nextId = 1;
+	private buffer = "";
+	private isClosed = false;
+	private inputEnded = false;
+	private childHandlesClosed = false;
+	private forceTermination: Promise<AcpForceTerminationResult> | null = null;
+	private readonly terminationGraceMs: number;
+	private readonly terminationWaitMs: number;
+	private readonly childClosePromise: Promise<void>;
+	private resolveChildClose: (() => void) | null = null;
+	private readonly pending = new Map<string | number, PendingRequest>();
+	private readonly notificationHandlers = new Map<string, Set<NotificationHandler>>();
+	private readonly requestHandlers = new Map<string, RequestHandler>();
+	private readonly stderrHandlers = new Set<StderrHandler>();
+
+	constructor(command: string, args: string[], options: StdioTransportOptions = {}) {
+		this.terminationGraceMs = boundedMilliseconds(options.terminationGraceMs, 500);
+		this.terminationWaitMs = boundedMilliseconds(options.terminationWaitMs, 2_000);
+		this.childClosePromise = new Promise((resolve) => {
+			this.resolveChildClose = resolve;
+		});
+		this.child = spawn(command, args, {
+			cwd: options.cwd,
+			env: options.env ? { ...process.env, ...options.env } : process.env,
+			stdio: ["pipe", "pipe", "pipe"],
+			// POSIX detached children lead a new session/process group whose id is
+			// the child pid. That makes negative-pid signaling safe for this owned
+			// group. Windows detached semantics do not provide an equivalent
+			// killable tree, so the explicit fallback there is the direct child.
+			detached: process.platform !== "win32",
+		});
+		this.child.stdout.setEncoding("utf8");
+		this.child.stderr.setEncoding("utf8");
+		this.child.stdout.on("data", (chunk: string) => this.consumeStdout(chunk));
+		this.child.stderr.on("data", (chunk: string) => {
+			for (const handler of this.stderrHandlers) handler(chunk);
+		});
+		this.child.on("error", (err) => {
+			this.closeChannel(new AcpProcessError(`ACP process error: ${errorMessage(err)}`));
+		});
+		this.child.on("exit", (code, signal) => {
+			this.isClosed = true;
+			if (this.pending.size === 0) return;
+			const reason = new AcpProcessError(
+				`ACP process exited before replying (code=${code ?? "null"}, signal=${signal ?? "null"})`,
+			);
+			this.failAll(reason);
+		});
+		this.child.on("close", () => {
+			this.childHandlesClosed = true;
+			this.isClosed = true;
+			this.resolveChildClose?.();
+			this.resolveChildClose = null;
+		});
+		// Closing stdin during termination can race a peer exit. Consume the
+		// resulting EPIPE instead of letting an unhandled stream error escape.
+		this.child.stdin.on("error", (err) => {
+			if (!this.isClosed) this.closeChannel(new AcpProcessError(`ACP stdin error: ${errorMessage(err)}`));
+		});
+	}
+
+	get closed(): boolean {
+		return this.isClosed || this.child.exitCode !== null || this.child.signalCode !== null;
+	}
+
+	get pid(): number | null {
+		return this.child.pid ?? null;
+	}
+
+	request<T>(method: string, params?: unknown, timeoutMs?: number): Promise<T> {
+		if (this.closed) throw new AcpProcessError(`ACP process is closed; cannot request ${method}`);
+		const requestTimeoutMs = validateRequestTimeout(method, timeoutMs);
+		const id = this.nextId++;
+		const message = { jsonrpc: "2.0" as const, id, method, params };
+		const promise = new Promise<T>((resolve, reject) => {
+			const pending: PendingRequest = {
+				method,
+				resolve: (value) => resolve(value as T),
+				reject,
+			};
+			if (requestTimeoutMs !== undefined) {
+				// The timer must hold the event loop: its firing is the only
+				// thing that resolves a request the peer never answers. It is
+				// cleared on response and by failAll on close.
+				pending.timer = setTimeout(() => {
+					this.pending.delete(id);
+					reject(new AcpTimeoutError(`ACP request timed out after ${requestTimeoutMs}ms: ${method}`));
+				}, requestTimeoutMs);
+			}
+			this.pending.set(id, pending);
+		});
+		this.write(message);
+		return promise;
+	}
+
+	notify(method: string, params?: unknown): void {
+		if (this.closed) return;
+		this.write({ jsonrpc: "2.0" as const, method, params });
+	}
+
+	onNotification(method: string, handler: NotificationHandler): () => void {
+		const handlers = this.notificationHandlers.get(method) ?? new Set<NotificationHandler>();
+		handlers.add(handler);
+		this.notificationHandlers.set(method, handlers);
+		return () => {
+			handlers.delete(handler);
+		};
+	}
+
+	onRequest(method: string, handler: RequestHandler): () => void {
+		this.requestHandlers.set(method, handler);
+		return () => {
+			if (this.requestHandlers.get(method) === handler) this.requestHandlers.delete(method);
+		};
+	}
+
+	onStderr(handler: StderrHandler): () => void {
+		this.stderrHandlers.add(handler);
+		return () => {
+			this.stderrHandlers.delete(handler);
+		};
+	}
+
+	close(): void {
+		this.closeChannel(new AcpProcessError("ACP transport closed"));
+	}
+
+	terminate(): void {
+		this.closeChannel(new AcpProcessError("ACP transport terminated"));
+		this.signalOwnedScope("SIGTERM");
+	}
+
+	forceTerminate(): Promise<AcpForceTerminationResult> {
+		if (this.forceTermination !== null) return this.forceTermination;
+		this.forceTermination = this.runForceTermination();
+		return this.forceTermination;
+	}
+
+	waitForExit(timeoutMs: number): Promise<boolean> {
+		return this.waitForTermination(boundedMilliseconds(timeoutMs, 0));
+	}
+
+	private write(message: AcpJsonRpcMessage): void {
+		if (this.closed || !this.child.stdin.writable || this.child.stdin.destroyed) return;
+		try {
+			this.child.stdin.write(`${JSON.stringify(message)}\n`);
+		} catch (err) {
+			this.closeChannel(new AcpProcessError(`ACP stdin write failed: ${errorMessage(err)}`));
+		}
+	}
+
+	private consumeStdout(chunk: string): void {
+		this.buffer += chunk;
+		for (;;) {
+			const idx = this.buffer.indexOf("\n");
+			if (idx === -1) break;
+			const line = this.buffer.slice(0, idx).trimEnd();
+			this.buffer = this.buffer.slice(idx + 1);
+			if (line.length === 0) continue;
+			this.handleLine(line);
+		}
+	}
+
+	private handleLine(line: string): void {
+		const trimmed = line.trimStart();
+		if (!trimmed.startsWith("{")) {
+			return;
+		}
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(trimmed);
+		} catch (err) {
+			this.failAll(new AcpProtocolError(`ACP stdout contained invalid JSON: ${errorMessage(err)}`, { line }));
+			return;
+		}
+		if (!isRecord(parsed) || parsed.jsonrpc !== "2.0") {
+			return;
+		}
+		if (isSuccess(parsed) || isFailure(parsed)) {
+			this.handleResponse(parsed);
+			return;
+		}
+		const method = typeof parsed.method === "string" ? parsed.method : "";
+		if (!method) {
+			this.failAll(new AcpProtocolError("ACP request/notification missing method", parsed));
+			return;
+		}
+		if ("id" in parsed) {
+			void this.handleIncomingRequest(parsed.id as string | number, method, parsed.params);
+			return;
+		}
+		const handlers = this.notificationHandlers.get(method);
+		if (!handlers) return;
+		for (const handler of handlers) handler(parsed.params);
+	}
+
+	private handleResponse(message: AcpJsonRpcSuccess | AcpJsonRpcFailure): void {
+		const pending = this.pending.get(message.id ?? "");
+		if (!pending) return;
+		this.pending.delete(message.id ?? "");
+		if (pending.timer) clearTimeout(pending.timer);
+		if ("error" in message) {
+			pending.reject(new AcpProtocolError(`ACP ${pending.method} failed: ${message.error.message}`, message.error));
+			return;
+		}
+		pending.resolve(message.result);
+	}
+
+	private async handleIncomingRequest(id: string | number, method: string, params: unknown): Promise<void> {
+		const handler = this.requestHandlers.get(method);
+		if (!handler) {
+			this.write({
+				jsonrpc: "2.0",
+				id,
+				error: { code: -32601, message: `method not found: ${method}` },
+			});
+			return;
+		}
+		try {
+			const result = await handler(params);
+			this.write({ jsonrpc: "2.0", id, result });
+		} catch (err) {
+			this.write({
+				jsonrpc: "2.0",
+				id,
+				error: { code: -32000, message: errorMessage(err), data: err instanceof Error ? err.stack : undefined },
+			});
+		}
+	}
+
+	private closeChannel(reason: unknown): void {
+		if (!this.isClosed) {
+			this.isClosed = true;
+			this.failAll(reason);
+		}
+		if (this.inputEnded) return;
+		this.inputEnded = true;
+		try {
+			this.child.stdin.end();
+		} catch {
+			// The peer may have closed stdin concurrently.
+		}
+	}
+
+	private directChildAlive(): boolean {
+		return !this.childHandlesClosed && this.child.exitCode === null && this.child.signalCode === null;
+	}
+
+	private processGroupAlive(): boolean {
+		if (this.terminationScope !== "process-group") return this.directChildAlive();
+		const pid = this.pid;
+		if (pid === null) return this.directChildAlive();
+		try {
+			process.kill(-pid, 0);
+			return true;
+		} catch (err) {
+			const code = errorCode(err);
+			if (code === "ESRCH") return false;
+			// EPERM means the scope exists but cannot be signalled. Unknown errors
+			// are also treated as alive so force termination never reports success
+			// without observing disappearance.
+			return true;
+		}
+	}
+
+	private terminationObserved(): boolean {
+		return this.childHandlesClosed && !this.processGroupAlive();
+	}
+
+	private signalOwnedScope(signal: NodeJS.Signals): boolean {
+		const pid = this.pid;
+		if (this.terminationScope === "process-group" && pid !== null) {
+			try {
+				process.kill(-pid, signal);
+				return true;
+			} catch {
+				// Fall through to direct-child signaling. This cannot cover the
+				// group, but it is still safer than abandoning a live leader.
+			}
+		}
+		if (!this.directChildAlive()) return false;
+		try {
+			return this.child.kill(signal);
+		} catch {
+			// The child may exit between the liveness check and signal.
+			return false;
+		}
+	}
+
+	private async waitForTermination(timeoutMs: number): Promise<boolean> {
+		// Monotonic deadline: a backward wall-clock step used to extend this wait
+		// past the bound the caller asked for.
+		const deadline = performance.now() + timeoutMs;
+		while (!this.terminationObserved()) {
+			const remaining = deadline - performance.now();
+			if (remaining <= 0) return this.terminationObserved();
+			const interval = Math.min(10, remaining);
+			if (this.childHandlesClosed) {
+				await new Promise<void>((resolve) => setTimeout(resolve, interval));
+			} else {
+				await Promise.race([this.childClosePromise, new Promise<void>((resolve) => setTimeout(resolve, interval))]);
+			}
+		}
+		return true;
+	}
+
+	private async runForceTermination(): Promise<AcpForceTerminationResult> {
+		this.closeChannel(new AcpProcessError("ACP transport force-terminated"));
+		if (this.terminationObserved()) {
+			return { exited: true, escalated: false, scope: this.terminationScope };
+		}
+
+		this.signalOwnedScope("SIGTERM");
+		if (await this.waitForExit(this.terminationGraceMs)) {
+			return { exited: true, escalated: false, scope: this.terminationScope };
+		}
+
+		const escalated = this.signalOwnedScope("SIGKILL");
+		const exited = await this.waitForExit(this.terminationWaitMs);
+		return { exited, escalated, scope: this.terminationScope };
+	}
+
+	private failAll(reason: unknown): void {
+		for (const [id, pending] of this.pending.entries()) {
+			if (pending.timer) clearTimeout(pending.timer);
+			pending.reject(reason);
+			this.pending.delete(id);
+		}
+	}
+}
+
+export function createStdioTransport(
+	command: string,
+	args: string[] = [],
+	options: StdioTransportOptions = {},
+): AcpJsonRpcTransport {
+	if (command.trim().length === 0) {
+		throw new AcpProcessError("ACP stdio command must not be empty");
+	}
+	return new StdioJsonRpcTransport(command, args, options);
+}
+
+class StreamJsonRpcPeerTransport implements AcpJsonRpcPeerTransport {
+	private nextId = 1;
+	private buffer = "";
+	private isClosed = false;
+	private readonly pending = new Map<string | number, PendingRequest>();
+	private readonly notificationHandlers = new Map<string, Set<NotificationHandler>>();
+	private readonly requestHandlers = new Map<string, RequestHandler>();
+	private readonly closeHandlers = new Set<CloseHandler>();
+	private readonly input: Readable;
+	private readonly output: Writable;
+	private readonly writeOverride?: (chunk: string) => void;
+
+	constructor(options: StdioServerTransportOptions = {}) {
+		this.input = options.input ?? process.stdin;
+		this.output = options.output ?? process.stdout;
+		if (options.write !== undefined) this.writeOverride = options.write;
+		this.input.setEncoding("utf8");
+		this.input.on("data", (chunk: string) => this.consume(chunk));
+		this.input.on("end", () => this.markClosed(new AcpProcessError("ACP input closed")));
+		this.input.on("error", (err) => this.markClosed(new AcpProcessError(`ACP input error: ${errorMessage(err)}`)));
+		this.output.on?.("error", (err) => this.markClosed(new AcpProcessError(`ACP output error: ${errorMessage(err)}`)));
+	}
+
+	get closed(): boolean {
+		return this.isClosed;
+	}
+
+	request<T>(method: string, params?: unknown, timeoutMs?: number): Promise<T> {
+		if (this.closed) throw new AcpProcessError(`ACP transport is closed; cannot request ${method}`);
+		const requestTimeoutMs = validateRequestTimeout(method, timeoutMs);
+		const id = this.nextId++;
+		const message = { jsonrpc: "2.0" as const, id, method, params };
+		const promise = new Promise<T>((resolve, reject) => {
+			const pending: PendingRequest = {
+				method,
+				resolve: (value) => resolve(value as T),
+				reject,
+			};
+			if (requestTimeoutMs !== undefined) {
+				// The timer must hold the event loop: its firing is the only
+				// thing that resolves a request the peer never answers. It is
+				// cleared on response and by failAll on close.
+				pending.timer = setTimeout(() => {
+					this.pending.delete(id);
+					reject(new AcpTimeoutError(`ACP request timed out after ${requestTimeoutMs}ms: ${method}`));
+				}, requestTimeoutMs);
+			}
+			this.pending.set(id, pending);
+		});
+		this.write(message);
+		return promise;
+	}
+
+	notify(method: string, params?: unknown): void {
+		if (this.closed) return;
+		this.write({ jsonrpc: "2.0", method, params });
+	}
+
+	onNotification(method: string, handler: NotificationHandler): () => void {
+		const handlers = this.notificationHandlers.get(method) ?? new Set<NotificationHandler>();
+		handlers.add(handler);
+		this.notificationHandlers.set(method, handlers);
+		return () => {
+			handlers.delete(handler);
+		};
+	}
+
+	onRequest(method: string, handler: RequestHandler): () => void {
+		this.requestHandlers.set(method, handler);
+		return () => {
+			if (this.requestHandlers.get(method) === handler) this.requestHandlers.delete(method);
+		};
+	}
+
+	onClose(handler: CloseHandler): () => void {
+		this.closeHandlers.add(handler);
+		return () => {
+			this.closeHandlers.delete(handler);
+		};
+	}
+
+	close(): void {
+		this.markClosed(new AcpProcessError("ACP transport closed"));
+	}
+
+	private write(message: AcpJsonRpcMessage): void {
+		const line = `${JSON.stringify(message)}\n`;
+		if (this.writeOverride) {
+			this.writeOverride(line);
+			return;
+		}
+		this.output.write(line);
+	}
+
+	private consume(chunk: string): void {
+		this.buffer += chunk;
+		for (;;) {
+			const idx = this.buffer.indexOf("\n");
+			if (idx === -1) break;
+			const line = this.buffer.slice(0, idx).trimEnd();
+			this.buffer = this.buffer.slice(idx + 1);
+			if (line.length === 0) continue;
+			this.handleLine(line);
+		}
+	}
+
+	private handleLine(line: string): void {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(line);
+		} catch (err) {
+			this.write(jsonRpcError(null, -32700, `parse error: ${errorMessage(err)}`));
+			return;
+		}
+		if (!isRecord(parsed) || parsed.jsonrpc !== "2.0") {
+			this.write(jsonRpcError(null, -32600, "invalid JSON-RPC message", parsed));
+			return;
+		}
+		if (isSuccess(parsed) || isFailure(parsed)) {
+			this.handleResponse(parsed);
+			return;
+		}
+		const method = typeof parsed.method === "string" ? parsed.method : "";
+		const id = "id" in parsed ? (parsed.id as string | number | null) : undefined;
+		if (!method) {
+			if (id !== undefined) this.write(jsonRpcError(id, -32600, "request/notification missing method", parsed));
+			return;
+		}
+		if (id !== undefined) {
+			void this.handleRequest(id, method, parsed.params);
+			return;
+		}
+		const handlers = this.notificationHandlers.get(method);
+		if (!handlers) return;
+		for (const handler of handlers) handler(parsed.params);
+	}
+
+	private handleResponse(message: AcpJsonRpcSuccess | AcpJsonRpcFailure): void {
+		const pending = this.pending.get(message.id ?? "");
+		if (!pending) return;
+		this.pending.delete(message.id ?? "");
+		if (pending.timer) clearTimeout(pending.timer);
+		if ("error" in message) {
+			pending.reject(new AcpProtocolError(`ACP ${pending.method} failed: ${message.error.message}`, message.error));
+			return;
+		}
+		pending.resolve(message.result);
+	}
+
+	private async handleRequest(id: string | number | null, method: string, params: unknown): Promise<void> {
+		if (id === null) return;
+		const handler = this.requestHandlers.get(method);
+		if (!handler) {
+			this.write(jsonRpcError(id, -32601, `method not found: ${method}`));
+			return;
+		}
+		try {
+			const result = await handler(params);
+			this.write({ jsonrpc: "2.0", id, result });
+		} catch (err) {
+			this.write(jsonRpcError(id, -32000, errorMessage(err), err instanceof Error ? err.stack : undefined));
+		}
+	}
+
+	private markClosed(reason: unknown): void {
+		if (this.isClosed) return;
+		this.isClosed = true;
+		this.failAll(reason);
+		for (const handler of this.closeHandlers) handler();
+	}
+
+	private failAll(reason: unknown): void {
+		for (const [id, pending] of this.pending.entries()) {
+			if (pending.timer) clearTimeout(pending.timer);
+			pending.reject(reason);
+			this.pending.delete(id);
+		}
+	}
+}
+
+export function createStdioServerTransport(options: StdioServerTransportOptions = {}): AcpJsonRpcPeerTransport {
+	return new StreamJsonRpcPeerTransport(options);
+}