@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/engine/ai.ts

@@ -27,9 +27,11 @@ import {
 	type ToolCall,
 	type Usage,
 } from "@earendil-works/pi-ai";
+import type { BackendCompletionTimings } from "../core/cache-telemetry.js";
 import {
 	completeEngineSimple,
 	engineStream,
+	engineStreamSimple,
 	registerEngineBuiltins,
 	registerEngineFauxProvider,
 } from "./api-registry.js";
@@ -40,6 +42,14 @@ export { StringEnum };
 
 export const stream = engineStream;
 
+/**
+ * The dispatcher a turn runs on. `createEngineAgent` hands this to pi-agent-core
+ * as its `streamFn`, so a caller that needs a request byte-identical to the one
+ * the next turn would send (the session pre-warm) sends it through here rather
+ * than through `stream`, whose bare-call path has to guess a thinking level.
+ */
+export const streamSimple = engineStreamSimple;
+
 export interface EngineTextCompletionInput {
 	model: EngineModel;
 	systemPrompt: string;
@@ -55,6 +65,21 @@ export interface EngineTextCompletionResult {
 	text: string;
 	inputTokens: number;
 	outputTokens: number;
+	/**
+	 * The provider's full usage record for the call, so a caller that has to
+	 * account for the spend does not have to re-derive it from two token counts.
+	 */
+	usage: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+		reasoning: number;
+		totalTokens: number;
+		costUsd: number;
+	};
+	/** Backend prefill and prediction facts when the serving runtime reported them. */
+	backend: BackendCompletionTimings | null;
 }
 
 /** Run one tool-free completion while keeping pi message types at the engine boundary. */
@@ -83,6 +108,16 @@ export async function completeEngineText(input: EngineTextCompletionInput): Prom
 			.join(""),
 		inputTokens: response.usage.input,
 		outputTokens: response.usage.output,
+		usage: {
+			input: response.usage.input,
+			output: response.usage.output,
+			cacheRead: response.usage.cacheRead,
+			cacheWrite: response.usage.cacheWrite,
+			reasoning: response.usage.reasoning ?? 0,
+			totalTokens: response.usage.totalTokens,
+			costUsd: response.usage.cost.total,
+		},
+		backend: response.backendTimings ?? null,
 	};
 }
 

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

@@ -1,4 +1,5 @@
 import { performance } from "node:perf_hooks";
