@genesislcap/ai-assistant 14.431.0 → 14.432.0

package/dist/ai-assistant.api.json

@@ -963,7 +963,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/ai-assistant!AiChatWidget:interface",
-          "docComment": "/**\n * Interface that AI inline interaction components can implement. The `AiChatInteractionWrapper` always sets `data` and `resolved` on the rendered element.\n *\n * @beta\n */\n",
+          "docComment": "/**\n * Interface that AI inline interaction components can implement. The `AiChatInteractionWrapper` always sets `data`, `resolved`, and `shouldAutoFocus` on the rendered element.\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -1033,6 +1033,33 @@
                 "startIndex": 1,
                 "endIndex": 3
               }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AiChatWidget#shouldAutoFocus:member",
+              "docComment": "/**\n * True when the widget is being mounted fresh and the assistant currently has the user's engagement (last pointer/focus interaction was inside the assistant). Widgets with input fields should use this to decide whether to call `.focus()` on mount. False when: - the user has interacted with something outside the assistant, or - this widget has already been resolved (we're re-rendering history due to a layout-lifecycle remount, dock/undock, etc.).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "shouldAutoFocus?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "shouldAutoFocus",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
             }
           ],
           "extendsTokenRanges": []
@@ -2638,6 +2665,32 @@
             "endIndex": 7
           }
         },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/ai-assistant!ChatInputDuringExecutionMode:type",
+          "docComment": "/**\n * Controls how the main chat input area behaves while this agent is executing (i.e. while `state === 'loading'` — covers both LLM thinking and pending widget interactions).\n *\n * - `'disabled'` (default): input stays visible but disabled. - `'hidden'`: the entire input row (attach button, textarea, send button) is hidden. Useful for agents whose interaction widgets contain their own input affordances and where a second disabled chat input is redundant or confusing — typically long-running agents (planners) where one transition in/out is less jarring than mid-run flicker.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type ChatInputDuringExecutionMode = "
+            },
+            {
+              "kind": "Content",
+              "text": "'disabled' | 'hidden'"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/config/config.ts",
+          "releaseTag": "Beta",
+          "name": "ChatInputDuringExecutionMode",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "Function",
           "canonicalReference": "@genesislcap/ai-assistant!createToolFold:function(1)",
@@ -3229,6 +3282,37 @@
               "isAbstract": false,
               "name": "chatConfigChanged"
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#chatInputEl:member",
+              "docComment": "/**\n * Bound to the rapid-text-area chat input via the template ref.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "chatInputEl?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HTMLElement",
+                  "canonicalReference": "!HTMLElement:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "chatInputEl",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#connectedCallback:member(1)",
@@ -3563,7 +3647,16 @@
                 },
                 {
                   "kind": "Content",
-                  "text": "[];\n            } | {\n                toolDefinitions: import(\"../utils/tool-fold\")."
+                  "text": "[];\n                chatInputDuringExecution?: import(\"../config/config\")."
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ChatInputDuringExecutionMode",
+                  "canonicalReference": "@genesislcap/ai-assistant!ChatInputDuringExecutionMode:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";\n            } | {\n                toolDefinitions: import(\"../utils/tool-fold\")."
                 },
                 {
                   "kind": "Reference",
@@ -3590,7 +3683,16 @@
                 },
                 {
                   "kind": "Content",
-                  "text": "[];\n            })[];\n            activeSystemPrompt: string;\n            activePrimerHistory: "
+                  "text": "[];\n                chatInputDuringExecution?: import(\"../config/config\")."
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ChatInputDuringExecutionMode",
+                  "canonicalReference": "@genesislcap/ai-assistant!ChatInputDuringExecutionMode:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";\n            })[];\n            activeSystemPrompt: string;\n            activePrimerHistory: "
                 },
                 {
                   "kind": "Reference",
@@ -3609,7 +3711,7 @@
               "isStatic": false,
               "returnTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 18
+                "endIndex": 22
               },
               "releaseTag": "Beta",
               "isProtected": false,
@@ -3947,6 +4049,36 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#isEngaged:member",
+              "docComment": "/**\n * True when the user's last interaction (pointer or keyboard focus) was inside the assistant. Defaults to true so the assistant claims focus on first mount. Auto-focus features (chat input on idle, widget inputs on mount) gate on this to avoid stealing focus from elsewhere on the page.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "isEngaged: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "isEngaged",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#liveSubAgentName:member",

package/dist/ai-assistant.d.ts

@@ -159,7 +159,8 @@ export declare class AiChatMarkdown extends GenesisElement {
 
 /**
  * Interface that AI inline interaction components can implement.
- * The `AiChatInteractionWrapper` always sets `data` and `resolved` on the rendered element.
+ * The `AiChatInteractionWrapper` always sets `data`, `resolved`, and
+ * `shouldAutoFocus` on the rendered element.
  *
  * @beta
  */
@@ -167,6 +168,16 @@ export declare interface AiChatWidget {
     data: unknown;
     /** The result when the interaction has been resolved. Truthy = resolved; value contains status/payload for display. */
     resolved?: InteractionResult<unknown>;
+    /**
+     * True when the widget is being mounted fresh and the assistant currently has
+     * the user's engagement (last pointer/focus interaction was inside the
+     * assistant). Widgets with input fields should use this to decide whether to
+     * call `.focus()` on mount. False when:
+     *   - the user has interacted with something outside the assistant, or
+     *   - this widget has already been resolved (we're re-rendering history due
+     *     to a layout-lifecycle remount, dock/undock, etc.).
+     */
+    shouldAutoFocus?: boolean;
 }
 
 /**
@@ -294,6 +305,11 @@ declare interface BaseAgentConfig {
      * Sub-agents available to this agent's tool handlers via `requestSubAgent`.
      */
     subAgents?: AgentConfig[];
+    /**
+     * How the main chat input area behaves while this agent is executing.
+     * Defaults to `'disabled'`. See {@link ChatInputDuringExecutionMode}.
+     */
+    chatInputDuringExecution?: ChatInputDuringExecutionMode;
 }
 
 /**
@@ -433,6 +449,22 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
  */
 export declare type ChatHistoryUpdatedEvent = CustomEvent<ReadonlyArray<ChatMessage>>;
 
