@genesislcap/ai-assistant 14.419.2 → 14.421.0

package/src/main/main.ts

@@ -1,3 +1,26 @@
+// =============================================================================
+// 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.
+//
+// =============================================================================
+
 import { AIProvider } from '@genesislcap/foundation-ai';
 import type { ChatAttachment, ChatConfig, ChatMessage } from '@genesislcap/foundation-ai';
 import { avoidTreeShaking } from '@genesislcap/foundation-utils';
@@ -10,19 +33,38 @@ import {
   attr,
 } from '@genesislcap/web-core';
 import { agenticActivityBus } from '../channel/ai-activity-bus';
-import type { AiAssistantSerializedState } from '../channel/ai-activity-channel';
 import { AiActivityHalo } from '../components/activity-halo/activity-halo';
+import type { AiDriver, AllAgentSummary } from '../components/ai-driver/ai-driver';
 import { AiChatBubble } from '../components/chat-bubble/chat-bubble';
 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 type { AgentConfig } from '../config/config';
+import { getOrCreateDriver, deleteDriver } from '../state/driver-registry';
+import { getSessionStore, hasSessionStore, type SessionStoreReturn } 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';
-import type { AiAssistantAnimation, AiAssistantState, PopoutMode } from './main.types';
+import type {
+  AiAssistantAnimation,
+  AiAssistantState,
+  PopoutMode,
+  SuggestionsState,
+} from './main.types';
+
+/** Context window sizes (in tokens) for known models. */
+const MODEL_CONTEXT_LIMITS: Record<string, number> = {
+  'gemini-2.5-flash': 1_048_576,
+  'gemini-2.5-flash-lite': 1_048_576,
+  'gpt-4o': 128_000,
+  'gpt-4o-mini': 128_000,
+  'gpt-4-turbo': 128_000,
+};
 
 // Register supporting components when the main component module is imported.
 avoidTreeShaking(
@@ -31,6 +73,7 @@ avoidTreeShaking(
   AiHaloOverlay,
   AiChatBubble,
   AiActivityHalo,
+  ChatSuggestions,
 );
 
 /**
@@ -38,7 +81,8 @@ avoidTreeShaking(
  *
  * @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.
  *
@@ -57,7 +101,7 @@ export class FoundationAiAssistant extends GenesisElement {
   @AIProvider aiProvider!: AIProvider;
 
   @observable designSystemPrefix: string = 'rapid';
-  @attr({ attribute: 'header-title' }) headerTitle?: string;
+  @attr({ attribute: 'header-title' }) headerTitle: string = 'Genesis Assistant';
   @attr({ attribute: 'image-src' }) imageSrc?: string;
   @attr() placeholder: string = 'Message assistant...';
   /**
@@ -74,46 +118,155 @@ export class FoundationAiAssistant extends GenesisElement {
   @observable agents?: AgentConfig[];
   @observable chatConfig: ChatConfig = {};
   @observable debugStateFactory?: () => unknown;
+  /** When set, enables Redux DevTools for this instance's session store. */
+  @attr({ attribute: 'debug-redux', mode: 'boolean' }) debugRedux = false;
 
-  @observable messages: ChatMessage[] = [];
-  @observable state: AiAssistantState = 'idle';
-  @observable inputValue = '';
-  @observable attachments: ChatAttachment[] = [];
-  @observable attachmentErrors: string[] = [];
+  // ---- Store-backed state (getter reads from store, setter dispatches) ----
+
+  private _sessionRef?: SessionStoreReturn;
+
+  get messages(): ChatMessage[] {
+    return this._sessionRef?.store.aiAssistant.messages ?? [];
+  }
+  set messages(value: ChatMessage[]) {
+    this._sessionRef?.actions.aiAssistant.setMessages(value);
+    this.handleMessagesUpdate();
+  }
+
+  get state(): AiAssistantState {
+    return this._sessionRef?.store.aiAssistant.state ?? 'idle';
+  }
+  set state(value: AiAssistantState) {
+    this._sessionRef?.actions.aiAssistant.setState(value);
+    this.syncShowHalo();
+  }
+
+  get activeAgent(): Omit<AgentConfig, 'toolHandlers'> | undefined {
+    return this._sessionRef?.store.aiAssistant.activeAgent;
+  }
+  set activeAgent(value: AgentConfig | undefined) {
+    // 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: _, ...serializable } = value;
+      this._sessionRef?.actions.aiAssistant.setActiveAgent(serializable);
+    } else {
+      this._sessionRef?.actions.aiAssistant.setActiveAgent(undefined);
+    }
+  }
+
+  get suggestionsState(): SuggestionsState {
+    return this._sessionRef?.store.aiAssistant.suggestionsState ?? { status: 'idle' };
+  }
+  set suggestionsState(value: SuggestionsState) {
+    this._sessionRef?.actions.aiAssistant.setSuggestionsState(value);
+  }
 
   /** Current user-facing toggle state for tool call visibility. */
