@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/chat/display/ButtonGlow.d.ts

@@ -0,0 +1,9 @@
+export interface ButtonGlowProps {
+    /**
+     * The colour of the light: the button's own. A theme token or any CSS
+     * colour; the theme's `accent.emphasis` when absent.
+     */
+    color?: string;
+}
+export declare function ButtonGlow({ color }: ButtonGlowProps): import("react").JSX.Element;
+export default ButtonGlow;

package/lib/chat/display/ButtonGlow.js

@@ -0,0 +1,60 @@
+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.
+ */
+/**
+ * A soft light breathing around a round button, as if it were alive.
+ *
+ * Two blurred halos in the button's colour swell and fade on cycles of
+ * different lengths, 3.4 s and 5.3 s, so the light drifts rather than
+ * blinks: the two never line up the same way twice in a row. For a reader
+ * who asks the system for less motion, the halos hold still, a little dimmer.
+ *
+ * The halos sit behind the button: the parent must be `position: relative`
+ * and make a stacking context of its own (`isolation: 'isolate'`), or they
+ * would slip behind the page instead.
+ *
+ * @module chat/display/ButtonGlow
+ */
+import { Box } from '@datalayer/primer-addons';
+const halo = (color) => ({
+    position: 'absolute',
+    inset: 0,
+    borderRadius: '50%',
+    bg: color || 'accent.emphasis',
+    zIndex: -1,
+    pointerEvents: 'none',
+    willChange: 'transform, opacity',
+});
+export function ButtonGlow({ color }) {
+    return (_jsxs(_Fragment, { children: [_jsx(Box, { "aria-hidden": true, "data-button-glow": "breath", sx: {
+                    ...halo(color),
+                    filter: 'blur(10px)',
+                    animation: 'agentRuntimesGlowBreath 3.4s ease-in-out infinite',
+                    '@keyframes agentRuntimesGlowBreath': {
+                        '0%, 100%': { transform: 'scale(0.9)', opacity: 0.35 },
+                        '50%': { transform: 'scale(1.25)', opacity: 0.7 },
+                    },
+                    '@media (prefers-reduced-motion: reduce)': {
+                        animation: 'none',
+                        transform: 'scale(1.1)',
+                        opacity: 0.4,
+                    },
+                } }), _jsx(Box, { "aria-hidden": true, "data-button-glow": "aura", sx: {
+                    ...halo(color),
+                    filter: 'blur(18px)',
+                    animation: 'agentRuntimesGlowAura 5.3s ease-in-out infinite',
+                    '@keyframes agentRuntimesGlowAura': {
+                        '0%, 100%': { transform: 'scale(1)', opacity: 0.15 },
+                        '40%': { transform: 'scale(1.55)', opacity: 0.4 },
+                        '70%': { transform: 'scale(1.3)', opacity: 0.25 },
+                    },
+                    '@media (prefers-reduced-motion: reduce)': {
+                        animation: 'none',
+                        transform: 'scale(1.3)',
+                        opacity: 0.2,
+                    },
+                } })] }));
+}
+export default ButtonGlow;

package/lib/chat/display/EmptyState.d.ts

@@ -8,6 +8,20 @@
  */
 import { type ReactNode } from 'react';
 import type { EmptyStateConfig, Suggestion } from '../../types/chat';
