@datalayer/agent-runtimes 1.0.29 → 1.3.10

package/lib/chat/prompt/promptHistory.js

@@ -0,0 +1,123 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Walking back through what was sent, the way a shell does on the arrow keys.
+ *
+ * Two lists make the history: what the runtime remembers from before this
+ * page loaded (`seeded`, from the agent's initial state), and what was sent
+ * from this composer since (`local`). They are joined oldest first, and a
+ * prompt the runtime has since reported for itself is not counted twice.
+ *
+ * The cursor points into that joined list; one past its end is the draft —
+ * whatever was being typed when the walk began, put back when the walk
+ * returns there. Typing anything ends the walk: the text on screen becomes a
+ * new draft, wherever it was taken from.
+ *
+ * Pure functions over a plain state, so the rules are testable without an
+ * editor; `usePromptHistory` holds one such state for a composer.
+ *
+ * @module chat/prompt/promptHistory
+ */
+import { useCallback, useEffect, useRef } from 'react';
+/** How many prompts a composer keeps of its own, on top of the seed. */
+export const MAX_LOCAL_PROMPTS = 100;
+/** The whole history, oldest first, without the seed's own entries repeated. */
+export function historyEntries(state) {
+    const seen = new Set(state.seeded);
+    return [...state.seeded, ...state.local.filter(prompt => !seen.has(prompt))];
+}
+export function createPromptHistory(seeded = []) {
+    const clean = seeded.map(prompt => prompt.trim()).filter(Boolean);
+    return { seeded: clean, local: [], cursor: clean.length, draft: '' };
+}
+/**
+ * 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 function reseed(state, seeded) {
+    const clean = seeded.map(prompt => prompt.trim()).filter(Boolean);
+    if (clean.length === state.seeded.length &&
+        clean.every((prompt, index) => prompt === state.seeded[index])) {
+        return state;
+    }
+    const next = { ...state, seeded: clean, draft: '' };
+    return { ...next, cursor: historyEntries(next).length };
+}
+/** A prompt was sent: it becomes the newest entry, and the walk starts over. */
+export function remember(state, prompt) {
+    const text = prompt.trim();
+    const entries = historyEntries(state);
+    // Sent twice in a row is one entry, as the runtime keeps it too.
+    if (!text || entries[entries.length - 1] === text) {
+        return { ...state, cursor: entries.length, draft: '' };
+    }
+    const local = [...state.local, text].slice(-MAX_LOCAL_PROMPTS);
+    const next = { ...state, local, draft: '' };
+    return { ...next, cursor: historyEntries(next).length };
+}
+/** Something was typed: the walk is over, and what is on screen is the draft. */
+export function edited(state) {
+    const length = historyEntries(state).length;
+    return state.cursor === length
+        ? state
+        : { ...state, cursor: length, draft: '' };
+}
+/**
+ * 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 function step(state, direction, current) {
+    const entries = historyEntries(state);
+    if (direction === 'up') {
+        if (state.cursor === 0) {
+            return null;
+        }
+        const cursor = state.cursor - 1;
+        const draft = state.cursor === entries.length ? current : state.draft;
+        return { state: { ...state, cursor, draft }, text: entries[cursor] };
+    }
+    if (state.cursor >= entries.length) {
+        return null;
+    }
+    const cursor = state.cursor + 1;
+    const text = cursor === entries.length ? state.draft : entries[cursor];
+    return { state: { ...state, cursor }, text };
+}
+/**
+ * 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 function usePromptHistory(seeded) {
+    const stateRef = useRef(createPromptHistory(seeded));
+    useEffect(() => {
+        stateRef.current = reseed(stateRef.current, seeded ?? []);
+    }, [seeded]);
+    const rememberPrompt = useCallback((prompt) => {
+        stateRef.current = remember(stateRef.current, prompt);
+    }, []);
+    const editedPrompt = useCallback(() => {
+        stateRef.current = edited(stateRef.current);
+    }, []);
+    /** The text to show after a step, or `null` when there is nowhere to go. */
+    const navigate = useCallback((direction, current) => {
+        const result = step(stateRef.current, direction, current);
+        if (!result) {
+            return null;
+        }
+        stateRef.current = result.state;
+        return result.text;
+    }, []);
+    return { remember: rememberPrompt, edited: editedPrompt, navigate };
+}
+export default usePromptHistory;

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

