Drivers, instances, registries, and multi-instance routing

“Which provider owns this thread?” sounds like one lookup. In the implementation it is an identity chain:

T3 thread → persisted provider-instance id → current ProviderInstance
          → captured adapter → native session / resume cursor

The driver kind travels beside that chain as an implementation and consistency label. A native account may be visible in a discovery snapshot. Neither replaces the instance id as the normal route.

This separation is what lets codex_personal and codex_work use the same Codex driver with different homes, environment, credentials, processes, snapshots, and adapter state.

The identity ladder

 * Splits the historical "provider kind" concept into two:
 *
 *   - `ProviderDriverKind` is the implementation kind selector (e.g. codex,
 *     claudeAgent, a fork's `ollama`, …). It picks which driver package
 *     handles the protocol, the probe, the adapter, and text generation.
 *
 *   - `ProviderInstanceId` is the routing key (a user-defined slug).
 *     Threads, sessions, runtime events, and persisted bindings reference
 *     instance ids — never driver kinds — so a user can configure multiple
 *     instances of the same driver (e.g. `codex_personal` + `codex_work`),
 *     each with independent driver-specific configuration.
 *
 * Forward/backward compatibility invariant
 * ----------------------------------------
 * `ProviderDriverKind` is intentionally an **open** branded slug, not a closed
 * literal union. The server hosts forks, ships in PRs that add drivers, and
 * users frequently roll between branches and forks. Any of those paths can
 * leave `ServerSettings`, persisted thread state, or session bindings
 * referencing a driver that the currently-running build does not know about.
 *
 * The rule: parsing any of those payloads must always succeed, and the
 * runtime is responsible for marking the unknown driver/instance as
 * "unavailable" rather than crashing. Built-in drivers shipped by the core
 * product happens to register in a given build is not part of the contract
 * layer. Driver availability is discovered through the runtime registry.
 *
 * Driver-specific configuration is similarly opaque at the contracts layer:
 * drivers live in (or will be extracted to) their own packages and own their
 * config schemas. The contracts package only knows the envelope.

ProviderDriverKind is intentionally not a closed five-literal union. The shipped build registers Codex, Claude, Cursor, Grok, and OpenCode, but settings and persisted state can outlive a build, move between forks, or refer to a driver that is absent after rollback. Schema decoding accepts any valid slug; the runtime makes absence visible.

Drivers are factories; instances are scoped records

 * `ProviderDriver` is a record, not a Context.Service. The thing it produces
 * (`ProviderInstance`) is also a record — three captured closures
 * (`snapshot`, `adapter`, `textGeneration`), an id, and a driver kind. There
 * are intentionally no per-driver Context tags because tags are
 * singleton-per-runtime and we need many instances of the same driver.
 *
 * The only Effect service involved is `ProviderInstanceRegistry`, which
 * owns the live `Map<InstanceId, ProviderInstance>` and is itself a
 * singleton.
 *
 * Driver factories are functions of `(typed config, env)` where:
 *   - `typed config` is decoded once by the registry via `configSchema`,
 *     so drivers never deal with raw `unknown`.
 *   - `env` flows through Effect's R channel. Each driver declares the
 *     subset of infrastructure services it needs (FileSystem,
 *     ChildProcessSpawner, …) on its `create` return type; the registry
 *     layer's R is the union of those, and the runtime layer satisfies it.

/**
 * One materialized provider instance. Held by the registry, looked up by
 * `instanceId`, torn down by closing the scope it was created in.
 *
 * The three "shape" fields are captured closures owned by this instance —
 * stopping one instance cannot affect another, and starting a second
 * instance of the same driver does not reach into the first instance's
 * state.
 */
export interface ProviderInstance {
  readonly instanceId: ProviderInstanceId;
  readonly driverKind: ProviderDriverKind;
  readonly continuationIdentity: ProviderContinuationIdentity;
  readonly displayName: string | undefined;
  readonly accentColor?: string | undefined;
  readonly enabled: boolean;
  readonly snapshot: ServerProviderShape;
  readonly adapter: ProviderAdapterShape<ProviderAdapterError>;
  readonly textGeneration: TextGeneration.TextGeneration["Service"];
}
 
export interface ProviderContinuationIdentity {
  readonly driverKind: ProviderDriverKind;
  readonly continuationKey: string;
}
 
export function defaultProviderContinuationIdentity(input: {
  readonly driverKind: ProviderDriverKind;
  readonly instanceId: ProviderInstanceId;
}): ProviderContinuationIdentity {
  return {
    driverKind: input.driverKind,
    continuationKey: `${input.driverKind}:instance:${input.instanceId}`,
  };
}
 
/**
 * Inputs the registry passes to a driver's `create` function.
 *
 * `config` is the typed payload — already decoded by the registry through
 * `driver.configSchema`. Drivers never decode their own raw envelope.
 */
export interface ProviderDriverCreateInput<Config> {
  readonly instanceId: ProviderInstanceId;
  readonly displayName: string | undefined;
  readonly accentColor?: string | undefined;
  readonly environment: ProviderInstanceEnvironment;
  readonly enabled: boolean;
  readonly config: Config;
}
 
/**
 * Driver SPI — registered as a plain value, not a Layer.
 *
 * `Config` is whatever the driver decoded from
 * `ProviderInstanceConfig.config`. `R` is the union of infrastructure
 * services the driver depends on; the registry layer aggregates `R` across
 * all registered drivers and the runtime supplies them.
 *
 * `create` is responsible for *all* per-instance state — process handles,
 * pubsub topics, refs, file watchers — and must release them when its
 * scope closes. Two calls to `create` with different `instanceId` /
 * `config` MUST yield instances with no shared mutable state.

A ProviderDriver contributes:

• an open driverKind and static presentation metadata;
• a schema for its opaque config envelope and a typed default;
• a scoped create function.

The registry decodes config once, then passes the typed value, instance id, presentation overrides, effective enabled flag, and materialized environment into create. The result is a ProviderInstance containing three captured closures: discovery snapshot, provider adapter, and text generation.

This record-based SPI avoids the singleton trap. Two Context tags named “Codex” would still describe one service per Effect environment; two ordinary instance records can each own different Refs, PubSubs, child processes, file watchers, and finalizers.

Settings hydrate an explicit map over legacy defaults

T3 Code is midway through a provider-instance migration. Settings contain both:

• legacy typed blobs under settings.providers.<kind>;
• a new providerInstances record whose keys are instance ids and whose values carry driver, opaque config, generic environment, enabled state, and optional presentation.

Hydration begins with the explicit map. For each built-in driver it computes the default instance id—literally the driver slug. Only if that key is absent does it synthesize an instance from the legacy blob. An explicit providerInstances.codex entry therefore wins over providers.codex; a custom codex_work exists alongside either default.

Enabled state has its own precedence. Explicit false in the instance envelope or decoded driver config always disables. Otherwise the envelope value wins, then the driver config value, then the default is enabled.

flowchart LR
  S[settings changed] --> H[explicit map + missing legacy defaults]
  H --> Q{unchanged live identity?}
  Q -->|yes| K[retain existing scoped instance]
  Q -->|no| C[close prior child scope if present]
  C --> X{replacement still configured?}
  X -->|no · removed| M[set live Ref, then unavailable Ref]
  X -->|yes| D{driver + config valid?}
  D -->|yes| L[create scoped live instance]
  D -->|no| U[build unavailable shadow]
  K --> M
  L --> M
  U --> M
  M --> G{entries, order, or shadows changed?}
  G -->|no| N[no change tick]
  G -->|yes| T[publish one registry change tick]
  T --> P[discovery registry re-pulls]
  T --> A[ProviderService re-subscribes]
  B[(durable thread binding)] -.next eligible operation.-> R[adopt or resume]
  A --> R

Unavailable shadows preserve configuration truth

Three construction failures become UI-visible shadows instead of server-boot failures:

1. the driver slug is valid but not registered in this build;
2. the registered driver’s config decoder rejects the opaque value;
3. driver creation returns ProviderDriverError.

The shadow is disabled, not installed, in error status, has unknown auth, carries the exact unavailable reason, and appears in discovery aggregation. It is excluded from live adapter lookup and listInstances, so a caller cannot accidentally route a turn to a presentation-only object.

This is rollback/fork tolerance: “I understand the saved shape but cannot run it” is represented as product state, not a corrupt settings file.

Environment values are materialized, not sandboxed

Every instance can define generic environment entries. Sensitive entries are persisted in the server secret store under a name derived from instance id and variable name. Client-facing settings replace their value with an empty string and set valueRedacted: true; server-internal settings materialize the secret before driver construction. A redacted patch preserves the existing secret.

At process construction, the materialized instance environment overlays inherited process.env. An intentional empty string overrides the inherited value. This is ordinary child-process configuration—not isolation from the parent environment.

Discovery and routing are two registries

ProviderRegistry aggregates snapshots for presentation: availability, models, authentication, health, maintenance state, and per-instance refresh streams. It can hydrate a correlated cache at boot and retain selected prior model metadata while a fresh probe is partial.

ProviderAdapterRegistry resolves live behavior. It is a stateless facade over the instance registry: getByInstance, getInstanceInfo, listInstances, and a change stream. Snapshot presence is not sufficient to route; a shadow is visible to the first registry and absent from the second.

These surfaces all key by instance id, but their correlation checks live at different boundaries. ProviderRegistry validates that a discovery snapshot’s driver and instance match its source. ProviderService performs the corresponding check for hot runtime events. ProviderAdapterRegistry is the exact live lookup/list/change facade; it does not perform either payload-correlation check.

The durable route is recovered lazily

For an operation such as send, interrupt, approval, structured input, or rollback, ProviderService performs this decision:

1. load the persisted binding for the T3 thread;
2. require its instance id and resolve that exact current adapter;
3. if the adapter already has the thread session, route immediately;
4. otherwise, when recovery is allowed, invoke the recovery helper; it rechecks the adapter and can list, adopt, and upsert an existing session;
5. if that recheck finds no listed session, require an opaque resume cursor;
6. restore persisted cwd/model/runtime mode, prepare MCP, and call startSession with that cursor;
7. validate the returned driver and update the durable binding.

stopSession deliberately does not recover a stopped process merely to stop it. Starting a new session also stops stale live sessions for the same T3 thread on other current instances.

flowchart TB
  O[thread operation] --> B{persisted binding?}
  B -->|no| X[validation failure]
  B -->|yes| I[resolve exact instance adapter]
  I -->|missing or shadow| U[route failure]
  I -->|live| H{adapter has session?}
  H -->|yes| A[route to active live session]
  H -->|no| Q{recovery allowed?}
  Q -->|no · stop| Z[mark stopped without restart]
  Q -->|yes| J{recovery recheck finds listed session?}
  J -->|yes| A2[adopt listed live session]
  A2 --> W[upsert durable binding]
  J -->|no| C{resume cursor?}
  C -->|no| X
  C -->|yes| R[startSession with saved cursor + mode + cwd + model]
  R -->|identity valid| W
  R -->|native error| F[propagate typed failure]

Default continuation identity includes both driver and instance. Codex and Claude can override it with home/layout-derived groups, so a same-driver instance switch is compatible only when both driver kind and continuation key match. A shared native login by itself is not enough evidence.

Route a conceptual provider fleet

Use the lab to compare a legacy default, an explicit same-driver work instance, an unknown-driver shadow, a removed instance with an old binding, and a rebuilt instance with or without resume state. The animation separates settings materialization from live lookup and lazy recovery.

Evidence and remaining seams

Registry tests construct two Codex instances and verify distinct adapter, text-generation, and snapshot closures. They cover nested enabled-state precedence and boot-safe unknown-driver shadows. Settings tests verify that marked sensitive environment values do not enter settings.json, while redacted updates preserve the stored secret. ProviderService tests exercise persisted routing, resume, stale-session cleanup, event correlation, and input validation.

The inspected tests do not inject a hard crash into every instruction of child-scope replacement and subsequent lazy recovery. They also do not enforce supportsMultipleInstances: false, because the production registry does not yet implement that documented branch.