@bitkyc08/opencodex 2.14.0 → 2.14.1

package/src/providers/registry.ts

@@ -1300,10 +1300,10 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelContextWindows: CLINE_PASS_MODEL_CONTEXT_WINDOWS,
     modelInputModalities: CLINE_PASS_MODEL_INPUT_MODALITIES,
     noVisionModels: CLINE_PASS_TEXT_ONLY_MODELS,
-    // Only low and the `reasoning: { enabled, effort }` request shape have been accepted by a live
-    // ClinePass request. Neither wire detail is currently documented, so clamp higher Codex
-    // requests to the verified tier until the gateway documents or is live-probed more broadly.
-    reasoningEfforts: ["low"],
+    // Live-probed 2026-08-13 across every static ClinePass model: the gateway accepts and
+    // validates low/medium/high/xhigh/max, and rejects an invalid sentinel. Preserve the
+    // caller's requested tier and let ClinePass own any backend-specific normalization.
+    reasoningEfforts: ["low", "medium", "high", "xhigh", "max"],
     reasoningWireFormat: "gateway-object",
     preserveCustomDestination: true,
     note: "ClinePass subscription API. Uses a Cline API key and the full cline-pass/<model> upstream slug; quota is shared across the account's rolling 5-hour, weekly, and monthly limits.",
@@ -1789,7 +1789,7 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     liveModels: true,
     preserveCustomDestination: true,
     // /v1/models is documented as callable authenticated or unauthenticated, so a 2xx catalog
-    // response cannot prove the supplied Bearer key is valid.
+    // response cannot prove that the supplied Bearer key is valid.
     apiKeyValidation: "unknown",
     // Featherless documents tool calling, but not a provider-wide parallel tool-call contract.
     parallelToolCalls: false,

package/src/router.ts

@@ -267,6 +267,14 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
   const modelReasoningEffortMap = mergeNestedRecord(registryEntry.modelReasoningEffortMap, provider.modelReasoningEffortMap);
   const modelReasoningEfforts = mergeStringArrayRecord(registryEntry.modelReasoningEfforts, provider.modelReasoningEfforts);
   const modelDefaultReasoningEfforts = mergeRecordFill(registryEntry.modelDefaultReasoningEfforts, provider.modelDefaultReasoningEfforts);
+  // Key-login used to persist this exact low-only ClinePass capability seed. Once the gateway's
+  // wider input ladder was live-verified, leaving that generated row untouched would keep old
+  // installs clamped forever. This branch is reached only after canonical transport matching, so
+  // same-named custom destinations and every other explicit ladder still retain user precedence.
+  const repairLegacyClinePassReasoningEfforts = providerName === "cline-pass"
+    && provider.reasoningWireFormat === "gateway-object"
+    && provider.reasoningEfforts?.length === 1
+    && provider.reasoningEfforts[0] === "low";
   const modelContextWindows = providerName === OPENAI_API_PROVIDER_ID
     ? mergePositiveNumberCaps(registryEntry.modelContextWindows, provider.modelContextWindows)
     : mergeRecordFill(registryEntry.modelContextWindows, provider.modelContextWindows);
@@ -342,7 +350,10 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
     ...(provider.project === undefined && registryEntry.project !== undefined ? { project: registryEntry.project } : {}),
     ...(provider.location === undefined && registryEntry.location !== undefined ? { location: registryEntry.location } : {}),
     ...(provider.contextWindow === undefined && registryEntry.contextWindow !== undefined ? { contextWindow: registryEntry.contextWindow } : {}),
-    ...(provider.reasoningEfforts === undefined && registryEntry.reasoningEfforts !== undefined ? { reasoningEfforts: registryEntry.reasoningEfforts } : {}),
+    ...((provider.reasoningEfforts === undefined || repairLegacyClinePassReasoningEfforts)
+      && registryEntry.reasoningEfforts !== undefined
+      ? { reasoningEfforts: [...registryEntry.reasoningEfforts] }
+      : {}),
     ...(provider.escapeBuiltinToolNames === undefined && registryEntry.escapeBuiltinToolNames !== undefined ? { escapeBuiltinToolNames: registryEntry.escapeBuiltinToolNames } : {}),
     ...(provider.keyOptional === undefined && registryEntry.keyOptional !== undefined ? { keyOptional: registryEntry.keyOptional } : {}),
     ...(provider.modelSuffixBracketStrip === undefined && registryEntry.modelSuffixBracketStrip !== undefined ? { modelSuffixBracketStrip: registryEntry.modelSuffixBracketStrip } : {}),

