@linxiraos/pi-utils 1.0.0

package/src/acp/transport.ts

@@ -0,0 +1,213 @@
+import type { MaybePromise } from "./protocol";
+import type { Stream } from "./stream";
+
+/** JSON-RPC request identifier. */
+export type JsonRpcId = string | number | null;
+/** JSON-RPC request. */
+export interface AnyRequest {
+	jsonrpc: "2.0";
+	id: JsonRpcId;
+	method: string;
+	params?: unknown;
+}
+/** JSON-RPC notification. */
+export interface AnyNotification {
+	jsonrpc: "2.0";
+	method: string;
+	params?: unknown;
+}
+/** JSON-RPC error payload. */
+export interface ErrorResponse {
+	code: number;
+	message: string;
+	data?: unknown;
+}
+/** JSON-RPC response. */
+export type AnyResponse = { jsonrpc: "2.0"; id: JsonRpcId } & ({ result: unknown } | { error: ErrorResponse });
+/** Any JSON-RPC wire message. */
+export type AnyMessage = AnyRequest | AnyNotification | AnyResponse;
+
+/** Error returned by a JSON-RPC peer or handler. */
+export class RequestError extends Error {
+	/** JSON-RPC error code. */
+	readonly code: number;
+	/** Optional protocol error data. */
+	readonly data?: unknown;
+
+	constructor(code: number, message: string, data?: unknown) {
+		super(message);
+		this.name = "RequestError";
+		this.code = code;
+		this.data = data;
+	}
+
+	/** Creates a JSON parse error. */
+	static parseError(data?: unknown, additionalMessage?: string): RequestError {
+		return createStandardError(-32700, "Parse error", data, additionalMessage);
+	}
+	/** Creates an invalid-request error. */
+	static invalidRequest(data?: unknown, additionalMessage?: string): RequestError {
+		return createStandardError(-32600, "Invalid request", data, additionalMessage);
+	}
+	/** Creates a method-not-found error. */
+	static methodNotFound(method: string): RequestError {
+		return new RequestError(-32601, `"Method not found": ${method}`, { method });
+	}
+	/** Creates an invalid-parameters error. */
+	static invalidParams(data?: unknown, additionalMessage?: string): RequestError {
+		return createStandardError(-32602, "Invalid params", data, additionalMessage);
+	}
+	/** Creates an internal error. */
+	static internalError(data?: unknown, additionalMessage?: string): RequestError {
+		return createStandardError(-32603, "Internal error", data, additionalMessage);
+	}
+	/** Creates a cancellation error. */
+	static requestCancelled(data?: unknown, additionalMessage?: string): RequestError {
+		return createStandardError(-32800, "Request cancelled", data, additionalMessage);
+	}
+	/** Creates an authentication-required error. */
+	static authRequired(data?: unknown, additionalMessage?: string): RequestError {
+		return createStandardError(-32000, "Authentication required", data, additionalMessage);
+	}
+	/** Creates a resource-not-found error. */
+	static resourceNotFound(uri?: string): RequestError {
+		return new RequestError(
+			-32002,
+			uri === undefined ? "Resource not found" : `Resource not found: ${uri}`,
+			uri === undefined ? undefined : { uri },
+		);
+	}
+	/** Converts this error into a JSON-RPC result. */
+	toResult(): { error: ErrorResponse } {
+		return { error: this.toErrorResponse() };
+	}
+	/** Converts this error into a JSON-RPC error payload. */
+	toErrorResponse(): ErrorResponse {
+		return { code: this.code, message: this.message, ...(this.data === undefined ? {} : { data: this.data }) };
+	}
+}
+
+function createStandardError(
+	code: number,
+	message: string,
+	data: unknown,
+	additionalMessage: string | undefined,
+): RequestError {
+	return new RequestError(code, additionalMessage ? `${message}: ${additionalMessage}` : message, data);
+}
+
+type Dispatcher = (method: string, params: unknown, notification: boolean) => MaybePromise<unknown>;
+type Pending = { resolve(value: unknown): void; reject(reason: unknown): void };
+
+/** Correlated bidirectional JSON-RPC connection. */
+export class RpcConnection {
+	#nextId = 0;
+	#pending = new Map<JsonRpcId, Pending>();
+	#writable: WritableStream<AnyMessage>;
+	#writeTail: Promise<void> = Promise.resolve();
+	#abort = new AbortController();
+	#closed = Promise.withResolvers<void>();
+	#dispatcher: Dispatcher;
+
+	constructor(stream: Stream, dispatcher: Dispatcher) {
+		this.#writable = stream.writable;
+		this.#dispatcher = dispatcher;
+		void this.#read(stream.readable);
+	}
+
+	/** Signal aborted when the stream closes. */
+	get signal(): AbortSignal {
+		return this.#abort.signal;
+	}
+	/** Promise resolved when the stream closes. */
+	get closed(): Promise<void> {
+		return this.#closed.promise;
+	}
+
+	/** Sends a correlated JSON-RPC request. */
+	request<Response>(method: string, params?: unknown): Promise<Response> {
+		if (this.signal.aborted) return Promise.reject(new Error("Connection closed"));
+		const id = this.#nextId++;
+		const deferred = Promise.withResolvers<unknown>();
+		this.#pending.set(id, deferred);
+		void this.#write({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) }).catch(error => {
+			this.#pending.delete(id);
+			deferred.reject(error);
+		});
+		return deferred.promise as Promise<Response>;
+	}
+
+	/** Sends a JSON-RPC notification. */
+	async notify(method: string, params?: unknown): Promise<void> {
+		await this.#write({ jsonrpc: "2.0", method, ...(params === undefined ? {} : { params }) });
+	}
+
+	/** Closes the connection and rejects outstanding requests. */
+	close(error?: unknown): void {
+		if (this.signal.aborted) return;
+		this.#abort.abort(error);
+		for (const pending of this.#pending.values()) pending.reject(error ?? new Error("Connection closed"));
+		this.#pending.clear();
+		this.#closed.resolve();
+	}
+
+	#write(message: AnyMessage): Promise<void> {
+		const write = this.#writeTail.then(async () => {
+			const writer = this.#writable.getWriter();
+			try {
+				await writer.write(message);
+			} finally {
+				writer.releaseLock();
+			}
+		});
+		this.#writeTail = write.catch(() => {});
+		return write;
+	}
+
+	async #read(readable: ReadableStream<AnyMessage>): Promise<void> {
+		const reader = readable.getReader();
+		try {
+			while (true) {
+				const next = await reader.read();
+				if (next.done) break;
+				void this.#handle(next.value).catch(error => this.close(error));
+			}
+			this.close();
+		} catch (error) {
+			this.close(error);
+		} finally {
+			reader.releaseLock();
+		}
+	}
+
+	async #handle(message: AnyMessage): Promise<void> {
+		if ("id" in message && !("method" in message)) {
+			const pending = this.#pending.get(message.id);
+			if (!pending) return;
+			this.#pending.delete(message.id);
+			if ("error" in message)
+				pending.reject(new RequestError(message.error.code, message.error.message, message.error.data));
+			else pending.resolve(message.result);
+			return;
+		}
+		if (!("method" in message)) return;
+		if (!("id" in message)) {
+			try {
+				await this.#dispatcher(message.method, message.params, true);
+			} catch {
+				/* Notifications have no error channel. */
+			}
+			return;
+		}
+		try {
+			const result = await this.#dispatcher(message.method, message.params, false);
+			await this.#write({ jsonrpc: "2.0", id: message.id, result: result ?? {} });
+		} catch (error) {
+			const protocolError =
+				error instanceof RequestError
+					? error
+					: RequestError.internalError({ details: error instanceof Error ? error.message : String(error) });
+			await this.#write({ jsonrpc: "2.0", id: message.id, error: protocolError.toErrorResponse() });
+		}
+	}
+}

