@oh-my-pi/pi-coding-agent 16.3.4 → 16.3.6

package/src/modes/utils/transcript-render-helpers.ts

@@ -7,8 +7,14 @@
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import { type Component, Text } from "@oh-my-pi/pi-tui";
 import { formatBytes, formatDuration } from "@oh-my-pi/pi-utils";
-import { type CustomMessage, type FileMentionMessage, isSilentAbort, resolveAbortLabel } from "../../session/messages";
+import {
+	type CustomMessage,
+	type FileMentionMessage,
+	resolveAbortLabel,
+	shouldRenderAbortReason,
+} from "../../session/messages";
 import { createIrcMessageCard } from "../../tools/irc";
+import { replaceTabs, TRUNCATE_LENGTHS, truncateToWidth } from "../../tools/render-utils";
 import { canonicalizeMessage } from "../../utils/thinking-display";
 import { TranscriptBlock } from "../components/transcript-container";
 import { theme } from "../theme/theme";
@@ -138,20 +144,41 @@ export function normalizeToolArgs(args: unknown): Record<string, unknown> {
 	return args && typeof args === "object" && !Array.isArray(args) ? (args as Record<string, unknown>) : {};
 }
 
+export type AssistantErrorPresentation =
+	| { kind: "none" }
+	| { kind: "full"; text: string; isError: true }
+	| { kind: "compact-recovered"; text: string; isError: false };
+
+function sanitizeRecoveredRetryNote(note: string): string {
+	const normalized = replaceTabs(note).replace(/\s+/g, " ").trim();
+	return truncateToWidth(normalized || "retried", TRUNCATE_LENGTHS.CONTENT);
+}
+
 /**
- * Resolve the inline error label, if any, for a turn-ending assistant message.
- * Silent aborts yield no label. `retryAttempt` tunes the abort label wording.
+ * Resolve the turn-ending assistant error presentation, if any.
+ * Silent and user-interrupt aborts yield no label. Recovered auto-retry errors
+ * collapse to a single non-error note; terminal errors keep the full red presentation.
  */
