@genesislcap/ai-assistant 14.420.0 → 14.421.1

package/dist/ai-assistant.d.ts

@@ -1,49 +1,23 @@
 import { AIProvider } from '@genesislcap/foundation-ai';
 import type { ChatAttachment } from '@genesislcap/foundation-ai';
 import type { ChatConfig } from '@genesislcap/foundation-ai';
+import type { ChatDriverResult } from '@genesislcap/foundation-ai';
 import type { ChatMessage } from '@genesislcap/foundation-ai';
 import type { ChatToolDefinition } from '@genesislcap/foundation-ai';
 import type { ChatToolHandlers } from '@genesislcap/foundation-ai';
 import { GenesisElement } from '@genesislcap/web-core';
+import type { InteractionResult } from '@genesislcap/foundation-ai';
 import { ViewTemplate } from '@genesislcap/web-core';
 
 /**
- * Configuration for a single specialist agent.
+ * Configuration for an agent passed to `FoundationAiAssistant`.
  *
- * When multiple agents are provided to `FoundationAiAssistant`, an orchestrating layer
- * will route each user message to the appropriate specialist based on intent. When only
- * one agent is configured, routing is skipped.
+ * Either a specialist (requires `description`) or a fallback (requires
+ * `fallback: true`). Passing both or neither is a compile error.
  *
  * @beta
  */
-export declare interface AgentConfig {
-    /**
-     * Display name shown in the chat header when this agent is active.
-     */
-    name: string;
-    /**
-     * Plain-language description of what this agent handles.
-     * Used by the classifier to auto-generate its routing prompt.
-     */
-    description: string;
-    /**
-     * System prompt injected into every conversation turn for this agent.
-     */
-    systemPrompt?: string;
-    /**
-     * Tool definitions (JSON Schema) passed to the AI provider for this agent.
-     */
-    toolDefinitions?: ChatToolDefinition[];
-    /**
-     * Tool handler implementations for this agent.
-     */
-    toolHandlers?: ChatToolHandlers;
-    /**
-     * Optional primer history prepended to every call (not visible to the user).
-     * Used to establish agent identity and behavioural rules.
-     */
-    primerHistory?: ChatMessage[];
-}
+export declare type AgentConfig = SpecialistAgentConfig | FallbackAgentConfig;
 
 /**
  * Typed in-process event bus for AI assistant activity events.
@@ -144,14 +118,10 @@ export declare interface AgenticActivityEvents {
     };
     /** Fired when the assistant finishes all tool processing and returns to idle. */
     'halo-stop': undefined;
-    /** Fired when the user clicks the expand button — moves assistant from bubble into layout. */
-    'chat-popout': {
-        state: AiAssistantSerializedState;
-    };
-    /** Fired when the user clicks the collapse button — moves assistant from layout back to bubble. */
-    'chat-popin': {
-        state: AiAssistantSerializedState;
-    };
+    /** Fired when the user clicks the expand button — moves assistant from bubble into layout. State lives in the session store, not in this event. */
+    'chat-popout': undefined;
+    /** Fired when the user clicks the collapse button — moves assistant from layout back to bubble. State lives in the session store, not in this event. */
+    'chat-popin': undefined;
 }
 
 /**
@@ -173,19 +143,6 @@ export declare interface AiAssistantAnimationDef {
     tooltip: string;
 }
 
-/**
- * Serialized state of a `FoundationAiAssistant` instance.
- * All fields are JSON-serializable.
- *
- * @beta
- */
-export declare interface AiAssistantSerializedState {
-    messages: ChatMessage[];
-    showToolCalls: boolean;
-    showThinkingSteps: boolean;
-    enabledAnimations: AiAssistantAnimation[];
-}
-
 /**
  * State of the AI assistant component.
  *
@@ -193,6 +150,13 @@ export declare interface AiAssistantSerializedState {
  */
 export declare type AiAssistantState = 'idle' | 'loading' | 'error';
 
