@yalehwang/cloudpit 2.0.0 → 3.0.0

package/server/modules/providers/services/provider-models.service.ts

@@ -14,14 +14,36 @@ import type {
   ProviderModelsDefinition,
   ProviderSessionModel,
 } from '@/shared/types.js';
+import {
+  readCodexProviderRegistryPort,
+  type CodexProviderRegistryReading,
+} from '@/shared/ports/codex-provider-registry.port.js';
 import { AppError } from '@/shared/utils.js';
 
+import {
+  createSessionModelResolver,
+  type RecordedSessionSelection,
+} from './session-model-resolver.js';
+import {
+  assertProviderAvailable,
+  assertProviderSwitchAllowed,
+  readRecordedProviderBinding,
+  resolveModelProviderId,
+} from './session-provider-binding.js';
+
 /** Session-row access the service needs, narrowed so tests can stub it. */
 type ProviderModelsSessionStore = {
   getSessionById(
     sessionId: string,
-  ): { model: string | null; effort: string | null; permission_mode: string | null } | null;
+  ): {
+    model: string | null;
+    effort: string | null;
+    permission_mode: string | null;
+    model_provider_id?: string | null;
+  } | null;
   setSessionModel(sessionId: string, model: string): void;
+  /** Returns false when the row already carries a binding (the column is write-once). */
+  setSessionModelProviderId(sessionId: string, modelProviderId: string): boolean;
   setSessionEffort(sessionId: string, effort: string): void;
   /** Returns false when no session row matched. */
   setSessionPermissionMode(sessionId: string, permissionMode: string): boolean;
@@ -38,10 +60,21 @@ type ProviderModelsCatalogStore = Pick<
   | 'deleteCustomProviderModel'
 >;
 
+/**
+ * The Codex provider registry reading a model write validates against.
+ *
+ * `null` means no registry is wired (a focused criterion that injected no fake);
+ * the service then refuses a declared `codexProviderId` instead of guessing.
+ */
+type ProviderModelsCodexProviders = {
+  read(): CodexProviderRegistryReading | null;
+};
+
 type ProviderModelsServiceDependencies = {
   resolveProvider?: (provider: LLMProvider) => Pick<IProvider, 'models'>;
   catalog?: ProviderModelsCatalogStore;
   sessions?: ProviderModelsSessionStore;
+  codexProviders?: ProviderModelsCodexProviders;
 };
 
 /**
@@ -52,6 +85,7 @@ const toPublicConfig = (config: ProviderModelConfig | null): ProviderModelPublic
   config === null
     ? null
     : {
+      ...(config.codexProviderId === undefined ? {} : { codexProviderId: config.codexProviderId }),
       env: config.env.map((row) => {
         if (row.kind === 'secret') {
           return { key: row.key, kind: 'secret' as const, isSet: true as const };
@@ -64,15 +98,26 @@ const toPublicConfig = (config: ProviderModelConfig | null): ProviderModelPublic
     }
 );
 
+/**
+ * The picker row for one custom model.
+ *
+ * A model bound to a project Codex provider carries the provider id in its label
+ * (`model · provider`) so two entries with the same display name — one bound to
+ * each endpoint — stay distinguishable in the merged catalog. An entry with no
+ * binding keeps its bare name: it inherits the Codex global default.
+ */
 const toCustomProviderModelOption = (
   record: CustomProviderModelRecord,
-): ProviderModelOption => ({
-  value: record.modelId,
-  label: record.model,
-  recordId: record.recordId,
-  isCustom: true,
-  config: toPublicConfig(record.config),
-});
+): ProviderModelOption => {
+  const providerId = record.config?.codexProviderId;
+  return {
+    value: record.modelId,
+    label: providerId === undefined ? record.model : `${record.model} · ${providerId}`,
+    recordId: record.recordId,
+    isCustom: true,
+    config: toPublicConfig(record.config),
+  };
+};
 
 const mergeProviderModels = (
   predefined: ProviderModelsDefinition,
@@ -120,15 +165,42 @@ const resolveSecretRows = (
     }
     env.push({ key: row.key, kind: 'secret', value: kept.value });
   }