+/**
+ * Controls how the main chat input area behaves while this agent is executing
+ * (i.e. while `state === 'loading'` — covers both LLM thinking and pending
+ * widget interactions).
+ *
+ * - `'disabled'` (default): input stays visible but disabled.
+ * - `'hidden'`: the entire input row (attach button, textarea, send button) is
+ *   hidden. Useful for agents whose interaction widgets contain their own
+ *   input affordances and where a second disabled chat input is redundant or
+ *   confusing — typically long-running agents (planners) where one transition
+ *   in/out is less jarring than mid-run flicker.
+ *
+ * @beta
+ */
+export declare type ChatInputDuringExecutionMode = 'disabled' | 'hidden';
+
 /**
  * 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.
@@ -581,6 +613,16 @@ export declare class FoundationAiAssistant extends GenesisElement {
     set messages(value: ChatMessage[]);
     get state(): AiAssistantState;
     set state(value: AiAssistantState);
+    /**
+     * Focus the main chat input if the user is still engaged with the assistant.
+     * Deferred to the next frame so any conditional re-render (e.g. unhiding the
+     * input row when an agent's `chatInputDuringExecution: 'hidden'` execution
+     * ends) has committed before we call `.focus()`.
+     *
+     * `rapid-text-area` does not delegate focus to its inner native `<textarea>`,
+     * so we drill into its shadow root and focus the textarea directly.
+     */
+    private maybeAutoFocusChatInput;
     get activeAgent(): Omit<AgentConfig, 'toolHandlers'> | undefined;
     set activeAgent(value: AgentConfig | undefined);
     get suggestionsState(): SuggestionsState;
@@ -627,6 +669,16 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private _driverAgentsKey?;
     /** Bound to the messages container via the template ref — assigned by FAST before connectedCallback logic runs. */
     messagesEl?: HTMLElement;
+    /** Bound to the rapid-text-area chat input via the template ref. */
+    chatInputEl?: HTMLElement;
+    /**
+     * True when the user's last interaction (pointer or keyboard focus) was inside
+     * the assistant. Defaults to true so the assistant claims focus on first mount.
+     * Auto-focus features (chat input on idle, widget inputs on mount) gate on this
+     * to avoid stealing focus from elsewhere on the page.
+     */
+    isEngaged: boolean;
+    private _handleGlobalInteraction;
     /** True when the user has intentionally scrolled away from the bottom — suppresses auto-scroll. */
     private _userScrolledAway;
     private _scrollListener?;
@@ -718,6 +770,7 @@ export declare class FoundationAiAssistant extends GenesisElement {
                 systemPrompt?: string;
                 primerHistory?: ChatMessage[];
                 subAgents?: AgentConfig[];
+                chatInputDuringExecution?: ChatInputDuringExecutionMode;
             } | {
                 toolDefinitions: ToolTreeNode[];
                 toolHandlers: any;
@@ -727,6 +780,7 @@ export declare class FoundationAiAssistant extends GenesisElement {
                 systemPrompt?: string;
                 primerHistory?: ChatMessage[];
                 subAgents?: AgentConfig[];
+                chatInputDuringExecution?: ChatInputDuringExecutionMode;
             })[];
             activeSystemPrompt: string;
             activePrimerHistory: ChatMessage[];
@@ -746,7 +800,6 @@ export declare class FoundationAiAssistant extends GenesisElement {
     handleSuggestionClick(suggestion: string): void;
     private fetchSuggestions;
     private send;
-    private restoreFocusIfAppropriate;
     onChatHeaderMouseDown(e: MouseEvent): void;
     handleInteractionCompleted(e: Event): void;
 }

package/dist/dts/components/chat-interaction-wrapper/chat-interaction-wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat-interaction-wrapper.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAiB,cAAc,EAAc,MAAM,uBAAuB,CAAC;AAKlF,MAAM,MAAM,wBAAwB,GAAG;IACrC,uBAAuB,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACjF,CAAC;AAEF;;;;;GAKG;AACH,qBAKa,wBAAyB,SAAQ,cAAc;IAC1D,gBAAgB;IACJ,aAAa,EAAE,MAAM,CAAM;IACvC,gBAAgB;IACJ,IAAI,EAAE,GAAG,CAAC;IACtB,gBAAgB;IACJ,aAAa,EAAE,MAAM,CAAM;IACvC,6GAA6G;IACjG,QAAQ,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,SAAS,CAAa;IAEzE,gBAAgB;IAChB,SAAS,EAAG,WAAW,CAAC;IAExB,iBAAiB;IAKjB,oBAAoB;IAIpB,eAAe;IAOf,OAAO,CAAC,eAAe;CA8CxB"}
+{"version":3,"file":"chat-interaction-wrapper.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAiB,cAAc,EAAc,MAAM,uBAAuB,CAAC;AAKlF,MAAM,MAAM,wBAAwB,GAAG;IACrC,uBAAuB,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACjF,CAAC;AAEF;;;;;GAKG;AACH,qBAKa,wBAAyB,SAAQ,cAAc;IAC1D,gBAAgB;IACJ,aAAa,EAAE,MAAM,CAAM;IACvC,gBAAgB;IACJ,IAAI,EAAE,GAAG,CAAC;IACtB,gBAAgB;IACJ,aAAa,EAAE,MAAM,CAAM;IACvC,6GAA6G;IACjG,QAAQ,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,SAAS,CAAa;IAEzE,gBAAgB;IAChB,SAAS,EAAG,WAAW,CAAC;IAExB,iBAAiB;IAKjB,oBAAoB;IAIpB,eAAe;IAOf,OAAO,CAAC,eAAe;CAoDxB"}

