@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/chat/prompt/plugins/CommandPlugin.js

@@ -0,0 +1,359 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { ActionList, Overlay } from '@primer/react';
+import { CommentDiscussionIcon, FoldIcon, BriefcaseIcon, ToolsIcon, } from '@primer/octicons-react';
+import { Box } from '@datalayer/primer-addons';
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
+import { $getSelection, $isRangeSelection, COMMAND_PRIORITY_CRITICAL, KEY_ARROW_DOWN_COMMAND, KEY_ARROW_UP_COMMAND, KEY_ENTER_COMMAND, KEY_ESCAPE_COMMAND, } from 'lexical';
+/**
+ * The commands, for now.
+ *
+ * Hardcoded and every one disabled, because none of them is wired to anything
+ * yet. A menu that lists what is coming is honest; one that accepts a choice
+ * and does nothing is not.
+ */
+export const PROMPT_COMMANDS = [
+    {
+        name: 'compact',
+        description: 'Shorten the conversation so far, keeping what the agent still needs.',
+        icon: FoldIcon,
+        disabled: true,
+        disabledReason: 'Not wired up yet',
+    },
+    {
+        name: 'mcp',
+        description: 'Show the MCP servers this agent can reach, and their tools.',
+        icon: ToolsIcon,
+        disabled: true,
+        disabledReason: 'Not wired up yet',
+    },
+    {
+        name: 'skills',
+        description: 'Show the skills loaded into this agent, and what they do.',
+        icon: BriefcaseIcon,
+        disabled: true,
+        disabledReason: 'Not wired up yet',
+    },
+];
+/**
+ * How wide the menu is, and how tall it may grow.
+ *
+ * Named because the position is computed from them: the menu is lifted its own
+ * height to sit above the caret, and held back from the right edge by its own
+ * width.
+ */
+const MENU_WIDTH = 440;
+const MENU_MAX_HEIGHT = 240;
+/**
+ * Read the `/word` immediately before the caret.
+ *
+ * Anchored to a word boundary so a path or a fraction does not open a menu:
+ * `/` counts only at the start of the text or after whitespace.
+ */
+function readCommandQuery(editor) {
+    let query = null;
+    editor.getEditorState().read(() => {
+        const selection = $getSelection();
+        if (!$isRangeSelection(selection) || !selection.isCollapsed()) {
+            return;
+        }
+        const node = selection.anchor.getNode();
+        const before = node.getTextContent().slice(0, selection.anchor.offset);
+        const match = /(?:^|\s)\/([\w-]*)$/.exec(before);
+        if (!match) {
+            return;
+        }
+        const domSelection = window.getSelection();
+        const rect = domSelection && domSelection.rangeCount > 0
+            ? domSelection.getRangeAt(0).getBoundingClientRect()
+            : null;
+        query = { text: match[1], rect };
+    });
+    return query;
+}
+/**
+ * Offer the commands while `/` is being typed.
+ */
+export function CommandPlugin({ commands, }) {
+    const [editor] = useLexicalComposerContext();
+    const [query, setQuery] = useState(null);
+    const [highlighted, setHighlighted] = useState(0);
+    const anchorRef = useRef(null);
+    /* The rows, by command name, so the lit one can be brought into view. */
+    const rowRefs = useRef(new Map());
+    /* Set while the document change that inserted a command is being applied. */
+    const justInserted = useRef(false);
+    const matches = query
+        ? commands.filter(command => command.name.toLowerCase().startsWith(query.text.toLowerCase()))
+        : [];
+    const open = matches.length > 0;
+    /*
+     * Where the arrows and Enter may land. A disabled row is in `matches` so it
+     * renders, and out of here so the keyboard never selects it — the two lists
+     * exist because "shown" and "choosable" stopped being the same thing.
+     */
+    const choosable = matches.filter(command => !command.disabled);
+    /*
+     * Back to the first choosable row whenever the typing changes.
+     *
+     * Kept in range as the list narrows — a highlight past the end would submit
+     * nothing on Enter, which reads as the key being broken — and reset
+     * outright as the `@word` changes, so each new filter offers its best match
+     * rather than whichever position the last one happened to leave behind.
+     */
+    useEffect(() => {
+        setHighlighted(0);
+    }, [query?.text]);
+    useEffect(() => {
+        setHighlighted(current => (current < choosable.length ? current : 0));
+    }, [choosable.length]);
+    /*
+     * Keep the lit row in view: the menu scrolls past a few rows, and a
+     * highlight moved below the fold is a choice the person cannot see.
+     */
+    const litName = choosable[highlighted]?.name;
+    useEffect(() => {
+        if (!open || !litName) {
+            return;
+        }
+        const row = rowRefs.current.get(litName);
+        if (row && typeof row.scrollIntoView === 'function') {
+            row.scrollIntoView({ block: 'nearest' });
+        }
+    }, [open, litName]);
+    useEffect(() => {
+        return editor.registerUpdateListener(() => {
+            const next = readCommandQuery(editor);
+            if (justInserted.current) {
+                /*
+                 * Every update belonging to the insertion, not just the first.
+                 *
+                 * One `editor.update()` raises several of them — the range emptied,
+                 * the node placed, the trailing space — and they all run
+                 * synchronously. Clearing the flag on the first let a later one
+                 * reopen the menu against the chip just written, a line higher, which
+                 * is what a reader saw. Clearing it on "the caret asks nothing" was
+                 * the same bet in a different disguise: it assumed one of those
+                 * intermediate states would read as settled, and one did not.
+                 *
+                 * The flag is lifted on the next macrotask instead, which is after
+                 * every synchronous update from this edit and before anything a
+                 * person can type.
+                 */
+                setQuery(null);
+                return;
+            }
+            setQuery(next);
+        });
+    }, [editor]);
+    /** Replace the `@partial` with the chosen name. */
+    const insert = useCallback((command) => {
+        editor.update(() => {
+            const selection = $getSelection();
+            if (!$isRangeSelection(selection) || !selection.isCollapsed()) {
+                return;
+            }
+            const node = selection.anchor.getNode();
+            const offset = selection.anchor.offset;
+            const before = node.getTextContent().slice(0, offset);
+            const match = /(?:^|\s)\/([\w-]*)$/.exec(before);
+            if (!match) {
+                return;
+            }
+            // Only the typed fragment is replaced, so whatever preceded it —
+            // including the space that made `@` a mention — survives.
+            const start = offset - match[1].length - 1;
+            selection.setTextNodeRange(node, start, node, offset);
+            // Plain text. A command is one word with no spaces in it, so the
+            // editing hazard that made a mention a node does not arise here.
+            selection.insertText(`/${command.name} `);
+        });
+        justInserted.current = true;
+        setQuery(null);
+        window.setTimeout(() => {
+            justInserted.current = false;
+        }, 0);
+    }, [editor]);
+    /*
+     * The menu owns these keys only while it is open, so Enter still submits and
+     * the arrows still move the caret the rest of the time.
+     *
+     * At `CRITICAL`, above the `HIGH` the submit handler uses. Lexical runs the
+     * higher priority first and stops at the first handler that returns true —
+     * so registering these `LOW` meant Enter reached submit before the menu ever
+     * saw it, and choosing an command sent the half-written message instead.
+     *
+     * Being above submit is safe precisely because this effect only runs while
+     * the menu is open, and each handler declines when it has nothing to do.
+     */
+    useEffect(() => {
+        if (!open) {
+            return undefined;
+        }
+        const unregister = [
+            editor.registerCommand(KEY_ARROW_DOWN_COMMAND, (event) => {
+                /*
+                  Declined when nothing can be chosen.
+      
+                  The menu opens for a single command that is already the one being
+                  addressed — shown greyed, because a menu that hides its only row
+                  looks broken — and then `% choosable.length` is `% 0`, which is
+                  NaN. Handing the key back leaves the caret working as it should.
+                */
+                if (choosable.length === 0) {
+                    return false;
+                }
+                // The browser's default too: the arrow would otherwise move the
+                // caret off the `@word`, and the menu it was steering would close.
+                event.preventDefault();
+                setHighlighted(current => (current + 1) % choosable.length);
+                return true;
+            }, COMMAND_PRIORITY_CRITICAL),
+            editor.registerCommand(KEY_ARROW_UP_COMMAND, (event) => {
+                if (choosable.length === 0) {
+                    return false;
+                }
+                event.preventDefault();
+                setHighlighted(current => (current - 1 + choosable.length) % choosable.length);
+                return true;
+            }, COMMAND_PRIORITY_CRITICAL),
+            editor.registerCommand(KEY_ENTER_COMMAND, (event) => {
+                const command = choosable[highlighted];
+                if (!command) {
+                    return false;
+                }
+                /*
+                 * The browser's default, as well as Lexical's.
+                 *
+                 * Returning `true` stops the command reaching the plain-text
+                 * plugin, but the keypress is still a keypress in a
+                 * `contenteditable` — so the browser inserted its own line break
+                 * after the chip. Choosing with the mouse never did, which is
+                 * exactly the shape of a missing `preventDefault`.
+                 */
+                event?.preventDefault();
+                insert(command);
+                return true;
+            }, COMMAND_PRIORITY_CRITICAL),
+            editor.registerCommand(KEY_ESCAPE_COMMAND, () => {
+                setQuery(null);
+                return true;
+            }, COMMAND_PRIORITY_CRITICAL),
+        ];
+        return () => unregister.forEach(remove => remove());
+    }, [editor, open, choosable, highlighted, insert]);
+    if (!open || !query?.rect) {
+        return null;
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(Box, { ref: anchorRef, sx: {
+                    position: 'fixed',
+                    left: query.rect.left,
+                    top: query.rect.top,
+                    width: 1,
+                    height: query.rect.height || 16,
+                    pointerEvents: 'none',
+                } }), _jsx(Overlay, { returnFocusRef: anchorRef, onEscape: () => setQuery(null), onClickOutside: () => setQuery(null), anchorSide: "outside-top", 
+                // The caret already has focus and must keep it: a person is still
+                // typing, and the menu is a suggestion rather than a destination.
+                preventFocusOnOpen: true, 
+                /*
+                 * Primer's own width prop, not an `sx` width.
+                 *
+                 * `Overlay` renders its width as a `data-width-*` attribute backed by
+                 * a CSS-module rule, and the default `auto` means "size to content" —
+                 * which an `sx` width does not reliably beat, since the two are equal
+                 * specificity and the module's rule wins on source order. That is why
+                 * the menu stayed as wide as the longest description in it. `medium`
+                 * is 320px.
+                 */
+                width: "large", 
+                /*
+                 * Positioned through `style`, not `sx`.
+                 *
+                 * `Overlay` writes `left`, `right`, `top`, `bottom` and `position` as
+                 * *inline* styles taken from its own props, and spreads a `style` prop
+                 * last. An `sx` rule is a class, and a class never beats an inline
+                 * style — so every position written there was discarded and the menu
+                 * rendered wherever the default left it: pinned to the left edge of
+                 * the window, a long way from the `@` it belongs to.
+                 *
+                 * Anchored to the caret: `left` at the character, and its bottom edge
+                 * just above the line, so it sits over what came before rather than
+                 * over the word being typed. Clamped so a caret near the right edge
+                 * does not push it off screen.
+                 */
+                style: {
+                    position: 'fixed',
+                    left: Math.max(8, Math.min(query.rect.left, window.innerWidth - MENU_WIDTH - 8)),
+                    /*
+                      The bottom edge, pinned above the caret — not the top edge pulled
+                      up by a transform.
+          
+                      `top` plus `translateY(-100%)` is a position that depends on the
+                      element's own height, and the height is only known once its rows
+                      have been laid out. So it painted once at the caret's line and
+                      again where it belonged, which reads as the menu falling into
+                      place.
+          
+                      `bottom` needs no such measurement: the browser resolves it
+                      against the viewport, and the first paint is the final one.
+                    */
+                    ...(query.rect.top >= MENU_MAX_HEIGHT + 16
+                        ? { bottom: window.innerHeight - query.rect.top + 6, top: 'auto' }
+                        : // No room above — a caret near the top of the window — so it
+                            // hangs below the line instead of being pushed off screen.
+                            {
+                                top: query.rect.top + (query.rect.height || 16) + 6,
+                                bottom: 'auto',
+                            }),
+                    right: 'auto',
+                }, sx: {
+                    maxHeight: MENU_MAX_HEIGHT,
+                    overflowY: 'auto',
+                    maxWidth: 'calc(100vw - 16px)',
+                }, children: _jsx(Box, { sx: { width: '100%', maxWidth: MENU_WIDTH, minWidth: 0 }, children: _jsx(ActionList, { selectionVariant: "single", children: matches.map(command => {
+                            const index = choosable.indexOf(command);
+                            return (_jsxs(ActionList.Item, { ref: element => {
+                                    if (element) {
+                                        rowRefs.current.set(command.name, element);
+                                    }
+                                    else {
+                                        rowRefs.current.delete(command.name);
+                                    }
+                                }, active: index >= 0 && index === highlighted, "aria-disabled": command.disabled, title: command.disabledReason, onSelect: () => {
+                                    if (!command.disabled) {
+                                        insert(command);
+                                    }
+                                }, 
+                                /*
+                                  The highlight, drawn here rather than asked for.
+              
+                                  `active` is Primer's "the keyboard is here" state and this
+                                  list renders it faintly; `selected` draws a tick in the
+                                  leading-visual slot, which these rows already fill with the
+                                  command's own icon — so neither showed. The row Enter would
+                                  take looked exactly like the rest, which is the one thing a
+                                  menu driven by arrow keys must not do.
+              
+                                  A background says it plainly, and says it the same way
+                                  whatever variant the list is in.
+                                */
+                                sx: {
+                                    ...(index >= 0 && index === highlighted
+                                        ? { bg: 'accent.subtle' }
+                                        : null),
+                                    ...(command.disabled ? { opacity: 0.5 } : null),
+                                }, children: [_jsx(ActionList.LeadingVisual, { children: command.icon ? (_jsx(command.icon, {})) : (_jsx(CommentDiscussionIcon, {})) }), command.name, command.description ? (_jsx(ActionList.Description, { variant: "block", 
+                                        /* Wrapped and breakable. `minWidth: 0` is the load-bearing
+                                         one: a grid item defaults to `min-content`, so without
+                                         it the description refuses to be narrower than its
+                                         longest unbroken run and pushes the row wide. */
+                                        sx: {
+                                            display: 'block',
+                                            whiteSpace: 'normal',
+                                            overflowWrap: 'anywhere',
+                                            minWidth: 0,
+                                        }, children: command.description })) : null] }, command.name));
+                        }) }) }) })] }));
+}
+export default CommandPlugin;

