@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/domains/providers/runtime-resolution.ts

@@ -273,6 +273,34 @@ function appendThinkingDiagnostics(
 	diagnostics.push(diagnostic(severity, `thinking-${thinking.noticeKind}`, thinking.notice));
 }
 
+const CHAT_TEMPLATE_KWARGS_UNDELIVERABLE = "chat-template-kwargs-undeliverable";
+
+/**
+ * One warning when the family declares chat-template kwargs the runtime
+ * cannot carry (#268). LM Studio ignores `chat_template_kwargs` for every
+ * family measured, so a Nemotron 3.5 target on that runtime runs without the
+ * `force_nonempty_content` its card asks for; the operator sees that once per
+ * target and model rather than finding the key silently missing from the wire.
+ */
+function appendChatTemplateKwargsDiagnostics(
+	diagnostics: RuntimeResolutionDiagnostic[],
+	resolved: ResolvedModelRuntimeCapabilities,
+): void {
+	const undeliverable = resolved.request.undeliverableChatTemplateKwargs;
+	if (!undeliverable || undeliverable.keys.length === 0) return;
+	const keys = undeliverable.keys.join(", ");
+	const declared = undeliverable.declaredUnsupported
+		? "its family entry marks them unsupported there"
+		: "its family entry does not say so";
+	diagnostics.push(
+		diagnostic(
+			"warning",
+			CHAT_TEMPLATE_KWARGS_UNDELIVERABLE,
+			`chat-template kwargs ${keys} cannot reach ${resolved.runtimeId}, which ignores chat_template_kwargs; ${resolved.modelId} runs without them and ${declared}`,
+		),
+	);
+}
+
 function nonNegativeFiniteNumber(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
 }