+export { groupSuggestions } from './groupSuggestions';
+/**
+ * How wide a suggestion chip stands, in pixels — fixed, not a cap.
+ *
+ * An opener is a whole request in the words somebody would type, and some
+ * are a sentence long — "Explain this notebook cell by cell, as if I am new
+ * to Python" — while others are a few words — "Rerun with another model".
+ * Sized to their own words, a row of them read as uneven lines of text
+ * rather than as one set of options. One width, for every chip and every
+ * place that draws them (the empty state below and the page layout's row
+ * under the composer); past it the label truncates, and the chip's own
+ * title still carries the whole sentence on hover.
+ */
+export declare const SUGGESTION_CHIP_WIDTH = 140;
 export interface ChatEmptyStateProps {
     /** Empty-state configuration (icon, title, subtitle, render) */
     emptyState?: EmptyStateConfig;
@@ -24,4 +38,4 @@ export interface ChatEmptyStateProps {
     /** Whether clicking a suggestion auto-submits it */
     submitOnSuggestionClick?: boolean;
 }
-export declare function ChatEmptyState({ emptyState, brandIcon, description, suggestions, onSuggestionSubmit, onSuggestionFill, submitOnSuggestionClick, }: ChatEmptyStateProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatEmptyState({ emptyState, brandIcon, description, suggestions, onSuggestionSubmit, onSuggestionFill, submitOnSuggestionClick, }: ChatEmptyStateProps): import("react").JSX.Element;

package/lib/chat/display/EmptyState.js

@@ -2,6 +2,21 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { Text, LabelGroup, Label, Truncate, ThemeProvider, } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { AiAgentIcon } from '@datalayer/icons-react';
+import { groupSuggestions } from './groupSuggestions';
+export { groupSuggestions } from './groupSuggestions';
+/**
+ * How wide a suggestion chip stands, in pixels — fixed, not a cap.
+ *
+ * An opener is a whole request in the words somebody would type, and some
+ * are a sentence long — "Explain this notebook cell by cell, as if I am new
+ * to Python" — while others are a few words — "Rerun with another model".
+ * Sized to their own words, a row of them read as uneven lines of text
+ * rather than as one set of options. One width, for every chip and every
+ * place that draws them (the empty state below and the page layout's row
+ * under the composer); past it the label truncates, and the chip's own
+ * title still carries the whole sentence on hover.
+ */
+export const SUGGESTION_CHIP_WIDTH = 140;
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
@@ -18,24 +33,78 @@ export function ChatEmptyState({ emptyState, brandIcon, description, suggestions
             onSuggestionFill?.(suggestion.message);
         }
     };
+    /*
+     * The openers in blocks: the ungrouped ones first, as the one row they
+     * always were, then each group under its own heading in the order the
+     * groups first appear. A team's openers and, beneath them, the addressed
+     * member's own is the case this draws — and when the host gave the empty
+     * state *levels*, each level takes its own group's openers and the blocks
+     * below are only what no level claimed.
+     */
+    const sections = emptyState?.sections ?? [];
+    const claimed = new Set(sections.map(section => section.group));
+    const blocks = groupSuggestions((suggestions ?? []).filter(suggestion => suggestion.group === undefined || !claimed.has(suggestion.group)));
+    const chips = (items) => (_jsx(LabelGroup, { sx: { justifyContent: 'center' }, children: items.map((suggestion, index) => (_jsx(Label, { variant: "accent", 
+            // The whole request: the chip may show only its summary.
+            title: suggestion.message, sx: {
+                cursor: 'pointer',
+                display: 'inline-flex',
+                alignItems: 'center',
+                // A short opener sits in the middle of its fixed-width chip, not
+                // against its left edge with the rest of the chip empty.
+                justifyContent: 'center',
+                width: SUGGESTION_CHIP_WIDTH,
+                flex: `0 0 ${SUGGESTION_CHIP_WIDTH}px`,
+                '&:hover': {
+                    bg: 'accent.emphasis',
+                    color: 'var(--button-primary-fgColor-rest)',
+                    borderColor: 'accent.emphasis',
+                },
+            }, onClick: () => handleSuggestionClick(suggestion), children: _jsx(Truncate, { inline: true, title: suggestion.message, maxWidth: "100%", sx: { minWidth: 0 }, children: suggestion.title }) }, index))) }));
     return (_jsx(ThemeProvider, { children: _jsxs(Box, { sx: {
                 display: 'flex',
                 flexDirection: 'column',
+                // Centred across the column, anchored to its top: the introduction
+                // is where a conversation starts, and the first message should
+                // appear under it rather than push it around the canvas.
                 alignItems: 'center',
-                justifyContent: 'center',
-                height: '100%',
+                justifyContent: 'flex-start',
                 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))) }))] }) }));