-  return { env };
+  return {
+    ...(config.codexProviderId === undefined ? {} : { codexProviderId: config.codexProviderId }),
+    env,
+  };
 };
 
 /**
- * Semantic validation of a model's env rows: allowlisted keys (the same
- * function launch profiles use), one row per key, and `value` present exactly
- * when the kind carries one. Rejected config is never persisted.
+ * Reads the Codex provider registry once for the write that is about to happen.
+ *
+ * The thunk is only invoked when a config actually declares `codexProviderId`,
+ * so an ordinary Claude/Codex row that inherits the Codex default never touches
+ * the settings file.
+ */
+const readInstalledCodexProviders = (): CodexProviderRegistryReading | null =>
+  readCodexProviderRegistryPort()?.read() ?? null;
+
+/**
+ * Semantic validation of a model's env rows and its upstream-provider binding.
+ *
+ * Env rows: allowlisted keys (the same function launch profiles use), one row
+ * per key, and `value` present exactly when the kind carries one.
+ *
+ * `codexProviderId`: a declared id must name a provider the project registry
+ * defines (or one Codex reserves for its built-ins). A missing registry, an
+ * unknown id, or an id that was deleted since the entry was written is refused
+ * with a readable 409 carrying the id; nothing is persisted. An undeclared id
+ * is left out entirely, which is the "inherit the Codex global default" path
+ * every pre-existing row takes.
+ *
+ * Rejected config is never persisted: every caller validates before it touches
+ * the catalog.
  */
