@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
416 lines (400 loc) • 18.9 kB
text/typescript
import { approvedCodexProviders } from "./provider-routing";
import { currentExternalCodexModelProvider, injectCodexConfig } from "./inject";
import { FOREIGN_CODEX_HOME_OWNER_MESSAGE, UNKNOWN_CODEX_HOME_OWNER_MESSAGE, unbackedRoutedRemovalMessage } from "./catalog/routed-removal";
import { printProjectCodexConfigWarnings, groupProjectCodexConfigWarningsByPath, type ProjectCodexConfigWarning } from "./project-config-warnings";
import { refreshCodexModelCatalog } from "./refresh";
import { applyProxyEnv, loadConfig } from "../config";
import type { OcxConfig } from "../types";
import { collectOrcaCodexHomeDiagnostic } from "./home";
import { summarizeComboCatalogOmissions, type ComboCatalogOmission } from "./catalog/aggregation";
import {
localClientSkipMessage,
localClientSkipReason,
shouldSyncCodexOnStart,
type LocalClientSkipReason,
} from "./desired-state";
import { admitCodexWrite, type CodexAdmission } from "./admission";
import type { CodexCatalogSyncOptions } from "./catalog/sync";
import { resetCodexAppServerCatalogStateCache } from "./app-server-processes";
import { providerUsesReasoningMetadata, refreshReasoningMetadata } from "../providers/reasoning-metadata";
export interface CodexSyncResult {
/**
* `skipped` is policy truth, never evidence that Codex was written.
* `catalog-only` means an explicit sync refreshed the catalog/cache while
* config/history injection was skipped (integration OFF, or externally owned).
*/
status: "applied" | "skipped" | "catalog-only" | "refused";
ok: boolean;
/** `hub-gated` is the hub-role gate, not the user's toggle — the two read very differently. */
skippedReason?: LocalClientSkipReason;
/** Present when unattended convergence refused another service's native home. */
authority?: "service-home";
added: number;
catalogPath: string | null;
catalogExists: boolean;
catalogWritten: boolean;
/** Committed configuration-byte change, never inferred from a successful no-op. */
configChanged?: boolean;
cacheSynced: boolean;
/**
* Whether the catalog owner committed a validated catalog or refused the
* refresh. Available on applied and catalog-only results; `ok` on applied
* describes config injection, so callers must also inspect catalog evidence.
*/
refreshOutcome?: "committed" | "refused";
message: string;
warning?: string;
comboOmissions?: ComboCatalogOmission[];
nativeSubagentDefaultsWarning?: string;
projectConfigWarnings?: ProjectCodexConfigWarning[];
projectConfigGrouped?: { path: string; issues: string[]; bypass: string }[];
}
export interface CodexSyncOptions {
/**
* Explicit `ocx sync` is also the refresh path for side profiles that consume
* the OpenCodex catalog without injection. When set, the sync still refreshes
* the catalog and models cache even if the Codex integration toggle is OFF or
* an external `model_provider` owns config.toml. Config/history injection is
* skipped in those two cases. A paginated-history refusal is NOT one of them:
* the injector writes config and stands only its relabel unit down.
*/
catalogEvenWhenNotInjected?: boolean;
}
type CodexSyncAdmission = Extract<CodexAdmission, { kind: "refused" }> | { readonly kind: "admitted" };
interface CodexSyncDeps {
refreshCodexModelCatalog: typeof refreshCodexModelCatalog;
injectCodexConfig: typeof injectCodexConfig;
/** The sync entry only needs this admission's service-home verdict. */
admitCodexWrite?: () => CodexSyncAdmission;
currentExternalCodexModelProvider?: typeof currentExternalCodexModelProvider;
collectCodexHomeDiagnostic?: typeof collectOrcaCodexHomeDiagnostic;
refreshReasoningMetadata?: typeof refreshReasoningMetadata;
}
const defaultDeps: CodexSyncDeps = {
refreshCodexModelCatalog,
injectCodexConfig,
refreshReasoningMetadata,
};
async function refreshReasoningMetadataForSync(config: OcxConfig, deps: CodexSyncDeps): Promise<void> {
if (Object.values(config.providers).some(providerUsesReasoningMetadata)) {
await deps.refreshReasoningMetadata?.({ waitMs: 2_000 });
}
}
function reportCodexHomeTarget(
log: Pick<Console, "log" | "error"> | null,
collectDiagnostic: typeof collectOrcaCodexHomeDiagnostic,
): void {
if (!log) return;
const target = collectDiagnostic();
log.log(` Target Codex home: ${target.effectiveCodexHome}`);
if (target.warning) {
log.error(`WARNING: ${target.warning}`);
log.error(`Action: ${target.action}`);
}
}
export async function syncModelsToCodex(
port?: number,
config: OcxConfig = loadConfig(),
log: Pick<Console, "log" | "error"> | null = console,
deps: CodexSyncDeps = defaultDeps,
options: CodexSyncOptions = {},
): Promise<CodexSyncResult> {
// `config` can be the server's startup object. The decision, however, is a
// durable user switch and must be read again at this production boundary: a
// PUT OFF while provider discovery is in flight cannot be allowed to commit
// through an older captured object.
const gateSnapshot = loadConfig();
const desiredDisabled = !shouldSyncCodexOnStart(gateSnapshot);
const catalogEvenWhenNotInjected = options.catalogEvenWhenNotInjected === true;
if (desiredDisabled && !catalogEvenWhenNotInjected) {
return {
status: "skipped",
skippedReason: localClientSkipReason(gateSnapshot),
ok: true,
added: 0,
catalogPath: null,
catalogExists: false,
catalogWritten: false,
cacheSynced: false,
message: localClientSkipMessage(
gateSnapshot,
"Codex integration is OFF; no Codex config, catalog, cache, or history was changed.",
"No Codex config, catalog, cache, or history was changed.",
),
};
}
// Catalog gathering precedes injection and can itself write the native
// catalog/cache. It therefore needs the same unattended service-home veto as
// the injector, before it gets a chance to create any artifact.
const admission = (deps.admitCodexWrite ?? admitCodexWrite)();
if (admission.kind === "refused" && admission.authority === "service-home") {
// Startup turns this result into a failed /readyz and records nothing else, and
// `ocx sync` only says the sync did not complete, so an unattended refusal must
// leave one line behind (#5782). The admission message can name private home and
// service-definition paths, so the log carries the authority only; POST /api/sync
// returns the specific reason to an authenticated operator.
log?.error(
"[opencodex] Codex write refused (service-home): this proxy could not prove it owns the "
+ "installed service homes, so catalog sync and Codex config injection were skipped. "
+ "POST /api/sync returns the specific reason.",
);
return {
status: "refused",
authority: "service-home",
ok: false,
added: 0,
catalogPath: null,
catalogExists: false,
catalogWritten: false,
cacheSynced: false,
message: admission.message,
};
}
// Config injection is a relevant Codex write even when the catalog bytes are unchanged.
// Drop cached process evidence before async discovery so a process that appeared since the
// last read cannot make native-default guidance report active after this sync.
resetCodexAppServerCatalogStateCache();
const p = port ?? config.port ?? 10100;
const externalProvider = (deps.currentExternalCodexModelProvider ?? currentExternalCodexModelProvider)();
if (desiredDisabled && catalogEvenWhenNotInjected) {
// Explicit `ocx sync` with the integration OFF: refresh the catalog/cache so
// side profiles that route to the proxy keep their model list current, but
// never touch config, journal, or history.
applyProxyEnv(config);
const refreshed = await refreshCatalogForSync(config, deps, { allowWhenDesiredDisabled: true }, log);
const message = refreshed.catalogWritten || refreshed.cacheSynced
? localClientSkipMessage(
gateSnapshot,
"Codex integration is OFF; catalog and models cache refreshed, Codex config untouched.",
"Catalog and models cache refreshed, Codex config untouched.",
)
: localClientSkipMessage(
gateSnapshot,
"Codex integration is OFF; catalog refresh skipped, Codex config untouched.",
"Catalog refresh skipped, Codex config untouched.",
);
return {
status: "catalog-only",
ok: true,
...refreshed,
message,
...(refreshed.comboOmissions.length > 0 ? { comboOmissions: refreshed.comboOmissions } : {}),
};
}
if (externalProvider && !approvedCodexProviders().includes(externalProvider)) {
if (catalogEvenWhenNotInjected) {
// External providers own config.toml, and the injector removes the OpenCodex
// journal for external providers (inject.ts). This explicit catalog-only sync
// must not touch config, journal, or history, so refresh the catalog/cache and
// return without injection.
applyProxyEnv(config);
const refreshed = await refreshCatalogForSync(config, deps, undefined, log);
const message = refreshed.catalogWritten || refreshed.cacheSynced
? "External provider owns config.toml; catalog and models cache refreshed, Codex config/journal untouched."
: "External provider owns config.toml; catalog refresh skipped, Codex config/journal untouched.";
return {
status: "catalog-only",
ok: true,
...refreshed,
message,
...(refreshed.comboOmissions.length > 0 ? { comboOmissions: refreshed.comboOmissions } : {}),
};
}
const result = await deps.injectCodexConfig(p, config, {});
if (result.success) log?.log(result.message);
else log?.error(result.message);
reportCodexHomeTarget(log, deps.collectCodexHomeDiagnostic ?? collectOrcaCodexHomeDiagnostic);
return {
status: "applied",
ok: result.success,
...(result.success && result.configChanged === true ? { configChanged: true } : {}),
added: 0,
catalogPath: null,
catalogExists: false,
catalogWritten: false,
cacheSynced: false,
message: result.message,
...(result.nativeSubagentDefaultsWarning ? { nativeSubagentDefaultsWarning: result.nativeSubagentDefaultsWarning } : {}),
};
}
// Injection has deterministic refusal paths (for example an ambiguous marker-owned TOML
// table) that do not depend on provider discovery. Exercise the SAME transformation and
// coordination eligibility before catalog gathering: a known-bad config must not turn a
// working catalog/cache into the partial result of an otherwise unnecessary refresh.
const preflight = await deps.injectCodexConfig(p, config, { validateOnly: true });
if (!preflight.success) {
// A paginated-history refusal used to be downgraded here to a `catalog-only` success.
// That is what made the model picker regression silent: the catalog file was rewritten
// and reported synchronized while config.toml kept no provider table and no catalog
// path, so Codex offered only its native models. The injector now writes config and
// stands the relabel unit down instead, so nothing reaches this branch for that reason
// and a surviving refusal is a real config/integrity failure again.
log?.error(preflight.message);
reportCodexHomeTarget(log, deps.collectCodexHomeDiagnostic ?? collectOrcaCodexHomeDiagnostic);
return {
status: "applied",
ok: false,
added: 0,
catalogPath: null,
catalogExists: false,
catalogWritten: false,
cacheSynced: false,
message: preflight.message,
...(preflight.nativeSubagentDefaultsWarning
? { nativeSubagentDefaultsWarning: preflight.nativeSubagentDefaultsWarning }
: {}),
};
}
applyProxyEnv(config); // `ocx ensure`/`ocx sync` fetch provider models outside the server process
await refreshReasoningMetadataForSync(config, deps);
let added = 0;
let catalogPath: string | null = null;
let catalogPathForInjection: string | null | undefined;
let catalogExists = false;
let catalogWritten = false;
let cacheSynced = false;
let warning: string | undefined;
let comboOmissions: ComboCatalogOmission[] = [];
let refreshOutcome: "committed" | "refused" | undefined;
try {
const cat = await deps.refreshCodexModelCatalog(config);
added = cat.added;
refreshOutcome = cat.refreshOutcome;
catalogExists = cat.catalogExists;
catalogWritten = cat.catalogWritten;
cacheSynced = cat.cacheSynced;
catalogPathForInjection = cat.catalogExists ? cat.path : null;
catalogPath = catalogPathForInjection;
comboOmissions = cat.comboOmissions ?? [];
if (cat.skippedReason === "unbacked_routed_removal" || cat.skippedReason === "foreign_owner" || cat.skippedReason === "owner_unknown") {
// The catalog on disk is kept as it was; say so, or a native-only refresh refused for safety
// reads exactly like a successful sync (#6529).
warning = cat.skippedReason === "foreign_owner"
? FOREIGN_CODEX_HOME_OWNER_MESSAGE
: cat.skippedReason === "owner_unknown" ? UNKNOWN_CODEX_HOME_OWNER_MESSAGE
: unbackedRoutedRemovalMessage(cat.protectedRoutedNamespaces ?? 1);
log?.error(`[opencodex] ${warning}`);
} else if (cat.added > 0) {
log?.log(` + ${cat.added} models appended to Codex catalog (${cat.path})`);
} else if (!cat.catalogExists) {
warning = "catalog sync skipped: no Codex catalog source found; keeping Codex's native catalog.";
log?.error(warning);
}
if (comboOmissions.length > 0) {
// Individual omission lines already went through console.warn during gather;
// keep a single summary on the sync logger to avoid duplicate stderr noise.
const summary = summarizeComboCatalogOmissions(comboOmissions);
log?.error(summary);
warning = warning ? `${warning} ${summary}` : summary;
}
} catch (e) {
warning = `catalog sync skipped: ${e instanceof Error ? e.message : String(e)}`;
log?.error(warning);
}
const result = await deps.injectCodexConfig(p, config, { catalogPath: catalogPathForInjection });
if (result.status === "skipped") {
return {
status: "skipped",
// The apply direction's only policy skips are desired OFF, the hub gate and a sibling
// instance; carry whichever the injector reported so the caller can say the honest thing.
skippedReason: result.skippedReason === "hub-gated" || result.skippedReason === "sibling"
? result.skippedReason
: "desired_disabled",
ok: true,
added: 0,
catalogPath: null,
catalogExists: false,
catalogWritten: false,
cacheSynced: false,
message: result.message,
};
}
if (result.success) log?.log(result.message);
else log?.error(result.message);
// The config was written; only the relabel unit stood down. Carry that as a warning so a
// caller reading the structured result sees it without parsing the display message.
if (result.success && result.historyPreflightFailureReason) {
const historyWarning = `Codex conversation-history relabel left to Codex's native writer: ${result.historyPreflightFailureReason}.`;
warning = warning ? `${warning} ${historyWarning}` : historyWarning;
}
reportCodexHomeTarget(log, deps.collectCodexHomeDiagnostic ?? collectOrcaCodexHomeDiagnostic);
const projectConfigWarnings = printProjectCodexConfigWarnings(log, { cwd: process.cwd() });
return {
status: "applied",
ok: result.success,
...(result.success && result.configChanged === true ? { configChanged: true } : {}),
added,
...(refreshOutcome ? { refreshOutcome } : {}),
catalogPath,
catalogExists,
catalogWritten,
cacheSynced,
message: result.message,
...(warning ? { warning } : {}),
...(comboOmissions.length > 0 ? { comboOmissions } : {}),
...(result.nativeSubagentDefaultsWarning ? { nativeSubagentDefaultsWarning: result.nativeSubagentDefaultsWarning } : {}),
...(projectConfigWarnings.length > 0 ? {
projectConfigWarnings,
projectConfigGrouped: groupProjectCodexConfigWarningsByPath(projectConfigWarnings),
} : {}),
};
}
async function refreshCatalogForSync(
config: OcxConfig,
deps: CodexSyncDeps,
catalogOptions: CodexCatalogSyncOptions | undefined,
log: Pick<Console, "log" | "error"> | null,
): Promise<{
added: number;
catalogPath: string | null;
catalogExists: boolean;
catalogWritten: boolean;
cacheSynced: boolean;
comboOmissions: ComboCatalogOmission[];
refreshOutcome?: "committed" | "refused";
warning?: string;
}> {
let added = 0;
let catalogPath: string | null = null;
let catalogExists = false;
let catalogWritten = false;
let cacheSynced = false;
let warning: string | undefined;
let refreshOutcome: "committed" | "refused" | undefined;
let comboOmissions: ComboCatalogOmission[] = [];
try {
await refreshReasoningMetadataForSync(config, deps);
const cat = await deps.refreshCodexModelCatalog(config, undefined, catalogOptions);
refreshOutcome = cat.refreshOutcome;
added = cat.added;
catalogExists = cat.catalogExists;
catalogWritten = cat.catalogWritten;
cacheSynced = cat.cacheSynced;
catalogPath = cat.catalogExists ? cat.path : null;
comboOmissions = cat.comboOmissions ?? [];
if (cat.skippedReason === "unbacked_routed_removal" || cat.skippedReason === "foreign_owner" || cat.skippedReason === "owner_unknown") {
// The catalog on disk is kept as it was; say so, or a native-only refresh refused for safety
// reads exactly like a successful sync (#6529).
warning = cat.skippedReason === "foreign_owner"
? FOREIGN_CODEX_HOME_OWNER_MESSAGE
: cat.skippedReason === "owner_unknown" ? UNKNOWN_CODEX_HOME_OWNER_MESSAGE
: unbackedRoutedRemovalMessage(cat.protectedRoutedNamespaces ?? 1);
log?.error(`[opencodex] ${warning}`);
} else if (cat.added > 0) {
log?.log(` + ${cat.added} models appended to Codex catalog (${cat.path})`);
} else if (!cat.catalogExists) {
warning = "catalog sync skipped: no Codex catalog source found; keeping Codex's native catalog.";
log?.error(warning);
}
if (comboOmissions.length > 0) {
const summary = summarizeComboCatalogOmissions(comboOmissions);
log?.error(summary);
warning = warning ? `${warning} ${summary}` : summary;
}
} catch (e) {
warning = `catalog sync skipped: ${e instanceof Error ? e.message : String(e)}`;
log?.error(warning);
}
return { added, catalogPath, catalogExists, catalogWritten, cacheSynced, comboOmissions,
...(refreshOutcome ? { refreshOutcome } : {}), ...(warning ? { warning } : {}) };
}