@genesislcap/ai-assistant 14.420.0 → 14.421.1

package/dist/esm/main/main.js

@@ -1,5 +1,27 @@
+// =============================================================================
+// ARCHITECTURAL RULES — read before modifying this file
+// =============================================================================
+//
+// 1. STORE INIT MUST PRECEDE super.connectedCallback()
+//    `_sessionRef` must be assigned before calling `super.connectedCallback()`.
+//    FAST triggers its first render inside `super.connectedCallback()`. The store
+//    Proxy calls Observable.track() when a slice is read, which wires up FAST's
+//    reactivity. If `_sessionRef` is null during that first render, no tracking
+//    is registered and subsequent Redux dispatches will not trigger re-renders.
+//    Do not reorder these lines.
+//
+// 2. MARK @volatile ON GETTERS WITH CONDITIONAL OBSERVABLE ACCESS
+//    FAST only tracks observables that are actually accessed during a getter's
+//    last evaluation. If a getter has branches that access different observables
+//    depending on runtime state (e.g. filtering over messages of varying types,
+//    or a ternary that reads one observable OR another), FAST may not know to
+//    re-evaluate when an unvisited branch's observable changes. Mark such
+//    getters @volatile so FAST always re-evaluates them when any dependency
+//    changes, rather than relying on cached dependency tracking.
+//
+// =============================================================================
 var FoundationAiAssistant_1;
-import { __awaiter, __decorate } from "tslib";
+import { __awaiter, __decorate, __rest } from "tslib";
 import { AIProvider } from '@genesislcap/foundation-ai';
 import { avoidTreeShaking } from '@genesislcap/foundation-utils';
 import { customElement, html, GenesisElement, observable, volatile, attr, } from '@genesislcap/web-core';
@@ -10,18 +32,32 @@ import { ChatDriver } from '../components/chat-driver/chat-driver';
 import { AiChatInteractionWrapper } from '../components/chat-interaction-wrapper/chat-interaction-wrapper';
 import { AiChatMarkdown } from '../components/chat-markdown/chat-markdown';
 import { AiHaloOverlay } from '../components/halo-overlay';
+import { OrchestratingDriver } from '../components/orchestrating-driver/orchestrating-driver';
+import { getOrCreateDriver, deleteDriver } from '../state/driver-registry';
+import { getSessionStore, hasSessionStore } from '../state/session-store';
+import { ChatSuggestions } from '../suggestions/chat-suggestions';
 import { logger } from '../utils/logger';
+import { expandToolTree } from '../utils/tool-fold';
 import { styles } from './main.styles';
 import { FoundationAiAssistantTemplate } from './main.template';
 import { ALL_ANIMATIONS } from './main.types';
+/** Context window sizes (in tokens) for known models. */
+const MODEL_CONTEXT_LIMITS = {
+    'gemini-2.5-flash': 1048576,
+    'gemini-2.5-flash-lite': 1048576,
+    'gpt-4o': 128000,
+    'gpt-4o-mini': 128000,
+    'gpt-4-turbo': 128000,
+};
 // Register supporting components when the main component module is imported.
-avoidTreeShaking(AiChatMarkdown, AiChatInteractionWrapper, AiHaloOverlay, AiChatBubble, AiActivityHalo);
+avoidTreeShaking(AiChatMarkdown, AiChatInteractionWrapper, AiHaloOverlay, AiChatBubble, AiActivityHalo, ChatSuggestions);
 /**
  * Foundation AI Assistant component.
  *
  * @remarks
  * Inject an `AIProvider` through the DI container. Pass agent configuration via the `agents`
- * property. The component creates a `ChatDriver` to manage the conversation loop.
+ * property. The component creates a `ChatDriver` (single agent) or `OrchestratingDriver`
+ * (multiple agents) to manage the conversation loop.
  *
  * Popout/collapse coordination uses `agenticActivityBus` topics `chat-popout` and `chat-popin` — not DOM `CustomEvent`s on this element.
  *
@@ -33,37 +69,143 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
     constructor() {
         super(...arguments);
         this.designSystemPrefix = 'rapid';
+        this.headerTitle = 'Genesis Assistant';
         this.placeholder = 'Message assistant...';
         this.chatConfig = {};
-        this.messages = [];
-        this.state = 'idle';
-        this.inputValue = '';
+        /** When set, enables Redux DevTools for this instance's session store. */
+        this.debugRedux = false;
+        // ---- Transient UI state (stays as @observable on the component) ----
+        this._suggestionsGeneration = 0;
         this.attachments = [];
         this.attachmentErrors = [];
-        /** Current user-facing toggle state for tool call visibility. */
-        this.showToolCalls = false;
-        /** Current user-facing toggle state for thinking step visibility. */
-        this.showThinkingSteps = false;
-        /** Currently enabled animations. */
-        this.enabledAnimations = [];
         /** Whether the loading spinner is currently visible. Controlled by the loading delay timer. */
         this.showLoadingIndicator = false;
         /** Whether the settings panel is open. */
         this.settingsOpen = false;
