@yalehwang/cloudpit 2.0.0 → 3.0.0

package/server/modules/providers/list/codex/codex-host-driver.provider.ts

@@ -23,6 +23,7 @@ import {
   type PendingTurn,
   type ResidentSession,
 } from '@/modules/providers/list/codex/codex-host-driver.contract.js';
+import { pendingLaunchForHost, residentLaunchForOptions } from '@/modules/providers/list/codex/codex-resident-provider-launch.js';
 import {
   createCodexLiveSettings,
   type CodexLiveSettings,
@@ -95,6 +96,8 @@ export class CodexHostDriver implements IProviderHostDriver {
   private readonly sessions = new Map<string, ResidentSession>();
   /** Launches carried from `startResidentSession` to the `bind` it causes. */
   private readonly pendingLaunches = new Map<string, PendingResidentLaunch>();
+  /** The per-session launch each host was spawned with; absent = the driver-wide launch. */
+  private readonly hostLaunches = new Map<string, CodexAppServerLaunch>();
   /** The `process/*` verbs and the `background-task` leases they report. */
   private readonly background: CodexBackgroundProcesses;
   /** Serial for the `turn` lease's `runId`; unique per turn of this instance. */
@@ -170,6 +173,12 @@ export class CodexHostDriver implements IProviderHostDriver {
     this.closedHostIds.delete(host.hostId);
     this.host = host;
     this.sink = sink;
+    // The connection (and so the process) is created before `bind` runs, so the
+    // pending per-session launch has to move onto the host id first.
+    const pendingLaunch = pendingLaunchForHost(host, this.pendingLaunches);
+    if (pendingLaunch) {
+      this.hostLaunches.set(host.hostId, pendingLaunch);
+    }
     const connection = this.connectionFor(host.hostId);
     await connection.initialize();
     host.pid = connection.pid;
@@ -402,6 +411,7 @@ export class CodexHostDriver implements IProviderHostDriver {
       this.pendingLaunches.delete(session.appSessionId);
     }
     this.connections.delete(host.hostId);
+    this.hostLaunches.delete(host.hostId);
     if (this.connection === connection) {
       this.connection = null;
     }
@@ -437,6 +447,10 @@ export class CodexHostDriver implements IProviderHostDriver {
     this.pendingLaunches.set(appSessionId, {
       providerSessionId: launch.context.resolveProviderSessionId(appSessionId),
       threadDefaults: residentThreadDefaults(launch.options),
+      // Compile BEFORE opening the host: a session bound to a provider the
+      // registry no longer defines must fail readably here (no process, no
+      // silent fall-back to Codex's `openai`), not on the first turn.
+      launch: residentLaunchForOptions(launch.options, this.launch),
     });
     try {
       const host = await hostPort.openHost({
@@ -797,7 +811,7 @@ export class CodexHostDriver implements IProviderHostDriver {
     if (existing) {
       return existing;
     }
-    const connection = this.createConnection(this.launch);
+    const connection = this.createConnection(this.hostLaunches.get(hostId) ?? this.launch);
     this.connections.set(hostId, connection);
     this.connection = connection;
     connection.onNotification((method, params) => this.handleNotification(method, params));

package/server/modules/providers/list/codex/codex-models.provider.ts

@@ -219,9 +219,13 @@ const defaultCatalogCacheKey = (): string => `${resolvePackagedCliVersion()}|${p
 
 const toCodexModelOption = (model: CodexModelDescriptor): ProviderModelOption => {
   const effortValues = (model.supportedReasoningEfforts ?? [])
-    .map((effort) => effort.reasoningEffort)
-    .filter((value): value is string => typeof value === 'string' && value.length > 0)
-    .map((value) => ({ value }));
+    .filter((effort): effort is { reasoningEffort: string; description?: string } => (
+      typeof effort.reasoningEffort === 'string' && effort.reasoningEffort.length > 0
+    ))
+    .map((effort) => ({
+      value: effort.reasoningEffort,
+      ...(effort.description === undefined ? {} : { description: effort.description }),
+    }));
 
   return {
     value: model.id,
@@ -235,6 +239,15 @@ const toCodexModelOption = (model: CodexModelDescriptor): ProviderModelOption =>
         values: effortValues,
       },
     }),
+    // A catalog entry's own window/threshold is the fact source for the launch
+    // when it declares one; the Codex runtime lifts these into
+    // `model_context_window` / `model_auto_compact_token_limit` overrides.
+    ...(model.modelContextWindow === undefined
+      ? {}
+      : { contextWindow: model.modelContextWindow }),
+    ...(model.modelAutoCompactTokenLimit === undefined
+      ? {}
+      : { autoCompactTokenLimit: model.modelAutoCompactTokenLimit }),
   };
 };
 

package/server/modules/providers/list/codex/codex-provider-injection.ts

@@ -0,0 +1,323 @@
+/**
+ * Builds the `CodexOptions` a per-run Codex SDK process needs to talk to a
+ * project-owned upstream provider.
+ *
+ * WHY THIS IS A SEPARATE CAPABILITY. The Codex SDK constructor takes the
+ * endpoint as `config.model_provider` + `config.model_providers.<id>` and the
+ * credential as an environment variable named by the provider's `env_key`.
+ * Passing only `ThreadOptions.modelProvider` is not enough: Codex 0.166 reports
+ * `modelProviderMismatch` unless the process itself was launched under the
+ * provider, so the options must exist at `new Codex(...)` time. This module is
+ * the one place that turns a resolved registry entry into that shape, so the
+ * resident injection path can reuse it instead of growing a second compiler.
+ *
+ * THE SECRET TRAVELS IN ENV, NEVER IN ARGV. The SDK serialises `config` into
+ * `--config key=value` arguments; `env_key` is only the variable NAME. The
+ * secret is placed in the child environment (`env`), which is also why a host
+ * sentinel must not survive: the SDK replaces `process.env` entirely whenever
+ * `env` is supplied, so the child sees only the plumbing allowlist plus the one
+ * provider credential.
+ *
+ * Consumed by `codex-runtime.provider.ts` (queryCodex, the per-run SDK path)
+ * and `codex-host-driver.provider.ts` (the resident app-server path, which needs
+ * `-c` spawn args instead of constructor options). The resolver is read from the
+ * shared port at call time; neither consumer imports the settings module (that
+ * edge would close the AC-394 providers/settings cycle).
+ */
+import type { CodexOptions } from '@openai/codex-sdk';
+
+import type { CodexAppServerLaunch } from '@/modules/providers/list/codex/codex-app-server.connection.js';
+import {
+  readCodexProviderRegistryPort,
+  type ResolvedCodexUpstreamProvider,
+} from '@/shared/ports/codex-provider-registry.port.js';
+import { AppError } from '@/shared/utils.js';
+
+/**
+ * Host variables a non-interactive Codex process needs that are plumbing, not
+ * credentials. Anything outside this list (API keys, arbitrary operator
+ * exports, test sentinels) is deliberately dropped: when the SDK is handed an
+ * `env`, it stops inheriting `process.env`, and that is exactly the isolation
+ * this injection promises.
+ */
+const CODEX_CHILD_ENV_ALLOWLIST: readonly string[] = [
+  'PATH',
+  'HOME',
+  'TMPDIR',
+  'TMP',
+  'TEMP',
+  'LANG',
+  'LC_ALL',
+  'LC_CTYPE',
+  'TZ',
+  'TERM',
+  'USER',
+  'LOGNAME',
+  'SHELL',
+  'CODEX_HOME',
+  'XDG_CONFIG_HOME',
+  'XDG_DATA_HOME',
+  'XDG_CACHE_HOME',
+  'XDG_STATE_HOME',
+  'SSL_CERT_FILE',
+  'SSL_CERT_DIR',
+  'NODE_EXTRA_CA_CERTS',
+  'HTTP_PROXY',
+  'HTTPS_PROXY',
+  'ALL_PROXY',
+  'NO_PROXY',
+  'http_proxy',
+  'https_proxy',
+  'all_proxy',
+  'no_proxy',
+];
+
+/**
+ * The child environment for one injected provider: the plumbing allowlist plus
+ * the token-file secret under the provider's own `env_key`.
+ *
+ * A host variable that happens to share the provider's `env_key` is overwritten
+ * by the resolved secret, so a stale operator credential can never win.
+ */
+export function buildCodexProviderEnv(
+  provider: ResolvedCodexUpstreamProvider,
+  source: Record<string, string | undefined> = process.env,
+): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of CODEX_CHILD_ENV_ALLOWLIST) {
+    const value = source[key];
+    if (typeof value === 'string' && value.length > 0) {
+      env[key] = value;
+    }
+  }
+  // `env_http_headers` maps a header to the NAME of a variable Codex reads from
+  // its own environment. Because this injection replaces the child environment,
+  // those variables have to be carried across explicitly or the headers would
+  // silently vanish. Only names the entry itself declares are forwarded.
+  for (const variable of Object.values(provider.envHttpHeaders ?? {})) {
+    const value = source[variable];
+    if (typeof value === 'string' && value.length > 0) {
+      env[variable] = value;
+    }
+  }
+  env[provider.envKey] = provider.secret;
+  return env;
+}
+
+/**
+ * The `[model_providers.<id>]` advanced settings in Codex's snake_case spelling.
+ *
+ * Only fields the entry declared are present, so an entry with none produces
+ * exactly the config it produced before these settings existed (and the AC-464
+ * criterion's strict deep-equal keeps its shape).
+ */
+function providerAdvancedConfig(
+  provider: ResolvedCodexUpstreamProvider,
+): Record<string, unknown> {
+  return {
+    ...(provider.httpHeaders === undefined ? {} : { http_headers: provider.httpHeaders }),
+    ...(provider.envHttpHeaders === undefined ? {} : { env_http_headers: provider.envHttpHeaders }),
+    ...(provider.queryParams === undefined ? {} : { query_params: provider.queryParams }),
+    ...(provider.requestMaxRetries === undefined
+      ? {}
+      : { request_max_retries: provider.requestMaxRetries }),
+    ...(provider.streamMaxRetries === undefined
+      ? {}
+      : { stream_max_retries: provider.streamMaxRetries }),
+    ...(provider.streamIdleTimeoutMs === undefined
+      ? {}
+      : { stream_idle_timeout_ms: provider.streamIdleTimeoutMs }),
+    ...(provider.modelCatalogUrl === undefined
+      ? {}
+      : { model_catalog_url: provider.modelCatalogUrl }),
+  };
+}
+
+/**
+ * A selected model entry's own window and auto-compaction threshold, the tier
+ * that wins over the provider entry's defaults.
+ */
+export type CodexModelLimits = {
+  contextWindow?: number | undefined;
+  autoCompactTokenLimit?: number | undefined;
+};
+
+/**
+ * The context-window overrides one launch carries.
+ *
+ * Codex keeps `model_context_window` / `model_auto_compact_token_limit` at the
+ * TOP LEVEL of its config, not inside `[model_providers.<id>]`. The selected
+ * model entry is the most specific fact source (the same tier Claude's launch
+ * profile occupies), then the provider entry's own default.
+ */
+function codexWindowConfig(
+  provider: ResolvedCodexUpstreamProvider,
+  limits: CodexModelLimits = {},
+): Record<string, number> {
+  const contextWindow = limits.contextWindow ?? provider.modelContextWindow;
+  const autoCompactTokenLimit = limits.autoCompactTokenLimit ?? provider.modelAutoCompactTokenLimit;
+  return {
+    ...(contextWindow === undefined ? {} : { model_context_window: contextWindow }),
+    ...(autoCompactTokenLimit === undefined
+      ? {}
+      : { model_auto_compact_token_limit: autoCompactTokenLimit }),
+  };
+}
+
+/**
+ * The SDK options for one resolved provider.
+ *
+ * `wire_api` is carried as the schema's literal `responses`: Codex 0.166
+ * refuses to load a provider that asks for Chat Completions, and the settings
+ * schema already rejects that value at write time.
+ */
+export function codexOptionsForProvider(
+  provider: ResolvedCodexUpstreamProvider,
+  limits: CodexModelLimits = {},
+): CodexOptions {
+  return {
+    config: {
+      ...codexWindowConfig(provider, limits),
+      model_provider: provider.id,
+      model_providers: {
+        [provider.id]: {
+          name: provider.name,
+          base_url: provider.baseUrl,
+          env_key: provider.envKey,
+          wire_api: provider.wireApi,
+          ...providerAdvancedConfig(provider),
+        },
+      },
+    },
+    env: buildCodexProviderEnv(provider),
+  };
+}
+
+/**
+ * Resolves one provider id against the installed project registry.
+ *
+ * Throws a readable error instead of falling back to Codex's `openai` default:
+ * after a user bound a model to a custom endpoint, dialling the default one
+ * silently would send the conversation to a different account and endpoint.
+ * The `CODEX_PROVIDER_NOT_CONFIGURED` code is what a launch surface maps to the
+ * app-server's own `modelProviderNotConfigured` reading; the sentence is the
+ * registry's (it names the id and the settings file). An unwired registry is
+ * reported the same way — a focused test that never installed the port cannot
+ * accidentally "pass" by omitting the injection.
+ */
+export function resolveCodexUpstreamProvider(providerId: string): ResolvedCodexUpstreamProvider {
+  const registry = readCodexProviderRegistryPort();
+  if (registry === null || typeof registry.resolve !== 'function') {
+    throw new AppError(
+      `Codex provider "${providerId}" cannot be resolved: the project Codex provider registry is not wired in this process.`,
+      { code: 'CODEX_PROVIDER_NOT_CONFIGURED', statusCode: 409 },
+    );
+  }
+
+  const resolution = registry.resolve(providerId);
+  if (!resolution.ok) {
+    throw new AppError(resolution.problem, {
+      code: 'CODEX_PROVIDER_NOT_CONFIGURED',
+      statusCode: 409,
+    });
+  }
+  return resolution.provider;
+}
+
+/** A TOML basic string, so a value Codex reads as config cannot break the `-c` line. */
+function tomlBasicString(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/** A TOML inline table of string values (`{ "X-Header" = "v" }`). */
+function tomlInlineMap(map: Record<string, string>): string {
+  const entries = Object.entries(map)
+    .map(([key, value]) => `${tomlBasicString(key)} = ${tomlBasicString(value)}`)
+    .join(', ');
+  return `{ ${entries} }`;
+}
+
+/**
+ * The `-c` overrides a resident `codex app-server` is spawned with.
+ *
+ * Codex 0.166 refuses `turn/start` with `modelProviderMismatch` when the
+ * provider is only named on `thread/start`; the process-global provider has to
+ * be selected at spawn time. The endpoint table is written as an inline TOML
+ * table because that is the same document `~/.codex/config.toml` carries, and
+ * the secret is deliberately NOT here: `env_key` only names the child
+ * environment variable (see {@link buildCodexProviderEnv}), because an argv
+ * value is visible to every `ps` on the machine.
+ *
+ * Advanced settings are appended INSIDE that same table; a value whose key is
+ * not valid in a bare TOML key is quoted. The two context-window keys are
+ * top-level in Codex's config, so they get their own `-c` lines.
+ */
+export function codexProviderSpawnArgs(
+  provider: ResolvedCodexUpstreamProvider,
+  limits: CodexModelLimits = {},
+): string[] {
+  const entry = [
+    `name = ${tomlBasicString(provider.name)}`,
+    `base_url = ${tomlBasicString(provider.baseUrl)}`,
+    `env_key = ${tomlBasicString(provider.envKey)}`,
+    `wire_api = ${tomlBasicString(provider.wireApi)}`,
+    ...(provider.httpHeaders === undefined
+      ? []
+      : [`http_headers = ${tomlInlineMap(provider.httpHeaders)}`]),
+    ...(provider.envHttpHeaders === undefined
+      ? []
+      : [`env_http_headers = ${tomlInlineMap(provider.envHttpHeaders)}`]),
+    ...(provider.queryParams === undefined
+      ? []
+      : [`query_params = ${tomlInlineMap(provider.queryParams)}`]),
+    ...(provider.requestMaxRetries === undefined
+      ? []
+      : [`request_max_retries = ${provider.requestMaxRetries}`]),
+    ...(provider.streamMaxRetries === undefined
+      ? []
+      : [`stream_max_retries = ${provider.streamMaxRetries}`]),
+    ...(provider.streamIdleTimeoutMs === undefined
+      ? []
+      : [`stream_idle_timeout_ms = ${provider.streamIdleTimeoutMs}`]),
+    ...(provider.modelCatalogUrl === undefined
+      ? []
+      : [`model_catalog_url = ${tomlBasicString(provider.modelCatalogUrl)}`]),
+  ].join(', ');
+  const windows = codexWindowConfig(provider, limits);
+  return [
+    '-c', `model_provider=${tomlBasicString(provider.id)}`,
+    '-c', `model_providers.${provider.id}={ ${entry} }`,
+    ...Object.entries(windows).flatMap(([key, value]) => ['-c', `${key}=${value}`]),
+  ];
+}
+
+/**
+ * The launch one resident app-server is spawned with for a bound provider.
+ *
+ * `base` is the driver-wide transport launch (working directory and the like);
+ * the provider overrides are appended to its args. The environment is REPLACED
+ * with the plumbing allowlist plus the one provider credential rather than
+ * merged with `base.env`: `spawn` treats an explicit env as the whole child
+ * environment, and a host sentinel surviving into the child is exactly what the
+ * isolation reading forbids. The MCP-gateway wrapper composes its own variable
+ * on top of this launch afterwards.
+ */
+export function compileCodexProviderLaunch(
+  providerId: string,
+  base: CodexAppServerLaunch = {},
+): CodexAppServerLaunch {
+  const provider = resolveCodexUpstreamProvider(providerId);
+  return {
+    ...base,
+    args: [...(base.args ?? []), ...codexProviderSpawnArgs(provider)],
+    env: buildCodexProviderEnv(provider),
+  };
+}
+
+/** Resolves one model's `codexProviderId` and compiles its per-run SDK options. */
+export function compileCodexProviderOptions(
+  providerId: string,
+  limits: CodexModelLimits = {},
+): CodexOptions {
+  return codexOptionsForProvider(resolveCodexUpstreamProvider(providerId), limits);
+}

package/server/modules/providers/list/codex/codex-resident-provider-launch.ts

@@ -0,0 +1,71 @@
+/**
+ * How one resident session's provider binding becomes an app-server spawn launch.
+ *
+ * WHY THIS IS ITS OWN FILE. `CodexHostDriver` keeps the process, the thread and
+ * the turn state; the question "which command line does this host start with"
+ * is a data transformation that only needs the session's launch bag and the
+ * registry credential. Keeping it beside the driver pushed that file over the
+ * architecture ratchet's committed line count for no structural gain, so the
+ * transformation lives here — the same seam pattern as
+ * `codex-resident-steer.ts` and `codex-resident-blocked-events.ts`.
+ *
+ * TWO CALL POINTS, ONE READING. `startResidentSession` compiles the provider id
+ * recorded on the session row; `startHost` has to place the result on the host
+ * id because `openHost` starts the process BEFORE it binds the session. Both
+ * read the id from the same field (`modelProviderId`), so the two paths cannot
+ * disagree about what a "bound session" is.
+ *
+ * A blank id is "no binding", not a provider named "": the driver then keeps
+ * its unbound launch byte-for-byte, which is the negative control for the
+ * injection.
+ */
+import type { CodexAppServerLaunch } from '@/modules/providers/list/codex/codex-app-server.connection.js';
+import type {
+  PendingResidentLaunch,
+} from '@/modules/providers/list/codex/codex-host-driver.contract.js';
+import { compileCodexProviderLaunch } from '@/modules/providers/list/codex/codex-provider-injection.js';
+import type { AnyRecord, ProcessHost } from '@/shared/types.js';
+
+/** The upstream provider id a resident launch bag records, or null. */
+export function residentProviderIdFromLaunchOptions(options: AnyRecord): string | null {
+  const value = options.modelProviderId;
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+/**
+ * The process launch one resident session's host must be spawned with.
+ *
+ * Null is the unbound arm (the driver-wide launch, unchanged). A recorded id is
+ * compiled into `-c` args plus the child environment's one credential; an id
+ * the registry cannot resolve throws the readable
+ * `CODEX_PROVIDER_NOT_CONFIGURED` error before any process starts, so a
+ * restarted host never silently falls back to Codex's `openai`.
+ */
+export function residentLaunchForOptions(
+  options: AnyRecord,
+  driverLaunch: CodexAppServerLaunch,
+): CodexAppServerLaunch | null {
+  const providerId = residentProviderIdFromLaunchOptions(options);
+  return providerId === null ? null : compileCodexProviderLaunch(providerId, driverLaunch);
+}
+
+/**
+ * The launch this host's first binding carried, if the host was opened on demand.
+ *
+ * `openHost` registers the binding and then calls `startHost`, so this is the
+ * only moment the pending launch is reachable: the request that it belongs to
+ * (`bind`) runs afterwards, by which time the process — and its argv — already
+ * exist.
+ */
+export function pendingLaunchForHost(
+  host: ProcessHost,
+  launches: ReadonlyMap<string, PendingResidentLaunch>,
+): CodexAppServerLaunch | null {
+  for (const appSessionId of host.bindings.keys()) {
+    const launch = launches.get(appSessionId)?.launch;
+    if (launch) {
+      return launch;
+    }
+  }
+  return null;
+}

package/server/modules/providers/list/codex/codex-runtime.provider.ts

@@ -22,6 +22,7 @@ import {
   createNormalizedMessage,
 } from '@/shared/index.js';
 import { notifyRunFailed, notifyRunStopped } from '@/modules/notifications/index.js';
+import { compileCodexProviderOptions } from '@/modules/providers/list/codex/codex-provider-injection.js';
 import { readCodexSessionTokenUsage } from '@/modules/providers/list/codex/codex-token-usage-files.js';
 import { approvalRequests } from '@/modules/providers/shared/base/approval-requests.service.js';
 import type { AnyRecord, ProviderRuntimeContext, ProviderRuntimeWriter } from '@/shared/index.js';
@@ -340,6 +341,16 @@ async function queryCodex(
     ? effort as ModelReasoningEffort
     : undefined;
 
+  // A model entry bound to a project Codex provider must be launched under that
+  // provider: Codex 0.166 rejects a turn whose provider differs from the one the
+  // process started with (`modelProviderMismatch`), so the injection has to be on
+  // the SDK options, not only on ThreadOptions. An unbound model keeps the exact
+  // previous behaviour — `new Codex()` with no options, inheriting Codex's global
+  // default. A bound model whose provider cannot be resolved throws inside the try
+  // below, which surfaces the readable line instead of silently dialling the
+  // default endpoint.
+  const codexProviderId = selectedModel?.config?.codexProviderId;
+
   let codex: Codex;
   let thread: Thread;
   // Provider-native thread id (starts as the resume id, or is captured from
@@ -359,7 +370,15 @@ async function queryCodex(
   const sessionKey = () => sessionId || capturedSessionId || null;
 
   try {
-    codex = new Codex();
+    codex = codexProviderId
+      ? new Codex(compileCodexProviderOptions(codexProviderId, {
+        // The selected catalog entry is the most specific context-window fact
+        // source (the tier a Claude launch profile occupies), falling back to
+        // the provider entry's own default inside the compiler.
+        contextWindow: selectedModel?.contextWindow,
+        autoCompactTokenLimit: selectedModel?.autoCompactTokenLimit,
+      }))
+      : new Codex();
 
     const threadOptions: ThreadOptions = {
       workingDirectory,

package/server/modules/providers/list/cursor/cursor-models.provider.ts

@@ -12,7 +12,7 @@ import {
   sanitizeLeafDirectoryName,
 } from '@/shared/utils.js';
 
-/** Curated Cursor catalog shipped as immutable CloudCLI defaults. */
+/** Curated Cursor catalog shipped as immutable Cloudpit defaults. */
 export const CURSOR_PREDEFINED_MODELS: ProviderModelsDefinition = {
   OPTIONS: [
     { value: 'auto', label: 'Auto', description: 'Let Cursor choose the model.' },

package/server/modules/providers/list/opencode/opencode-models.provider.ts

@@ -18,7 +18,7 @@ import {
 } from '@/shared/utils.js';
 
 /**
- * Curated OpenCode catalog shipped as immutable CloudCLI defaults.
+ * Curated OpenCode catalog shipped as immutable Cloudpit defaults.
  *
  * OpenCode routes by `<providerID>/<modelID>`, so this list mirrors the
  * providers `opencode models --verbose` reports: the OpenCode Zen gateway, the

package/server/modules/providers/provider.routes.ts

@@ -537,6 +537,13 @@ const parseModelConfigPayload = (raw: unknown): ProviderModelConfig | null | und
   if (typeof raw !== 'object' || !Array.isArray(env)) {
     throw new AppError('config.env must be an array.', { code: 'INVALID_MODEL_CONFIG', statusCode: 400 });
   }
+  const codexProviderId = (raw as { codexProviderId?: unknown }).codexProviderId;
+  if (codexProviderId !== undefined && typeof codexProviderId !== 'string') {
+    throw new AppError('config.codexProviderId must be a string.', {
+      code: 'INVALID_MODEL_CONFIG',
+      statusCode: 400,
+    });
+  }
   const rows = env.map((entry): ProviderModelEnvRow => {
     const row = (entry ?? {}) as Record<string, unknown>;
     const kinds = ['value', 'secret', 'envref', 'unset'];
@@ -554,7 +561,10 @@ const parseModelConfigPayload = (raw: unknown): ProviderModelConfig | null | und
       ? { key: row.key, kind: row.kind as ProviderModelEnvRow['kind'] }
       : { key: row.key, kind: row.kind as ProviderModelEnvRow['kind'], value: row.value };
   });
-  return { env: rows };
+  return {
+    ...(codexProviderId === undefined ? {} : { codexProviderId }),
+    env: rows,
+  };
 };
 
 const parseCustomProviderModelPayload = (payload: unknown): CustomProviderModelInput => {
@@ -699,7 +709,18 @@ router.post(
     // A session with no row has no recorded permission mode either, so that
     // answer is null rather than a mode the session never sent with.
     res.json(createApiSuccessResponse(
-      stored ?? { provider, sessionId, model, effort: null, permissionMode: null, source: 'session' as const },
+      stored ?? {
+        provider,
+        sessionId,
+        model,
+        effort: null,
+        permissionMode: null,
+        // No row yet, so no binding has been recorded either; the first send
+        // that reaches a row is what writes one.
+        modelProviderId: null,
+        modelProviderProblem: null,
+        source: 'session' as const,
+      },
     ));
   }),
 );