+            }, children: [sections.length > 0 ? (
+                /*
+                 * Levels: the first at full size, the ones under it a step
+                 * smaller and set off by a rule — a team, then the member of it
+                 * being addressed, each introducing itself and offering its own
+                 * openers.
+                 */
+                sections.map((section, level) => (_jsxs(Box, { sx: {
+                        display: 'flex',
+                        flexDirection: 'column',
+                        alignItems: 'center',
+                        gap: 2,
+                        width: '100%',
+                        ...(level > 0
+                            ? {
+                                mt: 3,
+                                pt: 3,
+                                borderTop: '1px solid',
+                                borderColor: 'border.muted',
+                            }
+                            : null),
+                    }, children: [section.icon, _jsx(Text, { sx: {
+                                fontSize: level === 0 ? 2 : 1,
+                                fontWeight: level === 0 ? 'normal' : 'semibold',
+                            }, children: section.title }), section.subtitle ? (_jsx(Text, { sx: { fontSize: level === 0 ? 1 : 0 }, children: section.subtitle })) : null, (() => {
+                            const own = (suggestions ?? []).filter(suggestion => suggestion.group === section.group);
+                            return own.length > 0 ? chips(own) : null;
+                        })()] }, section.group)))) : (_jsxs(_Fragment, { 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 }))] })), blocks.map(block => (_jsxs(Box, { sx: {
+                        display: 'flex',
+                        flexDirection: 'column',
+                        alignItems: 'center',
+                        gap: 1,
+                        mt: 2,
+                    }, children: [block.group ? (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: block.group })) : null, chips(block.items)] }, block.group ?? '')))] }) }));
 }

package/lib/chat/display/FloatingBrandButton.d.ts

