@datalayer/agent-runtimes 1.0.28 → 1.3.10

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

@@ -1,4 +1,22 @@
+/**
+ * EphemeralNotebook — an in-memory Jupyter notebook rendered next to the chat.
+ *
+ * The notebook model lives purely in memory (the `nbformat` content below is
+ * never persisted to a file) and is backed by a sandbox kernel obtained via
+ * `useJupyter`. This mirrors the pattern used by the notebook editor and the
+ * `NotebookNbformat` example, so the agent can drive the notebook through the
+ * registered notebook frontend tools while nothing is written to disk.
+ *
+ * The container structure (relative wrapper + absolutely positioned inner box
+ * + `#dla-Jupyter-Notebook` overrides) is copied from the notebook editor
+ * (`NotebookEditorPanel`) so the cells get a resolved height and actually
+ * render — a plain `height: 100%` collapses to zero inside a flex parent.
+ *
+ * @module chat/notebook/EphemeralNotebook
+ */
+import type { JSX } from 'react';
 import type { INotebookContent } from '@jupyterlab/nbformat';
+import { ServiceManager } from '@jupyterlab/services';
 import { type ToolbarItem } from '@datalayer/primer-addons';
 import type { ICollaborationProvider } from '@datalayer/jupyter-react';
 import type { EphemeralNotebookToolbarComponent } from '../../types/chat';
@@ -18,7 +36,7 @@ export interface EphemeralRuntimeOverride {
     /** Bearer/JWT token appended to requests (`appendToken`). */
     token?: string;
     /** Stable identifier used for the sandbox service-manager registry. */
-    podName?: string;
+    runtimeName?: string;
 }
 export interface EphemeralNotebookProps {
     /**
@@ -27,7 +45,7 @@ export interface EphemeralNotebookProps {
      */
     notebookId: string;
     /** Preferred runtime pod name to bind the notebook kernel to. */
-    runtimePodName?: string;
+    runtimeName?: string;
     /**
      * Explicit runtime endpoint override. When supplied, the notebook binds its
      * kernel to this endpoint directly instead of resolving a pod from the user's
@@ -44,6 +62,24 @@ export interface EphemeralNotebookProps {
     onNbformatChange?: (content: INotebookContent) => void;
     /** Optional toolbar component override. */
     toolbarComponent?: EphemeralNotebookToolbarComponent;
+    /**
+     * Whether to draw a toolbar at all. Defaults to true.
+     *
+     * For a host where the toolbar is somebody's to provide — the LOOP
+     * workspace, where a plugin owns it and can be switched off. `false` draws
+     * no bar rather than an empty one: an empty bar still costs a row and a
+     * border, and reads as broken rather than as absent.
+     */
+    showToolbar?: boolean;
+    /**
+     * Whether the toolbar offers Save.
+     *
+     * False by default. This notebook is held in memory and written back by
+     * whoever mounted it, so the button commits nothing a reader can point at —
+     * and in a browser sandbox there is no file behind it at all. A host that
+     * does persist the notebook, and wants an explicit save, sets this.
+     */
+    showSaveItem?: boolean;
     /**
      * Items added to the toolbar of the notebook.
      *
@@ -65,9 +101,34 @@ export interface EphemeralNotebookProps {
      * tunnel.
      */
     collaborationProvider?: ICollaborationProvider;
+    /**
+     * A `ServiceManager` to bind to instead of resolving one from a runtime.
+     *
+     * For hosts that already own the connection — a browser (Pyodide) sandbox,
+     * where the kernel runs in the page and there is no pod to look up. Binding
+     * to the host's manager is what puts the agent's executions and the reader's
+     * cells in the same kernel.
+     */
+    /**
+     * Render without wrapping the content in a theme provider.
+     *
+     * For a host that already owns one — the LOOP workspace, where the entry
+     * point provides the theme and the views inherit it. Nested providers fight
+     * over `BaseStyles` and font tokens, and the inner one wins for the wrong
+     * reasons.
+     */
+    inheritTheme?: boolean;
+    serviceManager?: ServiceManager.IManager;
+    /**
+     * A kernel already running on that manager to bind to.
+     *
+     * Supplied with `serviceManager` when the host has a kernel of its own — a
+     * browser sandbox, say. Without it the notebook starts a second kernel on the
+     * same manager, which for Pyodide dies on arrival and, more importantly,
+     * would put the reader's cells and the agent's executions in different
+     * kernels.
+     */
+    kernelId?: string;
 }
