@iowarp/clio-coder 0.4.6 → 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/engine/tui.ts

@@ -80,11 +80,13 @@ export {
 	getKeybindings,
 	Input,
 	isKeyRelease,
+	isKeyRepeat,
 	KeybindingsManager,
 	Markdown,
 	Marked,
 	matchesKey,
 	ProcessTerminal,
+	parseKey,
 	ScrollView,
 	setKeybindings,
 	stripTerminalSequences,
@@ -97,6 +99,7 @@ export {
 	visibleWidth,
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
+export { decodePrintableKey } from "@earendil-works/pi-tui/dist/keys.js";
 export {
 	InstrumentedTuiAltScreen,
 	InstrumentedTuiMainScreen,

package/src/engine/worker-runtime.ts

@@ -1,3 +1,9 @@
+import type { WorkerContextSeed } from "../domains/context/worker/contract.js";
+import { createWorkerContextGuard, WorkerContextExhaustedError } from "../domains/context/worker/pressure.js";
+import { createWorkerObservationStore } from "../domains/context/worker/recall.js";
+import { seededWorkerMessages } from "../worker/context-seed.js";
+import { engineStreamSimple } from "./api-registry.js";
+import { estimateInputTokensFromContext, resolveReservedOutputTokens } from "./apis/output-budget.js";
 /**
  * Worker-subprocess engine boundary.
  *
@@ -10,7 +16,6 @@
  */
 
 import path from "node:path";
-import { validateSettingsFile } from "../core/config.js";
 import {
 	configureGuardrails,
 	guardrailValuesFromSettings,
@@ -18,6 +23,7 @@ import {
 	isWorkerToolCallCapSynthesisReason,
 } from "../core/guardrails.js";
 import { runtimeSpeaksResponseSchemaDialect } from "../core/response-schema.js";
+import { readLayeredSettings } from "../core/settings-layers.js";
 import { agentSkillToolPolicy } from "../core/skill-activation.js";
 import { type ToolName, ToolNames } from "../core/tool-names.js";
 import {
@@ -89,6 +95,7 @@ import { createWorkerSafety, createWorkerToolRegistry } from "./worker-tools.js"
 export interface WorkerRunInput {
 	sessionId?: string;
 	systemPrompt: string;
+	contextSeed?: WorkerContextSeed;
 	dynamicPromptMessages?: ReadonlyArray<WorkerPromptMessage>;
 	agentId: string;
 	task: string;
@@ -360,6 +367,8 @@ function resolveWorkerRuntimeBudget(input: Pick<WorkerRunInput, "budget">): Work
  */
 export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): WorkerRunHandle {
 	assertResponseSchemaRuntime(input);
+	if (input.contextSeed && input.runtime.kind !== "http")
+		throw new Error("worker context: history seeds require a native Pi runtime");
 	// The wire carries the contract as data; the one strict parser owns its
 	// shape. The worker subprocess may not import it (it stays slim), so the
 	// check lands here, before any model call. The wire parser, not the recipe
@@ -382,11 +391,11 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	// so it must register them here before any agent.prompt() touches a local
 	// runtime (lmstudio, ollama-native).
 	registerClioApiProviders();
-	// The worker is a fresh process; mirror the orchestrator's global output
-	// budget so dispatched runs honor settings.defaults.maxTokens too. Use the
-	// non-throwing read: a worker must not abort over a settings issue the parent
-	// already surfaced.
-	const workerSettings = validateSettingsFile().settings;
+	// The worker is a fresh process. Resolve its workspace's trusted settings
+	// layers so project output limits and guardrails survive dispatch. Keep the
+	// best-effort read: the parent already surfaced settings diagnostics, and
+	// untrusted or changed project settings must still fall back to lower layers.
+	const workerSettings = readLayeredSettings(input.cwd ?? process.cwd()).settings;
 	setGlobalDefaultMaxOutputTokens(workerSettings.chat.maxOutputTokens);
 	// Same mirroring for guardrail policy: the fresh process needs its settings
 	// projection installed before any registry or tool construction reads it.
@@ -484,6 +493,7 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 				}
 			: {}),
 	});
+	const observations = createWorkerObservationStore();
 	const registry = createWorkerToolRegistry(
 		input.middlewareSnapshot,
 		safety,
@@ -512,6 +522,7 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 		input.autonomy,
 		(effects) => middlewareToolChoice.apply(effects),
 		input.agentLedger,
+		observations.recall,
 	);
 	const contractCwd = input.cwd ?? process.cwd();
 	let resultContractRepairsQueued = 0;
@@ -621,13 +632,46 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 		input.runtimeResolution?.effectiveThinkingLevel ?? input.thinkingLevel,
 	);
 
+	const inheritedMessages = seededWorkerMessages(input.contextSeed);
+	const inheritedCount = inheritedMessages.length;
+	const contextGuard = createWorkerContextGuard(observations.archive);
 	const options: EngineAgentOptions = {
+		streamFn: (currentModel, currentContext, streamOptions) => {
+			const window = input.runtimeResolution?.capabilities.contextWindow ?? currentModel.contextWindow;
+			let messages: AgentMessage[];
+			try {
+				messages = contextGuard({
+					messages: currentContext.messages,
+					systemPrompt: currentContext.systemPrompt ?? "",
+					tools: currentContext.tools ?? [],
+					contextWindow: window,
+					threshold: workerSettings.context.compaction.threshold,
+					autoEvict: workerSettings.context.compaction.auto && workerSettings.context.workingSet.enabled,
+					outputReserve: resolveReservedOutputTokens(currentModel.maxTokens, {
+						api: currentModel.api,
+						contextWindow: window,
+						inputTokens: estimateInputTokensFromContext(currentContext),
+					}),
+				});
+			} catch (error) {
+				if (error instanceof WorkerContextExhaustedError) {
+					workerBoundFailure = error.message;
+					emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "worker_context_exhausted" } });
+				}
+				throw error;
+			}
+			return engineStreamSimple(
+				currentModel,
+				{ ...currentContext, messages: messages as typeof currentContext.messages },
+				streamOptions,
+			);
+		},
 		initialState: {
 			systemPrompt: input.systemPrompt,
 			model,
 			thinkingLevel: effectiveThinkingLevel,
 			tools,
-			messages: [],
+			messages: inheritedMessages,
 		},
 		onPayload: async (payload, currentModel) => {
 			const middlewareChoice = middlewareToolChoice.current();
@@ -1003,12 +1047,12 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 			await agent.waitForIdle();
 			unsubscribe();
 			if (workerBoundFailure !== null) {
-				return { messages: agent.state.messages, exitCode: 1 };
+				return { messages: agent.state.messages.slice(inheritedCount), exitCode: 1 };
 			}
 			if (permissionFailure) {
-				return { messages: agent.state.messages, exitCode: WORKER_EXIT_PERMISSION_REQUIRED };
+				return { messages: agent.state.messages.slice(inheritedCount), exitCode: WORKER_EXIT_PERMISSION_REQUIRED };
 			}
-			const messages = agent.state.messages;
+			const messages = agent.state.messages.slice(inheritedCount);
 			const errorMessage = getTerminalAgentError(messages);
 			if (errorMessage !== null) {
 				if (errorMessage.length > 0) {
@@ -1020,15 +1064,15 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 		} catch (err) {
 			unsubscribe();
 			if (workerBoundFailure !== null) {
-				return { messages: agent.state.messages, exitCode: 1 };
+				return { messages: agent.state.messages.slice(inheritedCount), exitCode: 1 };
 			}
 			if (permissionFailure) {
-				return { messages: agent.state.messages, exitCode: WORKER_EXIT_PERMISSION_REQUIRED };
+				return { messages: agent.state.messages.slice(inheritedCount), exitCode: WORKER_EXIT_PERMISSION_REQUIRED };
 			}
 			const msg = err instanceof Error ? err.message : String(err);
-			emit({ type: "agent_end", messages: agent.state.messages });
+			emit({ type: "agent_end", messages: agent.state.messages.slice(inheritedCount) });
 			process.stderr.write(`[worker] agent error: ${msg}\n`);
-			return { messages: agent.state.messages, exitCode: 1 };
+			return { messages: agent.state.messages.slice(inheritedCount), exitCode: 1 };
 		} finally {
 			clearActiveEscalation();
 			unsubscribePermission();

package/src/engine/worker-tools.ts

@@ -1,3 +1,4 @@
+import type { WorkerRecall } from "../domains/context/worker/recall.js";
 /**
  * Worker-subprocess tool construction.
  *
@@ -29,6 +30,7 @@ import {
 import { CONFIRMED_SCOPE, isSubset, READONLY_SCOPE, WORKSPACE_SCOPE } from "../domains/safety/scope.js";
 import { effectiveToolNames } from "../tools/agent-tools.js";
 import { assertRegisteredBuiltinTools, registerCoreTools } from "../tools/core-bootstrap.js";
+import { registerHarnessExtensionTools } from "../tools/harness-extensions.js";
 import type { ToolProfileName } from "../tools/profiles.js";
 import { createRegistry, type RegistryDeps, type ToolRegistry } from "../tools/registry.js";
 import { type AgentLedgerPort, toolSignatureOf } from "../worker/protocol.js";
@@ -139,6 +141,7 @@ export function createWorkerToolRegistry(
 	autonomy?: AutonomyLevel,
 	onMiddlewareEffects?: RegistryDeps["onMiddlewareEffects"],
 	agentLedger?: AgentLedgerPort,
+	workerRecall?: WorkerRecall,
 ): ToolRegistry {
 	// A worker always gets a middleware contract, even without a snapshot from
 	// the orchestrator, because the loop guard rides on it as a before_tool
@@ -163,6 +166,7 @@ export function createWorkerToolRegistry(
 	// is what keeps that true now that the session registry omits the tool.
 	const registration = registerCoreTools(registry, {
 		includeLedgerTools: true,
+		...(workerRecall ? { workerRecall } : {}),
 		...(agentLedger ? { agentLedger } : {}),
 		// A worker cannot install a skill or reach the operator who could, so
 		// its skill listing carries installed (or bound) skills only; the
@@ -177,6 +181,7 @@ export function createWorkerToolRegistry(
 		}),
 	});
 	assertRegisteredBuiltinTools(registry, registration, false);
+	registerHarnessExtensionTools(registry);
 	return registry;
 }