@datalayer/agent-runtimes 0.0.11 → 1.0.0

package/lib/lexical/ChatInlinePlugin.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 /*
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
@@ -6,27 +6,41 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * ChatInlinePlugin - Lexical plugin for inline AI chat.
  *
- * This plugin displays a floating AI chat interface when text is selected
- * in the Lexical editor. It provides AI-powered text manipulation features
- * like improve, summarize, translate, etc.
+ * This plugin displays a floating AI chat interface when the user triggers
+ * an AI action (via the toolbar's AI dropdown or sparkle button). It provides
+ * AI-powered text manipulation features like improve, summarize, translate, etc.
  *
- * Features:
- * - Detects text selection in the editor
- * - Shows floating ChatInline component near the selection
- * - Supports custom prompts and pre-defined AI actions
- * - Can replace selection, insert inline, or insert below
- * - Uses floating-ui for positioning
+ * IMPORTANT: This plugin no longer renders its own formatting toolbar.
+ * Instead, AI actions are registered as `extraItems` in the
+ * `FloatingTextFormatToolbarPlugin` via the `useChatInlineToolbarItems` hook.
+ *
+ * Usage:
+ * ```tsx
+ * const { toolbarItems, isAiOpen, pendingPrompt, clearPendingPrompt, closeAi } =
+ *   useChatInlineToolbarItems();
+ *
+ * <FloatingTextFormatToolbarPlugin
+ *   anchorElem={floatingAnchorElem}
+ *   setIsLinkEditMode={setIsLinkEditMode}
+ *   extraItems={toolbarItems}
+ * />
+ * <ChatInlinePlugin
+ *   protocol={protocol}
+ *   isOpen={isAiOpen}
+ *   onClose={closeAi}
+ *   pendingPrompt={pendingPrompt}
+ *   onPendingPromptConsumed={clearPendingPrompt}
+ * />
+ * ```
  *
  * @module lexical/ChatInlinePlugin
  */
-import { useCallback, useEffect, useLayoutEffect, useRef, useState, } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { createPortal } from 'react-dom';
-import { $getSelection, $isRangeSelection, $createParagraphNode, $createTextNode, TextNode, COMMAND_PRIORITY_LOW, createCommand, FORMAT_TEXT_COMMAND, } from 'lexical';
-import { $isLinkNode, TOGGLE_LINK_COMMAND } from '@lexical/link';
+import { $getSelection, $isRangeSelection, $createParagraphNode, $createTextNode, TextNode, COMMAND_PRIORITY_LOW, createCommand, } from 'lexical';
 import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
 import { autoUpdate, hide, limitShift, offset, shift, size, useFloating, } from '@floating-ui/react-dom';
-import { Box, IconButton } from '@primer/react';
-import { BoldIcon, ItalicIcon, StrikethroughIcon, CodeIcon, LinkIcon, SparkleFillIcon, } from '@primer/octicons-react';
+import { Box } from '@primer/react';
 import { ChatInline, } from '../components/chat/components/ChatInline';
 // Margin from editor edges
 const MARGIN_X = 32;
