@datalayer/agent-runtimes 1.3.61 → 1.3.62

package/lib/runtimes/browser/a2aPeer.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Another application, asked over A2A from an agent whose loop turns in the page.
+ *
+ * A team of applications says who asks whom (agentspecs `teams`, `talks_to`
+ * over `a2a`). The application asked is served on a runtime with fasta2a; the
+ * one that asks may run here, in the browser, and asks with the A2A SDK
+ * (`@a2a-js/sdk` 1.x) itself, with no wrapper of ours between them:
+ *
+ * - {@link connectA2APeer} reads the peer's agent card and makes a client
+ *   from it. The card says where to send a request, what to ask (its skill:
+ *   description, examples, text in, text out) and that a key is needed.
+ * - {@link a2aPeerTool} is the tool the asking agent calls. It takes one
+ *   request in words, as the skill does, streams the task and returns the
+ *   peer's answer in words. Each step is told to {@link A2APeerEvent} as it
+ *   happens, so a page can show the exchange: asked, working, answered.
+ *
+ * The key goes as a bearer token on every request, the card's too. The
+ * runtime hands it to the peer's run, which then reaches the peer's
+ * connections with it and with nothing broader.
+ *
+ * @module runtimes/browser/a2aPeer
+ */
+import { type AgentCard, type AgentSkill, type Message, type Part } from '@a2a-js/sdk';
+import { type Client } from '@a2a-js/sdk/client';
+import { type Tool } from 'ai';
+/** Where an A2A agent's card is, under the address it is served at. */
+export declare const AGENT_CARD_PATH = ".well-known/agent-card.json";
+/** A peer reached over A2A: its client, its card, and the skill it is asked for. */
+export type A2APeer = {
+    client: Client;
+    card: AgentCard;
+    skill: AgentSkill;
+};
+export type ConnectA2APeerOptions = {
+    /** Where the peer is served: `…/api/v1/a2a/agents/<application id>`. */
+    url: string;
+    /** A key granted to the peer's route, sent as a bearer token. */
+    key?: string;
+    /** The fetch to use, for tests and hosts that wrap the network. */
+    fetch?: typeof globalThis.fetch;
+};
+/**
+ * Read a peer's agent card and make a client from it.
+ *
+ * The card's first skill is what the peer is asked for: a peer served from an
+ * application has one, named for it.
+ */
+export declare function connectA2APeer(options: ConnectA2APeerOptions): Promise<A2APeer>;
+/** What happens to one request, as it happens. */
+export type A2APeerEvent = {
+    phase: 'asked';
+    request: string;
+} | {
+    phase: 'working';
+    taskId: string;
+    note?: string;
+} | {
+    phase: 'answered';
+    taskId: string;
+    answer: string;
+} | {
+    phase: 'failed';
+    error: string;
+};
+/** The text of a message's or an artifact's parts. */
+export declare function textOf(parts: Part[] | undefined): string;
+/** A user's message of one text part, as the SDK's 1.x types write it. */
+export declare function textMessage(text: string): Message;
+/**
+ * Ask a peer once, streaming the task, and return its answer.
+ *
+ * The answer is the text of the task's artifact, assembled from its chunks,
+ * or the final status message's when there is no artifact. A task that ends
+ * other than completed is thrown, with what the peer said.
+ */
+export declare function askA2APeer(peer: A2APeer, request: string, options?: {
+    signal?: AbortSignal;
+    onEvent?: (event: A2APeerEvent) => void;
+}): Promise<string>;
+export type A2APeerToolOptions = {
+    peer: A2APeer;
+    /** Told each step of each request, as it happens. */
+    onEvent?: (event: A2APeerEvent) => void;
+};
+/** The tool's description: the peer's skill, and what it may be asked. */
+export declare function peerToolDescription(peer: A2APeer): string;
+/**
+ * The tool an agent asks its peer with: a request in, the peer's answer out.
+ *
+ * A failed request is returned rather than thrown, so the agent can tell the
+ * person what the peer said instead of the whole run failing.
+ */
+export declare function a2aPeerTool(options: A2APeerToolOptions): Tool;

package/lib/runtimes/browser/a2aPeer.js

