@datalayer/agent-runtimes 1.0.10 → 1.0.18

package/lib/chat/display/EmptyState.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Text, LabelGroup, Label, Truncate } from '@primer/react';
+import { Text, LabelGroup, Label, Truncate, ThemeProvider, } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { AiAgentIcon } from '@datalayer/icons-react';
 // ---------------------------------------------------------------------------
@@ -18,24 +18,24 @@ export function ChatEmptyState({ emptyState, brandIcon, description, suggestions
             onSuggestionFill?.(suggestion.message);
         }
     };
-    return (_jsxs(Box, { sx: {
-            display: 'flex',
-            flexDirection: 'column',
-            alignItems: 'center',
-            justifyContent: 'center',
-            height: '100%',
-            p: 4,
-            color: 'fg.muted',
-            textAlign: 'center',
-            gap: 2,
-        }, children: [emptyState?.icon || brandIcon || _jsx(AiAgentIcon, { colored: true, size: 48 }), _jsx(Text, { sx: { fontSize: 2 }, children: emptyState?.title || 'Start a conversation' }), (emptyState?.subtitle || description) && (_jsx(Text, { sx: { fontSize: 1 }, children: emptyState?.subtitle || description })), suggestions && suggestions.length > 0 && (_jsx(LabelGroup, { sx: { mt: 2, justifyContent: 'center' }, children: suggestions.map((suggestion, index) => (_jsx(Label, { variant: "accent", title: suggestion.title, sx: {
-                        cursor: 'pointer',
-                        display: 'inline-flex',
-                        alignItems: 'center',
-                        '&:hover': {
-                            bg: 'accent.emphasis',
-                            color: 'var(--button-primary-fgColor-rest)',
-                            borderColor: 'accent.emphasis',
-                        },
-                    }, onClick: () => handleSuggestionClick(suggestion), children: _jsx(Box, { sx: { width: 140, maxWidth: 140, minWidth: 140 }, children: _jsx(Truncate, { title: suggestion.title, maxWidth: "100%", children: suggestion.title }) }) }, index))) }))] }));
+    return (_jsx(ThemeProvider, { children: _jsxs(Box, { sx: {
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                justifyContent: 'center',
+                height: '100%',
+                p: 4,
+                color: 'fg.muted',
+                textAlign: 'center',
+                gap: 2,
+            }, children: [emptyState?.icon || brandIcon || _jsx(AiAgentIcon, { colored: true, size: 48 }), _jsx(Text, { sx: { fontSize: 2 }, children: emptyState?.title || 'Start a conversation' }), (emptyState?.subtitle || description) && (_jsx(Text, { sx: { fontSize: 1 }, children: emptyState?.subtitle || description })), suggestions && suggestions.length > 0 && (_jsx(LabelGroup, { sx: { mt: 2, justifyContent: 'center' }, children: suggestions.map((suggestion, index) => (_jsx(Label, { variant: "accent", title: suggestion.title, sx: {
+                            cursor: 'pointer',
+                            display: 'inline-flex',
+                            alignItems: 'center',
+                            '&:hover': {
+                                bg: 'accent.emphasis',
+                                color: 'var(--button-primary-fgColor-rest)',
+                                borderColor: 'accent.emphasis',
+                            },
+                        }, onClick: () => handleSuggestionClick(suggestion), children: _jsx(Box, { sx: { width: 140, maxWidth: 140, minWidth: 140 }, children: _jsx(Truncate, { title: suggestion.title, maxWidth: "100%", children: suggestion.title }) }) }, index))) }))] }) }));
 }

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

