@iislee/opencodex 2.11.0

package/src/providers/slug-codec.ts

@@ -0,0 +1,67 @@
+/**
+ * Codex-facing slug codec for routed models whose NATIVE ids contain "/".
+ *
+ * Codex's models-manager resolves per-model metadata (effort ladder, context window,
+ * capabilities — "tagging") with an exact one-slash rule: the namespaced-suffix lookup
+ * (codex-rs models-manager/src/manager.rs, `find_model_by_namespaced_suffix`) splits
+ * once on "/" and rejects the lookup when the remainder still contains "/". Providers
+ * whose native ids are themselves namespaced (zenmux `moonshotai/kimi-k3-free`,
+ * openrouter `anthropic/...`, nvidia `moonshotai/...`, together, fireworks, …) would
+ * otherwise produce two-slash Codex slugs that silently fall back to default metadata.
+ *
+ * Contract:
+ * - Codex-facing surfaces (catalog entries, picker lists, Codex-bound config picks)
+ *   use `routedSlug(provider, id)` — inner slashes become "-".
+ * - Internal state (upstream requests, logs, usage, jawcode metadata, combo keys)
+ *   keeps the native id. Decoding is an EXACT bijective lookup against the provider's
+ *   known native ids — never a blind "-" → "/" replace — with three ordered rules:
+ *   native exact match (back-compat with raw full-slash selectors) > unique alias
+ *   match > pass-through unchanged (honest upstream error).
+ * - Config comparisons are tolerant via `slugEquals`/`slugsEquivalent` so legacy raw
+ *   values keep working regardless of which form was stored.
+ */
+
+/** Separator standing in for "/" inside the model-id portion of a Codex-facing slug. */
+export const SLUG_ALIAS_SEPARATOR = "-";
+
+/** Native model id -> Codex-facing alias id. No-op for ids without "/". */
+export function encodeRoutedModelId(id: string): string {
+  return id.includes("/") ? id.replaceAll("/", SLUG_ALIAS_SEPARATOR) : id;
+}
+
+/** Codex-facing routed slug: exactly one "/" — `<provider>/<encoded id>`. */
+export function routedSlug(provider: string, id: string): string {
+  return `${provider}/${encodeRoutedModelId(id)}`;
+}
+
+/**
+ * Map a Codex-supplied model id back to the provider's native id.
+ * `knownIds` is the provider's known native ids (config ∪ registry ∪ live cache).
+ */
+export function decodeRoutedModelId(requested: string, knownIds: Iterable<string>): string {
+  let aliasMatch: string | undefined;
+  for (const id of knownIds) {
+    if (id === requested) return requested; // native exact (raw selector back-compat)
+    if (id.includes("/") && encodeRoutedModelId(id) === requested) {
+      // Ambiguous alias (e.g. both `a/b` and `a-b` exist): refuse to guess.
+      if (aliasMatch !== undefined && aliasMatch !== id) return requested;
+      aliasMatch = id;
+    }
+  }
+  return aliasMatch ?? requested;
+}
+
+/** Does a stored config slug name this routed model, in either raw or encoded form? */
+export function slugEquals(stored: string, provider: string, id: string): boolean {
+  return stored === `${provider}/${id}` || stored === routedSlug(provider, id);
+}
+
+/** Equivalence between two routed slugs regardless of raw/encoded mix. */
+export function slugsEquivalent(a: string, b: string): boolean {
+  if (a === b) return true;
+  const pa = a.indexOf("/");
+  const pb = b.indexOf("/");
+  if (pa <= 0 || pb <= 0) return false;
+  if (a.slice(0, pa) !== b.slice(0, pb)) return false;
+  return encodeRoutedModelId(a.slice(pa + 1)) === encodeRoutedModelId(b.slice(pb + 1));
+}

package/src/providers/xai-transport.ts