@@ -0,0 +1,241 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Another application, asked over A2A from an agent whose loop turns in the page.
+ *
+ * A team of applications says who asks whom (agentspecs `teams`, `talks_to`
+ * over `a2a`). The application asked is served on a runtime with fasta2a; the
+ * one that asks may run here, in the browser, and asks with the A2A SDK
+ * (`@a2a-js/sdk` 1.x) itself, with no wrapper of ours between them:
+ *
+ * - {@link connectA2APeer} reads the peer's agent card and makes a client
+ *   from it. The card says where to send a request, what to ask (its skill:
+ *   description, examples, text in, text out) and that a key is needed.
+ * - {@link a2aPeerTool} is the tool the asking agent calls. It takes one
+ *   request in words, as the skill does, streams the task and returns the
+ *   peer's answer in words. Each step is told to {@link A2APeerEvent} as it
+ *   happens, so a page can show the exchange: asked, working, answered.
+ *
+ * The key goes as a bearer token on every request, the card's too. The
+ * runtime hands it to the peer's run, which then reaches the peer's
+ * connections with it and with nothing broader.
+ *
+ * @module runtimes/browser/a2aPeer
+ */
+import { Role, TaskState, } from '@a2a-js/sdk';
+import { ClientFactory, ClientFactoryOptions, DefaultAgentCardResolver, JsonRpcTransportFactory, } from '@a2a-js/sdk/client';
+import { jsonSchema, tool } from 'ai';
+/** Where an A2A agent's card is, under the address it is served at. */
+export const AGENT_CARD_PATH = '.well-known/agent-card.json';
+/** A fetch that sends the key as a bearer token, beside the caller's headers. */
+function withKey(base, key) {
+    if (!key) {
+        return base;
+    }
+    return (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.set('Authorization', `Bearer ${key}`);
+        return base(input, { ...init, headers });
+    };
+}
+/**
+ * Read a peer's agent card and make a client from it.
+ *
+ * The card's first skill is what the peer is asked for: a peer served from an
+ * application has one, named for it.
+ */
+export async function connectA2APeer(options) {
+    const base = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const fetchImpl = withKey(base, options.key);
+    const factory = new ClientFactory(ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
+        transports: [new JsonRpcTransportFactory({ fetchImpl })],
+        cardResolver: new DefaultAgentCardResolver({ fetchImpl }),
+    }));
+    const root = options.url.replace(/\/+$/, '');
+    // The full address of the card, with an empty path: the resolver's default
+    // path would replace the peer's own path rather than extend it.
+    const client = await factory.createFromUrl(`${root}/${AGENT_CARD_PATH}`, '');
+    const card = await client.getAgentCard();
+    const [skill] = card.skills;
+    if (!skill) {
+        throw new Error(`${card.name || root} offers no skill on its agent card: there is nothing to ask it.`);
+    }
+    return { client, card, skill };
+}
+/** The text of a message's or an artifact's parts. */
+export function textOf(parts) {
+    return (parts ?? [])
+        .map(part => (part.content?.$case === 'text' ? part.content.value : ''))
+        .join('');
+}
+/** A user's message of one text part, as the SDK's 1.x types write it. */
+export function textMessage(text) {
+    return {
+        messageId: globalThis.crypto.randomUUID(),
+        contextId: '',
+        taskId: '',
+        role: Role.ROLE_USER,
+        parts: [
+            {
+                content: { $case: 'text', value: text },
+                metadata: undefined,
+                filename: '',
+                mediaType: '',
+            },
+        ],
+        metadata: undefined,
+        extensions: [],
+        referenceTaskIds: [],
+    };
+}
+/** What a tool call or a tool result says while the peer works, in a few words. */
+function noteOf(message) {
+    for (const part of message?.parts ?? []) {
+        const content = part.content;
+        if (content?.$case === 'text' && content.value.trim()) {
+            return content.value;
+        }
+        if (content?.$case === 'data' && content.value) {
+            // What the runtime's A2A worker publishes while its agent works.
+            const data = content.value;
+            const name = (data.tool_call ?? data.tool_result)?.name;
+            if (name) {
+                return data.tool_call ? `Calling ${name}` : `Read ${name}`;
+            }
+        }
+    }
+    return undefined;
+}
+const ENDED_BADLY = {
+    [TaskState.TASK_STATE_FAILED]: 'failed',
+    [TaskState.TASK_STATE_CANCELED]: 'was canceled',
+    [TaskState.TASK_STATE_REJECTED]: 'was rejected',
+    [TaskState.TASK_STATE_AUTH_REQUIRED]: 'asks for a key it was not given',
+    [TaskState.TASK_STATE_INPUT_REQUIRED]: 'asks for more than it was told',
+};
+/**
+ * Ask a peer once, streaming the task, and return its answer.
+ *
+ * The answer is the text of the task's artifact, assembled from its chunks,
+ * or the final status message's when there is no artifact. A task that ends
+ * other than completed is thrown, with what the peer said.
+ */
+export async function askA2APeer(peer, request, options = {}) {
+    const { signal, onEvent } = options;
+    onEvent?.({ phase: 'asked', request });
+    try {
+        return await streamTask(peer, request, signal, onEvent);
+    }
+    catch (reason) {
+        const error = reason instanceof Error ? reason.message : String(reason);
+        onEvent?.({ phase: 'failed', error });
+        throw reason;
+    }
+}
+async function streamTask(peer, request, signal, onEvent) {
+    const artifacts = new Map();
+    let taskId = '';
+    let final = '';
+    let ended;
+    const stream = peer.client.sendMessageStream({
+        tenant: '',
+        message: textMessage(request),
+        configuration: undefined,
+        metadata: undefined,
+    }, { signal });
+    for await (const event of stream) {
+        const payload = event.payload;
+        if (!payload) {
+            continue;
+        }
+        if (payload.$case === 'task') {
+            taskId = payload.value.id;
+            onEvent?.({ phase: 'working', taskId });
+        }
+        else if (payload.$case === 'statusUpdate') {
+            const status = payload.value.status;
+            taskId = payload.value.taskId || taskId;
+            if (status?.state === TaskState.TASK_STATE_WORKING) {
+                onEvent?.({ phase: 'working', taskId, note: noteOf(status.message) });
+            }
+            else if (status) {
+                ended = status.state;
+                final = textOf(status.message?.parts) || final;
+            }
+        }
+        else if (payload.$case === 'artifactUpdate') {
+            const artifact = payload.value.artifact;
+            if (artifact) {
+                const text = textOf(artifact.parts);
+                const before = artifacts.get(artifact.artifactId) ?? '';
+                // Chunks are appended; the last chunk carries the whole answer again.
+                artifacts.set(artifact.artifactId, payload.value.append && !payload.value.lastChunk
+                    ? before + text
+                    : text);
+            }
+        }
+        else if (payload.$case === 'message') {
+            final = textOf(payload.value.parts);
+            ended = TaskState.TASK_STATE_COMPLETED;
+        }
+    }
+    if (ended !== TaskState.TASK_STATE_COMPLETED) {
+        const how = (ended !== undefined && ENDED_BADLY[ended]) || 'ended without an answer';
+        throw new Error(`${peer.card.name} ${how}${final ? `: ${final}` : '.'}`);
+    }
+    const answer = [...artifacts.values()].join('\n') || final;
+    onEvent?.({ phase: 'answered', taskId, answer });
+    return answer;
+}
+/** The input of a peer's tool: one request, in words, as its skill takes it. */
+const REQUEST_SCHEMA = {
+    type: 'object',
+    properties: {
+        request: {
+            type: 'string',
+            description: 'What to ask, in one request that can be acted on without the rest of this conversation.',
+        },
+    },
+    required: ['request'],
+};
+/** The tool's description: the peer's skill, and what it may be asked. */
+export function peerToolDescription(peer) {
+    const { card, skill } = peer;
+    const examples = skill.examples.length
+        ? ` For example: ${skill.examples.map(example => `"${example}"`).join('; ')}.`
+        : '';
+    return `Ask ${card.name}, over A2A: ${skill.description}${examples} It answers in words; report its answer as it gave it.`;
+}
+/**
+ * The tool an agent asks its peer with: a request in, the peer's answer out.
+ *
+ * A failed request is returned rather than thrown, so the agent can tell the
+ * person what the peer said instead of the whole run failing.
+ */
+export function a2aPeerTool(options) {
+    const { peer, onEvent } = options;
+    return tool({
+        description: peerToolDescription(peer),
+        inputSchema: jsonSchema(REQUEST_SCHEMA),
+        execute: async (input, execution) => {
+            const { request } = (input ?? {});
+            if (!request?.trim()) {
+                return { error: `A request to ${peer.card.name} says what it asks.` };
+            }
+            try {
+                const answer = await askA2APeer(peer, request, {
+                    signal: execution?.abortSignal,
+                    onEvent,
+                });
+                return { answer };
+            }
+            catch (reason) {
+                return {
+                    error: reason instanceof Error ? reason.message : String(reason),
+                };
+            }
+        },
+    });
+}

