@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/examples/NotebookAgentSidebarExample.js

@@ -4,7 +4,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * Agent Runtime Notebook Example - Chat with Jupyter Notebook.
+ * Notebook Agent Sidebar Example - Chat with Jupyter Notebook.
  *
  * This example demonstrates using the chat component with:
  * - Jupyter Notebook integration
@@ -19,41 +19,20 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  *
  * @module examples/NotebookAgentSidebarExample
  */
-import { useEffect, useMemo, useState } from 'react';
 import { Box } from '@datalayer/primer-addons';
-import { Notebook, useJupyter } from '@datalayer/jupyter-react';
+import { Notebook } from '@datalayer/jupyter-react';
 import { useNotebookTools } from '../tools/adapters/agent-runtimes/notebookHooks';
-import { ThemedJupyterProvider } from './utils/themedProvider';
+import { ThemedJupyterProvider, ThemedProvider } from './utils/themedProvider';
 import { ChatSidebar } from '../chat';
-import { DEFAULT_MODEL } from '../specs';
-import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
-import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
+import { useExampleJupyterAgent } from './hooks/useExampleJupyterAgent';
 import MatplotlibNotebook from './utils/notebooks/Matplotlib.ipynb.json';
+import { ExampleNotebookToolbar } from './utils/notebookToolbarItems';
 // Fixed notebook ID
 const NOTEBOOK_ID = 'chat-notebook-example';
 // Use the imported Matplotlib notebook
 const NOTEBOOK_CONTENT = MatplotlibNotebook;
 // Default configuration
 const DEFAULT_AGENT_ID = import.meta.env.VITE_AGENT_ID || 'notebook-sidebar-agent-runtime-example';