package/src/server/index.ts

@@ -485,7 +485,7 @@ export function warnAgentTaskRecoveryStartup(config: {
   if (config.agentTaskRecovery?.enabled !== true) return;
   console.warn("⚠️  Experimental encrypted V2 task recovery is enabled.");
   console.warn("   A scoped cache miss may send an additional authenticated request to ChatGPT and may consume quota or add latency; concurrent misses can share one request.");
-  console.warn("   Recovered model output is retained only in a bounded in-memory cache; exact fidelity is not guaranteed and the path depends on undocumented backend behavior.");
+  console.warn("   Recovered plaintext assignment data is retained only in a bounded, process-local in-memory cache; exact fidelity is not guaranteed and the path depends on undocumented backend behavior.");
 }
 
 export function startServer(port?: number, deps: StartServerDeps = {}): Server<WsData> {

package/src/server/management/config-routes.ts

@@ -54,7 +54,16 @@ import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
 import { getProviderRegistryEntry } from "../../providers/registry";
 import { VISION_REASONING_EFFORTS, isVisionReasoningEffort } from "../../reasoning-effort";
 import { normalizeVisionReasoningForModel } from "../../vision/reasoning";
-import { findAnthropicVisionProvider, resolveEffectiveVisionModel, resolveVisionBackend } from "../../vision";
+import {
+  findAnthropicVisionProvider,
+  isValidVisionTimeoutMs,
+  MAX_VISION_TIMEOUT_MS,
+  MIN_VISION_TIMEOUT_MS,
+  resolveEffectiveVisionModel,
+  resolveMaxDescriptionsPerTurn,
+  resolveVisionBackend,
+  resolveVisionTimeoutMs,
+} from "../../vision";
 import {
   visionCandidateRows,
   visionDescriberIsProvablyBlind,
@@ -108,6 +117,21 @@ async function sidecarVisionResponseSettings(config: OcxConfig): Promise<{
   return { model, reasoning, models };
 }
 
+function publicVisionSidecarSettings(
+  config: OcxConfig,
+  vision: Awaited<ReturnType<typeof sidecarVisionResponseSettings>>,
+) {
+  const vs = config.visionSidecar ?? {};
+  return {
+    enabled: vs.enabled !== false,
+    model: vision.model,
+    backend: vs.backend,
+    reasoning: vision.reasoning,
+    maxDescriptionsPerTurn: resolveMaxDescriptionsPerTurn(vs.maxDescriptionsPerTurn),
+    timeoutMs: resolveVisionTimeoutMs(vs.timeoutMs),
+  };
+}
+
 export async function handleConfigRoutes(ctx: ManagementContext): Promise<Response | null> {
   const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
   if (url.pathname === "/api/config" && req.method === "GET") {
@@ -407,7 +431,6 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
 
   if (url.pathname === "/api/sidecar-settings" && req.method === "GET") {
     const ws = config.webSearchSidecar ?? {};
-    const vs = config.visionSidecar ?? {};
     const vision = await sidecarVisionResponseSettings(config);
     return jsonResponse({
       webSearch: {
@@ -415,12 +438,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         backend: ws.backend,
         streamRoutedModelOutput: ws.streamRoutedModelOutput === true,
       },
-      vision: {
-        model: vision.model,
-        backend: vs.backend,
-        reasoning: vision.reasoning,
-        maxDescriptionsPerTurn: vs.maxDescriptionsPerTurn,
-      },
+      vision: publicVisionSidecarSettings(config, vision),
       visionModels: vision.models,
     });
   }
@@ -435,7 +453,14 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     if (raw.vision !== undefined && !isPlainRecord(raw.vision)) return jsonResponse({ error: "vision must be an object" }, 400);
     const body = raw as {
       webSearch?: { model?: unknown; backend?: unknown; reasoning?: unknown; streamRoutedModelOutput?: unknown };
-      vision?: { model?: unknown; backend?: unknown; reasoning?: unknown; maxDescriptionsPerTurn?: unknown };
+      vision?: {
+        model?: unknown;
+        backend?: unknown;
+        reasoning?: unknown;
+        maxDescriptionsPerTurn?: unknown;
+        enabled?: unknown;
+        timeoutMs?: unknown;
+      };
     };
     if (body.webSearch && body.webSearch.backend !== undefined && body.webSearch.backend !== null
       && body.webSearch.backend !== "openai" && body.webSearch.backend !== "anthropic") {
@@ -455,6 +480,14 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         || body.vision.maxDescriptionsPerTurn <= 0)) {
       return jsonResponse({ error: "vision.maxDescriptionsPerTurn must be a positive integer" }, 400);
     }
+    if (body.vision && body.vision.enabled !== undefined && typeof body.vision.enabled !== "boolean") {
+      return jsonResponse({ error: "vision.enabled must be a boolean" }, 400);
+    }
+    if (body.vision && body.vision.timeoutMs !== undefined && !isValidVisionTimeoutMs(body.vision.timeoutMs)) {
+      return jsonResponse({
+        error: `vision.timeoutMs must be an integer from ${MIN_VISION_TIMEOUT_MS} to ${MAX_VISION_TIMEOUT_MS}`,
+      }, 400);
+    }
     if (body.vision?.reasoning !== undefined && !isVisionReasoningEffort(body.vision.reasoning)) {
       return jsonResponse({ error: `vision.reasoning must be ${VISION_REASONING_EFFORTS.join(", ")}` }, 400);
     }
@@ -517,6 +550,14 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       if (typeof body.vision.maxDescriptionsPerTurn === "number") {
         config.visionSidecar.maxDescriptionsPerTurn = body.vision.maxDescriptionsPerTurn;
       }
+      if (typeof body.vision.enabled === "boolean") {
+        // `true` is the default — drop the key so disable/re-enable does not rewrite the file.
+        if (body.vision.enabled) delete config.visionSidecar.enabled;
+        else config.visionSidecar.enabled = false;
+      }
+      if (typeof body.vision.timeoutMs === "number") {
+        config.visionSidecar.timeoutMs = body.vision.timeoutMs;
+      }
       if (visionReasoningTouched) {
         if (normalizedVisionReasoning === undefined) delete config.visionSidecar.reasoning;
         else config.visionSidecar.reasoning = normalizedVisionReasoning;
@@ -524,7 +565,6 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     }
     saveConfigPreservingClaudeCode(config);
     const ws = config.webSearchSidecar ?? {};
-    const vs = config.visionSidecar ?? {};
     const vision = await sidecarVisionResponseSettings(config);
     return jsonResponse({
       ok: true,
@@ -533,12 +573,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         backend: ws.backend,
         streamRoutedModelOutput: ws.streamRoutedModelOutput === true,
       },
-      vision: {
-        model: vision.model,
-        backend: vs.backend,
-        reasoning: vision.reasoning,
-        maxDescriptionsPerTurn: vs.maxDescriptionsPerTurn,
-      },
+      vision: publicVisionSidecarSettings(config, vision),
       visionModels: vision.models,
     });
   }

package/src/server/responses/core.ts

@@ -1779,7 +1779,6 @@ async function handleResponsesInner(
               );
             }
           }