package/lib/specs/actions.js

@@ -642,6 +642,57 @@ export const SERVER_ACTIONS = {
  * to reproduce.
  */
 export const APP_BEHAVIOURS = {
+    accounting: {
+        'odoo-accounting.odoo_accounting_aged_balance': 'do_it',
+        'odoo-accounting.odoo_accounting_bank_status': 'do_it',
+        'odoo-accounting.odoo_accounting_book_bank_line': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_check_tax_period': 'do_it',
+        'odoo-accounting.odoo_accounting_create_customer_invoice': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_create_draft_invoice': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_create_draft_journal_entry': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_create_matching_model': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_create_vendor_bill': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_explain_account_balance': 'do_it',
+        'odoo-accounting.odoo_accounting_general_ledger': 'do_it',
+        'odoo-accounting.odoo_accounting_get_asset': 'do_it',
+        'odoo-accounting.odoo_accounting_get_bank_line': 'do_it',
+        'odoo-accounting.odoo_accounting_get_invoice': 'do_it',
+        'odoo-accounting.odoo_accounting_get_journal_entry': 'do_it',
+        'odoo-accounting.odoo_accounting_get_lock_dates': 'do_it',
+        'odoo-accounting.odoo_accounting_get_tax_return': 'do_it',
+        'odoo-accounting.odoo_accounting_get_tax_settings': 'do_it',
+        'odoo-accounting.odoo_accounting_link_bank_feed': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_list_accounts': 'do_it',
+        'odoo-accounting.odoo_accounting_list_assets': 'do_it',
+        'odoo-accounting.odoo_accounting_list_bank_feeds': 'do_it',
+        'odoo-accounting.odoo_accounting_list_bank_lines': 'do_it',
+        'odoo-accounting.odoo_accounting_list_currency_rates': 'do_it',
+        'odoo-accounting.odoo_accounting_list_invoices': 'do_it',
+        'odoo-accounting.odoo_accounting_list_journal_entries': 'do_it',
+        'odoo-accounting.odoo_accounting_list_journals': 'do_it',
+        'odoo-accounting.odoo_accounting_list_open_balances': 'do_it',
+        'odoo-accounting.odoo_accounting_list_partners': 'do_it',
+        'odoo-accounting.odoo_accounting_list_tax_grid_lines': 'do_it',
+        'odoo-accounting.odoo_accounting_list_tax_returns': 'do_it',
+        'odoo-accounting.odoo_accounting_list_taxes': 'do_it',
+        'odoo-accounting.odoo_accounting_list_untagged_tax_lines': 'do_it',
+        'odoo-accounting.odoo_accounting_match_bank_line': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_partner_ledger': 'do_it',
+        'odoo-accounting.odoo_accounting_post_invoice': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_post_journal_entry': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_reconcile_lines': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_remove_duplicate_bank_lines': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_reset_bank_line': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_set_currency_rates': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_set_lock_date': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_set_tax_grids': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_set_tax_periodicity': 'leave_to_me',
+        'odoo-accounting.odoo_accounting_suggest_bank_matches': 'do_it',
+        'odoo-accounting.odoo_accounting_suggest_reconciliations': 'do_it',
+        'odoo-accounting.odoo_accounting_tax_grids': 'do_it',
+        'odoo-accounting.odoo_accounting_trial_balance': 'do_it',
+        'odoo-accounting.odoo_accounting_unreconcile_lines': 'leave_to_me',
+    },
     'customer-interview': {},
     'data-quality': {},
     decide: {},
@@ -771,6 +822,7 @@ export const APP_BEHAVIOURS = {
     'pipeline-report': {},
     'quote-calculator': {},
     'report-from-a-file': {},
+    sales: {},
     'ship-or-fix': {},
     'supplier-comparison': {},
     'support-desk': {},
@@ -787,6 +839,7 @@ export const APP_BEHAVIOURS = {
  * application and tool, each condition and the behaviour when it holds.
  */
 export const APP_ESCALATIONS = {
+    accounting: {},
     'customer-interview': {},
     'data-quality': {},
     decide: {},
@@ -828,6 +881,7 @@ export const APP_ESCALATIONS = {
     'pipeline-report': {},
     'quote-calculator': {},
     'report-from-a-file': {},
+    sales: {},
     'ship-or-fix': {},
     'supplier-comparison': {},
     'support-desk': {},

package/lib/specs/apps.d.ts

@@ -8,6 +8,7 @@
  * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.
  */
 import type { AppBuilt, AppKind, AppSpec } from '../types/agentspecs';
+export declare const ACCOUNTING_APP_0_0_1: AppSpec;
 export declare const CUSTOMER_INTERVIEW_APP_0_0_1: AppSpec;
 export declare const DATA_QUALITY_APP_0_0_1: AppSpec;
 export declare const DECIDE_APP_0_0_1: AppSpec;
@@ -16,6 +17,7 @@ export declare const MODEL_CHOICE_APP_0_0_1: AppSpec;
 export declare const PIPELINE_REPORT_APP_0_0_1: AppSpec;
 export declare const QUOTE_CALCULATOR_APP_0_0_1: AppSpec;
 export declare const REPORT_FROM_A_FILE_APP_0_0_1: AppSpec;
+export declare const SALES_APP_0_0_1: AppSpec;
 export declare const SHIP_OR_FIX_APP_0_0_1: AppSpec;
 export declare const SUPPLIER_COMPARISON_APP_0_0_1: AppSpec;
 export declare const SUPPORT_DESK_APP_0_0_1: AppSpec;