@sayknow-cli/coding-agent 0.4.7 → 0.5.0

package/src/sdk/transport/relay.ts

@@ -0,0 +1,252 @@
+import type { Readable, Writable } from "node:stream";
+
+export const REQUEST_FRAME_BYTES = 256 * 1024;
+export const DEFAULT_PENDING_CEILING_BYTES = 8 * 1024 * 1024;
+export const MIN_PENDING_CEILING_BYTES = REQUEST_FRAME_BYTES;
+
+export type RelayDirection = "downstream->ws" | "ws->downstream";
+export type TransportError = {
+	type: "transport_error";
+	code: "frame_oversize" | "pending_overflow" | "protocol_error";
+	direction?: RelayDirection;
+};
+
+export type RelayPair = {
+	close(): Promise<void>;
+	readonly done: Promise<void>;
+};
+
+export class RelayOpenAbortedError extends Error {
+	constructor() {
+		super("relay_open_aborted");
+		this.name = "RelayOpenAbortedError";
+	}
+}
+
+export type RelayWebSocketEvent = { data?: unknown };
+
+export type RelayWebSocket = {
+	readonly bufferedAmount: number;
+	readonly readyState: number;
+	close(): void;
+	send(data: string): void;
+	addEventListener(type: string, listener: (event: RelayWebSocketEvent) => void, options?: { once?: boolean }): void;
+	removeEventListener(type: string, listener: (event: RelayWebSocketEvent) => void): void;
+};
+
+export type RelayOptions = {
+	url: string;
+	token: string;
+	pendingCeilingBytes: number;
+	downstream: Readable;
+	downstreamSink: Writable;
+	initialDownstreamBytes?: Buffer;
+	onTransportError: (error: TransportError) => void;
+	webSocketFactory?: (url: string) => RelayWebSocket;
+	signal?: AbortSignal;
+};
+
+type QueuedFrame = { bytes: Buffer; accounted: boolean };
+
+function upstreamUrl(url: string, token: string): string {
+	const endpoint = new URL(url);
+	endpoint.pathname = `${endpoint.pathname.replace(/\/$/, "")}/`;
+	endpoint.searchParams.set("token", token);
+	return endpoint.toString();
+}
+
+function waitForDrain(stream: Writable): Promise<void> {
+	const { promise, reject, resolve } = Promise.withResolvers<void>();
+	const onDrain = (): void => done(resolve);
+	const onError = (error: Error): void => done(() => reject(error));
+	const done = (callback: () => void): void => {
+		stream.removeListener("drain", onDrain);
+		stream.removeListener("error", onError);
+		callback();
+	};
+	stream.once("drain", onDrain);
+	stream.once("error", onError);
+	return promise;
+}
+
+const WEBSOCKET_CONNECTING = 0;
+const WEBSOCKET_OPEN = 1;
+
+function waitForWebSocketDrain(ws: RelayWebSocket, isClosed: () => boolean): Promise<void> {
+	const { promise, resolve } = Promise.withResolvers<void>();
+	const poll = (): void => {
+		if (isClosed() || ws.readyState !== WEBSOCKET_OPEN || ws.bufferedAmount === 0) {
+			resolve();
+			return;
+		}
+		setTimeout(poll, 10);
+	};
+	poll();
+	return promise;
+}
+
+/** Starts a dedicated raw-WebSocket relay for exactly one downstream stream. */
+export async function startRelayPair(options: RelayOptions): Promise<RelayPair> {
+	if (options.signal?.aborted) throw new RelayOpenAbortedError();
+	const ws: RelayWebSocket =
+		options.webSocketFactory?.(upstreamUrl(options.url, options.token)) ??
+		new WebSocket(upstreamUrl(options.url, options.token));
+	const opened = Promise.withResolvers<void>();
+	const finished = Promise.withResolvers<void>();
+	let closed = false;
+	let completed = false;
+	let downstreamBuffer = Buffer.alloc(0);
+	const toWs: QueuedFrame[] = [];
+	const toDownstream: QueuedFrame[] = [];
+	let pendingToWs = 0;
+	let pendingToDownstream = 0;
+	let writingWs = false;
+	let writingDownstream = false;
+
+	const settle = (error?: Error): void => {
+		if (completed) return;
+		completed = true;
+		if (error) finished.reject(error);
+		else finished.resolve();
+	};
+	void finished.promise.catch(() => undefined);
+	const detach = (): void => {
+		options.downstream.removeListener("data", onData);
+		options.downstream.removeListener("end", onEnd);
+		options.downstream.removeListener("error", onDownstreamError);
+		ws.removeEventListener("message", onMessage);
+		ws.removeEventListener("close", onClose);
+		ws.removeEventListener("error", onWebSocketError);
+		cleanupOpening();
+	};
+	const close = async (error?: Error): Promise<void> => {
+		if (closed) return finished.promise.catch(() => undefined);
+		closed = true;
+		detach();
+		options.downstream.pause();
+		if (ws.readyState === WEBSOCKET_OPEN || ws.readyState === WEBSOCKET_CONNECTING) ws.close();
+		settle(error);
+		return await finished.promise.catch(() => undefined);
+	};
+	const fail = (transportError: TransportError): void => {
+		if (closed) return;
+		options.onTransportError(transportError);
+		void close(new Error(transportError.code));
+	};
+	const enqueue = (queue: QueuedFrame[], direction: RelayDirection, bytes: Buffer): void => {
+		const isWsDirection = direction === "downstream->ws";
+		const active = isWsDirection ? writingWs : writingDownstream;
+		const pending = isWsDirection ? pendingToWs : pendingToDownstream;
+		if (active && pending + bytes.length > options.pendingCeilingBytes) {
+			fail({ type: "transport_error", code: "pending_overflow", direction });
+			return;
+		}
+		queue.push({ bytes, accounted: active });
+		if (active) {
+			if (isWsDirection) pendingToWs += bytes.length;
+			else pendingToDownstream += bytes.length;
+		}
+		if (isWsDirection) void pumpWs();
+		else void pumpDownstream();
+	};
+	const pumpWs = async (): Promise<void> => {
+		if (writingWs || closed) return;
+		const frame = toWs.shift();
+		if (!frame) return;
+		writingWs = true;
+		if (frame.accounted) pendingToWs -= frame.bytes.length;
+		try {
+			if (ws.readyState !== WEBSOCKET_OPEN) throw new Error("upstream_closed");
+			ws.send(frame.bytes.toString("utf8"));
+			await waitForWebSocketDrain(ws, () => closed);
+		} catch (error) {
+			await close(error instanceof Error ? error : new Error(String(error)));
+			return;
+		} finally {
+			writingWs = false;
+		}
+		void pumpWs();
+	};
+	const pumpDownstream = async (): Promise<void> => {
+		if (writingDownstream || closed) return;
+		const frame = toDownstream.shift();
+		if (!frame) return;
+		writingDownstream = true;
+		if (frame.accounted) pendingToDownstream -= frame.bytes.length;
+		try {
+			if (!options.downstreamSink.write(frame.bytes)) await waitForDrain(options.downstreamSink);
+		} catch (error) {
+			await close(error instanceof Error ? error : new Error(String(error)));
+			return;
+		} finally {
+			writingDownstream = false;
+		}
+		void pumpDownstream();
+	};
+	const consumeLines = (chunk: Buffer): void => {
+		downstreamBuffer = Buffer.concat([downstreamBuffer, chunk]);
+		let newline = downstreamBuffer.indexOf(0x0a);
+		while (newline >= 0) {
+			const line = downstreamBuffer.subarray(0, newline);
+			downstreamBuffer = downstreamBuffer.subarray(newline + 1);
+			if (line.length === 0)
+				return fail({ type: "transport_error", code: "protocol_error", direction: "downstream->ws" });
+			if (line.length > REQUEST_FRAME_BYTES)
+				return fail({ type: "transport_error", code: "frame_oversize", direction: "downstream->ws" });
+			enqueue(toWs, "downstream->ws", line);
+			if (closed) return;
+			newline = downstreamBuffer.indexOf(0x0a);
+		}
+		if (downstreamBuffer.length > REQUEST_FRAME_BYTES)
+			fail({ type: "transport_error", code: "frame_oversize", direction: "downstream->ws" });
+	};
+	const onData = (chunk: Buffer | string): void => consumeLines(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+	const onEnd = (): void => void close();
+	const onDownstreamError = (error: Error): void => void close(error);
+	const onMessage = (event: RelayWebSocketEvent): void => {
+		if (typeof event.data !== "string") {
+			fail({ type: "transport_error", code: "protocol_error", direction: "ws->downstream" });
+			return;
+		}
+		enqueue(toDownstream, "ws->downstream", Buffer.concat([Buffer.from(event.data, "utf8"), Buffer.from("\n")]));
+	};
+	const onClose = (): void => void close();
+	const onWebSocketError = (): void => void close(new Error("upstream_error"));
+	const onOpen = (): void => {
+		cleanupOpening();
+		opened.resolve();
+	};
+	const onOpenError = (): void => {
+		cleanupOpening();
+		opened.reject(new Error("upstream_error"));
+	};
+	const onAbort = (): void => {
+		const error = new RelayOpenAbortedError();
+		cleanupOpening();
+		opened.reject(error);
+		void close(error);
+	};
+	const cleanupOpening = (): void => {
+		ws.removeEventListener("open", onOpen);
+		ws.removeEventListener("error", onOpenError);
+		options.signal?.removeEventListener("abort", onAbort);
+	};
+	ws.addEventListener("open", onOpen, { once: true });
+	ws.addEventListener("error", onOpenError, { once: true });
+	options.signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		await opened.promise;
+	} catch (error) {
+		await close(error instanceof Error ? error : new Error(String(error)));
+		throw error;
+	}
+	ws.addEventListener("message", onMessage);
+	ws.addEventListener("close", onClose);
+	ws.addEventListener("error", onWebSocketError);
+	options.downstream.on("data", onData);
+	options.downstream.once("end", onEnd);
+	options.downstream.once("error", onDownstreamError);
+	if (options.initialDownstreamBytes?.length) consumeLines(options.initialDownstreamBytes);
+	if (!closed) options.downstream.resume();
+	return { close: () => close(), done: finished.promise };
+}