-          toolBridgeMaps = buildToolBridgeMaps(parsed, translatorBudget);
         } catch {
           unreadableEncryptedAgentTask = true;
         }

package/src/server/responses/fetch-helpers.ts

@@ -1,4 +1,5 @@
 import type { Server } from "bun";
+import { codexWsUpstreamFetch, shouldUseCodexWsUpstream } from "./ws-upstream";
 import { bridgeToResponsesSSE, buildResponseJSON, formatErrorResponse, type ResponsesTerminalStatus } from "../../bridge";
 import {
   getConfigPath,
@@ -131,7 +132,17 @@ export function safeOriginLabel(url: string): string {
 
 
 export function providerFetch(provider: OcxProviderConfig): typeof globalThis.fetch {
-  return (provider as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch ?? globalThis.fetch;
+  const base = (provider as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch ?? globalThis.fetch;
+  // ChatGPT Codex backend: streaming turns ride the responses_websockets
+  // transport (measured ~3s faster TTFT than the SSE POST queue); everything
+  // else keeps the provider's HTTP fetch. See ws-upstream.ts for the details.
+  const wrapped = (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
+    if (typeof input === "string" && init && shouldUseCodexWsUpstream(input, init)) {
+      return codexWsUpstreamFetch(input, init, base);
+    }
+    return base(input, init);
+  };
+  return wrapped as typeof globalThis.fetch;
 }
 
 

package/src/server/responses/ws-upstream.ts

@@ -0,0 +1,199 @@
+// Upstream WebSocket transport for the ChatGPT Codex backend.
+//
+// Why this exists: the Codex backend serves the responses_websockets path from
+// a measurably faster queue than the plain SSE POST path. Measured 2026-08-12
+// KST (same account, same payload, strictly sequential): gpt-5.6-luna TTFT p50
+// ~1.0s over WS vs ~3.9s over SSE. Codex CLI itself defaults to the WS
+// transport; opencodex previously always POSTed SSE, which is where its extra
+// 2-3s of TTFT came from.
+//
+// The wrapper only swaps the transport. It dials wss:// with the same headers,
+// sends the JSON body as a single `response.create` frame, and re-encodes the
+// returned event frames as an SSE byte stream, so every downstream consumer
+// (passthrough relay, adapter parsers, usage sniffing) is unchanged.
+
+const CODEX_RESPONSES_HTTP_URL = "https://chatgpt.com/backend-api/codex/responses";
+const CODEX_RESPONSES_WS_URL = "wss://chatgpt.com/backend-api/codex/responses";
+const WS_BETA = "responses_websockets=2026-02-06";
+// If the 101 never arrives (network black hole), give SSE a chance well before
+// the caller's connect timeout (default 200s) would fire.
+const UPGRADE_DEADLINE_MS = 10_000;
+
+export function shouldUseCodexWsUpstream(url: string, init?: RequestInit): boolean {
+  if (url !== CODEX_RESPONSES_HTTP_URL) return false;
+  if ((init?.method ?? "GET").toUpperCase() !== "POST") return false;
+  const body = init?.body;
+  if (typeof body !== "string") return false;
+  // Only root-level stream:true selects WS: JSON-mode calls keep the HTTP path
+  // because the WS path only speaks the event protocol, and a nested
+  // {"metadata":{"stream":true}} must not flip the transport. Parsing (not
+  // substring matching) also keeps whitespace-formatted bodies routable.
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      && (parsed as Record<string, unknown>).stream === true;
+  } catch {
+    return false;
+  }
+}
+
+export function codexWsUpstreamFetch(
+  url: string,
+  init: RequestInit,
+  sseFallback: typeof globalThis.fetch,
+): Promise<Response> {
+  const signal = init.signal ?? undefined;
+  if (signal?.aborted) {
+    return Promise.reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+  }
+
+  let frameText: string;
+  try {
+    const body = JSON.parse(init.body as string) as Record<string, unknown>;
+    // The WS create frame is implicitly streaming; the backend rejects the
+    // HTTP-only `stream` flag inside a frame.
+    delete body.stream;
+    frameText = JSON.stringify({ ...body, type: "response.create" });
+  } catch {
+    return sseFallback(url, init);
+  }
+
+  const headers: Record<string, string> = {};
+  new Headers(init.headers ?? {}).forEach((value, key) => {
+    // HTTP-body framing headers do not apply to a WS handshake.
+    if (key === "content-type" || key === "content-length" || key === "accept" || key === "accept-encoding") return;
+    headers[key] = value;
+  });
+  headers["openai-beta"] = headers["openai-beta"]
+    ? headers["openai-beta"].includes("responses_websockets")
+      ? headers["openai-beta"]
+      : `${headers["openai-beta"]}, ${WS_BETA}`
+    : WS_BETA;
+  // A genuine caller `originator` is already in these headers via the forward
+  // set. Never fabricate one here: pool/forward traffic must not impersonate
+  // Codex CLI, per the metadata-integrity contract. (The backend's fast lane
+  // keys on WS + originator, so callers without the tag simply keep their own
+  // provenance and scheduling.)
+
+  return new Promise<Response>((resolve, reject) => {
+    let ws: WebSocket;
+    try {
+      // Bun accepts per-handshake headers; the DOM lib types only list protocol arrays.
+      ws = new WebSocket(CODEX_RESPONSES_WS_URL, { headers } as unknown as string[]);
+    } catch {
+      resolve(sseFallback(url, init));
+      return;
+    }
+
+    let opened = false;
+    let settledPreOpen = false;
+    let terminal = false;
+    let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
+    const encoder = new TextEncoder();
+
+    const upgradeTimer = setTimeout(() => {
+      if (opened || settledPreOpen) return;
+      settledPreOpen = true;
+      try { ws.close(); } catch { /* already closing */ }
+      resolve(sseFallback(url, init));
+    }, UPGRADE_DEADLINE_MS);
+
+    const onAbort = () => {
+      if (!opened) {
+        if (settledPreOpen) return;
+        // Settle BEFORE close(): the close handler treats a pre-open close as
+        // an upgrade rejection and would dial the SSE fallback for a request
+        // the caller just cancelled.
+        settledPreOpen = true;
+        clearTimeout(upgradeTimer);
+        try { ws.close(); } catch { /* already closing */ }
+        reject(signal?.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+        return;
+      }
+      try { ws.close(); } catch { /* already closing */ }
+      if (controller && !terminal) {
+        terminal = true;
+        // Mirror an aborted fetch: the body read rejects with the abort reason.
+        try { controller.error(signal?.reason ?? new DOMException("The operation was aborted.", "AbortError")); } catch { /* stream already done */ }
+      }
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    ws.addEventListener("open", () => {
+      if (settledPreOpen) return;
+      clearTimeout(upgradeTimer);
+      try {
+        ws.send(frameText);
+      } catch {
+        // send() throwing means the frame never left, so no upstream turn
+        // started and the SSE resend cannot double-generate. Falling back
+        // (instead of erroring a synthetic 200 body) keeps the pre-stream
+        // HTTP error/refresh/failover machinery in charge.
+        settledPreOpen = true;
+        try { ws.close(); } catch { /* already closing */ }
+        resolve(sseFallback(url, init));
+        return;
+      }
+      opened = true;
+      const stream = new ReadableStream<Uint8Array>({
+        start(c) { controller = c; },
+        cancel() { try { ws.close(); } catch { /* already closing */ } },
+      });
+      resolve(new Response(stream, {
+        status: 200,
+        // The 101 response headers (x-codex-*-reset-at quota hints) are not
+        // exposed by Bun's WebSocket; the periodic quota poller covers those.
+        headers: { "content-type": "text/event-stream; charset=utf-8" },
+      }));
+    });
+
+    ws.addEventListener("message", (event) => {
+      if (!controller || terminal) return;
+      const text = typeof event.data === "string" ? event.data : "";
+      if (!text) return;
+      let type: unknown;
+      try { type = (JSON.parse(text) as { type?: unknown }).type; } catch { return; }
+      if (typeof type !== "string") return;
+      // Relay only the event surface the SSE path produces today. WS-only
+      // frames (codex.rate_limits, responsesapi.websocket_timing) are dropped
+      // so downstream clients see exactly the stream shape they always got.
+      if (!type.startsWith("response.") && type !== "error") return;
+      try {
+        controller.enqueue(encoder.encode(`event: ${type}\ndata: ${text}\n\n`));
+      } catch {
+        return;
+      }
+      if (type === "response.completed" || type === "response.failed" || type === "response.incomplete" || type === "error") {
+        terminal = true;
+        try { controller.close(); } catch { /* already closed */ }
+        try { ws.close(); } catch { /* already closing */ }
+      }
+    });
+
+    ws.addEventListener("close", () => {
+      signal?.removeEventListener("abort", onAbort);
+      if (!opened) {
+        if (settledPreOpen) return;
+        settledPreOpen = true;
+        clearTimeout(upgradeTimer);
+        // Upgrade rejected (401/403/429/5xx). Retry over plain SSE so the real
+        // HTTP status reaches the existing refresh/rotation handlers. No turn
+        // started upstream, so the resend cannot double-generate.
+        resolve(sseFallback(url, init));
+        return;
+      }
+      if (controller && !terminal) {
+        terminal = true;
+        // Connection dropped before a Responses terminal event. A clean EOF
+        // here would reach clients with no response.completed/failed at all —
+        // relaySseWithFailedTail() only synthesizes a failed terminal when the
+        // body read THROWS. Error the stream like a reset TCP socket.
+        try { controller.error(new Error("codex websocket closed before a Responses terminal event")); } catch { /* stream already done */ }
+      }
+    });
+
+    ws.addEventListener("error", () => {
+      /* Bun always follows error with close; the close handler settles. */
+    });
+  });
+}

package/src/vision/index.ts

@@ -11,6 +11,11 @@ import type { ResolvedOpenAiForwardSidecar } from "../providers/openai-sidecar";
 import type { SidecarOutcomeRecorder } from "../web-search/executor";
 import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
 import type { TranslatorBudget } from "../lib/translator-budget";
+import {
+  DEFAULT_VISION_TIMEOUT_MS,
+  MAX_VISION_TIMEOUT_MS,
+  MIN_VISION_TIMEOUT_MS,
+} from "./timeout-bounds";
 
 export { describeImage } from "./describe";
 export { describeImageAnthropic, parseAnthropicVisionSSE } from "./anthropic-describe";
@@ -23,12 +28,16 @@ export {
   visionEligibleModelOptions,
 } from "./eligibility";
 export type { VisionCandidateModel, VisionModelOption, VisionSidecarBackend } from "./eligibility";
+export {
+  DEFAULT_VISION_TIMEOUT_MS,
+  MAX_VISION_TIMEOUT_MS,
+  MIN_VISION_TIMEOUT_MS,
+};
 
 const DEFAULT_VISION_MODEL = "gpt-5.4-mini";
 const DEFAULT_ANTHROPIC_VISION_MODEL = "claude-sonnet-5";
-const DEFAULT_TIMEOUT_MS = 45_000;
 const DEFAULT_REASONING: VisionReasoningEffort = "low";
-const DEFAULT_MAX_DESCRIPTIONS_PER_TURN = 8;
+export const DEFAULT_MAX_DESCRIPTIONS_PER_TURN = 8;
 const DESCRIPTION_CACHE_MAX_ENTRIES = 256;
 export const VISION_DESCRIPTION_CACHE_MAX_BYTES = 1024 * 1024;
 const descriptionEncoder = new TextEncoder();
@@ -154,6 +163,18 @@ export function resolveMaxDescriptionsPerTurn(value: unknown): number {
     : DEFAULT_MAX_DESCRIPTIONS_PER_TURN;
 }
 
+export function isValidVisionTimeoutMs(value: unknown): value is number {
+  return typeof value === "number"
+    && Number.isInteger(value)
+    && value >= MIN_VISION_TIMEOUT_MS
+    && value <= MAX_VISION_TIMEOUT_MS;
+}
+
+/** Runtime config is permissive: malformed or out-of-range values fall back to the default. */
+export function resolveVisionTimeoutMs(value: unknown): number {
+  return isValidVisionTimeoutMs(value) ? value : DEFAULT_VISION_TIMEOUT_MS;
+}
+
 /** Run `worker` over `items` with bounded concurrency, preserving input order in the result array. */
 async function runBounded<T, R>(items: T[], limit: number, worker: (item: T) => Promise<R>): Promise<R[]> {
   const results = new Array<R>(items.length);
@@ -271,7 +292,7 @@ export function planVisionSidecar(
       settings: {
         model,
         reasoning: normalizeVisionReasoningForModel(model, cfg.reasoning) ?? DEFAULT_REASONING,
-        timeoutMs: cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        timeoutMs: resolveVisionTimeoutMs(cfg.timeoutMs),
       },
       maxDescriptionsPerTurn,
     };
@@ -284,7 +305,7 @@ export function planVisionSidecar(
     settings: {
       model,
       reasoning: normalizeVisionReasoningForModel(model, cfg.reasoning) ?? DEFAULT_REASONING,
-      timeoutMs: cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        timeoutMs: resolveVisionTimeoutMs(cfg.timeoutMs),
     },
     maxDescriptionsPerTurn,
   };

package/src/vision/timeout-bounds.ts

@@ -0,0 +1,9 @@
+/**
+ * Inclusive integer bounds for `visionSidecar.timeoutMs`.
+ * The ceiling is the 32-bit timer delay used by `signalWithTimeout` / `setTimeout`.
+ * This module is the single authority: the runtime, management API, and Dashboard
+ * import these numbers rather than restating them.
+ */
+export const DEFAULT_VISION_TIMEOUT_MS = 45_000;
+export const MIN_VISION_TIMEOUT_MS = 1;
+export const MAX_VISION_TIMEOUT_MS = 2_147_483_647;