@bitkyc08/opencodex 2.28.0 → 2.29.0

package/src/vision/index.ts

@@ -7,7 +7,7 @@ import { describeImage, type DescribeOutcome, type VisionSettings } from "./desc
 import { describeImageAnthropic } from "./anthropic-describe";
 import { normalizeVisionReasoningForModel } from "./reasoning";
 import type { CodexAuthContext } from "../codex/auth-context";
-import { getAccountSet } from "../oauth/store";
+import { resolveSidecarAuth } from "../sidecar/auth";
 import type { ResolvedOpenAiForwardSidecar } from "../providers/openai-sidecar";
 import type { SidecarOutcomeRecorder } from "../web-search/executor";
 import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
@@ -215,15 +215,14 @@ export interface AnthropicVisionProvider {
   provider: OcxProviderConfig;
 }
 
-/** First enabled Anthropic OAuth provider whose active stored account is not marked for reauth. */
+/**
+ * First enabled Anthropic OAuth provider whose active stored account is not marked for reauth.
+ * Delegates to the shared sidecar auth module (#2188) — same predicate as web-search.
+ */
 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;
+  const auth = resolveSidecarAuth(config);
+  if (!auth.isAnthropicAuth || !auth.anthropicProviderName || !auth.anthropicProvider) return undefined;
+  return { providerName: auth.anthropicProviderName, provider: auth.anthropicProvider };
 }
 
 export function resolveVisionBackend(

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 };
+}

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