-function getJupyterSandboxUrl(serviceManager) {
-    const envUrl = import.meta.env.VITE_JUPYTER_SANDBOX_URL;
-    if (envUrl) {
-        return envUrl;
-    }
-    const baseUrl = serviceManager?.serverSettings?.baseUrl?.replace(/\/$/, '');
-    if (!baseUrl) {
-        return undefined;
-    }
-    if (baseUrl.includes('token=')) {
-        return baseUrl;
-    }
-    const token = serviceManager?.serverSettings?.token;
-    if (!token) {
-        return baseUrl;
-    }
-    const separator = baseUrl.includes('?') ? '&' : '?';
-    return `${baseUrl}${separator}token=${encodeURIComponent(token)}`;
-}
 function NotebookUI({ serviceManager }) {
     if (!serviceManager) {
         return (_jsx(Box, { sx: {
@@ -64,59 +43,34 @@ function NotebookUI({ serviceManager }) {
                 color: 'fg.muted',
             }, children: "Loading Simple services..." }));
     }
-    return (_jsx(Notebook, { nbformat: NOTEBOOK_CONTENT, id: NOTEBOOK_ID, serviceManager: serviceManager, height: "100%", cellSidebarMargin: 120, startDefaultKernel: true }));
+    return (
+    // Only the notebook is wrapped. `JupyterReactTheme` nests a Primer theme
+    // of its own, so wrapping the example in it made every surface around the
+    // notebook — header, sidebar, error panel — read `canvas.default` from
+    // Primer's stock light palette rather than from the chosen theme, which is
+    // what showed as a white background.
+    _jsx(ThemedJupyterProvider, { fullHeight: true, children: _jsx(Notebook, { nbformat: NOTEBOOK_CONTENT, id: NOTEBOOK_ID, Toolbar: ExampleNotebookToolbar, serviceManager: serviceManager, height: "100%", cellSidebarMargin: 120, startDefaultKernel: true }) }));
 }
 export function AgentRuntimeNotebookExampleInner({ serviceManager, }) {
-    const baseUrl = useExampleAgentRuntimesUrl();
-    const vercelAiEndpoint = `${baseUrl}/api/v1/vercel-ai/${DEFAULT_AGENT_ID}`;
-    const [createRequested, setCreateRequested] = useState(false);
-    const jupyterSandboxUrl = useMemo(() => getJupyterSandboxUrl(serviceManager), [serviceManager]);
-    const { agentId, isReady, status, error, createAgent } = useExampleAgentRuntime({
+    // The tools. Which of the chat and the harness runs them depends on
+    // where the loop turns, and the hook decides that.
+    const tools = useNotebookTools(NOTEBOOK_ID);
+    const { agentReady, protocol: protocolConfig, chatFrontendTools, error, unavailableReason, } = useExampleJupyterAgent({
         exampleId: 'NotebookAgentSidebarExample',
         agentName: DEFAULT_AGENT_ID,
-        autoCreateAgent: false,
-        agentConfig: {
-            name: DEFAULT_AGENT_ID,
-            description: 'Demo agent for notebook sidebar example',
-            protocol: 'vercel-ai',
-            model: DEFAULT_MODEL,
-            systemPrompt: 'You are a helpful AI assistant that helps users work with Jupyter notebooks. For notebook operations, always use the notebook frontend tools (runCell, readAllCells, readCell, insertCell, updateCell, deleteCells) so actions happen in the live notebook UI. Use executeCode only for temporary inspection code that should not modify notebook cells.',
-            enableCodemode: false,
-            sandboxVariant: 'jupyter',
-            jupyterSandbox: jupyterSandboxUrl,
-        },
+        description: 'Demo agent for notebook sidebar example',
+        systemPrompt: 'You are a helpful AI assistant that helps users work with Jupyter notebooks. For notebook operations, always use the notebook frontend tools (runCell, readAllCells, readCell, insertCell, updateCell, deleteCells) so actions happen in the live notebook UI. Use executeCodeInNotebook only for temporary inspection code that should not modify notebook cells.',
+        serviceManager,
+        frontendTools: tools,
     });
-    useEffect(() => {
-        if (!jupyterSandboxUrl || createRequested || agentId) {
-            return;
-        }
-        setCreateRequested(true);
-        void createAgent({
-            name: DEFAULT_AGENT_ID,
-            description: 'Demo agent for notebook sidebar example',
-            protocol: 'vercel-ai',
-            model: DEFAULT_MODEL,
-            systemPrompt: 'You are a helpful AI assistant that helps users work with Jupyter notebooks. For notebook operations, always use the notebook frontend tools (runCell, readAllCells, readCell, insertCell, updateCell, deleteCells) so actions happen in the live notebook UI. Use executeCode only for temporary inspection code that should not modify notebook cells.',
-            enableCodemode: false,
-            sandboxVariant: 'jupyter',
-            jupyterSandbox: jupyterSandboxUrl,
-        }).catch(() => {
-            setCreateRequested(false);
-        });
-    }, [jupyterSandboxUrl, createRequested, agentId, createAgent]);
-    const effectiveReady = isReady || status === 'ready';
+    // One failed attempt is reported, not retried — see
+    // `useExampleJupyterAgent`.
+    const chatError = error || unavailableReason;
+    // The example's own agent, not merely the runtime: on the cloud target the
+    // runtime is ready before this agent has been registered on it.
+    const effectiveReady = agentReady;
     // Get notebook tools for ChatSidebar
-    const tools = useNotebookTools(NOTEBOOK_ID);
     // Build Vercel AI protocol config
-    const protocolConfig = useMemo(() => {
-        return {
-            type: 'vercel-ai',
-            endpoint: vercelAiEndpoint,
-            agentId: DEFAULT_AGENT_ID,
-            enableConfigQuery: true,
-            configEndpoint: `${baseUrl}/api/v1/configure`,
-        };
-    }, [baseUrl, vercelAiEndpoint]);
     return (_jsx(_Fragment, { children: _jsxs(Box, { sx: {
                 height: 'calc(100vh - 70px)',
                 width: '100vw',
@@ -132,7 +86,7 @@ export function AgentRuntimeNotebookExampleInner({ serviceManager, }) {
                                 borderBottom: '1px solid',
                                 borderColor: 'border.default',
                                 bg: 'canvas.default',
-                            }, children: [_jsx("h1", { style: { margin: 0, fontSize: '1.5rem' }, children: "Agent Runtime Notebook Chat Sidebar Example" }), _jsx("p", { style: { margin: '8px 0 0', color: 'var(--fgColor-muted)' }, children: "Chat with Jupyter Notebook integration" })] }), _jsx(Box, { sx: {
+                            }, children: [_jsx("h1", { style: { margin: 0, fontSize: '1.5rem' }, children: "Notebook Chat Sidebar Example" }), _jsx("p", { style: { margin: '8px 0 0', color: 'var(--fgColor-muted)' }, children: "Chat with Jupyter Notebook integration" })] }), _jsx(Box, { sx: {
                                 flex: 1,
                                 display: 'flex',
                                 overflow: 'hidden',
@@ -146,7 +100,7 @@ export function AgentRuntimeNotebookExampleInner({ serviceManager, }) {
                                     overflow: 'hidden',
                                 }, children: _jsx(NotebookUI, { serviceManager: serviceManager }) }) })] }), effectiveReady && (_jsx(ChatSidebar, { title: "AI Assistant", protocol: protocolConfig, position: "right", width: 400, showNewChatButton: true, showClearButton: true, showSettingsButton: true, defaultOpen: true, panelProps: {
                         protocol: protocolConfig,
-                        frontendTools: tools,
+                        frontendTools: chatFrontendTools,
                         useStore: false,
                         showModelSelector: true,
                         showToolsMenu: true,
@@ -169,7 +123,7 @@ export function AgentRuntimeNotebookExampleInner({ serviceManager, }) {
                                 message: 'Can you suggest improvements for the code?',
                             },
                         ],
-                    } })), error && (_jsxs(Box, { sx: {
+                    } })), chatError && (_jsxs(Box, { sx: {
                         position: 'fixed',
                         bottom: 20,
                         right: 20,
@@ -179,16 +133,18 @@ export function AgentRuntimeNotebookExampleInner({ serviceManager, }) {
                         borderRadius: 2,
                         maxWidth: 320,
                         zIndex: 999,
-                    }, children: [_jsx("strong", { children: "Error:" }), " ", error] }))] }) }));
+                    }, children: [_jsx("strong", { children: "Error:" }), " ", chatError] }))] }) }));
 }
 /**
- * Main example component with Simple wrapper
+ * The example, in the app's theme.
+ *
+ * The service manager comes from the shell, as it does in every other example:
+ * the shell owns which of the four runtime targets is selected, and reading it
+ * from an ambient Jupyter provider instead — which is what this example used
+ * to do — meant it could be showing a notebook on a different runtime than the
+ * one the picker says.
  */