-export function resolveAssistantErrorMessage(
+export function resolveAssistantErrorPresentation(
 	message: AssistantAgentMessage,
 	retryAttempt = 0,
-): { hasErrorStop: boolean; errorMessage: string | null } {
-	const isAbortedSilently = message.stopReason === "aborted" && isSilentAbort(message);
-	const hasErrorStop = !isAbortedSilently && (message.stopReason === "aborted" || message.stopReason === "error");
-	const errorMessage = hasErrorStop
-		? message.stopReason === "aborted"
-			? resolveAbortLabel(message, retryAttempt)
-			: message.errorMessage || "Error"
-		: null;
-	return { hasErrorStop, errorMessage };
+): AssistantErrorPresentation {
+	if (message.retryRecovery?.status === "recovered") {
+		return {
+			kind: "compact-recovered",
+			text: sanitizeRecoveredRetryNote(message.retryRecovery.note),
+			isError: false,
+		};
+	}
+	if (message.stopReason === "aborted") {
+		if (!shouldRenderAbortReason(message)) return { kind: "none" };
+		return { kind: "full", text: resolveAbortLabel(message, retryAttempt), isError: true };
+	}
+	if (message.stopReason === "error") {
+		return { kind: "full", text: message.errorMessage || "Error", isError: true };
+	}
+	if (message.errorMessage && shouldRenderAbortReason(message)) {
+		return { kind: "full", text: message.errorMessage, isError: true };
+	}
+	return { kind: "none" };
 }

package/src/modes/utils/ui-helpers.ts

@@ -54,7 +54,7 @@ import {
 	buildFileMentionBlock,
 	buildIrcMessageCard,
 	normalizeToolArgs,
-	resolveAssistantErrorMessage,
+	resolveAssistantErrorPresentation,
 } from "./transcript-render-helpers";
 
 type TextBlock = { type: "text"; text: string };
@@ -317,7 +317,11 @@ export class UiHelpers {
 			const previous = waitingPoll;
 			if (!previous) return;
 			waitingPoll = null;
-			if (nextToolName === "job" && previous.isDisplaceableBlock()) {
+			if (
+				nextToolName === "job" &&
+				previous.isDisplaceableBlock() &&
+				this.ctx.chatContainer.isBlockUncommitted(previous)
+			) {
 				this.ctx.chatContainer.removeChild(previous);
 			}
 			// Sealing freezes the block and stops the waiting-poll spinner that
@@ -334,7 +338,9 @@ export class UiHelpers {
 			}
 			if (previous.canBeDisplacedBy(nextToolName)) {
 				todoSnapshot = null;
-				this.ctx.chatContainer.removeChild(previous);
+				if (this.ctx.chatContainer.isBlockUncommitted(previous)) {
+					this.ctx.chatContainer.removeChild(previous);
+				}
 				previous.seal();
 				return;
 			}
@@ -372,10 +378,9 @@ export class UiHelpers {
 					readGroup?.seal();
 					readGroup = null;
 				}
-				const { hasErrorStop, errorMessage } = resolveAssistantErrorMessage(
-					message,
-					this.ctx.viewSession.retryAttempt,
-				);
+				const errorPresentation = resolveAssistantErrorPresentation(message, this.ctx.viewSession.retryAttempt);
+				const hasErrorStop = errorPresentation.kind === "full";
+				const errorMessage = hasErrorStop ? errorPresentation.text : null;
 
 				// Render tool call components
 				for (const content of message.content) {

package/src/prompts/tools/read.md

@@ -67,7 +67,7 @@ For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 
 # Internal URIs
 
-All URI schemes take the same line selectors. `artifact://<id>` recovers full output a bash/eval/tool result spilled or truncated.
+All URI schemes take the same line selectors. `artifact://<id>` recovers spilled output; large artifacts block unbounded `:raw`, so page with `artifact://<id>:N-M` / `artifact://<id>:raw:N-M` and use the reported artifact file path for search/copy workflows.
 
 `ssh://host/<absolute-path>` reads a remote text file (UTF-8, ≤1 MiB) or lists a directory one level deep, on a pre-configured SSH host or `~/.ssh/config` alias; `ssh://host/` lists the remote root and bare `ssh://` lists the configured hosts. Files are also writable via `write` and searchable via `search`; a directory only lists (`search` refuses a directory, `write` refuses to overwrite one). A literal `:`, `?`, or `#` in the remote path must be percent-encoded (`%3A`/`%3F`/`%23`) — a trailing `:sel` is read as a line selector, and `?`/`#` start a URL query/fragment. Requires a POSIX login shell (`sh`/`bash`/`zsh`); a Windows host or a non-POSIX shell (fish, csh/tcsh) is rejected — use the `ssh` tool there.
 

package/src/sdk.ts

@@ -993,6 +993,7 @@ function createCustomToolsExtension(tools: CustomTool[]): ExtensionFactory {
 					success: event.success,
 					attempt: event.attempt,
 					finalError: event.finalError,
+					recoveredErrors: event.recoveredErrors,
 				},
 				ctx,
 			),

package/src/session/agent-session.ts

@@ -81,6 +81,8 @@ import type { ProtectedToolMatcher } from "@oh-my-pi/pi-agent-core/compaction/to
 import type {
 	AssistantMessage,
 	AssistantMessageEvent,
+	AssistantRetryRecovery,
+	AssistantRetryRecoveryKind,
 	Context,
 	ImageContent,
 	Message,
@@ -219,6 +221,7 @@ import { createExtensionModelQuery } from "../extensibility/extensions/model-api
 import type { CompactOptions, ContextUsage } from "../extensibility/extensions/types";
 import { ExtensionToolWrapper } from "../extensibility/extensions/wrapper";
 import type { HookCommandContext } from "../extensibility/hooks/types";
+import type { RecoveredRetryError } from "../extensibility/shared-events";
 import type { Skill, SkillWarning } from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
 import { GoalRuntime } from "../goals/runtime";
@@ -497,7 +500,13 @@ export type AgentSessionEvent =
 			errorMessage: string;
 			errorId?: number;
 	  }
-	| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
+	| {
+			type: "auto_retry_end";
+			success: boolean;
+			attempt: number;
+			finalError?: string;
+			recoveredErrors?: RecoveredRetryError[];
+	  }
 	| { type: "retry_fallback_applied"; from: string; to: string; role: string }
 	| { type: "retry_fallback_succeeded"; model: string; role: string }
 	| { type: "ttsr_triggered"; rules: Rule[] }
@@ -1425,6 +1434,13 @@ type MessageEndPersistenceSlot = {
 	persist: (persistMessage: () => void) => Promise<void>;
 	release: () => void;
 };
+type PendingRecoveredRetryError = {
+	entryId: string;
+	persistenceKey: string;
+	recovery: AssistantRetryRecoveryKind;
+	attempt: number;
+	note: string;
+};
 
 type PostPromptSkipReason = "aborted" | "stale-generation";
 
@@ -1581,6 +1597,7 @@ export class AgentSession {
 	#retryPromise: Promise<void> | undefined = undefined;
 	#retryResolve: (() => void) | undefined = undefined;
 	#activeRetryFallback: ActiveRetryFallbackState | undefined = undefined;
+	#pendingRecoveredRetryErrors: PendingRecoveredRetryError[] = [];
 	// Todo completion reminder state
 	#todoReminderCount = 0;
 	/**
@@ -3663,11 +3680,14 @@ export class AgentSession {
 							role: this.#activeRetryFallback.role,
 						});
 					}
+					const recoveredErrors = await this.#markPendingRecoveredRetryErrors(assistantMsg);
 					await this.#emitSessionEvent({
 						type: "auto_retry_end",
 						success: true,
 						attempt: this.#retryAttempt,
+						recoveredErrors,
 					});
+					this.#clearPendingRecoveredRetryErrors();
 					this.#retryAttempt = 0;
 				}
 				if (assistantMsg.provider === "opencode-go") {
@@ -5337,6 +5357,7 @@ export class AgentSession {
 				success: event.success,
 				attempt: event.attempt,
 				finalError: event.finalError,
+				recoveredErrors: event.recoveredErrors,
 			});
 		} else if (event.type === "ttsr_triggered") {
 			await this.#extensionRunner.emit({ type: "ttsr_triggered", rules: event.rules });
@@ -10386,6 +10407,126 @@ export class AgentSession {
 		return undefined;
 	}
 
+	#clearPendingRecoveredRetryErrors(): void {
+		this.#pendingRecoveredRetryErrors = [];
+	}
+
+	#retryRecoveryKind(
+		id: number,
+		switchedCredential: boolean,
+		switchedModel: boolean,
+		delayMs: number,
+	): AssistantRetryRecoveryKind {
+		if (switchedCredential) return "credential";
+		if (switchedModel) return "model";
+		if (AIError.is(id, AIError.Flag.UsageLimit) && delayMs > 0) return "wait";
+		return "plain";
+	}
+
+	#retryRecoveryNote(recovery: AssistantRetryRecoveryKind, rateLimited: boolean): string {
+		const parts: string[] = [];
+		if (rateLimited) {
+			parts.push("rate-limited");
+		} else if (recovery === "plain") {
+			parts.push("error");
+		}
+		if (recovery === "credential") {
+			parts.push("switched account");
+		} else if (recovery === "model") {
+			parts.push("switched model");
+		} else if (recovery === "wait") {
+			parts.push("waited");
+		}
+		parts.push("retried");
+		return parts.join("; ");
+	}
+
+	async #recordPendingRecoveredRetryError(
+		message: AssistantMessage,
+		id: number,
+		options: { switchedCredential: boolean; switchedModel: boolean; delayMs: number },
+	): Promise<void> {
+		await this.#waitForSessionMessagePersistence(message);
+		const persistenceKey = sessionMessagePersistenceKey(message);
+		if (!persistenceKey) return;
+		let branchEntry: SessionEntry | undefined;
+		for (const entry of this.sessionManager.getBranch().slice().reverse()) {
+			if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+			if (sessionMessagePersistenceKey(entry.message) !== persistenceKey) continue;
+			if (!sameMessageContent(entry.message, message) && !this.#isSameAssistantMessage(entry.message, message)) {
+				continue;
+			}
+			branchEntry = entry;
+			break;
+		}
+		if (!branchEntry) return;
+		if (this.#pendingRecoveredRetryErrors.some(error => error.entryId === branchEntry.id)) return;
+		const rateLimited = AIError.is(id, AIError.Flag.UsageLimit);
+		const recovery = this.#retryRecoveryKind(id, options.switchedCredential, options.switchedModel, options.delayMs);
+		const note = this.#retryRecoveryNote(recovery, rateLimited);
+		this.#pendingRecoveredRetryErrors.push({
+			entryId: branchEntry.id,
+			persistenceKey,
+			recovery,
+			attempt: this.#retryAttempt,
+			note,
+		});
+	}
+
+	async #markPendingRecoveredRetryErrors(supersedingMessage: AssistantMessage): Promise<RecoveredRetryError[]> {
+		if (this.#pendingRecoveredRetryErrors.length === 0) return [];
+		const branch = this.sessionManager.getBranch();
+		const branchById = new Map<string, SessionEntry>();
+		for (const entry of branch) {
+			branchById.set(entry.id, entry);
+		}
+		const recoveredAt = new Date().toISOString();
+		const supersededBy: AssistantRetryRecovery["supersededBy"] = {
+			timestamp: supersedingMessage.timestamp,
+			provider: supersedingMessage.provider,
+			model: supersedingMessage.model,
+		};
+		if (supersedingMessage.responseId) {
+			supersededBy.responseId = supersedingMessage.responseId;
+		}
+		const recoveredErrors: RecoveredRetryError[] = [];
+		for (const pending of this.#pendingRecoveredRetryErrors) {
+			let entry = branchById.get(pending.entryId);
+			if (entry?.type !== "message" || entry.message.role !== "assistant") {
+				entry = branch
+					.slice()
+					.reverse()
+					.find(
+						candidate =>
+							candidate.type === "message" &&
+							candidate.message.role === "assistant" &&
+							sessionMessagePersistenceKey(candidate.message) === pending.persistenceKey,
+					);
+			}
+			if (entry?.type !== "message" || entry.message.role !== "assistant") continue;
+			const retryRecovery: AssistantRetryRecovery = {
+				kind: "auto-retry",
+				status: "recovered",
+				attempt: pending.attempt,
+				recoveredAt,
+				recovery: pending.recovery,
+				note: pending.note,
+				supersededBy,
+			};
+			entry.message.retryRecovery = retryRecovery;
+			recoveredErrors.push({
+				entryId: entry.id,
+				persistenceKey: pending.persistenceKey,
+				note: retryRecovery.note,
+				retryRecovery,
+			});
+		}
+		if (recoveredErrors.length > 0) {
+			await this.sessionManager.rewriteEntries();
+		}
+		return recoveredErrors;
+	}
+
 	async #handleEmptyAssistantStop(assistantMessage: AssistantMessage): Promise<boolean> {
 		if (!this.#isEmptyAssistantStop(assistantMessage)) {
 			this.#emptyStopRetryCount = 0;
@@ -10406,6 +10547,7 @@ export class AgentSession {
 					attempt: this.#retryAttempt,
 					finalError: "Assistant returned empty stop after retry cap",
 				});
+				this.#clearPendingRecoveredRetryErrors();
 				this.#retryAttempt = 0;
 			}
 			this.#resolveRetry();
@@ -13265,6 +13407,7 @@ export class AgentSession {
 				attempt: this.#retryAttempt - 1,
 				finalError: message.errorMessage,
 			});
+			this.#clearPendingRecoveredRetryErrors();
 			this.#retryAttempt = 0;
 			this.#resolveRetry(); // Resolve so waitForRetry() completes
 			return false;
@@ -13384,10 +13527,13 @@ export class AgentSession {
 				attempt,
 				finalError: `Provider requested ${delayMs}ms wait, exceeds retry.maxDelayMs (${maxDelayMs}ms). Original error: ${errorMessage}`,
 			});
+			this.#clearPendingRecoveredRetryErrors();
 			this.#resolveRetry();
 			return false;
 		}
 
+		await this.#recordPendingRecoveredRetryError(message, id, { switchedCredential, switchedModel, delayMs });
+
 		await this.#emitSessionEvent({
 			type: "auto_retry_start",
 			attempt: this.#retryAttempt,
@@ -13425,6 +13571,7 @@ export class AgentSession {
 				attempt,
 				finalError: "Retry cancelled",
 			});
+			this.#clearPendingRecoveredRetryErrors();
 			this.#resolveRetry();
 			return false;
 		}

package/src/session/session-context.ts

@@ -251,6 +251,13 @@ export function buildSessionContext(
 	const appendMessage = (entry: SessionEntry) => {
 		handleEntryResetTracking(entry);
 		if (entry.type === "message") {
+			if (
+				!options?.transcript &&
+				entry.message.role === "assistant" &&
+				entry.message.retryRecovery?.status === "recovered"
+			) {
+				return;
+			}
 			pushMessage(entry.message);
 		} else if (entry.type === "custom_message") {
 			pushMessage(

package/src/subprocess/worker-runtime.ts

@@ -1,3 +1,4 @@
+import * as fsp from "node:fs/promises";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import type { ProgressInfo } from "@huggingface/transformers";
@@ -27,6 +28,15 @@ import packageJson from "../../package.json" with { type: "json" };
 
 export const TRANSFORMERS_PACKAGE = "@huggingface/transformers";
 const COMPILED_TRANSFORMERS_VERSION = process.env.PI_TINY_TRANSFORMERS_VERSION;
+const ONNX_RUNTIME_NODE_PACKAGE = "onnxruntime-node";
+const ONNX_RUNTIME_CUDA_INSTALL = "cuda12";
+const ONNX_RUNTIME_CUDA_PROVIDER_FILES = [
+	"libonnxruntime_providers_cuda.so",
+	"libonnxruntime_providers_shared.so",
+	"libonnxruntime_providers_tensorrt.so",
+] as const;
+const LINUX_X64_ONNX_RUNTIME_CUDA_PROVIDER_DIR = path.join("bin", "napi-v6", "linux", "x64");
+
 const sourceRequire = createRequire(import.meta.url);
 
 // ── Error serialization ─────────────────────────────────────────────
@@ -162,6 +172,87 @@ export async function installSharpStubResolver(runtimeDir: string): Promise<stri
 	return nodeModules;
 }
 
+function shouldInstallOnnxRuntimeCudaProviders(device: string | undefined): boolean {
+	const normalized = device?.trim().toLowerCase();
+	return (
+		process.platform === "linux" &&
+		process.arch === "x64" &&
+		(normalized === "cuda" || normalized === "gpu" || normalized === "auto")
+	);
+}
+
+async function missingOnnxRuntimeCudaProviderFiles(binDir: string): Promise<string[]> {
+	const missing: string[] = [];
+	for (const file of ONNX_RUNTIME_CUDA_PROVIDER_FILES) {
+		try {
+			await fsp.access(path.join(binDir, file));
+		} catch {
+			missing.push(file);
+		}
+	}
+	return missing;
+}
+
+async function readPipe(stream: ReadableStream<Uint8Array> | null): Promise<string> {
+	if (!stream) return "";
+	return new Response(stream).text();
+}
+
+async function installOnnxRuntimeCudaProviders(packageDir: string, runtimeDir: string, binDir: string): Promise<void> {
+	const script = path.join(packageDir, "script", "install.js");
+	try {
+		await fsp.access(script);
+	} catch {
+		throw new Error(
+			`ONNX Runtime CUDA provider binaries are missing from ${binDir}, and ${script} is unavailable. Remove the tiny-model side runtime cache at ${runtimeDir} and retry.`,
+		);
+	}
+
+	const proc = Bun.spawn([process.execPath, script], {
+		cwd: runtimeDir,
+		env: { ...Bun.env, BUN_BE_BUN: "1", ONNXRUNTIME_NODE_INSTALL: ONNX_RUNTIME_CUDA_INSTALL },
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const [stdout, stderr, exitCode] = await Promise.all([
+		readPipe(proc.stdout as ReadableStream<Uint8Array> | null),
+		readPipe(proc.stderr as ReadableStream<Uint8Array> | null),
+		proc.exited,
+	]);
+	if (exitCode !== 0) {
+		const output = `${stdout}\n${stderr}`.trim();
+		throw new Error(
+			`Failed to install ONNX Runtime CUDA provider binaries into ${binDir} with ${process.execPath} ${script} (exit ${exitCode}). Remove the tiny-model side runtime cache at ${runtimeDir} and retry with network access. ${output}`,
+		);
+	}
+}
+
+/**
+ * Repairs the compiled Transformers side runtime when CUDA was requested and
+ * Bun skipped `onnxruntime-node`'s NuGet sidecar install.
+ */
+export async function ensureOnnxRuntimeCudaProviders(
+	runtimeDir: string,
+	device = process.env.PI_TINY_DEVICE,
+): Promise<void> {
+	if (!shouldInstallOnnxRuntimeCudaProviders(device)) return;
+	const nodeModules = path.join(runtimeDir, "node_modules");
+	const manifest = resolveRuntimeModule(nodeModules, `${ONNX_RUNTIME_NODE_PACKAGE}/package.json`);
+	if (!manifest)
+		throw new Error(`Unable to resolve ${ONNX_RUNTIME_NODE_PACKAGE} in compiled runtime at ${nodeModules}`);
+	const packageDir = path.dirname(manifest);
+	const binDir = path.join(packageDir, LINUX_X64_ONNX_RUNTIME_CUDA_PROVIDER_DIR);
+	const missing = await missingOnnxRuntimeCudaProviderFiles(binDir);
+	if (missing.length === 0) return;
+
+	await installOnnxRuntimeCudaProviders(packageDir, runtimeDir, binDir);
+	const stillMissing = await missingOnnxRuntimeCudaProviderFiles(binDir);
+	if (stillMissing.length === 0) return;
+	throw new Error(
+		`ONNX Runtime CUDA provider install completed but ${stillMissing.join(", ")} are still missing from ${binDir}. Remove the tiny-model side runtime cache at ${runtimeDir} and retry.`,
+	);
+}
+
 /**
  * Prepare a freshly-installed compiled runtime for loading and return the
  * absolute entrypoint of `packageName` to `require`.
@@ -211,6 +302,114 @@ interface ConfigurableTransformers {
 	LogLevel: { ERROR: unknown };
 }
 
+export interface TransformersRuntimeMetadata {
+	__ompRuntimeNodeModules?: string;
+	__ompTransformersEntry?: string;
+	__ompCudaRepairError?: string;
+}
+
+function attachTransformersRuntimeMetadata<T extends ConfigurableTransformers>(
+	transformers: T,
+	metadata: TransformersRuntimeMetadata,
+): T {
+	const runtime = transformers as T & TransformersRuntimeMetadata;
+	runtime.__ompRuntimeNodeModules = metadata.__ompRuntimeNodeModules;
+	runtime.__ompTransformersEntry = metadata.__ompTransformersEntry;
+	runtime.__ompCudaRepairError = metadata.__ompCudaRepairError;
+	return runtime;
+}
+
+const TRANSITIVE_CUDA_LIBRARY_RE =
+	/\b(lib(?:cu|nv)[A-Za-z0-9_.+-]*\.so(?:\.[0-9]+)*)\b[^:\n]*:\s*cannot open shared object file/iu;
+const CUDA_DEVICE_UNAVAILABLE_RE = /\bCUDA failure 100\b|no CUDA-capable device is detected|cudaSetDevice|GPU=-1/iu;
+
+function cudaDeviceUnavailable(error: unknown): boolean {
+	return CUDA_DEVICE_UNAVAILABLE_RE.test(errorText(error));
+}
+
+function missingCudaLibrary(error: unknown): string | undefined {
+	return TRANSITIVE_CUDA_LIBRARY_RE.exec(errorText(error))?.[1];
+}
+
+function cudaFailureCause(
+	metadata: TransformersRuntimeMetadata,
+	error: unknown,
+	missingFiles: readonly string[],
+): string {
+	if (metadata.__ompCudaRepairError) {
+		return `ONNX Runtime CUDA provider install failed: ${metadata.__ompCudaRepairError}`;
+	}
+	if (missingFiles.length > 0) return `missing ONNX Runtime CUDA provider file(s): ${missingFiles.join(", ")}`;
+	const missingLibrary = missingCudaLibrary(error);
+	if (missingLibrary) return `${missingLibrary}: cannot open shared object file`;
+	if (cudaDeviceUnavailable(error)) {
+		return "CUDA provider files are present; CUDA runtime reports no CUDA-capable device";
+	}
+	return "CUDA provider files are present; inspect the original ONNX Runtime CUDA error";
+}
+
+function cudaFailureHint(
+	metadata: TransformersRuntimeMetadata,
+	error: unknown,
+	missingFiles: readonly string[],
+): string {
+	if (metadata.__ompCudaRepairError) {
+		return "restore network access to nuget.org (or pre-populate the tiny side runtime) and rerun; CPU inference remained available";
+	}
+	if (missingFiles.length > 0) return "reinstall the tiny side runtime with ONNX Runtime postinstall enabled";
+	if (missingCudaLibrary(error)) {
+		return "install the matching CUDA/cuDNN shared libraries and expose them on the dynamic loader path";
+	}
+	if (cudaDeviceUnavailable(error)) {
+		return "make the NVIDIA GPU visible to this process/session, or use providers.tinyModelDevice=default/cpu";
+	}
+	return "check the host CUDA driver, device visibility, and ONNX Runtime CUDA compatibility";
+}
+
+function resolveOnnxRuntimePackageDir(metadata: TransformersRuntimeMetadata): string | null {
+	const entry = metadata.__ompTransformersEntry;
+	if (entry) {
+		try {
+			return path.dirname(createRequire(entry).resolve(`${ONNX_RUNTIME_NODE_PACKAGE}/package.json`));
+		} catch {
+			// Fall through to the side-runtime resolver below.
+		}
+	}
+	const nodeModules = metadata.__ompRuntimeNodeModules;
+	if (!nodeModules) return null;
+	const manifest = resolveRuntimeModule(nodeModules, `${ONNX_RUNTIME_NODE_PACKAGE}/package.json`);
+	return manifest ? path.dirname(manifest) : null;
+}
+
+export async function formatOnnxRuntimeCudaDiagnostics(
+	metadata: TransformersRuntimeMetadata,
+	requestedDevice: string,
+	error: unknown,
+): Promise<string | null> {
+	const device = requestedDevice.trim().toLowerCase();
+	if (device !== "cuda" && device !== "gpu" && device !== "auto") return null;
+	if (process.platform !== "linux" || process.arch !== "x64") return null;
+	const packageDir = resolveOnnxRuntimePackageDir(metadata);
+	if (!packageDir) {
+		return [
+			"ONNX Runtime CUDA diagnostics:",
+			`  PI_TINY_DEVICE=${requestedDevice} requested CUDAExecutionProvider`,
+			"  cause: unable to resolve onnxruntime-node in the tiny-model runtime",
+		].join("\n");
+	}
+	const binDir = path.join(packageDir, LINUX_X64_ONNX_RUNTIME_CUDA_PROVIDER_DIR);
+	const missingFiles = await missingOnnxRuntimeCudaProviderFiles(binDir);
+	const sideRuntime = metadata.__ompRuntimeNodeModules;
+	const lines = [
+		"ONNX Runtime CUDA diagnostics:",
+		`  PI_TINY_DEVICE=${requestedDevice} requested CUDAExecutionProvider`,
+		sideRuntime ? `  side runtime: ${sideRuntime}` : `  onnxruntime-node: ${packageDir}`,
+		`  cause: ${cudaFailureCause(metadata, error, missingFiles)}`,
+	];
+	lines.push(`  hint: ${cudaFailureHint(metadata, error, missingFiles)}`);
+	return lines.join("\n");
+}
+
 function configureTransformers<T extends ConfigurableTransformers>(transformers: T): T {
 	transformers.env.cacheDir = getTinyModelsCacheDir();
 	transformers.env.allowLocalModels = false;
@@ -251,7 +450,12 @@ export function loadTransformersRuntime<T extends ConfigurableTransformers, K>(
 	runtimeDir: () => string,
 ): Promise<T> {
 	return holder.load(async () => {
-		if (!isCompiledBinary()) return configureTransformers(sourceRequire(TRANSFORMERS_PACKAGE) as T);
+		if (!isCompiledBinary()) {
+			const entry = sourceRequire.resolve(TRANSFORMERS_PACKAGE);
+			return attachTransformersRuntimeMetadata(configureTransformers(sourceRequire(entry) as T), {
+				__ompTransformersEntry: entry,
+			});
+		}
 		const installedDir = await ensureRuntimeInstalled({
 			runtimeDir: runtimeDir(),
 			install: {
@@ -270,8 +474,21 @@ export function loadTransformersRuntime<T extends ConfigurableTransformers, K>(
 					},
 				}),
 		});
+		let cudaRepairError: string | undefined;
+		try {
+			await ensureOnnxRuntimeCudaProviders(installedDir);
+		} catch (repairError) {
+			// Deferred failure: keep loading Transformers so `loadPipelineWithDeviceFallback`
+			// still gets its CUDA→CPU retry. The error is surfaced through the CUDA
+			// diagnostics attached to the runtime metadata.
+			cudaRepairError = errorMessage(repairError);
+		}
 		const entry = await prepareCompiledRuntime(installedDir, TRANSFORMERS_PACKAGE);
 		const require_ = createRequire(entry);
-		return configureTransformers(require_(entry) as T);
+		return attachTransformersRuntimeMetadata(configureTransformers(require_(entry) as T), {
+			__ompRuntimeNodeModules: path.join(installedDir, "node_modules"),
+			__ompTransformersEntry: entry,
+			__ompCudaRepairError: cudaRepairError,
+		});
 	});
 }