@datalayer/agent-runtimes 1.0.9 → 1.0.17

package/lib/chat/base/ChatBase.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 /*
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
@@ -16,9 +16,12 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  * @module chat/base/ChatBase
  */
 import { useContext } from 'react';
-import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
-import { Text, Spinner } from '@primer/react';
-import { Box, setupPrimerPortals, useThemeStore, getColorPalette, } from '@datalayer/primer-addons';
+import React, { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+import { Text, Spinner, IconButton } from '@primer/react';
+import { SkeletonText } from '@primer/react/experimental';
+import { SidebarExpandIcon } from '@primer/octicons-react';
+import { notebookStore, JupyterReactTheme } from '@datalayer/jupyter-react';
+import { Box, setupPrimerPortals, useThemeStore, getColorPalette, getThemeConfig, useSystemColorMode, } from '@datalayer/primer-addons';
 import { AlertIcon, PersonIcon } from '@primer/octicons-react';
 import { AiAgentIcon } from '@datalayer/icons-react';
 import { QueryClientProvider, QueryClientContext } from '@tanstack/react-query';
@@ -33,13 +36,99 @@ import { useAgentRuntimeWebSocket } from '../../hooks/useAgentRuntimes';
 import { agentRuntimeStore, useAgentRuntimeStore, useAgentRuntimeWsState, } from '../../stores/agentRuntimeStore';
 import { ChatBaseHeader } from '../header/ChatHeaderBase';
 import { ChatEmptyState } from '../display/EmptyState';
+import { FloatingBrandButton } from '../display/FloatingBrandButton';
 import { PoweredByTag } from '../display/PoweredByTag';
 import { ChatMessageList, } from '../messages/ChatMessageList';
 import { InputToolbar } from '../prompt/InputFooter';
 import { ToolApprovalBanner, ToolApprovalDialog, } from '../tools';
+import { EphemeralNotebook } from '../notebook/EphemeralNotebook';
+// EphemeralDocument statically imports `@datalayer/jupyter-lexical` (which
+// initialises Lumino-backed nodes on load). Lazy-load it so notebook-only chats
+// never pull lexical into the bundle or trigger its module side effects.
+const EphemeralDocument = React.lazy(() => import('../document/EphemeralDocument').then(m => ({
+    default: m.EphemeralDocument,
+})));
+import { useNotebookTools } from '../../tools/adapters/agent-runtimes/notebookHooks';
 // Tracks pending prompts already auto-sent for a given conversation scope.
 // This prevents layout-driven unmount/remount cycles from re-sending prompts.
 const sentPendingPromptKeys = new Set();
+/**
+ * Inline skeleton placeholder rendered inside the companion surface (notebook
+ * or document) while the agent runtime is still launching and the real
+ * ephemeral notebook/document is not yet ready. Shown in place of the surface
+ * content (never as an overlay) so structure appears as early as possible.
+ */
+function CompanionSurfaceSkeleton({ mode }) {
+    return (_jsx(Box, { "aria-label": mode === 'notebook' ? 'Preparing notebook…' : 'Preparing document…', sx: {
+            flex: 1,
+            minHeight: 0,
+            overflow: 'hidden',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 3,
+            p: 4,
+        }, children: mode === 'notebook' ? (_jsx(_Fragment, { children: [0, 1, 2].map(i => (_jsxs(Box, { sx: {
+                    p: 3,
+                    border: '1px solid',
+                    borderColor: 'border.muted',
+                    borderRadius: 2,
+                    bg: 'canvas.subtle',
+                    display: 'flex',
+                    flexDirection: 'column',
+                    gap: 2,
+                }, children: [_jsx(SkeletonText, { lines: 1 }), _jsx(SkeletonText, { lines: i === 0 ? 2 : 3 })] }, i))) })) : (_jsxs(Box, { sx: {
+                maxWidth: 860,
+                width: '100%',
+                mx: 'auto',
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 3,
+            }, children: [_jsx(SkeletonText, { lines: 1 }), _jsx(SkeletonText, { lines: 4 }), _jsx(SkeletonText, { lines: 3 }), _jsx(SkeletonText, { lines: 5 })] })) }));
+}
+// JupyterReactTheme forwards unknown props (e.g. `style`) to its inner Primer
+// `BaseStyles`. `style` is not part of its typings, so we widen the type here.
+const ThemedJupyterReactTheme = JupyterReactTheme;
+/**
+ * Theme boundary shared by every chat variant.
+ *
+ * Makes the chat follow the active Datalayer theme *variant* (matrix, earth,
+ * …) — its colours AND fonts — not merely the color mode, while keeping the
+ * jupyter-react Primer context required by `KernelIndicator`.
+ *
+ * Implementation notes:
+ * - We deliberately DON'T nest a `DatalayerThemeProvider` here. The host layout
+ *   already provides one, and it themes Primer portals by writing styles onto
+ *   `document.body`. Nesting another (especially one carrying layout styles
+ *   like `display: contents`) clobbers those body/portal styles and breaks
+ *   every overlay menu globally.
+ * - Instead we re-assert the variant's CSS custom properties (`--bgColor-*`,
+ *   `--fgColor-*`, `--fontStack-*`, …) INLINE on `JupyterReactTheme`'s
+ *   `BaseStyles`. Inline styles win over the `@primer/primitives`
+ *   `[data-color-mode]` rules that `JupyterReactTheme` re-scopes, so the chat
+ *   subtree renders in the selected theme (colours + fonts). `JupyterReactTheme`
+ *   also supplies the matching Primer theme object + resolved color mode for
+ *   jupyter-react components.
+ * - `display: contents` keeps the boundary from emitting a layout box (so the
+ *   chat height/flex chain is preserved); CSS custom properties and inherited
+ *   properties (color, font) still cascade through it.
+ */
+function ThemedChatBoundary({ children }) {
+    const colorMode = useThemeStore(s => s.colorMode);
+    const themeVariant = useThemeStore(s => s.theme);
+    const systemMode = useSystemColorMode();
+    const themeConfig = getThemeConfig(themeVariant);
+    const resolvedMode = colorMode === 'auto' ? systemMode : colorMode;
+    const modeStyles = resolvedMode === 'dark'
+        ? themeConfig.themeStyles.dark
+        : themeConfig.themeStyles.light;
+    const themeBackground = modeStyles.backgroundColor ?? '';
+    return (_jsx(ThemedJupyterReactTheme, { colormode: resolvedMode, theme: themeConfig.primerTheme, backgroundColor: themeBackground, loadJupyterLabCss: false, style: {
+            ...modeStyles,
+            color: 'var(--fgColor-default)',
+            fontSize: 'var(--text-body-size-medium)',
+            display: 'contents',
+        }, children: children }));
+}
 const AI_AGENTS_API_PREFIX = '/api/ai-agents/v1';
 const isDevTraceEnabled = () => {
     try {
@@ -203,23 +292,85 @@ function extractChatMessagesFromFullContext(fullContext) {
     return rawMessages
         .map((msg, index) => {
         const role = String(msg.role || '').toLowerCase();
-        // Only hydrate conversational turns in the visible history.
-        // System/tool messages may contain internal prompts and metadata.
-        if (role !== 'user' && role !== 'assistant') {
-            return null;
-        }
         const timestampValue = typeof msg.timestamp === 'string' && msg.timestamp.length > 0
             ? msg.timestamp
             : new Date().toISOString();
-        const createdAt = new Date(timestampValue);
-        const content = typeof msg.content === 'string'
+        const createdAtRaw = new Date(timestampValue);
+        const createdAt = Number.isNaN(createdAtRaw.getTime())
+            ? new Date()
+            : createdAtRaw;
+        const rawContent = typeof msg.content === 'string'
             ? msg.content
             : JSON.stringify(msg.content ?? '');
+        const isToolCall = Boolean(msg.isToolCall);
+        const isToolResult = Boolean(msg.isToolResult);
+        const toolCallId = typeof msg.toolCallId === 'string' && msg.toolCallId.length > 0
+            ? msg.toolCallId
+            : undefined;
+        const toolName = typeof msg.toolName === 'string' && msg.toolName.length > 0
+            ? msg.toolName
+            : undefined;
+        // Tool-call turns arrive as assistant messages whose `content` is the
+        // JSON-encoded tool arguments. Reconstruct a structured `toolCalls`
+        // entry so it renders as a tool card (matching the live stream) instead
+        // of leaking raw JSON into the transcript.
+        if (isToolCall) {
+            let args = {};
+            if (rawContent) {
+                try {
+                    const parsed = JSON.parse(rawContent);
+                    if (parsed &&
+                        typeof parsed === 'object' &&
+                        !Array.isArray(parsed)) {
+                        args = parsed;
+                    }
+                }
+                catch {
+                    args = {};
+                }
+            }
+            const resolvedToolCallId = toolCallId || `history-tc-${index}`;
+            return {
+                id: `history-toolcall-${index}-${timestampValue}`,
+                role: 'assistant',
+                content: '',
+                createdAt,
+                toolCalls: [
+                    {
+                        type: 'tool-call',
+                        toolCallId: resolvedToolCallId,
+                        toolName: toolName || 'tool',
+                        args,
+                        status: 'completed',
+                    },
+                ],
+            };
+        }
+        // Tool results arrive as `role: 'tool'` messages; keep them (with the
+        // matching toolCallId) so `convertHistoryToDisplayItems` can merge the
+        // result into its tool card.
+        if (isToolResult || role === 'tool') {
+            return {
+                id: `history-toolresult-${index}-${timestampValue}`,
+                role: 'tool',
+                content: rawContent,
+                createdAt,
+                metadata: {
+                    toolCallId,
+                    toolName,
+                },
+            };
+        }
+        // Only hydrate conversational turns in the visible history.
+        // System messages may contain internal prompts and metadata.
+        if (role !== 'user' && role !== 'assistant') {
+            return null;
+        }
         return {
             id: `history-${role}-${index}-${timestampValue}`,
             role,
-            content,
-            createdAt: Number.isNaN(createdAt.getTime()) ? new Date() : createdAt,
+            content: rawContent,
+            createdAt,
         };
     })
         .filter((m) => m !== null);
@@ -281,7 +432,7 @@ function parseApprovedMcpToolsByServer(mcpStatusData) {
  * ChatBase component — Universal chat panel supporting store, protocol, and custom modes.
  */
 export function ChatBase(props) {
-    const { agentRuntimeConfig, protocol: protocolProp, useStore: useStoreMode = true, } = props;
+    const { agentRuntimeConfig, protocol: protocolProp, useStore: useStoreMode = true, disableInternalJupyterTheme = false, } = props;
     // Resolve protocol: string Protocol overrides type in agentRuntimeConfig or
     // is combined with a full ProtocolConfig object.
     const protocolType = typeof protocolProp === 'string' ? protocolProp : undefined;
@@ -307,19 +458,21 @@ export function ChatBase(props) {
         protocol: protocol,
         useStore: effectiveUseStoreMode,
     };
+    const content = _jsx(ChatBaseInner, { ...innerProps });
+    const wrappedContent = disableInternalJupyterTheme ? (content) : (_jsx(ThemedChatBoundary, { children: content }));
     if (!existingQueryClient) {
-        return (_jsx(QueryClientProvider, { client: internalQueryClient, children: _jsx(ChatBaseInner, { ...innerProps }) }));
+        return (_jsx(QueryClientProvider, { client: internalQueryClient, children: wrappedContent }));
     }
-    return _jsx(ChatBaseInner, { ...innerProps });
+    return wrappedContent;
 }
 // ---------------------------------------------------------------------------
 // ChatBaseInner — contains all actual logic
 // ---------------------------------------------------------------------------
-function ChatBaseInner({ title, subtitle, showHeader = false, showTokenUsage = true, showLoadingIndicator = true, showErrors = true, showInput = true, showModelSelector = true, showToolsMenu = true, showSkillsMenu = true, disableInputPrompt = false, codemodeEnabled = false, onToggleCodemode, initialModel, availableModels, mcpServers, initialSkills: _initialSkills, className, loadingState, headerActions, kernelIndicatorState, kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, chatViewMode, onChatViewModeChange, 
+function ChatBaseInner({ title, subtitle, showHeader = false, showTokenUsage = true, showLoadingIndicator = true, showErrors = true, showInput = true, showModelSelector = true, showToolsMenu = true, showSkillsMenu = true, disableInputPrompt = false, overlay, launching = false, launchingMessage, autoConnect = true, codemodeEnabled = false, onToggleCodemode, initialModel, availableModels, mcpServers, initialSkills: _initialSkills, className, loadingState, headerActions, kernelIndicatorState, kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, chatViewMode, onChatViewModeChange, 
 // Mode selection
 useStore: useStoreMode = true, protocol: protocolRaw, onSendMessage, enableStreaming = false, 
 // Extended props
-brandIcon, avatarConfig, headerButtons, showPoweredBy = false, poweredByProps, emptyState, renderToolResult, footerContent, showInformation = false, onInformationClick, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact = false, placeholder, description = 'Start a conversation with the AI agent.', onStateUpdate, onNewChat, onClear, onMessagesChange, autoFocus = false, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, focusTrigger, frontendTools, 
+brandIcon, avatarConfig, headerButtons, showPoweredBy = false, poweredByProps, emptyState, renderToolResult, footerContent, showInformation = false, onInformationClick, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact = false, placeholder, description = 'Start a conversation with the AI agent.', onStateUpdate, onNewChat, onClear, onMessagesChange, autoFocus = false, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, focusTrigger, frontendTools: frontendToolsProp, enableEphemeralNotebook = false, initialEphemeralNotebookOpen = true, onEphemeralNotebookOpenChange, enableEphemeralDocument = false, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, 
 // Tool invocation hooks
 onToolCallStart, onToolCallComplete, 
 // Identity/Authorization props
@@ -344,10 +497,114 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     const protocolConfig = typeof protocolRaw === 'object'
         ? protocolRaw
         : undefined;
-    const configuredAiAgentsBaseUrl = useCoreStore((s) => s.configuration?.aiagentsRunUrl);
+    const configuredAiAgentsBaseUrl = useCoreStore((s) => s.configuration?.aiAgentsUrl);
     const activeAgentId = protocolConfig?.agentId || runtimeId;
     const historyScopeId = runtimeId || activeAgentId;
     const aiAgentsAuthToken = protocolConfig?.authToken;
+    // ── Ephemeral notebook (in-memory) ──────────────────────────────────────
+    // A stable notebook id scoped to this chat instance. Must match the id used
+    // by `useNotebookTools` so the agent's notebook tools drive this notebook.
+    const generatedNotebookIdRef = useRef(`ephemeral-notebook-${Math.random().toString(36).slice(2, 10)}`);
+    // Scope the ephemeral notebook to the STABLE runtime identity first (the pod
+    // name / route id that stays constant across navigation), falling back to the
+    // agent id. This keeps the persisted notebook model addressable by the same
+    // key when navigating away from and back to the same runtime page.
+    const notebookScopeId = runtimeId || protocolConfig?.agentId || activeAgentId;
+    const ephemeralNotebookId = notebookScopeId
+        ? `ephemeral-notebook-${notebookScopeId}`
+        : generatedNotebookIdRef.current;
+    const persistedEphemeralNbformat = useAgentRuntimeStore(s => s.getEphemeralNotebookModel(ephemeralNotebookId));
+    const setEphemeralNotebookModel = useAgentRuntimeStore(s => s.setEphemeralNotebookModel);
+    const handleEphemeralNotebookChange = useCallback((model) => {
+        setEphemeralNotebookModel(ephemeralNotebookId, model);
+    }, [ephemeralNotebookId, setEphemeralNotebookModel]);
+    // ── Ephemeral document (in-memory Lexical) ──────────────────────────────
+    // Scoped to the same stable runtime identity as the notebook so the persisted
+    // document survives navigation away from and back to the runtime page.
+    const ephemeralDocumentId = notebookScopeId
+        ? `ephemeral-document-${notebookScopeId}`
+        : `ephemeral-document-${generatedNotebookIdRef.current}`;
+    const persistedEphemeralDocument = useAgentRuntimeStore(s => s.getEphemeralDocumentModel(ephemeralDocumentId));
+    const setEphemeralDocumentModel = useAgentRuntimeStore(s => s.setEphemeralDocumentModel);
+    const handleEphemeralDocumentChange = useCallback((model) => {
+        setEphemeralDocumentModel(ephemeralDocumentId, model);
+    }, [ephemeralDocumentId, setEphemeralDocumentModel]);
+    // ── Companion surface mode (none / notebook / document) ─────────────────
+    const defaultSurfaceMode = initialEphemeralSurfaceMode ??
+        (enableEphemeralNotebook && initialEphemeralNotebookOpen
+            ? 'notebook'
+            : 'none');
+    const [ephemeralSurfaceMode, setEphemeralSurfaceMode] = useState(defaultSurfaceMode);
+    const handleEphemeralSurfaceModeChange = useCallback((mode) => {
+        setEphemeralSurfaceMode(mode);
+        onEphemeralSurfaceModeChange?.(mode);
+        // Back-compat: keep the legacy notebook open-state callback in sync.
+        onEphemeralNotebookOpenChange?.(mode === 'notebook');
+    }, [onEphemeralSurfaceModeChange, onEphemeralNotebookOpenChange]);
+    const notebookVisible = enableEphemeralNotebook && ephemeralSurfaceMode === 'notebook';
+    const documentVisible = enableEphemeralDocument && ephemeralSurfaceMode === 'document';
+    const surfaceVisible = notebookVisible || documentVisible;
+    const surfaceCollapsed = surfaceVisible && collapsed && Boolean(onExpandFromCollapsed);
+    // Track the ephemeral notebook's live kernel connection so the chat header
+    // renders the same rich `KernelIndicator` details (kernel id, client id,
+    // server/ws url, status) as the notebook editor. Without this the header
+    // falls back to the sandbox-status placeholder ("disconnected", "no-kernel").
+    const [notebookKernel, setNotebookKernel] = useState(null);
+    useEffect(() => {
+        if (!notebookVisible) {
+            setNotebookKernel(null);
+            return;
+        }
+        const readKernel = () => {
+            const notebook = notebookStore
+                .getState()
+                .selectNotebook(ephemeralNotebookId);
+            const adapter = notebook?.adapter;
+            return adapter?.kernel ?? null;
+        };
+        const sync = () => {
+            const next = readKernel();
+            setNotebookKernel(prev => (prev?.id === next?.id ? prev : next));
+        };
+        sync();
+        // Poll: the kernel connection appears asynchronously after the notebook
+        // mounts and can change on restart. Also react to store mutations.
+        const intervalId = window.setInterval(sync, 750);
+        const unsubscribe = notebookStore.subscribe(sync);
+        return () => {
+            window.clearInterval(intervalId);
+            unsubscribe();
+        };
+    }, [notebookVisible, ephemeralNotebookId]);
+    // When a companion surface is shown, the chat can be docked as a sidebar
+    // (default) or floated over it, driven by the header view-mode toggle.
+    const surfaceChatFloating = surfaceVisible &&
+        (chatViewMode === 'floating' || chatViewMode === 'floating-small');
+    // Notebook frontend tools are always created (hooks must be unconditional)
+    // but only merged into the tools sent to the agent while the notebook is
+    // visible, so the agent can manipulate the live notebook cells. Document
+    // (lexical) tools are reported upward by the lazily-loaded EphemeralDocument
+    // and merged in while the document is visible.
+    const notebookTools = useNotebookTools(ephemeralNotebookId);
+    const [documentTools, setDocumentTools] = useState([]);
+    const handleDocumentToolsReady = useCallback((tools) => {
+        setDocumentTools(tools);
+    }, []);
+    const frontendTools = useMemo(() => {
+        if (notebookVisible) {
+            return [...(frontendToolsProp || []), ...notebookTools];
+        }
+        if (documentVisible) {
+            return [...(frontendToolsProp || []), ...documentTools];
+        }
+        return frontendToolsProp;
+    }, [
+        notebookVisible,
+        documentVisible,
+        frontendToolsProp,
+        notebookTools,
+        documentTools,
+    ]);
     const aiAgentsBaseUrl = useMemo(() => normalizeAiAgentsBaseUrl(configuredAiAgentsBaseUrl || DEFAULT_SERVICE_URLS.AI_AGENTS), [configuredAiAgentsBaseUrl]);
     const aiAgentsApprovalWsRef = useRef(null);
     const resolvedToolCallSuppressionsRef = useRef(new Map());
@@ -604,6 +861,42 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         requestAiAgentsApprovalHistory,
         sendAiAgentsApprovalDecision,
     ]);
+    const reconcileResolvedApprovalInStore = useCallback((approval) => {
+        const state = agentRuntimeStore.getState();
+        const removalIds = new Set([approval.id]);
+        const hasResolvedToolName = Boolean(approval.tool_name);
+        const resolvedSignature = hasResolvedToolName
+            ? approvalSignature(approval.tool_name, approval.tool_args ?? {})
+            : null;
+        for (const existing of state.approvals) {
+            if (existing.status !== 'pending') {
+                continue;
+            }
+            if (!isApprovalForAgent(existing, activeAgentId)) {
+                continue;
+            }
+            if (existing.id === approval.id) {
+                removalIds.add(existing.id);
+                continue;
+            }
+            if (approval.tool_call_id &&
+                existing.tool_call_id &&
+                existing.tool_call_id === approval.tool_call_id) {
+                removalIds.add(existing.id);
+                continue;
+            }
+            if (!resolvedSignature || !existing.tool_name) {
+                continue;
+            }
+            const existingSignature = approvalSignature(existing.tool_name, existing.tool_args ?? {});
+            if (existingSignature === resolvedSignature) {
+                removalIds.add(existing.id);
+            }
+        }
+        for (const id of removalIds) {
+            state.removeApproval(id);
+        }
+    }, [activeAgentId]);
     // Optional ai-agents bridge for server-mode visibility.
     // This keeps approval synchronization in ChatBase so examples do not need
     // their own approval websocket plumbing.
@@ -702,7 +995,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                         state.upsertApproval(scopedApproval);
                     }
                     else {
-                        state.removeApproval(scopedApproval.id);
+                        reconcileResolvedApprovalInStore(scopedApproval);
                     }
                 }
             }
@@ -730,6 +1023,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         aiAgentsAuthToken,
         activeAgentId,
         isSuppressedPending,
+        reconcileResolvedApprovalInStore,
     ]);
     // The outer ChatBase wrapper always resolves a string Protocol to a full
     // ProtocolConfig (or undefined).  Narrow the type for internal use.
@@ -769,8 +1063,10 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     const historyRetryAttemptsRef = useRef(new Map());
     // Adapter-ready flag — flipped to true once the protocol adapter is initialised
     const [adapterReady, setAdapterReady] = useState(false);
-    // Guard so the pending prompt is sent at most once
-    const pendingPromptSentRef = useRef(false);
+    // Guard so each distinct pending prompt is sent at most once. Stores the
+    // last-sent key (not a boolean) so that changing `pendingPrompt` to a new
+    // value — e.g. re-submitting an interactive surface — triggers a fresh send.
+    const pendingPromptSentRef = useRef(null);
     const pendingPromptKey = pendingPrompt &&
         [
             runtimeId || historyEndpoint || protocol?.endpoint || protocol?.agentId,
@@ -789,8 +1085,13 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     const [_enabledTools, setEnabledTools] = useState([]);
     const wsState = useAgentRuntimeWsState();
     // ---- Data queries ----
-    const configQuery = useConfig(Boolean(protocol?.enableConfigQuery), protocol?.configEndpoint, protocol?.authToken, protocol?.agentId);
-    const skillsQuery = useSkills(Boolean(protocol?.enableConfigQuery) && showSkillsMenu, protocol?.configEndpoint, protocol?.authToken);
+    // Config-derived queries (models, skills, context, sandbox) must only run
+    // once the runtime endpoint exists. `autoConnect` is our single signal for
+    // "endpoint ready", so we gate every config query on it to avoid firing
+    // requests at a not-yet-created runtime during the launch overlay.
+    const configQueriesEnabled = Boolean(protocol?.enableConfigQuery) && autoConnect;
+    const configQuery = useConfig(configQueriesEnabled, protocol?.configEndpoint, protocol?.authToken, protocol?.agentId);
+    const skillsQuery = useSkills(configQueriesEnabled && showSkillsMenu, protocol?.configEndpoint, protocol?.authToken);
     const { enableSkill: wsEnableSkill, disableSkill: wsDisableSkill, approveSkill: wsApproveSkill, unapproveSkill: wsUnapproveSkill, } = useSkillActions(activeAgentId);
     // Optimistic skill-approval overrides so inline approval updates the
     // Skills selector immediately before the next WS snapshot lands.
@@ -858,9 +1159,9 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         });
         return set;
     }, [localSkillApproval, skillsQuery.data]);