-/**
- * Renders an in-memory notebook backed by a sandbox kernel.
- */
-export declare function EphemeralNotebook({ notebookId, runtimePodName, runtimeOverride, cellSidebarMargin, nbformat, onNbformatChange, toolbarComponent, toolbarExtraItems, themeVariant, colorMode, collaborationProvider, }: EphemeralNotebookProps): import("react/jsx-runtime").JSX.Element;
+export declare function EphemeralNotebook({ notebookId, runtimeName, runtimeOverride, serviceManager: externalServiceManager, inheritTheme, kernelId: externalKernelId, cellSidebarMargin, nbformat, onNbformatChange, toolbarComponent, toolbarExtraItems, showToolbar, showSaveItem, themeVariant, colorMode, collaborationProvider, }: EphemeralNotebookProps): JSX.Element;
 export default EphemeralNotebook;

package/lib/chat/notebook/EphemeralNotebook.js

@@ -1,30 +1,11 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-/*
- * Copyright (c) 2025-2026 Datalayer, Inc.
- * Distributed under the terms of the Modified BSD License.
- */
-/**
- * EphemeralNotebook — an in-memory Jupyter notebook rendered next to the chat.
- *
- * The notebook model lives purely in memory (the `nbformat` content below is
- * never persisted to a file) and is backed by a sandbox kernel obtained via
- * `useJupyter`. This mirrors the pattern used by the notebook editor and the
- * `NotebookNbformat` example, so the agent can drive the notebook through the
- * registered notebook frontend tools while nothing is written to disk.
- *
- * The container structure (relative wrapper + absolutely positioned inner box
- * + `#dla-Jupyter-Notebook` overrides) is copied from the notebook editor
- * (`NotebookEditorPanel`) so the cells get a resolved height and actually
- * render — a plain `height: 100%` collapses to zero inside a flex parent.
- *
- * @module chat/notebook/EphemeralNotebook
- */
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { ServerConnection, ServiceManager } from '@jupyterlab/services';
 import { DatalayerThemeProvider, getThemeConfig, useSystemColorMode, useThemeStore, } from '@datalayer/primer-addons';
 import { Box } from '@primer/react';
-import { Notebook, NotebookToolbar, CellSidebarExtension, CellSidebarButton, JupyterReactTheme, notebookStore, disposeServiceManager, } from '@datalayer/jupyter-react';
+import { Notebook, NotebookToolbar, CellSidebarExtension, CellSidebarButton, JupyterReactTheme, notebookStore, disposeServiceManager, useJupyterLabCssLoaded, } from '@datalayer/jupyter-react';
 import { useAgentsRuntimes } from '../../hooks/useAgentRuntimes';
+import { useResumeServerExecutions } from '../../jupyter/useResumeServerExecutions';
 import { registerSandboxServiceManager } from '../../services/sandboxServiceManagers';
 import { useProgressTask } from '../../hooks/useProgressTask';
 /**
@@ -55,7 +36,20 @@ const EPHEMERAL_NOTEBOOK_CONTENT = {
 /**
  * Renders an in-memory notebook backed by a sandbox kernel.
  */
