@bitkyc08/opencodex 0.1.0

package/src/star-prompt.ts

@@ -0,0 +1,50 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { getConfigDir } from "./config";
+
+const REPO = "lidge-jun/opencodex";
+/** Shared with scripts/postinstall.mjs so the prompt fires exactly once across install + first start. */
+const MARKER = ".star-prompted";
+
+function ghAvailable(): boolean {
+  const r = spawnSync("gh", ["--version"], { stdio: "ignore", timeout: 3000, windowsHide: true });
+  return !r.error && r.status === 0;
+}
+
+function starRepo(): { ok: boolean; error?: string } {
+  const r = spawnSync("gh", ["api", "-X", "PUT", `/user/starred/${REPO}`],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10000, windowsHide: true });
+  if (r.error) return { ok: false, error: r.error.message };
+  if (r.status !== 0) return { ok: false, error: (r.stderr || r.stdout || "").trim() || `gh exited ${r.status}` };
+  return { ok: true };
+}
+
+/**
+ * First interactive `ocx start`: a one-time `[Y/n]` "star on GitHub?" prompt. On yes, stars the repo
+ * via the user's `gh` auth (same approach as the npm postinstall). No-op under the background service,
+ * for non-TTY/piped runs, when already prompted, or when `gh` is unavailable. Never throws.
+ */
+export async function maybeShowStarPrompt(): Promise<void> {
+  try {
+    if (process.env.OCX_SERVICE || !process.stdin.isTTY || !process.stdout.isTTY) return;
+    const dir = getConfigDir();
+    const marker = join(dir, MARKER);
+    if (existsSync(marker)) return;
+    if (!ghAvailable()) return; // can't star without gh — stay silent and re-check on a later start
+    try { mkdirSync(dir, { recursive: true }); writeFileSync(marker, new Date().toISOString()); } catch { /* best-effort */ }
+
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let yes = false;
+    try {
+      const ans = (await rl.question("\n  \x1b[38;5;141m⭐ Enjoying opencodex? Star it on GitHub?\x1b[0m [Y/n] ")).trim().toLowerCase();
+      yes = ans === "" || ans === "y" || ans === "yes";
+    } finally {
+      rl.close();
+    }
+    if (!yes) return;
+    const r = starRepo();
+    console.log(r.ok ? "  Thanks for the star! ⭐\n" : `  Couldn't star automatically (${r.error}) — ${REPO}\n`);
+  } catch { /* never let the star prompt disrupt startup */ }
+}

package/src/types.ts

