@iowarp/clio-coder 0.4.2 → 0.4.3

package/src/engine/antigravity/subprocess-runtime.ts

@@ -1,45 +1,64 @@
 import { type ChildProcessByStdio, spawn } from "node:child_process";
-import type { Readable } from "node:stream";
+import type { Readable, Writable } from "node:stream";
 
+import { boundedExternalDiagnostic } from "../../core/external-diagnostic.js";
+import { buildSafeToolEnv, resolveSafeCwd } from "../../core/safe-exec.js";
 import type { AutonomyLevel } from "../../domains/safety/autonomy.js";
 import { assertToolProfileEnforceable } from "../../tools/profiles.js";
-import { readStderr, waitForClose } from "../external-subprocess.js";
+import { createProcessTreeTerminator, readBoundedLines, readStderr, waitForClose } from "../external-subprocess.js";
 import type { AgentEvent, AgentMessage, Usage } from "../types.js";
 import type { WorkerEventEmit, WorkerRunHandle, WorkerRunInput, WorkerRunResult } from "../worker-runtime.js";
 
-/** Binary name; resolved via PATH like the `claude` runner resolves `claude`. */
+/** Official CLI binary, resolved from the operator's PATH. */
 const ANTIGRAVITY_BINARY = "agy";
+export const ANTIGRAVITY_MAX_STREAM_LINE_BYTES = 1024 * 1024;
+export const ANTIGRAVITY_MAX_STREAM_BYTES = 8 * 1024 * 1024;
+export const ANTIGRAVITY_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+export const ANTIGRAVITY_MAX_PROMPT_BYTES = 4 * 1024 * 1024;
+const MAX_PROTOCOL_DIAGNOSTICS = 32;
+const MAX_CONVERSATION_ID_BYTES = 4096;
 
-type AntigravityChildProcess = ChildProcessByStdio<null, Readable, Readable>;
+type AntigravityChildProcess = ChildProcessByStdio<Writable, Readable, Readable>;
 
