@genesislcap/ai-assistant 14.444.1 → 14.445.0

package/dist/esm/main/main.styles.js

@@ -251,6 +251,58 @@ export const styles = css `
     font-family: var(--monospace-font, ui-monospace, monospace);
   }
 
+  .provider-list {
+    animation: settings-slide-in 0.2s ease-out;
+    padding: calc(var(--design-unit) * 1.5px) calc(var(--design-unit) * 3px);
+    border-bottom: 1px solid var(--neutral-stroke-rest);
+    background-color: var(--neutral-layer-2);
+    display: flex;
+    flex-direction: column;
+    gap: calc(var(--design-unit) * 1px);
+  }
+
+  .provider-list-label {
+    font-size: 0.85em;
+    font-weight: 600;
+    color: var(--neutral-foreground-rest);
+  }
+
+  .provider-list-row {
+    display: flex;
+    align-items: baseline;
+    gap: calc(var(--design-unit) * 1.5px);
+    font-size: 0.8em;
+    color: var(--neutral-foreground-hint, var(--neutral-foreground-rest));
+    opacity: 80%;
+  }
+
+  .provider-list-row.is-current {
+    opacity: 100%;
+    color: var(--neutral-foreground-rest);
+  }
+
+  .provider-list-name {
+    font-weight: 600;
+  }
+
+  .provider-list-model {
+    font-family: var(--monospace-font, ui-monospace, monospace);
+    flex: 1;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .provider-list-badge {
+    font-size: 0.7em;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0 calc(var(--design-unit) * 0.75px);
+    border-radius: calc(var(--design-unit) * 0.5px);
+    background-color: var(--neutral-layer-3);
+    color: var(--neutral-foreground-rest);
+  }
+
   .splash-wrapper {
     position: absolute;
     inset: 0;

package/dist/esm/main/main.template.js

@@ -376,12 +376,47 @@ ${(tc) => { var _a; return (((_a = tc.foldPath) === null || _a === void 0 ? void
             ></${progressTag}>
           </div>
         `)}
