@iislee/opencodex 2.11.0 → 2.31.0

package/src/providers/static-model-discovery.ts

@@ -0,0 +1,86 @@
+import type { OcxProviderConfig } from "../types";
+import {
+  getProviderRegistryEntry,
+  providerMatchesRegistryTransport,
+  type ProviderRegistryEntry,
+} from "./registry";
+
+const STATIC_MODEL_CATALOG_PROVIDER_IDS = new Set(["cline-pass", "mimo-free"]);
+
+function normalizedEndpoint(value: string): string {
+  const trimmed = value.trim();
+  try {
+    const parsed = new URL(trimmed);
+    parsed.pathname = parsed.pathname.replace(/\/+$/, "") || "/";
+    return parsed.toString().replace(/\/$/, "");
+  } catch {
+    return trimmed.replace(/\/+$/, "");
+  }
+}
+
+function exactRegistryTransportMatch(
+  entry: ProviderRegistryEntry,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>,
+  options: { allowLegacyMimoLocal?: boolean } = {},
+): boolean {
+  if (entry.allowBaseUrlOverride || /\{[^}]*\}/.test(entry.baseUrl)) return false;
+  if (typeof provider.baseUrl !== "string" || provider.adapter !== entry.adapter) return false;
+  const legacyMimoLocal = options.allowLegacyMimoLocal === true
+    && entry.id === "mimo-free"
+    && provider.authMode === "local";
+  if (provider.authMode !== undefined && provider.authMode !== "key" && !legacyMimoLocal) return false;
+  return normalizedEndpoint(provider.baseUrl) === normalizedEndpoint(entry.baseUrl);
+}
+
+/** Registry policy for providers whose maintained model list is authoritative. */
+export function registryEntrySupportsLiveModelDiscovery(entry: ProviderRegistryEntry): boolean {
+  return !STATIC_MODEL_CATALOG_PROVIDER_IDS.has(entry.id);
+}
+
+/**
+ * Static-catalog authority is tied to canonical provider identity and exact transport.
+ * Renamed/custom rows stay operator-owned: Cline and ClinePass intentionally share a transport,
+ * so destination matching alone cannot safely identify a renamed ClinePass configuration.
+ */
+export function staticModelCatalogEntryForProvider(
+  name: string,
+  provider: OcxProviderConfig,
+): ProviderRegistryEntry | undefined {
+  const entry = getProviderRegistryEntry(name);
+  if (!entry || !STATIC_MODEL_CATALOG_PROVIDER_IDS.has(entry.id)) return undefined;
+  return exactRegistryTransportMatch(entry, provider, { allowLegacyMimoLocal: true })
+    ? entry
+    : undefined;
+}
+
+export function providerSupportsLiveModelDiscovery(name: string, provider: OcxProviderConfig): boolean {
+  return staticModelCatalogEntryForProvider(name, provider) === undefined;
+}
+
+/**
+ * MiMo Free predates collision preservation in the registry. Keep same-named custom rows out of
+ * registry ownership without broadening the generic transport matcher to other key providers.
+ */
+export function providerMatchesRegistryTransportWithStaticGuards(
+  name: string,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>,
+): boolean {
+  if (name !== "mimo-free") return providerMatchesRegistryTransport(name, provider);
+  const entry = getProviderRegistryEntry(name);
+  return entry !== undefined
+    && exactRegistryTransportMatch(entry, provider, { allowLegacyMimoLocal: true });
+}
+
+/** Repair only registry-owned legacy state; operator-owned model lists stay untouched. */
+export function repairStaticModelCatalogProvider(name: string, provider: OcxProviderConfig): void {
+  const entry = staticModelCatalogEntryForProvider(name, provider);
+  if (!entry) return;
+  provider.liveModels = false;
+  if (
+    name === "mimo-free"
+    && entry.id === "mimo-free"
+    && (provider.authMode === undefined || provider.authMode === "local")
+  ) {
+    provider.authMode = "key";
+  }
+}

package/src/providers/xai-responses-opt-in.ts

@@ -0,0 +1,15 @@
+import type { OcxProviderConfig } from "../types";
+
+export const XAI_RESPONSES_OPT_IN_MODELS = ["grok-4.6", "grok-4.5"] as const;
+
+export type XaiResponsesOptInState = boolean | "mixed";
+
+/** Derived dashboard/API state for the two modelAdapters entries owned by the xAI opt-in. */
+export function xaiResponsesOptInState(provider: OcxProviderConfig): XaiResponsesOptInState {
+  const enabled = XAI_RESPONSES_OPT_IN_MODELS.map(
+    model => provider.modelAdapters?.[model] === "openai-responses",
+  );
+  if (enabled.every(Boolean)) return true;
+  if (enabled.some(Boolean)) return "mixed";
+  return false;
+}

