@linxiraos/pi-utils 1.0.0

package/src/abortable.ts

@@ -0,0 +1,109 @@
+import assert from "node:assert/strict";
+
+export class AbortError extends Error {
+	constructor(signal: AbortSignal) {
+		assert(signal.aborted, "Abort signal must be aborted");
+
+		const message = signal.reason instanceof Error ? signal.reason.message : "Cancelled";
+		super(`Aborted: ${message}`, { cause: signal.reason });
+		this.name = "AbortError";
+	}
+}
+
+/**
+ * Abortable async iteration over a {@link ReadableStream}. Reads the source
+ * reader directly and yields each chunk, so the consumer's `for await` drives a
+ * single read loop with no intermediate stream or per-chunk enqueue.
+ *
+ * Unlike `stream.pipeThrough(..., { signal })`, this explicitly cancels the
+ * source reader on abort or early `break`, propagating HTTP-client disconnects
+ * and watchdog timeouts to the backend request instead of only stopping the
+ * local consumer. On abort it throws {@link AbortError}; the lock is released
+ * on completion, abort, throw, or early exit. The source is cancelled only on
+ * abort or early exit — never on natural EOF.
+ */
+export async function* abortableSource<T>(stream: ReadableStream<T>, signal?: AbortSignal): AsyncGenerator<T> {
+	if (signal?.aborted) throw new AbortError(signal);
+	const reader = stream.getReader();
+	let onAbort: (() => void) | undefined;
+	if (signal) {
+		onAbort = () => {
+			void reader.cancel(signal.reason).catch(() => {});
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	}
+	let completed = false;
+	try {
+		for (;;) {
+			const result = await reader.read();
+			if (signal?.aborted) throw new AbortError(signal);
+			if (result.done) {
+				completed = true;
+				return;
+			}
+			yield result.value;
+		}
+	} finally {
+		if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+		// Propagate early-exit (`break`/`return`) and abort to the backend; skip
+		// on natural EOF where the stream already closed itself.
+		if (!completed) {
+			try {
+				await reader.cancel();
+			} catch {}
+		}
+		try {
+			reader.releaseLock();
+		} catch {}
+	}
+}
+
+/**
+ * Runs a promise-returning function (`pr`). If the given AbortSignal is aborted before or during
+ * execution, the promise is rejected with a standard error.
+ *
+ * @param signal - Optional AbortSignal to cancel the operation
+ * @param pr - Function returning a promise to run
+ * @returns Promise resolving as `pr` would, or rejecting on abort
+ */
+export function untilAborted<T>(
+	signal: AbortSignal | undefined | null,
+	pr: Promise<T> | (() => Promise<T>),
+): Promise<T> {
+	if (!signal) return typeof pr === "function" ? pr() : pr;
+	if (signal.aborted) return Promise.reject(new AbortError(signal));
+
+	const { promise, resolve, reject } = Promise.withResolvers<T>();
+	const onAbort = () => reject(new AbortError(signal));
+	signal.addEventListener("abort", onAbort, { once: true });
+
+	void (async () => {
+		try {
+			resolve(await (typeof pr === "function" ? pr() : pr));
+		} catch (err) {
+			reject(err);
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	})();
+
+	return promise;
+}
+
+/**
+ * Memoizes a function with no arguments, calling it once and caching the result.
+ *
+ * @param fn - Function to be called once
+ * @returns A function that returns the cached result of `fn`
+ */
+export function once<T>(fn: () => T): () => T {
+	let store = undefined as { value: T } | undefined;
+	return () => {
+		if (store) {
+			return store.value;
+		}
+		const value = fn();
+		store = { value };
+		return value;
+	};
+}

package/src/acp/connection.ts

@@ -0,0 +1,344 @@
+import type {
+	Agent,
+	AuthenticateRequest,
+	AuthenticateResponse,
+	CloseSessionRequest,
+	CloseSessionResponse,
+	CompleteElicitationNotification,
+	CreateElicitationRequest,
+	CreateElicitationResponse,
+	CreateTerminalRequest,
+	ForkSessionRequest,
+	ForkSessionResponse,
+	InitializeRequest,
+	InitializeResponse,
+	ListSessionsRequest,
+	ListSessionsResponse,
+	LoadSessionRequest,
+	LoadSessionResponse,
+	MaybePromise,
+	NewSessionRequest,
+	NewSessionResponse,
+	PromptRequest,
+	PromptResponse,
+	ReadTextFileRequest,
+	ReadTextFileResponse,
+	RequestPermissionRequest,
+	RequestPermissionResponse,
+	ResumeSessionRequest,
+	ResumeSessionResponse,
+	SessionNotification,
+	SetSessionConfigOptionRequest,
+	SetSessionConfigOptionResponse,
+	SetSessionModeRequest,
+	SetSessionModeResponse,
+	TerminalActionResponse,
+	TerminalOutputResponse,
+	WaitForTerminalExitResponse,
+	WriteTextFileRequest,
+	WriteTextFileResponse,
+} from "./protocol";
+import type { Stream } from "./stream";
+import { RequestError, RpcConnection } from "./transport";
+
+/** Terminal creation response returned by a client. */
+export interface CreateTerminalResponse {
+	terminalId: string;
+}
+/** Client callbacks handled by a client-side connection. */
+export interface Client {
+	requestPermission(params: RequestPermissionRequest): MaybePromise<RequestPermissionResponse>;
+	sessionUpdate(params: SessionNotification): MaybePromise<void>;
+	readTextFile?(params: ReadTextFileRequest): MaybePromise<ReadTextFileResponse>;
+	writeTextFile?(params: WriteTextFileRequest): MaybePromise<WriteTextFileResponse | void>;
+	createTerminal?(params: CreateTerminalRequest): MaybePromise<CreateTerminalResponse>;
+	terminalOutput?(params: { sessionId: string; terminalId: string }): MaybePromise<TerminalOutputResponse>;
+	waitForTerminalExit?(params: { sessionId: string; terminalId: string }): MaybePromise<WaitForTerminalExitResponse>;
+	killTerminal?(params: { sessionId: string; terminalId: string }): MaybePromise<TerminalActionResponse | void>;
+	releaseTerminal?(params: { sessionId: string; terminalId: string }): MaybePromise<TerminalActionResponse | void>;
+	unstable_createElicitation?(params: CreateElicitationRequest): MaybePromise<CreateElicitationResponse>;
+	unstable_completeElicitation?(params: CompleteElicitationNotification): MaybePromise<void>;
+	extMethod?(method: string, params: Record<string, unknown>): MaybePromise<Record<string, unknown>>;
+	extNotification?(method: string, params: Record<string, unknown>): MaybePromise<void>;
+}
+
+/** Agent-side ACP connection. */
+export class AgentSideConnection {
+	#connection: RpcConnection;
+
+	constructor(toAgent: (connection: AgentSideConnection) => Agent, stream: Stream) {
+		let agent: Agent | undefined;
+		this.#connection = new RpcConnection(stream, async (method, params, notification) => {
+			const target = agent;
+			if (!target) throw RequestError.internalError(undefined, "Agent is not initialized");
+			return dispatchAgent(target, method, params, notification);
+		});
+		agent = toAgent(this);
+	}
+
+	/** Signal aborted when the transport closes. */
+	get signal(): AbortSignal {
+		return this.#connection.signal;
+	}
+	/** Promise resolved when the transport closes. */
+	get closed(): Promise<void> {
+		return this.#connection.closed;
+	}
+	/** Sends a session update notification. */
+	sessionUpdate(params: SessionNotification): Promise<void> {
+		return this.#connection.notify("session/update", params);
+	}
+	/** Requests permission from the client. */
+	requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
+		return this.#connection.request("session/request_permission", params);
+	}
+	/** Reads a client-side text file. */
+	readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse> {
+		return this.#connection.request("fs/read_text_file", params);
+	}
+	/** Writes a client-side text file. */
+	writeTextFile(params: WriteTextFileRequest): Promise<WriteTextFileResponse> {
+		return this.#connection.request("fs/write_text_file", params);
+	}
+	/** Creates a client terminal and returns its control handle. */
+	async createTerminal(params: CreateTerminalRequest): Promise<TerminalHandle> {
+		const response = await this.#connection.request<CreateTerminalResponse>("terminal/create", params);
+		return new TerminalHandle(response.terminalId, params.sessionId, this.#connection);
+	}
+	/** Creates an interactive elicitation on the client. */
+	unstable_createElicitation(params: CreateElicitationRequest): Promise<CreateElicitationResponse> {
+		return this.#connection.request("elicitation/create", params);
+	}
+	/** Notifies a client that URL elicitation completed. */
+	unstable_completeElicitation(params: CompleteElicitationNotification): Promise<void> {
+		return this.#connection.notify("elicitation/complete", params);
+	}
+	/** Sends a custom request. */
+	request<Response = unknown, Params = unknown>(method: string, params?: Params): Promise<Response> {
+		return this.#connection.request(method, params);
+	}
+	/** Sends a custom notification. */
+	notify<Params = unknown>(method: string, params?: Params): Promise<void> {
+		return this.#connection.notify(method, params);
+	}
+	/** Sends a legacy extension request. */
+	extMethod(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>> {
+		return this.request(method, params);
+	}
+	/** Sends a legacy extension notification. */
+	extNotification(method: string, params: Record<string, unknown>): Promise<void> {
+		return this.notify(method, params);
+	}
+}
+
+/** Handle for controlling a client-owned terminal. */
+export class TerminalHandle {
+	/** Client terminal identifier. */
+	readonly id: string;
+	#sessionId: string;
+	#connection: RpcConnection;
+
+	constructor(id: string, sessionId: string, connection: RpcConnection) {
+		this.id = id;
+		this.#sessionId = sessionId;
+		this.#connection = connection;
+	}
+	/** Gets current terminal output. */
+	currentOutput(): Promise<TerminalOutputResponse> {
+		return this.#connection.request("terminal/output", { sessionId: this.#sessionId, terminalId: this.id });
+	}
+	/** Waits for terminal exit. */
+	waitForExit(): Promise<WaitForTerminalExitResponse> {
+		return this.#connection.request("terminal/wait_for_exit", { sessionId: this.#sessionId, terminalId: this.id });
+	}
+	/** Kills the terminal. */
+	kill(): Promise<TerminalActionResponse> {
+		return this.#connection.request("terminal/kill", { sessionId: this.#sessionId, terminalId: this.id });
+	}
+	/** Releases the terminal. */
+	release(): Promise<TerminalActionResponse | void> {
+		return this.#connection.request("terminal/release", { sessionId: this.#sessionId, terminalId: this.id });
+	}
+	/** Releases the terminal during async disposal. */
+	async [Symbol.asyncDispose](): Promise<void> {
+		await this.release();
+	}
+}
+
+/** Client-side ACP connection used to call an agent. */
+export class ClientSideConnection {
+	#connection: RpcConnection;
+
+	constructor(toClient: (connection: ClientSideConnection) => Client, stream: Stream) {
+		let client: Client | undefined;
+		this.#connection = new RpcConnection(stream, async (method, params, notification) => {
+			const target = client;
+			if (!target) throw RequestError.internalError(undefined, "Client is not initialized");
+			return dispatchClient(target, method, params, notification);
+		});
+		client = toClient(this);
+	}
+	/** Signal aborted when the transport closes. */
+	get signal(): AbortSignal {
+		return this.#connection.signal;
+	}
+	/** Promise resolved when the transport closes. */
+	get closed(): Promise<void> {
+		return this.#connection.closed;
+	}
+	/** Initializes protocol capabilities. */
+	initialize(params: InitializeRequest): Promise<InitializeResponse> {
+		return this.#connection.request("initialize", params);
+	}
+	/** Authenticates with an agent. */
+	authenticate(params: AuthenticateRequest): Promise<AuthenticateResponse> {
+		return this.#connection.request("authenticate", params);
+	}
+	/** Creates a session. */
+	newSession(params: NewSessionRequest): Promise<NewSessionResponse> {
+		return this.#connection.request("session/new", params);
+	}
+	/** Loads a session. */
+	loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse> {
+		return this.#connection.request("session/load", params);
+	}
+	/** Lists sessions. */
+	listSessions(params: ListSessionsRequest): Promise<ListSessionsResponse> {
+		return this.#connection.request("session/list", params);
+	}
+	/** Resumes a session. */
+	resumeSession(params: ResumeSessionRequest): Promise<ResumeSessionResponse> {
+		return this.#connection.request("session/resume", params);
+	}
+	/** Forks a session. */
+	unstable_forkSession(params: ForkSessionRequest): Promise<ForkSessionResponse> {
+		return this.#connection.request("session/fork", params);
+	}
+	/** Closes a session. */
+	closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse> {
+		return this.#connection.request("session/close", params);
+	}
+	/** Sets a session mode. */
+	setSessionMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse> {
+		return this.#connection.request("session/set_mode", params);
+	}
+	/** Sets a session config option. */
+	setSessionConfigOption(params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse> {
+		return this.#connection.request("session/set_config_option", params);
+	}
+	/** Sends a prompt. */
+	prompt(params: PromptRequest): Promise<PromptResponse> {
+		return this.#connection.request("session/prompt", params);
+	}
+	/** Cancels an active prompt. */
+	cancel(params: { sessionId: string }): Promise<void> {
+		return this.#connection.notify("session/cancel", params);
+	}
+}
+
+async function dispatchAgent(agent: Agent, method: string, params: unknown, notification: boolean): Promise<unknown> {
+	switch (method) {
+		case "initialize":
+			return agent.initialize(params as InitializeRequest);
+		case "authenticate":
+			return invokeRequired(agent, agent.authenticate, method, params as AuthenticateRequest);
+		case "session/new":
+			return agent.newSession(params as NewSessionRequest);
+		case "session/load":
+			return invokeRequired(agent, agent.loadSession, method, params as LoadSessionRequest);
+		case "session/list":
+			return invokeRequired(agent, agent.listSessions, method, params as ListSessionsRequest);
+		case "session/resume":
+			return invokeRequired(agent, agent.resumeSession, method, params as ResumeSessionRequest);
+		case "session/fork":
+			return invokeRequired(agent, agent.unstable_forkSession, method, params as ForkSessionRequest);
+		case "session/close":
+			return invokeRequired(agent, agent.closeSession, method, params as CloseSessionRequest);
+		case "session/set_mode":
+			return invokeRequired(agent, agent.setSessionMode, method, params as SetSessionModeRequest);
+		case "session/set_config_option":
+			return invokeRequired(agent, agent.setSessionConfigOption, method, params as SetSessionConfigOptionRequest);
+		case "session/prompt":
+			return agent.prompt(params as PromptRequest);
+		case "session/cancel":
+			return agent.cancel(params as { sessionId: string });
+		default:
+			if (method === "$/cancel_request") return;
+			if (notification && agent.extNotification)
+				return agent.extNotification(method, params as Record<string, unknown>);
+			if (!notification && agent.extMethod) return agent.extMethod(method, params as Record<string, unknown>);
+			throw RequestError.methodNotFound(method);
+	}
+}
+
+async function dispatchClient(
+	client: Client,
+	method: string,
+	params: unknown,
+	notification: boolean,
+): Promise<unknown> {
+	switch (method) {
+		case "session/request_permission":
+			return client.requestPermission(params as RequestPermissionRequest);
+		case "session/update":
+			return client.sessionUpdate(params as SessionNotification);
+		case "fs/read_text_file":
+			return invokeRequired(client, client.readTextFile, method, params as ReadTextFileRequest);
+		case "fs/write_text_file":
+			return invokeRequired(client, client.writeTextFile, method, params as WriteTextFileRequest);
+		case "terminal/create":
+			return invokeRequired(client, client.createTerminal, method, params as CreateTerminalRequest);
+		case "terminal/output":
+			return invokeRequired(
+				client,
+				client.terminalOutput,
+				method,
+				params as { sessionId: string; terminalId: string },
+			);
+		case "terminal/wait_for_exit":
+			return invokeRequired(
+				client,
+				client.waitForTerminalExit,
+				method,
+				params as { sessionId: string; terminalId: string },
+			);
+		case "terminal/kill":
+			return invokeRequired(
+				client,
+				client.killTerminal,
+				method,
+				params as { sessionId: string; terminalId: string },
+			);
+		case "terminal/release":
+			return invokeRequired(
+				client,
+				client.releaseTerminal,
+				method,
+				params as { sessionId: string; terminalId: string },
+			);
+		case "elicitation/create":
+			return invokeRequired(client, client.unstable_createElicitation, method, params as CreateElicitationRequest);
+		case "elicitation/complete":
+			return invokeRequired(
+				client,
+				client.unstable_completeElicitation,
+				method,
+				params as CompleteElicitationNotification,
+			);
+		default:
+			if (notification && client.extNotification)
+				return client.extNotification(method, params as Record<string, unknown>);
+			if (!notification && client.extMethod) return client.extMethod(method, params as Record<string, unknown>);
+			throw RequestError.methodNotFound(method);
+	}
+}
+
+function invokeRequired<Params, Response>(
+	receiver: Agent | Client,
+	handler: ((params: Params) => MaybePromise<Response>) | undefined,
+	method: string,
+	params: Params,
+): MaybePromise<Response> {
+	if (!handler) throw RequestError.methodNotFound(method);
+	return handler.call(receiver, params);
+}