@genesislcap/foundation-ai 14.461.2 → 14.462.0

package/dist/foundation-ai.d.ts

@@ -537,6 +537,24 @@ export declare interface ChatMessage {
      * Not shown to the user.
      */
     responseMeta?: ChatResponseMeta;
+    /**
+     * Concrete model id that produced this message — what the active provider's
+     * {@link AIProvider.getStatus} reported for the turn (e.g.
+     * `'gemini-2.5-flash-lite'`, `'claude-haiku-4-5-20251001'`). Stamped by the
+     * driver onto model-produced assistant messages; tool calls ride on the
+     * assistant message that requested them, so a message's `model` also
+     * attributes its `toolCalls`. Absent on driver-authored messages (error/empty
+     * fallbacks, user/tool messages) and when the provider reports no status.
+     */
+    model?: string;
+    /**
+     * Registry name the provider was resolved under for the turn that produced
+     * this message (e.g. a tier name, or the default name). Together with `model`
+     * it records both the slot the turn selected and the concrete model behind it,
+     * so swapping the model behind a stable name stays visible in the debug log.
+     * Stamped by the driver alongside `model`.
+     */
+    providerName?: string;
 }
 
 /**
@@ -1308,6 +1326,15 @@ export declare const isAIFeatureEnabled: () => boolean;
  */
 export declare function isChatToolCallUnknown(tc: ChatToolCall): tc is ChatToolCallUnknown;
 
+/**
+ * Feature-detects an {@link ObservableAIProviderRegistry}. Returns `true` when
+ * `r` exposes a `subscribe` method — i.e. it can notify on runtime changes —
+ * and `false` for the immutable built-ins.
+ *
+ * @beta
+ */
+export declare function isObservableAIProviderRegistry(r: AIProviderRegistry): r is ObservableAIProviderRegistry;
+
 /**
  * Speech-to-text using Web Speech API.
  * Gracefully degrades when SpeechRecognition is unavailable.
@@ -1333,6 +1360,108 @@ export declare class MalformedFunctionCallError extends Error {
     constructor(finishMessage?: string);
 }
 
+/**
+ * Map-backed registry built by {@link registerAIProviders}. Preserves the
+ * insertion order of `providers` for {@link (AIProviderRegistry:interface).names}
+ * and {@link (AIProviderRegistry:interface).listStatuses}.
+ *
+ * Mutable and observable: a host that holds a reference can rebind names,
+ * change the default, or atomically replace the whole mapping at runtime via
+ * {@link MutableAIProviderRegistry.set}, {@link MutableAIProviderRegistry.setDefault}
+ * and {@link MutableAIProviderRegistry.update}, and subscribe to be told when
+ * any of those happen. This is the substrate for runtime provider switching:
+ * the DI token resolves one stable instance, and consumers re-resolve their
+ * cached providers when {@link MutableAIProviderRegistry.subscribe | subscribe}
+ * fires. A registry that is never mutated behaves identically to an immutable
+ * one, so existing single-registration callers are unaffected.
+ *
+ * @beta
+ */
+export declare class MutableAIProviderRegistry implements ObservableAIProviderRegistry {
+    private providers;
+    private _defaultName;
+    private readonly listeners;
+    constructor(providers: Map<string, AIProvider>, defaultName: string);
+    /**
+     * The mapping invariant shared by construction and
+     * {@link MutableAIProviderRegistry.update}: at least one provider, and the
+     * resolved default name must be one of the keys. Throws
+     * with the same messages from both call sites. Validates the finalized map, so
+     * callers normalize/copy and resolve the default name first, then validate.
+     */
+    private static assertValidMapping;
+    get(name: string): AIProvider | undefined;
+    default(): AIProvider;
+    defaultName(): string;
+    names(): string[];
+    getStatus(name?: string): Promise<AIStatus | null>;
+    listStatuses(): Promise<AIProviderRegistryStatusEntry[]>;
+    /**
+     * Rebind (or add) a single name. Rebinding an existing name preserves its
+     * position in `names()`; a new name is appended. Notifies subscribers.
+     */
+    set(name: string, provider: AIProvider): void;
+    /**
+     * Change the default provider. Throws if `name` is not currently registered.
+     * Notifies subscribers.
+     */
+    setDefault(name: string): void;
+    /**
+     * Atomically replace the whole mapping (and optionally the default) in one
+     * step, then notify subscribers once. Applies the same validation as the
+     * constructor: an empty mapping throws, and the resolved default must be
+     * present. When `options.default` is omitted the current default name is
+     * retained (and must still exist in the new mapping).
+     */
+    update(providers: Record<string, AIProvider> | Map<string, AIProvider>, options?: {
+        default?: string;
+    }): void;
+    subscribe(listener: () => void): () => void;
+    /**
+     * Fire every listener once. Iterates a snapshot so a listener that
+     * unsubscribes (or subscribes) during notification doesn't perturb the
+     * in-flight iteration.
+     */
+    private notify;
+}
+
+/**
+ * Optional capability layered onto {@link (AIProviderRegistry:interface)}: a
+ * registry whose provider mapping and default can change at runtime, and that
+ * notifies listeners when they do.
+ *
+ * @remarks
+ * Consumers should **feature-detect** this with
+ * {@link isObservableAIProviderRegistry} rather than depend on it — the
+ * built-in empty fallback registry is immutable and deliberately does not
+ * implement it. The read contract ({@link (AIProviderRegistry:interface)})
+ * is unchanged; this only adds change notification, never new read methods.
+ *
+ * @beta
+ */
+export declare interface ObservableAIProviderRegistry extends AIProviderRegistry {
+    /**
+     * Register a listener fired once after any change to the provider mapping or
+     * default. Returns an unsubscribe function; call it to stop notifications.
+     */
+    subscribe(listener: () => void): () => void;
+}
+
+/**
+ * Registers a host-supplied {@link (AIProviderRegistry:interface)} instance on
+ * the DI container under the {@link (AIProviderRegistry:variable)} token.
+ *
+ * @remarks
+ * A thin wrapper over FAST's `Registration.instance` so a host can register its
+ * own pre-built registry — typically a {@link MutableAIProviderRegistry} it
+ * owns and mutates for runtime provider switching — **without importing FAST
+ * primitives** itself. {@link registerAIProviders} delegates to this; reach for
+ * it directly when you construct the registry yourself.
+ *
+ * @beta
+ */
+export declare function registerAIProviderRegistry(container: Container, registry: AIProviderRegistry): void;
+
 /**
  * Registers one or more named AI providers as an {@link (AIProviderRegistry:interface)}
  * on the given DI container.
@@ -1356,9 +1485,16 @@ export declare class MalformedFunctionCallError extends Error {
  * );
  * ```
  *
+ * @returns the constructed {@link MutableAIProviderRegistry}, so a host that
+ *   wants to switch providers at runtime can keep the handle and call
+ *   {@link MutableAIProviderRegistry.set | set} /
+ *   {@link MutableAIProviderRegistry.setDefault | setDefault} /
+ *   {@link MutableAIProviderRegistry.update | update} on it later. Callers that
+ *   register once and never switch can ignore the return value.
+ *
  * @beta
  */
