@datalayer/agent-runtimes 1.3.84 → 1.3.86

package/lib/components/inspector/AgentInspector.js

@@ -1,220 +1,32 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { useMemo, useState } from 'react';
-import { ActionList, ActionMenu, Button, Label, Text } from '@primer/react';
-import { Box } from '@datalayer/primer-addons';
-import { DownloadIcon, PlayIcon, TrashIcon, PauseIcon, } from '@primer/octicons-react';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { OtelLiveSpans, } from '@datalayer/core/lib/otel/views/OtelLiveSpans';
 import { SpecMark } from '../../chat/marks';
-import { AGENT_INSPECTOR_SOURCES, AGENT_INSPECTOR_SOURCE_LABELS, formatBytes, useAgentInspectorEntries, } from './agentInspector';
-import { JsonTree } from './JsonTree';
-/** Whether an entry is one agent's: done by it, or sent to or by it. */
-export function isAgentsEntry(entry, agent) {
-    return (entry.actor === agent ||
-        entry.direction?.from === agent ||
-        entry.direction?.to === agent);
-}
-/** Which way an entry went, from one agent's side: `→ Accounting`, `← Accounting`. */
-export function directionFrom(entry, agent) {
-    const direction = entry.direction;
-    if (!direction) {
-        return entry.actor;
-    }
-    if (agent === direction.from) {
-        return `sent → ${direction.to}`;
-    }
-    if (agent === direction.to) {
-        return `received ← ${direction.from}`;
-    }
-    return `${direction.from} → ${direction.to}`;
-}
-/** A kind, as its label is coloured. */
-const KIND_VARIANTS = {
-    request: 'accent',
-    'status-update': 'attention',
-    'artifact-update': 'success',
-    task: 'secondary',
-    message: 'done',
-    'agent-card': 'secondary',
-    response: 'secondary',
-    'tool-call': 'sponsors',
-    turn: 'primary',
-    error: 'danger',
-    approval: 'severe',
-};
-const pad = (value, length = 2) => String(value).padStart(length, '0');
-/** A time of day, to the millisecond: `15:44:31.299`. */
-export function clockTime(at) {
-    const date = new Date(at);
-    return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`;
-}
-/** Time since the first entry: `+1.204s`. */
-export function sinceFirst(at, first) {
-    return `+${((at - first) / 1000).toFixed(3)}s`;
-}
-/** How long a call took: `412 ms`, `3.4 s`. */
-export function durationText(ms) {
-    return ms < 1000 ? `${Math.round(ms)} ms` : `${(ms / 1000).toFixed(1)} s`;
-}
-/** The entries a filter keeps: an empty set keeps every value. */
-export function filterEntries(entries, filter) {
-    return entries.filter(entry => (!filter.sources.size || filter.sources.has(entry.source)) &&
-        (!filter.kinds.size || filter.kinds.has(entry.kind)) &&
-        (!filter.actors.size || filter.actors.has(entry.actor)));
-}
-/** A session, as JSON. */
-export function exportEntries(entries) {
-    return { exportedAt: new Date().toISOString(), entries: [...entries] };
-}
-function toggle(set, value) {
-    const next = new Set(set);
-    if (next.has(value)) {
-        next.delete(value);
-    }
-    else {
-        next.add(value);
-    }
-    return next;
-}
-function FilterMenu({ label, options, selected, onToggle, onAll, name, }) {
-    return (_jsxs(ActionMenu, { children: [_jsxs(ActionMenu.Button, { size: "small", "data-inspector-filter": label.toLowerCase(), children: [label, selected.size ? ` · ${selected.size}` : ''] }), _jsx(ActionMenu.Overlay, { width: "auto", children: _jsxs(ActionList, { selectionVariant: "multiple", "aria-label": label, children: [_jsx(ActionList.Item, { selected: !selected.size, onSelect: onAll, children: "All" }), _jsx(ActionList.Divider, {}), options.map(option => (_jsx(ActionList.Item, { selected: selected.has(option), onSelect: () => onToggle(option), children: name(option) }, option)))] }) })] }));
-}
-function Payload({ title, value, large, }) {
-    const bytes = useMemo(() => {
-        try {
-            return new TextEncoder().encode(JSON.stringify(value) ?? '').length;
-        }
-        catch {
-            return 0;
-        }
-    }, [value]);
-    const [shown, setShown] = useState(bytes <= large);
-    return (_jsxs(Box, { sx: { minWidth: 0 }, "data-inspector-payload": title, children: [_jsxs(Text, { sx: {
-                    fontSize: 0,
-                    color: 'fg.muted',
-                    fontWeight: 600,
-                    display: 'block',
-                }, children: [title, " \u00B7 ", formatBytes(bytes)] }), shown ? (_jsx(JsonTree, { value: value, expandDepth: bytes > large ? 1 : 2 })) : (_jsxs(Button, { size: "small", onClick: () => setShown(true), "data-inspector-large": "", children: ["Show ", formatBytes(bytes)] }))] }));
-}
-function Row({ entry, first, open, onToggle, large, agent, }) {
-    const ended = entry.endedAt !== undefined;
-    return (_jsxs(Box, { as: "li", "data-inspector-entry": entry.id, "data-inspector-source": entry.source, "data-inspector-kind": entry.kind, "data-inspector-status": entry.status ?? '', sx: {
-            borderBottom: '1px solid',
-            borderColor: 'border.muted',
-            listStyle: 'none',
-        }, children: [_jsxs(Box, { as: "button", type: "button", "aria-expanded": open, onClick: onToggle, sx: {
-                    width: '100%',
-                    display: 'grid',
-                    gridTemplateColumns: ['auto 1fr', 'auto auto auto minmax(0, 1fr)'],
-                    columnGap: 2,
-                    rowGap: 1,
-                    alignItems: 'center',
-                    px: 2,
-                    py: 1,
-                    border: 0,
-                    bg: open ? 'canvas.subtle' : 'transparent',
-                    color: 'fg.default',
-                    font: 'inherit',
-                    fontSize: 0,
-                    textAlign: 'left',
-                    cursor: 'pointer',
-                    '&:hover': { bg: 'canvas.subtle' },
-                }, children: [_jsxs(Box, { sx: { fontFamily: 'mono', color: 'fg.muted', whiteSpace: 'nowrap' }, children: [_jsx("span", { title: new Date(entry.at).toISOString(), children: clockTime(entry.at) }), ' ', _jsx(Text, { sx: { opacity: 0.7 }, children: sinceFirst(entry.at, first) })] }), _jsx(Text, { sx: { whiteSpace: 'nowrap', fontWeight: 600 }, "data-inspector-direction": "", children: directionFrom(entry, agent) }), _jsxs(Box, { sx: { display: 'flex', gap: 1, flexWrap: 'wrap' }, children: [_jsx(Label, { size: "small", variant: "secondary", children: AGENT_INSPECTOR_SOURCE_LABELS[entry.source] }), _jsx(Label, { size: "small", variant: KIND_VARIANTS[entry.kind] ?? 'secondary', children: entry.kind })] }), _jsxs(Box, { sx: { display: 'flex', gap: 1, alignItems: 'center', minWidth: 0 }, children: [(entry.icon || entry.emoji) && (_jsx(SpecMark, { icon: entry.icon, emoji: entry.emoji, size: 14 })), entry.name && entry.kind !== 'request' && (_jsx(Text, { sx: { fontFamily: 'mono', fontWeight: 600, whiteSpace: 'nowrap' }, children: entry.name })), entry.status && (_jsxs(Label, { size: "small", variant: entry.status === 'failed'
-                                    ? 'danger'
-                                    : entry.status === 'running'
-                                        ? 'attention'
-                                        : 'success', children: [entry.status, ended && entry.endedAt !== undefined
-                                        ? ` · ${durationText(entry.endedAt - entry.at)}`
-                                        : ''] })), _jsx(Text, { sx: {
-                                    color: 'fg.muted',
-                                    overflow: 'hidden',
-                                    textOverflow: 'ellipsis',
-                                    whiteSpace: 'nowrap',
-                                    minWidth: 0,
-                                }, title: entry.summary, children: entry.summary }), entry.bytes > large && (_jsx(Text, { sx: { color: 'fg.muted', whiteSpace: 'nowrap' }, children: formatBytes(entry.bytes) }))] })] }), open && (_jsxs(Box, { "data-inspector-details": "", sx: {
-                    px: 3,
-                    py: 2,
-                    display: 'flex',
-                    flexDirection: 'column',
-                    gap: 2,
-                    bg: 'canvas.subtle',
-                }, children: [entry.a2a && (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', fontFamily: 'mono' }, children: [
-                            entry.a2a.method && `method ${entry.a2a.method}`,
-                            entry.a2a.rpcId !== undefined && `id ${entry.a2a.rpcId}`,
-                            entry.a2a.taskId && `task ${entry.a2a.taskId}`,
-                            entry.a2a.contextId && `context ${entry.a2a.contextId}`,
-                            entry.a2a.state && entry.a2a.state,
-                            entry.a2a.chunks &&
-                                entry.a2a.chunks > 1 &&
-                                `${entry.a2a.chunks} chunks`,
-                        ]
-                            .filter(Boolean)
-                            .join(' · ') })), entry.error && (_jsx(Text, { sx: { color: 'danger.fg', fontSize: 0 }, children: entry.error })), entry.payload !== undefined && (_jsx(Payload, { title: entry.kind === 'tool-call' ? 'Arguments' : 'Payload', value: entry.payload, large: large })), entry.result !== undefined && (_jsx(Payload, { title: "Result", value: entry.result, large: large })), entry.events.length > 0 && (_jsx(Payload, { title: "Events", value: entry.events, large: large })), entry.links.length > 0 && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: ["Linked: ", entry.links.join(', ')] }))] }))] }));
-}
-/** Save a session as a JSON file. */
-function download(name, session) {
-    const blob = new Blob([JSON.stringify(session, null, 2)], {
-        type: 'application/json',
-    });
-    const url = URL.createObjectURL(blob);
-    const link = document.createElement('a');
-    link.href = url;
-    link.download = `${name}.json`;
-    link.click();
-    setTimeout(() => URL.revokeObjectURL(url), 1000);
+import { AGENT_SPAN_ATTRIBUTES, SPAN_SOURCE_LABELS, describeAgentSpan, sourceOfSpan, } from './agentSpans';
+/** The Inspector's filters: where a span comes from, what it does, which agent. */
+export const AGENT_INSPECTOR_FACETS = [
+    {
+        label: 'Source',
+        value: sourceOfSpan,
+        name: value => SPAN_SOURCE_LABELS[value] ?? value,
+    },
+    {
+        label: 'Operation',
+        value: span => {
+            const attributes = span.attributes ?? {};
+            const operation = attributes[AGENT_SPAN_ATTRIBUTES.operation] ?? attributes['rpc.method'];
+            return operation === undefined ? undefined : String(operation);
+        },
+    },
+    { label: 'Agent', value: span => span.service_name },
+];
+/** A span's mark: its tool's, as the catalogue gives it. */
+function spanMark(span) {
+    const icon = span.attributes?.[AGENT_SPAN_ATTRIBUTES.markIcon];
+    const emoji = span.attributes?.[AGENT_SPAN_ATTRIBUTES.markEmoji];
+    return icon || emoji ? (_jsx(SpecMark, { icon: typeof icon === 'string' ? icon : undefined, emoji: typeof emoji === 'string' ? emoji : undefined, size: 14 })) : null;
 }
 /** The Agent Inspector. */
-export function AgentInspector({ sink, entries: given, maxHeight = 420, largeBytes = 16_000, emptyText = 'Nothing recorded yet.', exportName = 'agent-inspector', agent, }) {
-    const live = useAgentInspectorEntries(sink);
-    const everything = given ?? live;
-    const all = useMemo(() => agent
-        ? everything.filter(entry => isAgentsEntry(entry, agent))
-        : everything, [everything, agent]);
-    const [held, setHeld] = useState(null);
-    const [clearedAt, setClearedAt] = useState(0);
-    const [sources, setSources] = useState(new Set());
-    const [kinds, setKinds] = useState(new Set());
-    const [actors, setActors] = useState(new Set());
-    const [open, setOpen] = useState(new Set());
-    const recorded = useMemo(() => (clearedAt ? all.filter(entry => entry.at >= clearedAt) : all), [all, clearedAt]);
-    const shown = held ?? recorded;
-    const waiting = held ? recorded.length - held.length : 0;
-    const kindOptions = useMemo(() => [...new Set(recorded.map(entry => entry.kind))].sort(), [recorded]);
-    const actorOptions = useMemo(() => [...new Set(recorded.map(entry => entry.actor))].sort(), [recorded]);
-    const sourceOptions = useMemo(() => AGENT_INSPECTOR_SOURCES.filter(source => recorded.some(entry => entry.source === source)), [recorded]);
-    const rows = useMemo(() => filterEntries(shown, { sources, kinds, actors }), [shown, sources, kinds, actors]);
-    const first = shown[0]?.at ?? 0;
-    return (_jsxs(Box, { "data-agent-inspector": "", sx: {
-            border: '1px solid',
-            borderColor: 'border.default',
-            borderRadius: 2,
-            bg: 'canvas.default',
-            color: 'fg.default',
-            minWidth: 0,
-        }, children: [_jsxs(Box, { role: "toolbar", "aria-label": agent ? `${agent}'s Agent Inspector` : 'Agent Inspector', sx: {
-                    display: 'flex',
-                    flexWrap: 'wrap',
-                    gap: 2,
-                    alignItems: 'center',
-                    p: 2,
-                    borderBottom: '1px solid',
-                    borderColor: 'border.default',
-                }, children: [_jsx(FilterMenu, { label: "Source", options: sourceOptions, selected: sources, onToggle: value => setSources(toggle(sources, value)), onAll: () => setSources(new Set()), name: value => AGENT_INSPECTOR_SOURCE_LABELS[value] }), _jsx(FilterMenu, { label: "Kind", options: kindOptions, selected: kinds, onToggle: value => setKinds(toggle(kinds, value)), onAll: () => setKinds(new Set()), name: value => value }), _jsx(FilterMenu, { label: "Actor", options: actorOptions, selected: actors, onToggle: value => setActors(toggle(actors, value)), onAll: () => setActors(new Set()), name: value => value }), _jsx(Box, { sx: { flex: 1 } }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, "data-inspector-count": "", children: [rows.length === shown.length
-                                ? `${rows.length} ${rows.length === 1 ? 'entry' : 'entries'}`
-                                : `${rows.length} of ${shown.length}`, waiting > 0 ? ` · ${waiting} new` : ''] }), _jsx(Button, { size: "small", leadingVisual: held ? PlayIcon : PauseIcon, "aria-pressed": held !== null, onClick: () => setHeld(held ? null : recorded), "data-inspector-pause": "", children: held ? 'Resume' : 'Pause' }), _jsx(Button, { size: "small", leadingVisual: TrashIcon, onClick: () => {
-                            setOpen(new Set());
-                            setHeld(null);
-                            // One agent's view of a shared record clears only itself.
-                            if (sink && !given && !agent) {
-                                sink.clear();
-                            }
-                            else {
-                                setClearedAt(Date.now());
-                            }
-                        }, "data-inspector-clear": "", children: "Clear" }), _jsx(Button, { size: "small", leadingVisual: DownloadIcon, disabled: !recorded.length, onClick: () => download(exportName, exportEntries(recorded)), "data-inspector-export": "", children: "Export" })] }), _jsx(Box, { as: "ol", "aria-label": "Recorded", sx: { m: 0, p: 0, maxHeight, overflowY: 'auto' }, children: rows.length === 0 ? (_jsx(Text, { as: "li", sx: {
-                        display: 'block',
-                        p: 3,
-                        color: 'fg.muted',
-                        fontSize: 1,
-                        listStyle: 'none',
-                    }, children: emptyText })) : (rows.map(entry => (_jsx(Row, { entry: entry, first: first, large: largeBytes, agent: agent, open: open.has(entry.id), onToggle: () => setOpen(toggle(open, entry.id)) }, entry.id)))) })] }));
+export function AgentInspector({ tracer, spans, agent, maxHeight = 420, compact = false, emptyText = 'Nothing recorded yet.', exportName = 'agent-inspector', }) {
+    return (_jsx("div", { "data-agent-inspector": agent ?? '', children: _jsx(OtelLiveSpans, { tracer: tracer, spans: spans, service: agent, facets: AGENT_INSPECTOR_FACETS, compact: compact, maxHeight: maxHeight, detailPlacement: "side", emptyText: emptyText, exportName: exportName, label: agent ? `${agent}'s Agent Inspector` : 'Agent Inspector', renderSpanMark: spanMark, describeSpan: describeAgentSpan }) }));
 }
 export default AgentInspector;

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

