@bitkyc08/opencodex 2.7.9-preview.20260712.1 → 2.7.9

package/src/vision/index.ts

@@ -1,13 +1,20 @@
+import { createHash } from "node:crypto";
 import type { OcxConfig, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTextContent } from "../types";
 import { modelInList } from "../types";
-import { describeImage, type VisionSettings } from "./describe";
+import { describeImage, type DescribeOutcome, type VisionSettings } from "./describe";
+import { describeImageAnthropic } from "./anthropic-describe";
 import type { CodexAuthContext } from "../codex/auth-context";
+import { getAccountSet } from "../oauth/store";
 import type { SidecarOutcomeRecorder } from "../web-search/executor";
 
 export { describeImage } from "./describe";
+export { describeImageAnthropic, parseAnthropicVisionSSE } from "./anthropic-describe";
 
 const DEFAULT_VISION_MODEL = "gpt-5.4-mini";
+const DEFAULT_ANTHROPIC_VISION_MODEL = "claude-sonnet-5";
 const DEFAULT_TIMEOUT_MS = 45_000;
+const DEFAULT_MAX_DESCRIPTIONS_PER_TURN = 8;
+const DESCRIPTION_CACHE_MAX_ENTRIES = 256;
 /** Max images described in parallel — keeps first-token latency bounded without flooding the backend. */
 const VISION_CONCURRENCY = 3;
 /** Per-image description hard cap (chars) so multi-image turns can't blow the main model's context. */
@@ -15,6 +22,59 @@ const DESC_MAX_CHARS = 2000;
 /** User-text context passed to the describer, capped. */
 const CONTEXT_MAX_CHARS = 800;
 