-  @observable showToolCalls = false;
+  get showToolCalls(): boolean {
+    return this._sessionRef?.store.aiAssistant.showToolCalls ?? false;
+  }
+  set showToolCalls(value: boolean) {
+    this._sessionRef?.actions.aiAssistant.setShowToolCalls(value);
+  }
+
   /** Current user-facing toggle state for thinking step visibility. */
-  @observable showThinkingSteps = false;
+  get showThinkingSteps(): boolean {
+    return this._sessionRef?.store.aiAssistant.showThinkingSteps ?? false;
+  }
+  set showThinkingSteps(value: boolean) {
+    this._sessionRef?.actions.aiAssistant.setShowThinkingSteps(value);
+  }
+
+  /** Current user-facing toggle state for agent switch indicator visibility. */
+  get showAgentSwitchIndicator(): boolean {
+    return this._sessionRef?.store.aiAssistant.showAgentSwitchIndicator ?? false;
+  }
+  set showAgentSwitchIndicator(value: boolean) {
+    this._sessionRef?.actions.aiAssistant.setShowAgentSwitchIndicator(value);
+  }
+
   /** Currently enabled animations. */
-  @observable enabledAnimations: AiAssistantAnimation[] = [];
+  get enabledAnimations(): AiAssistantAnimation[] {
+    return this._sessionRef?.store.aiAssistant.enabledAnimations ?? [];
+  }
+  set enabledAnimations(value: AiAssistantAnimation[]) {
+    this._sessionRef?.actions.aiAssistant.setEnabledAnimations(value);
+  }
+
+  /** Most recent prompt token count from the AI provider, if available. */
+  get contextTokens(): number | undefined {
+    return this._sessionRef?.store.aiAssistant.contextTokens;
+  }
+  set contextTokens(value: number | undefined) {
+    this._sessionRef?.actions.aiAssistant.setContextTokens(value);
+  }
+
+  /** Context window size for the active model, if known. */
+  get contextLimit(): number | undefined {
+    return this._sessionRef?.store.aiAssistant.contextLimit;
+  }
+  set contextLimit(value: number | undefined) {
+    this._sessionRef?.actions.aiAssistant.setContextLimit(value);
+  }
+
+  // ---- Transient UI state (stays as @observable on the component) ----
+
+  private _suggestionsGeneration = 0;
+
+  get inputValue(): string {
+    return this._sessionRef?.store.aiAssistant.inputValue ?? '';
+  }
+  set inputValue(value: string) {
+    this._sessionRef?.actions.aiAssistant.setInputValue(value);
+  }
+  @observable attachments: ChatAttachment[] = [];
+  @observable attachmentErrors: string[] = [];
   /** Whether the loading spinner is currently visible. Controlled by the loading delay timer. */
   @observable showLoadingIndicator = false;
   /** Whether the settings panel is open. */
   @observable settingsOpen = false;