package/dist/dts/config/config.d.ts

@@ -1,4 +1,19 @@
 import type { ChatMessage, ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
+/**
+ * Controls how the main chat input area behaves while this agent is executing
+ * (i.e. while `state === 'loading'` — covers both LLM thinking and pending
+ * widget interactions).
+ *
+ * - `'disabled'` (default): input stays visible but disabled.
+ * - `'hidden'`: the entire input row (attach button, textarea, send button) is
+ *   hidden. Useful for agents whose interaction widgets contain their own
+ *   input affordances and where a second disabled chat input is redundant or
+ *   confusing — typically long-running agents (planners) where one transition
+ *   in/out is less jarring than mid-run flicker.
+ *
+ * @beta
+ */
+export type ChatInputDuringExecutionMode = 'disabled' | 'hidden';
 interface BaseAgentConfig {
     /**
      * Display name shown in the chat header when this agent is active.
@@ -25,6 +40,11 @@ interface BaseAgentConfig {
      * Sub-agents available to this agent's tool handlers via `requestSubAgent`.
      */
     subAgents?: AgentConfig[];
+    /**
+     * How the main chat input area behaves while this agent is executing.
+     * Defaults to `'disabled'`. See {@link ChatInputDuringExecutionMode}.
+     */
+    chatInputDuringExecution?: ChatInputDuringExecutionMode;
 }
 /**
  * Configuration for a specialist agent.

package/dist/dts/config/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/config/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEpG,UAAU,eAAe;IACvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACvC;;OAEG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;OAGG;IACH,aAAa,CAAC,EAAE,WAAW,EAAE,CAAC;IAC9B;;OAEG;IACH,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D;;OAEG;IACH,QAAQ,EAAE,IAAI,CAAC;IACf,WAAW,CAAC,EAAE,KAAK,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,qBAAqB,GAAG,mBAAmB,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,WAAW,CAAC,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAErE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/config/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEpG;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,4BAA4B,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEjE,UAAU,eAAe;IACvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACvC;;OAEG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;OAGG;IACH,aAAa,CAAC,EAAE,WAAW,EAAE,CAAC;IAC9B;;OAEG;IACH,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC;IAC1B;;;OAGG;IACH,wBAAwB,CAAC,EAAE,4BAA4B,CAAC;CACzD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D;;OAEG;IACH,QAAQ,EAAE,IAAI,CAAC;IACf,WAAW,CAAC,EAAE,KAAK,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,qBAAqB,GAAG,mBAAmB,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,WAAW,CAAC,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAErE"}

package/dist/dts/main/main.d.ts

@@ -44,6 +44,16 @@ export declare class FoundationAiAssistant extends GenesisElement {
     set messages(value: ChatMessage[]);
     get state(): AiAssistantState;
     set state(value: AiAssistantState);
+    /**
+     * Focus the main chat input if the user is still engaged with the assistant.
+     * Deferred to the next frame so any conditional re-render (e.g. unhiding the
+     * input row when an agent's `chatInputDuringExecution: 'hidden'` execution
+     * ends) has committed before we call `.focus()`.
+     *
+     * `rapid-text-area` does not delegate focus to its inner native `<textarea>`,
+     * so we drill into its shadow root and focus the textarea directly.
+     */
+    private maybeAutoFocusChatInput;
     get activeAgent(): Omit<AgentConfig, 'toolHandlers'> | undefined;
     set activeAgent(value: AgentConfig | undefined);
     get suggestionsState(): SuggestionsState;
@@ -90,6 +100,16 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private _driverAgentsKey?;
     /** Bound to the messages container via the template ref — assigned by FAST before connectedCallback logic runs. */
     messagesEl?: HTMLElement;
+    /** Bound to the rapid-text-area chat input via the template ref. */
+    chatInputEl?: HTMLElement;
+    /**
+     * True when the user's last interaction (pointer or keyboard focus) was inside
+     * the assistant. Defaults to true so the assistant claims focus on first mount.
+     * Auto-focus features (chat input on idle, widget inputs on mount) gate on this
+     * to avoid stealing focus from elsewhere on the page.
+     */
+    isEngaged: boolean;
+    private _handleGlobalInteraction;
     /** True when the user has intentionally scrolled away from the bottom — suppresses auto-scroll. */
     private _userScrolledAway;
     private _scrollListener?;
@@ -181,6 +201,7 @@ export declare class FoundationAiAssistant extends GenesisElement {
                 systemPrompt?: string;
                 primerHistory?: ChatMessage[];
                 subAgents?: AgentConfig[];
+                chatInputDuringExecution?: import("../config/config").ChatInputDuringExecutionMode;
             } | {
                 toolDefinitions: import("../utils/tool-fold").ToolTreeNode[];
                 toolHandlers: any;
@@ -190,6 +211,7 @@ export declare class FoundationAiAssistant extends GenesisElement {
                 systemPrompt?: string;
                 primerHistory?: ChatMessage[];
                 subAgents?: AgentConfig[];
+                chatInputDuringExecution?: import("../config/config").ChatInputDuringExecutionMode;
             })[];
             activeSystemPrompt: string;
             activePrimerHistory: ChatMessage[];
@@ -209,7 +231,6 @@ export declare class FoundationAiAssistant extends GenesisElement {
     handleSuggestionClick(suggestion: string): void;
     private fetchSuggestions;
     private send;
-    private restoreFocusIfAppropriate;
     onChatHeaderMouseDown(e: MouseEvent): void;
     handleInteractionCompleted(e: Event): void;
 }

package/dist/dts/main/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/main/main.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/main/main.ts"],"names":[],"mappings":"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"}

package/dist/dts/main/main.template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.template.d.ts","sourceRoot":"","sources":["../../../src/main/main.template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAA2B,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAiIpD,gBAAgB;AAChB,eAAO,MAAM,6BAA6B,GACxC,oBAAoB,MAAM,KACzB,YAAY,CAAC,qBAAqB,CA0ZpC,CAAC"}
+{"version":3,"file":"main.template.d.ts","sourceRoot":"","sources":["../../../src/main/main.template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAA2B,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAiIpD,gBAAgB;AAChB,eAAO,MAAM,6BAA6B,GACxC,oBAAoB,MAAM,KACzB,YAAY,CAAC,qBAAqB,CA+ZpC,CAAC"}

package/dist/dts/types/ai-chat-widget.d.ts

@@ -1,7 +1,8 @@
 import type { InteractionResult } from '@genesislcap/foundation-ai';
 /**
  * Interface that AI inline interaction components can implement.
- * The `AiChatInteractionWrapper` always sets `data` and `resolved` on the rendered element.
+ * The `AiChatInteractionWrapper` always sets `data`, `resolved`, and
+ * `shouldAutoFocus` on the rendered element.
  *
  * @beta
  */
@@ -9,5 +10,15 @@ export interface AiChatWidget {
     data: unknown;
     /** The result when the interaction has been resolved. Truthy = resolved; value contains status/payload for display. */
     resolved?: InteractionResult<unknown>;
+    /**
+     * True when the widget is being mounted fresh and the assistant currently has
+     * the user's engagement (last pointer/focus interaction was inside the
+     * assistant). Widgets with input fields should use this to decide whether to
+     * call `.focus()` on mount. False when:
+     *   - the user has interacted with something outside the assistant, or
+     *   - this widget has already been resolved (we're re-rendering history due
+     *     to a layout-lifecycle remount, dock/undock, etc.).
+     */
+    shouldAutoFocus?: boolean;
 }
 //# sourceMappingURL=ai-chat-widget.d.ts.map

package/dist/dts/types/ai-chat-widget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-chat-widget.d.ts","sourceRoot":"","sources":["../../../src/types/ai-chat-widget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,uHAAuH;IACvH,QAAQ,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;CACvC"}
+{"version":3,"file":"ai-chat-widget.d.ts","sourceRoot":"","sources":["../../../src/types/ai-chat-widget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,uHAAuH;IACvH,QAAQ,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACtC;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B"}

package/dist/esm/components/chat-interaction-wrapper/chat-interaction-wrapper.js

@@ -52,6 +52,12 @@ let AiChatInteractionWrapper = class AiChatInteractionWrapper extends GenesisEle
                 element.data = this.data;
             }
             element.resolved = this.resolved;
+            // Pierce the wrapper's shadow boundary to read engagement from the
+            // assistant host. False if the widget is already resolved — re-renders
+            // from history (layout remount, dock/undock) must never steal focus.
+            const root = this.getRootNode();
+            const host = root instanceof ShadowRoot ? root.host : null;
+            element.shouldAutoFocus = !this.resolved && !!(host === null || host === void 0 ? void 0 : host.isEngaged);
             // Handle completion from the inner component.
             // Guard against re-emission if the interaction was already resolved
             // (e.g. auto-resolve components fire on connectedCallback when rendering history).

package/dist/esm/main/main.js

@@ -91,6 +91,19 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         /** Whether the splash overlay is currently showing (no messages and showSplash is enabled). Reflected as a boolean attribute on the host. */
         this.showingSplash = false;
         this.haloStartPublished = false;
+        /**
+         * True when the user's last interaction (pointer or keyboard focus) was inside
+         * the assistant. Defaults to true so the assistant claims focus on first mount.
+         * Auto-focus features (chat input on idle, widget inputs on mount) gate on this
+         * to avoid stealing focus from elsewhere on the page.
+         */
+        this.isEngaged = true;
+        this._handleGlobalInteraction = (e) => {
+            const next = e.composedPath().includes(this);
+            if (next === this.isEngaged)
+                return;
+            this.isEngaged = next;
+        };
         /** True when the user has intentionally scrolled away from the bottom — suppresses auto-scroll. */
         this._userScrolledAway = false;
         this.showHalo = 'no';
@@ -109,9 +122,35 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.state) !== null && _b !== void 0 ? _b : 'idle';
     }
     set state(value) {
-        var _a;
-        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setState(value);
+        var _a, _b;
+        const prev = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.state;
+        (_b = this._sessionRef) === null || _b === void 0 ? void 0 : _b.actions.aiAssistant.setState(value);
         this.syncShowHalo();
+        // When the agent finishes (loading → !loading) the input row reappears (or
+        // becomes enabled) — refocus it so the user can type immediately, but only
+        // if they haven't moved on to something else on the page.
+        if (prev === 'loading' && value !== 'loading') {
+            this.maybeAutoFocusChatInput();
+        }
+    }
+    /**
+     * Focus the main chat input if the user is still engaged with the assistant.
+     * Deferred to the next frame so any conditional re-render (e.g. unhiding the
+     * input row when an agent's `chatInputDuringExecution: 'hidden'` execution
+     * ends) has committed before we call `.focus()`.
+     *
+     * `rapid-text-area` does not delegate focus to its inner native `<textarea>`,
+     * so we drill into its shadow root and focus the textarea directly.
+     */
+    maybeAutoFocusChatInput() {
+        if (!this.isEngaged)
+            return;
+        requestAnimationFrame(() => {
+            var _a, _b, _c;
+            if (!this.isEngaged || !this.isConnected)
+                return;
+            (_c = (_b = (_a = this.chatInputEl) === null || _a === void 0 ? void 0 : _a.shadowRoot) === null || _b === void 0 ? void 0 : _b.querySelector('textarea')) === null || _c === void 0 ? void 0 : _c.focus();
+        });
     }
     get activeAgent() {
         var _a;
@@ -474,6 +513,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                     this.stopLoadingTimer();
                     this.syncShowHalo();
                     this.fetchSuggestions();
+                    this.maybeAutoFocusChatInput();
                     (_b = this._executionCompletionUnsub) === null || _b === void 0 ? void 0 : _b.call(this);
                     this._executionCompletionUnsub = undefined;
                 }
