feat: Multi-Provider support

[juliusmarminge]

Core foundation for multi-providers with some UX improvements to nicely support multi-account codex or custom claude code instances for example

---

Note

Medium Risk
Changes the core wiring for all git text-generation calls to resolve by provider instance id, so misconfiguration or missing registry entries could break commit/PR/title generation across providers.

Overview
Switches git text-generation from kind-based routing (RoutingTextGenerationLive) to instance-based routing via a new TextGenerationLive that looks up modelSelection.instanceId in ProviderInstanceRegistry and delegates to that instance’s bound textGeneration implementation.

Refactors Codex/Claude/Cursor/OpenCode text-generation implementations into per-instance factories (make*TextGeneration(settings, env)), removes singleton *TextGenerationLive layers and provider-kind validation checks, and updates tests/integration harnesses to use ProviderDriverKind/ProviderInstanceId plus adapter-registry mocks and no-op provider event loggers. Also extends desktop persisted client settings to include providerModelPreferences.

^{Reviewed by Cursor Bugbot for commit 245ec79. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add multi-provider instance support routing all provider interactions by ProviderInstanceId

• Replaces the closed ProviderKind string union with open branded ProviderDriverKind and ProviderInstanceId types throughout contracts, server, and web, allowing multiple configured instances of the same driver (e.g. two Codex accounts).
• Introduces ProviderDriver SPI with built-in implementations for Codex, Claude, Cursor, and OpenCode; each driver's create() produces a ProviderInstance with adapter, text-generation, and snapshot closures bound to per-instance config.
• Adds ProviderInstanceRegistry and ProviderInstanceRegistryLive to manage live instances; ProviderRegistryLive is refactored to key snapshots and cache files by instanceId and react dynamically to instance add/remove/rebuild events.
• ModelSelection wire format migrates from { provider, model } to { instanceId, model } with a decode-time transform that promotes legacy provider strings; OrchestrationSession gains an optional providerInstanceId.
• Web settings UI gains AddProviderInstanceDialog and ProviderInstanceCard for creating and editing provider instances; ModelPickerContent, ModelPickerSidebar, and ChatComposer are refactored to select and display models per-instance.
• Sensitive provider instance environment variables are stored in a secret store and redacted before returning settings to clients.
• Adds DB migrations 27 and 28 adding nullable provider_instance_id columns and indexes to provider_session_runtime and projection_thread_sessions.
• Risk: ModelSelection shape changes from provider to instanceId on the wire; any client or stored event that contains the old shape will be migrated at decode time, but callers constructing raw objects must switch to instanceId.

^{Macroscope summarized 245ec79.}

---

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: d4436d2e-a060-4b92-a429-f1085c437e1b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/provider-instance-registry

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: CodexAdapter hardcoded instanceId check breaks custom instances
  • Removed the hardcoded instanceId === "codex" check and replaced it with an unconditional input.modelSelection check, matching the pattern already used in ClaudeAdapter.

Or push these changes by commenting:

@cursor push 84b0d74e0a

Preview (84b0d74e0a)

diff --git a/apps/server/src/provider/Layers/CodexAdapter.ts b/apps/server/src/provider/Layers/CodexAdapter.ts
--- a/apps/server/src/provider/Layers/CodexAdapter.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.ts
@@ -1368,10 +1368,8 @@
             ? { resumeCursor: input.resumeCursor }
             : {}),
           runtimeMode: input.runtimeMode,
-          ...(input.modelSelection?.instanceId === "codex"
-            ? { model: input.modelSelection.model }
-            : {}),
-          ...(input.modelSelection?.instanceId === "codex" &&
+          ...(input.modelSelection ? { model: input.modelSelection.model } : {}),
+          ...(input.modelSelection &&
           getModelSelectionOptionValue(input.modelSelection, "fastMode") === true
             ? { serviceTier: "fast" }
             : {}),

_{You can send follow-ups to the cloud agent here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Hardcoded "codex" provider in unknown-driver error path
  • Replaced the hardcoded provider: "codex" with provider: threadInstanceId so the error correctly identifies the actual unknown driver slug.
• ✅ Fixed: Instance-level comparison blocks custom instances of same driver
  • Added a resolveDriverKindForInstanceId helper that maps instance IDs to their underlying driver kind via ServerSettings.providerInstances, so custom instances resolve to their driver for the narrowing check and the provider-switch guard now compares driver kinds instead of instance IDs.

Or push these changes by commenting:

@cursor push b84bfe908a

Preview (b84bfe908a)

diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
@@ -170,6 +170,22 @@
       ),
     );
 
