@datalayer/agent-runtimes 1.3.85 → 1.3.87

package/lib/components/teams/sceneStage.js

@@ -0,0 +1,170 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { APP_CATALOGUE } from '../../specs/apps';
+import { listSceneSpecs } from '../../specs/scenes';
+/** A reference without its version: `accounting:0.0.1` is `accounting`. */
+export function refId(ref) {
+    const at = ref.lastIndexOf(':');
+    return at > 0 && ref.slice(at + 1).includes('.') ? ref.slice(0, at) : ref;
+}
+/** The application a cast member is, from the catalogue, or undefined. */
+export function appOfMember(member) {
+    const id = refId(member.app);
+    return id && Object.prototype.hasOwnProperty.call(APP_CATALOGUE, id)
+        ? APP_CATALOGUE[id]
+        : undefined;
+}
+/**
+ * The links of a team over A2A, in the order its members say them: each
+ * member's `talks_to … over: a2a`. A link to a server (over `mcp`) is a
+ * connection, drawn under the member, not an edge between members.
+ */
+export function teamLinksOf(team) {
+    const members = 'cast' in team
+        ? team.cast.map(member => ({
+            id: member.member,
+            talksTo: member.talksTo,
+        }))
+        : team.agents;
+    return members.flatMap(member => (member.talksTo ?? [])
+        .filter(link => link.over === 'a2a')
+        .map(link => ({ from: member.id, to: link.member })));
+}
+/**
+ * The entry's suggestions: the script's cues, each labelled by the starter
+ * of the entry's Appspec that says the same words, or by its first words.
+ * Without a scene, the starters themselves.
+ */
+export function sceneCuesOf(scene, starters) {
+    const fromStarters = starters.map(starter => ({
+        label: starter.label,
+        prompt: starter.message,
+    }));
+    if (!scene) {
+        return fromStarters;
+    }
+    return scene.script
+        .map(beat => beat.cue.say.trim())
+        .filter(Boolean)
+        .map(prompt => ({
+        label: fromStarters.find(starter => starter.prompt === prompt)?.label ??
+            prompt.split(/\s+/).slice(0, 4).join(' '),
+        prompt,
+    }));
+}
+/**
+ * Read a scene's stage: its members with their applications, who the entry
+ * is and whom it asks, the links, the positions. Refused when a cast member
+ * is an application the catalogue does not have, or the entry is not in the
+ * cast: a page cannot stage what it cannot draw.
+ */
+export function sceneStageOf(scene) {
+    const members = scene.cast
+        .filter(member => member.app)
+        .map((member) => {
+        const app = appOfMember(member);
+        if (!app) {
+            throw new Error(`The scene ${scene.id} casts ${member.member} as ${member.app}, which the catalogue does not have.`);
+        }
+        const position = scene.stage.positions[member.member];
+        const variable = scene.deployment.addresses[member.member];
+        return {
+            id: member.member,
+            app,
+            cast: member,
+            entry: member.member === scene.entry,
+            runsIn: member.runsIn ?? 'runtime',
+            ...(variable ? { addressVariable: variable } : {}),
+            ...(position ? { position } : {}),
+            setup: app.setup ?? [],
+        };
+    });
+    const entry = members.find(member => member.entry);
+    if (!entry) {
+        throw new Error(`The scene ${scene.id} says its entry is ${scene.entry}, which is not in its cast.`);
+    }
+    const links = teamLinksOf(scene);
+    const asked = links
+        .filter(link => link.from === entry.id)
+        .map(link => link.to);
+    const peers = members.filter(member => !member.entry && asked.includes(member.id));
+    return {
+        scene,
+        entry,
+        peers,
+        members: [entry, ...members.filter(member => !member.entry)],
+        links,
+        positions: scene.stage.positions,
+        opensFirst: scene.stage.opensFirst || entry.id,
+        assumes: scene.setting.assumes,
+    };
+}
+/** The port the examples serve Accounting on, as `npm run examples` starts it. */
+export const ACCOUNTING_PORT = 8767;
+/** The first port `serve_scenes.py` starts a runtime on for the other members. */
+export const SCENE_PORTS_FROM = 8768;
+/**
+ * The members on a runtime across the catalogue's scenes, each once, in
+ * the catalogue's order (a scene's cast in its order): what
+ * `examples/sales-accounting-a2a/serve_scenes.py` serves, in that order.
+ */
+export function sceneRuntimeMembers(scenes = listSceneSpecs()) {
+    const seen = [];
+    for (const scene of scenes) {
+        for (const member of scene.cast) {
+            const id = refId(member.app);
+            if (id &&
+                (member.runsIn ?? 'runtime') === 'runtime' &&
+                !seen.includes(id)) {
+                seen.push(id);
+            }
+        }
+    }
+    return seen;
+}
+/**
+ * The port each runtime member is served on locally: Accounting on
+ * {@link ACCOUNTING_PORT}, the others from {@link SCENE_PORTS_FROM} on, in
+ * the order of {@link sceneRuntimeMembers}. `serve_scenes.py` gives the
+ * same ports by the same rule.
+ */
+export function sceneRuntimePorts(scenes = listSceneSpecs()) {
+    const ports = {};
+    let next = SCENE_PORTS_FROM;
+    for (const id of sceneRuntimeMembers(scenes)) {
+        if (id === 'accounting') {
+            ports[id] = ACCOUNTING_PORT;
+        }
+        else {
+            ports[id] = next;
+            next += 1;
+        }
+    }
+    return ports;
+}
+/** The variable the examples read a member's local address from: `VITE_A2A_CHANGE_DETECTION_URL`. */
+export function sceneAddressVariable(appId) {
+    return `VITE_A2A_${appId.replace(/-/g, '_').toUpperCase()}_URL`;
+}
+/** Where a member is served over A2A on a local runtime at `port`. */
+export function localA2AUrl(appId, port) {
+    return `http://127.0.0.1:${port}/api/v1/a2a/agents/${appId}`;
+}
+/**
+ * Where a member on a runtime is reached by the examples: its variable
+ * (`VITE_A2A_<MEMBER>_URL`) when set in `env`, else the local runtime
+ * `serve_scenes.py` serves it on.
+ */
+export function sceneMemberUrl(appId, env, ports = sceneRuntimePorts()) {
+    const port = ports[appId];
+    const set = env[sceneAddressVariable(appId)];
+    if (set) {
+        return set;
+    }
+    if (port === undefined) {
+        throw new Error(`${appId} runs on no local runtime the examples serve: set ${sceneAddressVariable(appId)}.`);
+    }
+    return localA2AUrl(appId, port);
+}

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

@@ -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 tracer: the entry's turns and its call to the
-     * peer are recorded there as spans.
+     * The Agent Inspector's tracer: the entry's turns and its calls to the
+     * peers are recorded there as spans.
      */
     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;