package/lib/chat/prompt/plugins/MentionChip.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What an `@agent` looks like in the prompt.
+ *
+ * Its own module because `MentionNode.decorate` returns it and a Lexical node
+ * file that also carried a styled component would be two things at once.
+ *
+ * @module chat/prompt/plugins/MentionChip
+ */
+import type { JSX } from 'react';
+import type { Icon } from '@primer/octicons-react';
+export declare function MentionChip({ name, icon: IconComponent, }: {
+    name: string;
+    icon?: Icon;
+}): JSX.Element;
+export default MentionChip;

package/lib/chat/prompt/plugins/MentionChip.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box } from '@datalayer/primer-addons';
+export function MentionChip({ name, icon: IconComponent, }) {
+    return (_jsxs(Box, { as: "span", 
+        // `contentEditable={false}` is what stops the caret entering it: without
+        // it a person can put the cursor between the icon and the name and type
+        // into a mention.
+        contentEditable: false, sx: {
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: 1,
+            px: 1,
+            py: '1px',
+            mx: '1px',
+            borderRadius: 6,
+            bg: 'accent.subtle',
+            color: 'accent.fg',
+            fontSize: 1,
+            lineHeight: 1.4,
+            whiteSpace: 'nowrap',
+            userSelect: 'none',
+        }, children: [IconComponent ? _jsx(IconComponent, { size: 12 }) : null, name] }));
+}
+export default MentionChip;