package/src/providers/xai-transport.ts

@@ -53,7 +53,7 @@ function withoutUserOverridden(
 
 function withGeneratedRequestId(
   init: RequestInit | undefined,
-  configuredRequestId: string | undefined,
+  pinnedRequestId: string,
   stableHeaders: Readonly<Record<string, string>>,
 ): RequestInit {
   const headers = new Headers(init?.headers);
@@ -63,7 +63,7 @@ function withGeneratedRequestId(
   if (!headers.has(XAI_GROK_COMPATIBILITY.headers.requestId)) {
     headers.set(
       XAI_GROK_COMPATIBILITY.headers.requestId,
-      configuredRequestId ?? randomUUID(),
+      pinnedRequestId,
     );
   }
   return { ...init, headers };
@@ -83,7 +83,9 @@ export function deriveXaiConvId(promptCacheKey: string): string {
 
 /**
  * Resolve xAI's runtime transport without mutating persisted config. Conversation/session
- * affinity is stable for this resolved transport; request identity is generated per fetch.
+ * affinity is stable for this resolved transport; request identity is pinned per resolved
+ * transport (= per logical request until key rotation), so same-target replays and transient
+ * retries carry the same id while a rotated key gets a fresh one.
  * Agent, deployment, model-override, turn, mode, and user identity headers are intentionally
  * omitted because opencodex has no truthful values for the official fields.
  */
@@ -128,9 +130,14 @@ export function resolveProviderTransport(
     provider.headers,
     XAI_GROK_COMPATIBILITY.headers.requestId,
   );
+  // Pin the request id per resolved transport (= per logical request until key rotation):
+  // same-target 429 replays must carry the SAME x-grok-req-id as the original dispatch, and
+  // transient retries reuse one id so the upstream can dedupe them. A rotated key resolves a
+  // fresh transport, which gets its own id.
+  const requestId = configuredRequestId ?? randomUUID();
   const baseFetch = provider.fetch ?? globalThis.fetch;
   const attemptFetch = ((input, init) =>
-    baseFetch(input, withGeneratedRequestId(init, configuredRequestId, stableHeaders))) as typeof globalThis.fetch;
+    baseFetch(input, withGeneratedRequestId(init, requestId, stableHeaders))) as typeof globalThis.fetch;
 
   return {
     ...provider,

package/src/reasoning-effort.ts

@@ -19,6 +19,52 @@ export function isCodexReasoningEffort(effort: string): boolean {
   return CODEX_REASONING_SET.has(effort);
 }
 
+/**
+ * True for ladder members plus the `none`/`minimal` sentinels. Both are valid declared
+ * efforts (OpenAI accepts `minimal`; Codex validates `none` against
+ * `supported_reasoning_levels` for no-reasoning subagent spawns, #883/#962) but are NOT
+ * part of the low..ultra ladder: they never appear in default ladders, ranks, or clamps
+ * (`minimal` is mapped to `low` on the wire by requestToCodexEffort).
+ */
+export function isDeclaredReasoningEffort(effort: string): boolean {
+  return effort === "none" || effort === "minimal" || CODEX_REASONING_SET.has(effort);
+}
+
+/**
+ * Reorder any declared subset (low..ultra, plus the optional `none`/`minimal` sentinels
+ * first, in that order) into canonical order and drop duplicates. Catalog
+ * `supported_reasoning_levels` follow the input order and the fallback default picks the
+ * first entry, so a caller-chosen order would otherwise leak into the catalog.
+ */
+export function canonicalizeReasoningEfforts(values: readonly string[]): string[] {
+  const seen = new Set(values);
+  const ordered = CODEX_REASONING_ORDER.filter(effort => seen.has(effort));
+  const sentinels = ["none", "minimal"].filter(effort => seen.has(effort));
+  return [...sentinels, ...ordered];
+}
+
+/**
+ * Reasoning ladder accepted for the OpenAI vision sidecar. `ultra` is deliberately excluded:
+ * the vision describer is a single helper call, and `ultra` would be collapsed to `max` by the
+ * upstream client boundary anyway.
+ */
+export const VISION_REASONING_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
+export type VisionReasoningEffort = typeof VISION_REASONING_EFFORTS[number];
+
+/** True when `effort` is one of the vision sidecar's supported Responses reasoning levels. */
+export function isVisionReasoningEffort(effort: unknown): effort is VisionReasoningEffort {
+  return typeof effort === "string" && (VISION_REASONING_EFFORTS as readonly string[]).includes(effort);
+}
+
+/**
+ * Normalize a persisted/configured vision reasoning value. Invalid values (hand-edited config,
+ * stale files) degrade to `undefined` so the caller falls back to the documented default instead
+ * of forwarding an upstream-rejected effort.
+ */
+export function sanitizeVisionReasoning(effort: unknown): VisionReasoningEffort | undefined {
+  return isVisionReasoningEffort(effort) ? effort : undefined;
+}
+
 /** Position of `effort` in the Codex ladder (low=0 .. ultra=5), or -1 when not a ladder member. */
 export function codexEffortRank(effort: string): number {
   return CODEX_REASONING_ORDER.indexOf(effort);
@@ -44,7 +90,9 @@ export function sanitizeCodexReasoningEfforts(efforts: readonly string[] | undef
   const seen = new Set<string>();
   const out: string[] = [];
   for (const effort of efforts) {
-    if (!CODEX_REASONING_SET.has(effort) || seen.has(effort)) continue;
+    // `none`/`minimal` are valid declared sentinels, kept and sorted first (rank -1); they
+    // never appear in the default ladder.
+    if ((effort !== "none" && effort !== "minimal" && !CODEX_REASONING_SET.has(effort)) || seen.has(effort)) continue;
     seen.add(effort);
     out.push(effort);
   }

package/src/responses/compaction.ts

@@ -33,6 +33,24 @@ export const SUMMARY_PREFIX = "Another language model started to solve this prob
 
 export const OPAQUE_COMPACTION_NOTE = "[earlier conversation was compacted; the summary is stored in a format this model cannot read]";
 
+/**
+ * Item types in the compact wire family. Each carries an `encrypted_content` blob the client
+ * replays verbatim on every later turn, and the minting backend verifies it is unmodified.
+ *
+ * Keep this the only enumeration: a copy that listed just `compaction` let the response-side
+ * field backfill synthesize ids into the other two, which the client then replayed as "modified
+ * from the compact response".
+ */
+const COMPACTION_ITEM_TYPES: ReadonlySet<string> = new Set([
+  "compaction",
+  "compaction_summary",
+  "context_compaction",
+]);
+
+export function isCompactionItemType(type: unknown): boolean {
+  return typeof type === "string" && COMPACTION_ITEM_TYPES.has(type);
+}
+
 export function encodeCompactionSummary(summary: string): string {
   return OCX_COMPACTION_PREFIX + Buffer.from(summary, "utf-8").toString("base64");
 }
@@ -105,7 +123,14 @@ export function buildCompactV1Output(userMessages: string[], summary: string): R
       remaining -= msg.length;
     } else {
       // Budget partially covers this older message: keep its tail (most recent context) and stop.
-      selected.push(msg.slice(msg.length - remaining));
+      let tailStart = msg.length - remaining;
+      // Never start the retained tail on a lone LOW surrogate: the pair's
+      // other half would be lost and encoding substitutes U+FFFD.
+      if (tailStart > 0 && tailStart < msg.length) {
+        const first = msg.charCodeAt(tailStart);
+        if (first >= 0xdc00 && first <= 0xdfff) tailStart += 1;
+      }
+      selected.push(msg.slice(tailStart));
       break;
     }
   }

package/src/responses/custom-tool-compat.ts

@@ -0,0 +1,266 @@
+import { namespacedToolName } from "../types";
+import { collectResponsesToolGroups } from "./tool-groups";
+
+const ROUTED_CUSTOM_TOOL_PASSTHROUGH = new Set(["apply_patch"]);
+const BUILTIN_FUNCTIONS_NAMESPACE = "functions";
+
+function routedCustomToolPassesThrough(
+  name: string,
+  supportsResponsesCustomTools: boolean | undefined,
+): boolean {
+  return supportsResponsesCustomTools !== false && ROUTED_CUSTOM_TOOL_PASSTHROUGH.has(name);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function customToolInput(argumentsText: unknown): string {
+  if (typeof argumentsText !== "string") return "";
+  try {
+    const parsed = JSON.parse(argumentsText) as unknown;
+    if (isPlainObject(parsed) && typeof parsed.input === "string") return parsed.input;
+  } catch { /* malformed arguments stay visible to the client */ }
+  return argumentsText;
+}
+
+function customToolWireName(namespace: string | undefined, name: string): string {
+  return namespace === BUILTIN_FUNCTIONS_NAMESPACE ? name : namespacedToolName(namespace, name);
+}
+
+/** Final upstream identity of a call, including a namespace restored by an earlier rewrite. */
+export function routedCustomToolWireName(value: unknown): string | undefined {
+  if (!isPlainObject(value) || typeof value.name !== "string") return undefined;
+  return customToolWireName(
+    typeof value.namespace === "string" ? value.namespace : undefined,
+    value.name,
+  );
+}
+
+/**
+ * Names of converted custom declarations after namespace lowering. Restoration uses these exact
+ * wire identities so same-named function and custom children in different namespaces stay distinct.
+ */
+function collectRoutedCustomToolWireNames(
+  body: unknown,
+  supportsResponsesCustomTools?: boolean,
+): Set<string> {
+  const names = new Set<string>();
+  const groups = collectResponsesToolGroups(body);
+  const bareWireNames = new Set<string>();
+  for (const group of groups) {
+    for (const tool of group) {
+      if (
+        isPlainObject(tool)
+        && tool.type !== "namespace"
+        && typeof tool.name === "string"
+      ) bareWireNames.add(tool.name);
+    }
+  }
+
+  for (const group of groups) {
+    for (const tool of group) {
+      if (!isPlainObject(tool)) continue;
+      if (
+        tool.type === "custom"
+        && typeof tool.name === "string"
+        && !routedCustomToolPassesThrough(tool.name, supportsResponsesCustomTools)
+      ) {
+        names.add(tool.name);
+        continue;
+      }
+      if (tool.type !== "namespace" || typeof tool.name !== "string" || !Array.isArray(tool.tools)) {
+        continue;
+      }
+      for (const child of tool.tools) {
+        if (
+          isPlainObject(child)
+          && child.type === "custom"
+          && typeof child.name === "string"
+          && !routedCustomToolPassesThrough(child.name, supportsResponsesCustomTools)
+          && !(tool.name === BUILTIN_FUNCTIONS_NAMESPACE && bareWireNames.has(child.name))
+        ) names.add(customToolWireName(tool.name, child.name));
+      }
+    }
+  }
+  return names;
+}
+
+export function customToolItemId(id: unknown): unknown {
+  if (typeof id !== "string") return id;
+  return id.startsWith("fc_") ? `ctc_${id.slice(3)}` : id;
+}
+
+export function collectRoutedCustomToolNames(
+  body: unknown,
+  supportsResponsesCustomTools?: boolean,
+): Set<string> {
+  const names = new Set<string>();
+  const visit = (value: unknown): void => {
+    if (Array.isArray(value)) {
+      for (const entry of value) visit(entry);
+      return;
+    }
+    if (!isPlainObject(value)) return;
+    if (
+      value.type === "custom"
+      && typeof value.name === "string"
+      && !routedCustomToolPassesThrough(value.name, supportsResponsesCustomTools)
+    ) {
+      names.add(value.name);
+    }
+    for (const entry of Object.values(value)) visit(entry);
+  };
+  visit(body);
+  return names;
+}
+
+function collectConvertedCallIds(value: unknown, names: ReadonlySet<string>, out: Set<string>): void {
+  if (Array.isArray(value)) {
+    for (const entry of value) collectConvertedCallIds(entry, names, out);
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  if (
+    (value.type === "custom_tool_call" || value.type === "function_call")
+    && typeof value.name === "string"
+    && names.has(value.name)
+    && typeof value.call_id === "string"
+  ) {
+    out.add(value.call_id);
+  }
+  for (const entry of Object.values(value)) collectConvertedCallIds(entry, names, out);
+}
+
+function rewriteForUpstream(
+  value: unknown,
+  names: ReadonlySet<string>,
+  callIds: ReadonlySet<string>,
+): unknown {
+  if (Array.isArray(value)) return value.map(entry => rewriteForUpstream(entry, names, callIds));
+  if (!isPlainObject(value)) return value;
+
+  if (value.type === "custom" && typeof value.name === "string" && names.has(value.name)) {
+    const { format: _format, ...rest } = value;
+    const isDefinition = typeof value.description === "string"
+      || isPlainObject(value.format)
+      || isPlainObject(value.parameters);
+    if (!isDefinition) return { ...rest, type: "function" };
+    const inputDescription = value.name === "exec"
+      ? "JavaScript source for unified exec. Use await tools.exec_command(...) for shell commands and text(...) to return textual output; do not provide a bare shell command."
+      : "Raw input for this client-executed custom tool.";
+    return {
+      ...rest,
+      type: "function",
+      parameters: {
+        type: "object",
+        properties: {
+          input: {
+            type: "string",
+            description: inputDescription,
+          },
+        },
+        required: ["input"],
+        additionalProperties: false,
+      },
+    };
+  }
+
+  if (
+    value.type === "custom_tool_call"
+    && typeof value.name === "string"
+    && names.has(value.name)
+  ) {
+    const { input, id: _id, ...rest } = value;
+    return {
+      ...rest,
+      type: "function_call",
+      arguments: JSON.stringify({ input: typeof input === "string" ? input : "" }),
+    };
+  }
+
+  if (
+    value.type === "custom_tool_call_output"
+    && typeof value.call_id === "string"
+    && callIds.has(value.call_id)
+  ) {
+    return { ...value, type: "function_call_output" };
+  }
+
+  let changed = false;
+  const next: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const rewritten = rewriteForUpstream(entry, names, callIds);
+    next[key] = rewritten;
+    changed ||= rewritten !== entry;
+  }
+  return changed ? next : value;
+}
+
+export function rewriteRoutedCustomToolsForUpstream(
+  body: unknown,
+  supportsResponsesCustomTools?: boolean,
+): {
+  body: unknown;
+  names: Set<string>;
+} {
+  const conversionNames = collectRoutedCustomToolNames(body, supportsResponsesCustomTools);
+  const names = collectRoutedCustomToolWireNames(body, supportsResponsesCustomTools);
+  if (conversionNames.size === 0) return { body, names };
+  const callIds = new Set<string>();
+  collectConvertedCallIds(body, conversionNames, callIds);
+  return { body: rewriteForUpstream(body, conversionNames, callIds), names };
+}
+
+export function restoreRoutedCustomCalls(
+  value: unknown,
+  names: ReadonlySet<string>,
+): { value: unknown; changed: boolean } {
+  if (Array.isArray(value)) {
+    let changed = false;
+    const restored = value.map(entry => {
+      const result = restoreRoutedCustomCalls(entry, names);
+      changed ||= result.changed;
+      return result.value;
+    });
+    return changed ? { value: restored, changed: true } : { value, changed: false };
+  }
+  if (!isPlainObject(value)) return { value, changed: false };
+
+  let changed = false;
+  const restored: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const result = restoreRoutedCustomCalls(entry, names);
+    restored[key] = result.value;
+    changed ||= result.changed;
+  }
+
+  const wireName = routedCustomToolWireName(value);
+  if (value.type === "function_call" && wireName !== undefined && names.has(wireName)) {
+    restored.type = "custom_tool_call";
+    restored.id = customToolItemId(value.id);
+    restored.input = customToolInput(value.arguments);
+    delete restored.arguments;
+    changed = true;
+  }
+  return changed ? { value: restored, changed: true } : { value, changed: false };
+}
+
+export function restoreRoutedCustomCallsInJson(
+  text: string,
+  names: ReadonlySet<string>,
+): string {
+  if (names.size === 0) return text;
+  let payload: unknown;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return text;
+  }
+  const restored = restoreRoutedCustomCalls(payload, names);
+  return restored.changed ? JSON.stringify(restored.value) : text;
+}
+
+export function unwrapRoutedCustomToolArguments(argumentsText: unknown): string {
+  return customToolInput(argumentsText);
+}

package/src/responses/hosted-tool-policy.ts

@@ -0,0 +1,9 @@
+/** Hosted tools rejected by specific native model slugs. */
+const UNSUPPORTED_HOSTED_TOOLS: ReadonlyArray<{ match: (model: string) => boolean; tools: ReadonlySet<string> }> = [
+  { match: model => model.includes("codex-spark"), tools: new Set(["image_generation", "tool_search"]) },
+];
+
+/** True when forwarding this hosted tool to the model would be rejected upstream. */
+export function isHostedToolUnsupportedForModel(modelId: string, tool: string): boolean {
+  return UNSUPPORTED_HOSTED_TOOLS.some(entry => entry.match(modelId) && entry.tools.has(tool));
+}