@@ -447,6 +475,7 @@ export function resolveRuntimeTarget(
 	const decisions = capabilityDecisions(runtime, capabilities);
 	appendCapabilityDiagnostics(diagnostics, input, capabilities, decisions, targetId);
 	appendThinkingDiagnostics(diagnostics, modelRuntime, requestedThinkingLevel);
+	appendChatTemplateKwargsDiagnostics(diagnostics, modelRuntime);
 
 	if (hasError(diagnostics)) return { ok: false, diagnostics };
 
@@ -493,6 +522,7 @@ function withoutStaleRuntimeDiagnostics(
 ): RuntimeResolutionDiagnostic[] {
 	return diagnostics.filter((entry) => {
 		if (entry.code.startsWith("thinking-")) return false;
+		if (entry.code === CHAT_TEMPLATE_KWARGS_UNDELIVERABLE) return false;
 		if (entry.code === "output-budget-unknown" && decisions.maxTokens > 0) return false;
 		if (entry.code === "tools-unsupported" && decisions.tools) return false;
 		return true;
@@ -545,6 +575,7 @@ export function refineRuntimeTargetWithModelHints(
 	const decisions = capabilityDecisions(target.runtime, capabilities);
 	const diagnostics = withoutStaleRuntimeDiagnostics(target.diagnostics, decisions);
 	appendThinkingDiagnostics(diagnostics, modelRuntime, target.requestedThinkingLevel);
+	appendChatTemplateKwargsDiagnostics(diagnostics, modelRuntime);
 	return {
 		...target,
 		capabilities,

package/src/domains/providers/runtimes/antigravity/antigravity-code.ts

@@ -1,78 +1,258 @@
+import { boundedExternalDiagnostic } from "../../../../core/external-diagnostic.js";
+import { runCommandVector, type SafeCommandResult } from "../../../../core/safe-exec.js";
 import type { Api, Model } from "../../../../engine/types.js";
 
 import { synthesizeCatalogBackedModel } from "../../catalog.js";
 import type { CapabilityFlags } from "../../types/capability-flags.js";
 import type { KnowledgeBaseHit } from "../../types/knowledge-base.js";
-import type { RuntimeDescriptor } from "../../types/runtime-descriptor.js";
+import type { ProbeContext, ProbeResult, RuntimeDescriptor } from "../../types/runtime-descriptor.js";
 import type { TargetDescriptor } from "../../types/target-descriptor.js";
 
 /**
- * Antigravity CLI (`agy`) subscription runtime.
+ * Antigravity CLI (`agy`) external delegation runtime.
  *
- * A subprocess worker runtime that drives the local `agy --print`, the same
- * shape as the `claude-code` runtime: Clio spawns the CLI, streams its output,
- * and maps Clio autonomy levels onto the CLI's permission flags. `agy` brings
- * Google's Antigravity agent harness (Gemini 3.x and hosted Claude/GPT-OSS
- * models, up to ~1M tokens of context) to the Clio worker fleet.
- *
- * `agy --print` prints plain text (there is no structured event stream), so the
- * worker runner cannot mediate individual agy tool calls the way the Claude SDK
- * runner does. Permission gating is coarse: `--mode plan --sandbox` for
- * read-only runs and `--dangerously-skip-permissions` only under `full-auto`
- * plus the explicit `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1` environment gate.
- * agy's own `settings.json` still governs modes that Clio does not explicitly
- * constrain.
+ * This is deliberately a dispatch-only subprocess, not a Gemini inference
+ * provider. The installed official CLI owns authentication, its agent loop,
+ * tools, network access, and model access. Clio supplies one bounded work order
+ * and translates the documented structured result into a worker result.
  */
 
 export const ANTIGRAVITY_AUTH_NOTICE =
-	"Uses your existing Antigravity (`agy`) login. Clio stores no Antigravity credentials. " +
-	"agy runs its own agent harness as a subprocess; Clio maps autonomy levels onto its CLI flags " +
-	"but cannot mediate individual agy tool calls.";
+	"Experimental local delegation through your installed Antigravity (`agy`) CLI. Clio neither signs in nor stores " +
+	"or inspects Antigravity credentials. Run `agy` yourself and complete sign-in before probing this target.";
 
-// Exact model strings accepted by `agy --model` (from `agy models`). The High
-// Flash tier leads: it is the fast, large-context default.
+// Hints only until an account returns a live catalog. They are never used to
+// validate a model after a successful live probe.
 export const ANTIGRAVITY_MODELS: ReadonlyArray<string> = [
-	"Gemini 3.5 Flash (High)",
-	"Gemini 3.5 Flash (Medium)",
-	"Gemini 3.5 Flash (Low)",
-	"Gemini 3.1 Pro (High)",
-	"Gemini 3.1 Pro (Low)",
-	"Claude Sonnet 4.6 (Thinking)",
-	"Claude Opus 4.6 (Thinking)",
-	"GPT-OSS 120B (Medium)",
+	"gemini-3.8-flash-high",
+	"gemini-3.8-flash-medium",
+	"gemini-3.8-flash-low",
+	"gemini-3.1-pro-high",
+	"gemini-3.1-pro-low",
 ];
 
+/** Typed Clio capabilities only. Antigravity's own opaque tools are declared separately. */
 export const antigravityCapabilities: CapabilityFlags = {
 	chat: true,
-	tools: true,
-	toolCallFormat: "openai",
-	reasoning: true,
-	vision: true,
+	tools: false,
+	reasoning: false,
+	vision: false,
 	audio: false,
 	embeddings: false,
 	rerank: false,
 	fim: false,
-	contextWindow: 1_000_000,
-	maxTokens: 8192,
+	contextWindow: 0,
+	maxTokens: 0,
 };
 
+export const ANTIGRAVITY_MAX_CATALOG_BYTES = 1024 * 1024;
+export const ANTIGRAVITY_MAX_DISCOVERED_MODELS = 4096;
+const MAX_MODEL_ID_CHARS = 1024;
+const MAX_MODEL_LABEL_CHARS = 1024;
+
+type AntigravityProbeFailureKind = NonNullable<ProbeResult["failureKind"]>;
+
+class AntigravityCatalogError extends Error {
+	readonly kind: AntigravityProbeFailureKind;
+
+	constructor(kind: AntigravityProbeFailureKind, message: string) {
+		super(message);
+		this.name = "AntigravityCatalogError";
+		this.kind = kind;
+	}
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: null;
+}
+
+export interface AntigravityModelCatalog {
+	models: string[];
+	labels: Record<string, string>;
+}
+
+/** Decode the machine-readable catalog emitted by `agy --output-format json models`. */
+export function parseAntigravityModelCatalogDetails(output: string): AntigravityModelCatalog {
+	let decoded: unknown;
+	try {
+		decoded = JSON.parse(output);
+	} catch {
+		throw new AntigravityCatalogError(
+			"unsupported-feature",
+			"agy returned an unreadable model catalog; update the Antigravity CLI and retry",
+		);
+	}
+	const envelope = record(decoded);
+	const command = record(envelope?.command);
+	const data = record(command?.data);
+	if (envelope?.status !== "SUCCESS") {
+		const detail = boundedExternalDiagnostic(
+			typeof envelope?.error === "string"
+				? envelope.error
+				: typeof command?.error === "string"
+					? command.error
+					: "agy could not list models",
+		);
+		const kind = classifyAntigravityDiagnostic(detail);
+		throw new AntigravityCatalogError(kind, antigravityProbeMessage(kind, detail));
+	}
+	if (command?.name !== "models" || !Array.isArray(data?.models)) {
+		throw new AntigravityCatalogError(
+			"unsupported-feature",
+			"agy returned an unsupported model catalog; update the Antigravity CLI and retry",
+		);
+	}
+	if (data.models.length === 0) {
+		throw new AntigravityCatalogError(
+			"catalog-unavailable",
+			"agy returned no available models; run `agy` locally and verify the signed-in account has model access",
+		);
+	}
+	if (data.models.length > ANTIGRAVITY_MAX_DISCOVERED_MODELS) {
+		throw new AntigravityCatalogError(
+			"catalog-unavailable",
+			`agy returned more than ${ANTIGRAVITY_MAX_DISCOVERED_MODELS} models; the authoritative catalog was refused rather than truncated`,
+		);
+	}
+
+	const models: string[] = [];
+	const labels: Record<string, string> = {};
+	const seen = new Set<string>();
+	for (const value of data.models) {
+		const model = record(value);
+		const id = typeof model?.id === "string" ? model.id.trim() : "";
+		const label = typeof model?.label === "string" ? model.label.trim() : "";
+		if (id.length === 0 || id.length > MAX_MODEL_ID_CHARS || /[\r\n\0]/u.test(id)) {
+			throw new AntigravityCatalogError("catalog-unavailable", "agy returned an invalid model identifier");
+		}
+		if (label.length === 0 || label.length > MAX_MODEL_LABEL_CHARS || /[\r\n\0]/u.test(label)) {
+			throw new AntigravityCatalogError("catalog-unavailable", `agy returned an invalid label for model '${id}'`);
+		}
+		if (seen.has(id)) {
+			if (labels[id] !== label) {
+				throw new AntigravityCatalogError(
+					"catalog-unavailable",
+					`agy returned conflicting labels for duplicate model '${id}'`,
+				);
+			}
+			continue;
+		}
+		seen.add(id);
+		models.push(id);
+		labels[id] = label;
+	}
+	return { models, labels };
+}
+
+function classifyAntigravityDiagnostic(detail: string): AntigravityProbeFailureKind {
+	if (/(?:enoent|not found|cannot find|could not start|spawn .*agy)/iu.test(detail)) return "missing";
+	if (/(?:sign[ -]?in|log[ -]?in|unauthori[sz]ed|authenticat|credential|account.*required)/iu.test(detail)) {
+		return "authentication";
+	}
+	if (
+		/(?:unknown|unsupported|unrecognized|invalid) (?:option|argument|command)|output-format|models command/iu.test(detail)
+	) {
+		return "unsupported-feature";
+	}
+	return "generic";
+}
+
+function antigravityProbeMessage(kind: AntigravityProbeFailureKind, detail: string): string {
+	const safeDetail = boundedExternalDiagnostic(detail || "no diagnostic was provided");
+	switch (kind) {
+		case "missing":
+			return "Antigravity CLI is not installed or `agy` is not on PATH";
+		case "authentication":
+			return `Antigravity sign-in is required; run \`agy\` yourself and complete sign-in (${safeDetail})`;
+		case "unsupported-feature":
+			return `the installed Antigravity CLI does not expose the required structured model catalog; update \`agy\` (${safeDetail})`;
+		case "catalog-unavailable":
+			return safeDetail;
+		case "cancelled":
+			return "Antigravity model discovery was cancelled";
+		default:
+			return `Antigravity model discovery failed: ${safeDetail}`;
+	}
+}
+
+export async function probeAntigravityModelCatalog(
+	ctx: ProbeContext,
+	runner: typeof runCommandVector = runCommandVector,
+): Promise<ProbeResult> {
+	const result: SafeCommandResult = await runner("agy", ["--output-format", "json", "models"], {
+		cwd: process.cwd(),
+		workspaceRoot: process.cwd(),
+		timeoutMs: Math.max(1, ctx.httpTimeoutMs),
+		maxOutputBytes: ANTIGRAVITY_MAX_CATALOG_BYTES,
+		...(ctx.signal ? { signal: ctx.signal } : {}),
+	});
+	if (result.aborted || result.timedOut) {
+		return {
+			ok: false,
+			latencyMs: result.durationMs,
+			failureKind: "cancelled",
+			error: antigravityProbeMessage("cancelled", ""),
+		};
+	}
+	if (result.outputCapped) {
+		return {
+			ok: false,
+			latencyMs: result.durationMs,
+			failureKind: "catalog-unavailable",
+			error: `agy model catalog exceeded ${ANTIGRAVITY_MAX_CATALOG_BYTES} bytes`,
+		};
+	}
+	if (result.exitCode !== 0) {
+		const detail = boundedExternalDiagnostic(result.stderr || result.stdout || `agy exited ${String(result.exitCode)}`);
+		const kind = classifyAntigravityDiagnostic(detail);
+		return { ok: false, latencyMs: result.durationMs, failureKind: kind, error: antigravityProbeMessage(kind, detail) };
+	}
+	try {
+		const catalog = parseAntigravityModelCatalogDetails(result.stdout);
+		return {
+			ok: true,
+			latencyMs: result.durationMs,
+			models: catalog.models,
+			modelLabels: catalog.labels,
+		};
+	} catch (cause) {
+		const kind = cause instanceof AntigravityCatalogError ? cause.kind : "generic";
+		const detail = cause instanceof Error ? cause.message : String(cause);
+		return { ok: false, latencyMs: result.durationMs, failureKind: kind, error: boundedExternalDiagnostic(detail) };
+	}
+}
+
 const antigravityCodeRuntime: RuntimeDescriptor = {
 	id: "antigravity-code",
-	displayName: "Antigravity CLI",
+	displayName: "Antigravity CLI — experimental local delegation",
 	kind: "subprocess",
 	tier: "subscription",
-	// Reuses the existing `google-generative-ai` api family: the worker branches
-	// to its own runner before any pi-ai inference, so this only needs to be a
-	// valid, google-backed family. The runner is selected by runtime id, and the
-	// plain-text parser is named by `outputParser`.
-	apiFamily: "google-generative-ai",
+	apiFamily: "external-agent-subprocess",
 	auth: "none",
 	authNotice: ANTIGRAVITY_AUTH_NOTICE,
 	knownModels: [...ANTIGRAVITY_MODELS],
 	binaryName: "agy",
-	headlessCommand: "agy --print",
-	outputParser: "antigravity-print-text",
+	headlessCommand: "agy --input-format stream-json --output-format stream-json",
+	outputParser: "antigravity-stream-json",
 	defaultCapabilities: antigravityCapabilities,
+	externalAgentLoop: {
+		tools: "externally-governed-unobserved",
+		network: "externally-governed-unobserved",
+		budget: "external-one-shot",
+		generatingRetry: "forbidden",
+		modelCatalog: "live-authoritative",
+	},
+	async probe(_target: TargetDescriptor, ctx: ProbeContext) {
+		try {
+			return await probeAntigravityModelCatalog(ctx);
+		} catch (cause) {
+			const detail = boundedExternalDiagnostic(cause instanceof Error ? cause.message : String(cause));
+			const kind = classifyAntigravityDiagnostic(detail);
+			return { ok: false, failureKind: kind, error: antigravityProbeMessage(kind, detail) };
+		}
+	},
 	synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api> {
 		return synthesizeCatalogBackedModel({
 			target,
@@ -80,9 +260,9 @@ const antigravityCodeRuntime: RuntimeDescriptor = {
 			kb,
 			defaultCapabilities: antigravityCapabilities,
 			runtimeId: "antigravity-code",
-			api: "google-generative-ai",
-			provider: "google",
-			defaultBaseUrl: "antigravity://local",
+			api: "external-agent-subprocess",
+			provider: "antigravity",
+			defaultBaseUrl: "external-agent://antigravity/local",
 		});
 	},
 };

package/src/domains/providers/runtimes/common/lmstudio-http.ts

@@ -300,9 +300,13 @@ export function lmStudioReasoningLevels(options: ReadonlyArray<string> | undefin
 export function lmStudioReasoningEffort(
 	level: ThinkingLevel,
 	options?: ReadonlyArray<string>,
-): "none" | "low" | "medium" | "high" {
+): "none" | "low" | "medium" | "high" | undefined {
+	// `allowed_options` describes the model's binary setting, but LM Studio's
+	// OpenAI-compatible request schema still accepts only effort-level values.
+	// Omit an active override for binary/default-on models; sending `low` works
+	// only through a warning and sending the advertised literal `on` is a 400.
+	if (options?.includes("on") && options.includes("off")) return level === "off" ? "none" : undefined;
 	if (level === "off") return "none";
-	if (options?.includes("on") && !options.includes("medium") && !options.includes("high")) return "low";
 	if (level === "medium" && options?.includes("medium") !== false) return "medium";
 	if ((level === "high" || level === "xhigh" || level === "max") && options?.includes("high") !== false) return "high";
 	return "low";

package/src/domains/providers/runtimes/common/local-synth.ts

@@ -24,6 +24,7 @@ export interface ClioLocalModelMetadata {
 		quirks?: LocalModelQuirks;
 		chatTemplateKwargsUnsupported?: boolean;
 		lmstudio?: TargetDescriptor["lmstudio"];
+		litellm?: TargetDescriptor["litellm"];
 	};
 }
 
@@ -109,6 +110,7 @@ export function synthLocalModel(input: LocalSynthesisInput): Model<Api> {
 			...(kb?.entry.family ? { family: kb.entry.family } : {}),
 			...(quirks ? { quirks } : {}),
 			...(target.lmstudio ? { lmstudio: target.lmstudio } : {}),
+			...(target.litellm ? { litellm: target.litellm } : {}),
 		},
 	};
 	if (headers) model.headers = headers;

package/src/domains/providers/runtimes/common/probe-helpers.ts

@@ -374,6 +374,8 @@ export interface LlamaCppStatusEnrichment {
 	modelId?: string;
 	serverFlags?: LlamaCppServerFlags;
 	notes?: string[];
+	/** The router's own load state for the selected model, when it reports one. */
+	loadState?: ProbeModelStatus["state"];
 }
 
 function argsFromStatus(status: unknown): string[] {
@@ -490,8 +492,11 @@ export async function probeLlamaCppModelStatus(
 	const entries = await probeOpenAIModelEntries(base, ctx);
 	const selected = selectedModelEntry(entries, target);
 	if (!selected) return {};
+	const loadState = modelStateFromOpenAIModelEntry({ id: selected.id, status: selected.status })?.state;
+	const withState = (enrichment: LlamaCppStatusEnrichment): LlamaCppStatusEnrichment =>
+		loadState === undefined ? enrichment : { ...enrichment, loadState };
 	const args = argsFromStatus(selected.status);
-	if (args.length === 0) return { notes: statusNotes(selected.id, selected.status) };
+	if (args.length === 0) return withState({ notes: statusNotes(selected.id, selected.status) });
 	const flags = parseLlamaCppServerFlags(args);
 	const caps: Partial<CapabilityFlags> = {};
 	const window = llamaCppRequestContextWindow(flags);
@@ -512,7 +517,7 @@ export async function probeLlamaCppModelStatus(
 		);
 	}
 	if (notes.length > 0) enrichment.notes = notes;
-	return enrichment;
+	return withState(enrichment);
 }
 
 /**

package/src/domains/providers/runtimes/local-native/llamacpp.ts

@@ -56,7 +56,15 @@ const llamacppRuntime: RuntimeDescriptor = {
 		const health = await (ctx.signal ? probeHttp({ ...healthOpts, signal: ctx.signal }) : probeHttp(healthOpts));
 		if (!health.ok) return health;
 		const status = await probeLlamaCppModelStatus(base, target, ctx);
-		const props = await probeLlamaCppProps(base, ctx, status.modelId ?? target.defaultModel);
+		// A router answers /props?model=<id> by loading that model, and with
+		// --models-max 1 that evicts whatever is resident: every probe of a
+		// fleet target's default model unloaded the chat model, so the next turn
+		// prefilled from zero (11,601 tokens, cache_n 0, on the round-3 resume
+		// run on mini). The router's model list already carries the worker's
+		// flags (--parallel, --ctx-size) for an unloaded model, so the worker is
+		// asked only when it is resident.
+		const resident = status.loadState === undefined || status.loadState === "loaded";
+		const props = await probeLlamaCppProps(base, ctx, resident ? (status.modelId ?? target.defaultModel) : undefined);
 		const catalog = await probeOpenAIModelCatalog(base, ctx);
 		const result: ProbeResult = { ok: true };
 		if (catalog.models.length > 0) result.models = catalog.models;