package/lib/chat/prompt/plugins/MentionNode.d.ts

@@ -0,0 +1,66 @@
+/**
+ * An `@agent` in the prompt, as one thing.
+ *
+ * It used to be plain text — `@Notebook Compactor` typed straight into the
+ * paragraph — which reads correctly and edits badly. A name with a space in it
+ * is several words to a text editor: backspace takes off "Compactor" and
+ * leaves "@Notebook", which is a mention of somebody who does not exist, and
+ * arrow keys walk through the middle of it. Whatever a person does to half a
+ * mention, the model still receives it as an address.
+ *
+ * A `DecoratorNode` makes it atomic: selected in one, moved in one, deleted in
+ * one. `getTextContent` still returns `@Name`, so the string handed to the
+ * agent is exactly what it was before — the change is to editing, not to the
+ * message.
+ *
+ * @module chat/prompt/plugins/MentionNode
+ */
+import type { JSX } from 'react';
+import { DecoratorNode, type LexicalNode, type NodeKey, type SerializedLexicalNode, type Spread } from 'lexical';
+import type { Icon } from '@primer/octicons-react';
+/** What the node needs to draw and to serialise itself. */
+export type MentionPayload = {
+    /** The agent's name, as typed after `@`. */
+    name: string;
+    /** The icon its spec asked for, resolved by whoever created the node. */
+    icon?: Icon;
+};
+/**
+ * A mention on its way through the clipboard or a saved editor state.
+ *
+ * The name only. `icon` is a React component, which does not survive
+ * `JSON.stringify` and has no business trying to — a mention pasted into a
+ * different prompt is drawn with whatever that prompt knows about the agent,
+ * and the name is the part that addresses it.
+ */
+export type SerializedMentionNode = Spread<{
+    name: string;
+}, SerializedLexicalNode>;
+export declare class MentionNode extends DecoratorNode<JSX.Element> {
+    __name: string;
+    __icon?: Icon;
+    static getType(): string;
+    static clone(node: MentionNode): MentionNode;
+    constructor(payload?: MentionPayload, key?: NodeKey);
+    static importJSON(serialized: SerializedMentionNode): MentionNode;
+    exportJSON(): SerializedMentionNode;
+    /**
+     * What the prompt is worth as a string.
+     *
+     * The whole point of keeping this exact: the agent is reachable because it
+     * is one of the parent's tools and the tool is named after it, so a mention
+     * is a hint in the prompt rather than a control channel. A person can still
+     * type `@Name` by hand and it works the same way.
+     */
+    getTextContent(): string;
+    /** Sits in the line of text rather than on a line of its own. */
+    isInline(): boolean;
+    /** Selectable as a unit, which is what makes one backspace remove it. */
+    isKeyboardSelectable(): boolean;
+    createDOM(): HTMLElement;
+    updateDOM(): false;
+    decorate(): JSX.Element;
+}
+export declare function $createMentionNode(payload: MentionPayload): MentionNode;
+export declare function $isMentionNode(node: LexicalNode | null | undefined): node is MentionNode;
+export default MentionNode;