-export declare function registerAIProviders(container: Container, providers: Record<string, AIProvider>, options?: RegisterAIProvidersOptions): void;
+export declare function registerAIProviders(container: Container, providers: Record<string, AIProvider>, options?: RegisterAIProvidersOptions): MutableAIProviderRegistry;
 
 /**
  * Options for {@link registerAIProviders}.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-ai",
   "description": "Genesis Foundation AI - Provider-agnostic AI configuration and shared utilities",
-  "version": "14.461.2",
+  "version": "14.462.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -52,17 +52,17 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.461.2",
-    "@genesislcap/genx": "14.461.2",
-    "@genesislcap/rollup-builder": "14.461.2",
-    "@genesislcap/ts-builder": "14.461.2",
-    "@genesislcap/uvu-playwright-builder": "14.461.2",
-    "@genesislcap/vite-builder": "14.461.2",
-    "@genesislcap/webpack-builder": "14.461.2"
+    "@genesislcap/foundation-testing": "14.462.0",
+    "@genesislcap/genx": "14.462.0",
+    "@genesislcap/rollup-builder": "14.462.0",
+    "@genesislcap/ts-builder": "14.462.0",
+    "@genesislcap/uvu-playwright-builder": "14.462.0",
+    "@genesislcap/vite-builder": "14.462.0",
+    "@genesislcap/webpack-builder": "14.462.0"
   },
   "dependencies": {
-    "@genesislcap/foundation-logger": "14.461.2",
-    "@genesislcap/foundation-utils": "14.461.2",
+    "@genesislcap/foundation-logger": "14.462.0",
+    "@genesislcap/foundation-utils": "14.462.0",
     "@microsoft/fast-foundation": "2.50.0"
   },
   "repository": {
@@ -73,5 +73,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7999f5af9df17157002c463d10fe75a14ac43521"
+  "gitHead": "d332227a536531b1b807ae33f65ce4639f0991ba"
 }