@yansigit/opencodex 2.31.3 → 2.33.0

package/src/codex/shim.ts

@@ -603,6 +603,47 @@ function backupPathFor(path: string): string {
   return ext ? `${path.slice(0, -ext.length)}.opencodex-real${ext}` : `${path}.opencodex-real`;
 }
 
+/**
+ * True when a Codex binary lives inside a version manager's install tree.
+ *
+ * These trees are rewritten in place on upgrade, which destroys both the shim
+ * and the sibling .opencodex-real backup it restores from (#2412). The tempting
+ * repair — adopt the newly installed binary as a fresh original — is wrong
+ * twice: it records a provenance that never happened, and the next upgrade wipes
+ * it again, so the repair silently un-repairs on the version manager's schedule.
+ *
+ * Scope is the three managers named in the report. nvm/fnm/npm-prefix are
+ * deliberately excluded: a false positive here refuses a restore that would
+ * otherwise be correct.
+ */
+export function isVersionManagerOwnedCodexPath(path: string): boolean {
+  const normalized = path.replace(/\\/g, "/").toLowerCase();
+  return normalized.includes("/mise/installs/")
+    || normalized.includes("/mise/shims/")
+    || normalized.includes("/.asdf/installs/")
+    || normalized.includes("/.asdf/shims/")
+    || normalized.includes("/.volta/");
+}
+
+/**
+ * Why auto-restore refused, in the operator's own terms. Auto-restore used to
+ * return a bare `{ status: "ineligible" }`, and the CLI warns only when a
+ * message is present, so `ocx start`, `ocx ensure`, and `ocx service repair` all
+ * reported success while routing quietly stayed native (#2412, the cause behind
+ * the misleading green status in #2411).
+ */
+function destroyedShimMessage(file: ShimFileState): string {
+  const wrapper = existsSync(file.wrapperPath)
+    ? isShim(file.wrapperPath) ? "present but unusable" : "present but not an opencodex shim"
+    : "missing";
+  const backup = existsSync(file.backupPath) ? "present" : "missing";
+  const base = `Codex autostart shim not restored: wrapper ${wrapper} at ${file.wrapperPath}; original backup ${backup} at ${file.backupPath}.`;
+  if (!isVersionManagerOwnedCodexPath(file.wrapperPath)) {
+    return `${base} Re-run 'ocx codex-shim install' once the Codex binary is stable.`;
+  }
+  return `${base} This Codex binary is owned by a version manager (mise/asdf/volta), so opencodex will not wrap it as a new original — the next upgrade would overwrite the shim and its backup again. Route through Codex instead with 'ocx start', and use 'ocx service install' for autostart.`;
+}
+
 function shQuote(value: string): string {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
@@ -2039,14 +2080,20 @@ export function autoRestoreCodexShim(options: {
     if (seen.has(file.wrapperPath)) return { status: "ineligible" };
     seen.add(file.wrapperPath);
     if (file.preserveOnly) {
-      if (!existsSync(file.backupPath) || existsSync(file.originalPath)) return { status: "ineligible" };
+      if (!existsSync(file.backupPath) || existsSync(file.originalPath)) {
+        return { status: "ineligible", message: destroyedShimMessage(file) };
+      }
       continue;
     }
-    if (!existsSync(file.wrapperPath) || !hasUsableBackingPath(file)) return { status: "ineligible" };
+    if (!existsSync(file.wrapperPath) || !hasUsableBackingPath(file)) {
+      return { status: "ineligible", message: destroyedShimMessage(file) };
+    }
     const probe = stableShimPathProbe(file.wrapperPath);
     if (!probe) return { status: "deferred" };
     if (probe.prefix.includes(SHIM_MARKER)) {
-      if (!isHealthyShimProbe(probe, state.platform)) return { status: "ineligible" };
+      if (!isHealthyShimProbe(probe, state.platform)) {
+        return { status: "ineligible", message: destroyedShimMessage(file) };
+      }
       if (state.platform !== "win32" && !isCurrentUnixShimProbe(probe)) {
         obsoleteShimProbes.set(file.wrapperPath, probe);
         continue;
@@ -2054,6 +2101,12 @@ export function autoRestoreCodexShim(options: {
       healthyCount += 1;
       continue;
     }
+    // A surviving backup would otherwise let the replacement path below wrap the
+    // version manager's NEW binary as a fresh original — the same adoption the
+    // missing-backup case refuses, arriving through the back door.
+    if (isVersionManagerOwnedCodexPath(file.wrapperPath)) {
+      return { status: "ineligible", message: destroyedShimMessage(file) };
+    }
     replacementProbes.set(file.wrapperPath, probe);
   }
 

package/src/combos/failover.ts

@@ -109,6 +109,28 @@ export function clearComboTargetCooldowns(comboId?: string): void {
 
 export type ComboFailureDecision = "hop" | "stop";
 
+function isModelLifecycleGone(
+  status: number,
+  message: string,
+  code?: string | null,
+): boolean {
+  if (status !== 410) return false;
+  const normalizedCode = code?.trim().toLowerCase().replaceAll("-", "_");
+  if ([
+    "model_deprecated",
+    "model_end_of_life",
+    "model_eol",
+    "model_not_found",
+    "model_retired",
+  ].includes(normalizedCode ?? "")) return true;
+  const text = message.toLowerCase();
+  return /\bmodel\b/.test(text) && (
+    /\bend[ -]of[ -]life\b/.test(text)
+    || /\bno longer available\b/.test(text)
+    || /\b(?:deprecated|retired|retirement|sunset|decommissioned)\b/.test(text)
+  );
+}
+
 export function comboFailureDecision(
   status: number,
   message: string,
@@ -119,6 +141,11 @@ export function comboFailureDecision(
   // Cyber policy is a hard non-retryable refusal — honor structured code even when
   // classificationText was truncated before the JSON code field.
   if (isCyberPolicyCode(options?.code)) return "stop";
+  // HTTP 410 is normally terminal. A model-specific lifecycle verdict is target-local,
+  // however: another provider/model in the declared combo can still serve the request.
+  // Require structured lifecycle code or explicit model+lifecycle prose so unrelated
+  // application-level 410 responses remain fail-closed.
+  if (isModelLifecycleGone(status, message, options?.code)) return "hop";
   const error = classifyError(status, "upstream_error", message);
   if (isCyberPolicyCode(error.code)) return "stop";
   // A local input-admission refusal (#1524) says "this candidate cannot fit the request",

package/src/compatibility/index.ts

@@ -0,0 +1,26 @@
+import { OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST } from "./openai-responses";
+import type { CompatibilityManifestV1 } from "./manifest";
+
+export {
+  COMPATIBILITY_DISPOSITIONS,
+  COMPATIBILITY_MANIFEST_SCHEMA_VERSION,
+  compatibilityManifestIssues,
+  defineCompatibilityManifest,
+} from "./manifest";
+export type {
+  CompatibilityClaimV1,
+  CompatibilityDisposition,
+  CompatibilityEvidenceKind,
+  CompatibilityEvidenceRefV1,
+  CompatibilityManifestV1,
+  CompatibilitySubjectV1,
+} from "./manifest";
+export { OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST } from "./openai-responses";
+
+export const COMPATIBILITY_MANIFESTS: readonly CompatibilityManifestV1[] = Object.freeze([
+  OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST,
+]);
+
+export function getCompatibilityManifest(id: string): CompatibilityManifestV1 | undefined {
+  return COMPATIBILITY_MANIFESTS.find(manifest => manifest.id === id);
+}

package/src/compatibility/manifest.ts

@@ -0,0 +1,253 @@
+export const COMPATIBILITY_MANIFEST_SCHEMA_VERSION = 1 as const;
+
+export const COMPATIBILITY_DISPOSITIONS = [
+  "passthrough",
+  "translated",
+  "degraded",
+  "unsupported",
+] as const;
+
+export type CompatibilityDisposition = typeof COMPATIBILITY_DISPOSITIONS[number];
+export type CompatibilityEvidenceKind = "fixture" | "lab-scenario";
+
+export interface CompatibilityEvidenceRefV1 {
+  kind: CompatibilityEvidenceKind;
+  id: string;
+  /** Exact fixture assertions that prove this claim. Required for fixture evidence. */
+  assertionIds?: readonly string[];
+}
+
+export interface CompatibilityClaimV1 {
+  /** Stable manifest-local claim id. */
+  id: string;
+  /** Stable public feature key, such as `request.previous_response_id`. */
+  feature: string;
+  disposition: CompatibilityDisposition;
+  summary: string;
+  /** Required when behavior is not byte/semantic passthrough. */
+  limitation?: string;
+  evidence: readonly CompatibilityEvidenceRefV1[];
+}
+
+export interface CompatibilitySubjectV1 {
+  providerId: string;
+  /** Exact normalized provider base URL; destination changes require a new subject/version. */
+  baseUrl: string;
+  adapterId: string;
+  authMode: "forward" | "key" | "oauth" | "local";
+  inboundProtocol: "responses" | "chat" | "messages";
+  upstreamProtocol: string;
+  /** Claims apply only to these exact wire model ids. */
+  modelIds: readonly string[];
+}
+
+export interface CompatibilityManifestV1 {
+  schemaVersion: typeof COMPATIBILITY_MANIFEST_SCHEMA_VERSION;
+  id: string;
+  version: string;
+  subject: CompatibilitySubjectV1;
+  claims: readonly CompatibilityClaimV1[];
+}
+
+const ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+const FEATURE_PATTERN = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/;
+const DISPOSITIONS = new Set<string>(COMPATIBILITY_DISPOSITIONS);
+const EVIDENCE_KINDS = new Set<string>(["fixture", "lab-scenario"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function checkKnownKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  path: string,
+  issues: string[],
+): void {
+  const allowedSet = new Set(allowed);
+  for (const key of Object.keys(value)) {
+    if (!allowedSet.has(key)) issues.push(`${path}${path ? "." : ""}${key} is not allowed by schema v1`);
+  }
+}
+
+function checkId(value: unknown, path: string, issues: string[]): value is string {
+  if (typeof value !== "string" || !ID_PATTERN.test(value)) {
+    issues.push(`${path} must match ${ID_PATTERN}`);
+    return false;
+  }
+  return true;
+}
+
+function checkNonBlank(value: unknown, path: string, issues: string[]): value is string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    issues.push(`${path} must be a non-blank string`);
+    return false;
+  }
+  return true;
+}
+
+function checkNormalizedBaseUrl(value: unknown, path: string, issues: string[]): value is string {
+  if (typeof value !== "string") {
+    issues.push(`${path} must be a normalized absolute HTTP(S) base URL`);
+    return false;
+  }
+  try {
+    const parsed = new URL(value);
+    if (
+      (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+      || parsed.username
+      || parsed.password
+      || parsed.search
+      || parsed.hash
+    ) {
+      issues.push(`${path} must be a normalized absolute HTTP(S) base URL without credentials, query, or fragment`);
+      return false;
+    }
+    const normalizedPath = parsed.pathname.replace(/\/+$/, "");
+    const normalized = `${parsed.origin}${normalizedPath}`;
+    if (value !== normalized) {
+      issues.push(`${path} must be normalized as ${normalized}`);
+      return false;
+    }
+    return true;
+  } catch {
+    issues.push(`${path} must be a normalized absolute HTTP(S) base URL`);
+    return false;
+  }
+}
+
+function checkSortedUniqueStrings(
+  value: unknown,
+  path: string,
+  issues: string[],
+  options: { nonEmpty?: boolean } = {},
+): value is string[] {
+  if (!Array.isArray(value) || (options.nonEmpty === true && value.length === 0)) {
+    issues.push(`${path} must be${options.nonEmpty === true ? " a non-empty" : " an"} array`);
+    return false;
+  }
+  if (value.some(item => typeof item !== "string" || item.trim().length === 0)) {
+    issues.push(`${path} must contain only non-blank strings`);
+    return false;
+  }
+  const strings = value as string[];
+  if (new Set(strings).size !== strings.length) issues.push(`${path} must not contain duplicates`);
+  const sorted = [...strings].sort();
+  if (strings.some((item, index) => item !== sorted[index])) issues.push(`${path} must be sorted`);
+  return true;
+}
+
+function checkEvidence(value: unknown, path: string, issues: string[]): void {
+  if (!Array.isArray(value) || value.length === 0) {
+    issues.push(`${path} must be a non-empty array`);
+    return;
+  }
+  const seen = new Set<string>();
+  value.forEach((raw, index) => {
+    const evidencePath = `${path}[${index}]`;
+    if (!isRecord(raw)) {
+      issues.push(`${evidencePath} must be an object`);
+      return;
+    }
+    checkKnownKeys(raw, ["kind", "id", "assertionIds"], evidencePath, issues);
+    if (!EVIDENCE_KINDS.has(String(raw.kind))) {
+      issues.push(`${evidencePath}.kind must be fixture or lab-scenario`);
+    }
+    const id = checkId(raw.id, `${evidencePath}.id`, issues) ? raw.id : "";
+    const assertionIds = raw.assertionIds;
+    if (raw.kind === "fixture") {
+      checkSortedUniqueStrings(assertionIds, `${evidencePath}.assertionIds`, issues, { nonEmpty: true });
+    } else if (assertionIds !== undefined) {
+      checkSortedUniqueStrings(assertionIds, `${evidencePath}.assertionIds`, issues, { nonEmpty: true });
+    }
+    const key = `${String(raw.kind)}:${id}:${JSON.stringify(assertionIds ?? [])}`;
+    if (seen.has(key)) issues.push(`${evidencePath} duplicates an earlier evidence reference`);
+    seen.add(key);
+  });
+}
+
+/**
+ * Validate one versioned compatibility manifest without importing provider or Lab state.
+ * Keeping this as a leaf lets future CLI/GUI readers load contracts without activating Lab.
+ */
+export function compatibilityManifestIssues(value: unknown): string[] {
+  const issues: string[] = [];
+  if (!isRecord(value)) return ["manifest must be an object"];
+  checkKnownKeys(value, ["schemaVersion", "id", "version", "subject", "claims"], "", issues);
+  if (value.schemaVersion !== COMPATIBILITY_MANIFEST_SCHEMA_VERSION) {
+    issues.push(`schemaVersion must be ${COMPATIBILITY_MANIFEST_SCHEMA_VERSION}`);
+  }
+  checkId(value.id, "id", issues);
+  checkNonBlank(value.version, "version", issues);
+
+  if (!isRecord(value.subject)) {
+    issues.push("subject must be an object");
+  } else {
+    checkKnownKeys(
+      value.subject,
+      ["providerId", "baseUrl", "adapterId", "authMode", "inboundProtocol", "upstreamProtocol", "modelIds"],
+      "subject",
+      issues,
+    );
+    checkId(value.subject.providerId, "subject.providerId", issues);
+    checkNormalizedBaseUrl(value.subject.baseUrl, "subject.baseUrl", issues);
+    checkId(value.subject.adapterId, "subject.adapterId", issues);
+    if (!["forward", "key", "oauth", "local"].includes(String(value.subject.authMode))) {
+      issues.push("subject.authMode must be forward, key, oauth, or local");
+    }
+    if (!["responses", "chat", "messages"].includes(String(value.subject.inboundProtocol))) {
+      issues.push("subject.inboundProtocol must be responses, chat, or messages");
+    }
+    checkNonBlank(value.subject.upstreamProtocol, "subject.upstreamProtocol", issues);
+    checkSortedUniqueStrings(value.subject.modelIds, "subject.modelIds", issues, { nonEmpty: true });
+  }
+
+  if (!Array.isArray(value.claims) || value.claims.length === 0) {
+    issues.push("claims must be a non-empty array");
+    return issues;
+  }
+  const claimIds = new Set<string>();
+  const claimFeatures = new Set<string>();
+  value.claims.forEach((raw, index) => {
+    const path = `claims[${index}]`;
+    if (!isRecord(raw)) {
+      issues.push(`${path} must be an object`);
+      return;
+    }
+    checkKnownKeys(raw, ["id", "feature", "disposition", "summary", "limitation", "evidence"], path, issues);
+    const id = checkId(raw.id, `${path}.id`, issues) ? raw.id : "";
+    if (id && claimIds.has(id)) issues.push(`${path}.id duplicates ${id}`);
+    if (id) claimIds.add(id);
+    if (typeof raw.feature !== "string" || !FEATURE_PATTERN.test(raw.feature)) {
+      issues.push(`${path}.feature must be a dotted stable feature key`);
+    } else if (claimFeatures.has(raw.feature)) {
+      issues.push(`${path}.feature duplicates ${raw.feature}`);
+    } else {
+      claimFeatures.add(raw.feature);
+    }
+    if (!DISPOSITIONS.has(String(raw.disposition))) {
+      issues.push(`${path}.disposition is invalid`);
+    }
+    checkNonBlank(raw.summary, `${path}.summary`, issues);
+    if (raw.disposition !== "passthrough") {
+      checkNonBlank(raw.limitation, `${path}.limitation`, issues);
+    } else if (raw.limitation !== undefined) {
+      issues.push(`${path}.limitation must be omitted for passthrough claims`);
+    }
+    checkEvidence(raw.evidence, `${path}.evidence`, issues);
+  });
+  return issues;
+}
+
+function deepFreeze<T>(value: T, seen = new WeakSet<object>()): Readonly<T> {
+  if (!value || typeof value !== "object" || seen.has(value)) return value;
+  seen.add(value);
+  for (const nested of Object.values(value as Record<string, unknown>)) deepFreeze(nested, seen);
+  return Object.freeze(value);
+}
+
+export function defineCompatibilityManifest<T extends CompatibilityManifestV1>(manifest: T): Readonly<T> {
+  const issues = compatibilityManifestIssues(manifest);
+  if (issues.length > 0) throw new TypeError(`Invalid compatibility manifest ${manifest.id}: ${issues.join("; ")}`);
+  return deepFreeze(manifest);
+}

package/src/compatibility/openai-responses.ts

@@ -0,0 +1,81 @@
+import { defineCompatibilityManifest } from "./manifest";
+
+const FIXTURE_ID = "openai-codex-forward-gpt56-sol-v1";
+
+/**
+ * First deliberately narrow compatibility slice: one exact native Codex-login model.
+ * Broader model/provider claims require their own fixtures instead of inheriting this row.
+ */
+export const OPENAI_CODEX_FORWARD_GPT56_SOL_MANIFEST = defineCompatibilityManifest({
+  schemaVersion: 1,
+  id: "openai.codex-forward.gpt-5-6-sol.responses",
+  version: "1.0.0",
+  subject: {
+    providerId: "openai",
+    baseUrl: "https://chatgpt.com/backend-api/codex",
+    adapterId: "openai-responses",
+    authMode: "forward",
+    inboundProtocol: "responses",
+    upstreamProtocol: "openai-responses",
+    modelIds: ["gpt-5.6-sol"],
+  },
+  claims: [
+    {
+      id: "custom-tools",
+      feature: "request.custom_tools",
+      disposition: "passthrough",
+      summary: "Native custom-tool declarations retain their Responses representation.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["custom-tool-preserved"] }],
+    },
+    {
+      id: "prompt-cache-key",
+      feature: "request.prompt_cache_key",
+      disposition: "passthrough",
+      summary: "The caller's prompt cache key is forwarded unchanged.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["prompt-cache-key-preserved"] }],
+    },
+    {
+      id: "previous-response-id",
+      feature: "request.previous_response_id",
+      disposition: "translated",
+      summary: "Continuation is owned by the proxy rather than the ChatGPT backend field.",
+      limitation: "OpenCodex expands remembered input locally and removes previous_response_id before dispatch.",
+      evidence: [
+        { kind: "fixture", id: FIXTURE_ID, assertionIds: ["previous-response-id-removed"] },
+        { kind: "lab-scenario", id: "codex-core.protocol.previous-response-replay" },
+      ],
+    },
+    {
+      id: "orphan-tool-output",
+      feature: "continuation.orphan_tool_output",
+      disposition: "degraded",
+      summary: "An output whose prior call is unavailable remains visible to the model.",
+      limitation: "The orphan output is converted to user text because the forward backend cannot accept the unmatched item.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["orphan-output-converted"] }],
+    },
+    {
+      id: "max-output-tokens",
+      feature: "request.max_output_tokens",
+      disposition: "unsupported",
+      summary: "The ChatGPT Codex forward route does not receive max_output_tokens.",
+      limitation: "The field is removed before dispatch to avoid a backend parameter rejection.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["max-output-tokens-removed"] }],
+    },
+    {
+      id: "metadata",
+      feature: "request.metadata",
+      disposition: "unsupported",
+      summary: "Caller metadata is not forwarded to the ChatGPT Codex backend.",
+      limitation: "The field is removed before dispatch.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["metadata-removed"] }],
+    },
+    {
+      id: "prompt-cache-retention",
+      feature: "request.prompt_cache_retention",
+      disposition: "unsupported",
+      summary: "The retired retention field is not sent for gpt-5.6-sol.",
+      limitation: "The field is removed without inventing a replacement prompt_cache_options value.",
+      evidence: [{ kind: "fixture", id: FIXTURE_ID, assertionIds: ["prompt-cache-retention-removed"] }],
+    },
+  ],
+} as const);