@yansigit/opencodex 2.31.0

package/src/vision/reasoning.ts

@@ -0,0 +1,55 @@
+import { NATIVE_OPENAI_MODELS, nativeReasoningEfforts } from "../codex/catalog/metadata";
+import {
+  VISION_REASONING_EFFORTS,
+  sanitizeVisionReasoning,
+  type VisionReasoningEffort,
+} from "../reasoning-effort";
+
+/** Keep the public config type aligned without replacing the heavily-changed shared types file. */
+declare module "../types" {
+  interface OcxVisionSidecarConfig {
+    /** OpenAI Responses reasoning effort used by the vision describer. Default: low. */
+    reasoning?: VisionReasoningEffort;
+  }
+}
+
+const NATIVE_VISION_MODELS = new Set(NATIVE_OPENAI_MODELS);
+
+/**
+ * Return the known vision reasoning ladder for a native OpenAI model.
+ * Unknown/custom models deliberately return undefined so callers stay permissive when reliable
+ * capability metadata is unavailable.
+ */
+export function nativeVisionReasoningEfforts(modelId: string): VisionReasoningEffort[] | undefined {
+  if (!NATIVE_VISION_MODELS.has(modelId)) return undefined;
+  const advertised = new Set(nativeReasoningEfforts(modelId));
+  const supported = VISION_REASONING_EFFORTS.filter(effort => advertised.has(effort));
+  return supported.length > 0 ? [...supported] : undefined;
+}
+
+/**
+ * Normalize one configured effort against a model's known ladder. Invalid enum values degrade to
+ * undefined; valid values on unknown/custom models are preserved. A known native model clamps to
+ * the highest supported rung at or below the requested value.
+ */
+export function normalizeVisionReasoningForModel(
+  modelId: string,
+  value: unknown,
+): VisionReasoningEffort | undefined {
+  const requested = sanitizeVisionReasoning(value);
+  if (!requested) return undefined;
+  const supported = nativeVisionReasoningEfforts(modelId);
+  if (!supported || supported.includes(requested)) return requested;
+
+  const requestedRank = VISION_REASONING_EFFORTS.indexOf(requested);
+  let best = supported[0];
+  let bestRank = VISION_REASONING_EFFORTS.indexOf(best);
+  for (const effort of supported) {
+    const rank = VISION_REASONING_EFFORTS.indexOf(effort);
+    if (rank <= requestedRank && rank >= bestRank) {
+      best = effort;
+      bestRank = rank;
+    }
+  }
+  return best;
+}

package/src/vision/routed-describe.ts

