@genesislcap/ai-assistant 14.444.1 → 14.445.1

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.1",
   "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.1",
+    "@genesislcap/genx": "14.445.1",
+    "@genesislcap/rollup-builder": "14.445.1",
+    "@genesislcap/ts-builder": "14.445.1",
+    "@genesislcap/uvu-playwright-builder": "14.445.1",
+    "@genesislcap/vite-builder": "14.445.1",
+    "@genesislcap/webpack-builder": "14.445.1",
     "@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.1",
+    "@genesislcap/foundation-logger": "14.445.1",
+    "@genesislcap/foundation-redux": "14.445.1",
+    "@genesislcap/foundation-ui": "14.445.1",
+    "@genesislcap/foundation-utils": "14.445.1",
+    "@genesislcap/rapid-design-system": "14.445.1",
+    "@genesislcap/web-core": "14.445.1",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -93,5 +93,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "837befe80b4972686cb48fe7d86334c5d819ced6"
+  "gitHead": "893e8b2ffadacaedb39f1935c1979278191b6730"
 }

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
@@ -715,7 +795,17 @@ export class ChatDriver extends EventTarget implements AiDriver {
         }),
       );
     };
+    // Re-dispatch the child's `provider-changed` so the UI reflects whichever
+    // provider is *actually* running right now (the sub-agent may use a
+    // different provider than the parent). Restoration of the parent's
+    // provider on `sub-agent-stop` is handled by the listener in main.ts.
+    const forwardProviderChanged = (e: Event) => {
+      this.dispatchEvent(
+        new CustomEvent('provider-changed', { detail: (e as CustomEvent).detail }),
+      );
+    };
     child.addEventListener('history-updated', forwardTrace);
+    child.addEventListener('provider-changed', forwardProviderChanged);
 
     // Unique per-invocation id so listeners can pair start/stop reliably even
     // when the same sub-agent runs multiple times in parallel.
@@ -728,6 +818,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       await child.sendMessage(task ?? '');
     } finally {
       child.removeEventListener('history-updated', forwardTrace);
+      child.removeEventListener('provider-changed', forwardProviderChanged);
       this.dispatchEvent(new CustomEvent('sub-agent-stop', { detail: lifecycleDetail }));
     }
 
@@ -750,10 +841,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 +1119,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;

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

@@ -1,5 +1,5 @@
 import type {
-  AIProvider,
+  AIProviderRegistry,
   ChatAttachment,
   ChatDriverResult,
   ChatMessage,
@@ -12,6 +12,7 @@ import type {
   SystemPromptContext,
   SystemPromptInput,
 } from '../../config/config';
+import { validateStaticAgentProviders } from '../../config/validate-providers';
 import { transformHistoryForAgent } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
@@ -110,7 +111,7 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
   activeAgent?: AgentConfig;
 
   constructor(
-    private readonly aiProvider: AIProvider,
+    private readonly providerRegistry: AIProviderRegistry,
     private readonly agents: AgentConfig[],
     options: {
       sessionKey?: string;
@@ -129,6 +130,11 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
       options.classifierHistoryLength ?? DEFAULT_CLASSIFIER_HISTORY_LENGTH;
     this.classifierRetries = options.classifierRetries ?? DEFAULT_CLASSIFIER_RETRIES;
 
+    // Static-name validation: walk every agent (and nested sub-agents). Any
+    // `provider: '<name>'` that isn't registered, or resolves to a provider
+    // without `chat()`, throws now rather than at first turn.
+    validateStaticAgentProviders(agents, providerRegistry);
+
     // Specialists drive the classifier. `excludeFromClassifier` agents are still
     // resolvable by name (so manual pinning works) but never auto-routed.
     this.specialists = agents.filter(isSpecialist).filter((a) => !a.excludeFromClassifier);
@@ -145,7 +151,7 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
       : undefined;
 
     this.chatDriver = new ChatDriver(
-      aiProvider,
+      providerRegistry,
       {},
       [],
       undefined,
@@ -180,6 +186,11 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
         new CustomEvent('interaction-stop', { detail: (e as CustomEvent).detail }),
       );
     });
+    this.chatDriver.addEventListener('provider-changed', (e: Event) => {
+      this.dispatchEvent(
+        new CustomEvent('provider-changed', { detail: (e as CustomEvent).detail }),
+      );
+    });
   }
 
   resolveInteraction(interactionId: string, result: unknown): void {
@@ -190,6 +201,11 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
     return this.chatDriver.isBusy();
   }
 
+  /** Currently active provider name from the underlying ChatDriver. */
+  getActiveProviderName(): string {
+    return this.chatDriver.getActiveProviderName();
+  }
+
   /**
    * Pins routing to a specific agent by name. While pinned, the classifier is
    * skipped and the continuation tool is hidden from the agent's tool list, so
@@ -530,8 +546,17 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
           systemPrompt: classifierPrompt,
           tools: [routingTool],
         };
+        // Classification is orchestrator-level, not bound to any single agent —
+        // always run against the registry default.
+        const classifierProvider = this.providerRegistry.default();
+        if (!classifierProvider.chat) {
+          logger.warn(
+            'OrchestratingDriver: default AI provider does not implement chat() — cannot classify.',
+          );
+          break;
+        }
         // oxlint-disable-next-line no-await-in-loop
-        const response = await this.aiProvider.chat!([], input, options);
+        const response = await classifierProvider.chat([], input, options);
         const tc = response.toolCalls?.[0];
         const index = tc?.name === 'select_agent' ? (tc.args.agent_index as number) : -1;
 

package/src/config/config.ts

@@ -75,6 +75,20 @@ export type ToolHandlersInput =
   | ChatToolHandlers
   | ((ctx: SystemPromptContext) => ChatToolHandlers | Promise<ChatToolHandlers>);
 
+/**
+ * Names which registered `AIProviderRegistry` entry an agent uses. Either
+ * a static string (resolved once at agent registration) or a function resolved
+ * each tool-loop iteration — pick the function form to vary the provider by
+ * current state (e.g. a stateful agent that switches providers between
+ * machine states).
+ *
+ * Unknown provider names hard-error: static names at agent registration time,
+ * function-resolved names on first resolution.
+ *
+ * @beta
+ */
+export type ProviderInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
+
 /**
  * Opts an agent in to manual selection from the assistant's agent picker.
  *
@@ -138,6 +152,24 @@ interface BaseAgentConfig {
    * See {@link ToolHandlersInput}.
    */
   toolHandlers?: ToolHandlersInput;
+  /**
+   * Which registered AI provider this agent uses, by name. Either a static
+   * string (resolved once at agent registration) or a function resolved each
+   * tool-loop iteration — pick the function form to vary the provider by
+   * current state (e.g. a stateful agent that switches providers between
+   * machine states).
+   *
+   * Omit to use the registry's default provider. Unknown names hard-error:
+   * static names at registration time, function-resolved names on first
+   * resolution.
+   *
+   * Known limitation: switching provider mid-conversation can blow the
+   * smaller provider's context window if history accumulated under a
+   * larger one. No automatic trimming is performed.
+   *
+   * @beta
+   */
+  provider?: ProviderInput;
   /**
    * Optional primer history prepended to every call (not visible to the user).
    * Used to establish agent identity and behavioural rules.