@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/chat/prompt/menus/ToolsMenu.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What the agent may call: builtin tools, MCP servers, and codemode.
+ *
+ * @module chat/prompt/menus/ToolsMenu
+ */
+import { Text, Button, ActionMenu, ActionList, ToggleSwitch, Tooltip, } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { ToolsIcon } from '@primer/octicons-react';
+export function ToolsMenu({ codemodeEnabled, onToggleCodemode, mcpServers, enabledMcpTools, enabledMcpToolCount, onToggleMcpTool, onToggleAllMcpServerTools, approvedMcpTools, onToggleMcpToolApproval, availableTools, }) {
+    const hasUsableMcpServers = mcpServers.some(server => server.isAvailable);
+    /*
+     * A count, not a word.
+     *
+     * Four labelled buttons on one row is most of the width of a chat panel, and
+     * the icon already says which menu this is. What the word was carrying — the
+     * name, and what is behind it — moves to the tooltip, where it costs nothing
+     * until somebody asks.
+     */
+    const summary = [
+        `${availableTools.length} tool${availableTools.length === 1 ? '' : 's'}`,
+        enabledMcpToolCount > 0 ? `${enabledMcpToolCount} MCP enabled` : null,
+        hasUsableMcpServers ? null : 'no MCP server available',
+    ]
+        .filter(Boolean)
+        .join(' · ');
+    return (_jsxs(ActionMenu, { children: [_jsx(ActionMenu.Anchor, { children: _jsx(Tooltip, { text: `Tools — ${summary}`, direction: "n", children: _jsx(Button, { type: "button", variant: "invisible", size: "small", "aria-label": `Tools — ${summary}`, leadingVisual: ToolsIcon, children: _jsx(Text, { sx: { fontSize: 0 }, children: availableTools.length + enabledMcpToolCount }) }) }) }), _jsx(ActionMenu.Overlay, { side: "outside-top", align: "start", width: "large", children: _jsx(Box, { sx: { maxHeight: '60vh', overflowY: 'auto' }, children: _jsxs(ActionList, { children: [_jsx(ActionList.Group, { title: "Codemode", children: _jsxs(Box, { sx: {
+                                        display: 'flex',
+                                        alignItems: 'center',
+                                        justifyContent: 'space-between',
+                                        px: 3,
+                                        py: 2,
+                                        borderBottom: '1px solid',
+                                        borderColor: 'border.muted',
+                                        gap: 2,
+                                    }, children: [_jsxs(Box, { sx: { flex: 1, minWidth: 0 }, children: [_jsx(Text, { id: "toggle-codemode", sx: { fontWeight: 'semibold', display: 'block' }, children: "Enable Codemode" }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: codemodeEnabled
+                                                        ? 'MCP tools accessible via meta-tools (search_tools, execute_code).'
+                                                        : 'Expose MCP tools directly to the model.' })] }), _jsx(ToggleSwitch, { size: "small", checked: codemodeEnabled, disabled: !onToggleCodemode, onClick: () => {
+                                                if (onToggleCodemode) {
+                                                    void onToggleCodemode(!codemodeEnabled);
+                                                }
+                                            }, "aria-labelledby": "toggle-codemode" })] }) }), availableTools.length > 0 ? (_jsx(ActionList.Group, { title: "Tools", children: availableTools.map(tool => (_jsx(ActionList.Item, { disabled: true, children: tool.name }, tool.id))) })) : null, mcpServers.length > 0 && hasUsableMcpServers ? (mcpServers.map(server => {
+                                const serverTools = enabledMcpTools.get(server.id);
+                                const allToolNames = server.tools.map(t => t.name);
+                                const enabledCount = serverTools?.size ?? 0;
+                                const allEnabled = enabledCount === allToolNames.length &&
+                                    allToolNames.length > 0;
+                                return (_jsxs(ActionList.Group, { title: `${server.name}${server.isAvailable ? '' : ' (unavailable)'}`, children: [server.isAvailable && server.tools.length > 0 && (_jsxs(Box, { sx: {
+                                                display: 'flex',
+                                                alignItems: 'center',
+                                                justifyContent: 'space-between',
+                                                px: 3,
+                                                py: 2,
+                                                borderBottom: '1px solid',
+                                                borderColor: 'border.muted',
+                                            }, children: [_jsxs(Text, { id: `toggle-all-${server.id}`, sx: {
+                                                        fontSize: 0,
+                                                        fontWeight: 'semibold',
+                                                        color: 'fg.muted',
+                                                    }, children: ["Enable all (", enabledCount, "/", allToolNames.length, ")"] }), _jsx(ToggleSwitch, { size: "small", checked: allEnabled, onClick: () => onToggleAllMcpServerTools(server.id, allToolNames, !allEnabled), "aria-labelledby": `toggle-all-${server.id}` })] })), server.isAvailable && server.tools.length > 0 ? (server.tools.map(tool => {
+                                            const isEnabled = serverTools?.has(tool.name) ?? false;
+                                            const serverApproved = approvedMcpTools.get(server.id);
+                                            // Tools default to NOT approved — user must explicitly
+                                            // approve each one (matches the Skills approval UX).
+                                            const isApproved = serverApproved?.has(tool.name) ?? false;
+                                            return (_jsxs(Box, { sx: {
+                                                    display: 'flex',
+                                                    alignItems: 'center',
+                                                    justifyContent: 'space-between',
+                                                    px: 3,
+                                                    py: 2,
+                                                    '&:hover': {
+                                                        backgroundColor: 'canvas.subtle',
+                                                    },
+                                                }, children: [_jsxs(Box, { sx: { flex: 1, minWidth: 0 }, children: [_jsx(Text, { id: `toggle-tool-${server.id}-${tool.name}`, sx: { fontWeight: 'semibold' }, children: tool.name }), tool.description && (_jsx(Text, { sx: {
+                                                                    display: 'block',
+                                                                    fontSize: 0,
+                                                                    color: 'fg.muted',
+                                                                    overflow: 'hidden',
+                                                                    textOverflow: 'ellipsis',
+                                                                    whiteSpace: 'nowrap',
+                                                                }, children: tool.description }))] }), _jsxs(Box, { sx: {
+                                                            display: 'flex',
+                                                            alignItems: 'center',
+                                                            gap: 3,
+                                                        }, children: [_jsxs(Box, { sx: {
+                                                                    display: 'flex',
+                                                                    flexDirection: 'column',
+                                                                    alignItems: 'center',
+                                                                    gap: '2px',
+                                                                }, children: [_jsx(Text, { sx: { fontSize: '10px', color: 'fg.muted' }, children: "Enabled" }), _jsx(ToggleSwitch, { size: "small", checked: isEnabled, onClick: () => onToggleMcpTool(server.id, tool.name), "aria-labelledby": `toggle-tool-${server.id}-${tool.name}` })] }), _jsxs(Box, { sx: {
+                                                                    display: 'flex',
+                                                                    flexDirection: 'column',
+                                                                    alignItems: 'center',
+                                                                    gap: '2px',
+                                                                }, children: [_jsx(Text, { sx: { fontSize: '10px', color: 'fg.muted' }, children: "Approved" }), _jsx(ToggleSwitch, { size: "small", checked: isApproved, onClick: () => onToggleMcpToolApproval(server.id, tool.name), "aria-labelledby": `toggle-tool-${server.id}-${tool.name}` })] })] })] }, `${server.id}-${tool.name}`));
+                                        })) : server.isAvailable ? (_jsx(ActionList.Item, { disabled: true, children: _jsx(Text, { sx: { color: 'fg.muted', fontStyle: 'italic' }, children: "No tools discovered" }) })) : (_jsx(ActionList.Item, { disabled: true, children: _jsx(Text, { sx: { color: 'fg.muted', fontStyle: 'italic' }, children: "Server unavailable" }) }))] }, server.id));
+                            })) : (_jsx(ActionList.Group, { title: "No MCP Servers", children: _jsx(ActionList.Item, { disabled: true, children: _jsx(Text, { sx: { color: 'fg.muted', fontStyle: 'italic' }, children: "No MCP Servers" }) }) }))] }) }) })] }));
+}

