@iowarp/clio-coder 0.4.7 → 0.4.8

package/src/engine/prewarm.ts

@@ -0,0 +1,232 @@
+/**
+ * One bounded-output warm through the eventual caller's engine request path.
+ * Copies portable context, applies public Pi transforms and payload hooks,
+ * and consumes the response without running tools or appending conversation.
+ * Admission and lifecycle remain with the caller. A matching serialized
+ * prefix is only a reuse candidate; the backend decides actual cache reuse.
+ */
+
+import type { Agent } from "@earendil-works/pi-agent-core";
+import type { BackendCompletionTimings } from "../core/cache-telemetry.js";
+import { streamSimple } from "./ai.js";
+import { estimateInputTokensFromContext } from "./apis/output-budget.js";
+import type { AgentMessage, AgentTool, EngineModel, Usage } from "./types.js";
+
+/**
+ * The one user message appended so the chat template renders the prefix up to
+ * the user turn. One character: it has to exist for the template to close the
+ * prefix, and everything after the last shared byte is re-evaluated by the real
+ * turn anyway.
+ */
+export const PREWARM_USER_TEXT = ".";
+
+/** Output budget for the round. The tokens the model produces are not the point. */
+export const PREWARM_MAX_TOKENS = 1;
+
+/** Which trigger asked for the pre-warm. Recorded on the ledger entry. */
+export type PrewarmTrigger = "session-start" | "resume" | "compaction";
+
+export interface PrewarmContext {
+	systemPrompt: string;
+	messages: ReadonlyArray<AgentMessage>;
+	tools: ReadonlyArray<AgentTool>;
+}
+
+/**
+ * The roles pi-agent-core's default `convertToLlm` keeps when it turns the
+ * agent's message list into provider messages. The pre-warm applies the same
+ * filter so its message array is the one a turn would send, not the agent's
+ * internal list.
+ */
+const LLM_MESSAGE_ROLES: ReadonlySet<string> = new Set(["user", "assistant", "toolResult"]);
+
+export interface PrewarmRoundInput {
+	model: EngineModel;
+	/** Live agent state the next turn would send. Read-only; the round copies it. */
+	state: {
+		systemPrompt: string;
+		messages: ReadonlyArray<AgentMessage>;
+		tools: ReadonlyArray<AgentTool>;
+		thinkingLevel: string;
+	};
+	apiKey?: string;
+	signal?: AbortSignal;
+	/** Admission bound on the engine's input estimate, after context selection. */
+	maxInputTokens?: number;
+	/** Public Pi preparation hooks of the eventual caller. No tools or agent loop are executed. */
+	agent?: Pick<
+		Agent,
+		| "transformContext"
+		| "convertToLlm"
+		| "streamFunction"
+		| "onPayload"
+		| "onResponse"
+		| "sessionId"
+		| "thinkingBudgets"
+		| "transport"
+		| "maxRetryDelayMs"
+	>;
+	/** Test seam. Production uses the engine dispatcher a turn runs on. */
+	streamFn?: typeof streamSimple;
+}
+
+export interface PrewarmRoundResult {
+	/** True when the operator submitted (or the session moved) before the round settled. */
+	aborted: boolean;
+	/** Provider usage for the round; null when the backend reported none. */
+	usage: Usage | null;
+	/** Backend prefill and prediction timings when the server reported them. */
+	backend: BackendCompletionTimings | null;
+	/** Wall clock the round spent, in the shape a turn's assistant entry uses. */
+	timing: { ttftMs: number | null; apiMs: number };
+	/** Provider error text when the round failed outright. */
+	errorMessage: string | null;
+}
+
+function usageOf(message: unknown): Usage | null {
+	if (message === null || typeof message !== "object") return null;
+	const usage = (message as { usage?: unknown }).usage;
+	if (usage === null || typeof usage !== "object") return null;
+	const record = usage as Usage;
+	// Pi initializes missing usage to zero, including on aborted/error calls.
+	// A warm with no observed tokens cannot be called a measured free request.
+	return [record.input, record.output, record.cacheRead, record.cacheWrite, record.cost?.total].some(
+		(value) => typeof value === "number" && Number.isFinite(value) && value > 0,
+	)
+		? record
+		: null;
+}
+
+function backendOf(message: unknown): BackendCompletionTimings | null {
+	if (message === null || typeof message !== "object") return null;
+	const backend = (message as { backendTimings?: unknown }).backendTimings;
+	return backend !== null && typeof backend === "object" ? (backend as BackendCompletionTimings) : null;
+}
+
+/**
+ * Prompt tokens the backend actually processed for one pre-warm. The server's
+ * own prompt count is authoritative when it reported one; otherwise the
+ * provider usage prompt side, cached tokens folded in, is the honest figure.
+ * Null when neither exists, which is different from a measured zero.
+ */
+export function prewarmPromptTokens(result: Pick<PrewarmRoundResult, "usage" | "backend">): number | null {
+	if (result.backend) return result.backend.promptTokens;
+	const usage = result.usage;
+	if (!usage) return null;
+	const total = (usage.input || 0) + (usage.cacheRead || 0) + (usage.cacheWrite || 0);
+	return total > 0 ? total : null;
+}
+
+/**
+ * Send the prefix and wait for the backend to acknowledge it. Resolves rather
+ * than rejects on a provider failure: a pre-warm is an optimization, and a
+ * backend that refuses it must not be able to break the session it was warming.
+ */
+export async function runPrewarmRound(input: PrewarmRoundInput): Promise<PrewarmRoundResult> {
+	// pi-agent-core maps `thinkingLevel: "off"` onto an absent `reasoning`; the
+	// pre-warm has to make the same mapping or the thinking composition resolves
+	// against a different level and the rendered template moves.
+	const options: Record<string, unknown> = { maxTokens: PREWARM_MAX_TOKENS };
+	// Narrow residency authority without changing prompt rendering. A warm may
+	// not inherit the foreground turn's implicit load/unload authorization.
+	const metadata = (input.model as EngineModel & { clioCoder?: Record<string, unknown> }).clioCoder;
+	const model = metadata ? { ...input.model, clioCoder: { ...metadata, lifecycle: "user-managed" } } : input.model;
+	if (metadata?.runtimeId === "llamacpp") {
+		// A worker that disappeared after admission must not be JIT-loaded by
+		// the pinned llama router. This query is independent of prompt bytes.
+		options.fetch = (request: string | URL | Request, init?: RequestInit) => {
+			const url = new URL(request instanceof Request ? request.url : request);
+			url.searchParams.set("autoload", "false");
+			return fetch(request instanceof Request ? new Request(url, request) : url, init);
+		};
+	}
+	if (input.state.thinkingLevel !== "off") options.reasoning = input.state.thinkingLevel;
+	if (input.apiKey !== undefined) options.apiKey = input.apiKey;
+	if (input.signal !== undefined) options.signal = input.signal;
+	if (input.agent) {
+		for (const key of [
+			"onPayload",
+			"onResponse",
+			"sessionId",
+			"thinkingBudgets",
+			"transport",
+			"maxRetryDelayMs",
+		] as const) {
+			if (input.agent[key] !== undefined) options[key] = input.agent[key];
+		}
+	}
+
+	const send = input.streamFn ?? input.agent?.streamFunction ?? streamSimple;
+	const startedAt = performance.now();
+	let firstDeltaAt: number | null = null;
+	const elapsed = (): number => Math.round(Math.max(0, performance.now() - startedAt));
+	const ttft = (): number | null => (firstDeltaAt === null ? null : Math.round(Math.max(0, firstDeltaAt - startedAt)));
+
+	try {
+		input.signal?.throwIfAborted();
+		let messages: AgentMessage[] = [
+			...structuredClone([...input.state.messages]),
+			{ role: "user", content: [{ type: "text", text: PREWARM_USER_TEXT }], timestamp: Date.now() },
+		];
+		if (input.agent?.transformContext) messages = await input.agent.transformContext(messages, input.signal);
+		const converted = input.agent
+			? await input.agent.convertToLlm(messages)
+			: messages.filter((message) => LLM_MESSAGE_ROLES.has(message.role));
+		input.signal?.throwIfAborted();
+		const context = {
+			systemPrompt: input.state.systemPrompt,
+			messages: converted,
+			tools: [...input.state.tools],
+		} as Parameters<typeof streamSimple>[1];
+		if (input.maxInputTokens !== undefined && estimateInputTokensFromContext(context) > input.maxInputTokens) {
+			throw new Error("pre-warm input estimate exceeds its token budget");
+		}
+		const events = await send(
+			model,
+			context as unknown as Parameters<typeof streamSimple>[1],
+			options as unknown as Parameters<typeof streamSimple>[2],
+		);
+		for await (const event of events) {
+			const hasDelta =
+				event.type === "toolcall_start" ||
+				((event.type === "text_delta" || event.type === "thinking_delta" || event.type === "toolcall_delta") &&
+					event.delta.length > 0);
+			if (firstDeltaAt === null && hasDelta) firstDeltaAt = performance.now();
+			if (event.type === "done") {
+				return {
+					aborted: false,
+					usage: usageOf(event.message),
+					backend: backendOf(event.message),
+					timing: { ttftMs: ttft(), apiMs: elapsed() },
+					errorMessage: null,
+				};
+			}
+			if (event.type === "error") {
+				const failed = event.error as { stopReason?: unknown; errorMessage?: unknown };
+				const aborted = event.reason === "aborted" || failed.stopReason === "aborted" || input.signal?.aborted === true;
+				return {
+					aborted,
+					usage: usageOf(event.error),
+					backend: backendOf(event.error),
+					timing: { ttftMs: ttft(), apiMs: elapsed() },
+					errorMessage: aborted ? null : typeof failed.errorMessage === "string" ? failed.errorMessage : "pre-warm failed",
+				};
+			}
+		}
+	} catch (error) {
+		return {
+			aborted: input.signal?.aborted === true,
+			usage: null,
+			backend: null,
+			timing: { ttftMs: ttft(), apiMs: elapsed() },
+			errorMessage: input.signal?.aborted === true ? null : error instanceof Error ? error.message : String(error),
+		};
+	}
+	return {
+		aborted: input.signal?.aborted === true,
+		usage: null,
+		backend: null,
+		timing: { ttftMs: ttft(), apiMs: elapsed() },
+		errorMessage: null,
+	};
+}