@@ -0,0 +1,23 @@
+import type { FrontendToolDefinition } from '../../types/tools';
+import '@datalayer/jupyter-react/lib/css/PrismCss';
+import '@datalayer/jupyter-lexical/style/index.css';
+export interface EphemeralDocumentProps {
+    /**
+     * Document identifier. Must match the id passed to `useLexicalTools` so the
+     * agent's lexical frontend tools operate on this document instance.
+     */
+    documentId: string;
+    /** Preferred runtime pod name to bind the document kernel to. */
+    runtimePodName?: string;
+    /** 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;
+}
+/**
+ * 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 default EphemeralDocument;

package/lib/chat/document/EphemeralDocument.js

@@ -0,0 +1,270 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * EphemeralDocument — an in-memory Lexical rich-text document rendered next to
+ * the chat.
+ *
+ * This is the document analogue of {@link EphemeralNotebook}. The Lexical
+ * editor state lives purely in memory and is mirrored into the agent-runtime
+ * Zustand store (`ephemeralDocumentModels`) so the document survives navigating
+ * away from and back to the same runtime page. While mounted, its lexical
+ * frontend tools are reported upward via `onToolsReady` so the agent can drive
+ * the document blocks (insert / update / delete / read).
+ *
+ * IMPORTANT: this module statically imports `@datalayer/jupyter-lexical`, which
+ * initialises Lumino-backed nodes on load. It is therefore lazy-loaded by
+ * `ChatBase` (via `React.lazy`) so notebook-only chats never pull in lexical.
+ *
+ * @module chat/document/EphemeralDocument
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+import { $getRoot, $createParagraphNode, } from 'lexical';
+import { LexicalComposer } from '@lexical/react/LexicalComposer';
+import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
+import { ContentEditable } from '@lexical/react/LexicalContentEditable';
+import { HistoryPlugin } from '@lexical/react/LexicalHistoryPlugin';
+import { OnChangePlugin } from '@lexical/react/LexicalOnChangePlugin';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary';
+import { AutoFocusPlugin } from '@lexical/react/LexicalAutoFocusPlugin';
+import { MarkdownShortcutPlugin } from '@lexical/react/LexicalMarkdownShortcutPlugin';
+import { TRANSFORMERS } from '@lexical/markdown';
+import { registerCodeHighlighting } from '@lexical/code';
+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 { 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 { editorConfig } from '../../examples/lexical/editorConfig';
+import { useLexicalTools } from '../../tools/adapters/agent-runtimes/lexicalHooks';
+import { useAgentsRuntimes } from '../../hooks/useAgentRuntimes';
+import { registerSandboxServiceManager } from '../../services/sandboxServiceManagers';
+import { useProgressTask } from '../../hooks/useProgressTask';
+import '@datalayer/jupyter-react/lib/css/PrismCss';
+import '@datalayer/jupyter-lexical/style/index.css';
+/**
+ * Lexical plugin that loads the initial (restored) editor state exactly once.
+ */
+function LoadContentPlugin({ content }) {
+    const [editor] = useLexicalComposerContext();
+    const isFirstRender = useRef(true);
+    useEffect(() => {
+        if (!isFirstRender.current) {
+            return;
+        }
+        isFirstRender.current = false;
+        if (!content) {
+            editor.update(() => {
+                const root = $getRoot();
+                if (root.getChildrenSize() === 0) {
+                    root.append($createParagraphNode());
+                }
+            }, { tag: 'history-merge' });
+            return;
+        }
+        try {
+            const parsed = JSON.parse(content);
+            if (parsed && typeof parsed === 'object' && parsed.root) {
+                const editorState = editor.parseEditorState(content);
+                editor.setEditorState(editorState, { tag: 'history-merge' });
+            }
+            else {
+                throw new Error('Invalid Lexical editor state format');
+            }
+        }
+        catch {
+            editor.update(() => {
+                const root = $getRoot();
+                root.clear();
+                root.append($createParagraphNode());
+            }, { tag: 'history-merge' });
+        }
+    }, [content, editor]);
+    return null;
+}
+/** Registers code syntax highlighting for code blocks. */
+function CodeHighlightPlugin() {
+    const [editor] = useLexicalComposerContext();
+    useEffect(() => registerCodeHighlighting(editor), [editor]);
+    return null;
+}
+/**
+ * Top document toolbar mirroring the notebook/document editor toolbar. Reads
+ * the active editor from the Lexical composer context and drives the shared
+ * {@link ToolbarPlugin} (block type, formatting, insert menu, …).
+ */
+function DocumentToolbar({ setIsLinkEditMode, }) {
+    const [editor] = useLexicalComposerContext();
+    const [activeEditor, setActiveEditor] = useState(editor);
+    return (_jsx(ToolbarPlugin, { editor: editor, activeEditor: activeEditor, setActiveEditor: setActiveEditor, setIsLinkEditMode: setIsLinkEditMode }));
+}
+/**
+ * Renders an in-memory Lexical document backed by a sandbox kernel.
+ */
+export function EphemeralDocument({ documentId, runtimePodName, content, onContentChange, onToolsReady, }) {
+    // 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);
+    const initialDocumentIdRef = useRef(documentId);
+    if (initialDocumentIdRef.current !== documentId) {
+        initialDocumentIdRef.current = documentId;
+        initialContentRef.current = content;
+    }
+    const initialContent = initialContentRef.current;
+    // Hash of the last content we persisted, so onChange only writes on change.
+    const lastSavedHashRef = useRef(initialContent ?? '');
+    // Lexical frontend tools scoped to this document. Reported upward so the
+    // agent can drive the document while it is visible.
+    const lexicalTools = useLexicalTools(documentId);
+    useEffect(() => {
+        onToolsReady?.(lexicalTools);
+    }, [lexicalTools, onToolsReady]);
+    // 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 selectedRuntime = useMemo(() => {
+        const preferredPod = String(runtimePodName || '').trim();
+        if (!preferredPod) {
+            return undefined;
+        }
+        return runtimes.find(rt => String(rt?.pod_name || '') === preferredPod);
+    }, [runtimePodName, runtimes]);
+    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.
+    const [documentKernel, setDocumentKernel] = useState(undefined);
+    useEffect(() => {
+        let cancelled = false;
+        let manager = null;
+        let unregisterManager = null;
+        const connectRuntime = async () => {
+            const baseUrl = String(selectedRuntime?.url || '').trim();
+            if (!baseUrl) {
+                if (!cancelled) {
+                    setRuntimeServiceManager(null);
+                    setDocumentKernel(undefined);
+                }
+                return;
+            }
+            try {
+                const token = String(selectedRuntime?.token || '').trim();
+                const serverSettings = ServerConnection.makeSettings({
+                    baseUrl,
+                    wsUrl: baseUrl.replace(/^http/, 'ws'),
+                    token,
+                    appendToken: true,
+                });
+                manager = new ServiceManager({ serverSettings });
+                // Central sandbox registry: runtime terminate/pause disposes this
+                // manager immediately so its pollers cannot hit the dead pod ingress.
+                unregisterManager = registerSandboxServiceManager(String(selectedRuntime?.pod_name || ''), manager);
+                await manager.ready;
+                const kernelConnection = await manager.kernels.startNew();
+                if (!cancelled) {
+                    const kernel = new Kernel({
+                        kernelName: kernelConnection.model.name,
+                        kernelSpecName: kernelConnection.model.name,
+                        kernelModel: kernelConnection.model,
+                        kernelManager: manager.kernels,
+                        kernelspecsManager: manager.kernelspecs,
+                        sessionManager: manager.sessions,
+                    });
+                    setRuntimeServiceManager(manager);
+                    setDocumentKernel(kernel);
+                }
+            }
+            catch {
+                if (!cancelled) {
+                    setRuntimeServiceManager(null);
+                    setDocumentKernel(undefined);
+                }
+            }
+        };
+        connectRuntime();
+        return () => {
+            cancelled = true;
+            unregisterManager?.();
+            if (manager) {
+                disposeServiceManager(manager);
+            }
+        };
+    }, [selectedRuntime?.pod_name, selectedRuntime?.url, selectedRuntime?.token]);
+    const activeServiceManager = runtimeServiceManager;
+    const isRuntimeStarting = Boolean(String(runtimePodName || '').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.
+    const initialConfig = useMemo(() => {
+        // Drop the demo `editorState` and the examples `lexicalTheme`. Use the
+        // shared `commentTheme` (same as the document editor) so the Jupyter cell
+        // and rich-text nodes get the class names styled by jupyter-lexical CSS.
+        const { editorState: _ignored, theme: _theme, ...rest } = editorConfig;
+        return {
+            ...rest,
+            theme: commentTheme,
+            namespace: `ephemeral-document-${documentId}`,
+        };
+    }, [documentId]);
+    const handleChange = useCallback((editorState) => {
+        if (!onContentChange) {
+            return;
+        }
+        const json = JSON.stringify(editorState.toJSON());
+        if (json === lastSavedHashRef.current) {
+            return;
+        }
+        lastSavedHashRef.current = json;
+        onContentChange(json);
+    }, [onContentChange]);
+    const [floatingAnchorElem, setFloatingAnchorElem] = useState(null);
+    const [, setIsLinkEditMode] = useState(false);
+    const onAnchorRef = (elem) => {
+        if (elem !== null) {
+            setFloatingAnchorElem(elem);
+        }
+    };
+    // 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 systemMode = useSystemColorMode();
+    const themeConfig = getThemeConfig(themeVariant);
+    const resolvedMode = colorMode === 'auto' ? systemMode : colorMode;
+    const modeStyles = resolvedMode === 'dark'
+        ? themeConfig.themeStyles.dark
+        : themeConfig.themeStyles.light;
+    const themeBackground = modeStyles.backgroundColor ?? '';
+    return (_jsx(Box, { sx: {
+            flex: 1,
+            minHeight: 0,
+            height: '100%',
+            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: {
+                        position: 'absolute',
+                        inset: 0,
+                        display: 'flex',
+                        flexDirection: 'column',
+                        overflow: 'auto',
+                        overscrollBehaviorY: 'contain',
+                        padding: 2,
+                        '& .editor-shell': {
+                            backgroundColor: themeBackground,
+                            borderRadius: 2,
+                        },
+                        '& .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 }));
+}
+export default EphemeralDocument;

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

@@ -10,7 +10,7 @@
 import { type ReactNode } from 'react';
 import { type ExecutionState } from '@datalayer/jupyter-react';
 import type { IKernelConnection } from '@jupyterlab/services/lib/kernel/kernel';
-import type { ChatViewMode, HeaderButtonsConfig } from '../../types/chat';
+import type { ChatViewMode, EphemeralSurfaceMode, HeaderButtonsConfig } from '../../types/chat';
 import type { SandboxStatusData } from '../../types/context';
 import type { SandboxWsStatus } from '../../types/sandbox';
 type RuntimeStatus = SandboxStatusData | SandboxWsStatus;
@@ -58,6 +58,16 @@ export interface ChatBaseHeaderProps {
     chatViewMode?: ChatViewMode;
     /** Callback when view mode changes */
     onChatViewModeChange?: (mode: ChatViewMode) => void;
+    /** Show the companion-surface segmented control (None / Notebook / Document). */
+    showEphemeralSurfaceControl?: boolean;
+    /** Whether the Notebook option is available in the surface control. */
+    enableEphemeralNotebookOption?: boolean;
+    /** Whether the Document option is available in the surface control. */
+    enableEphemeralDocumentOption?: boolean;
+    /** Current companion-surface mode. */
+    ephemeralSurfaceMode?: EphemeralSurfaceMode;
+    /** 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, }: ChatBaseHeaderProps): import("react/jsx-runtime").JSX.Element;
+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 {};

package/lib/chat/header/ChatHeaderBase.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Heading, IconButton, Text, Truncate } from '@primer/react';
+import { Heading, IconButton, Text, Tooltip, Truncate } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { KernelIndicator } from '@datalayer/jupyter-react';
-import { PlusIcon, TrashIcon, GearIcon, CommentDiscussionIcon, DeviceMobileIcon, SidebarExpandIcon, InfoIcon, } from '@primer/octicons-react';
+import { PlusIcon, TrashIcon, GearIcon, CommentDiscussionIcon, DeviceMobileIcon, SidebarExpandIcon, InfoIcon, RowsIcon, FileIcon, CircleSlashIcon, } from '@primer/octicons-react';
 import { AiAgentIcon } from '@datalayer/icons-react';
 export function toRuntimeExecutionState(runtimeStatus) {
     if (!runtimeStatus) {
@@ -29,7 +29,7 @@ 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, }) {
+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, }) {
     const effectiveIndicatorState = kernelIndicatorState ?? toRuntimeExecutionState(runtimeStatus);
     return (_jsx(Box, { sx: {
             display: 'flex',
@@ -47,7 +47,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 }), (title || subtitle) && (_jsxs(Box, { sx: {
+                    }, 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: {
                                 display: 'flex',
                                 flexDirection: 'column',
                                 minWidth: 0,
@@ -62,7 +62,60 @@ 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: [kernel ? (_jsx(KernelIndicator, { kernel: kernel, environmentName: kernelEnvironmentName, cpu: kernelCpu, memory: kernelMemory, gpu: kernelGpu, position: "sw", bordered: false })) : (_jsx(KernelIndicator, { state: effectiveIndicatorState ?? 'undefined', environmentName: kernelEnvironmentName, cpu: kernelCpu, memory: kernelMemory, gpu: kernelGpu, position: "sw", bordered: false })), 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 })), chatViewMode && onChatViewModeChange && (_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 }))] }), _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: {
+                                display: 'inline-flex',
+                                alignItems: 'center',
+                                bg: 'neutral.muted',
+                                borderRadius: '6px',
+                                p: '2px',
+                                gap: '1px',
+                            }, children: [
+                                {
+                                    mode: 'none',
+                                    icon: CircleSlashIcon,
+                                    label: 'Chat only',
+                                    enabled: true,
+                                },
+                                {
+                                    mode: 'notebook',
+                                    icon: RowsIcon,
+                                    label: 'Notebook',
+                                    enabled: enableEphemeralNotebookOption,
+                                },
+                                {
+                                    mode: 'document',
+                                    icon: FileIcon,
+                                    label: 'Document',
+                                    enabled: enableEphemeralDocumentOption,
+                                },
+                            ]
+                                .filter(({ enabled }) => enabled)
+                                .map(({ mode, icon: ModeIcon, label }) => (_jsx(Tooltip, { text: label, direction: "n", children: _jsx(Box, { as: "button", "aria-label": label, onClick: () => onEphemeralSurfaceModeChange?.(mode), sx: {
+                                        display: 'inline-flex',
+                                        alignItems: 'center',
+                                        justifyContent: 'center',
+                                        width: 26,
+                                        height: 24,
+                                        borderRadius: '4px',
+                                        border: 'none',
+                                        cursor: 'pointer',
+                                        bg: ephemeralSurfaceMode === mode
+                                            ? 'canvas.default'
+                                            : 'transparent',
+                                        boxShadow: ephemeralSurfaceMode === mode
+                                            ? 'shadow.small'
+                                            : 'none',
+                                        color: ephemeralSurfaceMode === mode
+                                            ? 'fg.default'
+                                            : 'fg.muted',
+                                        transition: 'all 0.15s ease',
+                                        '&:hover': {
+                                            color: 'fg.default',
+                                            bg: ephemeralSurfaceMode === mode
+                                                ? 'canvas.default'
+                                                : 'neutral.subtle',
+                                        },
+                                    }, children: _jsx(ModeIcon, { size: 14 }) }) }, mode))) })), chatViewMode && onChatViewModeChange && (_jsx(Box, { sx: {
                                 display: 'inline-flex',
                                 alignItems: 'center',
                                 bg: 'neutral.muted',
@@ -85,24 +138,26 @@ export function ChatBaseHeader({ title, subtitle, brandIcon, headerContent, head
                                     icon: SidebarExpandIcon,
                                     label: 'Sidebar panel',
                                 },
-                            ].map(({ mode, icon: ModeIcon, label }) => (_jsx(Box, { as: "button", "aria-label": label, title: label, onClick: () => onChatViewModeChange(mode), sx: {
-                                    display: 'inline-flex',
-                                    alignItems: 'center',
-                                    justifyContent: 'center',
-                                    width: 26,
-                                    height: 24,
-                                    borderRadius: '4px',
-                                    border: 'none',
-                                    cursor: 'pointer',
-                                    bg: chatViewMode === mode ? 'canvas.default' : 'transparent',
-                                    boxShadow: chatViewMode === mode ? 'shadow.small' : 'none',
-                                    color: chatViewMode === mode ? 'fg.default' : 'fg.muted',
-                                    transition: 'all 0.15s ease',
-                                    '&:hover': {
-                                        color: 'fg.default',
+                            ].map(({ mode, icon: ModeIcon, label }) => (_jsx(Tooltip, { text: label, direction: "n", children: _jsx(Box, { as: "button", "aria-label": label, onClick: () => onChatViewModeChange(mode), sx: {
+                                        display: 'inline-flex',
+                                        alignItems: 'center',
+                                        justifyContent: 'center',
+                                        width: 26,
+                                        height: 24,
+                                        borderRadius: '4px',
+                                        border: 'none',
+                                        cursor: 'pointer',
                                         bg: chatViewMode === mode
                                             ? 'canvas.default'
-                                            : 'neutral.subtle',
-                                    },
-                                }, children: _jsx(ModeIcon, { size: 14 }) }, mode))) })), headerActions] })] }) }));
+                                            : 'transparent',
+                                        boxShadow: chatViewMode === mode ? 'shadow.small' : 'none',
+                                        color: chatViewMode === mode ? 'fg.default' : 'fg.muted',
+                                        transition: 'all 0.15s ease',
+                                        '&:hover': {
+                                            color: 'fg.default',
+                                            bg: chatViewMode === mode
+                                                ? 'canvas.default'
+                                                : 'neutral.subtle',
+                                        },
+                                    }, children: _jsx(ModeIcon, { size: 14 }) }) }, mode))) })), headerActions] })] }) }));
 }

package/lib/chat/index.d.ts

@@ -64,3 +64,4 @@ export { ToolApprovalBanner, type ToolApprovalBannerProps, type PendingApproval,
 export { Chat, type ChatProps } from './Chat';
 export { ChatFloating, type ChatFloatingProps } from './ChatFloating';
 export { ChatInline, type ChatInlineProps, type ChatInlineProtocolConfig, } from './ChatInline';
+export { AgentRuntimeChat, type AgentRuntimeChatProps, } from '../agents/AgentRuntimeChat';

package/lib/chat/index.js

@@ -72,3 +72,5 @@ export { ToolApprovalBanner, } from './tools/ToolApprovalBanner';
 export { Chat } from './Chat';
 export { ChatFloating } from './ChatFloating';
 export { ChatInline, } from './ChatInline';
+// Generic full-page chat surface for a live agent runtime (with launching state)
+export { AgentRuntimeChat, } from '../agents/AgentRuntimeChat';

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

@@ -0,0 +1,24 @@
+import type { INotebookContent } from '@jupyterlab/nbformat';
+import type { EphemeralNotebookToolbarComponent } from '../../types/chat';
+export interface EphemeralNotebookProps {
+    /**
+     * Notebook identifier. Must match the id passed to `useNotebookTools` so the
+     * agent's notebook frontend tools operate on this notebook instance.
+     */
+    notebookId: string;
+    /** Preferred runtime pod name to bind the notebook kernel to. */
+    runtimePodName?: string;
+    /** Left margin reserved for the cell sidebar (default 120). */
+    cellSidebarMargin?: number;
+    /** Optional persisted notebook model to restore when mounting. */
+    nbformat?: INotebookContent;
+    /** Callback fired when the notebook model changes. */
+    onNbformatChange?: (content: INotebookContent) => void;
+    /** Optional toolbar component override. */
+    toolbarComponent?: EphemeralNotebookToolbarComponent;
+}
+/**
+ * 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 default EphemeralNotebook;