+        /** Whether the splash overlay is currently showing (no messages and showSplash is enabled). Reflected as a boolean attribute on the host. */
+        this.showingSplash = false;
         this.haloStartPublished = false;
-        /**
-         * Whether the halo animation should be shown.
-         * True when the AI is actively computing (loading state, no pending interaction).
-         */
-        this.showHalo = false;
+        /** True when the user has intentionally scrolled away from the bottom — suppresses auto-scroll. */
+        this._userScrolledAway = false;
+        this.showHalo = 'no';
+    }
+    get messages() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.messages) !== null && _b !== void 0 ? _b : [];
+    }
+    set messages(value) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setMessages(value);
+        this.handleMessagesUpdate();
+    }
+    get state() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.state) !== null && _b !== void 0 ? _b : 'idle';
+    }
+    set state(value) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setState(value);
+        this.syncShowHalo();
+    }
+    get activeAgent() {
+        var _a;
+        return (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.activeAgent;
+    }
+    set activeAgent(value) {
+        var _a, _b;
+        // Strip toolHandlers before storing — functions are non-serializable and Redux
+        // serializable-state middleware will warn. toolHandlers are never read back from
+        // the store; they are always sourced from this.agents when the driver is built.
+        if (value) {
+            const { toolHandlers: _ } = value, serializable = __rest(value, ["toolHandlers"]);
+            (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setActiveAgent(serializable);
+        }
+        else {
+            (_b = this._sessionRef) === null || _b === void 0 ? void 0 : _b.actions.aiAssistant.setActiveAgent(undefined);
+        }
+    }
+    get suggestionsState() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.suggestionsState) !== null && _b !== void 0 ? _b : { status: 'idle' };
+    }
+    set suggestionsState(value) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setSuggestionsState(value);
+    }
+    /** Current user-facing toggle state for tool call visibility. */
+    get showToolCalls() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.showToolCalls) !== null && _b !== void 0 ? _b : false;
+    }
+    set showToolCalls(value) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setShowToolCalls(value);
+    }
+    /** Current user-facing toggle state for thinking step visibility. */
+    get showThinkingSteps() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.showThinkingSteps) !== null && _b !== void 0 ? _b : false;
+    }
+    set showThinkingSteps(value) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setShowThinkingSteps(value);
+    }
+    /** Current user-facing toggle state for agent switch indicator visibility. */
+    get showAgentSwitchIndicator() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.showAgentSwitchIndicator) !== null && _b !== void 0 ? _b : false;
+    }
+    set showAgentSwitchIndicator(value) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setShowAgentSwitchIndicator(value);
+    }
+    /** Currently enabled animations. */
+    get enabledAnimations() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.enabledAnimations) !== null && _b !== void 0 ? _b : [];
+    }
+    set enabledAnimations(value) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setEnabledAnimations(value);
+    }
+    /** Most recent prompt token count from the AI provider, if available. */
+    get contextTokens() {
+        var _a;
+        return (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.contextTokens;
+    }
+    set contextTokens(value) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setContextTokens(value);
+    }
+    /** Context window size for the active model, if known. */
+    get contextLimit() {
+        var _a;
+        return (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.contextLimit;
+    }
+    set contextLimit(value) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setContextLimit(value);
+    }
+    get inputValue() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.inputValue) !== null && _b !== void 0 ? _b : '';
+    }
+    set inputValue(value) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setInputValue(value);
     }
     syncShowHalo() {
         if (this.state !== 'loading') {
-            this.showHalo = false;
+            this.showHalo = 'no';
             return;
         }
         const last = this.messages[this.messages.length - 1];
-        this.showHalo = !(last === null || last === void 0 ? void 0 : last.interaction);
+        if (last === null || last === void 0 ? void 0 : last.interaction) {
+            this.showHalo = 'no';
+        }
+        else if (this.showHalo !== 'orchestrating') {
+            this.showHalo = 'agent';
+        }
     }
     /** True when there is a pending (unresolved) interaction — disables the popout button. */
     get hasActivePendingInteraction() {
@@ -76,7 +218,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         var _a;
         if (!((_a = this.enabledAnimations) === null || _a === void 0 ? void 0 : _a.includes('halo')))
             return;
-        if (!this.showHalo) {
+        if (this.showHalo === 'no') {
             agenticActivityBus.publish('halo-stop', undefined);
             this.haloStartPublished = false;
         }
@@ -98,10 +240,24 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      * Messages filtered by the current toggle state.
      * Tool-related messages (those with toolCalls or toolResult) are hidden when
      * `showToolCalls` is false.
+     *
+     * Marked `@volatile` because the filter branches conditionally access
+     * `showToolCalls`, `showThinkingSteps`, and `showAgentSwitchIndicator`
+     * depending on message content. Without it, FAST would only track the
+     * observables accessed on the last evaluation and miss toggle changes that
+     * happen to hit an untracked branch.
      */
     get visibleMessages() {
+        var _a;
+        const showAgentSwitchIndicator = ((_a = this.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.showAgentSwitchIndicator) != null
+            ? this.showAgentSwitchIndicator
+            : this.showToolCalls;
         return this.messages.filter((m) => {
             var _a, _b, _c;
+            // Agent switch indicators are shown when the toggle is on (or showToolCalls implies it)
+            if (m.role === 'system-event') {
+                return showAgentSwitchIndicator;
+            }
             // Never show tool messages to the user
             if (m.role === 'tool') {
                 return false;
@@ -118,45 +274,247 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             return !isToolRelated || this.showToolCalls;
         });
     }
+    agentsChanged() {
+        var _a, _b, _c;
+        // Guard: driver doesn't exist yet during connectedCallback — createDriver/wireDriver handle that.
+        if (!this.driver)
+            return;
+        const key = this.getStateKey();
+        if (!key)
+            return;
+        // Skip rebuild if the agent configuration hasn't meaningfully changed.
+        // This prevents spurious driver teardowns when the collapse-mode element
+        // connects and its parent re-assigns the same agents array, which would
+        // destroy pending interactions in the existing driver.
+        const newKey = this.getAgentsKey(this.agents);
+        if (newKey === this._driverAgentsKey)
+            return;
+        this._driverAgentsKey = newKey;
+        // Don't rebuild while the driver is busy — it was created with the correct agents
+        // and has live pending interactions. This prevents the collapse element (which
+        // initially has no agents, then gets them assigned by its wrapper) from tearing
+        // down a mid-flight driver and creating a fresh idle one.
+        if (this.driver.isBusy())
+            return;
+        const history = (_c = (_b = (_a = this.driver).getRawHistory) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : [];
+        this.unwireDriver();
+        deleteDriver(key);
+        this.driver = getOrCreateDriver(key, () => this.createDriver());
+        this.wireDriver();
+        if (history.length)
+            this.driver.loadHistory([...history]);
+    }
+    /** Returns a stable fingerprint for an agents array based on agent names and tool handler keys. */
+    getAgentsKey(agents) {
+        if (!(agents === null || agents === void 0 ? void 0 : agents.length))
+            return '';
+        return agents
+            .map((a) => {
+            var _a;
+            const toolNames = Object.keys((_a = a.toolHandlers) !== null && _a !== void 0 ? _a : {})
+                .sort()
+                .join('+');
+            return `${a.name}[${toolNames}]`;
+        })
+            .join(',');
+    }
+    /**
+     * Pure factory — creates a ChatDriver or OrchestratingDriver based on the
+     * current agent configuration. Does not wire event listeners or register in
+     * the driver registry.
+     */
+    createDriver() {
+        var _a, _b, _c;
+        const agent = (_a = this.chatConfig.agent) !== null && _a !== void 0 ? _a : {};
+        const { agents } = this;
+        if (agents && agents.length > 1) {
+            return new OrchestratingDriver(this.aiProvider, agents, {
+                maxHandoffs: agent.maxHandoffs,
+                classifierHistoryLength: agent.classifierHistoryLength,
+                classifierRetries: agent.classifierRetries,
+                maxToolIterations: agent.maxToolIterations,
+                maxFoldOperations: agent.maxFoldOperations,
+            });
+        }
+        const singleAgent = agents === null || agents === void 0 ? void 0 : agents[0];
+        this.activeAgent = singleAgent;
+        return new ChatDriver(this.aiProvider, (_b = singleAgent === null || singleAgent === void 0 ? void 0 : singleAgent.toolHandlers) !== null && _b !== void 0 ? _b : {}, (_c = singleAgent === null || singleAgent === void 0 ? void 0 : singleAgent.toolDefinitions) !== null && _c !== void 0 ? _c : [], singleAgent === null || singleAgent === void 0 ? void 0 : singleAgent.systemPrompt, singleAgent === null || singleAgent === void 0 ? void 0 : singleAgent.primerHistory, agent.maxToolIterations, agent.maxFoldOperations);
+    }
+    /**
+     * Attaches event listeners to the current driver. Stores a cleanup function
+     * so `unwireDriver` can remove them precisely. Safe to call multiple
+     * times — unwires any existing listeners first.
+     */
+    wireDriver() {
+        const { driver } = this;
+        if (!driver)
+            return;
+        // Idempotent — unwire previous listeners on this component before re-wiring.
+        this.unwireDriver();
+        const onHistoryUpdated = (e) => {
+            this.messages = [...e.detail];
+        };
+        driver.addEventListener('history-updated', onHistoryUpdated);
+        const cleanups = [
+            () => driver.removeEventListener('history-updated', onHistoryUpdated),
+        ];
+        if (driver instanceof OrchestratingDriver) {
+            const onOrchStart = () => {
+                this.showHalo = 'orchestrating';
+            };
+            const onOrchStop = () => {
+                if (this.showHalo === 'orchestrating')
+                    this.showHalo = 'agent';
+            };
+            const onAgentChanged = (e) => {
+                this.activeAgent = e.detail;
+            };
+            driver.addEventListener('orchestrating-start', onOrchStart);
+            driver.addEventListener('orchestrating-stop', onOrchStop);
+            driver.addEventListener('agent-changed', onAgentChanged);
+            cleanups.push(() => driver.removeEventListener('orchestrating-start', onOrchStart), () => driver.removeEventListener('orchestrating-stop', onOrchStop), () => driver.removeEventListener('agent-changed', onAgentChanged));
+        }
+        this.driverCleanup = () => {
+            for (const fn of cleanups)
+                fn();
+        };
+    }
+    /**
+     * Removes event listeners attached by `wireDriver`. Does not destroy
+     * the driver or remove it from the registry.
+     */
+    unwireDriver() {
+        var _a;
+        (_a = this.driverCleanup) === null || _a === void 0 ? void 0 : _a.call(this);
+        this.driverCleanup = undefined;
+    }
     connectedCallback() {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e;
+        // Initialise the store reference BEFORE super.connectedCallback() so that
+        // the first FAST render has access to the store. The store Proxy calls
+        // Observable.track(observableStore, sliceName) whenever a slice is read,
+        // and actions call Observable.notify — so FAST's reactivity wires up
+        // correctly only if _sessionRef is set during that first render pass.
+        const key = this.getStateKey();
+        const isNewStore = !hasSessionStore(key);
+        this._sessionRef = getSessionStore(key, this.debugRedux || undefined);
         super.connectedCallback();
-        const { showToolCalls, showThinkingSteps, animations } = this.chatConfig;
-        this.showToolCalls = showToolCalls === true;
-        this.showThinkingSteps = showThinkingSteps === true;
-        this.enabledAnimations =
-            (_a = animations === null || animations === void 0 ? void 0 : animations.enabled) !== null && _a !== void 0 ? _a : (animations ? [...ALL_ANIMATIONS] : []);
-        // TODO: multi-agent orchestration — classify intent and route to the correct agent
-        if (this.agents && this.agents.length > 1) {
-            logger.warn('FoundationAiAssistant: multiple agents configured but orchestration is not yet implemented. Only the first agent will be used.');
+        // Only apply chatConfig UI defaults to a freshly created store.
+        // Existing stores already hold the correct state from a prior session.
+        if (isNewStore) {
+            const ui = (_a = this.chatConfig.ui) !== null && _a !== void 0 ? _a : {};
+            this.showToolCalls = ui.showToolCalls === true;
+            this.showThinkingSteps = ui.showThinkingSteps === true;
+            this.showAgentSwitchIndicator = ui.showAgentSwitchIndicator === true;
+            this.enabledAnimations =
+                (_c = (_b = ui.animations) === null || _b === void 0 ? void 0 : _b.enabled) !== null && _c !== void 0 ? _c : (ui.animations ? [...ALL_ANIMATIONS] : []);
         }
-        const agent = (_b = this.agents) === null || _b === void 0 ? void 0 : _b[0];
-        this.driver = new ChatDriver(this.aiProvider, (_c = agent === null || agent === void 0 ? void 0 : agent.toolHandlers) !== null && _c !== void 0 ? _c : {}, (_d = agent === null || agent === void 0 ? void 0 : agent.toolDefinitions) !== null && _d !== void 0 ? _d : [], agent === null || agent === void 0 ? void 0 : agent.systemPrompt, agent === null || agent === void 0 ? void 0 : agent.primerHistory, this.chatConfig.maxToolIterations);
-        this.driver.addEventListener('history-updated', (e) => {
-            this.messages = [...e.detail];
-        });
-        // When embedded in a bubble (expand mode), listen for chat-popin to restore state
-        // when the layout panel collapses back.
+        this.driver = getOrCreateDriver(key, () => this.createDriver());
+        this._driverAgentsKey = this.getAgentsKey(this.agents);
+        this.wireDriver();
         if (this.popoutMode === 'expand') {
-            this.unsubBus = agenticActivityBus.subscribe('chat-popin', ({ state }) => {
-                this.applyState(state);
+            // Dual-listener guard: when the assistant is popped out into the layout
+            // panel, a collapse-mode element connects and wires to the same shared
+            // driver. Unwire this (hidden) instance on popout; re-wire on popin.
+            const unsubPopout = agenticActivityBus.subscribe('chat-popout', () => {
+                this.unwireDriver();
             });
+            const unsubPopin = agenticActivityBus.subscribe('chat-popin', () => {
+                this.wireDriver();
+            });
+            this.unsubBus = () => {
+                unsubPopout();
+                unsubPopin();
+            };
+        }
+        this.syncShowingSplash();
+        // Restore loading state if the driver is still executing mid-lifecycle.
+        // disconnectedCallback resets state to 'idle', so we must check real driver state here.
+        if ((_d = this.driver) === null || _d === void 0 ? void 0 : _d.isBusy()) {
+            this.state = 'loading';
+            this.startLoadingTimer();
+            // Subscribe once so that when the originating send() completes (possibly on a
+            // different element instance that has since disconnected), this element cleans up
+            // its own timer, syncs the halo, and triggers the post-response suggestion fetch.
+            this._executionCompletionUnsub = (_e = this._sessionRef) === null || _e === void 0 ? void 0 : _e.subscribeKey((s) => s.aiAssistant.state, () => {
+                var _a, _b;
+                if (((_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.state) === 'idle') {
+                    this.stopLoadingTimer();
+                    this.syncShowHalo();
+                    this.fetchSuggestions();
+                    (_b = this._executionCompletionUnsub) === null || _b === void 0 ? void 0 : _b.call(this);
+                    this._executionCompletionUnsub = undefined;
+                }
+            });
+        }
+        this.fetchSuggestions();
+        void this.resolveContextLimit();
+        if (this.messagesEl) {
+            this._scrollListener = () => {
+                this._userScrolledAway =
+                    this.messagesEl.scrollTop + this.messagesEl.clientHeight <
+                        this.messagesEl.scrollHeight - FoundationAiAssistant_1.SCROLL_BOTTOM_THRESHOLD_PX;
+            };
+            this.messagesEl.addEventListener('scroll', this._scrollListener);
         }
         logger.debug('FoundationAiAssistant connected');
     }
     disconnectedCallback() {
-        var _a;
+        var _a, _b;
         super.disconnectedCallback();
         this.stopLoadingTimer();
         this.state = 'idle';
+        this.unwireDriver();
         (_a = this.unsubBus) === null || _a === void 0 ? void 0 : _a.call(this);
         this.unsubBus = undefined;
+        (_b = this._executionCompletionUnsub) === null || _b === void 0 ? void 0 : _b.call(this);
+        this._executionCompletionUnsub = undefined;
+        if (this.messagesEl && this._scrollListener) {
+            this.messagesEl.removeEventListener('scroll', this._scrollListener);
+        }
+        this._scrollListener = undefined;
+        this._userScrolledAway = false;
+        // Clear local references only — driver and store stay in their registries.
         this.driver = undefined;
+        this._sessionRef = undefined;
     }
-    stateChanged() {
-        this.syncShowHalo();
+    resolveContextLimit() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            try {
+                const status = yield ((_b = (_a = this.aiProvider).getStatus) === null || _b === void 0 ? void 0 : _b.call(_a));
+                if (status === null || status === void 0 ? void 0 : status.model) {
+                    this.contextLimit = MODEL_CONTEXT_LIMITS[status.model];
+                }
+            }
+            catch (_c) {
+                // Non-fatal — context limit display simply won't show
+            }
+        });
+    }
+    chatConfigChanged() {
+        this.syncShowingSplash();
+    }
+    showingSplashChanged() {
+        if (this.showingSplash) {
+            this.setAttribute('showing-splash', '');
+        }
+        else {
+            this.removeAttribute('showing-splash');
+        }
+    }
+    // Sets the observable which reflects as a boolean attribute on the host via showingSplashChanged.
+    // Must be an attribute on the host (not a shadow DOM class) so consumer CSS can target slotted
+    // light DOM content — shadow DOM classes are not visible to external stylesheets.
+    syncShowingSplash() {
+        var _a;
+        this.showingSplash = !!((_a = this.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.showSplash) && this.messages.length === 0;
     }
-    messagesChanged() {
+    /**
+     * Runs side effects that were previously in `messagesChanged()`.
+     * Called from the `messages` setter after dispatching to the store.
+     */
+    handleMessagesUpdate() {
         var _a, _b;
         // Reset the loading timer when an assistant message arrives mid-loop so each
         // individual step gets a fresh window before the spinner appears.
@@ -172,11 +530,16 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             }
         }
         this.syncShowHalo();
+        this.syncShowingSplash();
+        // Update context token count from the most recent message that carries usage data.
+        for (let i = this.messages.length - 1; i >= 0; i -= 1) {
+            if (this.messages[i].inputTokens != null) {
+                this.contextTokens = this.messages[i].inputTokens;
+                break;
+            }
+        }
         // Publish halo-start whenever a new toolCalls message arrives.
-        // If we've already published one this turn, send halo-stop first so grids
-        // not relevant to the new tools begin deactivating (fix #2).
-        // Never publish with empty toolNames (fix #3).
-        if (this.showHalo && ((_a = this.enabledAnimations) === null || _a === void 0 ? void 0 : _a.includes('halo'))) {
+        if (this.showHalo !== 'no' && ((_a = this.enabledAnimations) === null || _a === void 0 ? void 0 : _a.includes('halo'))) {
             const last = this.messages[this.messages.length - 1];
             if ((_b = last === null || last === void 0 ? void 0 : last.toolCalls) === null || _b === void 0 ? void 0 : _b.length) {
                 const toolNames = this.getActiveToolNames();
@@ -192,7 +555,6 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         this.scrollToBottom();
     }
     showLoadingIndicatorChanged() {
-        // Scroll to bottom when the spinner appears so it is visible.
         if (this.showLoadingIndicator) {
             this.scrollToBottom();
         }
@@ -200,19 +562,19 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
     // Double rAF: first frame lets the framework flush the DOM update,
     // second frame reads the correct scrollHeight after layout.
     scrollToBottom() {
+        if (this._userScrolledAway)
+            return;
         requestAnimationFrame(() => {
             requestAnimationFrame(() => {
-                var _a;
-                const el = (_a = this.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector('.messages');
-                if (el)
-                    el.scrollTop = el.scrollHeight;
+                if (this.messagesEl)
+                    this.messagesEl.scrollTop = this.messagesEl.scrollHeight;
             });
         });
     }
     startLoadingTimer() {
-        var _a;
+        var _a, _b;
         this.clearLoadingTimer();
-        const delay = (_a = this.chatConfig.loadingDelay) !== null && _a !== void 0 ? _a : FoundationAiAssistant_1.DEFAULT_LOADING_DELAY_S;
+        const delay = (_b = (_a = this.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.loadingDelay) !== null && _b !== void 0 ? _b : FoundationAiAssistant_1.DEFAULT_LOADING_DELAY_S;
         if (delay === 0) {
             this.showLoadingIndicator = true;
         }
@@ -235,31 +597,35 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
     /** Called when the user clicks the popout button. */
     handlePopout() {
         if (this.popoutMode === 'expand') {
-            agenticActivityBus.publish('chat-popout', { state: this.serializeState() });
+            agenticActivityBus.publish('chat-popout', undefined);
         }
         else if (this.popoutMode === 'collapse') {
-            agenticActivityBus.publish('chat-popin', { state: this.serializeState() });
+            agenticActivityBus.publish('chat-popin', undefined);
         }
     }
-    /** Applies a serialized state snapshot to this live instance (used on collapse path). */
-    applyState(state) {
-        var _a;
-        this.messages = [...state.messages];
-        this.showToolCalls = state.showToolCalls;
-        this.showThinkingSteps = state.showThinkingSteps;
-        this.enabledAnimations = [...state.enabledAnimations];
-        (_a = this.driver) === null || _a === void 0 ? void 0 : _a.loadHistory(state.messages);
-    }
-    serializeState() {
-        return {
-            messages: [...this.messages],
-            showToolCalls: this.showToolCalls,
-            showThinkingSteps: this.showThinkingSteps,
-            enabledAnimations: [...this.enabledAnimations],
-        };
+    /** Returns a cache key for this instance, or undefined if the component has no identity. */
+    getStateKey() {
+        const parts = [this.id, this.headerTitle].filter(Boolean);
+        return parts.length ? parts.join('::') : undefined;
     }
     toggleSettings() {
-        this.settingsOpen = !this.settingsOpen;
+        var _a;
+        if (this.settingsOpen) {
+            const panel = (_a = this.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector('.settings-panel');
+            if (panel) {
+                panel.classList.add('closing');
+                panel.addEventListener('animationend', () => {
+                    panel.classList.remove('closing');
+                    this.settingsOpen = false;
+                }, { once: true });
+            }
+            else {
+                this.settingsOpen = false;
+            }
+        }
+        else {
+            this.settingsOpen = true;
+        }
     }
     toggleShowToolCalls() {
         this.showToolCalls = !this.showToolCalls;
@@ -267,23 +633,38 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
     toggleShowThinkingSteps() {
         this.showThinkingSteps = !this.showThinkingSteps;
     }
+    toggleShowAgentSwitchIndicator() {
+        this.showAgentSwitchIndicator = !this.showAgentSwitchIndicator;
+    }
     setEnabledAnimations(animations) {
         this.enabledAnimations = animations;
     }
-    downloadHistory() {
-        var _a, _b, _c, _d;
+    getDebugLog() {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const timestamp = new Date().toISOString().replace(/:/g, '-');
+        return {
+            messages: (_c = (_b = (_a = this.driver) === null || _a === void 0 ? void 0 : _a.getRawHistory) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : this.messages,
+            meta: {
+                timestamp,
+                host: window.location.host,
+                agentSummary: (_d = this.agents) === null || _d === void 0 ? void 0 : _d.map((a) => {
+                    var _a, _b;
+                    return (Object.assign(Object.assign({}, a), { toolDefinitions: expandToolTree((_a = a.toolDefinitions) !== null && _a !== void 0 ? _a : [], (_b = a.toolHandlers) !== null && _b !== void 0 ? _b : {}), toolHandlers: undefined }));
+                }),
+                activeSystemPrompt: (_e = this.activeAgent) === null || _e === void 0 ? void 0 : _e.systemPrompt,
+                activePrimerHistory: (_f = this.activeAgent) === null || _f === void 0 ? void 0 : _f.primerHistory,
+                activeFoldStack: this.driver instanceof ChatDriver ? this.driver.getActiveFoldNames() : undefined,
+                debug: (_g = this.debugStateFactory) === null || _g === void 0 ? void 0 : _g.call(this),
+            },
+        };
+    }
+    downloadDebugLog() {
+        var _a, _b, _c;
         const timestamp = new Date().toISOString().replace(/:/g, '-');
-        // TODO: multi-agent orchestration — use the active agent rather than always agents[0]
-        const agent = (_a = this.agents) === null || _a === void 0 ? void 0 : _a[0];
-        const agentName = ((_c = (_b = agent === null || agent === void 0 ? void 0 : agent.name) !== null && _b !== void 0 ? _b : this.headerTitle) !== null && _c !== void 0 ? _c : 'chat')
+        const agentName = ((_c = (_b = (_a = this.activeAgent) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : this.headerTitle) !== null && _c !== void 0 ? _c : 'chat')
             .toLowerCase()
             .replace(/\s+/g, '-');
-        const payload = {
-            messages: this.messages,
-            systemPrompt: agent === null || agent === void 0 ? void 0 : agent.systemPrompt,
-            primerHistory: agent === null || agent === void 0 ? void 0 : agent.primerHistory,
-            debug: (_d = this.debugStateFactory) === null || _d === void 0 ? void 0 : _d.call(this),
-        };
+        const payload = this.getDebugLog();
         const blob = new Blob([JSON.stringify(payload, null, 2)], { type: 'application/json' });
         const url = URL.createObjectURL(blob);
         const a = document.createElement('a');
@@ -312,12 +693,12 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         }
     }
     isAcceptedFile(file) {
-        var _a, _b;
-        const accepted = this.chatConfig.acceptedFiles;
+        var _a, _b, _c;
+        const accepted = (_a = this.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.acceptedFiles;
         if (!accepted)
             return false;
         const acceptedList = accepted.split(',').map((s) => s.trim().toLowerCase());
-        const ext = `.${(_b = (_a = file.name.split('.').pop()) === null || _a === void 0 ? void 0 : _a.toLowerCase()) !== null && _b !== void 0 ? _b : ''}`;
+        const ext = `.${(_c = (_b = file.name.split('.').pop()) === null || _b === void 0 ? void 0 : _b.toLowerCase()) !== null && _c !== void 0 ? _c : ''}`;
         return acceptedList.some((a) => a === ext ||
             a === file.type ||
             (a.endsWith('/*') && file.type.startsWith(a.replace('/*', '/'))));
@@ -367,16 +748,79 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
     handleSendClick() {
         this.send();
     }
+    handleSuggestionClick(suggestion) {
+        this.inputValue = suggestion;
+        this.send();
+    }
+    fetchSuggestions() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const suggestionsConfig = this.chatConfig.suggestions;
+            if (!this.driver || !suggestionsConfig || suggestionsConfig.behavior === 'never') {
+                return;
+            }
+            if (suggestionsConfig.behavior === 'initial' && this.messages.length > 0) {
+                return;
+            }
+            // Skip if a tool flow is currently executing — suggestions would be generated
+            // from partial history and would be replaced by the post-response fetch anyway.
+            if ((_a = this.driver) === null || _a === void 0 ? void 0 : _a.isBusy()) {
+                return;
+            }
+            // Skip if suggestions were already fetched or are in-flight — avoids redundant
+            // AI calls when the component reconnects during lifecycle events (pop-out/pop-in,
+            // docking) since suggestionsState is persisted in the store.
+            if (this.suggestionsState.status === 'loaded' || this.suggestionsState.status === 'loading') {
+                return;
+            }
+            this._suggestionsGeneration += 1;
+            const generation = this._suggestionsGeneration;
+            this.suggestionsState = { status: 'loading' };
+            // For single-agent (ChatDriver used directly), activeAgent is set but its name is never
+            // passed to the driver — build agentInfo here so getSuggestions has context.
+            // OrchestratingDriver ignores this parameter and builds its own from specialists.
+            const agentInfo = this.activeAgent
+                ? [
+                    {
+                        name: this.activeAgent.name,
+                        description: 'description' in this.activeAgent ? this.activeAgent.description : '',
+                        tools: (_b = this.activeAgent.toolDefinitions) !== null && _b !== void 0 ? _b : [],
+                    },
+                ]
+                : undefined;
+            try {
+                const suggestions = yield this.driver.getSuggestions(this.messages, suggestionsConfig.prompt || '', suggestionsConfig.count || FoundationAiAssistant_1.DEFAULT_SUGGESTION_COUNT, agentInfo);
+                if (generation !== this._suggestionsGeneration)
+                    return;
+                this.suggestionsState = { status: 'loaded', suggestions };
+                this.scrollToBottom();
+            }
+            catch (e) {
+                if (generation !== this._suggestionsGeneration)
+                    return;
+                this.suggestionsState = { status: 'error', message: e.message };
+                logger.error('Failed to fetch suggestions:', e);
+            }
+        });
+    }
     send() {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             const input = this.inputValue.trim();
             if ((!input && !this.attachments.length) || this.state === 'loading')
                 return;
+            // Capture the session ref before any await. If a lifecycle event occurs during
+            // execution, disconnectedCallback clears this._sessionRef — but the captured
+            // reference lets the finally block still write 'idle' back to the shared store,
+            // which in turn triggers the _executionCompletionUnsub subscription on whichever
+            // element is currently active (e.g. the collapse-mode element after docking).
+            const capturedSessionRef = this._sessionRef;
             const pendingAttachments = this.attachments.length ? [...this.attachments] : undefined;
             this.inputValue = '';
             this.attachments = [];
             this.attachmentErrors = [];
+            this.suggestionsState = { status: 'idle' };
+            this._userScrolledAway = false;
             this.state = 'loading';
             this.startLoadingTimer();
             const displayInput = (pendingAttachments === null || pendingAttachments === void 0 ? void 0 : pendingAttachments.length)
@@ -387,15 +831,17 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             }
             finally {
                 this.stopLoadingTimer();
-                this.state = 'idle';
+                // Write directly via captured ref — this._sessionRef may be null if the element
+                // disconnected mid-execution. The state setter also calls syncShowHalo(); replicate
+                // that here for the case where this element is still connected.
+                capturedSessionRef === null || capturedSessionRef === void 0 ? void 0 : capturedSessionRef.actions.aiAssistant.setState('idle');
+                this.syncShowHalo();
+                this.fetchSuggestions();
                 this.restoreFocusIfAppropriate();
             }
         });
     }
     restoreFocusIfAppropriate() {
-        // If focus is still within this component (document.activeElement === this, since shadow DOM
-        // reports the host) or nothing specific has focus (body), return focus to the input.
-        // If the user has navigated to another element in the app, leave them there.
         const active = document.activeElement;
         if (active !== document.body && active !== this)
             return;
@@ -405,7 +851,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         });
     }
     onChatHeaderMouseDown(e) {
-        if (this.popoutMode !== 'expand')
+        if (this.popoutMode === 'collapse')
             return;
         e.preventDefault();
         this.dispatchEvent(new CustomEvent('chat-header-mousedown', {
@@ -419,11 +865,14 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         const detail = e.detail;
         if (detail && detail.interactionId) {
             this.startLoadingTimer();
-            (_a = this.driver) === null || _a === void 0 ? void 0 : _a.resolveInteraction(detail.interactionId, detail);
+            const { interactionId } = detail, result = __rest(detail, ["interactionId"]);
+            (_a = this.driver) === null || _a === void 0 ? void 0 : _a.resolveInteraction(interactionId, result);
         }
     }
 };
+FoundationAiAssistant.SCROLL_BOTTOM_THRESHOLD_PX = 50;
 FoundationAiAssistant.DEFAULT_LOADING_DELAY_S = 5;
+FoundationAiAssistant.DEFAULT_SUGGESTION_COUNT = 3;
 FoundationAiAssistant.MS_PER_SECOND = 1000;
 __decorate([
     AIProvider
@@ -453,29 +902,14 @@ __decorate([
     observable
 ], FoundationAiAssistant.prototype, "debugStateFactory", void 0);
 __decorate([
-    observable
-], FoundationAiAssistant.prototype, "messages", void 0);
-__decorate([
-    observable
-], FoundationAiAssistant.prototype, "state", void 0);
-__decorate([
-    observable
-], FoundationAiAssistant.prototype, "inputValue", void 0);
+    attr({ attribute: 'debug-redux', mode: 'boolean' })
+], FoundationAiAssistant.prototype, "debugRedux", void 0);
 __decorate([
     observable
 ], FoundationAiAssistant.prototype, "attachments", void 0);
 __decorate([
     observable
 ], FoundationAiAssistant.prototype, "attachmentErrors", void 0);
-__decorate([
-    observable
-], FoundationAiAssistant.prototype, "showToolCalls", void 0);
-__decorate([
-    observable
-], FoundationAiAssistant.prototype, "showThinkingSteps", void 0);
-__decorate([
-    observable
-], FoundationAiAssistant.prototype, "enabledAnimations", void 0);
 __decorate([
     observable
 ], FoundationAiAssistant.prototype, "showLoadingIndicator", void 0);
@@ -484,10 +918,10 @@ __decorate([
 ], FoundationAiAssistant.prototype, "settingsOpen", void 0);
 __decorate([
     observable
-], FoundationAiAssistant.prototype, "showHalo", void 0);
+], FoundationAiAssistant.prototype, "showingSplash", void 0);
 __decorate([
-    volatile
-], FoundationAiAssistant.prototype, "hasActivePendingInteraction", null);
+    observable
+], FoundationAiAssistant.prototype, "showHalo", void 0);
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "visibleMessages", null);