-const validateModelConfig = (config: ProviderModelConfig): ProviderModelConfig => {
+const validateModelConfig = (
+  config: ProviderModelConfig,
+  readRegistry: () => CodexProviderRegistryReading | null,
+): ProviderModelConfig => {
   const seen = new Set<string>();
   for (const row of config.env) {
     if (!isAllowedLaunchEnvKey(row.key)) {
@@ -142,12 +214,37 @@ const validateModelConfig = (config: ProviderModelConfig): ProviderModelConfig =
       throw invalidConfig(`Environment variable ${row.key} has an invalid value for kind ${row.kind}.`);
     }
   }
-  return config;
+
+  if (config.codexProviderId === undefined) {
+    return config;
+  }
+
+  const codexProviderId = config.codexProviderId.trim();
+  if (!codexProviderId) {
+    throw invalidConfig('codexProviderId must name a provider.');
+  }
+  const registry = readRegistry();
+  const known = registry !== null && (
+    registry.reservedIds.includes(codexProviderId)
+    || registry.providers.some((provider) => provider.id === codexProviderId)
+  );
+  if (!known) {
+    throw new AppError(
+      `Codex provider "${codexProviderId}" does not exist; save it in the Codex provider settings or omit codexProviderId to inherit the Codex default.`,
+      {
+        code: 'CODEX_PROVIDER_UNKNOWN',
+        statusCode: 409,
+        details: { codexProviderId },
+      },
+    );
+  }
+  return { ...config, codexProviderId };
 };
 
 const normalizeCustomModelInput = (
   input: CustomProviderModelInput,
   stored: ProviderModelConfig | null = null,
+  readRegistry: () => CodexProviderRegistryReading | null = () => null,
 ): CustomProviderModelInput => ({
   id: input.id.trim(),
   model: input.model.trim(),
@@ -156,7 +253,7 @@ const normalizeCustomModelInput = (
     : {
       config: input.config === null
         ? null
-        : validateModelConfig(resolveSecretRows(input.config, stored)),
+        : validateModelConfig(resolveSecretRows(input.config, stored), readRegistry),
     }),
 });
 
@@ -179,7 +276,15 @@ const withSourceConfig = (
   sourceConfig: ProviderModelConfig | null,
 ): CustomProviderModelInput => (
   input.config === undefined && sourceConfig !== null
-    ? { ...input, config: { env: sourceConfig.env.map((row) => ({ ...row })) } }
+    ? {
+      ...input,
+      config: {
+        ...(sourceConfig.codexProviderId === undefined
+          ? {}
+          : { codexProviderId: sourceConfig.codexProviderId }),
+        env: sourceConfig.env.map((row) => ({ ...row })),
+      },
+    }
     : input
 );
 
@@ -213,6 +318,10 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
   const resolveProvider = dependencies.resolveProvider ?? providerRegistry.resolveProvider;
   const catalog = dependencies.catalog ?? providerModelsDb;
   const sessions = dependencies.sessions ?? sessionsDb;
+  // Read lazily: the registry port is installed by the settings module at boot, which may
+  // evaluate after this module, so capturing its reading here would freeze a null.
+  const codexProviders = dependencies.codexProviders ?? { read: readInstalledCodexProviders };
+  const readCodexRegistry = (): CodexProviderRegistryReading | null => codexProviders.read();
 
   const getProviderModels = async (provider: LLMProvider): Promise<ProviderModelsDefinition> => {
     const predefined = await resolveProvider(provider).models.getSupportedModels();
@@ -319,7 +428,7 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
     stored: ProviderModelConfig | null = null,
   ): Promise<{ model: ProviderModelOption; models: ProviderModelsDefinition }> => {
     const predefined = await resolveProvider(provider).models.getSupportedModels();
-    const normalized = normalizeCustomModelInput(input, stored);
+    const normalized = normalizeCustomModelInput(input, stored, readCodexRegistry);
     assertModelIdAvailable(provider, predefined, normalized.id);
 
     try {
@@ -369,7 +478,7 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
   ): Promise<{ model: ProviderModelOption; models: ProviderModelsDefinition }> => {
     const predefined = await resolveProvider(provider).models.getSupportedModels();
     const existing = readCustomModel(provider, recordId);
-    const normalized = normalizeCustomModelInput(input, existing.config);
+    const normalized = normalizeCustomModelInput(input, existing.config, readCodexRegistry);
     assertModelIdAvailable(provider, predefined, normalized.id, recordId);
 
     try {
@@ -416,9 +525,7 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
     };
   };
 
-  const readRecordedSessionSelection = (
-    sessionId: string,
-  ): { model: string | null; effort: string | null; permissionMode: string | null } | null => {
+  const readRecordedSessionSelection = (sessionId: string): RecordedSessionSelection | null => {
     const session = sessions.getSessionById(sessionId);
     if (!session) {
       return null;
@@ -428,9 +535,20 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
       model: session.model?.trim() || null,
       effort: session.effort?.trim() || null,
       permissionMode: session.permission_mode?.trim() || null,
+      modelProviderId: session.model_provider_id?.trim() || null,
     };
   };
 
+  // The display/resume half of the service: which model a session is on, and
+  // which model a resume should launch. Composed here because it reads the same
+  // catalog and row access this service owns.
+  const { resolveSessionModel, resolveResumeModel } = createSessionModelResolver({
+    readRecordedSelection: readRecordedSessionSelection,
+    readCodexRegistry,
+    getProviderModels,
+    getCurrentActiveModel,
+  });
+
   /**
    * Records the model one session runs with.
    *
@@ -439,6 +557,14 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
    * ran with. Sessions the app has not created yet (no row) are ignored rather
    * than treated as an error: the client keeps its own pending selection and
    * the value lands on the row with the first send.
+   *
+   * The session's upstream provider is recorded here too, on the first write
+   * that names a model bound to one (`model_provider_id`). This is the send
+   * funnel, so it is the one place every first turn passes through. A later
+   * selection that would run under a DIFFERENT provider is refused — with the
+   * fork/new-session action in the message — because the provider runtime
+   * cannot switch it in place; the same selection on the same provider is an
+   * ordinary model change.
    */
   const setSessionModel = (
     provider: LLMProvider,
@@ -456,17 +582,56 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
       return null;
     }
 
+    const registry = readCodexRegistry();
+    const requestedProviderId = resolveModelProviderId(catalog, provider, normalizedModel);
+    assertProviderSwitchAllowed(recordedSelection.modelProviderId, requestedProviderId, normalizedModel);
+    assertProviderAvailable(registry, requestedProviderId, normalizedModel);
+
     sessions.setSessionModel(normalizedSessionId, normalizedModel);
+    if (requestedProviderId && !recordedSelection.modelProviderId) {
+      sessions.setSessionModelProviderId(normalizedSessionId, requestedProviderId);
+    }
     return {
       provider,
       sessionId: normalizedSessionId,
       model: normalizedModel,
       effort: recordedSelection.effort,
       permissionMode: recordedSelection.permissionMode,
+      ...readRecordedProviderBinding(registry, recordedSelection.modelProviderId ?? requestedProviderId),
       source: 'session',
     };
   };
 
+  /**
+   * Answers whether a send may name this model for this session, throwing the
+   * same readable refusal the record path throws.
+   *
+   * `chat-websocket.service.ts` calls this BEFORE the session's run is admitted.
+   * The record path (`setSessionModel`) would refuse the equal case, but it runs
+   * after the run is reserved — and a throw there would leave a `running` run
+   * with no process behind it. A missing row, or a session with no recorded
+   * binding, is not a refusal: the first send of a session is exactly where a
+   * binding is allowed to be established.
+   */
+  const assertSessionProviderSwitch = (
+    provider: LLMProvider,
+    sessionId: string,
+    model: string,
+  ): void => {
+    const normalizedSessionId = sessionId.trim();
+    const normalizedModel = model.trim();
+    if (!normalizedSessionId || !normalizedModel) {
+      return;
+    }
+    const recordedSelection = readRecordedSessionSelection(normalizedSessionId);
+    if (!recordedSelection) {
+      return;
+    }
+    const requestedProviderId = resolveModelProviderId(catalog, provider, normalizedModel);
+    assertProviderSwitchAllowed(recordedSelection.modelProviderId, requestedProviderId, normalizedModel);
+    assertProviderAvailable(readCodexRegistry(), requestedProviderId, normalizedModel);
+  };
+
   /**
    * Records the reasoning effort one session runs with.
    *
@@ -541,109 +706,6 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
     };
   };
 
-  /**
-   * Answers "which model is this session using?" for every display surface.
-   *
-   * Precedence, highest first:
-   *   1. the model recorded on the session row;
-   *   2. the provider's own session state for externally-created sessions;
-   *   3. `requestedModel`, the client's current default;
-   *   4. the source-controlled provider catalog default.
-   *
-   * The permission mode rides along unchanged: it has no provider-side source
-   * and no client-supplied fallback (the client is not allowed to persist one),
-   * so the only two answers are the recorded mode or NULL for "never sent one".
-   */
-  const resolveSessionModel = async (
-    provider: LLMProvider,
-    options: { sessionId?: string | null; requestedModel?: string | null } = {},
-  ): Promise<ProviderSessionModel> => {
-    const normalizedSessionId = typeof options.sessionId === 'string' ? options.sessionId.trim() : '';
-    const normalizedRequestedModel = typeof options.requestedModel === 'string'
-      ? options.requestedModel.trim()
-      : '';
-
-    if (normalizedSessionId) {
-      const recordedSelection = readRecordedSessionSelection(normalizedSessionId);
-      if (recordedSelection?.model) {
-        return {
-          provider,
-          sessionId: normalizedSessionId,
-          model: recordedSelection.model,
-          effort: recordedSelection.effort,
-          permissionMode: recordedSelection.permissionMode,
-          source: 'session',
-        };
-      }
-
-      const providerCatalog = await getProviderModels(provider);
-      const providerModel = await getCurrentActiveModel(provider, normalizedSessionId);
-      const resolvedProviderModel = providerModel.model?.trim();
-      if (resolvedProviderModel && resolvedProviderModel !== providerCatalog.DEFAULT) {
-        return {
-          provider,
-          sessionId: normalizedSessionId,
-          model: resolvedProviderModel,
-          effort: recordedSelection?.effort ?? null,
-          permissionMode: recordedSelection?.permissionMode ?? null,
-          source: 'provider',
-        };
-      }
-
-      return {
-        provider,
-        sessionId: normalizedSessionId,
-        model: normalizedRequestedModel || providerCatalog.DEFAULT,
-        effort: recordedSelection?.effort ?? null,
-        permissionMode: recordedSelection?.permissionMode ?? null,
-        source: normalizedRequestedModel ? 'session' : 'default',
-      };
-    }
-
-    if (normalizedRequestedModel) {
-      return {
-        provider,
-        sessionId: null,
-        model: normalizedRequestedModel,
-        effort: null,
-        permissionMode: null,
-        source: 'session',
-      };
-    }
-
-    const providerCatalog = await getProviderModels(provider);
-    return {
-      provider,
-      sessionId: null,
-      model: providerCatalog.DEFAULT,
-      effort: null,
-      permissionMode: null,
-      source: 'default',
-    };
-  };
-
-  /**
-   * Picks the model one resumed provider run should use.
-   *
-   * Provider-global state is deliberately ignored because it must never
-   * override the model explicitly selected in the composer.
-   */
-  const resolveResumeModel = async (
-    provider: LLMProvider,
-    sessionId: string | undefined,
-    requestedModel?: string | null,
-  ): Promise<string | undefined> => {
-    void provider;
-    const normalizedRequestedModel = typeof requestedModel === 'string' ? requestedModel.trim() : '';
-    const normalizedSessionId = sessionId?.trim();
-    if (!normalizedSessionId) {
-      return normalizedRequestedModel || undefined;
-    }
-
-    const recordedModel = readRecordedSessionSelection(normalizedSessionId)?.model;
-    return recordedModel || normalizedRequestedModel || undefined;
-  };
-
   /**
    * SERVER-INTERNAL ONLY: returns the stored config including secret values
    * for the launch compiler. Never mount this on a route or return its result
@@ -662,6 +724,7 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
     updateCustomModel,
     deleteCustomModel,
     setSessionModel,
+    assertSessionProviderSwitch,
     setSessionEffort,
     setSessionPermissionMode,
     resolveSessionModel,

package/server/modules/providers/services/provider-runtime.service.ts

@@ -321,6 +321,9 @@ async function defaultResidentLaunchOptions(
     model: selection.model,
     effort: selection.effort ?? undefined,
     permissionMode: selection.permissionMode ?? undefined,
+    // The upstream provider the session's model was bound to (row
+    // `model_provider_id`); the resident driver compiles it into `-c` spawn args.
+    ...(selection.modelProviderId ? { modelProviderId: selection.modelProviderId } : {}),
   };
 }
 

package/server/modules/providers/services/session-model-resolver.ts

@@ -0,0 +1,180 @@
+/**
+ * Which model — and which upstream provider binding — one session runs with.
+ *
+ * WHY IT IS ITS OWN FILE. The answer has four sources of truth in a fixed
+ * precedence (the recorded row, the provider's own session state, the client's
+ * requested default, the provider catalog default), and it must agree across
+ * the `/models` picker, `/cost`, `/status`, the active-model route and both
+ * runtimes. Keeping it beside the catalog CRUD made `provider-models.service.ts`
+ * the module's every-concern file; this is the display/resume half, with the
+ * catalog and row access injected so the service stays the composition root.
+ *
+ * THE UPSTREAM PROVIDER RIDES ALONG. A session may record the upstream
+ * provider its model was bound to (`model_provider_id`). A reader gets that id
+ * back unchanged, plus the explicit mark when the registry no longer defines it
+ * — the model is never re-resolved from the catalog default because a provider
+ * disappeared. See `session-provider-binding.ts`.
+ *
+ * Consumers: `provider-models.service.ts` only. Every other module reaches
+ * these answers through `providerModelsService`, which composes this factory.
+ */
+import type { CodexProviderRegistryReading } from '@/shared/ports/codex-provider-registry.port.js';
+import type {
+  LLMProvider,
+  ProviderCurrentActiveModel,
+  ProviderModelsDefinition,
+  ProviderSessionModel,
+} from '@/shared/types.js';
+
+import { readRecordedProviderBinding } from './session-provider-binding.js';
+
+/**
+ * The selection recorded on one session row, as the resolver reads it.
+ *
+ * NULL in any member means "not recorded", which is a real answer for each:
+ * the model falls through to the provider's own state, the effort and
+ * permission mode have no provider-side source, and the provider id means no
+ * binding was ever established for this conversation.
+ */
+export type RecordedSessionSelection = {
+  model: string | null;
+  effort: string | null;
+  permissionMode: string | null;
+  modelProviderId: string | null;
+};
+
+/** The reads a model resolution needs, injected by the composition root. */
+export type SessionModelResolverDependencies = {
+  /** The session row's recorded selection, or null when no row has that id. */
+  readRecordedSelection(sessionId: string): RecordedSessionSelection | null;
+  /** The installed upstream-provider registry, or null when none is wired. */
+  readCodexRegistry(): CodexProviderRegistryReading | null;
+  /** The provider's catalog merged with its custom model rows. */
+  getProviderModels(provider: LLMProvider): Promise<ProviderModelsDefinition>;
+  /** The model the provider itself reports for one of its session ids. */
+  getCurrentActiveModel(provider: LLMProvider, sessionId?: string): Promise<ProviderCurrentActiveModel>;
+};
+
+export function createSessionModelResolver(dependencies: SessionModelResolverDependencies) {
+  const { readRecordedSelection, readCodexRegistry, getProviderModels, getCurrentActiveModel } = dependencies;
+
+  /**
+   * Answers "which model is this session using?" for every display surface.
+   *
+   * Precedence, highest first:
+   *   1. the model recorded on the session row;
+   *   2. the provider's own session state for externally-created sessions;
+   *   3. `requestedModel`, the client's current default;
+   *   4. the source-controlled provider catalog default.
+   *
+   * The permission mode rides along unchanged: it has no provider-side source
+   * and no client-supplied fallback (the client is not allowed to persist one),
+   * so the only two answers are the recorded mode or NULL for "never sent one".
+   *
+   * The upstream provider id and its problem mark come from the session row
+   * alone (see the file header): no branch below ever rewrites the model
+   * because the provider it was bound to is gone.
+   */
+  const resolveSessionModel = async (
+    provider: LLMProvider,
+    options: { sessionId?: string | null; requestedModel?: string | null } = {},
+  ): Promise<ProviderSessionModel> => {
+    const normalizedSessionId = typeof options.sessionId === 'string' ? options.sessionId.trim() : '';
+    const normalizedRequestedModel = typeof options.requestedModel === 'string'
+      ? options.requestedModel.trim()
+      : '';
+
+    if (normalizedSessionId) {
+      const recordedSelection = readRecordedSelection(normalizedSessionId);
+      const binding = readRecordedProviderBinding(
+        readCodexRegistry(),
+        recordedSelection?.modelProviderId ?? null,
+      );
+      if (recordedSelection?.model) {
+        return {
+          provider,
+          sessionId: normalizedSessionId,
+          model: recordedSelection.model,
+          effort: recordedSelection.effort,
+          permissionMode: recordedSelection.permissionMode,
+          ...binding,
+          source: 'session',
+        };
+      }
+
+      const providerCatalog = await getProviderModels(provider);
+      const providerModel = await getCurrentActiveModel(provider, normalizedSessionId);
+      const resolvedProviderModel = providerModel.model?.trim();
+      if (resolvedProviderModel && resolvedProviderModel !== providerCatalog.DEFAULT) {
+        return {
+          provider,
+          sessionId: normalizedSessionId,
+          model: resolvedProviderModel,
+          effort: recordedSelection?.effort ?? null,
+          permissionMode: recordedSelection?.permissionMode ?? null,
+          ...binding,
+          source: 'provider',
+        };
+      }
+
+      return {
+        provider,
+        sessionId: normalizedSessionId,
+        model: normalizedRequestedModel || providerCatalog.DEFAULT,
+        effort: recordedSelection?.effort ?? null,
+        permissionMode: recordedSelection?.permissionMode ?? null,
+        ...binding,
+        source: normalizedRequestedModel ? 'session' : 'default',
+      };
+    }
+
+    if (normalizedRequestedModel) {
+      return {
+        provider,
+        sessionId: null,
+        model: normalizedRequestedModel,
+        effort: null,
+        permissionMode: null,
+        modelProviderId: null,
+        modelProviderProblem: null,
+        source: 'session',
+      };
+    }
+
+    const providerCatalog = await getProviderModels(provider);
+    return {
+      provider,
+      sessionId: null,
+      model: providerCatalog.DEFAULT,
+      effort: null,
+      permissionMode: null,
+      modelProviderId: null,
+      modelProviderProblem: null,
+      source: 'default',
+    };
+  };
+
+  /**
+   * Picks the model one resumed provider run should use.
+   *
+   * Provider-global state is deliberately ignored because it must never
+   * override the model explicitly selected in the composer.
+   */
+  const resolveResumeModel = async (
+    provider: LLMProvider,
+    sessionId: string | undefined,
+    requestedModel?: string | null,
+  ): Promise<string | undefined> => {
+    void provider;
+    const normalizedRequestedModel = typeof requestedModel === 'string' ? requestedModel.trim() : '';
+    const normalizedSessionId = sessionId?.trim();
+    if (!normalizedSessionId) {
+      return normalizedRequestedModel || undefined;
+    }
+
+    const recordedModel = readRecordedSelection(normalizedSessionId)?.model;
+    return recordedModel || normalizedRequestedModel || undefined;
+  };
+
+  return { resolveSessionModel, resolveResumeModel };
+}