package/lib/chat/prompt/plugins/MentionNode.js

@@ -0,0 +1,77 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { DecoratorNode, } from 'lexical';
+import { MentionChip } from './MentionChip';
+export class MentionNode extends DecoratorNode {
+    __name;
+    __icon;
+    static getType() {
+        return 'agent-mention';
+    }
+    static clone(node) {
+        return new MentionNode({ name: node.__name, icon: node.__icon }, node.__key);
+    }
+    /*
+     * `payload` has a default, and that is not tidiness.
+     *
+     * Lexical inspects the constructor's arity when a node type is registered:
+     * two required arguments and it insists on a static `importJSON`, refusing
+     * to register otherwise — which surfaced as the whole view failing to load
+     * rather than as a mention that did not draw. Both halves are supplied here.
+     */
+    constructor(payload = { name: '' }, key) {
+        super(key);
+        this.__name = payload.name;
+        this.__icon = payload.icon;
+    }
+    static importJSON(serialized) {
+        return $createMentionNode({ name: serialized.name });
+    }
+    exportJSON() {
+        return {
+            ...super.exportJSON(),
+            type: MentionNode.getType(),
+            version: 1,
+            name: this.__name,
+        };
+    }
+    /**
+     * What the prompt is worth as a string.
+     *
+     * The whole point of keeping this exact: the agent is reachable because it
+     * is one of the parent's tools and the tool is named after it, so a mention
+     * is a hint in the prompt rather than a control channel. A person can still
+     * type `@Name` by hand and it works the same way.
+     */
+    getTextContent() {
+        return `@${this.__name}`;
+    }
+    /** Sits in the line of text rather than on a line of its own. */
+    isInline() {
+        return true;
+    }
+    /** Selectable as a unit, which is what makes one backspace remove it. */
+    isKeyboardSelectable() {
+        return true;
+    }
+    createDOM() {
+        const span = document.createElement('span');
+        // Baseline-aligned, so a chip does not lift the line it sits in.
+        span.style.display = 'inline-flex';
+        span.style.verticalAlign = 'middle';
+        return span;
+    }
+    updateDOM() {
+        // The chip is rendered by React; Lexical never has to patch this element.
+        return false;
+    }
+    decorate() {
+        return _jsx(MentionChip, { name: this.__name, icon: this.__icon });
+    }
+}
+export function $createMentionNode(payload) {
+    return new MentionNode(payload);
+}
+export function $isMentionNode(node) {
+    return node instanceof MentionNode;
+}
+export default MentionNode;

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