@@ -53,7 +67,6 @@ function usePreserveSelection(editor) {
                 editor.update(() => {
                     const selection = savedSelectionRef.current;
                     if (selection) {
-                        // Note: We create a new reference to avoid stale selection issues
                         try {
                             const anchor = selection.anchor;
                             const focus = selection.focus;
@@ -83,16 +96,13 @@ function usePreserveSelection(editor) {
 }
 /**
  * Hook to get current text selection range
- * Uses native DOM selection for immediate response during drag operations
  */
 function useRange() {
     const [editor] = useLexicalComposerContext();
     const [range, setRange] = useState(null);
     useEffect(() => {
-        // Function to update range from DOM selection
         const updateRange = () => {
             const domSelection = window.getSelection();
-            // Check if selection exists and is within the editor
             if (!domSelection ||
                 domSelection.rangeCount === 0 ||
                 !editor._rootElement) {
@@ -100,26 +110,21 @@ function useRange() {
                 return;
             }
             const domRange = domSelection.getRangeAt(0);
-            // Check if selection is within the editor
             if (!editor._rootElement.contains(domRange.commonAncestorContainer)) {
                 setRange(null);
                 return;
             }
-            // Check if selection is collapsed (just a cursor, no text selected)
             if (domRange.collapsed) {
                 setRange(null);
                 return;
             }
             setRange(domRange.cloneRange());
         };
-        // Listen for Lexical editor updates
         const unregister = editor.registerUpdateListener(({ tags }) => {
-            // Ignore collaboration updates
             if (tags.has('collaboration'))
                 return;
             updateRange();
         });
-        // Listen for DOM selection changes to catch drag selections
         document.addEventListener('selectionchange', updateRange);
         return () => {
             unregister();
@@ -145,91 +150,18 @@ function useSelectionText() {
     return textContent;
 }
 /**
- * Hook to detect if mouse is pressed outside a specific element (for drag selection detection)
- * Returns true only when mouse is down AND the click started outside the provided element
- */
-function useIsMouseDownOutside(getElement) {
-    const [isMouseDownOutside, setIsMouseDownOutside] = useState(false);
-    // Force update counter to trigger re-render on mouseup
-    const [, forceUpdate] = useState(0);
-    useEffect(() => {
-        const handleMouseDown = (e) => {
-            const element = getElement();
-            // Check if the click is outside the toolbar element
-            if (element && element.contains(e.target)) {
-                // Click is inside toolbar, don't set mouse down state
-                setIsMouseDownOutside(false);
-            }
-            else {
-                // Click is outside toolbar (in editor), set mouse down state
-                setIsMouseDownOutside(true);
-            }
-        };
-        const handleMouseUp = () => {
-            setIsMouseDownOutside(false);
-            // Force a re-render to show toolbar after selection completes
-            forceUpdate(n => n + 1);
-        };
-        document.addEventListener('mousedown', handleMouseDown);
-        document.addEventListener('mouseup', handleMouseUp);
-        return () => {
-            document.removeEventListener('mousedown', handleMouseDown);
-            document.removeEventListener('mouseup', handleMouseUp);
-        };
-    }, [getElement]);
-    return isMouseDownOutside;
-}
-/**
- * ChatInlinePlugin - Floating AI toolbar for Lexical text selection.
+ * ChatInlinePlugin - Floating AI chat panel for Lexical text selection.
+ *
+ * This plugin is controlled externally via `isOpen` prop. It positions a
+ * ChatInline component near the text selection when open.
  */
-export function ChatInlinePlugin({ protocol, portalContainer, }) {
+export function ChatInlinePlugin({ protocol, isOpen, onClose, pendingPrompt, onPendingPromptConsumed, portalContainer, }) {
     const [editor] = useLexicalComposerContext();
-    const [toolbarState, setToolbarState] = useState('closed');
-    const [fullWidth, setFullWidth] = useState(false);
     const padding = 20;
-    // Text format state
-    const [isBold, setIsBold] = useState(false);
-    const [isItalic, setIsItalic] = useState(false);
-    const [isStrikethrough, setIsStrikethrough] = useState(false);
-    const [isCode, setIsCode] = useState(false);
-    const [isLink, setIsLink] = useState(false);
-    // Update text format state based on selection
-    const updateFormatState = useCallback(() => {
-        editor.getEditorState().read(() => {
-            const selection = $getSelection();
-            if ($isRangeSelection(selection)) {
-                setIsBold(selection.hasFormat('bold'));
-                setIsItalic(selection.hasFormat('italic'));
-                setIsStrikethrough(selection.hasFormat('strikethrough'));
-                setIsCode(selection.hasFormat('code'));
-                // Check if selection contains a link
-                const nodes = selection.getNodes();
-                const isLinkNode = nodes.some(node => {
-                    const parent = node.getParent();
-                    return $isLinkNode(parent) || $isLinkNode(node);
-                });
-                setIsLink(isLinkNode);
-            }
-        });
-    }, [editor]);
-    // Listen for selection changes to update format state
-    useEffect(() => {
-        return editor.registerUpdateListener(({ editorState }) => {
-            editorState.read(() => {
-                updateFormatState();
-            });
-        });
-    }, [editor, updateFormatState]);
     // Selection preservation
     const { saveSelection, restoreSelection } = usePreserveSelection(editor);
-    // Ref for the toolbar container to detect clicks inside vs outside
-    const toolbarRef = useRef(null);
-    // Stable getter function for the toolbar element
-    const getToolbarElement = useCallback(() => toolbarRef.current, []);
-    // Track mouse state for detecting ongoing drag selections (only outside toolbar)
-    const isMouseDownOutside = useIsMouseDownOutside(getToolbarElement);
     // Floating UI setup
-    const { refs: { setReference, setFloating }, strategy, x, y, } = useFloating({
+    const { refs: { setReference, setFloating }, strategy, y, } = useFloating({
         strategy: 'fixed',
         placement: 'bottom',
         middleware: [
@@ -247,23 +179,33 @@ export function ChatInlinePlugin({ protocol, portalContainer, }) {
     // Selection tracking
     const { range } = useRange();
     const selectedText = useSelectionText();
-    // Update floating reference position based on selection
-    useLayoutEffect(() => {
-        setReference({
-            getBoundingClientRect: () => range?.getBoundingClientRect() || new DOMRect(),
-        });
-    }, [setReference, range]);
-    // Reset width when selection is removed, show button when selection appears
+    // ---------------------------------------------------------------
+    // Latch: save position & text when AI panel opens so that a
+    // transient selection loss (e.g. portal render triggering
+    // selectionchange) does not unmount the panel.
+    // ---------------------------------------------------------------
+    const savedRectRef = useRef(null);
+    const savedTextRef = useRef('');
     useEffect(() => {
-        if (range === null) {
-            setFullWidth(false);
-            setToolbarState('closed');
+        if (isOpen && range) {
+            // Keep saving the latest rect/text while open and range is valid
+            savedRectRef.current = range.getBoundingClientRect();
+            savedTextRef.current = selectedText || '';
         }
-        else {
-            // Only transition from closed to button, not from ai to button
-            setToolbarState(prev => (prev === 'closed' ? 'button' : prev));
+        if (!isOpen) {
+            savedRectRef.current = null;
+            savedTextRef.current = '';
         }
-    }, [range]);
+    }, [isOpen, range, selectedText]);
+    // Effective values: prefer live selection, fall back to saved snapshot
+    const effectiveRect = useMemo(() => range?.getBoundingClientRect() ?? savedRectRef.current ?? null, [range]);
+    const effectiveText = range ? selectedText : savedTextRef.current;
+    // Update floating reference position based on selection (or saved rect)
+    useLayoutEffect(() => {
+        setReference({
+            getBoundingClientRect: () => effectiveRect || new DOMRect(),
+        });
+    }, [setReference, effectiveRect]);
     // Handle replace selection
     const handleReplaceSelection = useCallback((text) => {
         editor.update(() => {
@@ -298,82 +240,23 @@ export function ChatInlinePlugin({ protocol, portalContainer, }) {
             }
         });
     }, [editor]);
-    // Handle close
-    const handleClose = useCallback(() => {
-        setToolbarState('button');
-        setFullWidth(false);
-    }, []);
-    // Handle open AI
-    const handleOpenAI = useCallback(() => {
-        setToolbarState('ai');
-        setFullWidth(true);
-    }, []);
-    // Text formatting handlers
-    const handleFormat = useCallback((format) => {
-        editor.dispatchCommand(FORMAT_TEXT_COMMAND, format);
-    }, [editor]);
-    const handleToggleLink = useCallback(() => {
-        if (isLink) {
-            editor.dispatchCommand(TOGGLE_LINK_COMMAND, null);
-        }
-        else {
-            editor.dispatchCommand(TOGGLE_LINK_COMMAND, 'https://');
-        }
-    }, [editor, isLink]);
-    // Don't render if no selection, mouse is still down outside toolbar (dragging), or toolbar closed
-    if (range === null || isMouseDownOutside || toolbarState === 'closed') {
+    // Don't render if not open, or if we have neither a live range nor a saved rect
+    if (!isOpen || (range === null && savedRectRef.current === null)) {
         return null;
     }
     const portalTarget = portalContainer || document.body;
-    return createPortal(_jsxs(Box, { ref: (el) => {
-            setFloating(el);
-            toolbarRef.current =
-                el;
-        }, sx: {
+    return createPortal(_jsx(Box, { ref: setFloating, sx: {
             pointerEvents: 'auto',
             zIndex: 50,
             position: strategy,
             top: 0,
-            left: fullWidth && editor._rootElement
+            left: editor._rootElement
                 ? editor._rootElement.getBoundingClientRect().left + MARGIN_X
                 : 0,
-            transform: fullWidth
-                ? `translate3d(0, ${Math.round(y)}px, 0)`
-                : `translate3d(${Math.round(x)}px, ${Math.round(y)}px, 0)`,
-            width: fullWidth && editor._rootElement
+            transform: `translate3d(0, ${Math.round(y)}px, 0)`,
+            width: editor._rootElement
                 ? editor._rootElement.getBoundingClientRect().width - MARGIN_X * 2
                 : 'auto',
-            minWidth: fullWidth ? undefined : 'max-content',
-        }, children: [toolbarState === 'button' && (_jsxs(Box, { sx: {
-                    display: 'flex',
-                    alignItems: 'center',
-                    gap: 0,
-                    p: 1,
-                    borderRadius: '12px',
-                    border: '1px solid',
-                    borderColor: 'border.default',
-                    boxShadow: 'shadow.large',
-                    bg: 'canvas.default',
-                }, children: [_jsx(IconButton, { icon: BoldIcon, "aria-label": "Bold", variant: "invisible", onClick: () => handleFormat('bold'), sx: {
-                            color: isBold ? 'accent.fg' : 'fg.muted',
-                            bg: isBold ? 'accent.subtle' : 'transparent',
-                        } }), _jsx(IconButton, { icon: ItalicIcon, "aria-label": "Italic", variant: "invisible", onClick: () => handleFormat('italic'), sx: {
-                            color: isItalic ? 'accent.fg' : 'fg.muted',
-                            bg: isItalic ? 'accent.subtle' : 'transparent',
-                        } }), _jsx(IconButton, { icon: StrikethroughIcon, "aria-label": "Strikethrough", variant: "invisible", onClick: () => handleFormat('strikethrough'), sx: {
-                            color: isStrikethrough ? 'accent.fg' : 'fg.muted',
-                            bg: isStrikethrough ? 'accent.subtle' : 'transparent',
-                        } }), _jsx(IconButton, { icon: CodeIcon, "aria-label": "Code", variant: "invisible", onClick: () => handleFormat('code'), sx: {
-                            color: isCode ? 'accent.fg' : 'fg.muted',
-                            bg: isCode ? 'accent.subtle' : 'transparent',
-                        } }), _jsx(IconButton, { icon: LinkIcon, "aria-label": "Link", variant: "invisible", onClick: handleToggleLink, sx: {
-                            color: isLink ? 'accent.fg' : 'fg.muted',
-                            bg: isLink ? 'accent.subtle' : 'transparent',
-                        } }), _jsx(Box, { sx: {
-                            width: '1px',
-                            height: '16px',
-                            bg: 'border.default',
-                            mx: 1,
-                        } }), _jsx(IconButton, { icon: SparkleFillIcon, "aria-label": "AI Assistant", variant: "invisible", onClick: handleOpenAI, sx: { color: 'fg.muted' } })] })), toolbarState === 'ai' && (_jsx(ChatInline, { selectedText: selectedText, protocol: protocol, onReplaceSelection: handleReplaceSelection, onInsertInline: handleInsertInline, onInsertBelow: handleInsertBelow, onClose: handleClose, onSaveSelection: saveSelection, onRestoreSelection: restoreSelection }))] }), portalTarget);
+        }, children: _jsx(ChatInline, { selectedText: effectiveText, protocol: protocol, onReplaceSelection: handleReplaceSelection, onInsertInline: handleInsertInline, onInsertBelow: handleInsertBelow, onClose: onClose, onSaveSelection: saveSelection, onRestoreSelection: restoreSelection, pendingPrompt: pendingPrompt, onPendingPromptConsumed: onPendingPromptConsumed }) }), portalTarget);
 }
 export default ChatInlinePlugin;

package/lib/lexical/index.d.ts

@@ -4,3 +4,4 @@
  * @module lexical
  */
 export { ChatInlinePlugin, type ChatInlinePluginProps, SAVE_SELECTION_COMMAND, RESTORE_SELECTION_COMMAND, } from './ChatInlinePlugin';
+export { useChatInlineToolbarItems, type ChatInlineToolbarOptions, type ChatInlineToolbarState, } from './useChatInlineToolbarItems';

package/lib/lexical/index.js

@@ -8,3 +8,4 @@
  * @module lexical
  */
 export { ChatInlinePlugin, SAVE_SELECTION_COMMAND, RESTORE_SELECTION_COMMAND, } from './ChatInlinePlugin';
+export { useChatInlineToolbarItems, } from './useChatInlineToolbarItems';

package/lib/lexical/useChatInlineToolbarItems.d.ts

@@ -0,0 +1,35 @@
+import type { ToolbarItem } from '@datalayer/primer-addons';
+/**
+ * Return type for useChatInlineToolbarItems.
+ */
+export interface ChatInlineToolbarState {
+    /** ToolbarItem[] to pass as extraItems to FloatingTextFormatToolbarPlugin */
+    toolbarItems: ToolbarItem[];
+    /** Whether the AI inline chat panel is open */
+    isAiOpen: boolean;
+    /** Submit a prompt directly (used by the dropdown actions) */
+    submitPrompt: (prompt: string) => void;
+    /** The pending prompt (set by dropdown, consumed by ChatInlinePlugin) */
+    pendingPrompt: string | null;
+    /** Clear the pending prompt after it has been consumed */
+    clearPendingPrompt: () => void;
+    /** Open the AI panel (with custom prompt input) */
+    openAi: () => void;
+    /** Close the AI panel */
+    closeAi: () => void;
+}
+/**
+ * Options for useChatInlineToolbarItems.
+ */
+export interface ChatInlineToolbarOptions {
+    /** When true the AI sparkle button is rendered in a disabled state. */
+    disabled?: boolean;
+}
+/**
+ * Hook that creates ToolbarItem[] for AI actions in the floating toolbar.
+ *
+ * Returns toolbar items (divider + AI sparkle button) and
+ * state for controlling the ChatInline panel.
+ */
+export declare function useChatInlineToolbarItems(options?: ChatInlineToolbarOptions): ChatInlineToolbarState;
+export default useChatInlineToolbarItems;

package/lib/lexical/useChatInlineToolbarItems.js

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * useChatInlineToolbarItems - Hook that creates ToolbarItem[] for the
+ * FloatingTextFormatToolbarPlugin's extraItems prop.
+ *
+ * Registers an AI sparkle button in the floating inline toolbar.
+ * Clicking the sparkle button directly opens the ChatInlinePlugin
+ * floating panel, where users can type free-form AI prompts.
+ *
+ * Usage:
+ * ```tsx
+ * const { toolbarItems, isAiOpen, pendingPrompt, clearPendingPrompt, closeAi } =
+ *   useChatInlineToolbarItems();
+ *
+ * <FloatingTextFormatToolbarPlugin
+ *   anchorElem={floatingAnchorElem}
+ *   setIsLinkEditMode={setIsLinkEditMode}
+ *   extraItems={toolbarItems}
+ * />
+ *
+ * <ChatInlinePlugin
+ *   isOpen={isAiOpen}
+ *   onClose={closeAi}
+ *   pendingPrompt={pendingPrompt}
+ *   onPendingPromptConsumed={clearPendingPrompt}
+ * />
+ * ```
+ *
+ * @module lexical/useChatInlineToolbarItems
+ */
+import { useState, useMemo, useCallback } from 'react';
+import { SparkleFillIcon } from '@primer/octicons-react';
+/**
+ * Hook that creates ToolbarItem[] for AI actions in the floating toolbar.
+ *
+ * Returns toolbar items (divider + AI sparkle button) and
+ * state for controlling the ChatInline panel.
+ */
+export function useChatInlineToolbarItems(options) {
+    const [isAiOpen, setIsAiOpen] = useState(false);
+    const [pendingPrompt, setPendingPrompt] = useState(null);
+    const openAi = useCallback(() => {
+        setIsAiOpen(true);
+    }, []);
+    const closeAi = useCallback(() => {
+        setIsAiOpen(false);
+        setPendingPrompt(null);
+    }, []);
+    const submitPrompt = useCallback((prompt) => {
+        setPendingPrompt(prompt);
+        setIsAiOpen(true);
+    }, []);
+    const clearPendingPrompt = useCallback(() => {
+        setPendingPrompt(null);
+    }, []);
+    const isDisabled = options?.disabled ?? false;
+    const toolbarItems = useMemo(() => {
+        return [
+            {
+                key: 'ai-divider',
+                type: 'divider',
+                order: 900,
+            },
+            {
+                key: 'ai-actions',
+                type: 'button',
+                order: 901,
+                ariaLabel: 'AI Actions',
+                title: isDisabled
+                    ? 'Assign an agent to enable AI actions'
+                    : 'AI Actions',
+                icon: SparkleFillIcon,
+                onClick: openAi,
+                disabled: isDisabled,
+            },
+        ];
+    }, [openAi, isDisabled]);
+    return {
+        toolbarItems,
+        isAiOpen,
+        submitPrompt,
+        pendingPrompt,
+        clearPendingPrompt,
+        openAi,
+        closeAi,
+    };
+}
+export default useChatInlineToolbarItems;

package/lib/runtime/useAgentRuntime.d.ts

@@ -82,7 +82,7 @@ export interface UseAgentRuntimeReturn {
  *     <>
  *       <Notebook />
  *       {isReady && (
- *         <ChatFloating endpoint={endpoint} tools={tools} />
+ *         <ChatFloating endpoint={endpoint} frontendTools={frontendTools} />
  *       )}
  *       {error && <ErrorBanner>{error}</ErrorBanner>}
  *     </>

package/lib/runtime/useAgentRuntime.js

@@ -57,7 +57,7 @@ import { useRuntimeStore, useRuntime, useAgent, useRuntimeStatus, useRuntimeErro
  *     <>
  *       <Notebook />
  *       {isReady && (
- *         <ChatFloating endpoint={endpoint} tools={tools} />
+ *         <ChatFloating endpoint={endpoint} frontendTools={frontendTools} />
  *       )}
  *       {error && <ErrorBanner>{error}</ErrorBanner>}
  *     </>

package/lib/{config/agents/code-ai → specs/agents/codeai}/agents.d.ts

@@ -5,7 +5,8 @@
  * THIS FILE IS AUTO-GENERATED. DO NOT EDIT MANUALLY.
  * Generated from YAML specifications in specs/agents/
  */
-import type { AgentSpec } from '../../../types';
+import type { AgentSpec } from '../../../types/Types';
+export declare const DATA_ACQUISITION_AGENT_SPEC: AgentSpec;
 export declare const SIMPLE_AGENT_SPEC: AgentSpec;
 export declare const AGENT_SPECS: Record<string, AgentSpec>;
 /**
@@ -14,8 +15,10 @@ export declare const AGENT_SPECS: Record<string, AgentSpec>;
 export declare function getAgentSpecs(agentId: string): AgentSpec | undefined;
 /**
  * List all available agent specifications.
+ *
+ * @param prefix - If provided, only return specs whose ID starts with this prefix.
  */
-export declare function listAgentSpecs(): AgentSpec[];
+export declare function listAgentSpecs(prefix?: string): AgentSpec[];
 /**
  * Collect all required environment variables for an agent spec.
  *