@datalayer/agent-runtimes 1.0.18 → 1.0.19

package/lib/chat/Chat.js

@@ -136,7 +136,7 @@ function getProtocolType(protocol) {
  * />
  * ```
  */
-export function Chat({ protocol: transport, extensions: _extensions, baseUrl = 'http://localhost:8765', wsUrl, agentId, authToken: authTokenProp, placeholder = 'Type your message...', title, subtitle, brandIcon, autoConnect = true, streaming: _streaming = true, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height = '600px', showHeader = true, showNewChatButton = true, showClearButton = true, showModelSelector = true, showToolsMenu = true, showInput = true, disableInputPrompt = false, overlay, launching = false, launchingMessage, showSkillsMenu = true, codemodeEnabled = false, onToggleCodemode, showTokenUsage = true, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount = true, suggestions, submitOnSuggestionClick = true, description, headerContent, headerActions, autoFocus = false, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation = true, chatViewMode, onChatViewModeChange, frontendTools, enableEphemeralNotebook, initialEphemeralNotebookOpen, onEphemeralNotebookOpenChange, enableEphemeralDocument, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, onToolCallStart, onToolCallComplete, renderToolResult, hideMessagesAfterToolUI = false, contextSnapshot, mcpStatusData, codemodeStatusData, sandboxStatusData, kernel, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, disableInternalJupyterTheme = false, }) {
+export function Chat({ protocol: transport, extensions: _extensions, baseUrl = 'http://localhost:8765', endpoint: endpointProp, configEndpoint: configEndpointProp, enableConfigQuery: enableConfigQueryProp, wsUrl, agentId, authToken: authTokenProp, placeholder = 'Type your message...', title, subtitle, brandIcon, autoConnect = true, streaming: _streaming = true, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height = '600px', showHeader = true, showNewChatButton = true, showClearButton = true, showModelSelector = true, showToolsMenu = true, showInput = true, disableInputPrompt = false, overlay, launching = false, launchingMessage, showSkillsMenu = true, codemodeEnabled = false, onToggleCodemode, showTokenUsage = true, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount = true, suggestions, submitOnSuggestionClick = true, description, headerContent, headerActions, autoFocus = false, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation = true, chatViewMode, onChatViewModeChange, frontendTools, enableEphemeralNotebook, initialEphemeralNotebookOpen, onEphemeralNotebookOpenChange, enableEphemeralDocument, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, onToolCallStart, onToolCallComplete, renderToolResult, hideMessagesAfterToolUI = false, contextSnapshot, mcpStatusData, codemodeStatusData, sandboxStatusData, kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, disableInternalJupyterTheme = false, }) {
     const resolvedAgentId = typeof agentId === 'string' && agentId.trim().length > 0
         ? agentId.trim()
         : 'default';
@@ -220,6 +220,10 @@ export function Chat({ protocol: transport, extensions: _extensions, baseUrl = '
                     break;
                 }
             }
+            // Explicit endpoint override (e.g. Agent Node tunnel proxy).
+            if (endpointProp) {
+                endpoint = endpointProp;
+            }
             return {
                 config: {
                     type: getProtocolType(transport),
@@ -228,12 +232,14 @@ export function Chat({ protocol: transport, extensions: _extensions, baseUrl = '
                     authToken,
                     options,
                     // Enable config query for all protocols to fetch models and tools
-                    enableConfigQuery: true,
+                    enableConfigQuery: enableConfigQueryProp ?? true,
                     // For Jupyter-based transports, use Jupyter requestAPI (configEndpoint undefined)
                     // For FastAPI-based transports, use direct fetch to the configure endpoint
-                    configEndpoint: transport === 'vercel-ai-jupyter'
-                        ? undefined // Use Jupyter requestAPI
-                        : `${baseUrl}/api/v1/configure`,
+                    configEndpoint: configEndpointProp !== undefined
+                        ? configEndpointProp
+                        : transport === 'vercel-ai-jupyter'
+                            ? undefined // Use Jupyter requestAPI
+                            : `${baseUrl}/api/v1/configure`,
                 },
                 error: null,
             };
@@ -245,7 +251,16 @@ export function Chat({ protocol: transport, extensions: _extensions, baseUrl = '
                 error: err instanceof Error ? err.message : 'Failed to configure',
             };
         }
-    }, [transport, baseUrl, wsUrl, resolvedAgentId, authTokenProp]);
+    }, [
+        transport,
+        baseUrl,
+        wsUrl,
+        resolvedAgentId,
+        authTokenProp,
+        endpointProp,
+        configEndpointProp,
+        enableConfigQueryProp,
+    ]);
     const protocolConfig = protocolConfigResult.config;
     // Set initialized once protocol config is built
     useEffect(() => {
@@ -349,6 +364,6 @@ export function Chat({ protocol: transport, extensions: _extensions, baseUrl = '
                                                 ? 'attention.fg'
                                                 : 'danger.fg',
                                             flex: 1,
-                                        }, children: errorBanner.message })] })), _jsx(ChatBase, { title: title, subtitle: subtitle, brandIcon: brandIcon, showHeader: showHeader, protocol: protocolConfig, placeholder: placeholder, description: description, suggestions: suggestions, submitOnSuggestionClick: submitOnSuggestionClick, autoFocus: autoFocus, runtimeId: runtimeId, historyEndpoint: historyEndpoint, pendingPrompt: pendingPrompt, showInformation: showInformation, onInformationClick: handleInformationClick, headerContent: headerContent, headerActions: headerActions, showModelSelector: showModelSelector, showToolsMenu: showToolsMenu, showInput: showInput, disableInputPrompt: disableInputPrompt, overlay: overlay, launching: launching, launchingMessage: launchingMessage, autoConnect: autoConnect, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, codemodeEnabled: codemodeEnabled, onToggleCodemode: onToggleCodemode, initialModel: initialModel, availableModels: availableModels, mcpServers: mcpServers, initialSkills: initialSkills, connectedIdentities: identitiesForChat, onNewChat: handleNewChat, onMessagesChange: handleMessagesChange, headerButtons: headerButtons, avatarConfig: avatarConfig, backgroundColor: "canvas.default", focusTrigger: focusTrigger, chatViewMode: chatViewMode, onChatViewModeChange: onChatViewModeChange, frontendTools: frontendTools, enableEphemeralNotebook: enableEphemeralNotebook, initialEphemeralNotebookOpen: initialEphemeralNotebookOpen, onEphemeralNotebookOpenChange: onEphemeralNotebookOpenChange, enableEphemeralDocument: enableEphemeralDocument, initialEphemeralSurfaceMode: initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange: onEphemeralSurfaceModeChange, collapsed: collapsed, onExpandFromCollapsed: onExpandFromCollapsed, ephemeralNotebookToolbar: ephemeralNotebookToolbar, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, renderToolResult: renderToolResult, hideMessagesAfterToolUI: hideMessagesAfterToolUI, contextSnapshot: contextSnapshot, mcpStatusData: mcpStatusData, sandboxStatusData: sandboxStatusData, kernel: kernel, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, disableInternalJupyterTheme: disableInternalJupyterTheme })] })] }) }) }));
+                                        }, children: errorBanner.message })] })), _jsx(ChatBase, { title: title, subtitle: subtitle, brandIcon: brandIcon, showHeader: showHeader, protocol: protocolConfig, placeholder: placeholder, description: description, suggestions: suggestions, submitOnSuggestionClick: submitOnSuggestionClick, autoFocus: autoFocus, runtimeId: runtimeId, historyEndpoint: historyEndpoint, pendingPrompt: pendingPrompt, showInformation: showInformation, onInformationClick: handleInformationClick, headerContent: headerContent, headerActions: headerActions, showModelSelector: showModelSelector, showToolsMenu: showToolsMenu, showInput: showInput, disableInputPrompt: disableInputPrompt, overlay: overlay, launching: launching, launchingMessage: launchingMessage, autoConnect: autoConnect, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, codemodeEnabled: codemodeEnabled, onToggleCodemode: onToggleCodemode, initialModel: initialModel, availableModels: availableModels, mcpServers: mcpServers, initialSkills: initialSkills, connectedIdentities: identitiesForChat, onNewChat: handleNewChat, onMessagesChange: handleMessagesChange, headerButtons: headerButtons, avatarConfig: avatarConfig, backgroundColor: "canvas.default", focusTrigger: focusTrigger, chatViewMode: chatViewMode, onChatViewModeChange: onChatViewModeChange, frontendTools: frontendTools, enableEphemeralNotebook: enableEphemeralNotebook, initialEphemeralNotebookOpen: initialEphemeralNotebookOpen, onEphemeralNotebookOpenChange: onEphemeralNotebookOpenChange, enableEphemeralDocument: enableEphemeralDocument, initialEphemeralSurfaceMode: initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange: onEphemeralSurfaceModeChange, collapsed: collapsed, onExpandFromCollapsed: onExpandFromCollapsed, ephemeralNotebookToolbar: ephemeralNotebookToolbar, ephemeralNotebookCollaborationProvider: ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId: ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration: ephemeralDocumentCollaboration, ephemeralRuntimeOverride: ephemeralRuntimeOverride, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, renderToolResult: renderToolResult, hideMessagesAfterToolUI: hideMessagesAfterToolUI, contextSnapshot: contextSnapshot, mcpStatusData: mcpStatusData, sandboxStatusData: sandboxStatusData, kernel: kernel, kernelEnvironmentName: kernelEnvironmentName, kernelCpu: kernelCpu, kernelMemory: kernelMemory, kernelGpu: kernelGpu, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, disableInternalJupyterTheme: disableInternalJupyterTheme })] })] }) }) }));
 }
 export default Chat;

package/lib/chat/base/ChatBase.js

@@ -17,11 +17,11 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  */
 import { useContext } from 'react';
 import React, { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
-import { Text, Spinner, IconButton } from '@primer/react';
+import { Box, 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 { 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';
@@ -472,7 +472,7 @@ function ChatBaseInner({ title, subtitle, showHeader = false, showTokenUsage = t
 // 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: frontendToolsProp, enableEphemeralNotebook = false, initialEphemeralNotebookOpen = true, onEphemeralNotebookOpenChange, enableEphemeralDocument = false, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, 
+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, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, 
 // Tool invocation hooks
 onToolCallStart, onToolCallComplete, 
 // Identity/Authorization props
@@ -510,9 +510,15 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     // 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;
+    // When an explicit collaboration document id is supplied (e.g. an Agent Node
+    // sharing a room with the SaaS UI), it becomes the notebook id directly so
+    // BOTH peers join the same collaborative room AND the agent's notebook tools
+    // (scoped by this same id) drive the shared notebook. Otherwise fall back to
+    // the derived, per-runtime in-memory id.
+    const ephemeralNotebookId = ephemeralNotebookCollaborationDocumentId ||
+        (notebookScopeId
+            ? `ephemeral-notebook-${notebookScopeId}`
+            : generatedNotebookIdRef.current);
     const persistedEphemeralNbformat = useAgentRuntimeStore(s => s.getEphemeralNotebookModel(ephemeralNotebookId));
     const setEphemeralNotebookModel = useAgentRuntimeStore(s => s.setEphemeralNotebookModel);
     const handleEphemeralNotebookChange = useCallback((model) => {
@@ -520,10 +526,14 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     }, [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}`;
+    // document survives navigation away from and back to the runtime page. When a
+    // collaboration room is supplied it becomes the document id directly so BOTH
+    // peers join the same Loro room AND the agent's lexical tools (scoped by this
+    // same id) drive the shared document.
+    const ephemeralDocumentId = ephemeralDocumentCollaboration?.roomId ||
+        (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) => {
@@ -576,6 +586,18 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             unsubscribe();
         };
     }, [notebookVisible, ephemeralNotebookId]);
