@bitkyc08/opencodex 2.7.9-preview.20260712.1 → 2.7.9

package/src/server/system-env.ts

@@ -15,24 +15,28 @@ export function getShellEnvFilePath(): string {
   return join(getConfigDir(), "claude-env.sh");
 }
 
+function shellValue(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
 function writeShellEnvFile(port: number, config: OcxConfig, modelEnv: Record<string, string> = {}, auto?: AutoContextMode): void {
   const lines = [
     `# Generated by opencodex — do not edit manually`,
-    `export ANTHROPIC_BASE_URL="http://127.0.0.1:${port}"`,
-    `export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`,
+    `export ANTHROPIC_BASE_URL=${shellValue(`http://127.0.0.1:${port}`)}`,
+    `export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=${shellValue("1")}`,
   ];
   if (config.apiKeys?.length) {
-    lines.push(`export ANTHROPIC_AUTH_TOKEN="${config.apiKeys[0].key.replace(/"/g, '\\"')}"`);
+    lines.push(`export ANTHROPIC_AUTH_TOKEN=${shellValue(config.apiKeys[0].key)}`);
   }
   // New lever keys are CONDITIONAL exports (audit 139 R2#1): a value the user already
   // exported in their shell wins even though launchctl knows nothing about it.
   const conditional = (name: string, value: string) =>
-    `[ -z "\${${name}+x}" ] && export ${name}="${value.replace(/"/g, '\\"')}"`;
+    `[ -z "\${${name}+x}" ] && export ${name}=${shellValue(value)}`;
   // Model slots (default + tiers + legacy small-fast) with [1m] applied (devlog 260712 B2).
   if (modelEnv.ANTHROPIC_MODEL) {
-    lines.push(`export ANTHROPIC_MODEL="${modelEnv.ANTHROPIC_MODEL.replace(/"/g, '\\"')}"`);
+    lines.push(`export ANTHROPIC_MODEL=${shellValue(modelEnv.ANTHROPIC_MODEL)}`);
   } else if (config.claudeCode?.model) {
-    lines.push(`export ANTHROPIC_MODEL="${config.claudeCode.model}"`);
+    lines.push(`export ANTHROPIC_MODEL=${shellValue(config.claudeCode.model)}`);
   }
   for (const [name, value] of Object.entries(modelEnv)) {
     if (name === "ANTHROPIC_MODEL") continue;
@@ -159,6 +163,34 @@ function ownedBaseUrl(port: number): string {
   return `http://127.0.0.1:${port}`;
 }
 
+function writeTracking(port: number, injectedKeys: string[]): void {
+  mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
+  writeFileSync(getSystemEnvTrackingPath(), JSON.stringify({
+    pid: process.pid,
+    port,
+    injectedAt: new Date().toISOString(),
+    injectedKeys,
+  }), { encoding: "utf8", mode: 0o600 });
+}
+
+function rollbackInjectedKeys(port: number, injectedKeys: string[]): void {
+  const rollbackFailed: string[] = [];
+  for (const name of [...injectedKeys].reverse()) {
+    try {
+      unsetLaunchctlEnv(name);
+    } catch {
+      rollbackFailed.unshift(name);
+    }
+  }
+
+  if (rollbackFailed.length > 0) {
+    writeTracking(port, rollbackFailed);
+    return;
+  }
+
+  try { unlinkSync(getSystemEnvTrackingPath()); } catch { /* already gone */ }
+}
+
 /**
  * In-process effective model-env (default + tier slots, [1m] applied) under the shared
  * 3s bound (audit R4#3). Returns {} on timeout/failure so injection degrades safely.
@@ -192,77 +224,86 @@ export async function injectSystemEnv(port: number, config: OcxConfig): Promise<
     return { injected: false, reason: `another instance owns env (port ${existingTracking.port})` };
   }
 
-  setLaunchctlEnv("ANTHROPIC_BASE_URL", ownedBaseUrl(port));
-  setLaunchctlEnv("CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "1");
-  const injectedKeys = [
-    "ANTHROPIC_BASE_URL",
-    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY",
-  ];
-  if (config.apiKeys?.length) {
-    setLaunchctlEnv("ANTHROPIC_AUTH_TOKEN", config.apiKeys[0].key);
-    injectedKeys.push("ANTHROPIC_AUTH_TOKEN");
-  }
-  // Lever keys (devlog 136 B6): user-wins — skip any key the user already set in the
-  // launchd domain, and track ONLY the keys we actually injected so revert cannot
-  // delete a pre-existing user value (audit 139 #3).
-  const injectLever = (name: string, value: string) => {
-    if (launchctlGetenv(name) !== undefined) return;
+  const injectedKeys: string[] = existingTracking
+    ? [...(existingTracking.injectedKeys ?? SYSTEM_ENV_NAMES)]
+    : [];
+  const inject = (name: string, value: string) => {
     setLaunchctlEnv(name, value);
-    injectedKeys.push(name);
+    if (!injectedKeys.includes(name)) injectedKeys.push(name);
+    writeTracking(port, injectedKeys);
   };
-  // Model slots (default + tier defaults + legacy small-fast) with [1m] auto-marking
-  // (devlog 260712 B2, audit R2#3/R4#3): in-process context-window computation under
-  // the same 3s bound; on timeout the tier keys are simply not injected this run.
-  // Auto-context: a user-owned launchd value drives the marking predicate so the
-  // marker and threshold never separate (audit 021 #2); injectLever's user-wins
-  // check below keeps that value untouched.
-  const userAutoCompact = launchctlGetenv("CLAUDE_CODE_AUTO_COMPACT_WINDOW");
-  const auto = resolveAutoContext(config.claudeCode, userAutoCompact);
-  const { modelEnv, windows } = await computeEffectiveModelEnv(config, auto);
-  for (const [name, value] of Object.entries(modelEnv)) {
-    if (name === "ANTHROPIC_MODEL") continue; // legacy slot handled by shell file only (back-compat)
-    injectLever(name, value);
-  }
-  const maxCtx = config.claudeCode?.maxContextTokens;
-  if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) {
-    injectLever("CLAUDE_CODE_MAX_CONTEXT_TOKENS", String(Math.floor(maxCtx)));
-    injectLever("DISABLE_COMPACT", "1");
-  }
-  // Auto-context (devlog 260712 020): user-wins lever, inert when maxContextTokens set.
-  if (auto.enabled) injectLever("CLAUDE_CODE_AUTO_COMPACT_WINDOW", String(auto.compactWindow));
-  if (config.claudeCode?.alwaysEnableEffort === true) {
-    injectLever("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1");
-  }
 
-  // Shell-hook env file: works for new shells in already-running Terminal.app.
-  writeShellEnvFile(port, config, modelEnv, auto);
-
-  // Gateway-model cache pre-write (devlog 030): plain `claude` sessions read the
-  // picker list from ~/.claude/cache/gateway-models.json and cannot refresh it
-  // without a token — keep it in sync with this proxy's /v1/models. Best-effort.
   try {
-    const { refreshGatewayModelCacheFromProxy } = await import("../claude/gateway-cache");
-    await refreshGatewayModelCacheFromProxy(port);
-  } catch { /* best-effort */ }
+    inject("ANTHROPIC_BASE_URL", ownedBaseUrl(port));
+    inject("CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "1");
+    if (config.apiKeys?.length) {
+      inject("ANTHROPIC_AUTH_TOKEN", config.apiKeys[0].key);
+    }
+    // Lever keys (devlog 136 B6): user-wins — skip any key the user already set in the
+    // launchd domain, and track ONLY the keys we actually injected so revert cannot
+    // delete a pre-existing user value (audit 139 #3).
+    const injectLever = (name: string, value: string) => {
+      if (launchctlGetenv(name) !== undefined) return;
+      inject(name, value);
+    };
+    // Model slots (default + tier defaults + legacy small-fast) with [1m] auto-marking
+    // (devlog 260712 B2, audit R2#3/R4#3): in-process context-window computation under
+    // the same 3s bound; on timeout the tier keys are simply not injected this run.
+    // Auto-context: a user-owned launchd value drives the marking predicate so the
+    // marker and threshold never separate (audit 021 #2); injectLever's user-wins
+    // check below keeps that value untouched.
+    const userAutoCompact = launchctlGetenv("CLAUDE_CODE_AUTO_COMPACT_WINDOW");
+    const auto = resolveAutoContext(config.claudeCode, userAutoCompact);
+    const { modelEnv, windows } = await computeEffectiveModelEnv(config, auto);
+    for (const [name, value] of Object.entries(modelEnv)) {
+      if (name === "ANTHROPIC_MODEL") continue; // legacy slot handled by shell file only (back-compat)
+      injectLever(name, value);
+    }
+    const maxCtx = config.claudeCode?.maxContextTokens;
+    if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) {
+      injectLever("CLAUDE_CODE_MAX_CONTEXT_TOKENS", String(Math.floor(maxCtx)));
+      injectLever("DISABLE_COMPACT", "1");
+    }
+    // Auto-context (devlog 260712 020): user-wins lever, inert when maxContextTokens set.
+    if (auto.enabled) injectLever("CLAUDE_CODE_AUTO_COMPACT_WINDOW", String(auto.compactWindow));
+    if (config.claudeCode?.alwaysEnableEffort === true) {
+      injectLever("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1");
+    }
 
-  // Roster agent definitions (devlog 070): same launch-time sync for plain `claude`.
-  // Reuses the window map computed above (audit 071 #5 — no second acquisition).
-  try {
-    const { injectClaudeAgentDefs } = await import("../claude/agents-inject");
-    injectClaudeAgentDefs(config, windows);
-  } catch { /* best-effort */ }
+    // Shell-hook env file: works for new shells in already-running Terminal.app.
+    writeShellEnvFile(port, config, modelEnv, auto);
 
-  mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 });
-  writeFileSync(getSystemEnvTrackingPath(), JSON.stringify({
-    pid: process.pid,
-    port,
-    injectedAt: new Date().toISOString(),
-    injectedKeys,
-  }), { encoding: "utf8", mode: 0o600 });
+    // Gateway-model cache pre-write (devlog 030): plain `claude` sessions read the
+    // picker list from ~/.claude/cache/gateway-models.json and cannot refresh it
+    // without a token — keep it in sync with this proxy's /v1/models. Best-effort.
+    try {
+      const { refreshGatewayModelCacheFromProxy } = await import("../claude/gateway-cache");
+      await refreshGatewayModelCacheFromProxy(port);
+    } catch { /* best-effort */ }
+
+    // Roster agent definitions (devlog 070): same launch-time sync for plain `claude`.
+    // Reuses the window map computed above (audit 071 #5 — no second acquisition).
+    try {
+      const { injectClaudeAgentDefs } = await import("../claude/agents-inject");
+      injectClaudeAgentDefs(config, windows);
+    } catch { /* best-effort */ }
+
+    writeTracking(port, injectedKeys);
+  } catch (error) {
+    rollbackInjectedKeys(port, injectedKeys);
+    removeShellEnvFile();
+    console.error("Failed to inject system environment; rolled back launchctl changes:", error);
+    throw error;
+  }
 
   return { injected: true };
 }
 