+  /** Whether the splash overlay is currently showing (no messages and showSplash is enabled). Reflected as a boolean attribute on the host. */
+  @observable showingSplash = false;
 
-  private driver?: ChatDriver;
+  private driver?: AiDriver;
+  private driverCleanup?: () => void;
   private loadingTimer: ReturnType<typeof setTimeout> | undefined;
   private unsubBus?: () => void;
   private haloStartPublished = false;
-
+  /** Fingerprint of the agents array used to build the current driver. Used by agentsChanged to skip spurious rebuilds. */
+  private _driverAgentsKey?: string;
+  /** Bound to the messages container via the template ref — assigned by FAST before connectedCallback logic runs. */
+  messagesEl?: HTMLElement;
+  /** True when the user has intentionally scrolled away from the bottom — suppresses auto-scroll. */
+  private _userScrolledAway = false;
+  private _scrollListener?: () => void;
+  private static readonly SCROLL_BOTTOM_THRESHOLD_PX = 50;
   /**
-   * Whether the halo animation should be shown.
-   * True when the AI is actively computing (loading state, no pending interaction).
+   * Unsubscribes a one-shot state subscription created when this element connects
+   * mid-execution. The subscription watches for `state` becoming 'idle' so that
+   * this element can stop its loading timer and sync the halo even when the
+   * originating `send()` ran on a different element instance.
    */
