@iowarp/clio-coder 0.4.7 → 0.4.9

package/src/domains/session/session-artifacts.ts

@@ -1,4 +1,5 @@
 import { isAbsolute, relative, resolve } from "node:path";
+import { effectiveToolCall } from "../../tools/surface.js";
 
 export type SessionArtifactTool = "artifact" | "write" | "edit";
 export type SessionArtifactKind = "plan" | "review" | "report";
@@ -61,7 +62,13 @@ export function foldSessionArtifacts(
 		if (!isRecord(raw) || raw.kind !== "message" || raw.role !== "tool_result") continue;
 		if (typeof raw.turnId !== "string" || typeof raw.timestamp !== "string") continue;
 		const payload = raw.payload;
-		if (!isRecord(payload) || !isSessionArtifactTool(payload.toolName)) continue;
+		if (!isRecord(payload) || typeof payload.toolName !== "string") continue;
+		const result = payload.result;
+		const details = isRecord(result) && isRecord(result.details) ? result.details : null;
+		// An artifact written through the gateway is recorded under `gateway`
+		// with the capability stamped on its details; it is the same write.
+		const toolName = effectiveToolCall(payload.toolName, undefined, details ?? undefined).toolName;
+		if (!isSessionArtifactTool(toolName)) continue;
 		if (
 			payload.isError === true ||
 			payload.outcome === "error" ||
@@ -71,12 +78,10 @@ export function foldSessionArtifacts(
 		) {
 			continue;
 		}
-		const result = payload.result;
-		if (!isRecord(result) || !isRecord(result.details) || !Array.isArray(result.details.paths)) continue;
-		const artifactKind =
-			payload.toolName === "artifact" && isSessionArtifactKind(result.details.kind) ? result.details.kind : undefined;
+		if (!isRecord(result) || details === null || !Array.isArray(details.paths)) continue;
+		const artifactKind = toolName === "artifact" && isSessionArtifactKind(details.kind) ? details.kind : undefined;
 		const pathsSeenInResult = new Set<string>();
-		for (const recordedPath of result.details.paths) {
+		for (const recordedPath of details.paths) {
 			if (typeof recordedPath !== "string" || recordedPath.trim().length === 0) continue;
 			const normalized = normalizedWorkspacePath(recordedPath, workspace);
 			if (normalized === null || pathsSeenInResult.has(normalized)) continue;
@@ -86,7 +91,7 @@ export function foldSessionArtifacts(
 			writeIndex += 1;
 			lastByPath.set(normalized, {
 				path: recordedPath,
-				tool: payload.toolName,
+				tool: toolName,
 				...(artifactKind ? { artifactKind } : {}),
 				turnId: raw.turnId,
 				timestamp: raw.timestamp,

package/src/domains/session/task-board.ts

@@ -9,9 +9,8 @@ import {
 /**
  * The session task board: the live state behind the `tasks` tool, the footer
  * tasks row, and the /tasks overlay. Every mutation persists a full-snapshot
- * `taskLedger` entry (the dormant Phase 12 entry kind gains its producer
- * here), so the board is replayable from the JSONL alone and survives
- * resume/fork without any side-car state.
+ * `taskLedger` entry, so the board is replayable from the JSONL alone and
+ * survives resume/fork without any side-car state.
  *
  * Shape mapping onto TaskLedgerEntry:
  *   - the board title is the single top-level goal

package/src/domains/session/usage.ts

@@ -13,10 +13,8 @@
  * every surface's accounting, which is the same thing the tools/interactive
  * boundary rule exists to prevent.
  *
- * Assistant turns marked aborted or error are skipped for the same reason the
- * context estimator skips them: their usage is not a completed call. A
- * cancelled partial persists a fully populated all-zero usage object, so
- * counting it would add an API call worth nothing.
+ * Failed/aborted calls with reported usage still consumed resources. Skip
+ * only all-zero SDK placeholders, whose accounting was never observed.
  */
 
 import {
@@ -39,6 +37,7 @@ export interface LedgerUsageCall {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	costUsd: number;
@@ -58,7 +57,7 @@ function numberAt(source: Record<string, unknown>, key: string): number {
 }
 
 function reasoningTokensOf(usage: Record<string, unknown>): number {
-	const direct = numberAt(usage, "reasoningTokens");
+	const direct = numberAt(usage, "reasoning") || numberAt(usage, "reasoningTokens");
 	if (direct > 0) return direct;
 	const details = usage.outputTokensDetails ?? usage.completionTokensDetails;
 	if (details && typeof details === "object") return numberAt(details as Record<string, unknown>, "reasoningTokens");
@@ -109,6 +108,7 @@ export function ledgerUsageCalls(
 				output: usage.output,
 				cacheRead: usage.cacheRead,
 				cacheWrite: usage.cacheWrite,
+				...(usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: usage.cacheWrite1h }),
 				reasoningTokens: usage.reasoning,
 				totalTokens: usage.totalTokens,
 				costUsd: usage.cost.total,
@@ -129,8 +129,6 @@ export function ledgerUsageCalls(
 		const payload = entry.payload;
 		if (!payload || typeof payload !== "object" || Array.isArray(payload)) continue;
 		const record = payload as Record<string, unknown>;
-		const stopReason = record.stopReason;
-		if (stopReason === "aborted" || stopReason === "error") continue;
 		const rawUsage = record.usage;
 		if (!rawUsage || typeof rawUsage !== "object" || Array.isArray(rawUsage)) continue;
 		const usage = rawUsage as Record<string, unknown>;
@@ -156,6 +154,7 @@ export function ledgerUsageCalls(
 			output,
 			cacheRead,
 			cacheWrite,
+			...(typeof usage.cacheWrite1h === "number" ? { cacheWrite1h: numberAt(usage, "cacheWrite1h") } : {}),
 			reasoningTokens: reasoningTokensOf(usage),
 			totalTokens,
 			costUsd,

package/src/engine/acp/server.ts

@@ -2559,6 +2559,17 @@ export async function serveClioAcpAgent(options: ClioAcpServerOptions): Promise<
 		}
 		const text = promptText(params);
 		if (text.length === 0) throw new AcpRequestError(-32602, "prompt text is required", { code: "invalid_params" });
+		// Check the same credential authority as the runtime, without resolving or
+		// echoing a secret. Desktop services do not inherit a terminal's API keys.
+		const targetId = routingSnapshot().target;
+		const target = targetId ? options.providers?.getTarget(targetId) : undefined;
+		const runtime = target ? options.providers?.getRuntime(target.runtime) : undefined;
+		if (target && runtime && options.providers && !options.providers.auth.statusForTarget(target, runtime).available) {
+			throw new AcpRequestError(-32000, "credentials for the selected target are unavailable", {
+				code: "prompt_not_admitted",
+				reason: "authentication-required",
+			});
+		}
 		if (options.session?.current()?.id !== session.id && options.session) options.session.resume(session.id);
 		const active = createActivePromptState();
 		session.activePrompt = active;

package/src/engine/ai.ts

@@ -76,6 +76,7 @@ export interface EngineTextCompletionResult {
 		output: number;
 		cacheRead: number;
 		cacheWrite: number;
+		cacheWrite1h?: number;
 		reasoning: number;
 		totalTokens: number;
 		costUsd: number;
@@ -110,6 +111,7 @@ export async function completeEngineText(input: EngineTextCompletionInput): Prom
 			output: response.usage.output,
 			cacheRead: response.usage.cacheRead,
 			cacheWrite: response.usage.cacheWrite,
+			...(response.usage.cacheWrite1h === undefined ? {} : { cacheWrite1h: response.usage.cacheWrite1h }),
 			reasoning: response.usage.reasoning ?? 0,
 			totalTokens: response.usage.totalTokens,
 			costUsd: response.usage.cost.total,

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

@@ -35,6 +35,7 @@ import type { LocalModelQuirks, SamplingProfile } from "../../domains/providers/
 import type { LiteLLMTargetSettings, LmStudioTargetSettings } from "../../domains/providers/types/target-descriptor.js";
 import { filterGemmaChannelStream, usesGemmaChannelMarkers } from "../gemma-channel-filter.js";
 import { HarmonyResponseParser } from "../harmony-response.js";
+import { captureErrorBody, restoreTruncatedErrorBody } from "../provider-error-body.js";
 import { createSentinelStripper, stripTokenizerSentinels } from "../strip-tokenizer-sentinels.js";
 import { ensureLlamaCppResidency } from "./llamacpp-residency.js";
 import { ensureLmStudioResidency } from "./lmstudio.js";
@@ -110,6 +111,8 @@ interface ResponseModelIdCapture {
 	backendTimings: BackendCompletionTimings | null;
 	backendTimingsSource: BackendTimingsSource | null;
 	gatewayRouting: GatewayRoutingObservation | null;
+	/** Latest non-2xx body, read from a clone before the SDK truncates its copy. */
+	errorBody: Promise<string | null> | null;
 	buffer: string;
 	decoder: TextDecoder | null;
 }
@@ -212,6 +215,7 @@ function captureResponseModelId(response: Response, capture: ResponseModelIdCapt
 	if (runtimeMetadata(model)?.runtimeId === "litellm") {
 		capture.gatewayRouting = liteLLMGatewayRoutingFromHeaders(response.headers);
 	}
+	if (!response.ok) capture.errorBody = captureErrorBody(response);
 	if (!response.body || !response.headers.get("content-type")?.toLowerCase().includes("text/event-stream")) {
 		return response;
 	}
@@ -247,6 +251,7 @@ function withResponseModelIdCapture<TOptions extends StreamOptions>(
 		backendTimings: null,
 		backendTimingsSource: backendTimingsSourceForModel(model),
 		gatewayRouting: null,
+		errorBody: null,
 		buffer: "",
 		decoder: new TextDecoder(),
 	};
@@ -271,6 +276,9 @@ function withResponseModelIdCapture<TOptions extends StreamOptions>(
 					if (capture.gatewayRouting !== null) event.message.gatewayRouting = capture.gatewayRouting;
 					if (capture.backendTimings !== null) event.message.backendTimings = capture.backendTimings;
 				} else if (event.type === "error") {
+					if (event.error.errorMessage !== undefined && capture.errorBody !== null) {
+						event.error.errorMessage = restoreTruncatedErrorBody(event.error.errorMessage, await capture.errorBody);
+					}
 					event.error.responseModelIdObservation = observation;
 					if (capture.gatewayRouting !== null) event.error.gatewayRouting = capture.gatewayRouting;
 					if (capture.backendTimings !== null) event.error.backendTimings = capture.backendTimings;
@@ -546,11 +554,15 @@ function applyLmStudioPayload(
 	return next;
 }
 
-function applyLlamaCppPromptCachePayload(payload: Record<string, unknown>, model: Model<Api>): Record<string, unknown> {
+function applyLlamaCppPromptCachePayload(
+	payload: Record<string, unknown>,
+	model: Model<Api>,
+	retention: StreamOptions["cacheRetention"],
+): Record<string, unknown> {
 	const metadata = runtimeMetadata(model);
 	if (model.provider !== "llamacpp" || metadata?.runtimeId !== "llamacpp") return payload;
 	if (payload.cache_prompt !== undefined) return payload;
-	return { ...payload, cache_prompt: true };
+	return { ...payload, cache_prompt: retention !== "none" };
 }
 
 function shouldApplyLlamaCppPromptCache(model: Model<"openai-completions">): boolean {
@@ -562,13 +574,14 @@ function shouldApplyLlamaCppPromptCache(model: Model<"openai-completions">): boo
 function composeThinkingOnPayload(
 	resolved: ResolvedModelRuntimeCapabilities,
 	base: AnyOnPayload | undefined,
+	retention: StreamOptions["cacheRetention"],
 ): AnyOnPayload {
 	return async (payload, model) => {
 		if (!isPlainRecord(payload)) {
 			return base ? await base(payload, model) : undefined;
 		}
 		const next = applyLmStudioPayload(
-			applyThinkingPayload(applyLlamaCppPromptCachePayload(payload, model), resolved.thinking, resolved, model),
+			applyThinkingPayload(applyLlamaCppPromptCachePayload(payload, model, retention), resolved.thinking, resolved, model),
 			model,
 			resolved,
 		);
@@ -625,7 +638,7 @@ function withSamplingOverrides<TOptions extends StreamOptions>(
 		applied.mechanism === "on-off" ||
 		applied.mechanism === "none"
 	) {
-		merged.onPayload = composeThinkingOnPayload(resolved, options?.onPayload);
+		merged.onPayload = composeThinkingOnPayload(resolved, options?.onPayload, options?.cacheRetention);
 	}
 	return merged as TOptions;
 }

package/src/engine/loop-guard.ts

@@ -949,6 +949,13 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 			return true;
 		},
 		evaluate(input): ReadonlyArray<MiddlewareEffect> {
+			// A nested invocation (the gateway calling the capability the model
+			// asked for) is the same model call the outer gateway occurrence
+			// already counted and fingerprinted. Counting it again would spend
+			// the worker cap and the turn budget twice per gateway call, and its
+			// inner fingerprint would never repeat across a model's retries the
+			// outer one does not already show.
+			if (input.metadata?.nested === true) return [];
 			if (input.hook === "after_tool") {
 				recordSuccessfulResult(input);
 				recordResultForStagnation(input);

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/provider-error-body.ts

@@ -0,0 +1,65 @@
+/**
+ * pi-ai formats an HTTP error from the parsed JSON body and keeps only its first
+ * 4000 characters. Clio's fetch wrapper sees the same response first, so the
+ * discarded tail can be restored when the captured body provably is the one the
+ * SDK truncated. Anything else leaves the SDK diagnostic unchanged.
+ */
+const SDK_BODY_CHARS = 4000;
+const SDK_MARKER = /\.\.\. \[truncated (\d+) chars\]/u;
+/** Bounds both the capture read and the restored diagnostic kept in the ledger. */
+export const MAX_RESTORED_ERROR_BODY_CHARS = 65_536;
+const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
+
+/** Read a clone so the SDK still owns the original body. Never throws. */
+export async function captureErrorBody(response: Response): Promise<string | null> {
+	if (response.ok || response.body === null) return null;
+	try {
+		const reader = response.clone().body?.getReader();
+		if (reader === undefined) return null;
+		const decoder = new TextDecoder();
+		let text = "";
+		let bytes = 0;
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			bytes += value.byteLength;
+			// A body too large to hold cannot be compared exactly; keep the SDK text.
+			if (bytes > MAX_CAPTURE_BYTES) {
+				await reader.cancel().catch(() => {});
+				return null;
+			}
+			text += decoder.decode(value, { stream: true });
+		}
+		return text + decoder.decode();
+	} catch {
+		return null;
+	}
+}
+
+export function restoreTruncatedErrorBody(message: string, capturedBody: string | null): string {
+	if (capturedBody === null) return message;
+	const marker = SDK_MARKER.exec(message);
+	if (marker === null || marker.index < SDK_BODY_CHARS) return message;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(capturedBody);
+	} catch {
+		return message;
+	}
+	const start = marker.index - SDK_BODY_CHARS;
+	const kept = message.slice(start, marker.index);
+	const dropped = Number(marker[1]);
+	// The openai SDK exposes the body's `error` member when present, else the body.
+	const nested = typeof parsed === "object" && parsed !== null ? (parsed as { error?: unknown }).error : undefined;
+	for (const candidate of [nested, parsed]) {
+		if (typeof candidate !== "object" || candidate === null) continue;
+		const full = JSON.stringify(candidate).trim();
+		if (full.length - SDK_BODY_CHARS !== dropped || !full.startsWith(kept)) continue;
+		const restored =
+			full.length > MAX_RESTORED_ERROR_BODY_CHARS
+				? `${full.slice(0, MAX_RESTORED_ERROR_BODY_CHARS)}... [truncated ${full.length - MAX_RESTORED_ERROR_BODY_CHARS} chars]`
+				: full;
+		return `${message.slice(0, start)}${restored}${message.slice(marker.index + marker[0].length)}`;
+	}
+	return message;
+}