+export interface VisionDescriptionCache {
+  get(key: string): string | undefined;
+  set(key: string, value: string): void;
+  clear(): void;
+}
+
+class BoundedLruDescriptionCache implements VisionDescriptionCache {
+  private readonly entries = new Map<string, string>();
+
+  constructor(private readonly maxEntries: number) {}
+
+  get(key: string): string | undefined {
+    const value = this.entries.get(key);
+    if (value === undefined) return undefined;
+    this.entries.delete(key);
+    this.entries.set(key, value);
+    return value;
+  }
+
+  set(key: string, value: string): void {
+    this.entries.delete(key);
+    this.entries.set(key, value);
+    while (this.entries.size > this.maxEntries) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest === undefined) break;
+      this.entries.delete(oldest);
+    }
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+}
+
+let descriptionCache: VisionDescriptionCache = new BoundedLruDescriptionCache(DESCRIPTION_CACHE_MAX_ENTRIES);
+
+/** Replace the process cache (primarily for deterministic tests). Passing undefined restores the default LRU. */
+export function setVisionDescriptionCache(cache?: VisionDescriptionCache): void {
+  descriptionCache = cache ?? new BoundedLruDescriptionCache(DESCRIPTION_CACHE_MAX_ENTRIES);
+}
+
+export function resetVisionDescriptionCache(): void {
+  descriptionCache.clear();
+}
+
+/** Runtime config is permissive: zero is intentional; malformed values fall back to the bounded default. */
+export function resolveMaxDescriptionsPerTurn(value: unknown): number {
+  if (value === 0) return 0;
+  return typeof value === "number" && Number.isInteger(value) && value > 0
+    ? value
+    : DEFAULT_MAX_DESCRIPTIONS_PER_TURN;
+}
+
 /** 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);
@@ -33,7 +93,7 @@ function clamp(s: string, max: number): string {
   return s.length <= max ? s : `${s.slice(0, max)}\n…[description truncated]`;
 }
 
-/** First configured forward (ChatGPT passthrough) provider — the path with native image input. */
+/** First configured forward (ChatGPT passthrough) provider — the OpenAI path with native image input. */
 function findForwardProvider(config: OcxConfig): OcxProviderConfig | undefined {
   for (const prov of Object.values(config.providers)) {
     if (prov.disabled === true) continue;
@@ -42,6 +102,30 @@ function findForwardProvider(config: OcxConfig): OcxProviderConfig | undefined {
   return undefined;
 }
 
+export interface AnthropicVisionProvider {
+  providerName: string;
+  provider: OcxProviderConfig;
+}
+
+/** First enabled Anthropic OAuth provider whose active stored account is not marked for reauth. */
+export function findAnthropicVisionProvider(config: OcxConfig): AnthropicVisionProvider | undefined {
+  for (const [providerName, provider] of Object.entries(config.providers)) {
+    if (provider.disabled === true || provider.adapter !== "anthropic" || provider.authMode !== "oauth") continue;
+    const accountSet = getAccountSet(providerName);
+    const active = accountSet?.accounts.find(account => account.id === accountSet.activeAccountId);
+    if (active && active.needsReauth !== true) return { providerName, provider };
+  }
+  return undefined;
+}
+
+export function resolveVisionBackend(
+  explicit: "openai" | "anthropic" | undefined,
+  anthropicSidecar: AnthropicVisionProvider | undefined,
+): "openai" | "anthropic" {
+  if (explicit === "openai" || explicit === "anthropic") return explicit;
+  return anthropicSidecar ? "anthropic" : "openai";
+}
+
 /** A user/developer/toolResult message can carry images (toolResult: e.g. Codex view_image output). */
 function carriesImages(role: string): boolean {
   return role === "user" || role === "developer" || role === "toolResult";
@@ -53,15 +137,18 @@ function messagesHaveImage(parsed: OcxParsedRequest): boolean {
 }
 
 export interface VisionPlan {
-  forwardProvider: OcxProviderConfig;
+  backend: "openai" | "anthropic";
+  forwardProvider?: OcxProviderConfig;
+  anthropicSidecar?: AnthropicVisionProvider;
   settings: VisionSettings;
+  maxDescriptionsPerTurn: number;
 }
 
 /**
  * Decide whether the vision sidecar should pre-describe images for this request, returning the plan
  * if so. Active when: the routed model is in `provider.noVisionModels`, the request actually carries
- * an image, a forward provider exists, the sidecar isn't disabled, and the caller forwarded ChatGPT
- * auth. Returns undefined otherwise (the request takes the normal path — images sent natively).
+ * an image, the sidecar isn't disabled, and the selected backend has usable auth. Returns undefined
+ * otherwise (the caller strips images before sending to a text-only model).
  */
 export function planVisionSidecar(
   config: OcxConfig,
@@ -75,12 +162,28 @@ export function planVisionSidecar(
   if (!messagesHaveImage(parsed)) return undefined;
   const cfg = config.visionSidecar ?? {};
   if (cfg.enabled === false) return undefined;
+  const anthropicSidecar = findAnthropicVisionProvider(config);
+  const backend = resolveVisionBackend(cfg.backend, anthropicSidecar);
+  const maxDescriptionsPerTurn = resolveMaxDescriptionsPerTurn(cfg.maxDescriptionsPerTurn);
+
+  if (backend === "anthropic") {
+    if (!anthropicSidecar) return undefined;
+    return {
+      backend,
+      anthropicSidecar,
+      settings: { model: cfg.model ?? DEFAULT_ANTHROPIC_VISION_MODEL, timeoutMs: cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS },
+      maxDescriptionsPerTurn,
+    };
+  }
+
   if (authContext.kind === "main" && !incomingHeaders.get("authorization")) return undefined;
   const forwardProvider = findForwardProvider(config);
   if (!forwardProvider) return undefined;
   return {
+    backend,
     forwardProvider,
     settings: { model: cfg.model ?? DEFAULT_VISION_MODEL, timeoutMs: cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS },
+    maxDescriptionsPerTurn,
   };
 }
 
@@ -100,6 +203,69 @@ function renderDescription(out: { text: string; error?: string }): OcxTextConten
   };
 }
 
+function sha256(value: string | Uint8Array): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function normalizedContext(contextText: string): string {
+  return contextText.trim().replace(/\s+/g, " ");
+}
+
+function descriptionIdentity(job: ImageJob, plan: VisionPlan): { key: string; persistent: boolean } {
+  let imageHash: string;
+  let persistent = false;
+  const data = /^data:[^;,]+;base64,(.*)$/s.exec(job.imageUrl);
+  if (data) {
+    imageHash = sha256(Buffer.from(data[1], "base64"));
+    persistent = true;
+  } else {
+    imageHash = sha256(job.imageUrl);
+  }
+  return {
+    key: JSON.stringify([
+      plan.backend,
+      plan.settings.model,
+      job.detail ?? "high",
+      imageHash,
+      sha256(normalizedContext(job.contextText)),
+    ]),
+    persistent,
+  };
+}
+
+async function executeDescription(
+  job: ImageJob,
+  plan: VisionPlan,
+  selectedForwardHeaders: Headers,
+  abortSignal?: AbortSignal,
+  recordSidecarOutcome?: SidecarOutcomeRecorder,
+): Promise<DescribeOutcome> {
+  if (plan.backend === "anthropic") {
+    const sidecar = plan.anthropicSidecar;
+    if (!sidecar) return { text: "", error: "anthropic vision sidecar is unavailable" };
+    return describeImageAnthropic(
+      job.imageUrl,
+      job.detail,
+      job.contextText,
+      sidecar.providerName,
+      sidecar.provider,
+      plan.settings,
+      abortSignal,
+    );
+  }
+  if (!plan.forwardProvider) return { text: "", error: "OpenAI vision sidecar is unavailable" };
+  return describeImage(
+    job.imageUrl,
+    job.detail,
+    job.contextText,
+    plan.forwardProvider,
+    selectedForwardHeaders,
+    plan.settings,
+    abortSignal,
+    recordSidecarOutcome,
+  );
+}
+
 /**
  * Replace every image part in the request with a gpt-described text part, so a text-only model can
  * reason about it. Mutates `parsed.context.messages` in place; uses the message's own text as the
@@ -108,9 +274,8 @@ function renderDescription(out: { text: string; error?: string }): OcxTextConten
  */
 export async function describeImagesInPlace(
   parsed: OcxParsedRequest,
-  forwardProvider: OcxProviderConfig,
+  plan: VisionPlan,
   selectedForwardHeaders: Headers,
-  settings: VisionSettings,
   abortSignal?: AbortSignal,
   recordSidecarOutcome?: SidecarOutcomeRecorder,
 ): Promise<void> {
@@ -133,9 +298,53 @@ export async function describeImagesInPlace(
   }
   if (jobs.length === 0) return;
 
-  // 2. Describe all images with bounded concurrency (order preserved).
-  const outcomes = await runBounded(jobs, VISION_CONCURRENCY, j =>
-    describeImage(j.imageUrl, j.detail, j.contextText, forwardProvider, selectedForwardHeaders, settings, abortSignal, recordSidecarOutcome));
+  // 2. Admit misses in source order. Cache hits and same-turn waiters do not consume the cap.
+  const inFlight = new Map<string, Promise<DescribeOutcome>>();
+  const executions: Array<() => Promise<void>> = [];
+  const outcomePromises: Array<Promise<DescribeOutcome>> = [];
+  let misses = 0;
+
+  for (const job of jobs) {
+    const identity = descriptionIdentity(job, plan);
+    const cached = identity.persistent ? descriptionCache.get(identity.key) : undefined;
+    if (cached !== undefined) {
+      outcomePromises.push(Promise.resolve({ text: cached }));
+      continue;
+    }
+
+    const existing = inFlight.get(identity.key);
+    if (existing) {
+      outcomePromises.push(existing);
+      continue;
+    }
+
+    if (misses >= plan.maxDescriptionsPerTurn) {
+      const capped = Promise.resolve<DescribeOutcome>({ text: "", error: "description cap reached for this turn" });
+      inFlight.set(identity.key, capped);
+      outcomePromises.push(capped);
+      continue;
+    }
+
+    misses += 1;
+    let resolveOutcome!: (outcome: DescribeOutcome) => void;
+    const pending = new Promise<DescribeOutcome>(resolve => { resolveOutcome = resolve; });
+    inFlight.set(identity.key, pending);
+    outcomePromises.push(pending);
+    executions.push(async () => {
+      let outcome: DescribeOutcome;
+      try {
+        outcome = await executeDescription(job, plan, selectedForwardHeaders, abortSignal, recordSidecarOutcome);
+      } catch (error) {
+        outcome = { text: "", error: error instanceof Error ? error.message : String(error) };
+      }
+      const successfulText = outcome.error ? "" : outcome.text.trim();
+      if (identity.persistent && successfulText) descriptionCache.set(identity.key, successfulText);
+      resolveOutcome(outcome);
+    });
+  }
+
+  await runBounded(executions, VISION_CONCURRENCY, execute => execute());
+  const outcomes = await Promise.all(outcomePromises);
 
   // 3. Rebuild each message, replacing image parts with their descriptions in order.
   let oi = 0;

package/src/web-search/anthropic-executor.ts

@@ -0,0 +1,187 @@
+import type { OcxProviderConfig } from "../types";
+import { getValidAccessToken } from "../oauth";
+import { ANTHROPIC_OAUTH_BETA, CLAUDE_CODE_SYSTEM_INSTRUCTION } from "../oauth/anthropic";
+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 type { WebSearchSource } from "./parse";
+import { BASE_INSTRUCTION, IMAGE_INSTRUCTION, type SidecarOutcome, type SidecarSettings } from "./executor";
+
+/** Hardcoded per-turn search bound handed to the server tool (mirrors the loop's maxSearches intent). */
+const ANTHROPIC_MAX_USES = 3;
+/** Answer budget; the injected tool_result is clamped downstream, so this only bounds the sidecar turn. */
+const ANTHROPIC_MAX_TOKENS = 8192;
+
+function isRec(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+/**
+ * Fold an Anthropic Messages SSE stream (a web_search_20250305 turn) into a WebSearchResult.
+ *
+ * Anthropic streams the FULL `web_search_tool_result.content` array on `content_block_start` (not via
+ * deltas), so sources are collected there; the answer text arrives as `text_delta` events, and
+ * `citations_delta` (web_search_result_location) contributes any additional cited URLs. A
+ * `web_search_tool_result_error` content object yields no sources. Never throws.
+ */
+export async function parseAnthropicSidecarSSE(res: Response): Promise<SidecarOutcome> {
+  const sources: WebSearchSource[] = [];
+  const seen = new Set<string>();
+  const pushSource = (url: unknown, title: unknown): void => {
+    if (typeof url !== "string" || url.length === 0 || seen.has(url)) return;
+    seen.add(url);
+    sources.push(typeof title === "string" && title.length > 0 ? { url, title } : { url });
+  };
+
+  let text = "";
+  let sawToolResultError = false;
+  if (!res.body) return { text: "", sources, error: "anthropic sidecar returned no response body" };
+
+  const decoder = new TextDecoder();
+  const reader = res.body.getReader();
+  let buffer = "";
+
+  const handleFrame = (data: Record<string, unknown>): void => {
+    const type = typeof data.type === "string" ? data.type : "";
+    if (type === "content_block_start") {
+      const block = isRec(data.content_block) ? data.content_block : {};
+      if (block.type === "web_search_tool_result") {
+        if (Array.isArray(block.content)) {
+          for (const hit of block.content) {
+            if (isRec(hit) && hit.type === "web_search_result") pushSource(hit.url, hit.title);
+          }
+        } else if (isRec(block.content) && block.content.type === "web_search_tool_result_error") {
+          sawToolResultError = true;
+        }
+      }
+    } else if (type === "content_block_delta") {
+      const delta = isRec(data.delta) ? data.delta : {};
+      if (delta.type === "text_delta" && typeof delta.text === "string") {
+        text += delta.text;
+      } else if (delta.type === "citations_delta") {
+        const citation = isRec(delta.citation) ? delta.citation : {};
+        if (citation.type === "web_search_result_location") pushSource(citation.url, citation.title);
+      }
+    }
+  };
+
+  // Parse one SSE frame's `data:` payload and fold it. Shared by the streaming loop and the EOF flush.
+  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 (isRec(data)) handleFrame(data);
+  };
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      // Normalize CRLF on the ACCUMULATED buffer so a `\r\n` pair split across two network chunks
+      // (chunk ends in `\r`, next starts with `\n`) still collapses to `\n` (audit round-2 F2).
+      buffer = (buffer + decoder.decode(value, { stream: true })).replace(/\r\n/g, "\n");
+      let sep: number;
+      while ((sep = buffer.indexOf("\n\n")) !== -1) {
+        const rawFrame = buffer.slice(0, sep);
+        buffer = buffer.slice(sep + 2);
+        processFrame(rawFrame);
+      }
+    }
+    // Flush the decoder and process any final unterminated frame (a stream that ends without \n\n).
+    buffer = (buffer + decoder.decode()).replace(/\r\n/g, "\n");
+    if (buffer.trim().length > 0) processFrame(buffer);
+  } catch {
+    /* mid-stream abort/decode failure: fall through with whatever text/sources were gathered */
+  }
+
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return { text: "", sources, error: sawToolResultError ? "anthropic web search returned an error result" : "anthropic sidecar produced no answer" };
+  }
+  return { text: trimmed, sources };
+}
+
+/**
+ * Execute ONE web search via a Claude sidecar through the STORED anthropic OAuth credential — the
+ * Anthropic-backed analog of runWebSearch. Authenticates with getValidAccessToken (refresh handled)
+ * and reproduces the Claude Code OAuth fingerprint (identity system block first, oauth beta, client
+ * headers, stable session id) so the request is first-party-shaped. Never throws — returns `{error}`
+ * so the caller injects a graceful tool result.
+ */
+export async function runAnthropicWebSearch(
+  query: string,
+  providerName: string,
+  provider: OcxProviderConfig,
+  settings: SidecarSettings,
+  abortSignal?: AbortSignal,
+): Promise<SidecarOutcome> {
+  const base = provider.baseUrl.replace(/\/v1\/?$/, "");
+  const url = `${base}/v1/messages`;
+  let token: string;
+  try {
+    token = await getValidAccessToken(providerName);
+  } catch (e) {
+    return { text: "", sources: [], error: `anthropic sidecar auth failed: ${e instanceof Error ? e.message : String(e)}` };
+  }
+  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 instruction = settings.describeImages ? BASE_INSTRUCTION + IMAGE_INSTRUCTION : BASE_INSTRUCTION;
+  const body = {
+    model: settings.model,
+    max_tokens: ANTHROPIC_MAX_TOKENS,
+    // sonnet-5 defaults to adaptive thinking when omitted; keep the sidecar fast/cheap (audit F2).
+    thinking: { type: "disabled" },
+    // OAuth fingerprint requires the Claude Code identity as the FIRST system block (audit F6/anthropic.ts).
+    system: [
+      { type: "text", text: CLAUDE_CODE_SYSTEM_INSTRUCTION },
+      { type: "text", text: instruction },
+    ],
+    messages: [{ role: "user", content: [{ type: "text", text: query }] }],
+    tools: [{ type: "web_search_20250305", name: "web_search", max_uses: ANTHROPIC_MAX_USES }],
+    stream: true,
+  };
+
+  const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
+  const sidecarExit = sidecarEnter("web-search");
+  const t0 = Date.now();
+  try {
+    const res = await fetchWithResetRetry(
+      () => fetch(url, { method: "POST", headers, body: JSON.stringify(body), signal: linkedSignal.signal }),
+      { abortSignal: linkedSignal.signal, label: "web-search-sidecar-anthropic" },
+    );
+    if (!res.ok) {
+      const t = await res.text().catch(() => "");
+      console.warn(`[web-search] anthropic sidecar HTTP ${res.status} for query "${query.slice(0, 80)}" (${Date.now() - t0}ms)`);
+      return { text: "", sources: [], error: `sidecar HTTP ${res.status}: ${t.slice(0, 200)}` };
+    }
+    const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
+    try {
+      return await parseAnthropicSidecarSSE(res);
+    } finally {
+      detachBodyGuard();
+    }
+  } catch (e) {
+    const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
+    console.warn(`[web-search] anthropic sidecar ${kind} for query "${query.slice(0, 80)}" (${Date.now() - t0}ms)`);
+    return { text: "", sources: [], error: e instanceof Error ? e.message : String(e) };
+  } finally {
+    sidecarExit();
+    linkedSignal.cleanup();
+  }
+}

