@bitkyc08/opencodex 2.7.4 → 2.7.7

package/src/server/images.ts

@@ -0,0 +1,218 @@
+/**
+ * /v1/images/{generations,edits} relay (issue #83).
+ *
+ * codex-rs's standalone image_gen extension executes CLIENT-SIDE: it POSTs
+ * `{base_url}/images/generations` (edits when reference images are attached) with the same
+ * ChatGPT bearer auth it uses for chat. Under Design B injection base_url IS this proxy, so
+ * without a route the tool died on the /v1/* JSON-404 guard. Only an OpenAI-family upstream
+ * can serve these endpoints — routed providers (Cursor, Kiro, Gemini, …) have no image
+ * generation surface — so the handler relays the body verbatim to the ChatGPT forward
+ * provider (or an OpenAI API-key provider) and passes the response through untouched:
+ * codex's images client parses `{created, data:[{b64_json}]}` strictly and Debug-prints
+ * error bodies into the model-visible failure, so upstream errors must stay legible.
+ */
+import { formatErrorResponse } from "../bridge";
+import {
+  CodexAccountCooldownError,
+  CodexAuthContextError,
+  CodexThreadAffinityExpiredError,
+  headersForCodexAuthContext,
+  isCodexAuthContextUsable,
+  resolveCodexAuthContext,
+} from "../codex/auth-context";
+import { formatCodexProviderForLog } from "../codex/routing";
+import { resolveEnvValue } from "../config";
+import { signalWithTimeout } from "../lib/abort";
+import { sidecarEnter } from "../lib/sidecar-tracker";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import { isProxyAdmissionSecret } from "./auth-cors";
+import { readJsonRequestBody } from "./request-decompress";
+import type { RequestLogContext } from "./request-log";
+import { codexLogAccountId, decodeRequestErrorResponse, sidecarOutcomeRecorder } from "./responses";
+
+export type ImagesEndpoint = "generations" | "edits";
+
+/** Image generation is slow (tens of seconds); bound a hung upstream, not a working one. */
+const IMAGES_UPSTREAM_TIMEOUT_MS = 300_000;
+
+/**
+ * Cap for the buffered upstream response body (100 MiB). Images responses are JSON documents
+ * containing base64-encoded images — typically a few MB. This prevents an oversized or malicious
+ * response from exhausting process memory.
+ */
+const IMAGES_RESPONSE_MAX_BYTES = 100 * 1024 * 1024;
+
+interface NamedProvider {
+  name: string;
+  provider: OcxProviderConfig;
+}
+
+interface ImagesUpstreamCandidates {
+  /** ChatGPT passthrough — the backend codex itself would have called absent the base_url override. */
+  forward?: NamedProvider;
+  /** Keyed openai-responses provider (e.g. api.openai.com), whose /v1/images/* is the platform Images API. */
+  keyed?: NamedProvider & { apiKey: string };
+}
+
+/**
+ * Collect the upstreams that can serve /images/*. The forward provider is preferred (same
+ * precedence as the vision/web-search sidecars) but only usable when the request actually
+ * carries relayable ChatGPT auth — startServer auto-upserts a `chatgpt` forward entry into
+ * every config, so its mere presence proves nothing about credentials.
+ */
+function findImagesUpstreams(config: OcxConfig): ImagesUpstreamCandidates {
+  const candidates: ImagesUpstreamCandidates = {};
+  for (const [name, provider] of Object.entries(config.providers)) {
+    if (provider.disabled === true) continue;
+    if (provider.authMode === "forward") {
+      candidates.forward ??= { name, provider };
+      continue;
+    }
+    if (candidates.keyed || provider.adapter !== "openai-responses" || provider.authMode === "oauth") continue;
+    const apiKey = resolveEnvValue(provider.apiKey);
+    if (apiKey) candidates.keyed = { name, provider, apiKey };
+  }
+  return candidates;
+}
+
+export async function handleImages(
+  req: Request,
+  config: OcxConfig,
+  endpoint: ImagesEndpoint,
+  logCtx: RequestLogContext,
+): Promise<Response> {
+  let body: unknown;
+  try {
+    body = await readJsonRequestBody(req);
+  } catch (err) {
+    return decodeRequestErrorResponse(err, "images");
+  }
+  const model = (body as { model?: unknown } | null)?.model;
+  if (typeof model === "string" && model) logCtx.model = model;
+
+  const candidates = findImagesUpstreams(config);
+  if (!candidates.forward && !candidates.keyed) {
+    // 400, not 5xx: codex retries every 5xx up to 5 total attempts, and this is a permanent
+    // configuration state that must surface on the first attempt.
+    return formatErrorResponse(
+      400,
+      "invalid_request_error",
+      "Built-in image generation needs an OpenAI upstream (ChatGPT login or an OpenAI API-key provider), "
+      + "but none is configured in opencodex. Routed providers cannot serve /v1/images/* — "
+      + "add an OpenAI provider or disable the tool with `codex features disable image_generation`.",
+    );
+  }
+
+  // Resolve forward auth first; failures are captured, not returned, so a configured keyed
+  // provider can still serve the request (e.g. every pool account cooling down must not
+  // 429 image_gen while api.openai.com sits idle).
+  let forwardAuthHeaders: Headers | undefined;
+  let forwardAuthError: Response | undefined;
+  let recordOutcome: ReturnType<typeof sidecarOutcomeRecorder>;
+  if (candidates.forward) {
+    try {
+      const authCtx = await resolveCodexAuthContext(req.headers, config);
+      if (!isCodexAuthContextUsable(authCtx, config)) {
+        forwardAuthError = formatErrorResponse(401, "authentication_error", "Selected Codex account needs reauthentication");
+      } else {
+        // Forwarded caller auth, overridden by the routed pool account's token when one is selected.
+        const authHeaders = headersForCodexAuthContext(req.headers, authCtx);
+        const bearer = authHeaders.get("authorization")?.replace(/^Bearer\s+/i, "") ?? "";
+        // A caller may authenticate to the proxy itself with `Authorization: Bearer <admission
+        // token>` (non-loopback binds); that secret must never be relayed to chatgpt.com.
+        if (bearer && isProxyAdmissionSecret(bearer, config)) authHeaders.delete("authorization");
+        // Only relay through the ChatGPT backend when there is a bearer to relay: startServer
+        // auto-upserts the `chatgpt` provider, so an unauthenticated request must not be bounced
+        // off chatgpt.com when a keyed OpenAI provider (or an honest error) serves it better.
+        if (authHeaders.get("authorization")) {
+          forwardAuthHeaders = authHeaders;
+          recordOutcome = sidecarOutcomeRecorder(config, authCtx);
+          logCtx.provider = formatCodexProviderForLog(candidates.forward.name, codexLogAccountId(authCtx), config);
+        }
+      }
+    } catch (err) {
+      if (err instanceof CodexAccountCooldownError) {
+        forwardAuthError = formatErrorResponse(429, "rate_limit_error", "Selected Codex account is cooling down");
+      } else if (err instanceof CodexThreadAffinityExpiredError) {
+        forwardAuthError = formatErrorResponse(409, "invalid_request_error", "Codex thread account affinity expired; start a new session");
+      } else if (err instanceof CodexAuthContextError) {
+        const safeAccountLabel = formatCodexProviderForLog(candidates.forward.name, err.accountId, config);
+        console.error(`[images] Pool account ${safeAccountLabel} token failed; reauthentication required`);
+        forwardAuthError = formatErrorResponse(401, "authentication_error", "Selected Codex account needs reauthentication");
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  let url: string;
+  if (forwardAuthHeaders && candidates.forward) {
+    const { provider } = candidates.forward;
+    if (provider.headers) Object.assign(headers, provider.headers);
+    for (const [name, value] of forwardAuthHeaders) headers[name] = value;
+    // The ChatGPT codex backend takes bare paths (matches the adapter's `${baseUrl}/responses`).
+    url = `${provider.baseUrl}/images/${endpoint}`;
+  } else if (candidates.keyed) {
+    const { provider, apiKey, name } = candidates.keyed;
+    if (provider.headers) Object.assign(headers, provider.headers);
+    headers["authorization"] = `Bearer ${apiKey}`;
+    logCtx.provider = name;
+    // Keyed providers tolerate baseUrl with or without /v1 (mirrors openai-responses.ts).
+    url = `${provider.baseUrl.replace(/\/v1\/?$/, "")}/v1/images/${endpoint}`;
+  } else if (forwardAuthError) {
+    return forwardAuthError;
+  } else {
+    return formatErrorResponse(
+      401,
+      "authentication_error",
+      "image generation relay needs ChatGPT auth (Authorization header) or an OpenAI API-key provider",
+    );
+  }
+
+  const timeoutMs = config.images?.timeoutMs ?? IMAGES_UPSTREAM_TIMEOUT_MS;
+  const linkedSignal = signalWithTimeout(timeoutMs, req.signal);
+  const sidecarExit = sidecarEnter("images");
+  try {
+    // Images POSTs create paid, non-idempotent work. One fetch only: no reset retry without a
+    // source-proven idempotency contract.
+    const upstreamResponse = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: linkedSignal.signal,
+    });
+    // Buffer rather than stream: the payload is one JSON document (base64 image, typically a few
+    // MB), and buffering keeps the timeout window covering the whole exchange. Cap the size to
+    // prevent an oversized response from exhausting process memory.
+    const payload = await upstreamResponse.arrayBuffer();
+    if (payload.byteLength > IMAGES_RESPONSE_MAX_BYTES) {
+      return formatErrorResponse(502, "upstream_error", `image ${endpoint} response too large (${payload.byteLength} bytes)`);
+    }
+    recordOutcome?.(upstreamResponse.status);
+    const relayHeaders: Record<string, string> = {};
+    const contentType = upstreamResponse.headers.get("content-type");
+    if (contentType) relayHeaders["content-type"] = contentType;
+    return new Response(payload, { status: upstreamResponse.status, headers: relayHeaders });
+  } catch (err) {
+    // Client cancel first: it aborts the linked signal too, and must not be logged as an
+    // upstream failure (499 maps to client_closed_request in the request log).
+    if (req.signal.aborted) {
+      return formatErrorResponse(499, "client_closed_request", `image ${endpoint} request canceled by client`);
+    }
+    if (err instanceof Error && err.name === "TimeoutError") {
+      recordOutcome?.("timeout");
+      // codex retries 5xx up to 4 more times; a retried 504 is acceptable for a transient hang.
+      return formatErrorResponse(504, "upstream_error", `image ${endpoint} upstream timed out`);
+    }
+    recordOutcome?.("connect_error");
+    return formatErrorResponse(
+      502,
+      "upstream_error",
+      `image ${endpoint} relay failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  } finally {
+    sidecarExit();
+    linkedSignal.cleanup();
+  }
+}

package/src/server/index.ts

@@ -59,6 +59,7 @@ export {
 } from "./lifecycle";
 import {
   addFinalRequestLog,
+  httpStatusForRequestLogTerminal,
   httpStatusForTerminalStatus,
   inspectResponseLogSsePayload,
   nextRequestLogId,
@@ -116,6 +117,8 @@ export {
 } from "./auth-cors";
 import { disableResponsesRequestTimeout, handleResponses, handleResponsesCompact } from "./responses";
 export { disableResponsesRequestTimeout, linkAbortSignal } from "./responses";
+import { handleImages } from "./images";
+import { handleSearch } from "./search";
 import { fetchAllModels, handleManagementAPI, VERSION } from "./management-api";
 
 const MAX_WS_FRAME_BYTES = 50 * 1024 * 1024;
@@ -304,6 +307,58 @@ export function startServer(port?: number) {
         return withCors(await handleResponsesCompact(req, config), req, config);
       }
 
+      if (
+        req.method === "POST"
+        && (url.pathname === "/v1/images/generations" || url.pathname === "/v1/images/edits")
+      ) {
+        disableResponsesRequestTimeout(req, requestServer);
+        if (isDraining()) {
+          return new Response("Service shutting down", {
+            status: 503,
+            headers: { ...corsHeaders(req, config), "Retry-After": "5" },
+          });
+        }
+        const apiAuthError = requireApiAuth(req, config, "data-plane");
+        if (apiAuthError) return withCors(apiAuthError, req, config);
+        if (!isAllowedRequestOrigin(req, config)) {
+          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, config);
+        }
+        const start = Date.now();
+        const requestId = nextRequestLogId(start);
+        const logCtx: RequestLogContext = { model: "image_gen", provider: "unknown" };
+        const endpoint = url.pathname.endsWith("/edits") ? "edits" as const : "generations" as const;
+        const response = await handleImages(req, config, endpoint, logCtx);
+        addFinalRequestLog(requestId, start, logCtx, response.status, response.status === 499 ? { closeReason: "client_cancel" } : undefined);
+        return withCors(response, req, config);
+      }
+
+      if (url.pathname === "/v1/alpha/search" && req.method === "POST") {
+        disableResponsesRequestTimeout(req, requestServer);
+        if (isDraining()) {
+          return new Response("Service shutting down", {
+            status: 503,
+            headers: { ...corsHeaders(req, config), "Retry-After": "5" },
+          });
+        }
+        const apiAuthError = requireApiAuth(req, config, "data-plane");
+        if (apiAuthError) return withCors(apiAuthError, req, config);
+        if (!isAllowedRequestOrigin(req, config)) {
+          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, config);
+        }
+        const start = Date.now();
+        const requestId = nextRequestLogId(start);
+        const logCtx: RequestLogContext = { model: "web_search", provider: "unknown" };
+        const response = await handleSearch(req, config, logCtx);
+        addFinalRequestLog(
+          requestId,
+          start,
+          logCtx,
+          response.status,
+          response.status === 499 ? { closeReason: "client_cancel" } : undefined,
+        );
+        return withCors(response, req, config);
+      }
+
       if (url.pathname === "/v1/responses" && req.method === "POST") {
         disableResponsesRequestTimeout(req, requestServer);
         if (isDraining()) {
@@ -343,7 +398,7 @@ export function startServer(port?: number) {
 
       // Data-plane guard: unknown /v1/* paths must fail with JSON 404, never fall through to the
       // GUI static handler (extensionless paths would get index.html with HTTP 200 and codex-rs
-      // endpoint clients — alpha/search, images/*, memories/*, realtime/* — would surface confusing
+      // endpoint clients — memories/*, realtime/* — would surface confusing
       // serde decode errors instead of a clean not-found).
       if (url.pathname.startsWith("/v1/")) {
         return withCors(formatErrorResponse(404, "not_found", `Unknown endpoint: ${req.method} ${url.pathname}`), req, config);
@@ -485,7 +540,7 @@ export function startServer(port?: number) {
               onSsePayload: payload => inspectResponseLogSsePayload(logCtx, payload),
               onTerminal: status => {
                 terminalRecorder?.(status);
-                finalizeLog(httpStatusForTerminalStatus(status), {
+                finalizeLog(httpStatusForRequestLogTerminal(status, logCtx), {
                   terminalStatus: status,
                   closeReason: "terminal",
                 });

package/src/server/management-api.ts

@@ -572,6 +572,34 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     return jsonResponse({ ok: true, model: config.injectionModel ?? null, effort: config.injectionEffort ?? null, prompt: config.injectionPrompt ?? null });
   }
 
+  // Hard reasoning-effort caps (devlog/260710_subagent_effort_intercept): a global ceiling and a
+  // sub-agent-only ceiling, enforced per-request in handleResponses (src/server/effort-policy.ts).
+  // Key semantics per field: absent -> unchanged; null/"" -> clear; ladder value -> set; else 400.
+  if (url.pathname === "/api/effort-caps" && req.method === "GET") {
+    const { CODEX_REASONING_LEVELS } = await import("../reasoning-effort");
+    return jsonResponse({
+      effortCap: config.effortCap ?? null,
+      subagentEffortCap: config.subagentEffortCap ?? null,
+      efforts: CODEX_REASONING_LEVELS.map(l => l.effort),
+    });
+  }
+  if (url.pathname === "/api/effort-caps" && req.method === "PUT") {
+    let body: { effortCap?: unknown; subagentEffortCap?: unknown };
+    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    const { isCodexReasoningEffort } = await import("../reasoning-effort");
+    for (const key of ["effortCap", "subagentEffortCap"] as const) {
+      if (!(key in body)) continue;
+      const value = body[key];
+      if (value === null || value === "") { delete config[key]; continue; }
+      if (typeof value !== "string" || !isCodexReasoningEffort(value)) {
+        return jsonResponse({ error: `unknown reasoning effort "${String(value)}"` }, 400);
+      }
+      config[key] = value;
+    }
+    saveConfig(config);
+    return jsonResponse({ ok: true, effortCap: config.effortCap ?? null, subagentEffortCap: config.subagentEffortCap ?? null });
+  }
+
   // Subagent model picker: which ≤5 routed models Codex's spawn_agent advertises (it shows the
   // first 5 routed catalog entries). PUT reorders the injected catalog so the chosen ones lead.
   if (url.pathname === "/api/subagent-models" && req.method === "GET") {

package/src/server/responses.ts

@@ -374,7 +374,7 @@ export function codexForwardTerminalOutcomeRecorder(
  * zstd-compressed screenshot history exceeds the limit), or a genuine JSON syntax error (400). The
  * real decode error was previously swallowed, so log it before returning the generic 400.
  */
-function decodeRequestErrorResponse(err: unknown, label: string): Response {
+export function decodeRequestErrorResponse(err: unknown, label: string): Response {
   if (err instanceof UnsupportedContentEncodingError) {
     return formatErrorResponse(415, "invalid_request_error", err.message);
   }
@@ -470,6 +470,33 @@ export async function handleResponses(
     }
   }
 
+  // Hard effort caps (effortCap / subagentEffortCap): enforcement companion to the advisory
+  // injection above — spawn-arg prompting cannot stop codex-rs from inheriting the parent's
+  // ultra-tier default on bare spawns (see src/server/effort-policy.ts). Runs BEFORE the
+  // mock-max clamp so a capped effort is what nativeness clamping then validates; rewrites
+  // both request shapes (same dual-write contract as the clamp below).
+  // GATE: v2 feature only (effortCapAppliesTo) — v2-surface main turns plus header-marked
+  // child turns admitted regardless of tool surface (depth-limited leaves carry no collab
+  // tools while shallower children do, so tool sniffing alone would cap siblings
+  // inconsistently); multiAgentMode "v1" disables caps entirely; compaction turns bypass
+  // caps so routed compaction matches native /v1/responses/compact (which never enters
+  // handleResponses).
+  {
+    const { applyEffortCap, effortCapAppliesTo, supportedLadderFor } = await import("./effort-policy");
+    const surface = collabSurface(parsed);
+    if (effortCapAppliesTo(surface, req.headers, config, parsed._compactionRequest === true)) {
+      const capped = applyEffortCap(parsed, req.headers, config, supportedLadderFor(route));
+      if (capped) {
+        logCtx.requestedEffort = `${capped.from}->${capped.to}`;
+        if (isInjectionDebugEnabled()) {
+          console.log(`[opencodex] ${route.modelId}: effort cap applied (${capped.from} -> ${capped.to}, ${capped.subagent ? "sub-agent" : "main"} turn)`);
+        }
+      }
+    } else if (isInjectionDebugEnabled() && (config.effortCap || config.subagentEffortCap)) {
+      console.log(`[opencodex] ${route.modelId}: effort cap skipped (surface=${surface ?? "none"}, v2 feature only)`);
+    }
+  }
+
   // Mock-max clamp: native models whose real ladder stops below max (gpt-5.5/5.4/…)
   // receive `max` when the user picks Ultra (codex converts ultra->max client-side).
   // Clamp to the model's highest real effort BEFORE any adapter — the ChatGPT
@@ -810,6 +837,7 @@ export async function handleResponses(
       abortSignal: options.abortSignal,
       recordSidecarOutcome,
       connectTimeoutMs: config.connectTimeoutMs ?? 200_000,
+      routedModelStallTimeoutMs: wsPlan.routedModelStallTimeoutMs,
       stallTimeoutSec: wsPlan.stallTimeoutSec,
       on429: retryAfter => {
         const rotated = rotateKeyOn429(config, route.providerName, retryAfter, Date.now(), route.provider.apiKey);

package/src/server/search.ts

@@ -0,0 +1,150 @@
+/**
+ * /v1/alpha/search relay.
+ *
+ * codex-rs's built-in search client executes CLIENT-SIDE: it POSTs `alpha/search` against the
+ * configured base_url with the same ChatGPT bearer auth used for model requests. Under Design B
+ * injection base_url is this proxy, so the request otherwise dies on the /v1/* JSON-404 guard.
+ * The endpoint is private to the ChatGPT Codex backend, so routed providers and OpenAI API-key
+ * providers cannot serve it. Relay the JSON request and response verbatim through the configured
+ * ChatGPT forward provider.
+ */
+import { formatErrorResponse } from "../bridge";
+import {
+  CodexAccountCooldownError,
+  CodexAuthContextError,
+  CodexThreadAffinityExpiredError,
+  headersForCodexAuthContext,
+  isCodexAuthContextUsable,
+  resolveCodexAuthContext,
+} from "../codex/auth-context";
+import { formatCodexProviderForLog } from "../codex/routing";
+import { signalWithTimeout } from "../lib/abort";
+import { sidecarEnter } from "../lib/sidecar-tracker";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import { isProxyAdmissionSecret } from "./auth-cors";
+import { readJsonRequestBody } from "./request-decompress";
+import type { RequestLogContext } from "./request-log";
+import { codexLogAccountId, decodeRequestErrorResponse, sidecarOutcomeRecorder } from "./responses";
+
+/**
+ * Default TOTAL deadline for one search relay. alpha/search is non-streaming JSON — response
+ * headers arrive only when the search finishes — so the budget must cover the whole request.
+ * Overridable via config.search.timeoutMs; never config.connectTimeoutMs, whose documented
+ * contract is the DNS/TCP/TLS/header-arrival budget (a 10s connect budget would kill every
+ * long-running search).
+ */
+const SEARCH_UPSTREAM_TIMEOUT_MS = 200_000;
+const SEARCH_RESPONSE_MAX_BYTES = 16 * 1024 * 1024;
+
+interface NamedProvider {
+  name: string;
+  provider: OcxProviderConfig;
+}
+
+function findSearchUpstream(config: OcxConfig): NamedProvider | undefined {
+  for (const [name, provider] of Object.entries(config.providers)) {
+    if (provider.disabled !== true && provider.authMode === "forward") return { name, provider };
+  }
+  return undefined;
+}
+
+export async function handleSearch(
+  req: Request,
+  config: OcxConfig,
+  logCtx: RequestLogContext,
+): Promise<Response> {
+  let body: unknown;
+  try {
+    body = await readJsonRequestBody(req);
+  } catch (err) {
+    return decodeRequestErrorResponse(err, "search");
+  }
+  const model = (body as { model?: unknown } | null)?.model;
+  if (typeof model === "string" && model) logCtx.model = model;
+
+  const upstream = findSearchUpstream(config);
+  if (!upstream) {
+    return formatErrorResponse(
+      400,
+      "invalid_request_error",
+      "Built-in web search needs a ChatGPT forward provider, but none is configured in opencodex. "
+      + "Routed and OpenAI API-key providers cannot serve /v1/alpha/search.",
+    );
+  }
+
+  let authHeaders: Headers;
+  let recordOutcome: ReturnType<typeof sidecarOutcomeRecorder>;
+  try {
+    const authCtx = await resolveCodexAuthContext(req.headers, config);
+    if (!isCodexAuthContextUsable(authCtx, config)) {
+      return formatErrorResponse(401, "authentication_error", "Selected Codex account needs reauthentication");
+    }
+    authHeaders = headersForCodexAuthContext(req.headers, authCtx);
+    const bearer = authHeaders.get("authorization")?.replace(/^Bearer\s+/i, "") ?? "";
+    if (bearer && isProxyAdmissionSecret(bearer, config)) authHeaders.delete("authorization");
+    if (!authHeaders.get("authorization")) {
+      return formatErrorResponse(
+        401,
+        "authentication_error",
+        "web search relay needs ChatGPT auth (Authorization header)",
+      );
+    }
+    recordOutcome = sidecarOutcomeRecorder(config, authCtx);
+    logCtx.provider = formatCodexProviderForLog(upstream.name, codexLogAccountId(authCtx), config);
+  } catch (err) {
+    if (err instanceof CodexAccountCooldownError) {
+      return formatErrorResponse(429, "rate_limit_error", "Selected Codex account is cooling down");
+    }
+    if (err instanceof CodexThreadAffinityExpiredError) {
+      return formatErrorResponse(409, "invalid_request_error", "Codex thread account affinity expired; start a new session");
+    }
+    if (err instanceof CodexAuthContextError) {
+      const safeAccountLabel = formatCodexProviderForLog(upstream.name, err.accountId, config);
+      console.error(`[search] Pool account ${safeAccountLabel} token failed; reauthentication required`);
+      return formatErrorResponse(401, "authentication_error", "Selected Codex account needs reauthentication");
+    }
+    throw err;
+  }
+
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (upstream.provider.headers) Object.assign(headers, upstream.provider.headers);
+  for (const [name, value] of authHeaders) headers[name] = value;
+  const url = `${upstream.provider.baseUrl}/alpha/search`;
+  const timeoutMs = config.search?.timeoutMs ?? SEARCH_UPSTREAM_TIMEOUT_MS;
+  const linkedSignal = signalWithTimeout(timeoutMs, req.signal);
+  const sidecarExit = sidecarEnter("search");
+  try {
+    const upstreamResponse = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: linkedSignal.signal,
+    });
+    const payload = await upstreamResponse.arrayBuffer();
+    if (payload.byteLength > SEARCH_RESPONSE_MAX_BYTES) {
+      return formatErrorResponse(502, "upstream_error", `search response too large (${payload.byteLength} bytes)`);
+    }
+    recordOutcome?.(upstreamResponse.status);
+    const relayHeaders: Record<string, string> = {};
+    const contentType = upstreamResponse.headers.get("content-type");
+    if (contentType) relayHeaders["content-type"] = contentType;
+    return new Response(payload, { status: upstreamResponse.status, headers: relayHeaders });
+  } catch (err) {
+    if (req.signal.aborted) {
+      return formatErrorResponse(499, "client_closed_request", "search request canceled by client");
+    }
+    if (err instanceof Error && err.name === "TimeoutError") {
+      recordOutcome?.("timeout");
+      return formatErrorResponse(504, "upstream_error", "search upstream timed out");
+    }
+    recordOutcome?.("connect_error");
+    return formatErrorResponse(
+      502,
+      "upstream_error",
+      `search relay failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  } finally {
+    sidecarExit();
+    linkedSignal.cleanup();
+  }
+}

package/src/types.ts

@@ -259,6 +259,20 @@ export interface OcxConfig {
    * the resolved sub-agent roster block ("" when nothing resolves).
    */
   injectionPrompt?: string;
+  /**
+   * Global hard ceiling for the reasoning effort of EVERY proxied turn (main agent AND
+   * sub-agents). Ladder value "low".."max"; incoming efforts ranking above it are rewritten
+   * in both request shapes before any adapter or clamp. Unset = no cap. codex-rs converts
+   * ultra -> max client-side, so e.g. a "high" cap sends ultra/max-tier turns as high.
+   */
+  effortCap?: string;
+  /**
+   * Hard ceiling applied ONLY to sub-agent turns — requests carrying codex-rs's spawned-child
+   * markers (`x-openai-subagent` header, or `subagent_kind` inside `x-codex-turn-metadata`).
+   * Lets the main agent keep its tier while delegated children are capped. When both caps are
+   * set, the lower one wins for sub-agents. See src/server/effort-policy.ts.
+   */
+  subagentEffortCap?: string;
   /**
    * Models hidden from Codex. Routed ids are namespaced ("<provider>/<model>") and are excluded
    * from the catalog + /v1/models entirely. BARE ids (no "/") are native GPT passthrough slugs:
@@ -312,6 +326,10 @@ export interface OcxConfig {
   webSearchSidecar?: OcxWebSearchSidecarConfig;
   /** Vision sidecar: describe images via a gpt vision model so text-only models can "see" them. */
   visionSidecar?: OcxVisionSidecarConfig;
+  /** /v1/images relay for codex's built-in image_gen tool. */
+  images?: OcxImagesConfig;
+  /** /v1/alpha/search relay for codex's built-in web search client. */
+  search?: OcxSearchConfig;
   /** Codex multi-account pool. */
   codexAccounts?: CodexAccount[];
   /** Active pool account id for next session. undefined = main (passthrough as-is). */
@@ -357,6 +375,20 @@ export interface OcxTokenGuardianConfig {
   codexWarmupModel?: string;
 }
 
+export interface OcxImagesConfig {
+  /** Upstream timeout (ms) for one /v1/images relay. Default 300000 — generation is slow. */
+  timeoutMs?: number;
+}
+
+export interface OcxSearchConfig {
+  /**
+   * Total upstream deadline (ms) for one /v1/alpha/search relay. Default 200000. The endpoint
+   * is non-streaming JSON (headers arrive only when the search completes), so this is a whole-
+   * request budget — deliberately NOT connectTimeoutMs, which is a header-arrival budget.
+   */
+  timeoutMs?: number;
+}
+
 export interface OcxVisionSidecarConfig {
   /** Master switch. Default: enabled when a forward (ChatGPT) provider exists and the caller is logged in. */
   enabled?: boolean;
@@ -377,6 +409,11 @@ export interface OcxWebSearchSidecarConfig {
   maxSearchesPerTurn?: number;
   /** Sidecar fetch timeout (ms). */
   timeoutMs?: number;
+  /**
+   * Config-file-only deadline (ms) for continuous routed-model response-body raw-byte inactivity
+   * during a web-search turn. Default 200000. Must be an integer from 1 through 2147483647.
+   */
+  routedModelStallTimeoutMs?: number;
 }
 
 export interface OcxProviderConfig {