[WRONG BRANCH] feat(web-search): openai-apikey backend with a per-lane reasoning toggle

src/lib/redact.ts

@@ -7,7 +7,7 @@ export const REDACTED_SECRET = "[REDACTED]";
  * credentials over an unsafe channel (e.g. plaintext non-loopback HTTP) rather than
  * re-deriving a narrower local list.
  */
-export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cookie|set-cookie|set-cookie2|api[-_]?key|x-api-key|x-goog-api-key|x-amz-security-token|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|client[-_]?secret|password|profile[-_]?arn|exa[-_]?api[-_]?key)$/i;
+export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cookie|set-cookie|set-cookie2|api[-_]?key|openai[-_]?api[-_]?key|x-api-key|x-goog-api-key|x-amz-security-token|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|client[-_]?secret|password|profile[-_]?arn|exa[-_]?api[-_]?key)$/i;
 
 /**
  * Colon-labelled credential headers echoed back inside an error body
@@ -40,7 +40,7 @@ export const SENSITIVE_KEY_PATTERN = /^(?:authorization|proxy-authorization|cook
 // Every letter position also accepts \u0001, the placeholder the fold emits for
 // an unresolved HTML named reference: `authorⅈzation` is the label with one
 // character we cannot name, and that is still the label.
-const CREDENTIAL_HEADER_LABEL_RAW = "x-api-key|x-goog-api-key|x-amz-security-token|api[_-]?key|apiKey|exa[_-]?api[_-]?key|exaApiKey|access[_-]?token|accessToken|refresh[_-]?token|refreshToken|id[_-]?token|client[_-]?secret|clientSecret|authorization|proxy-authorization|cookie|set-cookie|password|secret|token";
+const CREDENTIAL_HEADER_LABEL_RAW = "x-api-key|x-goog-api-key|x-amz-security-token|api[_-]?key|apiKey|openai[_-]?api[_-]?key|openaiApiKey|exa[_-]?api[_-]?key|exaApiKey|access[_-]?token|accessToken|refresh[_-]?token|refreshToken|id[_-]?token|client[_-]?secret|clientSecret|authorization|proxy-authorization|cookie|set-cookie|password|secret|token";
 
 const CREDENTIAL_HEADER_LABEL = CREDENTIAL_HEADER_LABEL_RAW
   .replace(/(?<![\[\\])([A-Za-z])(?![\]\-])/g, "[$1\u0001]");

src/server/management/agent-settings-routes.ts

@@ -1293,7 +1293,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       // unknown literal would persist a backend the vision resolver reads as
       // unset (review F1's failure mode).
       const allowedBackends = field === "webSearchSidecar"
-        ? ["openai", "anthropic", "xai", "gemini", "exa"]
+        ? ["openai", "anthropic", "xai", "gemini", "exa", "openai-apikey"]
         : ["openai", "anthropic", "routed"];
       if (section.backend !== undefined && section.backend !== null
         && !allowedBackends.includes(section.backend as string)) {
@@ -1370,7 +1370,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       }
       // The per-field validation above guarantees vision only ever carries the two-member
       // union; the cast is the loop's shared-shape compromise, not a wider write path.
-      const requested = section as { backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa" | null; model?: string };
+      const requested = section as { backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa" | "openai-apikey" | null; model?: string };
       const override = { ...next[field] } as NonNullable<OcxClaudeCodeConfig[typeof field]>;
       if (requested.backend === null) delete override.backend;
       else if (requested.backend !== undefined) override.backend = requested.backend as never;

src/server/management/config-routes.ts

@@ -706,6 +706,10 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         enabled: ws.enabled !== false,
         model: ws.model ?? "gpt-5.6-luna",
         backend: ws.backend,
+        // Reasoning effort echoed so a client can read the current toggle. It is NOT a secret
+        // (unlike exaApiKey/openaiApiKey, which never leave), so it rides the GET/PUT payloads.
+        // Unset is a distinct "on (lane default)" state from "off": surface only when present.
+        reasoning: ws.reasoning,
         streamRoutedModelOutput: ws.streamRoutedModelOutput === true,
         ...(ws.xSearch ? { xSearch: ws.xSearch } : {}),
       },
@@ -726,7 +730,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     if (raw.webSearch !== undefined && !isPlainRecord(raw.webSearch)) return jsonResponse({ error: "webSearch must be an object" }, 400);
     if (raw.vision !== undefined && !isPlainRecord(raw.vision)) return jsonResponse({ error: "vision must be an object" }, 400);
     const body = raw as {
-      webSearch?: { model?: unknown; backend?: unknown; reasoning?: unknown; streamRoutedModelOutput?: unknown; exaApiKey?: unknown; xSearch?: unknown };
+      webSearch?: { model?: unknown; backend?: unknown; reasoning?: unknown; streamRoutedModelOutput?: unknown; exaApiKey?: unknown; openaiApiKey?: unknown; xSearch?: unknown };
       vision?: {
         model?: unknown;
         backend?: unknown;
@@ -736,10 +740,10 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         timeoutMs?: unknown;
       };
     };
-    const WEB_SEARCH_BACKENDS_UNION = ["openai", "anthropic", "xai", "gemini", "exa"] as const;
+    const WEB_SEARCH_BACKENDS_UNION = ["openai", "anthropic", "xai", "gemini", "exa", "openai-apikey"] as const;
     if (body.webSearch && body.webSearch.backend !== undefined && body.webSearch.backend !== null
       && !WEB_SEARCH_BACKENDS_UNION.includes(body.webSearch.backend as never)) {
-      return jsonResponse({ error: "webSearch.backend must be openai, anthropic, xai, gemini, exa, or null" }, 400);
+      return jsonResponse({ error: "webSearch.backend must be openai, anthropic, xai, gemini, exa, openai-apikey, or null" }, 400);
     }
     if (body.webSearch?.model !== undefined && typeof body.webSearch.model !== "string") {
       return jsonResponse({ error: "webSearch.model must be a string" }, 400);
@@ -845,13 +849,25 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       else if (WEB_SEARCH_BACKENDS_UNION.includes(body.webSearch.backend as never)) {
         webSearchCandidate.backend = body.webSearch.backend as typeof WEB_SEARCH_BACKENDS_UNION[number];
       }
-      if (typeof body.webSearch.reasoning === "string") webSearchCandidate.reasoning = body.webSearch.reasoning;
+      // Reasoning effort toggle: a string sets, an empty string clears (back to the lane
+      // default). The reserved value "off" passes through — resolveSidecarReasoning collapses
+      // it at plan time so the executor omits the `reasoning` field entirely.
+      if (typeof body.webSearch.reasoning === "string") {
+        if (body.webSearch.reasoning === "") delete webSearchCandidate.reasoning;
+        else webSearchCandidate.reasoning = body.webSearch.reasoning;
+      }
       // Operator secret for the exa backend: string sets, empty string clears. The GET
       // payload deliberately never carries it and redact.ts strips the key from logs.
       if (typeof body.webSearch.exaApiKey === "string") {
         if (body.webSearch.exaApiKey === "") delete webSearchCandidate.exaApiKey;
         else webSearchCandidate.exaApiKey = body.webSearch.exaApiKey;
       }
+      // Operator secret for the openai-apikey backend: string sets, empty string clears. Same
+      // invariants as exaApiKey — the GET payload never carries it and redact.ts strips the key.
+      if (typeof body.webSearch.openaiApiKey === "string") {
+        if (body.webSearch.openaiApiKey === "") delete webSearchCandidate.openaiApiKey;
+        else webSearchCandidate.openaiApiKey = body.webSearch.openaiApiKey;
+      }
       // Opt-in x_search block (L7): null clears; an object is doc-validated before persisting.
       if (body.webSearch.xSearch === null) delete webSearchCandidate.xSearch;
       else if (body.webSearch.xSearch !== undefined) {
@@ -945,6 +961,10 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         enabled: ws.enabled !== false,
         model: ws.model ?? "gpt-5.6-luna",
         backend: ws.backend,
+        // Reasoning effort echoed so a client can read the current toggle. It is NOT a secret
+        // (unlike exaApiKey/openaiApiKey, which never leave), so it rides the GET/PUT payloads.
+        // Unset is a distinct "on (lane default)" state from "off": surface only when present.
+        reasoning: ws.reasoning,
         streamRoutedModelOutput: ws.streamRoutedModelOutput === true,
         ...(ws.xSearch ? { xSearch: ws.xSearch } : {}),
       },

src/server/responses/sidecar-execution.ts

@@ -5,7 +5,7 @@ import type { ResponsesSidecarAuth } from "./request-sidecar-auth";
 import type { ResponsesEffects } from "./response-effects";
 import type { ResponsesSendBudget } from "./request-send-budget";
 import { formatErrorResponse } from "../../bridge";
-import { planWebSearch, buildWebSearchTool, runWithWebSearch } from "../../web-search";
+import { planWebSearch, buildWebSearchTool, runWithWebSearch, resolveOpenAiApiKeyCredential } from "../../web-search";
 import {
   planImageBridge,
   planVideoBridge,
@@ -420,6 +420,9 @@ export async function executeResponsesSidecars(
       xaiSearchOptions: wsPlan.xaiSearchOptions,
       // The exa key never rides the plan: read it from config at unpack time (L9).
       ...(wsPlan.exaConfigured ? { exaApiKey: config.webSearchSidecar?.exaApiKey } : {}),
+      // Same invariant for the openai-apikey lane: the key never rides the plan, and resolving it
+      // here (not in planWebSearch) keeps the env fallback (OPENAI_API_KEY) current per request.
+      ...(wsPlan.openaiApiKeyConfigured ? { openaiApiKey: resolveOpenAiApiKeyCredential(config) } : {}),
       hostedTool: wsPlan.hostedTool,
       selectedForwardHeaders: wsPlan.forwardSidecar?.headers ?? requestState.selectedForwardHeaders,
       settings: wsPlan.settings,

src/types/config.ts

@@ -136,7 +136,7 @@ export interface OcxClaudeCodeConfig {
    */
   subagentEffort?: "low" | "medium" | "high" | "xhigh" | "max";
   /** Claude-originated web-search override. Unset fields inherit the global sidecar settings. */