@@ -0,0 +1,141 @@
+import { createHash, randomUUID } from "node:crypto";
+import type { OcxProviderConfig } from "../types";
+import { resolveGithubCopilotTransport } from "./github-copilot-transport";
+
+export const XAI_GROK_CLI_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
+
+export const XAI_GROK_COMPATIBILITY = {
+  version: "0.2.93",
+  userAgent: "opencodex-grok/0.2.93",
+  headers: {
+    clientIdentifier: "x-grok-client-identifier",
+    clientVersion: "x-grok-client-version",
+    tokenAuth: "x-xai-token-auth",
+    authenticateResponse: "x-authenticateresponse",
+    conversationId: "x-grok-conv-id",
+    requestId: "x-grok-req-id",
+    sessionId: "x-grok-session-id",
+    userAgent: "User-Agent",
+  },
+} as const;
+
+export const XAI_GROK_CLIENT_VERSION = XAI_GROK_COMPATIBILITY.version;
+export const XAI_CONV_ID_HEADER = XAI_GROK_COMPATIBILITY.headers.conversationId;
+
+export type OcxProviderTransport = OcxProviderConfig & {
+  /** Request executor used only at runtime; never persisted. */
+  fetch?: typeof globalThis.fetch;
+};
+
+const XAI_GROK_CLI_HEADERS: Readonly<Record<string, string>> = {
+  [XAI_GROK_COMPATIBILITY.headers.clientIdentifier]: "opencodex",
+  [XAI_GROK_COMPATIBILITY.headers.clientVersion]: XAI_GROK_CLIENT_VERSION,
+  [XAI_GROK_COMPATIBILITY.headers.tokenAuth]: "xai-grok-cli",
+  [XAI_GROK_COMPATIBILITY.headers.authenticateResponse]: "authenticate-response",
+};
+
+function hasHeaderCaseInsensitive(
+  headers: Record<string, string> | undefined,
+  name: string,
+): boolean {
+  const target = name.toLowerCase();
+  return Object.keys(headers ?? {}).some(key => key.toLowerCase() === target);
+}
+
+function withoutUserOverridden(
+  defaults: Readonly<Record<string, string>>,
+  userHeaders: Record<string, string> | undefined,
+): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(defaults).filter(([name]) => !hasHeaderCaseInsensitive(userHeaders, name)),
+  );
+}
+
+function withGeneratedRequestId(
+  init: RequestInit | undefined,
+  configuredRequestId: string | undefined,
+  stableHeaders: Readonly<Record<string, string>>,
+): RequestInit {
+  const headers = new Headers(init?.headers);
+  for (const [name, value] of Object.entries(stableHeaders)) {
+    if (!headers.has(name)) headers.set(name, value);
+  }
+  if (!headers.has(XAI_GROK_COMPATIBILITY.headers.requestId)) {
+    headers.set(
+      XAI_GROK_COMPATIBILITY.headers.requestId,
+      configuredRequestId ?? randomUUID(),
+    );
+  }
+  return { ...init, headers };
+}
+
+function findHeaderCaseInsensitive(
+  headers: Record<string, string> | undefined,
+  name: string,
+): string | undefined {
+  const target = name.toLowerCase();
+  return Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === target)?.[1];
+}
+
+export function deriveXaiConvId(promptCacheKey: string): string {
+  return createHash("sha256").update(promptCacheKey).digest("hex").slice(0, 32);
+}
+
+/**
+ * Resolve xAI's runtime transport without mutating persisted config. Conversation/session
+ * affinity is stable for this resolved transport; request identity is generated per fetch.
+ * Agent, deployment, model-override, turn, mode, and user identity headers are intentionally
+ * omitted because opencodex has no truthful values for the official fields.
+ */
+export function resolveProviderTransport(
+  providerName: string,
+  provider: OcxProviderTransport,
+  promptCacheKey?: string,
+  apiBaseUrl?: string,
+): OcxProviderTransport {
+  if (providerName === "github-copilot") {
+    return resolveGithubCopilotTransport(provider, apiBaseUrl);
+  }
+  if (providerName !== "xai") return provider;
+
+  const cacheKey = promptCacheKey?.trim();
+  const affinity = cacheKey ? deriveXaiConvId(cacheKey) : undefined;
+  const stableDefaults: Record<string, string> = {
+    [XAI_GROK_COMPATIBILITY.headers.userAgent]: XAI_GROK_COMPATIBILITY.userAgent,
+    ...(affinity
+      ? {
+          [XAI_GROK_COMPATIBILITY.headers.conversationId]: affinity,
+          [XAI_GROK_COMPATIBILITY.headers.sessionId]: affinity,
+        }
+      : {}),
+    ...(provider.authMode === "oauth" ? XAI_GROK_CLI_HEADERS : {}),
+  };
+  const stableHeaders = {
+    ...withoutUserOverridden(stableDefaults, provider.headers),
+    ...(provider.headers ?? {}),
+  };
+  // Keep API-key provider metadata compatible with key-pool rotation; session/UA defaults
+  // remain transport-scoped and are applied by the wrapper immediately below.
+  const headers = provider.authMode === "oauth"
+    ? stableHeaders
+    : {
+        ...(affinity && !hasHeaderCaseInsensitive(provider.headers, XAI_GROK_COMPATIBILITY.headers.conversationId)
+          ? { [XAI_GROK_COMPATIBILITY.headers.conversationId]: affinity }
+          : {}),
+        ...(provider.headers ?? {}),
+      };
+  const configuredRequestId = findHeaderCaseInsensitive(
+    provider.headers,
+    XAI_GROK_COMPATIBILITY.headers.requestId,
+  );
+  const baseFetch = provider.fetch ?? globalThis.fetch;
+  const attemptFetch = ((input, init) =>
+    baseFetch(input, withGeneratedRequestId(init, configuredRequestId, stableHeaders))) as typeof globalThis.fetch;
+
+  return {
+    ...provider,
+    ...(provider.authMode === "oauth" ? { baseUrl: XAI_GROK_CLI_BASE_URL } : {}),
+    headers,
+    fetch: attemptFetch,
+  };
+}

