@genesislcap/ai-assistant 14.420.0 → 14.421.0

package/dist/esm/state/session-store.js

@@ -0,0 +1,39 @@
+import { createStore } from '@genesislcap/foundation-redux';
+import { aiAssistantSlice, defaultSessionState, } from './ai-assistant-slice';
+const sessionStores = new Map();
+function makeStore(devTools) {
+    return createStore([aiAssistantSlice], { aiAssistant: defaultSessionState }, devTools !== undefined ? { devTools } : undefined);
+}
+/**
+ * Returns the session store for the given key, creating one if it does not
+ * already exist. Omit `devTools` (or pass `undefined`) to defer to `isDev()`.
+ * Pass `true` to force-enable or `false` to force-disable Redux DevTools.
+ */
+export function getSessionStore(key, devTools) {
+    const existing = sessionStores.get(key);
+    if (existing)
+        return existing;
+    const created = makeStore(devTools);
+    sessionStores.set(key, created);
+    return created;
+}
+/**
+ * Returns true if a session store already exists for the given key.
+ */
+export function hasSessionStore(key) {
+    return sessionStores.has(key);
+}
+/**
+ * Deletes the session store for the given key.
+ */
+export function deleteSessionStore(key) {
+    sessionStores.delete(key);
+}
+/**
+ * Removes all session stores. Exposed for test isolation only — not part of the public API.
+ *
+ * @internal
+ */
+export function clearAllSessionStores() {
+    sessionStores.clear();
+}

package/dist/esm/suggestions/chat-suggestions.js

@@ -0,0 +1,147 @@
+import { __decorate } from "tslib";
+import { customElement, observable, html, css, repeat, when } from '@genesislcap/web-core';
+import { GenesisElement } from '@genesislcap/web-core';
+const PILL_ANIMATION_STAGGER_MS = 70;
+const template = html `
+  ${when((x) => x.state.status === 'loading', html `
+      <div class="suggestions-container">
+        ${repeat(() => Array.from({ length: 3 }), html `
+            <div class="suggestion-placeholder"></div>
+          `)}
+      </div>
+    `)}
+  ${when((x) => x.state.status === 'loaded', html `
+      <div class="suggestions-container">
+        ${repeat((x) => x.state.suggestions, html `
+            <button
+              class="suggestion-pill"
+              style="animation-delay: ${(_, c) => c.index * PILL_ANIMATION_STAGGER_MS}ms"
+              @click="${(suggestion, c) => c.parent.handleSuggestionClick(suggestion)}"
+            >
+              ${(suggestion) => suggestion}
+            </button>
+          `)}
+      </div>
+    `)}
+`;
+const styles = css `
+  :host {
+    display: block;
+  }
+
+  .suggestions-container {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px;
+    padding: 10px calc(var(--design-unit) * 3px) 6px;
+    background-color: var(--neutral-layer-2);
+    animation: suggestions-appear 0.2s ease-out both;
+  }
+
+  @keyframes suggestions-appear {
+    from {
+      opacity: 0;
+      transform: translateY(6px);
+    }
+
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+
+  .suggestion-pill {
+    display: inline-flex;
+    align-items: center;
+    padding: 5px 14px;
+    background: color-mix(in srgb, var(--accent-fill-rest) 10%, var(--neutral-layer-3));
+    color: var(--neutral-foreground-rest);
+    border: 1px solid color-mix(in srgb, var(--accent-fill-rest) 25%, var(--neutral-stroke-rest));
+    border-radius: 20px;
+    font-family: var(--body-font);
+    font-size: 0.85em;
+    cursor: pointer;
+    transition:
+      background 0.15s ease,
+      border-color 0.15s ease,
+      transform 0.15s ease,
+      box-shadow 0.15s ease;
+    animation: pill-appear 0.3s ease-out both;
+    max-width: 100%;
+    white-space: normal;
+    text-align: left;
+  }
+
+  .suggestion-pill:hover {
+    background: color-mix(in srgb, var(--accent-fill-rest) 20%, var(--neutral-layer-3));
+    border-color: color-mix(in srgb, var(--accent-fill-rest) 50%, var(--neutral-stroke-rest));
+    transform: translateY(-1px);
+    box-shadow: 0 2px 8px color-mix(in srgb, var(--accent-fill-rest) 20%, transparent);
+  }
+
+  .suggestion-pill:active {
+    transform: translateY(0);
+    box-shadow: none;
+  }
+
+  @keyframes pill-appear {
+    from {
+      opacity: 0;
+      transform: scale(0.88) translateY(4px);
+    }
+
+    to {
+      opacity: 1;
+      transform: scale(1) translateY(0);
+    }
+  }
+
+  .suggestion-placeholder {
+    height: 30px;
+    width: 110px;
+    background: var(--neutral-layer-3);
+    border-radius: 20px;
+    animation: placeholder-pulse 1.6s ease-in-out infinite;
+  }
+
+  .suggestion-placeholder:nth-child(2) {
+    width: 150px;
+    animation-delay: 0.25s;
+  }
+
+  .suggestion-placeholder:nth-child(3) {
+    width: 130px;
+    animation-delay: 0.5s;
+  }
+
+  @keyframes placeholder-pulse {
+    0%,
+    100% {
+      opacity: 0.35;
+    }
+
+    50% {
+      opacity: 0.65;
+    }
+  }
+`;
+let ChatSuggestions = class ChatSuggestions extends GenesisElement {
+    constructor() {
+        super(...arguments);
+        this.state = { status: 'idle' };
+    }
+    handleSuggestionClick(suggestion) {
+        this.$emit('suggestion-clicked', suggestion);
+    }
+};
+__decorate([
+    observable
+], ChatSuggestions.prototype, "state", void 0);
+ChatSuggestions = __decorate([
+    customElement({
+        name: 'chat-suggestions',
+        template,
+        styles,
+    })
+], ChatSuggestions);
+export { ChatSuggestions };