@@ -0,0 +1,175 @@
+/**
+ * Describe ONE image via a ROUTED model through the proxy's own
+ * /v1/chat/completions on loopback (#2188 roadmap 180 revised).
+ *
+ * One executor for every provider the router can reach: the chat inbound
+ * translates image_url parts and each adapter compiles its own wire
+ * (Anthropic blocks, Antigravity inlineData, xai Responses input_image, plain
+ * openai-chat), so provider coverage is the router's job, not this file's.
+ *
+ * Recursion fence: the request carries `x-opencodex-vision-describe: 1`.
+ * The Chat surface detects the raw header before its bridge rebuilds headers
+ * and carries it into handleResponses as `visionDescribeTerminal`; a marked
+ * request STRIPS images instead of planning another describe (depth cap 1,
+ * holds under predicate drift and combo re-resolution — audit rounds 2-4).
+ *
+ * Admission ladder (audit round 3): configuredApiAuthToken() (env token) ||
+ * service token file || first config.apiKeys entry, sent as
+ * `x-opencodex-api-key` — never Authorization (gateway-cache.ts rule: an
+ * admission secret in a forwardable header is a forwarding hazard). Loopback
+ * binds require no token at all (resolveApiAuth admits loopback).
+ *
+ * Known limitation (recorded in roadmap 170): a bindHost where 127.0.0.1
+ * does not answer cannot reach its own loopback — same latent limitation
+ * gateway-cache has.
+ */
+import type { OcxConfig } from "../types";
+import { signalWithTimeout, cancelBodyOnAbort } from "../lib/abort";
+import { redactSecretString } from "../lib/redact";
+import { sidecarEnter } from "../lib/sidecar-tracker";
+import { configuredApiAuthToken, configuredPort } from "../server/auth-cors";
+import { loadServiceTokenFromFile } from "../lib/service-secrets";
+import type { DescribeOutcome, VisionSettings } from "./describe";
+
+export const VISION_DESCRIBE_TERMINAL_HEADER = "x-opencodex-vision-describe";
+
+const ALLOWED_IMAGE_MIME = new Set(["image/png", "image/jpeg", "image/jpg", "image/webp", "image/gif"]);
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+/** Bound the loopback JSON response; descriptions are clamped to ~2k chars by the caller anyway. */
+const MAX_ROUTED_RESPONSE_BYTES = 4 * 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.";
+
+function validateImageUrl(url: string): string | null {
+  if (url.startsWith("data:")) {
+    const match = /^data:([^;,]+?)(;base64)?,(.*)$/s.exec(url);
+    if (!match) return "malformed data URL";
+    const mime = match[1].toLowerCase();
+    if (!ALLOWED_IMAGE_MIME.has(mime)) return `unsupported image type "${mime}"`;
+    if (match[2]) {
+      const bytes = Math.floor((match[3].length * 3) / 4);
+      if (bytes > MAX_IMAGE_BYTES) return `image too large (~${Math.round(bytes / 1024 / 1024)}MB)`;
+    }
+    return null;
+  }
+  if (url.startsWith("https://")) return null;
+  return "unsupported image URL scheme (expected data: or https:)";
+}
+
+/** The admission ladder: env token, service token file, first configured API key. */
+export function routedDescribeAdmissionToken(config: Pick<OcxConfig, "apiKeys">): string | undefined {
+  const envToken = configuredApiAuthToken();
+  if (envToken) return envToken;
+  const fileToken = loadServiceTokenFromFile(process.env);
+  if (fileToken) return fileToken;
+  const first = config.apiKeys?.[0]?.key?.trim();
+  return first || undefined;
+}
+
+/** Base URL seam for tests; production always self-fetches loopback. */
+export function routedDescribeBaseUrl(config: Pick<OcxConfig, "port">): string {
+  // config.port can be 0 (ephemeral bind, tests) or stale after a live port
+  // override; the server records its ACTUAL bound port via setCorsOrigin at
+  // startup, so prefer that when config carries no positive port.
+  const port = config.port && config.port > 0 ? String(config.port) : configuredPort();
+  return `http://127.0.0.1:${port}`;
+}
+
+export async function describeImageRouted(
+  imageUrl: string,
+  _detail: string | undefined,
+  contextText: string,
+  routedModel: string,
+  config: Pick<OcxConfig, "port" | "apiKeys">,
+  settings: VisionSettings,
+  abortSignal?: AbortSignal,
+  baseUrlOverride?: string,
+): Promise<DescribeOutcome> {
+  const invalid = validateImageUrl(imageUrl);
+  if (invalid) return { text: "", error: invalid };
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    [VISION_DESCRIBE_TERMINAL_HEADER]: "1",
+  };
+  const admission = routedDescribeAdmissionToken(config);
+  if (admission) headers["x-opencodex-api-key"] = admission;
+
+  const requestBody = {
+    model: routedModel,
+    stream: false,
+    messages: [
+      { role: "system", content: DESCRIBE_INSTRUCTION },
+      {
+        role: "user",
+        content: [
+          ...(contextText ? [{ type: "text", text: `User's request context: ${contextText}` }] : []),
+          { type: "image_url", image_url: { url: imageUrl } },
+        ],
+      },
+    ],
+  };
+
+  const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
+  const sidecarExit = sidecarEnter("vision");
+  const t0 = Date.now();
+  try {
+    const res = await fetch(`${baseUrlOverride ?? routedDescribeBaseUrl(config)}/v1/chat/completions`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(requestBody),
+      signal: linkedSignal.signal,
+      redirect: "manual",
+    });
+    const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
+    try {
+      const raw = await res.text();
+      if (raw.length > MAX_ROUTED_RESPONSE_BYTES) {
+        return { text: "", error: "routed describe response exceeded byte bound" };
+      }
+      if (!res.ok) {
+        return { text: "", error: `routed describe HTTP ${res.status}: ${redactSecretString(raw.slice(0, 200))}` };
+      }
+      let payload: unknown;
+      try { payload = JSON.parse(raw); } catch {
+        return { text: "", error: "routed describe returned non-JSON" };
+      }
+      const content = extractChatContent(payload);
+      if (!content) return { text: "", error: "routed describe returned no text" };
+      return { text: content };
+    } finally {
+      detachBodyGuard();
+    }
+  } catch (e) {
+    const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
+    console.warn(`[vision] routed describe ${kind} (${Date.now() - t0}ms)`);
+    return { text: "", error: redactSecretString(e instanceof Error ? e.message : String(e)) };
+  } finally {
+    sidecarExit();
+    linkedSignal.cleanup();
+  }
+}
+
+function extractChatContent(payload: unknown): string | undefined {
+  if (!payload || typeof payload !== "object") return undefined;
+  const choices = (payload as { choices?: unknown }).choices;
+  if (!Array.isArray(choices) || choices.length === 0) return undefined;
+  const message = (choices[0] as { message?: unknown })?.message;
+  if (!message || typeof message !== "object") return undefined;
+  const content = (message as { content?: unknown }).content;
+  if (typeof content === "string" && content.trim().length > 0) return content;
+  // Some adapters emit content parts; join text parts.
+  if (Array.isArray(content)) {
+    const joined = content
+      .map(part => (part && typeof part === "object" && typeof (part as { text?: unknown }).text === "string"
+        ? (part as { text: string }).text
+        : ""))
+      .join("");
+    if (joined.trim().length > 0) return joined;
+  }
+  return undefined;
+}

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;

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