@@ -0,0 +1,81 @@
+/**
+ * A stack: one horizontal band around the prompt.
+ *
+ * The prompt has four regions — above and below the input, each of those
+ * either inside the bordered box or under it — and every one of them is a
+ * *list* of bands rather than a single slot. That was already true of the
+ * footers, where the context ring and the controls bar are two bands with
+ * different rules; it was not true of the headers, which had one slot and no
+ * way to add a second without editing the prompt.
+ *
+ * Naming the regions is the point of this module's neighbours:
+ *
+ * | | above the input | below the input |
+ * | --- | --- | --- |
+ * | inside the box | `InPromptHeader` | `InPromptFooter` |
+ * | under the box | `BelowPromptHeader` | `BelowPromptFooter` |
+ *
+ * @module chat/prompt/stack
+ */
+import type { ReactNode } from 'react';
+/** One band in a region. */
+export type PromptStack = {
+    /** Identity, for React and for a host reasoning about which band is which. */
+    id: string;
+    /** What the band shows. A band with nothing in it is not rendered. */
+    content?: ReactNode;
+    /**
+     * Reserve this height even when the band is empty.
+     *
+     * For content that arrives late and would otherwise make the layout jump —
+     * token usage is the case this exists for. Left unset, an empty band takes
+     * no space at all, which is what a band with nothing coming should do: a
+     * permanent white stripe reserved for something that never arrives reads as
+     * a rendering fault.
+     */
+    minHeight?: number;
+    /**
+     * Dim the band and make it inert.
+     *
+     * Opacity rather than `grayscale`, which takes the theme with it: a
+     * workspace on the Jupyter variant showed a grey strip under a coloured
+     * page, as though the theme had failed rather than the controls being
+     * unavailable. Opacity alone says "not now" without saying "not yours".
+     */
+    disabled?: boolean;
+    /** A rule above the band, separating it from what precedes it. */
+    bordered?: boolean;
+    /** A tinted ground, for a band of controls rather than of information. */
+    subtle?: boolean;
+    /** Horizontal padding, in theme units. */
+    px?: number | number[];
+    /** Vertical padding, in theme units. */
+    py?: number;
+    /** Top padding, overriding `py`. The bands around the input are asymmetric. */
+    pt?: number;
+    /** Bottom padding, overriding `py`. */
+    pb?: number;
+    /** Space between the items in the band. */
+    gap?: number;
+    /**
+     * How the band lays its content out.
+     *
+     * `'row'` — the default — is a flex row of controls: menus, indicators,
+     * buttons, laid out with `gap`.
+     *
+     * `'block'` is for content that *is* the band and draws its own full width.
+     * The context ring is one: it brings its own padding and background, and in
+     * a flex row it shrinks to its content and leaves the rest of the row
+     * showing the page behind it — a pale stripe down the right-hand side.
+     */
+    layout?: 'row' | 'block';
+};
+export type PromptStacksProps = {
+    /** The bands, top to bottom. */
+    stacks: readonly PromptStack[];
+    /** Applied to every band, for a region that is disabled as a whole. */
+    disabled?: boolean;
+};
+/** Render a region's bands, skipping the ones with nothing to show. */
+export declare function PromptStacks({ stacks, disabled, }: PromptStacksProps): React.JSX.Element | null;
+export default PromptStacks;