+import { residencyTargetKey } from "../../core/residency-target-key.js";
 import { sleep } from "../../core/timers.js";
 import {
 	type ResidencyAdapter,
@@ -169,6 +170,26 @@ async function fetchRouterModels(
 	return parseRouterModels(await response.json());
 }
 
+class RouterModelPostError extends Error {
+	constructor(
+		readonly url: string,
+		readonly status: number,
+		readonly responseBody: string,
+	) {
+		super(`llama.cpp router rejected ${url}: HTTP ${status}; response: ${responseBody}`);
+		this.name = "RouterModelPostError";
+	}
+}
+
+async function routerErrorBody(response: Response): Promise<string> {
+	try {
+		const body = (await response.text()).trim();
+		return body.length > 0 ? body : "<empty body>";
+	} catch (error) {
+		return `<unreadable body: ${error instanceof Error ? error.message : String(error)}>`;
+	}
+}
+
 async function postRouterModel(fetchImpl: typeof fetch, url: string, modelId: string): Promise<void> {
 	const response = await fetchImpl(url, {
 		method: "POST",
@@ -177,7 +198,38 @@ async function postRouterModel(fetchImpl: typeof fetch, url: string, modelId: st
 		signal: AbortSignal.timeout(LOAD_TIMEOUT_MS),
 	});
 	if (response.ok) return;
-	throw new Error(`llama.cpp router rejected ${url}: HTTP ${response.status}`);
+	throw new RouterModelPostError(url, response.status, await routerErrorBody(response));
+}
+
+function alreadyRunningResponse(body: string): boolean {
+	return body.toLowerCase().includes("already running");
+}
+
+/**
+ * A router wake and Clio's explicit load can cross between the listing and the
+ * POST. In that race the router rejects the duplicate request even though the
+ * requested model now owns a resident slot. Re-read the authoritative listing
+ * before treating a non-2xx as a load failure; only a definitively absent,
+ * unloaded, or failed model preserves the rejection.
+ */
+async function postRouterLoad(input: LlamaCppResidencyInput, fetchImpl: typeof fetch, modelId: string): Promise<void> {
+	try {
+		await postRouterModel(fetchImpl, loadUrl(input.baseUrl), modelId);
+	} catch (error) {
+		if (!(error instanceof RouterModelPostError)) throw error;
+		let model: LlamaCppRouterModel | undefined;
+		try {
+			model = (await fetchRouterModels(input, fetchImpl)).find((entry) => entry.id === modelId);
+		} catch {
+			// The router's explicit "already running" answer is sufficient even if
+			// the confirming snapshot itself races or is temporarily unavailable.
+			if (alreadyRunningResponse(error.responseBody)) return;
+			throw error;
+		}
+		if (alreadyRunningResponse(error.responseBody)) return;
+		if (model !== undefined && model.state !== "unloaded" && model.state !== "failed") return;
+		throw error;
+	}
 }
 
 async function waitForLoaded(input: LlamaCppResidencyInput, fetchImpl: typeof fetch, modelId: string): Promise<void> {
@@ -206,7 +258,7 @@ async function ensureModelLoaded(
 	// router answers `400 model is already running`, which fails the turn before
 	// it reaches the model.
 	if (knownState === "loaded" || knownState === "sleeping") return;
-	if (knownState !== "loading") await postRouterModel(fetchImpl, loadUrl(input.baseUrl), modelId);
+	if (knownState !== "loading") await postRouterLoad(input, fetchImpl, modelId);
 	await waitForLoaded(input, fetchImpl, modelId);
 }
 
@@ -246,7 +298,7 @@ export async function ensureLlamaCppResidency(input: LlamaCppResidencyInput): Pr
 	const fetchImpl = input.fetchImpl ?? fetch;
 	let snapshot: LlamaCppRouterModel[] = [];
 	const adapter: ResidencyAdapter = {
-		targetKey: `llamacpp|${input.baseUrl}`,
+		targetKey: residencyTargetKey("llamacpp", input.baseUrl),
 		targetId: input.targetId,
 		runtimeId: input.runtimeId,
 		keepModelId: input.keepModelId,

package/src/engine/apis/lmstudio.ts

@@ -1,5 +1,6 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 
+import { residencyTargetKey } from "../../core/residency-target-key.js";
 import {
 	type LmStudioCatalog,
 	type LmStudioLoadedInstance,
@@ -11,7 +12,7 @@ import {
 } from "../../domains/providers/runtimes/common/lmstudio-http.js";
 import type { TargetDescriptor } from "../../domains/providers/types/target-descriptor.js";
 import { coResidentContextCeiling, fitLoadContextLength } from "./lmstudio-residency.js";
-import { emitResidencyNotice, reconcileResidency, residencyManagedFor } from "./residency.js";
+import { emitResidencyMutation, emitResidencyNotice, reconcileResidency, residencyManagedFor } from "./residency.js";
 import { withResidencyLock } from "./residency-lock.js";
 
 interface LmStudioModelMetadata {
@@ -205,7 +206,7 @@ export async function ensureLmStudioResidency(
 		entry.loadedInstances.map((instance) => ({ modelKey: entry.key, identifier: instance.id, instance })),
 	);
 	const managed = residencyManagedFor(info.lifecycle);
-	const targetKey = `lmstudio|${lmStudioRootUrl(target.url ?? model.baseUrl)}`;
+	const targetKey = residencyTargetKey("lmstudio", target.url ?? model.baseUrl);
 	const contextLength = target.lmstudio?.load?.contextLength;
 	const plan = await reconcileResidency({
 		targetKey,
@@ -248,17 +249,36 @@ export async function ensureLmStudioResidency(
 			});
 		}
 	}
+	const loadAndReport = async (): Promise<string> => {
+		const instanceId = await loadOwnedInstance(target, targetKey, body, options.apiKey, options.signal);
+		emitResidencyMutation({
+			targetKey,
+			targetId: info.targetId,
+			runtimeId: "lmstudio",
+			model: modelKey,
+			operation: "load",
+		});
+		return instanceId ?? model.id;
+	};
 	try {
-		return (await loadOwnedInstance(target, targetKey, body, options.apiKey, options.signal)) ?? model.id;
+		return await loadAndReport();
 	} catch (error) {
 		if (plan.decision === "observe" || plan.fallbackEvict.length === 0) throw error;
 		return withResidencyLock(targetKey, async () => {
 			for (const candidate of plan.fallbackEvict) {
 				for (const entry of instances.filter((resident) => resident.modelKey === candidate.modelId)) {
-					await unloadOwnedInstance(target, targetKey, entry.identifier, options.apiKey, options.signal);
+					if (await unloadOwnedInstance(target, targetKey, entry.identifier, options.apiKey, options.signal)) {
+						emitResidencyMutation({
+							targetKey,
+							targetId: info.targetId,
+							runtimeId: "lmstudio",
+							model: candidate.modelId,
+							operation: "evict",
+						});
+					}
 				}
 			}
-			return (await loadOwnedInstance(target, targetKey, body, options.apiKey, options.signal)) ?? model.id;
+			return loadAndReport();
 		});
 	}
 }

package/src/engine/apis/ollama-native.ts

@@ -24,6 +24,7 @@ import {
 	type Tool as OllamaTool,
 	type ToolCall as OllamaToolCall,
 } from "ollama";
+import { residencyTargetKey } from "../../core/residency-target-key.js";
 import {
 	type AppliedThinking,
 	resolveModelRuntimeCapabilitiesForModel,
@@ -75,7 +76,7 @@ async function reconcileOllamaResidency(model: Model<"ollama-native">, headers:
 	if (!baseUrl) return;
 	const metadata = (model as Model<"ollama-native"> & ClioRuntimeMetadata).clio;
 	const adapter: ResidencyAdapter = {
-		targetKey: `ollama-native|${baseUrl}`,
+		targetKey: residencyTargetKey("ollama-native", baseUrl),
 		targetId: ollamaTargetId(model),
 		runtimeId: "ollama-native",
 		keepModelId: model.id,

package/src/engine/apis/openai-completions.ts

@@ -16,6 +16,7 @@ import {
 	type Usage,
 } from "@earendil-works/pi-ai";
 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
+import type { BackendCompletionTimings, BackendTimingsSource } from "../../core/cache-telemetry.js";
 import type { ResponseModelIdObservation } from "../../core/response-model-id.js";
 import {
 	type AppliedThinking,
@@ -41,6 +42,8 @@ declare module "@earendil-works/pi-ai" {
 	interface AssistantMessage {
 		/** Direct observation of model-id presence in an OpenAI-compatible response. */
 		responseModelIdObservation?: ResponseModelIdObservation;
+		/** Backend-reported prefill and prediction timings when available. */
+		backendTimings?: BackendCompletionTimings;
 	}
 }
 
@@ -95,13 +98,57 @@ function isPlainRecord(value: unknown): value is Record<string, unknown> {
 interface ResponseModelIdCapture {
 	reportedModelId: string | null;
 	observed: boolean;
-	done: boolean;
+	modelIdDone: boolean;
+	backendTimings: BackendCompletionTimings | null;
+	backendTimingsSource: BackendTimingsSource | null;
 	buffer: string;
 	decoder: TextDecoder | null;
 }
 
-function observeResponseModelIdLine(line: string, capture: ResponseModelIdCapture): void {
-	if (capture.done) return;
+function nonnegativeFiniteNumber(value: unknown): number | null {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+/**
+ * The operator's llama.cpp router reported build b226-2115b73d8. Its nonstream
+ * response placed a `{ prompt_n, prompt_ms, predicted_n, predicted_ms, cache_n }`
+ * timing object at the top level. Its stream placed the timing object on the
+ * final SSE JSON event without `timings_per_token`. Setting
+ * `timings_per_token: true` repeated cumulative timing objects for individual
+ * tokens. LM Studio's OpenAI-compatible stream and nonstream responses omitted
+ * timings both with and without that flag. Its native runtime reported
+ * llama.cpp-win-x86_64-nvidia-cuda12-avx2 2.29.0.
+ */
+function backendCompletionTimings(value: unknown, source: BackendTimingsSource): BackendCompletionTimings | null {
+	if (!isPlainRecord(value)) return null;
+	const promptN = nonnegativeFiniteNumber(value.prompt_n);
+	const predictedN = nonnegativeFiniteNumber(value.predicted_n);
+	const promptMs = nonnegativeFiniteNumber(value.prompt_ms);
+	const predictedMs = nonnegativeFiniteNumber(value.predicted_ms);
+	if (promptN === null || predictedN === null || promptMs === null || predictedMs === null) return null;
+	const cacheN = nonnegativeFiniteNumber(value.cache_n);
+	return {
+		promptTokens: promptN + (cacheN ?? 0),
+		cachedTokens: cacheN,
+		predictedTokens: predictedN,
+		promptMs,
+		predictedMs,
+		source,
+	};
+}
+
+function backendTimingsSourceForModel(model: Model<Api>): BackendTimingsSource | null {
+	const metadata = (model as Model<Api> & ClioRuntimeMetadata).clio;
+	if (model.provider === "llamacpp" && metadata?.runtimeId === "llamacpp") return "llamacpp-timings";
+	if (model.provider === "lmstudio" && metadata?.runtimeId === "lmstudio") return "lmstudio-timings";
+	return null;
+}
+
+function captureCanStopEarly(capture: ResponseModelIdCapture): boolean {
+	return capture.modelIdDone && capture.backendTimingsSource === null;
+}
+
+function observeResponseMetadataLine(line: string, capture: ResponseModelIdCapture): void {
 	const normalized = line.endsWith("\r") ? line.slice(0, -1) : line;
 	if (!normalized.startsWith("data:")) return;
 	const data = normalized.slice("data:".length).trimStart();
@@ -109,10 +156,16 @@ function observeResponseModelIdLine(line: string, capture: ResponseModelIdCaptur
 	try {
 		const payload = JSON.parse(data) as unknown;
 		if (!isPlainRecord(payload)) return;
-		const model = payload.model;
-		if (typeof model === "string" && model.trim().length > 0) {
-			capture.reportedModelId = model.trim();
-			capture.done = true;
+		if (!capture.modelIdDone) {
+			const model = payload.model;
+			if (typeof model === "string" && model.trim().length > 0) {
+				capture.reportedModelId = model.trim();
+				capture.modelIdDone = true;
+			}
+		}
+		if (capture.backendTimingsSource !== null) {
+			const timings = backendCompletionTimings(payload.timings, capture.backendTimingsSource);
+			if (timings !== null) capture.backendTimings = timings;
 		}
 	} catch {
 		// A partial or vendor-specific event is pi-ai's parsing concern. This
@@ -125,14 +178,14 @@ function observeResponseModelIdBytes(
 	capture: ResponseModelIdCapture,
 	flush = false,
 ): void {
-	if (capture.done || !capture.decoder) return;
+	if (!capture.decoder) return;
 	capture.buffer += chunk ? capture.decoder.decode(chunk, { stream: !flush }) : capture.decoder.decode();
 	let newline = capture.buffer.indexOf("\n");
 	while (newline >= 0) {
 		const line = capture.buffer.slice(0, newline);
 		capture.buffer = capture.buffer.slice(newline + 1);
-		observeResponseModelIdLine(line, capture);
-		if (capture.done) {
+		observeResponseMetadataLine(line, capture);
+		if (captureCanStopEarly(capture)) {
 			capture.buffer = "";
 			capture.decoder = null;
 			return;
@@ -140,10 +193,10 @@ function observeResponseModelIdBytes(
 		newline = capture.buffer.indexOf("\n");
 	}
 	if (flush && capture.buffer.length > 0) {
-		observeResponseModelIdLine(capture.buffer, capture);
+		observeResponseMetadataLine(capture.buffer, capture);
 		capture.buffer = "";
 	}
-	if (capture.done || flush) capture.decoder = null;
+	if (captureCanStopEarly(capture) || flush) capture.decoder = null;
 }
 
 function captureResponseModelId(response: Response, capture: ResponseModelIdCapture): Response {
@@ -154,12 +207,12 @@ function captureResponseModelId(response: Response, capture: ResponseModelIdCapt
 		new TransformStream<Uint8Array, Uint8Array>({
 			transform(chunk, controller) {
 				capture.observed = true;
-				if (!capture.done) observeResponseModelIdBytes(chunk, capture);
+				observeResponseModelIdBytes(chunk, capture);
 				controller.enqueue(chunk);
 			},
 			flush() {
 				capture.observed = true;
-				if (!capture.done) observeResponseModelIdBytes(undefined, capture, true);
+				observeResponseModelIdBytes(undefined, capture, true);
 			},
 		}),
 	);
@@ -171,13 +224,16 @@ function captureResponseModelId(response: Response, capture: ResponseModelIdCapt
 }
 
 function withResponseModelIdCapture<TOptions extends StreamOptions>(
+	model: Model<Api>,
 	options: TOptions,
 	sourceFactory: (capturedOptions: TOptions) => AssistantMessageEventStream,
 ): AssistantMessageEventStream {
 	const capture: ResponseModelIdCapture = {
 		reportedModelId: null,
 		observed: false,
-		done: false,
+		modelIdDone: false,
+		backendTimings: null,
+		backendTimingsSource: backendTimingsSourceForModel(model),
 		buffer: "",
 		decoder: new TextDecoder(),
 	};
@@ -197,8 +253,13 @@ function withResponseModelIdCapture<TOptions extends StreamOptions>(
 						? { state: "not-reported" }
 						: { state: "reported", reportedModelId: capture.reportedModelId }
 					: { state: "not-observed" };
-				if (event.type === "done") event.message.responseModelIdObservation = observation;
-				else if (event.type === "error") event.error.responseModelIdObservation = observation;
+				if (event.type === "done") {
+					event.message.responseModelIdObservation = observation;
+					if (capture.backendTimings !== null) event.message.backendTimings = capture.backendTimings;
+				} else if (event.type === "error") {
+					event.error.responseModelIdObservation = observation;
+					if (capture.backendTimings !== null) event.error.backendTimings = capture.backendTimings;
+				}
 				annotated.push(event as AssistantMessageEvent);
 			}
 			annotated.end();
@@ -863,6 +924,7 @@ export const openAICompletionsApiProvider: EngineApiProvider<"openai-completions
 					stripNeverReasoningFromStream(
 						filterGemmaChannelStream(
 							withResponseModelIdCapture(
+								model,
 								withRemainingContextBudget(model, effectiveContext, withSamplers),
 								(capturedOptions) =>
 									withLocalResidency(
@@ -895,6 +957,7 @@ export const openAICompletionsApiProvider: EngineApiProvider<"openai-completions
 					stripNeverReasoningFromStream(
 						filterGemmaChannelStream(
 							withResponseModelIdCapture(
+								model,
 								withRemainingContextBudget(model, effectiveContext, withSamplers),
 								(capturedOptions) =>
 									withLocalResidency(

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

@@ -12,12 +12,14 @@
 import { join } from "node:path";
 import { withStateFileLock } from "../../core/state-file-lock.js";
 import { clioStatePath } from "../../core/xdg.js";
+import { canonicalEndpointKey } from "../../domains/providers/endpoint-capacity.js";
 
 /** Total time one process waits for another's mutation before proceeding unlocked. */
 const LOCK_WAIT_MS = 120_000;
 
 function lockTargetFor(targetKey: string): string {
-	return join(clioStatePath(), "residency-locks", targetKey.replace(/[^a-zA-Z0-9._-]+/g, "_"));
+	const key = canonicalEndpointKey(targetKey) ?? targetKey;
+	return join(clioStatePath(), "residency-locks", key.replace(/[^a-zA-Z0-9._-]+/g, "_"));
 }
 
 /** Run `fn` while holding the per-target residency lock. */

package/src/engine/apis/residency.ts

@@ -35,7 +35,12 @@
  * unload/load against the same server.
  */
 
-import { BusChannels, type RuntimeNoticeKind, type RuntimeNoticePayload } from "../../core/bus-events.js";
+import {
+	BusChannels,
+	type ResidencyMutationPayload,
+	type RuntimeNoticeKind,
+	type RuntimeNoticePayload,
+} from "../../core/bus-events.js";
 import type { ProtectedModelRef, ResidencyRole } from "../../core/residency-protection.js";
 import { getSharedBus } from "../../core/shared-bus.js";
 import { withResidencyLock } from "./residency-lock.js";
@@ -73,6 +78,11 @@ export function emitResidencyNotice(notice: ResidencyNotice): void {
 	}
 }
 
+/** Publish one successful residency mutation to in-process cache telemetry. */
+export function emitResidencyMutation(mutation: Omit<ResidencyMutationPayload, "at">): void {
+	getSharedBus().emit(BusChannels.ResidencyMutation, { ...mutation, at: Date.now() });
+}
+
 // --- configured-model protection ---------------------------------------------
 
 // Wire model ids the operator's own configuration references, with the role
@@ -543,6 +553,13 @@ async function restoreEvictedModels(
 		try {
 			await adapter.reloadEvicted(entry.modelId);
 			restored.push(entry.modelId);
+			emitResidencyMutation({
+				targetKey: adapter.targetKey,
+				targetId: adapter.targetId,
+				runtimeId: adapter.runtimeId,
+				model: entry.modelId,
+				operation: "load",
+			});
 		} catch {
 			failed.push(entry.modelId);
 		}
@@ -705,6 +722,13 @@ export async function reconcileResidency(adapter: ResidencyAdapter): Promise<Rec
 					await adapter.unload(entry.modelId);
 					forgetClioLoaded(adapter.targetKey, entry.modelId);
 					evicted.push(entry);
+					emitResidencyMutation({
+						targetKey: adapter.targetKey,
+						targetId: adapter.targetId,
+						runtimeId: adapter.runtimeId,
+						model: entry.modelId,
+						operation: "evict",
+					});
 				} catch {
 					// Best-effort: a failed unload self-heals on the next reconcile.
 				}
@@ -712,6 +736,15 @@ export async function reconcileResidency(adapter: ResidencyAdapter): Promise<Rec
 			if (!adapter.load) return;
 			try {
 				await adapter.load(adapter.keepModelId);
+				if (!plan.keepResident) {
+					emitResidencyMutation({
+						targetKey: adapter.targetKey,
+						targetId: adapter.targetId,
+						runtimeId: adapter.runtimeId,
+						model: adapter.keepModelId,
+						operation: "load",
+					});
+				}
 			} catch (error) {
 				// The eviction bought nothing: the slot it freed is still empty and
 				// the target is now serving less than before the reconcile. Put back

package/src/engine/claude/sdk-module.ts

@@ -0,0 +1,98 @@
+/**
+ * Lazy loader for the optional `@anthropic-ai/claude-agent-sdk` package.
+ *
+ * The SDK's platform package ships a 224MB proprietary binary, so it lives in
+ * `optionalDependencies` and a default install skips it under
+ * `npm install --omit=optional`. Nothing may import it at module scope: boot,
+ * `doctor`, and every non-Claude runtime have to work on an install that never
+ * fetched it. The one value the runtime needs (`query`) is reached through the
+ * dynamic import below, at the moment a `claude-sdk` run actually starts, and a
+ * missing package surfaces as a typed error naming the package and the install
+ * command instead of an ESM resolution stack.
+ */
+import type { query } from "@anthropic-ai/claude-agent-sdk";
+
+/** The optional package this module resolves. */
+export const CLAUDE_AGENT_SDK_PACKAGE = "@anthropic-ai/claude-agent-sdk";
+
+/**
+ * Version the checkout pins in `optionalDependencies`. A contract test keeps
+ * the two in step so the install command quoted in the diagnostic never drifts
+ * from the version the runtime was built against.
+ */
+export const CLAUDE_AGENT_SDK_VERSION = "0.3.186";
+
+/** Exact command an operator can paste to make the Claude SDK runtime usable. */
+export const CLAUDE_AGENT_SDK_INSTALL_COMMAND = `npm install ${CLAUDE_AGENT_SDK_PACKAGE}@${CLAUDE_AGENT_SDK_VERSION}`;
+
+/** The slice of the SDK surface the worker runtime calls. */
+export interface ClaudeAgentSdkModule {
+	query: typeof query;
+}
+
+/** Thrown when a `claude-sdk` run starts on an install that omitted the optional package. */
+export class ClaudeAgentSdkUnavailableError extends Error {
+	readonly code = "CLAUDE_AGENT_SDK_UNAVAILABLE";
+	readonly packageName = CLAUDE_AGENT_SDK_PACKAGE;
+	readonly installCommand = CLAUDE_AGENT_SDK_INSTALL_COMMAND;
+
+	constructor(cause?: unknown) {
+		super(
+			`The claude-sdk runtime needs the optional package ${CLAUDE_AGENT_SDK_PACKAGE}, which is not installed. ` +
+				`Install it with \`${CLAUDE_AGENT_SDK_INSTALL_COMMAND}\` (or reinstall clio-coder without \`--omit=optional\`), ` +
+				`then select the target again. Every other runtime works without it.`,
+			cause === undefined ? undefined : { cause },
+		);
+		this.name = "ClaudeAgentSdkUnavailableError";
+	}
+}
+
+/** Resolution failures that mean "the package is not on disk" rather than "the package is broken". */
+const MISSING_MODULE_CODES: ReadonlySet<string> = new Set([
+	"ERR_MODULE_NOT_FOUND",
+	"MODULE_NOT_FOUND",
+	"ERR_PACKAGE_PATH_NOT_EXPORTED",
+]);
+
+function isMissingModuleError(error: unknown): boolean {
+	const code = (error as { code?: unknown } | null)?.code;
+	return typeof code === "string" && MISSING_MODULE_CODES.has(code);
+}
+
+export type ClaudeAgentSdkLoader = () => Promise<ClaudeAgentSdkModule>;
+
+// The literal specifier is what keeps the SDK's types available here; the tsup
+// `external` entry keeps esbuild from bundling it and leaves this as a real
+// runtime `import()`.
+const realLoader: ClaudeAgentSdkLoader = async () => await import("@anthropic-ai/claude-agent-sdk");
+
+let loader: ClaudeAgentSdkLoader = realLoader;
+let cached: ClaudeAgentSdkModule | null = null;
+
+/**
+ * Swap the import used by {@link loadClaudeAgentSdk}. The absence of a 224MB
+ * optional package cannot be staged inside a normal test process, so the
+ * contract test intercepts the import here; passing `null` restores the real
+ * one and clears the cache.
+ */
+export function setClaudeAgentSdkLoader(next: ClaudeAgentSdkLoader | null): void {
+	loader = next ?? realLoader;
+	cached = null;
+}
+
+/**
+ * Resolve the SDK, or fail with {@link ClaudeAgentSdkUnavailableError}. A load
+ * error that is not a resolution failure (a broken install, a throwing module
+ * top level) propagates unchanged, so a real fault is never mislabeled as an
+ * absent package.
+ */
+export async function loadClaudeAgentSdk(): Promise<ClaudeAgentSdkModule> {
+	if (cached) return cached;
+	try {
+		cached = await loader();
+		return cached;
+	} catch (error) {
+		if (isMissingModuleError(error)) throw new ClaudeAgentSdkUnavailableError(error);
+		throw error;
+	}
+}

package/src/engine/claude/sdk-runtime.ts

@@ -1,15 +1,18 @@
-import {
-	type CanUseTool,
-	type EffortLevel,
-	type HookCallback,
-	type Options,
-	type PermissionMode,
-	type PermissionResult,
+// Types only. `@anthropic-ai/claude-agent-sdk` is an optional dependency, so
+// nothing here may reach it at module scope; the one value this runtime calls
+// (`query`) comes from the lazy loader in ./sdk-module.js at run time.
+import type {
+	CanUseTool,
+	EffortLevel,
+	HookCallback,
+	Options,
+	PermissionMode,
+	PermissionResult,
 	query,
-	type SDKMessage,
-	type SDKResultMessage,
-	type SDKUserMessage,
-	type ThinkingConfig,
+	SDKMessage,
+	SDKResultMessage,
+	SDKUserMessage,
+	ThinkingConfig,
 } from "@anthropic-ai/claude-agent-sdk";
 
 import { readClioVersion } from "../../core/package-root.js";
@@ -19,6 +22,7 @@ import { isReserveAdmittedTool, resolveDeliveryTools } from "../loop-guard.js";
 import type { AgentEvent, AgentMessage, Usage } from "../types.js";
 import type { WorkerEventEmit, WorkerRunHandle, WorkerRunInput, WorkerRunResult } from "../worker-runtime.js";
 import { createWorkerSafety } from "../worker-tools.js";
+import { loadClaudeAgentSdk } from "./sdk-module.js";
 import { isClaudeCodeSessionId } from "./session-id.js";
 import {
 	type ClaudeToolPermissionDecision,
@@ -607,6 +611,10 @@ export function startClaudeSdkWorkerRun(input: WorkerRunInput, emit: WorkerEvent
 
 		emit({ type: "agent_start" } as AgentEvent);
 		try {
+			// First touch of the optional SDK. An install that omitted it fails
+			// here with a typed diagnostic naming the package and the install
+			// command, and lands in the catch below as an ordinary run failure.
+			const { query } = await loadClaudeAgentSdk();
 			queryHandle = query({ prompt: buildClaudeSdkPrompt(input), options });
 			for await (const sdkMessage of queryHandle) {
 				if (sdkMessage.type === "system" && (sdkMessage as { subtype?: string }).subtype === "init") {