@@ -0,0 +1,228 @@
+export interface OcxParsedRequest {
+  modelId: string;
+  context: OcxContext;
+  stream: boolean;
+  options: OcxRequestOptions;
+  _rawBody?: unknown;
+  /**
+   * The hosted `{type:"web_search", ...}` tool config, stashed when Codex enables web search. Routed
+   * (non-OpenAI) providers can't run it server-side, so the proxy re-exposes it as a function tool and
+   * executes searches via the gpt-5.4-mini sidecar (see src/web-search). Absent when not requested.
+   */
+  _webSearch?: Record<string, unknown>;
+  /**
+   * True when Codex requested structured output (`text.format` = json_schema/json_object). The
+   * web-search tool_result is then rendered as compact JSON instead of markdown prose, so its
+   * answer/"Sources:" text can't bleed into and corrupt the model's schema-constrained output.
+   */
+  _structuredOutput?: boolean;
+}
+
+export interface OcxContext {
+  systemPrompt?: string[];
+  messages: OcxMessage[];
+  tools?: OcxTool[];
+}
+
+export type OcxMessage =
+  | OcxUserMessage
+  | OcxAssistantMessage
+  | OcxDeveloperMessage
+  | OcxToolResultMessage;
+
+export interface OcxUserMessage {
+  role: "user";
+  content: string | OcxContentPart[];
+  timestamp: number;
+}
+
+export interface OcxAssistantMessage {
+  role: "assistant";
+  content: OcxAssistantContentPart[];
+  model?: string;
+  timestamp: number;
+}
+
+export interface OcxDeveloperMessage {
+  role: "developer";
+  content: string | OcxContentPart[];
+  timestamp: number;
+}
+
+export interface OcxToolResultMessage {
+  role: "toolResult";
+  toolCallId: string;
+  toolName: string;
+  /** Text, or content parts when a tool (e.g. Codex view_image) returns an image in its output. */
+  content: string | OcxContentPart[];
+  isError: boolean;
+  timestamp: number;
+}
+
+export interface OcxTextContent {
+  type: "text";
+  text: string;
+}
+
+export interface OcxImageContent {
+  type: "image";
+  /** A `data:` URL (base64) or a remote https URL — passed through from Codex verbatim, NEVER inlined as text. */
+  imageUrl: string;
+  /** Fidelity hint from Codex: "low" | "high" | "auto". */
+  detail?: string;
+}
+
+/** A user/developer message content part: text or an image (vision). */
+export type OcxContentPart = OcxTextContent | OcxImageContent;
+
+export interface OcxThinkingContent {
+  type: "thinking";
+  thinking: string;
+  signature?: string;
+  itemId?: string;
+}
+
+export interface OcxToolCall {
+  type: "toolCall";
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  customWireName?: string;
+  thoughtSignature?: string;
+  /** MCP namespace (e.g. "mcp__context7") when this call targets a namespaced tool. */
+  namespace?: string;
+}
+
+export type OcxAssistantContentPart = OcxTextContent | OcxThinkingContent | OcxToolCall;
+
+export interface OcxTool {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  strict?: boolean;
+  /** MCP namespace (e.g. "mcp__context7") for tools flattened out of a Responses "namespace" tool. */
+  namespace?: string;
+  /** Freeform/custom tool (e.g. apply_patch): the model's call must be relayed as a custom_tool_call. */
+  freeform?: boolean;
+  /** Client-executed tool discovery (tool_search): the model's call must be relayed as a tool_search_call. */
+  toolSearch?: boolean;
+  /** Synthetic web_search tool: the model's call is executed by the gpt-5.4-mini sidecar, not relayed to Codex. */
+  webSearch?: boolean;
+}
+
+/**
+ * Wire name a chat model sees for a tool. Namespaced (MCP) tools are flattened to
+ * "<namespace>__<name>" so they survive the chat-completions function-tool format;
+ * the proxy maps this back to {namespace, name} on the return trip (Codex routes MCP
+ * calls by an explicit `namespace` field, not by parsing the name).
+ */
+export function namespacedToolName(namespace: string | undefined, name: string): string {
+  return namespace ? `${namespace}__${name}` : name;
+}
+
+/**
+ * Whether `modelId` is in a per-provider classification list (e.g. `noVisionModels`). Matches the full
+ * id, OR — for Ollama-style ids — the family before the ":size" tag, so a `gpt-oss` entry covers
+ * `gpt-oss:120b`/`gpt-oss:20b`. Colon-less ids (e.g. `grok-build-0.1`) still match exactly only.
+ */
+export function modelInList(list: string[] | undefined, modelId: string): boolean {
+  if (!list || list.length === 0) return false;
+  if (list.includes(modelId)) return true;
+  const colon = modelId.indexOf(":");
+  return colon > 0 && list.includes(modelId.slice(0, colon));
+}
+
+export interface OcxRequestOptions {
+  maxOutputTokens?: number;
+  temperature?: number;
+  topP?: number;
+  stopSequences?: string[];
+  toolChoice?: "auto" | "none" | "required" | { name: string };
+  reasoning?: string;
+  hideThinkingSummary?: boolean;
+  serviceTier?: string;
+  presencePenalty?: number;
+  frequencyPenalty?: number;
+  promptCacheKey?: string;
+}
+
+export type AdapterEvent =
+  | { type: "text_delta"; text: string }
+  | { type: "thinking_delta"; thinking: string }
+  | { type: "tool_call_start"; id: string; name: string }
+  | { type: "tool_call_delta"; arguments: string }
+  | { type: "tool_call_end" }
+  | { type: "done"; usage?: OcxUsage }
+  | { type: "error"; message: string };
+
+export interface OcxUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export interface OcxConfig {
+  port: number;
+  providers: Record<string, OcxProviderConfig>;
+  defaultProvider: string;
+  /**
+   * Up to 5 routed model ids ("<provider>/<model>") to feature FIRST in the injected Codex catalog.
+   * Codex's spawn_agent only advertises the first 5 routed models, so this picks which 5 appear.
+   */
+  subagentModels?: string[];
+  /** Routed model ids ("<provider>/<model>") hidden from Codex (excluded from the catalog + /v1/models). */
+  disabledModels?: string[];
+  /** Freshness window (ms) for the per-provider live `/models` cache. Defaults to 5 min. */
+  modelCacheTtlMs?: number;
+  /** Web-search sidecar: route web_search for non-OpenAI models through a gpt-mini via ChatGPT passthrough. */
+  webSearchSidecar?: OcxWebSearchSidecarConfig;
+  /** Vision sidecar: describe images via a gpt vision model so text-only models can "see" them. */
+  visionSidecar?: OcxVisionSidecarConfig;
+}
+
+export interface OcxVisionSidecarConfig {
+  /** Master switch. Default: enabled when a forward (ChatGPT) provider exists and the caller is logged in. */
+  enabled?: boolean;
+  /** Vision model that describes images (must be a native ChatGPT model with image input). */
+  model?: string;
+  /** Sidecar fetch timeout (ms). */
+  timeoutMs?: number;
+}
+
+export interface OcxWebSearchSidecarConfig {
+  /** Master switch. Default: enabled when a forward (ChatGPT) provider exists and the caller is logged in. */
+  enabled?: boolean;
+  /** Sidecar model that runs the real server-side web_search (must be a native ChatGPT model). */
+  model?: string;
+  /** Reasoning effort for the sidecar — "minimal" (non-thinking) keeps it fast/cheap. */
+  reasoning?: string;
+  /** Max searches executed per main-model turn (loop guard). */
+  maxSearchesPerTurn?: number;
+  /** Sidecar fetch timeout (ms). */
+  timeoutMs?: number;
+}
+
+export interface OcxProviderConfig {
+  adapter: string;
+  baseUrl: string;
+  apiKey?: string;
+  defaultModel?: string;
+  models?: string[];
+  headers?: Record<string, string>;
+  /**
+   * "key" (default): authenticate upstream with `apiKey`.
+   * "forward": relay the caller's incoming auth headers verbatim (OAuth passthrough; gpt only).
+   * "oauth": resolve a stored OAuth access token (auto-refreshed) and use it as the Bearer key.
+   * Only the openai-responses adapter implements "forward"; openai-chat uses its own key/token.
+   */
+  authMode?: "key" | "forward" | "oauth";
+  /**
+   * Model ids that do NOT support a reasoning/thinking parameter. The openai-chat adapter drops
+   * reasoning_effort for these even when Codex selects a reasoning level (e.g. xAI grok-build-0.1).
+   */
+  noReasoningModels?: string[];
+  /**
+   * Model ids that do NOT accept image inputs. The proxy gives them "eyes" via the vision sidecar:
+   * attached images are described by a gpt vision model and replaced with text before the call.
+   */
+  noVisionModels?: string[];
+}

