@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
371 lines (342 loc) • 18.2 kB
text/typescript
/**
* Claude-surface context-window map + effective model-env computation
* (devlog/260712_cli_context_cache/010 B2, audit R2#1/R3#1/R3#4/R4#3).
*
* The map registers EVERY selector form a Claude Code model slot might store —
* bare native slug, provider/id, desktop3p alias, current ocx-claude-* alias and
* the legacy claude-ocx-* spelling a saved selector may still carry —
* with first-wins dedupe (mirrors the desktop3p registry collision policy).
* Values are authoritative context windows only (native override table /
* adapter-reported CatalogModel.contextWindow / the Anthropic registry for passthrough ids);
* nothing is guessed.
*/
import { aliasForNative, aliasForRoute, currentClaudeAliasSpelling, legacyAliasForNative, legacyAliasForRoute, resolveAlias } from "./alias";
import { desktop3pAlias } from "./desktop-3p";
import { nativeOpenAiContextWindow, type CatalogModel, type NativeContextLimitsInput } from "../codex/catalog";
import { compareStrictSemver, parseStrictSemver } from "../lib/strict-semver";
import { ANTHROPIC_MODEL_CONTEXT_WINDOWS } from "../providers/registry/model-seeds";
import type { OcxClaudeCodeConfig } from "../types";
import { AUTO_COMPACT_WINDOW_DEFAULT, AUTO_CONTEXT_FLOOR, ONE_MILLION } from "./long-context";
export { AUTO_COMPACT_WINDOW_DEFAULT, AUTO_CONTEXT_FLOOR } from "./long-context";
/**
* Behind a gateway Claude Code accounts an unmarked id at 200k, so unset tier slots use
* concrete model ids when the map marks them (#5755). Claude Code sends a marked alias
* such as `sonnet[1m]` upstream unresolved. Haiku has no automatic fill.
*/
const CLAUDE_CODE_NATIVE_TIERS = { opus: "claude-opus-5-5", sonnet: "claude-sonnet-5-5" } as const;
const FABLE_52_MODEL = "claude-fable-5-2";
// Anthropic rejects Fable 5.2 with a Claude Code identity below this floor.
const FABLE_52_MIN_CLAUDE_CODE = parseStrictSemver("2.1.290")!;
/** Binary-verified accepted range for CLAUDE_CODE_AUTO_COMPACT_WINDOW (2.1.207: pSo=1e5, yDs=1e6). */
export const AUTO_COMPACT_WINDOW_MIN = 100_000;
export const AUTO_COMPACT_WINDOW_MAX = ONE_MILLION;
/** Case-insensitive [1m] marker helpers — the CLI matches /\[1m\]/i (audit 021 #7). */
const ONE_M_MARKER_RE = /\[1m\]$/i;
export function hasOneMillionMarker(value: string): boolean {
return ONE_M_MARKER_RE.test(value);
}
export function stripOneMillionMarker(value: string): string {
return value.replace(ONE_M_MARKER_RE, "");
}
export interface AutoContextMode {
enabled: boolean;
/** Effective CLAUDE_CODE_AUTO_COMPACT_WINDOW value (tokens). */
compactWindow: number;
/** claudeCode.contextAccounting "200k": nothing is marked [1m] automatically, whatever its window. */
accounting200k?: true;
}
export const AUTO_CONTEXT_OFF: AutoContextMode = { enabled: false, compactWindow: AUTO_COMPACT_WINDOW_DEFAULT };
/**
* Marking mode for surfaces whose runner may not inherit the compaction env (Desktop pickers,
* discovery, generated subagents). shouldMarkOneMillion under it equals isLongContextWindow
* (long-context.ts); kept as a mode so the existing marker helpers serve every surface.
*/
export const UNPAIRED_AUTO_CONTEXT: AutoContextMode = { enabled: true, compactWindow: AUTO_COMPACT_WINDOW_DEFAULT };
/** The "200k" opt-in: no widening, no compact-window injection, no automatic marker. */
export const ACCOUNTING_200K: AutoContextMode = { enabled: false, compactWindow: AUTO_COMPACT_WINDOW_DEFAULT, accounting200k: true };
interface AutoContextConfigSlice {
autoContext?: boolean;
autoCompactWindow?: number;
maxContextTokens?: number;
contextAccounting?: string;
}
function inAutoCompactRange(value: number): boolean {
return Number.isInteger(value) && value >= AUTO_COMPACT_WINDOW_MIN && value <= AUTO_COMPACT_WINDOW_MAX;
}
/**
* Resolve the auto-context mode from claudeCode config. Disabled when the user
* turned it off OR when maxContextTokens is set. That override injects only
* CLAUDE_CODE_MAX_CONTEXT_TOKENS: compact stays enabled (no DISABLE_COMPACT) and
* Claude Code compacts against that window for ocx-claude-* ids, so no
* CLAUDE_CODE_AUTO_COMPACT_WINDOW is injected beside it and [1m] auto-marking stays
* off. maxContextTokens accepts values outside the compact variable's 100k–1M
* range, so deriving that variable from it could only produce ignored values.
*
* `envOverride` is the raw CLAUDE_CODE_AUTO_COMPACT_WINDOW the USER already
* exported (user-wins injection keeps it): a valid value drives the marking
* predicate so marker and threshold never separate (audit 021 #2); an invalid
* value disables auto marking entirely (the CLI would ignore it, leaving marked
* sub-1M models without their safety net). Out-of-range CONFIG values fall back
* to AUTO_COMPACT_WINDOW_DEFAULT (the management API rejects them; this guards hand-edits).
*/
export function resolveAutoContext(claudeCode: AutoContextConfigSlice | undefined, envOverride?: string): AutoContextMode {
// The 200k opt-in wins over every other lever, a user-exported compact window included.
if (claudeCode?.contextAccounting === "200k") return ACCOUNTING_200K;
if (claudeCode?.autoContext === false) return AUTO_CONTEXT_OFF;
const maxCtx = claudeCode?.maxContextTokens;
if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) return AUTO_CONTEXT_OFF;
if (typeof envOverride === "string" && envOverride !== "") {
const parsed = Number(envOverride);
return inAutoCompactRange(parsed) ? { enabled: true, compactWindow: parsed } : AUTO_CONTEXT_OFF;
}
const raw = claudeCode?.autoCompactWindow;
const compactWindow = typeof raw === "number" && inAutoCompactRange(raw) ? raw : AUTO_COMPACT_WINDOW_DEFAULT;
return { enabled: true, compactWindow };
}
/**
* Config value -> ENABLE_TOOL_SEARCH wire value (#4838).
*
* Claude Code parses this variable itself and accepts more than a boolean:
* "true", "auto", "auto:N" (N is a percentage floor for non-deferred tools; its
* parser rejects anything under 100) and "force", which also overrides an
* OS-level managed-settings suppression. Passing a string through verbatim keeps
* that whole vocabulary reachable instead of flattening it to a boolean that
* would have to be re-expanded here later.
*
* `false`, absent and blank inject nothing rather than injecting "false". Every
* caller injects with user-wins semantics, so an operator's own export survives
* either way, and writing "false" would be the one path that could quietly
* disagree with it.
*/
export function claudeToolSearchEnv(value: boolean | string | undefined): string | undefined {
if (value === true) return "true";
if (typeof value !== "string") return undefined;
const trimmed = value.trim();
return trimmed.length > 0 ? trimmed : undefined;
}
/**
* [1m]-marking predicate. Windows >= 1M always mark (CLI accounts exactly 1M).
* Auto-context additionally marks windows > 200k that can safely host the compact
* window — marking a model whose real window is BELOW the compact window would put
* the compaction safety net behind the real API limit (mid-session 400s).
*/
export function shouldMarkOneMillion(window: number | undefined, auto: AutoContextMode): boolean {
if (typeof window !== "number" || window <= 0) return false;
if (auto.accounting200k) return false;
if (window >= ONE_MILLION) return true;
return auto.enabled && window > AUTO_CONTEXT_FLOOR && window >= auto.compactWindow;
}
/** Present when bare Claude ids take the native passthrough on this launch (#5755). */
export interface NativeClaudePassthrough {
/** `claudeCode.modelMap`: a mapped id is routed, not passed through. */
modelMap?: Readonly<Record<string, string>>;
}
/**
* On a local subscription launch with `nativePassthrough` on, a bare `claude-*` id goes straight
* to Anthropic under Claude Code's own login and never reaches the router
* (server/claude-messages.ts `wantsNativePassthrough`). Undefined when the router decides:
* proxy auth, passthrough off, or a connected client, which authenticates with an admission token.
*/
export function nativeClaudePassthroughFor(
claudeCode: OcxClaudeCodeConfig | undefined,
markerMode: "proxy" | "subscription",
): NativeClaudePassthrough | undefined {
return markerMode === "subscription" && claudeCode?.nativePassthrough !== false
? { modelMap: claudeCode?.modelMap }
: undefined;
}
export function buildClaudeContextWindows(
nativeSlugs: readonly string[],
routedModels: readonly CatalogModel[],
// A configured providerContextCaps.openai has to reach the native rows here too. Without
// it the Claude surface keeps advertising the uncapped authoritative window while the
// Codex catalog advertises the capped one, and the two disagree about the same model.
nativeContextCap?: NativeContextLimitsInput,
nativeClaude?: NativeClaudePassthrough,
): Record<string, number> {
const out: Record<string, number> = {};
const put = (key: string | null, value: number) => {
if (!key) return;
if (out[key] === undefined) out[key] = value; // first-wins (registry policy)
};
for (const slug of nativeSlugs) {
const window = nativeOpenAiContextWindow(slug, nativeContextCap);
if (typeof window !== "number" || window <= 0) continue;
put(slug, window);
put(desktop3pAlias("native", slug), window);
put(aliasForNative(slug), window);
put(legacyAliasForNative(slug), window);
}
// Passthrough ids never reach the router, so the registry speaks for them ahead of any routed
// row that shares the bare id (#5755). An anthropic row capped under 1M still keeps its id
// unmarked, and a modelMap entry routes its id elsewhere.
if (nativeClaude) {
const capped = new Set(routedModels.flatMap(m =>
m.provider === "anthropic" && typeof m.contextWindow === "number" && m.contextWindow < ONE_MILLION ? [m.id] : []));
for (const [id, window] of Object.entries(ANTHROPIC_MODEL_CONTEXT_WINDOWS)) {
if (window >= ONE_MILLION && !capped.has(id) && !nativeClaude.modelMap?.[id]) put(id, window);
}
}
// Anthropic passthrough guard (audit 021 #3): canonical claude ids ride the
// subscription passthrough — marking a sub-1M one would strap [1m]/1M-beta onto
// a model that cannot host it. Register anthropic rows only at >=1M.
const registrable = routedModels.filter(
m =>
typeof m.contextWindow === "number" &&
m.contextWindow > 0 &&
!(m.provider === "anthropic" && m.contextWindow < ONE_MILLION),
);
// Bare routed ids are registered only when unambiguous across providers (audit
// 021 #5) — natives are registered first, so a native slug always wins the bare
// key. Counted over the rows that can actually claim the key: a row this loop
// skips contributes no window, so letting it veto the bare key withholds an
// answer that was never in doubt.
const bareCounts = new Map<string, number>();
for (const m of registrable) bareCounts.set(m.id, (bareCounts.get(m.id) ?? 0) + 1);
for (const m of registrable) {
const window = m.contextWindow as number;
put(`${m.provider}/${m.id}`, window);
put(desktop3pAlias(m.provider, m.id), window);
put(aliasForRoute(m.provider, m.id), window);
put(legacyAliasForRoute(m.provider, m.id), window);
if (bareCounts.get(m.id) === 1) put(m.id, window);
}
return out;
}
/** Strip a trailing [1m] marker before map lookup (selector may already carry it). */
function bareSelector(value: string): string {
return stripOneMillionMarker(value);
}
/**
* Apply the [1m] context-variant marker to a model selector when its authoritative
* window is >= 1M (Claude Code accounts exactly 1M for the marker; compaction stays
* alive) — or, in auto-context mode, when the window clears the marking predicate
* above. Already-marked selectors pass through; unknown selectors stay untouched.
*/
export function withOneMillionMarker(selector: string | undefined, windows: Record<string, number>, auto: AutoContextMode = AUTO_CONTEXT_OFF): string | undefined {
if (!selector) return selector;
if (hasOneMillionMarker(selector)) return selector;
const window = windows[bareSelector(selector)];
return shouldMarkOneMillion(window, auto) ? `${selector}[1m]` : selector;
}
export interface ClaudeTierModels {
opus?: string;
sonnet?: string;
haiku?: string;
fable?: string;
}
type ModelEnvConfig = AutoContextConfigSlice & {
model?: string;
smallFastModel?: string;
tierModels?: ClaudeTierModels;
};
/** Only probe if the installed CLI can affect the automatic Fable selection. */
export async function probeClaudeCodeVersionForTierFill(
claudeCode: ModelEnvConfig | undefined,
windows: Record<string, number>,
): Promise<string | null> {
if (claudeCode?.tierModels?.fable !== undefined || claudeCode?.contextAccounting === "200k" || !windows[FABLE_52_MODEL]) {
return null;
}
const { probeInstalledClaudeCodeVersion } = await import("./subagent-force-status");
return probeInstalledClaudeCodeVersion();
}
/**
* The exact env map Claude Code consumes for model slots (audit R4#4):
* ANTHROPIC_MODEL + the four tier defaults + the legacy small-fast alias.
* effective-haiku contract (audit R1#8): tierModels.haiku ?? smallFastModel, one
* value injected into BOTH haiku variables.
*/
export function effectiveModelEnv(
claudeCode: ModelEnvConfig | undefined,
windows: Record<string, number>,
autoOverride?: AutoContextMode,
claudeCodeVersion?: string | null,
): Record<string, string> {
const out: Record<string, string> = {};
const auto = autoOverride ?? resolveAutoContext(claudeCode);
// A slot still configured with a legacy claude-ocx selector is emitted in its current
// ocx-claude spelling. The route is identical, but Claude Code applies the context window
// (and keeps compact) only for ids that do not start with "claude-".
const set = (name: string, value: string | undefined) => {
const marked = withOneMillionMarker(value === undefined ? undefined : currentClaudeAliasSpelling(value), windows, auto);
if (marked) out[name] = marked;
};
// An unset tier slot is filled only when its native id marks; otherwise Claude Code keeps
// choosing, as before.
const tier = (configured: string | undefined, native: string) =>
configured ?? (shouldMarkOneMillion(windows[native], auto) ? native : undefined);
set("ANTHROPIC_MODEL", claudeCode?.model);
set("ANTHROPIC_DEFAULT_OPUS_MODEL", tier(claudeCode?.tierModels?.opus, CLAUDE_CODE_NATIVE_TIERS.opus));
set("ANTHROPIC_DEFAULT_SONNET_MODEL", tier(claudeCode?.tierModels?.sonnet, CLAUDE_CODE_NATIVE_TIERS.sonnet));
const installed = parseStrictSemver(claudeCodeVersion);
const fable = installed && compareStrictSemver(installed, FABLE_52_MIN_CLAUDE_CODE) >= 0
? FABLE_52_MODEL : "claude-fable-5-1";
set("ANTHROPIC_DEFAULT_FABLE_MODEL", tier(claudeCode?.tierModels?.fable, fable));
const effectiveHaiku = claudeCode?.tierModels?.haiku ?? claudeCode?.smallFastModel;
set("ANTHROPIC_DEFAULT_HAIKU_MODEL", effectiveHaiku);
set("ANTHROPIC_SMALL_FAST_MODEL", effectiveHaiku);
return out;
}
/**
* Tier slots Claude Code pairs with a `<slot>_NAME` label (#6926). Its /model tier row is
* `label: <slot>_NAME ?? <first-party display name> ?? <slot value>` (2.1.296), and an
* `ocx-claude-*` alias is not a first-party id, so without the label the row prints the alias.
* The alias itself stays the submitted id: saved selections and inbound resolution depend on it.
*/
export const CLAUDE_TIER_LABEL_SLOTS = [
"ANTHROPIC_DEFAULT_OPUS_MODEL",
"ANTHROPIC_DEFAULT_SONNET_MODEL",
"ANTHROPIC_DEFAULT_FABLE_MODEL",
"ANTHROPIC_DEFAULT_HAIKU_MODEL",
] as const;
export type ClaudeTierLabelSlot = (typeof CLAUDE_TIER_LABEL_SLOTS)[number];
export function isClaudeTierLabelSlot(name: string): name is ClaudeTierLabelSlot {
return (CLAUDE_TIER_LABEL_SLOTS as readonly string[]).includes(name);
}
/**
* The picker label for a tier slot holding an OpenCodex alias, spelled like the discovery
* row's `display_name` (model-info.ts): `<slug> (native)`, `<model> (<provider>)` and a
* ` · 1M` variant. The native-namespaced `claude-*` selector is the Anthropic Fable picker
* alias, which discovery labels `(anthropic)`. A trailing `--fast` stays in the model name:
* without the catalog this cannot tell a synthetic Fast sibling from a real model whose id ends
* in `--fast`, and naming the exact model beats a prettier label that could name the wrong one.
* Anything that is not an alias (a first-party id, `provider/model`, a bare slug) gets no
* label: Claude Code either names it itself or the id is already what the user typed.
*/
export function claudeTierDisplayName(selector: string): string | undefined {
const trimmed = selector.trim();
const oneMillion = hasOneMillionMarker(trimmed);
const route = resolveAlias(stripOneMillionMarker(trimmed));
if (route === null) return undefined;
const slash = route.indexOf("/");
let provider = slash > 0 ? route.slice(0, slash) : "native";
const model = slash > 0 ? route.slice(slash + 1) : route;
if (!model) return undefined;
if (provider === "native" && model.startsWith("claude-")) provider = "anthropic";
return `${model} (${provider})${oneMillion ? " · 1M" : ""}`;
}
/** `{ "<slot>_NAME": label }` for each tier slot in `env` that holds an OpenCodex alias. */
export function claudeTierDisplayNameEnv(env: Readonly<Record<string, string | undefined>>): Record<string, string> {
const out: Record<string, string> = {};
for (const slot of CLAUDE_TIER_LABEL_SLOTS) {
const value = env[slot];
const label = value ? claudeTierDisplayName(value) : undefined;
if (label !== undefined) out[`${slot}_NAME`] = label;
}
return out;
}
/** Shared 3s bounded acquisition (audit R4#3) for context-window sources. */
export async function boundedContextWindows(
acquire: () => Promise<Record<string, number>>,
timeoutMs = 3_000,
): Promise<Record<string, number> | null> {
try {
return await Promise.race([
acquire(),
new Promise<null>(resolve => setTimeout(() => resolve(null), timeoutMs)),
]);
} catch {
return null;
}
}