package/src/acp.ts

@@ -0,0 +1,6 @@
+/** Behavior-compatible reimplementation of @agentclientprotocol/sdk's used surface. */
+export * from "./acp/connection";
+export * from "./acp/protocol";
+export * from "./acp/schema";
+export * from "./acp/stream";
+export * from "./acp/transport";

package/src/async.ts

@@ -0,0 +1,91 @@
+/**
+ * Wrap a promise with a timeout and optional abort signal.
+ * Rejects with the given message if the timeout fires first.
+ * Cleans up all listeners on settlement.
+ */
+export function withTimeout<T>(promise: Promise<T>, ms: number, message: string, signal?: AbortSignal): Promise<T> {
+	if (signal?.aborted) {
+		const reason = signal.reason instanceof Error ? signal.reason : new Error("Aborted");
+		return Promise.reject(reason);
+	}
+
+	const { promise: wrapped, resolve, reject } = Promise.withResolvers<T>();
+	let settled = false;
+	const timeoutId = setTimeout(() => {
+		if (settled) return;
+		settled = true;
+		if (signal) signal.removeEventListener("abort", onAbort);
+		reject(new Error(message));
+	}, ms);
+
+	const onAbort = () => {
+		if (settled) return;
+		settled = true;
+		clearTimeout(timeoutId);
+		reject(signal?.reason instanceof Error ? signal.reason : new Error("Aborted"));
+	};
+
+	if (signal) {
+		signal.addEventListener("abort", onAbort, { once: true });
+	}
+
+	promise.then(
+		value => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeoutId);
+			if (signal) signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		},
+		err => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeoutId);
+			if (signal) signal.removeEventListener("abort", onAbort);
+			reject(err);
+		},
+	);
+
+	return wrapped;
+}
+
+/**
+ * Coalesces rapid-fire writes into one deferred batch. `push` queues a value
+ * and returns a promise for the batch flush; the first push of a batch arms a
+ * timer (`delayMs`, or a microtask at 0), and every push before it fires joins
+ * the same batch and shares the same promise. Used to keep hot paths off
+ * synchronous storage (prompt history, model perf).
+ */
+export class AsyncDrain<T> {
+	#queue?: T[];
+	#promise = Promise.resolve();
+
+	constructor(readonly delayMs: number = 0) {}
+
+	/** Queue `value`; `hnd` receives the whole batch when the window closes. */
+	push(value: T, hnd: (values: T[]) => Promise<void> | void): Promise<void> {
+		let queue = this.#queue;
+		if (!queue) {
+			this.#queue = queue = [];
+			const { promise, resolve, reject } = Promise.withResolvers<void>();
+			const exec = (): void => {
+				try {
+					if (this.#queue === queue) {
+						this.#queue = undefined;
+					}
+					resolve(hnd(queue!));
+				} catch (error) {
+					reject(error);
+				}
+			};
+			if (this.delayMs > 0) {
+				setTimeout(exec, this.delayMs);
+			} else {
+				queueMicrotask(exec);
+			}
+			this.#promise = promise;
+		}
+		queue.push(value);
+		return this.#promise;
+	}
+}

