@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
193 lines (181 loc) • 9.21 kB
text/typescript
/**
* #4207: a connected client reported `connected` with a present, freshly synced catalog while
* its installed Codex CLI exited before making a request, because the hub's catalog contained a
* reasoning level that CLI does not know:
*
* failed to parse model_catalog_json ... unknown variant `max`,
* expected one of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`
*
* The connection state answered a different question from the one the operator was asking. It
* proved the hub was reachable and the credential worked; it never proved the selected local
* runtime could consume what was downloaded. This module supplies the missing half, and the
* connect path fails closed on it: an incompatible catalog is refused before it is written, so
* the previous known-good file survives and no success is reported.
*
* What it deliberately does not do: rewrite the hub's catalog into a locally compatible
* projection (the client would then silently disagree with hub truth) and terminate running
* Codex processes. Both are ruled out by the issue.
*/
import { catalogEffortCompatibility, codexSupportedReasoningEfforts } from "../codex/catalog/effort";
import type { RawEntry } from "../codex/catalog/parsing";
export type ClientCatalogCompatibility =
| { kind: "compatible" }
/** The runtime ladder could not be observed, so incompatibility cannot be established. */
| { kind: "unverified"; reason: string }
| {
kind: "incompatible";
unsupportedEfforts: readonly string[];
affectedModels: readonly string[];
};
export interface CatalogCompatibilityDeps {
/** Injected in tests; defaults to observing the selected local Codex runtime. */
supportedEfforts?: () => ReadonlySet<string> | null;
}
/** State of the materialized client catalog file, as `ocx connect status` already reports it. */
export type ClientCatalogFileState = "present" | "missing" | "unsafe";
/**
* Whether the selected local Codex runtime can consume the catalog that is *already on disk* —
* a different question from the write-time gate, and the one #4207 was actually asking.
*
* The gate runs once, on bytes about to be written. It cannot speak for a file that predates it,
* for a file written while the ladder was {@link ClientCatalogCompatibility} `unverified`, or for
* a runtime that was swapped after the write. Those are exactly the states that kept reporting
* `connected` while `codex exec` died on `unknown variant \`max\``.
*
* Only `ready` means ready. `unverified` is not `incompatible`: a client machine may legitimately
* have no observable Codex CLI, and calling that an incompatibility would condemn a working
* install on absent evidence — the same mistake the write-time gate refuses to make.
*/
export type ClientCatalogReadiness =
| { kind: "ready" }
| { kind: "unverified"; reason: string }
| {
kind: "incompatible";
reason: string;
unsupportedEfforts: readonly string[];
affectedModels: readonly string[];
};
function parseModels(body: string): RawEntry[] | null {
try {
const parsed = JSON.parse(body) as { models?: unknown };
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
return Array.isArray(parsed.models) ? parsed.models as RawEntry[] : [];
} catch {
return null;
}
}
/**
* Assess a downloaded catalog against the reasoning efforts the selected local Codex runtime
* accepts. Unreadable bytes are reported as unverified rather than incompatible: the hub
* client already rejects a malformed body, and inventing a second cause for it here would
* repeat the mistake #4169 was filed for.
*/
export function assessClientCatalogCompatibility(
body: string,
deps: CatalogCompatibilityDeps = {},
): ClientCatalogCompatibility {
const models = parseModels(body);
if (!models) return { kind: "unverified", reason: "the downloaded catalog could not be read" };
const supported = (deps.supportedEfforts ?? (() => codexSupportedReasoningEfforts()))();
if (!supported) {
return {
kind: "unverified",
reason: "the selected local Codex runtime did not report the reasoning levels it supports",
};
}
const result = catalogEffortCompatibility(models, supported);
if (result.compatible) return { kind: "compatible" };
return {
kind: "incompatible",
unsupportedEfforts: result.unsupportedEfforts,
affectedModels: result.affectedModels,
};
}
/**
* Raised instead of writing an incompatible catalog. It names both remedies the issue asks
* for, because the operator cannot act on "incompatible" alone, and it never suggests editing
* the hub.
*/
export class ClientCatalogIncompatibleError extends Error {
readonly unsupportedEfforts: readonly string[];
readonly affectedModels: readonly string[];
constructor(unsupportedEfforts: readonly string[], affectedModels: readonly string[]) {
const efforts = unsupportedEfforts.join(", ");
const models = affectedModels.length > 3
? `${affectedModels.slice(0, 3).join(", ")} and ${affectedModels.length - 3} more`
: affectedModels.join(", ");
super(
`catalog_incompatible: the hub catalog uses reasoning ${unsupportedEfforts.length === 1 ? "level" : "levels"} `
+ `${efforts}, which the selected local Codex CLI rejects${models ? ` (${models})` : ""}. `
+ "The previous catalog was kept and nothing was changed. Upgrade the Codex CLI to a "
+ "version that supports those levels, or point CODEX_CLI_PATH at one that does and run "
+ "`ocx sync`, then retry. `ocx doctor` reports which runtime is selected.",
);
this.name = "ClientCatalogIncompatibleError";
this.unsupportedEfforts = unsupportedEfforts;
this.affectedModels = affectedModels;
}
}
/** Fail closed: refuse an incompatible catalog before anything is written. */
export function assertClientCatalogCompatible(body: string, deps: CatalogCompatibilityDeps = {}): void {
const assessment = assessClientCatalogCompatibility(body, deps);
if (assessment.kind !== "incompatible") return;
throw new ClientCatalogIncompatibleError(assessment.unsupportedEfforts, assessment.affectedModels);
}
/**
* Why an already-installed incompatible catalog does not reuse the refusal message above:
* nothing was kept back. The unusable bytes are the ones Codex will read on its next launch,
* so "the previous catalog was kept" would be false. The two remedies are the same, because
* the operator's options do not depend on when the file arrived.
*/
function installedCatalogRejectionReason(
unsupportedEfforts: readonly string[],
affectedModels: readonly string[],
): string {
const models = affectedModels.length > 3
? `${affectedModels.slice(0, 3).join(", ")} and ${affectedModels.length - 3} more`
: affectedModels.join(", ");
return `the installed catalog uses reasoning ${unsupportedEfforts.length === 1 ? "level" : "levels"} `
+ `${unsupportedEfforts.join(", ")}, which the selected local Codex CLI rejects`
+ `${models ? ` (${models})` : ""}. Codex exits before its first request until the CLI is `
+ "upgraded to a version that supports those levels, or CODEX_CLI_PATH points at one that "
+ "does and `ocx sync` is run. `ocx doctor` reports which runtime is selected.";
}
/**
* Assess the catalog this machine has already installed, so a surface can stop calling a
* connection ready when the local runtime cannot launch against it.
*
* `body` is the file's bytes, or `null` when they could not be read; `file` is the state the
* caller already established by stat. Neither non-present file state is an incompatibility: an
* absent or non-regular catalog is a different fault, and this function only ever claims an
* incompatibility it has proven.
*/
export function inspectClientCatalogReadiness(
file: ClientCatalogFileState,
body: string | null,
deps: CatalogCompatibilityDeps = {},
): ClientCatalogReadiness {
if (file === "missing") {
return { kind: "unverified", reason: "no catalog is installed for the local Codex CLI to read" };
}
if (file === "unsafe") {
return { kind: "unverified", reason: "the catalog path is not a regular file, so its bytes were not read" };
}
if (body === null) return { kind: "unverified", reason: "the installed catalog could not be read" };
const assessment = assessClientCatalogCompatibility(body, deps);
if (assessment.kind === "compatible") return { kind: "ready" };
if (assessment.kind === "unverified") {
// assessClientCatalogCompatibility words its parse failure for bytes that have just been
// downloaded. These bytes are already installed, so blaming a download would send the
// operator to the wrong place; name the file that is actually unusable.
return parseModels(body) === null
? { kind: "unverified", reason: "the installed catalog is not readable JSON, so the local Codex CLI cannot parse it either" }
: assessment;
}
return {
kind: "incompatible",
reason: installedCatalogRejectionReason(assessment.unsupportedEfforts, assessment.affectedModels),
unsupportedEfforts: assessment.unsupportedEfforts,
affectedModels: assessment.affectedModels,
};
}