@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/adapters/openai-responses.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import type { IncomingMeta, ProviderAdapter } from "./base";
 import { namespacedToolName, type AdapterEvent, type OcxParsedRequest, type OcxProviderConfig, type OcxUsage, type TierDecision } from "../types";
 import { catalogModelSupportsReasoningSummaries } from "../codex/catalog";
+import { applyCodexRoutingHint, CODEX_RESPONSES_LITE_HEADER, CODEX_ROUTING_HINT_HEADER } from "../codex/forward-transport-headers";
 import { COMPACT_PROMPT, compactionItemToText, decodeCompactionSummary, isCompactionItemType } from "../responses/compaction";
 import { collectResponsesToolGroups } from "../responses/tool-groups";
 import { isHostedToolUnsupportedForModel } from "../responses/hosted-tool-policy";
@@ -20,6 +21,7 @@ import { rewriteRoutedCustomToolsForUpstream } from "../responses/custom-tool-co
 import { rewriteRoutedToolSearchForUpstream } from "../responses/tool-search-compat";
 import { rewriteRoutedNamespaceToolsForUpstream } from "../responses/namespace-tool-compat";
 import { openaiResponsesUrl } from "./openai-responses-url";
+import { normalizeResponsesCodeMode } from "./responses-code-mode";
 import { injectXaiResponsesXSearch, normalizeXaiResponsesWebSearch } from "./xai-web-search";
 import { EMPTY_TOOL_OUTPUT_ANNOTATION, isWhitespaceOnlyTextPartArray } from "./empty-tool-output-annotation";
 import {
@@ -51,6 +53,7 @@ export const FORWARD_HEADERS = [
   "x-oai-attestation",
   "x-openai-subagent",
   "x-responsesapi-include-timing-metrics",
+  CODEX_RESPONSES_LITE_HEADER,
 ];
 
 /**
@@ -187,7 +190,7 @@ const CANONICAL_ONLY_TOOL_FIELDS: readonly { field: string; toolTypes?: Readonly
   // OWNERSHIP: official OpenAI API-key traffic and unclassified gateways ACCEPT this field, so
   // it is only stripped when the provider capability denies it (supportsOpenAiWebSearchToolFields
   // === false), matching stripOpenAiOnlyWebSearchFields; see
-  // tests/responses-routed-web-search-fields.test.ts.
+  // tests/responses/responses-routed-web-search-fields.test.ts.
   { field: "external_web_access", toolTypes: new Set(["web_search", "web_search_preview"]), capabilityGated: true },
   // Deferred-discovery marker. `activateDeferredTool` clears it only for tools a `tool_search_output`
   // already loaded, so a still-deferred declaration — including one promoted out of a namespace
@@ -906,6 +909,61 @@ function toolOutputText(output: unknown): string {
   }).filter(Boolean).join("\n");
 }
 
+/** True when an output can be losslessly represented as user-message content. */
+function isRepairableToolOutput(output: unknown): output is string | Record<string, unknown>[] {
+  if (typeof output === "string") return true;
+  if (!Array.isArray(output)) return false;
+  return output.every(part => {
+    if (!isPlainObject(part)) return false;
+    if (typeof part.type !== "string") return false;
+    if (["output_text", "text", "input_text"].includes(part.type)) {
+      return typeof part.text === "string";
+    }
+    if (part.type === "refusal") return typeof part.refusal === "string";
+    if (part.type === "encrypted_content") return typeof part.encrypted_content === "string";
+    if (part.type !== "input_image") return false;
+    const imageUrl = part.image_url;
+    const fileId = part.file_id;
+    const imageUrlIsString = typeof imageUrl === "string";
+    const fileIdIsString = typeof fileId === "string";
+    const hasUsableSource = (imageUrlIsString && imageUrl.length > 0)
+      || (fileIdIsString && fileId.length > 0);
+    const validSource = hasUsableSource
+      && (part.image_url === undefined || imageUrlIsString)
+      && (part.file_id === undefined || fileIdIsString);
+    const validDetail = part.detail === undefined
+      || (typeof part.detail === "string"
+        && ["auto", "low", "high", "original"].includes(part.detail));
+    return validSource && validDetail;
+  });
+}
+
+/** Convert orphaned tool output to user-message content without discarding valid images. */
+function orphanedToolOutputContent(output: unknown, callId = ""): Record<string, unknown>[] {
+  const marker = `[tool output for ${callId || "unknown call"}]`;
+  if (typeof output !== "string" && !Array.isArray(output)) {
+    return [{ type: "input_text", text: marker }];
+  }
+  if (!Array.isArray(output)) {
+    return [{ type: "input_text", text: `${marker}\n${toolOutputText(output)}` }];
+  }
+
+  const content: Record<string, unknown>[] = [{ type: "input_text", text: marker }];
+  for (const part of output) {
+    if (!isPlainObject(part)) continue;
+    if (part.type === "input_image") {
+      content.push(part);
+    } else if (part.type === "encrypted_content" && typeof part.encrypted_content === "string") {
+      content.push({ type: "input_text", text: "[encrypted content omitted]" });
+    } else if (typeof part.text === "string") {
+      content.push({ type: "input_text", text: part.text });
+    } else if (part.type === "refusal" && typeof part.refusal === "string") {
+      content.push({ type: "input_text", text: `[refusal] ${part.refusal}` });
+    }
+  }
+  return content;
+}
+
 /** True when a Responses tool output item is present but carries no usable content. */
 function isToolOutputEmpty(output: unknown): boolean {
   if (typeof output === "string") return output.trim() === "";
@@ -940,6 +998,32 @@ function annotateEmptyResponsesToolOutputs(body: unknown, enabled: boolean): unk
   return changed ? { ...body, input } : body;
 }
 
+/**
+ * Preserve the text of structurally invalid tool-output items before they reach a strict
+ * Responses parser. Stateful destinations may legitimately receive an output whose matching
+ * call lives behind `previous_response_id`, so ordinary orphan repair cannot run universally.
+ * A missing or empty `call_id`, however, cannot identify stored state on any destination.
+ */
+function repairUnidentifiedToolOutputItems(body: unknown): unknown {
+  if (!isPlainObject(body) || !Array.isArray(body.input)) return body;
+  let changed = false;
+  const input = body.input.map(item => {
+    if (!isPlainObject(item)
+      || (item.type !== "function_call_output" && item.type !== "custom_tool_call_output")
+      || (typeof item.call_id === "string" && item.call_id.length > 0)) {
+      return item;
+    }
+    if (!isRepairableToolOutput(item.output)) return item;
+    changed = true;
+    return {
+      type: "message",
+      role: "user",
+      content: orphanedToolOutputContent(item.output),
+    };
+  });
+  return changed ? { ...body, input } : body;
+}
+
 /**
  * Repair a forward-mode input array whose continuation context was lost. When the replay
  * expansion misses (proxy restart, unrecorded prior turn), previous_response_id is stripped
@@ -1060,12 +1144,17 @@ function repairOrphanedInputItems(body: unknown, dropReasoning: boolean, synthes
       flushPendingSyntheticOutputs();
       const callId = typeof item.call_id === "string" ? item.call_id : "";
       const paired = isFnOutput ? functionCallIds.has(callId) : customCallIds.has(callId);
-      if (!paired) {
+      const usableOutput = isRepairableToolOutput(item.output);
+      // A known orphan call is still useful as a labeled user message even when its output is
+      // incomplete. With no call id and no output, preserve the invalid item so validation fails
+      // closed rather than pretending any tool result exists.
+      const knownNullOutput = callId.length > 0 && item.output == null;
+      if (!paired && (knownNullOutput || usableOutput)) {
         changed = true;
         repaired.push({
           type: "message",
           role: "user",
-          content: [{ type: "input_text", text: `[tool output for ${callId || "unknown call"}]\n${toolOutputText(item.output)}` }],
+          content: orphanedToolOutputContent(item.output, callId),
         });
         continue;
       }
@@ -1893,14 +1982,67 @@ function normalizeImageGenClientTools(body: unknown): unknown {
  * carries a tool the upstream model 400s on. No-op (returns the original reference) when nothing
  * matches, keeping the common path allocation-free.
  */
-function stripUnsupportedHostedTools(body: unknown): unknown {
-  if (!isPlainObject(body) || !Array.isArray(body.tools)) return body;
+function stripUnsupportedHostedTools(body: unknown, provider: Pick<OcxProviderConfig, "baseUrl">): unknown {
+  if (!isPlainObject(body)) return body;
   const model = typeof body.model === "string" ? body.model : "";
-  const tools = body.tools.filter(t => {
-    const type = isPlainObject(t) && typeof t.type === "string" ? t.type : undefined;
-    return !type || !isHostedToolUnsupportedForModel(model, type);
-  });
-  return tools.length === body.tools.length ? body : { ...body, tools };
+  const filterTools = (tools: unknown[]): unknown[] => {
+    const filtered = tools.filter(t => {
+      const type = isPlainObject(t) && typeof t.type === "string" ? t.type : undefined;
+      return !type || !isHostedToolUnsupportedForModel(model, type, provider.baseUrl);
+    });
+    return filtered.length === tools.length ? tools : filtered;
+  };
+
+  let next: Record<string, unknown> = body;
+  let changed = false;
+  if (Array.isArray(body.tools)) {
+    const tools = filterTools(body.tools);
+    if (tools !== body.tools) {
+      next = { ...next, tools };
+      changed = true;
+    }
+  }
+  if (Array.isArray(body.input)) {
+    let inputChanged = false;
+    const input = body.input.map(item => {
+      if (!isPlainObject(item) || item.type !== "additional_tools" || !Array.isArray(item.tools)) return item;
+      const tools = filterTools(item.tools);
+      if (tools === item.tools) return item;
+      inputChanged = true;
+      return { ...item, tools };
+    });
+    if (inputChanged) {
+      next = { ...next, input };
+      changed = true;
+    }
+  }
+
+  const toolChoice = next.tool_choice;
+  if (isPlainObject(toolChoice) && toolChoice.type === "allowed_tools" && Array.isArray(toolChoice.tools)) {
+    const tools = filterTools(toolChoice.tools);
+    if (tools !== toolChoice.tools) {
+      next = { ...next, tool_choice: tools.length > 0 ? { ...toolChoice, tools } : "none" };
+      changed = true;
+    }
+  } else if (
+    isPlainObject(toolChoice)
+    && typeof toolChoice.type === "string"
+    && isHostedToolUnsupportedForModel(model, toolChoice.type, provider.baseUrl)
+  ) {
+    next = { ...next, tool_choice: "none" };
+    changed = true;
+  } else if (changed && toolChoice === "required") {
+    const hasDeclaredTools = (Array.isArray(next.tools) && next.tools.length > 0)
+      || (Array.isArray(next.input) && next.input.some(item =>
+        isPlainObject(item)
+        && item.type === "additional_tools"
+        && Array.isArray(item.tools)
+        && item.tools.length > 0));
+    if (!hasDeclaredTools) {
+      next = { ...next, tool_choice: "none" };
+    }
+  }
+  return changed ? next : body;
 }
 
 /**
@@ -1966,10 +2108,10 @@ export function stripOpenAiOnlyWebSearchFields(body: unknown): unknown {
 }
 
 /**
- * Muse Spark ids whose Responses gateway refuses `search_content_types` on a plain
+ * Muse Spark ids whose Responses gateway refuses provider-specific fields on a plain
  * `web_search` tool. Membership, not equality: 1.3 shipped 2026-09-02 as the
  * same-shaped successor to 1.2 on the same Zen wire, and an equality check would
- * have let a Codex-emitted `web_search` + `search_content_types` body reach the
+ * have let a Codex-emitted `web_search` body reach the
  * gateway and come back 400 for every request the moment 1.3 was selected.
  */
 const MUSE_SPARK_WEB_SEARCH_STRICT_MODELS = new Set([
@@ -1977,26 +2119,51 @@ const MUSE_SPARK_WEB_SEARCH_STRICT_MODELS = new Set([
   "muse-spark-1.2-contributor",
 ]);
 
+const MUSE_SPARK_WEB_SEARCH_STRICT_RESPONSE_URLS = new Set([
+  "https://opencode.ai/zen/v1/responses",
+  "https://opencode.ai/zen/go/v1/responses",
+]);
+
+const MUSE_SPARK_UNSUPPORTED_WEB_SEARCH_FIELDS = [
+  "search_content_types",
+  "indexed_web_access",
+] as const;
+
 /**
- * OpenCode Zen / Go Muse Spark Responses gateway refuses `search_content_types`
- * on a plain `web_search` tool (400) but accepts it on `web_search_preview`; a
- * plain `web_search` is also accepted. Probed directly against the gateway on
- * 2026-08-26: `web_search` + `search_content_types` -> 400, `web_search_preview`
- * + `search_content_types` -> 200, plain `web_search` -> 200. Luna accepts every
- * shape, so this is Muse-only. Drop only the field the gateway refuses while
- * keeping the tool type and every other accepted option intact.
+ * OpenCode Zen / Go Muse Spark Responses gateway refuses a short list of Codex
+ * `web_search` fields. `web_search_preview` keeps its accepted shape, and Luna
+ * remains untouched. Match the exact effective request URL; malformed, credentialed,
+ * or parameterized destinations keep their original body instead of assuming this
+ * gateway contract. Keep the rejected names together so a newly identified field is
+ * a one-line compatibility update rather than another bespoke rewrite.
  */
-function stripMuseSparkUnsupportedWebSearchFields(body: unknown, modelId: unknown): unknown {
+function stripMuseSparkUnsupportedWebSearchFields(
+  body: unknown,
+  modelId: unknown,
+  responseUrl: string,
+): unknown {
   if (!isPlainObject(body)) return body;
   if (typeof modelId !== "string") return body;
   if (!MUSE_SPARK_WEB_SEARCH_STRICT_MODELS.has(modelId.trim().toLowerCase())) return body;
+  let destination: string;
+  try {
+    const url = new URL(responseUrl);
+    if (url.username || url.password || url.search || url.hash) return body;
+    destination = `${url.origin.toLowerCase()}${url.pathname.replace(/\/+$/, "")}`;
+  } catch {
+    return body;
+  }
+  if (!MUSE_SPARK_WEB_SEARCH_STRICT_RESPONSE_URLS.has(destination)) return body;
 
   const rewriteTools = (tools: unknown[]): { tools: unknown[]; changed: boolean } => {
     let changed = false;
     const rewritten = tools.map(tool => {
       if (!isPlainObject(tool) || tool.type !== "web_search") return tool;
-      if (!Object.hasOwn(tool, "search_content_types")) return tool;
-      const { search_content_types: _dropped, ...rest } = tool;
+      if (!MUSE_SPARK_UNSUPPORTED_WEB_SEARCH_FIELDS.some(field => Object.hasOwn(tool, field))) {
+        return tool;
+      }
+      const rest = { ...tool };
+      for (const field of MUSE_SPARK_UNSUPPORTED_WEB_SEARCH_FIELDS) delete rest[field];
       changed = true;
       return rest;
     });
@@ -2152,7 +2319,14 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         if (mayForwardCallerCredentials) {
           for (const h of FORWARD_HEADERS) {
             const v = incoming?.headers.get(h);
-            if (v) headers[h] = v;                                      // …so forwarded auth always wins.
+            if (v) {
+              if (h === CODEX_RESPONSES_LITE_HEADER) {
+                for (const name of Object.keys(headers)) {
+                  if (name.toLowerCase() === h) delete headers[name];
+                }
+              }
+              headers[h] = v; // …so genuine forwarded fields win.
+            }
           }
         }
         const override = runtimeProvider._codexAccountOverride;
@@ -2265,18 +2439,22 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         if (provider.supportsOpenAiWebSearchToolFields === false) {
           outBody = stripOpenAiOnlyWebSearchFields(outBody);
         }
-        outBody = stripMuseSparkUnsupportedWebSearchFields(outBody, parsed.modelId);
+        outBody = stripMuseSparkUnsupportedWebSearchFields(outBody, parsed.modelId, url);
         // Last, so promoted namespace children are also cleared of Codex-private fields.
         outBody = stripCanonicalOnlyToolFields(outBody, provider.supportsOpenAiWebSearchToolFields === false);
       }
       // Same predicate as the routedCompaction gate in handleResponses(): an authMode check would
       // let a noncanonical custom forward provider skip this rewrite while the server still routes
       // it as a summarizer turn (#422). The compaction body build removes the tool surface and must
-      // therefore be the last routed transform: anything before it may depend on the declarations;
-      // anything after it cannot.
+      // therefore be the last routed transform that may depend on those declarations. Structural
+      // sanitizers below can still run after it.
+      outBody = normalizeResponsesCodeMode(outBody, parsed, provider);
       if (parsed._compactionRequest === true && !isCanonicalOpenAiForwardProvider(provider)) {
         outBody = buildRoutedCompactionBody(outBody);
       }
+      // Run after routed compaction so nested input_image parts are replaced before a malformed
+      // tool output is flattened to text and can no longer be inspected structurally.
+      outBody = repairUnidentifiedToolOutputItems(outBody);
       const threadServingIdentityChanged = parsed._stripReasoningEncryptedContent === true;
       const sanitizedBody = normalizeToolSchemas(
         stripSparkCompatibility(
@@ -2296,6 +2474,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
                       stripEncryptedContent: threadServingIdentityChanged,
                     },
                   ),
+                  provider,
                 ),
               ),
             ),
@@ -2312,6 +2491,17 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         provider,
         parsed.modelId,
       );
+      if (isCanonicalOpenAiForwardProvider(provider)) {
+        const routingHeaders = new Headers(headers);
+        applyCodexRoutingHint(routingHeaders, finalBody);
+        // Static headers may use mixed casing. Remove every stale spelling
+        // without normalizing unrelated headers returned by this adapter.
+        for (const name of Object.keys(headers)) {
+          if (name.toLowerCase() === CODEX_ROUTING_HINT_HEADER) delete headers[name];
+        }
+        const hint = routingHeaders.get(CODEX_ROUTING_HINT_HEADER);
+        if (hint !== null) headers[CODEX_ROUTING_HINT_HEADER] = hint;
+      }
       const actualServiceTier = isPlainObject(finalBody) && typeof finalBody.service_tier === "string"
         ? finalBody.service_tier
         : null;

package/src/adapters/responses-code-mode.ts

@@ -0,0 +1,59 @@
+import { toolChoiceToolPredicate, type OcxParsedRequest, type OcxProviderConfig } from "../types";
+import { isOpenAiOperatedResponsesDestination } from "../providers/openai-tiers";
+import { CODE_MODE_RESULT_ECHO_SENTENCE, normalizeEmptyExecToolResultText } from "./exec-tool-result-normalize";
+import { isBareShellBridgeTool, isCodexCodeModeExecTool } from "./tool-catalog-nudge";
+
+function record(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Inspect the whole result, not just its empty header: later text or media is real output. */
+function textOnlyOutput(output: unknown): string | undefined {
+  if (typeof output === "string") return output;
+  if (!Array.isArray(output)) return undefined;
+  if (!output.every(part => record(part)
+    && ["text", "input_text", "output_text"].includes(String(part.type))
+    && typeof part.text === "string")) return undefined;
+  return output.map(part => part.text).join("\n");
+}
+
+function withExecInputGuidance(tool: unknown): unknown {
+  if (!record(tool) || tool.type !== "function" || tool.name !== "exec" || tool.namespace !== undefined) return tool;
+  if (!record(tool.parameters) || !record(tool.parameters.properties) || !record(tool.parameters.properties.input)) return tool;
+  return { ...tool, parameters: { ...tool.parameters, properties: {
+    ...tool.parameters.properties,
+    input: {
+      ...tool.parameters.properties.input,
+      description: `JavaScript source for unified exec; do not provide a bare shell command. ${CODE_MODE_RESULT_ECHO_SENTENCE}`,
+    },
+  } } };
+}
+
+/** Native routed Responses needs the same first-call/output contract as translated adapters. */
+export function normalizeResponsesCodeMode(body: unknown, parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown {
+  if (!record(body) || parsed._compactionRequest || isOpenAiOperatedResponsesDestination(provider)) return body;
+  const visible = parsed.context.tools?.filter(toolChoiceToolPredicate(parsed.options.toolChoice, parsed.context.tools));
+  if (!visible?.some(isCodexCodeModeExecTool) || visible.some(isBareShellBridgeTool)) return body;
+  const instructions = typeof body.instructions === "string" ? body.instructions : "";
+  const input = Array.isArray(body.input) ? body.input : undefined;
+  const execCalls = new Set(input?.filter(item => record(item)
+    && (item.type === "function_call" || item.type === "custom_tool_call")
+    && item.name === "exec" && item.namespace === undefined && typeof item.call_id === "string")
+    .map(item => item.call_id));
+  return {
+    ...body,
+    instructions: instructions.includes(CODE_MODE_RESULT_ECHO_SENTENCE)
+      ? instructions : [instructions, CODE_MODE_RESULT_ECHO_SENTENCE].filter(Boolean).join("\n\n"),
+    ...(Array.isArray(body.tools) ? { tools: body.tools.map(withExecInputGuidance) } : {}),
+    ...(input ? { input: input.map(item => {
+      if (!record(item)) return item;
+      if (item.type === "additional_tools" && Array.isArray(item.tools)) {
+        return { ...item, tools: item.tools.map(withExecInputGuidance) };
+      }
+      if ((item.type !== "function_call_output" && item.type !== "custom_tool_call_output") || !execCalls.has(item.call_id)) return item;
+      const text = textOnlyOutput(item.output);
+      const normalized = text === undefined ? undefined : normalizeEmptyExecToolResultText(text, { toolName: "exec" });
+      return normalized === undefined ? item : { ...item, output: normalized };
+    }) } : {}),
+  };
+}

package/src/adapters/tool-catalog-nudge.ts

@@ -121,7 +121,7 @@ export function buildNonOpenAIToolCatalogNudgeFromNames(
     "Call only listed names with their listed argument keys; do not invent, translate, or rename tools.",
     "Names mentioned only in instructions, tool descriptions, argument descriptions, or nested helper APIs are not additional top-level tools.",
     verifiedCodeModeExecName
-      ? "`" + verifiedCodeModeExecName + "` is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.<name>(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `" + verifiedCodeModeExecName + "`'s description is not absence: deferred helpers stay callable on `tools.<name>`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names. " + CODE_MODE_RESULT_ECHO_SENTENCE + " Nested `tools.apply_patch(input)` is host-executed: the string must begin exactly with `*** Begin Patch` and end with `*** End Patch` (no trailing `***` on those lines). OpenCodex does not rewrite JavaScript inside exec, so a decorated `*** Begin Patch ***` envelope is rejected by Codex before the file is touched."
+      ? "`" + verifiedCodeModeExecName + "` is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.<name>(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `" + verifiedCodeModeExecName + "`'s description is not absence: deferred helpers stay callable on `tools.<name>`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names. " + CODE_MODE_RESULT_ECHO_SENTENCE + " Nested `tools.apply_patch(input)` is host-executed: the string must begin exactly with `*** Begin Patch` and end with `*** End Patch`, each marker line being three asterisks, one space, the two words, then end of line with no further asterisks. OpenCodex does not rewrite JavaScript inside exec, so extra asterisks on a marker line are rejected by Codex before the file is touched."
       : "If a listed tool exposes nested helpers such as a tools.* API, call the listed parent tool and use those helpers only inside that tool's input.",
     unavailableNeighborNames.length > 0
       ? "Do not use neighboring-agent tool names " + quoteNames(unavailableNeighborNames) + " unless this turn's catalog lists those exact names."

package/src/adapters/xai-schema-analysis.ts

@@ -0,0 +1,86 @@
+export function isSchemaObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function decodeJsonPointerToken(token: string): string {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/** Resolve a local `#/`-rooted JSON Pointer against `root`; undefined when it does not resolve. */
+export function lookupLocalJsonPointer(root: unknown, ref: string): unknown {
+  if (ref === "#" || ref === "#/") return root;
+  if (!ref.startsWith("#/")) return undefined;
+  let current: unknown = root;
+  for (const token of ref.slice(2).split("/").map(decodeJsonPointerToken)) {
+    if (!isSchemaObject(current) || !Object.hasOwn(current, token)) return undefined;
+    current = current[token];
+  }
+  return current;
+}
+
+/** Values a schema pins through `const`/`enum`, or undefined when it pins none. */
+function xaiLiteralValues(schema: unknown): unknown[] | undefined {
+  if (!isSchemaObject(schema)) return undefined;
+  if (Object.hasOwn(schema, "const")) return [schema.const];
+  if (Array.isArray(schema.enum)) return schema.enum;
+  return undefined;
+}
+
+/** JSON type name for a literal, so it can be compared against a `type` keyword. */
+function xaiJsonTypeOf(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "string") return "string";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  return "object";
+}
+
+/** Types a schema declares, or undefined when it constrains none. */
+function xaiDeclaredTypes(schema: unknown): Set<string> | undefined {
+  if (!isSchemaObject(schema)) return undefined;
+  const type = schema.type;
+  if (typeof type === "string") return new Set([type]);
+  if (Array.isArray(type) && type.every(item => typeof item === "string")) return new Set(type as string[]);
+  return undefined;
+}
+
+/** `integer` is a subset of `number`, so those two names overlap rather than exclude. */
+function xaiTypesOverlap(left: string, right: string): boolean {
+  if (left === right) return true;
+  return (left === "integer" && right === "number") || (left === "number" && right === "integer");
+}
+
+/**
+ * Conservative mutual-exclusion test: true only when no instance can satisfy both schemas.
+ * Proof comes from disjoint literal sets or disjoint declared types; anything it cannot prove
+ * is reported as overlapping so the caller refuses the merge instead of widening the schema.
+ */
+function xaiSchemasAreProvablyDisjoint(left: unknown, right: unknown): boolean {
+  const leftValues = xaiLiteralValues(left);
+  const rightValues = xaiLiteralValues(right);
+  if (leftValues && rightValues) {
+    const seen = new Set(rightValues.map(value => JSON.stringify(value)));
+    return leftValues.every(value => !seen.has(JSON.stringify(value)));
+  }
+  const leftTypes = xaiDeclaredTypes(left);
+  const rightTypes = xaiDeclaredTypes(right);
+  const literalsExcludedByTypes = (values: unknown[], types: Set<string>): boolean =>
+    values.every(value => ![...types].some(type => xaiTypesOverlap(xaiJsonTypeOf(value), type)));
+  if (leftValues && rightTypes) return literalsExcludedByTypes(leftValues, rightTypes);
+  if (rightValues && leftTypes) return literalsExcludedByTypes(rightValues, leftTypes);
+  if (leftTypes && rightTypes) {
+    return ![...leftTypes].some(leftType => [...rightTypes].some(rightType => xaiTypesOverlap(leftType, rightType)));
+  }
+  return false;
+}
+
+/** Every pair provably disjoint, so a union over them accepts each instance exactly once. */
+export function xaiSchemasArePairwiseDisjoint(schemas: unknown[]): boolean {
+  for (let i = 0; i < schemas.length; i += 1) {
+    for (let j = i + 1; j < schemas.length; j += 1) {
+      if (!xaiSchemasAreProvablyDisjoint(schemas[i], schemas[j])) return false;
+    }
+  }
+  return true;
+}

package/src/adapters/xai-tool-schema.ts

@@ -1,8 +1,6 @@
 import type { OcxProviderConfig } from "../types";
-
-function isSchemaObject(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
+export { lookupLocalJsonPointer } from "./xai-schema-analysis";
+import { isSchemaObject, lookupLocalJsonPointer, xaiSchemasArePairwiseDisjoint } from "./xai-schema-analysis";
 
 export function isXaiSchemaTarget(provider: Pick<OcxProviderConfig, "baseUrl">): boolean {
   try {
@@ -58,22 +56,6 @@ function createXaiSchemaBudget(): XaiSchemaBudget {
   return { remainingNodes: XAI_MAX_SCHEMA_NODES, remainingVariants: XAI_MAX_ROOT_VARIANTS };
 }
 
-function decodeJsonPointerToken(token: string): string {
-  return token.replace(/~1/g, "/").replace(/~0/g, "~");
-}
-
-/** Resolve a local `#/`-rooted JSON Pointer against `root`; undefined when it does not resolve. */
-export function lookupLocalJsonPointer(root: unknown, ref: string): unknown {
-  if (ref === "#" || ref === "#/") return root;
-  if (!ref.startsWith("#/")) return undefined;
-  let current: unknown = root;
-  for (const token of ref.slice(2).split("/").map(decodeJsonPointerToken)) {
-    if (!isSchemaObject(current) || !Object.hasOwn(current, token)) return undefined;
-    current = current[token];
-  }
-  return current;
-}
-
 /** Resolve local `#/` `$ref`s. Unresolvable, cyclic, or over-budget refs return undefined. */
 function resolveXaiSchemaRefs(
   schema: unknown,
@@ -168,73 +150,6 @@ function xaiRequiredSetsMatch(variants: Record<string, unknown>[]): boolean {
   return serialized.every(value => value === serialized[0]);
 }
 
-/** Values a schema pins through `const`/`enum`, or undefined when it pins none. */
-function xaiLiteralValues(schema: unknown): unknown[] | undefined {
-  if (!isSchemaObject(schema)) return undefined;
-  if (Object.hasOwn(schema, "const")) return [schema.const];
-  if (Array.isArray(schema.enum)) return schema.enum;
-  return undefined;
-}
-
-/** JSON type name for a literal, so it can be compared against a `type` keyword. */
-function xaiJsonTypeOf(value: unknown): string {
-  if (value === null) return "null";
-  if (Array.isArray(value)) return "array";
-  if (typeof value === "string") return "string";
-  if (typeof value === "boolean") return "boolean";
-  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
-  return "object";
-}
-
-/** Types a schema declares, or undefined when it constrains none. */
-function xaiDeclaredTypes(schema: unknown): Set<string> | undefined {
-  if (!isSchemaObject(schema)) return undefined;
-  const type = schema.type;
-  if (typeof type === "string") return new Set([type]);
-  if (Array.isArray(type) && type.every(item => typeof item === "string")) return new Set(type as string[]);
-  return undefined;
-}
-
-/** `integer` is a subset of `number`, so those two names overlap rather than exclude. */
-function xaiTypesOverlap(left: string, right: string): boolean {
-  if (left === right) return true;
-  return (left === "integer" && right === "number") || (left === "number" && right === "integer");
-}
-
-/**
- * Conservative mutual-exclusion test: true only when no instance can satisfy both schemas.
- * Proof comes from disjoint literal sets or disjoint declared types; anything it cannot prove
- * is reported as overlapping so the caller refuses the merge instead of widening the schema.
- */
-function xaiSchemasAreProvablyDisjoint(left: unknown, right: unknown): boolean {
-  const leftValues = xaiLiteralValues(left);
-  const rightValues = xaiLiteralValues(right);
-  if (leftValues && rightValues) {
-    const seen = new Set(rightValues.map(value => JSON.stringify(value)));
-    return leftValues.every(value => !seen.has(JSON.stringify(value)));
-  }
-  const leftTypes = xaiDeclaredTypes(left);
-  const rightTypes = xaiDeclaredTypes(right);
-  const literalsExcludedByTypes = (values: unknown[], types: Set<string>): boolean =>
-    values.every(value => ![...types].some(type => xaiTypesOverlap(xaiJsonTypeOf(value), type)));
-  if (leftValues && rightTypes) return literalsExcludedByTypes(leftValues, rightTypes);
-  if (rightValues && leftTypes) return literalsExcludedByTypes(rightValues, leftTypes);
-  if (leftTypes && rightTypes) {
-    return ![...leftTypes].some(leftType => [...rightTypes].some(rightType => xaiTypesOverlap(leftType, rightType)));
-  }
-  return false;
-}
-
-/** Every pair provably disjoint, so a union over them accepts each instance exactly once. */
-function xaiSchemasArePairwiseDisjoint(schemas: unknown[]): boolean {
-  for (let i = 0; i < schemas.length; i += 1) {
-    for (let j = i + 1; j < schemas.length; j += 1) {
-      if (!xaiSchemasAreProvablyDisjoint(schemas[i], schemas[j])) return false;
-    }
-  }
-  return true;
-}
-
 /** Deduplicate schemas by serialized shape, preserving first-seen order. */
 function uniqueXaiSchemas(values: unknown[]): unknown[] {
   const unique: unknown[] = [];

package/src/adapters/xai-web-search.ts

@@ -55,7 +55,7 @@ function normalizeToolGroup(tools: unknown[]): ToolGroupRewrite {
     // `search_context_size` 400s, while `user_location`, `search_content_types`, `filters` and
     // `enable_image_search` are all accepted. Deleting the accepted ones was a silent capability
     // loss, and it contradicted the sibling layer, whose own probe note already records
-    // user_location/filters as accepted (tests/responses-routed-web-search-fields.test.ts).
+    // user_location/filters as accepted (tests/responses/responses-routed-web-search-fields.test.ts).
     delete next.external_web_access;
     delete next.search_context_size;
     if (enableImageSearch && !Object.hasOwn(next, "enable_image_search")) {