@coseung2/opencodex 2.8.0-cs.16 → 2.8.0-cs.17

package/src/adapters/openai-chat.ts

@@ -9,6 +9,7 @@ import { redactSecretString } from "../lib/redact";
 import { contentPartsToText } from "./image";
 import { neutralizeIdentity } from "./identity";
 import { buildNonOpenAIToolCatalogNudgeForTools, shouldInjectNonOpenAIToolCatalogNudge } from "./tool-catalog-nudge";
+import { isXaiSchemaTarget, normalizeXaiToolParameters } from "./xai-tool-schema";
 import { openRouterProviderPayload, resolveOpenRouterRouting } from "../providers/openrouter-routing";
 import {
   isTranslatorBudgetExceededError,
@@ -360,16 +361,6 @@ function shouldSanitizeZenToolParameters(provider: OcxProviderConfig): boolean {
     || baseUrl === "https://opencode.ai/zen/go/v1";
 }
 
-const XAI_SCHEMA_BASE_URLS = new Set(["api.x.ai", "cli-chat-proxy.grok.com"]);
-
-function isXaiSchemaTarget(provider: OcxProviderConfig): boolean {
-  try {
-    return XAI_SCHEMA_BASE_URLS.has(new URL(provider.baseUrl).hostname);
-  } catch {
-    return false;
-  }
-}
-
 function isKimiSchemaTarget(provider: OcxProviderConfig): boolean {
   try {
     return new URL(provider.baseUrl).hostname === "api.kimi.com";
@@ -429,38 +420,6 @@ function ensureKimiRootObjectType(parameters: unknown): Record<string, unknown>
   return { ...obj, type: "object" };
 }
 
-function expandXaiRootObjectSchemas(schema: unknown): Record<string, unknown>[] | undefined {
-  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return undefined;
-  const obj = schema as Record<string, unknown>;
-  const compositionKey = ["oneOf", "anyOf"].find(key => Array.isArray(obj[key]));
-  if (!compositionKey) {
-    if (obj.type !== undefined && obj.type !== "object") return undefined;
-    return [{ ...obj, type: "object" }];
-  }
-
-  const siblings = Object.fromEntries(Object.entries(obj).filter(([key]) => key !== compositionKey));
-  const branches = obj[compositionKey];
-  if (!Array.isArray(branches)) return undefined;
-  const expanded: Record<string, unknown>[] = [];
-  for (const branch of branches) {
-    const variants = expandXaiRootObjectSchemas(branch);
-    if (!variants) return undefined;
-    for (const variant of variants) expanded.push({ ...siblings, ...variant });
-  }
-  return expanded.length > 0 ? expanded : undefined;
-}
-
-function normalizeXaiToolParameters(parameters: unknown): Record<string, unknown> | undefined {
-  const variants = expandXaiRootObjectSchemas(parameters);
-  if (!variants) return undefined;
-  if (variants.length === 1) return variants[0];
-  const root = parameters && typeof parameters === "object" && !Array.isArray(parameters)
-    ? parameters as Record<string, unknown>
-    : {};
-  const metadata = Object.fromEntries(Object.entries(root).filter(([key]) => key !== "oneOf" && key !== "anyOf" && key !== "type"));
-  return { ...metadata, oneOf: variants };
-}
-
 function toolsToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] | undefined {
   if (!parsed.context.tools || parsed.context.tools.length === 0) return undefined;
   const allowed = isAllowedToolChoice(parsed.options.toolChoice)

package/src/adapters/openai-responses.ts

@@ -3,7 +3,13 @@ import type { IncomingMeta, ProviderAdapter } from "./base";
 import { namespacedToolName, type AdapterEvent, type OcxParsedRequest, type OcxProviderConfig, type OcxUsage } from "../types";
 import { catalogModelSupportsReasoningSummaries } from "../codex/catalog";
 import { COMPACT_PROMPT, decodeCompactionSummary, SUMMARY_PREFIX } from "../responses/compaction";
+import { isOpenCodeMuseResponses } from "../providers/opencode-go-transport";
+import { isXaiResponsesDestination } from "../providers/xai-transport";
+import { debugProviderDiagnostic } from "../lib/debug";
+import { isXaiSchemaTarget, normalizeXaiToolParameters, XaiToolSchemaCompatibilityError } from "./xai-tool-schema";
+import { normalizeXaiResponsesWebSearch } from "./xai-web-search";
 import { collectResponsesToolGroups } from "../responses/tool-groups";
+import { lowerXaiResponsesCustomTools } from "../responses/xai-custom-tool-compat";
 import { decodeServerSentEvents } from "../lib/sse-decoder";
 import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
 import { OCX_REASONING_PREFIX } from "../responses/reasoning-envelope";
@@ -255,11 +261,8 @@ function normalizeConfiguredReasoningSummaryDelivery(
  * - Drops tool_search_call/tool_search_output input items
  * - Sets parallel_tool_calls to false
  */
-const MUSE_SPARK_WEB_SEARCH_STRICT_MODELS = new Set(["muse-spark-1.3-contributor", "muse-spark-1.2-contributor"]);
-
-function stripMuseSparkUnsupportedWebSearchFields(body: unknown, modelId: unknown): unknown {
-  if (!isPlainObject(body) || typeof modelId !== "string"
-    || !MUSE_SPARK_WEB_SEARCH_STRICT_MODELS.has(modelId.trim().toLowerCase())) return body;
+function stripMuseSparkUnsupportedWebSearchFields(body: unknown, modelId: unknown, responseUrl: string): unknown {
+  if (!isPlainObject(body) || !isOpenCodeMuseResponses(modelId, responseUrl)) return body;
   const rewrite = (tools: unknown[]) => {
     let changed = false;
     const next = tools.map(tool => {
@@ -389,12 +392,34 @@ function stripSparkCompatibility(body: unknown): unknown {
     : body;
 }
 
+function stripXaiOAuthOnlyParams(body: unknown, provider: OcxProviderConfig): unknown {
+  if (provider.authMode !== "oauth" || !isXaiResponsesDestination(provider) || !isPlainObject(body)) return body;
+  let changed = false;
+  const next: Record<string, unknown> = { ...body };
+  // The Grok subscription gateway has no caller-owned Priority/Fast contract. A global fastMode or
+  // stale client may still send the OpenAI service_tier parameter after the model switches wires.
+  if (Object.hasOwn(next, "service_tier")) { delete next.service_tier; changed = true; }
+  // xAI does not document OpenAI's text.verbosity control; stale catalog clients can keep sending
+  // it after a metadata refresh, so fail soft at the destination boundary as well.
+  if (isPlainObject(next.text) && Object.hasOwn(next.text, "verbosity")) {
+    const text = { ...next.text };
+    delete text.verbosity;
+    next.text = text;
+    changed = true;
+  }
+  return changed ? next : body;
+}
+
 function isPlainObject(v: unknown): v is Record<string, unknown> {
   return !!v && typeof v === "object" && !Array.isArray(v);
 }
 
-function normalizeFunctionToolSchema(tool: unknown): unknown {
+function normalizeFunctionToolSchema(tool: unknown, xaiTarget: boolean): unknown | undefined {
   if (!isPlainObject(tool) || tool.type !== "function") return tool;
+  if (xaiTarget) {
+    const parameters = normalizeXaiToolParameters(isPlainObject(tool.parameters) ? tool.parameters : {});
+    return parameters === undefined ? undefined : { ...tool, parameters };
+  }
   if (isPlainObject(tool.parameters) && tool.parameters.type === "object") return tool;
   return {
     ...tool,
@@ -402,16 +427,55 @@ function normalizeFunctionToolSchema(tool: unknown): unknown {
   };
 }
 
-function normalizeToolSchemas(body: unknown): unknown {
-  if (!isPlainObject(body)) return body;
+function reconcileToolChoiceForOmittedTools(
+  body: Record<string, unknown>,
+  omittedFunctionNames: ReadonlySet<string>,
+): Record<string, unknown> {
+  if (omittedFunctionNames.size === 0) return body;
+  const toolChoice = body.tool_choice;
+  if (!isPlainObject(toolChoice)) return body;
+  const refuse = (name: string): never => {
+    throw new XaiToolSchemaCompatibilityError(
+      `tool_choice requires function "${name}", but its parameter schema cannot be represented for this destination; `
+      + "relax tool_choice or simplify the tool's parameter schema",
+    );
+  };
+  if (toolChoice.type === "function" && typeof toolChoice.name === "string") {
+    return omittedFunctionNames.has(toolChoice.name) ? refuse(toolChoice.name) : body;
+  }
+  if (toolChoice.type === "allowed_tools" && Array.isArray(toolChoice.tools)) {
+    const omitted = toolChoice.tools.filter(tool =>
+      isPlainObject(tool)
+      && tool.type === "function"
+      && typeof tool.name === "string"
+      && omittedFunctionNames.has(tool.name));
+    if (omitted.length === 0) return body;
+    const kept = toolChoice.tools.filter(tool => !omitted.includes(tool));
+    if (kept.length === 0) {
+      const first = omitted[0];
+      return refuse(isPlainObject(first) && typeof first.name === "string" ? first.name : "unknown");
+    }
+    return { ...body, tool_choice: { ...toolChoice, tools: kept } };
+  }
+  return body;
+}
 
+function normalizeToolSchemas(body: unknown, xaiTarget: boolean): unknown {
+  if (!isPlainObject(body)) return body;
+  const omittedFunctionNames = new Set<string>();
   const normalizeTools = (tools: unknown[]): unknown[] => {
     let changed = false;
-    const normalized = tools.map((tool) => {
-      const fixed = normalizeFunctionToolSchema(tool);
+    const normalized: unknown[] = [];
+    for (const tool of tools) {
+      const fixed = normalizeFunctionToolSchema(tool, xaiTarget);
+      if (fixed === undefined) {
+        changed = true;
+        if (isPlainObject(tool) && typeof tool.name === "string") omittedFunctionNames.add(tool.name);
+        continue;
+      }
       if (fixed !== tool) changed = true;
-      return fixed;
-    });
+      normalized.push(fixed);
+    }
     return changed ? normalized : tools;
   };
 
@@ -431,7 +495,10 @@ function normalizeToolSchemas(body: unknown): unknown {
     });
     if (inputChanged) normalizedBody = { ...normalizedBody, input };
   }
-  return normalizedBody;
+  if (omittedFunctionNames.size > 0) {
+    debugProviderDiagnostic("openai-responses", "tool-schema-omitted", { omitted: [...omittedFunctionNames] });
+  }
+  return reconcileToolChoiceForOmittedTools(normalizedBody, omittedFunctionNames);
 }
 
 const MAX_RESPONSES_CALL_ID_LENGTH = 64;
@@ -1062,7 +1129,19 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
       if (parsed._compactionRequest === true && !isCanonicalOpenAiForwardProvider(provider)) {
         outBody = buildRoutedCompactionBody(outBody);
       }
-      const sanitizedBody = normalizeToolSchemas(stripMuseSparkUnsupportedWebSearchFields(stripSparkCompatibility(stripUnsupportedReasoningParams(stripItemIdsWhenUnstored(stripInvalidItemIds(stripUnsupportedHostedTools(sanitizeReasoningInputContent(scrubOcxCompactionItems(outBody))))))), parsed.modelId));
+      if (isXaiResponsesDestination(provider)) {
+        outBody = lowerXaiResponsesCustomTools(outBody).body;
+      }
+      const sanitizedBody = stripXaiOAuthOnlyParams(
+        normalizeXaiResponsesWebSearch(
+          normalizeToolSchemas(
+            stripMuseSparkUnsupportedWebSearchFields(stripSparkCompatibility(stripUnsupportedReasoningParams(stripItemIdsWhenUnstored(stripInvalidItemIds(stripUnsupportedHostedTools(sanitizeReasoningInputContent(scrubOcxCompactionItems(outBody))))))), parsed.modelId, url),
+            isXaiSchemaTarget(provider),
+          ),
+          provider,
+        ),
+        provider,
+      );
       const body = JSON.stringify(stripDisabledReasoningSummaries(
         normalizeConfiguredReasoningSummaryDelivery(sanitizedBody, provider, parsed.modelId),
         provider,

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

@@ -0,0 +1,78 @@
+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;
+}
+
+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;
+}
+
+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";
+}
+
+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;
+}
+
+function xaiTypesOverlap(left: string, right: string): boolean {
+  if (left === right) return true;
+  return (left === "integer" && right === "number") || (left === "number" && right === "integer");
+}
+
+/** Conservative proof: return true only when no instance can satisfy both schemas. */
+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 is provably disjoint, so `anyOf` and `oneOf` accept the same union. */
+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

@@ -0,0 +1,274 @@
+import type { OcxProviderConfig } from "../types";
+import { isSchemaObject, lookupLocalJsonPointer, xaiSchemasArePairwiseDisjoint } from "./xai-schema-analysis";
+
+/** A selected tool whose schema was omitted must fail locally instead of silently relaxing tool choice. */
+export class XaiToolSchemaCompatibilityError extends Error {}
+
+/** Public api.x.ai accepts root object unions; only the Grok CLI proxy rejects them. */
+export function isXaiSchemaTarget(provider: Pick<OcxProviderConfig, "baseUrl">): boolean {
+  try {
+    return new URL(provider.baseUrl).hostname === "cli-chat-proxy.grok.com";
+  } catch {
+    return false;
+  }
+}
+
+function stringRequiredFields(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+}
+
+const XAI_VARIANT_MERGE_KEYS = new Set([
+  "type", "properties", "required", "additionalProperties", "description", "title", "$comment", "$defs", "definitions",
+]);
+const XAI_MAX_SCHEMA_DEPTH = 64;
+const XAI_MAX_SCHEMA_NODES = 4_096;
+const XAI_MAX_ROOT_VARIANTS = 256;
+
+interface XaiSchemaBudget {
+  remainingNodes: number;
+  remainingVariants: number;
+}
+
+function createXaiSchemaBudget(): XaiSchemaBudget {
+  return { remainingNodes: XAI_MAX_SCHEMA_NODES, remainingVariants: XAI_MAX_ROOT_VARIANTS };
+}
+
+function composeXaiObjectSchemas(
+  inherited: Record<string, unknown>,
+  branch: Record<string, unknown>,
+): Record<string, unknown> {
+  const composed: Record<string, unknown> = { ...inherited, ...branch };
+  const inheritedProps = isSchemaObject(inherited.properties) ? inherited.properties : undefined;
+  const branchProps = isSchemaObject(branch.properties) ? branch.properties : undefined;
+  if (inheritedProps || branchProps) {
+    const properties: Record<string, unknown> = { ...(inheritedProps ?? {}) };
+    for (const [name, value] of Object.entries(branchProps ?? {})) {
+      const inheritedValue = inheritedProps?.[name];
+      properties[name] = inheritedValue !== undefined && JSON.stringify(inheritedValue) !== JSON.stringify(value)
+        ? { allOf: [inheritedValue, value] }
+        : value;
+    }
+    composed.properties = properties;
+  }
+  const required = [...new Set([
+    ...stringRequiredFields(inherited.required),
+    ...stringRequiredFields(branch.required),
+  ])];
+  if (required.length > 0) composed.required = required;
+  else delete composed.required;
+  return composed;
+}
+
+/** Resolve local refs under a bounded walk; ambiguous/cyclic/over-budget schemas fail closed. */
+function resolveXaiSchemaRefs(
+  schema: unknown,
+  root: Record<string, unknown>,
+  budget: XaiSchemaBudget,
+  stack: Set<string> = new Set(),
+  depth = 0,
+): unknown | undefined {
+  if (!isSchemaObject(schema)) return schema;
+  if (depth >= XAI_MAX_SCHEMA_DEPTH || budget.remainingNodes <= 0) return undefined;
+  budget.remainingNodes -= 1;
+
+  if (typeof schema.$ref === "string") {
+    const ref = schema.$ref;
+    if (stack.has(ref)) return undefined;
+    const target = lookupLocalJsonPointer(root, ref);
+    if (target === undefined) return undefined;
+    stack.add(ref);
+    const resolvedTarget = resolveXaiSchemaRefs(target, root, budget, stack, depth + 1);
+    stack.delete(ref);
+    if (resolvedTarget === undefined) return undefined;
+    const rest: Record<string, unknown> = { ...schema };
+    delete rest.$ref;
+    if (Object.keys(rest).length === 0) return resolvedTarget;
+    const resolvedRest = resolveXaiSchemaRefs(rest, root, budget, stack, depth + 1);
+    if (resolvedRest === undefined || !isSchemaObject(resolvedTarget) || !isSchemaObject(resolvedRest)) return undefined;
+    return composeXaiObjectSchemas(resolvedTarget, resolvedRest);
+  }
+
+  const resolved: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if ((key === "oneOf" || key === "anyOf") && Array.isArray(value)) {
+      const items: unknown[] = [];
+      for (const item of value) {
+        const next = resolveXaiSchemaRefs(item, root, budget, stack, depth + 1);
+        if (next === undefined) return undefined;
+        items.push(next);
+      }
+      resolved[key] = items;
+      continue;
+    }
+    if (key === "properties" && isSchemaObject(value)) {
+      const properties: Record<string, unknown> = {};
+      for (const [name, property] of Object.entries(value)) {
+        const next = resolveXaiSchemaRefs(property, root, budget, stack, depth + 1);
+        if (next === undefined) return undefined;
+        properties[name] = next;
+      }
+      resolved[key] = properties;
+      continue;
+    }
+    resolved[key] = value;
+  }
+  return resolved;
+}
+
+function xaiVariantIsConcreteObject(variant: Record<string, unknown>): boolean {
+  if (variant.type !== undefined && variant.type !== "object") return false;
+  return Object.keys(variant).every(key => XAI_VARIANT_MERGE_KEYS.has(key));
+}
+
+function variantProperties(variant: Record<string, unknown>): Record<string, unknown> {
+  return isSchemaObject(variant.properties) ? variant.properties : {};
+}
+
+/** Independent per-property unions are exact only when all variants carry the same property names and <=1 schema differs. */
+function xaiPropertyMergeIsLossless(variants: Record<string, unknown>[]): boolean {
+  const names = new Set<string>();
+  const props = variants.map(variant => {
+    const properties = variantProperties(variant);
+    for (const name of Object.keys(properties)) names.add(name);
+    return properties;
+  });
+  let schemaConflicts = 0;
+  for (const name of names) {
+    const values = props.map(property => property[name]);
+    if (values.some(value => value === undefined)) return false;
+    if (values.some(value => JSON.stringify(value) !== JSON.stringify(values[0]))) schemaConflicts += 1;
+  }
+  return schemaConflicts <= 1;
+}
+
+function xaiRequiredSetsMatch(variants: Record<string, unknown>[]): boolean {
+  const serialized = variants.map(variant => [...stringRequiredFields(variant.required)].sort().join("\0"));
+  return serialized.every(value => value === serialized[0]);
+}
+
+function uniqueXaiSchemas(values: unknown[]): unknown[] {
+  const unique: unknown[] = [];
+  const serialized = new Set<string>();
+  for (const value of values) {
+    const key = JSON.stringify(value);
+    if (serialized.has(key)) continue;
+    serialized.add(key);
+    unique.push(value);
+  }
+  return unique;
+}
+
+function mergeXaiAdditionalProperties(
+  variants: Record<string, unknown>[],
+): { ok: true; value?: unknown } | { ok: false } {
+  const values = variants.map(variant => variant.additionalProperties);
+  const explicit = values.filter(value => value !== undefined);
+  if (explicit.length === 0) return { ok: true };
+  if (explicit.length !== values.length) return { ok: false };
+  const hasFalse = explicit.some(value => value === false);
+  const permissive = explicit.filter(value => value !== false);
+  if (hasFalse && permissive.length > 0) return { ok: false };
+  if (hasFalse) return { ok: true, value: false };
+  const unique = uniqueXaiSchemas(permissive);
+  return unique.length === 1 ? { ok: true, value: unique[0] } : { ok: false };
+}
+
+interface XaiRootExpansion {
+  variants: Record<string, unknown>[];
+  isUnion: boolean;
+  exclusive: boolean;
+  nestedUnion: boolean;
+}
+
+function expandXaiRootObjectSchemas(
+  schema: unknown,
+  budget: XaiSchemaBudget,
+  depth = 0,
+): XaiRootExpansion | undefined {
+  if (!isSchemaObject(schema) || depth >= XAI_MAX_SCHEMA_DEPTH) return undefined;
+  const compositionKey = ["oneOf", "anyOf"].find(key => Array.isArray(schema[key]));
+  if (!compositionKey) {
+    if (schema.type !== undefined && schema.type !== "object") return undefined;
+    if (budget.remainingVariants <= 0) return undefined;
+    budget.remainingVariants -= 1;
+    return { variants: [{ ...schema, type: "object" }], isUnion: false, exclusive: false, nestedUnion: false };
+  }
+
+  const siblings = Object.fromEntries(Object.entries(schema).filter(([key]) => key !== compositionKey));
+  const branches = schema[compositionKey];
+  if (!Array.isArray(branches)) return undefined;
+  const expanded: Record<string, unknown>[] = [];
+  let exclusive = compositionKey === "oneOf";
+  let nestedUnion = false;
+  for (const branch of branches) {
+    const nested = expandXaiRootObjectSchemas(branch, budget, depth + 1);
+    if (!nested) return undefined;
+    exclusive ||= nested.exclusive;
+    nestedUnion ||= nested.isUnion || nested.nestedUnion;
+    for (const variant of nested.variants) expanded.push(composeXaiObjectSchemas(siblings, variant));
+  }
+  return expanded.length > 0 ? { variants: expanded, isUnion: true, exclusive, nestedUnion } : undefined;
+}
+
+/**
+ * Flatten only root object unions the Grok CLI proxy rejects, and only when the rewrite is lossless.
+ * The bounded ref/variant walk prevents adversarial tool schemas from causing exponential work.
+ */
+export function normalizeXaiToolParameters(parameters: unknown): Record<string, unknown> | undefined {
+  if (!isSchemaObject(parameters)) return undefined;
+  const budget = createXaiSchemaBudget();
+  const resolved = resolveXaiSchemaRefs(parameters, parameters, budget);
+  if (!isSchemaObject(resolved)) return undefined;
+
+  const normalizedRoot = { ...resolved };
+  delete normalizedRoot.$schema;
+  const expansion = expandXaiRootObjectSchemas(normalizedRoot, budget);
+  if (!expansion) return undefined;
+  const { variants, exclusive, nestedUnion } = expansion;
+  if (variants.length === 1) return xaiVariantIsConcreteObject(variants[0]) ? variants[0] : undefined;
+  if (!variants.every(xaiVariantIsConcreteObject) || !xaiRequiredSetsMatch(variants)) return undefined;
+  const additionalProperties = mergeXaiAdditionalProperties(variants);
+  if (!additionalProperties.ok || !xaiPropertyMergeIsLossless(variants)) return undefined;
+
+  const metadata = Object.fromEntries(Object.entries(normalizedRoot)
+    .filter(([key]) => key !== "oneOf" && key !== "anyOf" && key !== "type"));
+  delete metadata.properties;
+  delete metadata.required;
+  delete metadata.additionalProperties;
+
+  const propertyValues = new Map<string, unknown[]>();
+  for (const variant of variants) {
+    if (!isSchemaObject(variant.properties)) continue;
+    for (const [name, value] of Object.entries(variant.properties)) {
+      const values = propertyValues.get(name) ?? [];
+      values.push(value);
+      propertyValues.set(name, values);
+    }
+  }
+
+  const properties: Record<string, unknown> = {};
+  const differingNames: string[] = [];
+  for (const [name, values] of propertyValues) {
+    const unique = uniqueXaiSchemas(values);
+    if (unique.length === 1) {
+      properties[name] = unique[0];
+      continue;
+    }
+    if (exclusive && nestedUnion) return undefined;
+    differingNames.push(name);
+    properties[name] = exclusive && !xaiSchemasArePairwiseDisjoint(unique)
+      ? { oneOf: unique }
+      : { anyOf: unique };
+  }
+
+  let required = stringRequiredFields(variants[0]?.required);
+  if (exclusive && differingNames.length > 0) required = [...new Set([...required, ...differingNames])];
+
+  return {
+    ...metadata,
+    type: "object",
+    properties,
+    ...(required.length > 0 ? { required } : {}),
+    ...("value" in additionalProperties ? { additionalProperties: additionalProperties.value } : {}),
+  };
+}