@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/engine/acp/transport.ts

@@ -1,10 +1,43 @@
 import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
 import { performance } from "node:perf_hooks";
 import type { Readable, Writable } from "node:stream";
+import {
+	gitCommitAttributionEnabled,
+	reportCommitAttributionDiagnostic,
+	withManagedGitCommitAttributionEnvironment,
+} from "../../core/git-commit-attribution.js";
 import { MAX_TIMER_DELAY_MS } from "../../core/timers.js";
-import { AcpProcessError, AcpProtocolError, AcpTimeoutError } from "./errors.js";
+import {
+	ACP_INTERNAL_ERROR_MESSAGE,
+	ACP_METHOD_NOT_FOUND_MESSAGE,
+	AcpProcessError,
+	AcpProtocolError,
+	AcpRequestError,
+	AcpTimeoutError,
+	acpErrorData,
+	acpErrorMessage,
+} from "./errors.js";
 import type { AcpJsonRpcFailure, AcpJsonRpcMessage, AcpJsonRpcSuccess } from "./types.js";
 
+/**
+ * Largest single stdin line this process will buffer, in UTF-8 bytes. A
+ * newline-delimited protocol has no other backstop: without a bound, a peer
+ * that never sends a newline grows the pending buffer until the process dies.
+ * Past the bound the line is discarded up to the next newline, one error frame
+ * is emitted, and the channel stays open and parseable.
+ */
+export const ACP_MAX_INPUT_LINE_BYTES = 1024 * 1024;
+
+/**
+ * Cheap guard before the O(n) byte measurement. UTF-8 never spends more than
+ * three bytes on one UTF-16 code unit (a surrogate pair is two units and four
+ * bytes), so anything at or under a third of the bound cannot exceed it.
+ */
+function exceedsInputLineBytes(value: string): boolean {
+	if (value.length <= ACP_MAX_INPUT_LINE_BYTES / 3) return false;
+	return Buffer.byteLength(value, "utf8") > ACP_MAX_INPUT_LINE_BYTES;
+}
+
 type NotificationHandler = (params: unknown) => void;
 type RequestHandler = (params: unknown) => Promise<unknown> | unknown;
 type StderrHandler = (chunk: string) => void;
@@ -76,6 +109,12 @@ export interface StdioServerTransportOptions {
 	input?: Readable;
 	output?: Writable;
 	write?: (chunk: string) => void;
+	/**
+	 * Where the original text of an unclassified handler failure goes. Stdout is
+	 * JSON-RPC only, so the detail behind an `internal_error` frame lands on the
+	 * unstructured stderr tail (CONTRACT C001 §6). Defaults to dropping it.
+	 */
+	diagnostics?: (line: string) => void;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -124,6 +163,26 @@ function jsonRpcError(id: string | number | null, code: number, message: string,
 	};
 }
 
+/**
+ * The one serialization for a request handler that threw. A thrower that knows
+ * its failure raises {@link AcpRequestError} and owns the JSON-RPC code, the
+ * host-authored message, and the machine-readable detail; anything else is an
+ * internal error the client cannot act on beyond retrying, and its message is
+ * text no part of this process authored. Bounding that text was not enough:
+ * whatever threw can name an absolute path, a URL with credentials, or a token,
+ * and a bounded copy of a secret is still the secret. The frame carries fixed
+ * host text plus the `internal_error` code, the original goes to `diagnostics`,
+ * and neither form ever carries a stack, an echoed frame, or unbounded data.
+ */
+function handlerErrorFrame(id: string | number, err: unknown, diagnostics?: (line: string) => void): AcpJsonRpcFailure {
+	if (err instanceof AcpRequestError) {
+		const message = err.detail.code === "internal_error" ? ACP_INTERNAL_ERROR_MESSAGE : acpErrorMessage(err.message);
+		return jsonRpcError(id, err.rpcCode, message, acpErrorData(err.detail));
+	}
+	diagnostics?.(`internal error: ${acpErrorMessage(err)}`);
+	return jsonRpcError(id, -32000, ACP_INTERNAL_ERROR_MESSAGE, acpErrorData({ code: "internal_error" }));
+}
+
 class StdioJsonRpcTransport implements AcpJsonRpcTransport {
 	readonly child: ChildProcessWithoutNullStreams;
 	readonly terminationScope: AcpTerminationScope = process.platform === "win32" ? "child" : "process-group";
@@ -148,9 +207,18 @@ class StdioJsonRpcTransport implements AcpJsonRpcTransport {
 		this.childClosePromise = new Promise((resolve) => {
 			this.resolveChildClose = resolve;
 		});
+		const childEnvironment = options.env ? { ...process.env, ...options.env } : process.env;
+		// A delegated external harness authors its own commits. Clio only
+		// assisted by delegating, so no Co-authored-by is claimed for it.
+		const attribution = withManagedGitCommitAttributionEnvironment(childEnvironment, {
+			cwd: options.cwd ?? process.cwd(),
+			enabled: gitCommitAttributionEnabled(process.env),
+			evidence: { materiallyAssisted: true },
+		});
+		reportCommitAttributionDiagnostic(attribution.diagnostic);
 		this.child = spawn(command, args, {
 			cwd: options.cwd,
-			env: options.env ? { ...process.env, ...options.env } : process.env,
+			env: attribution.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
@@ -349,11 +417,7 @@ class StdioJsonRpcTransport implements AcpJsonRpcTransport {
 			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 },
-			});
+			this.write(handlerErrorFrame(id, err));
 		}
 	}
 