+  const resolveDriverKindForInstanceId = (
+    instanceId: string,
+  ): Effect.Effect<ProviderKind | undefined> => {
+    if (Schema.is(ProviderKind)(instanceId)) {
+      return Effect.succeed(instanceId);
+    }
+    return serverSettingsService.getSettings.pipe(
+      Effect.map((settings) => {
+        const instances = settings.providerInstances as Record<string, { driver?: string }>;
+        const driver = instances[instanceId]?.driver;
+        return driver !== undefined && Schema.is(ProviderKind)(driver) ? driver : undefined;
+      }),
+      Effect.orElseSucceed(() => undefined),
+    );
+  };
+
   const threadModelSelections = new Map<string, ModelSelection>();
 
   const appendProviderFailureActivity = (input: {
@@ -277,29 +293,28 @@
       ? thread.session.providerName
       : undefined;
     const requestedModelSelection = options?.modelSelection;
-    // The thread's model selection is keyed by `instanceId` (an open slug);
-    // for built-in drivers the default instance id equals the driver id, so
-    // narrow back to the closed `ProviderKind` here. Threads persisted
-    // against a fork/unknown driver are surfaced via a structured error
-    // rather than silently routed to the wrong provider.
-    const threadProviderCandidate: string = currentProvider ?? thread.modelSelection.instanceId;
-    if (!Schema.is(ProviderKind)(threadProviderCandidate)) {
+    const threadInstanceId: string = currentProvider ?? thread.modelSelection.instanceId;
+    const resolvedThreadDriver: ProviderKind | undefined =
+      yield* resolveDriverKindForInstanceId(threadInstanceId);
+    if (resolvedThreadDriver === undefined) {
       return yield* new ProviderAdapterRequestError({
-        provider: "codex",
+        provider: threadInstanceId,
         method: "thread.turn.start",
-        detail: `Thread '${threadId}' references unknown provider driver '${threadProviderCandidate}'. The driver is not installed in this build (rolled-back / fork mismatch).`,
+        detail: `Thread '${threadId}' references unknown provider driver '${threadInstanceId}'. The driver is not installed in this build (rolled-back / fork mismatch).`,
       });
     }
-    const threadProvider: ProviderKind = threadProviderCandidate;
-    if (
-      requestedModelSelection !== undefined &&
-      requestedModelSelection.instanceId !== threadProvider
-    ) {
-      return yield* new ProviderAdapterRequestError({
-        provider: threadProvider,
-        method: "thread.turn.start",
-        detail: `Thread '${threadId}' is bound to provider '${threadProvider}' and cannot switch to '${requestedModelSelection.instanceId}'.`,
-      });
+    const threadProvider: ProviderKind = resolvedThreadDriver;
+    if (requestedModelSelection !== undefined) {
+      const requestedDriver: ProviderKind | undefined = yield* resolveDriverKindForInstanceId(
+        requestedModelSelection.instanceId,
+      );
+      if (requestedDriver !== threadProvider) {
+        return yield* new ProviderAdapterRequestError({
+          provider: threadProvider,
+          method: "thread.turn.start",
+          detail: `Thread '${threadId}' is bound to provider '${threadProvider}' and cannot switch to '${requestedModelSelection.instanceId}'.`,
+        });
+      }
     }
     const preferredProvider: ProviderKind = threadProvider;
     const desiredModelSelection = requestedModelSelection ?? thread.modelSelection;

_{You can send follow-ups to the cloud agent here.}

[macroscopeapp]

🟡 Medium src/settings.ts:195

ModelSelectionPatch accepts instanceId but callers still sending provider will have that key silently ignored, leaving instanceId undefined. This breaks backward compatibility for any API calls or persisted patches using the old field name. Consider adding a decode transformation that maps provider to instanceId if present.

Also found in 1 other location(s)

apps/server/src/provider/Layers/ClaudeAdapter.ts:557

The condition input.modelSelection?.instanceId === "claudeAgent" will likely fail for most Claude instances. According to ClaudeDriver metadata, supportsMultipleInstances: true, meaning instances can have arbitrary IDs (e.g., "claude-work", "claude-personal"). The original code checked provider === "claudeAgent" which is a constant discriminant on all Claude adapters (as defined in ClaudeAdapterShape). After this change, effort and model settings will only be applied when an instance happens to have the exact ID "claudeAgent", causing rawEffort to be null and claudeModel to be undefined for all other Claude instances.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file packages/contracts/src/settings.ts around line 195:

`ModelSelectionPatch` accepts `instanceId` but callers still sending `provider` will have that key silently ignored, leaving `instanceId` undefined. This breaks backward compatibility for any API calls or persisted patches using the old field name. Consider adding a decode transformation that maps `provider` to `instanceId` if present.

Evidence trail:
packages/contracts/src/settings.ts:195-199 (ModelSelectionPatch schema - no `provider` field), packages/contracts/src/orchestration.ts:75-104 (ModelSelection has provider→instanceId transform), packages/contracts/src/orchestration.test.ts:641 (test confirms ModelSelection migration), packages/contracts/src/ws.ts:112 and packages/contracts/src/rpc.ts:163 (ServerSettingsPatch exposed via API)

Also found in 1 other location(s):
- apps/server/src/provider/Layers/ClaudeAdapter.ts:557 -- The condition `input.modelSelection?.instanceId === "claudeAgent"` will likely fail for most Claude instances. According to `ClaudeDriver` metadata, `supportsMultipleInstances: true`, meaning instances can have arbitrary IDs (e.g., "claude-work", "claude-personal"). The original code checked `provider === "claudeAgent"` which is a constant discriminant on all Claude adapters (as defined in `ClaudeAdapterShape`). After this change, effort and model settings will only be applied when an instance happens to have the exact ID "claudeAgent", causing `rawEffort` to be `null` and `claudeModel` to be `undefined` for all other Claude instances.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Disabled instance check missing in text generation routing
  • Added an instance.enabled check in resolveInstance so disabled provider instances now surface a TextGenerationError instead of silently delegating to the underlying text generation closure.
• ✅ Fixed: Empty registry when initial settings read fails
  • Changed the fallback from an empty ProviderInstanceConfigMap to DEFAULT_SERVER_SETTINGS so that built-in driver default instances are always materialized even when the initial settings read fails.

Or push these changes by commenting:

@cursor push 1a12ea9124

Preview (1a12ea9124)

diff --git a/apps/server/src/git/Layers/TextGenerationLive.ts b/apps/server/src/git/Layers/TextGenerationLive.ts
--- a/apps/server/src/git/Layers/TextGenerationLive.ts
+++ b/apps/server/src/git/Layers/TextGenerationLive.ts
@@ -51,7 +51,14 @@
   registry.getInstance(instanceId).pipe(
     Effect.flatMap((instance) =>
       instance
-        ? Effect.succeed(instance.textGeneration)
+        ? instance.enabled
+          ? Effect.succeed(instance.textGeneration)
+          : Effect.fail(
+              new TextGenerationError({
+                operation,
+                detail: `Provider instance '${instanceId}' is disabled.`,
+              }),
+            )
         : Effect.fail(
             new TextGenerationError({
               operation,

diff --git a/apps/server/src/provider/Layers/ProviderInstanceRegistryHydration.ts b/apps/server/src/provider/Layers/ProviderInstanceRegistryHydration.ts
--- a/apps/server/src/provider/Layers/ProviderInstanceRegistryHydration.ts
+++ b/apps/server/src/provider/Layers/ProviderInstanceRegistryHydration.ts
@@ -42,6 +42,7 @@
  * @module provider/Layers/ProviderInstanceRegistryHydration
  */
 import {
+  DEFAULT_SERVER_SETTINGS,
   defaultInstanceIdForDriver,
   type ProviderInstanceConfig,
   type ProviderInstanceConfigMap,
@@ -158,13 +159,10 @@
 > = Layer.unwrap(
   Effect.gen(function* () {
     const serverSettings = yield* ServerSettingsService;
-    const initialSettings: ServerSettings | undefined = yield* serverSettings.getSettings.pipe(
-      Effect.orElseSucceed(() => undefined),
+    const initialSettings: ServerSettings = yield* serverSettings.getSettings.pipe(
+      Effect.orElseSucceed(() => DEFAULT_SERVER_SETTINGS),
     );
-    const initialConfigMap =
-      initialSettings === undefined
-        ? ({} as ProviderInstanceConfigMap)
-        : deriveProviderInstanceConfigMap(initialSettings);
+    const initialConfigMap = deriveProviderInstanceConfigMap(initialSettings);
 
     const mutableLayer = ProviderInstanceRegistryMutableLayer({
       drivers: BUILT_IN_DRIVERS,

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Metric test asserts branded type against plain string attribute
  • Changed the test setup to use ProviderDriverKind.make() for both the initial value and the reassignment, so the recorded attribute uses a branded type consistent with the assertion and real production usage.

Or push these changes by commenting:

@cursor push c9731a0748

Preview (c9731a0748)

diff --git a/apps/server/src/observability/Metrics.test.ts b/apps/server/src/observability/Metrics.test.ts
--- a/apps/server/src/observability/Metrics.test.ts
+++ b/apps/server/src/observability/Metrics.test.ts
@@ -76,10 +76,10 @@
     Effect.gen(function* () {
       const counter = Metric.counter("with_metrics_lazy_total");
       const timer = Metric.timer("with_metrics_lazy_duration");
-      let provider = "unknown";
+      let provider: string = ProviderDriverKind.make("unknown");
 
       yield* Effect.sync(() => {
-        provider = "codex";
+        provider = ProviderDriverKind.make("codex");
       }).pipe(
         withMetrics({
           counter,

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 01f2b68. Configure here.}