package/lib/chat/prompt/stack.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { Box } from '@datalayer/primer-addons';
+/**
+ * Whether a band would draw anything.
+ *
+ * A band kept for its `minHeight` still counts: reserving the space is the
+ * whole reason it is there.
+ */
+function isRendered(stack) {
+    return Boolean(stack.content) || Boolean(stack.minHeight);
+}
+/** Render a region's bands, skipping the ones with nothing to show. */
+export function PromptStacks({ stacks, disabled = false, }) {
+    const visible = stacks.filter(isRendered);
+    if (visible.length === 0) {
+        return null;
+    }
+    return (_jsx(_Fragment, { children: visible.map(stack => {
+            const isDisabled = disabled || stack.disabled;
+            return (_jsx(Box, { "data-prompt-stack": stack.id, "aria-disabled": isDisabled || undefined, sx: {
+                    ...(stack.layout === 'block'
+                        ? null
+                        : {
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: stack.gap ?? 2,
+                        }),
+                    px: stack.px ?? 2,
+                    py: stack.py ?? 1,
+                    ...(stack.pt === undefined ? null : { pt: stack.pt }),
+                    ...(stack.pb === undefined ? null : { pb: stack.pb }),
+                    minHeight: stack.minHeight,
+                    ...(stack.bordered
+                        ? { borderTop: '1px solid', borderColor: 'border.default' }
+                        : null),
+                    ...(stack.subtle ? { bg: 'canvas.subtle' } : null),
+                    ...(isDisabled ? { opacity: 0.5, pointerEvents: 'none' } : null),
+                }, children: stack.content }, stack.id));
+        }) }));
+}
+export default PromptStacks;

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

@@ -0,0 +1,52 @@
+/** Where the animation has got to. */
+export type TypingState = {
+    /** Which phrase, modulo the list's length. */
+    index: number;
+    /** How many of its characters are showing. */
+    shown: number;
+    /** Whether it is being taken away rather than put up. */
+    erasing: boolean;
+};
+/**
+ * The state at rest, and what a stopped animation returns to.
+ *
+ * One character already showing, not none. A phrase begins the instant it is
+ * its turn — at mount, and again when the prompt loses focus — because the
+ * alternative is a beat of the ordinary placeholder before every phrase, and
+ * the pause between phrases is where that belongs.
+ */
+export declare const TYPING_START: TypingState;
+/**
+ * The next state, and how long to wait before adopting it.
+ *
+ * Pulled out of the hook and left pure so the rhythm can be read — and
+ * tested — without a renderer. The hook is then only a timer and some state.
+ */
+export declare function nextTypingStep(state: TypingState, phrases: string[]): {
+    delayMs: number;
+    state: TypingState;
+};
+/** What is on screen in a given state. */
+export declare function typedText(state: TypingState, phrases: string[]): string;
+export type TypingPlaceholderOptions = {
+    /** The phrases to type out, in order, looping. */
+    phrases: string[];
+    /**
+     * Whether the animation should run.
+     *
+     * False for a focused prompt, a prompt with something already typed in it,
+     * and a prompt that cannot be typed in at all.
+     */
+    enabled: boolean;
+    /** What to show whenever it is not running. */
+    idle: string;
+};
+/**
+ * The placeholder to show right now.
+ *
+ * Returns `idle` unchanged whenever there is nothing to animate, so a caller
+ * can pass the result straight through without asking whether the animation
+ * is on.
+ */
+export declare function useTypingPlaceholder({ phrases, enabled, idle, }: TypingPlaceholderOptions): string;
+export default useTypingPlaceholder;

package/lib/chat/prompt/useTypingPlaceholder.js

