@datalayer/agent-runtimes 1.3.74 → 1.3.75

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

@@ -0,0 +1,179 @@
+/**
+ * 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 { type JSX, type ReactNode } from 'react';
+/** Where an entry comes from. */
+export type AgentInspectorSource = 'a2a' | 'mcp' | 'skill' | 'frontend-tool' | 'backend-tool' | 'model' | 'approval';
+/** Every source, in the order the filters list them. */
+export declare const AGENT_INSPECTOR_SOURCES: readonly AgentInspectorSource[];
+/** A source, in words. */
+export declare const AGENT_INSPECTOR_SOURCE_LABELS: Record<AgentInspectorSource, string>;
+export type AgentInspectorStatus = 'running' | 'done' | 'failed';
+/** What A2A says of an entry: its JSON-RPC method and id, its task and context, its state. */
+export type AgentInspectorA2A = {
+    method?: string;
+    rpcId?: string | number;
+    taskId?: string;
+    contextId?: string;
+    /** `TASK_STATE_WORKING`, … */
+    state?: string;
+    /** The tool step a status carries: its call's id, and whether it is its end. */
+    step?: {
+        toolId?: string;
+        name: string;
+        ended: boolean;
+    };
+    /** The artifact an artifact update is a chunk of. */
+    artifactId?: string;
+    /** How many chunks an artifact entry holds. */
+    chunks?: number;
+};
+export type AgentInspectorEntry = {
+    id: string;
+    /** When it happened, or started: ms since the epoch. */
+    at: number;
+    /** When it ended, for a call. */
+    endedAt?: number;
+    /** Which agent did it. */
+    actor: string;
+    source: AgentInspectorSource;
+    /** `request`, `status-update`, `artifact-update`, `task`, `message`, `tool-call`, `turn`, … */
+    kind: string;
+    /** The tool's, skill's or method's name. */
+    name?: string;
+    /** Its mark, as `SpecMark` draws it. */
+    icon?: string;
+    emoji?: string;
+    status?: AgentInspectorStatus;
+    /** One line that says it. */
+    summary: string;
+    /** Which way it went, between two agents. */
+    direction?: {
+        from: string;
+        to: string;
+    };
+    a2a?: AgentInspectorA2A;
+    /** What was sent: a message, or a call's arguments. */
+    payload?: unknown;
+    /** What came back, for a call. */
+    result?: unknown;
+    error?: string;
+    /** How large `payload` and `result` are, as JSON, in bytes. */
+    bytes: number;
+    /** The key a call's start and end share. */
+    key?: string;
+    /** Entries this one goes with: a tool call's A2A statuses, … */
+    links: string[];
+    /** What a caller made of it: the semantic events attached (`A2APeerEvent`, …). */
+    events: unknown[];
+};
+/** What is pushed: an entry, less what the sink works out. */
+export type AgentInspectorInput = Omit<AgentInspectorEntry, 'id' | 'at' | 'bytes' | 'links' | 'events'> & {
+    at?: number;
+    links?: string[];
+};
+/** How a call ended. */
+export type AgentInspectorOutcome = {
+    status?: Exclude<AgentInspectorStatus, 'running'>;
+    result?: unknown;
+    error?: string;
+    at?: number;
+    summary?: string;
+    links?: string[];
+};
+/** A session, exported. */
+export type AgentInspectorExport = {
+    exportedAt: string;
+    entries: AgentInspectorEntry[];
+};
+export interface AgentInspectorSink {
+    /** Record something that happened at once; returns its id. */
+    push(input: AgentInspectorInput): string;
+    /**
+     * Open a call under `key`; a call already open under it has its payload
+     * and summary updated instead (arguments that stream in).
+     */
+    start(input: AgentInspectorInput & {
+        key: string;
+    }): string;
+    /** Close the call open under `key`; `undefined` when none is. */
+    end(key: string, outcome?: AgentInspectorOutcome): string | undefined;
+    /** Change an entry. */
+    update(id: string, patch: (entry: AgentInspectorEntry) => Partial<AgentInspectorEntry>): void;
+    /**
+     * Attach a semantic event to the newest entry `match` takes, or to the
+     * first that arrives and does (a few are kept waiting).
+     */
+    attach(match: (entry: AgentInspectorEntry) => boolean, event: unknown): void;
+    /** Whether a call is open under `key`. */
+    running(key: string): boolean;
+    /**
+     * Say what a caller made of something (an `A2APeerEvent`): it is attached
+     * to the entry it came from, as the first linker that knows it says
+     * (`addLinker`; the A2A capture adds one). Nothing knows it: dropped.
+     */
+    note(event: unknown): void;
+    /** Teach the sink to link a kind of event to its entry; returns its removal. */
+    addLinker(linker: AgentInspectorLinker): () => void;
+    clear(): void;
+    entries(): readonly AgentInspectorEntry[];
+    subscribe(listener: () => void): () => void;
+    exportSession(): AgentInspectorExport;
+}
+/** The entry an event came from, as a matcher; `undefined` for an event it does not know. */
+export type AgentInspectorLinker = (event: unknown) => ((entry: AgentInspectorEntry) => boolean) | undefined;
+/** How large a value is, as JSON, in bytes. */
+export declare function jsonBytes(value: unknown): number;
+/** A size, in words: `812 B`, `12.3 kB`, `1.2 MB`. */
+export declare function formatBytes(bytes: number): string;
+/** A line short enough for a row. */
+export declare function shortLine(text: string, length?: number): string;
+export type AgentInspectorOptions = {
+    /** The clock: `Date.now` unless a test sets it. */
+    now?: () => number;
+    /** The most entries kept: the oldest go first. */
+    limit?: number;
+};
+/** Make a sink: the record, and who listens to it. */
+export declare function createAgentInspector(options?: AgentInspectorOptions): AgentInspectorSink;
+/** A sink's entries, kept current; none without a sink. */
+export declare function useAgentInspectorEntries(sink: AgentInspectorSink | null | undefined): readonly AgentInspectorEntry[];
+/**
+ * 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 declare function useAgentInspector(given?: AgentInspectorSink | null): {
+    sink: AgentInspectorSink;
+    entries: readonly AgentInspectorEntry[];
+};
+/** The sink the chats under it push into. */
+export declare const AgentInspectorContext: import("react").Context<AgentInspectorSink | null>;
+/** The sink of the nearest {@link AgentInspectorProvider}, if any. */
+export declare function useAgentInspectorSink(): AgentInspectorSink | null;
+/** Every chat under it records what its agent does into `sink`. */
+export declare function AgentInspectorProvider({ sink, children, }: {
+    sink: AgentInspectorSink;
+    children?: ReactNode;
+}): JSX.Element;
+/** What a tool call is, for the inspector: its source and its mark. */
+export type ToolClass = {
+    source: AgentInspectorSource;
+    icon?: string;
+    emoji?: string;
+};
+/** A call's arguments, in a few words: `kind=customer, limit=100`. */
+export declare function argumentsLine(args: unknown, length?: number): string;

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';