-export function AgentRuntimeNotebookAgentSidebarExample() {
-    return (_jsx(ThemedJupyterProvider, { children: _jsx(SimpleWrapper, {}) }));
-}
-function SimpleWrapper() {
-    const { serviceManager } = useJupyter();
-    return _jsx(AgentRuntimeNotebookExampleInner, { serviceManager: serviceManager });
+export function AgentRuntimeNotebookAgentSidebarExample({ serviceManager, }) {
+    return (_jsx(ThemedProvider, { children: _jsx(AgentRuntimeNotebookExampleInner, { serviceManager: serviceManager }) }));
 }
 export default AgentRuntimeNotebookAgentSidebarExample;

package/lib/examples/NotebookCollaborationExample.d.ts

@@ -12,5 +12,5 @@ import { ServiceManager } from '@jupyterlab/services';
 type INotebookCollaborationExampleProps = {
     serviceManager?: ServiceManager.IManager;
 };
-declare const NotebookCollaborationExample: (props: INotebookCollaborationExampleProps) => import("react/jsx-runtime").JSX.Element;
+declare const NotebookCollaborationExample: (props: INotebookCollaborationExampleProps) => import("react").JSX.Element;
 export default NotebookCollaborationExample;

package/lib/examples/NotebookCollaborationExample.js

@@ -7,13 +7,16 @@ import { createDatalayerServiceManager } from '../services/DatalayerServiceManag
 import { useState, useEffect, useMemo } from 'react';
 import { Checkbox, FormControl, Heading } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
-import { loadJupyterConfig, Notebook } from '@datalayer/jupyter-react';
+import { loadJupyterConfig, Notebook, JupyterCollaborationProvider, } from '@datalayer/jupyter-react';
 import { DatalayerCollaborationProvider } from '../collaboration';
 import { useCoreStore } from '../state';
 import { ThemedJupyterProvider } from './utils/themedProvider';
+import { useRuntimeTargetStore } from './utils/runtimeTargetStore';
 import nbformatExample from './utils/notebooks/NotebookExample1.ipynb.json';
+import { ExampleNotebookToolbar } from './utils/notebookToolbarItems';
 // This corresponds to the notebook ID in the URL when you open an existing notbook in your library
 const NOTEBOOK_ID = '01JZQRQ35GG871QQCZW9TB1A8J';
+const ROOM_PATH = 'notebook-collaboration-example.ipynb';
 const NotebookCollaborationExample = (props) => {
     // Load config on component mount
     loadJupyterConfig();
@@ -21,7 +24,70 @@ const NotebookCollaborationExample = (props) => {
     const [enableCollaboration, setEnableCollaboration] = useState(false);
     const [readonly] = useState(false);
     const [serviceManager, setServiceManager] = useState(props.serviceManager);
+    const [collaborationReady, setCollaborationReady] = useState(false);
+    const [collaborationError, setCollaborationError] = useState(null);
     const { configuration } = useCoreStore();
+    const runtimeTarget = useRuntimeTargetStore(state => state.target);
+    useEffect(() => {
+        let cancelled = false;
+        const prepare = async () => {
+            if (!enableCollaboration || !serviceManager) {
+                setCollaborationReady(false);
+                setCollaborationError(null);
+                return;
+            }
+            setCollaborationReady(false);
+            setCollaborationError(null);
+            if (runtimeTarget === 'datalayer') {
+                setCollaborationReady(true);
+                return;
+            }
+            try {
+                await serviceManager.ready;
+                try {
+                    await serviceManager.contents.get(ROOM_PATH, { content: false });
+                }
+                catch (error) {
+                    if (error.response?.status !==
+                        404)
+                        throw error;
+                    try {
+                        await serviceManager.contents.save(ROOM_PATH, {
+                            type: 'notebook',
+                            format: 'json',
+                            content: nbformat,
+                        });
+                    }
+                    catch (saveError) {
+                        // Some Jupyter backends create the file but return a response that
+                        // the contents client cannot decode. Verify before reporting it.
+                        try {
+                            await serviceManager.contents.get(ROOM_PATH, { content: false });
+                        }
+                        catch {
+                            throw saveError;
+                        }
+                    }
+                }
+                // Do not open the collaboration websocket until the room file is
+                // observable through the same service manager.
+                await serviceManager.contents.get(ROOM_PATH, { content: false });
+                if (!cancelled)
+                    setCollaborationReady(true);
+            }
+            catch (error) {
+                console.error('Failed to prepare collaboration room:', error);
+                if (!cancelled) {
+                    setCollaborationReady(false);
+                    setCollaborationError(String(error));
+                }
+            }
+        };
+        void prepare();
+        return () => {
+            cancelled = true;
+        };
+    }, [enableCollaboration, nbformat, runtimeTarget, serviceManager]);
     useEffect(() => {
         // Create DatalayerServiceManager if not provided
         const createManager = async () => {
@@ -49,25 +115,47 @@ const NotebookCollaborationExample = (props) => {
         };
         createManager();
     }, [props.serviceManager, configuration]);
-    // Create the collaboration provider when enabled
-    const collaborationProvider = useMemo(() => {
-        if (!enableCollaboration) {
-            return undefined;
+    // Each Notebook owns its own shared model, so each pane needs a separate
+    // provider. Both providers point at the same real library document.
+    const collaborationProviders = useMemo(() => {
+        if (!enableCollaboration || !collaborationReady) {
+            return [undefined, undefined];
+        }
+        if (runtimeTarget === 'local') {
+            const config = {
+                path: ROOM_PATH,
+                serverSettings: serviceManager?.serverSettings,
+            };
+            return [
+                new JupyterCollaborationProvider(config),
+                new JupyterCollaborationProvider(config),
+            ];
         }
         const spacerUrl = configuration?.spacerUrl;
         const token = configuration?.token;
-        if (!spacerUrl || !token) {
-            console.warn('Datalayer collaboration enabled but spacerUrl or token not configured. ' +
-                'Please configure them in the Datalayer store or environment.');
-            return undefined;
-        }
-        // Create and return the Datalayer collaboration provider
-        return new DatalayerCollaborationProvider({
-            spacerUrl,
-            token,
-        });
-    }, [enableCollaboration, configuration]);
-    return (_jsx(ThemedJupyterProvider, { children: _jsxs(Box, { p: 3, children: [_jsx(Heading, { as: "h2", sx: { mb: 3 }, children: "Notebook Collaboration Example" }), _jsx(Box, { sx: { mb: 3 }, children: _jsxs(FormControl, { children: [_jsx(Checkbox, { checked: enableCollaboration, onChange: e => setEnableCollaboration(e.target.checked) }), _jsx(FormControl.Label, { children: "Enable Datalayer Collaboration" })] }) }), (!configuration?.spacerUrl || !configuration?.token) && (_jsx(Box, { sx: { mb: 2, p: 2, bg: 'danger.subtle' }, children: "Warning: Datalayer configuration is missing. Please configure spacerUrl and token to use DatalayerServiceManager and collaboration features." })), !serviceManager && (_jsx(Box, { sx: { mb: 2, p: 2, bg: 'attention.subtle' }, children: "Note: DatalayerServiceManager is not available. Notebook functionality will be limited." })), enableCollaboration ? (_jsxs(Box, { sx: {
+        if (!spacerUrl || !token)
+            return [undefined, undefined];
+        return [
+            new DatalayerCollaborationProvider({ spacerUrl, token }),
+            new DatalayerCollaborationProvider({ spacerUrl, token }),
+        ];
+    }, [
+        enableCollaboration,
+        collaborationReady,
+        runtimeTarget,
+        configuration?.spacerUrl,
+        configuration?.token,
+    ]);
+    const [collaborationProvider1, collaborationProvider2] = collaborationProviders;
+    // Close websocket connections when collaboration is disabled or the example
+    // is unmounted. This also prevents stale providers from keeping a notebook
+    // in its loading state after toggling the checkbox.
+    useEffect(() => {
+        return () => {
+            collaborationProviders.forEach(provider => provider?.dispose());
+        };
+    }, [collaborationProviders]);
+    return (_jsx(ThemedJupyterProvider, { children: _jsxs(Box, { p: 3, children: [_jsx(Heading, { as: "h2", sx: { mb: 3 }, children: "Notebook Collaboration Example" }), _jsxs(Box, { sx: { mb: 3 }, children: [_jsxs(FormControl, { children: [_jsx(Checkbox, { checked: enableCollaboration, onChange: e => setEnableCollaboration(e.target.checked) }), _jsx(FormControl.Label, { children: "Enable Datalayer Collaboration" })] }), enableCollaboration && runtimeTarget !== 'datalayer' && (_jsx(Box, { sx: { mt: 1, color: 'fg.muted', fontSize: 0 }, children: "Real-time Datalayer collaboration requires the cloud runtime target. Local mode does not expose a collaboration room." }))] }), (!configuration?.spacerUrl || !configuration?.token) && (_jsx(Box, { sx: { mb: 2, p: 2, bg: 'danger.subtle' }, children: "Warning: Datalayer configuration is missing. Please configure spacerUrl and token to use DatalayerServiceManager and collaboration features." })), !serviceManager && (_jsx(Box, { sx: { mb: 2, p: 2, bg: 'attention.subtle' }, children: "Note: DatalayerServiceManager is not available. Notebook functionality will be limited." })), collaborationError && (_jsxs(Box, { sx: { mb: 2, p: 2, bg: 'danger.subtle' }, children: ["Collaboration could not start: ", collaborationError] })), enableCollaboration && collaborationReady ? (_jsxs(Box, { sx: {
                         display: 'flex',
                         gap: 2,
                         flexDirection: 'row',
@@ -82,7 +170,7 @@ const NotebookCollaborationExample = (props) => {
                                         borderBottom: '1px solid',
                                         borderColor: 'border.default',
                                         fontWeight: 'bold',
-                                    }, children: "Collaborator 1" }), serviceManager ? (_jsx(Notebook, { id: `${NOTEBOOK_ID}-collab-1`, height: "calc(100vh - 280px)", nbformat: nbformat, readonly: readonly, serviceManager: serviceManager, startDefaultKernel: true, collaborationProvider: collaborationProvider })) : (_jsx(Box, { sx: { p: 4, textAlign: 'center' }, children: "Loading ServiceManager..." }))] }), _jsxs(Box, { sx: {
+                                    }, children: "Collaborator 1" }), serviceManager ? (_jsx(Notebook, { id: NOTEBOOK_ID, Toolbar: ExampleNotebookToolbar, path: ROOM_PATH, height: "calc(100vh - 280px)", nbformat: nbformat, readonly: readonly, serviceManager: serviceManager, startDefaultKernel: true, collaborationProvider: collaborationProvider1 })) : (_jsx(Box, { sx: { p: 4, textAlign: 'center' }, children: "Loading ServiceManager..." }))] }), _jsxs(Box, { sx: {
                                 flex: 1,
                                 border: '1px solid',
                                 borderColor: 'border.default',
@@ -93,10 +181,10 @@ const NotebookCollaborationExample = (props) => {
                                         borderBottom: '1px solid',
                                         borderColor: 'border.default',
                                         fontWeight: 'bold',
-                                    }, children: "Collaborator 2" }), serviceManager ? (_jsx(Notebook, { id: `${NOTEBOOK_ID}-collab-2`, height: "calc(100vh - 280px)", nbformat: nbformat, readonly: readonly, serviceManager: serviceManager, startDefaultKernel: false, collaborationProvider: collaborationProvider })) : (_jsx(Box, { sx: { p: 4, textAlign: 'center' }, children: "Loading ServiceManager..." }))] })] })) : (_jsx(Box, { sx: {
+                                    }, children: "Collaborator 2" }), serviceManager ? (_jsx(Notebook, { id: NOTEBOOK_ID, Toolbar: ExampleNotebookToolbar, path: ROOM_PATH, height: "calc(100vh - 280px)", nbformat: nbformat, readonly: readonly, serviceManager: serviceManager, startDefaultKernel: false, collaborationProvider: collaborationProvider2 })) : (_jsx(Box, { sx: { p: 4, textAlign: 'center' }, children: "Loading ServiceManager..." }))] })] })) : (_jsx(Box, { sx: {
                         border: '1px solid',
                         borderColor: 'border.default',
                         borderRadius: 2,
-                    }, children: serviceManager ? (_jsx(Notebook, { id: NOTEBOOK_ID, height: "calc(100vh - 200px)", nbformat: nbformat, readonly: readonly, serviceManager: serviceManager, startDefaultKernel: true, collaborationProvider: collaborationProvider })) : (_jsx(Box, { sx: { p: 4, textAlign: 'center' }, children: "Loading ServiceManager..." })) })), _jsxs(Box, { sx: { mt: 2, fontSize: 1, color: 'fg.subtle' }, children: [_jsx(Box, { as: "p", sx: { m: 0, mb: 2 }, children: "This example demonstrates how to use Datalayer services with Notebook:" }), _jsxs(Box, { as: "ul", sx: { m: 0, pl: 3, '& li': { mb: 1 } }, children: [_jsxs("li", { children: [_jsx("strong", { children: "DatalayerServiceManager:" }), " Connects to Datalayer infrastructure for kernel management"] }), _jsxs("li", { children: [_jsx("strong", { children: "DatalayerCollaborationProvider:" }), " Enables real-time collaboration"] }), _jsx("li", { children: "Both require Datalayer credentials (spacerUrl and token)" }), _jsx("li", { children: "Pass them directly to the base Notebook component" }), _jsx("li", { children: "No wrapper components needed - just create the services and pass them as props" }), _jsx("li", { children: "This shows the explicit, composable pattern for Datalayer integration" })] })] })] }) }));
+                    }, children: serviceManager ? (_jsx(Notebook, { id: NOTEBOOK_ID, Toolbar: ExampleNotebookToolbar, height: "calc(100vh - 200px)", nbformat: nbformat, readonly: readonly, serviceManager: serviceManager, startDefaultKernel: true, collaborationProvider: collaborationProvider1 })) : (_jsx(Box, { sx: { p: 4, textAlign: 'center' }, children: "Loading ServiceManager..." })) })), _jsxs(Box, { sx: { mt: 2, fontSize: 1, color: 'fg.subtle' }, children: [_jsx(Box, { as: "p", sx: { m: 0, mb: 2 }, children: "This example demonstrates how to use Datalayer services with Notebook:" }), _jsxs(Box, { as: "ul", sx: { m: 0, pl: 3, '& li': { mb: 1 } }, children: [_jsxs("li", { children: [_jsx("strong", { children: "DatalayerServiceManager:" }), " Connects to Datalayer infrastructure for kernel management"] }), _jsxs("li", { children: [_jsx("strong", { children: "DatalayerCollaborationProvider:" }), " Enables real-time collaboration"] }), _jsx("li", { children: "Both require Datalayer credentials (spacerUrl and token)" }), _jsx("li", { children: "Pass them directly to the base Notebook component" }), _jsx("li", { children: "No wrapper components needed - just create the services and pass them as props" }), _jsx("li", { children: "This shows the explicit, composable pattern for Datalayer integration" })] })] })] }) }));
 };
 export default NotebookCollaborationExample;

