@mono-agent/agent-runtime 0.20.2 → 0.20.3

package/README.md

@@ -331,6 +331,7 @@ inferSkillsRoot
 **`@mono-agent/agent-runtime/agent/tools/index.js`**
 
 ```text
+DEFAULT_CODEX_SEARCH_MODEL
 bashToolImpl
 bashToolRun
 createWebToolController
@@ -339,6 +340,7 @@ execToolImpl
 execToolRun
 globToolImpl
 grepToolImpl
+inspectCodexSubscriptionSearch
 isPathAllowed
 isWorkdirAllowed
 normalizeBashTimeoutMs
@@ -347,6 +349,7 @@ performWebFetch
 performWebSearch
 readToolImpl
 resolveRgPath
+searchCodexSubscription
 webFetchToolImpl
 webSearchToolImpl
 writeToolImpl
@@ -824,7 +827,7 @@ Per-call options (a non-exhaustive selection):
 | `codexSandboxNetworkAccess` | `boolean` | Code-only Codex app-server per-turn network control. Only strict `true` enables it for plan/default/acceptEdits; omitted or any other value disables it. |
 | `mcpServers` | `Record<string, McpServerConfig>` | Configured MCP servers (stdio / sse / http); on direct Codex, each forwarded server authorizes its own tool calls. |
 | `sandboxPolicy` | `SandboxPolicy` | Optional fail-closed sandbox policy for built-in tools and stdio MCP process startup. |
-| `webSearchConfig` | `{ backend?, endpoint? }` | Run-scoped local SearXNG/keyless WebSearch backend selection. |
+| `webSearchConfig` | `{ backend?, endpoint?, codex?: { model? } }` | Run-scoped local SearXNG, ChatGPT-subscription Codex, and keyless WebSearch backend selection. |
 | `webFetchConfig` | `{ render?, browserCommand? }` | Run-scoped static extraction and optional isolated browser-render policy. |
 | `piToolExecutionMode` | `"safe-parallel" \| "sequential"` | Pi built-in scheduling. Safe parallelism is the default; stateful/mutating and MCP tools stay sequential. |
 | `maxTurns` | `number` | Hard cap on agent turns. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.20.2",
+  "version": "0.20.3",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, Pi SDK, and ACP v1 bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",

package/src/agent/tools/codex-subscription-search.js

@@ -0,0 +1,435 @@
+// @ts-check
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createCodexAppServerClient } from "../../ai/providers/codex-app.js";
+
+export const DEFAULT_CODEX_SEARCH_MODEL = "gpt-5.6-luna";
+
+const REQUEST_TIMEOUT_MS = 30_000;
+const IDLE_CLOSE_MS = 1_000;
+const MAX_MODEL_PAGES = 10;
+const MAX_RESULTS = 100;
+const SEARCH_ONLY_INSTRUCTIONS = [
+  "You are a search transport, not a general assistant.",
+  "Run exactly one live web search for the user's query, preserving quoted phrases and site: operators exactly.",
+  "Do not use shell, filesystem, MCP, apps, subagents, image, or any other tool.",
+  "Do not ask questions. The host consumes only the structured webSearch results and ignores your prose.",
+].join(" ");
+
+/** @type {{client: any, directory: string, models: Set<string>} | null} */
+let broker = null;
+/** @type {Promise<any> | null} */
+let brokerOpening = null;
+/** @type {Promise<void>} */
+let serial = Promise.resolve();
+/** @type {NodeJS.Timeout | null} */
+let idleTimer = null;
+
+/**
+ * Inspect the installed Codex app-server without reading or exporting tokens.
+ *
+ * @param {{model?: string, clientFactory?: typeof createCodexAppServerClient}} [options]
+ */
+export async function inspectCodexSubscriptionSearch(options = {}) {
+  const model = normalizeModel(options.model);
+  let owned;
+  try {
+    owned = await openBroker(options.clientFactory);
+    const ready = await inspectClient(owned.client, model);
+    const { models: _models, ...publicReadiness } = ready;
+    return publicReadiness;
+  } catch (error) {
+    return {
+      ok: false,
+      code: "codex_unavailable",
+      reason: publicReason(error),
+      model,
+    };
+  } finally {
+    if (owned) await closeOwnedBroker(owned);
+  }
+}
+
+/**
+ * Execute one subscription-backed live search through Codex app-server.
+ * Calls are serialized process-wide so one agent cannot fan out subscription
+ * turns or cross-wire app-server notifications between requests.
+ *
+ * @param {string} query
+ * @param {{model?: string, signal?: AbortSignal, clientFactory?: typeof createCodexAppServerClient}} [options]
+ */
+export function searchCodexSubscription(query, options = {}) {
+  return enqueue(async () => {
+    if (options.signal?.aborted) return abortedResult();
+    const model = normalizeModel(options.model);
+    let current;
+    try {
+      current = await getBroker(model, options.clientFactory);
+      const result = await runSearch(current, query, model, options.signal);
+      scheduleIdleClose();
+      return result;
+    } catch (error) {
+      await closeBroker();
+      return {
+        ok: false,
+        backend: "codex",
+        message: `Codex subscription search unavailable: ${publicReason(error)}`,
+        retryable: isRetryable(error),
+      };
+    }
+  });
+}
+
+function enqueue(task) {
+  const result = serial.then(task, task);
+  serial = result.then(() => {}, () => {});
+  return result;
+}
+
+async function getBroker(model, clientFactory) {
+  clearIdleTimer();
+  if (broker?.models.has(model)) return broker;
+  if (broker && !broker.models.has(model)) await closeBroker();
+  if (!brokerOpening) {
+    brokerOpening = (async () => {
+      const owned = await openBroker(clientFactory);
+      const ready = await inspectClient(owned.client, model);
+      if (!ready.ok) {
+        await closeOwnedBroker(owned);
+        throw new Error(ready.reason);
+      }
+      owned.models = ready.models;
+      broker = owned;
+      return owned;
+    })().finally(() => { brokerOpening = null; });
+  }
+  return await brokerOpening;
+}
+
+async function openBroker(clientFactory = createCodexAppServerClient) {
+  const directory = await mkdtemp(join(tmpdir(), "mono-agent-codex-search-"));
+  /** @type {{handler: (message: any) => void}} */
+  const target = { handler: () => {} };
+  let client;
+  try {
+    client = clientFactory({
+      cwd: directory,
+      onNotification: (message) => target.handler(message),
+      onServerRequest: (message) => {
+        target.handler(message);
+        throw new Error("Codex subscription search rejected an unexpected server request.");
+      },
+    });
+    await client.request("initialize", {
+      clientInfo: { name: "mono-agent-web-search", title: "mono-agent WebSearch", version: "0" },
+      capabilities: { experimentalApi: true },
+    }, { timeoutMs: REQUEST_TIMEOUT_MS });
+    return { client, directory, models: new Set(), target };
+  } catch (error) {
+    await Promise.resolve(client?.close?.()).catch(() => {});
+    await rm(directory, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function inspectClient(client, model) {
+  const account = await client.request("account/read", { refreshToken: false }, { timeoutMs: REQUEST_TIMEOUT_MS });
+  if (account?.account?.type !== "chatgpt") {
+    return {
+      ok: false,
+      code: "codex_chatgpt_login_required",
+      reason: "Codex must be signed in with ChatGPT subscription access.",
+      model,
+      models: new Set(),
+    };
+  }
+  const capabilities = await client.request(
+    "modelProvider/capabilities/read",
+    {},
+    { timeoutMs: REQUEST_TIMEOUT_MS },
+  );
+  if (capabilities?.webSearch !== true) {
+    return {
+      ok: false,
+      code: "codex_web_search_unavailable",
+      reason: "The signed-in Codex account does not expose web search.",
+      model,
+      models: new Set(),
+    };
+  }
+  const models = await readModels(client);
+  if (!models.has(model)) {
+    return {
+      ok: false,
+      code: "codex_model_unavailable",
+      reason: `Codex model ${model} is not available to the signed-in account.`,
+      model,
+      models,
+    };
+  }
+  return {
+    ok: true,
+    code: "ok",
+    reason: "",
+    model,
+    models,
+  };
+}
+
+async function readModels(client) {
+  const models = new Set();
+  let cursor = null;
+  for (let page = 0; page < MAX_MODEL_PAGES; page += 1) {
+    const response = await client.request("model/list", {
+      includeHidden: false,
+      limit: 100,
+      ...(cursor === null ? {} : { cursor }),
+    }, { timeoutMs: REQUEST_TIMEOUT_MS });
+    if (!Array.isArray(response?.data)) throw new Error("Codex returned an invalid model catalog.");
+    for (const row of response.data) {
+      if (typeof row?.id === "string" && row.id.trim()) models.add(row.id.trim());
+    }
+    cursor = typeof response?.nextCursor === "string" && response.nextCursor ? response.nextCursor : null;
+    if (cursor === null) return models;
+  }
+  throw new Error("Codex model catalog exceeded the pagination bound.");
+}
+
+async function runSearch(current, query, model, signal) {
+  const state = /** @type {any} */ ({
+    threadId: "",
+    turnId: "",
+    completed: false,
+    violation: "",
+    webSearchItems: [],
+    resolve: () => {},
+  });
+  const completion = new Promise((resolve) => { state.resolve = resolve; });
+  current.target.handler = (message) => handleNotification(message, state, current.client);
+  const onAbort = () => {
+    if (state.threadId && state.turnId) {
+      void current.client.request("turn/interrupt", {
+        threadId: state.threadId,
+        turnId: state.turnId,
+      }).catch(() => {});
+    }
+    state.violation ||= "WebSearch was aborted.";
+    state.resolve();
+  };
+  signal?.addEventListener?.("abort", onAbort, { once: true });
+  try {
+    const thread = await current.client.request("thread/start", {
+      model,
+      modelProvider: "openai",
+      allowProviderModelFallback: false,
+      cwd: current.directory,
+      runtimeWorkspaceRoots: [current.directory],
+      approvalPolicy: "untrusted",
+      sandbox: "read-only",
+      config: {
+        web_search: "live",
+        project_doc_max_bytes: 0,
+        mcp_servers: {},
+      },
+      developerInstructions: SEARCH_ONLY_INSTRUCTIONS,
+      ephemeral: true,
+      sessionStartSource: "startup",
+      environments: [],
+      dynamicTools: [],
+      selectedCapabilityRoots: [],
+      experimentalRawEvents: false,
+    }, { timeoutMs: REQUEST_TIMEOUT_MS });
+    state.threadId = thread?.thread?.id || "";
+    if (!state.threadId) throw new Error("Codex did not return a search thread id.");
+    const turn = await current.client.request("turn/start", {
+      threadId: state.threadId,
+      input: [{ type: "text", text: String(query), text_elements: [] }],
+      cwd: current.directory,
+      runtimeWorkspaceRoots: [current.directory],
+      approvalPolicy: "untrusted",
+      sandboxPolicy: { type: "readOnly", networkAccess: false },
+      model,
+      effort: "low",
+      summary: "none",
+      environments: [],
+    }, { timeoutMs: REQUEST_TIMEOUT_MS });
+    state.turnId = turn?.turn?.id || state.turnId;
+    if (state.violation && state.turnId) {
+      await current.client.request("turn/interrupt", {
+        threadId: state.threadId,
+        turnId: state.turnId,
+      }).catch(() => {});
+    }
+    await waitForCompletion(completion, signal);
+    if (state.violation) throw new Error(state.violation);
+    if (!state.completed) throw new Error("Codex search turn did not complete.");
+    if (state.webSearchItems.length !== 1) {
+      throw new Error(`Codex search turn produced ${state.webSearchItems.length} web search items; expected exactly one.`);
+    }
+    const item = state.webSearchItems[0];
+    const actualQuery = typeof item.query === "string" && item.query.trim()
+      ? item.query.trim()
+      : String(query);
+    if (actualQuery !== String(query)) {
+      throw new Error("Codex changed the exact web search query.");
+    }
+    const results = normalizeResults(item.results);
+    return {
+      ok: true,
+      backend: "codex",
+      results,
+      actualQuery,
+    };
+  } finally {
+    signal?.removeEventListener?.("abort", onAbort);
+    current.target.handler = () => {};
+  }
+}
+
+function handleNotification(message, state, client) {
+  const method = typeof message?.method === "string" ? message.method : "";
+  if (method === "turn/started" && message?.params?.threadId === state.threadId) {
+    state.turnId ||= message?.params?.turn?.id || "";
+    return;
+  }
+  if ((method === "item/started" || method === "item/completed")
+    && message?.params?.threadId === state.threadId) {
+    const item = message?.params?.item;
+    if (item?.type === "webSearch") {
+      if (method === "item/completed") state.webSearchItems.push(item);
+      return;
+    }
+    if (["userMessage", "agentMessage", "reasoning", "plan"].includes(item?.type)) return;
+    state.violation ||= `Codex subscription search attempted unsupported item ${String(item?.type || "unknown")}.`;
+    if (state.threadId && state.turnId) {
+      void client.request("turn/interrupt", { threadId: state.threadId, turnId: state.turnId }).catch(() => {});
+    }
+    state.resolve();
+    return;
+  }
+  if (method === "turn/completed" && message?.params?.threadId === state.threadId) {
+    const turn = message?.params?.turn;
+    state.turnId ||= turn?.id || "";
+    state.completed = turn?.status === "completed";
+    if (!state.completed) state.violation ||= "Codex search turn failed.";
+    state.resolve();
+    return;
+  }
+  if (method === "error") {
+    state.violation ||= "Codex search turn reported an error.";
+    state.resolve();
+    return;
+  }
+  if (Object.prototype.hasOwnProperty.call(message || {}, "id") && method) {
+    state.violation ||= "Codex subscription search attempted an unsupported server request.";
+    state.resolve();
+  }
+}
+
+function normalizeResults(rows) {
+  if (!Array.isArray(rows)) return [];
+  const results = [];
+  for (const row of rows) {
+    if (!row || typeof row !== "object" || typeof row.url !== "string") continue;
+    results.push({
+      title: boundedText(row.title, 500),
+      url: row.url,
+      snippet: boundedText(row.snippet, 4_000),
+      provenance: boundedText(row.domain || row.ref_id || row.type, 300),
+      backend: "codex",
+    });
+    if (results.length >= MAX_RESULTS) break;
+  }
+  return results;
+}
+
+async function waitForCompletion(completion, signal) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(Object.assign(new Error("Codex search turn timed out."), {
+      code: "CODEX_SEARCH_TIMEOUT",
+    })), REQUEST_TIMEOUT_MS);
+  });
+  try {
+    if (signal?.aborted) throw Object.assign(new Error("WebSearch was aborted."), { name: "AbortError" });
+    await Promise.race([completion, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function scheduleIdleClose() {
+  clearIdleTimer();
+  idleTimer = setTimeout(() => {
+    idleTimer = null;
+    void enqueue(async () => { await closeBroker(); });
+  }, IDLE_CLOSE_MS);
+}
+
+function clearIdleTimer() {
+  if (idleTimer) clearTimeout(idleTimer);
+  idleTimer = null;
+}
+
+async function closeBroker() {
+  clearIdleTimer();
+  const owned = broker;
+  broker = null;
+  if (owned) await closeOwnedBroker(owned);
+}
+
+async function closeOwnedBroker(owned) {
+  await Promise.resolve(owned.client?.close?.()).catch(() => {});
+  await rm(owned.directory, { recursive: true, force: true }).catch(() => {});
+}
+
+function normalizeModel(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : DEFAULT_CODEX_SEARCH_MODEL;
+}
+
+function boundedText(value, max) {
+  return typeof value === "string" ? value.replace(/\s+/gu, " ").trim().slice(0, max) : "";
+}
+
+function safeReason(error) {
+  if (error?.name === "AbortError") return "WebSearch was aborted.";
+  const message = error instanceof Error ? error.message : String(error || "unknown error");
+  return message.replace(/[\r\n\t]+/gu, " ").slice(0, 500) || "unknown error";
+}
+
+function publicReason(error) {
+  const reason = safeReason(error);
+  if (reason === "WebSearch was aborted.") return reason;
+  if (/timed out/iu.test(reason)) return "Codex app-server timed out.";
+  if (/signed in with ChatGPT subscription access/iu.test(reason)) return reason;
+  if (/does not expose web search/iu.test(reason)) return reason;
+  if (/Codex model .* is not available/iu.test(reason)) return reason;
+  if (/attempted unsupported item/iu.test(reason)) return "Codex attempted a non-search tool and the request was rejected.";
+  if (/unsupported server request/iu.test(reason)) return "Codex requested an unsupported interaction and the request was rejected.";
+  if (/produced .* web search items/iu.test(reason)) return "Codex did not produce exactly one structured web search result set.";
+  if (/changed the exact web search query/iu.test(reason)) return "Codex did not preserve the exact web search query.";
+  return "Codex app-server is not ready for subscription web search.";
+}
+
+function isRetryable(error) {
+  return error?.name === "AbortError" || error?.code === "CODEX_SEARCH_TIMEOUT"
+    || error?.code === "CODEX_APP_SERVER_REQUEST_TIMEOUT";
+}
+
+function abortedResult() {
+  return {
+    ok: false,
+    backend: "codex",
+    message: "WebSearch was aborted.",
+    retryable: false,
+  };
+}
+
+/** Test hook for process-shared broker state. */
+export async function __resetCodexSubscriptionSearchForTests() {
+  await enqueue(async () => { await closeBroker(); });
+  brokerOpening = null;
+}

package/src/agent/tools/index.js

@@ -18,6 +18,11 @@ export {
 export { execToolImpl, execToolRun } from "./exec.js";
 export { webFetchToolImpl, performWebFetch } from "./web-fetch.js";
 export { webSearchToolImpl, performWebSearch } from "./web-search.js";
+export {
+  DEFAULT_CODEX_SEARCH_MODEL,
+  inspectCodexSubscriptionSearch,
+  searchCodexSubscription,
+} from "./codex-subscription-search.js";
 export { createWebToolController } from "./web-controller.js";
 
 export { isPathAllowed, isWorkdirAllowed } from "./shared/path-resolver.js";

package/src/agent/tools/pi-bridge.js

@@ -575,7 +575,7 @@ export function getPiBuiltinTools(allowedTools, {
         outcome: { status: "error", code: "controller_unavailable", retryable: false, attempts: 0 },
         error: true,
       }), toolContext),
-    WebSearch: createBuiltinTool("WebSearch", "Web Search", "Search the public web with an operator-owned SearXNG endpoint when available, otherwise a keyless fallback, and return deduplicated ranked results.", objectSchema({
+    WebSearch: createBuiltinTool("WebSearch", "Web Search", "Search the public web through local SearXNG, ChatGPT-subscription Codex search, and keyless fallbacks according to the configured backend, then return relevance-filtered deduplicated results.", objectSchema({
       query: { type: "string" },
       limit: { type: "integer" },
       alternate_queries: { type: "array", items: { type: "string" }, maxItems: 3 },

package/src/agent/tools/web-controller.js

@@ -28,7 +28,7 @@ const sharedSearchCache = new Map();
  * cleanup. Search results are the exception: they live in the process-wide
  * cache above so sibling subagents and later turns can reuse them.
  *
- * @param {{searchConfig?: any, fetchConfig?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, fetchImpl?: typeof fetch, browserRenderer?: any}} [options]
+ * @param {{searchConfig?: any, fetchConfig?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, fetchImpl?: typeof fetch, browserRenderer?: any, codexSearch?: any}} [options]
  */
 export function createWebToolController({
   searchConfig,
@@ -38,6 +38,7 @@ export function createWebToolController({
   ctx,
   fetchImpl,
   browserRenderer,
+  codexSearch,
 } = {}) {
   const namespace = `mono-agent-web-${randomUUID()}`;
   const fetchCache = new Map();
@@ -137,6 +138,7 @@ export function createWebToolController({
         sandboxPolicy: policy,
         ctx: resolvedCtx,
         fetchImpl,
+        codexSearch,
         signal: execution.signal,
       }));
     },

package/src/agent/tools/web-search.js

@@ -2,6 +2,7 @@
 
 import { parseHTML } from "linkedom";
 import { passthroughSandbox } from "../sandbox-seam.js";
+import { searchCodexSubscription } from "./codex-subscription-search.js";
 import { readToolRuntime } from "./shared/runtime-context.js";
 import { createCountingSemaphore } from "./shared/semaphore.js";
 import { resolveSandboxPolicy } from "./shared/tool-context.js";
@@ -81,11 +82,12 @@ export async function webSearchToolImpl(params, options = {}) {
 }
 
 /**
- * Search through an operator-owned SearXNG endpoint and/or the keyless HTML
- * fallback chain. Returns a structured internal outcome for the Pi bridge.
+ * Search through an operator-owned SearXNG endpoint, ChatGPT-subscription
+ * Codex search, and/or the keyless HTML fallback chain. Returns a structured
+ * internal outcome for the Pi bridge.
  *
  * @param {{query: string, limit?: number, alternate_queries?: string[], domains?: string[], exclude_domains?: string[], language?: string, time_range?: string}} params
- * @param {{sandboxPolicy?: any, ctx?: any, signal?: AbortSignal, searchConfig?: any, fetchImpl?: typeof fetch}} [options]
+ * @param {{sandboxPolicy?: any, ctx?: any, signal?: AbortSignal, searchConfig?: any, fetchImpl?: typeof fetch, codexSearch?: typeof searchCodexSubscription}} [options]
  */
 export async function performWebSearch(
   {
@@ -103,6 +105,7 @@ export async function performWebSearch(
     signal,
     searchConfig,
     fetchImpl = globalThis.fetch,
+    codexSearch = searchCodexSubscription,
   } = {},
 ) {
   const startedAt = Date.now();
@@ -111,7 +114,8 @@ export async function performWebSearch(
     return failure("Error: WebSearch query must not be empty.", "invalid_query", startedAt);
   }
   const max = clampInteger(limit, 1, 10, 5);
-  const includeDomains = normalizeDomains(domains);
+  const explicitDomains = normalizeDomains(Array.isArray(domains) ? domains : []);
+  const includeDomains = normalizeDomains([...explicitDomains, ...querySiteDomains(normalizedQuery)]);
   const excludeDomains = normalizeDomains(exclude_domains);
   const config = normalizeSearchConfig(searchConfig);
   if (config.error) return failure(`Error: ${config.error}`, "invalid_search_config", startedAt);
@@ -119,26 +123,33 @@ export async function performWebSearch(
   const resolvedCtx = ctx ?? readToolRuntime();
   const sandbox = resolvedCtx.sandbox ?? passthroughSandbox;
   const policy = resolveSandboxPolicy(resolvedCtx, sandboxPolicy);
+  // Operators, quotes, and site: constraints are never relaxed or rewritten by
+  // the host. Alternate queries are explicit model input, not host-generated
+  // substitutions for the user's exact primary query.
   const initialQueries = uniqueStrings([normalizedQuery, ...alternate_queries], 4);
   /** @type {Array<Array<{title: string, url: string, snippet: string, backend: string}>>} */
   const rankedLists = [];
   const providerFailures = [];
   const providersUsed = new Set();
+  const attemptedBackends = new Set();
+  const actualQueries = [];
   let attempts = 0;
   let anyProviderSucceeded = false;
 
-  const runQuery = async (candidate) => {
+  const runQuery = async (candidate, backend) => {
     attempts += 1;
+    attemptedBackends.add(backend);
     return await searchOneQuery(
-      queryWithDomains(candidate, includeDomains),
+      queryWithDomains(candidate, explicitDomains),
       {
-        config,
+        config: { ...config, backend },
         language,
         timeRange: time_range,
         sandbox,
         policy,
         signal,
         fetchImpl,
+        codexSearch,
       },
     );
   };
@@ -147,16 +158,51 @@ export async function performWebSearch(
     // so a silent degradation to the fallback is still visible in the outcome.
     if (result.failures?.length) providerFailures.push(...result.failures);
     if (result.ok) {
-      anyProviderSucceeded = true;
-      providersUsed.add(result.backend);
-      rankedLists.push(filterByDomains(result.results, includeDomains, excludeDomains));
+      const filtered = filterRelevantResults(
+        filterByDomains(result.results, includeDomains, excludeDomains),
+        normalizedQuery,
+      );
+      if (filtered.length > 0) {
+        anyProviderSucceeded = true;
+        providersUsed.add(result.backend);
+        rankedLists.push(filtered);
+      } else if (result.results.length === 0) {
+        anyProviderSucceeded = true;
+      } else {
+        providerFailures.push({
+          ok: false,
+          backend: result.backend,
+          message: `${result.backend} returned no relevant results.`,
+          retryable: false,
+          relevance: true,
+        });
+      }
+      if (typeof result.actualQuery === "string" && result.actualQuery.trim()) {
+        actualQueries.push(result.actualQuery.trim());
+      }
     } else if (!result.failures?.length) {
       providerFailures.push(result);
     }
   };
 
-  const initialResults = await Promise.all(initialQueries.map(runQuery));
-  initialResults.forEach(recordResult);
+  const runStage = async (backend, candidates) => {
+    const results = await Promise.all(candidates.map((candidate) => runQuery(candidate, backend)));
+    results.forEach(recordResult);
+    return mergeRankedResults(rankedLists, max);
+  };
+
+  let merged = [];
+  if (config.backend === "searxng" || (config.backend === "auto" && config.endpoint)) {
+    merged = await runStage("searxng", initialQueries);
+  }
+  if (config.backend === "codex" || (config.backend === "auto" && merged.length === 0)) {
+    // Exactly one subscription turn per WebSearch call. Alternate queries still
+    // help local/keyless rank fusion but never multiply paid subscription work.
+    merged = await runStage("codex", [normalizedQuery]);
+  }
+  if (config.backend === "keyless" || (config.backend === "auto" && merged.length === 0)) {
+    merged = await runStage("keyless", initialQueries);
+  }
   if (signal?.aborted) {
     return failure("Error: WebSearch was aborted.", "aborted", startedAt, {
       attempts,
@@ -164,15 +210,6 @@ export async function performWebSearch(
     });
   }
 
-  let merged = mergeRankedResults(rankedLists, max);
-  if (merged.length < max && initialQueries.length < 4) {
-    const relaxed = relaxedQuery(normalizedQuery);
-    if (relaxed && !initialQueries.includes(relaxed)) {
-      recordResult(await runQuery(relaxed));
-      merged = mergeRankedResults(rankedLists, max);
-    }
-  }
-
   if (!anyProviderSucceeded) {
     // Four query variants against two backends produce the same handful of
     // messages over and over; dedupe so the reason stays readable.
@@ -190,10 +227,14 @@ export async function performWebSearch(
       retryable: providerFailures.some((entry) => entry.retryable),
       rateLimited: throttled,
       cooldownBackends: [...backendCooldownUntil.keys()],
+      attemptedBackends: [...attemptedBackends],
+      failureMetadata: sanitizeFailureMetadata(providerFailures),
     });
   }
 
-  const backend = providersUsed.size === 1 ? [...providersUsed][0] : "mixed";
+  const backend = providersUsed.size === 1
+    ? [...providersUsed][0]
+    : providersUsed.size > 1 ? "mixed" : config.backend;
   const body = merged.length === 0
     ? "No results."
     : merged.map((result, index) => {
@@ -202,6 +243,12 @@ export async function performWebSearch(
       }).join("\n\n");
   const text = [
     "[BEGIN UNTRUSTED WEB SEARCH RESULTS]",
+    searchMetadataLine({
+      backend,
+      attemptedBackends: [...attemptedBackends],
+      query: actualQueries[0] || normalizedQuery,
+      providerFailures,
+    }),
     body,
     "[END UNTRUSTED WEB SEARCH RESULTS]",
   ].join("\n");
@@ -221,6 +268,9 @@ export async function performWebSearch(
       providerFailureCount: providerFailures.length,
       rateLimited: providerFailures.some((entry) => entry.rateLimited || entry.cooldown),
       cooldownBackends: [...backendCooldownUntil.keys()],
+      attemptedBackends: [...attemptedBackends],
+      actualQueries: uniqueStrings(actualQueries.length > 0 ? actualQueries : [normalizedQuery], 4),
+      failureMetadata: sanitizeFailureMetadata(providerFailures),
     },
     error: false,
   };
@@ -243,16 +293,27 @@ async function searchOneQuery(query, options) {
   // circuit `auto` outright, so the fallbacks below could never rescue a query.
   let emptySuccess = null;
   if (options.signal?.aborted) return abortedSearch(config.backend, failures);
-  if (config.backend === "searxng" || (config.backend === "auto" && config.endpoint)) {
+  if (config.backend === "searxng") {
     const result = await searchSearxng(query, options);
-    // Strict mode has nothing to fall through to, so its answer stands as-is.
-    if (config.backend === "searxng") return { ...result, failures };
-    if (result.ok && result.results.length > 0) return { ...result, failures };
-    if (result.ok) emptySuccess = result;
-    else failures.push(result);
-    if (options.signal?.aborted) return abortedSearch(result.backend, failures);
-  }
-  if (config.backend === "keyless" || config.backend === "auto") {
+    return { ...result, failures };
+  }
+  if (config.backend === "codex") {
+    if (!options.sandbox.networkAllowsUrl(options.policy, "https://chatgpt.com")) {
+      return {
+        ok: false,
+        backend: "codex",
+        message: "Network access denied by sandbox policy.",
+        retryable: false,
+        failures,
+      };
+    }
+    const result = await options.codexSearch(query, {
+      model: config.codex.model,
+      signal: options.signal,
+    });
+    return { ...result, failures };
+  }
+  if (config.backend === "keyless") {
     for (const backend of KEYLESS_BACKENDS) {
       if (options.signal?.aborted) return abortedSearch(backend, failures);
       if (backendInCooldown(backend)) {
@@ -694,8 +755,8 @@ export function mergeRankedResults(rankedLists, limit = 10) {
 
 function normalizeSearchConfig(input) {
   const backend = input?.backend ?? "auto";
-  if (!["auto", "searxng", "keyless"].includes(backend)) {
-    return { error: "Web search backend must be auto, searxng, or keyless." };
+  if (!["auto", "searxng", "codex", "keyless"].includes(backend)) {
+    return { error: "Web search backend must be auto, searxng, codex, or keyless." };
   }
   let endpoint;
   if (input?.endpoint !== undefined && String(input.endpoint).trim()) {
@@ -716,7 +777,13 @@ function normalizeSearchConfig(input) {
   if (backend === "searxng" && !endpoint) {
     return { error: "SearXNG backend requires tools.web.search.endpoint." };
   }
-  return { backend, endpoint };
+  const model = typeof input?.codex?.model === "string" && input.codex.model.trim()
+    ? input.codex.model.trim()
+    : "gpt-5.6-luna";
+  if (model.length > 160 || /[\u0000-\u001f\u007f]/u.test(model)) {
+    return { error: "Codex web search model must be a valid model id." };
+  }
+  return { backend, endpoint, codex: { model } };
 }
 
 function isLoopbackHost(hostname) {
@@ -746,6 +813,48 @@ function filterByDomains(results, include, exclude) {
   });
 }
 
+const RELEVANCE_STOP_WORDS = new Set([
+  "about", "after", "before", "best", "find", "from", "into", "latest",
+  "near", "news", "that", "the", "their", "this", "time", "what", "when",
+  "where", "which", "with", "your",
+]);
+
+function filterRelevantResults(results, query) {
+  const phrases = [...String(query).matchAll(/"([^"]{2,})"/gu)]
+    .map((match) => comparableText(match[1]))
+    .filter(Boolean);
+  const terms = uniqueStrings(
+    comparableText(String(query)
+      .replace(/"[^"]*"/gu, " ")
+      .replace(/\bsite:\S+/giu, " "))
+      .split(" ")
+      .filter((term) => term.length >= 3 && !RELEVANCE_STOP_WORDS.has(term)),
+    20,
+  );
+  if (phrases.length === 0 && terms.length === 0) return results;
+  const requiredTerms = Math.min(terms.length, terms.length >= 3 ? 2 : 1);
+  return results.filter((result) => {
+    const haystack = comparableText(`${result.title} ${result.snippet} ${result.url}`);
+    if (phrases.some((phrase) => !haystack.includes(phrase))) return false;
+    if (requiredTerms === 0) return true;
+    let matches = 0;
+    for (const term of terms) {
+      if (haystack.includes(term)) matches += 1;
+      if (matches >= requiredTerms) return true;
+    }
+    return false;
+  });
+}
+
+function comparableText(value) {
+  return String(value || "")
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .replace(/\s+/gu, " ")
+    .trim();
+}
+
 function domainMatches(host, domain) {
   return host === domain || host.endsWith(`.${domain}`);
 }
@@ -755,13 +864,38 @@ function queryWithDomains(query, domains) {
   return `${query} (${domains.map((domain) => `site:${domain}`).join(" OR ")})`;
 }
 
-function relaxedQuery(query) {
-  const relaxed = query
-    .replace(/"([^"]+)"/gu, "$1")
-    .replace(/\bsite:\S+/giu, " ")
-    .replace(/\s+/gu, " ")
-    .trim();
-  return relaxed && relaxed !== query ? relaxed : null;
+function querySiteDomains(query) {
+  return [...String(query).matchAll(/\bsite:([a-z0-9.-]+)(?:\/\S*)?/giu)]
+    .map((match) => match[1]);
+}
+
+function sanitizeFailureMetadata(failures) {
+  const seen = new Set();
+  const metadata = [];
+  for (const failureEntry of failures) {
+    const backend = collapseWhitespace(failureEntry?.backend).slice(0, 40) || "unknown";
+    const code = failureEntry?.relevance
+      ? "no_relevant_results"
+      : failureEntry?.rateLimited ? "rate_limited"
+        : failureEntry?.cooldown ? "cooldown"
+          : failureEntry?.message === "Network access denied by sandbox policy."
+            ? "network_denied"
+            : "unavailable";
+    const key = `${backend}:${code}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    metadata.push({ backend, code });
+    if (metadata.length >= 12) break;
+  }
+  return metadata;
+}
+
+function searchMetadataLine({ backend, attemptedBackends, query, providerFailures }) {
+  const attempted = attemptedBackends.join(",") || "none";
+  const failures = sanitizeFailureMetadata(providerFailures)
+    .map((entry) => `${entry.backend}:${entry.code}`)
+    .join(",") || "none";
+  return `[Search metadata: backend=${backend}; attempted=${attempted}; actual_query=${JSON.stringify(collapseWhitespace(query).slice(0, 500))}; fallback=${failures}]`;
 }
 
 function uniqueStrings(values, limit) {

package/src/ai/types.js

@@ -287,7 +287,7 @@
  * @property {import('./providers/acp-client.js').AcpClientHostOptions["resolveAcpProfile"]} [resolveAcpProfile] Per-run ACP profile resolver; wins over the host default.
  * @property {import('./providers/acp-client.js').AcpClientHostOptions["onAcpInteractionRequest"]} [onAcpInteractionRequest] Per-run ACP permission/elicitation callback; wins over the host default.
  * @property {Uint8Array} [acpSessionTokenKey] Host-owned 32-byte key for confidential authenticated ACP session handles. Required for every ACP task run.
- * @property {{backend?: "auto"|"searxng"|"keyless", endpoint?: string}} [webSearchConfig] Run-scoped WebSearch backend configuration.
+ * @property {{backend?: "auto"|"searxng"|"codex"|"keyless", endpoint?: string, codex?: {model?: string}}} [webSearchConfig] Run-scoped WebSearch backend configuration.
  * @property {{render?: "never"|"auto", browserCommand?: string}} [webFetchConfig] Run-scoped WebFetch extraction/render configuration.
  * @property {"sequential"|"safe-parallel"} [piToolExecutionMode] Pi built-in tool scheduling mode. Safe parallelism is the default.
  * @property {"one-at-a-time"|"all"} [piToolParallelismMode] DEPRECATED. Compatibility alias mapped to piToolExecutionMode.

package/types/agent/tools/codex-subscription-search.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Inspect the installed Codex app-server without reading or exporting tokens.
+ *
+ * @param {{model?: string, clientFactory?: typeof createCodexAppServerClient}} [options]
+ */
+export function inspectCodexSubscriptionSearch(options?: {
+    model?: string;
+    clientFactory?: typeof createCodexAppServerClient;
+}): Promise<{
+    ok: boolean;
+    code: string;
+    reason: string;
+    model: any;
+}>;
+/**
+ * Execute one subscription-backed live search through Codex app-server.
+ * Calls are serialized process-wide so one agent cannot fan out subscription
+ * turns or cross-wire app-server notifications between requests.
+ *
+ * @param {string} query
+ * @param {{model?: string, signal?: AbortSignal, clientFactory?: typeof createCodexAppServerClient}} [options]
+ */
+export function searchCodexSubscription(query: string, options?: {
+    model?: string;
+    signal?: AbortSignal;
+    clientFactory?: typeof createCodexAppServerClient;
+}): Promise<void>;
+/** Test hook for process-shared broker state. */
+export function __resetCodexSubscriptionSearchForTests(): Promise<void>;
+export const DEFAULT_CODEX_SEARCH_MODEL: "gpt-5.6-luna";
+import { createCodexAppServerClient } from "../../ai/providers/codex-app.js";

package/types/agent/tools/index.d.ts

@@ -9,4 +9,5 @@ export { bashToolImpl, bashToolRun, normalizeBashTimeoutMs, normalizeProcessTime
 export { execToolImpl, execToolRun } from "./exec.js";
 export { webFetchToolImpl, performWebFetch } from "./web-fetch.js";
 export { webSearchToolImpl, performWebSearch } from "./web-search.js";
+export { DEFAULT_CODEX_SEARCH_MODEL, inspectCodexSubscriptionSearch, searchCodexSubscription } from "./codex-subscription-search.js";
 export { isPathAllowed, isWorkdirAllowed } from "./shared/path-resolver.js";

package/types/agent/tools/web-controller.d.ts

@@ -4,9 +4,9 @@
  * cleanup. Search results are the exception: they live in the process-wide
  * cache above so sibling subagents and later turns can reuse them.
  *
- * @param {{searchConfig?: any, fetchConfig?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, fetchImpl?: typeof fetch, browserRenderer?: any}} [options]
+ * @param {{searchConfig?: any, fetchConfig?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, fetchImpl?: typeof fetch, browserRenderer?: any, codexSearch?: any}} [options]
  */
-export function createWebToolController({ searchConfig, fetchConfig, sandboxPolicy, sandboxEngine, ctx, fetchImpl, browserRenderer, }?: {
+export function createWebToolController({ searchConfig, fetchConfig, sandboxPolicy, sandboxEngine, ctx, fetchImpl, browserRenderer, codexSearch, }?: {
     searchConfig?: any;
     fetchConfig?: any;
     sandboxPolicy?: any;
@@ -14,6 +14,7 @@ export function createWebToolController({ searchConfig, fetchConfig, sandboxPoli
     ctx?: any;
     fetchImpl?: typeof fetch;
     browserRenderer?: any;
+    codexSearch?: any;
 }): {
     namespace: string;
     search(params: any, execution?: {}): Promise<any>;

package/types/agent/tools/web-search.d.ts

@@ -20,11 +20,12 @@ export function webSearchToolImpl(params: {
     fetchImpl?: typeof fetch;
 }): Promise<any>;
 /**
- * Search through an operator-owned SearXNG endpoint and/or the keyless HTML
- * fallback chain. Returns a structured internal outcome for the Pi bridge.
+ * Search through an operator-owned SearXNG endpoint, ChatGPT-subscription
+ * Codex search, and/or the keyless HTML fallback chain. Returns a structured
+ * internal outcome for the Pi bridge.
  *
  * @param {{query: string, limit?: number, alternate_queries?: string[], domains?: string[], exclude_domains?: string[], language?: string, time_range?: string}} params
- * @param {{sandboxPolicy?: any, ctx?: any, signal?: AbortSignal, searchConfig?: any, fetchImpl?: typeof fetch}} [options]
+ * @param {{sandboxPolicy?: any, ctx?: any, signal?: AbortSignal, searchConfig?: any, fetchImpl?: typeof fetch, codexSearch?: typeof searchCodexSubscription}} [options]
  */
 export function performWebSearch({ query, limit, alternate_queries, domains, exclude_domains, language, time_range, }: {
     query: string;
@@ -34,12 +35,13 @@ export function performWebSearch({ query, limit, alternate_queries, domains, exc
     exclude_domains?: string[];
     language?: string;
     time_range?: string;
-}, { sandboxPolicy, ctx, signal, searchConfig, fetchImpl, }?: {
+}, { sandboxPolicy, ctx, signal, searchConfig, fetchImpl, codexSearch, }?: {
     sandboxPolicy?: any;
     ctx?: any;
     signal?: AbortSignal;
     searchConfig?: any;
     fetchImpl?: typeof fetch;
+    codexSearch?: typeof searchCodexSubscription;
 }): Promise<{
     text: any;
     outcome: {
@@ -70,6 +72,12 @@ export function performWebSearch({ query, limit, alternate_queries, domains, exc
         providerFailureCount: number;
         rateLimited: boolean;
         cooldownBackends: string[];
+        attemptedBackends: any[];
+        actualQueries: string[];
+        failureMetadata: {
+            backend: string;
+            code: string;
+        }[];
     };
     error: boolean;
 }>;
@@ -98,3 +106,4 @@ export function parseStartpageResults(html: any): {
 }[];
 export function canonicalizeSearchUrl(value: any, base: any): string;
 export function mergeRankedResults(rankedLists: any, limit?: number): any[];
+import { searchCodexSubscription } from "./codex-subscription-search.js";

package/types/ai/types.d.ts

@@ -247,7 +247,7 @@
  * @property {import('./providers/acp-client.js').AcpClientHostOptions["resolveAcpProfile"]} [resolveAcpProfile] Per-run ACP profile resolver; wins over the host default.
  * @property {import('./providers/acp-client.js').AcpClientHostOptions["onAcpInteractionRequest"]} [onAcpInteractionRequest] Per-run ACP permission/elicitation callback; wins over the host default.
  * @property {Uint8Array} [acpSessionTokenKey] Host-owned 32-byte key for confidential authenticated ACP session handles. Required for every ACP task run.
- * @property {{backend?: "auto"|"searxng"|"keyless", endpoint?: string}} [webSearchConfig] Run-scoped WebSearch backend configuration.
+ * @property {{backend?: "auto"|"searxng"|"codex"|"keyless", endpoint?: string, codex?: {model?: string}}} [webSearchConfig] Run-scoped WebSearch backend configuration.
  * @property {{render?: "never"|"auto", browserCommand?: string}} [webFetchConfig] Run-scoped WebFetch extraction/render configuration.
  * @property {"sequential"|"safe-parallel"} [piToolExecutionMode] Pi built-in tool scheduling mode. Safe parallelism is the default.
  * @property {"one-at-a-time"|"all"} [piToolParallelismMode] DEPRECATED. Compatibility alias mapped to piToolExecutionMode.
@@ -941,8 +941,11 @@ export type RuntimeRunOptions = {
      * Run-scoped WebSearch backend configuration.
      */
     webSearchConfig?: {
-        backend?: "auto" | "searxng" | "keyless";
+        backend?: "auto" | "searxng" | "codex" | "keyless";
         endpoint?: string;
+        codex?: {
+            model?: string;
+        };
     };
     /**
      * Run-scoped WebFetch extraction/render configuration.