@genesislcap/ai-assistant 14.420.0 → 14.421.0

package/src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts

@@ -1,4 +1,4 @@
-import { InteractionResult } from '@genesislcap/foundation-ai';
+import type { InteractionResult } from '@genesislcap/foundation-ai';
 import { customElement, GenesisElement, observable } from '@genesislcap/web-core';
 import { logger } from '../../utils/logger';
 import { AiChatInteractionWrapperStyles } from './chat-interaction-wrapper.styles';
@@ -26,8 +26,8 @@ export class AiChatInteractionWrapper extends GenesisElement {
   @observable data: any;
   /** @internal */
   @observable interactionId: string = '';
-  /** When true, the interaction has already been resolved. Forwarded to the rendered component. @internal */
-  @observable resolved: boolean = false;
+  /** The resolved result once the interaction has completed. Forwarded to the rendered component. @internal */
+  @observable resolved: InteractionResult<unknown> | undefined = undefined;
 
   /** @internal */
   container!: HTMLElement;

package/src/components/chat-markdown/chat-markdown.ts

@@ -77,7 +77,7 @@ const styles = css`
   styles,
 })
 export class AiChatMarkdown extends GenesisElement {
-  /** @internal */
+  /** The markdown string to render. */
   @observable content: string = '';
 
   /** @internal */

package/src/components/halo-overlay.ts

@@ -6,6 +6,11 @@ import {
   AI_COLOUR_VIOLET,
 } from '../styles/ai-colours';
 
+const HALO_DEFAULT_SPEED = 1.5;
+const HALO_DEFAULT_BORDER_SIZE = 3;
+const HALO_DEFAULT_GLOW_OPACITY = 0.35;
+const HALO_DEFAULT_GLOW_SPREAD = 70;
+
 /**
  * Animated halo overlay — rotating conic-gradient border with an inward glow.
  *
@@ -46,7 +51,7 @@ import {
       position: absolute;
       inset: 0;
       border-radius: inherit;
-      padding: 3px;
+      padding: var(--halo-border-size, 3px);
       background: repeating-conic-gradient(
         from var(--halo-angle, 0deg),
         ${AI_COLOUR_AMBER},
@@ -79,14 +84,47 @@ import {
         ${AI_COLOUR_VIOLET},
         ${AI_COLOUR_AMBER}
       );
-      opacity: 0.35;
-      -webkit-mask-image: radial-gradient(ellipse at center, transparent 70%, black 100%);
-      mask-image: radial-gradient(ellipse at center, transparent 70%, black 100%);
+      opacity: var(--halo-glow-opacity, 0.35);
+      -webkit-mask-image: radial-gradient(
+        ellipse at center,
+        transparent var(--halo-glow-spread, 70%),
+        black 100%
+      );
+      mask-image: radial-gradient(
+        ellipse at center,
+        transparent var(--halo-glow-spread, 70%),
+        black 100%
+      );
     }
   `,
 })
 export class AiHaloOverlay extends GenesisElement {
   @attr({ mode: 'boolean' }) active: boolean = false;
+  /** Rotation speed in degrees per frame. Default: 1.5 (≈ 4 s per full revolution at 60 fps). */
+  @attr({ converter: { fromView: Number, toView: String } }) speed: number = HALO_DEFAULT_SPEED;
+  /** Rotation direction. Default: 'cw' (clockwise). */
+  @attr direction: 'cw' | 'ccw' = 'cw';
+  /** Border thickness in px. Default: 3. */
+  @attr({ attribute: 'border-size', converter: { fromView: Number, toView: String } })
+  borderSize: number = HALO_DEFAULT_BORDER_SIZE;
+  /** Glow layer opacity (0–1). Default: 0.35. */
+  @attr({ attribute: 'glow-opacity', converter: { fromView: Number, toView: String } })
+  glowOpacity: number = HALO_DEFAULT_GLOW_OPACITY;
+  /** Transparent stop of the radial glow mask as a percentage (0–100). Higher = less spread. Default: 70. */
+  @attr({ attribute: 'glow-spread', converter: { fromView: Number, toView: String } })
+  glowSpread: number = HALO_DEFAULT_GLOW_SPREAD;
+
+  borderSizeChanged() {
+    this.style.setProperty('--halo-border-size', `${this.borderSize}px`);
+  }
+
+  glowOpacityChanged() {
+    this.style.setProperty('--halo-glow-opacity', String(this.glowOpacity));
+  }
+
+  glowSpreadChanged() {
+    this.style.setProperty('--halo-glow-spread', `${this.glowSpread}%`);
+  }
 
   // TODO: The rAF loop is fine for demos but has two drawbacks vs a pure CSS @property animation:
   // 1. It runs on the main thread, so heavy JS work can cause the animation to stutter.
@@ -94,8 +132,6 @@ export class AiHaloOverlay extends GenesisElement {
   // Once @property inside Shadow DOM has solid cross-browser support, consider switching back
   // to a CSS @keyframes approach and removing connectedCallback/disconnectedCallback/tick().
 
-  // 1.5° per frame @ 60 fps ≈ 4 s per full revolution
-  private static readonly DEG_PER_FRAME = 1.5;
   private static readonly FULL_ROTATION_DEG = 360;
 
   private angle = 0;
@@ -114,7 +150,9 @@ export class AiHaloOverlay extends GenesisElement {
   }
 
   private tick() {
-    this.angle = (this.angle + AiHaloOverlay.DEG_PER_FRAME) % AiHaloOverlay.FULL_ROTATION_DEG;
+    const step = this.direction === 'ccw' ? -this.speed : this.speed;
+    this.angle =
+      (this.angle + step + AiHaloOverlay.FULL_ROTATION_DEG) % AiHaloOverlay.FULL_ROTATION_DEG;
     this.style.setProperty('--halo-angle', `${this.angle}deg`);
     this.animFrame = requestAnimationFrame(() => this.tick());
   }

package/src/components/orchestrating-driver/index.ts

@@ -0,0 +1 @@
+export { OrchestratingDriver } from './orchestrating-driver';

package/src/components/orchestrating-driver/orchestrating-driver.ts

@@ -0,0 +1,328 @@
+import type {
+  AIProvider,
+  ChatAttachment,
+  ChatDriverResult,
+  ChatMessage,
+  ChatRequestOptions,
+} from '@genesislcap/foundation-ai';
+import type { AgentConfig, FallbackAgentConfig, SpecialistAgentConfig } from '../../config/config';
+import { logger } from '../../utils/logger';
+import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
+import { ChatDriver, REQUEST_CONTINUATION_TOOL } from '../chat-driver/chat-driver';
+
+const DEFAULT_MAX_HANDOFFS = 3;
+const DEFAULT_CLASSIFIER_HISTORY_LENGTH = 4;
+const DEFAULT_CLASSIFIER_RETRIES = 2;
+
+const REQUEST_CONTINUATION_DEFINITION = {
+  name: REQUEST_CONTINUATION_TOOL,
+  description:
+    "Call this when you have completed your part of the task but fulfilling the user's full request requires capabilities outside your domain. Do not call this if you can complete the request yourself. Pass a plain-language description of what still needs to be done — another specialist will be selected automatically.",
+  parameters: {
+    type: 'object',
+    required: ['summary', 'remaining_task'],
+    properties: {
+      summary: {
+        type: 'string',
+        description: 'What you found or did — passed as context to the next specialist.',
+      },
+      remaining_task: {
+        type: 'string',
+        description:
+          'What still needs to be done, in plain language. Used to route to the right specialist.',
+      },
+    },
+  },
+};
+
+function isSpecialist(agent: AgentConfig): agent is SpecialistAgentConfig {
+  return !agent.fallback;
+}
+
+function isFallback(agent: AgentConfig): agent is FallbackAgentConfig {
+  return agent.fallback === true;
+}
+
+function buildFallbackSystemPrompt(
+  fallback: FallbackAgentConfig,
+  specialists: SpecialistAgentConfig[],
+): string {
+  const agentList = specialists.map((s) => `- ${s.name}: ${s.description}`).join('\n');
+  if (fallback.systemPrompt) {
+    return fallback.systemPrompt.replace('{{agents}}', agentList);
+  }
+  return `You are a helpful assistant. You cannot directly help with the user's request, but the following specialists are available:\n\n${agentList}\n\nPolitely let the user know what you can help with and invite them to rephrase their request.`;
+}
+
+/**
+ * Prepares history for the LLM only: masks tool call args and results from other
+ * agents so the active specialist is not confused by tools it does not have.
+ * Canonical history in `ChatDriver` stays unmasked for UI and logging.
+ */
+function transformHistoryForAgent(history: ChatMessage[], agentName: string): ChatMessage[] {
+  return history.map((msg) => {
+    if (!msg.agentName || msg.agentName === agentName) return msg;
+    if (msg.toolCalls?.length) {
+      return { ...msg, toolCalls: msg.toolCalls.map((tc) => ({ ...tc, args: {} })) };
+    }
+    if (msg.toolResult) {
+      return {
+        ...msg,
+        toolResult: { ...msg.toolResult, content: "[other agent's tool result omitted]" },
+      };
+    }
+    return msg;
+  });
+}
+
+/**
+ * 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 class OrchestratingDriver extends EventTarget implements AiDriver {
+  private readonly chatDriver: ChatDriver;
+  private readonly specialists: SpecialistAgentConfig[];
+  private readonly fallback?: FallbackAgentConfig;
+  private readonly maxHandoffs: number;
+  private readonly classifierHistoryLength: number;
+  private readonly classifierRetries: number;
+
+  activeAgent?: AgentConfig;
+
+  constructor(
+    private readonly aiProvider: AIProvider,
+    private readonly agents: AgentConfig[],
+    options: {
+      maxHandoffs?: number;
+      classifierHistoryLength?: number;
+      classifierRetries?: number;
+      maxToolIterations?: number;
+      maxFoldOperations?: number;
+    } = {},
+  ) {
+    super();
+    this.maxHandoffs = options.maxHandoffs ?? DEFAULT_MAX_HANDOFFS;
+    this.classifierHistoryLength =
+      options.classifierHistoryLength ?? DEFAULT_CLASSIFIER_HISTORY_LENGTH;
+    this.classifierRetries = options.classifierRetries ?? DEFAULT_CLASSIFIER_RETRIES;
+
+    this.specialists = agents.filter(isSpecialist);
+    const fallbacks = agents.filter(isFallback);
+    if (fallbacks.length > 1) {
+      logger.warn(
+        'OrchestratingDriver: multiple fallback agents found — only the first will be used.',
+      );
+    }
+
+    const rawFallback = fallbacks[0];
+    this.fallback = rawFallback
+      ? { ...rawFallback, systemPrompt: buildFallbackSystemPrompt(rawFallback, this.specialists) }
+      : undefined;
+
+    this.chatDriver = new ChatDriver(
+      aiProvider,
+      {},
+      [],
+      undefined,
+      undefined,
+      options.maxToolIterations,
+      options.maxFoldOperations,
+    );
+
+    // Proxy history-updated events from the shared driver
+    this.chatDriver.addEventListener('history-updated', (e: Event) => {
+      this.dispatchEvent(new CustomEvent('history-updated', { detail: (e as CustomEvent).detail }));
+    });
+  }
+
+  resolveInteraction(interactionId: string, result: unknown): void {
+    this.chatDriver.resolveInteraction(interactionId, result);
+  }
+
+  isBusy(): boolean {
+    return this.chatDriver.isBusy();
+  }
+
+  loadHistory(messages: ChatMessage[]): void {
+    this.chatDriver.loadHistory(messages);
+  }
+
+  getRawHistory(): readonly ChatMessage[] {
+    return this.chatDriver.getHistory();
+  }
+
+  async getSuggestions(
+    history: ChatMessage[],
+    prompt: string,
+    count: number,
+    allAgentInfo?: AllAgentSummary[],
+  ): Promise<string[]> {
+    const agentInfo = this.specialists.map((s) => ({
+      name: s.name,
+      description: s.description,
+      tools: s.toolDefinitions ?? [],
+    }));
+    return this.chatDriver.getSuggestions(history, prompt, count, agentInfo);
+  }
+
+  async sendMessage(input: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult> {
+    const history = this.chatDriver.getHistory() as ChatMessage[];
+
+    // Emit the user message immediately so the UI reflects it during the classify
+    // round-trip — without this the chat appears frozen until classify returns.
+    this.dispatchEvent(
+      new CustomEvent('history-updated', {
+        detail: [...history, { role: 'user', content: input, attachments }],
+      }),
+    );
+
+    this.dispatchEvent(new CustomEvent('orchestrating-start'));
+    let currentAgent = await this.classify(input, history);
+    let isHandoff = false;
+    let handoffs = 0;
+    let handoffSummary = '';
+    let remainingTask = '';
+
+    while (true) {
+      this.applyAgent(currentAgent);
+
+      let result: ChatDriverResult;
+      if (isHandoff) {
+        const contextPrimer: ChatMessage[] = handoffSummary
+          ? [{ role: 'user', content: `[Context from previous agent]: ${handoffSummary}` }]
+          : [];
+        // eslint-disable-next-line no-await-in-loop
+        result = await this.chatDriver.continueFromHistory(contextPrimer);
+      } else {
+        // eslint-disable-next-line no-await-in-loop
+        result = await this.chatDriver.sendMessage(input, attachments);
+      }
+
+      if (result.reason !== 'agent-handoff' || isFallback(currentAgent)) {
+        break;
+      }
+
+      handoffs += 1;
+      if (handoffs > this.maxHandoffs) {
+        this.appendInlineMessage(
+          `I wasn't able to fully complete your request — the task required more hand-offs between specialists than allowed (max: ${this.maxHandoffs}). Please try breaking your request into smaller steps.`,
+        );
+        break;
+      }
+
+      handoffSummary = result.summary;
+      remainingTask = result.remainingTask;
+      isHandoff = true;
+
+      const updatedHistory = this.chatDriver.getHistory() as ChatMessage[];
+      this.dispatchEvent(new CustomEvent('orchestrating-start'));
+      // eslint-disable-next-line no-await-in-loop
+      currentAgent = await this.classify(remainingTask, updatedHistory);
+    }
+
+    return { reason: 'done' };
+  }
+
+  async continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult> {
+    return this.chatDriver.continueFromHistory(transientPrimer);
+  }
+
+  private applyAgent(agent: AgentConfig): void {
+    // Fallback agents are terminal and should not hand off to other specialists
+    const agentToApply = isFallback(agent)
+      ? agent
+      : {
+          ...agent,
+          toolDefinitions: [...(agent.toolDefinitions ?? []), REQUEST_CONTINUATION_DEFINITION],
+        };
+
+    const previousAgent = this.activeAgent;
+    if (previousAgent && previousAgent.name !== agent.name) {
+      const rawHistory = this.chatDriver.getHistory() as ChatMessage[];
+      this.chatDriver.loadHistory([...rawHistory, { role: 'system-event', content: agent.name }]);
+    }
+
+    this.chatDriver.setProviderHistoryTransform((h) => transformHistoryForAgent(h, agent.name));
+    this.chatDriver.applyAgent(agentToApply);
+    this.activeAgent = agent;
+    this.dispatchEvent(new CustomEvent('orchestrating-stop'));
+    this.dispatchEvent(new CustomEvent('agent-changed', { detail: agent }));
+  }
+
+  private async classify(input: string, history: ChatMessage[]): Promise<AgentConfig> {
+    if (this.specialists.length === 0) {
+      return this.fallback ?? { name: 'Assistant', fallback: true };
+    }
+
+    const agentList = this.specialists
+      .map((a, i) => `${i}: ${a.name} — ${a.description}`)
+      .join('\n');
+
+    const recentMessages = history
+      .filter((m) => m.role === 'user' || m.role === 'assistant')
+      .slice(-this.classifierHistoryLength)
+      .map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`)
+      .join('\n');
+
+    const classifierPrompt = `You are a routing classifier. Call select_agent with the index of the best matching agent for the user message. Use -1 only if the request is entirely unrelated to every agent listed — prefer the closest match when in doubt. If the request spans multiple agents, pick the one that should act first; I will re-classify and route again once that agent is done.\n\nAgents:\n${agentList}${recentMessages ? `\n\nRecent conversation:\n${recentMessages}` : ''}`;
+
+    const routingTool = {
+      name: 'select_agent',
+      description: 'Select the most appropriate agent for the user message.',
+      parameters: {
+        type: 'object',
+        required: ['agent_index'],
+        properties: {
+          agent_index: {
+            type: 'integer',
+            description: 'Zero-based index of the matching agent, or -1 if no agent matches.',
+          },
+        },
+      },
+    };
+
+    for (let attempt = 0; attempt <= this.classifierRetries; attempt += 1) {
+      try {
+        const options: ChatRequestOptions = {
+          systemPrompt: classifierPrompt,
+          tools: [routingTool],
+        };
+        // eslint-disable-next-line no-await-in-loop
+        const response = await this.aiProvider.chat!([], input, options);
+        const tc = response.toolCalls?.[0];
+        const index = tc?.name === 'select_agent' ? (tc.args.agent_index as number) : -1;
+
+        if (index >= 0 && index < this.specialists.length) {
+          return this.specialists[index];
+        }
+        // index === -1 — fall through to fallback
+        break;
+      } catch (e) {
+        logger.warn(`OrchestratingDriver: classifier attempt ${attempt + 1} failed:`, e);
+        if (attempt === this.classifierRetries) {
+          logger.error('OrchestratingDriver: classifier failed after all retries, using fallback');
+        }
+      }
+    }
+
+    if (this.fallback) return this.fallback;
+
+    // No fallback configured — emit an inline response and return first specialist as no-op
+    const specialistNames = this.specialists.map((s) => s.name).join(', ');
+    this.appendInlineMessage(
+      `I'm not sure how to help with that. I can assist with: ${specialistNames}.`,
+    );
+    return this.specialists[0];
+  }
+
+  private appendInlineMessage(content: string): void {
+    const history = this.chatDriver.getHistory() as ChatMessage[];
+    this.chatDriver.loadHistory([...history, { role: 'assistant', content }]);
+    this.dispatchEvent(
+      new CustomEvent('history-updated', { detail: this.chatDriver.getHistory() }),
+    );
+  }
+}

package/src/components/popout-manager/index.ts

@@ -0,0 +1 @@
+export * from './popout-manager';

package/src/components/popout-manager/popout-manager.ts

@@ -0,0 +1,147 @@
+import { customElement, GenesisElement, html, observable } from '@genesislcap/web-core';
+import { agenticActivityBus } from '../../channel/ai-activity-bus';
+
+/**
+ * Contract for pages that support docking the AI assistant.
+ * Register an implementation with {@link getAiPopoutManager} on mount and deregister on unmount.
+ *
+ * @beta
+ */
+export 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;
+}
+
+/**
+ * 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
+ */
+@customElement({
+  name: 'foundation-ai-popout-manager',
+  template: html`
+    <slot></slot>
+  `,
+})
+export class FoundationAiPopoutManager extends GenesisElement {
+  /** True when a dock provider is registered — controls expand button visibility. */
+  @observable canDock = false;
+
+  private collapseEl: HTMLElement | null = null;
+  private dockProvider: AiDockProvider | null = null;
+  private isDocked = false;
+  private unsubBus?: () => void;
+
+  connectedCallback() {
+    super.connectedCallback();
+    _aiPopoutManager = this;
+
+    const bubble = this.querySelector('foundation-ai-chat-bubble');
+    const assistantEl = bubble?.querySelector('[slot="dialog-content"]');
+    if (assistantEl) {
+      this.collapseEl = document.createElement(assistantEl.tagName.toLowerCase());
+      this.collapseEl.setAttribute('popout-mode', 'collapse');
+      // Copy identity attributes so the collapse element shares the same session
+      // store and driver registry key as the expand-mode element in the bubble.
+      const headerTitle = assistantEl.getAttribute('header-title');
+      if (headerTitle) this.collapseEl.setAttribute('header-title', headerTitle);
+      if (assistantEl.id) this.collapseEl.id = assistantEl.id;
+    }
+
+    const unsubPopout = agenticActivityBus.subscribe('chat-popout', async () => {
+      if (this.isDocked || !this.dockProvider || !this.collapseEl) return;
+      this.isDocked = true;
+      await this.dockProvider.onDock(this.collapseEl);
+    });
+
+    const unsubPopin = agenticActivityBus.subscribe('chat-popin', () => {
+      this.isDocked = false;
+      this.dockProvider?.onUndock();
+    });
+
+    this.unsubBus = () => {
+      unsubPopout();
+      unsubPopin();
+    };
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.unsubBus?.();
+    this.unsubBus = undefined;
+    _aiPopoutManager = undefined;
+  }
+
+  canDockChanged() {
+    const bubble = this.querySelector('foundation-ai-chat-bubble');
+    const assistantEl = bubble?.querySelector('[slot="dialog-content"]');
+    if (this.canDock) {
+      assistantEl?.setAttribute('popout-mode', 'expand');
+    } else {
+      assistantEl?.removeAttribute('popout-mode');
+    }
+  }
+
+  registerDockProvider(provider: AiDockProvider): void {
+    this.dockProvider = provider;
+    this.canDock = true;
+  }
+
+  deregisterDockProvider(): void {
+    this.isDocked = false;
+    this.dockProvider = null;
+    this.canDock = false;
+  }
+
+  /**
+   * If the assistant is currently docked, collapses it back into the bubble.
+   * Await this in `onBeforeNavButtonClick` to ensure cleanup before navigation.
+   */
+  collapseIfDocked(): Promise<void> {
+    if (!this.isDocked || !this.dockProvider) return Promise.resolve();
+    this.dockProvider.initiateCollapse();
+    return Promise.resolve();
+  }
+}
+
+let _aiPopoutManager: FoundationAiPopoutManager | undefined;
+
+/**
+ * Returns the active `FoundationAiPopoutManager` instance, or `undefined` if none is mounted.
+ * Import this in pages to call `registerDockProvider` / `deregisterDockProvider`.
+ *
+ * @beta
+ */
+export function getAiPopoutManager(): FoundationAiPopoutManager | undefined {
+  return _aiPopoutManager;
+}

package/src/config/config.ts

@@ -1,24 +1,10 @@
 import type { ChatMessage, ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
 
-/**
- * Configuration for a single specialist agent.
- *
- * 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.
- *
- * @beta
- */
-export interface AgentConfig {
+interface BaseAgentConfig {
   /**
    * 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.
    */
@@ -37,3 +23,47 @@ export interface AgentConfig {
    */
   primerHistory?: ChatMessage[];
 }
+
+/**
+ * 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 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;
+}
+
+/**
+ * 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 interface FallbackAgentConfig extends BaseAgentConfig {
+  /**
+   * Marks this agent as the fallback for unrecognised requests.
+   */
+  fallback: true;
+  description?: never;
+}
+
+/**
+ * Configuration for an agent passed to `FoundationAiAssistant`.
+ *
+ * Either a specialist (requires `description`) or a fallback (requires
+ * `fallback: true`). Passing both or neither is a compile error.
+ *
+ * @beta
+ */
+export type AgentConfig = SpecialistAgentConfig | FallbackAgentConfig;