package/src/web-search/executor.ts

@@ -18,11 +18,13 @@ export interface SidecarSettings {
   describeImages?: boolean;
 }
 
-const BASE_INSTRUCTION =
+// Shared with the anthropic-backed executor (single source; audit F3). The instruction is
+// backend-agnostic — both the gpt-mini sidecar and a Claude sidecar answer the same way.
+export const BASE_INSTRUCTION =
   "You are a web-search assistant. Use the web_search tool to find current information for the " +
   "user's query, then reply with a concise, factual answer. End your reply with a `Sources:` " +
   "section listing each source you used on its own line as `- Title: URL` (one per line).";
-const IMAGE_INSTRUCTION =
+export const IMAGE_INSTRUCTION =
   " The model that will read your answer is TEXT-ONLY and cannot see images: if the results include " +
   "relevant images, describe what they show in words and include their source URLs in your answer.";
 

package/src/web-search/index.ts

@@ -2,11 +2,15 @@ import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../types";
 import { modelInList } from "../types";
 import type { SidecarSettings } from "./executor";
 import type { CodexAuthContext } from "../codex/auth-context";
+import { getAccountSet } from "../oauth/store";
 
 export { runWithWebSearch } from "./loop";
 export { buildWebSearchTool, extractHostedWebSearch, WEB_SEARCH_TOOL_NAME } from "./synthetic-tool";
