@datalayer/agent-runtimes 1.0.18 → 1.0.20

package/lib/api/runtimes/runtimes.d.ts

@@ -120,6 +120,63 @@ export interface ResumeRuntimeBody {
     /** Additional metadata */
     metadata?: Record<string, any>;
 }
+/**
+ * Persisted memory record returned by ``/api/runtimes/v1/memories``.
+ */
+export interface RuntimeMemory {
+    id: string;
+    memory?: string | null;
+    hash?: string | null;
+    user_id?: string | null;
+    agent_id?: string | null;
+    run_id?: string | null;
+    actor_id?: string | null;
+    role?: string | null;
+    scope?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    metadata?: Record<string, any>;
+}
+/**
+ * Response payload for listing persisted runtime memories.
+ */
+export interface ListRuntimeMemoriesResponse {
+    success: boolean;
+    message?: string;
+    count: number;
+    limit: number;
+    offset: number;
+    user_id?: string;
+    memories: RuntimeMemory[];
+}
+/**
+ * Response payload for fetching one persisted memory.
+ */
+export interface GetRuntimeMemoryResponse {
+    success: boolean;
+    message?: string;
+    memory: RuntimeMemory;
+}
+/**
+ * Query options for listing persisted runtime memories.
+ */
+export interface ListRuntimeMemoriesOptions {
+    userId?: string;
+    agentId?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * List persisted memories from the runtimes API.
+ *
+ * Non-admin callers are automatically scoped to their own personal account by
+ * the backend, even when ``userId`` is omitted.
+ */
+export declare const listRuntimeMemories: (token: string, options?: ListRuntimeMemoriesOptions, baseUrl?: string) => Promise<ListRuntimeMemoriesResponse>;
+/**
+ * Fetch one persisted memory by id from the runtimes API.
+ */
+export declare const getRuntimeMemory: (token: string, memoryId: string, baseUrl?: string) => Promise<GetRuntimeMemoryResponse>;
 /**
  * Resume a paused runtime by restoring from a checkpoint (async).
  *

package/lib/api/runtimes/runtimes.js

@@ -39,7 +39,7 @@ export const createRuntime = async (token, data, baseUrl = DEFAULT_SERVICE_URLS.
             const responseData = error.response.data || {};
             if (status === 404) {
                 // Environment not found
-                throw new Error(`Environment '${data.environment_name}' not found. ${responseData.message || 'Please check the environment name and try again.'}`);
+                throw new Error(`Environment '${data.environment?.name || ''}' not found. ${responseData.message || 'Please check the environment name and try again.'}`);
             }
             else if (status === 503) {
                 // No runtime available
@@ -203,6 +203,60 @@ export const pauseRuntime = async (token, podName, baseUrl = DEFAULT_SERVICE_URL
         ...(body ? { body } : {}),
     });
 };
+/**
+ * List persisted memories from the runtimes API.
+ *
+ * Non-admin callers are automatically scoped to their own personal account by
+ * the backend, even when ``userId`` is omitted.
+ */
+export const listRuntimeMemories = async (token, options = {}, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    const query = new URLSearchParams();
+    if (options.userId?.trim()) {
+        query.set('user_id', options.userId.trim());
+    }
+    if (options.agentId?.trim()) {
+        query.set('agent_id', options.agentId.trim());
+    }
+    if (typeof options.limit === 'number' && Number.isFinite(options.limit)) {
+        query.set('limit', String(Math.max(1, Math.min(1000, Math.floor(options.limit)))));
+    }
+    if (typeof options.offset === 'number' && Number.isFinite(options.offset)) {
+        query.set('offset', String(Math.max(0, Math.floor(options.offset))));
+    }
+    const qs = query.toString();
+    const response = await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/memories${qs ? `?${qs}` : ''}`,
+        method: 'GET',
+        token,
+    });
+    return {
+        success: Boolean(response?.success),
+        message: response?.message,
+        count: Number(response?.count ?? 0),
+        limit: Number(response?.limit ?? options.limit ?? 100),
+        offset: Number(response?.offset ?? options.offset ?? 0),
+        user_id: response?.user_id,
+        memories: Array.isArray(response?.memories) ? response.memories : [],
+    };
+};
+/**
+ * Fetch one persisted memory by id from the runtimes API.
+ */
+export const getRuntimeMemory = async (token, memoryId, baseUrl = DEFAULT_SERVICE_URLS.RUNTIMES) => {
+    validateToken(token);
+    validateRequiredString(memoryId, 'Memory id');
+    const response = await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.RUNTIMES}/memories/${encodeURIComponent(memoryId)}`,
+        method: 'GET',
+        token,
+    });
+    return {
+        success: Boolean(response?.success),
+        message: response?.message,
+        memory: response?.memory,
+    };
+};
 /**
  * Resume a paused runtime by restoring from a checkpoint (async).
  *

package/lib/chat/Chat.d.ts

@@ -10,6 +10,19 @@ export interface ChatProps extends ChatCommonProps {
     extensions?: Extension[];
     /** Base URL of the server (for HTTP-based protocols) */
     baseUrl?: string;