-const ZERO_USAGE: Usage = {
-	input: 0,
-	output: 0,
-	cacheRead: 0,
-	cacheWrite: 0,
-	totalTokens: 0,
-	cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+type AntigravityUsage = {
+	input_tokens?: unknown;
+	output_tokens?: unknown;
+	thinking_tokens?: unknown;
+	cache_read_tokens?: unknown;
+	total_tokens?: unknown;
 };
 
+type AntigravityResult = {
+	conversation_id?: unknown;
+	status?: unknown;
+	response?: unknown;
+	error?: unknown;
+	usage?: unknown;
+};
+
+export type AntigravityStreamEvent =
+	| { event: "init"; conversationId: string | null; model: string | null }
+	| { event: "text"; conversationId: string | null; delta: string }
+	| { event: "result"; result: AntigravityResult }
+	| { event: "other" };
+
 export interface AntigravitySubprocessConfig {
 	extraArgs: string[];
 	dangerousBypass: boolean;
-	externalMode: "plan+sandbox" | "bypassPermissions" | "agy-settings-default";
+	externalMode: "plan+sandbox" | "accept-edits" | "bypassPermissions";
+}
+
+export interface AntigravityRuntimeDependencies {
+	binary?: string;
+	workspaceRoot?: string;
+	environment?: NodeJS.ProcessEnv;
+	killGraceMs?: number;
 }
 
 /**
- * agy `--print` permission flags for a given autonomy level, mirroring the
- * Claude Code runner's posture against agy's coarser flag surface. agy exposes
- * an agent execution mode and a terminal sandbox, but no per-tool callback or
- * allowlist Clio can mediate.
- *
- *  - `full-auto` + `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1` opens the dangerous
- *    bypass (`--dangerously-skip-permissions`); nothing else does.
- *  - `read-only` runs `--mode plan --sandbox`: plan prevents agent edits and
- *    sandbox independently restricts terminal execution.
- *  - `suggest` is refused because `agy --print` cannot pause to ask.
- *  - `auto-edit` and ungated `full-auto` pass no permission flag and defer to
- *    agy's own `settings.json`.
+ * Translate Clio's effective autonomy ceiling to the official CLI's coarser
+ * modes. Every non-bypass launch is explicit, so changing interactive `agy`
+ * defaults cannot silently widen a delegated run.
  */
 export function antigravitySubprocessConfigForAutonomy(
 	level: AutonomyLevel | undefined,
@@ -60,7 +79,9 @@ export function antigravitySubprocessConfigForAutonomy(
 	if (level === "read-only") {
 		return { extraArgs: ["--mode", "plan", "--sandbox"], dangerousBypass: false, externalMode: "plan+sandbox" };
 	}
-	return { extraArgs: [], dangerousBypass: false, externalMode: "agy-settings-default" };
+	// Both auto-edit and ungated full-auto stay at agy's explicit
+	// accept-edits ceiling. Shell/network policy remains owned by agy.
+	return { extraArgs: ["--mode", "accept-edits"], dangerousBypass: false, externalMode: "accept-edits" };
 }
 
 function buildAntigravityPrompt(input: WorkerRunInput): string {
@@ -75,131 +96,376 @@ function buildAntigravityPrompt(input: WorkerRunInput): string {
 	return parts.join("\n\n");
 }
 
-function buildAgyArgs(input: WorkerRunInput): string[] {
+/** Official one-turn stream-json stdin record. JSON encoding keeps prompt text literal. */
+export function buildAgyStdinLine(input: WorkerRunInput): string {
+	const content = buildAntigravityPrompt(input);
+	if (Buffer.byteLength(content, "utf8") > ANTIGRAVITY_MAX_PROMPT_BYTES) {
+		throw new Error(`Antigravity work order exceeded ${ANTIGRAVITY_MAX_PROMPT_BYTES} bytes`);
+	}
+	return `${JSON.stringify({ event: "user", message: { content } })}\n`;
+}
+
+export function buildAgyArgs(input: WorkerRunInput, gateEnv: NodeJS.ProcessEnv = process.env): string[] {
 	assertToolProfileEnforceable(input.toolProfile, "antigravity-code");
-	const permission = antigravitySubprocessConfigForAutonomy(input.autonomy);
-	const args = ["--print", ...permission.extraArgs];
+	const permission = antigravitySubprocessConfigForAutonomy(input.autonomy, gateEnv);
+	const args = [
+		...permission.extraArgs,
+		"--input-format",
+		"stream-json",
+		"--output-format",
+		"stream-json",
+		"--disable-slash-commands",
+	];
 	if (input.wireModelId.trim().length > 0) args.push("--model", input.wireModelId.trim());
-	args.push(buildAntigravityPrompt(input));
 	return args;
 }
 
+function record(value: unknown): Record<string, unknown> | null {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: null;
+}
+
+/** Parse one event from agy's newline-delimited `stream-json` output. */
+export function parseAntigravityStreamLine(line: string): AntigravityStreamEvent | null {
+	let decoded: unknown;
+	try {
+		decoded = JSON.parse(line);
+	} catch {
+		return null;
+	}
+	const envelope = record(decoded);
+	if (!envelope || typeof envelope.event !== "string") return null;
+	if (envelope.event === "init") {
+		return {
+			event: "init",
+			conversationId: typeof envelope.conversation_id === "string" ? envelope.conversation_id : null,
+			model: typeof envelope.model === "string" ? envelope.model : null,
+		};
+	}
+	if (envelope.event === "step_update") {
+		const update = record(envelope.step_update);
+		if (!update) return null;
+		if (update.step_type !== "agent_response" || typeof update.text_delta !== "string") {
+			return { event: "other" };
+		}
+		return {
+			event: "text",
+			conversationId: typeof update.conversation_id === "string" ? update.conversation_id : null,
+			delta: update.text_delta,
+		};
+	}
+	if (envelope.event === "result") {
+		const result = record(envelope.result);
+		return result ? { event: "result", result } : null;
+	}
+	return { event: "other" };
+}
+
+function finite(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.min(value, Number.MAX_SAFE_INTEGER) : 0;
+}
+
+function normalizeUsage(raw: unknown): Usage {
+	const source = (record(raw) ?? {}) as AntigravityUsage;
+	const input = finite(source.input_tokens);
+	const output = finite(source.output_tokens);
+	const cacheRead = finite(source.cache_read_tokens);
+	const reasoningTokens = finite(source.thinking_tokens);
+	const usage: Usage & { reasoningTokens?: number } = {
+		input,
+		output,
+		cacheRead,
+		cacheWrite: 0,
+		totalTokens: finite(source.total_tokens) || input + output + reasoningTokens,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+	};
+	if (reasoningTokens > 0) usage.reasoningTokens = reasoningTokens;
+	return usage;
+}
+
+function appendBoundedText(current: string, delta: string): string {
+	if (Buffer.byteLength(current, "utf8") + Buffer.byteLength(delta, "utf8") > ANTIGRAVITY_MAX_RESPONSE_BYTES) {
+		throw new Error(`Antigravity response exceeded ${ANTIGRAVITY_MAX_RESPONSE_BYTES} bytes`);
+	}
+	return current + delta;
+}
+
+function boundedProviderField(value: unknown, field: string): string {
+	if (typeof value !== "string") return "";
+	if (Buffer.byteLength(value, "utf8") > ANTIGRAVITY_MAX_RESPONSE_BYTES) {
+		throw new Error(`Antigravity terminal ${field} exceeded ${ANTIGRAVITY_MAX_RESPONSE_BYTES} bytes`);
+	}
+	return value;
+}
+
+function boundedConversationId(value: unknown): string | null {
+	if (typeof value !== "string" || value.length === 0) return null;
+	return Buffer.byteLength(value, "utf8") <= MAX_CONVERSATION_ID_BYTES ? value : null;
+}
+
+interface StreamState {
+	started: boolean;
+	text: string;
+	model: string;
+	result: AntigravityResult | null;
+	conversationId: string | null;
+	initSeen: boolean;
+	terminalSeen: boolean;
+	protocolDiagnostics: string[];
+}
+
+function protocolFailure(state: StreamState, detail: string): void {
+	if (state.protocolDiagnostics.length < MAX_PROTOCOL_DIAGNOSTICS) state.protocolDiagnostics.push(detail);
+}
+
+function emitTextDelta(emit: WorkerEventEmit, state: StreamState, delta: string): void {
+	if (delta.length === 0) return;
+	state.text = appendBoundedText(state.text, delta);
+	if (!state.started) {
+		state.started = true;
+		emit({
+			type: "message_start",
+			message: buildAssistantMessage({
+				model: state.model,
+				text: "",
+				result: null,
+				conversationId: null,
+				exitCode: 0,
+				aborted: false,
+				diagnostic: "",
+			}),
+		} as AgentEvent);
+	}
+	// This runner is worker-only. The NDJSON event contract consumes the delta;
+	// cumulative message/partial copies are intentionally omitted.
+	emit({
+		type: "message_update",
+		assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta },
+	} as AgentEvent);
+}
+
+async function readStream(child: AntigravityChildProcess, emit: WorkerEventEmit, state: StreamState): Promise<void> {
+	for await (const bounded of readBoundedLines(child.stdout, {
+		maxLineBytes: ANTIGRAVITY_MAX_STREAM_LINE_BYTES,
+		maxTotalBytes: ANTIGRAVITY_MAX_STREAM_BYTES,
+	})) {
+		if (bounded.kind === "oversized") {
+			protocolFailure(state, "oversized structured output line");
+			continue;
+		}
+		const line = bounded.line;
+		if (!line.trim()) continue;
+		const event = parseAntigravityStreamLine(line);
+		if (!event) {
+			protocolFailure(state, "unreadable structured output line");
+			continue;
+		}
+		if (state.terminalSeen) {
+			protocolFailure(state, "event after terminal result");
+			continue;
+		}
+		switch (event.event) {
+			case "init":
+				if (state.initSeen) {
+					protocolFailure(state, "duplicate init event");
+					break;
+				}
+				state.initSeen = true;
+				state.conversationId = boundedConversationId(event.conversationId);
+				if (event.model?.trim()) state.model = event.model.trim();
+				break;
+			case "text":
+				if (!state.initSeen) {
+					protocolFailure(state, "text event before init");
+					break;
+				}
+				state.conversationId = boundedConversationId(event.conversationId) ?? state.conversationId;
+				emitTextDelta(emit, state, event.delta);
+				break;
+			case "result":
+				if (!state.initSeen) {
+					protocolFailure(state, "terminal result before init");
+					break;
+				}
+				state.terminalSeen = true;
+				state.result = event.result;
+				state.conversationId = boundedConversationId(event.result.conversation_id) ?? state.conversationId;
+				break;
+			case "other":
+				if (!state.initSeen) protocolFailure(state, "event before init");
+				break;
+		}
+	}
+}
+
+function resultDiagnostic(input: {
+	result: AntigravityResult | null;
+	exitCode: number;
+	spawnError: string;
+	stderr: string;
+	protocolDiagnostics: ReadonlyArray<string>;
+	streamError: string;
+	aborted: boolean;
+}): string {
+	if (input.aborted) return "Antigravity run was cancelled";
+	if (input.spawnError) return input.spawnError;
+	if (input.streamError) return input.streamError;
+	if (input.protocolDiagnostics.length > 0) {
+		return `Antigravity structured output violated the protocol: ${input.protocolDiagnostics.join("; ")}`;
+	}
+	if (input.result === null) {
+		return "Antigravity CLI ended without a terminal stream result. Update `agy` and verify stream-json support.";
+	}
+	if (input.result.status !== "SUCCESS") {
+		const providerError = boundedProviderField(input.result.error, "error").trim();
+		return providerError || `Antigravity returned terminal status ${String(input.result.status ?? "missing")}`;
+	}
+	if (input.exitCode !== 0) return `Antigravity returned SUCCESS but exited with status ${input.exitCode}`;
+	if (typeof input.result.response !== "string") return "Antigravity SUCCESS result omitted its required response";
+	// Successful structured output is authoritative. Some CLI builds write
+	// benign notices to stderr; retaining those as run failures would turn a
+	// valid SUCCESS terminal record into a protocol contradiction.
+	return "";
+}
+
 function buildAssistantMessage(input: {
 	model: string;
 	text: string;
+	result: AntigravityResult | null;
+	conversationId: string | null;
 	exitCode: number;
 	aborted: boolean;
-	stderr: string;
+	diagnostic: string;
 }): AgentMessage & { role: "assistant" } {
+	const succeeded =
+		!input.aborted &&
+		input.exitCode === 0 &&
+		input.result?.status === "SUCCESS" &&
+		typeof input.result.response === "string" &&
+		input.diagnostic.length === 0;
 	const message: AgentMessage & { role: "assistant" } = {
 		role: "assistant",
 		content: [{ type: "text", text: input.text }],
-		api: "google-generative-ai",
-		provider: "google",
+		api: "external-agent-subprocess",
+		provider: "antigravity",
 		model: input.model,
-		usage: ZERO_USAGE,
-		stopReason: input.aborted ? "aborted" : input.exitCode === 0 ? "stop" : "error",
+		usage: normalizeUsage(input.result?.usage),
+		stopReason: input.aborted ? "aborted" : succeeded ? "stop" : "error",
 		timestamp: Date.now(),
 	} as AgentMessage & { role: "assistant" };
-	if (input.exitCode !== 0 && !input.aborted) {
-		const detail = input.stderr.trim();
-		if (detail.length > 0) message.errorMessage = detail;
-	}
+	// Opaque provider observation only. This runtime never accepts it as a
+	// resumable Clio session id.
+	if (input.conversationId) message.responseId = input.conversationId;
+	if (input.diagnostic) message.errorMessage = boundedExternalDiagnostic(input.diagnostic);
 	return message;
 }
 
-function emitTextDelta(
+export function startAntigravityWorkerRun(
+	input: WorkerRunInput,
 	emit: WorkerEventEmit,
-	state: { started: boolean; text: string; model: string },
-	delta: string,
-): void {
-	if (delta.length === 0) return;
-	state.text += delta;
-	const message = buildAssistantMessage({
-		model: state.model,
-		text: state.text,
-		exitCode: 0,
-		aborted: false,
-		stderr: "",
+	dependencies: AntigravityRuntimeDependencies = {},
+): WorkerRunHandle {
+	const sourceEnv = dependencies.environment ?? process.env;
+	const args = buildAgyArgs(input, sourceEnv);
+	const stdinLine = buildAgyStdinLine(input);
+	const workspaceRoot = dependencies.workspaceRoot ?? process.cwd();
+	const cwd = resolveSafeCwd(input.cwd, workspaceRoot);
+	const child: AntigravityChildProcess = spawn(dependencies.binary ?? ANTIGRAVITY_BINARY, args, {
+		cwd,
+		env: buildSafeToolEnv({}, sourceEnv),
+		detached: process.platform !== "win32",
+		stdio: ["pipe", "pipe", "pipe"],
 	});
-	if (!state.started) {
-		state.started = true;
-		emit({ type: "message_start", message } as AgentEvent);
-	}
-	emit({
-		type: "message_update",
-		message,
-		assistantMessageEvent: {
-			type: "text_delta",
-			contentIndex: 0,
-			delta,
-			partial: message,
-		},
-	} as AgentEvent);
-}
-
-async function readStdout(
-	child: AntigravityChildProcess,
-	emit: WorkerEventEmit,
-	state: { started: boolean; text: string; model: string },
-): Promise<void> {
-	for await (const chunk of child.stdout) {
-		emitTextDelta(emit, state, String(chunk));
-	}
-}
-
-export function startAntigravityWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): WorkerRunHandle {
-	const args = buildAgyArgs(input);
-	const child = spawn(ANTIGRAVITY_BINARY, args, {
-		cwd: process.cwd(),
-		env: process.env,
-		stdio: ["ignore", "pipe", "pipe"],
-	});
-	const streamState = { started: false, text: "", model: input.wireModelId };
+	const streamState: StreamState = {
+		started: false,
+		text: "",
+		model: input.wireModelId,
+		result: null,
+		conversationId: null,
+		initSeen: false,
+		terminalSeen: false,
+		protocolDiagnostics: [],
+	};
 	let aborted = false;
-	let killTimer: NodeJS.Timeout | null = null;
-
+	let spawnError = "";
+	let streamError = "";
+	const terminator = createProcessTreeTerminator(child, dependencies.killGraceMs ?? 1500);
 	const abort = (): void => {
+		if (child.exitCode !== null) return;
 		aborted = true;
-		if (child.killed) return;
-		child.kill("SIGTERM");
-		killTimer = setTimeout(() => {
-			if (!child.killed) child.kill("SIGKILL");
-		}, 1500);
+		terminator.terminate();
 	};
-	if (input.signal) {
-		if (input.signal.aborted) abort();
-		else input.signal.addEventListener("abort", abort, { once: true });
-	}
+	const onAbort = (): void => abort();
+	if (input.signal?.aborted) abort();
+	else input.signal?.addEventListener("abort", onAbort, { once: true });
+	child.once("error", (cause) => {
+		spawnError =
+			(cause as NodeJS.ErrnoException).code === "ENOENT"
+				? "Antigravity CLI (`agy`) is not installed or not on PATH."
+				: boundedExternalDiagnostic(cause.message);
+	});
+	child.stdin.on("error", (cause) => {
+		if (!aborted) spawnError ||= boundedExternalDiagnostic(`could not send work order to Antigravity: ${cause.message}`);
+	});
+	child.stdin.end(stdinLine);
 
 	const promise = (async (): Promise<WorkerRunResult> => {
 		emit({ type: "agent_start" } as AgentEvent);
-		const stderrPromise = readStderr(child);
-		const stdoutPromise = readStdout(child, emit, streamState);
-		const exitCode = await waitForClose(child);
-		await stdoutPromise.catch(() => {});
-		const stderr = await stderrPromise.catch(() => "");
-		if (killTimer) clearTimeout(killTimer);
-		const finalText = streamState.text || (exitCode === 0 ? "" : stderr.trim());
-		const finalMessage = buildAssistantMessage({
-			model: streamState.model,
-			text: finalText,
-			exitCode,
-			aborted,
-			stderr,
-		});
-		if (!streamState.started) emit({ type: "message_start", message: finalMessage } as AgentEvent);
-		emit({ type: "message_end", message: finalMessage } as AgentEvent);
-		const messages: AgentMessage[] = [finalMessage];
-		emit({ type: "agent_end", messages } as AgentEvent);
-		if (exitCode !== 0 && stderr.trim().length > 0 && !aborted) {
-			process.stderr.write(`[worker:antigravity-code] ${stderr.trim()}\n`);
+		try {
+			const stderrPromise = readStderr(child);
+			const stdoutPromise = readStream(child, emit, streamState).catch((cause) => {
+				streamError = boundedExternalDiagnostic(cause instanceof Error ? cause.message : String(cause));
+				terminator.terminate();
+			});
+			const exitCode = await waitForClose(child);
+			await stdoutPromise;
+			const stderr = await stderrPromise.catch((cause) =>
+				boundedExternalDiagnostic(cause instanceof Error ? cause.message : String(cause)),
+			);
+			let terminalResponse = "";
+			try {
+				terminalResponse = boundedProviderField(streamState.result?.response, "response");
+			} catch (cause) {
+				streamError ||= boundedExternalDiagnostic(cause instanceof Error ? cause.message : String(cause));
+			}
+			let diagnostic = "";
+			try {
+				diagnostic = resultDiagnostic({
+					result: streamState.result,
+					exitCode,
+					spawnError,
+					stderr,
+					protocolDiagnostics: streamState.protocolDiagnostics,
+					streamError,
+					aborted,
+				});
+			} catch (cause) {
+				diagnostic = boundedExternalDiagnostic(cause instanceof Error ? cause.message : String(cause));
+			}
+			const finalText = terminalResponse || streamState.text;
+			const finalMessage = buildAssistantMessage({
+				model: streamState.model,
+				text: finalText,
+				result: streamState.result,
+				conversationId: streamState.conversationId,
+				exitCode,
+				aborted,
+				diagnostic,
+			});
+			if (!streamState.started) emit({ type: "message_start", message: finalMessage } as AgentEvent);
+			emit({ type: "message_end", message: finalMessage } as AgentEvent);
+			const messages: AgentMessage[] = [finalMessage];
+			emit({ type: "agent_end", messages } as AgentEvent);
+			if (finalMessage.stopReason === "error" && diagnostic && !aborted) {
+				process.stderr.write(`[worker:antigravity-code] ${boundedExternalDiagnostic(diagnostic)}\n`);
+			}
+			return { messages, exitCode: finalMessage.stopReason === "stop" ? 0 : 1 };
+		} finally {
+			terminator.cleanup();
+			input.signal?.removeEventListener("abort", onAbort);
 		}
-		return { messages, exitCode: exitCode === 0 ? 0 : 1 };
 	})();
 
-	return {
-		promise,
-		abort,
-	};
+	return { promise, abort };
 }

package/src/engine/api-registry.ts

@@ -176,6 +176,9 @@ export async function completeEngineSimple(
 	return engineStreamSimple(model, context, options).result();
 }
 
+/** Engine-owned fixture seam for decorating a faux transport before registration. */
+export { createFauxCore as createEngineFauxCore };
+
 export function registerEngineFauxProvider(options: RegisterFauxProviderOptions = {}): FauxProviderRegistration {
 	registerEngineBuiltins();
 	const core = createFauxCore(options);