@@ -0,0 +1,195 @@
+import type { OcxProviderConfig } from "../types";
+import { getValidAccessToken, publicOAuthAuthenticationErrorMessage } 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: ${publicOAuthAuthenticationErrorMessage(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" },
+    );
+    // Guard before any branch reads the body: the failure branch's `res.text()` ran ahead of
+    // the success-path guard, reopening the fetch-resolution-to-reader-attach race
+    // (found investigating #1419).
+    const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
+    if (!res.ok) {
+      const t = await res.text().catch(() => "");
+      detachBodyGuard();
+      console.warn(`[web-search] anthropic sidecar HTTP ${res.status} for query "${query.slice(0, 80)}" (${Date.now() - t0}ms)`);
+      if (res.status === 401) {
+        return { text: "", sources: [], error: `anthropic sidecar auth failed: ${publicOAuthAuthenticationErrorMessage(new Error(t))}` };
+      }
+      // Upstream bodies are untrusted and may contain credentials, paths, or provider diagnostics.
+      return { text: "", sources: [], error: `sidecar HTTP ${res.status}` };
+    }
+    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: `anthropic sidecar ${kind}` };
+  } finally {
+    sidecarExit();
+    linkedSignal.cleanup();
+  }
+}

package/src/web-search/backends.ts