package/dist/esm/utils/index.js

@@ -1 +1,2 @@
 export * from './logger';
+export * from './tool-fold';

package/dist/esm/utils/tool-fold.js

@@ -0,0 +1,92 @@
+import { __awaiter } from "tslib";
+/**
+ * Symbol used to attach ToolFold metadata to a facade handler function.
+ * The ChatDriver inspects this to detect fold facades at runtime.
+ *
+ * @internal
+ */
+export const TOOL_FOLD_SYMBOL = Symbol('toolFold');
+/**
+ * Creates a tool fold — a facade that hides a group of related tools behind a single
+ * named entry, revealing them progressively when the model invokes the facade.
+ *
+ * The `tools` and `handlers` parameters accept the exact same types as `AgentConfig.toolDefinitions`
+ * and `AgentConfig.toolHandlers`, so existing tool creation functions can be passed in unchanged.
+ *
+ * @example
+ * ```typescript
+ * const tradingTools = createToolFold({
+ *   name: 'trading_tools',
+ *   tools: createTradesToolDefinitions(),
+ *   handlers: createTradesToolHandlers(connect),
+ * });
+ *
+ * const agent: AgentConfig = {
+ *   name: 'Trades',
+ *   systemPrompt: '...',
+ *   toolDefinitions: [getCurrentDateDef, tradingTools.definition],
+ *   toolHandlers: { get_current_date: handler, ...tradingTools.handler },
+ * };
+ * ```
+ *
+ * @example Nesting folds
+ * ```typescript
+ * const insertFold = createToolFold({
+ *   name: 'trade_insertion',
+ *   tools: [validateDef, insertDef],
+ *   handlers: { validate_trade: vHandler, insert_trade: iHandler },
+ * });
+ *
+ * const tradingFold = createToolFold({
+ *   name: 'trading_tools',
+ *   tools: [searchDef, insertFold.definition],
+ *   handlers: { search_trades: sHandler, ...insertFold.handler },
+ * });
+ * ```
+ *
+ * @beta
+ */
+export function createToolFold(config) {
+    var _a, _b;
+    const description = (_a = config.description) !== null && _a !== void 0 ? _a : `Contains: ${config.tools.map((t) => t.name).join(', ')}. Invoke to access these tools.`;
+    const fold = {
+        name: config.name,
+        description,
+        usageNotes: config.usageNotes,
+        tools: config.tools,
+        handlers: config.handlers,
+        exclusive: (_b = config.exclusive) !== null && _b !== void 0 ? _b : true,
+    };
+    const definition = {
+        name: config.name,
+        description,
+        parameters: { type: 'object', properties: {} },
+    };
+    // The facade handler body is never actually called — the driver intercepts it
+    // via TOOL_FOLD_SYMBOL before dispatch. The body is a no-op fallback.
+    const facadeHandler = () => __awaiter(this, void 0, void 0, function* () { return `Fold: ${config.name}`; });
+    facadeHandler[TOOL_FOLD_SYMBOL] = fold;
+    return {
+        definition,
+        handler: {
+            [config.name]: facadeHandler,
+        },
+    };
+}
+/**
+ * Expands a flat list of tool definitions into a nested tree by resolving fold
+ * metadata from the corresponding handlers. Use this for debug output so the
+ * full tool hierarchy is visible rather than just the top-level facade names.
+ *
+ * @beta
+ */
+export function expandToolTree(definitions, handlers) {
+    return definitions.map((def) => {
+        const handler = handlers[def.name];
+        const fold = handler ? handler[TOOL_FOLD_SYMBOL] : undefined;
+        if (fold) {
+            return Object.assign(Object.assign({}, def), { tools: expandToolTree(fold.tools, fold.handlers) });
+        }
+        return Object.assign({}, def);
+    });
+}

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/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/config/config.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/styles/ai-colours.ts","../src/styles/index.ts","../src/styles/styles.ts","../src/tags/index.ts","../src/types/ai-chat-widget.ts","../src/utils/index.ts","../src/utils/logger.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/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/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/index.ts","../src/utils/logger.ts","../src/utils/tool-fold.ts"],"version":"5.9.2"}