package/src/binary.ts

@@ -0,0 +1,50 @@
+/**
+ * Content-based binary/text classification for files that are about to be
+ * decoded as UTF-8 text and shown to a model or user.
+ *
+ * The read tool and `@file` auto-read both materialize file bytes as UTF-8
+ * strings. For a binary file (font, object, archive, packed blob) that decode
+ * is lossy: NUL bytes and invalid sequences survive as control characters and
+ * U+FFFD replacements, which corrupt terminal rendering and waste the context
+ * window with mojibake. Sniff the header first and refuse instead.
+ *
+ * @example
+ * if (await isProbablyBinary(path)) return "[binary file omitted]";
+ * const text = await Bun.file(path).text();
+ */
+import { peekFile, peekFileSync } from "./peek-file";
+
+/** Header window sniffed for the binary heuristic; mirrors git's 8000-byte scan. */
+const BINARY_SNIFF_BYTES = 8192;
+
+/**
+ * Classify an in-memory byte header as binary (non-UTF-8-text).
+ *
+ * Binary when the header contains a NUL byte (true binary, plus UTF-16/UTF-32
+ * text whose ASCII range is NUL-padded) or when it is not valid UTF-8. The
+ * decode runs in streaming mode so a multibyte sequence truncated at the header
+ * boundary is tolerated, while any genuinely invalid byte still fails — matching
+ * the strict `fatal` decode the `local://`/`ssh://` read paths already use.
+ */
+export function isProbablyBinaryHeader(header: Uint8Array): boolean {
+	if (header.indexOf(0) !== -1) return true;
+	try {
+		new TextDecoder("utf-8", { fatal: true }).decode(header, { stream: true });
+		return false;
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * Sniff the first {@link BINARY_SNIFF_BYTES} of `filePath` and report whether it
+ * is binary (non-UTF-8-text). See {@link isProbablyBinaryHeader} for the rule.
+ */
+export function isProbablyBinary(filePath: string, maxBytes = BINARY_SNIFF_BYTES): Promise<boolean> {
+	return peekFile(filePath, maxBytes, isProbablyBinaryHeader);
+}
+
+/** Synchronous {@link isProbablyBinary}. */
+export function isProbablyBinarySync(filePath: string, maxBytes = BINARY_SNIFF_BYTES): boolean {
+	return peekFileSync(filePath, maxBytes, isProbablyBinaryHeader);
+}