package/src/update.ts

@@ -0,0 +1,64 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const PKG = "@bitkyc08/opencodex";
+const HERE = dirname(fileURLToPath(import.meta.url)); // .../opencodex/src
+
+type Installer = "bun" | "npm" | "source";
+
+/** Infer how opencodex is installed from the running module's path. */
+function detectInstall(): Installer {
+  if (!HERE.includes("node_modules")) return "source"; // a git checkout, not a global install
+  return HERE.includes(".bun") ? "bun" : "npm";
+}
+
+function currentVersion(): string {
+  try {
+    return (JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8")).version as string) ?? "?";
+  } catch {
+    return "?";
+  }
+}
+
+/** Latest published version from the registry (best-effort; null if npm isn't available). */
+function latestVersion(): string | null {
+  const r = spawnSync("npm", ["view", PKG, "version"], { encoding: "utf8", timeout: 12000, windowsHide: true });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+/**
+ * `ocx update` — self-update opencodex to the latest published version, using the same package
+ * manager it was installed with (bun or npm global). A source checkout is told to `git pull` instead.
+ */
+export function runUpdate(): void {
+  const installer = detectInstall();
+  const current = currentVersion();
+  console.log(`opencodex v${current} (installed via ${installer})`);
+
+  if (installer === "source") {
+    console.log("Running from a source checkout — update with:  git pull && bun install");
+    return;
+  }
+
+  const latest = latestVersion();
+  if (latest && latest === current) {
+    console.log(`Already on the latest version (v${latest}).`);
+    return;
+  }
+
+  const bin = installer === "bun" ? "bun" : "npm";
+  const cmdArgs = installer === "bun"
+    ? ["add", "-g", `${PKG}@latest`]
+    : ["install", "-g", `${PKG}@latest`];
+  console.log(`Updating${latest ? ` to v${latest}` : ""}…\n$ ${bin} ${cmdArgs.join(" ")}`);
+
+  const r = spawnSync(bin, cmdArgs, { stdio: "inherit", timeout: 180000, windowsHide: true });
+  if (r.status === 0) {
+    console.log(`\n✅ Updated${latest ? ` to v${latest}` : ""}. Restart the proxy:  ocx stop && ocx start`);
+  } else {
+    console.error(`\n⚠️  Update failed (${bin} exit ${r.status ?? "?"}). Try manually:  ${bin} ${cmdArgs.join(" ")}`);
+    process.exit(1);
+  }
+}

package/src/vision/describe.ts

@@ -0,0 +1,98 @@
+import type { OcxProviderConfig } from "../types";
+import { FORWARD_HEADERS } from "../adapters/openai-responses";
+import { parseSidecarSSE } from "../web-search/parse";
+
+export interface VisionSettings {
+  model: string;
+  timeoutMs: number;
+}
+
+/** A description, or an `error` string when it couldn't run (caller injects a graceful marker). */
+export type DescribeOutcome = { text: string; error?: string };
+
+const ALLOWED_IMAGE_MIME = new Set(["image/png", "image/jpeg", "image/jpg", "image/webp", "image/gif"]);
+/** ~20 MB — generous enough for screenshots; rejects pathological payloads before forwarding. */
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+
+/**
+ * Validate an image URL before forwarding. Data URLs are checked for an allowed media type and a sane
+ * decoded size (a malformed/huge/unsupported one would otherwise 400 at the backend or waste tokens).
+ * Remote https URLs are passed through — the ChatGPT backend fetches them, not this proxy (so there's
+ * no SSRF surface here). Returns an error string when the URL must be rejected, else null.
+ */
+function validateImageUrl(url: string): string | null {
+  if (url.startsWith("data:")) {
+    const m = /^data:([^;,]+?)(;base64)?,(.*)$/s.exec(url);
+    if (!m) return "malformed data URL";
+    const mime = m[1].toLowerCase();
+    if (!ALLOWED_IMAGE_MIME.has(mime)) return `unsupported image type "${mime}"`;
+    if (m[2]) {
+      const bytes = Math.floor((m[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:)";
+}
+
+/**
+ * Describe ONE image via a gpt vision model through the ChatGPT forward backend — the path that has
+ * native image input. Reuses the caller's forwarded OAuth headers. The user's own request text is
+ * passed as context so the description is focused. Never throws — returns `{error}` on failure.
+ */
+export async function describeImage(
+  imageUrl: string,
+  detail: string | undefined,
+  contextText: string,
+  forwardProvider: OcxProviderConfig,
+  incomingHeaders: Headers,
+  settings: VisionSettings,
+): Promise<DescribeOutcome> {
+  const invalid = validateImageUrl(imageUrl);
+  if (invalid) return { text: "", error: invalid };
+
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (forwardProvider.headers) Object.assign(headers, forwardProvider.headers);
+  for (const h of FORWARD_HEADERS) {
+    const v = incomingHeaders.get(h);
+    if (v) headers[h] = v;
+  }
+  const content: unknown[] = [];
+  if (contextText) content.push({ type: "input_text", text: `The user's request about this image: ${contextText}` });
+  content.push({ type: "input_image", image_url: imageUrl, detail: detail ?? "high" });
+
+  const body = {
+    model: settings.model,
+    instructions:
+      "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.",
+    input: [{ type: "message", role: "user", content }],
+    reasoning: { effort: "low" },
+    // The ChatGPT (codex) backend rejects `max_output_tokens` ("Unsupported parameter"); the
+    // description is clamped downstream (DESC_MAX_CHARS) instead.
+    store: false,
+    stream: true,
+  };
+  try {
+    const res = await fetch(`${forwardProvider.baseUrl}/responses`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(settings.timeoutMs),
+    });
+    if (!res.ok) {
+      const t = await res.text().catch(() => "");
+      return { text: "", error: `vision sidecar HTTP ${res.status}: ${t.slice(0, 200)}` };
+    }
+    const parsed = await parseSidecarSSE(res);
+    // The backend can return HTTP 200 then stream a `response.failed`/`error` event with no text;
+    // surface that as a describe error instead of an empty (silently-blank) description.
+    if (!parsed.text.trim() && parsed.error) return { text: "", error: parsed.error };
+    return { text: parsed.text };
+  } catch (e) {
+    return { text: "", error: e instanceof Error ? e.message : String(e) };
+  }
+}

package/src/vision/index.ts

@@ -0,0 +1,141 @@
+import type { OcxConfig, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTextContent } from "../types";
+import { modelInList } from "../types";
+import { describeImage, type VisionSettings } from "./describe";
+
+export { describeImage } from "./describe";
+
+const DEFAULT_VISION_MODEL = "gpt-5.4-mini";
+const DEFAULT_TIMEOUT_MS = 45_000;
+/** Max images described in parallel — keeps first-token latency bounded without flooding the backend. */
+const VISION_CONCURRENCY = 3;
+/** Per-image description hard cap (chars) so multi-image turns can't blow the main model's context. */
+const DESC_MAX_CHARS = 2000;
+/** User-text context passed to the describer, capped. */
+const CONTEXT_MAX_CHARS = 800;
+
+/** Run `worker` over `items` with bounded concurrency, preserving input order in the result array. */
+async function runBounded<T, R>(items: T[], limit: number, worker: (item: T) => Promise<R>): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let next = 0;
+  const runner = async (): Promise<void> => {
+    while (next < items.length) {
+      const i = next++;
+      results[i] = await worker(items[i]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, runner));
+  return results;
+}
+
+function clamp(s: string, max: number): string {
+  return s.length <= max ? s : `${s.slice(0, max)}\n…[description truncated]`;
+}
+
+/** First configured forward (ChatGPT passthrough) provider — the path with native image input. */
+function findForwardProvider(config: OcxConfig): OcxProviderConfig | undefined {
+  for (const prov of Object.values(config.providers)) {
+    if (prov.authMode === "forward") return prov;
+  }
+  return undefined;
+}
+
+/** A user/developer/toolResult message can carry images (toolResult: e.g. Codex view_image output). */
+function carriesImages(role: string): boolean {
+  return role === "user" || role === "developer" || role === "toolResult";
+}
+
+function messagesHaveImage(parsed: OcxParsedRequest): boolean {
+  return parsed.context.messages.some(m =>
+    carriesImages(m.role) && Array.isArray(m.content) && (m.content as OcxContentPart[]).some(p => p.type === "image"));
+}
+
+export interface VisionPlan {
+  forwardProvider: OcxProviderConfig;
+  settings: VisionSettings;
+}
+
+/**
+ * Decide whether the vision sidecar should pre-describe images for this request, returning the plan
+ * if so. Active when: the routed model is in `provider.noVisionModels`, the request actually carries
+ * an image, a forward provider exists, the sidecar isn't disabled, and the caller forwarded ChatGPT
+ * auth. Returns undefined otherwise (the request takes the normal path — images sent natively).
+ */
+export function planVisionSidecar(
+  config: OcxConfig,
+  provider: OcxProviderConfig,
+  modelId: string,
+  parsed: OcxParsedRequest,
+  incomingHeaders: Headers,
+): VisionPlan | undefined {
+  if (!modelInList(provider.noVisionModels, modelId)) return undefined;
+  if (!messagesHaveImage(parsed)) return undefined;
+  const cfg = config.visionSidecar ?? {};
+  if (cfg.enabled === false) return undefined;
+  if (!incomingHeaders.get("authorization")) return undefined;
+  const forwardProvider = findForwardProvider(config);
+  if (!forwardProvider) return undefined;
+  return {
+    forwardProvider,
+    settings: { model: cfg.model ?? DEFAULT_VISION_MODEL, timeoutMs: cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS },
+  };
+}
+
+interface ImageJob {
+  imageUrl: string;
+  detail?: string;
+  contextText: string;
+}
+
+/** Render one describe outcome as the replacement text part (clamped to the per-image budget). */
+function renderDescription(out: { text: string; error?: string }): OcxTextContent {
+  return {
+    type: "text",
+    text: out.error
+      ? `[An image was attached but could not be processed: ${out.error}]`
+      : `[Image content — described by a vision model because you cannot see images directly:\n${clamp(out.text.trim(), DESC_MAX_CHARS)}]`,
+  };
+}
+
+/**
+ * Replace every image part in the request with a gpt-described text part, so a text-only model can
+ * reason about it. Mutates `parsed.context.messages` in place; uses the message's own text as the
+ * description context. All images are described with bounded concurrency (not serially) so a
+ * multi-image turn doesn't pay the sum of per-image latencies. Failures degrade to a short marker.
+ */
+export async function describeImagesInPlace(
+  parsed: OcxParsedRequest,
+  forwardProvider: OcxProviderConfig,
+  incomingHeaders: Headers,
+  settings: VisionSettings,
+): Promise<void> {
+  // 1. Gather every image part across messages, each with its own message's text as context.
+  const jobs: ImageJob[] = [];
+  const targets: { msg: OcxMessage; parts: OcxContentPart[] }[] = [];
+  for (const msg of parsed.context.messages) {
+    if (!carriesImages(msg.role) || !Array.isArray(msg.content)) continue;
+    const parts = msg.content as OcxContentPart[];
+    if (!parts.some(p => p.type === "image")) continue;
+    const contextText = parts
+      .filter((p): p is OcxTextContent => p.type === "text")
+      .map(p => p.text)
+      .join(" ")
+      .slice(0, CONTEXT_MAX_CHARS);
+    for (const p of parts) {
+      if (p.type === "image") jobs.push({ imageUrl: p.imageUrl, detail: p.detail, contextText });
+    }
+    targets.push({ msg, parts });
+  }
+  if (jobs.length === 0) return;
+
+  // 2. Describe all images with bounded concurrency (order preserved).
+  const outcomes = await runBounded(jobs, VISION_CONCURRENCY, j =>
+    describeImage(j.imageUrl, j.detail, j.contextText, forwardProvider, incomingHeaders, settings));
+
+  // 3. Rebuild each message, replacing image parts with their descriptions in order.
+  let oi = 0;
+  for (const { msg, parts } of targets) {
+    const newParts: OcxContentPart[] = [];
+    for (const p of parts) newParts.push(p.type === "image" ? renderDescription(outcomes[oi++]) : p);
+    msg.content = newParts;
+  }
+}

package/src/web-search/executor.ts

@@ -0,0 +1,75 @@
+import type { OcxProviderConfig } from "../types";
+import { FORWARD_HEADERS } from "../adapters/openai-responses";
+import { parseSidecarSSE, type WebSearchResult } from "./parse";
+
+export interface SidecarSettings {
+  model: string;
+  reasoning: string;
+  timeoutMs: number;
+  /**
+   * True when the routed (downstream) model is text-only. The search model CAN see images, so it's
+   * told to verbalize any relevant image results and include their URLs — otherwise a non-vision model
+   * would receive bare image links it cannot interpret (the image-web-search gap).
+   */
+  describeImages?: boolean;
+}
+
+const BASE_INSTRUCTION =
+  "You are a web-search assistant. Use the web_search tool to find current information for the " +
+  "user's query, then reply with a concise, factual answer and cite the sources you used.";
+const IMAGE_INSTRUCTION =
+  " The model that will read your answer is TEXT-ONLY and cannot see images: if the results include " +
+  "relevant images, describe what they show in words and include their source URLs in your answer.";
+
+/** A search result, or an `error` string when the search couldn't run (surfaced as a tool result). */
+export type SidecarOutcome = WebSearchResult & { error?: string };
+
+/**
+ * Execute ONE web search via the gpt-mini sidecar through the ChatGPT forward backend — the only path
+ * with a real server-side web_search. Reuses the caller's forwarded OAuth headers (the forward adapter
+ * has no key of its own), replays the hosted web_search tool config verbatim, and runs the mini at
+ * minimal reasoning. Never throws — returns `{error}` so the caller injects a graceful tool result.
+ */
+export async function runWebSearch(
+  query: string,
+  hostedTool: Record<string, unknown>,
+  forwardProvider: OcxProviderConfig,
+  incomingHeaders: Headers,
+  settings: SidecarSettings,
+): Promise<SidecarOutcome> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (forwardProvider.headers) Object.assign(headers, forwardProvider.headers);
+  for (const h of FORWARD_HEADERS) {
+    const v = incomingHeaders.get(h);
+    if (v) headers[h] = v;
+  }
+  const body = {
+    model: settings.model,
+    instructions: settings.describeImages ? BASE_INSTRUCTION + IMAGE_INSTRUCTION : BASE_INSTRUCTION,
+    input: [{ type: "message", role: "user", content: [{ type: "input_text", text: query }] }],
+    tools: [hostedTool],
+    tool_choice: "auto",
+    reasoning: { effort: settings.reasoning },
+    // NOTE: the ChatGPT (codex) backend rejects `max_output_tokens` ("Unsupported parameter") and
+    // requires `store: false` — keep this body minimal. Answer length is capped downstream
+    // (format-result clamps the injected tool_result), so no upstream cap is needed.
+    store: false,
+    stream: true,
+  };
+  const url = `${forwardProvider.baseUrl}/responses`;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(settings.timeoutMs),
+    });
+    if (!res.ok) {
+      const t = await res.text().catch(() => "");
+      return { text: "", sources: [], error: `sidecar HTTP ${res.status}: ${t.slice(0, 200)}` };
+    }
+    return await parseSidecarSSE(res);
+  } catch (e) {
+    return { text: "", sources: [], error: e instanceof Error ? e.message : String(e) };
+  }
+}