@@ -30,5 +30,5 @@ export interface FloatingBrandButtonProps {
  * Floating brand button component
  * A circular button that floats in a corner to open/close the chat
  */
-export declare function FloatingBrandButton({ isOpen, onToggle, position, icon, tooltip, unreadCount, className, brandColor, }: FloatingBrandButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function FloatingBrandButton({ isOpen, onToggle, position, icon, tooltip, unreadCount, className, brandColor, }: FloatingBrandButtonProps): React.JSX.Element;
 export default FloatingBrandButton;

package/lib/chat/display/PoweredByTag.d.ts

@@ -22,5 +22,5 @@ export interface PoweredByTagProps {
  * PoweredBy tag component
  * Displays a "Powered by X" branding tag
  */
-export declare function PoweredByTag({ show, brandName, brandUrl, brandIcon, }: PoweredByTagProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function PoweredByTag({ show, brandName, brandUrl, brandIcon, }: PoweredByTagProps): React.JSX.Element | null;
 export default PoweredByTag;

package/lib/chat/display/groupSuggestions.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Openers in blocks.
+ *
+ * A suggestion may name a `group`; the ungrouped ones come first, as one
+ * block, and each group follows as a block of its own in the order it first
+ * appears. The empty state draws the blocks as rows of chips under headings
+ * and the composer's suggestions menu as sections — the same shape, so a
+ * team's openers and the addressed member's own read the same in both.
+ *
+ * @module chat/display/groupSuggestions
+ */
+/** The least a suggestion needs to be grouped. */
+export type Groupable = {
+    group?: string;
+};
+export type SuggestionBlock<T extends Groupable> = {
+    group?: string;
+    items: T[];
+};
+/** The openers in blocks: the ungrouped first, then each group as it first appears. */
+export declare function groupSuggestions<T extends Groupable>(suggestions: T[]): SuggestionBlock<T>[];

package/lib/chat/display/groupSuggestions.js

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The openers in blocks: the ungrouped first, then each group as it first appears. */
+export function groupSuggestions(suggestions) {
+    const blocks = [];
+    for (const suggestion of suggestions) {
+        const block = blocks.find(entry => entry.group === suggestion.group);
+        if (block) {
+            block.items.push(suggestion);
+        }
+        else {
+            blocks.push({ group: suggestion.group, items: [suggestion] });
+        }
+    }
+    return blocks.sort((left, right) => left.group === undefined ? -1 : right.group === undefined ? 1 : 0);
+}

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

@@ -1,8 +1,27 @@
+/**
+ * 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 '@datalayer/jupyter-react/lib/css/PrismCss';
+import type { JSX } from 'react';
+import { ServiceManager } from '@jupyterlab/services';
 import type { IKernelConnection } from '@jupyterlab/services/lib/kernel/kernel';
 import { type ToolbarItem } from '@datalayer/primer-addons';
 import type { FrontendToolDefinition } from '../../types/tools';
 import type { EphemeralRuntimeOverride } from '../notebook/EphemeralNotebook';
-import '@datalayer/jupyter-react/lib/css/PrismCss';
 import '@datalayer/jupyter-lexical/style/index.css';
 /**
  * Real-time collaboration configuration for the ephemeral document.
@@ -38,9 +57,27 @@ export interface EphemeralDocumentProps {
      */
     documentId: string;
     /** Preferred runtime pod name to bind the document kernel to. */
-    runtimePodName?: string;
+    runtimeName?: string;
     /** Optional explicit runtime endpoint (agent-node tunnel proxy path). */
     runtimeOverride?: EphemeralRuntimeOverride;
+    /**
+     * Services the host already has, used instead of building some from a URL.
+     *
+     * An in-page sandbox — JupyterLite over Pyodide — has no address to connect
+     * to: it *is* the services. Without this the document had no way to reach
+     * such a kernel and rendered an empty editor with nothing in the console,
+     * because "no base url" was a silent early return rather than a failure.
+     *
+     * The host keeps ownership: a manager passed in is never disposed here.
+     */
+    serviceManager?: ServiceManager.IManager;
+    /**
+     * Kernel to join on that manager, rather than starting another.
+     *
+     * The agent and the reader should be looking at one kernel; starting a
+     * second one beside it is how they end up with different variables.
+     */
+    kernelId?: string;
     /** Optional theme variant override from host chat context. */
     themeVariant?: string;
     /** Optional color mode override from host chat context. */
@@ -73,10 +110,37 @@ export interface EphemeralDocumentProps {
      * change it — the same way the notebook surface does through the
      * `extraItems` of its toolbar.
      */
+    /**
+     * 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;
     toolbarExtraItems?: ToolbarItem[];
+    /**
+     * 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 document takes the caret once its editor mounts. Defaults to
+     * `true`.
+     *
+     * `false` for a host whose composer already asked for the caret on mount:
+     * this editor only exists once a sandbox — and, for the ephemeral case, a
+     * kernel — has finished starting, well after a chat composer's own
+     * `autoFocus` effect has already run and stopped watching, so the
+     * document's unconditional autofocus otherwise steals the caret back a
+     * moment later purely by mounting second.
+     */
+    autoFocus?: boolean;
 }
-/**
- * Renders an in-memory Lexical document backed by a sandbox kernel.
- */
-export declare function EphemeralDocument({ documentId, runtimePodName, runtimeOverride, themeVariant, colorMode, content, onContentChange, onToolsReady, onKernelChange, collaboration, toolbarExtraItems, }: EphemeralDocumentProps): import("react/jsx-runtime").JSX.Element;
+export declare function EphemeralDocument({ documentId, runtimeName, runtimeOverride, serviceManager: providedServiceManager, kernelId, themeVariant, colorMode, content, onContentChange, onToolsReady, onKernelChange, collaboration, toolbarExtraItems, showToolbar, inheritTheme, autoFocus, }: EphemeralDocumentProps): JSX.Element;
 export default EphemeralDocument;