package/lib/examples/NotebookExample.d.ts

@@ -2,5 +2,5 @@ import { ServiceManager } from '@jupyterlab/services';
 type IJupyterNotebookExampleProps = {
     serviceManager?: ServiceManager.IManager;
 };
-export declare const JupyterNotebookExample: (props: IJupyterNotebookExampleProps) => import("react/jsx-runtime").JSX.Element;
+export declare const JupyterNotebookExample: (props: IJupyterNotebookExampleProps) => import("react").JSX.Element;
 export default JupyterNotebookExample;

package/lib/examples/NotebookExample.js

@@ -3,23 +3,33 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-/*
- * Copyright (c) 2021-2023 Datalayer, Inc.
- *
- * MIT License
- */
 import { useMemo } from 'react';
 import { Box } from '@datalayer/primer-addons';
-import { Notebook, NotebookToolbar, CellSidebarExtension, CellSidebarButton, } from '@datalayer/jupyter-react';
+import { Notebook, CellSidebarExtension, CellSidebarButton, } from '@datalayer/jupyter-react';
 import { ThemedJupyterProvider } from './utils/themedProvider';
 import nbformatExample from './utils/notebooks/NotebookExample1.ipynb.json';
+import { ExampleNotebookToolbar } from './utils/notebookToolbarItems';
 const NOTEBOOK_ID = 'notebook-example-1';
 export const JupyterNotebookExample = (props) => {
     const { serviceManager } = props;
     const extensions = useMemo(() => [new CellSidebarExtension({ factory: CellSidebarButton })], []);
-    if (!serviceManager) {
-        return (_jsxs(Box, { as: "h1", children: ["Notebook Example", _jsx("div", { children: "Loading..." })] }));
-    }
-    return (_jsxs(ThemedJupyterProvider, { children: [_jsx(Box, { as: "h1", children: "Notebook Example" }), _jsx(Notebook, { id: NOTEBOOK_ID, nbformat: nbformatExample, serviceManager: serviceManager, startDefaultKernel: true, extensions: extensions, Toolbar: NotebookToolbar })] }));
+    return (_jsxs(Box, { sx: {
+            flex: 1,
+            display: 'flex',
+            flexDirection: 'column',
+            overflow: 'auto',
+            padding: 3,
+        }, children: [_jsxs(Box, { sx: {
+                    marginBottom: 3,
+                    paddingBottom: 3,
+                    borderBottom: '1px solid',
+                    borderColor: 'border.default',
+                }, children: [_jsx(Box, { as: "h1", sx: { margin: 0 }, children: "Notebook Example" }), _jsx("p", { children: "A notebook on the selected sandbox, with the kernel indicator in its toolbar." })] }), _jsx(Box, { sx: {
+                    border: '1px solid',
+                    borderColor: 'border.default',
+                    borderRadius: 2,
+                    padding: 3,
+                    backgroundColor: 'canvas.default',
+                }, children: serviceManager ? (_jsx(ThemedJupyterProvider, { children: _jsx(Notebook, { id: NOTEBOOK_ID, nbformat: nbformatExample, serviceManager: serviceManager, startDefaultKernel: true, extensions: extensions, Toolbar: ExampleNotebookToolbar, height: "calc(100vh - 300px)", cellSidebarMargin: 120 }) })) : (_jsx(Box, { sx: { padding: 3 }, children: _jsx("p", { children: "Loading service manager..." }) })) })] }));
 };
 export default JupyterNotebookExample;