package/lib/chat/prompt/menus/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The menus under the prompt.
+ *
+ * One file each, and exported from here so the prompt imports a folder rather
+ * than four paths. They were private sub-components of one 1100-line module,
+ * which made the file hard to read and each menu hard to find.
+ *
+ * @module chat/prompt/menus
+ */
+export { AgentsMenu } from './AgentsMenu';
+export { InlineAgentsMenu } from './InlineAgentsMenu';
+export { ToolsMenu } from './ToolsMenu';
+export { SkillsMenu } from './SkillsMenu';
+export { ModelSelector } from './ModelSelector';
+export { SuggestionsMenu } from './SuggestionsMenu';

package/lib/chat/prompt/menus/index.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The menus under the prompt.
+ *
+ * One file each, and exported from here so the prompt imports a folder rather
+ * than four paths. They were private sub-components of one 1100-line module,
+ * which made the file hard to read and each menu hard to find.
+ *
+ * @module chat/prompt/menus
+ */
+export { AgentsMenu } from './AgentsMenu';
+export { InlineAgentsMenu } from './InlineAgentsMenu';
+export { ToolsMenu } from './ToolsMenu';
+export { SkillsMenu } from './SkillsMenu';
+export { ModelSelector } from './ModelSelector';
+export { SuggestionsMenu } from './SuggestionsMenu';

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