@@ -0,0 +1,141 @@
+/**
+ * Execute ONE web search via Gemini google_search grounding on the Antigravity
+ * Cloud Code Assist transport (#2188 L8). Live-probed 2026-08-20/21 (devlog 002):
+ * the CCA envelope with tools [{google_search:{}}] returns a grounded answer
+ * plus groundingMetadata; a non-IDE User-Agent gets 404, so the request reuses
+ * the adapter's fingerprint constants. The OAuth bearer only ever travels to
+ * the REGISTRY-pinned endpoint — a config-level baseUrl override is never
+ * trusted for token transmission (same rule as src/server/images.ts).
+ * Never throws — returns {error} so the caller injects a graceful tool result.
+ */
+import type { OcxProviderConfig } from "../types";
+import { getValidAccessTokenSnapshot, publicOAuthAuthenticationErrorMessage } from "../oauth";
+import { fetchWithResetRetry } from "../lib/upstream-retry";
+import { cancelBodyOnAbort, signalWithTimeout } from "../lib/abort";
+import { readBoundedResponseBytes } from "../lib/bounded-body";
+import { sidecarEnter } from "../lib/sidecar-tracker";
+import { redactSecretString } from "../lib/redact";
+import { ANTIGRAVITY_REQUEST_UA } from "../adapters/google-antigravity-wire";
+import { resolveAntigravityEffortWireModel } from "../providers/antigravity-models";
+import { getProviderRegistryEntry } from "../providers/registry";
+import { MAX_SIDECAR_RESPONSE_BYTES, type WebSearchSource } from "./parse";
+import { BASE_INSTRUCTION, IMAGE_INSTRUCTION, type SidecarOutcome, type SidecarSettings } from "./executor";
+
+const CCA_FALLBACK_BASE = "https://daily-cloudcode-pa.googleapis.com";
+
+function isRec(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+export async function runGeminiWebSearch(
+  query: string,
+  providerName: string,
+  _provider: OcxProviderConfig,
+  settings: SidecarSettings,
+  abortSignal?: AbortSignal,
+): Promise<SidecarOutcome> {
+  let token: string;
+  let project: string | undefined;
+  try {
+    const snapshot = await getValidAccessTokenSnapshot(providerName);
+    token = snapshot.accessToken;
+    project = snapshot.projectId;
+  } catch (e) {
+    return { text: "", sources: [], error: `gemini sidecar auth failed: ${publicOAuthAuthenticationErrorMessage(e)}` };
+  }
+  if (!project) {
+    return { text: "", sources: [], error: "gemini sidecar missing Cloud Code Assist project id — re-run ocx login google-antigravity" };
+  }
+  // Destination pinned to the registry endpoint (see module doc).
+  const base = getProviderRegistryEntry("google-antigravity")?.baseUrl ?? CCA_FALLBACK_BASE;
+  const { wireModelId, thinkingLevel } = resolveAntigravityEffortWireModel(settings.model, settings.reasoning, base);
+  const instruction = settings.describeImages ? BASE_INSTRUCTION + IMAGE_INSTRUCTION : BASE_INSTRUCTION;
+  const envelope = {
+    model: wireModelId,
+    userAgent: "antigravity",
+    requestType: "agent",
+    project,
+    requestId: `agent-${crypto.randomUUID()}`,
+    request: {
+      systemInstruction: { role: "user", parts: [{ text: instruction }] },
+      contents: [{ role: "user", parts: [{ text: query }] }],
+      tools: [{ google_search: {} }],
+      sessionId: crypto.randomUUID(),
+      ...(thinkingLevel ? { generationConfig: { thinkingConfig: { thinkingLevel } } } : {}),
+    },
+  };
+  const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
+  const sidecarExit = sidecarEnter("web-search");
+  const t0 = Date.now();
+  try {
+    const res = await fetchWithResetRetry(
+      () => fetch(`${base}/v1internal:generateContent`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${token}`,
+          "User-Agent": ANTIGRAVITY_REQUEST_UA,
+        },
+        body: JSON.stringify(envelope),
+        signal: linkedSignal.signal,
+        redirect: "manual",
+      }),
+      { abortSignal: linkedSignal.signal, label: "gemini-web-search-sidecar" },
+    );
+    const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
+    try {
+      const bounded = await readBoundedResponseBytes(res, {
+        maxBytes: MAX_SIDECAR_RESPONSE_BYTES,
+        signal: linkedSignal.signal,
+      });
+      if (bounded.oversized) {
+        const prefix = res.ok ? "gemini sidecar response" : `gemini sidecar HTTP ${res.status} response`;
+        return { text: "", sources: [], error: `${prefix} exceeded byte bound` };
+      }
+      const text = new TextDecoder("utf-8", { fatal: true }).decode(bounded.bytes);
+      if (!res.ok) {
+        return { text: "", sources: [], error: `gemini sidecar HTTP ${res.status}: ${redactSecretString(text.slice(0, 200))}` };
+      }
+      let payload: unknown = null;
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        // The mapper owns the stable malformed/empty JSON outcome.
+      }
+      return mapCcaGroundedResponse(payload);
+    } finally {
+      detachBodyGuard();
+    }
+  } catch (e) {
+    const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
+    console.warn(`[web-search] gemini sidecar ${kind} (${Date.now() - t0}ms)`);
+    return { text: "", sources: [], error: redactSecretString(e instanceof Error ? e.message : String(e)) };
+  } finally {
+    sidecarExit();
+    linkedSignal.cleanup();
+  }
+}
+
+/** Map a CCA generateContent payload (possibly wrapped in {response}) to text + grounding sources. */
+export function mapCcaGroundedResponse(payload: unknown): SidecarOutcome {
+  const root = isRec(payload) && isRec(payload.response) ? payload.response : payload;
+  if (!isRec(root)) return { text: "", sources: [], error: "gemini sidecar returned a non-JSON or empty body" };
+  const candidate = Array.isArray(root.candidates) && isRec(root.candidates[0]) ? root.candidates[0] : undefined;
+  if (!candidate) return { text: "", sources: [], error: "gemini sidecar returned no candidates" };
+  const parts = isRec(candidate.content) && Array.isArray(candidate.content.parts) ? candidate.content.parts : [];
+  const text = parts.map(p => (isRec(p) && typeof p.text === "string" ? p.text : "")).join("");
+  const sources: WebSearchSource[] = [];
+  const seen = new Set<string>();
+  const gm = isRec(candidate.groundingMetadata) ? candidate.groundingMetadata : undefined;
+  if (gm && Array.isArray(gm.groundingChunks)) {
+    for (const chunk of gm.groundingChunks) {
+      const web = isRec(chunk) && isRec(chunk.web) ? chunk.web : undefined;
+      const uri = web && typeof web.uri === "string" ? web.uri : undefined;
+      if (!uri || seen.has(uri)) continue;
+      seen.add(uri);
+      sources.push({ url: uri, ...(typeof web?.title === "string" && web.title.length > 0 ? { title: web.title } : {}) });
+    }
+  }
+  if (text.length === 0) return { text: "", sources, error: "gemini sidecar returned no text" };
+  return { text, sources };
+}

package/src/web-search/index.ts

@@ -3,17 +3,27 @@ import { modelInList, toolChoiceToolPredicate } from "../types";
 import { isModelTextOnly } from "../vision";
 import type { SidecarSettings } from "./executor";
 import type { ResolvedOpenAiForwardSidecar } from "../providers/openai-sidecar";
+import { resolveSidecarAuth } from "../sidecar/auth";
 import { getAccountSet } from "../oauth/store";
+import { validateXaiSearchOptions, type XaiSearchOptions } from "./xai-executor";
+import type { OcxWebSearchSidecarConfig } from "../types";
 import { DEFAULT_STALL_TIMEOUT_SEC } from "../stall-timeout";
 import { buildWebSearchTool, extractHostedWebSearch, WEB_SEARCH_TOOL_NAME } from "./synthetic-tool";
 
 export { runWithWebSearch } from "./loop";
 export { buildWebSearchTool, extractHostedWebSearch, WEB_SEARCH_TOOL_NAME };
 export { runAnthropicWebSearch, parseAnthropicSidecarSSE } from "./anthropic-executor";
+export { runXaiWebSearch, parseXaiResponsesSSE, validateXaiSearchOptions, type XaiSearchOptions } from "./xai-executor";
+export { runGeminiWebSearch, mapCcaGroundedResponse } from "./gemini-executor";
+export { runExaWebSearch, mapExaSearchResponse } from "./exa-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";
+// Default Grok model for the xai-backed sidecar (probe-verified with hosted tools, devlog 003).
+const DEFAULT_XAI_SIDECAR_MODEL = "grok-4.6";
+// Default Gemini model for the gemini-backed sidecar (CCA grounding probe, devlog 002).
+const DEFAULT_GEMINI_SIDECAR_MODEL = "gemini-3.7-flash";
 // "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";
@@ -83,37 +93,94 @@ export interface AnthropicSidecarProvider {
  * 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.
+ * Delegates to the shared sidecar auth module (#2188) so web-search and vision
+ * cannot drift on what "Anthropic auth present" means.
  */
 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 };
-  }
+  const auth = resolveSidecarAuth(config);
+  if (!auth.isAnthropicAuth || !auth.anthropicProviderName || !auth.anthropicProvider) return undefined;
+  return { providerName: auth.anthropicProviderName, provider: auth.anthropicProvider };
+}
+
+/**
+ * First enabled provider whose stored Grok OAuth account is active and not marked for
+ * reauth — the only credential the xai web-search executor may spend. Same account-set
+ * predicate the shared sidecar auth module applies to Anthropic.
+ */
+export function findXaiSidecarProvider(config: OcxConfig): { providerName: string; provider: OcxProviderConfig } | undefined {
+  // The stored Grok credential lives under the provider named "xai" (registry id);
+  // OAuth account sets are keyed by provider name, so the name IS the credential key.
+  const provider = config.providers["xai"];
+  if (!provider || provider.disabled === true || provider.authMode !== "oauth") return undefined;
+  const set = getAccountSet("xai");
+  const active = set?.accounts.find(account => account.id === set.activeAccountId);
+  if (active && active.needsReauth !== true) return { providerName: "xai", provider };
   return undefined;
 }
 
+/**
+ * First usable Antigravity credential holder: the "google-antigravity" provider
+ * (registry id = OAuth store key, same narrowing as findXaiSidecarProvider) whose
+ * active stored account is healthy AND carries a discovered CCA projectId — the
+ * executor cannot form the envelope without it.
+ */
+export function findGeminiSidecarProvider(config: OcxConfig): { providerName: string; provider: OcxProviderConfig } | undefined {
+  const provider = config.providers["google-antigravity"];
+  if (!provider || provider.disabled === true || provider.authMode !== "oauth") return undefined;
+  const set = getAccountSet("google-antigravity");
+  const active = set?.accounts.find(account => account.id === set.activeAccountId);
+  if (!active || active.needsReauth === true) return undefined;
+  const projectId = (active.credential as { projectId?: string } | undefined)?.projectId;
+  if (!projectId) return undefined;
+  return { providerName: "google-antigravity", provider };
+}
+
+/** Lift the persisted xSearch config block into executor options (absent block = web_search only). */
+export function xaiSearchOptionsFromConfig(cfg: Pick<OcxWebSearchSidecarConfig, "xSearch">): XaiSearchOptions {
+  const x = cfg.xSearch;
+  if (!x || x.enabled !== true) return {};
+  return {
+    xSearch: true,
+    ...(x.allowedXHandles ? { allowedXHandles: x.allowedXHandles } : {}),
+    ...(x.excludedXHandles ? { excludedXHandles: x.excludedXHandles } : {}),
+    ...(x.fromDate ? { fromDate: x.fromDate } : {}),
+    ...(x.toDate ? { toDate: x.toDate } : {}),
+  };
+}
+
+/** Every backend id the config union admits. New ids are explicit-only and inert until their executor ships. */
+export type WebSearchBackendId = "openai" | "anthropic" | "xai" | "gemini" | "exa";
+
 /**
  * Precedence: explicit config wins; unset defaults to "openai" (ChatGPT forward path). The
  * anthropic backend (web_search_20250305) is only used when explicitly configured — auto-selecting
  * it from credential availability caused the sidecar to send incompatible models (e.g. gpt-5.6-luna)
  * to the Anthropic API.
+ * The 2188 follow-up ids (xai/gemini/exa) resolve to themselves the same explicit-only way; their
+ * planWebSearch arms stay fail-closed until each executor layer lands.
  */
 export function resolveSidecarBackend(
-  explicit: "openai" | "anthropic" | undefined,
-): "openai" | "anthropic" {
-  return explicit === "anthropic" ? "anthropic" : "openai";
+  explicit: WebSearchBackendId | undefined,
+): WebSearchBackendId {
+  if (explicit === "anthropic" || explicit === "xai" || explicit === "gemini" || explicit === "exa") return explicit;
+  return "openai";
 }
 
 export interface SidecarPlan {
   /** Which executor runs the search. Anthropic does not require a forward provider. */
-  backend: "openai" | "anthropic";
+  backend: WebSearchBackendId;
   /** Present for the openai backend (ChatGPT forward path); undefined for anthropic. */
   forwardSidecar?: ResolvedOpenAiForwardSidecar;
   /** Present for the anthropic backend (stored-OAuth /v1/messages path); undefined for openai. */
   anthropicSidecar?: AnthropicSidecarProvider;
+  /** Present for the xai backend (stored Grok OAuth /v1/responses path). */
+  xaiSidecar?: { providerName: string; provider: OcxProviderConfig };
+  /** Present for the gemini backend (Antigravity CCA grounding path). */
+  geminiSidecar?: { providerName: string; provider: OcxProviderConfig };
+  /** Opt-in x_search options for the xai backend (validated at the management layer and again in the executor). */
+  xaiSearchOptions?: XaiSearchOptions;
+  /** Presence marker for the exa backend — the API key itself never rides the plan. */
+  exaConfigured?: true;
   hostedTool: Record<string, unknown>;
   settings: SidecarSettings;
   maxSearches: number;
@@ -157,7 +224,12 @@ export function planWebSearch(
   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);
+  // Shared auth state (#2188): presence only — backend PREFERENCE stays with
+  // resolveSidecarBackend's explicit-or-openai contract.
+  const auth = resolveSidecarAuth(config);
+  const anthropicSidecar = auth.isAnthropicAuth && auth.anthropicProviderName && auth.anthropicProvider
+    ? { providerName: auth.anthropicProviderName, provider: auth.anthropicProvider }
+    : undefined;
   const backend = resolveSidecarBackend(cfg.backend);
   const maxSearches = cfg.maxSearchesPerTurn ?? DEFAULT_MAX_SEARCHES;
   const stallTimeoutSec = webSearchStallTimeoutSec(
@@ -189,6 +261,61 @@ export function planWebSearch(
     };
   }
 
+  // xAI backend (L7): explicit-only, authenticated by the STORED Grok OAuth credential.
+  // Same fail-closed stance as anthropic — an explicit choice with no usable credential
+  // produces no plan instead of borrowing another login.
+  if (backend === "xai") {
+    const xaiSidecar = findXaiSidecarProvider(config);
+    if (!xaiSidecar) return undefined;
+    const xaiOptions = xaiSearchOptionsFromConfig(cfg);
+    if (validateXaiSearchOptions(xaiOptions)) return undefined;
+    return {
+      backend: "xai",
+      xaiSidecar,
+      xaiSearchOptions: xaiOptions,
+      hostedTool: parsed._webSearch,
+      settings: { model: cfg.model ?? DEFAULT_XAI_SIDECAR_MODEL, reasoning, timeoutMs, describeImages },
+      maxSearches,
+      routedModelStallTimeoutMs,
+      stallTimeoutSec,
+      streamRoutedModelOutput,
+    };
+  }
+
+  // Gemini backend (L8): explicit-only, authenticated by the stored Antigravity CCA
+  // OAuth credential; requires the discovered projectId. Fail-closed like the others.
+  if (backend === "gemini") {
+    const geminiSidecar = findGeminiSidecarProvider(config);
+    if (!geminiSidecar) return undefined;
+    return {
+      backend: "gemini",
+      geminiSidecar,
+      hostedTool: parsed._webSearch,
+      settings: { model: cfg.model ?? DEFAULT_GEMINI_SIDECAR_MODEL, reasoning, timeoutMs, describeImages },
+      maxSearches,
+      routedModelStallTimeoutMs,
+      stallTimeoutSec,
+      streamRoutedModelOutput,
+    };
+  }
+
+  // exa (L9): explicit-only, keyed by the operator-supplied exaApiKey. The KEY never
+  // rides the plan object — core.ts reads it from config at unpack time; the plan
+  // carries only a presence marker. Fail-closed without a key.
+  if (backend === "exa") {
+    if (!cfg.exaApiKey) return undefined;
+    return {
+      backend: "exa",
+      exaConfigured: true,
+      hostedTool: parsed._webSearch,
+      settings: { model: cfg.model ?? DEFAULT_SIDECAR_MODEL, reasoning, timeoutMs, describeImages },
+      maxSearches,
+      routedModelStallTimeoutMs,
+      stallTimeoutSec,
+      streamRoutedModelOutput,
+    };
+  }
+
   // OpenAI backend: needs a ChatGPT login (main) and a forward provider to reach server-side web_search.
   if (!openAiSidecar) return undefined;
   return {