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;
}
