@datalayer/agent-runtimes 1.3.84 → 1.3.86

package/lib/components/teams/sceneTranscript.js

@@ -0,0 +1,294 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { connectionOfTool } from './a2aTeamFlow';
+/** The person in the scene, as the transcript names them. */
+export const PERSON = 'You';
+/** What a tool that is no connection's reaches, by where it comes from. */
+const TOOL_HOMES = {
+    frontend: 'the page',
+    skill: 'a skill',
+    codemode: 'codemode',
+    runtime: 'its runtime',
+};
+const text = (value) => typeof value === 'string' ? value : '';
+/** The text of the first message of a GenAI messages attribute (JSON). */
+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('')
+            .trim();
+    }
+    catch {
+        return '';
+    }
+}
+/** A time as the span writes it, in milliseconds. */
+function millis(iso, fallback = 0) {
+    const parsed = iso ? Date.parse(iso) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+/** The member a service name is: by name, then by id; else the name itself. */
+function memberNamed(service, members) {
+    return (members.find(member => member.name === service) ??
+        members.find(member => member.id === service) ?? {
+        id: service,
+        name: service,
+    });
+}
+/** Where a tool call goes: the connection it is of (`Odoo`), else its home by kind. */
+function calledOf(tool, kind, member) {
+    const connection = connectionOfTool(tool, [...(member.connections ?? [])]);
+    return connection?.label ?? TOOL_HOMES[kind] ?? TOOL_HOMES.runtime;
+}
+const isA2A = (span, attributes) => attributes['rpc.service'] === 'a2a' || span.span_name.startsWith('a2a ');
+/** The lines in the order they happened: by time, a tie kept as given. */
+function inOrder(lines) {
+    return lines
+        .map((line, index) => ({ line, index }))
+        .sort((a, b) => a.line.at - b.line.at || a.index - b.index)
+        .map(({ line }) => line);
+}
+/**
+ * The same thing said twice is said once: a member's answer comes back as
+ * the A2A request's events and, on a runtime whose own spans are read, as
+ * its `invoke_agent` span too. The first one stands.
+ */
+function onceEach(lines) {
+    const seen = new Set();
+    return lines.filter(line => {
+        // Words said are the same words whoever they were said to.
+        const said = `${line.kind}\u0000${line.from}\u0000${line.kind === 'said' ? '' : (line.to ?? '')}\u0000${line.text}`;
+        if (seen.has(said)) {
+            return false;
+        }
+        seen.add(said);
+        return true;
+    });
+}
+/**
+ * The transcript of a scene from the spans recorded while it works (the
+ * Agent Inspector's, one tracer for every member).
+ */
+export function transcriptOfSpans(spans, members) {
+    const lines = [];
+    // A tool call under which an A2A request sits is the asking itself: the
+    // request says it, with its words.
+    const asking = new Set();
+    for (const span of spans) {
+        if (span.parent_span_id && isA2A(span, span.attributes ?? {})) {
+            asking.add(span.parent_span_id);
+        }
+    }
+    for (const span of spans) {
+        const attributes = span.attributes ?? {};
+        const start = millis(span.start_time);
+        const end = millis(span.end_time, start);
+        const operation = attributes['gen_ai.operation.name'];
+        const failed = span.status_code === 'ERROR';
+        if (operation === 'invoke_agent') {
+            const agent = memberNamed(text(attributes['gen_ai.agent.name']) || span.service_name, members);
+            const asked = messageText(attributes['gen_ai.input.messages']);
+            // The person's question, at the top of a turn; a turn asked by another
+            // member is told by its A2A request.
+            if (asked && !span.parent_span_id) {
+                lines.push({
+                    key: `${span.span_id}:asked`,
+                    at: start,
+                    from: PERSON,
+                    to: agent.name,
+                    kind: 'asked',
+                    text: asked,
+                });
+            }
+            const said = messageText(attributes['gen_ai.output.messages']);
+            if (said) {
+                lines.push({
+                    key: `${span.span_id}:said`,
+                    at: end,
+                    from: agent.name,
+                    kind: 'said',
+                    text: said,
+                    ...(failed ? { failed } : {}),
+                });
+            }
+            else if (failed) {
+                lines.push({
+                    key: `${span.span_id}:said`,
+                    at: end,
+                    from: agent.name,
+                    kind: 'said',
+                    text: `could not answer${span.status_message ? `: ${span.status_message}` : ''}`,
+                    failed,
+                });
+            }
+            continue;
+        }
+        if (operation === 'execute_tool') {
+            if (asking.has(span.span_id)) {
+                continue;
+            }
+            const agent = memberNamed(text(attributes['gen_ai.agent.name']) || span.service_name, members);
+            const tool = text(attributes['gen_ai.tool.name']) || span.span_name;
+            lines.push({
+                key: `${span.span_id}:called`,
+                at: start,
+                from: agent.name,
+                to: calledOf(tool, text(attributes['datalayer.tool.kind']), agent),
+                kind: 'called',
+                text: tool,
+                ...(span.in_progress ? { open: true } : {}),
+                ...(failed ? { failed } : {}),
+            });
+            continue;
+        }
+        if (isA2A(span, attributes)) {
+            const request = text(attributes['a2a.message.text']).trim();
+            if (!request) {
+                // The agent card, a task read: nothing said.
+                continue;
+            }
+            const asker = memberNamed(span.service_name, members);
+            const peer = memberNamed(text(attributes['peer.service']), members);
+            lines.push({
+                key: `${span.span_id}:asked`,
+                at: start,
+                from: asker.name,
+                to: peer.name,
+                kind: 'asked',
+                text: request,
+                ...(span.in_progress ? { open: true } : {}),
+            });
+            // What came back: the answer, or the last words of its events.
+            let answer = text(attributes['a2a.answer.text']).trim();
+            let answeredAt = end;
+            if (!answer) {
+                for (const event of span.events ?? []) {
+                    if (event.name === 'a2a.message' ||
+                        event.name === 'a2a.artifact_update') {
+                        const words = text(event.attributes?.['a2a.message.text']).trim();
+                        if (words) {
+                            answer = words;
+                            answeredAt = millis(event.timestamp, end);
+                        }
+                    }
+                }
+            }
+            if (answer) {
+                lines.push({
+                    key: `${span.span_id}:said`,
+                    at: answeredAt,
+                    from: peer.name,
+                    to: asker.name,
+                    kind: 'said',
+                    text: answer,
+                    ...(failed ? { failed } : {}),
+                });
+            }
+            else if (failed) {
+                lines.push({
+                    key: `${span.span_id}:said`,
+                    at: end,
+                    from: peer.name,
+                    to: asker.name,
+                    kind: 'said',
+                    text: `could not answer${span.status_message ? `: ${span.status_message}` : ''}`,
+                    failed,
+                });
+            }
+        }
+    }
+    return onceEach(inOrder(lines));
+}
+/**
+ * The transcript of one member's run once it is over, from its record: a
+ * `turn` is what the person asked and what it answered, a `tool_call` what
+ * it called in between. The calls of a turn are recorded before the turn
+ * itself (at its close), so the question is placed where the turn began.
+ */
+export function transcriptOfRecord(entries, member) {
+    const ordered = [...entries].sort((a, b) => millis(a.createdAt) - millis(b.createdAt) || a.version - b.version);
+    const lines = [];
+    let pending = [];
+    let answered = false;
+    for (const entry of ordered) {
+        const at = millis(entry.createdAt);
+        if (entry.kind === 'tool_call') {
+            const tool = text(entry.payload.tool) || entry.summary;
+            pending.push({
+                key: `${entry.uid}:called`,
+                at,
+                from: member.name,
+                to: calledOf(tool, '', member),
+                kind: 'called',
+                text: tool,
+                ...(entry.payload.error ? { failed: true } : {}),
+            });
+        }
+        else if (entry.kind === 'turn') {
+            const asked = text(entry.payload.asked) || entry.summary;
+            const said = text(entry.payload.answered);
+            lines.push({
+                key: `${entry.uid}:asked`,
+                at: pending[0]?.at ?? at,
+                from: PERSON,
+                to: member.name,
+                kind: 'asked',
+                text: asked,
+            });
+            lines.push(...pending);
+            pending = [];
+            if (said) {
+                lines.push({
+                    key: `${entry.uid}:said`,
+                    at,
+                    from: member.name,
+                    kind: 'said',
+                    text: said,
+                });
+            }
+            answered = true;
+        }
+        else if (entry.kind === 'output' && !answered) {
+            // A record kept without its conversations: the answer's summary.
+            pending.push({
+                key: `${entry.uid}:said`,
+                at,
+                from: member.name,
+                kind: 'said',
+                text: entry.summary,
+            });
+        }
+    }
+    lines.push(...pending);
+    return lines;
+}
+/** A line's time, as a clock reads it: `14:03:27`. */
+export function timeText(at) {
+    const date = new Date(at);
+    const two = (value) => String(value).padStart(2, '0');
+    return `${two(date.getHours())}:${two(date.getMinutes())}:${two(date.getSeconds())}`;
+}
+/** Who a line is from and to: `Sales`, `Sales → Accounting`, `Accounting → Odoo`. */
+export function lineHeading(line) {
+    return line.to && line.kind !== 'said'
+        ? `${line.from} → ${line.to}`
+        : line.from;
+}
+/** A line in words: `Sales → Accounting: Which invoices are open?`. */
+export function lineText(line) {
+    const tail = line.open ? '…' : line.failed ? ' (failed)' : '';
+    return `${lineHeading(line)}: ${line.text}${tail}`;
+}
+/** The transcript as text, one line each with its time: what *Copy as text* copies. */
+export function transcriptText(lines) {
+    return lines
+        .map(line => `${timeText(line.at)}  ${lineText(line)}`)
+        .join('\n');
+}

package/lib/components/teams/teamConnections.d.ts

@@ -1,6 +1,6 @@
 import type { AppSpec } from '../../types/agentspecs';
 import { type A2ATeamConnection } from './a2aTeamFlow';
-import type { ToolClass } from '../inspector/agentInspector';
+import type { ToolClass } from '../inspector/agentSpans';
 /**
  * The connections of an application, each with its server's name and mark
  * and its tools. A connection to a server the catalogue does not have is
@@ -8,7 +8,7 @@ import type { ToolClass } from '../inspector/agentInspector';
  */
 export declare function teamConnectionsOf(app: Pick<AppSpec, 'connections'>): A2ATeamConnection[];
 /**
- * Where a member's tool call comes from, for the Agent Inspector: a call to
+ * Where a member's tool call comes from, for its span: a call to
  * one of its connections is an MCP call, with the server's mark; any other
  * is `fallback`'s (`classifyToolCall`, by the catalogues) or a tool its
  * runtime runs (`write_notebook`).

package/lib/components/teams/teamConnections.js

@@ -49,7 +49,7 @@ export function teamConnectionsOf(app) {
     return connections;
 }
 /**
- * Where a member's tool call comes from, for the Agent Inspector: a call to
+ * Where a member's tool call comes from, for its span: a call to
  * one of its connections is an MCP call, with the server's mark; any other
  * is `fallback`'s (`classifyToolCall`, by the catalogues) or a tool its
  * runtime runs (`write_notebook`).
@@ -59,11 +59,11 @@ export function teamToolClassifier(connections, fallback) {
         const connection = connectionOfTool(name, connections);
         if (connection) {
             return {
-                source: 'mcp',
+                kind: 'mcp',
                 ...(connection.icon ? { icon: connection.icon } : {}),
                 ...(connection.emoji ? { emoji: connection.emoji } : {}),
             };
         }
-        return fallback?.(name, args) ?? { source: 'backend-tool' };
+        return fallback?.(name, args) ?? { kind: 'runtime' };
     };
 }

package/lib/components/teams/useA2ATeam.d.ts

@@ -3,7 +3,7 @@ import type { DisplayItem } from '../../types/chat';
 import { type BrowserModelOptions } from '../../runtimes/browser/model';
 import { type A2APeer, type A2APeerArtifact } from '../../runtimes/browser/a2aPeer';
 import type { AppSpec } from '../../types/agentspecs';
-import type { AgentInspectorSink } from '../inspector/agentInspector';
+import type { OtelLiveTracer } from '@datalayer/core/lib/otel/live';
 import { type A2ATeamCall, type A2ATeamConnection, type A2ATeamFlow } from './a2aTeamFlow';
 import { type BalloonToolLine } from '../../chat/assistant/toolLine';
 /** What one member's character does: its state, its balloon, and whether it was sent away. */
@@ -38,36 +38,104 @@ export declare function answeredLine(artifacts: A2APeerArtifact[]): string;
 export declare function notebookAmong(artifacts: A2APeerArtifact[]): A2APeerArtifact | null;
 /** A line short enough for a balloon. */
 export declare function balloonLine(text: string, length?: number): string;
+/** The name of the entry's tool for a peer, as its instructions call it: `ask_<peer id>`. */
+export declare function askToolOf(peerId: string): string;
+/**
+ * What a member says when it is asked, before it works: the books when it
+ * reaches Odoo, the system it reaches otherwise, or just that it is on it.
+ */
+export declare function askedLine(connections: readonly A2ATeamConnection[]): string;
+/**
+ * The entry's instructions for a team of more than one peer: its own, and
+ * which tool asks whom, so that it names each. A team of two keeps the
+ * entry's instructions as they are.
+ */
+export declare function teamInstructions(entry: Pick<AppSpec, 'instructions'>, peers: readonly {
+    app: Pick<AppSpec, 'name'>;
+    askTool: string;
+}[]): string;
+/** A member the entry asks over A2A. */
+export type A2ATeamPeerOptions = {
+    /** The member asked. */
+    app: AppSpec;
+    /** The peer, once its card is read; `null` until then. */
+    peer: A2APeer | null;
+    /** The name of the entry's tool for it; `ask_<its id>` unsaid. */
+    askTool?: string;
+    /** Its connections (`teamConnectionsOf(app)`): the calls to them are kept. */
+    connections?: A2ATeamConnection[];
+    /**
+     * What its balloon says before it is asked (a scene's `opens_first`, its
+     * persona's line); unsaid, it waits quietly.
+     */
+    greeting?: string;
+};
 export type UseA2ATeamOptions = {
     /** The member that talks to the person and asks: it runs in this page. */
     entry: AppSpec;
-    /** The member it asks over A2A. */
-    peerApp: AppSpec;
-    /** The peer, once its card is read; `null` until then. */
-    peer: A2APeer | null;
+    /** A team of two: the member it asks over A2A. */
+    peerApp?: AppSpec;
+    /** A team of two: the peer, once its card is read; `null` until then. */
+    peer?: A2APeer | null;
+    /** A team of two: the name of the entry's tool, as its instructions call it: `ask_<peer id>`. */
+    askTool?: string;
+    /** A team of two: the peer's connections (`teamConnectionsOf(peerApp)`). */
+    peerConnections?: A2ATeamConnection[];
+    /**
+     * A team of N: the members the entry asks, in the order its tools are
+     * offered. Give the same array while nothing changed (memoised): a new
+     * one makes the entry's agent again.
+     */
+    peers?: readonly A2ATeamPeerOptions[];
+    /**
+     * The entry itself, when it runs on a runtime and is asked over A2A from
+     * the page: no agent turns in the browser, `send` asks it directly, and
+     * its persona follows what it tells (asked, working, its tools, answered).
+     * `null` until its card is read.
+     */
+    entryPeer?: A2APeer | null;
     /** Where the entry's model is asked, and with whose token. */
     inference: Omit<BrowserModelOptions, 'model'>;
-    /** The name of the entry's tool, as its instructions call it: `ask_<peer id>`. */
-    askTool?: string;
     /** The most steps of one turn. */
     maxSteps?: number;
-    /** The peer's connections (`teamConnectionsOf(peerApp)`): the calls to them are kept. */
-    peerConnections?: A2ATeamConnection[];
     /**
-     * The media types the page accepts from the peer (`acceptedOutputModes`):
+     * The media types the page accepts from the peers (`acceptedOutputModes`):
      * words, and the formats it can show, such as a notebook. Unsaid, words alone.
      */
     accept?: readonly string[];
     /**
-     * The Agent Inspector's sink: the entry's turns and its call to the peer
-     * are recorded there, and what the peer's events were made of.
+     * The Agent Inspector's tracer: the entry's turns and its calls to the
+     * peers are recorded there as spans.
      */
-    inspector?: AgentInspectorSink | null;
+    inspector?: OtelLiveTracer | null;
+};
+/** One peer of the team, as the team keeps it. */
+export type A2ATeamPeer = {
+    /** Its id: its application's. */
+    id: string;
+    app: AppSpec;
+    /** The name of the entry's tool for it. */
+    askTool: string;
+    connections: A2ATeamConnection[];
+    /** Whether it is reached: its card was read. */
+    connected: boolean;
+    persona: A2ATeamPersona;
+    /** What it was asked, the tools it called and what it answered. */
+    history: DisplayItem[];
+    /** Its last answer, as it gave it. */
+    report: string | null;
+    /** What it gave besides words with its last answer. */
+    artifacts: A2APeerArtifact[];
+    /** Which way its link carries a message now. */
+    flow: A2ATeamFlow;
+    setAway: (away: boolean) => void;
 };
 export type A2ATeam = {
     entryPersona: A2ATeamPersona;
+    /** The first peer's persona: the peer of a team of two. */
     peerPersona: A2ATeamPersona;
     setEntryAway: (away: boolean) => void;
+    /** Sends the first peer away, or calls it back. */
     setPeerAway: (away: boolean) => void;
     turns: A2ATeamTurn[];
     /**
@@ -76,26 +144,30 @@ export type A2ATeam = {
      */
     entryHistory: DisplayItem[];
     /**
-     * What the peer was asked, the tools it called and what it answered, in
-     * the chat's model (messages and tool calls).
+     * What the first peer was asked, the tools it called and what it
+     * answered, in the chat's model (messages and tool calls).
      */
     peerHistory: DisplayItem[];
-    /** The peer's last answer, as it gave it. */
+    /** The peers, in their order, each as the team keeps it. */
+    peers: A2ATeamPeer[];
+    /** Which way each peer's link carries a message now, by the peer's id. */
+    flows: Record<string, A2ATeamFlow>;
+    /** The last answer a peer gave, as it gave it. */
     report: string | null;
-    /** What the peer gave besides words with its last answer, by media type. */
+    /** What a peer gave besides words with the last answer, by media type. */
     artifacts: A2APeerArtifact[];
-    /** The latest notebook the peer gave, kept until another one comes. */
+    /** The latest notebook a peer gave, kept until another one comes. */
     notebook: A2APeerArtifact | null;
-    /** Which way the link carries a message now. */
+    /** Which way the first peer's link carries a message now. */
     flow: A2ATeamFlow;
-    /** The tool calls the peer's connections are answering now. */
+    /** The tool calls the peers' connections are answering now. */
     calls: A2ATeamCall[];
     /** Whether a turn is under way. */
     busy: boolean;
-    /** Whether the entry can be asked: its peer is connected. */
+    /** Whether the entry can be asked: every peer is connected, or the entry is. */
     ready: boolean;
     send: (text: string) => Promise<void>;
     stop: () => void;
 };
-/** Run a team of two over A2A in the page. */
+/** Run a team over A2A in the page. */
 export declare function useA2ATeam(options: UseA2ATeamOptions): A2ATeam;