@datalayer/agent-runtimes 1.0.18 → 1.0.20

package/lib/chat/document/EphemeralDocument.js

@@ -37,9 +37,11 @@ import { ListPlugin } from '@lexical/react/LexicalListPlugin';
 import { CheckListPlugin } from '@lexical/react/LexicalCheckListPlugin';
 import { LinkPlugin } from '@lexical/react/LexicalLinkPlugin';
 import { ServerConnection, ServiceManager } from '@jupyterlab/services';
-import { Box, DatalayerThemeProvider, getThemeConfig, useSystemColorMode, useThemeStore, } from '@datalayer/primer-addons';
+import { DatalayerThemeProvider, getThemeConfig, useSystemColorMode, useThemeStore, } from '@datalayer/primer-addons';
+import { Box, Spinner, Text } from '@primer/react';
 import { JupyterReactTheme, Kernel, disposeServiceManager, } from '@datalayer/jupyter-react';
 import { ComponentPickerMenuPlugin, JupyterCellPlugin, JupyterInputOutputPlugin, DraggableBlockPlugin, ImagesPlugin, ExcalidrawPlugin, TablePlugin, TableCellResizerPlugin, TableActionMenuPlugin, TableHoverActionsV2Plugin, CollapsiblePlugin, HorizontalRulePlugin, EquationsPlugin, YouTubePlugin, AutoLinkPlugin, AutoEmbedPlugin, LexicalConfigProvider, LexicalStatePlugin, FloatingTextFormatToolbarPlugin, CodeActionMenuPlugin, ListMaxIndentLevelPlugin, ToolbarPlugin, ToolbarContext, CommentsProvider, commentTheme, } from '@datalayer/jupyter-lexical';
+import { createWebsocketProvider, LoroCollaborationPlugin, } from '@datalayer/lexical-loro';
 import { editorConfig } from '../../examples/lexical/editorConfig';
 import { useLexicalTools } from '../../tools/adapters/agent-runtimes/lexicalHooks';
 import { useAgentsRuntimes } from '../../hooks/useAgentRuntimes';