@@ -0,0 +1,54 @@
+/**
+ * Addressing an agent from the prompt, by typing `@`.
+ *
+ * The picker in the header says who the *conversation* is with. This says who
+ * a single request is for, which is a different question and wants a different
+ * answer: a person mid-sentence should not have to leave the sentence.
+ *
+ * What it inserts is a plain `@Name`, not a node of its own. The name is read
+ * by the model — 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*, not a control channel. That means a person can type one by hand, or
+ * edit one afterwards, and it still works; a bespoke node would have made both
+ * of those break in ways nobody could see.
+ *
+ * @module chat/prompt/plugins/AgentMentionPlugin
+ */
+import type { JSX } from 'react';
+import type { Icon } from '@primer/octicons-react';
+/** One agent a prompt may address. */
+export type MentionableAgent = {
+    /** The name typed after `@`, and the name of the tool that reaches it. */
+    name: string;
+    /** One line about what it is for. */
+    description?: string;
+    emoji?: string;
+    /**
+     * The octicon its agentspec asked for.
+     *
+     * Resolved by whoever builds the list — this module has no opinion about
+     * where an icon name comes from — and drawn in place of the emoji, which was
+     * the same picture for every agent that had not set one.
+     */
+    icon?: Icon;
+    /**
+     * Shown, but not choosable.
+     *
+     * The member already being addressed is the case this exists for: leaving
+     * it out made the list look arbitrary — a team of two offering one name —
+     * while offering it would let a person address the agent they are already
+     * talking to. It stays visible, greyed, and says why.
+     */
+    disabled?: boolean;
+    /** Why it cannot be chosen, when it cannot. */
+    disabledReason?: string;
+};
+export type AgentMentionPluginProps = {
+    /** Everyone this prompt may address. No menu when there is nobody. */
+    agents: MentionableAgent[];
+};
+/**
+ * Offer the agents while `@` is being typed.
+ */
+export declare function AgentMentionPlugin({ agents, }: AgentMentionPluginProps): JSX.Element | null;
+export default AgentMentionPlugin;

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