@@ -1,19 +1,19 @@
 /**
  * The Agent Inspector over the page: a large dialog, the inspector loaded
- * only when it opens, fed by the sink the agent's chat or team feeds. Esc
- * closes it.
+ * only when it opens, drawing the spans the agent's chat or team records
+ * into its tracer. Esc closes it.
  *
  * @module components/inspector/AgentInspectorDialog
  */
 import type { JSX } from 'react';
-import type { AgentInspectorSink } from './agentInspector';
+import type { OtelLiveTracer } from '@datalayer/core/lib/otel/live';
 export type AgentInspectorDialogProps = {
-    sink: AgentInspectorSink | null;
+    tracer: OtelLiveTracer | null;
     /** The dialog's title. */
     title?: string;
-    /** One agent's own record (`AgentInspector`'s `agent`); all of it without. */
+    /** One agent's own spans (`AgentInspector`'s `agent`); all of them without. */
     agent?: string;
     onClose: () => void;
 };
-export declare function AgentInspectorDialog({ sink, title, agent, onClose, }: AgentInspectorDialogProps): JSX.Element;
+export declare function AgentInspectorDialog({ tracer, title, agent, onClose, }: AgentInspectorDialogProps): JSX.Element;
 export default AgentInspectorDialog;

package/lib/components/inspector/AgentInspectorDialog.js