+    /**
+     * Explicit endpoint URL override. When set, it is used verbatim instead of
+     * deriving `${baseUrl}${getEndpointPath(protocol, agentId)}`. Useful for
+     * proxied endpoints such as the Agent Node tunnel proxy.
+     */
+    endpoint?: string;
+    /**
+     * Explicit config endpoint override. When provided (including `null`/empty
+     * to disable), it replaces the default `${baseUrl}/api/v1/configure`.
+     */
+    configEndpoint?: string;
+    /** Override whether the protocol queries the backend for models/tools. */
+    enableConfigQuery?: boolean;
     /** WebSocket URL (for WebSocket-based protocols like ACP) */
     wsUrl?: string;
     /** Agent ID */
@@ -94,5 +107,5 @@ export interface ChatProps extends ChatCommonProps {
  * />
  * ```
  */
-export declare function Chat({ protocol: transport, extensions: _extensions, baseUrl, wsUrl, agentId, authToken: authTokenProp, placeholder, title, subtitle, brandIcon, autoConnect, streaming: _streaming, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height, showHeader, showNewChatButton, showClearButton, showModelSelector, showToolsMenu, showInput, disableInputPrompt, overlay, launching, launchingMessage, showSkillsMenu, codemodeEnabled, onToggleCodemode, showTokenUsage, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount, suggestions, submitOnSuggestionClick, description, headerContent, headerActions, autoFocus, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation, chatViewMode, onChatViewModeChange, frontendTools, enableEphemeralNotebook, initialEphemeralNotebookOpen, onEphemeralNotebookOpenChange, enableEphemeralDocument, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed, onExpandFromCollapsed, ephemeralNotebookToolbar, onToolCallStart, onToolCallComplete, renderToolResult, hideMessagesAfterToolUI, contextSnapshot, mcpStatusData, codemodeStatusData, sandboxStatusData, kernel, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, disableInternalJupyterTheme, }: ChatProps): import("react/jsx-runtime").JSX.Element;
+export declare function Chat({ protocol: transport, extensions: _extensions, baseUrl, endpoint: endpointProp, configEndpoint: configEndpointProp, enableConfigQuery: enableConfigQueryProp, wsUrl, agentId, authToken: authTokenProp, placeholder, title, subtitle, brandIcon, autoConnect, streaming: _streaming, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height, showHeader, showNewChatButton, showClearButton, showModelSelector, showToolsMenu, showInput, disableInputPrompt, overlay, launching, launchingMessage, showSkillsMenu, codemodeEnabled, onToggleCodemode, showTokenUsage, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount, suggestions, submitOnSuggestionClick, description, headerContent, headerActions, autoFocus, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation, chatViewMode, onChatViewModeChange, frontendTools, enableEphemeralNotebook, initialEphemeralNotebookOpen, onEphemeralNotebookOpenChange, enableEphemeralDocument, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, onToolCallStart, onToolCallComplete, renderToolResult, hideMessagesAfterToolUI, contextSnapshot, mcpStatusData, codemodeStatusData, sandboxStatusData, kernel, kernelIndicatorPlacement, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, themeVariant, colorMode, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, disableInternalJupyterTheme, }: ChatProps): import("react/jsx-runtime").JSX.Element;
 export default Chat;

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, kernelIndicatorPlacement, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, themeVariant, colorMode, 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, kernelIndicatorPlacement: kernelIndicatorPlacement, kernelEnvironmentName: kernelEnvironmentName, kernelCpu: kernelCpu, kernelMemory: kernelMemory, kernelGpu: kernelGpu, themeVariant: themeVariant, colorMode: colorMode, 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';
@@ -112,12 +112,14 @@ const ThemedJupyterReactTheme = JupyterReactTheme;
  *   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);
+function ThemedChatBoundary({ children, themeVariant, colorMode, }) {
+    const storeColorMode = useThemeStore(s => s.colorMode);
+    const storeThemeVariant = useThemeStore(s => s.theme);
+    const resolvedColorMode = colorMode ?? storeColorMode;
+    const resolvedThemeVariant = themeVariant ?? storeThemeVariant;
     const systemMode = useSystemColorMode();
-    const themeConfig = getThemeConfig(themeVariant);
-    const resolvedMode = colorMode === 'auto' ? systemMode : colorMode;
+    const themeConfig = getThemeConfig(resolvedThemeVariant);
+    const resolvedMode = resolvedColorMode === 'auto' ? systemMode : resolvedColorMode;
     const modeStyles = resolvedMode === 'dark'
         ? themeConfig.themeStyles.dark
         : themeConfig.themeStyles.light;
@@ -432,7 +434,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, disableInternalJupyterTheme = false, } = props;
+    const { agentRuntimeConfig, protocol: protocolProp, useStore: useStoreMode = true, disableInternalJupyterTheme = false, themeVariant, colorMode, } = props;
     // Resolve protocol: string Protocol overrides type in agentRuntimeConfig or
     // is combined with a full ProtocolConfig object.
     const protocolType = typeof protocolProp === 'string' ? protocolProp : undefined;
@@ -459,7 +461,7 @@ export function ChatBase(props) {
         useStore: effectiveUseStoreMode,
     };
     const content = _jsx(ChatBaseInner, { ...innerProps });
-    const wrappedContent = disableInternalJupyterTheme ? (content) : (_jsx(ThemedChatBoundary, { children: content }));
+    const wrappedContent = disableInternalJupyterTheme ? (content) : (_jsx(ThemedChatBoundary, { themeVariant: themeVariant, colorMode: colorMode, children: content }));
     if (!existingQueryClient) {
         return (_jsx(QueryClientProvider, { client: internalQueryClient, children: wrappedContent }));
     }
@@ -468,11 +470,11 @@ export function ChatBase(props) {
 // ---------------------------------------------------------------------------
 // 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, 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, 
+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, kernelIndicatorPlacement = 'left', kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, themeVariant, colorMode, 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: 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 +512,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 +528,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 +588,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 &&
@@ -861,6 +885,10 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         requestAiAgentsApprovalHistory,
         sendAiAgentsApprovalDecision,
     ]);
+    // Assigned once `applyServerApprovalDecision` is defined below. A ref lets the
+    // ai-agents approval WS effect (declared earlier) drive the deferred-run
+    // continuation without re-subscribing when the callback identity changes.
+    const applyServerApprovalDecisionRef = useRef(null);
     const reconcileResolvedApprovalInStore = useCallback((approval) => {
         const state = agentRuntimeStore.getState();
         const removalIds = new Set([approval.id]);
@@ -966,7 +994,24 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                 }
                 const state = agentRuntimeStore.getState();
                 for (const record of records) {
-                    const approval = normalizeApprovalPayload(record);
+                    let approval = normalizeApprovalPayload(record);
+                    // SaaS-resolved events (tool_approval_approved/rejected) can arrive
+                    // with only {approvalId, status} and no tool_name/tool_args. Recover
+                    // the full envelope from the store (populated by the earlier pending
+                    // event) so the card clears AND the deferred run can resume.
+                    if (!approval) {
+                        const rawId = (typeof record.id === 'string' && record.id) ||
+                            (typeof record.approval_id === 'string' && record.approval_id) ||
+                            (typeof record.approvalId === 'string' && record.approvalId) ||
+                            '';
+                        const rawStatus = (typeof record.status === 'string' && record.status) || '';
+                        if (rawId && rawStatus && rawStatus !== 'pending') {
+                            const stored = state.approvals.find(a => a.id === rawId);
+                            if (stored) {
+                                approval = { ...stored, status: rawStatus };
+                            }
+                        }
+                    }
                     if (!approval) {
                         continue;
                     }
@@ -996,6 +1041,11 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                     }
                     else {
                         reconcileResolvedApprovalInStore(scopedApproval);
+                        // Resume the deferred tool call when the decision was made on
+                        // another surface (e.g. the SaaS Tool Approvals UI). Without this
+                        // the pending card clears but pydantic-ai never receives the
+                        // client continuation and the run stays parked.
+                        applyServerApprovalDecisionRef.current?.(scopedApproval, scopedApproval.status === 'approved', scopedApproval.note ?? undefined);
                     }
                 }
             }
@@ -1237,13 +1287,16 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         });
         return true;
     }, [activeAgentId]);
+    applyServerApprovalDecisionRef.current = applyServerApprovalDecision;
     // ---- Agent-runtime WebSocket (monitoring stream) ----
     // Derive the bare base URL from configEndpoint or protocol.endpoint.
+    const isAgentNodeTunnelAgUi = Boolean(protocol?.endpoint &&
+        /\/api\/runtimes\/v1\/agent-nodes\/[^/]+\/ag-ui\/?$/.test(protocol.endpoint));
     const wsBaseUrl = protocol?.configEndpoint
         ? protocol.configEndpoint.replace(/\/api\/v1\/(config|configure)\/?$/, '')
         : (protocol?.endpoint?.replace(/\/api\/v1\/.*$/, '') ?? '');
     useAgentRuntimeWebSocket({
-        enabled: !!protocol && !!wsBaseUrl,
+        enabled: !!protocol && !!wsBaseUrl && !isAgentNodeTunnelAgUi,
         baseUrl: wsBaseUrl,
         authToken: protocol?.authToken,
         agentId: protocol?.agentId,
@@ -2418,7 +2471,11 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             pendingPromptSentRef.current = pendingPromptKey;
             return;
         }
-        if (!historyLoaded)
+        // Do not block prompt replay forever when runtime history cannot be fetched
+        // (e.g. websocket not connected yet/anymore). In that case we fall back to
+        // submitting once the adapter is ready.
+        const canProceedWithoutHistory = !historyScopeId || wsState !== 'connected';
+        if (!historyLoaded && !canProceedWithoutHistory)
             return;
         if (!adapterReady && !onSendMessage)
             return;
@@ -2431,6 +2488,8 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         pendingPrompt,
         pendingPromptKey,
         historyLoaded,
+        historyScopeId,
+        wsState,
         adapterReady,
         handleSend,
         onSendMessage,
@@ -2827,7 +2886,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, kernelIndicatorPlacement: kernelIndicatorPlacement, 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 +2937,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, themeVariant: themeVariant, colorMode: colorMode, nbformat: persistedEphemeralNbformat ?? undefined, onNbformatChange: handleEphemeralNotebookChange, toolbarComponent: ephemeralNotebookToolbar, collaborationProvider: ephemeralNotebookCollaborationProvider })) : (_jsx(React.Suspense, { fallback: null, children: _jsx(EphemeralDocument, { documentId: ephemeralDocumentId, runtimePodName: runtimeId || activeAgentId, runtimeOverride: ephemeralRuntimeOverride, themeVariant: themeVariant, colorMode: colorMode, 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,34 @@ 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 theme variant override from host chat context. */
+    themeVariant?: string;
+    /** Optional color mode override from host chat context. */
+    colorMode?: 'light' | 'dark' | 'auto';
     /** 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, themeVariant, colorMode, content, onContentChange, onToolsReady, onKernelChange, collaboration, }: EphemeralDocumentProps): import("react/jsx-runtime").JSX.Element;
 export default EphemeralDocument;