@genesislcap/ai-assistant 14.494.0 → 14.496.0

package/dist/custom-elements.json

@@ -2,6 +2,205 @@
   "schemaVersion": "1.0.0",
   "readme": "",
   "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/chat-driver-node.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./components/chat-driver"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./components/orchestrating-driver"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./channel/ai-activity-channel"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./channel/ai-activity-bus"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./config/config"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./config/define-stateful-agent"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./config/fallback-agents"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "AnthropicProvider",
+          "declaration": {
+            "name": "AnthropicProvider",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "AnthropicTransport",
+          "declaration": {
+            "name": "AnthropicTransport",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "GeminiProvider",
+          "declaration": {
+            "name": "GeminiProvider",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "GeminiTransport",
+          "declaration": {
+            "name": "GeminiTransport",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MutableAIProviderRegistry",
+          "declaration": {
+            "name": "MutableAIProviderRegistry",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "isObservableAIProviderRegistry",
+          "declaration": {
+            "name": "isObservableAIProviderRegistry",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "AIProvider",
+          "declaration": {
+            "name": "AIProvider",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "AIProviderRegistry",
+          "declaration": {
+            "name": "AIProviderRegistry",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "AnthropicModelId",
+          "declaration": {
+            "name": "AnthropicModelId",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "CachePolicy",
+          "declaration": {
+            "name": "CachePolicy",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ChatFallback",
+          "declaration": {
+            "name": "ChatFallback",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ChatMessage",
+          "declaration": {
+            "name": "ChatMessage",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ChatRequestOptions",
+          "declaration": {
+            "name": "ChatRequestOptions",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ChatToolChoice",
+          "declaration": {
+            "name": "ChatToolChoice",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ChatToolDefinition",
+          "declaration": {
+            "name": "ChatToolDefinition",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ChatToolHandlers",
+          "declaration": {
+            "name": "ChatToolHandlers",
+            "package": "@genesislcap/foundation-ai"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "GeminiModelId",
+          "declaration": {
+            "name": "GeminiModelId",
+            "package": "@genesislcap/foundation-ai"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/index.ts",
@@ -151,6 +350,14 @@
             "package": "./utils/tool-fold"
           }
         },
+        {
+          "kind": "js",
+          "name": "TurnFailureReason",
+          "declaration": {
+            "name": "TurnFailureReason",
+            "module": "./state/debug-event-log"
+          }
+        },
         {
           "kind": "js",
           "name": "TimelineMessage",
@@ -221,6 +428,15 @@
       "kind": "javascript-module",
       "path": "src/channel/ai-activity-bus.ts",
       "declarations": [
+        {
+          "kind": "variable",
+          "name": "NOOP_ACTIVITY_BUS",
+          "type": {
+            "text": "ActivityBus"
+          },
+          "default": "{ publish: () => {} }",
+          "description": "No-op ActivityBus. The default when no bus is injected (Node, tests, headless\nserver use) — publishing goes nowhere and nothing is left open to tear down."
+        },
         {
           "kind": "class",
           "description": "Typed in-process event bus for AI assistant activity events.\n\nDispatches events synchronously to all local subscribers in the same JS module instance\n(i.e. the same browser tab). Events listed in `crossTabEvents` are additionally forwarded\nvia a shared `BroadcastChannel` so that other tabs on the same origin receive them.",
@@ -243,6 +459,15 @@
               "readonly": true,
               "default": "new Set(config?.crossTabEvents ?? [])"
             },
+            {
+              "kind": "field",
+              "name": "channelNameFactory",
+              "type": {
+                "text": "() => string | undefined"
+              },
+              "privacy": "private",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "channel",
@@ -251,6 +476,26 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "channelInitialised",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "method",
+              "name": "ensureChannel",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Lazily open the cross-tab `BroadcastChannel` on first use. Deferred (rather than\ncreated in the constructor) so that importing this module, or constructing the bus\noff-browser (Node, tests, headless server), never opens a live channel or reads\n`sessionStorage` — both would keep a Node event loop alive and hang the process.\nCross-tab forwarding is inherently browser-only, so channel creation is gated on a\nbrowser environment; elsewhere the bus stays purely in-process."
+            },
             {
               "kind": "method",
               "name": "subscribe",
@@ -356,11 +601,19 @@
         {
           "kind": "variable",
           "name": "agenticActivityBus",
-          "default": "new AgenticActivityBus({\n  crossTabEvents: ['halo-start', 'halo-stop', 'tool-loop-start', 'tool-loop-end'],\n  channelName: getTabScopedChannelName('foundation-ai-activity'),\n})",
+          "default": "new AgenticActivityBus({\n  crossTabEvents: ['halo-start', 'halo-stop', 'tool-loop-start', 'tool-loop-end'],\n  // Lazy: the tab-scoped name (and its `sessionStorage` read) is computed on first\n  // cross-tab use in a browser, not at module-eval — so importing this module is\n  // side-effect-free and Node/test-safe.\n  channelNameFactory: () => getTabScopedChannelName('foundation-ai-activity'),\n})",
           "description": "Pre-instantiated singleton event bus for AI assistant activity.\n\n- `halo-start` / `halo-stop` are forwarded via a tab-scoped `BroadcastChannel` so that\n  popout windows opened from this tab show halo animations, while remaining isolated from\n  unrelated tabs on the same origin (tab-scoped channel name).\n- `tool-loop-start` / `tool-loop-end` are cross-tab for the same reason: they describe the\n  assistant's lifecycle (a turn beginning / ending), and the most common subscribers\n  (workspace transitions, post-turn deferred recomputation, UI gates tied to the assistant\n  being idle) need the event regardless of whether the user is interacting with the chat\n  in the main tab or a popout window. Tab-local-only telemetry can subscribe and filter.\n- `chat-popout` / `chat-popin` are in-memory only — they must only affect the tab where the\n  user clicked."
         }
       ],
       "exports": [
+        {
+          "kind": "js",
+          "name": "NOOP_ACTIVITY_BUS",
+          "declaration": {
+            "name": "NOOP_ACTIVITY_BUS",
+            "module": "src/channel/ai-activity-bus.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "AgenticActivityBus",
@@ -867,44 +1120,241 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/main/index.ts",
-      "declarations": [],
+      "path": "src/config/config.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "defineAgent",
+          "description": "Identity helper that infers the narrowest possible type for an agent config,\npreserving string literal types (including `name`) without requiring `as const`.\n\nUse this when you need `typeof myAgent` to carry the literal `name` type —\nfor example, when wiring `ChatToolHandlers<typeof myAgent>`.\n\n```ts\nconst myAgent = defineAgent({ name: 'my_agent', ... });\ntype Handlers = ChatToolHandlers<typeof myAgent>;\n// requestSubAgent name param is now typed as 'my_agent'\n```"
+        }
+      ],
       "exports": [
         {
           "kind": "js",
-          "name": "*",
+          "name": "CachePolicy",
           "declaration": {
-            "name": "*",
-            "package": "./main.template"
+            "name": "CachePolicy",
+            "module": "src/config/config.ts"
           }
         },
         {
           "kind": "js",
-          "name": "*",
+          "name": "ChatFallback",
           "declaration": {
-            "name": "*",
-            "package": "./main"
+            "name": "ChatFallback",
+            "module": "src/config/config.ts"
           }
         },
         {
           "kind": "js",
-          "name": "*",
+          "name": "ChatInputDuringExecutionMode",
           "declaration": {
-            "name": "*",
-            "package": "./main.types"
+            "name": "ChatInputDuringExecutionMode",
+            "module": "src/config/config.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ChatToolChoice",
+          "declaration": {
+            "name": "ChatToolChoice",
+            "module": "src/config/config.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "defineAgent",
+          "declaration": {
+            "name": "defineAgent",
+            "module": "src/config/config.ts"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "src/main/main.styles.ts",
+      "path": "src/config/define-stateful-agent.ts",
       "declarations": [
         {
-          "kind": "variable",
-          "name": "styles",
-          "default": "css`\n  ${baseStyles}\n  ${settingsModalStyles}\n`"
-        }
+          "kind": "function",
+          "name": "restoreMachine",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "machine",
+              "type": {
+                "text": "{ stop: () => void; start: (options?: { state?: unknown }) => void }"
+              },
+              "description": "the machine to restore (already constructed/started)."
+            },
+            {
+              "name": "restored",
+              "type": {
+                "text": "unknown"
+              },
+              "description": "the agent's serialized image (`ctx.restored` in `init`)."
+            },
+            {
+              "name": "key",
+              "default": "'machine'",
+              "description": "the property the machine occupies in the snapshot; defaults to\n`'machine'` to match the conventional `{ machine }` state bag."
+            }
+          ],
+          "description": "Restore a foundation-state-machine instance from a snapshot produced by the\ndefault serializer (or `machine.getPersistedSnapshot()`). Call inside a\nstateful agent's `init` to resume the machine in its exact prior place:\n\n```ts\ninit: ({ restored }) => {\n  const machine = new MyMachine();\n  restoreMachine(machine, restored); // resume, or no-op on a fresh start\n  return { machine };\n}\n```\n\nNo-ops when there is nothing to restore (a fresh session), leaving the\nfreshly-constructed machine in its initial state."
+        },
+        {
+          "kind": "function",
+          "name": "defineStatefulAgent",
+          "return": {
+            "type": {
+              "text": "AgentConfig"
+            }
+          },
+          "parameters": [
+            {
+              "name": "opts",
+              "type": {
+                "text": "StatefulAgentInit<S>"
+              }
+            }
+          ],
+          "description": "Build an `AgentConfig` whose `systemPrompt`, `toolDefinitions`, and tool\nhandlers all close over a long-lived state object created on activation.\n\nThe framework wires the lifecycle: `init` on `onActivate`, `dispose` on\n`onDeactivate`. State is held inside the helper's closure — never exposed on\nthe resulting `AgentConfig` — so the redux serializer doesn't see it."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "restoreMachine",
+          "declaration": {
+            "name": "restoreMachine",
+            "module": "src/config/define-stateful-agent.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "defineStatefulAgent",
+          "declaration": {
+            "name": "defineStatefulAgent",
+            "module": "src/config/define-stateful-agent.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/config/fallback-agents.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "friendlyFallbackAgent",
+          "type": {
+            "text": "FallbackAgentConfig"
+          },
+          "default": "{\n  name: 'Assistant',\n  fallback: true,\n  systemPrompt: `You are a warm, friendly assistant. For general conversation like \"Hi\" or \"How are you\", you can have a friendly chat. For anything more complex, you cannot directly help, but you can explain what specialists are available. The available specialists are:\\n\\n{{agents}}\\n\\nPolitely let the user know what you can help with and invite them to rephrase their request if it is outside your scope.`,\n}",
+          "description": "A warm, conversational fallback agent. Acknowledges it can't help directly,\nexplains what the available specialists can do, and invites the user to retry.\n\nThe system prompt is generated at runtime by `OrchestratingDriver` from the\nspecialist list — no manual authoring required."
+        },
+        {
+          "kind": "variable",
+          "name": "strictFallbackAgent",
+          "type": {
+            "text": "FallbackAgentConfig"
+          },
+          "default": "{\n  name: 'Assistant',\n  fallback: true,\n  systemPrompt: `You are a concise assistant. The user's request is outside your scope. Respond with a single short sentence stating what you can assist with. Do not elaborate. The available specialists are: {{agents}}.`,\n}",
+          "description": "A brief, professional fallback agent. States what is available without\nelaboration. The `{{agents}}` placeholder is replaced at runtime by\n`OrchestratingDriver` with the generated specialist list."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "friendlyFallbackAgent",
+          "declaration": {
+            "name": "friendlyFallbackAgent",
+            "module": "src/config/fallback-agents.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "strictFallbackAgent",
+          "declaration": {
+            "name": "strictFallbackAgent",
+            "module": "src/config/fallback-agents.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/config/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./config"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./fallback-agents"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/config/validate-providers.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/main/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./main.template"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./main"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./main.types"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/main/main.styles.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "styles",
+          "default": "css`\n  ${baseStyles}\n  ${settingsModalStyles}\n`"
+        }
       ],
       "exports": [
         {
@@ -3350,381 +3800,192 @@
               "fieldName": "placeholder"
             },
             {
-              "name": "popout-mode",
-              "type": {
-                "text": "PopoutMode | undefined"
-              },
-              "description": "Controls the pop-out button shown next to the settings cog.\n\"expand\" — in bubble, expands to layout panel (fires chat-popout).\n\"collapse\" — in layout panel, collapses back to bubble (fires chat-popin).\nAbsent — no button (default standalone behaviour, no breaking change).",
-              "fieldName": "popoutMode"
-            },
-            {
-              "name": "debug-redux",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "When set, enables Redux DevTools for this instance's session store.",
-              "fieldName": "debugRedux"
-            }
-          ],
-          "superclass": {
-            "name": "GenesisElement",
-            "package": "@genesislcap/web-core"
-          },
-          "tagName": "foundation-ai-assistant",
-          "customElement": true
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "sparkleIconSvg",
-          "declaration": {
-            "name": "sparkleIconSvg",
-            "module": "src/main/main.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "userIconSvg",
-          "declaration": {
-            "name": "userIconSvg",
-            "module": "src/main/main.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "genesisIconSvg",
-          "declaration": {
-            "name": "genesisIconSvg",
-            "module": "src/main/main.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "FoundationAiAssistant",
-          "declaration": {
-            "name": "FoundationAiAssistant",
-            "module": "src/main/main.ts"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "foundation-ai-assistant",
-          "declaration": {
-            "name": "FoundationAiAssistant",
-            "module": "src/main/main.ts"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/main/main.types.ts",
-      "declarations": [
-        {
-          "kind": "variable",
-          "name": "AiAssistantEvent",
-          "type": {
-            "text": "{\n  /** Session wiped via the lifecycle menu's Clear. `detail`: `SessionClearedDetail`. */\n  SessionCleared: 'session-cleared',\n  /** Header pressed in `popout-mode=\"expand\"` (drag-to-popout hosts). `detail`: `ChatHeaderMouseDownDetail`. */\n  ChatHeaderMouseDown: 'chat-header-mousedown',\n}"
-          },
-          "default": "{\n  /** Session wiped via the lifecycle menu's Clear. `detail`: `SessionClearedDetail`. */\n  SessionCleared: 'session-cleared',\n  /** Header pressed in `popout-mode=\"expand\"` (drag-to-popout hosts). `detail`: `ChatHeaderMouseDownDetail`. */\n  ChatHeaderMouseDown: 'chat-header-mousedown',\n}",
-          "description": "DOM events the `<foundation-ai-assistant>` element dispatches to its host.\nAll bubble and are `composed` (they cross the shadow boundary), so a host can\nlisten on the element — or any ancestor — to react. Use these constants to\nwire listeners instead of hand-typing event-name strings.\n\nAn `as const` map (not a TS `enum` — this package ships none), so it serves as\nboth the listener-name value and, via the same-named type below, a union."
-        },
-        {
-          "kind": "variable",
-          "name": "ANIMATION_DEFS",
-          "type": {
-            "text": "object"
-          },
-          "default": "{\n  loading: {\n    label: 'Dots',\n    description: 'Shows pulsing dots while the assistant is generating a response.',\n    category: 'Loading style',\n  },\n  waves: {\n    label: 'Waves',\n    description:\n      'Shows glowing sine waves inside a circle while the assistant is generating a response.',\n    category: 'Loading style',\n  },\n  flowingWaves: {\n    label: 'Flowing waves',\n    description:\n      'Shows coloured waves rising and settling from a line while the assistant is generating a response.',\n    category: 'Loading style',\n  },\n  plasma: {\n    label: 'Plasma orb',\n    description:\n      'Shows a glowing plasma sphere with drifting energy while the assistant is generating a response.',\n    category: 'Loading style',\n  },\n  halo: {\n    label: 'Halo',\n    description:\n      'Displays a glowing halo around the assistant avatar while a response is streaming.',\n    category: 'Effects',\n  },\n}",
-          "description": "Registry of all available animations with their display metadata.\nAdding an entry here automatically extends the AiAssistantAnimation type."
-        },
-        {
-          "kind": "variable",
-          "name": "satisfies",
-          "description": "Registry of all available animations with their display metadata.\nAdding an entry here automatically extends the AiAssistantAnimation type."
-        },
-        {
-          "kind": "variable",
-          "name": "Record",
-          "description": "Registry of all available animations with their display metadata.\nAdding an entry here automatically extends the AiAssistantAnimation type."
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "AgentPickerMode",
-          "declaration": {
-            "name": "AgentPickerMode",
-            "package": "@genesislcap/foundation-ai"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "AiAssistantEvent",
-          "declaration": {
-            "name": "AiAssistantEvent",
-            "module": "src/main/main.types.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "ANIMATION_DEFS",
-          "declaration": {
-            "name": "ANIMATION_DEFS",
-            "module": "src/main/main.types.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "satisfies",
-          "declaration": {
-            "name": "satisfies",
-            "module": "src/main/main.types.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "Record",
-          "declaration": {
-            "name": "Record",
-            "module": "src/main/main.types.ts"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/provider/ai-provider-switcher.ts",
-      "declarations": [
-        {
-          "kind": "variable",
-          "name": "AIProviderSwitcher",
-          "description": "The DI token for the (AIProviderSwitcher:interface). Resolves a noop until the app\nregisters one."
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "AIProviderSwitcher",
-          "declaration": {
-            "name": "AIProviderSwitcher",
-            "module": "src/provider/ai-provider-switcher.ts"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/provider/assistant-app-settings.ts",
-      "declarations": [
-        {
-          "kind": "variable",
-          "name": "AssistantAppSettingsProvider",
-          "description": "The DI token for the (AssistantAppSettingsProvider:interface). Resolves a noop\nuntil the host registers one."
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "AssistantAppSettingsProvider",
-          "declaration": {
-            "name": "AssistantAppSettingsProvider",
-            "module": "src/provider/assistant-app-settings.ts"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/config/config.ts",
-      "declarations": [
-        {
-          "kind": "function",
-          "name": "defineAgent",
-          "description": "Identity helper that infers the narrowest possible type for an agent config,\npreserving string literal types (including `name`) without requiring `as const`.\n\nUse this when you need `typeof myAgent` to carry the literal `name` type —\nfor example, when wiring `ChatToolHandlers<typeof myAgent>`.\n\n```ts\nconst myAgent = defineAgent({ name: 'my_agent', ... });\ntype Handlers = ChatToolHandlers<typeof myAgent>;\n// requestSubAgent name param is now typed as 'my_agent'\n```"
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "CachePolicy",
-          "declaration": {
-            "name": "CachePolicy",
-            "module": "src/config/config.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "ChatInputDuringExecutionMode",
-          "declaration": {
-            "name": "ChatInputDuringExecutionMode",
-            "module": "src/config/config.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "ChatToolChoice",
-          "declaration": {
-            "name": "ChatToolChoice",
-            "module": "src/config/config.ts"
-          }
-        },
-        {
-          "kind": "js",
-          "name": "defineAgent",
-          "declaration": {
-            "name": "defineAgent",
-            "module": "src/config/config.ts"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/config/define-stateful-agent.ts",
-      "declarations": [
-        {
-          "kind": "function",
-          "name": "restoreMachine",
-          "return": {
-            "type": {
-              "text": "void"
-            }
-          },
-          "parameters": [
-            {
-              "name": "machine",
-              "type": {
-                "text": "{ stop: () => void; start: (options?: { state?: unknown }) => void }"
-              },
-              "description": "the machine to restore (already constructed/started)."
-            },
-            {
-              "name": "restored",
-              "type": {
-                "text": "unknown"
-              },
-              "description": "the agent's serialized image (`ctx.restored` in `init`)."
-            },
-            {
-              "name": "key",
-              "default": "'machine'",
-              "description": "the property the machine occupies in the snapshot; defaults to\n`'machine'` to match the conventional `{ machine }` state bag."
-            }
-          ],
-          "description": "Restore a foundation-state-machine instance from a snapshot produced by the\ndefault serializer (or `machine.getPersistedSnapshot()`). Call inside a\nstateful agent's `init` to resume the machine in its exact prior place:\n\n```ts\ninit: ({ restored }) => {\n  const machine = new MyMachine();\n  restoreMachine(machine, restored); // resume, or no-op on a fresh start\n  return { machine };\n}\n```\n\nNo-ops when there is nothing to restore (a fresh session), leaving the\nfreshly-constructed machine in its initial state."
-        },
-        {
-          "kind": "function",
-          "name": "defineStatefulAgent",
-          "return": {
-            "type": {
-              "text": "AgentConfig"
-            }
-          },
-          "parameters": [
+              "name": "popout-mode",
+              "type": {
+                "text": "PopoutMode | undefined"
+              },
+              "description": "Controls the pop-out button shown next to the settings cog.\n\"expand\" — in bubble, expands to layout panel (fires chat-popout).\n\"collapse\" — in layout panel, collapses back to bubble (fires chat-popin).\nAbsent — no button (default standalone behaviour, no breaking change).",
+              "fieldName": "popoutMode"
+            },
             {
-              "name": "opts",
+              "name": "debug-redux",
               "type": {
-                "text": "StatefulAgentInit<S>"
-              }
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "When set, enables Redux DevTools for this instance's session store.",
+              "fieldName": "debugRedux"
             }
           ],
-          "description": "Build an `AgentConfig` whose `systemPrompt`, `toolDefinitions`, and tool\nhandlers all close over a long-lived state object created on activation.\n\nThe framework wires the lifecycle: `init` on `onActivate`, `dispose` on\n`onDeactivate`. State is held inside the helper's closure — never exposed on\nthe resulting `AgentConfig` — so the redux serializer doesn't see it."
+          "superclass": {
+            "name": "GenesisElement",
+            "package": "@genesislcap/web-core"
+          },
+          "tagName": "foundation-ai-assistant",
+          "customElement": true
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "restoreMachine",
+          "name": "sparkleIconSvg",
           "declaration": {
-            "name": "restoreMachine",
-            "module": "src/config/define-stateful-agent.ts"
+            "name": "sparkleIconSvg",
+            "module": "src/main/main.ts"
           }
         },
         {
           "kind": "js",
-          "name": "defineStatefulAgent",
+          "name": "userIconSvg",
           "declaration": {
-            "name": "defineStatefulAgent",
-            "module": "src/config/define-stateful-agent.ts"
+            "name": "userIconSvg",
+            "module": "src/main/main.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "genesisIconSvg",
+          "declaration": {
+            "name": "genesisIconSvg",
+            "module": "src/main/main.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "FoundationAiAssistant",
+          "declaration": {
+            "name": "FoundationAiAssistant",
+            "module": "src/main/main.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "foundation-ai-assistant",
+          "declaration": {
+            "name": "FoundationAiAssistant",
+            "module": "src/main/main.ts"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "src/config/fallback-agents.ts",
+      "path": "src/main/main.types.ts",
       "declarations": [
         {
           "kind": "variable",
-          "name": "friendlyFallbackAgent",
+          "name": "AiAssistantEvent",
           "type": {
-            "text": "FallbackAgentConfig"
+            "text": "{\n  /** Session wiped via the lifecycle menu's Clear. `detail`: `SessionClearedDetail`. */\n  SessionCleared: 'session-cleared',\n  /** Header pressed in `popout-mode=\"expand\"` (drag-to-popout hosts). `detail`: `ChatHeaderMouseDownDetail`. */\n  ChatHeaderMouseDown: 'chat-header-mousedown',\n}"
           },
-          "default": "{\n  name: 'Assistant',\n  fallback: true,\n  systemPrompt: `You are a warm, friendly assistant. For general conversation like \"Hi\" or \"How are you\", you can have a friendly chat. For anything more complex, you cannot directly help, but you can explain what specialists are available. The available specialists are:\\n\\n{{agents}}\\n\\nPolitely let the user know what you can help with and invite them to rephrase their request if it is outside your scope.`,\n}",
-          "description": "A warm, conversational fallback agent. Acknowledges it can't help directly,\nexplains what the available specialists can do, and invites the user to retry.\n\nThe system prompt is generated at runtime by `OrchestratingDriver` from the\nspecialist list — no manual authoring required."
+          "default": "{\n  /** Session wiped via the lifecycle menu's Clear. `detail`: `SessionClearedDetail`. */\n  SessionCleared: 'session-cleared',\n  /** Header pressed in `popout-mode=\"expand\"` (drag-to-popout hosts). `detail`: `ChatHeaderMouseDownDetail`. */\n  ChatHeaderMouseDown: 'chat-header-mousedown',\n}",
+          "description": "DOM events the `<foundation-ai-assistant>` element dispatches to its host.\nAll bubble and are `composed` (they cross the shadow boundary), so a host can\nlisten on the element — or any ancestor — to react. Use these constants to\nwire listeners instead of hand-typing event-name strings.\n\nAn `as const` map (not a TS `enum` — this package ships none), so it serves as\nboth the listener-name value and, via the same-named type below, a union."
         },
         {
           "kind": "variable",
-          "name": "strictFallbackAgent",
+          "name": "ANIMATION_DEFS",
           "type": {
-            "text": "FallbackAgentConfig"
+            "text": "object"
           },
-          "default": "{\n  name: 'Assistant',\n  fallback: true,\n  systemPrompt: `You are a concise assistant. The user's request is outside your scope. Respond with a single short sentence stating what you can assist with. Do not elaborate. The available specialists are: {{agents}}.`,\n}",
-          "description": "A brief, professional fallback agent. States what is available without\nelaboration. The `{{agents}}` placeholder is replaced at runtime by\n`OrchestratingDriver` with the generated specialist list."
+          "default": "{\n  loading: {\n    label: 'Dots',\n    description: 'Shows pulsing dots while the assistant is generating a response.',\n    category: 'Loading style',\n  },\n  waves: {\n    label: 'Waves',\n    description:\n      'Shows glowing sine waves inside a circle while the assistant is generating a response.',\n    category: 'Loading style',\n  },\n  flowingWaves: {\n    label: 'Flowing waves',\n    description:\n      'Shows coloured waves rising and settling from a line while the assistant is generating a response.',\n    category: 'Loading style',\n  },\n  plasma: {\n    label: 'Plasma orb',\n    description:\n      'Shows a glowing plasma sphere with drifting energy while the assistant is generating a response.',\n    category: 'Loading style',\n  },\n  halo: {\n    label: 'Halo',\n    description:\n      'Displays a glowing halo around the assistant avatar while a response is streaming.',\n    category: 'Effects',\n  },\n}",
+          "description": "Registry of all available animations with their display metadata.\nAdding an entry here automatically extends the AiAssistantAnimation type."
+        },
+        {
+          "kind": "variable",
+          "name": "satisfies",
+          "description": "Registry of all available animations with their display metadata.\nAdding an entry here automatically extends the AiAssistantAnimation type."
+        },
+        {
+          "kind": "variable",
+          "name": "Record",
+          "description": "Registry of all available animations with their display metadata.\nAdding an entry here automatically extends the AiAssistantAnimation type."
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "friendlyFallbackAgent",
+          "name": "AgentPickerMode",
           "declaration": {
-            "name": "friendlyFallbackAgent",
-            "module": "src/config/fallback-agents.ts"
+            "name": "AgentPickerMode",
+            "package": "@genesislcap/foundation-ai"
           }
         },
         {
           "kind": "js",
-          "name": "strictFallbackAgent",
+          "name": "AiAssistantEvent",
           "declaration": {
-            "name": "strictFallbackAgent",
-            "module": "src/config/fallback-agents.ts"
+            "name": "AiAssistantEvent",
+            "module": "src/main/main.types.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ANIMATION_DEFS",
+          "declaration": {
+            "name": "ANIMATION_DEFS",
+            "module": "src/main/main.types.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "satisfies",
+          "declaration": {
+            "name": "satisfies",
+            "module": "src/main/main.types.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "Record",
+          "declaration": {
+            "name": "Record",
+            "module": "src/main/main.types.ts"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "src/config/index.ts",
-      "declarations": [],
+      "path": "src/provider/ai-provider-switcher.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "AIProviderSwitcher",
+          "description": "The DI token for the (AIProviderSwitcher:interface). Resolves a noop until the app\nregisters one."
+        }
+      ],
       "exports": [
         {
           "kind": "js",
-          "name": "*",
+          "name": "AIProviderSwitcher",
           "declaration": {
-            "name": "*",
-            "package": "./config"
+            "name": "AIProviderSwitcher",
+            "module": "src/provider/ai-provider-switcher.ts"
           }
-        },
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/provider/assistant-app-settings.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "AssistantAppSettingsProvider",
+          "description": "The DI token for the (AssistantAppSettingsProvider:interface). Resolves a noop\nuntil the host registers one."
+        }
+      ],
+      "exports": [
         {
           "kind": "js",
-          "name": "*",
+          "name": "AssistantAppSettingsProvider",
           "declaration": {
-            "name": "*",
-            "package": "./fallback-agents"
+            "name": "AssistantAppSettingsProvider",
+            "module": "src/provider/assistant-app-settings.ts"
           }
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/config/validate-providers.ts",
-      "declarations": [],
-      "exports": []
-    },
     {
       "kind": "javascript-module",
       "path": "src/state/ai-assistant-slice.ts",
@@ -3971,6 +4232,14 @@
             "module": "src/state/debug-event-log.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "TurnFailureReason",
+          "declaration": {
+            "name": "TurnFailureReason",
+            "module": "src/state/debug-event-log.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "recordTurnError",
@@ -6771,6 +7040,24 @@
               "privacy": "private",
               "description": "Active agent's tail-context selector (static value or per-turn resolver). The driver frames\nthe resolved string in a `<system-reminder>` marker and injects it at the message tail."
             },
+            {
+              "kind": "field",
+              "name": "activeResponseSchemaInput",
+              "type": {
+                "text": "ResponseSchemaInput | undefined"
+              },
+              "privacy": "private",
+              "description": "Active agent's structured-output schema selector (static value or per-turn resolver).\nWhen it resolves to a schema, the model's final answer is constrained to it this turn."
+            },
+            {
+              "kind": "field",
+              "name": "activeFallbacks",
+              "type": {
+                "text": "ChatFallback[] | undefined"
+              },
+              "privacy": "private",
+              "description": "Active agent's refusal-fallback chain (static). Passed through to the provider so a refused\nturn (e.g. Fable 5) is re-run on the next model server-side."
+            },
             {
               "kind": "field",
               "name": "activeOnUnresolvedTool",
@@ -6839,6 +7126,39 @@
               "privacy": "private",
               "description": "Unsubscribe handle for the provider-registry change listener (only set when\nthe injected registry is observable). Called in `dispose` so the long-lived\nregistry doesn't retain this driver — see the constructor and the sub-agent\nteardown in `runSubAgent`."
             },
+            {
+              "kind": "field",
+              "name": "maxToolIterations",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "description": "Hard cap on tool-loop iterations.",
+              "default": "maxToolIterations"
+            },
+            {
+              "kind": "field",
+              "name": "sessionKey",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "description": "Session identity used to file meta events onto the shared debug-log timeline.",
+              "default": "sessionKey"
+            },
+            {
+              "kind": "field",
+              "name": "activityBus",
+              "type": {
+                "text": "ActivityBus"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "description": "Injected activity bus; defaults to a no-op off-browser (Node/tests/headless).",
+              "default": "activityBus"
+            },
             {
               "kind": "method",
               "name": "dispose",
@@ -6892,6 +7212,66 @@
               },
               "description": "Finish a turn whose signal aborted. A user cancel adds a subtle \"Stopped.\"\nmarker; a dispose-driven abort stops quietly (the widget is gone and the\ncached history would otherwise gain a stray marker on remount)."
             },
+            {
+              "kind": "method",
+              "name": "turnDone",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "ChatDriverResult"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "failureReason",
+                  "optional": true,
+                  "type": {
+                    "text": "TurnFailureReason"
+                  }
+                }
+              ],
+              "description": "Build the `done` loop result, carrying the typed failure reason when the turn\nbailed (PTC-0). The discriminant stays `'done'` either way — the same value a\nclean turn returns — so consumers matching on `reason === 'done'` are unchanged;\n`failureReason` is simply present on a failure and absent on success. Omitted\n(rather than set to `undefined`) so a happy-path result stays byte-identical to\nthe historical `{ reason: 'done' }`."
+            },
+            {
+              "kind": "method",
+              "name": "failureReasonOf",
+              "privacy": "private",
+              "static": true,
+              "return": {
+                "type": {
+                  "text": "TurnFailureReason | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "result",
+                  "type": {
+                    "text": "ChatDriverResult"
+                  }
+                }
+              ],
+              "description": "The typed failure reason on a loop result, or `undefined` for a clean turn / handoff."
+            },
+            {
+              "kind": "method",
+              "name": "loopEndDetail",
+              "privacy": "private",
+              "static": true,
+              "return": {
+                "type": {
+                  "text": "{ failureReason: TurnFailureReason } | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "result",
+                  "type": {
+                    "text": "ChatDriverResult"
+                  }
+                }
+              ],
+              "description": "Build the `tool-loop-end` event detail for a turn's result. A failure carries a\n`{ failureReason }` detail; a clean turn emits `undefined` — the historical shape,\nkept byte-identical so subscribers see exactly what they always have."
+            },
             {
               "kind": "method",
               "name": "applyAgent",
@@ -8098,7 +8478,7 @@
               },
               "privacy": "private",
               "readonly": true,
-              "default": "new ChatDriver(\n      providerRegistry,\n      {},\n      [],\n      undefined,\n      undefined,\n      options.maxToolIterations,\n      options.maxFoldOperations,\n      options.maxTurnSnapshots,\n      this.sessionKey,\n    )"
+              "default": "new ChatDriver(providerRegistry, {\n      maxToolIterations: options.maxToolIterations,\n      maxFoldOperations: options.maxFoldOperations,\n      maxTurnSnapshots: options.maxTurnSnapshots,\n      sessionKey: this.sessionKey,\n      activityBus: options.activityBus,\n    })"
             },
             {
               "kind": "field",