-export function EphemeralNotebook({ notebookId, runtimePodName, runtimeOverride, cellSidebarMargin = 120, nbformat, onNbformatChange, toolbarComponent, toolbarExtraItems, themeVariant, colorMode, collaborationProvider, }) {
+/**
+ * The theme provider, or nothing.
+ *
+ * A host that already owns a theme root passes `inherit`; nested providers
+ * fight over `BaseStyles` and font tokens, and the inner one wins for the wrong
+ * reasons.
+ */
+function ThemeRoot({ inherit, colorMode, themeConfig, children, }) {
+    if (inherit) {
+        return _jsx(_Fragment, { children: children });
+    }
+    return (_jsx(DatalayerThemeProvider, { colorMode: colorMode, theme: themeConfig.primerTheme, themeStyles: themeConfig.themeStyles, children: children }));
+}
+export function EphemeralNotebook({ notebookId, runtimeName, runtimeOverride, serviceManager: externalServiceManager, inheritTheme = false, kernelId: externalKernelId, cellSidebarMargin = 120, nbformat, onNbformatChange, toolbarComponent, toolbarExtraItems, showToolbar = true, showSaveItem = false, themeVariant, colorMode, collaborationProvider, }) {
     // The `nbformat` passed to the `Notebook` component MUST stay a stable
     // reference for the lifetime of a given `notebookId`: the underlying
     // `useNotebookModel` hook rebuilds the notebook model (and its context /
@@ -78,13 +72,13 @@ export function EphemeralNotebook({ notebookId, runtimePodName, runtimeOverride,
     // notebook must bind to exactly the runtime assigned to this agent, or to
     // none at all (straight path).
     const { runtimes, refetchRuntimes } = useAgentsRuntimes();
-    const podResolvedRuntime = useMemo(() => {
-        const preferredPod = String(runtimePodName || '').trim();
-        if (!preferredPod) {
+    const resolvedRuntime = useMemo(() => {
+        const preferredRuntime = String(runtimeName || '').trim();
+        if (!preferredRuntime) {
             return undefined;
         }
-        return runtimes.find(rt => String(rt?.pod_name || '') === preferredPod);
-    }, [runtimePodName, runtimes]);
+        return runtimes.find(rt => String(rt?.runtime_name || '') === preferredRuntime);
+    }, [runtimeName, runtimes]);
     // An explicit endpoint override wins over the pod lookup: it lets a SaaS
     // browser bind the kernel through the runtimes tunnel proxy (the node's
     // Jupyter server is not directly reachable, so no pod exists in the list).
@@ -95,18 +89,19 @@ export function EphemeralNotebook({ notebookId, runtimePodName, runtimeOverride,
                 url: overrideBaseUrl,
                 wsUrl: String(runtimeOverride?.wsUrl || '').trim() || undefined,
                 token: String(runtimeOverride?.token || '').trim(),
-                pod_name: String(runtimeOverride?.podName || '').trim() || 'agent-node-proxy',
+                runtime_name: String(runtimeOverride?.runtimeName || '').trim() ||
+                    'agent-node-proxy',
             };
         }
-        return podResolvedRuntime;
-    }, [runtimeOverride, podResolvedRuntime]);
+        return resolvedRuntime;
+    }, [runtimeOverride, resolvedRuntime]);
     // While the assigned pod has not yet appeared in the runtimes list, poll the
     // list quickly instead of waiting for the default (10s) refresh interval.
     // This is what makes the "Starting notebook…" state clear promptly once the
     // agent runtime is ready, rather than lingering for several seconds. The
     // override path binds immediately, so no polling is needed there.
     const needsRuntimeLookup = Boolean(!runtimeOverride?.baseUrl &&
-        String(runtimePodName || '').trim() &&
+        String(runtimeName || '').trim() &&
         !selectedRuntime);
     useEffect(() => {
         if (!needsRuntimeLookup) {
@@ -147,37 +142,72 @@ export function EphemeralNotebook({ notebookId, runtimePodName, runtimeOverride,
                     token,
                     appendToken: true,
                 });
-                manager = new ServiceManager({ serverSettings });
+                const pending = new ServiceManager({ serverSettings });
+                manager = pending;
                 // 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;
-                await manager.kernels.refreshRunning();
-                const runningKernel = [...manager.kernels.running()][0];
-                if (!cancelled) {
-                    setRuntimeServiceManager(manager);
-                    setRuntimeKernelId(runningKernel?.id);
-                    setRuntimeStartDefaultKernel(!runningKernel);
+                unregisterManager = registerSandboxServiceManager(String(selectedRuntime?.runtime_name || ''), manager);
+                // The cleanup below may already have run: it captured `manager` while
+                // it was still null, because this function is async and assigns it
+                // after the first await the caller does not wait for. Switching
+                // sandboxes quickly is exactly that race, and the manager it orphans
+                // polls the abandoned server for the life of the page.
+                if (cancelled) {
+                    release(pending);
+                    return;
+                }
+                await pending.ready;
+                await pending.kernels.refreshRunning();
+                const runningKernel = [...pending.kernels.running()][0];
+                if (cancelled) {
+                    release(pending);
+                    return;
                 }
+                setRuntimeServiceManager(pending);
+                setRuntimeKernelId(runningKernel?.id);
+                setRuntimeStartDefaultKernel(!runningKernel);
             }
-            catch {
+            catch (reason) {
+                // Give up the manager, do not merely stop looking at it.
+                //
+                // A `ServiceManager` starts polling `/api/kernels` and `/api/sessions`
+                // the moment it is constructed, on its own schedule. Abandoning one
+                // whose `ready` rejected left those polls running against a server
+                // that had gone — a switch away from a restarted sandbox produced an
+                // endless run of ERR_CONNECTION_REFUSED, one every few seconds,
+                // forever.
+                if (manager) {
+                    release(manager);
+                    manager = null;
+                }
                 if (!cancelled) {
+                    console.warn(`[agent-runtimes] Could not reach the sandbox at ${baseUrl}.`, reason);
                     setRuntimeServiceManager(null);
                     setRuntimeKernelId(undefined);
                     setRuntimeStartDefaultKernel(false);
                 }
             }
         };
+        /** Unregister and dispose one manager, once. */
+        const release = (target) => {
+            unregisterManager?.();
+            unregisterManager = null;
+            disposeServiceManager(target);
+        };
         connectRuntime();
         return () => {
             cancelled = true;
-            unregisterManager?.();
             if (manager) {
-                disposeServiceManager(manager);
+                release(manager);
+                manager = null;
+            }
+            else {
+                unregisterManager?.();
+                unregisterManager = null;
             }
         };
     }, [
-        selectedRuntime?.pod_name,
+        selectedRuntime?.runtime_name,
         selectedRuntime?.url,
         selectedRuntime?.token,
         selectedRuntime?.wsUrl,
@@ -185,25 +215,94 @@ export function EphemeralNotebook({ notebookId, runtimePodName, runtimeOverride,
     // Bind strictly to the agent runtime sandbox; there is NO local fallback
     // kernel. The notebook executes on the agent's runtime or shows a waiting
     // state until the runtime is ready.
-    const activeServiceManager = runtimeServiceManager;
-    const activeKernelId = runtimeKernelId;
-    const activeStartDefaultKernel = runtimeStartDefaultKernel;
+    // A host that already owns a `ServiceManager` — a browser (Pyodide) sandbox,
+    // where the kernel runs in the page and there is no pod to resolve — passes
+    // it in. Binding to *that* manager is what puts the agent's executions and
+    // the reader's cells in the same kernel.
+    const activeServiceManager = externalServiceManager ?? runtimeServiceManager;
+    /*
+     * Wait for the JupyterLab stylesheets before the first paint.
+     *
+     * They arrive as their own webpack chunks, fetched when the first notebook
+     * on the page asks for them, and a notebook drawn before they land has no
+     * rules at all — the cells stack, the toolbar unwraps, and the panel looks
+     * broken until something makes it render again. On a reload the chunks come
+     * from cache fast enough that nobody sees it, which is why this only ever
+     * showed up on the first visit to an agent page.
+     *
+     * Holding here rather than in `JupyterReactTheme` because the theme wraps
+     * the whole page: blanking the conversation while a notebook's stylesheet
+     * loads would trade a small ugly moment for a large empty one. This is the
+     * one component that cannot be read without them.
+     *
+     * The hook resolves even if a chunk fails, so a missing stylesheet still
+     * gets a notebook — the old, ugly one — and never an empty box forever.
+     *
+     * It waits for as long as that takes — measured at about 3s warm and 6.5s
+     * cold — rather than drawing after a grace period, and the reason is in the
+     * bug report: a refresh was needed. Stylesheets that arrive late apply
+     * themselves, so a notebook that were merely racing them would repair itself
+     * the moment they landed and nobody would ever reach for reload. It does not
+     * repair, because Lumino measures this panel when it attaches and never
+     * measures again — attach it against no rules and it keeps those numbers for
+     * as long as it lives. Drawing early on a timer would reproduce exactly the
+     * state being fixed, on precisely the slow connections that hit it most.
+     */
+    const notebookReady = useJupyterLabCssLoaded();
+    const activeKernelId = externalKernelId ?? runtimeKernelId;
+    // Join the host's kernel when there is one; only start a kernel of our own
+    // when the host handed us a manager without one. Starting a second kernel
+    // beside the host's would split the reader's cells from the agent's
+    // executions — and for Pyodide the second one dies on arrival.
+    const activeStartDefaultKernel = externalServiceManager
+        ? !externalKernelId
+        : runtimeStartDefaultKernel;
     // The toolbar of the notebook, with the items of the host merged in. A host
     // replacing the toolbar altogether receives them as well, as every toolbar
     // built on the notebook one takes `extraItems`.
     const ToolbarComponent = useMemo(() => {
+        if (!showToolbar) {
+            // Undefined, not a component that renders null. `Notebook` guards with
+            // `{Toolbar && <Toolbar/>}`, so this removes it from the tree entirely —
+            // which matters for the sibling selectors below.
+            return undefined;
+        }
         const Base = toolbarComponent || NotebookToolbar;
-        if (!toolbarExtraItems?.length) {
+        /*
+         * No save button, unless a host asks for one.
+         *
+         * This notebook is ephemeral — that is its name. It is held in memory,
+         * written back by the host that mounted it, and in a browser sandbox there
+         * is no file on the other side of the button at all. A control that looks
+         * like it commits work and does not is worse than no control, and it is
+         * the first thing in the toolbar, where it reads as the primary action.
+         *
+         * The divider goes with it. Hiding the item alone leaves the toolbar
+         * opening on a rule with nothing before it.
+         */
+        const hiddenItems = showSaveItem
+            ? undefined
+            : ['notebook-save', 'notebook-divider-file'];
+        if (!toolbarExtraItems?.length && !hiddenItems) {
             return Base;
         }
         return function EphemeralNotebookToolbar(props) {
-            return _jsx(Base, { ...props, extraItems: toolbarExtraItems });
+            return (_jsx(Base, { ...props, extraItems: toolbarExtraItems, hiddenItems: hiddenItems }));
         };
-    }, [toolbarComponent, toolbarExtraItems]);
-    const isRuntimeStarting = Boolean((String(runtimePodName || '').trim() ||
+    }, [showToolbar, showSaveItem, toolbarComponent, toolbarExtraItems]);
+    const isRuntimeStarting = Boolean((String(runtimeName || '').trim() ||
         String(runtimeOverride?.baseUrl || '').trim()) &&
         !activeServiceManager);
     useProgressTask(`ephemeral-notebook-start-${notebookId}`, isRuntimeStarting);
+    /*
+     * What a previous page left running on the sandbox.
+     *
+     * The cells come back from the persisted model, each carrying the request
+     * the server accepted for it; once the sandbox is bound again, those
+     * requests are polled back into the cells, so a refresh mid-run finds the
+     * outputs that kept arriving while it was away.
+     */
+    useResumeServerExecutions(notebookId, activeServiceManager ?? undefined);
     useEffect(() => {
         // When a collaboration provider is active the shared ydoc is the single
         // source of truth and is synced remotely; the local in-memory persistence
@@ -259,6 +358,20 @@ export function EphemeralNotebook({ notebookId, runtimePodName, runtimeOverride,
         : themeConfig.themeStyles.light;
     const themeBackground = modeStyles.backgroundColor ?? '';
     const extensions = useMemo(() => [new CellSidebarExtension({ factory: CellSidebarButton })], []);
+    /*
+     * A session path under `.datalayer/`, so the server executor recovers outputs.
+     *
+     * `jupyter-server-nbmodel` streams a cell's outputs into the shared document
+     * of the server when the session names a file of it, and turns on HTTP
+     * output recovery when it does not — the case for every editor of Datalayer.
+     * Left to default, Jupyter React names the session `kernel-<id>`, which the
+     * executor reads as a real server document, so it keeps recovery OFF and an
+     * ephemeral notebook (which has no shared document on the pod at all) shows
+     * no outputs and loses a running cell on refresh. A `.datalayer/` path is
+     * how the executor is told there is no file here; the notebook id keeps two
+     * ephemeral notebooks on one sandbox from sharing a session.
+     */
+    const sessionPath = useMemo(() => `.datalayer/${notebookId}.ipynb`, [notebookId]);
     return (_jsx(Box, { sx: {
             flex: 1,
             minHeight: 0,
@@ -266,7 +379,7 @@ export function EphemeralNotebook({ notebookId, runtimePodName, runtimeOverride,
             position: 'relative',
             overflow: 'hidden',
             bg: 'canvas.default',
-        }, children: activeServiceManager ? (_jsx(DatalayerThemeProvider, { colorMode: effectiveColorMode, theme: themeConfig.primerTheme, themeStyles: themeConfig.themeStyles, children: _jsx(JupyterReactTheme, { colormode: resolvedMode, backgroundColor: themeBackground, children: _jsx(Box, { sx: {
+        }, children: activeServiceManager && notebookReady ? (_jsx(ThemeRoot, { inherit: inheritTheme, colorMode: effectiveColorMode, themeConfig: themeConfig, children: _jsx(JupyterReactTheme, { colormode: resolvedMode, backgroundColor: themeBackground, children: _jsx(Box, { sx: {
                         position: 'absolute',
                         inset: 0,
                         display: 'flex',
@@ -275,6 +388,7 @@ export function EphemeralNotebook({ notebookId, runtimePodName, runtimeOverride,
                         overscrollBehaviorY: 'contain',
                         overflowAnchor: 'none',
                         padding: 2,
+                        backgroundColor: themeBackground,
                         // Give the notebook a resolved height so cells render. The
                         // Jupyter Notebook component renders its outer container with
                         // id "dla-Jupyter-Notebook"; pin its toolbar and let the cell
@@ -283,17 +397,36 @@ export function EphemeralNotebook({ notebookId, runtimePodName, runtimeOverride,
                             display: 'flex',
                             flexDirection: 'column',
                         },
-                        '& #dla-Jupyter-Notebook > :first-of-type': {
-                            position: 'sticky',
-                            top: 0,
-                            zIndex: 2,
-                            flex: '0 0 auto',
-                            background: 'var(--jp-layout-color0, transparent)',
-                        },
+                        // Pin the toolbar — but only while there is one. This targets
+                        // the first child, and with the toolbar gone that is the
+                        // notebook body: it would be made sticky and painted with the
+                        // toolbar's own background.
+                        ...(showToolbar
+                            ? {
+                                '& #dla-Jupyter-Notebook > :first-of-type': {
+                                    position: 'sticky',
+                                    top: 0,
+                                    zIndex: 2,
+                                    flex: '0 0 auto',
+                                    backgroundColor: themeBackground,
+                                },
+                            }
+                            : {
+                                // `Notebook` gives the panel header `min-height: 50px` to
+                                // reserve room for a toolbar. With no toolbar that room
+                                // is a white band under nothing.
+                                '& .datalayer-NotebookPanel-header': {
+                                    display: 'none',
+                                    minHeight: 0,
+                                },
+                            }),
                         '& #dla-Jupyter-Notebook > .dla-Box-Notebook': {
                             flex: '1 1 auto',
                             minHeight: 0,
                         },
-                    }, children: _jsx(Notebook, { nbformat: initialNbformat, id: notebookId, serviceManager: activeServiceManager, startDefaultKernel: activeStartDefaultKernel, kernelId: activeKernelId, height: "100%", cellSidebarMargin: cellSidebarMargin, extensions: extensions, Toolbar: ToolbarComponent, collaborationProvider: collaborationProvider }) }) }) })) : null }));
+                        '& [role="toolbar"][aria-label="Notebook toolbar"]': {
+                            backgroundColor: themeBackground,
+                        },
+                    }, children: _jsx(Notebook, { nbformat: initialNbformat, id: notebookId, path: sessionPath, serviceManager: activeServiceManager, startDefaultKernel: activeStartDefaultKernel, kernelId: activeKernelId, height: "100%", cellSidebarMargin: cellSidebarMargin, extensions: extensions, Toolbar: ToolbarComponent, collaborationProvider: collaborationProvider }) }) }) })) : null }));
 }
 export default EphemeralNotebook;

package/lib/chat/parts/DynamicToolPart.d.ts

@@ -16,5 +16,5 @@ export interface DynamicToolPartProps {
  * for dynamic tool parts. In a production application, this would
  * render custom UI based on the tool's specification.
  */
-export declare function DynamicToolPart({ part }: DynamicToolPartProps): import("react/jsx-runtime").JSX.Element;
+export declare function DynamicToolPart({ part }: DynamicToolPartProps): import("react").JSX.Element;
 export default DynamicToolPart;

package/lib/chat/parts/MessagePart.d.ts

@@ -46,5 +46,5 @@ export interface MessagePartProps {
  * ))}
  * ```
  */
-export declare function MessagePart({ part, message, status, regen, index, lastMessage, }: MessagePartProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function MessagePart({ part, message, status, regen, index, lastMessage, }: MessagePartProps): import("react").JSX.Element | null;
 export default MessagePart;

package/lib/chat/parts/ReasoningPart.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Reasoning message part display component.
+ * Renders AI reasoning/thinking content with collapsible section.
+ *
+ * @module chat/display/ReasoningPart
+ */
+import React from 'react';
 export interface ReasoningPartProps {
     /** Reasoning text content */
     text: string;
@@ -13,5 +20,5 @@ export interface ReasoningPartProps {
  * - Visual indicator for streaming state
  * - Markdown support for reasoning content
  */
-export declare function ReasoningPart({ text, isStreaming }: ReasoningPartProps): import("react/jsx-runtime").JSX.Element;
+export declare function ReasoningPart({ text, isStreaming }: ReasoningPartProps): React.JSX.Element;
 export default ReasoningPart;

package/lib/chat/parts/TextPart.d.ts

@@ -24,5 +24,5 @@ export interface TextPartProps {
  * - Regenerate button for assistant messages
  * - Syntax highlighting for code blocks
  */
-export declare function TextPart({ text, message, isLastPart, onRegenerate, }: TextPartProps): import("react/jsx-runtime").JSX.Element;
+export declare function TextPart({ text, message, isLastPart, onRegenerate, }: TextPartProps): import("react").JSX.Element;
 export default TextPart;

package/lib/chat/parts/ToolPart.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Tool call display component.
+ * Renders tool execution with input, output, and status.
+ *
+ * @module chat/display/ToolPart
+ */
+import React from 'react';
 import type { ToolUIPart } from 'ai';
 export interface ToolPartProps {
     /** Tool UI part data */
@@ -13,5 +20,5 @@ export interface ToolPartProps {
  * - JSON display for output/result
  * - Rich error display with execution vs code error distinction
  */
-export declare function ToolPart({ part }: ToolPartProps): import("react/jsx-runtime").JSX.Element;
+export declare function ToolPart({ part }: ToolPartProps): React.JSX.Element;
 export default ToolPart;

package/lib/chat/prompt/FloatingCard.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A card that floats over its host and can be dragged by its handle.
+ *
+ * The mechanics behind `InputPrompt`'s `draggable` prop, kept apart from the
+ * prompt so the prompt module stays about composing messages. The card is
+ * absolutely positioned against the nearest positioned ancestor — whoever
+ * mounts a floating prompt owns giving it one — and sits bottom-centre until
+ * somebody picks it up.
+ *
+ * @module chat/prompt/FloatingCard
+ */
+import type { JSX, ReactNode } from 'react';
+export type FloatingCardProps = {
+    children: ReactNode;
+    /**
+     * Which edge the card starts on, until somebody moves it.
+     *
+     * `bottom` (the default): over the work but under the eye, where a
+     * composer waits without being in the way. `top`: the command line of a
+     * page — the page layout puts the prompt where a document's title bar
+     * would be, so the sheet below it reads as the thing being worked on.
+     */
+    anchor?: 'bottom' | 'top';
+};
+export declare function FloatingCard({ children, anchor, }: FloatingCardProps): JSX.Element;
+export default FloatingCard;

package/lib/chat/prompt/FloatingCard.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useRef, useState } from 'react';
+import { Box } from '@datalayer/primer-addons';
+import { GrabberIcon } from '@primer/octicons-react';
+/** Keep the card reachable: at least this much of it stays inside. */
+const MARGIN = 8;
+export function FloatingCard({ children, anchor = 'bottom', }) {
+    const [position, setPosition] = useState(null);
+    const cardRef = useRef(null);
+    /* Where the pointer took hold of the card, so dragging moves the card by
+       the pointer's delta rather than snapping its corner to the cursor. */
+    const grip = useRef(null);
+    const onHandlePointerDown = useCallback((event) => {
+        const card = cardRef.current;
+        const parent = card?.offsetParent;
+        if (!card || !parent) {
+            return;
+        }
+        const cardBox = card.getBoundingClientRect();
+        const parentBox = parent.getBoundingClientRect();
+        grip.current = {
+            dx: event.clientX - cardBox.left,
+            dy: event.clientY - cardBox.top,
+        };
+        const handle = event.currentTarget;
+        // Absent in test DOMs; the move listeners below still work there.
+        handle.setPointerCapture?.(event.pointerId);
+        const move = (moved) => {
+            if (!grip.current) {
+                return;
+            }
+            // Clamped so the card cannot be dropped where its handle is
+            // unreachable — a prompt dragged off the edge is a prompt lost.
+            const left = Math.min(Math.max(moved.clientX - parentBox.left - grip.current.dx, MARGIN - cardBox.width / 2), parentBox.width - cardBox.width / 2 - MARGIN);
+            const top = Math.min(Math.max(moved.clientY - parentBox.top - grip.current.dy, MARGIN), parentBox.height - MARGIN * 4);
+            setPosition({ left, top });
+        };
+        const up = () => {
+            grip.current = null;
+            handle.removeEventListener('pointermove', move);
+            handle.removeEventListener('pointerup', up);
+            handle.removeEventListener('pointercancel', up);
+        };
+        handle.addEventListener('pointermove', move);
+        handle.addEventListener('pointerup', up);
+        handle.addEventListener('pointercancel', up);
+        event.preventDefault();
+    }, []);
+    return (_jsxs(Box, { ref: cardRef, "data-floating-prompt": "", sx: {
+            position: 'absolute',
+            // Bottom-centre until somebody moves it: over the work but under the
+            // eye, which is where a composer waits without being in the way.
+            ...(position
+                ? { left: position.left, top: position.top }
+                : anchor === 'top'
+                    ? { left: '50%', top: 16, transform: 'translateX(-50%)' }
+                    : { left: '50%', bottom: 16, transform: 'translateX(-50%)' }),
+            width: 'min(640px, calc(100% - 32px))',
+            zIndex: 20,
+            bg: 'canvas.default',
+            border: '1px solid',
+            borderColor: 'border.default',
+            borderRadius: 2,
+            boxShadow: 'shadow.large',
+            overflow: 'hidden',
+        }, children: [_jsx(Box, { onPointerDown: onHandlePointerDown, "aria-label": "Move the prompt", sx: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    height: 18,
+                    cursor: 'grab',
+                    color: 'fg.subtle',
+                    bg: 'canvas.subtle',
+                    borderBottom: '1px solid',
+                    borderColor: 'border.muted',
+                    touchAction: 'none',
+                    '&:active': { cursor: 'grabbing' },
+                }, children: _jsx(GrabberIcon, { size: 16 }) }), children] }));
+}
+export default FloatingCard;