-  @observable showHalo: boolean = false;
+  private _executionCompletionUnsub?: () => void;
+
+  @observable showHalo: 'no' | 'orchestrating' | 'agent' = 'no';
 
   private syncShowHalo() {
     if (this.state !== 'loading') {
-      this.showHalo = false;
+      this.showHalo = 'no';
       return;
     }
     const last = this.messages[this.messages.length - 1];
-    this.showHalo = !last?.interaction;
+    if (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. */
-  @volatile
   get hasActivePendingInteraction(): boolean {
     if (this.state !== 'loading') return false;
     const last = this.messages[this.messages.length - 1];
@@ -122,7 +275,7 @@ export class FoundationAiAssistant extends GenesisElement {
 
   showHaloChanged() {
     if (!this.enabledAnimations?.includes('halo')) return;
-    if (!this.showHalo) {
+    if (this.showHalo === 'no') {
       agenticActivityBus.publish('halo-stop', undefined);
       this.haloStartPublished = false;
     }
@@ -145,10 +298,25 @@ export class FoundationAiAssistant extends GenesisElement {
    * 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.
    */
   @volatile
   get visibleMessages(): ChatMessage[] {
+    const showAgentSwitchIndicator =
+      this.chatConfig.ui?.showAgentSwitchIndicator != null
+        ? this.showAgentSwitchIndicator
+        : this.showToolCalls;
+
     return this.messages.filter((m) => {
+      // 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;
@@ -166,41 +334,207 @@ export class FoundationAiAssistant extends GenesisElement {
     });
   }
 
-  connectedCallback() {
-    super.connectedCallback();
-    const { showToolCalls, showThinkingSteps, animations } = this.chatConfig;
-    this.showToolCalls = showToolCalls === true;
-    this.showThinkingSteps = showThinkingSteps === true;
-    this.enabledAnimations =
-      (animations?.enabled as AiAssistantAnimation[]) ?? (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.',
-      );
+  agentsChanged(): void {
+    // 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 = this.driver.getRawHistory?.() ?? [];
+    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. */
+  private getAgentsKey(agents?: AgentConfig[]): string {
+    if (!agents?.length) return '';
+    return agents
+      .map((a) => {
+        const toolNames = Object.keys(a.toolHandlers ?? {})
+          .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.
+   */
+  private createDriver(): AiDriver {
+    const agent = this.chatConfig.agent ?? {};
+    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 agent = this.agents?.[0];
-    this.driver = new ChatDriver(
+
+    const singleAgent = agents?.[0];
+    this.activeAgent = singleAgent;
+    return new ChatDriver(
       this.aiProvider,
-      agent?.toolHandlers ?? {},
-      agent?.toolDefinitions ?? [],
-      agent?.systemPrompt,
-      agent?.primerHistory,
-      this.chatConfig.maxToolIterations,
+      singleAgent?.toolHandlers ?? {},
+      singleAgent?.toolDefinitions ?? [],
+      singleAgent?.systemPrompt,
+      singleAgent?.primerHistory,
+      agent.maxToolIterations,
+      agent.maxFoldOperations,
     );
-    this.driver.addEventListener('history-updated', (e: Event) => {
+  }
+
+  /**
+   * 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.
+   */
+  private wireDriver(): void {
+    const { driver } = this;
+    if (!driver) return;
+
+    // Idempotent — unwire previous listeners on this component before re-wiring.
+    this.unwireDriver();
+
+    const onHistoryUpdated = (e: Event) => {
       this.messages = [...(e as CustomEvent<ChatMessage[]>).detail];
-    });
+    };
+    driver.addEventListener('history-updated', onHistoryUpdated);
+
+    const cleanups: (() => void)[] = [
+      () => 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: Event) => {
+        this.activeAgent = (e as CustomEvent<AgentConfig>).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.
+   */
+  private unwireDriver(): void {
+    this.driverCleanup?.();
+    this.driverCleanup = undefined;
+  }
+
+  connectedCallback() {
+    // 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();
+
+    // 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 = this.chatConfig.ui ?? {};
+      this.showToolCalls = ui.showToolCalls === true;
+      this.showThinkingSteps = ui.showThinkingSteps === true;
+      this.showAgentSwitchIndicator = ui.showAgentSwitchIndicator === true;
+      this.enabledAnimations =
+        (ui.animations?.enabled as AiAssistantAnimation[]) ??
+        (ui.animations ? [...ALL_ANIMATIONS] : []);
+    }
+
+    this.driver = getOrCreateDriver(key, () => this.createDriver());
+    this._driverAgentsKey = this.getAgentsKey(this.agents);
+    this.wireDriver();
 
-    // When embedded in a bubble (expand mode), listen for chat-popin to restore state
-    // when the layout panel collapses back.
     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 (this.driver?.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 = this._sessionRef?.subscribeKey(
+        (s) => s.aiAssistant.state,
+        () => {
+          if (this._sessionRef?.store.aiAssistant.state === 'idle') {
+            this.stopLoadingTimer();
+            this.syncShowHalo();
+            this.fetchSuggestions();
+            this._executionCompletionUnsub?.();
+            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.SCROLL_BOTTOM_THRESHOLD_PX;
+      };
+      this.messagesEl.addEventListener('scroll', this._scrollListener);
+    }
     logger.debug('FoundationAiAssistant connected');
   }
 
@@ -208,16 +542,56 @@ export class FoundationAiAssistant extends GenesisElement {
     super.disconnectedCallback();
     this.stopLoadingTimer();
     this.state = 'idle';
+    this.unwireDriver();
     this.unsubBus?.();
     this.unsubBus = undefined;
+    this._executionCompletionUnsub?.();
+    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();
+  private async resolveContextLimit(): Promise<void> {
+    try {
+      const status = await this.aiProvider.getStatus?.();
+      if (status?.model) {
+        this.contextLimit = MODEL_CONTEXT_LIMITS[status.model];
+      }
+    } catch {
+      // 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.
+  private syncShowingSplash() {
+    this.showingSplash = !!this.chatConfig.ui?.showSplash && this.messages.length === 0;
   }
 
-  messagesChanged() {
+  /**
+   * Runs side effects that were previously in `messagesChanged()`.
+   * Called from the `messages` setter after dispatching to the store.
+   */
+  private handleMessagesUpdate(): void {
     // Reset the loading timer when an assistant message arrives mid-loop so each
     // individual step gets a fresh window before the spinner appears.
     // If the last message is a blocking interaction, stop the timer — the AI is
@@ -231,11 +605,16 @@ export class FoundationAiAssistant extends GenesisElement {
       }
     }
     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 && this.enabledAnimations?.includes('halo')) {
+    if (this.showHalo !== 'no' && this.enabledAnimations?.includes('halo')) {
       const last = this.messages[this.messages.length - 1];
       if (last?.toolCalls?.length) {
         const toolNames = this.getActiveToolNames();
@@ -252,7 +631,6 @@ export class FoundationAiAssistant extends GenesisElement {
   }
 
   showLoadingIndicatorChanged() {
-    // Scroll to bottom when the spinner appears so it is visible.
     if (this.showLoadingIndicator) {
       this.scrollToBottom();
     }
@@ -261,20 +639,21 @@ export class FoundationAiAssistant extends GenesisElement {
   // Double rAF: first frame lets the framework flush the DOM update,
   // second frame reads the correct scrollHeight after layout.
   private scrollToBottom() {
+    if (this._userScrolledAway) return;
     requestAnimationFrame(() => {
       requestAnimationFrame(() => {
-        const el = this.shadowRoot?.querySelector('.messages');
-        if (el) el.scrollTop = el.scrollHeight;
+        if (this.messagesEl) this.messagesEl.scrollTop = this.messagesEl.scrollHeight;
       });
     });
   }
 
   private static readonly DEFAULT_LOADING_DELAY_S = 5;
+  private static readonly DEFAULT_SUGGESTION_COUNT = 3;
   private static readonly MS_PER_SECOND = 1000;
 
   private startLoadingTimer() {
     this.clearLoadingTimer();
-    const delay = this.chatConfig.loadingDelay ?? FoundationAiAssistant.DEFAULT_LOADING_DELAY_S;
+    const delay = this.chatConfig.ui?.loadingDelay ?? FoundationAiAssistant.DEFAULT_LOADING_DELAY_S;
     if (delay === 0) {
       this.showLoadingIndicator = true;
     } else {
@@ -299,32 +678,37 @@ export class FoundationAiAssistant extends GenesisElement {
   /** Called when the user clicks the popout button. */
   handlePopout(): void {
     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: AiAssistantSerializedState): void {
-    this.messages = [...state.messages];
-    this.showToolCalls = state.showToolCalls;
-    this.showThinkingSteps = state.showThinkingSteps;
-    this.enabledAnimations = [...state.enabledAnimations];
-    this.driver?.loadHistory(state.messages);
-  }
-
-  private serializeState(): AiAssistantSerializedState {
-    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. */
+  private getStateKey(): string | undefined {
+    const parts = [this.id, this.headerTitle].filter(Boolean);
+    return parts.length ? parts.join('::') : undefined;
   }
 
   toggleSettings() {
-    this.settingsOpen = !this.settingsOpen;
+    if (this.settingsOpen) {
+      const panel = this.shadowRoot?.querySelector('.settings-panel') as HTMLElement | null;
+      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() {
@@ -335,23 +719,41 @@ export class FoundationAiAssistant extends GenesisElement {
     this.showThinkingSteps = !this.showThinkingSteps;
   }
 
+  toggleShowAgentSwitchIndicator() {
+    this.showAgentSwitchIndicator = !this.showAgentSwitchIndicator;
+  }
+
   setEnabledAnimations(animations: AiAssistantAnimation[]) {
     this.enabledAnimations = animations;
   }
 
-  downloadHistory() {
+  getDebugLog() {
+    const timestamp = new Date().toISOString().replace(/:/g, '-');
+    return {
+      messages: this.driver?.getRawHistory?.() ?? this.messages,
+      meta: {
+        timestamp,
+        host: window.location.host,
+        agentSummary: this.agents?.map((a) => ({
+          ...a,
+          toolDefinitions: expandToolTree(a.toolDefinitions ?? [], a.toolHandlers ?? {}),
+          toolHandlers: undefined,
+        })),
+        activeSystemPrompt: this.activeAgent?.systemPrompt,
+        activePrimerHistory: this.activeAgent?.primerHistory,
+        activeFoldStack:
+          this.driver instanceof ChatDriver ? this.driver.getActiveFoldNames() : undefined,
+        debug: this.debugStateFactory?.(),
+      },
+    };
+  }
+
+  downloadDebugLog() {
     const timestamp = new Date().toISOString().replace(/:/g, '-');
-    // TODO: multi-agent orchestration — use the active agent rather than always agents[0]
-    const agent = this.agents?.[0];
-    const agentName = (agent?.name ?? this.headerTitle ?? 'chat')
+    const agentName = (this.activeAgent?.name ?? this.headerTitle ?? 'chat')
       .toLowerCase()
       .replace(/\s+/g, '-');
-    const payload = {
-      messages: this.messages,
-      systemPrompt: agent?.systemPrompt,
-      primerHistory: agent?.primerHistory,
-      debug: this.debugStateFactory?.(),
-    };
+    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');
@@ -384,7 +786,7 @@ export class FoundationAiAssistant extends GenesisElement {
   }
 
   private isAcceptedFile(file: File): boolean {
-    const accepted = this.chatConfig.acceptedFiles;
+    const accepted = this.chatConfig.ui?.acceptedFiles;
     if (!accepted) return false;
 
     const acceptedList = accepted.split(',').map((s) => s.trim().toLowerCase());
@@ -446,13 +848,81 @@ export class FoundationAiAssistant extends GenesisElement {
     this.send();
   }
 
+  handleSuggestionClick(suggestion: string) {
+    this.inputValue = suggestion;
+    this.send();
+  }
+
+  private async fetchSuggestions() {
+    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 (this.driver?.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: AllAgentSummary[] | undefined = this.activeAgent
+      ? [
+          {
+            name: this.activeAgent.name,
+            description: 'description' in this.activeAgent ? this.activeAgent.description : '',
+            tools: this.activeAgent.toolDefinitions ?? [],
+          },
+        ]
+      : undefined;
+    try {
+      const suggestions = await this.driver.getSuggestions(
+        this.messages,
+        suggestionsConfig.prompt || '',
+        suggestionsConfig.count || FoundationAiAssistant.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 as Error).message };
+      logger.error('Failed to fetch suggestions:', e);
+    }
+  }
+
   private async send() {
     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?.length
@@ -462,15 +932,17 @@ export class FoundationAiAssistant extends GenesisElement {
       await this.driver?.sendMessage(displayInput, pendingAttachments);
     } 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?.actions.aiAssistant.setState('idle');
+      this.syncShowHalo();
+      this.fetchSuggestions();
       this.restoreFocusIfAppropriate();
     }
   }
 
   private 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;
     requestAnimationFrame(() => {
@@ -479,7 +951,7 @@ export class FoundationAiAssistant extends GenesisElement {
   }
 
   onChatHeaderMouseDown(e: MouseEvent) {
-    if (this.popoutMode !== 'expand') return;
+    if (this.popoutMode === 'collapse') return;
     e.preventDefault();
     this.dispatchEvent(
       new CustomEvent('chat-header-mousedown', {
@@ -494,7 +966,8 @@ export class FoundationAiAssistant extends GenesisElement {
     const detail = (e as CustomEvent).detail;
     if (detail && detail.interactionId) {
       this.startLoadingTimer();
-      this.driver?.resolveInteraction(detail.interactionId, detail);
+      const { interactionId, ...result } = detail;
+      this.driver?.resolveInteraction(interactionId, result);
     }
   }
 }