@@ -0,0 +1,180 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The prompt types its own suggestions, so the box is not merely empty.
+ *
+ * An empty composer under a chat asks a question nobody has answered for the
+ * reader: what can I ask this thing? The empty state's suggestion chips answer
+ * it, and they disappear the moment the first message is sent. Typing them
+ * into the placeholder answers it where the answer is needed — in the box
+ * about to be typed in — and keeps answering it later, when the chips are
+ * gone.
+ *
+ * It is the *placeholder* that types, never the editor's content. Animating
+ * the real value would put words in a person's message that they did not
+ * write, and one careless Enter would send them.
+ *
+ * Two rules that make it an invitation rather than a distraction:
+ *
+ * - **It yields.** The moment the prompt has focus the animation stops and the
+ *   ordinary placeholder returns — the one that mentions `/` and `@`, which is
+ *   what somebody about to type actually needs. A half-typed phrase frozen
+ *   under a caret reads as a bug; the static hint reads as help. On blur it
+ *   starts again, from the top of the phrase it was on.
+ * - **It respects `prefers-reduced-motion`.** For a reader who has asked the
+ *   machine to hold still, the suggestion is worth nothing and the movement
+ *   costs something.
+ *
+ * @module chat/prompt/useTypingPlaceholder
+ */
+import { useEffect, useRef, useState } from 'react';
+/** Milliseconds per character while typing. About 220 characters a minute. */
+const TYPE_MS = 45;
+/** How long a finished phrase stands before it is taken away. */
+const HOLD_MS = 1600;
+/**
+ * Milliseconds per character while rewinding.
+ *
+ * Much faster than typing, and deliberately so: the typing is the message and
+ * the erasing is only the way back. At an equal speed the pair reads as
+ * indecision.
+ */
+const ERASE_MS = 14;
+/**
+ * The beat between an emptied box and the next phrase starting.
+ *
+ * The ordinary placeholder stands here, which makes this the only moment the
+ * hint naming `/` and `@` is legible — everywhere else in the cycle a
+ * suggestion is on top of it. Long enough to be read, therefore, rather than
+ * long enough to be noticed: longer, in fact, than the beat a finished
+ * suggestion is held for, because the two are doing the same job for different
+ * sentences and this is the one a reader has had no chance to read yet.
+ */
+const GAP_MS = 2000;
+/**
+ * The state at rest, and what a stopped animation returns to.
+ *
+ * One character already showing, not none. A phrase begins the instant it is
+ * its turn — at mount, and again when the prompt loses focus — because the
+ * alternative is a beat of the ordinary placeholder before every phrase, and
+ * the pause between phrases is where that belongs.
+ */
+export const TYPING_START = {
+    index: 0,
+    shown: 1,
+    erasing: false,
+};
+/**
+ * The next state, and how long to wait before adopting it.
+ *
+ * Pulled out of the hook and left pure so the rhythm can be read — and
+ * tested — without a renderer. The hook is then only a timer and some state.
+ */
+export function nextTypingStep(state, phrases) {
+    const phrase = phrases[state.index % phrases.length] ?? '';
+    if (!state.erasing) {
+        if (state.shown < phrase.length) {
+            return {
+                delayMs: TYPE_MS,
+                state: { ...state, shown: state.shown + 1 },
+            };
+        }
+        // Typed out: stand there long enough to be read before it goes.
+        return { delayMs: HOLD_MS, state: { ...state, erasing: true } };
+    }
+    if (state.shown > 0) {
+        return { delayMs: ERASE_MS, state: { ...state, shown: state.shown - 1 } };
+    }
+    /*
+     * Emptied: a beat, then the next one, already on its first character.
+     *
+     * The state being left — nothing shown — is what stands for the length of
+     * that beat, and it is where the ordinary placeholder gets its turn. Landing
+     * on the next phrase's first character rather than on another empty frame is
+     * what keeps the beat to one pause instead of two. Wrapping, so it loops.
+     */
+    return {
+        delayMs: GAP_MS,
+        state: {
+            index: (state.index + 1) % phrases.length,
+            shown: TYPING_START.shown,
+            erasing: false,
+        },
+    };
+}
+/** What is on screen in a given state. */
+export function typedText(state, phrases) {
+    const phrase = phrases[state.index % phrases.length] ?? '';
+    return phrase.slice(0, state.shown);
+}
+/** Whether this reader has asked for less movement. */
+function prefersReducedMotion() {
+    return (typeof window !== 'undefined' &&
+        typeof window.matchMedia === 'function' &&
+        window.matchMedia('(prefers-reduced-motion: reduce)').matches);
+}
+/**
+ * The placeholder to show right now.
+ *
+ * Returns `idle` unchanged whenever there is nothing to animate, so a caller
+ * can pass the result straight through without asking whether the animation
+ * is on.
+ */
+export function useTypingPlaceholder({ phrases, enabled, idle, }) {
+    /*
+     * The phrase list as a primitive.
+     *
+     * The effect below schedules one timeout per character and cancels it on
+     * every re-run, so an array identity in its dependencies would let any
+     * re-render of the parent restart the pending tick — a prompt inside a chat
+     * that re-renders while streaming would type nothing at all. A joined string
+     * changes when the phrases do and not when the array is rebuilt.
+     */
+    const key = phrases.join(' ');
+    const phrasesRef = useRef(phrases);
+    phrasesRef.current = phrases;
+    const [state, setState] = useState(TYPING_START);
+    const [reduced] = useState(prefersReducedMotion);
+    const running = enabled && !reduced && phrases.length > 0;
+    // A new set of suggestions is a new animation, not a continuation of the old
+    // one at whatever character it had reached.
+    useEffect(() => {
+        setState(TYPING_START);
+    }, [key]);
+    // Stopped means stopped at the beginning: when it resumes it types a phrase
+    // out from the top rather than picking up mid-word, which is what makes the
+    // return read as an invitation rather than as a glitch. At the top, not
+    // before it — the first character is already there, so typing resumes on the
+    // instant rather than after a beat of nothing.
+    useEffect(() => {
+        if (!running) {
+            setState(current => ({
+                ...current,
+                shown: TYPING_START.shown,
+                erasing: false,
+            }));
+        }
+    }, [running]);
+    useEffect(() => {
+        if (!running) {
+            return undefined;
+        }
+        const step = nextTypingStep(state, phrasesRef.current);
+        const timer = setTimeout(() => setState(step.state), step.delayMs);
+        return () => clearTimeout(timer);
+    }, [running, state]);
+    if (!running) {
+        return idle;
+    }
+    /*
+     * The idle text until the first character lands.
+     *
+     * An empty placeholder between one phrase and the next is a box that looks
+     * broken for a third of a second, twice a cycle. The ordinary hint fills the
+     * gap, which is also the most useful thing to put there.
+     */
+    return typedText(state, phrases) || idle;
+}
+export default useTypingPlaceholder;