@@ -489,6 +529,14 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             };
             this.messagesEl.addEventListener('scroll', this._scrollListener);
         }
+        // Track whether the user's most recent interaction was inside this assistant.
+        // Capture phase + composedPath() pierces shadow boundaries reliably.
+        document.addEventListener('pointerdown', this._handleGlobalInteraction, true);
+        document.addEventListener('focusin', this._handleGlobalInteraction, true);
+        // Initial focus on mount when idle (skips during a mid-lifecycle reattach
+        // where state is loading and the input may be hidden or disabled).
+        if (this.state !== 'loading')
+            this.maybeAutoFocusChatInput();
         logger.debug('FoundationAiAssistant connected');
     }
     disconnectedCallback() {
@@ -506,6 +554,8 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         }
         this._scrollListener = undefined;
         this._userScrolledAway = false;
+        document.removeEventListener('pointerdown', this._handleGlobalInteraction, true);
+        document.removeEventListener('focusin', this._handleGlobalInteraction, true);
         // Clear local references only — driver and store stay in their registries.
         this.driver = undefined;
         this._sessionRef = undefined;
@@ -869,19 +919,13 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                 capturedSessionRef === null || capturedSessionRef === void 0 ? void 0 : capturedSessionRef.actions.aiAssistant.setState('idle');
                 this.syncShowHalo();
                 this.fetchSuggestions();