-    const contextSnapshotQuery = useContextSnapshot(Boolean(protocol?.enableConfigQuery) && showTokenUsage, protocol?.configEndpoint, protocol?.agentId, protocol?.authToken);
+    const contextSnapshotQuery = useContextSnapshot(configQueriesEnabled && showTokenUsage, protocol?.configEndpoint, protocol?.agentId, protocol?.authToken);
     const agentUsage = externalContextSnapshot ?? contextSnapshotQuery.data;
-    const sandboxStatusQuery = useSandbox(Boolean(protocol?.enableConfigQuery) && showHeader, protocol?.configEndpoint, protocol?.authToken, protocol?.agentId);
+    const sandboxStatusQuery = useSandbox(configQueriesEnabled && showHeader, protocol?.configEndpoint, protocol?.authToken, protocol?.agentId);
     // ---- Refs ----
     const adapterRef = useRef(null);
     const unsubscribeRef = useRef(null);
@@ -964,6 +1265,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                 }
                 return;
             }
+            reconcileResolvedApprovalInStore(payload);
             applyServerApprovalDecision(payload, msg.type === 'tool_approval_approved', payload.note ?? undefined);
         },
     });
@@ -1530,6 +1832,11 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     useEffect(() => {
         if (!protocol)
             return;
+        // Skip opening a protocol connection when auto-connect is disabled (e.g.
+        // the runtime endpoint is still being created). The chat shell, companion
+        // surface and launching overlay still render; we simply do not connect.
+        if (!autoConnect)
+            return;
         const adapter = createProtocolAdapter(protocol);
         if (!adapter)
             return;
@@ -1887,7 +2194,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             adapterRef.current?.disconnect();
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [protocolKey, onStateUpdate, useStoreMode]);
+    }, [protocolKey, onStateUpdate, useStoreMode, autoConnect]);
     // Helper to run a frontend tool and send result back via adapter
     function executeFrontendTool(toolHandler, toolCallMsg, toolCallId) {
         (async () => {
@@ -2101,17 +2408,21 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     ]);
     // Send pending prompt once history loaded and adapter/handler available
     useEffect(() => {
-        if (!pendingPrompt || pendingPromptSentRef.current)
+        if (!pendingPrompt)
             return;
+        // Already handled this exact prompt in the current component instance.
+        if (pendingPromptKey && pendingPromptSentRef.current === pendingPromptKey) {
+            return;
+        }
         if (pendingPromptKey && sentPendingPromptKeys.has(pendingPromptKey)) {
-            pendingPromptSentRef.current = true;
+            pendingPromptSentRef.current = pendingPromptKey;
             return;
         }
         if (!historyLoaded)
             return;
         if (!adapterReady && !onSendMessage)
             return;
-        pendingPromptSentRef.current = true;
+        pendingPromptSentRef.current = pendingPromptKey ?? null;
         if (pendingPromptKey) {
             sentPendingPromptKeys.add(pendingPromptKey);
         }
@@ -2495,10 +2806,33 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         protocol.enableConfigQuery === false ||
         !!configQuery.data ||
         !!skillsQuery.data;
+    const resolvedDescription = description || configQuery.data?.welcomeMessage || '';
+    const serverSuggestions = configQuery.data?.suggestions;
+    const resolvedSuggestions = suggestions && suggestions.length > 0
+        ? suggestions
+        : Array.isArray(serverSuggestions) && serverSuggestions.length > 0
+            ? serverSuggestions
+                .map(item => String(item || '').trim())
+                .filter(Boolean)
+                .map(item => ({ title: item, message: item }))
+            : undefined;
+    const messagesContent = children ? (children) : (_jsx(Box, { sx: {
+            display: 'flex',
+            flexDirection: 'column',
+            minHeight: 0,
+            bg: 'canvas.default',
+        }, children: _jsx(ChatMessageList, { displayItems: displayItems, isLoading: isLoading, isStreaming: isStreaming, showLoadingIndicator: showLoadingIndicator, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: defaultAvatarConfig, padding: padding, renderToolResult: renderToolResult, approvalConfig: approvalConfig, messagesEndRef: messagesEndRef, onRespond: handleRespond, emptyContent: launching ? null : (_jsx(ChatEmptyState, { emptyState: emptyState, brandIcon: brandIcon, description: resolvedDescription, suggestions: resolvedSuggestions, submitOnSuggestionClick: submitOnSuggestionClick, onSuggestionSubmit: handleSuggestionSubmit, onSuggestionFill: handleSuggestionFill })) }) }));
+    const inputToolbar = showInput ? (_jsx(InputToolbar, { input: input, setInput: setInput, isLoading: isLoading, kernelStatus: liveKernelStatus, connectionConfirmed: connectionConfirmed, placeholder: placeholder, autoFocus: autoFocus, focusTrigger: focusTrigger, padding: padding, onSend: () => handleSend(), onStop: handleStop, disableInputPrompt: disableInputPrompt || !!overlay || launching, showTokenUsage: showTokenUsage, agentUsage: agentUsage, showModelSelector: showModelSelector, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, codemodeEnabled: codemodeEnabled, onToggleCodemode: onToggleCodemode, isA2AProtocol: isA2AProtocol, hasConfigData: !!configQuery.data, hasSkillsData: !!skillsQuery.data, models: availableModels || configQuery.data?.models || [], selectedModel: selectedModel, onModelSelect: setSelectedModel, availableTools: configQuery.data?.builtinTools || [], mcpServers: filteredMcpServers, enabledMcpTools: enabledMcpTools, enabledMcpToolCount: getEnabledMcpToolNames().length, onToggleMcpTool: toggleMcpTool, onToggleAllMcpServerTools: toggleAllMcpServerTools, approvedMcpTools: approvedMcpTools, onToggleMcpToolApproval: toggleMcpToolApproval, skills: skillsQuery.data?.skills || [], skillsLoading: !!skillsQuery.isLoading, enabledSkills: enabledSkills, onToggleSkill: toggleSkill, onToggleAllSkills: toggleAllSkills, approvedSkills: approvedSkills, onToggleSkillApproval: toggleSkillApproval, apiBase: indicatorApiBase, authToken: protocol?.authToken, mcpStatusData: effectiveMcpStatusData })) : null;
+    // Shared header element. It is rendered either at the top of the chat (when
+    // no ephemeral notebook is shown) or INSIDE the chat body column (when the
+    // notebook is visible) so the header always follows the chat body across all
+    // view modes (docked sidebar, floating popup, floating-small).
+    const chatHeaderElement = showHeader ? (_jsx(ChatBaseHeader, { title: title, subtitle: subtitle, brandIcon: brandIcon, headerContent: headerContent, headerActions: headerActions, showInformation: showInformation, onInformationClick: onInformationClick, padding: padding, kernelIndicatorState: kernelIndicatorState, runtimeStatus: sandboxStatusData ?? sandboxStatusQuery.data, kernel: notebookVisible ? (notebookKernel ?? kernel) : kernel, kernelEnvironmentName: kernelEnvironmentName, kernelCpu: kernelCpu, kernelMemory: kernelMemory, kernelGpu: kernelGpu, headerButtons: headerButtons, messageCount: messages.length, onNewChat: handleNewChat, onClear: handleClear, chatViewMode: chatViewMode, onChatViewModeChange: onChatViewModeChange, showEphemeralSurfaceControl: enableEphemeralNotebook || enableEphemeralDocument, enableEphemeralNotebookOption: enableEphemeralNotebook, enableEphemeralDocumentOption: enableEphemeralDocument, ephemeralSurfaceMode: ephemeralSurfaceMode, onEphemeralSurfaceModeChange: handleEphemeralSurfaceModeChange })) : null;
     // ========================================================================
     // Render
     // ========================================================================
     return (_jsxs(Box, { className: className, sx: {
+            position: 'relative',
             display: 'flex',
             flexDirection: 'column',
             height: '100%',
@@ -2509,7 +2843,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             border,
             boxShadow,
             overflow: 'hidden',
-        }, children: [showHeader && (_jsx(ChatBaseHeader, { title: title, subtitle: subtitle, brandIcon: brandIcon, headerContent: headerContent, headerActions: headerActions, showInformation: showInformation, onInformationClick: onInformationClick, padding: padding, kernelIndicatorState: kernelIndicatorState, runtimeStatus: sandboxStatusData ?? sandboxStatusQuery.data, kernel: kernel, kernelEnvironmentName: kernelEnvironmentName, kernelCpu: kernelCpu, kernelMemory: kernelMemory, kernelGpu: kernelGpu, headerButtons: headerButtons, messageCount: messages.length, onNewChat: handleNewChat, onClear: handleClear, chatViewMode: chatViewMode, onChatViewModeChange: onChatViewModeChange })), showToolApprovalBanner &&
+        }, children: [!surfaceVisible && chatHeaderElement, showToolApprovalBanner &&
                 pendingApprovals &&
                 pendingApprovals.length > 0 && (_jsx(ToolApprovalBannerSection, { pendingApprovals: pendingApprovals, onApprove: handleBannerApprove, onReject: handleBannerReject })), showErrors && error && (_jsxs(Box, { sx: {
                     display: 'flex',
@@ -2519,18 +2853,112 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                     bg: 'danger.subtle',
                     borderBottom: '1px solid',
                     borderColor: 'danger.muted',
-                }, children: [_jsx(AlertIcon, { size: 16 }), _jsx(Text, { sx: { color: 'danger.fg', fontSize: 1 }, children: error.message })] })), _jsx(Box, { ref: messagesContainerRef, sx: {
+                }, children: [_jsx(AlertIcon, { size: 16 }), _jsx(Text, { sx: { color: 'danger.fg', fontSize: 1 }, children: error.message })] })), surfaceVisible ? (_jsxs(Box, { sx: {
                     flex: 1,
-                    flexGrow: 1,
                     minHeight: 0,
+                    display: 'flex',
+                    overflow: 'hidden',
+                    position: 'relative',
+                }, children: [_jsx(Box, { sx: {
+                            flex: 1,
+                            minWidth: 0,
+                            minHeight: 0,
+                            display: 'flex',
+                            flexDirection: 'column',
+                            overflow: 'hidden',
+                            ...(surfaceChatFloating
+                                ? null
+                                : surfaceCollapsed
+                                    ? null
+                                    : {
+                                        borderRight: '1px solid',
+                                        borderColor: 'border.default',
+                                    }),
+                        }, children: launching || overlay ? (_jsx(CompanionSurfaceSkeleton, { mode: notebookVisible ? 'notebook' : 'document' })) : notebookVisible ? (_jsx(EphemeralNotebook, { notebookId: ephemeralNotebookId, runtimePodName: runtimeId || activeAgentId, nbformat: persistedEphemeralNbformat ?? undefined, onNbformatChange: handleEphemeralNotebookChange, toolbarComponent: ephemeralNotebookToolbar })) : (_jsx(React.Suspense, { fallback: null, children: _jsx(EphemeralDocument, { documentId: ephemeralDocumentId, runtimePodName: runtimeId || activeAgentId, content: persistedEphemeralDocument ?? undefined, onContentChange: handleEphemeralDocumentChange, onToolsReady: handleDocumentToolsReady }) })) }), !surfaceCollapsed && (_jsxs(Box, { sx: surfaceChatFloating
+                            ? {
+                                position: 'absolute',
+                                right: 16,
+                                width: chatViewMode === 'floating-small' ? 360 : 440,
+                                maxWidth: 'calc(100% - 32px)',
+                                ...(chatViewMode === 'floating-small'
+                                    ? { bottom: 16, height: '62%' }
+                                    : { top: 16, bottom: 16 }),
+                                display: 'flex',
+                                flexDirection: 'column',
+                                minHeight: 0,
+                                overflow: 'hidden',
+                                bg: 'canvas.default',
+                                border: '1px solid',
+                                borderColor: 'border.default',
+                                borderRadius: 2,
+                                boxShadow: 'shadow.large',
+                                zIndex: 5,
+                            }
+                            : {
+                                flexShrink: 0,
+                                width: 440,
+                                minWidth: 320,
+                                maxWidth: '48%',
+                                minHeight: 0,
+                                display: 'flex',
+                                flexDirection: 'column',
+                                overflow: 'hidden',
+                                bg: 'canvas.default',
+                            }, children: [chatHeaderElement, _jsx(Box, { ref: messagesContainerRef, sx: {
+                                    flex: 1,
+                                    minHeight: 0,
+                                    overflow: 'auto',
+                                    bg: 'canvas.default',
+                                }, children: messagesContent }), footerContent, inputToolbar] })), surfaceCollapsed &&
+                        onExpandFromCollapsed &&
+                        (chatViewMode === 'sidebar' ? (_jsx(Box, { sx: {
+                                position: 'absolute',
+                                top: 8,
+                                right: 8,
+                                zIndex: 6,
+                            }, children: _jsx(IconButton, { icon: SidebarExpandIcon, "aria-label": "Open chat", onClick: onExpandFromCollapsed, variant: "default", size: "small" }) })) : (_jsx(FloatingBrandButton, { isOpen: false, onToggle: onExpandFromCollapsed, position: "bottom-right", tooltip: "Open chat" })))] })) : (_jsxs(_Fragment, { children: [_jsx(Box, { ref: messagesContainerRef, sx: {
+                            flex: 1,
+                            flexGrow: 1,
+                            minHeight: 0,
+                            overflow: 'auto',
+                            bg: 'canvas.default',
+                        }, children: messagesContent }), footerContent, inputToolbar] })), showPoweredBy && _jsx(PoweredByTag, { ...poweredByProps }), overlay && (_jsxs(Box, { sx: {
+                    position: 'absolute',
+                    inset: 0,
+                    zIndex: 20,
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    p: 3,
                     overflow: 'auto',
-                    bg: 'canvas.default',
-                }, children: children ? (children) : (_jsx(Box, { sx: {
-                        display: 'flex',
-                        flexDirection: 'column',
-                        minHeight: 0,
-                        bg: 'canvas.default',
-                    }, children: _jsx(ChatMessageList, { displayItems: displayItems, isLoading: isLoading, isStreaming: isStreaming, showLoadingIndicator: showLoadingIndicator, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: defaultAvatarConfig, padding: padding, renderToolResult: renderToolResult, approvalConfig: approvalConfig, messagesEndRef: messagesEndRef, onRespond: handleRespond, emptyContent: _jsx(ChatEmptyState, { emptyState: emptyState, brandIcon: brandIcon, description: description, suggestions: suggestions, submitOnSuggestionClick: submitOnSuggestionClick, onSuggestionSubmit: handleSuggestionSubmit, onSuggestionFill: handleSuggestionFill }) }) })) }), footerContent, showInput && (_jsx(InputToolbar, { input: input, setInput: setInput, isLoading: isLoading, kernelStatus: liveKernelStatus, connectionConfirmed: connectionConfirmed, placeholder: placeholder, autoFocus: autoFocus, focusTrigger: focusTrigger, padding: padding, onSend: () => handleSend(), onStop: handleStop, disableInputPrompt: disableInputPrompt, showTokenUsage: showTokenUsage, agentUsage: agentUsage, showModelSelector: showModelSelector, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, codemodeEnabled: codemodeEnabled, onToggleCodemode: onToggleCodemode, isA2AProtocol: isA2AProtocol, hasConfigData: !!configQuery.data, hasSkillsData: !!skillsQuery.data, models: availableModels || configQuery.data?.models || [], selectedModel: selectedModel, onModelSelect: setSelectedModel, availableTools: configQuery.data?.builtinTools || [], mcpServers: filteredMcpServers, enabledMcpTools: enabledMcpTools, enabledMcpToolCount: getEnabledMcpToolNames().length, onToggleMcpTool: toggleMcpTool, onToggleAllMcpServerTools: toggleAllMcpServerTools, approvedMcpTools: approvedMcpTools, onToggleMcpToolApproval: toggleMcpToolApproval, skills: skillsQuery.data?.skills || [], skillsLoading: !!skillsQuery.isLoading, enabledSkills: enabledSkills, onToggleSkill: toggleSkill, onToggleAllSkills: toggleAllSkills, approvedSkills: approvedSkills, onToggleSkillApproval: toggleSkillApproval, apiBase: indicatorApiBase, authToken: protocol?.authToken, mcpStatusData: effectiveMcpStatusData })), showPoweredBy && _jsx(PoweredByTag, { ...poweredByProps })] }));
+                }, children: [_jsx(Box, { "aria-hidden": true, sx: {
+                            position: 'absolute',
+                            inset: 0,
+                            bg: 'canvas.default',
+                            opacity: 0.4,
+                            backdropFilter: 'blur(1px)',
+                        } }), _jsx(Box, { sx: { position: 'relative', zIndex: 1, maxWidth: '100%' }, children: overlay })] })), launching && !overlay && (_jsxs(Box, { sx: {
+                    position: 'absolute',
+                    inset: 0,
+                    zIndex: 15,
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    p: 3,
+                }, children: [_jsx(Box, { "aria-hidden": true, sx: {
+                            position: 'absolute',
+                            inset: 0,
+                            bg: 'canvas.default',
+                            opacity: 0.35,
+                            backdropFilter: 'blur(1px)',
+                        } }), _jsxs(Box, { sx: {
+                            position: 'relative',
+                            zIndex: 1,
+                            display: 'flex',
+                            flexDirection: 'column',
+                            alignItems: 'center',
+                            gap: 3,
+                        }, children: [_jsx(Spinner, { size: "large" }), _jsx(Text, { sx: { color: 'fg.muted' }, children: launchingMessage || 'Launching your agent…' })] })] }))] }));
 }
 /**
  * Internal component rendering the top-of-chat approval banner + review dialog.