@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,940 lines • 102 kB
text/typescript
import type { OcxProviderConfig } from "./provider";
import type { CodexAccount, CodexAccountLoginConfig } from "./accounts";
import type { AnthropicAccountPoolConfig, OcxAccountPoolRotationStrategy } from "./anthropic-account-pool";
import type { AnthropicInstanceId } from "../providers/anthropic-instance-id";
import type { OcxFallbackConfig } from "./fallback";
import type { MultiAgentMode } from "./multi-agent";
import type { OcxTelemetryConfig } from "./telemetry";
import type { OcxClaudeCodeToolLoadingConfig } from "./claude-tool-loading";
import type { OcxLinkHomeConfig, OcxLinkTransportConfig } from "./link";
import type { OcxRoutingProfileConfig } from "./routing-profile";
export type { AnthropicAccountPoolConfig, AnthropicModelRoute, OcxAccountPoolRotationStrategy, OcxAccountPoolQuotaWindow } from "./anthropic-account-pool";
export type { OcxFallbackConfig, OcxFallbackDeviceConfig, OcxFallbackKind, OcxFallbackSwitches } from "./fallback";
export type { OcxClaudeCodeToolLoadingConfig } from "./claude-tool-loading";
export type {
OcxRoutingUnknownEvidenceMode, OcxRoutingProfileCandidate, OcxRoutingProfileRequirements, OcxRoutingProfileOptimize,
OcxRoutingUnknownCostCapMode, OcxRoutingProfileLimits, OcxRoutingProfileUnknownEvidence,
OcxRoutingProfileCompatibilitySuite, OcxRoutingProfileCompatibility, OcxRoutingProfileConfig,
} from "./routing-profile";
/** Public inference API exposure. Responses and Chat Completions are always served. */
export interface OcxApiSurfacesConfig {
/**
* `/v1/messages` and `/v1/messages/count_tokens`. Absent means "inherit
* `claudeCode.enabled !== false`"; a present non-boolean value disables the surface.
*/
messages?: { enabled?: boolean };
/** Gemini-compatible routes. The surface is open by default. */
gemini?: { enabled?: boolean };
}
/** Protocol delivery policy (devlog/_plan/260924_protocol_first_class). */
export interface OcxProtocolsConfig {
/**
* What happens when the final upstream wire cannot express a requested feature.
* `legacy` (default) keeps today's behavior; `reject` refuses before any upstream send.
*/
unrepresentable?: "legacy" | "reject";
/** Staged rollout switches. Every switch defaults off and changes no semantics while off. */
rollout?: {
/** Eligible Chat candidates inside combos and policy routes send natively. */
nativeChatCombos?: boolean;
/** Proxy-managed key-auth Anthropic targets receive `/v1/messages` natively. */
managedMessagesNative?: boolean;
/** Extends managed native Messages to Anthropic OAuth accounts. Requires the switch above. */
managedMessagesNativeOAuth?: boolean;
/** Chat and Messages clients are encoded directly from adapter events. */
directEncoders?: boolean;
/**
* Chat requests to a concrete Google Antigravity route decode straight into the IR and are
* answered through the direct encoders, with no internal Responses body in either direction.
*/
antigravityDirect?: boolean;
/** Preserve native Gemini payloads for concrete Antigravity OAuth routes on /v1beta. Default off. */
geminiNativeAntigravity?: boolean;
/** Compare the dispatch plan with the observed path; never sends a second request. */
shadowPlan?: boolean;
};
}
/**
* Claude Code inbound settings (devlog/260711_claude_inbound). Consumed by the
* /v1/messages surface, the `ocx claude` launcher, and the GUI Claude page. Tool-loading
* fields (toolSearch and the two tool-loading opt-ins) live in ./claude-tool-loading.
*/
export interface OcxClaudeCodeConfig extends OcxClaudeCodeToolLoadingConfig {
/** Route the standalone Claude Code CLI through the first-party intercept (settings.json env).
* Independent of Desktop's first-party mode. Absent/false = off. */
cliFirstParty?: boolean;
/**
* Opt-in relocation of supported trailing Claude harness notices from system instructions
* to a user input message on translated routes. Changes the Desktop cache-key prefix.
* Default: false; only literal true enables it. Native passthrough is unchanged.
*/
stabilizePromptCache?: boolean;
/** Opt-in translated Messages admission; unset keeps legacy behavior. Native passthrough is exempt. */
compatibility?: "shadow" | "enforce";
/** Kill switch for the /v1/messages inbound (GUI "Claude ON" toggle). Default: enabled. */
enabled?: boolean;
/**
* Verbatim passthrough of unmapped claude/anthropic models to api.anthropic.com with the
* caller's own sk-ant-* credential (Claude Code subscription OAuth). Default: enabled.
*/
nativePassthrough?: boolean;
/** Upstream for the native passthrough (tests/enterprise gateways). Default: https://api.anthropic.com */
anthropicBaseUrl?: string;
/**
* Native passthrough body inactivity budget in SECONDS — raw upstream-byte silence
* while a read is pending, NOT total duration (slow-but-alive streams never trip it;
* devlog 260716_passthrough_followups/010). Default 90. Min 1. Exactly 0 disables;
* negative/non-finite values fall back to the default.
*/
bodyStallSec?: number;
/**
* Native passthrough cumulative body byte cap (streamed SSE and buffered non-stream
* alike) — an OOM/occupancy guard, not a correctness limit. Default 67108864 (64 MiB).
* Exactly 0 disables; negative/non-finite values fall back to the default.
*/
bodyMaxBytes?: number;
/** Default model slot injected as ANTHROPIC_MODEL by `ocx claude`. */
model?: string;
/** Haiku/small-fast slot injected as ANTHROPIC_DEFAULT_HAIKU_MODEL (+ legacy SMALL_FAST). */
smallFastModel?: string;
/** Inbound model id remaps: exact id first, then date-stripped (`-\d{8}$`). */
modelMap?: Record<string, string>;
/**
* Explicit classifier model for Claude Code Auto Mode safety checks (e.g. "RelayA/claude-opus-5").
* When unset, bare classifier requests check modelMap, then same-provider affinity from
* `claudeCode.model`, then compatible Anthropic-adapter providers, and finally fallbacks.
*/
classifierModel?: string;
/**
* Ordered fallback candidates for Claude Code Auto Mode classifier routing when the primary
* classifier route is not available.
*/
classifierFallbacks?: string[];
/**
* Inject ANTHROPIC_BASE_URL etc. into the macOS user domain via `launchctl setenv`
* so plain `claude` commands route through the proxy without `ocx claude`. Reverted
* on stop/shutdown. Default: false (opt-in). macOS only.
*/
systemEnv?: boolean;
/**
* Auth mode for Claude Code inbound requests — a THREE-state intent.
*
* "proxy": inject the dummy ANTHROPIC_AUTH_TOKEN so Claude Code routes through the
* proxy without a real Anthropic key. "subscription": never inject it. UNSET means
* AUTO: the mode is resolved from detected Claude auth on every launch and every
* status read (src/claude/auth-mode.ts), so registering a Claude login switches the
* behaviour with no migration and no stored state.
*
* An explicit value always wins over detection and is never rewritten by the auto
* logic — that is what makes a manual choice stick (devlog 260726_claude_auth_auto).
*/
authMode?: "proxy" | "subscription";
/**
* ISO timestamp of the one-time authMode migration. Before auto existed, choosing
* "Subscription" DELETED the key, so a pre-upgrade config cannot distinguish an
* explicit subscription choice from "never chose". Its ABSENCE identifies a
* pre-upgrade block; the migration writes it once and never re-runs, so a user who
* later picks Auto (which deletes authMode) is not silently converted back.
*/
authModeMigratedAt?: string;
/**
* Context-window override for Claude Code/Desktop clients (devlog 136 B6).
* Injected as CLAUDE_CODE_MAX_CONTEXT_TOKENS only. Current ocx-claude aliases do
* not start with claude-, so Claude Code 2.1.278 honors the window without
* DISABLE_COMPACT. A persisted claude-ocx id is still claude-shaped and keeps
* the 200k accounting until the picker selects the new id. Unset = client defaults.
*/
maxContextTokens?: number;
/**
* Opt-in CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1 injection. Default OFF: opus-shaped
* aliases already carry output_config.effort on the wire (devlog 136 실측), and
* forcing effort on every request can leak reasoning params to non-reasoning routes.
*/
alwaysEnableEffort?: boolean;
/**
* Subagent tier slots (devlog 260712 B2): injected as ANTHROPIC_DEFAULT_*_MODEL so
* Claude Code's Agent-tool aliases (opus/sonnet/haiku/fable + parent-inherit) route
* to proxy models. haiku falls back to smallFastModel (one effective value feeds
* both ANTHROPIC_DEFAULT_HAIKU_MODEL and legacy ANTHROPIC_SMALL_FAST_MODEL).
*/
tierModels?: { opus?: string; sonnet?: string; haiku?: string; fable?: string };
/**
* Auto-context (devlog 260712 020): when not false, routed/native models whose
* authoritative window is > 200k AND >= the compact window get the [1m] marker
* (Claude Code then accounts 1M) and CLAUDE_CODE_AUTO_COMPACT_WINDOW is injected
* so compaction fires at the real budget. 2.1.207 semantics (binary-verified):
* effective compact window = min(believed window, env) — one global env behaves
* like a per-model floor. Default: enabled. Inert while maxContextTokens is set.
*/
autoContext?: boolean;
/** Compact-window tokens for auto-context. Default 829_800 (AUTO_COMPACT_WINDOW_DEFAULT). */
autoCompactWindow?: number;
/**
* Context accounting on Claude surfaces (devlog/_plan/261009_claude_1m_default/030). Absent
* (the default) = "1m": long-window models are offered at 1M wherever opencodex picks the
* default (launch env slots, Desktop pickers, Desktop 3P prefer1m, generated subagents).
* "200k" is the opt-in: nothing is marked [1m] automatically and no compact window is injected;
* a selector the user marks [1m] keeps it, and discovery and Desktop 3P keep offering 1M as a
* choice. The only stored value; "1m" deletes the key.
*/
contextAccounting?: "200k";
/**
* Local CONNECT proxy + TLS listener that intercepts Claude Code's own `api.anthropic.com`
* traffic without any `ANTHROPIC_BASE_URL` rewrite (src/claude/intercept). Claude Code reaches
* it via `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` in its settings env. Default: enabled on a
* hub; the proxy port defaults to the public port + 100.
*
* `modelMap` holds first-party model bindings (src/claude/intercept/model-bindings.ts): a
* Claude Desktop Code tab picker id such as `claude-sonnet-4-6` mapped to an opencodex route in
* the Desktop route vocabulary (`provider/model`, or `native/<slug>`). Bindings apply only to
* requests that arrive through the intercept pair, overlaid on the global `modelMap`.
*/
intercept?: {
enabled?: boolean;
port?: number;
/** First-party Desktop Code-tab picker injection; unset enables it when eligible. */
picker?: boolean;
modelMap?: Record<string, string>;
};
/**
* Bundled-skill content elision for ROUTED (non-Anthropic) models (devlog 260712
* 060): Skill-tool results whose skill name matches an entry here are replaced
* with a short stub in the anthropic->responses translation. Third-party models
* are not trained on these Anthropic doc bundles, and claude-api alone injects
* ~136k tokens (GitHub anthropics/claude-code#74473). Native Anthropic
* passthrough never goes through the translation, so Claude models keep the
* full content. Default: ["claude-api"]. Empty array = explicitly off.
*/
blockedSkills?: string[];
/**
* Sync the featured subagent roster (config.subagentModels + main model) into
* ~/.claude/agents/ocx-*.md custom agent definitions at launch (devlog 260712
* 070) so any routed model is dispatchable as a subagent_type — the Agent
* tool's model argument is a hard 4-alias enum, but definition frontmatter is
* free. Only ocx-*.md files are owned/pruned. Default: enabled.
*/
injectAgents?: boolean;
/**
* Optional Claude Code effort pinned in every generated ocx-* subagent
* definition. Unset inherits the parent session effort.
*/
subagentEffort?: "low" | "medium" | "high" | "xhigh" | "max";
/** Optional roster-style model forced on subagents at the next routed Claude Code launch. */
subagentModelForce?: string;
/** Claude-originated web-search override. Unset fields inherit the global sidecar settings. */
webSearchSidecar?: { enabled?: boolean; backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa"; model?: string; anthropicInstance?: AnthropicInstanceId };
/** Claude-originated vision override. Unset fields inherit the global sidecar settings. */
visionSidecar?: { enabled?: boolean; backend?: "openai" | "anthropic" | "routed"; model?: string; anthropicInstance?: AnthropicInstanceId };
/** Persisted Claude Desktop four-family routing profile. */
desktopProfile?: OcxClaudeDesktopProfile;
/**
* How Claude Desktop reaches opencodex (src/claude/desktop-first-party.ts).
* `gateway` (default) installs the third-party deployment profile (desktop-3p) for the whole app.
* `first-party` leaves the app on its normal claude.ai login and redirects only the Code tab's
* Claude Code process through the intercept pair via settings.json env; it sends Claude
* subscription traffic through a local interception proxy and carries an account-risk warning
* (src/claude/desktop-risk.ts). Unset: a gateway row or apply marker resolves to `gateway`, and
* first-party env that opencodex wrote resolves to `first-party` (observeClaudeDesktopMode).
*/
desktopMode?: "first-party" | "gateway";
/** Auto-reconcile Desktop 3P config when provider catalog changes. Default: enabled. */
desktopAutoApply?: boolean;
/**
* When false, omit `native/*` rows from Claude Desktop show/export/apply. Default: enabled.
* Routing-sidecar alias decoding is unchanged — only the Desktop model list writer.
*/
desktopNativeModels?: boolean;
/**
* Which models the Claude Desktop 3P list carries (src/claude/desktop-model-visibility.ts).
* Unset lists every available model. Independent of desktopProfile tiers and of
* provider-wide disabledModels; other clients are unaffected.
*/
desktopModelVisibility?: OcxClaudeDesktopModelVisibility;
}
/** `include`: only `routes` (new models hidden). `exclude`: all but `routes` (new models listed). */
export interface OcxClaudeDesktopModelVisibility {
mode: "include" | "exclude";
routes: string[];
}
export type OcxClaudeDesktopFamily = "opus" | "fable" | "sonnet" | "haiku";
export interface OcxClaudeDesktopAssignment {
family: OcxClaudeDesktopFamily;
alias: string;
}
export interface OcxClaudeDesktopProfile {
version: 1;
assignments: Record<string, OcxClaudeDesktopAssignment>;
defaults: Record<OcxClaudeDesktopFamily, string | null>;
/** SHA-256 fingerprint of the last successfully applied 3P config content. */
appliedFingerprint?: string;
/** ISO timestamp of the last successful apply. */
appliedAt?: string;
}
/**
* Opt-in archived-session auto-cleanup policy (issue #42 Phase 3).
* Persisted under `OcxConfig.storageCleanupPolicy`. Default `enabled: false`.
*/
export interface StorageCleanupPolicy {
/** When false/unset, the engine never mutates. Default false. */
enabled: boolean;
/** Run when archived session bytes exceed this threshold. */
trigger: { archivedBytesOver: number };
/** Either shrink archives toward a byte floor, or remove the oldest N%. */
target: { reduceToBytes?: number } | { removeOldestPercent?: number };
schedule: "startup" | "daily" | "weekly" | "manual";
/** Default quarantine. Permanent only when explicitly set. */
mode: "quarantine" | "permanent";
lastRun?: { at: number; freedBytes: number; removed: number };
/** Epoch ms when the next scheduled evaluation is due. */
nextRun?: number;
}
/** 사용자가 대시보드에서 직접 추가한 커스텀 모델 정의. */
export interface OcxCustomModel {
/** 고유 ID (crypto.randomUUID()) */
id: string;
/** 프로바이더 키 (기존 providers[name]) */
provider: string;
/** Native provider model id; slashes are allowed and encoded for Codex as provider/<hyphenated-id>. */
modelId: string;
/** 인간 가독 표시명 (선택, 슬래시 불가) */
displayName?: string;
/** 컨텍스트 윈도우 (토큰) */
contextWindow?: number;
/** 입력 모달리티 (선택, 기본 ["text"]) */
inputModalities?: string[];
/**
* Reasoning ladder (Codex labels) this custom row explicitly advertises. An empty array
* hides the effort control; an omitted key leaves the provider-derived ladder in charge.
*/
reasoningEfforts?: string[];
/** Default effort label when `reasoningEfforts` is non-empty. */
defaultReasoningEffort?: string;
/**
* Codex tool calling mode override for this custom model.
* "code_mode_only" (default) sets entry.tool_mode = "code_mode_only".
* "shell" leaves tool_mode unset so Codex declares top-level shell tools (exec_command).
*/
codexToolMode?: "code_mode_only" | "shell";
/** 추가 시각 (ISO 8601) */
addedAt?: string;
}
/**
* A generated `ocx_` data-plane key. `key` is the secret itself and never leaves
* the server except in the one-time POST /api/keys response; every other surface
* sees only the masked prefix.
*/
export interface OcxApiKeyEntry {
id: string;
name: string;
key: string;
createdAt: string;
pendingRotation?: OcxPendingApiKeyRotation;
/**
* Resolved provider names this key may reach. Absent or empty means every
* provider, which is what every existing key has, so adding the field
* changes nothing until an operator sets one.
*/
allowedProviders?: string[];
/**
* Resolved destinations this key may reach, as a bare model id or a
* `provider/model` pair. Absent or empty means every model.
*
* These name destinations, not the selectors a client sends: they are
* checked after alias, combo, fallback and compaction resolution, because
* that is the only point at which the model about to be billed is known.
*/
allowedModels?: string[];
/**
* Lets this key reach combo targets marked `metered`. Absent means no: an issued key stops
* at the last unmetered target. The environment token never qualifies. A loopback bind
* reads no key; local operator consent is instead declared on the combo.
*/
allowMeteredComboTargets?: boolean;
}
export interface OcxPendingApiKeyRotation {
id: string;
key: string;
createdAt: string;
expiresAt: string;
}
/**
* Durable per-client intent. One key today, deliberately.
*
* A top-level `codexEnabled` would force every later client to invent an
* unrelated name and its own helpers; a ten-key union recreated the coupling
* that failed two audits, because every phase then had to touch every client's
* write path. A one-key object keeps the extension point without letting this
* phase claim ownership over a client it does not implement.
*/
export interface OcxClientIntegrationsConfig {
/** Durable desired state for native Codex. MISSING MEANS ON. */
codex?: boolean;
/** Durable desired state for Grok Build. MISSING MEANS ON. */
grok?: boolean;
/** Durable desired state for Claude Desktop. MISSING MEANS ON. */
"claude-desktop"?: boolean;
}
/**
* Opt-in opencode-side request timeouts written into the generated opencode provider block
* (both the V1 `options` and V2 `settings` connection objects). Each maps to the matching
* opencode `settings` field and accepts a number of milliseconds or `false` to disable that wait.
*
* Omitted by default: opencode keeps its native header and chunk waits for every upstream reached
* through the proxy (current V2 defaults the header wait to 5 minutes and the longer chunk wait to
* 15 minutes; this repo pins no opencode release). The knob exists because the generated
* `opencodex` provider multiplexes all upstreams under one block and opencode's timeouts are
* provider-wide, so a user fronting a slow local model (whose prompt prefill behind a non-streaming
* turn can exceed the header wait before the proxy emits a byte) can raise or disable the wait
* without touching the safety net for anyone else only by setting it here.
*/
export interface OcxOpencodeClientExportConfig {
/** opencode `settings.headerTimeout`: client wait for the proxy's first response header (ms), or false to disable. */
headerTimeoutMs?: number | false;
/** opencode `settings.chunkTimeout`: wait between streamed response chunks (ms), or false to disable. */
chunkTimeoutMs?: number | false;
/** opencode `settings.timeout`: whole-request bound (ms), or false. opencode applies no default. */
timeoutMs?: number | false;
}
export interface OcxConfigRebaseProvenance {
version: 1;
deletedTopLevelKeys: string[];
}
export type SkillsCatalogRefresh = "per_session" | "per_turn";
export interface OcxSkillsConfig {
/**
* Refresh policy for the runtime skills catalog (#5569).
* `per_session` (default): snapshots incoming `<skills_instructions>` on the first turn of a trustworthy session and reuses it across turns to preserve the Anthropic prompt cache.
* `per_turn`: re-derives/passes through incoming skills instructions every turn (previous behavior).
*/
catalog_refresh?: SkillsCatalogRefresh;
}
export type OcxRuntimeRole = "standalone" | "hub" | "client";
export interface OcxHubConfig {
/** Canonical browser-reachable management origin advertised by a hub. */
managementPublicOrigin?: string;
/**
* Canonical client-reachable DATA origin of this hub — what a remote machine passes as the
* positional URL to `ocx connect`, and what `ocx hub invite` prints.
*
* Separate from `managementPublicOrigin` because the two are genuinely different sockets on a
* real deployment: management is a loopback-only ingress published by an HTTPS frontend, while
* the data listener is bound to the hub's tailnet/LAN address and fronted on its own port
* (`https://hub.tailnet.ts.net:8443`). Deriving one from the other produced an origin that
* answered `/readyz` and nothing else.
*
* Advisory only: it is the origin the hub ADVERTISES, never a bind address. When omitted,
* `ocx hub invite` falls back to `http://<hostname>:<port>`, which is correct for a plain
* tailnet bind with no TLS frontend.
*/
dataPublicOrigin?: string;
/**
* Optional management-only listener for a local HTTPS frontend such as Tailscale Serve.
* The hostname is deliberately not configurable: when enabled the socket is always bound
* to 127.0.0.1, and only GUI, session-bootstrap, and management API routes are admitted.
*/
managementIngress?:
| { enabled: false }
| { enabled: true; port: number };
}
export interface OcxRemoteGuiConfig {
/** Exact Tailscale login identities permitted to receive an automatic remote GUI session. */
allowedTailscaleUsers?: string[];
/**
* Retired. Once permitted a one-time pairing exchange over non-loopback plaintext HTTP.
*
* Still parsed so an existing config file keeps loading, but it grants nothing: a pairing
* grant now crosses loopback or authenticated HTTPS only. A persisted `true` is reported
* once and otherwise ignored. Kept in the type rather than deleted because the schema is
* strict — dropping the key outright would make an older config fail to load entirely,
* which is a worse outcome than ignoring one retired field.
*
* @deprecated has no effect; remove it from your config.
*/
allowInsecureHttp?: boolean;
}
export type OcxConnectedClientId = "codex" | "claude" | "claude-desktop" | "grok" | import("../clients/client-ids").ExportClientId;
/**
* Redaction policy for management and CLI projections (#3859).
*
* `privacy` rather than `dashboard`: `ocx status` and `ocx account` are not the dashboard, and
* they read the same projections.
*/
export interface OcxPrivacyConfig {
/**
* Mask stored account emails before they leave the proxy. Omitted or `true` is the historical
* behaviour and the default.
*
* Setting this to `false` is a real disclosure decision, not a display preference. Management
* is not always loopback — under `remoteGui` the unmasked address reaches every management
* principal that can reach the hub, not only someone sitting at the machine. The default
* therefore stays masked, and turning it off is an explicit opt-in by the operator who owns
* those accounts.
*/
maskEmails?: boolean;
}
export interface OcxClientConnectionConfig {
serverUrl: string;
managementUrl: string;
managementTransport: "direct" | "relay";
transport?: "hub" | "link";
link?: OcxLinkTransportConfig;
selectedClients: OcxConnectedClientId[];
tokenEnv: "OPENCODEX_API_AUTH_TOKEN";
apiKeyId: string;
tokenFingerprint: string;
protocolVersion: 1;
connectedAt: string;
/**
* sha256/base64url of the catalog bytes this connection wrote, used to tell "still ours"
* from "edited or replaced" before removing the file on disconnect.
*
* Our own hash rather than the hub's ETag: /v1/catalog emits no validator, and this was
* always an ownership check on local bytes rather than a cache concern.
*/
catalogFingerprint?: string;
/**
* The catalog that was on disk before connect overwrote it, base64-encoded, or the
* empty string when there was none.
*
* Durable because disconnect runs in a different process than connect: an in-memory
* snapshot only covers a connect that fails and rolls back on the spot. Without this,
* disconnect deletes the remote catalog and reports a restored native state while the
* user's own catalog is simply gone.
*/
priorCatalog?: string;
catalogSyncedAt?: string;
pendingOperation?: {
kind: "rotate";
rotationId: string;
newKeyIssuedAt: string;
oldKeyBackupPath: string;
};
}
export interface OcxConfig extends OcxLinkHomeConfig, CodexAccountLoginConfig {
/** Experimental macOS app-server stdout shim; absent or false disables it. */
chatgptDesktop?: { appServerShim?: boolean };
port: number;
/** Runtime topology role. Absence preserves the historical standalone behavior. */
runtimeRole?: OcxRuntimeRole;
/** Hub-only public management metadata. Presence is inert outside the hub role. */
hub?: OcxHubConfig;
/** Opt-in remote dashboard issuance policy. Presence is inert outside the hub role. */
remoteGui?: OcxRemoteGuiConfig;
/** Remote-hub client state. The admission secret is stored only in service-api-token. */
client?: OcxClientConnectionConfig;
/** Operator-facing redaction policy for management and CLI projections. */
privacy?: OcxPrivacyConfig;
/** Runtime skills catalog session snapshotting settings (#5569). */
skills?: OcxSkillsConfig;
/** Opt-in process-local aggregate request metrics on the authenticated management plane. */
metricsExport?: { enabled?: boolean };
telemetry?: OcxTelemetryConfig;
/**
* Opt-in recovery of a managed service proxy that stays alive but stops answering /healthz:
* a separate sentinel process terminates it so its supervisor restarts it (#6671).
*/
serviceHealthRecovery?: { enabled?: boolean };
/** Opt in to one identical-turn retry when a Responses completion has no text or tool call. */
emptyCompletionRetry?: boolean;
/** Suppress allowlisted client-facing Codex transport hints; provider enforcement is unchanged. */
dropCodexSafetyBuffering?: boolean;
/** Opt in to completing truncated plain-text translated Responses turns; default off. */
completeOnMaxOutputTokens?: boolean;
/**
* Whether a login may open a browser on the machine running the proxy.
*
* Absent and `true` both mean "open", which is what every existing install
* already does. Only an explicit `false` declines — for an operator who wants
* to paste the authorization URL into a different browser profile, or who is
* driving the dashboard from a different machine than the proxy.
*
* Deliberately a boolean and not an "auto" mode: inferring headlessness from
* SSH_CONNECTION or a missing DISPLAY breaks a working login silently when
* the guess is wrong.
*/
oauthOpenBrowser?: boolean;
/** Display Codex credits on account cards; display only, default off. */
showCodexCredits?: boolean;
/**
* @deprecated Compatibility-only limit for bounded legacy usage readers.
* `GET /api/usage` always aggregates the complete ledger.
*/
managementUsageMaxReadBytes?: number;
providers: Record<string, OcxProviderConfig>;
defaultProvider: string;
/** Persisted state for newly discovered provider models (#2464). Absent keeps legacy "on" behavior. */
modelDiscovery?: {
/** `admit` appends arrivals to custom provider selections (#8236); default `on`. */
newModelPolicy?: "on" | "off" | "admit";
knownModels?: Record<string, {
ids: string[];
removed: string[];
updatedAt: string;
/** Consecutive successful discoveries in which an active id was absent. */
missing?: Record<string, number>;
}>;
recentArrivals?: Record<string, Array<{
id: string;
at: string;
/** Appended to the provider's custom selection by the `admit` policy. */
admitted?: boolean;
/** Whether the `off` policy disabled it; absent on rows recorded before #8236. */
disabledByPolicy?: boolean;
}>>;
};
/** Enable the shipped model alias patterns for providers without an override. */
defaultModelAliases?: boolean;
/**
* When `true`, the raw OpenAI-compatible `/v1/models` list publishes a safe alias (e.g.
* `SEK-glm-4.7-flash`) as the row `id` instead of `provider/nativeId`
* (e.g. `Seek/glm-4.7-flash`). The original `provider/nativeId` moves to a
* new `native_id` field so clients that need it can still read it.
*
* **Default: `false`** — the historical `provider/nativeId` form remains the
* published `id`, and the alias is in the informational `alias_of` field.
*
* Codex (`client_version`) and Anthropic-specific discovery retain their own
* identities and are unchanged. Ambiguous or shadowed short aliases retain the
* qualified ID, as do aliases with unparseable synthetic Fast siblings.
* Existing requests using `provider/nativeId` continue to work unchanged.
*/
preferModelAliasIds?: boolean;
/**
* Opt-in Cursor Private Inference compatibility rows. When true, `/v1/models`
* adds `<base-id>--<effort>` selectors for reasoning-capable model ids absent
* from Cursor's built-in effort table. Omitted/false preserves discovery output.
*/
cursorEffortRows?: boolean;
/**
* Default-on synthetic Fast selectors. The raw OpenAI-style `/v1/models` list and
* Claude Code discovery add a `<base-id>--fast` row for every model whose resolved Fast
* policy is eligible, and selecting one routes the base model with the canonical
* `priority` service tier. Client config exports include the same selectors. Set false
* to disable them; omission enables them.
*/
fastRows?: boolean;
/**
* Opt-in Ultra Fast service tier, default off.
*
* On native GPT-6 Astra and GPT-6.1 Sol rows (bare and account-bound), the flag adds the
* Ultrafast speed choice OpenAI documents for those two models, so the Codex picker offers
* it even though `model_catalog_json` replaces ChatGPT's live, plan-aware model list
* (`src/codex/catalog/native-ultrafast.ts`). On routed rows it still never invents a tier:
* it keeps an `ultrafast` the operator configured from being stripped on regeneration
* (PR #2994 was closed for adding one the wire could not honor). Turning it off withdraws
* the generated native tier on the next catalog write.
*/
ultraFastTier?: boolean;
/**
* Stop new identity-matched main-account requests at configured window usage (#5694).
*
* On by default: an absent key and `true` both enable it, and only an explicit `false`
* opts out. While it blocks, the main account's Luna Reserve cannot activate, so an operator
* who wants Reserve has to turn the setting off rather than delete the key.
*/
codexMainAccountHardLock?: boolean;
/** Per-window percentages: short defaults to 90, long to 98; integers 80..100, short <= long. */
codexMainAccountHardLockThresholds?: { short?: number; long?: number };
/**
* Extended hard-lock settings: while the lock blocks and no Codex account can serve a
* qualifying request, the request reroutes to `model` (with `reasoningEffort` when set)
* instead of failing. The lock itself stays on and releases on its own as before; an
* absent section or model means the refusal behavior is unchanged.
*/
codexMainAccountHardLockFallback?: { enabled?: boolean; model?: string; reasoningEffort?: string };
/**
* Who refreshes the native main ChatGPT login in CODEX_HOME (#2999). "codex" asks the Codex
* binary through app-server `getAuthStatus` and never writes auth.json; "opencodex" keeps the
* guarded writer. Absent means "codex" when a Codex binary at or above the supported version
* is found, otherwise "opencodex". "codex" also falls back when no such binary exists.
*/
nativeMainRefresh?: "codex" | "opencodex";
/** Use included quota to 100% for these accounts; preserves thresholds and credit-spending policy. */
codexUseRemainingQuotaAccountIds?: string[];
/** Explicit top-level deletion intent used by stale whole-config rebases. */
configRebaseProvenance?: OcxConfigRebaseProvenance | Record<string, unknown>;
/** OpenAI provider-contract migration marker (v2 = single `openai` provider with account mode). */
openaiProviderTierVersion?: 1 | 2;
/** One-time migration marker for Antigravity's static-catalog defaults. */
googleAntigravityStaticCatalogVersion?: 1 | 2;
/** Claude Code inbound + launcher settings. */
claudeCode?: OcxClaudeCodeConfig;
/** Opt-in weekly reserve for explicitly marked caller-forward Claude subscription turns. */
subscriptionReserve?: {
enabled?: boolean;
soft?: number;
hard?: number;
targets?: string[];
};
/**
* Which public inference APIs this proxy serves. Read only through
* `resolveApiSurfaceSettings` in `src/protocols/settings.ts`, which fails closed on a
* malformed value and inherits `claudeCode.enabled` while no explicit value exists.
*/
apiSurfaces?: OcxApiSurfacesConfig;
/** Protocol delivery policy and rollout switches; see `resolveProtocolSettings`. */
protocols?: OcxProtocolsConfig;
/**
* Per-client durable intent. This phase owns only `codex`; later phases extend
* one key at a time rather than widening a shared union.
*/
clientIntegrations?: OcxClientIntegrationsConfig;
/**
* Opt-in opencode-side request timeouts emitted into the generated opencode provider block.
* Omitted by default (opencode keeps its native header/chunk waits). Set `headerTimeoutMs` to
* extend or disable the header wait that otherwise cuts a slow local model's prompt prefill.
* See {@link OcxOpencodeClientExportConfig}.
*/
opencodeClientExport?: OcxOpencodeClientExportConfig;
/** Opt-in dialect for the managed Pi-based omo block; omitted keeps `openai-completions` (#7431). */
omoClientExport?: { api?: "openai-completions" | "openai-responses" };
/** Aside account-backed profile synchronization; individual overrides survive bulk refresh. */
asideProfileSync?: {
allProfiles?: boolean;
profiles?: Record<string, boolean>;
/** Stable provenance for the one legacy root ownership record, or no root owner. */
legacyProfileId?: number | null;
};
/**
* Up to 5 Codex-facing catalog ids to feature first. Values may be bare catalog ids,
* exact account-qualified "<selector>/<native-openai-model>" ids, or routed
* "<provider>/<model>" ids. With account selectors, one bare native choice can expand
* into a selector-qualified group; Codex still advertises only the first 5 visible rows.
*/
subagentModels?: string[];
/** One-time featured-roster upgrade marker; later user ordering is preserved. */
subagentModelsVersion?: number;
/**
* Display-only order for the Codex picker, independent of subagentModels.
* Routed-only lists order non-featured routed rows; featured and native rows keep
* their normal positions. Including a bare native id opts into ordering the complete
* picker: listed ids appear first in array order, followed by unlisted rows in their
* natural priority order. Exact catalog ids take precedence over equivalent raw/encoded
* routed ids; empty entries are ignored. The separate natural priority used by
* OpenCodex guidance is preserved. Native Codex's advertised five follow display
* priority and may change; exact-name override eligibility is not restricted by that list.
* Unset or empty leaves catalog priorities unchanged.
*/
modelPickerOrder?: string[];
/** Saved preset provenance; snapshots are not recomputed during catalog discovery. */
modelPickerOrderMode?: "alphabetical" | "provider" | "most-used";
/**
* Priority-ordered fallback models for spawned sub-agents. When the requested
* model is quota-exhausted or recently failed, opencodex rewrites the child
* turn to the next available entry before routing.
*/
subagentModelFallback?: string[];
/**
* Per-primary-model fallback chains for spawned sub-agents, keyed by the
* requested primary model id (bare native or "provider/model"). Entries for
* the matching key are consulted after the requested model and before the
* global `subagentModelFallback` list.
*
* This is the supported home for per-role fallback metadata: storing it as
* `model_fallback` inside `$CODEX_HOME/agents/*.toml` makes Codex >= 0.146
* reject the whole role file as an unknown field (#1190).
*/
subagentModelFallbackByModel?: Record<string, string[]>;
/**
* Capability tier of named models for Codex role auto-assign, overriding its price-rank
* classification. Models no list names and no price covers are never proposed.
*/
codexRoleTiers?: { fast?: string[]; standard?: string[]; frontier?: string[] };
/**
* Measured-capability source for Codex role auto-assign. With an Artificial Analysis API key
* (a literal, ${ENV} or keychain reference) its indexes inform measured tiers.
*/
codexRoleCapability?: { artificialAnalysis?: { apiKey?: string } };
/**
* TTL (ms) for cached sub-agent model availability probes. Default 60_000.
*/
subagentModelFallbackPollMs?: number;
injectionModel?: string;
/**
* Opt in to synchronizing the selected injection model into Codex's native
* sub-agent defaults. Only meaningful while `injectionModel` is set.
*/
syncCodexSubagentDefaults?: boolean;
/**
* Optional reasoning effort reported as advisory metadata in v2 sub-agent guidance.
* It does not prescribe spawn overrides. Only meaningful while `injectionModel` is set; validated against
* the Codex ladder (src/reasoning-effort.ts CODEX_REASONING_LEVELS) at the API boundary.
*/
injectionEffort?: string;
/**
* Explicit sideband websocket base for realtime/live joins, mirroring upstream's
* `experimental_realtime_ws_base_url`. The value is a ROOT (or a recognized
* `/realtime`, `/realtime/calls/<id>`, `/live/<id>` endpoint form, which is
* stripped back to the root); `/v1` is appended during normalization. Intended
* for local development against a fake realtime server — plaintext `http`/`ws`
* is accepted only for loopback hosts, and URL userinfo is rejected; both
* failures close to the canonical `https://api.openai.com/v1`. Configured by
* editing this file; there is deliberately no management-API or GUI surface.
*/
experimentalRealtimeWsBaseUrl?: string;
/**
* Model ids the user has EXCLUDED from the Grok Build managed block. Absent or empty
* means "everything visible", which is the historical behaviour — so an existing
* config keeps the fence it already had.
*
* Exclusion list rather than an inclusion list on purpose: a newly added provider
* model should appear in Grok by default, exactly as it does today. An inclusion list
* would silently hide every future model behind a switch nobody knew to flip.
*/
grokExcludedModels?: string[];
/**
* Provider names the dashboard's suggested combos leave out (Combos page). View-only:
* existing combos that name one keep routing to it.
*/
comboSuggestionExcludedProviders?: string[];
/**
* When true, OpenAI-routed requests include `service_tier: "priority"` (fast inference).
* When false, service_tier is stripped so requests use default speed.
* Undefined = passthrough (don't modify what the client sends).
*/
fastMode?: boolean;
/**
* Windows/macOS SSE passthrough stream shape (#314 mitigation).
* On Windows, "auto" (default) selects eager relay only on a runtime proven
* to carry the Bun#32111 fix. On macOS, "auto" always stays on legacy tee and
* eager relay is explicit-only. "eager-relay" opts into the new relay (and
* accepts #32111 crash risk on Bun 1.3.14); "legacy-tee" pins the tee path.
* Persisted in config.json so service users can select the stream shape.
* See src/lib/bun-stream-caps.ts.
*/
streamMode?: "auto" | "legacy-tee" | "eager-relay";
/**
* Custom override for the injected v2 multi-agent guidance body (the text inside
* the <opencodex_subagent_guidance> tags). After guidance is enabled and the v2 surface and
* catalog-state gates pass, a configured injectionModel is sufficient to render it;
* otherwise an eligible roster or fallback is required. Placeholders: `{{model}}` -> the
* effective preferred model for the request (a bare native model is account-qualified
* only when the request targets an explicit account selector; unresolved or ambiguous
* bare values become "", while unresolved explicit routed or account-qualified values
* remain unchanged),
* `{{effort}}` -> injectionEffort, `{{roster}}` -> the resolved sub-agent roster
* block ("" when nothing resolves), `{{fallback}}` -> the configured subagent
* model fallback guidance block ("" when unset).
*/
injectionPrompt?: string;
/**
* Proxy-authored multi-agent developer guidance. Undefined/true = enabled for
* backward compatibility; false suppresses both v1 and v2 guidance injection.
*/
multiAgentGuidanceEnabled?: boolean;
/**
* Global hard ceiling for the reasoning effort of EVERY proxied turn (main agent AND
* sub-agents). Ladder value "low".."max"; incoming efforts ranking above it are rewritten
* in both request shapes before any adapter or clamp. Unset = no cap. codex-rs converts
* ultra -> max client-side, so e.g. a "high" cap sends ultra/max-tier turns as high.
*/
effortCap?: string;
/**
* Hard ceiling applied ONLY to sub-agent turns — requests carrying codex-rs's spawned-child
* markers (`x-openai-subagent` header, or `subagent_kind` inside `x-codex-turn-metadata`).
* Lets the main agent keep its tier while delegated children are capped. When both caps are
* set, the lower one wins for sub-agents. See src/server/effort-policy.ts.
*/
subagentEffortCap?: string;
/** Global model effort overrides, after provider model/wide pins; none means omission. */
modelPinnedEfforts?: Record<string, string>;
compactionRouting?: {
model: string;
/** Incoming model allowlist: exact selectors or provider/*; omitted means all models. */
sourceModels?: string[];
reasoningEffort?: string;
/** Compaction triggers this override covers; omission means `["manual"]`. */
triggers?: ("manual" | "auto")[];
};
/** Opt-in failure-only recovery; never replaces the initial compaction model. */
compactionRecovery?: { enabled: boolean; model: string; allowDevinInvalidArgument?: boolean };
/** Explicit opt-in (enabled === true), default off, for routed v1/v2 readable reasoning retention.
* Defaults: 20% of the compacting model's context window and 100,000 tokens (the smaller limit).
* Unknown windows use maxTokens alone; overflow is archived locally with a path notice.
* Native and opaque compaction output keep their existing protocols. */
reasoningRetention?: { enabled?: boolean; maxContextPercent?: number; maxTokens?: number };
nativeReasoningRetention?: { modelSwitch?: boolean; accountSwitch?: boolean }; // canonical ChatGPT reasoning replay allowances; both default off
/** Per-root fan-out ceilings (src/lib/workflow-budget.ts); omitted fields keep 8 / 256 / 64. */
workflowBudget?: { maxConcurrentChildren?: number; maxPhysicalSends?: number; maxDistinctChildren?: number };
routedCatalogDefaults?: import("./routed-catalog-defaults").OcxRoutedCatalogDefaultsConfig; // #6872; provider/model declarations win
/** Explicit opt-in; resumes Observe only using an existing trusted certificate and endpoints. */
desktopCompatibility?: { startOnProxyStart: boolean };
/**
* Destination model for Codex's own memory pipeline, per phase
* (src/server/responses/memory-models.ts).
*
* Codex runs Phase 1 ("extract") once per finished thread to summarize that thread's rollout,
* and Phase 2 ("consolidation") once as an agent run that merges the summaries into the files
* under `$CODEX_HOME/memories`. Without an entry here each phase keeps its existing route,
* including any configured shadow-call interception.
*
* A phase is recognized from Codex's turn metadata, never inferred from the model id, the timing
* or the token counts: Phase 1 shares `gpt-5.6-luna` with the app's title/commit helper calls,
* and `shadowCallIntercept` is the setting for those. A configured phase wins over that
* intercept, because the memory decision is the more specific one.
*
* `model` is required for a configured phase; omitting the phase leaves its route in place.
* `reasoningEffort` overrides the effort Codex hard-codes for that phase.
*/
memoryModels?: {
extract?: { model: string; reasoningEffort?: string };
consolidation?: { model: string; reasoningEffort?: string };
};
/**
* Models hidden from Codex discovery without blocking direct proxy calls. Routed provider ids
* are excluded from the catalog + /v1/models entirely. Account-qualified native ids hide only
* their generated selector row and are omitted from raw /v1/models. BARE native GPT ids hide
* the bare row plus every generated selector row and omit that model family from raw discovery.
*/
disabledModels?: string[];
/** Omit explicitly disabled native catalog rows, retaining their validated inheritance template. Default: false; direct routing is unchanged. */
omitDisabledNativeModels?: boolean;
/** 사용자가 대시보드에서 직접 추가한 커스텀 모델 목록. */
customModels?: OcxCustomModel[];
/**
* Internal, versioned evidence for reconciling custom-model deletions with
* pre-marker Codex catalog rows. Consumers must parse this defensively so a
* future state written by a newer binary survives older whole-config saves.
*/
customModelCatalogMigration?: unknown;
/**
* Shadow call intercept: redirect Codex's hard-coded helper calls (title generation,
* commit messages, skill orchestration) to a user-chosen model. Default intercepted
* source models: gpt-6-luna (Codex 0.154.0+) and gpt-5.6-luna (0.145.0-0.153.x).
* Clients through 0.144.x emitted gpt-5.4-mini instead; that model is retired upstream,
* but it stays available as an opt-in `sourceModels` prefix so an old client's helper
* calls can still be intercepted.
* Opt-in; disabled by default. Matching requests preserve their configured reasoning effort.
* All requests for configured shadow source models are intercepted regardless of request kind,
* except when the replacement intersects the same provider+model source set, and except
* spawned sub-agent turns (x-openai-subagent: collab_spawn / subagent_kind thread_spawn),
* which keep the model they were spawned with.
*/
shadowCallIntercept?: {
/** When true, requests for known shadow/helper source models are rewritten to the configured model. */
enabled?: boolean;
/** Replacement model id (e.g. "gpt-5.5"). */
model?: string;
/** Optional override of intercepted source-model prefixes (default: gpt-6-luna, gpt-5.6-luna). */
sourceModels?: string[];
};
/**
* Global auto-review (approval reviewer) selector for every catalog row, written by the
* Models settings panel. During catalog sync OpenCodex stamps it as
* `auto_review_model_override` on rows that carry no provider-scoped stamp, so an enabled block
* wins over Codex's own root `auto_review_model`; disabling it restores that fallback.
* `autoReviewModel` keeps its precedence on its own provider's rows.
*/
autoReviewOverride?: {
/** When true, the configured model replaces the reviewer on every unowned row. */
enabled?: boolean;
/** Public catalog selector in `provider/model` form; blank or absent clears the override. */
model?: string;
};
/**
* Optional map of blocked model IDs to their replacement model IDs.
* When configured, incoming requests targeting a blocked model (including
* account-namespaced and concrete routes) are redirected to the replacement
* model at the shared routing layer with routeReason "blocked-model-redirect".
* Unset or omitted by default.
*/
blockedModelRedirects?: Record<string, string>;
/** Multi-agent surface override; mode selection and consent follow MultiAgentMode. */
multiAgentMode?: MultiAgentMode;
/**
* Which revision of the sub-agent surface advisory this install has answered.
* Absent means it has answered none. Written by the dashboard, never by a mode change.
*/
multiAgentSurfaceAdvisoryVersion?: number;
/**
* When `multiAgentMode` is `"v2"`, keep ChatGPT-native catalog rows on v1.
* Routed parents get v2 tools; Sol/Terra can still spawn Grok/Claude (issue #92).
* Stored but inactive under `"v2-plaintext"`, which pins ChatGPT-native rows on v2.
*/
keepNativeChatGptOnV1?: boolean;
/** Experimental plaintext delivery for native v2 collaboration messages; disabled unless true. */
plaintextV2AgentMessages?: boolean;
/** Experimental, default-off ChatGPT recovery for encrypted V2 routed tasks. */
agentTaskRecovery?: {
enabled?: boolean;
/** ChatGPT model used by the recovery request. Default: gpt-5.6-sol. */
model?: string;
/** Recovery request timeout in milliseconds. Default: 45000. */
timeoutMs?: number;
/** Maximum in-memory ciphertext-to-assignment entries. Default: 200. */
cacheEntries?: number;
/**
* Extra recovery sends when ChatGPT rejects with a transient 5xx or the transport
* fails, sharing the same credential, deadline, and cache flight (#3661).
* Default: 0 (single attempt); maximum: 2.
*/
retries?: number;
};
/**
* Quota-reset detection and notification. Absent means off: no detection, no timer, no sink.
*
* Not in `getDefaultConfig()` on purpose — that function carries no optional-feature keys,
* so absence is the only default state this feature has.
*/
quotaResetNotify?: OcxQuotaResetNotifyConfig;
/**
* Periodic provider model-catalog refresh (issue #3630). Absent means on at the hourly
* default; `enabled: false` or `intervalMinutes: 0` turns it off.
*
* It started opt-in, and that is why GPT-6.1 Sol never reached an install without a
* release: nobody had turned the section on, so the authenticated Codex roster that
* announces a new model was never re-read. One hourly pass costs a live /models call per
* enabled provider, which is the price of new models appearing on their own. Not in
* `getDefaultConfig()` — absence is the default state.
*/
catalogAutoRefresh?: OcxCatalogAutoRefreshConfig;
/** Active provider context limits; native long windows remain within their supported ceilings. */
providerContextCaps?: Record<string, number>;
/** Last selected provider caps; retained while a cap is switched off. Not an active limit. */
providerContextCapValues?: Record<string, number>;
/** Global Codex-visible context cap value (tokens). Falls back to DEFAULT_PROVIDER_CONTEXT_CAP. */
contextCapValue?: number;
/** Bind hostname. Default "127.0.0.1" (loopback only). Set "0.0.0.0" to expose on all interfaces. */
hostname?: string;
/**
* Optional second listener bound to 127.0.0.1 that admits data-plane requests without a
* credential (issue #1102).
*
* Why a separate listener rather than an exemption on the main one: when `hostname` is a
* wildcard, every caller needs `x-opencodex-api-key`, but a `codex app-server` spawned
* directly from the resolved entrypoint never goes through the generated shim and so never
* inherits the token. Exempting "loopback-looking peers" on the public listener would be
* unsound — `requestIP()` only proves the last transport hop, and Docker Desktop port
* forwarding, host-network containers, WSL mirrored networking and tunnels all terminate
* remote connections locally. Binding a second socket to 127.0.0.1 makes the kernel refuse
* remote connections outright, so there is no address to judge.
*
* The public listener's admission policy is unchanged. This adds an explicit local trust
* surface: every process on the machine can reach it, spend account quota, and consume paid
* provider credentials. Off by default; not for multi-tenant hosts.
*
* Two enabled forms:
*
* - `{ enabled: true, port: N }` — a distinct port (the #1102 form). N must differ from the
* proxy port.
* - `{ enabled: true }` — the "companion" form: bind `127.0.0.1:<proxy port>`. Legal only
* when `hostname` is a specific non-loopback, non-wildcard address (a tailnet or LAN IP),
* because otherwise the public socket already owns that loopback address. This is the
* one-port hub shape: remote clients dial `hostname:port`, local processes dial
* `127.0.0.1:port`, and every integration that hardcodes `http://127.0.0.1:<proxy port>`
* keeps working on a hub whose public bind they cannot reach (#4236).
*
* Neither form is OS-assigned. A changing port would break already-running app-servers
* holding the previous `base_url` — the exact symptom #1102 reported and we disproved for
* token rotation.
*/
unauthenticatedLoopbackListener?:
| { enabled: false }
| { enabled: true; port?: number };
/**
* Outbound proxy URL for provider requests. HTTP(S) example: "http://user:pass@proxy:8080"
* or "${HTTPS_PROXY}". SOCKS5 example: "socks5://127.0.0.1:10808" (`ocx start --socks5`).
* HTTP URLs are mirrored into HTTP_PROXY/HTTPS_PROXY when unset. SOCKS5 URLs are mirrored
* into ALL_PROXY, clear inherited HTTP(S)_PROXY, and use OpenCodex's SOCKS5 transport.
* Loopback stays in NO_PROXY.
* The literal `"auto"` reads Windows WinINET or macOS static HTTP/HTTPS proxy settings
* once at startup. Inherited scheme proxies win; on macOS, inherited ALL_PROXY also skips
* discovery. A macOS `*.<domain>` exception maps to `.<domain>` (including the apex),
* exact link-local CIDRs are omitted with a warning, and other unsafe exceptions
* refuse discovery without environment writes.
* PAC/WPAD, SOCKS-only settings, and live changes are not followed.
*/
proxy?: string;
/**
* Hosts that bypass `proxy` for OpenCodex's own outbound provider calls, merged into
* NO_PROXY at startup. Accepts a comma-separated string (NO_PROXY syntax) or an array.
* Loopback is always excluded regardless of this setting, and an inherited NO_PROXY is
* preserved — this ADDS entries, it never replaces the environment.
*/
noProxy?: string | string[];
/**
* Upstream stall timeout (seconds). After this many seconds of no upstream data, emits
* response.incomplete. Default 300. Min 1.
*/
stallTimeoutSec?: number;
/**
* Connect timeout (ms) for upstream fetch — the deadline from dispatch until the upstream
* returns its first response header (covers DNS, TCP, TLS, and the header wait; NOT the body
* stream that follows, which is governed by stallTimeoutSec). Set 0 (or any non-positive value)
* to disable it entirely. When unset, a public upstream defaults to 200000, while a local
* upstream (loopback / private / `.local` / `.lan`) disables it — a local model's prompt prefill
* can hold the connection silent for minutes on a large prompt before the first header arrives.
*/
connectTimeoutMs?: number;
/** Opt-in (#7958): seconds (max 300) to wait for DNS after a pre-connect failure, then resend once. Unset or 0 is off. */ offlineResendWaitSec?: number;
/** Graceful shutdown drain timeout (ms). Active turns are aborted after this deadline. Default 5000. */
shutdownTimeoutMs?: number;
/** Advertise supports_websockets so Codex opens the WS endpoint. Default false; set true to opt in. */ websockets?: boolean;
/** Accept the Responses WebSocket from linked Children over the Remote Link. Default false; needs websockets too. */ linkResponsesWebsocket?: boolean;
/** On a Remote Link Child: true keeps Codex on HTTP over the link even when the Home offers the link WebSocket. Default: follow the Home. */ linkResponsesWebsocketOptOut?: boolean;
/** Experimental single-lane native OpenAI WebSocket steering; default off. */
codexNativeSteering?: boolean;
/** Experimental, default-off saved function-result injection on native multi-agent WebSockets. */
codexNativeInjection?: boolean;
/**
* Opt-in auto-cleanup policy for archived Codex sessions (issue #42 Phase 3).
* Default OFF (`enabled` false / unset). Never enabled implicitly.
* See `src/storage/policy.ts`.
*/
storageCleanupPolicy?: StorageCleanupPolicy;
/**
* Opt-in ceiling in bytes for `usage.jsonl`. Absent means the ledger grows without limit,
* which stays the default: history an operator did not ask to delete is not deleted. Values
* below the documented floor are treated as unset rather than enforced, because a ceiling
* smaller than a row cannot be met without emptying the file.
*/
usageLedgerMaxBytes?: number;
/** Generated API keys for external access to the proxy's /v1/responses endpoint. */
apiKeys?: OcxApiKeyEntry[];
/** Auto-start/sync the proxy from the Codex shim before launching Codex. Default true. */
codexAutoStart?: boolean;
/** Restore an installed shim after a stable external Codex update replaces it. Default true. */
codexShimAutoRestore?: boolean;
/**
* Opt-in authless Codex Desktop routing (#1107). On a loopback bind, inject the dedicated
* `[model_providers.opencodex]` table with `requires_openai_auth = false` instead of the root
* `openai_base_url` override, so Desktop opens without a ChatGPT login. Default off; ignored on
* non-loopback binds, whose admission token contract is unchanged.
*/
codexDesktopAuthless?: boolean;
/** Luna Reserve (#4961): seeded once from `codexDesktopAuthless`, then independent (absent = off). Grants no entitlement. */
codexReserveEnabled?: boolean;
/** Internal marker recording that one-time seed. */
codexReserveMigration?: number;
/**
* Opt into Codex-owned client compaction while keeping OpenCodex routing. On an authenticated
* loopback bind, inject the dedicated `opencodex` model provider instead of overriding the
* built-in `openai` provider, so Codex does not select native remote compaction. Default off.
*/
codexClientCompaction?: boolean;
/**
* Label Codex shows for the injected `opencodex` provider. Defaults to `OpenCodex Proxy`.
*
* Presentation only. Routing is keyed on the provider id `opencodex` — the root
* `model_provider = "opencodex"` line and the `[model_providers.opencodex]` header — and this
* setting never touches either, so renaming the label cannot reroute or orphan a thread whose
* row already names that id.
*
* There is no way to emit an empty label: Codex rejects a provider with no name, so a blank,
* over-long, or control-character value falls back to the default rather than writing a config
* Codex would refuse to load. "Suppressing" the OpenCodex branding therefore means choosing a
* neutral label, not removing the field.
*/
codexProviderDisplayName?: string;
/**
* Compatibility mode: temporarily rewrite Codex resume-history metadata while the proxy is active
* so Codex App can show old OpenAI chats and opencodex-created exec chats under its default
* interactive-source/provider filters. Default true; originals are backed up and restored by
* `ocx stop` / `ocx restore`. Set false to opt out of history remapping.
*/
syncResumeHistory?: boolean;
/** Freshness window (ms) for the per-provider live `/models` cache. Defaults to 5 min. */
modelCacheTtlMs?: number;
/** Evictable retained app-state budget in MiB. Default 256; valid 64..4096. */
appOwnedMemoryBudgetMb?: number;
/**
* Anthropic prompt-cache retention: "short" = 5-min ephemeral, "long" = 1-hour extended,
* "none" = disabled. Unset = "long" on first-party api.anthropic.com, "short" on
* Anthropic-compatible endpoints (adapters/anthropic/cache-retention.ts).
*/
cacheRetention?: "none" | "short" | "long";
/** Web-search sidecar: route web_search for non-OpenAI models through a gpt-mini via ChatGPT passthrough. */
webSearchSidecar?: OcxWebSearchSidecarConfig;
/**
* Advisor sidecar: an OpenCodex-owned expert consultation runtime. The proxy injects a synthetic
* `advisor` tool into routed worker turns, executes the configured expert model itself (loopback
* through the normal routing authority, so the advisor may be ANY routable provider/model), and
* reinjects the advice so the original worker continues. `policy: "preflight"` additionally
* attempts one automatic consultation per task without worker cooperation, once the task has
* produced orientation evidence. Task context is sent only after
* `contextSharingConsent` is the current version; `enabled` does not grant that consent.
*/
advisor?: OcxAdvisorConfig;
/** Vision sidecar: describe images via a gpt vision model so text-only models can "see" them. */
visionSidecar?: OcxVisionSidecarConfig;
/** /v1/images relay for codex's built-in image_gen tool. */
images?: OcxImagesConfig;
/** /v1/alpha/search relay for codex's built-in web search client. */
search?: OcxSearchConfig;
/** Codex multi-account pool. */
codexAccounts?: CodexAccount[];
/** Account ids administratively excluded from future pool selection until resumed. */
pausedCodexAccountIds?: string[];
/** Internal policy epochs; null marks malformed disk input and suppresses automatic pause. */
accountAutoPausePolicyRevisions?: Record<string, string> | null;
codexAccountPauseState?: Record<string, { revision: string; details?: import("./account-auto-pause").AccountPauseDetails }>;
/**
* Account ids, `__main__` included, allowed to keep serving from ChatGPT credits once one of
* their usage windows is full. Every other account is skipped by selection at 100% until its
* window resets, so spending credits is opt-in.
*/
creditCodexAccountIds?: string[];
/**
* Codex pool selection policy. Absent means no policy, so an existing install rotates exactly
* as before.
*
* Not in `getDefaultConfig()` on purpose — that function carries no optional-feature keys, so
* absence is the only default state this policy has.
*/
codexPool?: OcxCodexPoolConfig;
/**
* Durable token ceilings for the spend-reservation ledger (#4546). Absent means the
* historical behaviour exactly: token spend is still accounted and journalled, and nothing
* is refused on it.
*
* Not in `getDefaultConfig()` on purpose, and deliberately shipped with no default figure.
* The ledger is on by default, so a default ceiling would start refusing real traffic on
* upgrade against a number nobody chose.
*/
spend?: OcxSpendConfig;
/** Historical salted pool aliases; h(pool,P) cannot map to Q != P for any configured provider P. */
spendPoolAliases?: Record<string, string>;
/** Opt-in per-account activation of newly reset Codex quota windows. */
codexQuotaAutoRefresh?: Record<string, {
fiveHour?: boolean;
weekly?: boolean;
/** Upstream reset timestamps already activated, retained across restarts. */
lastFiveHourResetAt?: number;
lastWeeklyResetAt?: number;
/** Observed boundaries retained until activation, even if an idle upstream clock moves. */
nextFiveHourResetAt?: number;
nextWeeklyResetAt?: number;
}>;
/**
* Selection order per account id, higher used earlier; absent = 0. Keyed by id
* rather than stored on `codexAccounts` rows so the Desktop login (`__main__`),
* which has no row, can be ordered too. Range -100..100.
*/
codexAccountPriorities?: Record<string, number>;
/**
* Per-account proactive-switch threshold overrides. Missing account entry inherits
* `autoSwitchThreshold`; 0 disables usage-driven switching only for that account.
* Includes the synthetic `__main__` Desktop account. Range 0..100.
*/
codexAccountAutoSwitchThresholds?: Record<string, number>;
/**
* Account id the operator last selected by hand. Suppresses upward priority
* preemption until that account crosses the auto-switch threshold. Stores the
* id (not a flag) so a stale pin cannot outlive the selection it described.
*/
activeCodexAccountPinned?: string;
/**
* Public model-selector namespaces bound to one Codex account. Values are stored account ids;
* `"@main"` selects the Codex Desktop/main auth.json account. Account display aliases
* are intentionally separate from these selectors.
*/
codexAccountNamespaces?: Record<string, string>;
/**
* Picker visibility override for account-qualified native models. When omitted, a non-empty
* selector map remains visible for compatibility with hand-written configurations.
*/
codexAccountPickerEnabled?: boolean;
/**
* Opt-in auto-redemption of a main-account Codex reset credit shortly before it expires
* (#822). Default off. `leadTimeMinutes` (1–60, default 10) is how long before
* `expires_at` the redeem is attempted; the credit list is re-read upstream right before
* every dispatch and the request id is journaled first, so a manual redeem or a crash never
* spends a second credit. A malformed value reads as off.
*/
resetCreditAutoRedeem?: { enabled?: boolean; leadTimeMinutes?: number };
/**
* Shared account-pool kernel, opt-in and off by default.
*
* `kernel: true` is what makes a generic OAuth provider's stored `strategy` and
* `autoSwitchThreshold` actually select an account instead of merely being persisted.
* Off restores the pre-kernel path exactly, which is why the DTO keeps reporting
* `inert: true` until this is on. A malformed value reads as off.
*/
pool?: {
kernel?: boolean;
/**
* Cache-affinity ordering for bound Codex threads. **On unless set to `false`.**
*
* A bound Codex thread keeps its account until that account genuinely cannot serve,
* instead of moving the moment usage crosses `autoSwitchThreshold`. Moving a live
* conversation throws away the prompt cache warmed on that account, and a threshold
* crossing is a hint rather than evidence the account is spent.
*
* This shipped as an opt-in (#4292) and then #4546 measured what the opt-in default
* costs: a pool whose accounts all sit in the 80-99% band hands a conversation from
* account to account, re-sending the whole prefix every turn, and the install that gets
* hurt is precisely the one that never heard of this setting. `false` restores
* capacity-first routing for operators who want it.
*
* Separate from `kernel` on purpose: that one governs the generic OAuth strategy
* consumer, and one switch carrying two unrelated meanings cannot be turned on alone.
*
* Note what this does NOT govern. Unbound placement still follows
* `autoSwitchThreshold` and the configured strategy. A bound thread's destination must
* have real headroom under either setting, and a transient failure streak holds the
* binding under either setting -- neither is a cache-affinity preference.
*/
cacheAffinity?: boolean;
/**
* Operator-declared quota domains: groups of credential ids that demonstrably share
* one upstream usage limit (#4546, wp6). Members of one group count once toward
* available capacity, and a quota refusal inside a group is never answered by
* rotating to another member -- the limit is the same, so the move would pay a cold
* prefix for zero new capacity.
*
* Declared groups speak only to quota. Sharing a usage limit says nothing about
* prompt-cache compatibility, which keeps its own provider-documented domain.
* Absent or empty means no declared grouping, so an unconfigured install behaves
* exactly as before.
*
* A declaration has to mean exactly one thing, so the config rejects the spellings
* that could mean two. Credential ids are provider-scoped elsewhere (the auth store
* keys an account by provider and id), so each member is written
* `"<provider>:<credential-id>"` -- a bare `"acct-1"` names one credential per
* provider and would merge unrelated domains. The provider segment is matched
* case-insensitively through the usual aliases, so `chatgpt:` and `codex:` both mean
* OpenAI. Group ids must be unique, `credentials` must be non-empty, and a credential
* may belong to at most one group; a declaration that breaks any of those is rejected
* on write and dropped with a warning on load, never resolved by list order.
*/
credentialGroups?: Array<{
/** Operator-chosen group identifier; only equality matters. */
id: string;
/** Provider-qualified credential ids (`"<provider>:<credential-id>"`), non-empty. */
credentials: string[];
/** Free-text provenance note for the operator's own records. */
note?: string;
}>;
};
/** Active pool account id for next session. undefined = main (passthrough as-is). */
activeCodexAccountId?: string;
/** Auto-switch threshold (0-100). Default 80. 0 = disabled. */
autoSwitchThreshold?: number;
/** Opt-in: return bound quota-strategy tasks to recovered higher-priority accounts. */
codexAccountPriorityFailback?: boolean;
/** Prefer other identities, reserving the current native sign-in as pool fallback. */
codexPreserveSignedInAccount?: boolean;
/** New-session account rotation strategy for the Codex pool. Default quota (today's behaviour). */
accountPoolStrategy?: OcxAccountPoolRotationStrategy | "reset-first";
/** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
accountPoolStickyLimit?: number;
/** Consecutive non-2xx upstream responses before switching future new threads. Default 3. 0 = disabled. */
upstreamFailoverThreshold?: number;
/**
* Sliding 60s transient-failure ratio for Codex pool placement. Default on.
* Set false to steer new threads from the consecutive counter only.
*/
codexFailureWindow?: boolean;
/**
* What a manual pin does while its failure window is degraded.
* `hold` keeps using it and logs a warning. `detour-new-threads` places only new threads elsewhere.
*/
codexPinnedTransientPolicy?: "hold" | "detour-new-threads";
/** Opt-in: retain one Codex WebSocket per account and thread across turns. Default off. */
codexWsReuseAcrossTurns?: boolean;
/** Opt-in native WS upload deltas; implies cross-turn reuse. Default off. */
codexWsIncrementalUpload?: boolean;
/**
* Opt-in provider-origin circuit threshold for proven pre-connection reachability failures.
* Default 0 (disabled); range 0..20. The circuit never counts timeouts or HTTP responses.
*/
upstreamHostCircuitThreshold?: number;
/**
* Opt-in ceiling, in bytes, for a serialized native Responses **passthrough** body. When the
* built body exceeds it OpenCodex refuses locally instead of sending, naming the size and any
* embedded image payload. Translated adapter paths are not covered.
*
* Omitted or 0 = disabled, which is the default: no implicit ceiling is inferred for any
* destination. The only measured limit in this codebase is the WebSocket create-frame size,
* and the same body still succeeds over HTTP SSE, so a default here would refuse requests
* that work today — on Azure and custom Responses gateways as well, whose limits are unknown.
*/
maxUpstreamBodyBytes?: number;
/**
* Opt-in compression of native ChatGPT Responses HTTP request bodies (#7247): "gzip" or "zstd".
* Omitted, "off", or any other value = identity, the default. Applies only at the final HTTP send
* to chatgpt.com Codex responses/compact, to string bodies from 1 KiB to 16 MiB; WebSocket turns
* and every other destination are unchanged. Compression runs synchronously on the event loop.
*/
upstreamRequestCompression?: "off" | "gzip" | "zstd";
/** Optional lossy shortening of historical native Codex images/tool text. */
upstreamHistorySlim?: "off" | "codex";
/**
* Opt-in ceiling, in bytes, on a decompressed INBOUND data-plane request body (#3573).
*
* Omitted or 0 = the built-in 256 MiB default. The lever exists because a session on the
* 922k-token opt-in window serializes its full history past that default, and the request
* that crosses it is Codex's own remote-compaction request — so the session hits 413 on the
* one operation that would have shrunk it and cannot recover.
*
* Bounded on purpose. `resolveInboundBodyLimitBytes()` clamps to
* [1 MiB, 512 MiB]; an unbounded inbound cap is a memory DoS because the reader materializes
* the body several times over. The Bun listener's own `maxRequestBodySize` is fixed when the
* server starts, so raising this takes effect on restart.
*/
maxInboundBodyBytes?: number;
/**
* Aggregate admission budget, in bytes, for concurrent raised-limit inbound HTTP bodies.
* Omitted or 0 = the built-in 512 MiB budget. `resolveConcurrentInboundBodyLimitBytes()`
* clamps to [512 MiB, 2 GiB]; there is no disabled or unbounded mode. Changes take effect
* on proxy restart. This accounts for admitted bodies, not total process memory.
*/
maxConcurrentInboundBodyBytes?: number;
/**
* Opt-in Anthropic OAuth PROACTIVE routing (#294). Default OFF.
* Sticky session affinity; new sessions may pick lowest known 5h usage.
* Experimental — see docs and GUI warning before enabling.
*
* Reactive 429 failover is NOT gated here. It activates on account presence, like every
* other multi-credential provider, and cannot be switched off: rotating away from an account
* upstream has just rate-limited only ever runs after a refusal, so stranding it while a
* second logged-in account sits idle is a defect rather than a configuration choice.
*/
anthropicAccountPool?: AnthropicAccountPoolConfig;
/**
* Generic OAuth multi-account PROACTIVE account preference (#2568, #695).
*
* Reactive 429 rotation — moving to another logged-in account of the SAME provider when one
* is rate-limited — is presence-driven and NOT configurable here. It activates whenever a
* provider has 2 or more eligible stored accounts, the same consent rule an `apiKeyPool` of
* two keys already applies, and a single account remains a strict no-op.
*
* Proactive avoidance of an exhausted selected account requires `enabled: true`.
* A healthy selected account retains priority; an unknown quota is not exhaustion.
* `providers.<name>.oauthAccountFailover` overrides this per provider in either direction.
* Reactive 429 rotation remains presence-driven even when proactive routing is disabled.
*/
oauthAccountFailover?: {
enabled?: boolean;
};
/** Virtual `combo/<id>` models spanning concrete provider/model targets (issue #133). */
combos?: Record<string, OcxComboConfig>;
/**
* Routing policy profiles (Router Intelligence, RI-04+): explicitly requested
* `policy/<id>` (or configured alias) models select among an explicit
* candidate allowlist using hard capability requirements and deterministic
* scoring. Existing model ids are never routed through profiles implicitly.
*/
routingProfiles?: Record<string, OcxRoutingProfileConfig>;
/** Background proactive token refresh ("Token Guardian"). Off by default; see OcxTokenGuardianConfig. */
tokenGuardian?: OcxTokenGuardianConfig;
/** Additional exact origins allowed for CORS (e.g. HTTPS or chrome-extension://<id>). Loopback origins are always allowed. */
corsAllowOrigins?: string[];
/**
* #8338, opt-in, standalone only: the one reverse proxy a dashboard may sit behind and still
* remember devices. `origin` is the exact https origin the browser uses; `proxyAddresses` are
* the proxy hop's own IP addresses as this process observes them (never a range); and
* `trustHeaders` names the forwarded headers that carry the browser's host and scheme (default:
* Host only, scheme from `origin`). Absent, Remember stays direct HTTPS or loopback only. Parsed by
* src/config/dashboard-trusted-proxy.ts; enforced in managementRequestOrigin (src/server/auth-cors.ts).
*/
dashboardTrustedProxy?: {
origin: string;
proxyAddresses: string[];
trustHeaders?: Array<"x-forwarded-host" | "x-forwarded-proto">;
};
/**
* OCX-11 fallback off: refuse model or provider fallback per scope, and record per-device local
* fallback permission. Absent keeps every chain as it was. See src/routing/fallback-policy.ts.
*/
fallback?: OcxFallbackConfig;
}
export type OcxComboStrategy = "failover" | "round-robin" | "random" | "least-used" | "reset-window" | "jev";
export type OcxComboDefaultEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
export type OcxComboDefaultEffortMode = "fallback" | "force";
/**
* How a combo derives the reasoning ladder it publishes to the picker.
*
* `strict` (default) intersects every advertised ladder, so a target that explicitly
* advertises no effort control (`reasoningEfforts: []`) empties the combo's picker.
* `adaptive` excludes those empty ladders from the published intersection, keeping the
* control usable for a mixed-capability group. Unknown (`undefined`) ladders stay
* wildcards in both modes. An explicit empty ladder removes unsupported effort controls
* in either mode; adaptive dispatch also removes them before sending to an unknown target,
* while each known target still resolves its own effort.
*/
export type OcxComboReasoningEffortMode = "strict" | "adaptive";
/** Policy for how target cooldowns interact with `lastResort` targets (#5691). */
export type OcxComboCooldownWaitPolicy = "before-last-resort";
export interface OcxComboTarget {
provider: string;
model: string;
/** Relative target weight for round-robin batches and random selection. Default 1; valid range 1..10000. */
weight?: number;
/**
* Exact efforts JEV may choose for this target. Omit to allow every effort the
* target currently advertises; an explicit list must be non-empty.
*/
reasoningEfforts?: OcxComboDefaultEffort[];
/**
* Operator-authored capability description sent only to the JEV decision
* service for this target. The built-in model profile always applies.
*/
modelProfile?: string;
/**
* Marks an emergency-only target. Inert unless the combo sets
* `cooldownWaitPolicy`, and never makes a target permanently ineligible —
* see `OcxComboConfig.cooldownWaitPolicy` (#5691).
*/
lastResort?: boolean;
/**
* Pay-per-use target (for example an API-key row behind subscription targets). Only the
* configured keys with `allowMeteredComboTargets: true`, or a loopback-only combo
* with `allowMeteredTargets: true`, may reach it.
*/
metered?: boolean;
}
export interface OcxComboConfig {
targets: OcxComboTarget[];
/** Operator consent for metered targets on a loopback-only proxy. Default false; public listeners still require key consent. */
allowMeteredTargets?: boolean;
/** Ordered failover (default), round-robin, weighted random, least-used, or quota reset-window selection. */
strategy?: OcxComboStrategy;
/** Successful requests retained on one RR selection batch. Default 1; range 1..100. */
stickyLimit?: number;
/**
* Optional per-target cooldown used only when the upstream response has no Retry-After or Codex reset signal.
* Unset uses the upstream fallback (5 s for request-rate 429 codes 1302/1305, otherwise 60 s);
* an explicit value overrides that fallback. Range 1..600000.
*/
cooldownMs?: number;
/** Maximum wait for an eligible target cooldown to expire before failing closed. Default 0; range 0..600000, per selection attempt. */
waitForCooldownMs?: number;
/** Opt-in retry pass when all otherwise eligible targets are cooling. Disabled by default. */
cooldownReprobe?: {
enabled: boolean;
/** Minimum interval between recovery passes, in milliseconds. Default 300000; range 1000..86400000. */
intervalMs?: number;
};
/**
* `before-last-resort` defers targets marked `lastResort` while a normal
* target is merely cooling and that cooldown can be waited out inside
* `waitForCooldownMs`. Omitted keeps today's behavior, where a brief cooldown
* on a preferred target routes straight to the emergency target (#5691).
*
* It only ever defers. When no normal target can be reached — all cooling
* past the budget, excluded, or ruled out by the caller — the last-resort
* target is dispatched, because a policy that could withhold it would turn a
* fallback into an outage.
*/
cooldownWaitPolicy?: OcxComboCooldownWaitPolicy;
/** Used as a fallback when the client omits reasoning.effort, or as an override in `force` mode. null/omitted leaves the target default unchanged. */
defaultEffort?: OcxComboDefaultEffort | null;
/** `force` makes the combo default override a valid client effort. Omitted / `fallback` preserves client precedence. */
defaultEffortMode?: OcxComboDefaultEffortMode;
/**
* Picker-ladder derivation policy. Omitted / `"strict"` keeps the legacy rule where an
* explicitly empty target ladder suppresses the whole combo's effort control.
*/
reasoningEffortMode?: OcxComboReasoningEffortMode;
jevEffortMode?: import("./combo-jev-effort-mode").OcxComboJevEffortMode; // wire-effort owner on a `jev` combo; omitted = "decide"
capabilityPolicy?: import("./combo-capability-policy").OcxComboCapabilityPolicy; // omitted = "intersection"
onUnservable?: import("./combo-capability-policy").OcxComboOnUnservable; // `union` only; omitted = "degrade"
/**
* Disable image input even when every target supports it.
* Omitted / `"auto"` keeps automatic capability derivation (default: enabled when
* the target intersection includes image).
*/
imageInput?: "auto" | "disabled";
/**
* Optional public model name replacing the default `combo/<id>` slug. Bare names
* without "/" are allowed (e.g. "deepseek-v4-flash") so the combo can answer to a
* mandated model id; exact-match requests route here before any provider resolution.
*/
alias?: string;
/**
* Explicitly allow a bare OpenAI-native alias (for example `gpt-5.6-sol`) to
* be represented by this routed combo. Never inferred from `alias`.
*/
nativeAlias?: boolean;
/** Display-only label for the public catalog row. Required for native aliases. */
displayName?: string;
/** Display-only description for the public catalog row; unset keeps the generated text (#7229). */
description?: string;
/**
* `strategy: "jev"` only: provider id of the decision service. Omitted or `"jev"` uses the
* canonical TypeSafe endpoint; any other id must name a configured `adapter: "jev-decision"`
* row, such as a self-hosted Ollama `tev1` endpoint. That row's baseUrl is the full decision
* endpoint and only its own apiKey is sent there.
*/
decisionProvider?: string | null;
/** JEV only: an ordinary model route for decisions; null explicitly clears management input. */
decisionModel?: string | null;
/**
* `strategy: "jev"` only: decision deadline in milliseconds before failing open to the first
* eligible target. Default 4000; range 1000..120000. Raise it for a self-hosted decision model
* whose first call may include a cold model load.
*/
decisionTimeoutMs?: number;
/** JEV-only advisory loaded quota evidence; off/unset leaves request bytes unchanged. */
decisionQuotaSignals?: boolean | null;
/** Partial 0..100 tier overrides; defaults limited 70/nearlyExhausted 90. null clears. */
decisionQuotaTiers?: import("../combos/jev-quota-config").JevQuotaTiers | null;
/**
* `strategy: "jev"` only, default off: keep an explicit client session on the target JEV chose
* for it while the session stays active, so the provider prompt cache stays warm (#7525).
* `ttlMs` is the idle window after the last successful turn (60000..86400000). null clears.
*/
sessionPin?: import("../combos/jev-session-pin-config").JevSessionPinConfig | null;
}
export interface OcxTokenGuardianConfig {
/** Global kill-switch. Default false — the guardian does nothing unless explicitly enabled. */
enabled?: boolean;
/** Seconds between refresh sweeps. Default 21600 (6h). Min 60. */
tickSeconds?: number;
/** Random 0..jitterSeconds added before each sweep to de-synchronize. Default 300. */
jitterSeconds?: number;
/** Max concurrent refreshes per sweep. Default 3. Min 1. */
concurrency?: number;
/** Extra lead (seconds) beyond one tick when deciding a token is "expiring soon". Default 900. */
leadSeconds?: number;
/** First backoff (seconds) after a permanent refresh failure. Default 300. */
failureBackoffBaseSeconds?: number;
/** Backoff ceiling (seconds). Default 3600. */
failureBackoffMaxSeconds?: number;
/** Optional Codex pool session warmup sweep. Default false to avoid background synthetic traffic. */
codexWarmupEnabled?: boolean;
/** Max age before a Codex pool account is revalidated via `/codex/responses`. Default 691200 (8d). */
codexWarmupMaxAgeSeconds?: number;
/** Model used for optional Codex pool warmup. Default gpt-5.6-luna. */
codexWarmupModel?: string;
}
export interface OcxImagesConfig {
/** Optional custom API-key provider for /v1/images relays. Built-in OpenAI tiers remain automatic. */
provider?: string;
/** Upstream timeout (ms) for one image generation/edit call (bridge xAI + /v1/images relay). Default 60000 for the bridge; relay may use a higher default (300000). */
timeoutMs?: number;
/** Master switch for the image bridge. Default false — set true to enable paid xAI Grok Imagine generation. */
bridgeEnabled?: boolean;
/** xAI image model id. Default "grok-imagine-image-2.0". */
bridgeModel?: string;
/** Max image-generation loop iterations before forced-final. Default 3; clamped to [0, 10]. */
maxRounds?: number;
/** Max files retained under artifacts/. Oldest deleted when exceeded. Default 200. */
artifactsKeepCount?: number;
/** Master switch for the video bridge. Default false — must be explicitly opted in. */
videoBridgeEnabled?: boolean;
/** Optional API-key provider that serves `video_gen` (its own baseUrl and key). Unset keeps xAI; an unusable value fails closed. */
videoProvider?: string;
/** Model for xAI video generation. Default "grok-imagine-video-1.5-lite" (see src/images/video-capabilities.ts). */
/** Defaults to grok-imagine-video-1.5-lite. */
videoBridgeModel?: string;
/** Max video-gen rounds before forced-final. Default 2 (video is slower than image). */
videoMaxRounds?: number;
/** Per-video generation timeout (ms) including polling. Default 300000 (5 min). */
videoTimeoutMs?: number;
}
export interface OcxSearchConfig {
/**
* Total upstream deadline (ms) for one /v1/alpha/search relay. Default 200000. The endpoint
* is non-streaming JSON (headers arrive only when the search completes), so this is a whole-
* request budget — deliberately NOT connectTimeoutMs, which is a header-arrival budget.
*/
timeoutMs?: number;
}
export interface OcxVisionSidecarConfig {
/** Explicit Anthropic account pool; unset inherits the request's instance. */
anthropicInstance?: AnthropicInstanceId;
/** Master switch. Default: enabled when the selected backend has a usable credential. */
enabled?: boolean;
/**
* Description backend. Unset prefers a usable stored Anthropic OAuth credential, else OpenAI —
* the historical default order, deliberately unchanged by the union widening (#2188 roadmap
* 170/180 revised): "routed" describes through the proxy's OWN routing (loopback
* /v1/chat/completions) with a NAMESPACED "provider/model" describer, is explicit-only, and is
* never auto-selected from credential availability.
*/
backend?: "openai" | "anthropic" | "routed";
/** Vision model that describes images. */
model?: string;
/** Max description cache misses admitted in one main-model turn. Zero disables description calls. */
maxDescriptionsPerTurn?: number;
/** Sidecar fetch timeout (ms). */
timeoutMs?: number;
}
/**
* Advisor sidecar configuration. Automatic triggers require deterministic task evidence.
*/
export interface OcxAdvisorConfig {
/** Master switch. Default: false — the advisor stays off the request path entirely. */
enabled?: boolean;
/**
* The expert model consulted by the sidecar. Any model string the routing authority accepts:
* a bare native model ("gpt-6-astra"), an explicit "provider/model" ("anthropic/claude-...",
* "xai/grok-..."), or an account-qualified native model ("<namespace>/gpt-6-astra").
*/
model?: string;
/** Reasoning effort for the advisor call. Validated against the canonical effort ladder. */
effort?: "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
/**
* When the advisor is consulted. "manual" (default): only when the worker explicitly calls the
* synthetic `advisor` tool. "preflight": OpenCodex additionally attempts one automatic
* consultation per task once the task has produced orientation evidence (an assistant tool call
* or a tool result after the latest user message).
*/
policy?: "manual" | "preflight" | "adaptive";
/** question-only sends only the worker's explicit question and disables automatic consultations. */
contextMode?: "context" | "question-only";
/** Adaptive task consultation attempts (manual + automatic). Integer 1–3, default 3. */
maxConsultationsPerTask?: number;
/** Advisor fetch timeout (ms). Default 120000. */
timeoutMs?: number;
/**
* Operator consent to send task conversation and tool results to the configured Advisor
* provider. Only `"v1"` is current. Absent or any other value means the runtime must not
* send task context. `enabled: true` does not grant this, and upgrades do not write it.
*/
contextSharingConsent?: "v1";
}
export interface OcxWebSearchSidecarConfig {
/** Explicit Anthropic account pool; unset inherits the request's instance. */
anthropicInstance?: AnthropicInstanceId;
/** Master switch. Default: enabled when a forward (ChatGPT) provider exists and the caller is logged in. */
enabled?: boolean;
/**
* Which backend actually runs the server-side search. "openai" replays the hosted web_search via
* the ChatGPT forward provider (gpt-mini sidecar); "anthropic" runs web_search_20250305 on a Claude
* model authenticated by the STORED anthropic OAuth credential. "xai" runs Grok hosted web_search
* and optional x_search through stored Grok OAuth. "gemini" (google_search grounding via the
* Antigravity CCA transport) and "exa" (non-LLM search JSON via an operator key) are explicit-only
* and stay inactive until their executors ship. Unset ALWAYS resolves to "openai"; no backend is ever
* auto-selected from credential availability (that once sent incompatible models to the
* Anthropic API — see resolveSidecarBackend).
*/
backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa";
/** Sidecar model that runs the real server-side web_search (must be a native ChatGPT model). */
model?: string;
/**
* Operator-supplied Exa API key for the "exa" backend. Management GET responses never echo it,
* and src/lib/redact.ts strips it from any logged structure or error string.
*/
exaApiKey?: string;
/**
* Opt-in X (Twitter) search for the xai backend: adds the hosted x_search tool next to
* web_search. Limits are doc-validated at the management layer AND in the executor:
* handles <=20 per list, allow XOR exclude, ISO-8601 dates.
*/
xSearch?: {
enabled?: boolean;
allowedXHandles?: string[];
excludedXHandles?: string[];
fromDate?: string;
toDate?: string;
};
/** Reasoning effort for the sidecar — "minimal" (non-thinking) keeps it fast/cheap. */
reasoning?: string;
/** Max searches executed per main-model turn (loop guard). */
maxSearchesPerTurn?: number;
/** Sidecar fetch timeout (ms). */
timeoutMs?: number;
/**
* Config-file-only deadline (ms) for continuous routed-model response-body raw-byte inactivity
* during a web-search turn. Default 200000. Must be an integer from 1 through 2147483647.
*/
routedModelStallTimeoutMs?: number;
/**
* Stream the routed model's leading output (text/thinking deltas) live instead of buffering the
* whole iteration. Live delivery stops at the first tool-call boundary so web_search interception
* stays atomic. Tradeoff: text the model emits BEFORE deciding to search — which buffered mode
* silently drops — becomes visible to the client and may partially repeat in the post-search
* answer. Default: false (buffered, previous behavior).
*/
streamRoutedModelOutput?: boolean;
}
/**
* Codex account-pool selection policy.
*
* This is a selection policy, not a block. An excluded account keeps its credential, quota
* history, and thread affinity, stays visible on the account surface, and remains reachable by
* explicit account selection. Only automatic rotation skips it.
*/
export interface OcxCodexPoolConfig {
/** Start idle Codex windows when the pool is initialized. */
startIdleWindows?: boolean;
/** Enable process-local affinity for caller-owned credentials; defaults off. */
requestOwnedAffinity?: boolean;
/**
* Pool-only policy (#7410); defaults off. When true, automatic Pool resolution serves only
* registered, eligible non-main accounts: no ordered or preserved native main, no caller-main
* fallback, and a manual main pin is not honoured. An exhausted allowed pool refuses. Explicit
* account selectors (including `__main__` and Reserve) and Direct mode stay outside the policy.
*/
poolOnly?: boolean;
/**
* Plan keys ordinary rotation skips, matched case-insensitively against the plan stored on each
* account. Absent or empty means no policy.
*
* There is no `minimumPlan` counterpart: ranking ChatGPT plans against each other needs a total
* ordering this repository does not have, and inventing one would silently drain a tier the
* operator never meant to exclude.
*/
excludedPlans?: string[];
/** Optional per-account response to fresh quota observations at or above a usage percentage. */
lowQuotaProtection?: CodexLowQuotaProtectionConfig;
}
/** Optional policy for pausing accounts and notifying when selected quota windows are low. */
export interface CodexLowQuotaProtectionConfig {
enabled: boolean;
/** Inclusive usage percentage from 1 to 100. */
threshold: number;
actions: {
pause: boolean;
notify: boolean;
/** Opt-in: also hand each notice to this host's OS notifier (macOS, Linux). Requires notify. */
desktop?: boolean;
};
windows: {
short: boolean;
weekly: boolean;
};
}
/**
* Quota-reset notification settings.
*
* Every field is optional and the whole section defaults to off. `enabled: true` alone is not
* sufficient: without a webhook or a command there is nowhere to deliver, and treating that as
* off is what keeps the "a default install runs no detection code" guarantee true rather than
* nearly true.
*/
export interface OcxQuotaResetNotifyConfig {
/** Master switch. Default false — nothing detects, nothing polls, nothing fires. */
enabled?: boolean;
/** Which reset kinds to deliver. Default: both. */
kinds?: Array<"scheduled" | "surprise">;
/**
* Idle poll interval in seconds. Default 900, floor 60, and 0 disables polling entirely.
*
* Polling exists because the interesting case is a reset that happens while no request is in
* flight: without a poll, a window that reset overnight is only noticed on the next request.
*/
pollSeconds?: number;
/**
* POST the event as JSON here.
*
* Treated as a credential: for Slack and Discord the URL itself is the authorization, so it
* is redacted by `ocx config show` and excluded from `config export`.
*/
webhookUrl?: string;
/**
* Permit a loopback or private-network webhook target. Default false.
*
* An operator-supplied URL is an SSRF surface, so the default refuses anything that resolves
* private. Self-hosted receivers are the legitimate case for opting in.
*/
allowPrivateNetwork?: boolean;
/** Webhook timeout in milliseconds. Default 5000. */
timeoutMs?: number;
/**
* Run a local command with the event JSON on stdin.
*
* An argv array, never a shell string: the command is spawned directly, so an operator value
* cannot become a shell-injection surface.
*/
command?: string[];
}
/**
* Periodic model-catalog auto-refresh settings (issue #3630).
*
* Every field is optional and an absent section runs hourly. Each tick converges the
* served catalog the same way `ocx sync` does, which costs a live /models call against
* every enabled provider; set `enabled: false` to keep the catalog to explicit syncs.
*/
export interface OcxCatalogAutoRefreshConfig {
/** Master switch. Default true; false leaves the timer dormant with no upstream calls. */
enabled?: boolean;
/**
* Minutes between refresh ticks. Default 60, floor 15, and 0 keeps the timer dormant
* while leaving the section configured.
*
* The floor exists for the same reason src/quota/reset-poller.ts has MIN_INTERVAL_MS:
* provider catalogs are cached upstream for minutes, so a faster cadence buys no
* freshness and only risks a rate limit against every enabled provider at once.
*/
intervalMinutes?: number;
}
/**
* One scope's token ceiling.
*
* An object rather than a bare number because the ledger's scope limit is already a record in
* `SpendReservationPolicy`, and a config shape that mirrors the runtime one cannot drift from
* it silently. Absent `maxTokens` is the same as an absent scope: observe only.
*/
export interface OcxSpendScopeConfig {
/**
* Tokens the scope may hold at once, counting settled spend, open reservations and
* unresolved spend. A reservation is the request's whole input plus its enforceable output
* ceiling, so this is compared against a number that assumes every cached prefix misses.
*
* There is no default. A ceiling is a number only the operator knows -- it depends on the
* plan, the account roster and what the install is for -- and the recorded lesson from the
* observational phase of #4546 is that guessing one is worse than shipping none.
*/
maxTokens?: number;
}
/**
* Durable spend ceilings (#4546).
*
* The three scopes intersect: a request is admitted only when its own root workflow, the
* identity that would serve it, and the pool it would draw from all have room. That is what
* makes the ceiling hold against a caller that mints a fresh root id per request -- the root
* is new, the identity and pool are not.
*
* Every field is optional and an empty section is the same as no section at all.
*/
export interface OcxSpendConfig {
/** Ceiling for one root workflow -- the user-visible task, including its whole fan-out. */
root?: OcxSpendScopeConfig;
/** Ceiling for one authenticated identity, across every root it serves. */
identity?: OcxSpendScopeConfig;
/** Ceiling for one account pool, across every identity in it. */
pool?: OcxSpendScopeConfig;
/**
* Days a dormant scope's accounting is retained. Default 7.
*
* A scope is dropped only when it is both idle and under its ceiling, so shortening this
* cannot hand an exhausted scope a fresh allowance.
*/
retentionDays?: number;
}