package/src/reasoning-effort.ts

@@ -0,0 +1,135 @@
+import type { OcxProviderConfig } from "./types";
+import { modelInList } from "./types";
+
+// Descriptions mirror the upstream bundled models.json canonical wording (openai/codex PR #31684).
+export const CODEX_REASONING_LEVELS: { effort: string; description: string }[] = [
+  { effort: "low", description: "Fast responses with lighter reasoning" },
+  { effort: "medium", description: "Balances speed and reasoning depth for everyday tasks" },
+  { effort: "high", description: "Greater reasoning depth for complex problems" },
+  { effort: "xhigh", description: "Extra high reasoning depth for complex problems" },
+  { effort: "max", description: "Maximum reasoning depth for the hardest problems" },
+  { effort: "ultra", description: "Maximum reasoning with automatic task delegation" },
+];
+
+const CODEX_REASONING_ORDER = CODEX_REASONING_LEVELS.map(l => l.effort);
+const CODEX_REASONING_SET = new Set(CODEX_REASONING_ORDER);
+
+/** True when `effort` is a member of the Codex reasoning ladder (low..ultra). */
+export function isCodexReasoningEffort(effort: string): boolean {
+  return CODEX_REASONING_SET.has(effort);
+}
+
+/** 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);
+}
+
+export function modelRecordValue<T>(record: Record<string, T> | undefined, modelId: string): T | undefined {
+  if (!record) return undefined;
+  if (Object.prototype.hasOwnProperty.call(record, modelId)) return record[modelId];
+  const colon = modelId.indexOf(":");
+  if (colon > 0) {
+    const family = modelId.slice(0, colon);
+    if (Object.prototype.hasOwnProperty.call(record, family)) return record[family];
+  }
+  const folded = modelId.toLowerCase();
+  for (const [key, value] of Object.entries(record)) {
+    if (key.toLowerCase() === folded) return value;
+  }
+  return undefined;
+}
+
+export function sanitizeCodexReasoningEfforts(efforts: readonly string[] | undefined): string[] | undefined {
+  if (efforts === undefined) return undefined;
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const effort of efforts) {
+    if (!CODEX_REASONING_SET.has(effort) || seen.has(effort)) continue;
+    seen.add(effort);
+    out.push(effort);
+  }
+  return out.sort((a, b) => CODEX_REASONING_ORDER.indexOf(a) - CODEX_REASONING_ORDER.indexOf(b));
+}
+
+/**
+ * Provider/model configured reasoning levels for the Codex catalog. `undefined` means “no override”,
+ * while an empty array means “intentionally expose no effort control for this model”.
+ */
+export function configuredReasoningEfforts(provider: OcxProviderConfig, modelId: string): string[] | undefined {
+  if (modelInList(provider.noReasoningModels, modelId)) return [];
+  const modelEfforts = modelRecordValue(provider.modelReasoningEfforts, modelId);
+  if (modelEfforts !== undefined) return healMappedTiers(provider, modelId, sanitizeCodexReasoningEfforts(modelEfforts) ?? []);
+  if (provider.reasoningEfforts !== undefined) return healMappedTiers(provider, modelId, sanitizeCodexReasoningEfforts(provider.reasoningEfforts) ?? []);
+  return undefined;
+}
+
+/**
+ * Stale-ladder self-heal: a registry wire map is authoritative evidence of the upstream tiers
+ * it can emit. Merge Codex-native map values into an older persisted ladder so newly documented
+ * tiers appear without rewriting the user's config. Non-Codex values such as enabled/disabled
+ * and Kimi's none sentinel are ignored here; they remain request-only wire aliases.
+ */
+function healMappedTiers(provider: OcxProviderConfig, modelId: string, efforts: string[]): string[] {
+  if (efforts.length === 0) return efforts;
+  const wireMap = reasoningEffortMapFor(provider, modelId);
+  if (!wireMap) return efforts;
+  const mappedTiers = Object.values(wireMap).filter(isCodexReasoningEffort);
+  if (mappedTiers.length === 0) return efforts;
+  return sanitizeCodexReasoningEfforts([...efforts, ...mappedTiers]) ?? efforts;
+}
+
+function requestToCodexEffort(requested: string): string | undefined {
+  if (requested === "none") return undefined;
+  if (requested === "minimal") return "low";
+  return CODEX_REASONING_SET.has(requested) ? requested : undefined;
+}
+
+function clampToSupportedCodexEffort(requested: string, supported: readonly string[]): string | undefined {
+  if (supported.length === 0) return undefined;
+  const codex = requestToCodexEffort(requested);
+  if (!codex) return undefined;
+  if (supported.includes(codex)) return codex;
+
+  const requestedRank = CODEX_REASONING_ORDER.indexOf(codex);
+  let best = supported[0];
+  let bestRank = CODEX_REASONING_ORDER.indexOf(best);
+  for (const effort of supported) {
+    const rank = CODEX_REASONING_ORDER.indexOf(effort);
+    if (rank <= requestedRank && rank >= bestRank) {
+      best = effort;
+      bestRank = rank;
+    }
+  }
+  // If every supported tier is above the requested tier, choose the lowest supported tier.
+  return best;
+}
+
+export function reasoningEffortMapFor(provider: OcxProviderConfig, modelId: string): Record<string, string> | undefined {
+  return modelRecordValue(provider.modelReasoningEffortMap, modelId) ?? provider.reasoningEffortMap;
+}
+
+/**
+ * Translate Codex's reasoning label into the provider's real wire value. Prefer identity labels
+ * (`xhigh` stays `xhigh`, `max` stays `max`); provider maps are only for real upstream aliases.
+ */
+export function mapReasoningEffort(provider: OcxProviderConfig, modelId: string, requested: string | undefined): string | undefined {
+  if (!requested) return undefined;
+  if (modelInList(provider.noReasoningModels, modelId)) return undefined;
+
+  // Upstream codex-rs converts ultra -> max before ANY provider request (core/src/client.rs
+  // `reasoning_effort_for_request`), so "ultra" must never influence the provider wire — not even
+  // through a raw alias. Apply the boundary before alias/clamp resolution.
+  const boundary = requested === "ultra" ? "max" : requested;
+
+  const wireMap = reasoningEffortMapFor(provider, modelId);
+  if (wireMap && Object.prototype.hasOwnProperty.call(wireMap, boundary)) return wireMap[boundary];
+
+  const supported = configuredReasoningEfforts(provider, modelId);
+  const codexEffort = supported !== undefined ? clampToSupportedCodexEffort(boundary, supported) : requestToCodexEffort(boundary);
+  if (!codexEffort) return undefined;
+
+  // Belt for the odd config where the supported ladder is ultra-only and the clamp lands on it.
+  const wire = codexEffort === "ultra" ? "max" : codexEffort;
+  if (wireMap && Object.prototype.hasOwnProperty.call(wireMap, wire)) return wireMap[wire];
+  return wire;
+}