package/lib/examples/NotebookPageAgent.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A notebook as a page, with a team of agents working in it.
+ *
+ * The page layout: the notebook on a centred sheet over a quiet canvas, like
+ * a document application; the composer docked directly above the sheet and
+ * exactly as wide, as its command line; the conversation in a panel at the
+ * side, opened from the header when it is wanted. Ask the Analyst for an analysis and the cells
+ * appear on the page; ask the Reviewer to check it and the verdict lands
+ * beside them.
+ *
+ * Reactor plugins only. `pageLayout` mounts `LoopPageLayoutPlugin`, which
+ * hands the chat view's parts to primer-addons' page layout through the
+ * `LoopChatLayout` point; the
+ * `jupyter` team brings the Analyst, the Reviewer, the Writer and
+ * the rest of the notebook's agents;
+ * the loop turns in the browser, so nothing has to be installed or signed
+ * into.
+ *
+ * @module examples/NotebookPageAgent
+ */
+import React from 'react';
+declare const NotebookPageAgent: React.FC;
+export default NotebookPageAgent;

package/lib/examples/NotebookPageAgent.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from '@datalayer/primer-addons';
+import { ThemedProvider } from './utils/themedProvider';
+import { LoopEmbed } from '../loop';
+const NotebookPageAgent = () => (_jsx(ThemedProvider, { children: _jsx(Box, { sx: { height: '100vh', minHeight: 0 }, children: _jsx(LoopEmbed, { target: "browser", 
+            /* The Analyst is the team's front door; the team puts the other
+               members one click away in the composer's agents menu. */
+            agentId: "jupyter-data-analyst", teamId: "jupyter", 
+            /* The notebook, open on the page. */
+            defaultEditor: "notebook", pageLayout: true, 
+            /* The composer as a draggable card over the top of the page rather
+               than the docked band. */
+            pageLayoutPrompt: "floating", 
+            /* The header carries the editor choice — notebook, document, or the
+               conversation alone — and the page layout's conversation toggle. */
+            showHeader: true, editorSelector: true, commandPalette: true, agentSummary: false }) }) }));
+export default NotebookPageAgent;

