@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
271 lines (255 loc) • 13.2 kB
text/typescript
/**
* Candidate capability evidence for policy routing (RI-05).
*
* Evidence comes from canonical local sources only - provider config maps,
* the provider registry, the cached Codex catalog file, and the native-model
* metadata helpers. No live network fetch happens at routing time.
*
* "Unknown is not zero": any dimension without canonical evidence stays
* `undefined` (unknown) and the profile's `unknownEvidence` policy decides
* how that affects eligibility.
*/
import { modelInList, type OcxConfig, type OcxProviderConfig } from "../types";
import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
import { serviceTierSupportForModel } from "../providers/service-tier";
import { PROVIDER_REGISTRY } from "../providers/registry";
import {
nativeInputModalities,
nativeContextLimits, nativeOpenAiContextWindow,
nativeParallelToolCalls,
nativeReasoningEfforts,
} from "../codex/catalog/metadata";
import { readCatalog, readCodexCatalogPath } from "../codex/catalog/parsing";
import { modelRecordValue } from "../reasoning-effort";
import { statSync } from "node:fs";
import type { RouteCapabilityEvidence } from "./trace";
type CatalogModelRow = {
/** Exact provider/native-id identity, from the provenance block. */
provider: string;
id: string;
/** Only values a real source asserted; never a strict-parser default. */
contextWindow?: number;
inputModalities?: string[];
capabilities?: string[];
};
/**
* Catalog rows memoized by path + mtime: the cached Codex catalog is stable
* between refreshes, and re-reading/parsing the whole file per candidate on
* the request path would multiply a synchronous disk + JSON cost by the
* profile candidate count for every policy-routed request.
*/
let catalogCache: { path: string; mtimeMs: number; rows: CatalogModelRow[] } | null = null;
function cachedCatalogModels(): CatalogModelRow[] {
try {
const path = readCodexCatalogPath();
const mtimeMs = statSync(path).mtimeMs;
if (catalogCache && catalogCache.path === path && catalogCache.mtimeMs === mtimeMs) {
return catalogCache.rows;
}
const catalog = readCatalog(path);
const models = catalog?.models;
if (!Array.isArray(models)) return [];
// Read ONLY `opencodex_capability_provenance` (written by
// applyCatalogModelMetadata). The row's own `context_window` and
// `input_modalities` always exist because ensureStrictCatalogFields fills them
// with compatibility defaults for Codex's strict parser, so reading them would
// turn "nobody asserted anything" into a confident `image: false` and a
// fabricated 128000 — the opposite of this module's contract. A row without
// provenance contributes nothing.
const rows = models.flatMap((model): CatalogModelRow[] => {
if (typeof model !== "object" || model === null) return [];
const provenance = (model as Record<string, unknown>).opencodex_capability_provenance;
if (typeof provenance !== "object" || provenance === null) return [];
const source = provenance as Record<string, unknown>;
if (typeof source.provider !== "string" || typeof source.model_id !== "string") return [];
return [{
provider: source.provider,
id: source.model_id,
...(typeof source.context_window === "number" && source.context_window > 0
? { contextWindow: source.context_window }
: {}),
...(Array.isArray(source.input_modalities)
? { inputModalities: source.input_modalities.filter((value): value is string => typeof value === "string") }
: {}),
...(Array.isArray(source.capabilities)
? { capabilities: source.capabilities.filter((value): value is string => typeof value === "string") }
: {}),
}];
});
catalogCache = { path, mtimeMs, rows };
return rows;
} catch {
return [];
}
}
/**
* Classify a hostname for locality evidence. `URL.hostname` keeps IPv6
* literals bracketed (`[::1]`), so strip the brackets before matching.
* Anything not positively local or private stays unknown: "unknown is not
* zero", so an unrecognized host must never assert `remoteAllowed`.
*/
function classifyHostname(hostname: string): "local" | "private" | null {
const host = hostname.trim().toLowerCase().replace(/\.$/, "").replace(/^\[|\]$/g, "");
if (host === "localhost" || host.endsWith(".localhost") || host === "0.0.0.0") return "local";
if (host === "::1" || /^127\./.test(host)) return "local";
if (/^10\./.test(host)
|| /^192\.168\./.test(host)
|| /^169\.254\./.test(host)
|| /^172\.(1[6-9]|2\d|3[01])\./.test(host)
|| /^f[cd][0-9a-f]{2}:/.test(host)
|| /^fe80:/.test(host)
|| /^::ffff:(?:10\.|127\.|192\.168\.|169\.254\.|172\.(?:1[6-9]|2\d|3[01])\.)/.test(host)) {
return "private";
}
return null;
}
/**
* Adapters whose upstream protocol supports function/tool calling. Mirrors
* the adapter ids the resolver accepts (including the `azure` alias for
* `azure-openai`); `kiro` and `mimo-free` send/delegate tool calls.
*/
const TOOL_CAPABLE_ADAPTERS = new Set([
"openai-chat",
"openai-responses",
"anthropic",
"cursor",
"google",
"azure-openai",
"azure",
"kiro",
"mimo-free",
"command-code",
]);
function localRemoteEvidence(baseUrl: string | undefined): Pick<RouteCapabilityEvidence, "localOnly" | "remoteAllowed"> {
if (typeof baseUrl !== "string" || baseUrl.length === 0) return {};
try {
const hostname = new URL(baseUrl).hostname;
if (!hostname) return {};
const kind = classifyHostname(hostname);
if (kind === null) return {};
// Both booleans are emitted once classified: definitive negative evidence,
// so a local host cannot satisfy `require.remoteAllowed` (or vice versa)
// under `unknownEvidence.capability: "allow"`/`"penalize"`.
return kind === "local" || kind === "private"
? { localOnly: true, remoteAllowed: false }
: { remoteAllowed: true, localOnly: false };
} catch {
return {};
}
}
/**
* Assemble canonical capability evidence for one `provider/model` candidate.
* Sources (in priority order): provider config maps, provider registry hints,
* cached Codex catalog row, native-model metadata.
* Policy assembly supplies the resolved provider so every transport capability
* describes the destination dispatch will use. Its maps already include applicable
* registry defaults; name-only registry fallbacks must not override that authority.
*/
export function candidateCapabilityEvidence(
config: OcxConfig,
providerName: string,
modelId: string,
resolvedProvider?: OcxProviderConfig,
): RouteCapabilityEvidence {
const provider = resolvedProvider ?? config.providers[providerName];
const registryEntry = resolvedProvider === undefined
? PROVIDER_REGISTRY.find(entry => entry.id === providerName)
: undefined;
const catalogRow = cachedCatalogModels().find(model => model.provider === providerName && model.id === modelId);
const isNative = providerName === OPENAI_CODEX_PROVIDER_ID && !modelId.includes("/");
// `modelRecordValue`, not a bare lookup: every runtime reader of these three maps
// resolves them that way, so a `gpt-oss` entry covers `gpt-oss:120b`. Reading raw
// made the evidence disagree with the resolver it claims to describe — and for the
// window it did not even degrade to unknown, it fell through to the provider-wide
// value, which is a definite wrong answer rather than an absent one.
const rawContextWindow = modelRecordValue(provider?.modelContextWindows, modelId)
?? provider?.contextWindow
?? modelRecordValue(registryEntry?.modelContextWindows, modelId)
?? catalogRow?.contextWindow
?? (isNative ? nativeOpenAiContextWindow(modelId, nativeContextLimits(config)) : undefined);
// Native rows go through the accessor (raise-to-ceiling + opt-in). Routed rows keep
// the raw value; a provider cap on openai must not invent a window they do not have.
const contextWindow = isNative
? (nativeOpenAiContextWindow(modelId, nativeContextLimits(config)) ?? rawContextWindow)
: rawContextWindow;
// Exact capability declarations precede legacy vision hints, matching runtime eligibility.
// `noVisionModels` is checked before the remaining modality chain because that is the order
// `isModelTextOnly` uses: it matches the no-vision list and returns true before it
// ever reads `modelInputModalities` (`src/vision/index.ts:32`). So a `gpt-oss`
// no-vision entry beats an exact `gpt-oss:120b` entry that lists "image", and
// deriving `image` from the modality chain alone reported vision on a model the
// runtime refuses it for. That matters more here than on the CLI surface fixed in
// #2086: routing *acts* on this evidence, so it would select the candidate for image
// work that execution then rejects.
const noVision = modelInList(provider?.noVisionModels, modelId);
const explicitModalities = Object.hasOwn(provider?.modelCapabilities ?? {}, modelId)
? provider?.modelCapabilities?.[modelId]?.inputModalities : undefined;
const modalities = explicitModalities?.length ? explicitModalities : noVision
? ["text"]
: (modelRecordValue(provider?.modelInputModalities, modelId)
?? modelRecordValue(registryEntry?.modelInputModalities, modelId)
// Provider-wide declaration, for ids the per-model maps do not list. Read from the
// provider only: a name-only registry lookup would apply it to a custom destination.
?? provider?.inputModalities
?? catalogRow?.inputModalities
?? (isNative ? nativeInputModalities(modelId) : undefined));
const image = Array.isArray(modalities)
? modalities.includes("image")
: undefined;
const capabilities = catalogRow?.capabilities ?? [];
// The catalog `capabilities` list is a positive per-model signal; a row
// without "tools" is treated as unknown, never as a negative. Without a
// catalog row the adapter protocol itself is the signal: tool-capable
// adapters run single tool calls even when the parallel-call opt-in is
// unset or false. `parallelToolCalls` stays a positive provider-level
// override.
const tools = capabilities.includes("tools")
|| isNative
// The adapter protocol is positive evidence on its own. This was once gated
// on `catalogRow === undefined`, which was only safe while the catalog lookup
// never matched anything: once it matches, a row that simply does not
// enumerate "tools" would silently revoke tool support for every openai-chat
// and anthropic candidate.
|| (provider !== undefined && TOOL_CAPABLE_ADAPTERS.has(provider.adapter))
|| provider?.parallelToolCalls === true
|| undefined;
// `noReasoningModels` is a POSITIVE statement that this model has no effort control, and
// every other consumer already reads it that way: configuredReasoningEfforts
// (reasoning-effort.ts), supportedLadderFor (server/effort-policy.ts) and the
// compatibility fingerprint (routing/compatibility/behavior.ts) all check it first.
// Routing evidence did not, which was harmless only while no registry ladder existed to
// contradict it — a provider-level ladder would otherwise report supported rungs for a
// model the operator explicitly disabled reasoning for.
const reasoningEfforts = modelInList(provider?.noReasoningModels, modelId)
? []
: modelRecordValue(provider?.modelReasoningEfforts, modelId)
?? modelRecordValue(registryEntry?.modelReasoningEfforts, modelId)
?? provider?.reasoningEfforts
?? (isNative ? nativeReasoningEfforts(modelId) : undefined);
const tierSupport = provider
? serviceTierSupportForModel(provider, modelId, providerName)
: registryEntry ? serviceTierSupportForModel(registryEntry, modelId, providerName) : undefined;
const serviceTier = tierSupport === true
? "supported"
: tierSupport === false ? "unsupported" : "unknown";
const localRemote = localRemoteEvidence(provider?.baseUrl);
// Only emit a definitive encryptedCodexTasks value when the provider is
// present. An absent/unconfigured provider must stay unknown so
// require.encryptedCodexTasks does not fail closed on missing config.
const encryptedCodexTasks = provider === undefined
? undefined
: isCanonicalOpenAiForwardProvider(provider);
return {
...(typeof contextWindow === "number" ? { contextWindow } : {}),
...(typeof image === "boolean" ? { image } : {}),
...(typeof tools === "boolean" ? { tools } : {}),
// A DEFINED but empty ladder is known-negative evidence and must survive. Dropping it
// made the evaluator take its `!Array.isArray` branch and record "unknown", which is
// permissive — "we could not tell" rather than "this model has no effort control" — so
// an explicitly disabled model could still satisfy a reasoning-effort requirement.
...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
...(serviceTier !== "unknown" ? { serviceTier } : {}),
...localRemote,
...(typeof encryptedCodexTasks === "boolean" ? { encryptedCodexTasks } : {}),
};
}