@bitkyc08/opencodex 2.17.1-preview.20260814 → 2.19.0

package/src/service.ts

@@ -7,8 +7,8 @@
  */
 import { execFileSync, execSync, spawnSync } from "node:child_process";
 import { findLiveProxy, proxyIdentityAt, SERVICE_STOP_LIVENESS } from "./server/proxy-liveness";
-import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve, win32 } from "node:path";
 import { expandUserPath, getConfigDir, readPid, removePid, removeRuntimePort, verifyPidIdentity } from "./config";
 import { loadConfig } from "./config";
@@ -24,9 +24,11 @@ import {
   ELEVATION_REQUEST_TIMEOUT_MS,
   OCX_ELEVATED_PROTOCOL_FAILED,
   raceWithTimeout,
+  resolveTrustedWindowsPowerShellExe,
   resolveTrustedWindowsSchtasksExe,
   startElevatedSchtasksCreateAndRun,
   runWindowsElevated,
+  runWindowsElevatedScheduledTaskRegistration,
   toWindowsSchtasksError,
   WindowsElevationError,
   WindowsSchtasksError,
@@ -35,7 +37,12 @@ import {
   type ElevatedSchtasksCreateAndRunResult,
 } from "./lib/windows-elevation";
 import { defaultWinswEntry, installWinswService, startWinswService, stopWinswService, statusWinswRaw, uninstallWinswService, winswStatusSummary, winswXmlPath, WINSW_SERVICE_ID, WINSW_SHA256, WINSW_VERSION, type WinswStatus } from "./lib/winsw";
-import { hardenSecretDir, hardenSecretPath } from "./lib/windows-secret-acl";
+import {
+  forgetEphemeralSecretDir,
+  forgetEphemeralSecretPath,
+  hardenSecretDir,
+  hardenSecretPath,
+} from "./lib/windows-secret-acl";
 import { windowsEnvIndirectBatchPathList, windowsEnvIndirectBatchValue } from "./lib/win-paths";
 import { recordOwnedConfigPath } from "./lib/config-ownership";
 import { maybeShowStarPrompt } from "./cli/star-prompt";
@@ -1896,22 +1903,115 @@ function writeWindowsSchedulerAssets(): void {
   writeServiceAssetWithRetry(windowsTaskXmlPath(), `\uFEFF${buildWindowsTaskXml(script)}`, "utf16le");
 }
 
-function stageWindowsSchedulerRegistrationXml(attemptNonce: string): string {
-  if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
-  const path = join(getConfigDir(), `.opencodex-service-task.${randomUUID()}.xml`);
-  // This document points at the canonical launcher but does not publish or rewrite that
-  // launcher. UAC can therefore be refused while the current proxy still owns its port.
-  writeServiceAssetWithRetry(
-    path,
-    `\uFEFF${buildWindowsTaskXml(windowsServiceScriptPath(), windowsLauncherVbsPath(), attemptNonce)}`,
-    "utf16le",
+const WINDOWS_SCHEDULER_STAGE_PREFIX = "opencodex-service-stage-";
+const ownedWindowsSchedulerStages = new Set<string>();
+
+export interface WindowsSchedulerRegistrationStageDeps {
+  createStageDir?: () => string;
+  hardenDir?: (path: string) => void;
+  writeXml?: (path: string, contents: string) => void;
+  hardenPath?: (path: string) => void;
+  removeStageDir?: (path: string) => void;
+}
+
+function cleanupWindowsSchedulerStage(
+  stageDir: string,
+  xmlPath: string,
+  removeStageDir: (path: string) => void,
+): void {
+  let cleanupError: unknown;
+  try {
+    unlinkSync(xmlPath);
+    forgetEphemeralSecretPath(xmlPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") {
+      forgetEphemeralSecretPath(xmlPath);
+    } else {
+      cleanupError = error;
+    }
+  }
+  try {
+    removeStageDir(stageDir);
+    forgetEphemeralSecretDir(stageDir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") {
+      forgetEphemeralSecretDir(stageDir);
+    } else if (cleanupError) {
+      throw new AggregateError([cleanupError, error], "Task Scheduler staging cleanup failed.");
+    } else {
+      cleanupError = error;
+    }
+  }
+  if (cleanupError) throw cleanupError;
+}
+
+export function stageWindowsSchedulerRegistrationXml(
+  attemptNonce: string,
+  deps: WindowsSchedulerRegistrationStageDeps = {},
+): string {
+  const createStageDir = deps.createStageDir
+    ?? (() => mkdtempSync(join(tmpdir(), WINDOWS_SCHEDULER_STAGE_PREFIX)));
+  const hardenDir = deps.hardenDir
+    ?? ((path: string) => { hardenSecretDir(path, { required: true }); });
+  const writeXml = deps.writeXml ?? ((path: string, contents: string) => {
+    writeFileSync(path, contents, { encoding: "utf16le", flag: "wx", mode: 0o600 });
+  });
+  const hardenPath = deps.hardenPath
+    ?? ((path: string) => { hardenSecretPath(path, { required: true }); });
+  const removeStageDir = deps.removeStageDir
+    ?? ((path: string) => { rmdirSync(path); });
+
+  let stageDir: string | null = null;
+  let xmlPath: string | null = null;
+  try {
+    stageDir = createStageDir();
+    try { chmodSync(stageDir, 0o700); } catch { /* required Windows ACL is authoritative */ }
+    hardenDir(stageDir);
+    xmlPath = join(stageDir, "task.xml");
+    // This document points at the canonical launcher but does not publish or rewrite it.
+    // The hardened private directory prevents another local account from replacing the
+    // document while UAC is pending; the file harden independently proves its identity.
+    writeXml(
+      xmlPath,
+      `\uFEFF${buildWindowsTaskXml(windowsServiceScriptPath(), windowsLauncherVbsPath(), attemptNonce)}`,
+    );
+    hardenPath(xmlPath);
+    ownedWindowsSchedulerStages.add(xmlPath);
+    return xmlPath;
+  } catch (error) {
+    if (stageDir) {
+      try {
+        cleanupWindowsSchedulerStage(stageDir, xmlPath ?? join(stageDir, "task.xml"), removeStageDir);
+      } catch (cleanupError) {
+        throw new AggregateError(
+          [error, cleanupError],
+          "Task Scheduler staging failed and its private temporary directory could not be removed.",
+        );
+      }
+    }
+    throw error;
+  }
+}
+
+function removeWindowsSchedulerRegistrationStage(xmlPath: string): void {
+  if (!ownedWindowsSchedulerStages.has(xmlPath)) {
+    throw new Error("Refusing to remove an unrecognized Task Scheduler staging path.");
+  }
+  const stageDir = dirname(xmlPath);
+  cleanupWindowsSchedulerStage(
+    stageDir,
+    xmlPath,
+    path => { rmdirSync(path); },
   );
-  return path;
+  if (existsSync(stageDir)) {
+    throw new Error("The private Task Scheduler staging directory still exists after cleanup.");
+  }
+  ownedWindowsSchedulerStages.delete(xmlPath);
 }
 
 export interface FreshWindowsSchedulerRegistrationDeps {
   create?: (args: string[]) => void;
-  elevate?: (args: string[]) => Promise<void>;
+  elevate?: (taskName: string, xml: string) => Promise<void>;
   probe?: () => WindowsSchedulerTaskProbe;
   queryXml?: () => string;
   rollback?: () => Promise<string | null>;
@@ -1923,6 +2023,16 @@ export async function registerFreshWindowsSchedulerTask(
   deps: FreshWindowsSchedulerRegistrationDeps = {},
 ): Promise<void> {
   const args = buildWindowsSchtasksCreateArgsForXml(xmlPath);
+  // Capture and validate the exact definition before an access-denied attempt can
+  // cross the UAC boundary. The elevated fallback receives these immutable bytes,
+  // never the caller-writable staging pathname.
+  const expectedXml = decodeSchtasksOutput(readFileSync(xmlPath));
+  if (
+    !windowsTaskRegistrationHealthy(expectedXml)
+    || !windowsTaskRegistrationOwnedByAttempt(expectedXml, attemptNonce)
+  ) {
+    throw new Error("The staged Task Scheduler registration failed OpenCodex ownership or shape validation.");
+  }
   try {
     (deps.create ?? schtasks)(args);
   } catch (error) {
@@ -1933,9 +2043,13 @@ export async function registerFreshWindowsSchedulerTask(
     ) {
       throw error;
     }
-    // The elevated command is still the fixed trusted schtasks executable plus the
-    // owned create shape. It registers only; the task is not run until cleanup commits.
-    await (deps.elevate ?? elevateSchtasks)(args);
+    // Register from the captured XML string inside the elevated process. Another
+    // same-user process can mutate its own temp files, but cannot change this command.
+    const elevate = deps.elevate ?? (async (taskName: string, xml: string) => {
+      const exitCode = await runWindowsElevatedScheduledTaskRegistration(taskName, xml);
+      if (exitCode !== 0) throw new Error(`Background service install failed with exit code ${exitCode}.`);
+    });
+    await elevate(TASK, expectedXml);
   }
 
   const rollbackTask = deps.rollback ?? (() => rollbackWindowsSchedulerTaskOwnedByAttempt(attemptNonce, TASK));
@@ -1978,21 +2092,47 @@ export async function registerFreshWindowsSchedulerTask(
   }
 }
 
-function installWindows(): void {
-  recordOwnedConfigPath(getConfigDir(), serviceStatePath());
+function recordWindowsSchedulerOwnership(): boolean {
+  // Ownership claiming is deliberately conservative: a legacy non-empty config root
+  // without metadata stays unclaimed, but that must not turn a service reinstall into
+  // an outage after prepareServiceInstall has stopped the previous manager.
+  return recordOwnedConfigPath(getConfigDir(), serviceStatePath());
+}
+
+export interface RemoveNativeWindowsServiceDeps {
+  status?: () => WinswStatus;
+  uninstall?: () => void;
+  sleep?: (ms: number) => void;
+  settleChecks?: number;
+}
+
+export function removeNativeWindowsServiceForScheduler(
+  deps: RemoveNativeWindowsServiceDeps = {},
+): void {
+  const status = deps.status ?? statusWinswRaw;
+  const uninstall = deps.uninstall ?? uninstallWinswService;
+  const sleep = deps.sleep ?? Bun.sleepSync;
+  const settleChecks = Math.max(1, deps.settleChecks ?? 20);
   // Transactional backend switch: installing the scheduler backend removes a native
   // service first — two live managers would both respawn the proxy (conflict).
-  if (statusWinswRaw() !== "nonexistent") {
+  if (status() !== "nonexistent") {
     console.log("🔁 Removing the native (WinSW) service before installing the Task Scheduler backend...");
     try {
-      uninstallWinswService();
+      uninstall();
     } catch (err) {
       throw new Error(`Cannot remove the native service before switching to Task Scheduler: ${err instanceof Error ? err.message : String(err)}. Remove it manually with 'sc delete ${WINSW_SERVICE_ID}' or retry.`);
     }
-    if (statusWinswRaw() !== "nonexistent") {
-      throw new Error(`Native service registration could not be re-verified after the removal attempt — aborting switch. Check 'sc.exe query ${WINSW_SERVICE_ID}' and remove it manually if present.`);
+    for (let check = 0; check < settleChecks; check++) {
+      if (status() === "nonexistent") return;
+      if (check + 1 < settleChecks) sleep(250);
     }
+    throw new Error(`Native service registration could not be re-verified after the removal attempt — aborting switch. Check 'sc.exe query ${WINSW_SERVICE_ID}' and remove it manually if present.`);
   }
+}
+
+function installWindows(): void {
+  recordWindowsSchedulerOwnership();
+  removeNativeWindowsServiceForScheduler();
   // End a running task BEFORE rewriting the assets it is executing — cmd.exe reading the
   // script mid-rewrite runs a torn batch file, and its open handle can fail the write.
   try { stopWindows(); } catch { /* not running */ }
@@ -2164,6 +2304,50 @@ export function stopWindows(): void {
 }
 function statusWindows(): string { try { return schtasks(["/query", "/tn", TASK]); } catch { return ""; } }
 function statusWindowsXml(): string { try { return schtasks(["/query", "/tn", TASK, "/xml"]); } catch { return ""; } }
+
+/**
+ * Best-effort termination of surviving Windows scheduler launcher/wrapper processes.
+ * `schtasks /end` ends the task instance but often leaves wscript/cmd running the
+ * `:loop` batch, which brings the proxy back during a stop or restart. Same killer
+ * the update job uses, so both teardown paths share the guarantee.
+ *
+ * Matching is scoped to the CANONICAL paths of THIS installation (opencodex-service.cmd
+ * and opencodex-service-launcher.vbs under the current config dir), never a bare
+ * filename: a wrapper from another OpenCodex home — or an unrelated process whose
+ * command line merely contains the filename — must not be force-terminated.
+ * The path must appear as a COMPLETE command-line token (wscript.exe spawns the
+ * .vbs as an argument; cmd.exe /c runs the .cmd), so a substring-only match is
+ * excluded.
+ */
+function killWindowsServiceWrapperProcesses(): void {
+  if (process.platform !== "win32") return;
+  try {
+    const script = windowsServiceScriptPath();
+    const launcher = windowsLauncherVbsPath();
+    // Quote for PowerShell: single-quote the value and double any embedded quote.
+    const quote = (value: string) => `'${value.replace(/'/g, "''")}'`;
+    const ps = [
+      `$pats = @(${quote(script)}, ${quote(launcher)});`,
+      "Get-CimInstance Win32_Process | Where-Object {",
+      "  if ($_.ProcessId -eq $PID) { return $false };",
+      "  $c = $_.CommandLine; if (-not $c) { return $false };",
+      "  foreach ($p in $pats) {",
+      "    $i = $c.IndexOf($p, [System.StringComparison]::OrdinalIgnoreCase);",
+      "    if ($i -lt 0) { continue };",
+      "    $before = if ($i -gt 0) { $c.Substring($i - 1, 1) } else { ' ' };",
+      "    $end = $i + $p.Length;",
+      "    $after = if ($end -lt $c.Length) { $c.Substring($end, 1) } else { ' ' };",
+      "    if ($before -match '[\\s\"'']' -and $after -match '[\\s\"'']') { return $true };",
+      "  };",
+      "  $false",
+      "} | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }",
+    ].join(" ");
+    spawnSync(resolveTrustedWindowsPowerShellExe(), [
+      "-NoProfile", "-NoLogo", "-NonInteractive", "-WindowStyle", "Hidden",
+      "-Command", ps,
+    ], { stdio: "ignore", timeout: 5000, windowsHide: true });
+  } catch { /* best-effort */ }
+}
 function uninstallWindows(): void {
   const probe = probeWindowsSchedulerTask(TASK);
   if (probe.status === "present") {
@@ -2595,7 +2779,9 @@ export async function installServiceSafely(
 export interface FreshWindowsSchedulerInstallDeps {
   stageRegistrationXml?: (attemptNonce: string) => string;
   register?: (xmlPath: string, attemptNonce: string) => Promise<void>;
+  recordOwnership?: () => boolean;
   prepare?: () => Promise<void>;
+  removeNativeService?: () => void;
   publishAssets?: () => void;
   runTask?: () => void;
   writeState?: () => void;
@@ -2616,7 +2802,9 @@ export async function installFreshWindowsSchedulerSafely(
 ): Promise<void> {
   const stage = deps.stageRegistrationXml ?? stageWindowsSchedulerRegistrationXml;
   const register = deps.register ?? registerFreshWindowsSchedulerTask;
+  const recordOwnership = deps.recordOwnership ?? recordWindowsSchedulerOwnership;
   const prepare = deps.prepare ?? (() => prepareServiceInstall("scheduler"));
+  const removeNativeService = deps.removeNativeService ?? removeNativeWindowsServiceForScheduler;
   const publishAssets = deps.publishAssets ?? writeWindowsSchedulerAssets;
   const runTask = deps.runTask ?? startWindows;
   const writeState = deps.writeState ?? (() => writeServiceInstallState("scheduler"));
@@ -2624,11 +2812,12 @@ export async function installFreshWindowsSchedulerSafely(
     rollbackWindowsSchedulerTaskOwnedByAttempt(attemptNonce, TASK)
   ));
   const removeStagedXml = deps.removeStagedXml ?? ((path: string) => {
-    if (existsSync(path)) unlinkSync(path);
+    removeWindowsSchedulerRegistrationStage(path);
   });
 
   let stagedXml: string | null = null;
   const attemptNonce = randomUUID();
+  const configRootWasAbsent = !existsSync(getConfigDir());
   let registered = false;
   let started = false;
   try {
@@ -2637,7 +2826,19 @@ export async function installFreshWindowsSchedulerSafely(
     registered = true;
 
     // The destructive boundary begins only after Task Scheduler accepted the definition.
+    // The registration has consumed its temporary XML. Remove it before claiming a newly
+    // created config root, because ownership initialization intentionally requires emptiness.
+    removeStagedXml(stagedXml);
+    stagedXml = null;
+    const ownershipRecorded = recordOwnership();
+    if (!ownershipRecorded && configRootWasAbsent) {
+      throw new Error(
+        "The fresh OpenCodex config root could not be claimed for safe uninstall; "
+        + "aborting before service-manager cleanup or asset publication.",
+      );
+    }
     await prepare();
+    removeNativeService();
     publishAssets();
     runTask();
     started = true;
@@ -2663,8 +2864,11 @@ export async function installFreshWindowsSchedulerSafely(
   } finally {
     if (stagedXml) {
       try { removeStagedXml(stagedXml); } catch (error) {
+        const code = error && typeof error === "object" && "code" in error
+          ? String((error as NodeJS.ErrnoException).code)
+          : "";
         console.error(
-          `⚠️  Failed to remove temporary Task Scheduler XML ${stagedXml}: ${error instanceof Error ? error.message : String(error)}`,
+          `⚠️  Failed to remove the private Task Scheduler staging directory${code ? ` (${code})` : ""}.`,
         );
       }
     }
@@ -2692,6 +2896,10 @@ export function stopServiceIfInstalled(): boolean {
     if (statusWinswRaw() !== "nonexistent") {
       try { stopWinswService(); stopped = true; } catch { /* best-effort */ }
     }
+    // `schtasks /end` ends the task instance but the cmd `:loop` wrapper survives and
+    // respawns its child seconds later (issue #764), resurrecting the proxy during a
+    // stop or a tray restart. Kill the launcher/wrapper processes outright.
+    killWindowsServiceWrapperProcesses();
     if (stopped) return true;
   } else if (process.platform === "linux" && isSystemd() && existsSync(unitPath())) {
     try { stopSystemd(); return true; } catch { return false; }

package/src/tray/windows.ts

@@ -138,7 +138,6 @@ export function windowsTrayProcessArgs(entry: WindowsTrayEntry, mode: "Run" | "S
     "-NonInteractive",
     "-STA",
     "-ExecutionPolicy", "Bypass",
-    "-WindowStyle", "Hidden",
     "-File", safePath(entry.script),
     "-BunPath", safePath(entry.bun),
     "-BunRuntimeSource", entry.bunRuntimeSource,
@@ -173,7 +172,6 @@ export function buildWindowsTrayPowerShellCommand(entry: WindowsTrayEntry, power
     "-NonInteractive",
     "-STA",
     "-ExecutionPolicy", "Bypass",
-    "-WindowStyle", "Hidden",
     "-File", quoteRunValue(entry.script),
     "-BunPath", quoteRunValue(entry.bun),
     "-BunRuntimeSource", entry.bunRuntimeSource,

package/src/types.ts

@@ -32,11 +32,19 @@ export interface OcxParsedRequest {
   stream: boolean;
   options: OcxRequestOptions;
   _rawBody?: unknown;
-  /** Number of leading raw input items restored from local previous_response_id state. */
+  /**
+   * Boundary between replayed history and this turn's newly appended input. Usually the
+   * items the proxy restored from local previous_response_id state; also set when the
+   * CLIENT already carried that history verbatim and the proxy skipped the prepend.
+   */
   _replayPrefixLen?: number;
   /** Parsed-message index before the first conversational item in a continuation's current delta. */
   _continuationConversationMessageIndex?: number;
-  /** True when the proxy expanded a previous_response_id request into a full input replay. */
+  /**
+   * True when the full history for a previous_response_id request is present in the input —
+   * whether the proxy expanded it or the client already sent it. Consumers read this as
+   * "this request is self-contained", never as "the proxy mutated it".
+   */
   _previousResponseInputExpanded?: boolean;
   /** Provider-private stable Cursor conversation id resolved from the Responses previous_response_id chain. */
   _cursorConversationId?: string;

package/src/update/job.ts

@@ -578,7 +578,7 @@ export function spawnGuiUpdateWorker(
   ].join("; ");
   const launched = spawnSync(
     resolveTrustedWindowsPowerShellExe(),
-    ["-NoProfile", "-NoLogo", "-NonInteractive", "-WindowStyle", "Hidden", "-Command", ps],
+    ["-NoProfile", "-NoLogo", "-NonInteractive", "-Command", ps],
     { encoding: "utf8", windowsHide: true, timeout: 15_000 },
   );
   const pid = Number(String(launched.stdout ?? "").trim().split(/\r?\n/).pop());
@@ -1386,7 +1386,7 @@ function killWindowsServiceWrapperProcesses(): void {
       "} | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }",
     ].join(" ");
     spawnSync(resolveTrustedWindowsPowerShellExe(), [
-      "-NoProfile", "-NoLogo", "-NonInteractive", "-WindowStyle", "Hidden",
+      "-NoProfile", "-NoLogo", "-NonInteractive",
       "-Command", ps,
     ], { stdio: "ignore", timeout: 5000, windowsHide: true });
   } catch {

package/src/usage/summary.ts

@@ -136,9 +136,23 @@ export function parseUsageSurface(input: string | null | undefined): UsageSurfac
   return "all";
 }
 
-function rangeWindow(range: UsageRange, now: number): { since: number | null; days: number } {
-  if (range === "7d") return { since: now - 7 * DAY_MS, days: 7 };
-  if (range === "30d") return { since: now - 30 * DAY_MS, days: 30 };
+function startOfLocalDay(ts: number): number {
+  const d = new Date(ts);
+  d.setHours(0, 0, 0, 0);
+  return d.getTime();
+}
+
+export function rangeWindow(range: UsageRange, now: number): { since: number | null; days: number } {
+  if (range === "7d") {
+    const start = new Date(startOfLocalDay(now));
+    start.setDate(start.getDate() - 6);
+    return { since: start.getTime(), days: 7 };
+  }
+  if (range === "30d") {
+    const start = new Date(startOfLocalDay(now));
+    start.setDate(start.getDate() - 29);
+    return { since: start.getTime(), days: 30 };
+  }
   return { since: null, days: 0 };
 }
 
@@ -347,8 +361,11 @@ function buildDayGrid(range: UsageRange, since: number | null, now: number, entr
     m.attemptCount += 1;
     m.totalTokens += usageDisplayTotalTokens(attribution.usage, attribution.totalTokens) ?? 0;
   };
+  const startOfToday = startOfLocalDay(now);
   for (let i = days - 1; i >= 0; i--) {
-    const key = localDateKey(now - i * DAY_MS);
+    const d = new Date(startOfToday);
+    d.setDate(d.getDate() - i);
+    const key = localDateKey(d.getTime());
     grid.set(key, { date: key, requests: 0, measuredRequests: 0, reportedRequests: 0, totalTokens: 0, models: [] });
   }
   for (const entry of entries) {

package/src/vision/index.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import type { OcxConfig, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTextContent } from "../types";
 import { modelInList } from "../types";
+import { modelRecordValue } from "../reasoning-effort";
 import type { VisionReasoningEffort } from "../reasoning-effort";
 import { describeImage, type DescribeOutcome, type VisionSettings } from "./describe";
 import { describeImageAnthropic } from "./anthropic-describe";
@@ -18,6 +19,22 @@ import {
 } from "./timeout-bounds";
 
 export { describeImage } from "./describe";
+
+/**
+ * True when the model is explicitly known to be text-only — either listed in
+ * `noVisionModels` or declared with `modelInputModalities` that exclude "image".
+ * Returns false for unknown models (no evidence either way) so they fall through
+ * to native image passthrough, which is the safe default for an unclassified model.
+ */
+export function isModelTextOnly(
+  provider: OcxProviderConfig,
+  modelId: string,
+): boolean {
+  if (modelInList(provider.noVisionModels, modelId)) return true;
+  const modalities = modelRecordValue(provider.modelInputModalities, modelId);
+  if (Array.isArray(modalities) && modalities.length > 0 && !modalities.includes("image")) return true;
+  return false;
+}
 export { describeImageAnthropic, parseAnthropicVisionSSE } from "./anthropic-describe";
 export {
   BASELINE_VISION_MODELS,
@@ -245,10 +262,10 @@ function messagesHaveImage(parsed: OcxParsedRequest): boolean {
 export function shouldResolveOpenAiVisionSidecar(
   config: OcxConfig,
   provider: OcxProviderConfig,
-  modelId: string,
-  parsed: OcxParsedRequest,
+ modelId: string,
+ parsed: OcxParsedRequest,
 ): boolean {
-  if (!modelInList(provider.noVisionModels, modelId) || !messagesHaveImage(parsed)) return false;
+  if (!isModelTextOnly(provider, modelId) || !messagesHaveImage(parsed)) return false;
   const cfg = config.visionSidecar ?? {};
   if (cfg.enabled === false) return false;
   return resolveVisionBackend(cfg.backend, findAnthropicVisionProvider(config)) === "openai";
@@ -275,7 +292,7 @@ export function planVisionSidecar(
   parsed: OcxParsedRequest,
   openAiSidecar?: ResolvedOpenAiForwardSidecar,
 ): VisionPlan | undefined {
-  if (!modelInList(provider.noVisionModels, modelId)) return undefined;
+  if (!isModelTextOnly(provider, modelId)) return undefined;
   if (!messagesHaveImage(parsed)) return undefined;
   const cfg = config.visionSidecar ?? {};
   if (cfg.enabled === false) return undefined;

package/src/web-search/index.ts

@@ -1,5 +1,6 @@
 import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../types";
 import { modelInList, toolChoiceToolPredicate } from "../types";
+import { isModelTextOnly } from "../vision";
 import type { SidecarSettings } from "./executor";
 import type { ResolvedOpenAiForwardSidecar } from "../providers/openai-sidecar";
 import { getAccountSet } from "../oauth/store";
@@ -166,7 +167,7 @@ export function planWebSearch(
     timeoutMs,
   );
   // The routed model being text-only means the search model must verbalize image results (either backend).
-  const describeImages = modelInList(provider.noVisionModels, modelId);
+  const describeImages = isModelTextOnly(provider, modelId);
   const reasoning = cfg.reasoning ?? DEFAULT_SIDECAR_REASONING;
   const streamRoutedModelOutput = cfg.streamRoutedModelOutput === true;