@@ -0,0 +1,108 @@
+/**
+ * Which backends may RUN a hosted web_search, and which candidate rows each
+ * can run (#2188 rule 2 for web-search: ∩ probed backend with an executor).
+ *
+ * A backend registers here only when BOTH hold:
+ *  - an executor exists in this repository (src/web-search/executor.ts or
+ *    anthropic-executor.ts today), and
+ *  - its liveness probe passes. For the two shipped backends the probe IS
+ *    auth presence — the ChatGPT forward path and the stored Anthropic OAuth
+ *    path fail closed without a credential, so a live credential is the
+ *    strongest pre-flight signal short of spending a search.
+ *
+ * Future backends (Gemini google_search, Grok web_search, Zen hosted search,
+ * Exa-class vendors) stay OUT of this table until a live probe and an
+ * executor land — the research and probe contracts are recorded in
+ * devlog/_plan/260820_sidecar_selection_unification/002 and 031. Documenting
+ * a tool is not the same as being able to run it.
+ */
+import type { OcxConfig } from "../types";
+import { AUTH_SLOT_MODELS, type SidecarAuthState } from "../sidecar/auth";
+import type { SidecarCandidate } from "../sidecar/candidates";
+import { getAccountSet } from "../oauth/store";
+import type { WebSearchBackendId } from "./index";
+
+export interface WebSearchBackendDescriptor {
+  backend: WebSearchBackendId;
+  /** Liveness signal for this backend (auth presence for the shipped two). */
+  isActive(auth: SidecarAuthState, config: OcxConfig): boolean;
+  /** Which candidate rows this backend's executor can actually run. */
+  eligibleModel(candidate: SidecarCandidate, auth: SidecarAuthState): boolean;
+}
+
+export const WEB_SEARCH_BACKENDS: readonly WebSearchBackendDescriptor[] = [
+  {
+    backend: "openai",
+    isActive: auth => auth.isCodexAuth,
+    // The ChatGPT forward executor runs BARE native slugs and the Codex auth
+    // slot — settings.model is POSTed verbatim to the forward /responses, so
+    // an account-bound "selector/slug" row (model-rows emits those as
+    // provider "openai", native true) or a custom openai-keyed row would
+    // persist an id the executor cannot run (review F1). The sidecar never
+    // calls routeModel; there is no prefix-stripping on this path.
+    eligibleModel: candidate => candidate.provider === "openai"
+      && (candidate.native === true || candidate.authSlot === true)
+      && !candidate.id.includes("/"),
+  },
+  {
+    backend: "anthropic",
+    isActive: auth => auth.isAnthropicAuth,
+    // The stored-OAuth Messages executor dispatches through exactly ONE
+    // provider — the one the shared auth module resolved. Same-adapter keyed
+    // rows are unreachable, mirroring visionBackendForCandidate's stance.
+    eligibleModel: (candidate, auth) => candidate.provider === auth.anthropicProviderName,
+  },
+  {
+    backend: "xai",
+    // Probe = stored Grok OAuth usable: enabled oauth-mode "xai" provider whose
+    // active account is not marked for reauth — the same predicate
+    // findXaiSidecarProvider applies at plan time (L7).
+    isActive: (_auth, config) => {
+      const provider = config.providers["xai"];
+      if (!provider || provider.disabled === true || provider.authMode !== "oauth") return false;
+      const set = getAccountSet("xai");
+      const active = set?.accounts.find(account => account.id === set.activeAccountId);
+      return !!active && active.needsReauth !== true;
+    },
+    eligibleModel: candidate => candidate.provider === "xai",
+  },
+  {
+    backend: "gemini",
+    // Probe = usable Antigravity OAuth + discovered projectId (findGeminiSidecarProvider's predicate).
+    isActive: (_auth, config) => {
+      const provider = config.providers["google-antigravity"];
+      if (!provider || provider.disabled === true || provider.authMode !== "oauth") return false;
+      const set = getAccountSet("google-antigravity");
+      const active = set?.accounts.find(account => account.id === set.activeAccountId);
+      if (!active || active.needsReauth === true) return false;
+      return !!(active.credential as { projectId?: string } | undefined)?.projectId;
+    },
+    eligibleModel: candidate => candidate.provider === "google-antigravity",
+  },
+  {
+    backend: "exa",
+    // Probe = operator key present. Exa is not an LLM: no candidate models ever
+    // match, so the GUI's model list stays untouched by this backend.
+    isActive: (_auth, config) => !!config.webSearchSidecar?.exaApiKey,
+    eligibleModel: () => false,
+  },
+];
+
+/**
+ * (picker-visible ∪ auth slots) ∩ (active backend able to run the row).
+ * The auth slots always survive their own side's activation: a logged-in
+ * side keeps Luna/Haiku even when the picker hides them.
+ */
+export function webSearchSidecarCandidates(
+  config: OcxConfig,
+  auth: SidecarAuthState,
+  all: readonly SidecarCandidate[],
+): SidecarCandidate[] {
+  const active = WEB_SEARCH_BACKENDS.filter(descriptor => descriptor.isActive(auth, config));
+  return all.filter(candidate => active.some(descriptor => descriptor.eligibleModel(candidate, auth)));
+}
+
+/** True when the id is one of the fixed auth-slot models (#2188 write-gate exception). */
+export function isWebSearchAuthSlotModel(id: string): boolean {
+  return id === AUTH_SLOT_MODELS.codex || id === AUTH_SLOT_MODELS.anthropic;
+}

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