-      ${when((x) => { var _a; return x.settingsOpen && ((_a = x.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.showActiveModel) !== false && x.activeModel != null; }, html `
+      ${when((x) => {
+        var _a;
+        return x.settingsOpen &&
+            ((_a = x.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.showActiveModel) !== false &&
+            x.providerStatuses.length <= 1 &&
+            x.activeModel != null;
+    }, html `
           <div class="session-stat" part="active-model">
             <span class="session-stat-label">Model</span>
             <span class="session-stat-value">${(x) => x.activeModel}</span>
           </div>
         `)}
+      ${when((x) => {
+        var _a;
+        return x.settingsOpen &&
+            ((_a = x.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.showActiveModel) !== false &&
+            x.providerStatuses.length > 1;
+    }, html `
+          <div class="provider-list" part="provider-list">
+            <div class="provider-list-label">Providers</div>
+            ${repeat((x) => x.providerStatuses, html `
+                <div
+                  class="provider-list-row ${(entry, c) => entry.name === c.parent.activeProviderName ? 'is-current' : ''}"
+                  part="provider-list-row"
+                >
+                  <span class="provider-list-name">${(entry) => entry.name}</span>
+                  <span class="provider-list-model">${(entry) => { var _a, _b; return (_b = (_a = entry.status) === null || _a === void 0 ? void 0 : _a.model) !== null && _b !== void 0 ? _b : '—'; }}</span>
+                  ${when((entry) => entry.isDefault, html `
+                      <span class="provider-list-badge" part="provider-list-default-badge">
+                        default
+                      </span>
+                    `)}
+                  ${when((entry, c) => entry.name === c.parent.activeProviderName, html `
+                      <span class="provider-list-badge" part="provider-list-current-badge">
+                        current
+                      </span>
+                    `)}
+                </div>
+              `)}
+          </div>
+        `)}
       ${when((x) => { var _a; return x.settingsOpen && ((_a = x.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.showSessionCost) !== false && x.sessionCostUsd > 0; }, html `
           <div class="session-stat" part="session-cost">
             <span class="session-stat-label">Session cost</span>

package/dist/esm/state/ai-assistant-slice.js

@@ -11,6 +11,8 @@ export const defaultSessionState = {
     contextLimit: undefined,
     sessionCostUsd: 0,
     activeModel: undefined,
+    activeProviderName: undefined,
+    providerStatuses: [],
     activeAgent: undefined,
     pinnedAgentName: null,
     flowOwnerAgentName: null,
@@ -57,6 +59,12 @@ export const aiAssistantSlice = createSlice({
         setActiveModel(state, action) {
             state.activeModel = action.payload;
         },
+        setActiveProviderName(state, action) {
+            state.activeProviderName = action.payload;
+        },
+        setProviderStatuses(state, action) {
+            state.providerStatuses = action.payload;
+        },
         setActiveAgent(state, action) {
             state.activeAgent = action.payload;
         },

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/index.ts","../src/channel/ai-activity-bus.ts","../src/channel/ai-activity-channel.ts","../src/components/halo-overlay.ts","../src/components/activity-halo/activity-halo.ts","../src/components/agent-picker/agent-picker.constants.ts","../src/components/agent-picker/agent-picker.styles.ts","../src/components/agent-picker/agent-picker.template.ts","../src/components/agent-picker/agent-picker.ts","../src/components/agent-picker/index.ts","../src/components/ai-driver/ai-driver.ts","../src/components/ai-driver/index.ts","../src/components/chat-bubble/chat-bubble.styles.ts","../src/components/chat-bubble/chat-bubble.template.ts","../src/components/chat-bubble/chat-bubble.ts","../src/components/chat-bubble/index.ts","../src/components/chat-driver/chat-driver.ts","../src/components/chat-driver/index.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.styles.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.template.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts","../src/components/chat-interaction-wrapper/index.ts","../src/components/chat-markdown/chat-markdown.ts","../src/components/chat-markdown/index.ts","../src/components/orchestrating-driver/index.ts","../src/components/orchestrating-driver/orchestrating-driver.ts","../src/components/popout-manager/index.ts","../src/components/popout-manager/popout-manager.ts","../src/config/config.ts","../src/config/define-stateful-agent.ts","../src/config/fallback-agents.ts","../src/config/index.ts","../src/main/index.ts","../src/main/main.styles.ts","../src/main/main.template.ts","../src/main/main.ts","../src/main/main.types.ts","../src/state/ai-assistant-slice.ts","../src/state/driver-registry.ts","../src/state/session-store.ts","../src/styles/ai-colours.ts","../src/styles/index.ts","../src/styles/styles.ts","../src/suggestions/chat-suggestions.ts","../src/tags/index.ts","../src/types/ai-chat-widget.ts","../src/utils/animated-panel-toggle.ts","../src/utils/history-transform.ts","../src/utils/index.ts","../src/utils/logger.ts","../src/utils/tool-fold.ts"],"version":"5.9.2"}
+{"root":["../src/index.ts","../src/channel/ai-activity-bus.ts","../src/channel/ai-activity-channel.ts","../src/components/halo-overlay.ts","../src/components/activity-halo/activity-halo.ts","../src/components/agent-picker/agent-picker.constants.ts","../src/components/agent-picker/agent-picker.styles.ts","../src/components/agent-picker/agent-picker.template.ts","../src/components/agent-picker/agent-picker.ts","../src/components/agent-picker/index.ts","../src/components/ai-driver/ai-driver.ts","../src/components/ai-driver/index.ts","../src/components/chat-bubble/chat-bubble.styles.ts","../src/components/chat-bubble/chat-bubble.template.ts","../src/components/chat-bubble/chat-bubble.ts","../src/components/chat-bubble/index.ts","../src/components/chat-driver/chat-driver.ts","../src/components/chat-driver/index.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.styles.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.template.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts","../src/components/chat-interaction-wrapper/index.ts","../src/components/chat-markdown/chat-markdown.ts","../src/components/chat-markdown/index.ts","../src/components/orchestrating-driver/index.ts","../src/components/orchestrating-driver/orchestrating-driver.ts","../src/components/popout-manager/index.ts","../src/components/popout-manager/popout-manager.ts","../src/config/config.ts","../src/config/define-stateful-agent.ts","../src/config/fallback-agents.ts","../src/config/index.ts","../src/config/validate-providers.test.ts","../src/config/validate-providers.ts","../src/main/index.ts","../src/main/main.styles.ts","../src/main/main.template.ts","../src/main/main.ts","../src/main/main.types.ts","../src/state/ai-assistant-slice.ts","../src/state/driver-registry.ts","../src/state/session-store.ts","../src/styles/ai-colours.ts","../src/styles/index.ts","../src/styles/styles.ts","../src/suggestions/chat-suggestions.ts","../src/tags/index.ts","../src/types/ai-chat-widget.ts","../src/utils/animated-panel-toggle.ts","../src/utils/history-transform.ts","../src/utils/index.ts","../src/utils/logger.ts","../src/utils/tool-fold.ts"],"version":"5.9.2"}

package/docs/migration-GENC-1262.md

@@ -0,0 +1,219 @@
+# Migration Guide — GENC-1262 (Per-Agent AI Provider)
+
+This document covers the breaking changes introduced by the `mw/GENC-1262-per-agent-model` branch and the new per-agent provider capability that motivated them.
+
+The old single-provider DI token (`AIProvider`) is gone. Hosts now register a **named registry of providers** (`AIProviderRegistry`), and each agent can declare which named provider it wants.
+
+---
+
+## 1. Single-provider DI token replaced by a registry
+
+The `AIProvider` DI token (a const exported by `@genesislcap/foundation-ai`) has been **removed**. So has the `getAIProvider()` helper. They're replaced by a new token `AIProviderRegistry` and a registration helper `registerAIProviders`.
+
+The `AIProvider` **interface** still exists and is still exported (concrete provider classes implement it). Only the DI-token const and `getAIProvider` helper are gone.
+
+### Bootstrap: single-provider host
+
+**Before**
+
+```ts
+import { AIProvider, createAIProvider, resolveAIConfig } from '@genesislcap/foundation-ai';
+import { Registration } from '@microsoft/fast-foundation';
+
+const aiConfig = await resolveAIConfig({ provider: 'gemini', model: 'gemini-2.5-flash' });
+
+this.container.register(
+  Registration.instance(AIProvider, createAIProvider(aiConfig)),
+);
+```
+
+**After**
+
+```ts
+import { createAIProvider, registerAIProviders, resolveAIConfig } from '@genesislcap/foundation-ai';
+
+const aiConfig = await resolveAIConfig({ provider: 'gemini', model: 'gemini-2.5-flash' });
+
+registerAIProviders(this.container, { gemini: createAIProvider(aiConfig) });
+```
+
+Notes:
+
+- `registerAIProviders` is a function — call it directly with the container; **do not** wrap it in `container.register(...)`.
+- With one provider in the map, the default is inferred automatically. The key (`'gemini'` here) becomes both the registered name and the default name.
+- Pick a stable, descriptive key. It's how agents will reference this provider in their config, and it's what the settings panel will show.
+
+### Bootstrap: multi-provider host
+
+```ts
+import {
+  AnthropicProvider,
+  AnthropicTransport,
+  GeminiProvider,
+  GeminiTransport,
+  registerAIProviders,
+} from '@genesislcap/foundation-ai';
+
+const fast = new GeminiProvider({}, new GeminiTransport({ model: 'gemini-2.5-flash-lite' }));
+const deep = new AnthropicProvider({}, new AnthropicTransport({ model: 'claude-sonnet-4-6' }));
+
+registerAIProviders(this.container, { fast, deep }, { default: 'fast' });
+```
+
+- With **more than one** entry, `options.default` is **required**. Omitting it throws — there's no implicit ordering.
+- Unknown `options.default` (a name not present in `providers`) throws.
+- Empty `providers` map throws.
+
+### What happens if you register nothing?
+
+A built-in empty registry resolves from the DI container. Every lookup returns a no-op provider; the assistant renders inert. This preserves today's "AI feature flag off / nothing configured" behaviour — no need to special-case it.
+
+---
+
+## 2. New `BaseAgentConfig.provider` — per-agent provider override
+
+Every agent (specialist, fallback, or stateful) can now declare which registered provider it uses by name. Omit the field to use the registry's default.
+
+```ts
+import { defineAgent } from '@genesislcap/ai-assistant';
+
+const classifier = defineAgent({
+  name: 'classifier',
+  description: 'Quick triage and routing.',
+  provider: 'fast', // resolves against the AIProviderRegistry
+});
+
+const analyst = defineAgent({
+  name: 'analyst',
+  description: 'Deep analysis with long context.',
+  provider: 'deep',
+});
+```
+
+Type: `provider?: string | ((ctx: SystemPromptContext) => string | Promise<string>)`.
+
+### Function form (per-turn resolution)
+
+The function form mirrors `systemPrompt`, `toolDefinitions`, `toolHandlers` — resolved each tool-loop iteration with the same `SystemPromptContext`. On a plain `defineAgent` config this looks like:
+
+```ts
+const triage = defineAgent({
+  name: 'triage',
+  description: 'Routes intents.',
+  provider: (ctx) => (ctx.history.length > 8 ? 'deep' : 'fast'),
+});
+```
+
+The argument is just `SystemPromptContext` — `agentName`, `history`, `turnIndex`, `signal`. No `state` field, because plain agents don't own per-turn state.
+
+### Stateful agents (`defineStatefulAgent`)
+
+For agents built with `defineStatefulAgent<S>`, the `provider` resolver receives `StatefulAgentContext<S>` — the same context plus the live `state` value. This lets the agent flip provider based on whatever it owns (a state machine, an accumulator, anything in `S`):
+
+```ts
+const guidedBooking = defineStatefulAgent<{ machine: GuidedBookingMachine }>({
+  name: 'guided_booking',
+  description: 'Walks the user through a multi-step booking flow.',
+  init: ({ /* ... */ }) => ({ machine: createMachine(...) }),
+
+  provider: ({ state }) =>
+    state.machine.state === GuidedBookingStates.EnterDetails ? 'deep' : 'fast',
+
+  systemPrompt: ({ state }) => state.machine.meta?.systemPrompt ?? '...',
+  // ...
+});
+```
+
+`defineStatefulAgent` wraps the function so `state` is threaded in before each call — you don't write the wrapping yourself.
+
+**Use typed constants for state names.** Comparing against a string literal like `'enterDetails'` is fragile — renames in the machine don't break the resolver. Export a typed const map from the machine file and reference it from the agent:
+
+```ts
+// guided-booking.machine.ts
+export const GuidedBookingStates = {
+  PickCounterparty: 'pickCounterparty',
+  PickInstrument: 'pickInstrument',
+  EnterDetails: 'enterDetails',
+  Confirm: 'confirm',
+  Done: 'done',
+  Cancelled: 'cancelled',
+} as const satisfies Record<string, GuidedBookingState>;
+```
+
+Renaming a state now requires updating the map, which surfaces every consumer in one place. The `satisfies Record<string, GuidedBookingState>` keeps the values constrained to the state-name union.
+
+For dynamic stateful agents (no machine — see [`trade-operations.agent.ts`](../../../../../showcase/client-app/client/src/routes/ai/trade-operations/trade-operations.agent.ts)), the same pattern applies but the predicate is whatever derives "current phase" from the state shape — e.g. `provider: ({ state }) => isPlanning(state) ? 'deep' : 'fast'`.
+
+### Sub-agents
+
+`BaseAgentConfig.provider` is inherited by sub-agents. A sub-agent declared in `subAgents: [...]` can have its own `provider` field; it's validated alongside its parent.
+
+---
+
+## 3. Validation — unknown names and missing capabilities hard-error
+
+There are no silent fallbacks for misconfigured providers. The validation runs at two points:
+
+- **Static names** (`provider: 'fast'`) — validated at `OrchestratingDriver` construction time. Walks every agent and every nested sub-agent. Unknown names throw with the list of registered names. Providers missing `chat()` throw too.
+- **Function-form names** (`provider: ({ state }) => '...'`) — validated on first resolution per name (cached after that). Subsequent state transitions that return a different name validate again.
+
+Sample errors:
+
+```
+OrchestratingDriver: agent "analyst" references unknown provider "deep". Registered: fast
+ChatDriver: agent "analyst" resolved to provider "deep" which does not implement chat() — required by ChatDriver.
+```
+
+If you see one of these, the fix is in either the registration (`registerAIProviders(...)`) or the agent config (`provider: '...'`), not in this code.
+
+---
+
+## 4. Settings panel — multi-provider display
+
+The settings cog inside the assistant displays providers in two modes:
+
+- **1 provider** — same single "Model" row as before. No visible change for single-provider hosts.
+- **2+ providers** — a list of every registered provider with the model id from `getStatus()`, plus `default` and `current` badges. `current` follows the active agent's resolved provider.
+
+Status is fetched once on connect via `AIProviderRegistry.listStatuses()` and refreshed when the active provider changes.
+
+Nothing about the multi-provider list leaks outside the cog — the header, halo, and message rows are unchanged.
+
+---
+
+## 5. Consumer behaviour outside the assistant
+
+Other foundation-ui components that consume the AI layer use **the registry's default provider only** — they're not bound to any agent, so per-agent overrides don't apply:
+
+- `ai-criteria-search` (the natural-language criteria filter, including when embedded in `foundation-entity-management`) — calls `interpretCriteria` on the default provider.
+- `ai-indicator` (chrome status indicator) — reads status / triggers Chrome model download on the default provider.
+
+If your host needs criteria search backed by a specific provider, make sure that provider is your default.
+
+---
+
+## 6. Things that always use the default provider
+
+Inside the assistant itself, a few non-turn paths always run against the registry default rather than the active agent's provider:
+
+- **Suggestion generation** (`ChatDriver.getSuggestions`) — UI helper not bound to any agent.
+- **Classifier** (`OrchestratingDriver`'s intent routing) — orchestrator-level decision, runs before any specialist is picked.
+
+This is intentional: keep those paths cheap and predictable, and pick a default provider that's cheap enough for them.
+
+---
+
+## 7. Known limitations
+
+- **Context-window flip.** If an agent switches provider mid-conversation (e.g. a stateful agent moves from a long-window provider to a short-window one), history accumulated under the larger window can blow the smaller window. The driver does not auto-trim. Either keep providers compatible in context size, or design state transitions that reset / summarise history.
+- **Capability check is `chat()` only.** `ChatDriver` validates that the resolved provider implements `chat()`. It does **not** validate `streamChat()` or `prompt()`. If an agent's flow specifically needs streaming, ensure the provider implements it; otherwise calls will fall through to non-streaming.
+
+---
+
+## 8. Checklist for migrating a host app
+
+1. Replace `Registration.instance(AIProvider, createAIProvider(...))` with `registerAIProviders(container, { '<name>': createAIProvider(...) })`. Call it **outside** `container.register(...)`.
+2. Drop `import { AIProvider }` value imports; keep `import type { AIProvider }` if you still need the interface.
+3. Drop any `getAIProvider()` calls — pull the registry from DI (`@AIProviderRegistry providerRegistry!: AIProviderRegistry`) and use `providerRegistry.default()` or `providerRegistry.get(name)`.
+4. If you want per-agent providers, register multiple under distinct names with an explicit `default`, then add `provider: '<name>'` to the relevant `AgentConfig` entries.
+5. Re-run typecheck. The breakage surface is narrow: only sites that used the removed const or helper. Type-only uses of the `AIProvider` interface continue to work unchanged.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "14.444.1",
+  "version": "14.445.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -64,24 +64,24 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.444.1",
-    "@genesislcap/genx": "14.444.1",
-    "@genesislcap/rollup-builder": "14.444.1",
-    "@genesislcap/ts-builder": "14.444.1",
-    "@genesislcap/uvu-playwright-builder": "14.444.1",
-    "@genesislcap/vite-builder": "14.444.1",
-    "@genesislcap/webpack-builder": "14.444.1",
+    "@genesislcap/foundation-testing": "14.445.0",
+    "@genesislcap/genx": "14.445.0",
+    "@genesislcap/rollup-builder": "14.445.0",
+    "@genesislcap/ts-builder": "14.445.0",
+    "@genesislcap/uvu-playwright-builder": "14.445.0",
+    "@genesislcap/vite-builder": "14.445.0",
+    "@genesislcap/webpack-builder": "14.445.0",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "14.444.1",
-    "@genesislcap/foundation-logger": "14.444.1",
-    "@genesislcap/foundation-redux": "14.444.1",
-    "@genesislcap/foundation-ui": "14.444.1",
-    "@genesislcap/foundation-utils": "14.444.1",
-    "@genesislcap/rapid-design-system": "14.444.1",
-    "@genesislcap/web-core": "14.444.1",
+    "@genesislcap/foundation-ai": "14.445.0",
+    "@genesislcap/foundation-logger": "14.445.0",
+    "@genesislcap/foundation-redux": "14.445.0",
+    "@genesislcap/foundation-ui": "14.445.0",
+    "@genesislcap/foundation-utils": "14.445.0",
+    "@genesislcap/rapid-design-system": "14.445.0",
+    "@genesislcap/web-core": "14.445.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -93,5 +93,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "837befe80b4972686cb48fe7d86334c5d819ced6"
+  "gitHead": "ab4f2ce242dedb41dcd82795abf7e0acaf14979c"
 }

package/src/components/ai-driver/ai-driver.ts

@@ -75,4 +75,12 @@ export interface AiDriver extends EventTarget {
    * orchestrator just delegates to its inner `ChatDriver`.
    */
   getTurnSnapshots?(): ReadonlyArray<TurnSnapshot>;
+
+  /**
+   * Name of the AI provider used on the most recent turn. Falls back to the
+   * registry's default name when no turn has run yet.
+   *
+   * @beta
+   */
+  getActiveProviderName(): string;
 }

package/src/components/chat-driver/chat-driver.ts

@@ -1,5 +1,6 @@
 import type {
   AIProvider,
+  AIProviderRegistry,
   ChatAttachment,
   ChatDriverResult,
   ChatMessage,
@@ -14,11 +15,13 @@ import { MalformedFunctionCallError } from '@genesislcap/foundation-ai';
 import { agenticActivityBus } from '../../channel/ai-activity-bus';
 import type {
   AgentConfig,
+  ProviderInput,
   SystemPromptContext,
   SystemPromptInput,
   ToolDefinitionsInput,
   ToolHandlersInput,
 } from '../../config/config';
+import { resolveChatProvider } from '../../config/validate-providers';
 import { applyHistoryCap } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import { TOOL_FOLD_SYMBOL, type ToolFold } from '../../utils/tool-fold';
@@ -205,8 +208,24 @@ export class ChatDriver extends EventTarget implements AiDriver {
   private debugSnapshotter?: () => unknown;
   private readonly maxTurnSnapshots: number;
 
+  /**
+   * Active agent's provider selector (static name or per-turn resolver).
+   * `undefined` means "use the registry default".
+   */
+  private activeProviderInput?: ProviderInput;
+  /**
+   * Caches validated provider lookups per name within the current agent. Cleared
+   * by `applyAgent` so each new agent's static/function-resolved names are
+   * validated fresh.
+   */
+  private resolvedProviderCache = new Map<string, AIProvider>();
+  /** Last successfully resolved provider name — drives `getActiveProviderName`. */
+  private lastResolvedProviderName?: string;
+  /** Last dispatched `provider-changed` name; avoids duplicate events on stable turns. */
+  private lastDispatchedProviderName?: string;
+
   constructor(
-    private readonly aiProvider: AIProvider,
+    private readonly providerRegistry: AIProviderRegistry,
     toolHandlers: ToolHandlersInput = {},
     toolDefinitions: ToolDefinitionsInput = [],
     systemPrompt?: SystemPromptInput,
@@ -270,11 +289,72 @@ export class ChatDriver extends EventTarget implements AiDriver {
       typeof config.displayName === 'string' ? config.displayName : config.name;
     this.debugSnapshotter = config.getDebugSnapshot;
     this.subAgentsMap = new Map((config.subAgents ?? []).map((s) => [s.name, s]));
+    this.activeProviderInput = config.provider;
+    this.resolvedProviderCache.clear();
+    this.lastResolvedProviderName = undefined;
+    // Static validation: resolve the name now so unknown-provider and missing-
+    // capability errors fire at agent swap rather than on the first LLM call.
+    // Function-form `provider` is validated lazily inside `resolveProviderForTurn`.
+    if (typeof config.provider === 'string') {
+      this.resolveProviderByName(config.provider, config.name);
+    }
     // Reset fold state when agent changes — each specialist starts fresh
     this.foldStack = [];
     this.consecutiveFoldOps = 0;
   }
 
+  /**
+   * Returns the most recently resolved provider name. Falls back to the
+   * registry's default when no per-turn resolution has happened yet.
+   */
+  getActiveProviderName(): string {
+    return this.lastResolvedProviderName ?? this.providerRegistry.defaultName();
+  }
+
+  /**
+   * Resolve a named provider against the registry. Cached per-agent so
+   * repeated lookups during one agent's lifetime don't re-validate.
+   * Validation lives in `resolveChatProvider`; this wrapper just adds the
+   * cache.
+   */
+  private resolveProviderByName(name: string, agentName: string): AIProvider {
+    const cached = this.resolvedProviderCache.get(name);
+    if (cached) return cached;
+    const provider = resolveChatProvider(this.providerRegistry, name, agentName);
+    this.resolvedProviderCache.set(name, provider);
+    return provider;
+  }
+
+  /**
+   * Resolve the provider to use for the current turn. Walks the agent's
+   * `provider` selector (static or function form) or falls back to the
+   * registry default. Dispatches `provider-changed` when the resolved name
+   * differs from the last dispatched value.
+   */
+  private async resolveProviderForTurn(ctx: SystemPromptContext): Promise<AIProvider> {
+    let provider: AIProvider;
+    let resolvedName: string;
+    if (this.activeProviderInput === undefined) {
+      provider = this.providerRegistry.default();
+      resolvedName = this.providerRegistry.defaultName();
+    } else {
+      const name =
+        typeof this.activeProviderInput === 'function'
+          ? await this.activeProviderInput(ctx)
+          : this.activeProviderInput;
+      provider = this.resolveProviderByName(name, this.activeAgentName ?? '<unknown>');
+      resolvedName = name;
+    }
+    this.lastResolvedProviderName = resolvedName;
+    if (resolvedName !== this.lastDispatchedProviderName) {
+      this.lastDispatchedProviderName = resolvedName;
+      this.dispatchEvent(
+        new CustomEvent<{ name: string }>('provider-changed', { detail: { name: resolvedName } }),
+      );
+    }
+    return provider;
+  }
+
   /**
    * Returns the early-stop result set by `completeSubAgent`, if any.
    * Called by a parent `ChatDriver` after running this instance as a sub-agent.
@@ -362,8 +442,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
     count: number,
     allAgentInfo?: AllAgentSummary[],
   ): Promise<string[]> {
-    if (!this.aiProvider.prompt) {
-      logger.warn('ChatDriver: AIProvider does not implement prompt()');
+    // Suggestions are an out-of-turn UI helper, not bound to any single agent —
+    // always run against the registry default. Best-effort: a default with no
+    // `prompt()` just means no suggestions, not a hard error.
+    const defaultProvider = this.providerRegistry.default();
+    if (!defaultProvider.prompt) {
+      logger.warn('ChatDriver: default AI provider does not implement prompt()');
       return [];
     }
 
@@ -449,7 +533,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
         `- No preamble, headings, summary, or commentary before or after the list.`;
     }
 
-    const text = await this.aiProvider.prompt!(userMessage, { systemPrompt });
+    const text = await defaultProvider.prompt!(userMessage, { systemPrompt });
 
     // Lenient parsing as a defensive backstop: even with the strict prompt,
     // models occasionally slip in numbering, bullets, or surrounding markdown.
@@ -585,10 +669,6 @@ export class ChatDriver extends EventTarget implements AiDriver {
 
   async sendMessage(userInput: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult> {
     if (this.busy || (!userInput.trim() && !attachments?.length)) return { reason: 'done' };
-    if (!this.aiProvider.chat) {
-      logger.warn('ChatDriver: AIProvider does not implement chat()');
-      return { reason: 'done' };
-    }
 
     this.busy = true;
     this.subAgentCompletion = undefined;
@@ -697,7 +777,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       ...(subConfig.primerHistory ?? []),
     ];
 
-    const child = new ChatDriver(this.aiProvider);
+    const child = new ChatDriver(this.providerRegistry);
     child.applyAgent({ ...subConfig, primerHistory: effectivePrimer });
     // Route interactions back through this driver so widgets render in the
     // parent's (ultimately the root's) history and resolve via the same
@@ -750,10 +830,6 @@ export class ChatDriver extends EventTarget implements AiDriver {
    */
   async continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult> {
     if (this.busy) return { reason: 'done' };
-    if (!this.aiProvider.chat) {
-      logger.warn('ChatDriver: AIProvider does not implement chat()');
-      return { reason: 'done' };
-    }
 
     this.busy = true;
     this.subAgentCompletion = undefined;
@@ -1032,10 +1108,16 @@ export class ChatDriver extends EventTarget implements AiDriver {
         attachments: attachmentsForCall,
       };
 
+      // Resolve the active provider for this turn. Static names were validated
+      // in `applyAgent`; function-form names are validated on first resolution
+      // here and cached for the agent's lifetime.
+      // oxlint-disable-next-line no-await-in-loop
+      const activeProvider = await this.resolveProviderForTurn(promptCtx);
+
       let response: ChatMessage;
       try {
         // oxlint-disable-next-line no-await-in-loop
-        response = await this.aiProvider.chat!(historyForCall, userInputForCall, options);
+        response = await activeProvider.chat!(historyForCall, userInputForCall, options);
       } catch (e) {
         if (e instanceof MalformedFunctionCallError) {
           malformedAttempts += 1;