@@ -472,6 +536,8 @@ export function createStdioTransport(
 class StreamJsonRpcPeerTransport implements AcpJsonRpcPeerTransport {
 	private nextId = 1;
 	private buffer = "";
+	/** True while the bytes of an oversized line are being dropped up to its terminating newline. */
+	private discardingLine = false;
 	private isClosed = false;
 	private readonly pending = new Map<string | number, PendingRequest>();
 	private readonly notificationHandlers = new Map<string, Set<NotificationHandler>>();
@@ -480,13 +546,18 @@ class StreamJsonRpcPeerTransport implements AcpJsonRpcPeerTransport {
 	private readonly input: Readable;
 	private readonly output: Writable;
 	private readonly writeOverride?: (chunk: string) => void;
+	private readonly diagnostics?: (line: 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;
+		if (options.diagnostics !== undefined) this.diagnostics = options.diagnostics;
 		this.input.setEncoding("utf8");
 		this.input.on("data", (chunk: string) => this.consume(chunk));
+		// EOF with a nonblank partial frame drops that frame silently. A partial
+		// frame has no id, so there is no request to answer, and the channel it
+		// would be answered on is the one that just ended.
 		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)}`)));
@@ -560,6 +631,10 @@ class StreamJsonRpcPeerTransport implements AcpJsonRpcPeerTransport {
 			this.writeOverride(line);
 			return;
 		}
+		// A `false` return means the stream buffered rather than flushed. Honoring
+		// it means pausing frame production, which changes turn timing, so the
+		// decision to keep writing is deferred rather than forgotten (CONTRACT
+		// C001 §6 leaves stdout backpressure out of this profile).
 		this.output.write(line);
 	}
 
@@ -570,21 +645,53 @@ class StreamJsonRpcPeerTransport implements AcpJsonRpcPeerTransport {
 			if (idx === -1) break;
 			const line = this.buffer.slice(0, idx).trimEnd();
 			this.buffer = this.buffer.slice(idx + 1);
+			// The tail of a line already reported as oversized. Its newline ends the
+			// discard; the bytes before it are dropped without a second report.
+			if (this.discardingLine) {
+				this.discardingLine = false;
+				continue;
+			}
 			if (line.length === 0) continue;
+			// A complete but oversized line, which arrives when the whole line and
+			// its newline land in one chunk and the pending-buffer check below never
+			// saw it.
+			if (exceedsInputLineBytes(line)) {
+				this.reportOversizedLine();
+				continue;
+			}
 			this.handleLine(line);
 		}
+		if (this.discardingLine) {
+			this.buffer = "";
+			return;
+		}
+		// No newline yet: bound what is held for a line still being received.
+		if (exceedsInputLineBytes(this.buffer)) {
+			this.buffer = "";
+			this.discardingLine = true;
+			this.reportOversizedLine();
+		}
+	}
+
+	/** One error frame per oversized line. The transport stays open and parseable. */
+	private reportOversizedLine(): void {
+		this.write(
+			jsonRpcError(null, -32600, "input line exceeds the maximum size", acpErrorData({ code: "input_line_too_large" })),
+		);
 	}
 
 	private handleLine(line: string): void {
 		let parsed: unknown;
 		try {
 			parsed = JSON.parse(line);
-		} catch (err) {
-			this.write(jsonRpcError(null, -32700, `parse error: ${errorMessage(err)}`));
+		} catch {
+			// The parser's own message quotes the input it choked on, so the frame
+			// says only that parsing failed. The client already has the line.
+			this.write(jsonRpcError(null, -32700, "parse error", acpErrorData({ code: "parse_error" })));
 			return;
 		}
 		if (!isRecord(parsed) || parsed.jsonrpc !== "2.0") {
-			this.write(jsonRpcError(null, -32600, "invalid JSON-RPC message", parsed));
+			this.write(jsonRpcError(null, -32600, "invalid JSON-RPC message", acpErrorData({ code: "invalid_request" })));
 			return;
 		}
 		if (isSuccess(parsed) || isFailure(parsed)) {
@@ -594,7 +701,11 @@ class StreamJsonRpcPeerTransport implements AcpJsonRpcPeerTransport {
 		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));
+			if (id !== undefined) {
+				this.write(
+					jsonRpcError(id, -32600, "request/notification missing method", acpErrorData({ code: "invalid_request" })),
+				);
+			}
 			return;
 		}
 		if (id !== undefined) {
@@ -619,17 +730,27 @@ class StreamJsonRpcPeerTransport implements AcpJsonRpcPeerTransport {
 	}
 
 	private async handleRequest(id: string | number | null, method: string, params: unknown): Promise<void> {
-		if (id === null) return;
+		// A null id is a request nothing can answer, since a response correlates by
+		// id. Saying so beats the silent drop that left the caller waiting out its
+		// own timeout with no evidence of what happened.
+		if (id === null) {
+			this.write(jsonRpcError(null, -32600, "request id must not be null", acpErrorData({ code: "invalid_request_id" })));
+			return;
+		}
 		const handler = this.requestHandlers.get(method);
 		if (!handler) {
-			this.write(jsonRpcError(id, -32601, `method not found: ${method}`));
+			// The method name never goes back out. Bounding it was not enough: it is
+			// peer-controlled text on a channel where every message is authored by this
+			// process, and the client already knows which method it called. The frame
+			// carries fixed host text plus the `method_not_found` code.
+			this.write(jsonRpcError(id, -32601, ACP_METHOD_NOT_FOUND_MESSAGE, acpErrorData({ code: "method_not_found" })));
 			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));
+			this.write(handlerErrorFrame(id, err, this.diagnostics));
 		}
 	}
 

package/src/engine/acp/types.ts

@@ -8,6 +8,32 @@ import type { AgentMessage } from "../types.js";
 export const ACP_USAGE_META_KEY = "clio-coder/usage";
 export const ACP_SESSION_META_KEY = "clio-coder/session";
 
+/**
+ * Wire bounds for one prompt turn (CONTRACT C001 §3). A client renders every
+ * frame it receives, so an unbounded one is a denial-of-service on the client
+ * and a disclosure surface on the server: `rawInput` for a `write` carries the
+ * whole file body and for `bash` the whole command line.
+ *
+ * Every cap is UTF-8 bytes, which is what the peer's read buffer and any
+ * intermediary actually spend. `String.length` counts UTF-16 code units, so
+ * measuring with it let a chunk of CJK text reach three times its stated bound
+ * and a chunk of emoji twice.
+ */
+export const ACP_MAX_STRING_BYTES = 4096;
+export const ACP_MAX_RAW_RECORD_BYTES = 32768;
+export const ACP_MAX_CHUNK_BYTES = 16384;
+
+/**
+ * Upper bound on a `toolCallId` this server puts on the wire, in UTF-8 bytes
+ * (CONTRACT C001 §3). Identity is one call per id in both directions: an engine
+ * id over this bound, missing, or already claimed by another call this turn
+ * travels under a `clio-tool-<n>` alias, and an engine id starting a second call
+ * mints a fresh alias rather than reusing the first call's wire id. A permission
+ * request binds only to an id the client already received a `tool_call` for and
+ * has not yet seen finish; nothing is minted on that path.
+ */
+export const ACP_MAX_TOOL_CALL_ID_BYTES = 128;
+
 /** ACP v1 `ToolKind` closed enum (schema 0.4.5). */
 export type AcpToolKind =
 	| "read"

package/src/engine/agent.ts

@@ -5,13 +5,13 @@
  * separate state factory. AgentOptions drives the construction; the state is derived
  * from options.initialState on instantiation.
  *
- * pi-agent-core 0.83 requires an explicit stream function on every agent.
+ * pi-agent-core 0.84 requires an explicit stream function on every agent.
  * Clio's default is the compat `streamSimple` dispatcher (the same function the
  * pre-0.81 engine used implicitly); callers may override it for tests.
  */
 
 import { Agent, type AgentOptions, type StreamFn } from "@earendil-works/pi-agent-core";
-import { streamSimple } from "@earendil-works/pi-ai/compat";
+import { engineStreamSimple } from "./api-registry.js";
 
 export type EngineAgentOptions = Omit<AgentOptions, "streamFn"> & { streamFn?: StreamFn };
 
@@ -21,7 +21,7 @@ export interface EngineAgentHandle {
 }
 
 export function createEngineAgent(options: EngineAgentOptions = {}): EngineAgentHandle {
-	const agent = new Agent({ streamFn: streamSimple, ...options });
+	const agent = new Agent({ streamFn: engineStreamSimple, ...options });
 	return {
 		agent,
 		state: () => agent.state,

package/src/engine/ai.ts

@@ -13,7 +13,6 @@ import {
 	type Api,
 	type AssistantMessage,
 	fauxAssistantMessage,
-	fauxToolCall,
 	type KnownProvider,
 	type Model,
 	type ModelThinkingLevel,
@@ -21,27 +20,25 @@ import {
 	cleanupSessionResources as piCleanupSessionResources,
 	getSupportedThinkingLevels as piGetSupportedThinkingLevels,
 	isContextOverflow as piIsContextOverflow,
-	parseJsonWithRepair as piParseJsonWithRepair,
-	parseStreamingJson as piParseStreamingJson,
+	isRetryableAssistantError as piIsRetryableAssistantError,
 	validateToolArguments as piValidateToolArguments,
+	StringEnum,
 	type Tool,
 	type ToolCall,
 	type Usage,
 } from "@earendil-works/pi-ai";
 import {
-	getModels,
-	getProviders,
-	completeSimple as piCompleteSimple,
-	getModel as piGetModel,
-	stream as piStream,
-	registerBuiltInApiProviders,
-	registerFauxProvider,
-} from "@earendil-works/pi-ai/compat";
+	completeEngineSimple,
+	engineStream,
+	registerEngineBuiltins,
+	registerEngineFauxProvider,
+} from "./api-registry.js";
+import { engineModelProviders, engineModelsFor, getEngineModel } from "./models.js";
 import type { EngineModel } from "./types.js";
 
-export { fauxAssistantMessage, fauxToolCall, registerFauxProvider };
+export { StringEnum };
 
-export const stream = piStream;
+export const stream = engineStream;
 
 export interface EngineTextCompletionInput {
 	model: EngineModel;
@@ -62,7 +59,7 @@ export interface EngineTextCompletionResult {
 
 /** Run one tool-free completion while keeping pi message types at the engine boundary. */
 export async function completeEngineText(input: EngineTextCompletionInput): Promise<EngineTextCompletionResult> {
-	const response = await piCompleteSimple(
+	const response = await completeEngineSimple(
 		input.model,
 		{
 			systemPrompt: input.systemPrompt,
@@ -99,18 +96,18 @@ let registered = false;
 
 export function ensurePiAiRegistered(): void {
 	if (registered) return;
-	registerBuiltInApiProviders();
+	registerEngineBuiltins();
 	registered = true;
 }
 
 export function createEngineAi(): EngineAi {
 	ensurePiAiRegistered();
 	return {
-		listProviders: () => getProviders(),
-		listModels: (provider) => [...getModels(provider as never)] as EngineModel[],
+		listProviders: () => engineModelProviders(),
+		listModels: (provider) => engineModelsFor(provider) as EngineModel[],
 		getModel: (provider, modelId) => {
 			try {
-				return piGetModel(provider as never, modelId as never) as EngineModel;
+				return getEngineModel(provider, modelId) as EngineModel | undefined;
 			} catch {
 				return undefined;
 			}
@@ -152,6 +149,22 @@ export function isEngineContextOverflow(errorMessage: string, contextWindow?: nu
 	return piIsContextOverflow(message, contextWindow);
 }
 
+/** Classify one provider error through pi-ai without leaking its message shape across the engine boundary. */
+export function isEngineRetryableAssistantError(errorMessage: string): boolean {
+	const message: AssistantMessage = {
+		role: "assistant",
+		content: [],
+		api: "clio",
+		provider: "clio",
+		model: "unknown",
+		usage: emptyUsage(),
+		stopReason: "error",
+		errorMessage,
+		timestamp: Date.now(),
+	};
+	return piIsRetryableAssistantError(message);
+}
+
 export function validateEngineToolArguments(tool: Tool, toolCall: ToolCall): unknown {
 	return piValidateToolArguments(tool, toolCall);
 }
@@ -160,14 +173,6 @@ export function calculateEngineCost<TApi extends Api>(model: Model<TApi>, usage:
 	return piCalculateCost(model, usage);
 }
 
-export function parseEngineJsonWithRepair<T>(json: string): T {
-	return piParseJsonWithRepair<T>(json);
-}
-
-export function parseEngineStreamingJson<T = Record<string, unknown>>(partialJson: string | undefined): T {
-	return piParseStreamingJson<T>(partialJson);
-}
-
 /**
  * When `CLIO_CODER_WORKER_FAUX=1`, register the pi-ai faux provider and queue a
  * single deterministic assistant response. Used by the worker-entry diag so
@@ -186,7 +191,7 @@ export function registerFauxFromEnv(): EngineModel | null {
 	const text = process.env.CLIO_CODER_WORKER_FAUX_TEXT ?? "ok";
 	const stopReason = (process.env.CLIO_CODER_WORKER_FAUX_STOP_REASON ?? "stop") as AssistantMessage["stopReason"];
 	const errorMessage = process.env.CLIO_CODER_WORKER_FAUX_ERROR_MESSAGE;
-	const reg = registerFauxProvider({
+	const reg = registerEngineFauxProvider({
 		provider: "faux",
 		models: [{ id: modelId }],
 	});

package/src/engine/alcf-oauth.ts

@@ -121,7 +121,8 @@ export function grantToCredentials(grant: GlobusTokenGrant, previousRefresh?: st
 	};
 }
 
-async function postForm(body: Record<string, string>): Promise<GlobusTokenResponse> {
+async function postForm(body: Record<string, string>, signal?: AbortSignal): Promise<GlobusTokenResponse> {
+	const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000);
 	const response = await fetch(TOKEN_URL, {
 		method: "POST",
 		headers: {
@@ -129,7 +130,7 @@ async function postForm(body: Record<string, string>): Promise<GlobusTokenRespon
 			Accept: "application/json",
 		},
 		body: new URLSearchParams(body).toString(),
-		signal: AbortSignal.timeout(30_000),
+		signal: requestSignal,
 	});
 	const text = await response.text();
 	if (!response.ok) {
@@ -145,23 +146,29 @@ async function postForm(body: Record<string, string>): Promise<GlobusTokenRespon
 	return parsed as GlobusTokenResponse;
 }
 
-async function exchangeCode(code: string, verifier: string): Promise<OAuthCredentials> {
-	const payload = await postForm({
-		grant_type: "authorization_code",
-		client_id: AUTH_CLIENT_ID,
-		code,
-		code_verifier: verifier,
-		redirect_uri: REDIRECT_URI,
-	});
+async function exchangeCode(code: string, verifier: string, signal?: AbortSignal): Promise<OAuthCredentials> {
+	const payload = await postForm(
+		{
+			grant_type: "authorization_code",
+			client_id: AUTH_CLIENT_ID,
+			code,
+			code_verifier: verifier,
+			redirect_uri: REDIRECT_URI,
+		},
+		signal,
+	);
 	return grantToCredentials(selectGatewayGrant(payload));
 }
 
-async function refreshGatewayToken(refreshToken: string): Promise<OAuthCredentials> {
-	const payload = await postForm({
-		grant_type: "refresh_token",
-		client_id: AUTH_CLIENT_ID,
-		refresh_token: refreshToken,
-	});
+async function refreshGatewayToken(refreshToken: string, signal: AbortSignal): Promise<OAuthCredentials> {
+	const payload = await postForm(
+		{
+			grant_type: "refresh_token",
+			client_id: AUTH_CLIENT_ID,
+			refresh_token: refreshToken,
+		},
+		signal,
+	);
 	return grantToCredentials(selectGatewayGrant(payload), refreshToken);
 }
 
@@ -179,7 +186,7 @@ export async function loginAlcf(callbacks: OAuthLoginCallbacks): Promise<OAuthCr
 	const code = parseAuthorizationInput(pasted);
 	if (!code) throw new Error("No authorization code was provided.");
 	callbacks.onProgress?.("Exchanging authorization code for an ALCF access token...");
-	return exchangeCode(code, verifier);
+	return exchangeCode(code, verifier, callbacks.signal);
 }
 
 export const alcfOAuthProvider: EngineOAuthProvider = {
@@ -189,8 +196,8 @@ export const alcfOAuthProvider: EngineOAuthProvider = {
 	login(callbacks) {
 		return loginAlcf(callbacks);
 	},
-	refreshToken(credentials) {
-		return refreshGatewayToken(credentials.refresh);
+	refreshToken(credentials, signal) {
+		return refreshGatewayToken(credentials.refresh, signal);
 	},
 	async getApiKey(credentials) {
 		return credentials.access;