@iowarp/clio-coder 0.3.0 → 0.3.1

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

@@ -0,0 +1,205 @@
+import { type ChildProcessByStdio, spawn } from "node:child_process";
+import type { Readable } from "node:stream";
+
+import type { AutonomyLevel } from "../../domains/safety/autonomy.js";
+import { assertToolProfileEnforceable } from "../../tools/profiles.js";
+import { 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`. */
+const ANTIGRAVITY_BINARY = "agy";
+
+type AntigravityChildProcess = ChildProcessByStdio<null, 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 },
+};
+
+export interface AntigravitySubprocessConfig {
+	extraArgs: string[];
+	dangerousBypass: boolean;
+	externalMode: "plan+sandbox" | "bypassPermissions" | "agy-settings-default";
+}
+
+/**
+ * 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`.
+ */
+export function antigravitySubprocessConfigForAutonomy(
+	level: AutonomyLevel | undefined,
+	env: NodeJS.ProcessEnv = process.env,
+): AntigravitySubprocessConfig {
+	if (level === "full-auto" && env.CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS === "1") {
+		return {
+			extraArgs: ["--dangerously-skip-permissions"],
+			dangerousBypass: true,
+			externalMode: "bypassPermissions",
+		};
+	}
+	if (level === "suggest") {
+		throw new Error(
+			"antigravity-code runtime cannot enforce autonomy 'suggest': it cannot park tool calls for approval. Dispatch to a native or claude-sdk worker, or use read-only or auto-edit.",
+		);
+	}
+	if (level === "read-only") {
+		return { extraArgs: ["--mode", "plan", "--sandbox"], dangerousBypass: false, externalMode: "plan+sandbox" };
+	}
+	return { extraArgs: [], dangerousBypass: false, externalMode: "agy-settings-default" };
+}
+
+export function buildAntigravityPrompt(input: WorkerRunInput): string {
+	const parts: string[] = [];
+	const systemPrompt = input.systemPrompt.trim();
+	if (systemPrompt.length > 0) parts.push(systemPrompt);
+	for (const message of input.dynamicPromptMessages ?? []) {
+		const body = message.body.trim();
+		if (body.length > 0) parts.push(body);
+	}
+	parts.push(input.task);
+	return parts.join("\n\n");
+}
+
+export function buildAgyArgs(input: WorkerRunInput): string[] {
+	assertToolProfileEnforceable(input.toolProfile, "antigravity-code");
+	const permission = antigravitySubprocessConfigForAutonomy(input.autonomy);
+	const args = ["--print", ...permission.extraArgs];
+	if (input.wireModelId.trim().length > 0) args.push("--model", input.wireModelId.trim());
+	args.push(buildAntigravityPrompt(input));
+	return args;
+}
+
+function buildAssistantMessage(input: {
+	model: string;
+	text: string;
+	exitCode: number;
+	aborted: boolean;
+	stderr: string;
+}): AgentMessage & { role: "assistant" } {
+	const message: AgentMessage & { role: "assistant" } = {
+		role: "assistant",
+		content: [{ type: "text", text: input.text }],
+		api: "google-generative-ai",
+		provider: "google",
+		model: input.model,
+		usage: ZERO_USAGE,
+		stopReason: input.aborted ? "aborted" : input.exitCode === 0 ? "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;
+	}
+	return message;
+}
+
+function emitTextDelta(
+	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: "",
+	});
+	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 };
+	let aborted = false;
+	let killTimer: NodeJS.Timeout | null = null;
+
+	const abort = (): void => {
+		aborted = true;
+		if (child.killed) return;
+		child.kill("SIGTERM");
+		killTimer = setTimeout(() => {
+			if (!child.killed) child.kill("SIGKILL");
+		}, 1500);
+	};
+	if (input.signal) {
+		if (input.signal.aborted) abort();
+		else input.signal.addEventListener("abort", abort, { once: true });
+	}
+
+	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`);
+		}
+		return { messages, exitCode: exitCode === 0 ? 0 : 1 };
+	})();
+
+	return {
+		promise,
+		abort,
+	};
+}

package/src/engine/apis/degraded-inference.ts

@@ -0,0 +1,95 @@
+/**
+ * Degraded-inference watchdog for local runtimes.
+ *
+ * A local server whose weights or KV cache spilled to CPU does not fail: it
+ * answers, at roughly a hundredth of the speed, and the operator sees only a
+ * spinner. The observed case was 2m18s of streaming for 25 tokens with no
+ * indication that anything was wrong. This watchdog turns that silence into a
+ * notice: once a prediction has run past a grace period, a sustained token rate
+ * below the floor is reported once per turn, along with what is resident on the
+ * target so the cause is visible in the same line.
+ *
+ * The watchdog observes; it never cancels a turn. A slow model is still a
+ * working model, and the operator decides whether to abort.
+ */
+
+/** Wall-clock a prediction gets before its rate is judged. */
+export const DEGRADED_GRACE_MS = 30_000;
+/** Sustained output tokens per second below which inference is reported as degraded. */
+export const DEGRADED_FLOOR_TOKENS_PER_SECOND = 2;
+
+export interface DegradedInferenceReport {
+	elapsedMs: number;
+	tokens: number;
+	tokensPerSecond: number;
+}
+
+export interface DegradedInferenceOptions {
+	/** Called at most once, when the observed rate stays under the floor past the grace period. */
+	onDegraded: (report: DegradedInferenceReport) => void;
+	graceMs?: number;
+	floorTokensPerSecond?: number;
+	/** Sampling interval; the watchdog checks the rate this often. */
+	pollMs?: number;
+	now?: () => number;
+	setTimer?: (fn: () => void, ms: number) => { cancel: () => void };
+}
+
+export interface DegradedInferenceWatchdog {
+	/** Record generated tokens (output plus reasoning; both are work the server did). */
+	addTokens: (count: number) => void;
+	/** Test seam: evaluate the rate now instead of waiting for the next poll. */
+	check: () => void;
+	stop: () => void;
+}
+
+function defaultTimer(fn: () => void, ms: number): { cancel: () => void } {
+	const handle = setInterval(fn, ms);
+	handle.unref?.();
+	return { cancel: () => clearInterval(handle) };
+}
+
+/**
+ * Start watching a prediction's token rate. Call {@link
+ * DegradedInferenceWatchdog.addTokens} as fragments arrive and `stop()` when the
+ * turn ends, in a `finally`, so a failed turn never leaves a timer behind.
+ */
+export function startDegradedInferenceWatchdog(options: DegradedInferenceOptions): DegradedInferenceWatchdog {
+	const now = options.now ?? Date.now;
+	const graceMs = options.graceMs ?? DEGRADED_GRACE_MS;
+	const floor = options.floorTokensPerSecond ?? DEGRADED_FLOOR_TOKENS_PER_SECOND;
+	const pollMs = options.pollMs ?? 5_000;
+	const startedAt = now();
+	let tokens = 0;
+	let reported = false;
+	let stopped = false;
+
+	const check = (): void => {
+		if (reported || stopped) return;
+		const elapsedMs = now() - startedAt;
+		if (elapsedMs < graceMs) return;
+		const tokensPerSecond = tokens / (elapsedMs / 1000);
+		if (tokensPerSecond >= floor) return;
+		reported = true;
+		timer.cancel();
+		try {
+			options.onDegraded({ elapsedMs, tokens, tokensPerSecond });
+		} catch {
+			// A notice sink failure must never escape into the turn it describes.
+		}
+	};
+
+	const timer = (options.setTimer ?? defaultTimer)(check, pollMs);
+
+	return {
+		addTokens: (count) => {
+			if (Number.isFinite(count) && count > 0) tokens += count;
+		},
+		check,
+		stop: () => {
+			if (stopped) return;
+			stopped = true;
+			timer.cancel();
+		},
+	};
+}

package/src/engine/apis/index.ts

@@ -0,0 +1,20 @@
+import { registerApiProvider } from "@earendil-works/pi-ai/compat";
+
+import { lmstudioNativeApiProvider } from "./lmstudio-native.js";
+import { ollamaNativeApiProvider } from "./ollama-native.js";
+import { openAICompletionsApiProvider } from "./openai-completions.js";
+
+export { lmstudioNativeApiProvider } from "./lmstudio-native.js";
+export { ollamaNativeApiProvider } from "./ollama-native.js";
+export { openAICompletionsApiProvider } from "./openai-completions.js";
+export { setGlobalDefaultMaxOutputTokens } from "./output-budget.js";
+
+let registered = false;
+
+export function registerClioApiProviders(): void {
+	if (registered) return;
+	registered = true;
+	registerApiProvider(openAICompletionsApiProvider, "clio");
+	registerApiProvider(ollamaNativeApiProvider, "clio");
+	registerApiProvider(lmstudioNativeApiProvider, "clio");
+}

package/src/engine/apis/llamacpp-residency.ts

@@ -0,0 +1,252 @@
+import { performance } from "node:perf_hooks";
+import { sleep } from "../../core/timers.js";
+import {
+	type ResidencyAdapter,
+	reconcileResidency,
+	resetResidencyState,
+	residencyManaged,
+	residentTagProtected,
+} from "./residency.js";
+
+/**
+ * llama.cpp router adapter for the shared residency reconciler
+ * (residency.ts). The router is a multi-model server: `/v1/models` reports
+ * per-model load state and tags, `/props` advertises `max_instances`, and
+ * models load/unload through explicit POSTs. This module maps that surface
+ * onto the reconciler's "router" strategy so co-residency, capacity math,
+ * protection tiers, opt-outs, TTL dedupe, and the cross-process lock all come
+ * from the one shared policy. Plain llama-server builds without router load
+ * states are never managed.
+ */
+
+export interface LlamaCppResidencyInput {
+	/** OpenAI-compatible base URL, e.g. http://host:8080/v1. */
+	baseUrl: string;
+	targetId: string;
+	runtimeId: string;
+	keepModelId: string;
+	/**
+	 * Combined env + target lifecycle opt-out verdict from the caller
+	 * (residencyManagedFor). Defaults to the env-only switch.
+	 */
+	managed?: boolean;
+	fetchImpl?: typeof fetch;
+	now?: () => number;
+	ttlMs?: number;
+	/** Probe timeout; a residency probe must never stall a turn. */
+	timeoutMs?: number;
+	/** Test-only override for the cross-process mutation lock. */
+	withLock?<T>(targetKey: string, fn: () => Promise<T>): Promise<T>;
+}
+
+const LOAD_TIMEOUT_MS = 120_000;
+const POLL_INTERVAL_MS = 500;
+
+type LlamaCppModelState = "loaded" | "loading" | "unloaded" | "failed" | "unknown";
+
+interface LlamaCppResidentModel {
+	id: string;
+	tags: string[];
+}
+
+interface LlamaCppRouterModel extends LlamaCppResidentModel {
+	state: LlamaCppModelState;
+}
+
+interface LlamaCppRouterProps {
+	maxInstances?: number;
+}
+
+/** Test-only: clear the reconciler's TTL cache and Clio-loaded registry. */
+export function resetLlamaCppResidencyState(): void {
+	resetResidencyState();
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function routerModelState(entry: Record<string, unknown>): LlamaCppModelState {
+	const status = entry.status;
+	const state = isRecord(status) ? status.value : status;
+	if (state === "loaded" || state === "loading" || state === "unloaded" || state === "failed") return state;
+	return "unknown";
+}
+
+function parseRouterModels(payload: unknown): LlamaCppRouterModel[] {
+	if (!isRecord(payload)) return [];
+	const data = payload.data;
+	if (!Array.isArray(data)) return [];
+	const models: LlamaCppRouterModel[] = [];
+	for (const entry of data) {
+		if (!isRecord(entry) || typeof entry.id !== "string") continue;
+		const tags = Array.isArray(entry.tags) ? entry.tags.filter((tag): tag is string => typeof tag === "string") : [];
+		models.push({ id: entry.id, state: routerModelState(entry), tags });
+	}
+	return models;
+}
+
+function residentModel(model: LlamaCppRouterModel): boolean {
+	return model.state === "loaded" || model.state === "loading";
+}
+
+/** Extract resident (loaded or loading) model records from a /v1/models payload. */
+export function parseLlamaCppResidentModels(payload: unknown): LlamaCppResidentModel[] {
+	return parseRouterModels(payload)
+		.filter(residentModel)
+		.map((entry) => ({ id: entry.id, tags: entry.tags }));
+}
+
+/** Extract resident (loaded or loading) model ids from a /v1/models payload. */
+export function parseLlamaCppResident(payload: unknown): string[] {
+	return parseLlamaCppResidentModels(payload).map((entry) => entry.id);
+}
+
+export function parseLlamaCppRouterProps(payload: unknown): LlamaCppRouterProps {
+	if (!isRecord(payload)) return {};
+	const maxInstances = payload.max_instances;
+	return typeof maxInstances === "number" && Number.isFinite(maxInstances) && maxInstances > 0
+		? { maxInstances: Math.floor(maxInstances) }
+		: {};
+}
+
+function rootUrl(baseUrl: string): string {
+	return baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+
+function modelsUrl(baseUrl: string): string {
+	return `${baseUrl.replace(/\/+$/, "")}/models`;
+}
+
+function propsUrl(baseUrl: string): string {
+	return `${rootUrl(baseUrl)}/props`;
+}
+
+function loadUrl(baseUrl: string): string {
+	return `${rootUrl(baseUrl)}/models/load`;
+}
+
+function unloadUrl(baseUrl: string): string {
+	return `${rootUrl(baseUrl)}/models/unload`;
+}
+
+async function fetchRouterProps(input: LlamaCppResidencyInput, fetchImpl: typeof fetch): Promise<LlamaCppRouterProps> {
+	try {
+		const response = await fetchImpl(propsUrl(input.baseUrl), {
+			signal: AbortSignal.timeout(input.timeoutMs ?? 1500),
+		});
+		if (!response.ok) return {};
+		return parseLlamaCppRouterProps(await response.json());
+	} catch {
+		return {};
+	}
+}
+
+async function fetchRouterModels(
+	input: LlamaCppResidencyInput,
+	fetchImpl: typeof fetch,
+): Promise<LlamaCppRouterModel[]> {
+	const response = await fetchImpl(modelsUrl(input.baseUrl), {
+		signal: AbortSignal.timeout(input.timeoutMs ?? 1500),
+	});
+	if (!response.ok) throw new Error(`HTTP ${response.status}`);
+	return parseRouterModels(await response.json());
+}
+
+async function postRouterModel(fetchImpl: typeof fetch, url: string, modelId: string): Promise<void> {
+	const response = await fetchImpl(url, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ model: modelId }),
+		signal: AbortSignal.timeout(LOAD_TIMEOUT_MS),
+	});
+	if (response.ok) return;
+	throw new Error(`llama.cpp router rejected ${url}: HTTP ${response.status}`);
+}
+
+async function waitForLoaded(input: LlamaCppResidencyInput, fetchImpl: typeof fetch, modelId: string): Promise<void> {
+	const started = performance.now();
+	while (performance.now() - started < LOAD_TIMEOUT_MS) {
+		const models = await fetchRouterModels(input, fetchImpl);
+		const model = models.find((entry) => entry.id === modelId);
+		if (model?.state === "loaded") return;
+		if (model?.state === "failed") throw new Error(`llama.cpp router reports '${modelId}' failed to load`);
+		await sleep(POLL_INTERVAL_MS);
+	}
+	throw new Error(`timed out waiting for '${modelId}' to load`);
+}
+
+async function ensureModelLoaded(
+	input: LlamaCppResidencyInput,
+	fetchImpl: typeof fetch,
+	modelId: string,
+	knownState: LlamaCppModelState | undefined,
+): Promise<void> {
+	if (knownState === "loaded") return;
+	if (knownState !== "loading") await postRouterModel(fetchImpl, loadUrl(input.baseUrl), modelId);
+	await waitForLoaded(input, fetchImpl, modelId);
+}
+
+/**
+ * A router whose capacity Clio could not read may satisfy a load by
+ * displacing an LRU resident. Reload any tag-pinned resident the load
+ * displaced (one bounded pass), then verify the restore did not displace the
+ * keep model in turn.
+ */
+async function restoreDisplacedPinned(
+	input: LlamaCppResidencyInput,
+	fetchImpl: typeof fetch,
+	before: ReadonlyArray<LlamaCppRouterModel>,
+): Promise<void> {
+	const pinned = before.filter(
+		(entry) => residentModel(entry) && entry.id !== input.keepModelId && residentTagProtected(entry.tags),
+	);
+	if (pinned.length === 0) return;
+	const current = await fetchRouterModels(input, fetchImpl);
+	let changed = false;
+	for (const model of pinned) {
+		const state = current.find((entry) => entry.id === model.id)?.state;
+		if (state === "loaded") continue;
+		changed = true;
+		await ensureModelLoaded(input, fetchImpl, model.id, state);
+	}
+	if (!changed) return;
+	const finalModels = await fetchRouterModels(input, fetchImpl);
+	const keep = finalModels.find((entry) => entry.id === input.keepModelId);
+	if (keep?.state !== "loaded") throw new Error(`pinned-resident restore displaced '${input.keepModelId}'`);
+}
+
+/** Ensure the selected llama.cpp router model is resident before inference. */
+export async function ensureLlamaCppResidency(input: LlamaCppResidencyInput): Promise<void> {
+	const fetchImpl = input.fetchImpl ?? fetch;
+	let snapshot: LlamaCppRouterModel[] = [];
+	const adapter: ResidencyAdapter = {
+		targetKey: `llamacpp|${input.baseUrl}`,
+		targetId: input.targetId,
+		runtimeId: input.runtimeId,
+		keepModelId: input.keepModelId,
+		managed: input.managed ?? residencyManaged(),
+		strategy: "router",
+		listResident: async () => {
+			const models = await fetchRouterModels(input, fetchImpl);
+			if (!models.some((entry) => entry.state !== "unknown")) {
+				throw new Error("not a llama.cpp router: /v1/models reports no load states");
+			}
+			snapshot = models;
+			return models.filter(residentModel).map((entry) => ({ modelId: entry.id, tags: entry.tags }));
+		},
+		capacity: async () => (await fetchRouterProps(input, fetchImpl)).maxInstances,
+		keepModelTags: async () => snapshot.find((entry) => entry.id === input.keepModelId)?.tags,
+		unload: (modelId) => postRouterModel(fetchImpl, unloadUrl(input.baseUrl), modelId),
+		load: async (modelId) => {
+			const state = snapshot.find((entry) => entry.id === modelId)?.state;
+			if (state === "loaded") return;
+			await ensureModelLoaded(input, fetchImpl, modelId, state);
+			await restoreDisplacedPinned(input, fetchImpl, snapshot);
+		},
+	};
+	if (input.withLock) adapter.withLock = input.withLock;
+	if (input.now) adapter.now = input.now;
+	if (input.ttlMs !== undefined) adapter.ttlMs = input.ttlMs;
+	await reconcileResidency(adapter);
+}