-                this.restoreFocusIfAppropriate();
+                // setState was dispatched directly via the captured ref (not via the
+                // state setter) so the setter's auto-focus path doesn't fire here. Call
+                // it explicitly so the chat input refocuses after the run completes.
+                this.maybeAutoFocusChatInput();
             }
         });
     }
-    restoreFocusIfAppropriate() {
-        const active = document.activeElement;
-        if (active !== document.body && active !== this)
-            return;
-        requestAnimationFrame(() => {
-            var _a, _b;
-            (_b = (_a = this.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector('.chat-input')) === null || _b === void 0 ? void 0 : _b.focus();
-        });
-    }
     onChatHeaderMouseDown(e) {
         if (this.popoutMode === 'collapse')
             return;
@@ -951,6 +995,9 @@ __decorate([
 __decorate([
     observable
 ], FoundationAiAssistant.prototype, "showingSplash", void 0);
+__decorate([
+    observable
+], FoundationAiAssistant.prototype, "isEngaged", void 0);
 __decorate([
     observable
 ], FoundationAiAssistant.prototype, "showHalo", void 0);

package/dist/esm/main/main.template.js

@@ -376,33 +376,33 @@ ${(tc) => { var _a; return (((_a = tc.foldPath) === null || _a === void 0 ? void
               `)}
           </div>
         `)}
-
       ${when((x) => { var _a; return ((_a = x.chatConfig.suggestions) === null || _a === void 0 ? void 0 : _a.behavior) !== 'never'; }, html `
           <chat-suggestions
             :state="${(x) => x.suggestionsState}"
             @suggestion-clicked="${(x, c) => x.handleSuggestionClick(c.event.detail)}"
           ></chat-suggestions>
         `)}
-
-      <div class="input-row" part="input-row">
-        ${when((x) => { var _a; return !!((_a = x.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.acceptedFiles); }, html `
-            <${buttonTag}
-              class="attach-button"
-              part="attach-button"
-              appearance="stealth"
-              title=${(x) => { var _a; return `Attach file (${(_a = x.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.acceptedFiles})`; }}
+      ${when((x) => { var _a; return !(x.state === 'loading' && ((_a = x.activeAgent) === null || _a === void 0 ? void 0 : _a.chatInputDuringExecution) === 'hidden'); }, html `
+          <div class="input-row" part="input-row">
+            ${when((x) => { var _a; return !!((_a = x.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.acceptedFiles); }, html `
+                <${buttonTag}
+                  class="attach-button"
+                  part="attach-button"
+                  appearance="stealth"
+                  title=${(x) => { var _a; return `Attach file (${(_a = x.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.acceptedFiles})`; }}
+                  ?disabled=${(x) => x.state === 'loading'}
+                  @click=${(x) => x.triggerFileInput()}
+                ><${iconTag} name="paperclip"></${iconTag}></${buttonTag}>
+              `)}
+            <${textareaTag}
+              ${ref('chatInputEl')}
+              class="chat-input"
+              part="input"
+              placeholder=${(x) => x.placeholder}
+              :value=${(x) => x.inputValue}
               ?disabled=${(x) => x.state === 'loading'}
-              @click=${(x) => x.triggerFileInput()}
-            ><${iconTag} name="paperclip"></${iconTag}></${buttonTag}>
-          `)}
-        <${textareaTag}
-          class="chat-input"
-          part="input"
-          placeholder=${(x) => x.placeholder}
-          :value=${(x) => x.inputValue}
-          ?disabled=${(x) => x.state === 'loading'}
-          @input=${(x, c) => (x.inputValue = c.event.target.value)}
-          @keydown=${(x, c) => {
+              @input=${(x, c) => (x.inputValue = c.event.target.value)}
+              @keydown=${(x, c) => {
         if (c.event.key === 'Enter' &&
             !c.event.shiftKey) {
             c.event.preventDefault();
@@ -411,18 +411,19 @@ ${(tc) => { var _a; return (((_a = tc.foldPath) === null || _a === void 0 ? void
         }
         return true;
     }}
-        ></${textareaTag}>
-        <${buttonTag}
-          class="send-button"
-          part="send-button"
-          ?disabled=${(x) => x.state === 'loading' || (!x.inputValue.trim() && !x.attachments.length)}
-          @click=${(x) => x.handleSendClick()}
-        >Send</${buttonTag}>
-      </div>
+            ></${textareaTag}>
+            <${buttonTag}
+              class="send-button"
+              part="send-button"
+              ?disabled=${(x) => x.state === 'loading' || (!x.inputValue.trim() && !x.attachments.length)}
+              @click=${(x) => x.handleSendClick()}
+            >Send</${buttonTag}>
+          </div>
+        `)}
       <ai-halo-overlay
         part="halo-overlay"
         ?active=${(x) => x.showHalo !== 'no' && x.enabledAnimations.includes('halo')}
-        :speed="${(x) => (x.showHalo === 'orchestrating' ? HALO_SPEED_ORCHESTRATING : HALO_SPEED_DEFAULT)}"
+        :speed="${(x) => x.showHalo === 'orchestrating' ? HALO_SPEED_ORCHESTRATING : HALO_SPEED_DEFAULT}"
         direction="${(x) => (x.showHalo === 'orchestrating' ? 'ccw' : 'cw')}"
         :borderSize="${(x) => (x.showHalo === 'orchestrating' ? 2 : HALO_BORDER_SIZE_DEFAULT)}"
       ></ai-halo-overlay>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "14.431.0",
+  "version": "14.432.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -64,24 +64,24 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.431.0",
-    "@genesislcap/genx": "14.431.0",
-    "@genesislcap/rollup-builder": "14.431.0",
-    "@genesislcap/ts-builder": "14.431.0",
-    "@genesislcap/uvu-playwright-builder": "14.431.0",
-    "@genesislcap/vite-builder": "14.431.0",
-    "@genesislcap/webpack-builder": "14.431.0",
+    "@genesislcap/foundation-testing": "14.432.0",
+    "@genesislcap/genx": "14.432.0",
+    "@genesislcap/rollup-builder": "14.432.0",
+    "@genesislcap/ts-builder": "14.432.0",
+    "@genesislcap/uvu-playwright-builder": "14.432.0",
+    "@genesislcap/vite-builder": "14.432.0",
+    "@genesislcap/webpack-builder": "14.432.0",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "14.431.0",
-    "@genesislcap/foundation-logger": "14.431.0",
-    "@genesislcap/foundation-redux": "14.431.0",
-    "@genesislcap/foundation-ui": "14.431.0",
-    "@genesislcap/foundation-utils": "14.431.0",
-    "@genesislcap/rapid-design-system": "14.431.0",
-    "@genesislcap/web-core": "14.431.0",
+    "@genesislcap/foundation-ai": "14.432.0",
+    "@genesislcap/foundation-logger": "14.432.0",
+    "@genesislcap/foundation-redux": "14.432.0",
+    "@genesislcap/foundation-ui": "14.432.0",
+    "@genesislcap/foundation-utils": "14.432.0",
+    "@genesislcap/rapid-design-system": "14.432.0",
+    "@genesislcap/web-core": "14.432.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -93,5 +93,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "4e523b6a77df321a9c70fcdf7c12a4ffcb98769a"
+  "gitHead": "60d929edef90648c5566f3721748aa7dfada8030"
 }

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

@@ -72,6 +72,12 @@ export class AiChatInteractionWrapper extends GenesisElement {
         element.data = this.data;
       }
       element.resolved = this.resolved;
+      // Pierce the wrapper's shadow boundary to read engagement from the
+      // assistant host. False if the widget is already resolved — re-renders
+      // from history (layout remount, dock/undock) must never steal focus.
+      const root = this.getRootNode();
+      const host = root instanceof ShadowRoot ? (root.host as { isEngaged?: boolean }) : null;
+      element.shouldAutoFocus = !this.resolved && !!host?.isEngaged;
 
       // Handle completion from the inner component.
       // Guard against re-emission if the interaction was already resolved

package/src/config/config.ts

@@ -1,5 +1,21 @@
 import type { ChatMessage, ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
 
+/**
+ * Controls how the main chat input area behaves while this agent is executing
+ * (i.e. while `state === 'loading'` — covers both LLM thinking and pending
+ * widget interactions).
+ *
+ * - `'disabled'` (default): input stays visible but disabled.
+ * - `'hidden'`: the entire input row (attach button, textarea, send button) is
+ *   hidden. Useful for agents whose interaction widgets contain their own
+ *   input affordances and where a second disabled chat input is redundant or
+ *   confusing — typically long-running agents (planners) where one transition
+ *   in/out is less jarring than mid-run flicker.
+ *
+ * @beta
+ */
+export type ChatInputDuringExecutionMode = 'disabled' | 'hidden';
+
 interface BaseAgentConfig {
   /**
    * Display name shown in the chat header when this agent is active.
@@ -26,6 +42,11 @@ interface BaseAgentConfig {
    * Sub-agents available to this agent's tool handlers via `requestSubAgent`.
    */
   subAgents?: AgentConfig[];
+  /**
+   * How the main chat input area behaves while this agent is executing.
+   * Defaults to `'disabled'`. See {@link ChatInputDuringExecutionMode}.
+   */
+  chatInputDuringExecution?: ChatInputDuringExecutionMode;
 }
 
 /**

package/src/main/main.template.ts

@@ -499,7 +499,6 @@ ${(tc) => (tc.foldPath?.length ? `${tc.foldPath.join(' › ')} › ` : '')}<stro
           </div>
         `,
       )}
-
       ${when(
         (x) => x.chatConfig.suggestions?.behavior !== 'never',
         html<FoundationAiAssistant>`
@@ -510,51 +509,57 @@ ${(tc) => (tc.foldPath?.length ? `${tc.foldPath.join(' › ')} › ` : '')}<stro
           ></chat-suggestions>
         `,
       )}
-
-      <div class="input-row" part="input-row">
-        ${when(
-          (x) => !!x.chatConfig.ui?.acceptedFiles,
-          html<FoundationAiAssistant>`
-            <${buttonTag}
-              class="attach-button"
-              part="attach-button"
-              appearance="stealth"
-              title=${(x) => `Attach file (${x.chatConfig.ui?.acceptedFiles})`}
+      ${when(
+        (x) => !(x.state === 'loading' && x.activeAgent?.chatInputDuringExecution === 'hidden'),
+        html<FoundationAiAssistant>`
+          <div class="input-row" part="input-row">
+            ${when(
+              (x) => !!x.chatConfig.ui?.acceptedFiles,
+              html<FoundationAiAssistant>`
+                <${buttonTag}
+                  class="attach-button"
+                  part="attach-button"
+                  appearance="stealth"
+                  title=${(x) => `Attach file (${x.chatConfig.ui?.acceptedFiles})`}
+                  ?disabled=${(x) => x.state === 'loading'}
+                  @click=${(x) => x.triggerFileInput()}
+                ><${iconTag} name="paperclip"></${iconTag}></${buttonTag}>
+              `,
+            )}
+            <${textareaTag}
+              ${ref('chatInputEl')}
+              class="chat-input"
+              part="input"
+              placeholder=${(x) => x.placeholder}
+              :value=${(x) => x.inputValue}
               ?disabled=${(x) => x.state === 'loading'}
-              @click=${(x) => x.triggerFileInput()}
-            ><${iconTag} name="paperclip"></${iconTag}></${buttonTag}>
-          `,
-        )}
-        <${textareaTag}
-          class="chat-input"
-          part="input"
-          placeholder=${(x) => x.placeholder}
-          :value=${(x) => x.inputValue}
-          ?disabled=${(x) => x.state === 'loading'}
-          @input=${(x, c) => (x.inputValue = (c.event.target as any).value)}
-          @keydown=${(x, c) => {
-            if (
-              (c.event as KeyboardEvent).key === 'Enter' &&
-              !(c.event as KeyboardEvent).shiftKey
-            ) {
-              c.event.preventDefault();
-              x.handleSendClick();
-              return false;
-            }
-            return true;
-          }}
-        ></${textareaTag}>
-        <${buttonTag}
-          class="send-button"
-          part="send-button"
-          ?disabled=${(x) => x.state === 'loading' || (!x.inputValue.trim() && !x.attachments.length)}
-          @click=${(x) => x.handleSendClick()}
-        >Send</${buttonTag}>
-      </div>
+              @input=${(x, c) => (x.inputValue = (c.event.target as any).value)}
+              @keydown=${(x, c) => {
+                if (
+                  (c.event as KeyboardEvent).key === 'Enter' &&
+                  !(c.event as KeyboardEvent).shiftKey
+                ) {
+                  c.event.preventDefault();
+                  x.handleSendClick();
+                  return false;
+                }
+                return true;
+              }}
+            ></${textareaTag}>
+            <${buttonTag}
+              class="send-button"
+              part="send-button"
+              ?disabled=${(x) => x.state === 'loading' || (!x.inputValue.trim() && !x.attachments.length)}
+              @click=${(x) => x.handleSendClick()}
+            >Send</${buttonTag}>
+          </div>
+        `,
+      )}
       <ai-halo-overlay
         part="halo-overlay"
         ?active=${(x) => x.showHalo !== 'no' && x.enabledAnimations.includes('halo')}
-        :speed="${(x) => (x.showHalo === 'orchestrating' ? HALO_SPEED_ORCHESTRATING : HALO_SPEED_DEFAULT)}"
+        :speed="${(x) =>
+          x.showHalo === 'orchestrating' ? HALO_SPEED_ORCHESTRATING : HALO_SPEED_DEFAULT}"
         direction="${(x) => (x.showHalo === 'orchestrating' ? 'ccw' : 'cw')}"
         :borderSize="${(x) => (x.showHalo === 'orchestrating' ? 2 : HALO_BORDER_SIZE_DEFAULT)}"
       ></ai-halo-overlay>

package/src/main/main.ts

@@ -145,8 +145,32 @@ export class FoundationAiAssistant extends GenesisElement {
     return this._sessionRef?.store.aiAssistant.state ?? 'idle';
   }
   set state(value: AiAssistantState) {
+    const prev = this._sessionRef?.store.aiAssistant.state;
     this._sessionRef?.actions.aiAssistant.setState(value);
     this.syncShowHalo();
+    // When the agent finishes (loading → !loading) the input row reappears (or
+    // becomes enabled) — refocus it so the user can type immediately, but only
+    // if they haven't moved on to something else on the page.
+    if (prev === 'loading' && value !== 'loading') {
+      this.maybeAutoFocusChatInput();
+    }
+  }
+
+  /**
+   * Focus the main chat input if the user is still engaged with the assistant.
+   * Deferred to the next frame so any conditional re-render (e.g. unhiding the
+   * input row when an agent's `chatInputDuringExecution: 'hidden'` execution
+   * ends) has committed before we call `.focus()`.
+   *
+   * `rapid-text-area` does not delegate focus to its inner native `<textarea>`,
+   * so we drill into its shadow root and focus the textarea directly.
+   */
+  private maybeAutoFocusChatInput() {
+    if (!this.isEngaged) return;
+    requestAnimationFrame(() => {
+      if (!this.isEngaged || !this.isConnected) return;
+      this.chatInputEl?.shadowRoot?.querySelector<HTMLTextAreaElement>('textarea')?.focus();
+    });
   }
 
   get activeAgent(): Omit<AgentConfig, 'toolHandlers'> | undefined {
@@ -257,6 +281,20 @@ export class FoundationAiAssistant extends GenesisElement {
   private _driverAgentsKey?: string;
   /** Bound to the messages container via the template ref — assigned by FAST before connectedCallback logic runs. */
   messagesEl?: HTMLElement;
+  /** Bound to the rapid-text-area chat input via the template ref. */
+  chatInputEl?: HTMLElement;
+  /**
+   * True when the user's last interaction (pointer or keyboard focus) was inside
+   * the assistant. Defaults to true so the assistant claims focus on first mount.
+   * Auto-focus features (chat input on idle, widget inputs on mount) gate on this
+   * to avoid stealing focus from elsewhere on the page.
+   */
+  @observable isEngaged: boolean = true;
+  private _handleGlobalInteraction = (e: Event) => {
+    const next = e.composedPath().includes(this);
+    if (next === this.isEngaged) return;
+    this.isEngaged = next;
+  };
   /** True when the user has intentionally scrolled away from the bottom — suppresses auto-scroll. */
   private _userScrolledAway = false;
   private _scrollListener?: () => void;
@@ -553,6 +591,7 @@ export class FoundationAiAssistant extends GenesisElement {
             this.stopLoadingTimer();
             this.syncShowHalo();
             this.fetchSuggestions();
+            this.maybeAutoFocusChatInput();
             this._executionCompletionUnsub?.();
             this._executionCompletionUnsub = undefined;
           }
@@ -569,6 +608,13 @@ export class FoundationAiAssistant extends GenesisElement {
       };
       this.messagesEl.addEventListener('scroll', this._scrollListener);
     }
+    // Track whether the user's most recent interaction was inside this assistant.
+    // Capture phase + composedPath() pierces shadow boundaries reliably.
+    document.addEventListener('pointerdown', this._handleGlobalInteraction, true);
+    document.addEventListener('focusin', this._handleGlobalInteraction, true);
+    // Initial focus on mount when idle (skips during a mid-lifecycle reattach
+    // where state is loading and the input may be hidden or disabled).
+    if (this.state !== 'loading') this.maybeAutoFocusChatInput();
     logger.debug('FoundationAiAssistant connected');
   }
 
@@ -586,6 +632,8 @@ export class FoundationAiAssistant extends GenesisElement {
     }
     this._scrollListener = undefined;
     this._userScrolledAway = false;
+    document.removeEventListener('pointerdown', this._handleGlobalInteraction, true);
+    document.removeEventListener('focusin', this._handleGlobalInteraction, true);
     // Clear local references only — driver and store stay in their registries.
     this.driver = undefined;
     this._sessionRef = undefined;
@@ -972,18 +1020,13 @@ export class FoundationAiAssistant extends GenesisElement {
       capturedSessionRef?.actions.aiAssistant.setState('idle');
       this.syncShowHalo();
       this.fetchSuggestions();
-      this.restoreFocusIfAppropriate();
+      // setState was dispatched directly via the captured ref (not via the
+      // state setter) so the setter's auto-focus path doesn't fire here. Call
+      // it explicitly so the chat input refocuses after the run completes.
+      this.maybeAutoFocusChatInput();
     }
   }
 
-  private restoreFocusIfAppropriate() {
-    const active = document.activeElement;
-    if (active !== document.body && active !== this) return;
-    requestAnimationFrame(() => {
-      this.shadowRoot?.querySelector<HTMLElement>('.chat-input')?.focus();
-    });
-  }
-
   onChatHeaderMouseDown(e: MouseEvent) {
     if (this.popoutMode === 'collapse') return;
     e.preventDefault();

package/src/types/ai-chat-widget.ts

@@ -2,7 +2,8 @@ import type { InteractionResult } from '@genesislcap/foundation-ai';
 
 /**
  * Interface that AI inline interaction components can implement.
- * The `AiChatInteractionWrapper` always sets `data` and `resolved` on the rendered element.
+ * The `AiChatInteractionWrapper` always sets `data`, `resolved`, and
+ * `shouldAutoFocus` on the rendered element.
  *
  * @beta
  */
@@ -10,4 +11,14 @@ export interface AiChatWidget {
   data: unknown;
   /** The result when the interaction has been resolved. Truthy = resolved; value contains status/payload for display. */
   resolved?: InteractionResult<unknown>;
+  /**
+   * True when the widget is being mounted fresh and the assistant currently has
+   * the user's engagement (last pointer/focus interaction was inside the
+   * assistant). Widgets with input fields should use this to decide whether to
+   * call `.focus()` on mount. False when:
+   *   - the user has interacted with something outside the assistant, or
+   *   - this widget has already been resolved (we're re-rendering history due
+   *     to a layout-lifecycle remount, dock/undock, etc.).
+   */
+  shouldAutoFocus?: boolean;
 }