@genesislcap/ai-assistant 14.432.2 → 14.433.0

package/dist/esm/components/chat-driver/chat-driver.js

@@ -164,15 +164,39 @@ export class ChatDriver extends EventTarget {
     isBusy() {
         return this.busy;
     }
+    /**
+     * Wire a parent driver as the host for this driver's interactions. When set,
+     * `requestInteraction` delegates upward so the widget renders in (and
+     * resolves through) the parent's history and pending map. Calls chain
+     * naturally: a grandchild → child → root.
+     */
+    setHostInteractionRequester(fn) {
+        this.hostInteractionRequester = fn;
+    }
     /**
      * Request a custom UI interaction. Emits a new message with the interaction.
      * Tool handlers can call this to pause execution until the user completes the UI interaction.
      *
+     * If a host requester is wired (sub-agent case), the call delegates upward
+     * so the interaction lives on the parent — the main UI is only listening to
+     * the root driver. Only one interaction may be in flight at any time on a
+     * given root: concurrent calls (e.g. two parallel sub-agents both spawning a
+     * widget) throw. Parallel sub-agents are for parallel work, not for user
+     * interaction, which is inherently sequential.
+     *
      * @param componentName - The custom element name to render.
      * @param data - Data to pass to the component.
      */
     requestInteraction(componentName, data) {
         return __awaiter(this, void 0, void 0, function* () {
+            if (this.hostInteractionRequester) {
+                return this.hostInteractionRequester(componentName, data);
+            }
+            if (this.pendingInteractions.size > 0) {
+                throw new Error('requestInteraction: another user interaction is already in flight. ' +
+                    'Only one interaction may be active at a time — sequence them in a single tool handler ' +
+                    'rather than spawning widgets from parallel sub-agents or parallel tool calls.');
+            }
             const interactionId = crypto.randomUUID();
             return new Promise((resolve, reject) => {
                 this.pendingInteractions.set(interactionId, { resolve, reject });
@@ -297,19 +321,29 @@ export class ChatDriver extends EventTarget {
             ];
             const child = new ChatDriver(this.aiProvider);
             child.applyAgent(Object.assign(Object.assign({}, subConfig), { primerHistory: effectivePrimer }));
+            // Route interactions back through this driver so widgets render in the
+            // parent's (ultimately the root's) history and resolve via the same
+            // pending map the main UI is wired to. Recurses naturally for nested
+            // sub-agents.
+            child.setHostInteractionRequester((componentName, data) => this.requestInteraction(componentName, data));
             const forwardTrace = (e) => {
                 this.dispatchEvent(new CustomEvent('sub-agent-history-updated', {
                     detail: { agentName: subConfig.name, history: e.detail },
                 }));
             };
             child.addEventListener('history-updated', forwardTrace);
-            this.dispatchEvent(new CustomEvent('sub-agent-start', { detail: { name } }));
+            // Unique per-invocation id so listeners can pair start/stop reliably even
+            // when the same sub-agent runs multiple times in parallel.
+            const invocationId = crypto.randomUUID();
+            const chatInputDuringExecution = options === null || options === void 0 ? void 0 : options.chatInputDuringExecution;
+            const lifecycleDetail = { name, invocationId, chatInputDuringExecution };
+            this.dispatchEvent(new CustomEvent('sub-agent-start', { detail: lifecycleDetail }));
             try {
                 yield child.sendMessage(task !== null && task !== void 0 ? task : '');
             }
             finally {
                 child.removeEventListener('history-updated', forwardTrace);
-                this.dispatchEvent(new CustomEvent('sub-agent-stop', { detail: { name } }));
+                this.dispatchEvent(new CustomEvent('sub-agent-stop', { detail: lifecycleDetail }));
             }
             const trace = child.getHistory();
             const completion = child.getSubAgentCompletion();
@@ -514,16 +548,26 @@ export class ChatDriver extends EventTarget {
                     : emptyResponseAttempts > 0
                         ? `${baseSystemPrompt !== null && baseSystemPrompt !== void 0 ? baseSystemPrompt : ''}\n\nIMPORTANT: You must respond to the user's message. Call the appropriate tool or provide a text response — do not return an empty response.`
                         : baseSystemPrompt;
+                // Capture the pending user input, then clear the slots BEFORE the chat
+                // call. `sendMessage` already appended the user message to `this.history`,
+                // so on retries (empty / malformed) we must rely on history alone —
+                // otherwise the message gets sent twice (once via history, once via
+                // `currentInput`), which Gemini answers with an empty response and then
+                // we retry forever.
+                const userInputForCall = currentInput;
+                const attachmentsForCall = currentAttachments;
+                currentInput = '';
+                currentAttachments = undefined;
                 const options = {
                     systemPrompt,
                     // Strip fold-only properties (foldEvent, foldPath) before sending to provider
                     tools: this.toolDefinitions.length ? this.toolDefinitions : undefined,
-                    attachments: currentAttachments,
+                    attachments: attachmentsForCall,
                 };
                 let response;
                 try {
                     // eslint-disable-next-line no-await-in-loop
-                    response = yield this.aiProvider.chat(historyForCall, currentInput, options);
+                    response = yield this.aiProvider.chat(historyForCall, userInputForCall, options);
                 }
                 catch (e) {
                     if (e instanceof MalformedFunctionCallError) {
@@ -542,7 +586,6 @@ export class ChatDriver extends EventTarget {
                     }
                     throw e;
                 }
-                currentAttachments = undefined;
                 const isThinkingStep = response.content && ((_b = response.toolCalls) === null || _b === void 0 ? void 0 : _b.length);
                 const isEmptyResponse = !((_c = response.content) === null || _c === void 0 ? void 0 : _c.trim()) && !((_d = response.toolCalls) === null || _d === void 0 ? void 0 : _d.length);
                 if (isEmptyResponse) {
@@ -739,7 +782,6 @@ export class ChatDriver extends EventTarget {
                 if (this.subAgentCompletion) {
                     return { reason: 'done' };
                 }
-                currentInput = '';
             }
             if (iterations >= this.maxToolIterations) {
                 logger.warn('ChatDriver: reached max tool iterations, stopping');

package/dist/esm/components/orchestrating-driver/orchestrating-driver.js

@@ -49,6 +49,7 @@ export class OrchestratingDriver extends EventTarget {
         super();
         this.aiProvider = aiProvider;
         this.agents = agents;
+        this.pinnedAgentName = null;
         this.maxHandoffs = (_a = options.maxHandoffs) !== null && _a !== void 0 ? _a : DEFAULT_MAX_HANDOFFS;
         this.classifierHistoryLength =
             (_b = options.classifierHistoryLength) !== null && _b !== void 0 ? _b : DEFAULT_CLASSIFIER_HISTORY_LENGTH;
@@ -69,6 +70,9 @@ export class OrchestratingDriver extends EventTarget {
         this.chatDriver.addEventListener('sub-agent-history-updated', (e) => {
             this.dispatchEvent(new CustomEvent('sub-agent-history-updated', { detail: e.detail }));
         });
+        this.chatDriver.addEventListener('sub-agent-start', (e) => {
+            this.dispatchEvent(new CustomEvent('sub-agent-start', { detail: e.detail }));
+        });
         this.chatDriver.addEventListener('sub-agent-stop', (e) => {
             this.dispatchEvent(new CustomEvent('sub-agent-stop', { detail: e.detail }));
         });
@@ -79,6 +83,15 @@ export class OrchestratingDriver extends EventTarget {
     isBusy() {
         return this.chatDriver.isBusy();
     }
+    /**
+     * Pins routing to a specific agent by name. While pinned, the classifier is
+     * skipped and the continuation tool is hidden from the agent's tool list, so
+     * the agent cannot quietly hand back to the orchestrator. Pass `null` to
+     * return to automatic routing.
+     */
+    setPinnedAgent(name) {
+        this.pinnedAgentName = name;
+    }
     loadHistory(messages) {
         this.chatDriver.loadHistory(messages);
     }
@@ -87,7 +100,11 @@ export class OrchestratingDriver extends EventTarget {
     }
     getSuggestions(history, prompt, count, allAgentInfo) {
         return __awaiter(this, void 0, void 0, function* () {
-            const agentInfo = this.specialists.map((s) => {
+            // When pinned to a specialist, scope suggestions to that agent so the
+            // proposed prompts reflect the active routing instead of the full panel.
+            const pinned = this.resolvePinnedAgent();
+            const candidates = pinned && isSpecialist(pinned) ? [pinned] : this.specialists;
+            const agentInfo = candidates.map((s) => {
                 var _a;
                 return ({
                     name: s.name,
@@ -106,8 +123,10 @@ export class OrchestratingDriver extends EventTarget {
             this.dispatchEvent(new CustomEvent('history-updated', {
                 detail: [...history, { role: 'user', content: input, attachments }],
             }));
-            this.dispatchEvent(new CustomEvent('orchestrating-start'));
-            let currentAgent = yield this.classify(input, history, this.activeAgent);
+            const pinned = this.resolvePinnedAgent();
+            if (!pinned)
+                this.dispatchEvent(new CustomEvent('orchestrating-start'));
+            let currentAgent = pinned !== null && pinned !== void 0 ? pinned : (yield this.classify(input, history, this.activeAgent));
             let isHandoff = false;
             let handoffs = 0;
             let handoffSummary = '';
@@ -126,7 +145,9 @@ export class OrchestratingDriver extends EventTarget {
                     // eslint-disable-next-line no-await-in-loop
                     result = yield this.chatDriver.sendMessage(input, attachments);
                 }
-                if (result.reason !== 'agent-handoff' || isFallback(currentAgent)) {
+                // Pinned agents never hand off — the continuation tool is filtered out in
+                // applyAgent, but this guards against a model hallucinating a handoff result.
+                if (result.reason !== 'agent-handoff' || isFallback(currentAgent) || pinned) {
                     break;
                 }
                 handoffs += 1;
@@ -152,8 +173,9 @@ export class OrchestratingDriver extends EventTarget {
     }
     applyAgent(agent) {
         var _a;
-        // Fallback agents are terminal and should not hand off to other specialists
-        const agentToApply = isFallback(agent)
+        // Fallback and pinned agents are terminal — neither should hand off.
+        const isTerminal = isFallback(agent) || this.pinnedAgentName !== null;
+        const agentToApply = isTerminal
             ? agent
             : Object.assign(Object.assign({}, agent), { toolDefinitions: [...((_a = agent.toolDefinitions) !== null && _a !== void 0 ? _a : []), REQUEST_CONTINUATION_DEFINITION] });
         const previousAgent = this.activeAgent;
@@ -230,6 +252,21 @@ export class OrchestratingDriver extends EventTarget {
             return this.specialists[0];
         });
     }
+    /**
+     * Returns the pinned agent if `pinnedAgentName` matches a known specialist or
+     * fallback. Logs and returns `undefined` if pinned to a name that no longer
+     * exists in the agents array — caller falls back to the classifier.
+     */
+    resolvePinnedAgent() {
+        if (this.pinnedAgentName === null)
+            return undefined;
+        const match = this.agents.find((a) => a.name === this.pinnedAgentName);
+        if (!match) {
+            logger.warn(`OrchestratingDriver: pinned agent "${this.pinnedAgentName}" not found in agents array — falling back to classifier.`);
+            return undefined;
+        }
+        return match;
+    }
     appendInlineMessage(content) {
         const history = this.chatDriver.getHistory();
         this.chatDriver.loadHistory([...history, { role: 'assistant', content }]);

package/dist/esm/index.js

@@ -1,6 +1,7 @@
 export * from './main/main';
 export * from './main/main.types';
 export * from './main/main.template';
+export * from './components/agent-picker';
 export * from './components/ai-driver';
 export * from './components/chat-driver';
 export * from './components/orchestrating-driver';

package/dist/esm/main/main.js

@@ -27,6 +27,7 @@ import { avoidTreeShaking } from '@genesislcap/foundation-utils';
 import { customElement, html, GenesisElement, observable, volatile, attr, } 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 { 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';
@@ -35,13 +36,30 @@ import { AiHaloOverlay } from '../components/halo-overlay';
 import { OrchestratingDriver } from '../components/orchestrating-driver/orchestrating-driver';
 import { getOrCreateDriver, deleteDriver } from '../state/driver-registry';
 import { getSessionStore, hasSessionStore } from '../state/session-store';
+import { 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';
 /** 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 = {
     'gemini-2.5-flash': 1048576,
     'gemini-2.5-flash-lite': 1048576,
@@ -50,7 +68,7 @@ const MODEL_CONTEXT_LIMITS = {
     'gpt-4-turbo': 128000,
 };
 // Register supporting components when the main component module is imported.
-avoidTreeShaking(AiChatMarkdown, AiChatInteractionWrapper, AiHaloOverlay, AiChatBubble, AiActivityHalo, ChatSuggestions);
+avoidTreeShaking(AiChatMarkdown, AiChatInteractionWrapper, AiHaloOverlay, AiChatBubble, AiActivityHalo, ChatSuggestions, AgentPicker);
 /** Recursively strips `toolHandlers` from an agent and all its sub-agents. */
 function stripHandlers(agent) {
     const { toolHandlers: _, subAgents } = agent, rest = __rest(agent, ["toolHandlers", "subAgents"]);
@@ -107,6 +125,20 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         /** True when the user has intentionally scrolled away from the bottom — suppresses auto-scroll. */
         this._userScrolledAway = false;
         this.showHalo = 'no';
+        this._settingsToggle = new AnimatedPanelToggle(this, '.settings-panel', SETTINGS_CLOSE_MS, () => this.settingsOpen, (v) => {
+            this.settingsOpen = v;
+        });
+        this._agentPickerToggle = new AnimatedPanelToggle(this, '.agent-picker-panel', AGENT_PICKER_CLOSE_MS, () => this.agentPickerOpen, (v) => {
+            this.agentPickerOpen = v;
+        });
+    }
+    /**
+     * Resolved agent picker mode from `chatConfig.picker.mode`. Defaults to
+     * `'disabled'`.
+     */
+    get agentPicker() {
+        var _a, _b;
+        return (_b = (_a = this.chatConfig.picker) === null || _a === void 0 ? void 0 : _a.mode) !== null && _b !== void 0 ? _b : 'disabled';
     }
     get messages() {
         var _a, _b;
@@ -208,6 +240,41 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         var _a;
         (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.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() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.agentPickerOpen) !== null && _b !== void 0 ? _b : false;
+    }
+    set agentPickerOpen(value) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.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() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.pinnedAgentName) !== null && _b !== void 0 ? _b : null;
+    }
+    set pinnedAgentName(value) {
+        var _a, _b, _c;
+        const previous = (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.pinnedAgentName) !== null && _b !== void 0 ? _b : null;
+        (_c = this._sessionRef) === null || _c === void 0 ? void 0 : _c.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() {
         var _a, _b;
         return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.liveSubAgentTrace) !== null && _b !== void 0 ? _b : [];
@@ -224,6 +291,29 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         var _a;
         (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setLiveSubAgentName(value);
     }
+    /**
+     * In-flight per-call chat-input overrides pushed by `requestSubAgent`
+     * invocations. Empty means no override is active.
+     */
+    get subAgentInputOverrides() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.subAgentInputOverrides) !== null && _b !== void 0 ? _b : [];
+    }
+    /**
+     * 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'`.
+     */
+    get effectiveChatInputDuringExecution() {
+        var _a, _b;
+        const overrides = this.subAgentInputOverrides;
+        if (overrides.some((o) => o.mode === 'hidden'))
+            return 'hidden';
+        if (overrides.some((o) => o.mode === 'disabled'))
+            return 'disabled';
+        return (_b = (_a = this.activeAgent) === null || _a === void 0 ? void 0 : _a.chatInputDuringExecution) !== null && _b !== void 0 ? _b : 'disabled';
+    }
     /** Most recent prompt token count from the AI provider, if available. */
     get contextTokens() {
         var _a;
@@ -418,18 +508,38 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             // driver's own history array (which is still being mutated by the tool loop).
             this.liveSubAgentTrace = structuredClone(history);
         };
-        const onSubAgentStop = () => {
+        const onSubAgentStart = (e) => {
+            var _a;
+            const { invocationId, chatInputDuringExecution } = e.detail;
+            if (!chatInputDuringExecution)
+                return;
+            (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.addSubAgentInputOverride({
+                id: invocationId,
+                mode: chatInputDuringExecution,
+            });
+        };
+        const onSubAgentStop = (e) => {
+            var _a;
             this.liveSubAgentTrace = [];
             this.liveSubAgentName = null;
+            const { invocationId } = e.detail;
+            if (invocationId) {
+                (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.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 = [
             () => 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';
             };
@@ -460,7 +570,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         this.driverCleanup = undefined;
     }
     connectedCallback() {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c, _d, _e, _f, _g;
         // 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,
@@ -479,6 +589,10 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             this.showAgentSwitchIndicator = ui.showAgentSwitchIndicator === true;
             this.enabledAnimations =
                 (_c = (_b = ui.animations) === null || _b === void 0 ? void 0 : _b.enabled) !== null && _c !== void 0 ? _c : (ui.animations ? [...ALL_ANIMATIONS] : []);
+            const defaultAgent = (_d = this.chatConfig.picker) === null || _d === void 0 ? void 0 : _d.defaultAgent;
+            if (defaultAgent && ((_e = this.agents) !== null && _e !== void 0 ? _e : []).some((a) => a.name === defaultAgent)) {
+                this.pinnedAgentName = defaultAgent;
+            }
         }
         this.driver = getOrCreateDriver(key, () => this.createDriver());
         this._driverAgentsKey = this.getAgentsKey(this.agents);
@@ -501,13 +615,13 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         this.syncShowingSplash();
         // Restore loading state if the driver is still executing mid-lifecycle.
         // disconnectedCallback resets state to 'idle', so we must check real driver state here.
-        if ((_d = this.driver) === null || _d === void 0 ? void 0 : _d.isBusy()) {
+        if ((_f = this.driver) === null || _f === void 0 ? void 0 : _f.isBusy()) {
             this.state = 'loading';
             this.startLoadingTimer();
             // Subscribe once so that when the originating send() completes (possibly on a
             // different element instance that has since disconnected), this element cleans up
             // its own timer, syncs the halo, and triggers the post-response suggestion fetch.
-            this._executionCompletionUnsub = (_e = this._sessionRef) === null || _e === void 0 ? void 0 : _e.subscribeKey((s) => s.aiAssistant.state, () => {
+            this._executionCompletionUnsub = (_g = this._sessionRef) === null || _g === void 0 ? void 0 : _g.subscribeKey((s) => s.aiAssistant.state, () => {
                 var _a, _b;
                 if (((_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.state) === 'idle') {
                     this.stopLoadingTimer();
@@ -556,6 +670,11 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         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;
@@ -691,23 +810,79 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         return parts.length ? parts.join('::') : undefined;
     }
     toggleSettings() {
-        var _a;
-        if (this.settingsOpen) {
-            const panel = (_a = this.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector('.settings-panel');
-            if (panel) {
-                panel.classList.add('closing');
-                panel.addEventListener('animationend', () => {
-                    panel.classList.remove('closing');
-                    this.settingsOpen = false;
-                }, { once: true });
-            }
-            else {
-                this.settingsOpen = false;
-            }
-        }
-        else {
-            this.settingsOpen = true;
+        this._settingsToggle.toggle();
+    }
+    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, options) {
+        var _a, _b, _c;
+        if (!((_a = this.agents) !== null && _a !== void 0 ? _a : []).some((a) => a.name === agentName))
+            return false;
+        const force = (_b = options === null || options === void 0 ? void 0 : options.force) !== null && _b !== void 0 ? _b : true;
+        if (!force) {
+            const defaultAgent = (_c = this.chatConfig.picker) === null || _c === void 0 ? void 0 : _c.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. */
+    get agentPickerEnabled() {
+        var _a, _b, _c;
+        if (this.agentPicker === 'disabled')
+            return false;
+        if (((_b = (_a = this.agents) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) <= 1)
+            return false;
+        return ((_c = this.agents) !== null && _c !== void 0 ? _c : []).some((a) => { var _a; return (_a = a.manualSelection) === null || _a === void 0 ? void 0 : _a.enabled; });
+    }
+    /** Hint text for the currently pinned agent, if any. Used in the toggle button tooltip. */
+    get pinnedAgentHint() {
+        var _a, _b, _c;
+        if (this.pinnedAgentName === null)
+            return undefined;
+        return (_c = (_b = (_a = this.agents) === null || _a === void 0 ? void 0 : _a.find((a) => a.name === this.pinnedAgentName)) === null || _b === void 0 ? void 0 : _b.manualSelection) === null || _c === void 0 ? void 0 : _c.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`.
+     */
+    get pinnedAgentColour() {
+        var _a, _b, _c;
+        if (this.pinnedAgentName === null)
+            return undefined;
+        if ((_a = this.chatConfig.picker) === null || _a === void 0 ? void 0 : _a.disablePinColours)
+            return undefined;
+        const idx = (_c = (_b = this.agents) === null || _b === void 0 ? void 0 : _b.findIndex((a) => a.name === this.pinnedAgentName)) !== null && _c !== void 0 ? _c : -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.
+     */
+    get effectivePlaceholder() {
+        if (this.pinnedAgentName)
+            return `Message ${this.pinnedAgentName}...`;
+        return this.placeholder;
     }
     toggleShowToolCalls() {
         this.showToolCalls = !this.showToolCalls;
@@ -903,6 +1078,10 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             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 === null || pendingAttachments === void 0 ? void 0 : pendingAttachments.length)
@@ -980,6 +1159,9 @@ __decorate([
 __decorate([
     attr({ attribute: 'debug-redux', mode: 'boolean' })
 ], FoundationAiAssistant.prototype, "debugRedux", void 0);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "effectiveChatInputDuringExecution", null);
 __decorate([
     observable
 ], FoundationAiAssistant.prototype, "attachments", void 0);
@@ -1004,6 +1186,18 @@ __decorate([
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "visibleMessages", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "agentPickerEnabled", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "pinnedAgentHint", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "pinnedAgentColour", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "effectivePlaceholder", null);
 FoundationAiAssistant = FoundationAiAssistant_1 = __decorate([
     customElement({
         name: 'foundation-ai-assistant',

package/dist/esm/main/main.styles.js

@@ -516,10 +516,69 @@ export const styles = css `
     background-color: var(--neutral-layer-2);
   }
 
+  .input-left-controls {
+    display: flex;
+    flex-direction: column;
+    align-items: stretch;
+    gap: calc(var(--design-unit) * 1px);
+  }
+
+  /* Lock the width so the column doesn't reflow when the button content
+     switches between the "Auto" label, the pin icon, and the chevron. */
+  .agent-toggle-button {
+    width: 56px;
+    min-width: 56px;
+    max-width: 56px;
+    box-sizing: border-box;
+  }
+
+  .agent-toggle-label {
+    font-size: 0.75em;
+    font-weight: 600;
+    letter-spacing: 0.02em;
+  }
+
+  @keyframes agent-picker-slide-in {
+    from {
+      opacity: 0%;
+      transform: translateY(8px);
+    }
+
+    to {
+      opacity: 100%;
+      transform: translateY(0);
+    }
+  }
+
+  @keyframes agent-picker-slide-out {
+    from {
+      opacity: 100%;
+      transform: translateY(0);
+    }
+
+    to {
+      opacity: 0%;
+      transform: translateY(8px);
+    }
+  }
+
+  .agent-picker-panel {
+    animation: agent-picker-slide-in 0.2s ease-out;
+    overflow: hidden;
+  }
+
+  .agent-picker-panel.closing {
+    animation: agent-picker-slide-out 0.2s ease-in forwards;
+  }
+
   .chat-input {
     flex: 1;
     resize: none;
     max-height: 150px;
+
+    /* Match the height of the left-controls column when it has stacked buttons,
+       so the textarea fills the row instead of sitting flush to the send button. */
+    align-self: stretch;
   }
 
   .file-input {