package/src/engine/provider-diagnostics.ts

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { closeSync, constants, fstatSync, openSync, writeFileSync } from "node:fs";
 import { isAbsolute } from "node:path";
 import type { Api, AssistantMessageEventStream, Model, StreamOptions } from "@earendil-works/pi-ai";
+import type { TargetCacheSettings } from "../domains/providers/types/target-descriptor.js";
 import { findEngineEnvKeys } from "./env-api-keys.js";
 
 /** Process-owned opt-in reaches every native engine call, including prewarm and workers. */
@@ -11,7 +12,11 @@ export function instrumentProviderCall<T extends StreamOptions>(
 	invoke: (options: T | undefined) => AssistantMessageEventStream,
 ): AssistantMessageEventStream {
 	let effective = options;
-	if (model.api === "anthropic-messages" && options?.cacheRetention === undefined) {
+	const configured = (model as Model<Api> & { clioCoder?: { cache?: TargetCacheSettings } }).clioCoder?.cache?.retention;
+	if (options?.cacheRetention === undefined && configured !== undefined) {
+		effective = { ...options, cacheRetention: configured } as T;
+	}
+	if (model.api === "anthropic-messages" && effective?.cacheRetention === undefined) {
 		const retention = process.env.CLIO_CODER_ANTHROPIC_CACHE_RETENTION;
 		if (retention !== undefined && retention !== "") {
 			if (retention !== "none" && retention !== "short" && retention !== "long") {

package/src/entry/orchestrator.ts

@@ -36,7 +36,7 @@ import {
 import { getSharedBus } from "../core/shared-bus.js";
 import { isSkillActivation } from "../core/skill-activation.js";
 import { StartupTimer } from "../core/startup-timer.js";
-import { getTerminationCoordinator } from "../core/termination.js";
+import { getTerminationCoordinator, resolveShutdownHookBudgetMs } from "../core/termination.js";
 import { captureProjectSurface, projectSurfaceTrustNotice } from "../core/workspace-trust.js";
 import { clioDataDir, clioStateDir } from "../core/xdg.js";
 import { renderAgentCatalogSectionsFromSpecs } from "../domains/agents/catalog.js";
@@ -1203,8 +1203,10 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 			await dispatch.drain();
 		});
 	}
-	termination.onPersist(async () => {
-		await result.stop();
+	// The loader caps each domain separately. The outer hook must allow the
+	// whole sequence to finish, including cleanup after a timed-out domain.
+	termination.onPersist(() => result.stop(), {
+		timeoutMs: Math.min(2 ** 31 - 1, (result.loaded.length + 1) * resolveShutdownHookBudgetMs()),
 	});
 
 	bus.emit(BusChannels.SessionStart, { at: Date.now() });
@@ -1373,12 +1375,10 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	// this boot projection below.
 	configureRunEventJournal(resolvedSettings.fleet.history.journal);
 
-	// Guard registrations on the middleware contract, in order: loop guard,
-	// protected artifacts (last among guards so it absorbs protect_path effects
-	// from everything before it), dispatch dedup. Workers register their own
-	// loop guard and protected-artifacts instances inside their subprocess in
-	// worker-runtime.ts; the orchestrator instances carry the bus and the
-	// session persistence sink.
+	// Register the loop and dispatch guards first. The protected-artifact guard
+	// is constructed here but registered after user hooks below, so it can
+	// absorb their protect_path effects. Workers register their own guards in
+	// worker-runtime.ts; these instances carry the bus and session persistence.
 	middleware.registerHook(
 		createLoopGuardRegistration({
 			safety,
@@ -1427,7 +1427,6 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		}
 		return protectedArtifactsGuard.state();
 	};
-	middleware.registerHook(protectedArtifactsGuard);
 	middleware.registerHook(createDispatchDedupRegistration());
 	// Observers run after the guards; they emit no effects and their sinks are
 	// best-effort (session ledger, codewiki refresh).
@@ -1525,9 +1524,9 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	}
 	// User-defined hooks: extensions and the project (.clio-coder/hooks.yaml,
 	// .clio-coder/hooks.local.yaml) declare a conservative, receipted hook set on the
-	// same effect machinery. They register after the guards, so safety stays
-	// authoritative: a hook may add effects (including request block_tool) but
-	// cannot grant a permission safety would deny. Loading is best-effort.
+	// same effect machinery. A hook may add effects (including request block_tool)
+	// but cannot grant a permission safety would deny. The protected-artifact
+	// guard follows them to consume protect_path before tool execution.
 	// The coordinator is the only writer of the "user-hooks" owner and the only
 	// caller of the extensions reload; it publishes the extension generation
 	// and the hook registrations with two adjacent assignments on one stack
@@ -1535,7 +1534,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	// published here too (the extensions bundle publishes nothing at start),
 	// so no consumer ever sees extension resources paired with hooks from a
 	// different generation. The owner slot is anchored here, so user hooks
-	// keep evaluating after the guards and before the assessors below.
+	// keep evaluating before the protection consumer and assessors below.
 	const hookReceiptLog = createHookReceiptLog({ persistPath: join(clioStateDir(), "hook-receipts.json") });
 	let bootHookNotices = true;
 	const reloadPlugins = () =>
@@ -1556,6 +1555,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 		},
 	});
 	extensionReload.applyBoot();
+	middleware.registerHook(protectedArtifactsGuard);
 	bootHookNotices = false;
 	termination.onDrain(() => hookReceiptLog.flush());
 	// Autonomy is hot-reloaded for interactive and headless admissions. ACP
@@ -1836,8 +1836,12 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	// The config bundle publishes saved values on reload; session-scoped
 	// overrides must win, so re-derive every process-local projection from the
 	// effective session view after it.
-	const unsubscribeSettingsProjectionSync = bus.on(BusChannels.ConfigHotReload, () => bumpSessionState());
-	termination.onDrain(() => unsubscribeSettingsProjectionSync());
+	const unsubscribeSettingsProjectionSync = [BusChannels.ConfigHotReload, BusChannels.ConfigNextTurn].map((channel) =>
+		bus.on(channel, () => bumpSessionState()),
+	);
+	termination.onDrain(() => {
+		for (const unsubscribe of unsubscribeSettingsProjectionSync) unsubscribe();
+	});
 	const getTaskMemorySeedOffer = (): { source: string; count: number } | null => {
 		return taskMemoryHandoffSeedOffer(process.cwd(), getCurrentSettings().context.memory.enabled);
 	};

package/src/interactive/chat-loop-messages.ts

@@ -362,6 +362,7 @@ export interface RunUsageSummary {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoning: number;
 	apiCalls: number;
 	hadReasoning: boolean;
@@ -407,6 +408,7 @@ export function sumRunUsage(messages: ReadonlyArray<AgentMessage>): RunUsageSumm
 						output?: unknown;
 						cacheRead?: unknown;
 						cacheWrite?: unknown;
+						cacheWrite1h?: unknown;
 						totalTokens?: unknown;
 						cost?: { total?: unknown };
 					};
@@ -432,6 +434,7 @@ export function sumRunUsage(messages: ReadonlyArray<AgentMessage>): RunUsageSumm
 		summary.output += output;
 		summary.cacheRead += cacheRead;
 		summary.cacheWrite += cacheWrite;
+		if (typeof usage.cacheWrite1h === "number") summary.cacheWrite1h = (summary.cacheWrite1h ?? 0) + usage.cacheWrite1h;
 		const reasoning = extractReasoningTokens(usage);
 		if (reasoning !== null) {
 			summary.reasoning += reasoning;

package/src/interactive/chat-loop.ts

@@ -862,13 +862,6 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		deps.bus?.on(BusChannels.ConfigHotReload, () => {
 			context.invalidateSessionPromptCache();
 		}) ?? null;
-	// A committed extension generation with new content can change the skill
-	// and prompt inputs the session prompt compiles from; same invalidation.
-	const unsubscribeExtensionsReload =
-		deps.bus?.on(BusChannels.ExtensionsReloaded, (payload) => {
-			if (payload.changed) context.invalidateSessionPromptCache();
-		}) ?? null;
-
 	const unsubscribePluginsReload =
 		deps.bus?.on(BusChannels.PluginsReloaded, () => {
 			context.invalidateSessionPromptCache();
@@ -981,6 +974,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 				output: usage.output,
 				cacheRead: usage.cacheRead,
 				cacheWrite: usage.cacheWrite,
+				...(usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: usage.cacheWrite1h }),
 				reasoningTokens: usage.reasoning,
 				totalTokens: usage.totalTokens,
 				apiCalls: 1,
@@ -1004,6 +998,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 				output: usage.output,
 				cacheRead: usage.cacheRead,
 				cacheWrite: usage.cacheWrite,
+				...(usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: usage.cacheWrite1h }),
 				reasoning: usage.reasoning,
 				totalTokens: usage.totalTokens,
 				costUsd: usage.costUsd,
@@ -1572,7 +1567,6 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 
 		dispose(): void {
 			unsubscribeConfigReload?.();
-			unsubscribeExtensionsReload?.();
 			unsubscribePluginsReload?.();
 			unsubscribeSynthesisLock?.();
 			unsubscribePrewarmCompaction();

package/src/interactive/prewarm.ts

@@ -1,197 +1,11 @@
-/**
- * The session pre-warm round: the request the next turn would send, minus the
- * operator's text, issued as soon as the prefix is known.
- *
- * On a local server prefill is the cost. A fresh session's first turn prefills
- * the whole compiled prompt plus the tool schemas before the model emits a
- * token, and a resumed session's first turn prefills the entire replayed
- * history. Both are paid after the operator presses Enter, and both are fully
- * determined before they type anything. llama.cpp picks the slot with the
- * longest common prefix and re-evaluates only the suffix, so sending the prefix
- * early leaves the processed KV in the slot for the real turn to land on.
- *
- * The payload is not hand-assembled. It goes through `streamSimple`, the same
- * dispatcher `createEngineAgent` hands pi-agent-core as its `streamFn`, with the
- * same system prompt, the same tool schemas, the same replayed messages, and the
- * same thinking level, so `withSamplingOverrides`, the thinking composition, and
- * `cache_prompt` resolve exactly as they do for a turn. Any byte that differs
- * ahead of the user turn would defeat the purpose.
- */
-
-import type { BackendCompletionTimings } from "../core/cache-telemetry.js";
-import { streamSimple } from "../engine/ai.js";
-import type { AgentMessage, AgentTool, EngineModel, Usage } from "../engine/types.js";
-
-/**
- * The one user message appended so the chat template renders the prefix up to
- * the user turn. One character: it has to exist for the template to close the
- * prefix, and everything after the last shared byte is re-evaluated by the real
- * turn anyway.
- */
-export const PREWARM_USER_TEXT = ".";
-
-/** Output budget for the round. The tokens the model produces are not the point. */
-export const PREWARM_MAX_TOKENS = 1;
-
-/** Which trigger asked for the pre-warm. Recorded on the ledger entry. */
-export type PrewarmTrigger = "session-start" | "resume" | "compaction";
-
-export interface PrewarmContext {
-	systemPrompt: string;
-	messages: ReadonlyArray<AgentMessage>;
-	tools: ReadonlyArray<AgentTool>;
-}
-
-/**
- * The roles pi-agent-core's default `convertToLlm` keeps when it turns the
- * agent's message list into provider messages. The pre-warm applies the same
- * filter so its message array is the one a turn would send, not the agent's
- * internal list.
- */
-const LLM_MESSAGE_ROLES: ReadonlySet<string> = new Set(["user", "assistant", "toolResult"]);
-
-/**
- * The prefix of the next turn's request: system prompt, tool schemas, and the
- * replayed conversation, with no user turn yet.
- */
-function prewarmPrefix(state: {
-	systemPrompt: string;
-	messages: ReadonlyArray<AgentMessage>;
-	tools: ReadonlyArray<AgentTool>;
-}): PrewarmContext {
-	return {
-		systemPrompt: state.systemPrompt,
-		messages: state.messages.filter((message) => LLM_MESSAGE_ROLES.has((message as { role?: string }).role ?? "")),
-		tools: [...state.tools],
-	};
-}
-
-export interface PrewarmRoundInput {
-	model: EngineModel;
-	/** Live agent state the next turn would send. Read-only; the round copies it. */
-	state: {
-		systemPrompt: string;
-		messages: ReadonlyArray<AgentMessage>;
-		tools: ReadonlyArray<AgentTool>;
-		thinkingLevel: string;
-	};
-	apiKey?: string;
-	signal?: AbortSignal;
-	/** Test seam. Production uses the engine dispatcher a turn runs on. */
-	streamFn?: typeof streamSimple;
-}
-
-export interface PrewarmRoundResult {
-	/** True when the operator submitted (or the session moved) before the round settled. */
-	aborted: boolean;
-	/** Provider usage for the round; null when the backend reported none. */
-	usage: Usage | null;
-	/** Backend prefill and prediction timings when the server reported them. */
-	backend: BackendCompletionTimings | null;
-	/** Wall clock the round spent, in the shape a turn's assistant entry uses. */
-	timing: { ttftMs: number | null; apiMs: number };
-	/** Provider error text when the round failed outright. */
-	errorMessage: string | null;
-}
-
-function usageOf(message: unknown): Usage | null {
-	if (message === null || typeof message !== "object") return null;
-	const usage = (message as { usage?: unknown }).usage;
-	return usage !== null && typeof usage === "object" ? (usage as Usage) : null;
-}
-
-function backendOf(message: unknown): BackendCompletionTimings | null {
-	if (message === null || typeof message !== "object") return null;
-	const backend = (message as { backendTimings?: unknown }).backendTimings;
-	return backend !== null && typeof backend === "object" ? (backend as BackendCompletionTimings) : null;
-}
-
-/**
- * Prompt tokens the backend actually processed for one pre-warm. The server's
- * own prompt count is authoritative when it reported one; otherwise the
- * provider usage prompt side, cached tokens folded in, is the honest figure.
- * Null when neither exists, which is different from a measured zero.
- */
-export function prewarmPromptTokens(result: Pick<PrewarmRoundResult, "usage" | "backend">): number | null {
-	if (result.backend) return result.backend.promptTokens;
-	const usage = result.usage;
-	if (!usage) return null;
-	const total = (usage.input || 0) + (usage.cacheRead || 0) + (usage.cacheWrite || 0);
-	return total > 0 ? total : null;
-}
-
-/**
- * Send the prefix and wait for the backend to acknowledge it. Resolves rather
- * than rejects on a provider failure: a pre-warm is an optimization, and a
- * backend that refuses it must not be able to break the session it was warming.
- */
-export async function runPrewarmRound(input: PrewarmRoundInput): Promise<PrewarmRoundResult> {
-	const prefix = prewarmPrefix(input.state);
-	const context = {
-		systemPrompt: prefix.systemPrompt,
-		messages: [
-			...prefix.messages,
-			{ role: "user", content: [{ type: "text", text: PREWARM_USER_TEXT }], timestamp: Date.now() },
-		],
-		tools: prefix.tools,
-	};
-	// pi-agent-core maps `thinkingLevel: "off"` onto an absent `reasoning`; the
-	// pre-warm has to make the same mapping or the thinking composition resolves
-	// against a different level and the rendered template moves.
-	const options: Record<string, unknown> = { maxTokens: PREWARM_MAX_TOKENS };
-	if (input.state.thinkingLevel !== "off") options.reasoning = input.state.thinkingLevel;
-	if (input.apiKey !== undefined) options.apiKey = input.apiKey;
-	if (input.signal !== undefined) options.signal = input.signal;
-
-	const send = input.streamFn ?? streamSimple;
-	const startedAt = performance.now();
-	let firstDeltaAt: number | null = null;
-	const elapsed = (): number => Math.round(Math.max(0, performance.now() - startedAt));
-	const ttft = (): number | null => (firstDeltaAt === null ? null : Math.round(Math.max(0, firstDeltaAt - startedAt)));
-
-	try {
-		const events = send(
-			input.model,
-			context as unknown as Parameters<typeof streamSimple>[1],
-			options as unknown as Parameters<typeof streamSimple>[2],
-		);
-		for await (const event of events) {
-			if (firstDeltaAt === null && event.type !== "start") firstDeltaAt = performance.now();
-			if (event.type === "done") {
-				return {
-					aborted: false,
-					usage: usageOf(event.message),
-					backend: backendOf(event.message),
-					timing: { ttftMs: ttft(), apiMs: elapsed() },
-					errorMessage: null,
-				};
-			}
-			if (event.type === "error") {
-				const failed = event.error as { stopReason?: unknown; errorMessage?: unknown };
-				const aborted = event.reason === "aborted" || failed.stopReason === "aborted" || input.signal?.aborted === true;
-				return {
-					aborted,
-					usage: usageOf(event.error),
-					backend: backendOf(event.error),
-					timing: { ttftMs: ttft(), apiMs: elapsed() },
-					errorMessage: aborted ? null : typeof failed.errorMessage === "string" ? failed.errorMessage : "pre-warm failed",
-				};
-			}
-		}
-	} catch (error) {
-		return {
-			aborted: input.signal?.aborted === true,
-			usage: null,
-			backend: null,
-			timing: { ttftMs: ttft(), apiMs: elapsed() },
-			errorMessage: input.signal?.aborted === true ? null : error instanceof Error ? error.message : String(error),
-		};
-	}
-	return {
-		aborted: input.signal?.aborted === true,
-		usage: null,
-		backend: null,
-		timing: { ttftMs: ttft(), apiMs: elapsed() },
-		errorMessage: null,
-	};
-}
+/** Compatibility entry point; engine preparation is shared with headless callers. */
+export {
+	PREWARM_MAX_TOKENS,
+	PREWARM_USER_TEXT,
+	type PrewarmContext,
+	type PrewarmRoundInput,
+	type PrewarmRoundResult,
+	type PrewarmTrigger,
+	prewarmPromptTokens,
+	runPrewarmRound,
+} from "../engine/prewarm.js";

package/src/interactive/session-usage-reseed.ts

@@ -35,6 +35,7 @@ export interface SessionUsageSink {
 			output: number;
 			cacheRead: number;
 			cacheWrite: number;
+			cacheWrite1h?: number;
 			reasoningTokens: number;
 			totalTokens: number;
 			apiCalls?: number;
@@ -86,6 +87,7 @@ export function reseedSessionUsageFromLedger(
 				output: call.output,
 				cacheRead: call.cacheRead,
 				cacheWrite: call.cacheWrite,
+				...(call.cacheWrite1h === undefined ? {} : { cacheWrite1h: call.cacheWrite1h }),
 				reasoningTokens: call.reasoningTokens,
 				totalTokens: call.totalTokens,
 				apiCalls: call.apiCalls ?? 1,

package/src/interactive/side-question.ts

@@ -41,6 +41,7 @@ export interface SideQuestionUsage {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoning: number;
 	totalTokens: number;
 	costUsd: number;
@@ -117,6 +118,7 @@ export function sideQuestionUsage(raw: unknown): SideQuestionUsage | null {
 		output,
 		cacheRead,
 		cacheWrite,
+		...(usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: positive(usage.cacheWrite1h) }),
 		reasoning: positive(usage.reasoning),
 		totalTokens,
 		costUsd: positive(usage.cost?.total),

package/src/interactive/turn-context.ts

@@ -705,6 +705,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				output: usage.output,
 				cacheRead: usage.cacheRead,
 				cacheWrite: usage.cacheWrite,
+				...(usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: usage.cacheWrite1h }),
 				reasoningTokens: usage.reasoning,
 				totalTokens: usage.totalTokens,
 				apiCalls: Math.max(1, Math.round(usage.apiCalls)),

package/src/interactive/turn-persistence.ts

@@ -213,6 +213,9 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 			outputTokens: total.outputTokens + summary.output,
 			cacheReadTokens: total.cacheReadTokens + summary.cacheRead,
 			cacheWriteTokens: total.cacheWriteTokens + summary.cacheWrite,
+			...(total.cacheWrite1hTokens === undefined && summary.cacheWrite1h === undefined
+				? {}
+				: { cacheWrite1hTokens: (total.cacheWrite1hTokens ?? 0) + (summary.cacheWrite1h ?? 0) }),
 			reasoningTokens: total.reasoningTokens + summary.reasoning,
 			totalTokens: total.totalTokens + summary.tokens,
 			costUsd: (total.costUsd ?? 0) + summary.costUsd,