@gajae-code/ai 0.13.3 → 0.14.0

package/src/utils/idle-iterator.ts

@@ -106,12 +106,30 @@ export function resolveOpenAISdkRequestTimeoutMs(
 }
 
 export type Watchdog = NodeJS.Timeout | undefined;
+export interface FirstEventTimeoutFacts {
+	requestBytes?: number;
+	firstEventElapsedMs?: number;
+	firstEventTimeoutMs?: number;
+	endpointClass?: "canonical" | "custom";
+	retryMaxAttempts?: number;
+}
+
 export class FirstEventTimeoutError extends Error {
 	readonly providerCode = STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE;
+	readonly requestBytes?: number;
+	readonly firstEventElapsedMs?: number;
+	readonly firstEventTimeoutMs?: number;
+	readonly endpointClass?: "canonical" | "custom";
+	readonly retryMaxAttempts?: number;
 
-	constructor(message: string) {
+	constructor(message: string, facts: FirstEventTimeoutFacts = {}) {
 		super(message);
 		this.name = "FirstEventTimeoutError";
+		this.requestBytes = facts.requestBytes;
+		this.firstEventElapsedMs = facts.firstEventElapsedMs;
+		this.firstEventTimeoutMs = facts.firstEventTimeoutMs;
+		this.endpointClass = facts.endpointClass;
+		this.retryMaxAttempts = facts.retryMaxAttempts;
 	}
 }
 
@@ -202,6 +220,8 @@ export async function* iterateWithIdleTimeout<T>(
 		}
 	};
 	let lastProgressAt = Date.now();
+	const firstItemDeadlineAt =
+		firstItemTimeoutMs !== undefined && firstItemTimeoutMs > 0 ? Date.now() + firstItemTimeoutMs : undefined;
 
 	const noTimeoutEnforced =
 		(firstItemTimeoutMs === undefined || firstItemTimeoutMs <= 0) &&
