@monotykamary/pi-better-openai 0.1.25 → 0.1.26

package/README.md

@@ -34,11 +34,13 @@ Usage display, image generation, and live voice require pi's `openai-codex` OAut
 - Interactive settings picker via `/openai-settings`.
 - Footer customization for model, thinking, fast mode, usage, and token/cost context.
 - OpenAI image generation/editing through the `openai_image` tool and `/openai-image` command.
+- Live web search through the `openai_websearch` tool and `/openai-websearch` command, backed by the ChatGPT Codex search backend.
 - Codex-backed realtime voice through `/live`, with an animated microphone waveform and coding-task delegation into the active pi session.
 - Animated Codex custom pets rendered in the Better OpenAI footer.
 - Commands:
   - `/fast` toggles fast mode.
   - `/openai-image <prompt>` generates an image directly.
+  - `/openai-websearch <query>` searches the web and inserts the cited answer into the session.
   - `/live` starts or stops realtime voice mode. `Ctrl+Shift+L` is the keyboard toggle.
   - `/pets [help|list|wake [slug]|tuck|select <slug>]` renders or manages custom pets from `${CODEX_HOME:-~/.codex}/pets`.
   - `/openai-usage` shows current OpenAI subscription usage.
@@ -151,6 +153,31 @@ Save modes:
 
 The repository ignores `.pi/`, so generated images and local config should not be committed.
 
+## Web search
+
+Use the command for a quick search:
+
+```text
+/openai-websearch latest tanstack query release
+```
+
+Agents can call the `openai_websearch` tool directly. Supported parameters:
+
+- `query` (required): the web search query.
+- `responseLength`: `short`, `medium`, or `long`. Defaults to the configured value.
+
+The tool returns a synthesized answer plus cited source URLs. It calls the
+undocumented `chatgpt.com/backend-api/codex/alpha/search` endpoint with your ChatGPT
+OAuth credentials (`openai-codex` login), so it can change or break without notice;
+OAuth/API-key-only setups without ChatGPT login are not supported.
+
+Settings under `websearch` in the config file or the `/openai-settings` picker:
+
+- `enabled` (default `true`), `model` (default `gpt-5.6-luna`),
+  `reasoningEffort` (default `max`), `responseLength` (default `short`),
+  `maxOutputTokens` (default `4096`, clamped to 256-100000), and
+  `timeoutMs` (default `25000`, clamped to 5000-120000).
+
 ## Codex pets
 
 Codex pets are an OpenAI Codex app feature, so the floating overlay and pet picker are still controlled by Codex (`Settings → Appearance → Pets` or `/pet`). This extension can also render compatible custom pet spritesheets directly in pi's Better OpenAI footer.

package/index.ts

@@ -24,10 +24,12 @@ import {
   DEFAULT_LIVE_CONFIG,
   DEFAULT_PET_CONFIG,
   DEFAULT_SUPPORTED_MODELS,
+  DEFAULT_WEBSEARCH_CONFIG,
   PET_STATES,
   FOOTER_SETTING_DESCRIPTORS,
   USAGE_SETTING_DESCRIPTORS,
   IMAGE_SETTING_DESCRIPTORS,
+  WEBSEARCH_SETTING_DESCRIPTORS,
   LIVE_SETTING_DESCRIPTORS,
   PET_SETTING_DESCRIPTORS,
   FAST_SETTING_DESCRIPTORS,
@@ -51,6 +53,7 @@ import {
   readCodexAuth,
 } from "./src/usage.ts";
 import { registerOpenAIImage, _imageTest } from "./src/image.ts";
+import { registerOpenAIWebSearch, _websearchTest } from "./src/websearch.ts";
 import { registerOpenAILive } from "./src/live/index.ts";
 import {
   type CodexPetPackage,
@@ -296,6 +299,8 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
       "",
       `Image enabled: ${cfg.image.enabled}`,
       `Image default save: ${cfg.image.defaultSave}`,
+      `Websearch enabled: ${cfg.websearch.enabled}`,
+      `Websearch model: ${cfg.websearch.model} (${cfg.websearch.reasoningEffort}/${cfg.websearch.responseLength}, ${cfg.websearch.maxOutputTokens} tokens, ${cfg.websearch.timeoutMs}ms)`,
       `Live enabled: ${cfg.live.enabled}`,
       `Live voice: ${cfg.live.voice}`,
       `Pet enabled: ${cfg.pets.enabled}`,
@@ -538,6 +543,12 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
       : "disabled";
   }
 
+  function websearchSettingsSummary(cfg: ResolvedConfig): string {
+    return cfg.websearch.enabled
+      ? `enabled · ${cfg.websearch.model} · ${cfg.websearch.reasoningEffort}/${cfg.websearch.responseLength}`
+      : "disabled";
+  }
+
   function liveSettingsSummary(cfg: ResolvedConfig): string {
     return cfg.live.enabled ? `enabled · ${cfg.live.voice}` : "disabled";
   }
@@ -596,6 +607,10 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
     return settingsItemsFromDescriptors(IMAGE_SETTING_DESCRIPTORS, cfg);
   }
 