package/src/sdk/transport/serve-cli.ts

@@ -0,0 +1,105 @@
+import { CliParseError } from "@sayknow-cli/utils/cli";
+import type { SdkSessionEndpoint } from "../client/discovery";
+import { listSdkSessionEndpoints } from "../client/discovery";
+import { type SdkEndpointSelectionError, selectLiveEndpoint } from "../client/liveness";
+import { DEFAULT_PENDING_CEILING_BYTES, MIN_PENDING_CEILING_BYTES, startSocketServe, startStdioServe } from "./index";
+
+type ServeMode = { kind: "stdio" } | { kind: "socket"; socketPath: string };
+
+interface ServeArguments {
+	mode: ServeMode;
+	sessionId?: string;
+	pendingCeiling?: string;
+}
+
+function usageError(message: string): never {
+	throw new CliParseError(`skc sdk serve: ${message}`);
+}
+
+function readFlagValue(argv: string[], index: number, flag: string): string {
+	const value = argv[index + 1];
+	if (value === undefined || value.startsWith("-")) usageError(`${flag} requires a value`);
+	return value;
+}
+
+function parseServeArguments(argv: string[]): ServeArguments {
+	let stdio = false;
+	let socketPath: string | undefined;
+	let sessionId: string | undefined;
+	let pendingCeiling: string | undefined;
+	for (let index = 0; index < argv.length; index++) {
+		switch (argv[index]) {
+			case "--stdio":
+				if (stdio) usageError("--stdio may only be specified once");
+				stdio = true;
+				break;
+			case "--socket":
+				if (socketPath !== undefined) usageError("--socket may only be specified once");
+				socketPath = readFlagValue(argv, index, "--socket");
+				index++;
+				break;
+			case "--session":
+				if (sessionId !== undefined) usageError("--session may only be specified once");
+				sessionId = readFlagValue(argv, index, "--session");
+				index++;
+				break;
+			case "--pending-ceiling":
+				if (pendingCeiling !== undefined) usageError("--pending-ceiling may only be specified once");
+				pendingCeiling = readFlagValue(argv, index, "--pending-ceiling");
+				index++;
+				break;
+			default:
+				usageError(`unknown argument: ${argv[index]}`);
+		}
+	}
+	if (stdio === (socketPath !== undefined)) usageError("specify exactly one of --stdio or --socket <path>");
+	return { mode: stdio ? { kind: "stdio" } : { kind: "socket", socketPath: socketPath! }, sessionId, pendingCeiling };
+}
+
+/** Resolves the pending ceiling with flag > env > default precedence; exported for tests. */
+export function resolveServePendingCeiling(flagValue: string | undefined, envValue: string | undefined): number {
+	const value = flagValue ?? envValue;
+	if (value === undefined) return DEFAULT_PENDING_CEILING_BYTES;
+	if (!/^\d+$/.test(value)) usageError("--pending-ceiling must be a positive integer");
+	const ceiling = Number(value);
+	if (!Number.isSafeInteger(ceiling) || ceiling < MIN_PENDING_CEILING_BYTES)
+		usageError(`--pending-ceiling must be an integer of at least ${MIN_PENDING_CEILING_BYTES}`);
+	return ceiling;
+}
+
+function isSelectionError(value: SdkSessionEndpoint | SdkEndpointSelectionError): value is SdkEndpointSelectionError {
+	return "code" in value;
+}
+
+/** Attaches a stdio or Unix-socket relay to one live SDK session endpoint. */
+export async function runSdkServe(argv: string[]): Promise<void> {
+	const parsed = parseServeArguments(argv);
+	if (parsed.mode.kind === "socket" && process.platform === "win32")
+		throw new Error("unsupported_platform: --socket is unavailable on Windows.");
+	const pendingCeilingBytes = resolveServePendingCeiling(
+		parsed.pendingCeiling,
+		process.env.SKC_SDK_SERVE_PENDING_CEILING_BYTES,
+	);
+	const discovered = await listSdkSessionEndpoints(process.cwd());
+	const selected = selectLiveEndpoint(discovered.endpoints, parsed.sessionId);
+	if (isSelectionError(selected)) {
+		const sessionHint = parsed.sessionId ? ` for session ${parsed.sessionId}` : "; specify --session <id>";
+		throw new Error(`${selected.code}${sessionHint}`);
+	}
+	const options = { url: selected.url, token: selected.token, pendingCeilingBytes };
+	const handle =
+		parsed.mode.kind === "stdio"
+			? await startStdioServe(options)
+			: await startSocketServe({ ...options, socketPath: parsed.mode.socketPath });
+	const stop = () => {
+		void handle.close();
+	};
+	process.once("SIGINT", stop);
+	process.once("SIGTERM", stop);
+	try {
+		await handle.done;
+	} finally {
+		process.removeListener("SIGINT", stop);
+		process.removeListener("SIGTERM", stop);
+	}
+}

