@datalayer/agent-runtimes 1.3.83 → 1.3.85

package/lib/components/inspector/a2aInspect.js

@@ -1,478 +0,0 @@
-/*
- * Copyright (c) 2025-2026 Datalayer, Inc.
- * Distributed under the terms of the Modified BSD License.
- */
-import { argumentsLine, formatBytes, jsonBytes, shortLine, } from './agentInspector';
-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('')
-        : '';
-}
-/** `TASK_STATE_WORKING` is `working`. */
-export function stateWord(state) {
-    return typeof state === 'string'
-        ? state
-            .replace(/^TASK_STATE_/, '')
-            .toLowerCase()
-            .replace(/_/g, ' ')
-        : '';
-}
-/** 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;
-    }
-}
-/** What a request asks, in a line. */
-function requestSummary(method, params) {
-    const message = isObject(params) ? params.message : undefined;
-    const text = isObject(message) ? partsText(message.parts) : '';
-    if (text) {
-        return shortLine(text);
-    }
-    if (isObject(params) && typeof params.id === 'string') {
-        return `${method} ${params.id}`;
-    }
-    return method;
-}
-/** 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) } : {}),
-                ...(typeof told.note === 'string' && told.note
-                    ? { note: told.note }
-                    : {}),
-            };
-        }
-    }
-    return undefined;
-}
-/** Records the stream of one request, event by event. */
-class StreamRecorder {
-    options;
-    method;
-    rpcId;
-    /** The entry of each artifact being streamed, by its id. */
-    artifacts = new Map();
-    constructor(options, method, rpcId) {
-        this.options = options;
-        this.method = method;
-        this.rpcId = rpcId;
-    }
-    classify(name, args) {
-        return (this.options.classifyTool?.(name, args) ?? { source: 'backend-tool' });
-    }
-    /** One JSON-RPC message of the response: a response, or an event of a stream. */
-    record(message, streamed) {
-        const { sink, asker, peer } = this.options;
-        const direction = { from: peer, to: asker };
-        const base = { actor: peer, source: 'a2a', direction };
-        if (!isObject(message)) {
-            return;
-        }
-        if (isObject(message.error)) {
-            const error = message.error;
-            sink.push({
-                ...base,
-                kind: 'error',
-                name: this.method,
-                status: 'failed',
-                summary: shortLine(`${String(error.code ?? '')} ${String(error.message ?? '')}`),
-                error: String(error.message ?? ''),
-                a2a: { method: this.method, rpcId: this.rpcId },
-                payload: message,
-            });
-            return;
-        }
-        const result = isObject(message.result) ? message.result : undefined;
-        if (!result) {
-            sink.push({
-                ...base,
-                kind: 'response',
-                name: this.method,
-                summary: this.method,
-                a2a: { method: this.method, rpcId: this.rpcId },
-                payload: message,
-            });
-            return;
-        }
-        const a2a = { method: this.method, rpcId: this.rpcId };
-        if (isObject(result.task)) {
-            const task = result.task;
-            const status = isObject(task.status) ? task.status : {};
-            sink.push({
-                ...base,
-                kind: 'task',
-                summary: `Task ${stateWord(status.state)}`,
-                a2a: {
-                    ...a2a,
-                    taskId: String(task.id ?? ''),
-                    contextId: String(task.contextId ?? ''),
-                    state: String(status.state ?? ''),
-                },
-                payload: message,
-            });
-        }
-        else if (isObject(result.statusUpdate)) {
-            this.status(result.statusUpdate, message, a2a);
-        }
-        else if (isObject(result.artifactUpdate)) {
-            this.artifact(result.artifactUpdate, message, a2a);
-        }
-        else if (isObject(result.message)) {
-            const reply = result.message;
-            sink.push({
-                ...base,
-                kind: 'message',
-                summary: shortLine(partsText(reply.parts)) || 'A message',
-                a2a: {
-                    ...a2a,
-                    taskId: String(reply.taskId ?? ''),
-                    contextId: String(reply.contextId ?? ''),
-                },
-                payload: message,
-            });
-        }
-        else {
-            sink.push({
-                ...base,
-                kind: streamed ? 'event' : 'response',
-                summary: this.method,
-                a2a,
-                payload: message,
-            });
-        }
-    }
-    status(update, message, a2a) {
-        const { sink, asker, peer } = this.options;
-        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);
-        const summary = step
-            ? step.ended
-                ? `${stateWord(state)} · ${step.error ? `${step.name} failed` : `${step.name} returned`}`
-                : `${stateWord(state)} · calls ${step.name}(${argumentsLine(step.args)})`
-            : `${stateWord(state)}${text ? ` · ${shortLine(text)}` : ''}`;
-        const failed = /FAILED|REJECTED|CANCELED/.test(state);
-        const id = sink.push({
-            actor: peer,
-            source: 'a2a',
-            direction: { from: peer, to: asker },
-            kind: 'status-update',
-            summary,
-            ...(failed ? { status: 'failed' } : {}),
-            a2a: {
-                ...a2a,
-                taskId,
-                contextId: String(update.contextId ?? ''),
-                state,
-                ...(step
-                    ? {
-                        step: { toolId: step.toolId, name: step.name, ended: step.ended },
-                    }
-                    : {}),
-            },
-            payload: message,
-        });
-        if (!step) {
-            return;
-        }
-        // The call, as one entry of its own, the peer's: from its start to its end.
-        const key = `a2a:${taskId}:${step.toolId ?? step.name}`;
-        if (!step.ended) {
-            const kind = this.classify(step.name, step.args);
-            sink.start({
-                key,
-                actor: peer,
-                source: kind.source,
-                ...(kind.icon ? { icon: kind.icon } : {}),
-                ...(kind.emoji ? { emoji: kind.emoji } : {}),
-                kind: 'tool-call',
-                name: step.name,
-                summary: step.note ?? argumentsLine(step.args),
-                payload: step.args ?? {},
-                links: [id],
-            });
-        }
-        else if (sink.running(key)) {
-            sink.end(key, {
-                status: step.error ? 'failed' : 'done',
-                result: step.result,
-                ...(step.error ? { error: step.error } : {}),
-                links: [id],
-            });
-        }
-    }
-    artifact(update, message, a2a) {
-        const { sink, asker, peer } = this.options;
-        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);
-        if (known && update.append && !update.lastChunk) {
-            // A chunk of an artifact being streamed: one entry, its text growing.
-            known.text += text;
-            known.events.push(message);
-            const chunks = known.events.length;
-            const words = known.text;
-            sink.update(known.id, entry => ({
-                summary: `${String(artifact.name ?? 'artifact')} · ${shortLine(words)}`,
-                payload: [...known.events],
-                a2a: { ...entry.a2a, chunks },
-            }));
-            return;
-        }
-        const name = String(artifact.name ?? (artifactId || 'artifact'));
-        const summary = media
-            ? `${name} · ${String(media)}, ${formatBytes(jsonBytes(message))}`
-            : `${name} · ${shortLine(text)}`;
-        const id = sink.push({
-            actor: peer,
-            source: 'a2a',
-            direction: { from: peer, to: asker },
-            kind: 'artifact-update',
-            name,
-            summary,
-            a2a: {
-                ...a2a,
-                taskId: String(update.taskId ?? ''),
-                contextId: String(update.contextId ?? ''),
-                artifactId,
-                chunks: 1,
-            },
-            payload: message,
-        });
-        if (update.append && !update.lastChunk) {
-            this.artifacts.set(artifactId, { id, text, events: [message] });
-        }
-        else {
-            this.artifacts.delete(artifactId);
-        }
-    }
-}
-/** 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 into `options.sink`, and
- * hands the SDK what the network gave.
- */
-export function inspectA2AFetch(base, options) {
-    const { sink, asker, peer } = options;
-    // What the asker makes of the events (`A2APeerEvent`) is linked to them.
-    sink.addLinker(a2aEventLinker);
-    return async (input, init) => {
-        const rpc = rpcOf(init?.body);
-        const method = rpc ? String(rpc.method ?? '') : '';
-        const rpcId = rpc ? rpc.id : undefined;
-        const url = typeof input === 'string'
-            ? input
-            : input instanceof URL
-                ? input.href
-                : input.url;
-        if (rpc) {
-            sink.push({
-                actor: asker,
-                source: 'a2a',
-                direction: { from: asker, to: peer },
-                kind: 'request',
-                name: method,
-                summary: requestSummary(method, rpc.params),
-                a2a: { method, rpcId },
-                payload: rpc,
-            });
-        }
-        let response;
-        try {
-            response = await base(input, init);
-        }
-        catch (reason) {
-            sink.push({
-                actor: asker,
-                source: 'a2a',
-                direction: { from: asker, to: peer },
-                kind: 'error',
-                name: method || undefined,
-                status: 'failed',
-                summary: shortLine(`${method || url}: ${reason instanceof Error ? reason.message : String(reason)}`),
-                error: reason instanceof Error ? reason.message : String(reason),
-                a2a: { method, rpcId },
-            });
-            throw reason;
-        }
-        const type = response.headers.get('content-type') ?? '';
-        const recorder = new StreamRecorder(options, method, rpcId);
-        if (!response.ok) {
-            const copy = response.clone();
-            void copy.text().then(text => sink.push({
-                actor: peer,
-                source: 'a2a',
-                direction: { from: peer, to: asker },
-                kind: 'error',
-                name: method || undefined,
-                status: 'failed',
-                summary: shortLine(`${response.status} ${response.statusText} ${text}`),
-                error: `${response.status} ${response.statusText}`,
-                a2a: { method, rpcId },
-                payload: { status: response.status, body: text },
-            }));
-            return response;
-        }
-        if (type.includes('text/event-stream') && response.body) {
-            const [mine, theirs] = response.body.tee();
-            void readEvents(mine, data => recorder.record(data, true)).catch(() => undefined);
-            return new Response(theirs, {
-                status: response.status,
-                statusText: response.statusText,
-                headers: response.headers,
-            });
-        }
-        if (type.includes('json')) {
-            const copy = response.clone();
-            void copy
-                .json()
-                .then(data => {
-                if (rpc) {
-                    recorder.record(data, false);
-                }
-                else if (isObject(data) && Array.isArray(data.skills)) {
-                    // The agent card.
-                    sink.push({
-                        actor: peer,
-                        source: 'a2a',
-                        direction: { from: peer, to: asker },
-                        kind: 'agent-card',
-                        name: String(data.name ?? peer),
-                        summary: shortLine(`${String(data.name ?? peer)} · ${data.skills
-                            .map(skill => isObject(skill) ? String(skill.name ?? skill.id) : '')
-                            .join(', ')}`),
-                        payload: data,
-                    });
-                }
-            })
-                .catch(() => undefined);
-        }
-        return response;
-    };
-}
-/** The entry an event of the asker's came from. */
-function matchOf(event) {
-    switch (event.phase) {
-        case 'asked':
-            return entry => entry.source === 'a2a' &&
-                entry.kind === 'request' &&
-                /Message/.test(entry.a2a?.method ?? '') &&
-                entry.events.length === 0;
-        case 'working':
-            if (event.tool) {
-                const tool = event.tool;
-                return entry => entry.kind === 'status-update' &&
-                    entry.a2a?.taskId === event.taskId &&
-                    entry.a2a?.step?.name === tool.name &&
-                    entry.a2a?.step?.ended === tool.ended &&
-                    (tool.id === undefined || entry.a2a?.step?.toolId === tool.id);
-            }
-            if (event.note) {
-                return entry => entry.kind === 'status-update' &&
-                    entry.a2a?.taskId === event.taskId &&
-                    !entry.a2a?.step &&
-                    entry.events.length === 0;
-            }
-            return entry => (entry.kind === 'task' || entry.kind === 'status-update') &&
-                entry.a2a?.taskId === event.taskId &&
-                entry.events.length === 0;
-        case 'answered':
-            return entry => entry.kind === 'status-update' &&
-                entry.a2a?.taskId === event.taskId &&
-                entry.a2a?.state === 'TASK_STATE_COMPLETED';
-        default:
-            return entry => entry.source === 'a2a' && entry.direction?.to !== undefined;
-    }
-}
-/** Whether a value is an `A2APeerEvent`. */
-function isPeerEvent(event) {
-    return (isObject(event) &&
-        ['asked', 'working', 'answered', 'failed'].includes(String(event.phase)));
-}
-/**
- * The linker the A2A capture adds to its sink: an `A2APeerEvent` noted
- * (`sink.note`) is attached to the entry it came from.
- */
-export function a2aEventLinker(event) {
-    return isPeerEvent(event) ? matchOf(event) : undefined;
-}
-/** Attach what the asker made of an event to the A2A entry it came from. */
-export function linkA2APeerEvent(sink, event) {
-    sink.attach(matchOf(event), event);
-}

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

@@ -1,179 +0,0 @@
-/**
- * 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;