+export declare class AiChatMarkdown extends GenesisElement {
+    /** The markdown string to render. */
+    content: string;
+    /** @internal */
+    renderMarkdown(): string;
+}
+
 /**
  * Interface that AI inline interaction components can implement.
  * The `AiChatInteractionWrapper` always sets `data` and `resolved` on the rendered element.
@@ -201,8 +165,76 @@ export declare type AiAssistantState = 'idle' | 'loading' | 'error';
  */
 export declare interface AiChatWidget {
     data: unknown;
-    /** When true, the interaction has already been resolved. Components should render read-only. */
-    resolved?: boolean;
+    /** The result when the interaction has been resolved. Truthy = resolved; value contains status/payload for display. */
+    resolved?: InteractionResult<unknown>;
+}
+
+/**
+ * Contract for pages that support docking the AI assistant.
+ * Register an implementation with {@link getAiPopoutManager} on mount and deregister on unmount.
+ *
+ * @beta
+ */
+export declare interface AiDockProvider {
+    /**
+     * Called when the user expands the bubble. The provider is responsible for inserting
+     * the element into its layout. State is held in the session store and restored
+     * automatically when the element connects.
+     */
+    onDock(element: HTMLElement): Promise<void>;
+    /** Called when the user collapses the panel or before navigation. */
+    onUndock(): Promise<void>;
+    /**
+     * Called by `collapseIfDocked` before navigation. The provider is responsible for
+     * finding the docked assistant element and calling `handlePopout()` on it, which
+     * publishes `chat-popin` and returns the assistant to the bubble.
+     */
+    initiateCollapse(): void;
+}
+
+/**
+ * Common interface implemented by both `ChatDriver` (single-agent) and
+ * `OrchestratingDriver` (multi-agent). `FoundationAiAssistant` depends only
+ * on this interface — the concrete class is chosen at startup based on how
+ * many agents are configured.
+ *
+ * Extends `EventTarget` so consumers can subscribe to `history-updated` events
+ * without knowing the concrete implementation.
+ *
+ * @beta
+ */
+export declare interface AiDriver extends EventTarget {
+    /**
+     * Send a user message and run the tool loop to completion.
+     */
+    sendMessage(input: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult>;
+    /**
+     * Continue the tool loop from the current history without appending a new
+     * user message. Used by `OrchestratingDriver` on agent handoffs — the
+     * handoff context is already in history; `transientPrimer` is injected as
+     * an invisible one-shot message for this call only.
+     */
+    continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
+    /**
+     * Resolve a pending blocking interaction with the given result.
+     */
+    resolveInteraction(interactionId: string, result: unknown): void;
+    /**
+     * Seed the driver's message history (called on state restore / pop-in).
+     */
+    loadHistory(messages: ChatMessage[]): void;
+    /**
+     * Return the full, unredacted conversation history.
+     */
+    getRawHistory?(): readonly ChatMessage[];
+    /**
+     * Returns true if the driver is currently processing a request.
+     */
+    isBusy(): boolean;
+    /**
+     * Get query suggestions from the AI.
+     */
+    getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
 }
 
 /**
@@ -212,6 +244,13 @@ export declare interface AiChatWidget {
  */
 export declare const ALL_ANIMATIONS: AiAssistantAnimation[];
 
+/** @internal */
+declare interface AllAgentSummary {
+    name: string;
+    description: string;
+    tools: ChatToolDefinition[];
+}
+
 /**
  * Registry of all available animations with their display metadata.
  * Adding an entry here automatically extends the {@link AiAssistantAnimation} type.
@@ -229,6 +268,30 @@ export declare const ANIMATION_DEFS: {
     };
 };
 
+declare interface BaseAgentConfig {
+    /**
+     * Display name shown in the chat header when this agent is active.
+     */
+    name: string;
+    /**
+     * System prompt injected into every conversation turn for this agent.
+     */
+    systemPrompt?: string;
+    /**
+     * Tool definitions (JSON Schema) passed to the AI provider for this agent.
+     */
+    toolDefinitions?: ChatToolDefinition[];
+    /**
+     * Tool handler implementations for this agent.
+     */
+    toolHandlers?: ChatToolHandlers;
+    /**
+     * Optional primer history prepended to every call (not visible to the user).
+     * Used to establish agent identity and behavioural rules.
+     */
+    primerHistory?: ChatMessage[];
+}
+
 /**
  * Plain TS class that drives a multi-turn chat conversation, including the tool-call loop.
  * Owned by `FoundationAiAssistant` — created in `connectedCallback`, torn down in `disconnectedCallback`.
@@ -239,18 +302,45 @@ export declare const ANIMATION_DEFS: {
  *
  * @beta
  */