package/lib/chat/tools/A2AAgentDialog.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The overlay behind "card" on an A2A run.
+ *
+ * Everything the run's events said about the agent — where it was launched,
+ * its endpoint, its task and state — and the agent card fetched live from the
+ * agent itself, laid out field by field with the raw JSON underneath, and a
+ * link out to the card's URL for whoever wants the tab after all.
+ *
+ * @module chat/tools/A2AAgentDialog
+ */
+import React from 'react';
+import type { AgentStreamSubagentPayload } from '../../types/stream';
+/** What is known about an agent reached over A2A, from the run's events. */
+export interface A2AAgentDetails {
+    /** The subagent name the parent delegates to. */
+    name: string;
+    /** The agent's JSON-RPC endpoint. */
+    url?: string;
+    /** `local`, `cloud`, `remote`, or `auto` while undecided. */
+    launch?: string;
+    /** Where the run stands: `launching`, `ready`, then the A2A task states. */
+    state?: string;
+    taskId?: string | null;
+    runtimeUid?: string;
+    /** The card summary the server sent when it resolved the agent. */
+    card?: AgentStreamSubagentPayload['agentCard'];
+    /** The agentspec it was launched from, as `<id>:<version>`. */
+    ref?: string;
+    description?: string;
+}
+/**
+ * The agent behind a delegated run, or `null` when the run is not over A2A.
+ * Later events win, except the name, which is the first one's.
+ */
+export declare function a2aAgentDetails(events: readonly AgentStreamSubagentPayload[], fallbackName?: string): A2AAgentDetails | null;
+/** Where an A2A agent publishes its card. */
+export declare function agentCardUrl(url: string): string;
+export type AgentCardFetch = {
+    status: 'idle';
+} | {
+    status: 'loading';
+} | {
+    status: 'loaded';
+    card: Record<string, unknown>;
+} | {
+    status: 'error';
+    error: string;
+};
+/** The agent card at `url`, fetched when the URL is known and refetched when it changes. */
+export declare function useAgentCard(url: string | undefined): AgentCardFetch;
+export interface A2AAgentDialogProps {
+    details: A2AAgentDetails;
+    onClose: () => void;
+}
+/**
+ * Everything about the agent behind an A2A run: the run's own facts, the
+ * card fetched from the agent, the raw JSON, and the way out to the URL.
+ */
+export declare function A2AAgentDialog({ details, onClose, }: A2AAgentDialogProps): React.ReactElement;
+export default A2AAgentDialog;