package/src/responses/compaction.ts

@@ -0,0 +1,117 @@
+/**
+ * Remote compaction v2 support for ROUTED providers.
+ *
+ * Codex decides "this provider supports remote compaction" by provider name (built-in `OpenAI`),
+ * and Design B points that provider at this proxy — so Codex sends remote compaction v2 requests
+ * for EVERY routed model. The request is a normal /responses call whose input ends with
+ * `{"type":"compaction_trigger"}`; codex-rs `collect_compaction_output` then requires the stream
+ * to carry EXACTLY ONE `{"type":"compaction","encrypted_content":...}` output item
+ * (compact_remote_v2.rs) or it fatals with "expected exactly one compaction output item".
+ *
+ * Routed models cannot produce OpenAI's encrypted blob, so the proxy runs the model as a plain
+ * summarizer and wraps the summary text in a transparent envelope: `ocx1:` + base64(utf8 summary).
+ * Codex stores the item and replays it in later input; the parser decodes our envelope back into
+ * plain text for routed models. Real OpenAI-encrypted blobs (no `ocx1:` prefix) are opaque —
+ * routed models get a short "history was compacted" note instead.
+ */
+
+export const OCX_COMPACTION_PREFIX = "ocx1:";
+
+/** Mirrors codex-rs core/templates/compact/prompt.md (the local-compaction instruction). */
+export const COMPACT_PROMPT = `You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.
+
+Include:
+- Current progress and key decisions made
+- Important context, constraints, or user preferences
+- What remains to be done (clear next steps)
+- Any critical data, examples, or references needed to continue
+
+Be concise, structured, and focused on helping the next LLM seamlessly continue the work.`;
+
+/** Mirrors codex-rs core/templates/compact/summary_prefix.md (framing for a replayed summary). */
+export const SUMMARY_PREFIX = "Another language model started to solve this problem and produced a summary of its thinking process. You also have access to the state of the tools that were used by that language model. Use this to build on the work that has already been done and avoid duplicating work. Here is the summary produced by the other language model, use the information in this summary to assist with your own analysis:";
+
+export const OPAQUE_COMPACTION_NOTE = "[earlier conversation was compacted; the summary is stored in a format this model cannot read]";
+
+export function encodeCompactionSummary(summary: string): string {
+  return OCX_COMPACTION_PREFIX + Buffer.from(summary, "utf-8").toString("base64");
+}
+
+/** Decode an `ocx1:` envelope; returns null for real (OpenAI-encrypted) blobs or garbage. */
+export function decodeCompactionSummary(encryptedContent: string): string | null {
+  if (!encryptedContent.startsWith(OCX_COMPACTION_PREFIX)) return null;
+  try {
+    return Buffer.from(encryptedContent.slice(OCX_COMPACTION_PREFIX.length), "base64").toString("utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** Render a replayed compaction item as plain user-visible text for a routed model. */
+export function compactionItemToText(encryptedContent: string | undefined): string {
+  const decoded = typeof encryptedContent === "string" ? decodeCompactionSummary(encryptedContent) : null;
+  return decoded ? `${SUMMARY_PREFIX}\n\n${decoded}` : OPAQUE_COMPACTION_NOTE;
+}
+
+/**
+ * Remote compaction v1 (`POST /responses/compact`, unary) — codex-rs installs the returned
+ * `{"output":[ResponseItem...]}` as the REPLACEMENT history (compact_remote.rs
+ * process_compacted_history). Mirror codex-rs local `build_compacted_history`: recent real user
+ * messages within a token budget, then one user message `SUMMARY_PREFIX\n<summary>`. Plain user
+ * message items parse as real user messages on the codex side (event_mapping parse_user_message);
+ * contextual wrappers are filtered there, and v2-style `compaction` items are NOT expected here.
+ */
+
+/** codex-rs compact.rs COMPACT_USER_MESSAGE_MAX_TOKENS = 20k tokens (~4 chars/token). */
+const COMPACT_V1_RETAINED_CHAR_BUDGET = 20_000 * 4;
+
+/** Extract plain-text user messages from a Responses `input` array (for v1 compact retention). */
+export function extractCompactUserMessages(input: unknown): string[] {
+  if (!Array.isArray(input)) return [];
+  const out: string[] = [];
+  for (const item of input) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+    const rec = item as { type?: string; role?: string; content?: unknown };
+    if (rec.type !== undefined && rec.type !== "message") continue;
+    if (rec.role !== "user") continue;
+    let text = "";
+    if (typeof rec.content === "string") text = rec.content;
+    else if (Array.isArray(rec.content)) {
+      text = rec.content
+        .map(b => {
+          if (!b || typeof b !== "object") return "";
+          const block = b as { type?: string; text?: string };
+          return (block.type === "input_text" || block.type === "text") && typeof block.text === "string" ? block.text : "";
+        })
+        .join("");
+    }
+    if (text.trim().length > 0) out.push(text);
+  }
+  return out;
+}
+
+function compactUserMessageItem(text: string): Record<string, unknown> {
+  return { type: "message", role: "user", content: [{ type: "input_text", text }] };
+}
+
+/** Build the v1 compact `output` array: retained recent user messages + the summary message. */
+export function buildCompactV1Output(userMessages: string[], summary: string): Record<string, unknown>[] {
+  const selected: string[] = [];
+  let remaining = COMPACT_V1_RETAINED_CHAR_BUDGET;
+  for (let i = userMessages.length - 1; i >= 0 && remaining > 0; i--) {
+    const msg = userMessages[i];
+    if (msg.length <= remaining) {
+      selected.push(msg);
+      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));
+      break;
+    }
+  }
+  selected.reverse();
+  // codex-rs compact.rs uses "{SUMMARY_PREFIX}\n{summary}" (single newline) and detects stored
+  // summaries by that exact prefix — keep the same shape.
+  const summaryText = summary.trim().length > 0 ? `${SUMMARY_PREFIX}\n${summary}` : "(no summary available)";
+  return [...selected.map(compactUserMessageItem), compactUserMessageItem(summaryText)];
+}