UNPKG

@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
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 } : {}) }; }