+export async function applySystemEnvToggle(config: OcxConfig, port: number): Promise<SystemEnvResult | RevertResult> {
+  if (config.claudeCode?.systemEnv === true) return injectSystemEnv(port, config);
+  return revertSystemEnv();
+}
+
 export function revertSystemEnv(): RevertResult {
   if (process.platform !== "darwin") return { reverted: false, reason: "not macOS" };
 
@@ -270,7 +311,8 @@ export function revertSystemEnv(): RevertResult {
   if (!tracking) return { reverted: false, reason: "no tracking file" };
 
   try {
-    if (launchctlGetenv("ANTHROPIC_BASE_URL") !== ownedBaseUrl(tracking.port)) {
+    const tracksBaseUrl = tracking.injectedKeys?.includes("ANTHROPIC_BASE_URL") ?? true;
+    if (tracksBaseUrl && launchctlGetenv("ANTHROPIC_BASE_URL") !== ownedBaseUrl(tracking.port)) {
       return { reverted: false, reason: "ownership mismatch" };
     }
 

package/src/service.ts

@@ -16,6 +16,7 @@ import { isWslRuntime } from "./codex/home";
 import { durableBunPath, durableBunRuntime } from "./lib/bun-runtime";
 import { isProcessAlive, stopProxy } from "./lib/process-control";
 import { serviceApiTokenFilePath } from "./lib/service-secrets";
+import { hardenSecretDir, hardenSecretPath } from "./lib/windows-secret-acl";
 import { windowsEnvIndirectBatchPathList, windowsEnvIndirectBatchValue } from "./lib/win-paths";
 
 const LABEL = "com.opencodex.proxy";
@@ -103,6 +104,7 @@ function writeServiceInstallState(): void {
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
     writeFileSync(path, JSON.stringify(state, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
     try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+    if (process.platform === "win32") hardenSecretPath(path, { required: true });
   }
 }
 
@@ -169,8 +171,10 @@ function writeServiceApiTokenFile(): string | null {
   const path = serviceApiTokenFilePath();
   const dir = getConfigDir();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform === "win32") hardenSecretDir(dir, { required: true });
   writeFileSync(path, `${token}\n`, { encoding: "utf8", mode: 0o600 });
   try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+  if (process.platform === "win32") hardenSecretPath(path, { required: true });
   return path;
 }
 

package/src/types.ts

@@ -265,9 +265,9 @@ export interface OcxClaudeCodeConfig {
   /** Inbound model id remaps: exact id first, then date-stripped (`-\d{8}$`). */
   modelMap?: Record<string, string>;
   /**
-   * Inject ANTHROPIC_BASE_URL etc. into the macOS user domain via `launchctl setenv`
-   * so plain `claude` commands route through the proxy without `ocx claude`. Reverted
-   * on stop/shutdown. Default: true when `enabled` is not false. macOS only.
+  * Inject ANTHROPIC_BASE_URL etc. into the macOS user domain via `launchctl setenv`
+  * so plain `claude` commands route through the proxy without `ocx claude`. Reverted
+   * on stop/shutdown. Default: false (opt-in). macOS only.
    */
   systemEnv?: boolean;
   /**
@@ -320,6 +320,10 @@ export interface OcxClaudeCodeConfig {
    * free. Only ocx-*.md files are owned/pruned. Default: enabled.
    */
   injectAgents?: boolean;
+  /** Claude-originated web-search override. Unset fields inherit the global sidecar settings. */
+  webSearchSidecar?: { backend?: "openai" | "anthropic"; model?: string };
+  /** Claude-originated vision override. Unset fields inherit the global sidecar settings. */
+  visionSidecar?: { backend?: "openai" | "anthropic"; model?: string };
 }
 
 export interface OcxConfig {
@@ -485,10 +489,14 @@ export interface OcxSearchConfig {
 }
 
 export interface OcxVisionSidecarConfig {
-  /** Master switch. Default: enabled when a forward (ChatGPT) provider exists and the caller is logged in. */
+  /** Master switch. Default: enabled when the selected backend has a usable credential. */
   enabled?: boolean;
-  /** Vision model that describes images (must be a native ChatGPT model with image input). */
+  /** Description backend. Unset prefers a usable stored Anthropic OAuth credential, else OpenAI. */
+  backend?: "openai" | "anthropic";
+  /** Vision model that describes images. */
   model?: string;
+  /** Max description cache misses admitted in one main-model turn. Zero disables description calls. */
+  maxDescriptionsPerTurn?: number;
   /** Sidecar fetch timeout (ms). */
   timeoutMs?: number;
 }
@@ -496,6 +504,13 @@ export interface OcxVisionSidecarConfig {
 export interface OcxWebSearchSidecarConfig {
   /** Master switch. Default: enabled when a forward (ChatGPT) provider exists and the caller is logged in. */
   enabled?: boolean;
+  /**
+   * Which backend actually runs the server-side search. "openai" replays the hosted web_search via
+   * the ChatGPT forward provider (gpt-mini sidecar); "anthropic" runs web_search_20250305 on a Claude
+   * model authenticated by the STORED anthropic OAuth credential. Unset resolves to "anthropic" when a
+   * usable anthropic OAuth credential exists, else "openai".
+   */
+  backend?: "openai" | "anthropic";
   /** Sidecar model that runs the real server-side web_search (must be a native ChatGPT model). */
   model?: string;
   /** Reasoning effort for the sidecar — "minimal" (non-thinking) keeps it fast/cheap. */
@@ -514,6 +529,11 @@ export interface OcxWebSearchSidecarConfig {
 export interface OcxProviderConfig {
   adapter: string;
   baseUrl: string;
+  /**
+   * Explicit opt-in for non-registry private-network destinations such as localhost, RFC1918,
+   * link-local, or unique-local upstreams. Metadata endpoints remain blocked.
+   */
+  allowPrivateNetwork?: boolean;
   /** Keep provider settings on disk but exclude it from routing and model/catalog listings. */
   disabled?: boolean;
   apiKey?: string;

package/src/vision/anthropic-describe.ts

@@ -0,0 +1,185 @@
+import type { OcxProviderConfig } from "../types";
+import { CLAUDE_CODE_HEADERS, claudeCodeSessionId } from "../adapters/client-fingerprint";
+import { signalWithTimeout, cancelBodyOnAbort } from "../lib/abort";
+import { sidecarEnter } from "../lib/sidecar-tracker";
+import { fetchWithResetRetry } from "../lib/upstream-retry";
+import { getValidAccessToken } from "../oauth";
+import { ANTHROPIC_OAUTH_BETA, CLAUDE_CODE_SYSTEM_INSTRUCTION } from "../oauth/anthropic";
+import type { DescribeOutcome, VisionSettings } from "./describe";
+
+const ANTHROPIC_VISION_MAX_TOKENS = 1024;
+const ALLOWED_IMAGE_MIME = new Set(["image/png", "image/jpeg", "image/jpg", "image/webp", "image/gif"]);
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+const DESCRIBE_INSTRUCTION =
+  "You are a vision describer for a text-only model that cannot see the image. Describe the image " +
+  "thoroughly and factually so that model can fully reason about it: transcribe any visible text " +
+  "verbatim, and note UI/layout, colors, branding/logos, charts, and notable details. Focus on " +
+  "what's relevant to the user's request. Output only the description.";
+
+type AnthropicImageBlock =
+  | { type: "image"; source: { type: "base64"; media_type: string; data: string } }
+  | { type: "image"; source: { type: "url"; url: string } };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function buildImageBlock(imageUrl: string): { block?: AnthropicImageBlock; error?: string } {
+  if (imageUrl.startsWith("data:")) {
+    // Anthropic's base64 image source requires actual base64 bytes, so a non-base64 data URL
+    // (e.g. `data:image/png,raw`) is rejected here. This is intentionally stricter than the OpenAI
+    // vision executor, which forwards the raw data URL to `image_url` (review F3, documented delta).
+    const match = /^data:([^;,]+?)(;base64)?,(.*)$/s.exec(imageUrl);
+    if (!match || !match[2]) return { error: "malformed data URL" };
+    const mime = match[1].toLowerCase();
+    if (!ALLOWED_IMAGE_MIME.has(mime)) return { error: `unsupported image type "${mime}"` };
+    const bytes = Math.floor((match[3].length * 3) / 4);
+    if (bytes > MAX_IMAGE_BYTES) return { error: `image too large (~${Math.round(bytes / 1024 / 1024)}MB)` };
+    return { block: { type: "image", source: { type: "base64", media_type: mime, data: match[3] } } };
+  }
+  if (imageUrl.startsWith("https://")) {
+    return { block: { type: "image", source: { type: "url", url: imageUrl } } };
+  }
+  return { error: "unsupported image URL scheme (expected data: or https:)" };
+}
+
+/** Fold Anthropic Messages text deltas into one description. Malformed frames are ignored. */
+export async function parseAnthropicVisionSSE(res: Response): Promise<DescribeOutcome> {
+  if (!res.body) return { text: "", error: "anthropic vision sidecar returned no response body" };
+
+  let text = "";
+  let terminalError = "";
+  const decoder = new TextDecoder();
+  const reader = res.body.getReader();
+  let buffer = "";
+
+  const processFrame = (rawFrame: string): void => {
+    let dataLine = "";
+    for (const line of rawFrame.split("\n")) {
+      if (line.startsWith("data:")) dataLine += line.slice(line.startsWith("data: ") ? 6 : 5);
+    }
+    if (!dataLine || dataLine === "[DONE]") return;
+    let data: unknown;
+    try { data = JSON.parse(dataLine); } catch { return; }
+    if (!isRecord(data)) return;
+
+    if (data.type === "content_block_delta") {
+      const delta = isRecord(data.delta) ? data.delta : {};
+      if (delta.type === "text_delta" && typeof delta.text === "string") text += delta.text;
+    } else if (data.type === "error") {
+      const error = isRecord(data.error) ? data.error : {};
+      terminalError = typeof error.message === "string" ? error.message : "anthropic vision sidecar stream error";
+    }
+  };
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer = (buffer + decoder.decode(value, { stream: true })).replace(/\r\n/g, "\n");
+      let separator: number;
+      while ((separator = buffer.indexOf("\n\n")) !== -1) {
+        processFrame(buffer.slice(0, separator));
+        buffer = buffer.slice(separator + 2);
+      }
+    }
+    buffer = (buffer + decoder.decode()).replace(/\r\n/g, "\n");
+    if (buffer.trim()) processFrame(buffer);
+  } catch {
+    // A mid-stream read/decode failure after partial text is NOT a usable description. Mark it
+    // terminal so the caller returns an error and never caches an incomplete result (review F1).
+    if (!terminalError) terminalError = "anthropic vision sidecar stream ended abnormally";
+  }
+
+  const trimmed = text.trim();
+  // A terminal error (an in-stream `error` frame OR an abnormal body failure) invalidates any partial
+  // text: return an error outcome so vision/index.ts never caches an incomplete description (review F1).
+  if (terminalError) return { text: "", error: terminalError };
+  if (!trimmed) return { text: "", error: "anthropic vision sidecar produced no description" };
+  return { text: trimmed };
+}
+
+/** Describe one image through a stored Anthropic OAuth credential. Never throws. */
+export async function describeImageAnthropic(
+  imageUrl: string,
+  detail: string | undefined,
+  contextText: string,
+  providerName: string,
+  provider: OcxProviderConfig,
+  settings: VisionSettings,
+  abortSignal?: AbortSignal,
+): Promise<DescribeOutcome> {
+  const image = buildImageBlock(imageUrl);
+  if (!image.block) return { text: "", error: image.error ?? "invalid image" };
+
+  let token: string;
+  try {
+    token = await getValidAccessToken(providerName);
+  } catch (error) {
+    return { text: "", error: `anthropic vision sidecar auth failed: ${error instanceof Error ? error.message : String(error)}` };
+  }
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "anthropic-version": "2023-06-01",
+    "Accept": "text/event-stream",
+    "User-Agent": "@anthropic-ai/sdk/0.74.0",
+    "Authorization": `Bearer ${token}`,
+    "anthropic-beta": ANTHROPIC_OAUTH_BETA,
+    ...CLAUDE_CODE_HEADERS,
+    "X-Claude-Code-Session-Id": claudeCodeSessionId(token),
+    "x-client-request-id": crypto.randomUUID(),
+  };
+  if (provider.headers) Object.assign(headers, provider.headers);
+
+  const content: unknown[] = [];
+  if (contextText) content.push({ type: "text", text: `The user's request about this image: ${contextText}` });
+  content.push(image.block);
+  const body = {
+    model: settings.model,
+    max_tokens: ANTHROPIC_VISION_MAX_TOKENS,
+    thinking: { type: "disabled" },
+    system: [
+      { type: "text", text: CLAUDE_CODE_SYSTEM_INSTRUCTION },
+      { type: "text", text: DESCRIBE_INSTRUCTION },
+    ],
+    messages: [{ role: "user", content }],
+    stream: true,
+  };
+
+  // Anthropic image blocks have no detail field, but detail remains part of the cache identity.
+  void detail;
+  const base = provider.baseUrl.replace(/\/v1\/?$/, "");
+  const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
+  const sidecarExit = sidecarEnter("vision");
+  const startedAt = Date.now();
+  try {
+    const res = await fetchWithResetRetry(
+      () => fetch(`${base}/v1/messages`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: linkedSignal.signal,
+      }),
+      { abortSignal: linkedSignal.signal, label: "vision-sidecar-anthropic" },
+    );
+    if (!res.ok) {
+      const responseText = await res.text().catch(() => "");
+      console.warn(`[vision] anthropic sidecar HTTP ${res.status} (${Date.now() - startedAt}ms)`);
+      return { text: "", error: `anthropic vision sidecar HTTP ${res.status}: ${responseText.slice(0, 200)}` };
+    }
+    const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
+    try {
+      return await parseAnthropicVisionSSE(res);
+    } finally {
+      detachBodyGuard();
+    }
+  } catch (error) {
+    const kind = error instanceof Error && error.name === "TimeoutError" ? "timeout" : "connect_error";
+    console.warn(`[vision] anthropic sidecar ${kind} (${Date.now() - startedAt}ms)`);
+    return { text: "", error: error instanceof Error ? error.message : String(error) };
+  } finally {
+    sidecarExit();
+    linkedSignal.cleanup();
+  }
+}