@@ -0,0 +1,88 @@
+/**
+ * Execute ONE web search via the Exa Search API (#2188 L9) — the non-LLM lane.
+ *
+ * Exa returns ranked result JSON, not a prose answer: the outcome's text is a
+ * per-result digest the routed model synthesizes from. Probe-verified 2026-08-21
+ * (devlog 002): POST https://api.exa.ai/search with x-api-key returns
+ * {requestId, results[{title,url,publishedDate,text}], costDollars}.
+ * redirect: "manual" because Bun forwards custom headers across redirects.
+ * Never throws; every error string passes redactSecretString.
+ */
+import { fetchWithResetRetry } from "../lib/upstream-retry";
+import { signalWithTimeout } from "../lib/abort";
+import { sidecarEnter } from "../lib/sidecar-tracker";
+import { redactSecretString } from "../lib/redact";
+import type { WebSearchSource } from "./parse";
+import type { SidecarOutcome, SidecarSettings } from "./executor";
+
+const EXA_SEARCH_URL = "https://api.exa.ai/search";
+const EXA_NUM_RESULTS = 5;
+const EXA_SNIPPET_CHARS = 1000;
+
+function isRec(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+export async function runExaWebSearch(
+  query: string,
+  apiKey: string,
+  settings: SidecarSettings,
+  abortSignal?: AbortSignal,
+): Promise<SidecarOutcome> {
+  if (!apiKey) return { text: "", sources: [], error: "exa backend selected without an exaApiKey" };
+  // The executor KNOWS the secret — pattern-based redaction cannot be trusted to
+  // recognize an arbitrary operator key, so scrub the literal value explicitly.
+  const scrub = (s: string) => redactSecretString(s.split(apiKey).join("[redacted-exa-key]"));
+  const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
+  const sidecarExit = sidecarEnter("web-search");
+  const t0 = Date.now();
+  try {
+    const res = await fetchWithResetRetry(
+      () => fetch(EXA_SEARCH_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "x-api-key": apiKey },
+        body: JSON.stringify({ query, numResults: EXA_NUM_RESULTS, contents: { text: { maxCharacters: EXA_SNIPPET_CHARS } } }),
+        signal: linkedSignal.signal,
+        redirect: "manual",
+      }),
+      { abortSignal: linkedSignal.signal, label: "exa-web-search-sidecar" },
+    );
+    if (!res.ok) {
+      const t = await res.text().catch(() => "");
+      // Scrub BEFORE truncating: slicing first can cut the literal key at the
+      // boundary, leaving an unscrubbable key prefix in the surviving text.
+      return { text: "", sources: [], error: `exa sidecar HTTP ${res.status}: ${scrub(t).slice(0, 200)}` };
+    }
+    const payload = await res.json().catch(() => null);
+    return mapExaSearchResponse(payload);
+  } catch (e) {
+    const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
+    console.warn(`[web-search] exa sidecar ${kind} (${Date.now() - t0}ms)`);
+    return { text: "", sources: [], error: scrub(e instanceof Error ? e.message : String(e)) };
+  } finally {
+    sidecarExit();
+    linkedSignal.cleanup();
+  }
+}
+
+/** Map an Exa /search payload to a digest the routed model can synthesize from. */
+export function mapExaSearchResponse(payload: unknown): SidecarOutcome {
+  if (!isRec(payload) || !Array.isArray(payload.results)) {
+    return { text: "", sources: [], error: "exa sidecar returned a non-JSON or shapeless body" };
+  }
+  const sources: WebSearchSource[] = [];
+  const lines: string[] = [];
+  const seen = new Set<string>();
+  for (const result of payload.results) {
+    if (!isRec(result) || typeof result.url !== "string" || result.url.length === 0) continue;
+    if (seen.has(result.url)) continue;
+    seen.add(result.url);
+    const title = typeof result.title === "string" && result.title.length > 0 ? result.title : result.url;
+    sources.push({ url: result.url, ...(title !== result.url ? { title } : {}) });
+    const snippet = typeof result.text === "string" ? result.text.trim().slice(0, EXA_SNIPPET_CHARS) : "";
+    const dated = typeof result.publishedDate === "string" ? ` (${result.publishedDate.slice(0, 10)})` : "";
+    lines.push(`- ${title}${dated}: ${snippet || "(no excerpt)"} [${result.url}]`);
+  }
+  if (lines.length === 0) return { text: "", sources: [], error: "exa sidecar returned no results" };
+  return { text: `Search results:\n${lines.join("\n")}`, sources };
+}