@@ -0,0 +1,52 @@
+/** How many prompts a composer keeps of its own, on top of the seed. */
+export declare const MAX_LOCAL_PROMPTS = 100;
+export type HistoryDirection = 'up' | 'down';
+export type PromptHistoryState = {
+    /** What the runtime remembered, oldest first. */
+    readonly seeded: readonly string[];
+    /** What this composer sent, oldest first. */
+    readonly local: readonly string[];
+    /** Where the walk is; `entries.length` is the draft. */
+    readonly cursor: number;
+    /** What was being typed when the walk began. */
+    readonly draft: string;
+};
+/** The whole history, oldest first, without the seed's own entries repeated. */
+export declare function historyEntries(state: PromptHistoryState): string[];
+export declare function createPromptHistory(seeded?: readonly string[]): PromptHistoryState;
+/**
+ * The runtime's list, arrived or refreshed.
+ *
+ * The walk starts over from the draft: the entries under the cursor may have
+ * moved, and a cursor kept across that would land on the wrong prompt.
+ */
+export declare function reseed(state: PromptHistoryState, seeded: readonly string[]): PromptHistoryState;
+/** A prompt was sent: it becomes the newest entry, and the walk starts over. */
+export declare function remember(state: PromptHistoryState, prompt: string): PromptHistoryState;
+/** Something was typed: the walk is over, and what is on screen is the draft. */
+export declare function edited(state: PromptHistoryState): PromptHistoryState;
+/**
+ * One step through the history.
+ *
+ * `current` is what the composer shows now; it is kept as the draft when the
+ * first step up leaves it. Nothing to step to — older than the oldest, or
+ * newer than the draft — answers `null`, and the key goes on to do what it
+ * does in an editor.
+ */
+export declare function step(state: PromptHistoryState, direction: HistoryDirection, current: string): {
+    state: PromptHistoryState;
+    text: string;
+} | null;
+/**
+ * A composer's history: what to remember, and where the arrow keys go.
+ *
+ * Held in a ref rather than in state, because the walk has to answer a
+ * keystroke on the spot — the text goes into the composer's own value, and
+ * nothing here needs to render.
+ */
+export declare function usePromptHistory(seeded?: readonly string[]): {
+    remember: (prompt: string) => void;
+    edited: () => void;
+    navigate: (direction: HistoryDirection, current: string) => string | null;
+};
+export default usePromptHistory;