@datalayer/agent-runtimes 1.3.84 → 1.3.86

package/lib/components/inspector/a2aSpans.js

@@ -0,0 +1,373 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { endToolCall, jsonAttribute, shortLine, startToolCall, } from './agentSpans';
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The text of an A2A 1.0 message's or artifact's parts, as JSON carries them. */
+export function partsText(parts) {
+    return Array.isArray(parts)
+        ? parts
+            .map(part => isObject(part) && typeof part.text === 'string' ? part.text : '')
+            .join('')
+        : '';
+}
+/** A JSON-RPC request's body, if the request carries one. */
+function rpcOf(body) {
+    if (typeof body !== 'string') {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(body);
+        return isObject(parsed) && parsed.jsonrpc === '2.0' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The step a status message carries: a tool call or its end. */
+function stepOf(message) {
+    if (!isObject(message) || !Array.isArray(message.parts)) {
+        return undefined;
+    }
+    for (const part of message.parts) {
+        const data = isObject(part) ? part.data : undefined;
+        if (!isObject(data)) {
+            continue;
+        }
+        const call = isObject(data.tool_call) ? data.tool_call : undefined;
+        const done = isObject(data.tool_result) ? data.tool_result : undefined;
+        const told = call ?? done;
+        if (told && typeof told.name === 'string') {
+            return {
+                ...(typeof told.id === 'string' ? { toolId: told.id } : {}),
+                name: told.name,
+                ended: !call,
+                ...(call && isObject(call.arguments)
+                    ? { args: call.arguments }
+                    : {}),
+                ...(done && 'result' in done ? { result: done.result } : {}),
+                ...(done && done.error ? { error: String(done.error) } : {}),
+            };
+        }
+    }
+    return undefined;
+}
+const FAILED_STATES = /FAILED|REJECTED|CANCELED/;
+/** Records what came back for one request onto its span. */
+class ResponseRecorder {
+    options;
+    span;
+    /** The chunks of each artifact being streamed, by its id. */
+    artifacts = new Map();
+    /** The peer's tool calls still open, by task and call. */
+    calls = new Map();
+    constructor(options, span) {
+        this.options = options;
+        this.span = span;
+    }
+    /** One JSON-RPC message of the response: a response, or an event of a stream. */
+    record(message, streamed) {
+        if (!isObject(message)) {
+            return;
+        }
+        const whole = { 'a2a.event': jsonAttribute(message) };
+        if (isObject(message.error)) {
+            const error = message.error;
+            const words = `${String(error.code ?? '')} ${String(error.message ?? '')}`.trim();
+            this.span.addEvent('a2a.error', { ...whole, 'a2a.error': words });
+            this.span.setStatus('ERROR', words);
+            return;
+        }
+        const result = isObject(message.result) ? message.result : undefined;
+        if (!result) {
+            this.span.addEvent('a2a.response', whole);
+            return;
+        }
+        if (isObject(result.task)) {
+            const task = result.task;
+            const status = isObject(task.status) ? task.status : {};
+            this.task(String(task.id ?? ''), String(task.contextId ?? ''), String(status.state ?? ''));
+            this.span.addEvent('a2a.task', {
+                ...whole,
+                'a2a.task.id': String(task.id ?? ''),
+                'a2a.context.id': String(task.contextId ?? ''),
+                'a2a.task.state': String(status.state ?? ''),
+            });
+        }
+        else if (isObject(result.statusUpdate)) {
+            this.status(result.statusUpdate, whole);
+        }
+        else if (isObject(result.artifactUpdate)) {
+            this.artifact(result.artifactUpdate, message);
+        }
+        else if (isObject(result.message)) {
+            const reply = result.message;
+            const text = partsText(reply.parts);
+            this.span.addEvent('a2a.message', {
+                ...whole,
+                'a2a.task.id': String(reply.taskId ?? ''),
+                'a2a.context.id': String(reply.contextId ?? ''),
+                'a2a.message.text': text,
+            });
+            this.span.setAttribute('a2a.answer.text', text || undefined);
+        }
+        else {
+            this.span.addEvent(streamed ? 'a2a.event' : 'a2a.response', whole);
+        }
+    }
+    /** The task the span is about, and its latest state. */
+    task(taskId, contextId, state) {
+        this.span.setAttributes({
+            'a2a.task.id': taskId || undefined,
+            'a2a.context.id': contextId || undefined,
+            'a2a.task.state': state || undefined,
+        });
+        if (FAILED_STATES.test(state)) {
+            this.span.setStatus('ERROR', state);
+        }
+    }
+    status(update, whole) {
+        const status = isObject(update.status) ? update.status : {};
+        const taskId = String(update.taskId ?? '');
+        const state = String(status.state ?? '');
+        const step = stepOf(status.message);
+        const text = partsText(isObject(status.message) ? status.message.parts : undefined);
+        this.task(taskId, String(update.contextId ?? ''), state);
+        this.span.addEvent('a2a.status_update', {
+            ...whole,
+            'a2a.task.id': taskId,
+            'a2a.context.id': String(update.contextId ?? ''),
+            'a2a.task.state': state,
+            'a2a.message.text': text || undefined,
+            'gen_ai.tool.name': step?.name,
+            'gen_ai.tool.call.id': step?.toolId,
+        });
+        if (!step) {
+            return;
+        }
+        // The call, as a span of the peer's: from its start to its end.
+        const key = `${taskId}:${step.toolId ?? step.name}`;
+        if (!step.ended) {
+            if (this.calls.has(key)) {
+                return;
+            }
+            const { peer, classifyTool } = this.options;
+            this.calls.set(key, startToolCall(this.options.tracer, {
+                agent: peer,
+                name: step.name,
+                id: step.toolId,
+                args: step.args ?? {},
+                tool: classifyTool?.(step.name, step.args) ?? { kind: 'runtime' },
+                parent: this.span.context,
+                origin: 'a2a.status',
+            }));
+            return;
+        }
+        const call = this.calls.get(key);
+        if (call) {
+            this.calls.delete(key);
+            endToolCall(call, { result: step.result, error: step.error });
+        }
+    }
+    artifact(update, message) {
+        const artifact = isObject(update.artifact) ? update.artifact : {};
+        const artifactId = String(artifact.artifactId ?? '');
+        const text = partsText(artifact.parts);
+        const parts = Array.isArray(artifact.parts) ? artifact.parts : [];
+        const media = parts
+            .map(part => (isObject(part) ? part.mediaType : undefined))
+            .find(type => typeof type === 'string' && type && !type.startsWith('text/'));
+        const known = this.artifacts.get(artifactId);
+        const chunk = known ?? {
+            name: String(artifact.name ?? (artifactId || 'artifact')),
+            text: '',
+            events: [],
+            attributes: {
+                'a2a.task.id': String(update.taskId ?? ''),
+                'a2a.context.id': String(update.contextId ?? ''),
+                'a2a.artifact.id': artifactId,
+                'a2a.artifact.name': String(artifact.name ?? (artifactId || 'artifact')),
+                'a2a.artifact.media_type': typeof media === 'string' ? media : undefined,
+            },
+        };
+        chunk.text += text;
+        chunk.events.push(message);
+        if (update.append && !update.lastChunk) {
+            // A chunk of an artifact being streamed: one event once it is whole.
+            this.artifacts.set(artifactId, chunk);
+            return;
+        }
+        this.artifacts.delete(artifactId);
+        this.emitArtifact(chunk);
+    }
+    emitArtifact(chunk) {
+        this.span.addEvent('a2a.artifact_update', {
+            ...chunk.attributes,
+            'a2a.artifact.chunks': chunk.events.length,
+            'a2a.message.text': chunk.text ? shortLine(chunk.text, 2000) : undefined,
+            'a2a.event': jsonAttribute(chunk.events.length === 1 ? chunk.events[0] : chunk.events),
+        });
+    }
+    /** The response is over: what is still open is closed with it. */
+    finish(error) {
+        for (const chunk of this.artifacts.values()) {
+            this.emitArtifact(chunk);
+        }
+        this.artifacts.clear();
+        for (const call of this.calls.values()) {
+            call.end();
+        }
+        this.calls.clear();
+        if (error !== undefined) {
+            this.span.recordException(error);
+        }
+        this.span.end();
+    }
+}
+/** The JSON of each event of a server-sent stream, as it arrives. */
+async function readEvents(body, onEvent) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    const flush = (block) => {
+        const data = block
+            .split(/\r?\n/)
+            .filter(line => line.startsWith('data:'))
+            .map(line => line.slice(5).replace(/^ /, ''))
+            .join('\n');
+        if (!data) {
+            return;
+        }
+        try {
+            onEvent(JSON.parse(data));
+        }
+        catch {
+            onEvent({ unparsed: data });
+        }
+    };
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        buffer += decoder.decode(value, { stream: true });
+        let at;
+        while ((at = buffer.search(/\r?\n\r?\n/)) >= 0) {
+            const block = buffer.slice(0, at);
+            buffer = buffer.slice(at).replace(/^\r?\n\r?\n/, '');
+            flush(block);
+        }
+    }
+    if (buffer.trim()) {
+        flush(buffer);
+    }
+}
+/**
+ * A fetch that records the A2A traffic it carries as spans into
+ * `options.tracer`, and hands the SDK what the network gave.
+ */
+export function traceA2AFetch(base, options) {
+    const { tracer, asker, peer } = options;
+    return async (input, init) => {
+        const rpc = rpcOf(init?.body);
+        const method = rpc ? String(rpc.method ?? '') : '';
+        const url = typeof input === 'string'
+            ? input
+            : input instanceof URL
+                ? input.href
+                : input.url;
+        const httpMethod = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+        let path = url;
+        try {
+            path = new URL(url, globalThis.location?.href).pathname;
+        }
+        catch {
+            // A URL the page cannot read: said whole.
+        }
+        const params = rpc && isObject(rpc.params) ? rpc.params : undefined;
+        const message = params && isObject(params.message) ? params.message : undefined;
+        const span = tracer.startSpan(rpc ? `a2a ${method}` : `${httpMethod} ${path}`, {
+            serviceName: asker,
+            kind: 'CLIENT',
+            attributes: {
+                'peer.service': peer,
+                'url.full': url,
+                'http.request.method': httpMethod,
+                ...(rpc
+                    ? {
+                        'rpc.system': 'jsonrpc',
+                        'rpc.service': 'a2a',
+                        'rpc.method': method,
+                        'rpc.jsonrpc.version': '2.0',
+                        'rpc.jsonrpc.request_id': rpc.id === undefined ? undefined : String(rpc.id),
+                        'a2a.request': jsonAttribute(rpc),
+                        'a2a.message.text': message
+                            ? partsText(message.parts) || undefined
+                            : undefined,
+                        'a2a.task.id': typeof params?.id === 'string' ? params.id : undefined,
+                    }
+                    : {}),
+            },
+        });
+        const recorder = new ResponseRecorder(options, span);
+        let response;
+        try {
+            response = await base(input, init);
+        }
+        catch (reason) {
+            recorder.finish(reason);
+            throw reason;
+        }
+        span.setAttribute('http.response.status_code', response.status);
+        const type = response.headers.get('content-type') ?? '';
+        if (!response.ok) {
+            void response
+                .clone()
+                .text()
+                .then(text => {
+                span.setAttribute('a2a.error', shortLine(text, 2000) || undefined);
+                span.setAttribute('error.type', String(response.status));
+                recorder.finish(new Error(`${response.status} ${response.statusText}`.trim()));
+            })
+                .catch(reason => recorder.finish(reason));
+            return response;
+        }
+        if (type.includes('text/event-stream') && response.body) {
+            const [mine, theirs] = response.body.tee();
+            void readEvents(mine, data => recorder.record(data, true))
+                .then(() => recorder.finish())
+                .catch(reason => recorder.finish(reason));
+            return new Response(theirs, {
+                status: response.status,
+                statusText: response.statusText,
+                headers: response.headers,
+            });
+        }
+        if (type.includes('json')) {
+            void response
+                .clone()
+                .json()
+                .then(data => {
+                if (rpc) {
+                    recorder.record(data, false);
+                }
+                else if (isObject(data) && Array.isArray(data.skills)) {
+                    // The agent card.
+                    span.updateName('a2a agent card');
+                    span.setAttributes({
+                        'rpc.service': 'a2a',
+                        'a2a.agent.name': String(data.name ?? peer),
+                        'a2a.agent.skills': data.skills.map(skill => isObject(skill) ? String(skill.name ?? skill.id) : ''),
+                        'a2a.agent_card': jsonAttribute(data),
+                    });
+                }
+                recorder.finish();
+            })
+                .catch(reason => recorder.finish(reason));
+            return response;
+        }
+        recorder.finish();
+        return response;
+    };
+}

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