+  function buildWebsearchSettingsItems(cfg: ResolvedConfig): SettingsPickerItem[] {
+    return settingsItemsFromDescriptors(WEBSEARCH_SETTING_DESCRIPTORS, cfg);
+  }
+
   function buildLiveSettingsItems(cfg: ResolvedConfig): SettingsPickerItem[] {
     return settingsItemsFromDescriptors(LIVE_SETTING_DESCRIPTORS, cfg);
   }
@@ -690,6 +705,19 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
             () => done(imageSettingsSummary(config(ctx))),
           ),
       },
+      {
+        id: "section.websearch",
+        label: "Web search tool",
+        currentValue: websearchSettingsSummary(cfg),
+        description: "Configure ChatGPT Codex web search defaults.",
+        submenu: (_value, done) =>
+          settingsSubmenu(
+            "Web search tool settings",
+            () => buildWebsearchSettingsItems(config(ctx)),
+            ctx,
+            () => done(websearchSettingsSummary(config(ctx))),
+          ),
+      },
       {
         id: "section.live",
         label: "Live voice",
@@ -854,6 +882,7 @@ export default function betterOpenAI(pi: ExtensionAPI): void {
   });
 
   registerOpenAIImage(pi, config);
+  registerOpenAIWebSearch(pi, config);
   registerOpenAILive(pi, config);
   registerOpenAIPets(pi, {
     wake: async (ctx, slug) => {
@@ -1302,6 +1331,7 @@ export const _test = {
   DEFAULT_IMAGE_CONFIG,
   DEFAULT_LIVE_CONFIG,
   DEFAULT_PET_CONFIG,
+  DEFAULT_WEBSEARCH_CONFIG,
   SERVICE_TIER,
   configPaths,
   abbreviateHomePath,
@@ -1324,5 +1354,6 @@ export const _test = {
   readCodexAuth,
   textPanel,
   imageTest: _imageTest,
+  websearchTest: _websearchTest,
   petsTest: _petsTest,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monotykamary/pi-better-openai",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Improve OpenAI in pi with fast mode, usage stats, realtime voice, image generation, and footer polish.",
   "keywords": [
     "fast",

package/src/config.ts

@@ -13,6 +13,8 @@ import { piAgentDir } from "./paths.ts";
 export const FOOTER_MODES = ["replace", "status", "off"] as const;
 export const IMAGE_SAVE_MODES = ["none", "project", "global", "custom"] as const;
 export const IMAGE_OUTPUT_FORMATS = ["png", "jpeg", "webp"] as const;
+export const WEBSEARCH_REASONING_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
+export const WEBSEARCH_RESPONSE_LENGTHS = ["short", "medium", "long"] as const;
 export const PET_PLACEMENTS = [
   "stacked",
   "inline-left",
@@ -45,6 +47,8 @@ export const DEFAULT_SUPPORTED_MODELS = [
 export type FooterMode = (typeof FOOTER_MODES)[number];
 export type ImageSaveMode = (typeof IMAGE_SAVE_MODES)[number];
 export type ImageOutputFormat = (typeof IMAGE_OUTPUT_FORMATS)[number];
+export type WebsearchReasoningEffort = (typeof WEBSEARCH_REASONING_EFFORTS)[number];
+export type WebsearchResponseLength = (typeof WEBSEARCH_RESPONSE_LENGTHS)[number];
 export type PetPlacement = (typeof PET_PLACEMENTS)[number];
 export type PetState = (typeof PET_STATES)[number];
 
@@ -67,6 +71,15 @@ export type ImageConfig = {
   timeoutMs?: number;
 };
 
+export type WebsearchConfig = {
+  enabled?: boolean;
+  model?: string;
+  reasoningEffort?: WebsearchReasoningEffort;
+  responseLength?: WebsearchResponseLength;
+  maxOutputTokens?: number;
+  timeoutMs?: number;
+};
+
 export type LiveConfig = {
   enabled?: boolean;
   voice?: LiveVoice;
@@ -93,6 +106,7 @@ export interface ConfigFile {
   usage?: UsageConfig;
   footer?: FooterConfig;
   image?: ImageConfig;
+  websearch?: WebsearchConfig;
   live?: LiveConfig;
   pets?: PetConfig;
 }
@@ -115,6 +129,7 @@ export interface ResolvedConfig {
   usage: Required<UsageConfig>;
   footer: Required<FooterConfig>;
   image: Required<ImageConfig>;
+  websearch: Required<WebsearchConfig>;
   live: Required<LiveConfig>;
   pets: Required<PetConfig>;
 }
@@ -140,6 +155,17 @@ export const DEFAULT_IMAGE_CONFIG: Required<ImageConfig> = {
   timeoutMs: 180_000,
 };
 
+export const DEFAULT_WEBSEARCH_MODEL = "gpt-5.6-luna";
+
+export const DEFAULT_WEBSEARCH_CONFIG: Required<WebsearchConfig> = {
+  enabled: true,
+  model: DEFAULT_WEBSEARCH_MODEL,
+  reasoningEffort: "max",
+  responseLength: "short",
+  maxOutputTokens: 4096,
+  timeoutMs: 25_000,
+};
+
 export const DEFAULT_LIVE_CONFIG: Required<LiveConfig> = {
   enabled: true,
   voice: DEFAULT_LIVE_VOICE,
@@ -166,11 +192,19 @@ export const DEFAULT_CONFIG: ConfigFile = {
   usage: DEFAULT_USAGE_CONFIG,
   footer: DEFAULT_FOOTER_CONFIG,
   image: DEFAULT_IMAGE_CONFIG,
+  websearch: DEFAULT_WEBSEARCH_CONFIG,
   live: DEFAULT_LIVE_CONFIG,
   pets: DEFAULT_PET_CONFIG,
 };
 
-export type SettingsOptionSection = "root" | "usage" | "footer" | "image" | "live" | "pets";
+export type SettingsOptionSection =
+  | "root"
+  | "usage"
+  | "footer"
+  | "image"
+  | "websearch"
+  | "live"
+  | "pets";
 
 export type SettingsValueContext = {
   petEmptyValue?: string;
@@ -314,6 +348,69 @@ export const IMAGE_SETTING_DESCRIPTORS: readonly SettingsOptionDescriptor[] = [
   },
 ];
 
+export const WEBSEARCH_SETTING_DESCRIPTORS: readonly SettingsOptionDescriptor[] = [
+  {
+    id: "websearch.enabled",
+    section: "websearch",
+    key: "enabled",
+    label: "Web search tool",
+    currentValue: (cfg) => String(cfg.websearch.enabled),
+    values: ["true", "false"],
+    description: "Allow the openai_websearch tool to make search requests.",
+    parse: booleanSetting,
+  },
+  {
+    id: "websearch.model",
+    section: "websearch",
+    key: "model",
+    label: "Search model",
+    currentValue: (cfg) => cfg.websearch.model,
+    values: ["gpt-5.6-luna"],
+    description: "Model used by the ChatGPT Codex search backend.",
+    parse: stringSetting,
+  },
+  {
+    id: "websearch.reasoningEffort",
+    section: "websearch",
+    key: "reasoningEffort",
+    label: "Search reasoning",
+    currentValue: (cfg) => cfg.websearch.reasoningEffort,
+    values: WEBSEARCH_REASONING_EFFORTS,
+    description: "Reasoning effort requested from the search backend.",
+    parse: stringSetting,
+  },
+  {
+    id: "websearch.responseLength",
+    section: "websearch",
+    key: "responseLength",
+    label: "Answer length",
+    currentValue: (cfg) => cfg.websearch.responseLength,
+    values: WEBSEARCH_RESPONSE_LENGTHS,
+    description: "Default answer length produced by the search backend.",
+    parse: stringSetting,
+  },
+  {
+    id: "websearch.maxOutputTokens",
+    section: "websearch",
+    key: "maxOutputTokens",
+    label: "Max output tokens",
+    currentValue: (cfg) => String(cfg.websearch.maxOutputTokens),
+    values: ["1024", "2048", "4096", "8192"],
+    description: "Maximum output tokens for a search request.",
+    parse: numberSetting,
+  },
+  {
+    id: "websearch.timeoutMs",
+    section: "websearch",
+    key: "timeoutMs",
+    label: "Search timeout",
+    currentValue: (cfg) => String(cfg.websearch.timeoutMs),
+    values: ["10000", "25000", "60000", "120000"],
+    description: "Web search request timeout in milliseconds.",
+    parse: numberSetting,
+  },
+];
+
 export const LIVE_SETTING_DESCRIPTORS: readonly SettingsOptionDescriptor[] = [
   {
     id: "live.enabled",
@@ -446,6 +543,7 @@ export const SETTINGS_OPTION_DESCRIPTORS: readonly SettingsOptionDescriptor[] =
   ...FOOTER_SETTING_DESCRIPTORS,
   ...USAGE_SETTING_DESCRIPTORS,
   ...IMAGE_SETTING_DESCRIPTORS,
+  ...WEBSEARCH_SETTING_DESCRIPTORS,
   ...LIVE_SETTING_DESCRIPTORS,
   ...PET_SETTING_DESCRIPTORS,
 ];
@@ -553,6 +651,28 @@ export function readConfig(path: string): ConfigFile | undefined {
       config.image.outputFormat = parsed.image.outputFormat as ImageOutputFormat;
     if (typeof parsed.image.timeoutMs === "number") config.image.timeoutMs = parsed.image.timeoutMs;
   }
+  if (isRecord(parsed.websearch)) {
+    config.websearch = {};
+    if (typeof parsed.websearch.enabled === "boolean")
+      config.websearch.enabled = parsed.websearch.enabled;
+    if (typeof parsed.websearch.model === "string" && parsed.websearch.model.trim())
+      config.websearch.model = parsed.websearch.model.trim();
+    if (
+      typeof parsed.websearch.reasoningEffort === "string" &&
+      (WEBSEARCH_REASONING_EFFORTS as readonly string[]).includes(parsed.websearch.reasoningEffort)
+    )
+      config.websearch.reasoningEffort = parsed.websearch
+        .reasoningEffort as WebsearchReasoningEffort;
+    if (
+      typeof parsed.websearch.responseLength === "string" &&
+      (WEBSEARCH_RESPONSE_LENGTHS as readonly string[]).includes(parsed.websearch.responseLength)
+    )
+      config.websearch.responseLength = parsed.websearch.responseLength as WebsearchResponseLength;
+    if (typeof parsed.websearch.maxOutputTokens === "number")
+      config.websearch.maxOutputTokens = parsed.websearch.maxOutputTokens;
+    if (typeof parsed.websearch.timeoutMs === "number")
+      config.websearch.timeoutMs = parsed.websearch.timeoutMs;
+  }
   if (isRecord(parsed.live)) {
     config.live = {};
     if (typeof parsed.live.enabled === "boolean") config.live.enabled = parsed.live.enabled;
@@ -701,6 +821,29 @@ export function resolveConfig(cwd: string): ResolvedConfig {
         ),
       ),
     },
+    websearch: {
+      ...DEFAULT_WEBSEARCH_CONFIG,
+      ...globalConfig.websearch,
+      ...projectConfig.websearch,
+      maxOutputTokens: Math.max(
+        256,
+        Math.min(
+          100_000,
+          projectConfig.websearch?.maxOutputTokens ??
+            globalConfig.websearch?.maxOutputTokens ??
+            DEFAULT_WEBSEARCH_CONFIG.maxOutputTokens,
+        ),
+      ),
+      timeoutMs: Math.max(
+        5_000,
+        Math.min(
+          120_000,
+          projectConfig.websearch?.timeoutMs ??
+            globalConfig.websearch?.timeoutMs ??
+            DEFAULT_WEBSEARCH_CONFIG.timeoutMs,
+        ),
+      ),
+    },
     live: {
       ...DEFAULT_LIVE_CONFIG,
       ...globalConfig.live,

package/src/websearch.ts

@@ -0,0 +1,446 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Box, Container, Text } from "@earendil-works/pi-tui";
+import {
+  isRecord,
+  WEBSEARCH_RESPONSE_LENGTHS,
+  type ResolvedConfig,
+  type WebsearchResponseLength,
+} from "./config.ts";
+import { getCodexCredentials, type CodexCredentialsWithSource } from "./codex-auth.ts";
+import { maskIdentifier, sanitizeDiagnosticError } from "./format.ts";
+
+export const OPENAI_WEBSEARCH_TOOL = "openai_websearch";
+export const OPENAI_WEBSEARCH_COMMAND = "openai-websearch";
+export const CODEX_SEARCH_URL = "https://chatgpt.com/backend-api/codex/alpha/search";
+export const SEARCH_ORIGINATOR = "codex_cli_rs";
+export const MAX_QUERY_BYTES = 8 * 1024;
+export const MAX_RESPONSE_BYTES = 256 * 1024;
+export const MAX_TEXT_SOURCES = 10;
+
+export type WebSearchErrorCode =
+  | "authentication_required"
+  | "authentication_failed"
+  | "invalid_query"
+  | "request_failed"
+  | "request_timeout"
+  | "request_aborted"
+  | "response_too_large"
+  | "invalid_response";
+
+export class WebSearchError extends Error {
+  readonly code: WebSearchErrorCode;
+
+  constructor(code: WebSearchErrorCode, message: string) {
+    super(message);
+    this.name = "WebSearchError";
+    this.code = code;
+  }
+}
+
+export type WebSearchResult = {
+  url: string;
+  title?: string;
+  content?: string;
+};
+
+export type WebSearchAnswer = {
+  answer: string;
+  results: WebSearchResult[];
+};
+
+type ToolParams = {
+  query: string;
+  responseLength?: WebsearchResponseLength;
+};
+
+const TOOL_PARAMS = {
+  type: "object",
+  properties: {
+    query: {
+      type: "string",
+      description: "The web search query. Pass the user's information need verbatim.",
+    },
+    responseLength: {
+      type: "string",
+      enum: WEBSEARCH_RESPONSE_LENGTHS,
+      description:
+        "Answer length produced by the search backend. Defaults to the configured value.",
+    },
+  },
+  required: ["query"],
+  additionalProperties: false,
+} as const;
+
+export type WebSearchDebug = {
+  authFound: boolean;
+  authSource?: string;
+  accountId?: string;
+  endpoint: string;
+  model: string;
+  reasoningEffort: string;
+  enabled: boolean;
+  lastStatus?: string;
+  lastError?: string;
+};
+
+async function getCredentials(
+  ctx: ExtensionContext,
+  signal?: AbortSignal,
+): Promise<CodexCredentialsWithSource> {
+  const credentials = await getCodexCredentials(ctx, signal);
+  if (credentials) return credentials;
+  throw new WebSearchError(
+    "authentication_required",
+    "Missing openai-codex OAuth credentials. Run /login openai-codex.",
+  );
+}
+
+export function validateSearchQuery(query: string): string {
+  const value = query.trim();
+  if (!value) throw new WebSearchError("invalid_query", "Web search requires a non-empty query.");
+  if (new TextEncoder().encode(value).byteLength > MAX_QUERY_BYTES) {
+    throw new WebSearchError(
+      "invalid_query",
+      `Web search query exceeded ${MAX_QUERY_BYTES} UTF-8 bytes.`,
+    );
+  }
+  return value;
+}
+
+export function buildSearchRequestBody(
+  query: string,
+  cfg: ResolvedConfig["websearch"],
+  responseLength: WebsearchResponseLength,
+  id: string,
+): Record<string, unknown> {
+  return {
+    id,
+    model: cfg.model,
+    reasoning: { effort: cfg.reasoningEffort },
+    input: query,
+    commands: {
+      search_query: [{ q: query }],
+      response_length: responseLength,
+    },
+    settings: {
+      allowed_callers: ["direct"],
+      external_web_access: true,
+    },
+    max_output_tokens: cfg.maxOutputTokens,
+  };
+}
+
+export function buildSearchHeaders(
+  credentials: CodexCredentialsWithSource,
+): Record<string, string> {
+  return {
+    authorization: `Bearer ${credentials.accessToken}`,
+    "chatgpt-account-id": credentials.accountId,
+    accept: "application/json",
+    "content-type": "application/json",
+    originator: SEARCH_ORIGINATOR,
+    "User-Agent": "codex_cli_rs/0.0.0 (pi-better-openai)",
+  };
+}
+
+function trimmedText(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function isSafeUrl(value: string): boolean {
+  try {
+    const protocol = new URL(value).protocol;
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+export function parseSearchResponse(body: string): WebSearchAnswer {
+  let value: unknown;
+  try {
+    value = JSON.parse(body);
+  } catch {
+    throw new WebSearchError("invalid_response", "ChatGPT web search returned invalid JSON.");
+  }
+  if (!isRecord(value) || typeof value.output !== "string") {
+    throw new WebSearchError(
+      "invalid_response",
+      "ChatGPT web search returned an invalid response.",
+    );
+  }
+  if (value.results === undefined || value.results === null) {
+    throw new WebSearchError(
+      "invalid_response",
+      "ChatGPT web search did not return structured citations; the alpha protocol may have changed.",
+    );
+  }
+  if (!Array.isArray(value.results)) {
+    throw new WebSearchError("invalid_response", "ChatGPT web search returned invalid results.");
+  }
+  const results = value.results.flatMap((result): WebSearchResult[] => {
+    if (!isRecord(result) || result.type !== "text_result" || typeof result.url !== "string")
+      return [];
+    if (!isSafeUrl(result.url)) return [];
+    const title = trimmedText(result.title);
+    const content = trimmedText(result.snippet);
+    return [{ url: result.url, ...(title ? { title } : {}), ...(content ? { content } : {}) }];
+  });
+  return { answer: value.output.trim(), results };
+}
+
+async function readBoundedResponse(response: Response): Promise<string> {
+  const declared = response.headers.get("content-length");
+  if (declared && /^\d+$/.test(declared) && Number(declared) > MAX_RESPONSE_BYTES) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new WebSearchError(
+      "response_too_large",
+      `ChatGPT web search response exceeded ${MAX_RESPONSE_BYTES} bytes.`,
+    );
+  }
+  if (!response.body) return "";
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const item = await reader.read();
+      if (item.done) break;
+      size += item.value.byteLength;
+      if (size > MAX_RESPONSE_BYTES) {
+        await reader.cancel().catch(() => undefined);
+        throw new WebSearchError(
+          "response_too_large",
+          `ChatGPT web search response exceeded ${MAX_RESPONSE_BYTES} bytes.`,
+        );
+      }
+      chunks.push(item.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const body = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(body);
+}
+
+export function formatSearchText(query: string, answer: WebSearchAnswer): string {
+  const lines: string[] = [];
+  if (answer.answer) lines.push(answer.answer, "");
+  const sources = answer.results.slice(0, MAX_TEXT_SOURCES);
+  if (sources.length > 0) {
+    lines.push("Sources:");
+    sources.forEach((result, index) => {
+      lines.push(`${index + 1}. [${result.title ?? result.url}](${result.url})`);
+      if (result.content) lines.push(`   ${result.content}`);
+    });
+  }
+  if (lines.length === 0) return `No web results found for "${query}".`;
+  return lines.join("\n").trim();
+}
+
+async function requestWebSearch(
+  params: ToolParams,
+  ctx: ExtensionContext,
+  cfg: ResolvedConfig,
+  requestSignal?: AbortSignal,
+): Promise<{ query: string; answer: WebSearchAnswer; model: string }> {
+  if (!cfg.websearch.enabled) throw new Error("OpenAI web search is disabled in config.");
+  const query = validateSearchQuery(String(params.query ?? ""));
+  const responseLength = params.responseLength ?? cfg.websearch.responseLength;
+  const timeoutSignal = AbortSignal.timeout(cfg.websearch.timeoutMs);
+  const baseSignal = requestSignal ?? ctx.signal;
+  const signal = baseSignal ? AbortSignal.any([baseSignal, timeoutSignal]) : timeoutSignal;
+  const credentials = await getCredentials(ctx, signal);
+
+  let response: Response;
+  try {
+    response = await fetch(CODEX_SEARCH_URL, {
+      method: "POST",
+      headers: buildSearchHeaders(credentials),
+      body: JSON.stringify(
+        buildSearchRequestBody(query, cfg.websearch, responseLength, crypto.randomUUID()),
+      ),
+      signal,
+      redirect: "error",
+      credentials: "omit",
+      cache: "no-store",
+      referrerPolicy: "no-referrer",
+    });
+  } catch (error) {
+    if (error instanceof WebSearchError) throw error;
+    if (baseSignal?.aborted)
+      throw new WebSearchError("request_aborted", "ChatGPT web search was aborted.");
+    if (timeoutSignal.aborted)
+      throw new WebSearchError(
+        "request_timeout",
+        `ChatGPT web search timed out after ${cfg.websearch.timeoutMs}ms.`,
+      );
+    throw new WebSearchError(
+      "request_failed",
+      `ChatGPT web search request failed: ${sanitizeDiagnosticError(error instanceof Error ? error.message : String(error))}`,
+    );
+  }
+
+  if (response.url && new URL(response.url).origin !== new URL(CODEX_SEARCH_URL).origin) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new WebSearchError(
+      "request_failed",
+      "ChatGPT web search returned from an unexpected origin.",
+    );
+  }
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => undefined);
+    if (response.status === 401 || response.status === 403) {
+      throw new WebSearchError(
+        "authentication_failed",
+        `ChatGPT web search authentication failed (HTTP ${response.status}). Reconnect with /login openai-codex.`,
+      );
+    }
+    throw new WebSearchError(
+      "request_failed",
+      `ChatGPT web search failed (HTTP ${response.status}).`,
+    );
+  }
+
+  const parsed = parseSearchResponse(await readBoundedResponse(response));
+  return { query, answer: parsed, model: cfg.websearch.model };
+}
+
+export function registerOpenAIWebSearch(
+  pi: ExtensionAPI,
+  getConfig: (ctx: ExtensionContext) => ResolvedConfig,
+): { getDebug: (ctx: ExtensionContext) => Promise<WebSearchDebug> } {
+  let lastStatus: string | undefined;
+  let lastError: string | undefined;
+
+  async function search(
+    params: ToolParams,
+    ctx: ExtensionContext,
+    requestSignal?: AbortSignal,
+  ): Promise<{ text: string; details: Record<string, unknown> }> {
+    try {
+      lastStatus = "requesting";
+      lastError = undefined;
+      const result = await requestWebSearch(params, ctx, getConfig(ctx), requestSignal);
+      lastStatus = `completed (${result.answer.results.length} sources)`;
+      return {
+        text: formatSearchText(result.query, result.answer),
+        details: {
+          query: result.query,
+          answer: result.answer.answer,
+          results: result.answer.results,
+          model: result.model,
+        },
+      };
+    } catch (error) {
+      lastStatus = "error";
+      lastError = sanitizeDiagnosticError(error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+  }
+
+  async function getDebug(ctx: ExtensionContext): Promise<WebSearchDebug> {
+    const cfg = getConfig(ctx);
+    let credentials: CodexCredentialsWithSource | undefined;
+    try {
+      credentials = await getCredentials(ctx);
+    } catch {
+      credentials = undefined;
+    }
+    return {
+      authFound: credentials !== undefined,
+      authSource: credentials?.source,
+      accountId: maskIdentifier(credentials?.accountId),
+      endpoint: CODEX_SEARCH_URL,
+      model: cfg.websearch.model,
+      reasoningEffort: cfg.websearch.reasoningEffort,
+      enabled: cfg.websearch.enabled,
+      lastStatus,
+      lastError,
+    };
+  }
+
+  pi.registerMessageRenderer("openai-websearch", (message, _options, theme) => {
+    const text = Array.isArray(message.content)
+      ? message.content
+          .filter((part): part is { type: "text"; text: string } => part.type === "text")
+          .map((part) => part.text)
+          .join("\n")
+      : String(message.content ?? "");
+    const container = new Container();
+    const box = new Box(1, 1, (line) => theme.bg("customMessageBg", line));
+    box.addChild(
+      new Text(`${theme.fg("accent", theme.bold("[openai-websearch]"))}\n\n${text}`, 0, 0),
+    );
+    container.addChild(box);
+    return container;
+  });
+
+  pi.registerCommand(OPENAI_WEBSEARCH_COMMAND, {
+    description: "Search the web with the ChatGPT Codex search backend",
+    handler: async (args, ctx) => {
+      const query = args.trim();
+      if (!query) {
+        ctx.ui.notify("Usage: /openai-websearch <query>", "error");
+        return;
+      }
+      ctx.ui.notify("Searching the web via ChatGPT...", "info");
+      const result = await search({ query }, ctx);
+      pi.sendMessage({
+        customType: "openai-websearch",
+        content: [{ type: "text", text: result.text }],
+        display: true,
+        details: result.details,
+      });
+    },
+  });
+
+  pi.registerTool({
+    name: OPENAI_WEBSEARCH_TOOL,
+    label: "OpenAI web search",
+    description:
+      "Search the live web through the ChatGPT Codex search backend using OpenAI subscription auth. Returns an answer with cited sources.",
+    promptSnippet: "Search the live web via the ChatGPT Codex search backend.",
+    promptGuidelines: [
+      "Use openai_websearch when the user asks about current events, recent releases, prices, or anything requiring live web data.",
+      "Prefer openai_websearch over recalling facts that may have changed recently; cite the returned source URLs in your answer.",
+    ],
+    parameters: TOOL_PARAMS,
+    async execute(_toolCallId, params: ToolParams, signal, onUpdate, ctx) {
+      onUpdate?.({
+        content: [{ type: "text", text: `Searching the web via ChatGPT for "${params.query}"...` }],
+        details: undefined,
+      });
+      const result = await search(params, ctx, signal);
+      return {
+        content: [{ type: "text", text: result.text }],
+        details: result.details,
+      };
+    },
+  });
+
+  return { getDebug };
+}
+
+export const _websearchTest = {
+  CODEX_SEARCH_URL,
+  MAX_QUERY_BYTES,
+  MAX_RESPONSE_BYTES,
+  MAX_TEXT_SOURCES,
+  OPENAI_WEBSEARCH_COMMAND,
+  OPENAI_WEBSEARCH_TOOL,
+  SEARCH_ORIGINATOR,
+  buildSearchHeaders,
+  buildSearchRequestBody,
+  formatSearchText,
+  parseSearchResponse,
+  readBoundedResponse,
+  validateSearchQuery,
+};