package/src/sdk/transport/socket.ts

@@ -0,0 +1,197 @@
+import * as fsSync from "node:fs";
+import * as fs from "node:fs/promises";
+import * as net from "node:net";
+import * as path from "node:path";
+import { MAX_UNIX_SOCKET_PATH_BYTES } from "../../harness-control-plane/storage";
+import { authenticatePreface } from "./auth-preface";
+import type { ServeHandle, ServeOptions } from "./index";
+import type { RelayOptions, RelayPair, TransportError } from "./relay";
+import { startRelayPair } from "./relay";
+
+function socketFailure(code: string): Error {
+	return new Error(code);
+}
+
+async function validateSocketPath(socketPath: string): Promise<void> {
+	if (process.platform === "win32") throw socketFailure("unsupported_platform");
+	if (Buffer.byteLength(socketPath) > MAX_UNIX_SOCKET_PATH_BYTES) throw socketFailure("socket_path_too_long");
+	try {
+		await fs.lstat(socketPath);
+		throw socketFailure("socket_path_in_use");
+	} catch (error) {
+		if (error instanceof Error && error.message === "socket_path_in_use") throw error;
+		const code = error as NodeJS.ErrnoException;
+		if (code.code !== "ENOENT") throw error;
+	}
+	let parent: Awaited<ReturnType<typeof fs.stat>>;
+	try {
+		parent = await fs.stat(path.dirname(socketPath));
+	} catch {
+		throw socketFailure("socket_dir_insecure");
+	}
+	if (!parent.isDirectory() || parent.uid !== process.getuid?.() || (parent.mode & 0o022) !== 0)
+		throw socketFailure("socket_dir_insecure");
+}
+
+function sendTransportError(socket: net.Socket, error: TransportError): void {
+	socket.write(`${JSON.stringify(error)}\n`);
+}
+
+/** Serves authenticated SDK JSONL clients over a private Unix-domain socket. */
+export async function startSocketServe(
+	options: ServeOptions & { socketPath: string; webSocketFactory?: RelayOptions["webSocketFactory"] },
+): Promise<ServeHandle> {
+	await validateSocketPath(options.socketPath);
+	const pairs = new Set<RelayPair>();
+	const sockets = new Set<net.Socket>();
+	const connectionTasks = new Set<Promise<void>>();
+	const dialControllers = new Set<AbortController>();
+	let server: net.Server | undefined;
+	let ownedIdentity: { dev: number; ino: number } | undefined;
+	let closing: Promise<void> | undefined;
+	const done = Promise.withResolvers<void>();
+	void done.promise.catch(() => undefined);
+
+	const removeOwnedSocket = async (): Promise<void> => {
+		if (!ownedIdentity) return;
+		try {
+			const current = await fs.lstat(options.socketPath);
+			if (current.isSocket() && current.dev === ownedIdentity.dev && current.ino === ownedIdentity.ino)
+				await fs.unlink(options.socketPath);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+	};
+
+	const removeOwnedSocketSync = (): void => {
+		if (!ownedIdentity) return;
+		try {
+			const current = fsSync.lstatSync(options.socketPath);
+			if (current.isSocket() && current.dev === ownedIdentity.dev && current.ino === ownedIdentity.ino)
+				fsSync.unlinkSync(options.socketPath);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+	};
+	const cleanupOnExit = (): void => removeOwnedSocketSync();
+	process.once("exit", cleanupOnExit);
+	const close = async (fatalError?: Error): Promise<void> => {
+		if (closing) return await closing;
+		closing = (async () => {
+			const errors: Error[] = fatalError ? [fatalError] : [];
+			for (const controller of dialControllers) controller.abort();
+			for (const socket of sockets) socket.destroy();
+			const pairResults = await Promise.allSettled([...pairs].map(pair => pair.close()));
+			for (const result of pairResults) {
+				if (result.status === "rejected")
+					errors.push(result.reason instanceof Error ? result.reason : new Error(String(result.reason)));
+			}
+			const connectionResults = await Promise.allSettled([...connectionTasks]);
+			for (const result of connectionResults) {
+				if (result.status === "rejected")
+					errors.push(result.reason instanceof Error ? result.reason : new Error(String(result.reason)));
+			}
+			let displacedPath: string | undefined;
+			if (server?.listening && ownedIdentity) {
+				try {
+					const current = await fs.lstat(options.socketPath).catch(() => undefined);
+					if (current && (current.dev !== ownedIdentity.dev || current.ino !== ownedIdentity.ino)) {
+						displacedPath = `${options.socketPath}.${process.pid}.closing`;
+						await fs.rename(options.socketPath, displacedPath);
+					}
+				} catch (error) {
+					errors.push(error instanceof Error ? error : new Error(String(error)));
+				}
+			}
+			if (server?.listening) {
+				try {
+					await new Promise<void>((resolve, reject) =>
+						server?.close(error => (error ? reject(error) : resolve())),
+					);
+				} catch (error) {
+					errors.push(error instanceof Error ? error : new Error(String(error)));
+				}
+			}
+			if (displacedPath) {
+				try {
+					await fs.rename(displacedPath, options.socketPath);
+				} catch (error) {
+					errors.push(error instanceof Error ? error : new Error(String(error)));
+				}
+			}
+			try {
+				await removeOwnedSocket();
+			} catch (error) {
+				errors.push(error instanceof Error ? error : new Error(String(error)));
+			}
+			process.removeListener("exit", cleanupOnExit);
+			if (errors.length > 0) {
+				const error = new AggregateError(errors, "socket_serve_close_failed");
+				done.reject(error);
+				throw error;
+			}
+			done.resolve();
+		})();
+		return await closing;
+	};
+	const handleConnection = async (socket: net.Socket, signal: AbortSignal): Promise<void> => {
+		sockets.add(socket);
+		socket.once("close", () => sockets.delete(socket));
+		try {
+			const initialDownstreamBytes = await authenticatePreface(socket, options.token);
+			if (closing) {
+				socket.destroy();
+				return;
+			}
+			const pair = await startRelayPair({
+				...options,
+				signal,
+				downstream: socket,
+				downstreamSink: socket,
+				initialDownstreamBytes,
+				onTransportError: error => sendTransportError(socket, error),
+			});
+			pairs.add(pair);
+			try {
+				await pair.done.catch(() => undefined);
+			} finally {
+				pairs.delete(pair);
+				socket.end();
+			}
+		} catch {
+			socket.destroy();
+		}
+	};
+	server = net.createServer(socket => {
+		if (closing) {
+			socket.destroy();
+			return;
+		}
+		const controller = new AbortController();
+		dialControllers.add(controller);
+		const task = handleConnection(socket, controller.signal).finally(() => {
+			dialControllers.delete(controller);
+			connectionTasks.delete(task);
+		});
+		connectionTasks.add(task);
+		void task;
+	});
+	server.on("error", error => void close(error).catch(() => undefined));
+	await new Promise<void>((resolve, reject) => {
+		server?.once("error", reject);
+		server?.listen(options.socketPath, () => resolve());
+	});
+	const bound = await fs.lstat(options.socketPath);
+	if (!bound.isSocket()) {
+		await close();
+		throw socketFailure("socket_bind_failed");
+	}
+	ownedIdentity = { dev: bound.dev, ino: bound.ino };
+	try {
+		await fs.chmod(options.socketPath, 0o600);
+	} catch (error) {
+		await close();
+		throw error;
+	}
+	return { close, done: done.promise };
+}

package/src/sdk/transport/stdio.ts

@@ -0,0 +1,17 @@
+import type { ServeHandle, ServeOptions } from "./index";
+import { startRelayPair } from "./relay";
+
+function writeDiagnostic(value: unknown): void {
+	process.stderr.write(`${JSON.stringify(value)}\n`);
+}
+
+/** Serves one parent-owned JSONL connection over the process standard streams. */
+export async function startStdioServe(options: ServeOptions): Promise<ServeHandle> {
+	const pair = await startRelayPair({
+		...options,
+		downstream: process.stdin,
+		downstreamSink: process.stdout,
+		onTransportError: writeDiagnostic,
+	});
+	return { close: pair.close, done: pair.done };
+}