-export declare class ChatDriver extends EventTarget {
+export declare class ChatDriver extends EventTarget implements AiDriver {
     private readonly aiProvider;
-    private readonly toolHandlers;
-    private readonly toolDefinitions;
-    private readonly systemPrompt?;
-    private readonly primerHistory?;
     private readonly maxToolIterations;
     private history;
     private busy;
     private pendingInteractions;
-    constructor(aiProvider: AIProvider, toolHandlers?: ChatToolHandlers, toolDefinitions?: ChatToolDefinition[], systemPrompt?: string, primerHistory?: ChatMessage[], maxToolIterations?: number);
+    private systemPrompt?;
+    private toolDefinitions;
+    private toolHandlers;
+    private primerHistory?;
+    private activeAgentName?;
+    /**
+     * When set (e.g. by OrchestratingDriver), applied only to the conversation slice
+     * sent to the model — stored `history` stays unchanged for UI and logging.
+     */
+    private providerHistoryTransform?;
+    /** Stack of fold frames — grows when a fold opens, shrinks when it closes. */
+    private foldStack;
+    /** Consecutive fold open/close ops without a real tool call. Reset on real tool execution. */
+    private consecutiveFoldOps;
+    /** Consecutive unknown-tool calls without a real tool call. Reset on real tool execution. */
+    private consecutiveUnknownToolCalls;
+    private readonly maxFoldOperations;
+    constructor(aiProvider: AIProvider, toolHandlers?: ChatToolHandlers, toolDefinitions?: ChatToolDefinition[], systemPrompt?: string, primerHistory?: ChatMessage[], maxToolIterations?: number, maxFoldOperations?: number);
+    /**
+     * Swap in a new agent's configuration. Called by OrchestratingDriver before
+     * each specialist turn so the shared driver runs with the right tools and prompt.
+     */
+    applyAgent(config: AgentConfig): void;
+    /**
+     * Optional transform applied to conversation history immediately before each LLM request.
+     * Cleared when `undefined`. Does not alter stored history.
+     */
+    setProviderHistoryTransform(transform?: (history: ChatMessage[]) => ChatMessage[]): void;
     getHistory(): ReadonlyArray<ChatMessage>;
+    getRawHistory(): readonly ChatMessage[];
+    /** Returns the current fold stack names for debugging. */
+    getActiveFoldNames(): string[];
+    getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
     isBusy(): boolean;
     /**
      * Request a custom UI interaction. Emits a new message with the interaction.
@@ -270,7 +360,31 @@ export declare class ChatDriver extends EventTarget {
      * can continue an existing conversation. Call this before the first user message.
      */
     loadHistory(messages: ChatMessage[]): void;
-    sendMessage(userInput: string, attachments?: ChatAttachment[]): Promise<void>;
+    sendMessage(userInput: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult>;
+    /**
+     * Continue the tool loop from current history without appending a new user message.
+     * Used by OrchestratingDriver after an agent handoff.
+     */
+    continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
+    /** Extract ToolFold metadata from a handler, or undefined if it isn't a fold facade. */
+    private getFold;
+    /**
+     * Search all currently registered fold facades (and their nested folds recursively)
+     * to find which fold contains a given tool name. Returns the immediate parent fold name.
+     */
+    private findFoldContaining;
+    /**
+     * Install the fold's inner tool set, replacing (exclusive) or extending (non-exclusive)
+     * the current tool set. Also injects the close tool. Does NOT touch the fold stack.
+     */
+    private applyFoldToolSet;
+    /** Open a fold: push a stack frame, swap the tool set, return the response message. */
+    private openFold;
+    private pushFoldFrame;
+    /** Close the top fold: pop the stack frame, restore the previous tool set. */
+    private closeFold;
+    /** Build the fold-awareness suffix appended to the system prompt each LLM call. */
+    private buildFoldSystemPromptSuffix;
     private runToolLoop;
     private appendToHistory;
 }
@@ -282,12 +396,103 @@ export declare class ChatDriver extends EventTarget {
  */
 export declare type ChatHistoryUpdatedEvent = CustomEvent<ReadonlyArray<ChatMessage>>;
 
+/**
+ * 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 declare function createToolFold(config: {
+    /** Facade tool name — used as the tool name the model calls to open this fold. */
+    name: string;
+    /**
+     * Description shown to the model for the facade tool.
+     * If omitted, auto-generated from the inner tool names:
+     * "Contains: tool_a, tool_b. Invoke to access these tools."
+     */
+    description?: string;
+    /**
+     * Optional usage guidance injected into the fold-open response message.
+     * Not included in the facade description — only visible once the fold is open.
+     */
+    usageNotes?: string;
+    /** Inner tool definitions. Same type as `AgentConfig.toolDefinitions`. */
+    tools: ChatToolDefinition[];
+    /** Inner tool handlers. Same type as `AgentConfig.toolHandlers`. */
+    handlers: ChatToolHandlers;
+    /**
+     * When true (default), all other tools are removed when this fold opens.
+     * When false, sibling tools remain available alongside the inner tools.
+     */
+    exclusive?: boolean;
+}): ToolFoldResult;
+
+/**
+ * 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 declare function expandToolTree(definitions: ChatToolDefinition[], handlers: ChatToolHandlers): ToolTreeNode[];
+
+/**
+ * Configuration for a fallback agent.
+ *
+ * Invoked when the classifier returns no match. Excluded from the classifier
+ * prompt. Only one fallback is permitted per agents array.
+ *
+ * @beta
+ */
+export declare interface FallbackAgentConfig extends BaseAgentConfig {
+    /**
+     * Marks this agent as the fallback for unrecognised requests.
+     */
+    fallback: true;
+    description?: never;
+}
+
 /**
  * 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.
  *
@@ -298,7 +503,7 @@ export declare type ChatHistoryUpdatedEvent = CustomEvent<ReadonlyArray<ChatMess
 export declare class FoundationAiAssistant extends GenesisElement {
     aiProvider: AIProvider;
     designSystemPrefix: string;
-    headerTitle?: string;
+    headerTitle: string;
     imageSrc?: string;
     placeholder: string;
     /**
@@ -315,30 +520,67 @@ export declare class FoundationAiAssistant extends GenesisElement {
     agents?: AgentConfig[];
     chatConfig: ChatConfig;
     debugStateFactory?: () => unknown;
-    messages: ChatMessage[];
-    state: AiAssistantState;
-    inputValue: string;
-    attachments: ChatAttachment[];
-    attachmentErrors: string[];
+    /** When set, enables Redux DevTools for this instance's session store. */
+    debugRedux: boolean;
+    private _sessionRef?;
+    get messages(): ChatMessage[];
+    set messages(value: ChatMessage[]);
+    get state(): AiAssistantState;
+    set state(value: AiAssistantState);
+    get activeAgent(): Omit<AgentConfig, 'toolHandlers'> | undefined;
+    set activeAgent(value: AgentConfig | undefined);
+    get suggestionsState(): SuggestionsState;
+    set suggestionsState(value: SuggestionsState);
     /** Current user-facing toggle state for tool call visibility. */
-    showToolCalls: boolean;
+    get showToolCalls(): boolean;
+    set showToolCalls(value: boolean);
     /** Current user-facing toggle state for thinking step visibility. */
-    showThinkingSteps: boolean;
+    get showThinkingSteps(): boolean;
+    set showThinkingSteps(value: boolean);
+    /** Current user-facing toggle state for agent switch indicator visibility. */
+    get showAgentSwitchIndicator(): boolean;
+    set showAgentSwitchIndicator(value: boolean);
     /** Currently enabled animations. */
-    enabledAnimations: AiAssistantAnimation[];
+    get enabledAnimations(): AiAssistantAnimation[];
+    set enabledAnimations(value: AiAssistantAnimation[]);
+    /** Most recent prompt token count from the AI provider, if available. */
+    get contextTokens(): number | undefined;
+    set contextTokens(value: number | undefined);
+    /** Context window size for the active model, if known. */
+    get contextLimit(): number | undefined;
+    set contextLimit(value: number | undefined);
+    private _suggestionsGeneration;
+    get inputValue(): string;
+    set inputValue(value: string);
+    attachments: ChatAttachment[];
+    attachmentErrors: string[];
     /** Whether the loading spinner is currently visible. Controlled by the loading delay timer. */
     showLoadingIndicator: boolean;
     /** Whether the settings panel is open. */
     settingsOpen: boolean;
+    /** Whether the splash overlay is currently showing (no messages and showSplash is enabled). Reflected as a boolean attribute on the host. */
+    showingSplash: boolean;
     private driver?;
+    private driverCleanup?;
     private loadingTimer;
     private unsubBus?;
     private haloStartPublished;
+    /** Fingerprint of the agents array used to build the current driver. Used by agentsChanged to skip spurious rebuilds. */
+    private _driverAgentsKey?;
+    /** 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;
+    private _scrollListener?;
+    private static readonly SCROLL_BOTTOM_THRESHOLD_PX;
     /**
-     * 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.
      */
-    showHalo: boolean;
+    private _executionCompletionUnsub?;
+    showHalo: 'no' | 'orchestrating' | 'agent';
     private syncShowHalo;
     /** True when there is a pending (unresolved) interaction — disables the popout button. */
     get hasActivePendingInteraction(): boolean;
@@ -348,29 +590,91 @@ export declare 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.
      */
     get visibleMessages(): ChatMessage[];
+    agentsChanged(): void;
+    /** Returns a stable fingerprint for an agents array based on agent names and tool handler keys. */
+    private getAgentsKey;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Removes event listeners attached by `wireDriver`. Does not destroy
+     * the driver or remove it from the registry.
+     */
+    private unwireDriver;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    stateChanged(): void;
-    messagesChanged(): void;
+    private resolveContextLimit;
+    chatConfigChanged(): void;
+    showingSplashChanged(): void;
+    private syncShowingSplash;
+    /**
+     * Runs side effects that were previously in `messagesChanged()`.
+     * Called from the `messages` setter after dispatching to the store.
+     */
+    private handleMessagesUpdate;
     showLoadingIndicatorChanged(): void;
     private scrollToBottom;
     private static readonly DEFAULT_LOADING_DELAY_S;
+    private static readonly DEFAULT_SUGGESTION_COUNT;
     private static readonly MS_PER_SECOND;
     private startLoadingTimer;
     private clearLoadingTimer;
     private stopLoadingTimer;
     /** Called when the user clicks the popout button. */
     handlePopout(): void;
-    /** Applies a serialized state snapshot to this live instance (used on collapse path). */
-    applyState(state: AiAssistantSerializedState): void;
-    private serializeState;
+    /** Returns a cache key for this instance, or undefined if the component has no identity. */
+    private getStateKey;
     toggleSettings(): void;
     toggleShowToolCalls(): void;
     toggleShowThinkingSteps(): void;
+    toggleShowAgentSwitchIndicator(): void;
     setEnabledAnimations(animations: AiAssistantAnimation[]): void;
-    downloadHistory(): void;
+    getDebugLog(): {
+        messages: readonly ChatMessage[];
+        meta: {
+            timestamp: string;
+            host: string;
+            agentSummary: ({
+                toolDefinitions: ToolTreeNode[];
+                toolHandlers: any;
+                description: string;
+                fallback?: never;
+                name: string;
+                systemPrompt?: string;
+                primerHistory?: ChatMessage[];
+            } | {
+                toolDefinitions: ToolTreeNode[];
+                toolHandlers: any;
+                fallback: true;
+                description?: never;
+                name: string;
+                systemPrompt?: string;
+                primerHistory?: ChatMessage[];
+            })[];
+            activeSystemPrompt: string;
+            activePrimerHistory: ChatMessage[];
+            activeFoldStack: string[];
+            debug: unknown;
+        };
+    };
+    downloadDebugLog(): void;
     triggerFileInput(): void;
     handleFileSelect(e: Event): void;
     removeAttachment(attachment: ChatAttachment): void;
@@ -379,6 +683,8 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private readFileAsText;
     private loadSelectedFiles;
     handleSendClick(): void;
+    handleSuggestionClick(suggestion: string): void;
+    private fetchSuggestions;
     private send;
     private restoreFocusIfAppropriate;
     onChatHeaderMouseDown(e: MouseEvent): void;
@@ -388,6 +694,103 @@ export declare class FoundationAiAssistant extends GenesisElement {
 /** @internal */
 export declare const FoundationAiAssistantTemplate: (designSystemPrefix: string) => ViewTemplate<FoundationAiAssistant>;
 
+/**
+ * App-shell component that owns the pop-out/pop-in lifecycle for the AI assistant bubble.
+ *
+ * @remarks
+ * Place this in the persistent app shell, wrapping a `foundation-ai-chat-bubble` that
+ * contains an AI assistant element in the `dialog-content` slot. The component will
+ * auto-create a matching collapse-mode element for docking into pages, and will
+ * control the expand button visibility based on whether a dock provider is registered.
+ *
+ * Pages that support docking call `aiPopoutManager.registerDockProvider()` on mount
+ * and `aiPopoutManager.deregisterDockProvider()` on unmount.
+ *
+ * @example
+ * ```html
+ * <foundation-ai-popout-manager>
+ *   <foundation-ai-chat-bubble title="My Assistant">
+ *     <my-assistant slot="dialog-content"></my-assistant>
+ *   </foundation-ai-chat-bubble>
+ * </foundation-ai-popout-manager>
+ * ```
+ *
+ * @beta
+ */
+export declare class FoundationAiPopoutManager extends GenesisElement {
+    /** True when a dock provider is registered — controls expand button visibility. */
+    canDock: boolean;
+    private collapseEl;
+    private dockProvider;
+    private isDocked;
+    private unsubBus?;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    canDockChanged(): void;
+    registerDockProvider(provider: AiDockProvider): void;
+    deregisterDockProvider(): void;
+    /**
+     * If the assistant is currently docked, collapses it back into the bubble.
+     * Await this in `onBeforeNavButtonClick` to ensure cleanup before navigation.
+     */
+    collapseIfDocked(): Promise<void>;
+}
+
+/**
+ * A warm, conversational fallback agent. Acknowledges it can't help directly,
+ * explains what the available specialists can do, and invites the user to retry.
+ *
+ * The system prompt is generated at runtime by `OrchestratingDriver` from the
+ * specialist list — no manual authoring required.
+ *
+ * @beta
+ */
+export declare const friendlyFallbackAgent: FallbackAgentConfig;
+
+/**
+ * Returns the active `FoundationAiPopoutManager` instance, or `undefined` if none is mounted.
+ * Import this in pages to call `registerDockProvider` / `deregisterDockProvider`.
+ *
+ * @beta
+ */
+export declare function getAiPopoutManager(): FoundationAiPopoutManager | undefined;
+
+/**
+ * Orchestrates multiple specialist agents. Sits between `FoundationAiAssistant`
+ * and `ChatDriver`, classifying each user message and routing it to the right
+ * specialist — each with its own focused system prompt, tools, and primer.
+ *
+ * @beta
+ */
+export declare class OrchestratingDriver extends EventTarget implements AiDriver {
+    private readonly aiProvider;
+    private readonly agents;
+    private readonly chatDriver;
+    private readonly specialists;
+    private readonly fallback?;
+    private readonly maxHandoffs;
+    private readonly classifierHistoryLength;
+    private readonly classifierRetries;
+    activeAgent?: AgentConfig;
+    constructor(aiProvider: AIProvider, agents: AgentConfig[], options?: {
+        maxHandoffs?: number;
+        classifierHistoryLength?: number;
+        classifierRetries?: number;
+        maxToolIterations?: number;
+        maxFoldOperations?: number;
+    });
+    resolveInteraction(interactionId: string, result: unknown): void;
+    isBusy(): boolean;
+    loadHistory(messages: ChatMessage[]): void;
+    getRawHistory(): readonly ChatMessage[];
+    getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
+    sendMessage(input: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult>;
+    continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
+    private applyAgent;
+    private classify;
+    private appendInlineMessage;
+}
+
 /**
  * Controls the pop-out button shown in the assistant header.
  * - `"expand"` — assistant is embedded in the bubble dialog; button expands it to a layout panel.
@@ -397,4 +800,114 @@ export declare const FoundationAiAssistantTemplate: (designSystemPrefix: string)
  */
 export declare type PopoutMode = 'expand' | 'collapse';
 
+/** Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver. */
+export declare const REQUEST_CONTINUATION_TOOL = "request_continuation";
+
+/**
+ * Configuration for a specialist agent.
+ *
+ * Specialist agents are offered to the classifier for intent routing. The
+ * `description` is used to auto-generate the classifier prompt — no manual
+ * routing prompt authoring required.
+ *
+ * @beta
+ */
+export declare interface SpecialistAgentConfig extends BaseAgentConfig {
+    /**
+     * Plain-language description of what this agent handles.
+     * Used by the classifier to auto-generate its routing prompt.
+     */
+    description: string;
+    fallback?: never;
+}
+
+/**
+ * A brief, professional fallback agent. States what is available without
+ * elaboration. The `{{agents}}` placeholder is replaced at runtime by
+ * `OrchestratingDriver` with the generated specialist list.
+ *
+ * @beta
+ */
+export declare const strictFallbackAgent: FallbackAgentConfig;
+
+/**
+ * State of the chat suggestions feature.
+ *
+ * @beta
+ */
+export declare type SuggestionsState = {
+    status: 'idle';
+} | {
+    status: 'loading';
+} | {
+    status: 'loaded';
+    suggestions: string[];
+} | {
+    status: 'error';
+    message: string;
+};
+
+/**
+ * Symbol used to attach ToolFold metadata to a facade handler function.
+ * The ChatDriver inspects this to detect fold facades at runtime.
+ *
+ * @internal
+ */
+export declare const TOOL_FOLD_SYMBOL: unique symbol;
+
+/**
+ * Internal metadata for a tool fold. Attached to the facade handler via TOOL_FOLD_SYMBOL.
+ *
+ * @internal
+ */
+export declare interface ToolFold {
+    /** Facade tool name. */
+    name: string;
+    /** Description shown to the model. */
+    description: string;
+    /** Optional guidance injected in the fold-open response. */
+    usageNotes?: string;
+    /** Tool definitions inside this fold. */
+    tools: ChatToolDefinition[];
+    /** Handlers for the inner tools (keyed by tool name). */
+    handlers: ChatToolHandlers;
+    /**
+     * When true (default), all other tools are removed when this fold opens —
+     * the model can only see this fold's tools until it closes.
+     * When false, sibling tools remain alongside the inner tools.
+     */
+    exclusive: boolean;
+}
+
+/**
+ * The value returned by `createToolFold`.
+ *
+ * @beta
+ */
+export declare interface ToolFoldResult {
+    /**
+     * The facade tool definition. Add this to your agent's `toolDefinitions`.
+     * It is a regular `ChatToolDefinition` with an empty parameter schema.
+     */
+    definition: ChatToolDefinition;
+    /**
+     * The facade handler — a single-entry map keyed by the fold name.
+     * Spread this into your agent's `toolHandlers`.
+     * Inner tool handlers are NOT included here — they are encapsulated inside
+     * the fold metadata and installed by the driver only when the fold opens.
+     */
+    handler: ChatToolHandlers;
+}
+
+/**
+ * A tool entry in the expanded debug tree.
+ * Folds are represented as nodes with a `tools` array; regular tools have none.
+ *
+ * @beta
+ */
+export declare interface ToolTreeNode extends ChatToolDefinition {
+    /** Present when this tool is a fold — contains its inner tools recursively expanded. */
+    tools?: ToolTreeNode[];
+}
+
 export { }