@genesislcap/ai-assistant 14.432.2 → 14.433.0

package/src/main/main.ts

@@ -22,7 +22,12 @@
 // =============================================================================
 
 import { AIProvider } from '@genesislcap/foundation-ai';
-import type { ChatAttachment, ChatConfig, ChatMessage } from '@genesislcap/foundation-ai';
+import type {
+  ChatAttachment,
+  ChatConfig,
+  ChatInputDuringExecutionMode,
+  ChatMessage,
+} from '@genesislcap/foundation-ai';
 import { avoidTreeShaking } from '@genesislcap/foundation-utils';
 import {
   customElement,
@@ -34,6 +39,7 @@ import {
 } from '@genesislcap/web-core';
 import { agenticActivityBus } from '../channel/ai-activity-bus';
 import { AiActivityHalo } from '../components/activity-halo/activity-halo';
+import { AgentPicker } from '../components/agent-picker/agent-picker';
 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';
@@ -44,13 +50,21 @@ import { OrchestratingDriver } from '../components/orchestrating-driver/orchestr
 import type { AgentConfig } from '../config/config';
 import { getOrCreateDriver, deleteDriver } from '../state/driver-registry';
 import { getSessionStore, hasSessionStore, type SessionStoreReturn } from '../state/session-store';
+import {
+  AI_COLOUR_AMBER,
+  AI_COLOUR_CYAN,
+  AI_COLOUR_PINK,
+  AI_COLOUR_VIOLET,
+} from '../styles/ai-colours';
 import { ChatSuggestions } from '../suggestions/chat-suggestions';
+import { AnimatedPanelToggle } from '../utils/animated-panel-toggle';
 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 {
+  AgentPickerMode,
   AiAssistantAnimation,
   AiAssistantState,
   PopoutMode,
@@ -58,6 +72,24 @@ import type {
 } from './main.types';
 
 /** Context window sizes (in tokens) for known models. */
+/**
+ * Pin tint palette, cycled by agent position. Matches the four brand colours
+ * used by the halo overlay and loading dots.
+ */
+const PIN_COLOURS = [AI_COLOUR_AMBER, AI_COLOUR_PINK, AI_COLOUR_CYAN, AI_COLOUR_VIOLET];
+
+/**
+ * Duration of the agent-picker slide-out animation. Must stay in sync with the
+ * `agent-picker-slide-out` keyframe duration in `main.styles.ts`.
+ */
+const AGENT_PICKER_CLOSE_MS = 200;
+
+/**
+ * Duration of the settings panel slide-out animation. Must stay in sync with
+ * the `settings-slide-out` keyframe duration in `main.styles.ts`.
+ */
+const SETTINGS_CLOSE_MS = 200;
+
 const MODEL_CONTEXT_LIMITS: Record<string, number> = {
   'gemini-2.5-flash': 1_048_576,
   'gemini-2.5-flash-lite': 1_048_576,
@@ -74,6 +106,7 @@ avoidTreeShaking(
   AiChatBubble,
   AiActivityHalo,
   ChatSuggestions,
+  AgentPicker,
 );
 
 /** Recursively strips `toolHandlers` from an agent and all its sub-agents. */
@@ -125,6 +158,14 @@ export class FoundationAiAssistant extends GenesisElement {
    */
   @observable agents?: AgentConfig[];
   @observable chatConfig: ChatConfig = {};
+
+  /**
+   * Resolved agent picker mode from `chatConfig.picker.mode`. Defaults to
+   * `'disabled'`.
+   */
+  get agentPicker(): AgentPickerMode {
+    return this.chatConfig.picker?.mode ?? 'disabled';
+  }
   @observable debugStateFactory?: () => unknown;
   /** When set, enables Redux DevTools for this instance's session store. */
   @attr({ attribute: 'debug-redux', mode: 'boolean' }) debugRedux = false;
@@ -223,6 +264,39 @@ export class FoundationAiAssistant extends GenesisElement {
     this._sessionRef?.actions.aiAssistant.setEnabledAnimations(value);
   }
 
+  /**
+   * Whether the agent picker slide-out panel is open. Lives on the session
+   * store so the bubble-dialog and popout-panel instances stay in sync.
+   */
+  get agentPickerOpen(): boolean {
+    return this._sessionRef?.store.aiAssistant.agentPickerOpen ?? false;
+  }
+  set agentPickerOpen(value: boolean) {
+    this._sessionRef?.actions.aiAssistant.setAgentPickerOpen(value);
+  }
+
+  /**
+   * Name of the agent the user has pinned via the agent picker. `null` means
+   * automatic routing (Auto). Persisted on the session store, so it survives
+   * pop-in/pop-out but resets on page refresh.
+   */
+  get pinnedAgentName(): string | null {
+    return this._sessionRef?.store.aiAssistant.pinnedAgentName ?? null;
+  }
+  set pinnedAgentName(value: string | null) {
+    const previous = this._sessionRef?.store.aiAssistant.pinnedAgentName ?? null;
+    this._sessionRef?.actions.aiAssistant.setPinnedAgentName(value);
+    if (this.driver instanceof OrchestratingDriver) {
+      this.driver.setPinnedAgent(value);
+    }
+    // Suggestions are scoped to the active routing — resetting forces a fresh
+    // fetch when the user pins/unpins so the prompts match the new agent.
+    if (previous !== value) {
+      this.suggestionsState = { status: 'idle' };
+      this.fetchSuggestions();
+    }
+  }
+
   get liveSubAgentTrace(): ChatMessage[] {
     return this._sessionRef?.store.aiAssistant.liveSubAgentTrace ?? [];
   }
@@ -237,6 +311,28 @@ export class FoundationAiAssistant extends GenesisElement {
     this._sessionRef?.actions.aiAssistant.setLiveSubAgentName(value);
   }
 
+  /**
+   * In-flight per-call chat-input overrides pushed by `requestSubAgent`
+   * invocations. Empty means no override is active.
+   */
+  get subAgentInputOverrides() {
+    return this._sessionRef?.store.aiAssistant.subAgentInputOverrides ?? [];
+  }
+
+  /**
+   * Resolves the effective chat-input behaviour while the assistant is
+   * executing. Sub-agent overrides take precedence over the agent-level
+   * config; among overrides the most restrictive wins (`'hidden'` >
+   * `'disabled'`). Falls back to the active agent's config, then `'disabled'`.
+   */
+  @volatile
+  get effectiveChatInputDuringExecution(): ChatInputDuringExecutionMode {
+    const overrides = this.subAgentInputOverrides;
+    if (overrides.some((o) => o.mode === 'hidden')) return 'hidden';
+    if (overrides.some((o) => o.mode === 'disabled')) return 'disabled';
+    return this.activeAgent?.chatInputDuringExecution ?? 'disabled';
+  }
+
   /** Most recent prompt token count from the AI provider, if available. */
   get contextTokens(): number | undefined {
     return this._sessionRef?.store.aiAssistant.contextTokens;
@@ -484,20 +580,40 @@ export class FoundationAiAssistant extends GenesisElement {
       // driver's own history array (which is still being mutated by the tool loop).
       this.liveSubAgentTrace = structuredClone(history);
     };
-    const onSubAgentStop = () => {
+    const onSubAgentStart = (e: Event) => {
+      const { invocationId, chatInputDuringExecution } = (e as CustomEvent).detail as {
+        invocationId: string;
+        chatInputDuringExecution?: ChatInputDuringExecutionMode;
+      };
+      if (!chatInputDuringExecution) return;
+      this._sessionRef?.actions.aiAssistant.addSubAgentInputOverride({
+        id: invocationId,
+        mode: chatInputDuringExecution,
+      });
+    };
+    const onSubAgentStop = (e: Event) => {
       this.liveSubAgentTrace = [];
       this.liveSubAgentName = null;
+      const { invocationId } = (e as CustomEvent).detail as { invocationId?: string };
+      if (invocationId) {
+        this._sessionRef?.actions.aiAssistant.removeSubAgentInputOverride({ id: invocationId });
+      }
     };
     driver.addEventListener('sub-agent-history-updated', onSubAgentHistoryUpdated);
+    driver.addEventListener('sub-agent-start', onSubAgentStart);
     driver.addEventListener('sub-agent-stop', onSubAgentStop);
 
     const cleanups: (() => void)[] = [
       () => driver.removeEventListener('history-updated', onHistoryUpdated),
       () => driver.removeEventListener('sub-agent-history-updated', onSubAgentHistoryUpdated),
+      () => driver.removeEventListener('sub-agent-start', onSubAgentStart),
       () => driver.removeEventListener('sub-agent-stop', onSubAgentStop),
     ];
 
     if (driver instanceof OrchestratingDriver) {
+      // Restore any pinned agent from the session store onto the freshly built
+      // driver, so pop-in/pop-out and agents-array reassignment preserve the pin.
+      driver.setPinnedAgent(this.pinnedAgentName);
       const onOrchStart = () => {
         this.showHalo = 'orchestrating';
       };
@@ -553,6 +669,11 @@ export class FoundationAiAssistant extends GenesisElement {
       this.enabledAnimations =
         (ui.animations?.enabled as AiAssistantAnimation[]) ??
         (ui.animations ? [...ALL_ANIMATIONS] : []);
+
+      const defaultAgent = this.chatConfig.picker?.defaultAgent;
+      if (defaultAgent && (this.agents ?? []).some((a) => a.name === defaultAgent)) {
+        this.pinnedAgentName = defaultAgent;
+      }
     }
 
     this.driver = getOrCreateDriver(key, () => this.createDriver());
@@ -634,6 +755,11 @@ export class FoundationAiAssistant extends GenesisElement {
     this._userScrolledAway = false;
     document.removeEventListener('pointerdown', this._handleGlobalInteraction, true);
     document.removeEventListener('focusin', this._handleGlobalInteraction, true);
+    // Finalise any in-flight panel-close animations before clearing
+    // _sessionRef, otherwise the closed state never makes it to the store and
+    // the panel re-mounts open.
+    this._agentPickerToggle.finalize();
+    this._settingsToggle.finalize();
     // Clear local references only — driver and store stay in their registries.
     this.driver = undefined;
     this._sessionRef = undefined;
@@ -772,25 +898,97 @@ export class FoundationAiAssistant extends GenesisElement {
     return parts.length ? parts.join('::') : undefined;
   }
 
+  private readonly _settingsToggle = new AnimatedPanelToggle(
+    this,
+    '.settings-panel',
+    SETTINGS_CLOSE_MS,
+    () => this.settingsOpen,
+    (v) => {
+      this.settingsOpen = v;
+    },
+  );
+
   toggleSettings() {
-    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;
+    this._settingsToggle.toggle();
+  }
+
+  private readonly _agentPickerToggle = new AnimatedPanelToggle(
+    this,
+    '.agent-picker-panel',
+    AGENT_PICKER_CLOSE_MS,
+    () => this.agentPickerOpen,
+    (v) => {
+      this.agentPickerOpen = v;
+    },
+  );
+
+  toggleAgentPicker() {
+    this._agentPickerToggle.toggle();
+  }
+
+  /**
+   * Programmatically pin an agent by name. Returns `true` if the pin was
+   * applied, `false` if the agent isn't in the configured agents array or
+   * the call was suppressed by `force: false`.
+   *
+   * With `force: false`, the call is a no-op when a `picker.defaultAgent` is
+   * configured and the user has already moved away from it (either by picking
+   * another agent or by switching to Auto). This lets hosts seed an opinion
+   * without overriding an explicit user choice.
+   *
+   * @public
+   */
+  setAgent(agentName: string, options?: { force?: boolean }): boolean {
+    if (!(this.agents ?? []).some((a) => a.name === agentName)) return false;
+    const force = options?.force ?? true;
+    if (!force) {
+      const defaultAgent = this.chatConfig.picker?.defaultAgent;
+      if (defaultAgent && this.pinnedAgentName !== defaultAgent) return false;
     }
+    this.pinnedAgentName = agentName;
+    return true;
+  }
+
+  /** Whether the picker toggle button should appear. Mirrors the picker's own visibility rule. */
+  @volatile
+  get agentPickerEnabled(): boolean {
+    if (this.agentPicker === 'disabled') return false;
+    if ((this.agents?.length ?? 0) <= 1) return false;
+    return (this.agents ?? []).some((a) => a.manualSelection?.enabled);
+  }
+
+  /** Hint text for the currently pinned agent, if any. Used in the toggle button tooltip. */
+  @volatile
+  get pinnedAgentHint(): string | undefined {
+    if (this.pinnedAgentName === null) return undefined;
+    return this.agents?.find((a) => a.name === this.pinnedAgentName)?.manualSelection?.hint;
+  }
+
+  /**
+   * Tint applied to the pin icon when an agent is pinned. Picked from the
+   * brand palette by agent position (modulo the palette length), so each agent
+   * gets a consistent colour across renders. `undefined` when nothing is
+   * pinned, the agent isn't in the current array, or the host has opted out
+   * via `chatConfig.picker.disablePinColours`.
+   */
+  @volatile
+  get pinnedAgentColour(): string | undefined {
+    if (this.pinnedAgentName === null) return undefined;
+    if (this.chatConfig.picker?.disablePinColours) return undefined;
+    const idx = this.agents?.findIndex((a) => a.name === this.pinnedAgentName) ?? -1;
+    if (idx < 0) return undefined;
+    return PIN_COLOURS[idx % PIN_COLOURS.length];
+  }
+
+  /**
+   * Placeholder shown in the chat input. Substitutes the pinned agent's name
+   * when one is selected so the user has a clearer signal of where their
+   * message will go; otherwise falls back to the host-provided placeholder.
+   */
+  @volatile
+  get effectivePlaceholder(): string {
+    if (this.pinnedAgentName) return `Message ${this.pinnedAgentName}...`;
+    return this.placeholder;
   }
 
   toggleShowToolCalls() {
@@ -1005,6 +1203,9 @@ export class FoundationAiAssistant extends GenesisElement {
     this.attachmentErrors = [];
     this.suggestionsState = { status: 'idle' };
     this._userScrolledAway = false;
+    // Close the picker on send — the toggle button is disabled during loading,
+    // so without this an open panel would be stuck open with clickable segments.
+    if (this.agentPickerOpen) this.toggleAgentPicker();
     this.state = 'loading';
     this.startLoadingTimer();
     const displayInput = pendingAttachments?.length

package/src/main/main.types.ts

@@ -14,6 +14,8 @@ export type AiAssistantState = 'idle' | 'loading' | 'error';
  */
 export type PopoutMode = 'expand' | 'collapse';
 
+export type { AgentPickerMode } from '@genesislcap/foundation-ai';
+
 /**
  * State of the chat suggestions feature.
  *

package/src/state/ai-assistant-slice.ts

@@ -1,9 +1,24 @@
-import type { ChatMessage } from '@genesislcap/foundation-ai';
+import type { ChatInputDuringExecutionMode, ChatMessage } from '@genesislcap/foundation-ai';
 import { createSlice } from '@genesislcap/foundation-redux';
 import type { PayloadAction } from '@genesislcap/foundation-redux';
 import type { AgentConfig } from '../config/config';
 import type { AiAssistantAnimation, AiAssistantState, SuggestionsState } from '../main/main.types';
 
+/**
+ * A single in-flight per-call chat-input override pushed by a `requestSubAgent`
+ * invocation. Tracked as an array (not a counter) so the slice can survive
+ * pop-in/pop-out and so a listener that connects mid-execution can compute the
+ * effective mode without having seen the start event.
+ *
+ * @internal
+ */
+export interface SubAgentInputOverride {
+  /** Unique per-invocation id, paired with the start/stop events. */
+  id: string;
+  /** The mode requested for this invocation. */
+  mode: ChatInputDuringExecutionMode;
+}
+
 /**
  * Shape of a single AI assistant session's serializable state.
  *
@@ -20,12 +35,30 @@ export interface AiAssistantSessionState {
   contextTokens: number | undefined;
   contextLimit: number | undefined;
   activeAgent: Omit<AgentConfig, 'toolHandlers'> | undefined;
+  /**
+   * Name of the agent the user has pinned via the picker. `null` means the
+   * orchestrator chooses each turn (Auto). Survives lifecycle events but
+   * resets on page refresh.
+   */
+  pinnedAgentName: string | null;
+  /**
+   * Whether the agent picker slide-out panel is currently open. Lives in the
+   * slice so the bubble-dialog and popout-panel instances stay in sync as the
+   * user pops in and out.
+   */
+  agentPickerOpen: boolean;
   /** Draft text in the input box — preserved across pop-in/pop-out cycles. */
   inputValue: string;
   /** Live trace from a currently-executing sub-agent. Cleared on sub-agent-stop. */
   liveSubAgentTrace: ChatMessage[];
   /** Name of the currently-executing sub-agent, or null when idle. */
   liveSubAgentName: string | null;
+  /**
+   * In-flight per-call chat-input overrides pushed by `requestSubAgent` calls.
+   * The most restrictive entry (`'hidden'` > `'disabled'`) wins; an empty list
+   * means the agent-level `chatInputDuringExecution` applies.
+   */
+  subAgentInputOverrides: SubAgentInputOverride[];
 }
 
 export const defaultSessionState: AiAssistantSessionState = {
@@ -39,9 +72,12 @@ export const defaultSessionState: AiAssistantSessionState = {
   contextTokens: undefined,
   contextLimit: undefined,
   activeAgent: undefined,
+  pinnedAgentName: null,
+  agentPickerOpen: false,
   inputValue: '',
   liveSubAgentTrace: [],
   liveSubAgentName: null,
+  subAgentInputOverrides: [],
 };
 
 export const aiAssistantSlice = createSlice({
@@ -78,6 +114,12 @@ export const aiAssistantSlice = createSlice({
     setActiveAgent(state, action: PayloadAction<Omit<AgentConfig, 'toolHandlers'> | undefined>) {
       state.activeAgent = action.payload;
     },
+    setPinnedAgentName(state, action: PayloadAction<string | null>) {
+      state.pinnedAgentName = action.payload;
+    },
+    setAgentPickerOpen(state, action: PayloadAction<boolean>) {
+      state.agentPickerOpen = action.payload;
+    },
     setInputValue(state, action: PayloadAction<string>) {
       state.inputValue = action.payload;
     },
@@ -87,6 +129,14 @@ export const aiAssistantSlice = createSlice({
     setLiveSubAgentName(state, action: PayloadAction<string | null>) {
       state.liveSubAgentName = action.payload;
     },
+    addSubAgentInputOverride(state, action: PayloadAction<SubAgentInputOverride>) {
+      state.subAgentInputOverrides.push(action.payload);
+    },
+    removeSubAgentInputOverride(state, action: PayloadAction<{ id: string }>) {
+      state.subAgentInputOverrides = state.subAgentInputOverrides.filter(
+        (o) => o.id !== action.payload.id,
+      );
+    },
   },
   selectors: {},
 });

package/src/utils/animated-panel-toggle.ts

@@ -0,0 +1,62 @@
+/**
+ * Drives the open/close lifecycle of a slide-out panel inside a component's
+ * shadow root, with a tracked close timer instead of an `animationend`
+ * listener so the panel cannot wedge open if it's unmounted mid-animation
+ * (pop-in/pop-out, dock change, host disconnect).
+ *
+ * @internal
+ */
+export class AnimatedPanelToggle {
+  private timer?: ReturnType<typeof setTimeout>;
+
+  constructor(
+    private readonly host: HTMLElement,
+    private readonly selector: string,
+    private readonly closeDurationMs: number,
+    private readonly getOpen: () => boolean,
+    private readonly setOpen: (v: boolean) => void,
+  ) {}
+
+  private queryPanel(): HTMLElement | null {
+    return this.host.shadowRoot?.querySelector(this.selector) as HTMLElement | null;
+  }
+
+  toggle(): void {
+    if (this.getOpen()) {
+      // Capture the panel reference now so the timer callback strips
+      // `closing` from the same node, regardless of any later remounts.
+      // Leftover `closing` is what breaks the next open: with
+      // `animation-fill-mode: forwards` the slide-out keyframe pins the panel
+      // to opacity 0, so a remount looks like a no-op.
+      const panel = this.queryPanel();
+      panel?.classList.add('closing');
+      if (this.timer != null) clearTimeout(this.timer);
+      this.timer = setTimeout(() => {
+        this.timer = undefined;
+        panel?.classList.remove('closing');
+        this.setOpen(false);
+      }, this.closeDurationMs);
+    } else {
+      // Re-opened mid-close: cancel the pending flip and strip the closing
+      // class so the panel snaps back to the open state.
+      if (this.timer != null) {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.queryPanel()?.classList.remove('closing');
+      }
+      this.setOpen(true);
+    }
+  }
+
+  /**
+   * Synchronously finalise an in-flight close — call from
+   * `disconnectedCallback` so the closed state lands in the store before any
+   * session ref is cleared.
+   */
+  finalize(): void {
+    if (this.timer == null) return;
+    clearTimeout(this.timer);
+    this.timer = undefined;
+    this.setOpen(false);
+  }
+}

package/src/utils/index.ts

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