@iowarp/clio-coder 0.3.7 → 0.3.9

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/prompt-templates.ts

@@ -1 +1,18 @@
-export { parseCommandArgs, substituteArgs } from "@earendil-works/pi-agent-core";
+import { parseCommandArgs, substituteArgs as substituteParsedArgs } from "@earendil-works/pi-agent-core";
+
+export { parseCommandArgs };
+
+const RAW_ARGUMENTS_PLACEHOLDER = /\$ARGUMENTS/g;
+
+/**
+ * Substitute prompt arguments while optionally retaining the exact raw text
+ * for `$ARGUMENTS`. Positional, slice, and `$@` placeholders keep Pi's
+ * shell-style parsing semantics.
+ */
+export function substituteArgs(content: string, args: string[], rawArguments?: string): string {
+	if (rawArguments === undefined) return substituteParsedArgs(content, args);
+	return content
+		.split(RAW_ARGUMENTS_PLACEHOLDER)
+		.map((segment) => substituteParsedArgs(segment, args))
+		.join(rawArguments);
+}

package/src/engine/provider-payload.ts

@@ -1,4 +1,4 @@
-import { RESPONSE_SCHEMA_RUNTIME_ID } from "../core/response-schema.js";
+import { RESPONSE_SCHEMA_RUNTIME_ID, type ResponseSchemaDialect } from "../core/response-schema.js";
 import type { ThinkingLevel } from "../domains/providers/index.js";
 import type { EngineModel } from "./types.js";
 
@@ -217,6 +217,34 @@ function patchLlamaCppResponseSchemaPayload(
 	};
 }
 
+/**
+ * Apply a JSON-schema response constraint in the dialect the runtime takes.
+ *
+ * Unlike the worker patcher above, this one is for a seam that treats native
+ * enforcement as an optimization: the caller looks the dialect up first and
+ * simply does not call this when there is none, so an unconstrained request
+ * still goes out and the prompt-level instruction carries it (issue #223).
+ * Returns undefined when the payload is not an object, which leaves it alone.
+ */
+export function patchResponseSchemaPayloadForDialect(
+	payload: unknown,
+	dialect: ResponseSchemaDialect,
+	responseSchema: Record<string, unknown>,
+	schemaName: string,
+): unknown | undefined {
+	if (!isRecord(payload)) return undefined;
+	if (dialect === "llamacpp-json-object") {
+		return { ...payload, response_format: { type: "json_object", schema: responseSchema } };
+	}
+	return {
+		...payload,
+		response_format: {
+			type: "json_schema",
+			json_schema: { name: schemaName, strict: true, schema: responseSchema },
+		},
+	};
+}
+
 export interface WorkerPayloadPatchOptions {
 	runtimeId: string;
 	thinkingLevel?: ThinkingLevel;

package/src/engine/worker-runtime.ts

@@ -23,7 +23,7 @@ import { type ToolName, ToolNames } from "../core/tool-names.js";
 import {
 	type ObservedReadRanges,
 	type ObservedRunEffects,
-	parseResultContract,
+	parseWorkerResultContract,
 	RESULT_CONTRACT_REPAIR_LIMIT,
 	type ResultContract,
 	resultContractRepairMessages,
@@ -362,8 +362,11 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	assertResponseSchemaRuntime(input);
 	// 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.
-	if (input.resultContract !== undefined) parseResultContract(input.resultContract, "WorkerSpec.resultContract");
+	// check lands here, before any model call. The wire parser, not the recipe
+	// one: a dispatch request may override the seated recipe's postcondition
+	// with a kind the coordinator authors, and the recipe parser refusing those
+	// killed every council vote member with a fatal spec error.
+	if (input.resultContract !== undefined) parseWorkerResultContract(input.resultContract, "WorkerSpec.resultContract");
 	if (input.runtime.id === "claude-sdk") {
 		return startClaudeSdkWorkerRun(input, emit);
 	}