@yalehwang/cloudpit 2.0.0 → 3.0.0

package/server/modules/settings/codex-model-providers.store.ts

@@ -0,0 +1,244 @@
+/**
+ * Filesystem I/O for the project-owned Codex provider settings file and its per-provider
+ * secret files.
+ *
+ * WHY A FILE OF ITS OWN. `codex.settings.json` is the project's one writable surface for
+ * upstream Codex providers. The schema and validation live in
+ * `codex-model-providers.settings.ts`; this sibling owns only the bytes: resolving the
+ * path, hashing the content version a concurrent editor must send back, the atomic replace,
+ * and the `600` token files. Splitting the concern keeps both files under the module
+ * standard's line ceiling and lets a criterion drive the file layer without a route.
+ *
+ * THE PROJECT FILE IS THE ONLY WRITE TARGET. A user `~/.codex/config.toml` is never written:
+ * it is read-only compatibility, and an import binds into this project file instead.
+ *
+ * SECRETS NEVER ENTER THE JSON. `tokenFile` is a path. `readTokenSecret` is the only reader
+ * and its value is handed to a caller in memory; `writeTokenSecret` exists so the settings
+ * API can accept a secret without persisting it in the document. Every write here creates the
+ * file (or replaces it) with mode `600`.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  expandHome,
+  resolveSettingsPath,
+  writeSettingsFileAtomically,
+} from '@/shared/settings-file.js';
+import { AppError, errorMessage, isRecord } from '@/shared/utils.js';
+
+/** The only environment entry: it names the project Codex settings file. */
+export const CODEX_SETTINGS_PATH_ENV = 'CODEX_SETTINGS_PATH';
+
+/** The deployment's default location; a development checkout points the env entry at `config/`. */
+export function defaultCodexSettingsPath(homeDir: string): string {
+  return path.join(homeDir, '.config', 'cloudpit', 'codex.settings.json');
+}
+
+/** The file this process reads and writes. `explicit` is true when an operator named it. */
+export type CodexSettingsFileTarget = {
+  path: string;
+  explicit: boolean;
+};
+
+/**
+ * Resolves the Codex settings file: an explicit path, then `CODEX_SETTINGS_PATH`, then the
+ * shipped location. Consumers: the settings module (the production source) and the criterion.
+ */
+export function resolveCodexSettingsFileTarget(
+  options: {
+    settingsPath?: string | null;
+    env?: Record<string, string | undefined>;
+    homeDir?: string | undefined;
+  } = {},
+): CodexSettingsFileTarget {
+  const homeDir = options.homeDir ?? os.homedir();
+  const { filePath, explicit } = resolveSettingsPath({
+    settingsPath: options.settingsPath,
+    env: options.env ?? process.env,
+    envVar: CODEX_SETTINGS_PATH_ENV,
+    homeDir,
+    defaultPath: defaultCodexSettingsPath,
+  });
+  return { path: filePath ?? defaultCodexSettingsPath(homeDir), explicit };
+}
+
+/** The version reported for a file that does not exist yet (a first write creates it). */
+export const MISSING_CODEX_SETTINGS_VERSION = 'missing';
+
+/** One raw read: the parsed document, its content hash, and whether the file was present. */
+export type CodexSettingsDocumentReading = {
+  document: Record<string, unknown>;
+  version: string;
+  exists: boolean;
+};
+
+/** A content hash, so a stale editor can be told the file moved under it. */
+function versionOf(text: string): string {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+/**
+ * Reads the project file. A missing file is the ordinary "no providers yet" state; an
+ * unreadable or malformed one is a visible error, never silently treated as empty.
+ *
+ * Consumers: `codex-model-providers.settings.ts` (read, resolve and the version check).
+ */
+export function readCodexSettingsDocument(filePath: string): CodexSettingsDocumentReading {
+  let text: string;
+  try {
+    text = readFileSync(filePath, 'utf8');
+  } catch (failure) {
+    if ((failure as NodeJS.ErrnoException | null)?.code === 'ENOENT') {
+      return { document: {}, version: MISSING_CODEX_SETTINGS_VERSION, exists: false };
+    }
+    throw new AppError(`could not read ${filePath}: ${errorMessage(failure)}`, {
+      code: 'CODEX_SETTINGS_READ_FAILED',
+      statusCode: 500,
+    });
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (failure) {
+    throw new AppError(`${filePath} is not valid JSON: ${errorMessage(failure)}`, {
+      code: 'CODEX_SETTINGS_INVALID_JSON',
+      statusCode: 500,
+    });
+  }
+  if (!isRecord(parsed)) {
+    throw new AppError(`${filePath} must contain a JSON object`, {
+      code: 'CODEX_SETTINGS_INVALID_JSON',
+      statusCode: 500,
+    });
+  }
+  return { document: parsed, version: versionOf(text), exists: true };
+}
+
+/**
+ * Replaces the project file with `document` after proving the caller edited the version it
+ * read. The replace is atomic and always mode `600`, even when the previous file was wider,
+ * because this document describes credentials (paths and env names) and the task's contract
+ * is a 0600 project file.
+ *
+ * Consumers: `codex-model-providers.settings.ts`'s write path.
+ */
+export function writeCodexSettingsDocument(
+  filePath: string,
+  document: Record<string, unknown>,
+  options: { expectedVersion: string; versionPath?: string | undefined },
+): { version: string } {
+  const sourcePath = options.versionPath ?? filePath;
+  const current = readCodexSettingsDocument(sourcePath);
+  if (current.version !== options.expectedVersion) {
+    throw new AppError('The Codex provider settings changed since they were read; reload and save again.', {
+      code: 'VERSION_CONFLICT',
+      statusCode: 409,
+      details: { expectedVersion: options.expectedVersion, currentVersion: current.version },
+    });
+  }
+
+  const serialized = `${JSON.stringify(document, null, 2)}\n`;
+  try {
+    writeSettingsFileAtomically(filePath, serialized, { mode: 0o600 });
+  } catch (failure) {
+    throw new AppError(`could not write ${filePath}: ${errorMessage(failure)}`, {
+      code: 'CODEX_SETTINGS_WRITE_FAILED',
+      statusCode: 500,
+    });
+  }
+  return { version: versionOf(serialized) };
+}
+
+/**
+ * Resolves a provider's secret path. An operator-written `tokenFile` wins (a leading `~` is
+ * expanded and a relative path is resolved against the settings file's directory); otherwise
+ * every provider gets its own file under `<settings dir>/codex.secrets/<id>.token`.
+ *
+ * Consumers: `codex-model-providers.settings.ts`'s read/resolve/write paths.
+ */
+export function resolveCodexTokenFilePath(
+  settingsPath: string,
+  providerId: string,
+  rawTokenFile: string,
+  homeDir: string,
+): string {
+  const trimmed = rawTokenFile.trim();
+  if (trimmed !== '') {
+    const expanded = expandHome(trimmed, homeDir);
+    return path.isAbsolute(expanded)
+      ? expanded
+      : path.resolve(path.dirname(settingsPath), expanded);
+  }
+  return path.join(path.dirname(settingsPath), 'codex.secrets', `${providerId}.token`);
+}
+
+/** What one secret-file read observed: the value, or a line naming why it is unusable. */
+export type CodexTokenSecretReading =
+  | { ok: true; secret: string }
+  | { ok: false; problem: string };
+
+/**
+ * Reads one `600` token file. A missing or empty file is a readable "no secret" answer, not a
+ * throw: the runtime must be able to say why a provider cannot launch. The value never
+ * appears in the returned text.
+ *
+ * Consumers: `codex-model-providers.settings.ts`'s `read`/`resolve`.
+ */
+export function readCodexTokenSecret(tokenFile: string): CodexTokenSecretReading {
+  let secret: string;
+  try {
+    secret = readFileSync(tokenFile, 'utf8').trim();
+  } catch (failure) {
+    const code = (failure as NodeJS.ErrnoException | null)?.code;
+    return {
+      ok: false,
+      problem: code === 'ENOENT'
+        ? `token file ${tokenFile} is missing`
+        : `could not read token file ${tokenFile}: ${errorMessage(failure)}`,
+    };
+  }
+  if (secret === '') {
+    return { ok: false, problem: `token file ${tokenFile} is empty` };
+  }
+  return { ok: true, secret };
+}
+
+/**
+ * Writes a secret into its token file, atomically and mode `600`. Used only when the settings
+ * API is handed a write-only `token`; the value is never placed in the project document.
+ *
+ * Consumers: `codex-model-providers.settings.ts`'s write path.
+ */
+export function writeCodexTokenSecret(tokenFile: string, secret: string): void {
+  try {
+    writeSettingsFileAtomically(tokenFile, secret, { mode: 0o600 });
+  } catch (failure) {
+    throw new AppError(`could not write token file ${tokenFile}: ${errorMessage(failure)}`, {
+      code: 'CODEX_TOKEN_WRITE_FAILED',
+      statusCode: 500,
+    });
+  }
+}
+
+/**
+ * Reports (never throws) whether a token file is wider than `600`. The runtime tolerates a
+ * wide file — refusing it would turn a permissions typo into a dead provider — but the reading
+ * names the problem so an operator can fix it.
+ *
+ * Consumers: `codex-model-providers.settings.ts` (per-provider warnings).
+ */
+export function tokenFileModeWarning(tokenFile: string): string | null {
+  try {
+    const mode = statSync(tokenFile).mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+      return `token file ${tokenFile} has mode ${mode.toString(8)}; 600 is expected because it holds a secret`;
+    }
+  } catch {
+    // The read path already reports a missing file with its own, more useful message.
+  }
+  return null;
+}

package/server/modules/settings/index.ts

@@ -42,6 +42,24 @@ export type {
   ServerSettings,
 } from './server-settings.js';
 export type { CodexMcpGatewaySettings } from './codex-mcp-gateway.settings.js';
+// createCodexModelProvidersSource / CodexModelProvidersSource: the project-owned Codex upstream
+// provider registry (`~/.config/cloudpit/codex.settings.json`). The settings API writes through
+// the one instance `settings.module.ts` owns; the resident/per-run Codex injection tasks create
+// their own source over the same file and call `resolve(id)` AT SPAWN TIME (reads are uncached),
+// so an edit reaches the next launch without a restart.
+export {
+  createCodexModelProvidersSource,
+  type CodexModelProviderResolution,
+  type CodexModelProvidersSource,
+  type ResolvedCodexModelProvider,
+} from './codex-model-providers.settings.js';
+// The registry's own vocabulary, exported so a sibling task names the same reserved ids and the
+// same one accepted wire dialect instead of restating them.
+export {
+  CODEX_PROVIDER_WIRE_API,
+  RESERVED_CODEX_PROVIDER_IDS,
+} from './codex-model-providers.schema.js';
+export { CODEX_SETTINGS_PATH_ENV } from './codex-model-providers.store.js';
 // readCockpitSessionStartBoot / resolveServerSettingsFileTarget: the dual read/write target the
 // cockpit session-start settings use when the legacy file is the source. Exported so the
 // Cloudpit runtime criterion can drive the legacy-read → Cloudpit-write contract over a temp home.

package/server/modules/settings/server-settings-file.ts

@@ -21,22 +21,15 @@
  * top-level key and every other `cockpit`/`sessionStart` field, and committed by writing a
  * sibling temp file and renaming it over the target, so a reader never observes a half file.
  */
-import { createHash, randomUUID } from 'node:crypto';
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import path from 'node:path';
 
 import {
   defaultServerSettingsPath as defaultServerSettingsPathForHome,
   legacyServerSettingsPath,
+  migrateLegacyServerSettingsFile,
+  writeSettingsFileAtomically,
 } from '@/shared/settings-file.js';
 import { AppError, errorMessage, isRecord } from '@/shared/utils.js';
 
@@ -67,10 +60,11 @@ export function defaultServerSettingsPath(): string {
  * Resolves the file the boot reader and the settings API share. Same order as
  * `loadServerSettings`: an explicit path > `SERVER_SETTINGS_PATH` > the shipped location.
  *
- * The shipped location is now `<home>/.config/cloudpit/server.settings.json`. When that file does
- * not exist yet but the legacy `<home>/.config/claudecodeui/server.settings.json` does, the READ
- * falls back to the legacy file while `writePath` stays on the Cloudpit default: an upgrade keeps
- * its effective configuration and the next save lands in the new tree, never back in the old one.
+ * The shipped location is `<home>/.config/cloudpit/server.settings.json`. v3.0 deleted the
+ * runtime read fallback to `<home>/.config/claudecodeui/server.settings.json`: on the first
+ * resolution the legacy file is COPIED to the Cloudpit path once (never overwriting an existing
+ * Cloudpit file), and every read afterwards uses only the Cloudpit file. `path` and `writePath`
+ * are therefore always the same for the default target, and a save lands in the new tree.
  *
  * Consumers: `server-settings.ts` (the boot read) and `settings.module.ts` (the API's target).
  */
@@ -78,7 +72,6 @@ export function resolveServerSettingsFileTarget(options: {
   settingsPath?: string | undefined;
   env?: Record<string, string | undefined>;
   defaultPath?: string | undefined;
-  legacyDefaultPath?: string | undefined;
   homeDir?: string | undefined;
   exists?: ((filePath: string) => boolean) | undefined;
 } = {}): ServerSettingsFileTarget {
@@ -93,12 +86,19 @@ export function resolveServerSettingsFileTarget(options: {
   }
 
   const defaultPath = options.defaultPath ?? defaultServerSettingsPathForHome(homeDir);
-  // An injected defaultPath without an injected legacy path is a hermetic caller: do not consult
-  // the process HOME behind its back.
-  const legacyDefaultPath = options.legacyDefaultPath
-    ?? (options.defaultPath === undefined ? legacyServerSettingsPath(homeDir) : defaultPath);
-  const path_ = exists(defaultPath) || !exists(legacyDefaultPath) ? defaultPath : legacyDefaultPath;
-  return { path: path_, writePath: defaultPath, explicit: false };
+  // One-time upgrade aid: copy the pre-flip file into the Cloudpit tree when the latter is
+  // absent. The legacy file is never read again after this and is left on disk.
+  // An INJECTED defaultPath marks a hermetic caller (the criteria drive an arbitrary temp file);
+  // it must not consult the process HOME behind its back, so migration runs only for the shipped
+  // default derived from `homeDir`.
+  if (options.defaultPath === undefined) {
+    migrateLegacyServerSettingsFile({
+      legacyPath: legacyServerSettingsPath(homeDir),
+      targetPath: defaultPath,
+      exists,
+    });
+  }
+  return { path: defaultPath, writePath: defaultPath, explicit: false };
 }
 
 /**
@@ -293,30 +293,18 @@ function createSerialQueue(): { run<T>(operation: () => T): Promise<T> } {
 
 const cockpitSessionStartWrites = createSerialQueue();
 
-/** Writes a sibling temp file and renames it over the target, so no reader sees a half file. */
-function writeAtomically(filePath: string, contents: string, replacing: boolean): void {
-  const directory = path.dirname(filePath);
-  const temporary = path.join(
-    directory,
-    `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`,
-  );
+/**
+ * Writes the document through the shared atomic replace, wrapping a filesystem failure in this
+ * module's own error code. An existing file keeps its mode; a new one is created `0600`.
+ */
+function writeAtomically(filePath: string, contents: string): void {
   try {
-    mkdirSync(directory, { recursive: true });
-    const mode = replacing ? statSync(filePath).mode & 0o777 : 0o600;
-    writeFileSync(temporary, contents, { encoding: 'utf8', mode });
-    renameSync(temporary, filePath);
+    writeSettingsFileAtomically(filePath, contents);
   } catch (failure) {
     throw new AppError(`could not write ${filePath}: ${errorMessage(failure)}`, {
       code: 'SERVER_SETTINGS_WRITE_FAILED',
       statusCode: 500,
     });
-  } finally {
-    // The rename consumed the temp name on success; this removes it only after a failed write.
-    try {
-      rmSync(temporary, { force: true });
-    } catch {
-      // A leftover temp file is not a reason to hide the write's own error.
-    }
   }
 }
 
@@ -377,7 +365,7 @@ export function writeCockpitSessionStart(
     document.cockpit = cockpit;
 
     const serialized = `${JSON.stringify(document, null, 2)}\n`;
-    writeAtomically(filePath, serialized, existsSync(filePath));
+    writeAtomically(filePath, serialized);
     return { path: filePath, ...savedFieldsOf(document), version: versionOf(serialized) };
   });
 }

package/server/modules/settings/server-settings.ts

@@ -303,7 +303,6 @@ type ServerSettingsFileOptions = {
   settingsPath?: string | undefined;
   env?: Record<string, string | undefined>;
   defaultPath?: string | undefined;
-  legacyDefaultPath?: string | undefined;
   homeDir?: string | undefined;
   exists?: ((filePath: string) => boolean) | undefined;
 };
@@ -312,8 +311,8 @@ export function loadServerSettings(options: ServerSettingsFileOptions = {}): Ser
   const target = resolveServerSettingsFileTarget(options);
   const reading = readServerSettings(options, target);
   // The ONE boot read becomes the "currently in effect" reading the settings API reports, so
-  // the surface and the card `session.start` executor cannot disagree about this process;
-  // `writePath` stays on the Cloudpit default even when the reading came from the legacy file.
+  // the surface and the card `session.start` executor cannot disagree about this process.
+  // v3.0 removed the legacy read fallback, so `path` and `writePath` are the same default file.
   recordCockpitSessionStartBoot(reading.path, reading.cockpit.sessionStart, target.writePath);
   return reading;
 }

package/server/modules/settings/settings.module.ts

@@ -1,3 +1,5 @@
+import os from 'node:os';
+
 import {
   accessTokensDb,
   credentialsDb,
@@ -18,9 +20,15 @@ import {
   notifyUserIfEnabled,
 } from '@/modules/notifications/index.js';
 import { createAccessTokensService } from '@/modules/oauth/index.js';
+import { installCodexProviderRegistryPort } from '@/shared/ports/codex-provider-registry.port.js';
 
 import { createSettingsRouter } from './settings.routes.js';
 import { createSettingsService } from './settings.service.js';
+import { RESERVED_CODEX_PROVIDER_IDS } from './codex-model-providers.schema.js';
+import {
+  createCodexModelProvidersSource,
+  readCodexUserProviderImports,
+} from './codex-model-providers.settings.js';
 import { DEFAULT_COCKPIT_SESSION_START_MODEL } from './server-settings.js';
 import {
   readCockpitSessionStart,
@@ -31,6 +39,32 @@ import {
 
 const accessTokensService = createAccessTokensService({ now: () => new Date() });
 
+/**
+ * The project-owned Codex provider registry. One instance owns the file path and the write
+ * queue; the settings API writes through it and the Codex injection tasks create their own
+ * source over the same file (reads are uncached, so both see the latest edit).
+ */
+const codexModelProvidersSource = createCodexModelProvidersSource();
+
+/**
+ * The providers module refuses a model entry's `codexProviderId` unless it names a provider this
+ * registry (or Codex's built-in list) knows. It reads that judgement through a shared port rather
+ * than importing this module: `providers -> settings` would close the `providers -> settings ->
+ * mcp-gateway -> providers` cycle AC-394 pins. Reads are uncached, so a provider saved through
+ * the settings API is visible to the very next model write.
+ *
+ * The same install carries `resolve`, the spawn-time lookup a per-run/resident Codex injection
+ * uses to read the endpoint and the token-file secret. It resolves against the live file on every
+ * call, so an edit reaches the next launch without a restart.
+ */
+installCodexProviderRegistryPort({
+  read: () => ({
+    providers: codexModelProvidersSource.read().providers.map((provider) => ({ id: provider.id })),
+    reservedIds: RESERVED_CODEX_PROVIDER_IDS,
+  }),
+  resolve: (id) => codexModelProvidersSource.resolve(id),
+});
+
 /**
  * The two files the cockpit settings page works with: the one THIS boot read, and the one a save
  * must write. They differ only when the boot read fell back to the legacy settings file — the
@@ -176,6 +210,13 @@ const settingsService = createSettingsService({
       return boot === null ? null : { model: boot.model, effort: boot.effort };
     },
   },
+  codexModelProviders: {
+    read: () => codexModelProvidersSource.read(),
+    write: (input) => codexModelProvidersSource.write(input),
+    // The composition root decides WHOSE profile is imported: this process's operator. The read
+    // is one-way (the user's TOML files are never written); the bind goes to the project source.
+    readUserImports: () => readCodexUserProviderImports({ homeDir: os.homedir(), env: process.env }),
+  },
 });
 
 /** Settings router assembled for the authenticated server mount. */

package/server/modules/settings/settings.routes.ts

@@ -100,5 +100,42 @@ export function createSettingsRouter(
     };
   router.put('/cockpit/session-start', writeCockpitSessionStart(false));
   router.patch('/cockpit/session-start', writeCockpitSessionStart(true));
+
+  // The project-owned Codex upstream provider registry. GET reports each provider's fields and
+  // only whether its token file holds a secret (`tokenSet`); PUT is a full replacement guarded by
+  // the content hash it was based on (`expectedVersion` in the body, or `If-Match`), so a second
+  // editor's stale save is a 409 rather than a silent overwrite.
+  //
+  // The user-profile import lives at a sub-path: GET only READS the operator's `~/.codex` TOML
+  // blocks (never a secret value), and POST binds the named rows into the project file, carrying
+  // the same version proof as a save so a stale bind cannot overwrite a newer registry.
+  router.get('/codex/model-providers/import', respond(() => service.getCodexUserProviderImports()));
+  router.post('/codex/model-providers/import', async (req, res, next) => {
+    try {
+      const header = req.get('if-match');
+      const headerVersion = header === undefined
+        ? undefined
+        : header.replace(/^W\//, '').replace(/^"|"$/g, '');
+      const reading = await service.importCodexUserProviders({
+        body: req.body,
+        headerVersion,
+      });
+      res.status(200).set('ETag', `"${reading.version}"`).json(reading);
+    } catch (error) { next(error); }
+  });
+  router.get('/codex/model-providers', respond(() => service.getCodexModelProviders()));
+  router.put('/codex/model-providers', async (req, res, next) => {
+    try {
+      const header = req.get('if-match');
+      const headerVersion = header === undefined
+        ? undefined
+        : header.replace(/^W\//, '').replace(/^"|"$/g, '');
+      const reading = await service.updateCodexModelProviders({
+        body: req.body,
+        headerVersion,
+      });
+      res.status(200).set('ETag', `"${reading.version}"`).json(reading);
+    } catch (error) { next(error); }
+  });
   return router;
 }

package/server/modules/settings/settings.service.ts

@@ -1,7 +1,13 @@
 import type { McpAuditRouteEntry, McpGatewayGateReading } from '@/modules/mcp-gateway/index.js';
 import { normalizeAccessTokenScopes } from '@/modules/oauth/index.js';
+import { readExpectedVersion } from '@/shared/settings-file.js';
 import { AppError } from '@/shared/utils.js';
 
+import {
+  createCodexModelProvidersOperations,
+  type CodexModelProvidersPort,
+} from './codex-model-providers.service.js';
+
 type NotificationPreferences = Record<string, unknown> & {
   channels?: Record<string, unknown> & { webPush?: boolean };
 };
@@ -133,7 +139,7 @@ type SettingsDependencies = {
     list(userId: number): StoredOAuthToken[];
   };
   /**
-   * The read-only seams the Settings → API page's CloudCLI MCP block needs.
+   * The read-only seams the Settings → API page's Cloudpit MCP block needs.
    *
    * Optional so the existing service criteria keep constructing the dependency
    * object they always have; the module always supplies it (see
@@ -167,6 +173,14 @@ type SettingsDependencies = {
    * model with the shipped default, so this module never restates it.
    */
   cockpitSessionStart?: CockpitSessionStartPort;
+  /**
+   * The project-owned Codex provider registry (Settings → Agents → Codex).
+   *
+   * Optional so the existing service criteria keep constructing the dependency object they
+   * always have; `settings.module.ts` always supplies it. The operations live in a sibling
+   * file so this assembled service does not grow the registry's file and transport rules.
+   */
+  codexModelProviders?: CodexModelProvidersPort;
 };
 
 /** The only lifetimes a personal access token may request, in days. */
@@ -176,7 +190,7 @@ const ALLOWED_TOKEN_EXPIRY_DAYS: readonly number[] = [7, 30, 90];
 const DEFAULT_TOKEN_EXPIRY_DAYS = 30;
 
 /** Scopes applied when the caller omits them; the read scope is the required baseline. */
-const DEFAULT_TOKEN_SCOPES: readonly string[] = ['cloudcli:read'];
+const DEFAULT_TOKEN_SCOPES: readonly string[] = ['cloudpit:read'];
 
 /**
  * Projects a stored row to the client-facing token shape. Written as an
@@ -298,31 +312,12 @@ function readCockpitSessionStartEffort(value: unknown): string {
   return value.trim();
 }
 
-/** The version the edit was based on: the body's `expectedVersion`, else the `If-Match` header. */
-function readCockpitSessionStartVersion(
-  body: Record<string, unknown>,
-  headerVersion: string | undefined,
-): string {
-  if (body.expectedVersion !== undefined && typeof body.expectedVersion !== 'string') {
-    throw new AppError('expectedVersion must be a string', {
-      code: 'INVALID_VERSION',
-      statusCode: 400,
-    });
-  }
-  const fromBody = typeof body.expectedVersion === 'string' ? body.expectedVersion.trim() : '';
-  const version = fromBody || (headerVersion ?? '').trim();
-  if (!version) {
-    throw new AppError('expectedVersion is required to save', {
-      code: 'VERSION_REQUIRED',
-      statusCode: 400,
-    });
-  }
-  return version;
-}
-
 /** Creates settings workflows with repositories and notification effects injected. */
 export function createSettingsService(dependencies: SettingsDependencies) {
   return {
+    // The Codex provider registry's two endpoints are a distinct file-backed concern; they are
+    // composed here so `settings.module.ts` still builds one service.
+    ...createCodexModelProvidersOperations(dependencies.codexModelProviders),
     listCredentials(userId: number, credentialType: string | null) {
       return { credentials: dependencies.credentials.list(userId, credentialType) };
     },
@@ -459,7 +454,7 @@ export function createSettingsService(dependencies: SettingsDependencies) {
       return { success: true };
     },
     /**
-     * The Settings → API page's CloudCLI MCP block: whether the gateway is
+     * The Settings → API page's Cloudpit MCP block: whether the gateway is
      * enabled, the path it answers on, and the base url an MCP client should
      * dial. The gate is read through the mcp-gateway module (the single place
      * `MCP_ENABLED` is parsed) rather than re-derived here.
@@ -545,7 +540,7 @@ export function createSettingsService(dependencies: SettingsDependencies) {
         });
       }
 
-      const expectedVersion = readCockpitSessionStartVersion(body, input.headerVersion);
+      const expectedVersion = readExpectedVersion(body, input.headerVersion);
       const saved = await port.write({
         model,
         effort: input.partial ? effort : (effort ?? ''),

package/server/modules/settings/tests/cockpit-session-start-settings.routes.test.ts

@@ -318,6 +318,7 @@ test('AC1: real auth rejects anonymous and invalid callers; the GET is an allowl
       { label: 'non-string model', reply: await harness.put({ model: 42, expectedVersion: version }), code: 'INVALID_MODEL' },
       { label: 'non-string effort', reply: await harness.patch({ effort: 5, expectedVersion: version }), code: 'INVALID_EFFORT' },
       { label: 'missing version', reply: await harness.put({ model: 'x' }), code: 'VERSION_REQUIRED' },
+      { label: 'non-string version', reply: await harness.put({ model: 'x', expectedVersion: 42 }), code: 'INVALID_VERSION' },
       { label: 'PUT without a model', reply: await harness.put({ effort: 'high', expectedVersion: version }), code: 'MODEL_REQUIRED' },
       { label: 'empty PATCH', reply: await harness.patch({ expectedVersion: version }), code: 'NOTHING_TO_UPDATE' },
     ];