-  webSearchSidecar?: { backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa"; model?: string };
+  webSearchSidecar?: { backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa" | "openai-apikey"; model?: string };
   /** Claude-originated vision override. Unset fields inherit the global sidecar settings. */
   visionSidecar?: { backend?: "openai" | "anthropic" | "routed"; model?: string };
   /** Persisted Claude Desktop four-family routing profile. */
@@ -1247,18 +1247,29 @@ export interface OcxWebSearchSidecarConfig {
    * model authenticated by the STORED anthropic OAuth credential. "xai" runs Grok hosted web_search
    * and optional x_search through stored Grok OAuth. "gemini" (google_search grounding via the
    * Antigravity CCA transport) and "exa" (non-LLM search JSON via an operator key) are explicit-only
-   * and stay inactive until their executors ship. Unset ALWAYS resolves to "openai"; no backend is ever
-   * auto-selected from credential availability (that once sent incompatible models to the
-   * Anthropic API — see resolveSidecarBackend).
+   * and stay inactive until their executors ship. "openai-apikey" runs OpenAI's hosted web_search via
+   * the Responses API with an operator-supplied `openaiApiKey` — the key-auth twin of the ChatGPT
+   * forward "openai" backend, for deployments without a ChatGPT login but with a plain `sk-…` key.
+   * Unset ALWAYS resolves to "openai"; no backend is ever auto-selected from credential
+   * availability (that once sent incompatible models to the Anthropic API — see resolveSidecarBackend).
    */
-  backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa";
+  backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa" | "openai-apikey";
   /** Sidecar model that runs the real server-side web_search (must be a native ChatGPT model). */
   model?: string;
   /**
    * Operator-supplied Exa API key for the "exa" backend. Management GET responses never echo it,
    * and src/lib/redact.ts strips it from any logged structure or error string.
    */
   exaApiKey?: string;
+  /**
+   * Operator-supplied OpenAI API key for the "openai-apikey" backend (the key-auth twin of the
+   * ChatGPT forward "openai" backend). Management GET responses never echo it, and
+   * src/lib/redact.ts strips it from any logged structure or error string. When unset, the
+   * process `OPENAI_API_KEY` is the fallback (resolved by resolveOpenAiApiKeyCredential). The
+   * backend always posts to `https://api.openai.com/v1/responses` (the endpoint that hosts the
+   * web_search tool for a standard `sk-…` key).
+   */
+  openaiApiKey?: string;
   /**
    * Opt-in X (Twitter) search for the xai backend: adds the hosted x_search tool next to
    * web_search. Limits are doc-validated at the management layer AND in the executor:

src/web-search/alpha-search.ts

@@ -17,7 +17,7 @@ import { sidecarEnter } from "../lib/sidecar-tracker";
 import type { OcxConfig, OcxProviderConfig, OcxWebSearchSidecarConfig } from "../types";
 import { runAnthropicWebSearch } from "./anthropic-executor";
 import { runExaWebSearch } from "./exa-executor";
-import type { SidecarOutcome, SidecarSettings } from "./executor";
+import { resolveSidecarReasoning, type SidecarOutcome, type SidecarSettings } from "./executor";
 import { runGeminiWebSearch } from "./gemini-executor";
 import {
   findAnthropicSidecarProvider,
@@ -94,7 +94,11 @@ export function resolveAlphaSearchSidecar(config: OcxConfig): AlphaSearchSidecar
   // for alpha/search" — the one reading under which a disabled backend still spends money.
   if (sidecar?.enabled === false) return { status: "unconfigured" };
   const backend = resolveSidecarBackend(sidecar?.backend);
-  if (backend === "openai") return { status: "unconfigured" };
+  // Both the ChatGPT forward path ("openai") and the operator API-key path ("openai-apikey")
+  // cannot serve /v1/alpha/search — this surface only answers with a stored/secondary OAuth or
+  // Exa credential. See NO_FORWARD_PROVIDER_MESSAGE ("OpenAI API-key providers cannot serve
+  // /v1/alpha/search"). Returning "unconfigured" yields that message, matching the contract.
+  if (backend === "openai" || backend === "openai-apikey") return { status: "unconfigured" };
   switch (backend) {
     case "anthropic": {
       const found = findAnthropicSidecarProvider(config);
@@ -170,7 +174,7 @@ function sidecarSettingsForAlphaSearch(
   const sidecar = config.webSearchSidecar;
   return {
     model: modelForAlphaSearchBackend(backend, sidecar),
-    reasoning: sidecar?.reasoning ?? DEFAULT_REASONING,
+    reasoning: resolveSidecarReasoning(sidecar?.reasoning, DEFAULT_REASONING),
     timeoutMs: config.search?.timeoutMs ?? SEARCH_UPSTREAM_TIMEOUT_MS,
   };
 }

src/web-search/backends.ts

@@ -18,6 +18,7 @@
  */
 import type { OcxConfig } from "../types";
 import { AUTH_SLOT_MODELS, type SidecarAuthState } from "../sidecar/auth";
+import { resolveOpenAiApiKeyCredential } from "./sidecar-providers";
 import type { SidecarCandidate } from "../sidecar/candidates";
 import { getAccountSet } from "../oauth/store";
 import type { WebSearchBackendId } from "./index";
@@ -86,6 +87,17 @@ export const WEB_SEARCH_BACKENDS: readonly WebSearchBackendDescriptor[] = [
     isActive: (_auth, config) => !!config.webSearchSidecar?.exaApiKey,
     eligibleModel: () => false,
   },
+  {
+    backend: "openai-apikey",
+    // Probe = operator key resolvable (config field or OPENAI_API_KEY env).
+    isActive: (_auth, config) => resolveOpenAiApiKeyCredential(config) !== undefined,
+    // The executor POSTs the model string VERBATIM to api.openai.com, so only a
+    // bare native OpenAI slug is runnable — same stance as the "openai" lane
+    // (no namespaced ids, which this fixed public endpoint cannot route).
+    eligibleModel: candidate => candidate.provider === "openai"
+      && (candidate.native === true || candidate.authSlot === true)
+      && !candidate.id.includes("/"),
+  },
 ];
 
 /**

src/web-search/executor.ts

@@ -11,7 +11,14 @@ import { NATIVE_RESERVE_MODEL } from "../codex/catalog/native-models";
 
 export interface SidecarSettings {
   model: string;
-  reasoning: string;
+  /**
+   * Reasoning effort to send upstream, or `undefined` to omit the `reasoning` field from the
+   * request entirely. `resolveSidecarReasoning` produces it from config: an unset value keeps
+   * the lane default, while `"off"` (or an empty string) yields `undefined` because
+   * non-reasoning models (e.g. gpt-4.1-mini) reject the field with a 400 — the operator turns
+   * it off per backend. Executors omit the field whenever this is undefined.
+   */
+  reasoning?: string;
   timeoutMs: number;
   /** Effective Desktop authless compatibility does not grant auxiliary model use. */
   reserveCompatibility?: boolean;
@@ -23,6 +30,27 @@ export interface SidecarSettings {
   describeImages?: boolean;
 }
 
+/**
+ * Resolve the operator's reasoning effort (`webSearchSidecar.reasoning`) to the value
+ * `SidecarSettings.reasoning` carries. Unset keeps the lane default — a config that never named
+ * an effort behaves exactly as before. `"off"` (or an empty/whitespace string) means "send no
+ * reasoning field at all": non-reasoning models (e.g. gpt-4.1-mini) reject `reasoning` with a
+ * 400, so the operator can turn it off per backend. Anything else passes through verbatim — the
+ * executor posts it as `reasoning.effort` and the upstream decides.
+ *
+ * Lives in the shared executor leaf so the forward plan (index.ts), the alpha/search plan
+ * (alpha-search.ts, which must not import the barrel) and the passthrough-bridge plan all
+ * collapse `"off"` the same way instead of diverging.
+ */
+export function resolveSidecarReasoning(
+  configured: string | undefined,
+  defaultEffort: string,
+): string | undefined {
+  if (configured === undefined) return defaultEffort;
+  const trimmed = configured.trim();
+  return trimmed === "" || trimmed.toLowerCase() === "off" ? undefined : configured;
+}
+
 // 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 =
@@ -67,7 +95,9 @@ export async function runWebSearch(
     input: [{ type: "message", role: "user", content: [{ type: "input_text", text: query }] }],
     tools: [hostedTool],
     tool_choice: "auto",
-    reasoning: { effort: settings.reasoning },
+    // Omitted entirely when the operator turned reasoning off ("off"/"" in config): non-reasoning
+    // models reject the field with a 400. `reasoning.effort` values are sent verbatim otherwise.
+    ...(settings.reasoning !== undefined ? { reasoning: { effort: settings.reasoning } } : {}),
     // NOTE: the ChatGPT (codex) backend rejects `max_output_tokens` ("Unsupported parameter") and
     // requires `store: false` — keep this body minimal. The shared SSE parser bounds raw response
     // bytes before format-result applies its smaller display clamp.