+export { runAnthropicWebSearch, parseAnthropicSidecarSSE } from "./anthropic-executor";
 
 const DEFAULT_SIDECAR_MODEL = "gpt-5.6-luna";
+// Default Claude model for the anthropic-backed sidecar (used when cfg.model is unset).
+const DEFAULT_ANTHROPIC_SIDECAR_MODEL = "claude-sonnet-5";
 // "low" is the lightest effort the ChatGPT backend allows with web_search ("minimal" is rejected:
 // "tools cannot be used with reasoning.effort 'minimal'") — keeps the sidecar fast/cheap.
 const DEFAULT_SIDECAR_REASONING = "low";
@@ -70,8 +74,45 @@ export function findForwardProvider(config: OcxConfig): OcxProviderConfig | unde
   return undefined;
 }
 
+/** A configured anthropic-adapter OAuth provider whose ACTIVE stored account is usable (not needs-reauth). */
+export interface AnthropicSidecarProvider {
+  providerName: string;
+  provider: OcxProviderConfig;
+}
+
+/**
+ * First enabled anthropic-adapter OAuth provider whose ACTIVE account holds a usable credential — the
+ * only path that can run web_search_20250305 without a ChatGPT forward provider. Presence is decided by
+ * getAccountSet + the active account's `needsReauth` marker (audit F1: getCredential alone can pick a
+ * terminally-invalid account); token refresh happens later at executor time.
+ */
+export function findAnthropicSidecarProvider(config: OcxConfig): AnthropicSidecarProvider | undefined {
+  for (const [name, prov] of Object.entries(config.providers)) {
+    if (prov.disabled === true) continue;
+    if (prov.adapter !== "anthropic" || prov.authMode !== "oauth") continue;
+    const set = getAccountSet(name);
+    const active = set?.accounts.find(a => a.id === set.activeAccountId);
+    if (active && active.needsReauth !== true) return { providerName: name, provider: prov };
+  }
+  return undefined;
+}
+
+/** Precedence (audit F4/F7): explicit config wins; unset resolves to anthropic when a usable credential exists, else openai. */
+export function resolveSidecarBackend(
+  explicit: "openai" | "anthropic" | undefined,
+  anthropicSidecar: AnthropicSidecarProvider | undefined,
+): "openai" | "anthropic" {
+  if (explicit === "anthropic" || explicit === "openai") return explicit;
+  return anthropicSidecar ? "anthropic" : "openai";
+}
+
 export interface SidecarPlan {
-  forwardProvider: OcxProviderConfig;
+  /** Which executor runs the search. Anthropic does not require a forward provider. */
+  backend: "openai" | "anthropic";
+  /** Present for the openai backend (ChatGPT forward path); undefined for anthropic. */
+  forwardProvider?: OcxProviderConfig;
+  /** Present for the anthropic backend (stored-OAuth /v1/messages path); undefined for openai. */
+  anthropicSidecar?: AnthropicSidecarProvider;
   hostedTool: Record<string, unknown>;
   settings: SidecarSettings;
   maxSearches: number;
@@ -99,30 +140,51 @@ export function planWebSearch(
   if (!parsed._webSearch || isPassthrough) return undefined;
   const cfg = config.webSearchSidecar ?? {};
   if (cfg.enabled === false) return undefined;
-  if (authContext.kind === "main" && !incomingHeaders.get("authorization")) return undefined; // not logged into ChatGPT → sidecar can't run
-  const forwardProvider = findForwardProvider(config);
-  if (!forwardProvider) return undefined;
   const timeoutMs = cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const routedModelStallTimeoutMs = resolveRoutedModelStallTimeoutMs(cfg.routedModelStallTimeoutMs);
   // Same `?? 200_000` default the server applies when threading connectTimeoutMs into the loop.
   const connectTimeoutMs = config.connectTimeoutMs ?? 200_000;
+  const anthropicSidecar = findAnthropicSidecarProvider(config);
+  const backend = resolveSidecarBackend(cfg.backend, anthropicSidecar);
+  const maxSearches = cfg.maxSearchesPerTurn ?? DEFAULT_MAX_SEARCHES;
+  const stallTimeoutSec = webSearchStallTimeoutSec(
+    config.stallTimeoutSec,
+    connectTimeoutMs,
+    routedModelStallTimeoutMs,
+    timeoutMs,
+  );
+  // The routed model being text-only means the search model must verbalize image results (either backend).
+  const describeImages = modelInList(provider.noVisionModels, modelId);
+  const reasoning = cfg.reasoning ?? DEFAULT_SIDECAR_REASONING;
+
+  // Anthropic backend authenticates with the STORED credential — no forward provider or ChatGPT login gate.
+  // resolveSidecarBackend only returns "anthropic" when it was explicitly configured OR a usable credential
+  // exists; an EXPLICIT anthropic choice with no usable credential FAILS CLOSED (no plan) rather than
+  // silently borrowing ChatGPT credentials (audit round-2 F1).
+  if (backend === "anthropic") {
+    if (!anthropicSidecar) return undefined;
+    return {
+      backend: "anthropic",
+      anthropicSidecar,
+      hostedTool: parsed._webSearch,
+      settings: { model: cfg.model ?? DEFAULT_ANTHROPIC_SIDECAR_MODEL, reasoning, timeoutMs, describeImages },
+      maxSearches,
+      routedModelStallTimeoutMs,
+      stallTimeoutSec,
+    };
+  }
+
+  // OpenAI backend: needs a ChatGPT login (main) and a forward provider to reach server-side web_search.
+  if (authContext.kind === "main" && !incomingHeaders.get("authorization")) return undefined;
+  const forwardProvider = findForwardProvider(config);
+  if (!forwardProvider) return undefined;
   return {
+    backend: "openai",
     forwardProvider,
     hostedTool: parsed._webSearch,
-    settings: {
-      model: cfg.model ?? DEFAULT_SIDECAR_MODEL,
-      reasoning: cfg.reasoning ?? DEFAULT_SIDECAR_REASONING,
-      timeoutMs,
-      // The routed model is text-only → have the search model verbalize image results.
-      describeImages: modelInList(provider.noVisionModels, modelId),
-    },
-    maxSearches: cfg.maxSearchesPerTurn ?? DEFAULT_MAX_SEARCHES,
+    settings: { model: cfg.model ?? DEFAULT_SIDECAR_MODEL, reasoning, timeoutMs, describeImages },
+    maxSearches,
     routedModelStallTimeoutMs,
-    stallTimeoutSec: webSearchStallTimeoutSec(
-      config.stallTimeoutSec,
-      connectTimeoutMs,
-      routedModelStallTimeoutMs,
-      timeoutMs,
-    ),
+    stallTimeoutSec,
   };
 }