@@ -0,0 +1,120 @@
+/**
+ * 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 { type JSX, type ReactNode } from 'react';
+import { type OtelLiveSpan, type OtelLiveTracer, type OtelSpanContext } from '@datalayer/core/lib/otel/live';
+import type { OtelSpan } from '@datalayer/core/lib/otel/types';
+/** The attributes the record uses: the GenAI conventions, and a few of Datalayer's. */
+export declare const AGENT_SPAN_ATTRIBUTES: {
+    readonly operation: "gen_ai.operation.name";
+    readonly agentName: "gen_ai.agent.name";
+    readonly conversationId: "gen_ai.conversation.id";
+    readonly requestModel: "gen_ai.request.model";
+    readonly inputMessages: "gen_ai.input.messages";
+    readonly outputMessages: "gen_ai.output.messages";
+    readonly inputTokens: "gen_ai.usage.input_tokens";
+    readonly outputTokens: "gen_ai.usage.output_tokens";
+    readonly toolName: "gen_ai.tool.name";
+    readonly toolCallId: "gen_ai.tool.call.id";
+    readonly toolArguments: "gen_ai.tool.call.arguments";
+    readonly toolResult: "gen_ai.tool.call.result";
+    readonly toolType: "gen_ai.tool.type";
+    /** `mcp`, `frontend`, `skill`, `codemode`, `runtime`. */
+    readonly toolKind: "datalayer.tool.kind";
+    readonly markIcon: "datalayer.mark.icon";
+    readonly markEmoji: "datalayer.mark.emoji";
+    /** How the page knows of a span another process did: `a2a.status`. */
+    readonly origin: "datalayer.span.origin";
+    readonly errorType: "error.type";
+};
+/** Where a tool call comes from. */
+export type AgentToolKind = 'mcp' | 'frontend' | 'skill' | 'codemode' | 'runtime';
+/** Every kind, in the order the filters list them. */
+export declare const AGENT_TOOL_KINDS: readonly AgentToolKind[];
+/** What a tool call is: where it comes from, and its marks. */
+export type ToolClass = {
+    kind: AgentToolKind;
+    icon?: string;
+    emoji?: string;
+};
+/** A value as an attribute carries it: JSON text. */
+export declare function jsonAttribute(value: unknown): string | undefined;
+/** A line short enough for a row. */
+export declare function shortLine(text: string, length?: number): string;
+/** A call's arguments, in a few words: `kind=customer, limit=100`. */
+export declare function argumentsLine(args: unknown, length?: number): string;
+/** A turn of an agent: from the question to the answer. */
+export declare function startAgentTurn(tracer: OtelLiveTracer, turn: {
+    agent: string;
+    prompt: string;
+    model?: string;
+    conversationId?: string;
+}): OtelLiveSpan;
+/** Token counts, as the AI SDK and the chats say them. */
+export type TurnUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    promptTokens?: number;
+    completionTokens?: number;
+};
+/** End a turn: its answer, its tokens, or its error. */
+export declare function endAgentTurn(span: OtelLiveSpan, outcome: {
+    text?: string;
+    usage?: TurnUsage;
+    error?: string;
+}): void;
+/** A tool call: its name, id, arguments, kind and marks. */
+export declare function startToolCall(tracer: OtelLiveTracer, call: {
+    agent: string;
+    name: string;
+    id?: string;
+    args?: unknown;
+    tool: ToolClass;
+    /** The span it is part of: the agent's innermost open span unless said. */
+    parent?: OtelSpanContext;
+    /** How the page knows of it, when another process made it. */
+    origin?: string;
+}): OtelLiveSpan;
+/** End a tool call: its result, or its error. */
+export declare function endToolCall(span: OtelLiveSpan, outcome: {
+    result?: unknown;
+    error?: string;
+}): void;
+/** Where a span comes from, for the Inspector's *Source* filter. */
+export declare function sourceOfSpan(span: OtelSpan): string | undefined;
+/** A source, in words. */
+export declare const SPAN_SOURCE_LABELS: Record<string, string>;
+/** One line that says what a span carried: a call's arguments, a turn's question and answer, a message's words. */
+export declare function describeAgentSpan(span: OtelSpan): string | undefined;
+/** `TASK_STATE_WORKING` is `working`. */
+export declare function stateWord(state: unknown): string;
+/** A tracer for a page, made once (or the one given). */
+export declare function useAgentInspector(given?: OtelLiveTracer | null): {
+    tracer: OtelLiveTracer;
+};
+/** The tracer the chats under it record into. */
+export declare const AgentInspectorContext: import("react").Context<OtelLiveTracer | null>;
+/** The tracer of the nearest {@link AgentInspectorProvider}, if any. */
+export declare function useAgentInspectorTracer(): OtelLiveTracer | null;
+/** Every chat under it records what its agent does into `tracer`. */
+export declare function AgentInspectorProvider({ tracer, children, }: {
+    tracer: OtelLiveTracer;
+    children?: ReactNode;
+}): JSX.Element;