+    // Track the ephemeral document's live kernel connection the same way, so the
+    // header's kernel indicator reflects the real connected kernel while the
+    // document surface is active (instead of the "disconnected" placeholder).
+    const [documentKernel, setDocumentKernel] = useState(null);
+    const handleDocumentKernelChange = useCallback((next) => {
+        setDocumentKernel(prev => (prev?.id === next?.id ? prev : next));
+    }, []);
+    useEffect(() => {
+        if (!documentVisible) {
+            setDocumentKernel(null);
+        }
+    }, [documentVisible]);
     // 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 &&
@@ -2827,7 +2849,11 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     // 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;
+    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)
+            : documentVisible
+                ? (documentKernel ?? 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
     // ========================================================================
@@ -2874,7 +2900,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                                         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
+                        }, children: launching || overlay ? (_jsx(CompanionSurfaceSkeleton, { mode: notebookVisible ? 'notebook' : 'document' })) : notebookVisible ? (_jsx(EphemeralNotebook, { notebookId: ephemeralNotebookId, runtimePodName: runtimeId || activeAgentId, runtimeOverride: ephemeralRuntimeOverride, nbformat: persistedEphemeralNbformat ?? undefined, onNbformatChange: handleEphemeralNotebookChange, toolbarComponent: ephemeralNotebookToolbar, collaborationProvider: ephemeralNotebookCollaborationProvider })) : (_jsx(React.Suspense, { fallback: null, children: _jsx(EphemeralDocument, { documentId: ephemeralDocumentId, runtimePodName: runtimeId || activeAgentId, runtimeOverride: ephemeralRuntimeOverride, content: persistedEphemeralDocument ?? undefined, onContentChange: handleEphemeralDocumentChange, onToolsReady: handleDocumentToolsReady, onKernelChange: handleDocumentKernelChange, collaboration: ephemeralDocumentCollaboration }) })) }), !surfaceCollapsed && (_jsxs(Box, { sx: surfaceChatFloating
                             ? {
                                 position: 'absolute',
                                 right: 16,

package/lib/chat/document/EphemeralDocument.d.ts

@@ -1,6 +1,35 @@
+import type { IKernelConnection } from '@jupyterlab/services/lib/kernel/kernel';
 import type { FrontendToolDefinition } from '../../types/tools';
+import type { EphemeralRuntimeOverride } from '../notebook/EphemeralNotebook';
 import '@datalayer/jupyter-react/lib/css/PrismCss';
 import '@datalayer/jupyter-lexical/style/index.css';
+/**
+ * Real-time collaboration configuration for the ephemeral document.
+ *
+ * When supplied, the Lexical editor state is backed by a shared Loro CRDT
+ * document synchronised over a WebSocket (the spacer lexical endpoint) instead
+ * of the in-memory / persisted local state. Every peer that joins the same
+ * `roomId` edits the same document — this is how an Agent Node and the SaaS UI
+ * share a live document. The caller owns the room/identity lifecycle.
+ */
+export interface EphemeralDocumentCollaboration {
+    /**
+     * WebSocket URL of the Loro collaboration server, e.g.
+     * `wss://…/api/spacer/v1/lexical/ws`.
+     */
+    websocketUrl: string;
+    /** Shared collaboration room / document id joined by all peers. */
+    roomId: string;
+    /** Optional identity used for collaborative presence (cursors / awareness). */
+    identity?: {
+        userId?: string;
+        handle?: string;
+        displayName?: string;
+        initials?: string;
+        avatarUrl?: string;
+        color?: string;
+    };
+}
 export interface EphemeralDocumentProps {
     /**
      * Document identifier. Must match the id passed to `useLexicalTools` so the
@@ -9,15 +38,30 @@ export interface EphemeralDocumentProps {
     documentId: string;
     /** Preferred runtime pod name to bind the document kernel to. */
     runtimePodName?: string;
+    /** Optional explicit runtime endpoint (agent-node tunnel proxy path). */
+    runtimeOverride?: EphemeralRuntimeOverride;
     /** Optional persisted Lexical editor state (JSON string) to restore. */
     content?: string;
     /** Callback fired when the document's editor state changes. */
     onContentChange?: (content: string) => void;
     /** Reports the lexical frontend tools so the parent can pass them to the agent. */
     onToolsReady?: (tools: FrontendToolDefinition[]) => void;
+    /**
+     * Reports the document's live sandbox kernel connection upward so the chat
+     * header can render the same rich kernel indicator (kernel id, client id,
+     * status) as the notebook surface. Emits `null` while the kernel is absent.
+     */
+    onKernelChange?: (kernel: IKernelConnection | null) => void;
+    /**
+     * Optional real-time collaboration configuration. When supplied the document
+     * joins a shared Loro room over WebSocket so its state transits over RTC
+     * (e.g. between an Agent Node and the SaaS UI) rather than living purely in
+     * local memory.
+     */
+    collaboration?: EphemeralDocumentCollaboration;
 }
 /**
  * Renders an in-memory Lexical document backed by a sandbox kernel.
  */
-export declare function EphemeralDocument({ documentId, runtimePodName, content, onContentChange, onToolsReady, }: EphemeralDocumentProps): import("react/jsx-runtime").JSX.Element;
+export declare function EphemeralDocument({ documentId, runtimePodName, runtimeOverride, content, onContentChange, onToolsReady, onKernelChange, collaboration, }: EphemeralDocumentProps): import("react/jsx-runtime").JSX.Element;
 export default EphemeralDocument;

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, 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.
@@ -252,19 +316,79 @@ export function EphemeralDocument({ documentId, runtimePodName, content, onConte
                         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/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,17 @@ export interface EphemeralNotebookProps {
     onNbformatChange?: (content: INotebookContent) => void;
     /** Optional toolbar component override. */
     toolbarComponent?: EphemeralNotebookToolbarComponent;
+    /**
+     * 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, collaborationProvider, }: EphemeralNotebookProps): import("react/jsx-runtime").JSX.Element;
 export default EphemeralNotebook;