@datalayer/agent-runtimes 1.3.84 → 1.3.86

package/lib/components/inspector/agentSpans.js

@@ -0,0 +1,253 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What agents do in the page, as OpenTelemetry spans: the record the Agent
+ * Inspector reads. A turn is an `invoke_agent` span, each tool call an
+ * `execute_tool` span under it — the GenAI semantic conventions the runtime's
+ * own spans follow (pydantic-ai's): `gen_ai.operation.name`,
+ * `gen_ai.agent.name`, `gen_ai.request.model`, `gen_ai.tool.name`,
+ * `gen_ai.tool.call.id`, `gen_ai.tool.call.arguments` and `.result` (JSON
+ * text), `gen_ai.input.messages` and `gen_ai.output.messages`, the
+ * `gen_ai.usage.*` tokens. An agent is a service: `service.name` is its name.
+ *
+ * Where a tool comes from — an MCP server, the page (a frontend tool), a
+ * skill, codemode, the runtime — no convention says: `datalayer.tool.kind`
+ * does, beside `gen_ai.tool.type`, with the tool's marks
+ * (`datalayer.mark.icon`, `datalayer.mark.emoji`).
+ *
+ * The tracer is core's (`createOtelLiveTracer`): one a page, shared by its
+ * chats and its team (`AgentInspectorProvider`, or the `inspector` prop).
+ *
+ * @module components/inspector/agentSpans
+ */
+import { createContext, createElement, useContext, useState, } from 'react';
+import { createOtelLiveTracer, } from '@datalayer/core/lib/otel/live';
+/** The attributes the record uses: the GenAI conventions, and a few of Datalayer's. */
+export const AGENT_SPAN_ATTRIBUTES = {
+    operation: 'gen_ai.operation.name',
+    agentName: 'gen_ai.agent.name',
+    conversationId: 'gen_ai.conversation.id',
+    requestModel: 'gen_ai.request.model',
+    inputMessages: 'gen_ai.input.messages',
+    outputMessages: 'gen_ai.output.messages',
+    inputTokens: 'gen_ai.usage.input_tokens',
+    outputTokens: 'gen_ai.usage.output_tokens',
+    toolName: 'gen_ai.tool.name',
+    toolCallId: 'gen_ai.tool.call.id',
+    toolArguments: 'gen_ai.tool.call.arguments',
+    toolResult: 'gen_ai.tool.call.result',
+    toolType: 'gen_ai.tool.type',
+    /** `mcp`, `frontend`, `skill`, `codemode`, `runtime`. */
+    toolKind: 'datalayer.tool.kind',
+    markIcon: 'datalayer.mark.icon',
+    markEmoji: 'datalayer.mark.emoji',
+    /** How the page knows of a span another process did: `a2a.status`. */
+    origin: 'datalayer.span.origin',
+    errorType: 'error.type',
+};
+const A = AGENT_SPAN_ATTRIBUTES;
+/** Every kind, in the order the filters list them. */
+export const AGENT_TOOL_KINDS = [
+    'mcp',
+    'frontend',
+    'skill',
+    'codemode',
+    'runtime',
+];
+/** A value as an attribute carries it: JSON text. */
+export function jsonAttribute(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** 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;
+}
+/** 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);
+}
+/** A message in the GenAI conventions' shape: its role and its text part. */
+function messages(role, text) {
+    return JSON.stringify([{ role, parts: [{ type: 'text', content: text }] }]);
+}
+/** A turn of an agent: from the question to the answer. */
+export function startAgentTurn(tracer, turn) {
+    return tracer.startSpan(`invoke_agent ${turn.agent}`, {
+        serviceName: turn.agent,
+        parent: null,
+        attributes: {
+            [A.operation]: 'invoke_agent',
+            [A.agentName]: turn.agent,
+            [A.requestModel]: turn.model || undefined,
+            [A.conversationId]: turn.conversationId,
+            [A.inputMessages]: messages('user', turn.prompt),
+        },
+    });
+}
+/** End a turn: its answer, its tokens, or its error. */
+export function endAgentTurn(span, outcome) {
+    const usage = outcome.usage;
+    span.setAttributes({
+        [A.outputMessages]: outcome.text
+            ? messages('assistant', outcome.text)
+            : undefined,
+        [A.inputTokens]: usage?.inputTokens ?? usage?.promptTokens,
+        [A.outputTokens]: usage?.outputTokens ?? usage?.completionTokens,
+    });
+    if (outcome.error) {
+        span.setAttribute(A.errorType, 'error');
+        span.recordException(new Error(outcome.error));
+    }
+    else {
+        span.setStatus('OK');
+    }
+    span.end();
+}
+/** `gen_ai.tool.type` for a kind: an MCP server's tool is an extension. */
+function toolType(kind) {
+    return kind === 'mcp' ? 'extension' : 'function';
+}
+/** A tool call: its name, id, arguments, kind and marks. */
+export function startToolCall(tracer, call) {
+    return tracer.startSpan(`execute_tool ${call.name}`, {
+        serviceName: call.agent,
+        ...(call.parent ? { parent: call.parent } : {}),
+        attributes: {
+            [A.operation]: 'execute_tool',
+            [A.agentName]: call.agent,
+            [A.toolName]: call.name,
+            [A.toolCallId]: call.id,
+            [A.toolArguments]: jsonAttribute(call.args ?? {}),
+            [A.toolType]: toolType(call.tool.kind),
+            [A.toolKind]: call.tool.kind,
+            [A.markIcon]: call.tool.icon,
+            [A.markEmoji]: call.tool.emoji,
+            [A.origin]: call.origin,
+        },
+    });
+}
+/** End a tool call: its result, or its error. */
+export function endToolCall(span, outcome) {
+    span.setAttribute(A.toolResult, jsonAttribute(outcome.result));
+    if (outcome.error) {
+        span.setAttribute(A.errorType, 'tool_error');
+        span.recordException(new Error(outcome.error));
+    }
+    else {
+        span.setStatus('OK');
+    }
+    span.end();
+}
+/** Where a span comes from, for the Inspector's *Source* filter. */
+export function sourceOfSpan(span) {
+    const attributes = span.attributes ?? {};
+    if (attributes[A.toolKind]) {
+        return String(attributes[A.toolKind]);
+    }
+    if (attributes['rpc.service'] === 'a2a' ||
+        span.span_name.startsWith('a2a ')) {
+        return 'a2a';
+    }
+    if (attributes[A.operation] === 'invoke_agent') {
+        return 'model';
+    }
+    return undefined;
+}
+/** A source, in words. */
+export const SPAN_SOURCE_LABELS = {
+    a2a: 'A2A',
+    mcp: 'MCP',
+    frontend: 'Frontend tool',
+    skill: 'Skill',
+    codemode: 'Codemode',
+    runtime: 'Runtime tool',
+    model: 'Model',
+};
+/** The text of the first message of a GenAI messages attribute. */
+function messageText(value) {
+    if (typeof value !== 'string') {
+        return '';
+    }
+    try {
+        const parsed = JSON.parse(value);
+        return (parsed[0]?.parts ?? [])
+            .map(part => (typeof part.content === 'string' ? part.content : ''))
+            .join('');
+    }
+    catch {
+        return '';
+    }
+}
+/** One line that says what a span carried: a call's arguments, a turn's question and answer, a message's words. */
+export function describeAgentSpan(span) {
+    const attributes = span.attributes ?? {};
+    const operation = attributes[A.operation];
+    if (operation === 'execute_tool') {
+        let args;
+        try {
+            args = JSON.parse(String(attributes[A.toolArguments] ?? '{}'));
+        }
+        catch {
+            args = attributes[A.toolArguments];
+        }
+        return argumentsLine(args) || undefined;
+    }
+    if (operation === 'invoke_agent') {
+        const asked = messageText(attributes[A.inputMessages]);
+        const said = messageText(attributes[A.outputMessages]);
+        const input = Number(attributes[A.inputTokens] ?? 0);
+        const output = Number(attributes[A.outputTokens] ?? 0);
+        const tokens = input + output ? ` · ${input + output} tokens` : '';
+        return (shortLine(said ? `${shortLine(asked, 60)} → ${said}` : asked) + tokens);
+    }
+    const text = attributes['a2a.message.text'];
+    const state = attributes['a2a.task.state'];
+    const words = [
+        typeof state === 'string' ? stateWord(state) : '',
+        typeof text === 'string' ? shortLine(text) : '',
+    ].filter(Boolean);
+    if (words.length) {
+        return words.join(' · ');
+    }
+    const skills = attributes['a2a.agent.skills'];
+    return Array.isArray(skills) ? skills.join(', ') : undefined;
+}
+/** `TASK_STATE_WORKING` is `working`. */
+export function stateWord(state) {
+    return typeof state === 'string'
+        ? state
+            .replace(/^TASK_STATE_/, '')
+            .toLowerCase()
+            .replace(/_/g, ' ')
+        : '';
+}
+/** A tracer for a page, made once (or the one given). */
+export function useAgentInspector(given) {
+    const [own] = useState(() => given ?? createOtelLiveTracer({ serviceName: 'Agent' }));
+    return { tracer: given ?? own };
+}
+/** The tracer the chats under it record into. */
+export const AgentInspectorContext = createContext(null);
+/** The tracer of the nearest {@link AgentInspectorProvider}, if any. */
+export function useAgentInspectorTracer() {
+    return useContext(AgentInspectorContext);
+}
+/** Every chat under it records what its agent does into `tracer`. */
+export function AgentInspectorProvider({ tracer, children, }) {
+    return createElement(AgentInspectorContext.Provider, { value: tracer }, children);
+}

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

@@ -0,0 +1,36 @@
+/**
+ * A chat's agent, as OpenTelemetry spans: each turn an `invoke_agent` span
+ * (the prompt, the answer, the tokens), each tool call an `execute_tool` span
+ * under it from its start to its end — an MCP server's, a skill, a frontend
+ * tool the page runs, codemode's, 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/chatSpans
+ */
+import type { OtelLiveTracer } from '@datalayer/core/lib/otel/live';
+import type { MarkedMcpServer } from '../../chat/marks/toolMarks';
+import { type TurnUsage } from './agentSpans';
+export type ChatSpanRecorder = {
+    turnStarted: (prompt: string, model?: string) => void;
+    turnEnded: (outcome: {
+        text?: string;
+        usage?: TurnUsage;
+        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 (`agent`) into `tracer`. */
+export declare function chatSpanRecorder(tracer: OtelLiveTracer, agent: () => string, options?: {
+    /** The page's own tools, by name: frontend tools. */
+    frontendTools?: () => readonly string[];
+    mcpServers?: () => readonly MarkedMcpServer[];
+}): ChatSpanRecorder;

package/lib/components/inspector/chatSpans.js

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { endAgentTurn, endToolCall, startAgentTurn, startToolCall, } from './agentSpans';
+import { classifyToolCall } from './classify';
+/** A recorder for one chat's agent (`agent`) into `tracer`. */
+export function chatSpanRecorder(tracer, agent, options = {}) {
+    let turn;
+    const tools = new Map();
+    return {
+        turnStarted(prompt, model) {
+            turn = startAgentTurn(tracer, { agent: agent(), prompt, model });
+        },
+        turnEnded(outcome) {
+            if (!turn) {
+                return;
+            }
+            endAgentTurn(turn, outcome);
+            turn = undefined;
+        },
+        toolStarted({ id, name, args }) {
+            const known = tools.get(id);
+            if (known) {
+                // Arguments that stream in: the latest whole.
+                known.setAttribute('gen_ai.tool.call.arguments', JSON.stringify(args ?? {}));
+                return;
+            }
+            tools.set(id, startToolCall(tracer, {
+                agent: agent(),
+                name,
+                id,
+                args,
+                tool: classifyToolCall(name, args, {
+                    frontendTools: options.frontendTools?.(),
+                    mcpServers: options.mcpServers?.(),
+                }),
+                ...(turn ? { parent: turn.context } : {}),
+            }));
+        },
+        toolEnded(id, outcome) {
+            const span = tools.get(id);
+            if (!span) {
+                return;
+            }
+            tools.delete(id);
+            endToolCall(span, outcome);
+        },
+    };
+}

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

@@ -1,19 +1,22 @@
 /**
- * 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.
+ * Where a tool call comes from, for its span (`datalayer.tool.kind`), by
+ * what the catalogue says of its name. Apart from the spans themselves,
+ * which a page can record without loading the catalogues.
  *
  * @module components/inspector/classify
  */
 import { type MarkedMcpServer } from '../../chat/marks/toolMarks';
-import type { AgentInspectorSource, ToolClass } from './agentInspector';
+import type { AgentToolKind, ToolClass } from './agentSpans';
+/** The tools codemode exposes in place of the MCP tools it reaches. */
+export declare const CODEMODE_TOOLS: ReadonlySet<string>;
 /**
- * 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.
+ * Where a tool call comes from, by who claims its name: a frontend tool
+ * (one of `frontendTools`), a skill, one of `mcpServers`, a frontend tool of
+ * the catalogue, a runtime tool, codemode's; 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;
+    fallback?: AgentToolKind;
 }): ToolClass;

package/lib/components/inspector/classify.js

@@ -3,39 +3,38 @@
  * 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.
+ * Where a tool call comes from, for its span (`datalayer.tool.kind`), by
+ * what the catalogue says of its name. Apart from the spans themselves,
+ * which a page can record without loading the catalogues.
  *
  * @module components/inspector/classify
  */
 import { marksOfToolCall, } from '../../chat/marks/toolMarks';
+/** The tools codemode exposes in place of the MCP tools it reaches. */
+export const CODEMODE_TOOLS = new Set([
+    'list_servers',
+    'list_tool_names',
+    'search_tools',
+    'get_tool_details',
+    'execute_code',
+]);
 /**
- * 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.
+ * Where a tool call comes from, by who claims its name: a frontend tool
+ * (one of `frontendTools`), a skill, one of `mcpServers`, a frontend tool of
+ * the catalogue, a runtime tool, codemode's; 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');
+    const kind = options.frontendTools?.includes(name)
+        ? 'frontend'
+        : marks?.kind
+            ? marks.kind
+            : CODEMODE_TOOLS.has(name)
+                ? 'codemode'
+                : (options.fallback ?? 'runtime');
     return {
-        source,
+        kind,
         ...(marks?.icon ? { icon: marks.icon } : {}),
         ...(marks?.emoji ? { emoji: marks.emoji } : {}),
     };

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

@@ -1,14 +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.
+ * The Agent Inspector: what agents do — model turns, tool calls (MCP,
+ * frontend, skills, codemode, runtime), A2A requests and what came back —
+ * recorded as OpenTelemetry spans in the page's tracer (core's
+ * `createOtelLiveTracer`) and drawn by core's OTEL view (`OtelLiveSpans`).
  *
  * @module components/inspector
  */
-export * from './agentInspector';
+export * from './agentSpans';
 export * from './classify';
-export * from './chatInspect';
-export * from './a2aInspect';
-export * from './JsonTree';
+export * from './chatSpans';
+export * from './a2aSpans';
 export * from './AgentInspector';
 export * from './AgentInspectorDialog';

package/lib/components/inspector/index.js

@@ -3,16 +3,16 @@
  * 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.
+ * The Agent Inspector: what agents do — model turns, tool calls (MCP,
+ * frontend, skills, codemode, runtime), A2A requests and what came back —
+ * recorded as OpenTelemetry spans in the page's tracer (core's
+ * `createOtelLiveTracer`) and drawn by core's OTEL view (`OtelLiveSpans`).
  *
  * @module components/inspector
  */
-export * from './agentInspector';
+export * from './agentSpans';
 export * from './classify';
-export * from './chatInspect';
-export * from './a2aInspect';
-export * from './JsonTree';
+export * from './chatSpans';
+export * from './a2aSpans';
 export * from './AgentInspector';
 export * from './AgentInspectorDialog';