package/lib/examples/components/ExampleWrapper.d.ts

@@ -11,6 +11,11 @@ import React from 'react';
  * Also clears the shared chat + conversation stores synchronously as the
  * new example mounts, so switching examples never leaks messages from the
  * previously-mounted chat.
+ *
+ * And it declares, for every chat an example renders, whether there is an agent
+ * to talk to. Two of the four runtime targets are a sandbox and nothing else,
+ * and saying so once here is why no example has to know which: the chat shows
+ * itself switched off, with the reason in its header, wherever it is mounted.
  */
 export declare const ExampleWrapper: React.FC<{
     children: React.ReactNode;

package/lib/examples/components/ExampleWrapper.js

@@ -6,6 +6,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useLayoutEffect } from 'react';
 import { Box } from '@datalayer/primer-addons';
 import { useChatStore, useConversationStore } from '../../stores';
+import { ChatAvailabilityProvider } from '../../chat/base/ChatAvailability';
+import { useRuntimeTarget } from '../utils/runtimeTargetStore';
 /**
  * ExampleWrapper
  *
@@ -18,40 +20,46 @@ import { useChatStore, useConversationStore } from '../../stores';
  * Also clears the shared chat + conversation stores synchronously as the
  * new example mounts, so switching examples never leaks messages from the
  * previously-mounted chat.
+ *
+ * And it declares, for every chat an example renders, whether there is an agent
+ * to talk to. Two of the four runtime targets are a sandbox and nothing else,
+ * and saying so once here is why no example has to know which: the chat shows
+ * itself switched off, with the reason in its header, wherever it is mounted.
  */
 export const ExampleWrapper = ({ children, }) => {
+    const { hasAgent, noAgentReason } = useRuntimeTarget();
     useLayoutEffect(() => {
         useChatStore.getState().reset();
         useConversationStore.getState().clearAll();
     }, []);
-    return (_jsx(Box, { sx: {
-            position: 'relative',
-            height: '100%',
-            width: '100%',
-            minHeight: 0,
-            overflow: 'hidden',
-            display: 'flex',
-            flexDirection: 'column',
-            fontFamily: 'var(--fontStack-sansSerif, -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif)',
-            lineHeight: 1.5,
-            '& h1, & h2, & h3, & h4, & h5, & h6, & p, & li, & span, & label, & button, & input, & textarea, & select': {
-                fontFamily: 'inherit',
-            },
-            // Generic constraint: every example's root child fills the wrapper
-            // exactly and cannot exceed it. This neutralises stray `100vh`/
-            // `calc(100vh - Npx)` heights inside individual examples so the
-            // chat footer (or any bottom UI) always remains in the viewport.
-            '& > *': {
-                flex: '1 1 0',
-                minHeight: 0,
-                maxHeight: '100%',
+    return (_jsx(ChatAvailabilityProvider, { disabled: !hasAgent, disableReason: hasAgent ? undefined : noAgentReason, children: _jsx(Box, { sx: {
+                position: 'relative',
+                height: '100%',
                 width: '100%',
-                // Default scroll behaviour for plain content pages. Examples
-                // that manage their own internal scrollers can override this
-                // by setting `overflow: 'hidden'` (or another value) on their
-                // root element \u2014 the child rule wins on specificity.
-                overflow: 'auto',
-            },
-        }, children: children }));
+                minHeight: 0,
+                overflow: 'hidden',
+                display: 'flex',
+                flexDirection: 'column',
+                fontFamily: 'var(--fontStack-sansSerif, -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif)',
+                lineHeight: 1.5,
+                '& h1, & h2, & h3, & h4, & h5, & h6, & p, & li, & span, & label, & button, & input, & textarea, & select': {
+                    fontFamily: 'inherit',
+                },
+                // Generic constraint: every example's root child fills the wrapper
+                // exactly and cannot exceed it. This neutralises stray `100vh`/
+                // `calc(100vh - Npx)` heights inside individual examples so the
+                // chat footer (or any bottom UI) always remains in the viewport.
+                '& > *': {
+                    flex: '1 1 0',
+                    minHeight: 0,
+                    maxHeight: '100%',
+                    width: '100%',
+                    // Default scroll behaviour for plain content pages. Examples
+                    // that manage their own internal scrollers can override this
+                    // by setting `overflow: 'hidden'` (or another value) on their
+                    // root element \u2014 the child rule wins on specificity.
+                    overflow: 'auto',
+                },
+            }, children: children }) }));
 };
 export default ExampleWrapper;

package/lib/examples/components/LexicalEditor.d.ts

@@ -9,7 +9,7 @@ export interface LexicalEditorProps {
     serviceManager?: ServiceManager.IManager;
     /** Optional extra toolbar items (e.g. AI actions from useChatInlineToolbarItems) */
     extraItems?: ToolbarItem[];
-    /** Optional additional children to render inside the LexicalComposer */
+    /** Optional additional children to render inside the composer */
     children?: React.ReactNode;
 }
 /**