@@ -3,7 +3,7 @@ import { Suspense, lazy } from 'react';
 import { Dialog } from '@primer/react';
 import { Text } from '@primer/react';
 const AgentInspector = lazy(() => import('./AgentInspector'));
-export function AgentInspectorDialog({ sink, title = 'Agent Inspector', agent, onClose, }) {
-    return (_jsx(Dialog, { title: title, onClose: onClose, width: "xlarge", height: "large", "data-agent-inspector-dialog": "", children: _jsx(Suspense, { fallback: _jsx(Text, { sx: { color: 'fg.muted' }, children: "Loading the Agent Inspector\u2026" }), children: _jsx(AgentInspector, { sink: sink, agent: agent, maxHeight: "calc(80vh - 140px)", emptyText: "Nothing recorded yet: what the agent does shows here as it does it." }) }) }));
+export function AgentInspectorDialog({ tracer, title = 'Agent Inspector', agent, onClose, }) {
+    return (_jsx(Dialog, { title: title, onClose: onClose, width: "xlarge", height: "large", "data-agent-inspector-dialog": "", children: _jsx(Suspense, { fallback: _jsx(Text, { sx: { color: 'fg.muted' }, children: "Loading the Agent Inspector\u2026" }), children: _jsx(AgentInspector, { tracer: tracer, agent: agent, maxHeight: "calc(80vh - 140px)", emptyText: "Nothing recorded yet: what the agent does shows here as it does it." }) }) }));
 }
 export default AgentInspectorDialog;

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

@@ -0,0 +1,51 @@
+/**
+ * The A2A traffic between two agents, as OpenTelemetry spans: a fetch that
+ * hands every request on and records each JSON-RPC request as a client span
+ * of the asker's — `a2a <method>`, with the RPC conventions (`rpc.system`
+ * `jsonrpc`, `rpc.service` `a2a`, `rpc.method`, `rpc.jsonrpc.request_id`),
+ * the agent asked as `peer.service`, the request whole (`a2a.request`) and
+ * its words (`a2a.message.text`) — and what came back as its events: a
+ * JSON-RPC response, or each server-sent event of a stream (`a2a.task`,
+ * `a2a.status_update`, `a2a.artifact_update`, `a2a.message`, `a2a.error`),
+ * each with its task, context and state, and the event whole (`a2a.event`).
+ * The text chunks of one artifact are one event, their count kept.
+ *
+ * Any other request (the agent card) is a client span too: `a2a agent card`
+ * when it brings one back, its name and skills with it.
+ *
+ * A peer served by agent-runtimes tells each tool call of its agent on a
+ * `working` status (`{tool_call}`, then `{tool_result}`): each is recorded as
+ * an `execute_tool` span of the peer's under the request's span, from its
+ * start to its end, an MCP call, a skill, codemode's or a tool its runtime
+ * runs, by who claims its name (`datalayer.span.origin` `a2a.status`: the
+ * page knows of it from the peer's own words).
+ *
+ * It sits under the A2A SDK (`ClientFactory`'s `JsonRpcTransportFactory`
+ * takes a `fetchImpl`): the SDK reads the response it is handed, and this
+ * reads a copy of its body. Nothing it records changes what the SDK sees,
+ * and a key sent as a header is never recorded.
+ *
+ * @module components/inspector/a2aSpans
+ */
+import type { OtelLiveTracer } from '@datalayer/core/lib/otel/live';
+import { type ToolClass } from './agentSpans';
+export type A2ASpansOptions = {
+    tracer: OtelLiveTracer;
+    /** The agent that asks: `Sales`. */
+    asker: string;
+    /** The agent asked: `Accounting`. */
+    peer: string;
+    /**
+     * Where a peer's tool call comes from — an MCP server's, a skill, … — and
+     * its marks (`classifyToolCall`, or a team's `teamToolClassifier`).
+     * Without it, a tool the peer's runtime runs.
+     */
+    classifyTool?: (name: string, args?: Record<string, unknown>) => ToolClass;
+};
+/** The text of an A2A 1.0 message's or artifact's parts, as JSON carries them. */
+export declare function partsText(parts: unknown): string;
+/**
+ * A fetch that records the A2A traffic it carries as spans into
+ * `options.tracer`, and hands the SDK what the network gave.
+ */
+export declare function traceA2AFetch(base: typeof globalThis.fetch, options: A2ASpansOptions): typeof globalThis.fetch;