@datalayer/agent-runtimes 1.3.74 → 1.3.78

package/lib/components/inspector/agentInspector.js

@@ -0,0 +1,267 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The Agent Inspector's record: what an agent does, as it does it, one entry
+ * a thing — an A2A request or event, an MCP tool call, a skill, a frontend or
+ * backend tool, a model turn, an approval — each with its time, the agent
+ * that did it (`actor`), where it came from (`source`), its kind, its name,
+ * its status and, once it ends, its duration, a line that says it, and its
+ * payload whole.
+ *
+ * A call's start and its end are one entry: {@link AgentInspectorSink.start}
+ * opens it under a key (a tool call's id), {@link AgentInspectorSink.end}
+ * closes it with its result. Anything can push into a sink: the A2A capture
+ * (`inspectA2AFetch`), a team (`useA2ATeam`'s `inspector`), a chat
+ * (`ChatBase`, under {@link AgentInspectorProvider}). `AgentInspector` draws
+ * it.
+ *
+ * @module components/inspector/agentInspector
+ */
+import { createContext, createElement, useContext, useState, useSyncExternalStore, } from 'react';
+/** Every source, in the order the filters list them. */
+export const AGENT_INSPECTOR_SOURCES = [
+    'a2a',
+    'mcp',
+    'skill',
+    'frontend-tool',
+    'backend-tool',
+    'model',
+    'approval',
+];
+/** A source, in words. */
+export const AGENT_INSPECTOR_SOURCE_LABELS = {
+    a2a: 'A2A',
+    mcp: 'MCP',
+    skill: 'Skill',
+    'frontend-tool': 'Frontend tool',
+    'backend-tool': 'Backend tool',
+    model: 'Model',
+    approval: 'Approval',
+};
+/** How large a value is, as JSON, in bytes. */
+export function jsonBytes(value) {
+    if (value === undefined) {
+        return 0;
+    }
+    try {
+        const text = JSON.stringify(value);
+        return text === undefined ? 0 : new TextEncoder().encode(text).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/** A size, in words: `812 B`, `12.3 kB`, `1.2 MB`. */
+export function formatBytes(bytes) {
+    if (bytes < 1000) {
+        return `${bytes} B`;
+    }
+    if (bytes < 1_000_000) {
+        return `${(bytes / 1000).toFixed(1)} kB`;
+    }
+    return `${(bytes / 1_000_000).toFixed(1)} MB`;
+}
+/** A line short enough for a row. */
+export function shortLine(text, length = 160) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > length ? `${flat.slice(0, length - 1)}…` : flat;
+}
+/** How many semantic events wait for their entry. */
+const PENDING_LIMIT = 32;
+/** Make a sink: the record, and who listens to it. */
+export function createAgentInspector(options = {}) {
+    const now = options.now ?? Date.now;
+    const limit = options.limit ?? 2000;
+    let list = [];
+    let counter = 0;
+    const open = new Map();
+    const listeners = new Set();
+    let pending = [];
+    let scheduled = false;
+    const linkers = new Set();
+    const notify = () => {
+        if (scheduled) {
+            return;
+        }
+        scheduled = true;
+        queueMicrotask(() => {
+            scheduled = false;
+            listeners.forEach(listener => listener());
+        });
+    };
+    const replace = (id, next) => {
+        list = list.map(entry => (entry.id === id ? next : entry));
+    };
+    const settlePending = (entry) => {
+        if (!pending.length) {
+            return entry;
+        }
+        const taken = pending.filter(waiting => waiting.match(entry));
+        if (!taken.length) {
+            return entry;
+        }
+        pending = pending.filter(waiting => !taken.includes(waiting));
+        return {
+            ...entry,
+            events: [...entry.events, ...taken.map(waiting => waiting.event)],
+        };
+    };
+    const push = (input) => {
+        counter += 1;
+        const id = `e${counter}`;
+        const { links, at, ...rest } = input;
+        const entry = settlePending({
+            ...rest,
+            id,
+            at: at ?? now(),
+            bytes: jsonBytes(input.payload) + jsonBytes(input.result),
+            links: links ?? [],
+            events: [],
+        });
+        list = [...list, entry];
+        if (list.length > limit) {
+            list = list.slice(list.length - limit);
+        }
+        notify();
+        return id;
+    };
+    const find = (id) => list.find(entry => entry.id === id);
+    const sink = {
+        push,
+        start(input) {
+            const known = open.get(input.key);
+            const entry = known ? find(known) : undefined;
+            if (entry) {
+                const payload = input.payload ?? entry.payload;
+                replace(entry.id, {
+                    ...entry,
+                    payload,
+                    summary: input.summary || entry.summary,
+                    links: [...entry.links, ...(input.links ?? [])],
+                    bytes: jsonBytes(payload) + jsonBytes(entry.result),
+                });
+                notify();
+                return entry.id;
+            }
+            const id = push({ ...input, status: 'running' });
+            open.set(input.key, id);
+            return id;
+        },
+        end(key, outcome = {}) {
+            const id = open.get(key);
+            const entry = id ? find(id) : undefined;
+            if (!id || !entry) {
+                return undefined;
+            }
+            open.delete(key);
+            const result = outcome.result ?? entry.result;
+            replace(id, {
+                ...entry,
+                status: outcome.status ?? (outcome.error ? 'failed' : 'done'),
+                endedAt: outcome.at ?? now(),
+                result,
+                error: outcome.error ?? entry.error,
+                summary: outcome.summary ?? entry.summary,
+                links: [...entry.links, ...(outcome.links ?? [])],
+                bytes: jsonBytes(entry.payload) + jsonBytes(result),
+            });
+            notify();
+            return id;
+        },
+        update(id, patch) {
+            const entry = find(id);
+            if (!entry) {
+                return;
+            }
+            const next = { ...entry, ...patch(entry) };
+            replace(id, {
+                ...next,
+                bytes: jsonBytes(next.payload) + jsonBytes(next.result),
+            });
+            notify();
+        },
+        attach(match, event) {
+            for (let index = list.length - 1; index >= 0; index -= 1) {
+                const entry = list[index];
+                if (match(entry) && !entry.events.includes(event)) {
+                    replace(entry.id, { ...entry, events: [...entry.events, event] });
+                    notify();
+                    return;
+                }
+            }
+            pending = [...pending, { match, event }].slice(-PENDING_LIMIT);
+        },
+        running(key) {
+            return open.has(key);
+        },
+        note(event) {
+            for (const linker of linkers) {
+                const match = linker(event);
+                if (match) {
+                    sink.attach(match, event);
+                    return;
+                }
+            }
+        },
+        addLinker(linker) {
+            linkers.add(linker);
+            return () => {
+                linkers.delete(linker);
+            };
+        },
+        clear() {
+            list = [];
+            open.clear();
+            pending = [];
+            notify();
+        },
+        entries() {
+            return list;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        exportSession() {
+            return { exportedAt: new Date(now()).toISOString(), entries: [...list] };
+        },
+    };
+    return sink;
+}
+const NO_ENTRIES = [];
+const NO_SUBSCRIPTION = () => () => undefined;
+/** A sink's entries, kept current; none without a sink. */
+export function useAgentInspectorEntries(sink) {
+    return useSyncExternalStore(sink ? sink.subscribe : NO_SUBSCRIPTION, () => (sink ? sink.entries() : NO_ENTRIES), () => (sink ? sink.entries() : NO_ENTRIES));
+}
+/**
+ * A sink for a page, made once (or the one given), and its entries: what a
+ * page passes to its team, its chat and its `AgentInspector`.
+ */
+export function useAgentInspector(given) {
+    const [own] = useState(() => given ?? createAgentInspector());
+    const sink = given ?? own;
+    return { sink, entries: useAgentInspectorEntries(sink) };
+}
+/** The sink the chats under it push into. */
+export const AgentInspectorContext = createContext(null);
+/** The sink of the nearest {@link AgentInspectorProvider}, if any. */
+export function useAgentInspectorSink() {
+    return useContext(AgentInspectorContext);
+}
+/** Every chat under it records what its agent does into `sink`. */
+export function AgentInspectorProvider({ sink, children, }) {
+    return createElement(AgentInspectorContext.Provider, { value: sink }, children);
+}
+/** A call's arguments, in a few words: `kind=customer, limit=100`. */
+export function argumentsLine(args, length = 100) {
+    if (!args || typeof args !== 'object') {
+        return args === undefined ? '' : shortLine(String(args), length);
+    }
+    const parts = Object.entries(args).map(([key, value]) => `${key}=${typeof value === 'string' ? value : JSON.stringify(value)}`);
+    return shortLine(parts.join(', '), length);
+}

package/lib/components/inspector/chatInspect.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A chat's agent, as the Agent Inspector records it: each turn of its model
+ * (the prompt, the answer, the tokens), and each tool call from its start to
+ * its end — an MCP server's, a skill, a frontend tool the page runs, a tool
+ * the runtime runs — whatever transport the chat speaks (AG-UI, Vercel AI,
+ * A2A, the in-browser harness): `ChatBase` tells it what its adapter told.
+ *
+ * @module components/inspector/chatInspect
+ */
+import type { MarkedMcpServer } from '../../chat/marks/toolMarks';
+import { type AgentInspectorSink } from './agentInspector';
+export type ChatInspectorRecorder = {
+    turnStarted: (prompt: string, model?: string) => void;
+    turnEnded: (outcome: {
+        text?: string;
+        usage?: {
+            promptTokens?: number;
+            completionTokens?: number;
+            totalTokens?: number;
+        };
+        error?: string;
+    }) => void;
+    toolStarted: (call: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }) => void;
+    toolEnded: (id: string, outcome: {
+        result?: unknown;
+        error?: string;
+    }) => void;
+};
+/** A recorder for one chat's agent (`actor`) into `sink`. */
+export declare function chatInspectorRecorder(sink: AgentInspectorSink, actor: () => string, options?: {
+    /** The page's own tools, by name: frontend tools. */
+    frontendTools?: () => readonly string[];
+    mcpServers?: () => readonly MarkedMcpServer[];
+}): ChatInspectorRecorder;

package/lib/components/inspector/chatInspect.js

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { argumentsLine, shortLine, } from './agentInspector';
+import { classifyToolCall } from './classify';
+/** A recorder for one chat's agent (`actor`) into `sink`. */
+export function chatInspectorRecorder(sink, actor, options = {}) {
+    let turns = 0;
+    let turnKey;
+    return {
+        turnStarted(prompt, model) {
+            turns += 1;
+            turnKey = `chat-turn:${turns}`;
+            sink.start({
+                key: turnKey,
+                actor: actor(),
+                source: 'model',
+                kind: 'turn',
+                ...(model ? { name: model } : {}),
+                summary: shortLine(prompt),
+                payload: { prompt, ...(model ? { model } : {}) },
+            });
+        },
+        turnEnded({ text, usage, error }) {
+            if (!turnKey) {
+                return;
+            }
+            const total = usage?.totalTokens ??
+                (usage?.promptTokens ?? 0) + (usage?.completionTokens ?? 0);
+            sink.end(turnKey, {
+                ...(error ? { status: 'failed', error } : {}),
+                result: {
+                    ...(text ? { text } : {}),
+                    ...(usage ? { usage } : {}),
+                },
+                ...(total ? { summary: `${total} tokens` } : {}),
+            });
+            turnKey = undefined;
+        },
+        toolStarted({ id, name, args }) {
+            const kind = classifyToolCall(name, args, {
+                frontendTools: options.frontendTools?.(),
+                mcpServers: options.mcpServers?.(),
+            });
+            sink.start({
+                key: `chat-tool:${id}`,
+                actor: actor(),
+                source: kind.source,
+                ...(kind.icon ? { icon: kind.icon } : {}),
+                ...(kind.emoji ? { emoji: kind.emoji } : {}),
+                kind: 'tool-call',
+                name,
+                summary: argumentsLine(args),
+                payload: args,
+            });
+        },
+        toolEnded(id, { result, error }) {
+            sink.end(`chat-tool:${id}`, {
+                ...(error ? { status: 'failed', error } : {}),
+                result,
+            });
+        },
+    };
+}

package/lib/components/inspector/classify.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Where a tool call comes from, for the Agent Inspector, by what the
+ * catalogue says of its name. Apart from the record itself, which a page can
+ * keep without loading the catalogues.
+ *
+ * @module components/inspector/classify
+ */
+import { type MarkedMcpServer } from '../../chat/marks/toolMarks';
+import type { AgentInspectorSource, ToolClass } from './agentInspector';
+/**
+ * Where a tool call comes from, by who claims its name: a skill, one of
+ * `mcpServers`, a frontend tool (the catalogue's, or one of `frontendTools`),
+ * a runtime tool; otherwise `fallback` — a tool the runtime runs.
+ */
+export declare function classifyToolCall(name: string, args?: Record<string, unknown>, options?: {
+    mcpServers?: readonly MarkedMcpServer[];
+    frontendTools?: readonly string[];
+    fallback?: AgentInspectorSource;
+}): ToolClass;

package/lib/components/inspector/classify.js

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Where a tool call comes from, for the Agent Inspector, by what the
+ * catalogue says of its name. Apart from the record itself, which a page can
+ * keep without loading the catalogues.
+ *
+ * @module components/inspector/classify
+ */
+import { marksOfToolCall, } from '../../chat/marks/toolMarks';
+/**
+ * Where a tool call comes from, by who claims its name: a skill, one of
+ * `mcpServers`, a frontend tool (the catalogue's, or one of `frontendTools`),
+ * a runtime tool; otherwise `fallback` — a tool the runtime runs.
+ */
+export function classifyToolCall(name, args, options = {}) {
+    if (options.frontendTools?.includes(name)) {
+        const marks = marksOfToolCall(name, args, options.mcpServers);
+        return {
+            source: 'frontend-tool',
+            ...(marks?.icon ? { icon: marks.icon } : {}),
+            ...(marks?.emoji ? { emoji: marks.emoji } : {}),
+        };
+    }
+    const marks = marksOfToolCall(name, args, options.mcpServers);
+    const source = marks?.kind === 'skill'
+        ? 'skill'
+        : marks?.kind === 'mcp'
+            ? 'mcp'
+            : marks?.kind === 'frontend'
+                ? 'frontend-tool'
+                : marks?.kind === 'runtime'
+                    ? 'backend-tool'
+                    : (options.fallback ?? 'backend-tool');
+    return {
+        source,
+        ...(marks?.icon ? { icon: marks.icon } : {}),
+        ...(marks?.emoji ? { emoji: marks.emoji } : {}),
+    };
+}

package/lib/components/inspector/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The Agent Inspector: what agents do — A2A traffic, MCP calls, skills,
+ * frontend and backend tools, model turns, approvals — recorded into a sink
+ * and drawn as rows that unfold to their payloads.
+ *
+ * @module components/inspector
+ */
+export * from './agentInspector';
+export * from './classify';
+export * from './chatInspect';
+export * from './a2aInspect';
+export * from './JsonTree';
+export * from './AgentInspector';
+export * from './AgentInspectorDialog';

package/lib/components/inspector/index.js

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The Agent Inspector: what agents do — A2A traffic, MCP calls, skills,
+ * frontend and backend tools, model turns, approvals — recorded into a sink
+ * and drawn as rows that unfold to their payloads.
+ *
+ * @module components/inspector
+ */
+export * from './agentInspector';
+export * from './classify';
+export * from './chatInspect';
+export * from './a2aInspect';
+export * from './JsonTree';
+export * from './AgentInspector';
+export * from './AgentInspectorDialog';

package/lib/components/teams/A2ATeamGraph.d.ts

@@ -25,6 +25,12 @@
 import type { JSX } from 'react';
 import { type Edge, type EdgeProps, type Viewport } from '@xyflow/react';
 import '@xyflow/react/dist/base.css';
+import { type AssistantAbout } from '../../chat/assistant/AssistantStage';
+import type { BalloonSuggestion } from '../../chat/assistant/SpeechBalloon';
+import type { DisplayItem } from '../../types/chat';
+import type { AssistantMenuItem } from '../../chat/assistant/AssistantContextMenu';
+import type { AssistantSandbox } from '../../chat/assistant/assistantDetails';
+import type { AgentInspectorSink } from '../inspector/agentInspector';
 import { type A2ATeamCall, type A2ATeamConnection, type A2ATeamFlow } from './a2aTeamFlow';
 import type { A2ATeamPersona } from './useA2ATeam';
 import type { BalloonExpandTarget } from '../../chat/assistant/BalloonVisual';
@@ -65,6 +71,42 @@ export type A2ATeamGraphMember = {
     expandTarget?: BalloonExpandTarget;
     /** What its notebook is called: `Accounting's notebook`. */
     notebookTitle?: string;
+    /**
+     * What the person may ask it: chips in its balloon while it waits for a
+     * question, and a group of its menu; one chosen is sent (`onSuggestion`).
+     */
+    suggestions?: readonly BalloonSuggestion[];
+    onSuggestion?: (suggestion: BalloonSuggestion) => void;
+    /**
+     * The team's Agent Inspector: its menu offers *Inspect the agent…*, its
+     * own record (what it did, and the A2A messages it sent or received).
+     */
+    inspector?: AgentInspectorSink | null;
+    /** Stops its turn, from its menu, while it works. */
+    onStop?: () => void;
+    /** What its menu's *About* and *Agent Details…* say. */
+    about?: AssistantAbout;
+    /**
+     * Its code sandbox, for *Code Sandbox Details…*. The entry — the agent in
+     * the page — has the kernel of the notebook open under the graph, while
+     * one is.
+     */
+    sandbox?: AssistantSandbox;
+    /** The host's own entries of its menu. */
+    contextMenu?: readonly AssistantMenuItem[];
+    /**
+     * What its menu calls a click on it (`onToggle`): `Ask Sales` where it
+     * takes the person to the composer. Without `onToggle`, its menu has no
+     * such entry.
+     */
+    conversationLabel?: string;
+    /**
+     * What it said and did, as its `history` balloon lists it (`useA2ATeam`'s
+     * `entryHistory`, `peerHistory`): shown when its menu chooses *History*.
+     */
+    history?: readonly DisplayItem[];
+    /** Its balloon's display was chosen in its menu: the page may keep it. */
+    onBalloonDisplayChange?: (display: BalloonDisplay) => void;
 };
 export type A2ATeamGraphProps = {
     /** The member that asks: drawn on the left. */
@@ -81,7 +123,33 @@ export type A2ATeamGraphProps = {
     size?: number;
     /** The tool calls running now, to the members' connections (`useA2ATeam`). */
     calls?: A2ATeamCall[];
+    /**
+     * The room above the members for their balloons, in pixels at full scale:
+     * a page that shows suggestions, *more* and a notebook in them gives more.
+     * A notebook in a balloon gets at least its own.
+     */
+    balloonRoom?: number;
+};
+/** How far a member was moved from its place, in the graph's coordinates. */
+export type MemberOffset = {
+    dx: number;
+    dy: number;
+};
+/** How far a member may move: its node stays inside the graph's box. */
+export type MemberBounds = {
+    minDx: number;
+    maxDx: number;
+    minDy: number;
+    maxDy: number;
 };
+/** An offset kept inside its bounds. */
+export declare function clampOffset(offset: MemberOffset, bounds: MemberBounds): MemberOffset;
+/** A member's accessible name: its name, and where it runs. */
+export declare function memberLabel(member: Pick<A2ATeamGraphMember, 'name' | 'where'>): string;
+/** A connection's accessible name: `Odoo, Accounting's MCP connection`. */
+export declare function connectionLabel(connection: Pick<A2ATeamConnection, 'label'>, member: string | undefined): string;
+/** What a connection's details say: the server, who reaches it, and the call running now. */
+export declare function connectionDetails(connection: Pick<A2ATeamConnection, 'name' | 'tools'>, member: string | undefined, calling?: string): string;
 /** The words on the edge for a flow. */
 export declare function flowWords(flow: A2ATeamFlow, entry: string, peer: string): string;
 type CallData = {
@@ -95,5 +163,5 @@ export declare function callWords(member: string, connection: A2ATeamConnection,
 /** The viewport that shows the graph's width whole in a box `width` wide, never larger than drawn. */
 export declare function teamViewport(width: number): Viewport;
 /** Draw a team of two over A2A, the link moving with what travels on it. */
-export declare function A2ATeamGraph({ entry, peer, flow, connected, label, size, calls, }: A2ATeamGraphProps): JSX.Element;
+export declare function A2ATeamGraph({ entry, peer, flow, connected, label, size, calls, balloonRoom, }: A2ATeamGraphProps): JSX.Element;
 export default A2ATeamGraph;