package/docs/migration-FUI-2495.md

@@ -0,0 +1,339 @@
+# Migration Guide — FUI-2495 (AI Header & Orchestration)
+
+This document lists every breaking change introduced by the `mw/FUI-2495-ai-header-and-orchestration` branch and shows exactly what to change in consumer code.
+
+---
+
+## 1. `ChatConfig` restructured into sub-namespaces
+
+`ChatConfig` (from `@genesislcap/foundation-ai`) was a flat interface. It is now a three-field wrapper. The old fields have been split across `ui`, `agent`, and `suggestions`.
+
+The old `ChatConfig` interface is renamed `ChatUiConfig` and is still exported for typing the `ui` field.
+
+**Before**
+
+```ts
+import type { ChatConfig } from '@genesislcap/foundation-ai';
+
+const chatConfig: ChatConfig = {
+  showToolCalls: true,
+  showThinkingSteps: false,
+  allowDebugDownload: true,
+  acceptedFiles: '.txt,.md',
+  loadingDelay: 5,
+  animations: { enabledAnimations: ['halo'] },
+  maxToolIterations: 50,
+};
+```
+
+**After**
+
+```ts
+import type { ChatConfig } from '@genesislcap/foundation-ai';
+
+const chatConfig: ChatConfig = {
+  ui: {
+    showToolCalls: true,
+    showThinkingSteps: false,
+    allowDebugDownload: true,
+    acceptedFiles: '.txt,.md',
+    loadingDelay: 5,
+    animations: { enabledAnimations: ['halo'] },
+  },
+  agent: {
+    maxToolIterations: 50,
+  },
+};
+```
+
+**New fields available** (all optional):
+
+| Namespace | Field | Description |
+|---|---|---|
+| `ui` | `showSplash` | Show `slot="splash"` content when no messages exist |
+| `ui` | `showAgentSwitchIndicator` | Show a divider when the active specialist changes |
+| `ui` | `showContextUsage` | Show context window usage in the settings panel |
+| `agent` | `maxHandoffs` | Max agent-to-agent handoffs per user turn (default: 3) |
+| `agent` | `classifierHistoryLength` | Recent messages passed to the classifier (default: 4) |
+| `agent` | `classifierRetries` | Retries on classifier failure (default: 2) |
+| `agent` | `maxFoldOperations` | Max fold open/close cycles before a guidance message is injected (default: 5) |
+| `suggestions` | `behavior` | `'never'` \| `'initial'` \| `'always'` |
+| `suggestions` | `count` | Number of suggestions to generate (default: 3) |
+| `suggestions` | `prompt` | Custom prompt to steer suggestion generation |
+
+---
+
+## 2. `AgentConfig` is now a discriminated union
+
+`AgentConfig` (from `@genesislcap/foundation-mf/ai-assistant`) was a single flat interface. It is now a union of `SpecialistAgentConfig` (requires `description`) and `FallbackAgentConfig` (requires `fallback: true`).
+
+**Existing single-agent usage — no change required.** TypeScript will resolve the object as `SpecialistAgentConfig` automatically as long as `description` is present.
+
+**Before (multi-agent)**
+
+```ts
+import type { AgentConfig } from '@genesislcap/foundation-mf/ai-assistant';
+
+const agents: AgentConfig[] = [
+  {
+    name: 'Trades Agent',
+    description: 'Handles trade queries and execution.',
+    systemPrompt: '...',
+    toolHandlers: { ... },
+  },
+  {
+    name: 'General Agent',
+    description: 'Handles everything else.',
+    systemPrompt: '...',
+  },
+];
+```
+
+**After** — if you want a dedicated fallback agent, mark it explicitly. Specialist agents are unchanged.
+
+```ts
+import type { AgentConfig } from '@genesislcap/foundation-mf/ai-assistant';
+
+const agents: AgentConfig[] = [
+  {
+    name: 'Trades Agent',
+    description: 'Handles trade queries and execution.',  // still required for specialists
+    systemPrompt: '...',
+    toolHandlers: { ... },
+  },
+  {
+    name: 'General Agent',
+    fallback: true,   // replaces description for the catch-all agent
+    systemPrompt: '...',
+  },
+];
+```
+
+**Rules:**
+- A specialist must have `description` and must not have `fallback`.
+- A fallback must have `fallback: true` and must not have `description`.
+- Only one fallback is permitted per `agents` array.
+
+---
+
+## 3. `chat-popout` and `chat-popin` bus events no longer carry a state payload
+
+`AiAssistantSerializedState` has been deleted. The `chat-popout` and `chat-popin` bus events now carry `undefined`. State is managed automatically by the Redux session store shared between the bubble and layout instances — no manual transfer is required.
+
+**Before**
+
+```ts
+import { agenticActivityBus } from '@genesislcap/foundation-mf/ai-assistant';
+import type { AiAssistantSerializedState } from '@genesislcap/foundation-mf/ai-assistant';
+
+agenticActivityBus.subscribe('chat-popin', ({ state }: { state: AiAssistantSerializedState }) => {
+  myAssistant.applyState(state);
+});
+```
+
+**After**
+
+```ts
+import { agenticActivityBus } from '@genesislcap/foundation-mf/ai-assistant';
+
+// No payload — state transfer is automatic.
+agenticActivityBus.subscribe('chat-popin', () => {
+  // React to the event if needed, but state is already synced.
+});
+```
+
+Remove all imports of `AiAssistantSerializedState` — it no longer exists.
+
+---
+
+## 4. `applyState()` and `serializeState()` removed from `FoundationAiAssistant`
+
+These methods were used to manually transfer state between the bubble and layout instances. The session store makes them redundant.
+
+**Before**
+
+```ts
+const state = bubbleAssistant.serializeState();
+layoutAssistant.applyState(state);
+```
+
+**After** — delete these call sites. The session store handles state continuity automatically when the component is connected/disconnected.
+
+---
+
+## 5. `ChatInteraction.resolved` changed from `boolean` to `InteractionResult<unknown>`
+
+**Before**
+
+```ts
+if (this.resolved === true) {
+  // show read-only state
+}
+```
+
+**After** — use a truthy check. The value itself is now the result object, which widgets can also read.
+
+```ts
+if (this.resolved) {
+  // show read-only state
+  // optionally: use this.resolved.value for the result data
+}
+```
+
+If your interaction component explicitly typed this field:
+
+```ts
+// Before
+resolved?: boolean;
+
+// After
+import type { InteractionResult } from '@genesislcap/foundation-ai';
+resolved?: InteractionResult<unknown>;
+```
+
+---
+
+## 6. `ChatToolCall` changed from an interface to a union type
+
+`ChatToolCall` is now `ChatToolCallBase | ChatToolCallUnknown`. Code that was written against the original interface will still compile, but exhaustive handling should use the new type guard.
+
+**Before**
+
+```ts
+import type { ChatToolCall } from '@genesislcap/foundation-ai';
+
+function handleToolCall(tc: ChatToolCall) {
+  console.log(tc.name, tc.args);
+}
+```
+
+**After** — use `isChatToolCallUnknown` before narrowing:
+
+```ts
+import { isChatToolCallUnknown } from '@genesislcap/foundation-ai';
+import type { ChatToolCall } from '@genesislcap/foundation-ai';
+
+function handleToolCall(tc: ChatToolCall) {
+  if (isChatToolCallUnknown(tc)) {
+    console.warn('Unknown tool call', tc.name, 'Available:', tc.availableTools);
+    return;
+  }
+  console.log(tc.name, tc.args);
+}
+```
+
+New optional fields on all `ChatToolCall` objects (not sent to the AI provider):
+
+- `foldEvent?: 'open' | 'close'` — set when this call is a fold lifecycle event
+- `foldPath?: string[]` — breadcrumb path of active folds when the call was made
+
+---
+
+## 7. `ChatRole` has a new `'system-event'` value
+
+If you have an exhaustive `switch` or conditional chain on `ChatRole`, add a case for `'system-event'`.
+
+**Before**
+
+```ts
+switch (message.role) {
+  case 'user': ...
+  case 'assistant': ...
+  case 'system': ...
+  case 'tool': ...
+}
+```
+
+**After**
+
+```ts
+switch (message.role) {
+  case 'user': ...
+  case 'assistant': ...
+  case 'system': ...
+  case 'tool': ...
+  case 'system-event': ...
+}
+```
+
+---
+
+## 8. `GeminiAIConfig.model` is now typed as `GeminiModelId`
+
+The `model` field no longer accepts arbitrary strings. Only the values in `SUPPORTED_GEMINI_MODEL_IDS` are accepted at runtime and at compile time.
+
+**Before**
+
+```ts
+const config: GeminiAIConfig = {
+  providerType: 'gemini',
+  model: 'gemini-2.0-flash',   // was accepted as string
+};
+```
+
+**After**
+
+```ts
+import { SUPPORTED_GEMINI_MODEL_IDS } from '@genesislcap/foundation-ai';
+import type { GeminiAIConfig } from '@genesislcap/foundation-ai';
+
+const config: GeminiAIConfig = {
+  providerType: 'gemini',
+  model: 'gemini-2.5-flash',   // must be a GeminiModelId
+};
+```
+
+Supported values: `'gemini-2.5-flash'` | `'gemini-2.5-flash-lite'`
+
+If you were using `'gemini-2.0-flash'` or another deprecated model, migrate to `'gemini-2.5-flash'`.
+
+---
+
+## 9. `downloadHistory()` renamed to `getDebugLog()`
+
+**Before**
+
+```ts
+assistant.downloadHistory();
+```
+
+**After**
+
+```ts
+assistant.getDebugLog();
+```
+
+---
+
+## 10. `headerTitle` now defaults to `'Genesis Assistant'`
+
+Previously `headerTitle` was `undefined` by default, so the header title area was empty unless explicitly set. It now defaults to `'Genesis Assistant'`.
+
+If you were relying on the absence of a title (e.g. to hide a title element via CSS `:empty` or conditional rendering), set the attribute explicitly to an empty string or adjust your CSS.
+
+**Before** — no attribute set, title area was empty.
+
+**After** — set explicitly if you want a different value or no value:
+
+```html
+<!-- Custom title -->
+<foundation-ai-assistant header-title="My Assistant"></foundation-ai-assistant>
+
+<!-- No title -->
+<foundation-ai-assistant header-title=""></foundation-ai-assistant>
+```
+
+---
+
+## Quick reference checklist
+
+- [ ] Move `ChatConfig` fields into `ui`, `agent`, and `suggestions` sub-objects
+- [ ] Remove all imports of `AiAssistantSerializedState`
+- [ ] Remove `chat-popin`/`chat-popout` state payload destructuring
+- [ ] Remove calls to `applyState()` and `serializeState()`
+- [ ] Update `ChatInteraction.resolved` checks from `=== true` to truthy
+- [ ] Update `AgentConfig` arrays — add `fallback: true` to catch-all agents (remove `description` from them)
+- [ ] Add `'system-event'` case to any exhaustive `ChatRole` switches
+- [ ] Update `GeminiAIConfig.model` from `'gemini-2.0-flash'` to a supported `GeminiModelId`
+- [ ] Rename `downloadHistory()` calls to `getDebugLog()`
+- [ ] Audit `header-title` attribute usage if you relied on an empty default