@@ -106,7 +108,32 @@ function DocumentToolbar({ setIsLinkEditMode, }) {
 /**
  * Renders an in-memory Lexical document backed by a sandbox kernel.
  */
-export function EphemeralDocument({ documentId, runtimePodName, content, onContentChange, onToolsReady, }) {
+export function EphemeralDocument({ documentId, runtimePodName, runtimeOverride, themeVariant, colorMode, content, onContentChange, onToolsReady, onKernelChange, collaboration, }) {
+    // Real-time collaboration is active only when both a WebSocket endpoint and a
+    // room id are supplied. In that mode the shared Loro CRDT is the single source
+    // of truth: local content-seeding and undo history are disabled so the local
+    // editor never diverges from (or fights) the collaborative document.
+    const isCollaborative = Boolean(collaboration?.websocketUrl && collaboration?.roomId);
+    const collaborationName = collaboration?.identity?.displayName ||
+        collaboration?.identity?.handle ||
+        collaboration?.identity?.userId;
+    const collaborationColor = collaboration?.identity?.color;
+    const collaborationAwarenessData = useMemo(() => ({
+        user: {
+            id: collaboration?.identity?.userId,
+            username: collaboration?.identity?.userId ||
+                collaboration?.identity?.handle ||
+                collaboration?.identity?.displayName,
+            name: collaboration?.identity?.handle ||
+                collaboration?.identity?.displayName,
+            display_name: collaboration?.identity?.displayName ||
+                collaboration?.identity?.handle,
+            initials: collaboration?.identity?.initials,
+            color: collaboration?.identity?.color,
+            avatar_url: collaboration?.identity?.avatarUrl,
+            handle: collaboration?.identity?.handle,
+        },
+    }), [collaboration?.identity]);
     // Capture the restore seed ONCE per documentId so parent re-renders don't
     // remount the composer (which reads `initialConfig` a single time).
     const initialContentRef = useRef(content);
@@ -127,14 +154,38 @@ export function EphemeralDocument({ documentId, runtimePodName, content, onConte
     // Resolve the runtime sandbox strictly by its assigned pod name. There is
     // deliberately NO local fallback kernel: the ephemeral document executes on
     // exactly the runtime assigned to this agent, or shows a waiting state.
-    const { runtimes } = useAgentsRuntimes();
+    const { runtimes, refetchRuntimes } = useAgentsRuntimes();
     const selectedRuntime = useMemo(() => {
+        const overrideBaseUrl = String(runtimeOverride?.baseUrl || '').trim();
+        if (overrideBaseUrl) {
+            return {
+                url: overrideBaseUrl,
+                wsUrl: String(runtimeOverride?.wsUrl || '').trim() || undefined,
+                token: String(runtimeOverride?.token || '').trim(),
+                pod_name: String(runtimeOverride?.podName || '').trim() || 'agent-node-proxy',
+            };
+        }
         const preferredPod = String(runtimePodName || '').trim();
         if (!preferredPod) {
             return undefined;
         }
         return runtimes.find(rt => String(rt?.pod_name || '') === preferredPod);
-    }, [runtimePodName, runtimes]);
+    }, [runtimeOverride, runtimePodName, runtimes]);
+    const needsRuntimeLookup = Boolean(!runtimeOverride?.baseUrl &&
+        String(runtimePodName || '').trim() &&
+        !selectedRuntime);
+    useEffect(() => {
+        if (!needsRuntimeLookup) {
+            return;
+        }
+        void refetchRuntimes();
+        const intervalId = window.setInterval(() => {
+            void refetchRuntimes();
+        }, 1000);
+        return () => {
+            window.clearInterval(intervalId);
+        };
+    }, [needsRuntimeLookup, refetchRuntimes]);
     const [runtimeServiceManager, setRuntimeServiceManager] = useState(null);
     // Kernel started inside the agent runtime sandbox and threaded into the
     // Jupyter cell plugins, mirroring how the document editor wires its kernel.
@@ -154,9 +205,11 @@ export function EphemeralDocument({ documentId, runtimePodName, content, onConte
             }
             try {
                 const token = String(selectedRuntime?.token || '').trim();
+                const wsUrl = String(selectedRuntime?.wsUrl || '').trim() ||
+                    baseUrl.replace(/^http/, 'ws');
                 const serverSettings = ServerConnection.makeSettings({
                     baseUrl,
-                    wsUrl: baseUrl.replace(/^http/, 'ws'),
+                    wsUrl,
                     token,
                     appendToken: true,
                 });
@@ -195,8 +248,19 @@ export function EphemeralDocument({ documentId, runtimePodName, content, onConte
             }
         };
     }, [selectedRuntime?.pod_name, selectedRuntime?.url, selectedRuntime?.token]);
+    // Surface the document's live kernel connection to the parent so the chat
+    // header's kernel indicator reflects the real connected kernel instead of
+    // the "disconnected"/"no-kernel" placeholder while the document is active.
+    useEffect(() => {
+        onKernelChange?.(documentKernel?.connection ?? null);
+        return () => {
+            onKernelChange?.(null);
+        };
+    }, [documentKernel, onKernelChange]);
     const activeServiceManager = runtimeServiceManager;
-    const isRuntimeStarting = Boolean(String(runtimePodName || '').trim() && !activeServiceManager);
+    const isRuntimeStarting = Boolean((String(runtimePodName || '').trim() ||
+        String(runtimeOverride?.baseUrl || '').trim()) &&
+        !activeServiceManager);
     useProgressTask(`ephemeral-document-start-${documentId}`, isRuntimeStarting);
     // Build the initial config once per documentId, without the demo content so
     // the document starts empty and is either restored or filled by the agent.
@@ -232,10 +296,12 @@ export function EphemeralDocument({ documentId, runtimePodName, content, onConte
     // Resolve the active theme/color-mode exactly like the notebook editor so
     // the document honours dark / branded themes instead of always rendering
     // light.
-    const { colorMode, theme: themeVariant } = useThemeStore();
+    const { colorMode: storeColorMode, theme: storeThemeVariant } = useThemeStore();
+    const effectiveColorMode = colorMode ?? storeColorMode;
+    const effectiveThemeVariant = themeVariant ?? storeThemeVariant;
     const systemMode = useSystemColorMode();
-    const themeConfig = getThemeConfig(themeVariant);
-    const resolvedMode = colorMode === 'auto' ? systemMode : colorMode;
+    const themeConfig = getThemeConfig(effectiveThemeVariant);
+    const resolvedMode = effectiveColorMode === 'auto' ? systemMode : effectiveColorMode;
     const modeStyles = resolvedMode === 'dark'
         ? themeConfig.themeStyles.dark
         : themeConfig.themeStyles.light;
@@ -247,24 +313,84 @@ export function EphemeralDocument({ documentId, runtimePodName, content, onConte
             position: 'relative',
             overflow: 'hidden',
             bg: 'canvas.default',
-        }, children: activeServiceManager ? (_jsx(DatalayerThemeProvider, { colorMode: colorMode, theme: themeConfig.primerTheme, themeStyles: themeConfig.themeStyles, children: _jsx(JupyterReactTheme, { colormode: resolvedMode, backgroundColor: themeBackground, children: _jsx(Box, { sx: {
+        }, children: activeServiceManager ? (_jsx(DatalayerThemeProvider, { colorMode: effectiveColorMode, theme: themeConfig.primerTheme, themeStyles: themeConfig.themeStyles, children: _jsx(JupyterReactTheme, { colormode: resolvedMode, backgroundColor: themeBackground, children: _jsx(Box, { sx: {
                         position: 'absolute',
                         inset: 0,
                         display: 'flex',
                         flexDirection: 'column',
-                        overflow: 'auto',
+                        minHeight: 0,
+                        overflow: 'hidden',
                         overscrollBehaviorY: 'contain',
                         padding: 2,
                         '& .editor-shell': {
                             backgroundColor: themeBackground,
                             borderRadius: 2,
+                            display: 'flex',
+                            flexDirection: 'column',
+                            minHeight: 0,
+                            flex: 1,
+                            // The shared lexical stylesheet caps `.editor-shell` at
+                            // `max-width: 1100px; margin: 20px auto`, which leaves the
+                            // ephemeral document narrow and centered. Take the full
+                            // wrapping box width instead (matching the ui LiterateEditor,
+                            // whose root is `.editor-container` with no such cap).
+                            maxWidth: 'none',
+                            width: '100%',
+                            margin: 0,
+                        },
+                        '& .editor-container': {
+                            backgroundColor: themeBackground,
+                            display: 'flex',
+                            flexDirection: 'column',
+                            minHeight: 0,
+                            flex: 1,
+                            width: '100%',
+                            maxWidth: 'none',
+                            margin: 0,
+                        },
+                        '& .editor-inner': {
+                            backgroundColor: themeBackground,
+                            display: 'flex',
+                            flexDirection: 'column',
+                            minHeight: 0,
+                            flex: 1,
+                            width: '100%',
+                            maxWidth: 'none',
+                        },
+                        '& .editor-scroller': {
+                            minHeight: 0,
+                            flex: 1,
+                            overflow: 'auto',
+                            width: '100%',
+                            maxWidth: 'none',
+                        },
+                        '& .editor': {
+                            minHeight: '100%',
+                            width: '100%',
+                            maxWidth: 'none',
+                            margin: 0,
+                        },
+                        '& .editor-input': {
+                            backgroundColor: themeBackground,
+                            width: '100%',
+                            maxWidth: 'none',
+                            margin: 0,
+                        },
+                        '& .ContentEditable__root': {
+                            width: '100%',
+                            maxWidth: 'none',
+                            margin: 0,
                         },
-                        '& .editor-container': { backgroundColor: themeBackground },
-                        '& .editor-inner': { backgroundColor: themeBackground },
-                        '& .editor-input': { backgroundColor: themeBackground },
                         '& [role="toolbar"][aria-label="Editor toolbar"]': {
                             backgroundColor: themeBackground,
                         },
-                    }, children: _jsx(LexicalConfigProvider, { lexicalId: documentId, serviceManager: activeServiceManager, children: _jsx(LexicalComposer, { initialConfig: initialConfig, children: _jsx(CommentsProvider, { children: _jsx(ToolbarContext, { children: _jsxs("div", { className: "editor-shell", children: [_jsx(DocumentToolbar, { setIsLinkEditMode: setIsLinkEditMode }), _jsx("div", { className: "editor-container", children: _jsxs("div", { className: "editor-inner", children: [_jsx(LexicalStatePlugin, {}), _jsx(RichTextPlugin, { contentEditable: _jsx("div", { className: "editor-scroller", children: _jsx("div", { className: "editor", ref: onAnchorRef, children: _jsx(ContentEditable, { className: "editor-input", "aria-label": "Ephemeral document editor" }) }) }), ErrorBoundary: LexicalErrorBoundary }), _jsx(OnChangePlugin, { onChange: handleChange }), _jsx(HistoryPlugin, {}), _jsx(AutoFocusPlugin, {}), _jsx(ListPlugin, {}), _jsx(CheckListPlugin, {}), _jsx(LinkPlugin, {}), _jsx(AutoLinkPlugin, {}), _jsx(ListMaxIndentLevelPlugin, { maxDepth: 7 }), _jsx(MarkdownShortcutPlugin, { transformers: TRANSFORMERS }), _jsx(LoadContentPlugin, { content: initialContent }), _jsx(CodeHighlightPlugin, {}), _jsx(ImagesPlugin, { captionsEnabled: false }), _jsx(ExcalidrawPlugin, {}), _jsx(TablePlugin, {}), _jsx(TableCellResizerPlugin, {}), _jsx(TableActionMenuPlugin, {}), _jsx(TableHoverActionsV2Plugin, {}), _jsx(CollapsiblePlugin, {}), _jsx(HorizontalRulePlugin, {}), _jsx(EquationsPlugin, {}), _jsx(YouTubePlugin, {}), _jsx(AutoEmbedPlugin, {}), _jsx(JupyterCellPlugin, {}), _jsx(ComponentPickerMenuPlugin, { kernel: documentKernel }), _jsx(JupyterInputOutputPlugin, { kernel: documentKernel }), floatingAnchorElem && (_jsxs(_Fragment, { children: [_jsx(DraggableBlockPlugin, { anchorElem: floatingAnchorElem }), _jsx(FloatingTextFormatToolbarPlugin, { anchorElem: floatingAnchorElem, setIsLinkEditMode: setIsLinkEditMode }), _jsx(CodeActionMenuPlugin, { anchorElem: floatingAnchorElem })] }))] }) })] }) }) }) }) }) }) }) })) : null }));
+                    }, children: _jsx(LexicalConfigProvider, { lexicalId: documentId, serviceManager: activeServiceManager, children: _jsx(LexicalComposer, { initialConfig: initialConfig, children: _jsx(CommentsProvider, { children: _jsx(ToolbarContext, { children: _jsxs("div", { className: "editor-shell", children: [_jsx(DocumentToolbar, { setIsLinkEditMode: setIsLinkEditMode }), _jsx("div", { className: "editor-container", children: _jsxs("div", { className: "editor-inner", children: [isCollaborative && collaboration ? (_jsx(LoroCollaborationPlugin, { id: collaboration.roomId, providerFactory: createWebsocketProvider, websocketUrl: collaboration.websocketUrl, shouldBootstrap: true, showCollaborators: true, username: collaborationName, cursorColor: collaborationColor, awarenessData: collaborationAwarenessData })) : null, _jsx(LexicalStatePlugin, {}), _jsx(RichTextPlugin, { contentEditable: _jsx("div", { className: "editor-scroller", children: _jsx("div", { className: "editor", ref: onAnchorRef, children: _jsx(ContentEditable, { className: "editor-input", "aria-label": "Ephemeral document editor" }) }) }), ErrorBoundary: LexicalErrorBoundary }), !isCollaborative && (_jsx(OnChangePlugin, { onChange: handleChange })), !isCollaborative && _jsx(HistoryPlugin, {}), _jsx(AutoFocusPlugin, {}), _jsx(ListPlugin, {}), _jsx(CheckListPlugin, {}), _jsx(LinkPlugin, {}), _jsx(AutoLinkPlugin, {}), _jsx(ListMaxIndentLevelPlugin, { maxDepth: 7 }), _jsx(MarkdownShortcutPlugin, { transformers: TRANSFORMERS }), !isCollaborative && (_jsx(LoadContentPlugin, { content: initialContent })), _jsx(CodeHighlightPlugin, {}), _jsx(ImagesPlugin, { captionsEnabled: false }), _jsx(ExcalidrawPlugin, {}), _jsx(TablePlugin, {}), _jsx(TableCellResizerPlugin, {}), _jsx(TableActionMenuPlugin, {}), _jsx(TableHoverActionsV2Plugin, {}), _jsx(CollapsiblePlugin, {}), _jsx(HorizontalRulePlugin, {}), _jsx(EquationsPlugin, {}), _jsx(YouTubePlugin, {}), _jsx(AutoEmbedPlugin, {}), _jsx(JupyterCellPlugin, {}), _jsx(ComponentPickerMenuPlugin, { kernel: documentKernel }), _jsx(JupyterInputOutputPlugin, { kernel: documentKernel }), floatingAnchorElem && (_jsxs(_Fragment, { children: [_jsx(DraggableBlockPlugin, { anchorElem: floatingAnchorElem }), _jsx(FloatingTextFormatToolbarPlugin, { anchorElem: floatingAnchorElem, setIsLinkEditMode: setIsLinkEditMode }), _jsx(CodeActionMenuPlugin, { anchorElem: floatingAnchorElem })] }))] }) })] }) }) }) }) }) }) }) })) : isRuntimeStarting ? (_jsxs(Box, { sx: {
+                height: '100%',
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                gap: 2,
+                color: 'fg.muted',
+            }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Starting document..." })] })) : null }));
 }
 export default EphemeralDocument;

package/lib/chat/header/ChatHeaderBase.d.ts

@@ -26,6 +26,8 @@ export interface ChatBaseHeaderProps {
     padding: number;
     /** Optional kernel indicator state override from notebook runtime. */
     kernelIndicatorState?: ExecutionState;
+    /** Horizontal placement for the kernel indicator in the title row. */
+    kernelIndicatorPlacement?: 'left' | 'center' | 'right';
     /**
      * Runtime status from agent-runtimes sandbox status stream.
      * Uses the same execution-state model as KernelIndicator.
@@ -69,5 +71,5 @@ export interface ChatBaseHeaderProps {
     /** Callback fired when the user changes the companion-surface mode. */
     onEphemeralSurfaceModeChange?: (mode: EphemeralSurfaceMode) => void;
 }
-export declare function ChatBaseHeader({ title, subtitle, brandIcon, headerContent, headerActions, showInformation, onInformationClick, padding, kernelIndicatorState, runtimeStatus, kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, headerButtons, messageCount, onNewChat, onClear, chatViewMode, onChatViewModeChange, showEphemeralSurfaceControl, enableEphemeralNotebookOption, enableEphemeralDocumentOption, ephemeralSurfaceMode, onEphemeralSurfaceModeChange, }: ChatBaseHeaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatBaseHeader({ title, subtitle, brandIcon, headerContent, headerActions, showInformation, onInformationClick, padding, kernelIndicatorState, kernelIndicatorPlacement, runtimeStatus, kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, headerButtons, messageCount, onNewChat, onClear, chatViewMode, onChatViewModeChange, showEphemeralSurfaceControl, enableEphemeralNotebookOption, enableEphemeralDocumentOption, ephemeralSurfaceMode, onEphemeralSurfaceModeChange, }: ChatBaseHeaderProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/lib/chat/header/ChatHeaderBase.js

@@ -29,11 +29,13 @@ export function toRuntimeExecutionState(runtimeStatus) {
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
-export function ChatBaseHeader({ title, subtitle, brandIcon, headerContent, headerActions, showInformation, onInformationClick, padding, kernelIndicatorState, runtimeStatus, kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, headerButtons, messageCount, onNewChat, onClear, chatViewMode, onChatViewModeChange, showEphemeralSurfaceControl = false, enableEphemeralNotebookOption = false, enableEphemeralDocumentOption = false, ephemeralSurfaceMode = 'none', onEphemeralSurfaceModeChange, }) {
+export function ChatBaseHeader({ title, subtitle, brandIcon, headerContent, headerActions, showInformation, onInformationClick, padding, kernelIndicatorState, kernelIndicatorPlacement = 'left', runtimeStatus, kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, headerButtons, messageCount, onNewChat, onClear, chatViewMode, onChatViewModeChange, showEphemeralSurfaceControl = false, enableEphemeralNotebookOption = false, enableEphemeralDocumentOption = false, ephemeralSurfaceMode = 'none', onEphemeralSurfaceModeChange, }) {
     const effectiveIndicatorState = kernelIndicatorState ?? toRuntimeExecutionState(runtimeStatus);
+    const kernelIndicatorElement = kernel ? (_jsx(KernelIndicator, { kernel: kernel, environmentName: kernelEnvironmentName, cpu: kernelCpu, memory: kernelMemory, gpu: kernelGpu, position: "s", bordered: false })) : (_jsx(KernelIndicator, { state: effectiveIndicatorState ?? 'undefined', environmentName: kernelEnvironmentName, cpu: kernelCpu, memory: kernelMemory, gpu: kernelGpu, position: "s", bordered: false }));
     return (_jsx(Box, { sx: {
             display: 'flex',
             flexDirection: 'column',
+            bg: 'canvas.default',
             borderBottom: '1px solid',
             borderColor: 'border.default',
         }, children: _jsxs(Box, { sx: {
@@ -47,7 +49,7 @@ export function ChatBaseHeader({ title, subtitle, brandIcon, headerContent, head
                         gap: 2,
                         minWidth: 0,
                         flex: '1 1 auto',
-                    }, children: [brandIcon || _jsx(AiAgentIcon, { colored: true, size: 20 }), kernel ? (_jsx(KernelIndicator, { kernel: kernel, environmentName: kernelEnvironmentName, cpu: kernelCpu, memory: kernelMemory, gpu: kernelGpu, position: "s", bordered: false })) : (_jsx(KernelIndicator, { state: effectiveIndicatorState ?? 'undefined', environmentName: kernelEnvironmentName, cpu: kernelCpu, memory: kernelMemory, gpu: kernelGpu, position: "s", bordered: false })), (title || subtitle) && (_jsxs(Box, { sx: {
+                    }, children: [kernelIndicatorPlacement === 'left' && kernelIndicatorElement, brandIcon || _jsx(AiAgentIcon, { colored: true, size: 20 }), (title || subtitle) && (_jsxs(Box, { sx: {
                                 display: 'flex',
                                 flexDirection: 'column',
                                 minWidth: 0,
@@ -62,7 +64,7 @@ export function ChatBaseHeader({ title, subtitle, brandIcon, headerContent, head
                                         color: 'fg.muted',
                                         minWidth: 0,
                                         maxWidth: '100%',
-                                    }, children: _jsx(Truncate, { title: subtitle, maxWidth: "40ch", children: subtitle }) }))] })), headerContent, showInformation && (_jsx(IconButton, { icon: InfoIcon, "aria-label": "Information", variant: "invisible", size: "small", onClick: onInformationClick }))] }), _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1, flexShrink: 0 }, children: [headerButtons?.showNewChat && (_jsx(IconButton, { icon: PlusIcon, "aria-label": "New chat", variant: "invisible", size: "small", onClick: onNewChat })), headerButtons?.showClear && messageCount > 0 && (_jsx(IconButton, { icon: TrashIcon, "aria-label": "Clear messages", variant: "invisible", size: "small", onClick: onClear })), headerButtons?.showSettings && (_jsx(IconButton, { icon: GearIcon, "aria-label": "Settings", variant: "invisible", size: "small", onClick: headerButtons.onSettings })), showEphemeralSurfaceControl && (_jsx(Box, { sx: {
+                                    }, children: _jsx(Truncate, { title: subtitle, maxWidth: "40ch", children: subtitle }) }))] })), headerContent, showInformation && (_jsx(IconButton, { icon: InfoIcon, "aria-label": "Information", variant: "invisible", size: "small", onClick: onInformationClick })), kernelIndicatorPlacement === 'center' && kernelIndicatorElement] }), _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1, flexShrink: 0 }, children: [kernelIndicatorPlacement === 'right' && kernelIndicatorElement, headerButtons?.showNewChat && (_jsx(IconButton, { icon: PlusIcon, "aria-label": "New chat", variant: "invisible", size: "small", onClick: onNewChat })), headerButtons?.showClear && messageCount > 0 && (_jsx(IconButton, { icon: TrashIcon, "aria-label": "Clear messages", variant: "invisible", size: "small", onClick: onClear })), headerButtons?.showSettings && (_jsx(IconButton, { icon: GearIcon, "aria-label": "Settings", variant: "invisible", size: "small", onClick: headerButtons.onSettings })), showEphemeralSurfaceControl && (_jsx(Box, { sx: {
                                 display: 'inline-flex',
                                 alignItems: 'center',
                                 bg: 'neutral.muted',

package/lib/chat/messages/ChatMessageList.d.ts

@@ -46,4 +46,23 @@ export interface ChatMessageListProps {
      */
     approvalConfig?: ToolApprovalConfig;
 }
+type SubagentAvatarConfig = Required<Pick<AvatarConfig, 'userAvatar' | 'assistantAvatar' | 'showAvatars' | 'avatarSize' | 'userAvatarBg' | 'assistantAvatarBg'>>;
+export interface SubagentChatPanelProps {
+    /** Parent `delegate_task` tool call id used to look up streamed events. */
+    toolCallId: string;
+    /** Subagent name used as a fallback when the tool-call id does not match. */
+    subagentName?: string;
+    /** Fixed viewport height in pixels. */
+    height?: number;
+    /** Avatar configuration for the embedded message list. */
+    avatarConfig?: SubagentAvatarConfig;
+}
+/**
+ * Fixed-height, chat-style viewport for a single delegated subagent run.
+ * Reuses {@link ChatMessageList} so subagent output is formatted exactly like
+ * the primary agent, including tool-call cards and inline approvals. Tool
+ * approval decisions are sent over the shared monitoring socket.
+ */
+export declare function SubagentChatPanel({ toolCallId, subagentName: subagentNameHint, height, avatarConfig, }: SubagentChatPanelProps): React.ReactElement | null;
 export declare function ChatMessageList({ displayItems, isLoading, isStreaming, showLoadingIndicator, hideMessagesAfterToolUI, avatarConfig, padding, renderToolResult, emptyContent, messagesEndRef, onRespond, approvalConfig, }: ChatMessageListProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/chat/messages/ChatMessageList.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.
@@ -9,14 +9,15 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  *
  * @module chat/messages/MessageList
  */
-import { useState, useCallback, useMemo, } from 'react';
-import { Text } from '@primer/react';
+import { useState, useCallback, useEffect, useMemo, useRef, } from 'react';
+import { Text, Spinner } from '@primer/react';
+import { DependabotIcon, PersonIcon } from '@primer/octicons-react';
 import { Box } from '@datalayer/primer-addons';
 import { Streamdown } from 'streamdown';
 import { streamdownMarkdownStyles, streamdownCodeBlockStyles, } from '../styles/streamdownStyles';
 import { ToolCallDisplay } from '../tools/ToolCallDisplay';
 import { isToolCallMessage, getMessageText } from '../../utils';
-import { useAgentRuntimeStore } from '../../stores/agentRuntimeStore';
+import { useAgentRuntimeStore, useAgentRuntimeSubagentActivityByToolCall, agentRuntimeStore, } from '../../stores/agentRuntimeStore';
 // ---------------------------------------------------------------------------
 // Normalize helper
 // ---------------------------------------------------------------------------
@@ -70,6 +71,171 @@ function normalizeAssistantMarkdown(text) {
     });
     return out;
 }
+const SUBAGENT_AVATAR_CONFIG = {
+    userAvatar: _jsx(PersonIcon, { size: 14 }),
+    assistantAvatar: _jsx(DependabotIcon, { size: 14 }),
+    showAvatars: true,
+    avatarSize: 24,
+    userAvatarBg: 'neutral.muted',
+    assistantAvatarBg: 'accent.emphasis',
+};
+/**
+ * Convert streamed subagent activity into the `DisplayItem[]` shape the main
+ * chat renders: text deltas merge into markdown messages, and tool events pair
+ * into tool-call cards (with approval controls when the runtime requests one).
+ * Reasoning (`thinking`) is omitted to mirror the primary agent view.
+ */
+function buildSubagentDisplayItems(events, keyPrefix) {
+    const items = [];
+    const openByName = new Map();
+    let textBuffer = '';
+    let seq = 0;
+    const flushText = () => {
+        if (textBuffer.trim()) {
+            items.push({
+                id: `${keyPrefix}:msg:${seq++}`,
+                role: 'assistant',
+                content: textBuffer,
+                createdAt: new Date(0),
+            });
+        }
+        textBuffer = '';
+    };
+    for (const event of events) {
+        switch (event.phase) {
+            case 'text':
+                textBuffer += event.text ?? '';
+                break;
+            case 'tool_call': {
+                flushText();
+                const id = `${keyPrefix}:tool:${seq++}`;
+                const toolCall = {
+                    id,
+                    type: 'tool-call',
+                    toolCallId: id,
+                    toolName: event.toolName ?? 'tool',
+                    args: event.toolArgs ?? {},
+                    status: 'inProgress',
+                };
+                items.push(toolCall);
+                if (event.toolName) {
+                    openByName.set(event.toolName, toolCall);
+                }
+                break;
+            }
+            case 'tool_result': {
+                flushText();
+                const open = event.toolName
+                    ? openByName.get(event.toolName)
+                    : undefined;
+                if (open) {
+                    open.result = event.result;
+                    open.status = 'complete';
+                    if (event.toolName) {
+                        openByName.delete(event.toolName);
+                    }
+                }
+                else {
+                    const id = `${keyPrefix}:tool:${seq++}`;
+                    items.push({
+                        id,
+                        type: 'tool-call',
+                        toolCallId: id,
+                        toolName: event.toolName ?? 'tool',
+                        args: {},
+                        result: event.result,
+                        status: 'complete',
+                    });
+                }
+                break;
+            }
+            case 'error':
+                flushText();
+                items.push({
+                    id: `${keyPrefix}:msg:${seq++}`,
+                    role: 'assistant',
+                    content: `**\u26a0\ufe0f ${event.error ?? 'Subagent failed'}**`,
+                    createdAt: new Date(0),
+                });
+                break;
+            // `start`, `thinking`, and `end` do not produce display items.
+            default:
+                break;
+        }
+    }
+    flushText();
+    return items;
+}
+/**
+ * Fixed-height, chat-style viewport for a single delegated subagent run.
+ * Reuses {@link ChatMessageList} so subagent output is formatted exactly like
+ * the primary agent, including tool-call cards and inline approvals. Tool
+ * approval decisions are sent over the shared monitoring socket.
+ */
+export function SubagentChatPanel({ toolCallId, subagentName: subagentNameHint, height = 280, avatarConfig = SUBAGENT_AVATAR_CONFIG, }) {
+    const events = useAgentRuntimeSubagentActivityByToolCall(toolCallId, subagentNameHint);
+    const displayItems = useMemo(() => buildSubagentDisplayItems(events, toolCallId), [events, toolCallId]);
+    const messagesEndRef = useRef(null);
+    const subagentName = useMemo(() => {
+        for (const event of events) {
+            if (event.subagentName)
+                return event.subagentName;
+        }
+        return subagentNameHint ?? 'subagent';
+    }, [events, subagentNameHint]);
+    const isDone = useMemo(() => events.some(e => e.phase === 'end' || e.phase === 'error'), [events]);
+    const hasError = useMemo(() => events.some(e => e.phase === 'error'), [events]);
+    // Forward inline tool-approval decisions to the shared monitoring socket.
+    const handleRespond = useCallback(async (_toolCallId, result) => {
+        if (result && typeof result === 'object') {
+            const record = result;
+            if (record.type === 'tool-approval-decision' &&
+                typeof record.approved === 'boolean' &&
+                typeof record.approvalId === 'string') {
+                agentRuntimeStore
+                    .getState()
+                    .sendDecision(record.approvalId, record.approved);
+            }
+        }
+    }, []);
+    useEffect(() => {
+        messagesEndRef.current?.scrollIntoView({ block: 'end' });
+    }, [displayItems]);
+    if (events.length === 0) {
+        return null;
+    }
+    return (_jsxs(Box, { sx: {
+            mt: 2,
+            display: 'flex',
+            flexDirection: 'column',
+            height,
+            width: '100%',
+            border: '1px solid',
+            borderColor: 'border.default',
+            borderRadius: 2,
+            overflow: 'hidden',
+            bg: 'canvas.default',
+        }, children: [_jsxs(Box, { sx: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 1,
+                    px: 2,
+                    py: 1,
+                    borderBottom: '1px solid',
+                    borderColor: 'border.muted',
+                    bg: 'canvas.subtle',
+                    flexShrink: 0,
+                }, children: [_jsx(Box, { sx: {
+                            display: 'flex',
+                            color: hasError ? 'danger.fg' : isDone ? 'success.fg' : 'accent.fg',
+                        }, children: _jsx(DependabotIcon, { size: 14 }) }), _jsx(Text, { sx: { fontSize: 0, fontWeight: 'bold', color: 'fg.default' }, children: subagentName }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', ml: 'auto' }, children: hasError ? 'failed' : isDone ? 'done' : 'working\u2026' })] }), _jsx(Box, { sx: { flex: 1, minHeight: 0, overflowY: 'auto' }, children: _jsx(ChatMessageList, { displayItems: displayItems, isLoading: !isDone, isStreaming: !isDone, showLoadingIndicator: !isDone, hideMessagesAfterToolUI: false, avatarConfig: avatarConfig, padding: 2, onRespond: handleRespond, messagesEndRef: messagesEndRef, emptyContent: _jsxs(Box, { sx: {
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: 1,
+                            color: 'fg.muted',
+                            p: 2,
+                        }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 0 }, children: "Starting\u2026" })] }) }) })] }));
+}
 // ---------------------------------------------------------------------------
 // DefaultToolCallRenderer — reads approvals from the Zustand store,
 // sends decisions over the shared WebSocket (no REST polling).
@@ -175,11 +341,16 @@ function DefaultToolCallRenderer({ item, onRespond, }) {
         : externalDecision
             ? 'external'
             : undefined;
-    return (_jsx(ToolCallDisplay, { toolCallId: item.toolCallId, toolName: item.toolName, args: item.args, result: item.result, status: item.status, error: item.error, executionError: item.executionError, codeError: item.codeError, exitCode: item.exitCode, approvalRequired: hasApproval, approvalState: approvalState, approvalDecisionSource: approvalDecisionSource, onApprove: effectiveApprovalId && !decision && !externalDecision
-            ? () => makeDecision('approve')
-            : undefined, onDeny: effectiveApprovalId && !decision && !externalDecision
-            ? () => makeDecision('reject')
-            : undefined, approvalLoading: false }));
+    // `normalizeName` strips underscores, so compare against the normalized form.
+    const isSubagentDelegation = normalizedToolName === 'delegatetask';
+    const delegatedSubagentName = typeof item.args?.subagent_name === 'string'
+        ? item.args.subagent_name
+        : undefined;
+    return (_jsxs(_Fragment, { children: [_jsx(ToolCallDisplay, { toolCallId: item.toolCallId, toolName: item.toolName, args: item.args, result: item.result, status: item.status, error: item.error, executionError: item.executionError, codeError: item.codeError, exitCode: item.exitCode, approvalRequired: hasApproval, approvalState: approvalState, approvalDecisionSource: approvalDecisionSource, onApprove: effectiveApprovalId && !decision && !externalDecision
+                    ? () => makeDecision('approve')
+                    : undefined, onDeny: effectiveApprovalId && !decision && !externalDecision
+                    ? () => makeDecision('reject')
+                    : undefined, approvalLoading: false }), isSubagentDelegation && (_jsx(SubagentChatPanel, { toolCallId: item.toolCallId, subagentName: delegatedSubagentName }))] }));
 }
 // ---------------------------------------------------------------------------
 // Component

package/lib/chat/notebook/EphemeralNotebook.d.ts

@@ -1,5 +1,24 @@
 import type { INotebookContent } from '@jupyterlab/nbformat';
+import type { ICollaborationProvider } from '@datalayer/jupyter-react';
 import type { EphemeralNotebookToolbarComponent } from '../../types/chat';
+/**
+ * Explicit runtime endpoint used to bind an ephemeral notebook kernel without
+ * resolving a pod from the user's runtimes list. Used to reach an agent node's
+ * Jupyter server through the runtimes tunnel HTTP/WebSocket proxy.
+ */
+export interface EphemeralRuntimeOverride {
+    /** REST base URL, e.g. `https://.../agent-nodes/{nodeId}/jupyter`. */
+    baseUrl: string;
+    /**
+     * WebSocket base URL. Defaults to `baseUrl` with the http(s) scheme swapped
+     * for ws(s). For the tunnel proxy this is the `/ws` sibling of `baseUrl`.
+     */
+    wsUrl?: string;
+    /** Bearer/JWT token appended to requests (`appendToken`). */
+    token?: string;
+    /** Stable identifier used for the sandbox service-manager registry. */
+    podName?: string;
+}
 export interface EphemeralNotebookProps {
     /**
      * Notebook identifier. Must match the id passed to `useNotebookTools` so the
@@ -8,6 +27,14 @@ export interface EphemeralNotebookProps {
     notebookId: string;
     /** Preferred runtime pod name to bind the notebook kernel to. */
     runtimePodName?: string;
+    /**
+     * Explicit runtime endpoint override. When supplied, the notebook binds its
+     * kernel to this endpoint directly instead of resolving a pod from the user's
+     * runtimes list. This is how a SaaS browser reaches an agent node's Jupyter
+     * server through the runtimes tunnel proxy: `baseUrl` points at
+     * `.../agent-nodes/{nodeId}/jupyter` and `wsUrl` at its `/ws` sibling.
+     */
+    runtimeOverride?: EphemeralRuntimeOverride;
     /** Left margin reserved for the cell sidebar (default 120). */
     cellSidebarMargin?: number;
     /** Optional persisted notebook model to restore when mounting. */
@@ -16,9 +43,21 @@ export interface EphemeralNotebookProps {
     onNbformatChange?: (content: INotebookContent) => void;
     /** Optional toolbar component override. */
     toolbarComponent?: EphemeralNotebookToolbarComponent;
+    /** Optional theme variant override from host chat context. */
+    themeVariant?: string;
+    /** Optional color mode override from host chat context. */
+    colorMode?: 'light' | 'dark' | 'auto';
+    /**
+     * Optional real-time collaboration provider. When supplied, the notebook
+     * joins a shared collaborative room (the ydoc becomes the source of truth)
+     * and the local in-memory persistence poll is disabled. This is how a node's
+     * notebook state transits to the SaaS UI (and back) over RTC instead of the
+     * tunnel.
+     */
+    collaborationProvider?: ICollaborationProvider;
 }
 /**
  * Renders an in-memory notebook backed by a sandbox kernel.
  */
-export declare function EphemeralNotebook({ notebookId, runtimePodName, cellSidebarMargin, nbformat, onNbformatChange, toolbarComponent, }: EphemeralNotebookProps): import("react/jsx-runtime").JSX.Element;
+export declare function EphemeralNotebook({ notebookId, runtimePodName, runtimeOverride, cellSidebarMargin, nbformat, onNbformatChange, toolbarComponent, themeVariant, colorMode, collaborationProvider, }: EphemeralNotebookProps): import("react/jsx-runtime").JSX.Element;
 export default EphemeralNotebook;