@@ -0,0 +1,370 @@
+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 { AiAgentIcon } from '@datalayer/icons-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';
+import { $createMentionNode } from './MentionNode';
+/**
+ * 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. A number that only lived in the style would put it off screen the
+ * moment either changed.
+ */
+const MENU_WIDTH = 440;
+const MENU_MAX_HEIGHT = 240;
+/**
+ * Read the `@word` immediately before the caret.
+ *
+ * Anchored to a word boundary so an email address or a decorator does not open
+ * a menu: `@` counts only at the start of the text or after whitespace.
+ */
+function readMentionQuery(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 agents while `@` is being typed.
+ */
+export function AgentMentionPlugin({ agents, }) {
+    const [editor] = useLexicalComposerContext();
+    const [query, setQuery] = useState(null);
+    const [highlighted, setHighlighted] = useState(0);
+    const anchorRef = useRef(null);
+    /* The rows, by agent name, so the lit one can be brought into view. */
+    const rowRefs = useRef(new Map());
+    /* Set while the document change that inserted a mention is being applied. */
+    const justInserted = useRef(false);
+    /*
+     * Choosable rows first, then the greyed ones.
+     *
+     * The highlight — where Enter lands — starts on the first row a person can
+     * pick. The one already being addressed is listed too, greyed, and it used
+     * to come first because the team lists its front door first: so the menu
+     * opened with its second row lit, which read as the wrong row preselected.
+     * A stable sort keeps the team's own order within each group.
+     */
+    const matches = query
+        ? agents
+            .filter(agent => agent.name.toLowerCase().startsWith(query.text.toLowerCase()))
+            .sort((left, right) => Number(!!left.disabled) - Number(!!right.disabled))
+        : [];
+    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(agent => !agent.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 shows a few rows and scrolls for the rest, so an arrow that
+     * moved the highlight past the fold moved it out of sight — and Enter then
+     * chose a row the person never saw. `nearest` scrolls the menu by the
+     * least that shows the row, and nothing when it already shows.
+     */
+    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 = readMentionQuery(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((agent) => {
+        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);
+            /*
+             * Deleted first, then inserted into the collapsed caret.
+             *
+             * `insertNodes` over a *range* decides for itself how to reconcile
+             * what it is replacing, and for a decorator it reconciled by splitting
+             * the paragraph — so the chip landed and the caret went to a new line.
+             * Emptying the range first leaves a collapsed selection inside a text
+             * node, which is the one state an inline insert has no choice about.
+             */
+            selection.insertText('');
+            /*
+             * A node, not `@Name ` as text.
+             *
+             * As text a mention was several words to the editor: backspace took
+             * the last one off and left an address to somebody who does not
+             * exist. The trailing space stays plain, so the caret lands after the
+             * chip ready for the rest of the sentence.
+             */
+            const chip = $createMentionNode({ name: agent.name, icon: agent.icon });
+            selection.insertNodes([chip]);
+            // Explicitly after the chip. `insertNodes` leaves the selection where
+            // it sees fit, and typing must continue on this line, beside it.
+            chip.selectNext();
+            const after = $getSelection();
+            if ($isRangeSelection(after)) {
+                after.insertText(' ');
+            }
+        });
+        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 agent 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 agent 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 agent = choosable[highlighted];
+                if (!agent) {
+                    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(agent);
+                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(agent => {
+                            const index = choosable.indexOf(agent);
+                            return (_jsxs(ActionList.Item, { ref: element => {
+                                    if (element) {
+                                        rowRefs.current.set(agent.name, element);
+                                    }
+                                    else {
+                                        rowRefs.current.delete(agent.name);
+                                    }
+                                }, active: index >= 0 && index === highlighted, "aria-disabled": agent.disabled, title: agent.disabledReason, onSelect: () => {
+                                    if (!agent.disabled) {
+                                        insert(agent);
+                                    }
+                                }, 
+                                /*
+                                  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
+                                  agent'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),
+                                    ...(agent.disabled ? { opacity: 0.5 } : null),
+                                }, children: [_jsx(ActionList.LeadingVisual, { children: agent.icon ? _jsx(agent.icon, {}) : _jsx(AiAgentIcon, {}) }), agent.name, agent.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: agent.description })) : null] }, agent.name));
+                        }) }) }) })] }));
+}
+export default AgentMentionPlugin;

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

@@ -0,0 +1,52 @@
+/**
+ * Running something from the prompt, by typing `/`.
+ *
+ * The sibling of `AgentMentionPlugin`, and deliberately its twin: the same
+ * caret-anchored overlay, the same keyboard ownership while it is open, the
+ * same reset when the word changes. Two menus that behave differently for no
+ * reason a person could name would be worse than either.
+ *
+ * What it inserts is plain text, not a node. A command is read by whoever
+ * handles the prompt, and a person can type one by hand or edit one
+ * afterwards; a bespoke node would break both in ways nobody could see. That
+ * is the one place it differs from the mention plugin, whose chip exists
+ * because an agent's name has spaces in it and a command does not.
+ *
+ * The commands are hardcoded and every one of them is disabled: the menu is
+ * here to say what is coming, and offering something that does nothing when
+ * chosen would be worse than saying so.
+ *
+ * @module chat/prompt/plugins/CommandPlugin
+ */
+import type { JSX } from 'react';
+import type { Icon } from '@primer/octicons-react';
+/** One command a prompt may run. */
+export type PromptCommand = {
+    /** The word typed after `/`. */
+    name: string;
+    /** One line about what it does. */
+    description?: string;
+    /** The mark shown beside it. */
+    icon?: Icon;
+    /** Shown, but not choosable. */
+    disabled?: boolean;
+    /** Why it cannot be chosen, when it cannot. */
+    disabledReason?: string;
+};
+/**
+ * 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 declare const PROMPT_COMMANDS: PromptCommand[];
+export type CommandPluginProps = {
+    /** Every command this prompt offers. No menu when there are none. */
+    commands: PromptCommand[];
+};
+/**
+ * Offer the commands while `/` is being typed.
+ */
+export declare function CommandPlugin({ commands, }: CommandPluginProps): JSX.Element | null;
+export default CommandPlugin;