@@ -210,7 +230,8 @@ export async function* iterateWithIdleTimeout<T>(
 	while (true) {
 		let activeTimeoutMs: number | undefined;
 		if (awaitingFirstItem) {
-			activeTimeoutMs = firstItemTimeoutMs;
+			activeTimeoutMs =
+				firstItemDeadlineAt === undefined ? undefined : Math.max(0, firstItemDeadlineAt - Date.now());
 		} else if (options.idleTimeoutMs !== undefined && options.idleTimeoutMs > 0) {
 			activeTimeoutMs = options.idleTimeoutMs - (Date.now() - lastProgressAt);
 			// The idle deadline may already have elapsed because the *consumer*
@@ -235,10 +256,7 @@ export async function* iterateWithIdleTimeout<T>(
 
 		let timer: NodeJS.Timeout | undefined;
 		let resolveTimeout: ((value: { kind: "timeout" }) => void) | undefined;
-		const enforceTimeout =
-			!noTimeoutEnforced &&
-			activeTimeoutMs !== undefined &&
-			(awaitingFirstItem ? activeTimeoutMs > 0 : activeTimeoutMs >= 0);
+		const enforceTimeout = !noTimeoutEnforced && activeTimeoutMs !== undefined && activeTimeoutMs >= 0;
 		if (enforceTimeout) {
 			const { promise, resolve } = Promise.withResolvers<{ kind: "timeout" }>();
 			resolveTimeout = resolve;
@@ -283,6 +301,11 @@ export async function* iterateWithIdleTimeout<T>(
 			if (outcome.kind === "error") {
 				throw outcome.error;
 			}
+			if (awaitingFirstItem && firstItemDeadlineAt !== undefined && Date.now() >= firstItemDeadlineAt) {
+				options.onFirstItemTimeout?.();
+				closeIterator();
+				throw new FirstEventTimeoutError(options.firstItemErrorMessage ?? options.errorMessage);
+			}
 			if (outcome.result.done) {
 				markFirstItemReceived();
 				return;

package/src/utils/oauth/callback-server.ts

@@ -36,6 +36,17 @@ export interface OAuthCallbackFlowOptions {
 	 * `onManualCodeInput` handler on the controller.
 	 */
 	skipCallbackServer?: boolean;
+	/**
+	 * Expected authorization-server issuer recorded from validated metadata
+	 * (RFC 9207 / MCP 2026-07-28). When set, a present `iss` that differs
+	 * rejects the response before any other parameter is acted on.
+	 */
+	expectedIssuer?: string;
+	/**
+	 * `authorization_response_iss_parameter_supported` from the same metadata.
+	 * When true, a response WITHOUT `iss` is rejected.
+	 */
+	issuerResponseIssSupported?: boolean;
 }
 
 /**
@@ -48,6 +59,8 @@ export abstract class OAuthCallbackFlow {
 	callbackHostname: string;
 	callbackBindHostname: string;
 	redirectUri?: string;
+	expectedIssuer?: string;
+	issuerResponseIssSupported?: boolean;
 	readonly #skipCallbackServer: boolean;
 	#callbackResolve?: (result: CallbackResult) => void;
 	#callbackReject?: (error: string) => void;
@@ -72,6 +85,8 @@ export abstract class OAuthCallbackFlow {
 		this.callbackHostname = preferredPortOrOptions.callbackHostname ?? DEFAULT_HOSTNAME;
 		this.callbackBindHostname = preferredPortOrOptions.callbackBindHostname ?? this.callbackHostname;
 		this.redirectUri = preferredPortOrOptions.redirectUri;
+		this.expectedIssuer = preferredPortOrOptions.expectedIssuer;
+		this.issuerResponseIssSupported = preferredPortOrOptions.issuerResponseIssSupported;
 		this.#skipCallbackServer = preferredPortOrOptions.skipCallbackServer === true;
 	}
 
@@ -202,12 +217,27 @@ export abstract class OAuthCallbackFlow {
 		const state = url.searchParams.get("state") || "";
 		const error = url.searchParams.get("error") || "";
 		const errorDescription = url.searchParams.get("error_description") || error;
+		const iss = url.searchParams.get("iss");
 
 		type OkState = { ok: true; code: string; state: string };
 		type ErrorState = { ok?: false; error?: string };
 		let resultState: OkState | ErrorState;
 
-		if (error) {
+		// RFC 9207 §2.4 (MCP 2026-07-28): validate the response issuer before acting
+		// on any other parameter; on mismatch, server-supplied error details must not
+		// be acted on or displayed, so the failure message is generic by design.
+		let issuerFailure: string | null = null;
+		if (this.expectedIssuer) {
+			if (iss !== null && iss !== this.expectedIssuer) {
+				issuerFailure = "Authorization response issuer mismatch";
+			} else if (iss === null && this.issuerResponseIssSupported === true) {
+				issuerFailure = "Authorization response missing required issuer (iss)";
+			}
+		}
+
+		if (issuerFailure) {
+			resultState = { ok: false, error: issuerFailure };
+		} else if (error) {
 			resultState = { ok: false, error: `Authorization failed: ${errorDescription}` };
 		} else if (!code) {
 			resultState = { ok: false, error: "Missing authorization code" };

package/src/utils/parse-bind.ts

@@ -3,6 +3,7 @@
  * paths. Centralized so the two servers can't drift on what they accept (the
  * gateway used to silently allow empty hostnames; this fixes it).
  */
+import { isIP } from "node:net";
 
 export interface ParsedBind {
 	hostname: string;
@@ -52,3 +53,29 @@ export function parseBind(raw: string): ParsedBind {
 	}
 	return { hostname: hostPart, port: parsePort(portPart, raw) };
 }
+
+/** True for loopback-only hostnames the auth servers may bind without credentials. */
+export function isLoopbackHostname(hostname: string): boolean {
+	const normalized = hostname
+		.trim()
+		.toLowerCase()
+		.replace(/^\[|\]$/g, "");
+	if (normalized === "localhost" || normalized === "::1") return true;
+	// Strict numeric IPv4 loopback literals only: a bare prefix match would
+	// accept attacker-controlled names like `127.evil.example`, and short/hex
+	// IPv4 forms (`127.1`, `0x7f.1`) are rejected by the parser anyway.
+	return isIP(normalized) === 4 && normalized.split(".")[0] === "127";
+}
+
+/**
+ * Fail closed when an unauthenticated auth server (empty bearer token set)
+ * would bind a non-loopback address: that exposes credential operations to the
+ * network with no proof of possession.
+ */
+export function assertAuthenticatedOrLoopback(bind: ParsedBind, bearerTokenCount: number, serverName: string): void {
+	if (bearerTokenCount > 0) return;
+	if (isLoopbackHostname(bind.hostname)) return;
+	throw new Error(
+		`${serverName} refuses to bind ${bind.hostname}:${bind.port} without bearer tokens; unauthenticated mode is loopback-only.`,
+	);
+}

package/src/utils/tool-call-healing.ts

@@ -17,7 +17,7 @@
  * the end of a chunk is held back until the next chunk arrives.
  */
 
-import { parseJsonWithRepair } from "./json-parse";
+import { findUnnecessaryUnicodeEscape, parseJsonWithRepair } from "./json-parse";
 
 const TOK_SECTION_BEGIN = "<|tool_calls_section_begin|>";
 const TOK_SECTION_END = "<|tool_calls_section_end|>";
@@ -34,6 +34,13 @@ export interface HealedToolCall {
 	readonly id: string;
 	readonly name: string;
 	readonly arguments: string;
+	/**
+	 * Whether the raw leaked payload spelled a printable non-ASCII character as a
+	 * `\uXXXX` escape. Captured BEFORE the normalizing round-trip below, which
+	 * decodes escapes into literal characters and would otherwise erase the only
+	 * evidence that the text is unverifiable.
+	 */
+	readonly escapedNonAsciiArguments: boolean;
 }
 
 /**
@@ -230,6 +237,10 @@ export class ToolCallHealer {
 		const name = normalizeFunctionName(rawId);
 		const id = generateHealedToolCallId();
 
+		// Sample the raw payload first: the round-trip below decodes `\uXXXX` into
+		// literal characters, so checking `argsJson` afterwards always reports clean.
+		const escapedNonAsciiArguments = findUnnecessaryUnicodeEscape(rawArgs) !== undefined;
+
 		let argsJson = rawArgs;
 		if (rawArgs.length > 0) {
 			try {
@@ -242,7 +253,7 @@ export class ToolCallHealer {
 			argsJson = "{}";
 		}
 
-		this.#completed.push({ id, name, arguments: argsJson });
+		this.#completed.push({ id, name, arguments: argsJson, escapedNonAsciiArguments });
 		this.#inCall = false;
 		this.#inArgs = false;
 		this.#pendingId = "";

package/src/utils/tool-choice-capability.ts

@@ -1,3 +1,8 @@
+import { Database } from "bun:sqlite";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getToolChoiceCapabilityCachePath } from "@gajae-code/utils/dirs";
 import { extractHttpStatusFromError } from "@gajae-code/utils/fetch-retry";
 import * as logger from "@gajae-code/utils/logger";
 import type { Api, Model, ToolChoice, ToolChoiceCompat, ToolChoiceSupport, ToolChoiceSupportSource } from "../types";
@@ -11,6 +16,26 @@ const supportRank: Record<ToolChoiceSupport, number> = {
 
 const registry = new Map<string, ToolChoiceSupport>();
 const loggedRegistryKeys = new Set<string>();
+const registryExpiresAt = new Map<string, number>();
+const CACHE_SCHEMA_VERSION = 1;
+const CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const EMPTY_CACHE_TTL_MS = 5 * 60 * 1000;
+const CACHE_MAX_ENTRIES = 256;
+const REGISTRY_MAX_ENTRIES = 256;
+const CACHE_MUTATION_LOCK_STALE_MS = 5_000;
+
+type NativeExactUnlinkBindings = Pick<typeof import("@gajae-code/natives"), "exactUnlink">;
+
+let nativeExactUnlinkBindings: NativeExactUnlinkBindings | undefined;
+
+let cachePathOverride: string | undefined;
+let nowForTests: (() => number) | undefined;
+let beforeExpiredDeleteForTests: (() => void) | undefined;
+let beforeMalformedDeleteForTests: (() => void) | undefined;
+let onCacheOpenForTests: (() => void) | undefined;
+let simulateCacheOperationErrorForTests: (() => Error | undefined) | undefined;
+let beforeCorruptRetireForTests: (() => void) | undefined;
+let beforeLockExactUnlinkForTests: ((lockPath: string) => void) | undefined;
 
 /**
  * Claude Mythos accepts tools but rejects forced tool use (Anthropic 400:
@@ -45,21 +70,55 @@ export function toolChoiceRegistryKey(model: Model<Api>): string {
 
 /** Returns the current runtime tool-choice capability override for a model. */
 export function getToolChoiceCapabilityOverride(model: Model<Api>): ToolChoiceSupport | undefined {
-	return registry.get(toolChoiceRegistryKey(model));
+	const key = toolChoiceRegistryKey(model);
+	hydrateToolChoiceCapability(key);
+	return registry.get(key);
 }
 
 /** Clears runtime tool-choice capability overrides for tests. */
 export function clearToolChoiceIncapabilityRegistryForTests(): void {
 	registry.clear();
 	loggedRegistryKeys.clear();
+	registryExpiresAt.clear();
+}
+
+/** Overrides durable-cache dependencies for isolated tests. */
+export function configureToolChoiceCapabilityCacheForTests(options?: {
+	path?: string;
+	now?: () => number;
+	beforeExpiredDelete?: () => void;
+	beforeMalformedDelete?: () => void;
+	onCacheOpen?: () => void;
+	simulateOperationError?: () => Error | undefined;
+	beforeCorruptRetire?: () => void;
+	beforeLockExactUnlink?: (lockPath: string) => void;
+}): void {
+	cachePathOverride = options?.path;
+	nowForTests = options?.now;
+	beforeExpiredDeleteForTests = options?.beforeExpiredDelete;
+	beforeMalformedDeleteForTests = options?.beforeMalformedDelete;
+	onCacheOpenForTests = options?.onCacheOpen;
+	simulateCacheOperationErrorForTests = options?.simulateOperationError;
+	beforeCorruptRetireForTests = options?.beforeCorruptRetire;
+	beforeLockExactUnlinkForTests = options?.beforeLockExactUnlink;
+	clearToolChoiceIncapabilityRegistryForTests();
 }
 
 /** Records a discovered maximum supported tool-choice level for a model. */
 export function markToolChoiceIncapability(model: Model<Api>, maxSupport: ToolChoiceSupport, reason?: string): void {
 	const key = toolChoiceRegistryKey(model);
-	const existing = registry.get(key);
-	const next = existing && supportRank[existing] < supportRank[maxSupport] ? existing : maxSupport;
-	registry.set(key, next);
+	const releaseMutationLock = acquireCapabilityCacheMutationLock();
+	try {
+		hydrateToolChoiceCapability(key);
+		const existing = registry.get(key);
+		const next = existing && supportRank[existing] < supportRank[maxSupport] ? existing : maxSupport;
+		registry.set(key, next);
+		const persisted = persistToolChoiceCapability(key, next);
+		if (persisted) registry.set(key, persisted.support);
+		registryExpiresAt.set(key, (persisted?.observedAt ?? currentTime()) + CACHE_TTL_MS);
+	} finally {
+		releaseMutationLock?.();
+	}
 
 	if (!loggedRegistryKeys.has(key)) {
 		loggedRegistryKeys.add(key);
@@ -74,6 +133,100 @@ export function markToolChoiceIncapability(model: Model<Api>, maxSupport: ToolCh
 	}
 }
 
+function acquireCapabilityCacheMutationLock(): (() => void) | undefined {
+	if (process.env.NODE_ENV === "test" && cachePathOverride === undefined) return;
+	const cachePath = cachePathOverride ?? getToolChoiceCapabilityCachePath();
+	const lockPath = `${cachePath}.mutation.lock`;
+	const sleeper = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+	const owner = `${process.pid}:${crypto.randomUUID()}`;
+	while (true) {
+		try {
+			fs.mkdirSync(path.dirname(cachePath), { recursive: true, mode: 0o700 });
+			const descriptor = fs.openSync(lockPath, "wx", 0o600);
+			fs.writeFileSync(descriptor, owner);
+			fs.closeSync(descriptor);
+			return () => {
+				try {
+					exactUnlinkCapabilityLock(lockPath, owner);
+				} catch {
+					// A crashed owner was already reaped.
+				}
+			};
+		} catch (error) {
+			if (!(error && typeof error === "object" && (error as { code?: unknown }).code === "EEXIST")) return;
+			try {
+				const lockOwner = fs.readFileSync(lockPath, "utf8");
+				const ownerPid = Number(lockOwner.split(":", 1)[0]);
+				const ownerIsAlive = Number.isSafeInteger(ownerPid) && ownerPid > 0 && isProcessAlive(ownerPid);
+				const staleOwner =
+					!ownerIsAlive && Date.now() - fs.statSync(lockPath).mtimeMs > CACHE_MUTATION_LOCK_STALE_MS;
+				if (staleOwner && !exactUnlinkCapabilityLock(lockPath, lockOwner)) {
+					Atomics.wait(sleeper, 0, 0, 10);
+					continue;
+				}
+			} catch {
+				// The lock changed while this waiter was being inspected.
+			}
+			Atomics.wait(sleeper, 0, 0, 10);
+		}
+	}
+}
+
+function exactUnlinkCapabilityLock(lockPath: string, expectedOwner: string): boolean {
+	// Open the lock first and read bytes + identity from the SAME descriptor: the
+	// pinned inode cannot be recycled or substituted while the handle is open, so
+	// a replacement owner that lands at the pathname after the read can never be
+	// mistaken for the record whose bytes authorized this removal.
+	const descriptor = fs.openSync(lockPath, "r");
+	let bytes: Buffer;
+	let stat: import("node:fs").BigIntStats;
+	try {
+		bytes = fs.readFileSync(descriptor);
+		if (bytes.toString("utf8") !== expectedOwner) return false;
+		stat = fs.fstatSync(descriptor, { bigint: true });
+		beforeLockExactUnlinkForTests?.(lockPath);
+		if (!stat.isFile()) return false;
+	} finally {
+		fs.closeSync(descriptor);
+	}
+	const parent = fs.statSync(path.dirname(lockPath), { bigint: true });
+	if (!parent.isDirectory()) return false;
+	if (!nativeExactUnlinkBindings)
+		nativeExactUnlinkBindings = require("@gajae-code/natives") as NativeExactUnlinkBindings;
+	const bindings = nativeExactUnlinkBindings;
+	const result = bindings.exactUnlink(lockPath, {
+		dev: stat.dev,
+		ino: stat.ino,
+		nlink: stat.nlink,
+		parentDev: parent.dev,
+		parentIno: parent.ino,
+		size: stat.size,
+		mtimeNs: stat.mtimeNs,
+		sha256: crypto.createHash("sha256").update(bytes).digest("hex"),
+		quarantineName: `.tool-choice-capability-lock-${crypto.randomUUID()}`,
+	});
+	return (
+		result.ok ||
+		(result.code === "cleanup_pending" &&
+			result.payloadDurable === true &&
+			result.detachedPath !== undefined &&
+			result.retainedSuccessorPath === undefined &&
+			result.retainedUnknownPath === undefined)
+	);
+}
+
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		// EPERM means the process exists but may not be signalable; only ESRCH
+		// proves the pid is gone. Any other outcome is treated as alive so an
+		// uncertain owner is never reaped as stale.
+		return (error as { code?: string }).code !== "ESRCH";
+	}
+}
+
 /**
  * Resolves a requested tool_choice against static and runtime capability limits.
  * `compat` overrides `model.compat` for transports that layer URL/provider
@@ -85,12 +238,13 @@ export function resolveToolChoice(
 	compat?: ToolChoiceCompat,
 ): ResolveToolChoiceResult {
 	const derived = deriveToolChoiceSupport(compat ?? model.compat);
-	const runtime = registry.get(toolChoiceRegistryKey(model));
+	const registryKey = toolChoiceRegistryKey(model);
+	hydrateToolChoiceCapability(registryKey);
+	const runtime = registry.get(registryKey);
 	const support = runtime && supportRank[runtime] < supportRank[derived.support] ? runtime : derived.support;
 	const supportSource: ToolChoiceSupportSource = support === derived.support ? derived.source : "runtime";
 	const requestedInfo = requestedToolChoiceLevel(requested);
 	const clampLevel = requestedInfo.requestedLevel === "none" ? "auto" : requestedInfo.requestedLevel;
-	const registryKey = toolChoiceRegistryKey(model);
 
 	if (requested === undefined) {
 		return {
@@ -251,3 +405,229 @@ function safeHostname(baseUrl: string): string | undefined {
 		return undefined;
 	}
 }
+
+function hydrateToolChoiceCapability(registryKey: string): void {
+	const now = currentTime();
+	const expiresAt = registryExpiresAt.get(registryKey);
+	if (expiresAt !== undefined && now < expiresAt) return;
+	registry.delete(registryKey);
+	registryExpiresAt.delete(registryKey);
+	const hydrated = withCapabilityCache(database => {
+		const digest = capabilityKeyDigest(registryKey);
+		const row = database
+			.query("SELECT max_support, support_rank, observed_at FROM tool_choice_capabilities WHERE key_digest = ?")
+			.get(digest) as { max_support?: unknown; support_rank?: unknown; observed_at?: unknown } | null;
+		if (!row) return false;
+		if (
+			!isToolChoiceSupport(row.max_support) ||
+			row.support_rank !== supportRank[row.max_support] ||
+			!isValidObservedAt(row.observed_at, now)
+		) {
+			beforeMalformedDeleteForTests?.();
+			database.run(
+				"DELETE FROM tool_choice_capabilities WHERE key_digest = ? AND max_support = ? AND support_rank = ? AND observed_at = ?",
+				[
+					digest,
+					typeof row.max_support === "string" ? row.max_support : String(row.max_support),
+					typeof row.support_rank === "number" ? row.support_rank : -1,
+					typeof row.observed_at === "number" ? row.observed_at : -1,
+				],
+			);
+			return false;
+		}
+		if (now - row.observed_at >= CACHE_TTL_MS) {
+			beforeExpiredDeleteForTests?.();
+			database.run("DELETE FROM tool_choice_capabilities WHERE key_digest = ? AND observed_at = ?", [
+				digest,
+				row.observed_at,
+			]);
+			return false;
+		}
+		registry.set(registryKey, row.max_support);
+		registryExpiresAt.set(registryKey, row.observed_at + CACHE_TTL_MS);
+		return true;
+	});
+	if (hydrated === false && !registryExpiresAt.has(registryKey)) {
+		registryExpiresAt.set(registryKey, now + EMPTY_CACHE_TTL_MS);
+	}
+	pruneRegistry(now);
+}
+
+function persistToolChoiceCapability(
+	registryKey: string,
+	maxSupport: ToolChoiceSupport,
+): { support: ToolChoiceSupport; observedAt: number } | undefined {
+	return withCapabilityCache(database => {
+		const write = database.transaction(() => {
+			const digest = capabilityKeyDigest(registryKey);
+			const observedAt = currentTime();
+			database.run(
+				"INSERT INTO tool_choice_capabilities (key_digest, max_support, support_rank, observed_at) VALUES (?, ?, ?, ?) ON CONFLICT(key_digest) DO UPDATE SET max_support = excluded.max_support, support_rank = excluded.support_rank, observed_at = excluded.observed_at WHERE excluded.support_rank <= tool_choice_capabilities.support_rank",
+				[digest, maxSupport, supportRank[maxSupport], observedAt],
+			);
+			database.run(
+				"DELETE FROM tool_choice_capabilities WHERE key_digest NOT IN (SELECT key_digest FROM tool_choice_capabilities ORDER BY observed_at DESC, key_digest DESC LIMIT ?)",
+				[CACHE_MAX_ENTRIES],
+			);
+			const row = database
+				.query("SELECT max_support, observed_at FROM tool_choice_capabilities WHERE key_digest = ?")
+				.get(digest) as { max_support?: unknown; observed_at?: unknown } | null;
+			return row && isToolChoiceSupport(row.max_support) && typeof row.observed_at === "number"
+				? { support: row.max_support, observedAt: row.observed_at }
+				: undefined;
+		});
+		return write();
+	});
+}
+
+function withCapabilityCache<T>(operation: (database: Database) => T): T | undefined {
+	if (process.env.NODE_ENV === "test" && cachePathOverride === undefined) return;
+	const cachePath = cachePathOverride ?? getToolChoiceCapabilityCachePath();
+	let openedFileSize: number | undefined;
+	try {
+		fs.mkdirSync(path.dirname(cachePath), { recursive: true, mode: 0o700 });
+		try {
+			openedFileSize = fs.statSync(cachePath).size;
+		} catch {
+			// File does not exist yet (first run); nothing to identity-check on retirement.
+		}
+		const database = openCapabilityCache(cachePath);
+		try {
+			try {
+				fs.chmodSync(cachePath, 0o600);
+			} catch {
+				// Cache access remains fail-open on filesystems without POSIX modes.
+			}
+			const simulatedError = simulateCacheOperationErrorForTests?.();
+			if (simulatedError) throw simulatedError;
+			return operation(database);
+		} finally {
+			database.close();
+		}
+	} catch (error) {
+		logger.debug("Tool-choice capability cache unavailable", {
+			cachePath: path.basename(cachePath),
+			error: error instanceof Error ? error.message : String(error),
+		});
+		if (isCorruptCapabilityCacheError(error)) {
+			beforeCorruptRetireForTests?.();
+			retireCorruptCapabilityCache(cachePath, openedFileSize);
+		}
+	}
+}
+
+function openCapabilityCache(cachePath: string): Database {
+	onCacheOpenForTests?.();
+	const database = new Database(cachePath, { create: true, strict: true });
+	try {
+		database.run("PRAGMA busy_timeout = 3000");
+		database.run("PRAGMA journal_mode = WAL");
+		database.run("PRAGMA synchronous = FULL");
+		const initialize = database.transaction(() => {
+			const version = database.query("PRAGMA user_version").get() as { user_version?: number } | null;
+			const schemaVersion = version?.user_version ?? 0;
+			if (schemaVersion === 0) {
+				database.run(`
+				CREATE TABLE IF NOT EXISTS tool_choice_capabilities (
+					key_digest TEXT PRIMARY KEY NOT NULL,
+					max_support TEXT NOT NULL,
+					support_rank INTEGER NOT NULL,
+					observed_at INTEGER NOT NULL
+				) STRICT
+			`);
+				assertCapabilityCacheSchema(database);
+				database.run(`PRAGMA user_version = ${CACHE_SCHEMA_VERSION}`);
+				return;
+			}
+			if (schemaVersion !== CACHE_SCHEMA_VERSION) {
+				throw new CapabilityCacheCorruptionError("unsupported cache schema version");
+			}
+			assertCapabilityCacheSchema(database);
+		});
+		initialize();
+		return database;
+	} catch (error) {
+		database.close();
+		throw error;
+	}
+}
+
+function assertCapabilityCacheSchema(database: Database): void {
+	const columns = database.query("PRAGMA table_info(tool_choice_capabilities)").all() as Array<{
+		name?: unknown;
+		type?: unknown;
+		notnull?: unknown;
+		pk?: unknown;
+	}>;
+	const actual = columns.map(column => [column.name, column.type, column.notnull, column.pk]);
+	const expected = [
+		["key_digest", "TEXT", 1, 1],
+		["max_support", "TEXT", 1, 0],
+		["support_rank", "INTEGER", 1, 0],
+		["observed_at", "INTEGER", 1, 0],
+	];
+	if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+		throw new CapabilityCacheCorruptionError("invalid cache schema");
+	}
+}
+
+class CapabilityCacheCorruptionError extends Error {}
+
+function isCorruptCapabilityCacheError(error: unknown): boolean {
+	if (error instanceof CapabilityCacheCorruptionError) return true;
+	if (!error || typeof error !== "object") return false;
+	const code = (error as { code?: unknown }).code;
+	return code === "SQLITE_CORRUPT" || code === "SQLITE_NOTADB";
+}
+
+/**
+ * Removes a confirmed-corrupt cache file and its WAL/SHM siblings. The file
+ * size captured before the corrupt open (`openedFileSize`) is checked before
+ * unlinking so a concurrently recreated valid replacement database with a
+ * different file size is never deleted.
+ */
+function retireCorruptCapabilityCache(cachePath: string, openedFileSize?: number): void {
+	for (const suffix of ["", "-wal", "-shm"]) {
+		const target = `${cachePath}${suffix}`;
+		try {
+			if (openedFileSize !== undefined && suffix === "") {
+				const stat = fs.statSync(target);
+				if (stat.size !== openedFileSize) continue;
+			}
+			fs.rmSync(target, { force: true });
+		} catch {
+			// A best-effort cache reset must never break provider fallback behavior.
+		}
+	}
+}
+
+function capabilityKeyDigest(registryKey: string): string {
+	return crypto.createHash("sha256").update(registryKey).digest("hex");
+}
+
+function isToolChoiceSupport(value: unknown): value is ToolChoiceSupport {
+	return value === "none" || value === "auto" || value === "required" || value === "named";
+}
+
+function isValidObservedAt(value: unknown, now: number): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= now;
+}
+
+function currentTime(): number {
+	return nowForTests?.() ?? Date.now();
+}
+
+function pruneRegistry(now: number): void {
+	for (const [key, expiresAt] of registryExpiresAt) {
+		if (expiresAt <= now) {
+			registryExpiresAt.delete(key);
+			registry.delete(key);
+		}
+	}
+	while (registryExpiresAt.size > REGISTRY_MAX_ENTRIES) {
+		const oldestKey = registryExpiresAt.keys().next().value;
+		if (typeof oldestKey !== "string") break;
+		registryExpiresAt.delete(oldestKey);
+		registry.delete(oldestKey);
+	}
+}