@datalayer/agent-runtimes 1.5.4 → 1.5.7

package/lib/apps/apps/appspec.d.ts

@@ -99,7 +99,7 @@ export declare function uiProblems(app: Pick<AppSpec, 'ui' | 'enabled'>): string
  * know or said twice, a planned protocol while it is offered, and a `pap`,
  * `pact` or `a2a` block configuring a protocol it does not list.
  */
-export declare function protocolsProblems(app: Pick<AppSpec, 'protocols' | 'enabled' | 'pap' | 'pact' | 'a2a'>): string[];
+export declare function protocolsProblems(app: Pick<AppSpec, 'protocols' | 'enabled' | 'pap' | 'pact' | 'a2a' | 'commerce'>): string[];
 /**
  * An application as the document its file holds.
  *

package/lib/apps/apps/appspec.js

@@ -204,6 +204,7 @@ const KNOWN_KEYS = [
     'ui',
     'pap',
     'pact',
+    'commerce',
     'a2a',
     'rules',
     'permissions',
@@ -333,6 +334,41 @@ function parsePact(data) {
         })),
     };
 }
+/** Commerce (AGENT_PROTOCOLS PI-01): the merchants it shops at for each person. */
+function parseCommerce(data) {
+    return {
+        merchants: records(data.merchants).map(merchant => ({
+            id: text(merchant.id),
+            protocol: oneOf(merchant.protocol, ['ucp', 'acp'], 'ucp'),
+            merchant: text(merchant.merchant),
+            access: oneOf(merchant.access, ['read', 'write'], 'read'),
+            ...(isData(merchant.limit)
+                ? {
+                    limit: {
+                        amount: text(merchant.limit.amount),
+                        currency: text(merchant.limit.currency),
+                    },
+                }
+                : {}),
+        })),
+    };
+}
+/** Commerce as its document says it, nothing at its default. */
+function dumpCommerce(commerce) {
+    if (!commerce)
+        return {};
+    return new Writer().list('merchants', commerce.merchants.map(merchant => new Writer()
+        .text('id', merchant.id, '\u0000')
+        .text('protocol', merchant.protocol, '\u0000')
+        .text('merchant', merchant.merchant, '\u0000')
+        .value('access', merchant.access, 'read')
+        .part('limit', merchant.limit
+        ? {
+            amount: merchant.limit.amount,
+            currency: merchant.limit.currency,
+        }
+        : {}).data)).data;
+}
 /** PACT as its document says it, nothing at its default. */
 function dumpPact(pact) {
     if (!pact)
@@ -912,6 +948,9 @@ export function parseAppspec(document) {
     if (isData(data.pact)) {
         app.pact = parsePact(data.pact);
     }
+    if (isData(data.commerce)) {
+        app.commerce = parseCommerce(data.commerce);
+    }
     if (isData(data.a2a)) {
         app.a2a = parseA2A(data.a2a);
     }
@@ -976,6 +1015,12 @@ export function protocolsProblems(app) {
             problems.push(`Its \`${block}\` block configures ${spec.name}, which it does not list: add '${spec.id}' to \`protocols\`.`);
         }
     }
+    // The `commerce` block configures UCP and ACP, by each merchant's protocol.
+    for (const id of new Set((app.commerce?.merchants ?? []).map(merchant => merchant.protocol))) {
+        if (!app.protocols.includes(id)) {
+            problems.push(`Its \`commerce\` block shops over ${id.toUpperCase()}, which it does not list: add '${id}' to \`protocols\`.`);
+        }
+    }
     return problems;
 }
 // --- writing --------------------------------------------------------------------------
@@ -1243,6 +1288,7 @@ export function dumpAppspec(app) {
         .list('ui', app.ui)
         .part('pap', dumpPap(app.pap))
         .part('pact', dumpPact(app.pact))
+        .part('commerce', dumpCommerce(app.commerce))
         .part('a2a', dumpA2A(app.a2a))
         .list('rules', app.rules.map(rule => ({
         action: rule.action,

package/lib/apps/apps/sceneYaml.js

@@ -31,6 +31,7 @@ export const emptySceneSpec = () => ({
     schema: SCENE_SCHEMA,
     id: '',
     version: '0.0.1',
+    kind: 'team',
     name: '',
     description: '',
     tags: [],
@@ -57,6 +58,9 @@ export const emptySceneSpec = () => ({
     },
     deployment: { account: '', page: '', addresses: {} },
     setup: [],
+    actors: [],
+    lines: [],
+    live: '',
 });
 const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 /**

package/lib/examples/ScenesExample.js

@@ -208,7 +208,8 @@ function Scene({ scene }) {
                                 } }), _jsxs(Box, { display: "flex", gap: 2, mt: 2, children: [_jsx(Button, { variant: "primary", disabled: !team.ready || team.busy || !draft.trim(), onClick: () => send(draft), children: "Ask" }), team.busy && _jsx(Button, { onClick: team.stop, children: "Stop" })] }), _jsx(Box, { mt: 3, "data-team-conversation": "", children: team.turns.map((turn, index) => (_jsxs(Box, { p: 2, mb: 2, borderRadius: 2, bg: turn.role === 'user' ? 'accent.subtle' : 'canvas.subtle', children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', display: 'block' }, children: turn.role === 'user' ? PERSON : entry.app.name }), _jsx(Streamdown, { children: turn.text })] }, index))) })] }), _jsxs(Box, { flex: "1 1 360px", minWidth: 0, children: [!team.notebook && stage.peers.length > 0 && (_jsxs(_Fragment, { children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, mb: 2 }, children: "The report" }), _jsx(Box, { p: 3, border: "1px solid", borderColor: "border.default", borderRadius: 2, minHeight: 120, "data-team-report": "", children: team.report ? (_jsx(Streamdown, { children: team.report })) : (_jsx(Text, { sx: { color: 'fg.muted' }, children: "What the last member asked returns appears here, as it returned it, or as a notebook to run when it gives one." })) })] })), scene.setup.length > 0 && (_jsxs(Box, { mt: 3, "data-scene-setup": "", children: [_jsx(Heading, { as: "h3", sx: { fontSize: 1, mb: 1 }, children: "What this scene needs" }), scene.setup.map(line => (_jsx(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', m: 0 }, children: line }, line)))] }))] })] })] }));
 }
 function Scenes() {
-    const scenes = useMemo(() => listSceneSpecs(), []);
+    // A scripted scene is played as written on its page (PAP_DATALAYER X-02): here, the teams staged live.
+    const scenes = useMemo(() => listSceneSpecs().filter(scene => scene.kind === 'team'), []);
     const [selected, setSelected] = useState(scenes[0]?.id ?? '');
     const scene = scenes.find(one => one.id === selected) ?? scenes[0];
     return (_jsxs(Box, { p: 4, maxWidth: 1080, mx: "auto", children: [_jsx(Heading, { as: "h2", sx: { fontSize: 4, mb: 1 }, children: "Scenes" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mt: 0 }, children: ["The catalogue\u2019s scenes, played against the local servers: each member on a runtime is served over A2A by ", _jsx("code", { children: "serve_scenes.py" }), "; the entry in your browser asks on your token or a visitor\u2019s trial key."] }), _jsx(UnderlineNav, { "aria-label": "Scenes", sx: { mb: 3 }, children: scenes.map(one => (_jsxs(UnderlineNav.Item, { "aria-current": one.id === scene?.id ? 'page' : undefined, onSelect: event => {

package/lib/protocols/commerce.js

@@ -21,13 +21,21 @@ import { PROTOCOL_TOOL_CLASSES } from '../specs/actions';
  * thing: one with several classes, or none, throws rather than guess.
  */
 export function operationClasses(protocol) {
+    const table = PROTOCOL_TOOL_CLASSES[protocol];
+    // The table names the gateway's tools (`ucp_search`): an operation is the
+    // tool's name without its connection's prefix.
+    const prefix = `${table.connection}_`;
     const out = {};
-    for (const [name, classes] of Object.entries(PROTOCOL_TOOL_CLASSES[protocol].tools)) {
+    for (const [name, classes] of Object.entries(table.tools)) {
         if (classes.length !== 1) {
             throw new Error(`${protocol} ${name} is classed ${classes}: one class each`);
         }
-        out[name.replace(/_([a-z])/g, (_, c) => c.toUpperCase())] =
-            classes[0];
+        if (!name.startsWith(prefix)) {
+            throw new Error(`${protocol} ${name} is not one of its \`${prefix}\` tools`);
+        }
+        out[name
+            .slice(prefix.length)
+            .replace(/_([a-z])/g, (_, c) => c.toUpperCase())] = classes[0];
     }
     return out;
 }

package/lib/protocols/ucp/index.d.ts

@@ -47,6 +47,8 @@ export declare function negotiateCapabilities(profile: Json, reactor: ReactorPla
 export declare function revisionOf(checkout: Json): Promise<string>;
 /** What an agent may see of a checkout: no payment credential, no token. */
 export declare function checkoutSummary(checkout: Json): Json;
+/** What an agent may see of an order: its lines, how far each is fulfilled, its totals and link. */
+export declare function orderSummary(order: Json): Json;
 /** A platform's client of one business, over the REST binding. */
 export declare class UcpClient {
     private readonly business;
@@ -67,6 +69,8 @@ export declare class UcpClient {
     updateCheckout(id: string, update: Json): Promise<Json>;
     getCheckout(id: string): Promise<Json>;
     cancelCheckout(id: string): Promise<Json>;
+    /** After the sale: an order the business placed, its lines and how far each is fulfilled (`read`). */
+    getOrder(id: string): Promise<Json>;
     /** The exact purchase a `ready_for_complete` checkout would make. */
     proposeCompletion(id: string): Promise<CheckoutProposal>;
     /** Complete an approved proposal, once: refused if unapproved, spent, changed or expired. */

package/lib/protocols/ucp/index.js

@@ -16,7 +16,7 @@
  * @module protocols/ucp
  */
 import { contribution, defineContributionPoint, definePlugin, } from '@datalayer/reactor';
-import { ExtendedCheckoutResponseSchema } from '@ucp-js/sdk';
+import { ExtendedCheckoutResponseSchema, OrderSchema } from '@ucp-js/sdk';
 import { InMemoryProposalStore, digest, operationClasses, } from '../commerce';
 import { DEFAULT_ORDER, ProtocolDescriptions, firstContribution, } from '../core';
 export const UCP_VERSION = '2026-08-25';
@@ -131,6 +131,32 @@ export function checkoutSummary(checkout) {
         ...(checkout.order ? { order: { id: checkout.order.id } } : {}),
     };
 }
+function readOrder(body) {
+    if (body?.ucp?.status === 'error') {
+        const said = (body.messages ?? []).map((m) => m.content).join('; ');
+        throw new UcpError(`the business refused: ${said}`);
+    }
+    OrderSchema.parse(body);
+    return body;
+}
+/** What an agent may see of an order: its lines, how far each is fulfilled, its totals and link. */
+export function orderSummary(order) {
+    return {
+        id: order.id,
+        checkoutId: order.checkout_id,
+        permalinkUrl: order.permalink_url,
+        currency: order.currency,
+        lines: (order.line_items ?? []).map((line) => ({
+            title: line.item?.title ?? line.item?.id,
+            quantity: line.quantity?.total,
+            fulfilled: line.quantity?.fulfilled,
+            status: line.status,
+        })),
+        totals: Object.fromEntries((order.totals ?? []).map((t) => [t.type, t.amount])),
+        events: (order.fulfillment?.events ?? []).map((event) => event.type),
+        messages: (order.messages ?? []).map((m) => m.content),
+    };
+}
 /** A platform's client of one business, over the REST binding. */
 export class UcpClient {
     business;
@@ -218,6 +244,10 @@ export class UcpClient {
     async cancelCheckout(id) {
         return readCheckout(await this.call('POST', `/checkout-sessions/${id}/cancel`, {}, crypto.randomUUID()));
     }
+    /** After the sale: an order the business placed, its lines and how far each is fulfilled (`read`). */
+    async getOrder(id) {
+        return readOrder(await this.call('GET', `/orders/${id}`));
+    }
     /** The exact purchase a `ready_for_complete` checkout would make. */
     async proposeCompletion(id) {
         const checkout = await this.getCheckout(id);

package/lib/protocols/ucp/merchant.js

@@ -53,6 +53,8 @@ export function exampleStore(base = 'https://store.example') {
     const checkouts = new Map();
     const replies = new Map();
     const orders = [];
+    // Each order placed, by id: what was bought, as the order answers it.
+    const placed = new Map();
     const render = (checkout) => {
         let subtotal = 0;
         const lines = checkout.lines.map((line, index) => {
@@ -130,7 +132,13 @@ export function exampleStore(base = 'https://store.example') {
             checkouts.set(checkout.id, checkout);
             return { status: 201, body: render(checkout) };
         }
-        const [, , id, action] = path.split('/');
+        const [, collection, id, action] = path.split('/');
+        if (collection === 'orders') {
+            const order = method === 'GET' && !action ? placed.get(id) : undefined;
+            return order
+                ? { status: 200, body: order }
+                : { status: 404, body: { messages: [{ content: 'No such order' }] } };
+        }
         const checkout = checkouts.get(id);
         if (!checkout) {
             return { status: 404, body: { messages: [{ content: 'No checkout' }] } };
@@ -180,7 +188,24 @@ export function exampleStore(base = 'https://store.example') {
             checkout.status = 'completed';
             checkout.order = order;
             orders.push({ order: order.id, checkout: checkout.id });
-            return { status: 200, body: render(checkout) };
+            const rendered = render(checkout);
+            placed.set(order.id, {
+                ucp: { version: UCP_VERSION, status: 'success' },
+                id: order.id,
+                checkout_id: checkout.id,
+                permalink_url: order.permalink_url,
+                line_items: rendered.line_items.map((line) => ({
+                    id: line.id,
+                    item: line.item,
+                    quantity: { total: line.quantity, fulfilled: 0 },
+                    totals: line.totals,
+                    status: 'processing',
+                })),
+                fulfillment: { events: [] },
+                currency: rendered.currency,
+                totals: rendered.totals,
+            });
+            return { status: 200, body: rendered };
         }
         if (method === 'POST' && action === 'cancel') {
             if (checkout.status !== 'completed') {

package/lib/specs/actions.js

@@ -671,12 +671,11 @@ export const PROTOCOL_TOOL_CLASSES = {
     'agentic-commerce': {
         connection: 'acp',
         tools: {
-            propose_completion: ['read'],
-            get_checkout: ['read'],
-            create_checkout: ['write'],
-            update_checkout: ['write'],
-            cancel_checkout: ['write'],
-            complete: ['buy'],
+            acp_get_checkout: ['read'],
+            acp_create_checkout: ['write'],
+            acp_update_checkout: ['write'],
+            acp_cancel_checkout: ['write'],
+            acp_complete: ['buy'],
         },
     },
     pact: {
@@ -694,8 +693,8 @@ export const PROTOCOL_TOOL_CLASSES = {
         connection: 'pap',
         tools: {
             pap_company: ['read'],
-            pap_ask: ['read'],
-            pap_handoff: ['read'],
+            pap_ask: ['send'],
+            pap_handoff: ['send'],
             pap_sign_in: ['read'],
             pap_sign_in_status: ['read'],
             pap_read: ['read'],
@@ -708,13 +707,13 @@ export const PROTOCOL_TOOL_CLASSES = {
     ucp: {
         connection: 'ucp',
         tools: {
-            search: ['read'],
-            propose_completion: ['read'],
-            get_checkout: ['read'],
-            create_checkout: ['write'],
-            update_checkout: ['write'],
-            cancel_checkout: ['write'],
-            complete: ['buy'],
+            ucp_search: ['read'],
+            ucp_get_checkout: ['read'],
+            ucp_create_checkout: ['write'],
+            ucp_update_checkout: ['write'],
+            ucp_cancel_checkout: ['write'],
+            ucp_complete: ['buy'],
+            ucp_get_order: ['read'],
         },
     },
 };
@@ -775,6 +774,7 @@ export const APP_BEHAVIOURS = {
         'odoo-accounting.odoo_accounting_trial_balance': 'do_it',
         'odoo-accounting.odoo_accounting_unreconcile_lines': 'leave_to_me',
     },
+    'bookkeeping-desk': {},
     'change-detection': {
         'earthdata.download_earth_data_granules': 'leave_to_me',
         'earthdata.search_earth_datagranules': 'do_it',
@@ -917,6 +917,7 @@ export const APP_BEHAVIOURS = {
         'google-workspace.update_drive_file': 'leave_to_me',
         'google-workspace.update_paragraph_style': 'leave_to_me',
     },
+    'live-shop-chat': {},
     'model-choice': {},
     'month-end-close': {
         'odoo-accounting.odoo_accounting_aged_balance': 'do_it',
@@ -970,11 +971,16 @@ export const APP_BEHAVIOURS = {
         'odoo-accounting.odoo_accounting_unreconcile_lines': 'leave_to_me',
     },
     'order-desk': {},
+    'order-tracker': {},
     'pipeline-report': {},
     'quote-calculator': {},
     'report-from-a-file': {},
+    'returns-desk': {},
     sales: {},
     'ship-or-fix': {},
+    'shop-concierge': {},
+    'shopping-desk': {},
+    'sign-in-desk': {},
     'supplier-comparison': {},
     'support-desk': {},
     'travel-desk': {},
@@ -992,6 +998,7 @@ export const APP_BEHAVIOURS = {
  */
 export const APP_ESCALATIONS = {
     accounting: {},
+    'bookkeeping-desk': {},
     'change-detection': {},
     'crop-monitoring': {},
     'customer-interview': {},
@@ -1034,14 +1041,20 @@ export const APP_ESCALATIONS = {
             },
         ],
     },
+    'live-shop-chat': {},
     'model-choice': {},
     'month-end-close': {},
     'order-desk': {},
+    'order-tracker': {},
     'pipeline-report': {},
     'quote-calculator': {},
     'report-from-a-file': {},
+    'returns-desk': {},
     sales: {},
     'ship-or-fix': {},
+    'shop-concierge': {},
+    'shopping-desk': {},
+    'sign-in-desk': {},
     'supplier-comparison': {},
     'support-desk': {},
     'travel-desk': {},

package/lib/specs/apps.d.ts

@@ -9,6 +9,7 @@
  */
 import type { AppBuilt, AppKind, AppSpec } from '../types/agentspecs';
 export declare const ACCOUNTING_APP_0_0_1: AppSpec;
+export declare const BOOKKEEPING_DESK_APP_0_0_1: AppSpec;
 export declare const CHANGE_DETECTION_APP_0_0_1: AppSpec;
 export declare const CROP_MONITORING_APP_0_0_1: AppSpec;
 export declare const CUSTOMER_INTERVIEW_APP_0_0_1: AppSpec;
@@ -18,14 +19,20 @@ export declare const DISASTER_ASSESSMENT_APP_0_0_1: AppSpec;
 export declare const EVENT_RESPONSE_APP_0_0_1: AppSpec;
 export declare const EXCHANGE_DESK_APP_0_0_1: AppSpec;
 export declare const INBOX_TRIAGE_APP_0_0_1: AppSpec;
+export declare const LIVE_SHOP_CHAT_APP_0_0_1: AppSpec;
 export declare const MODEL_CHOICE_APP_0_0_1: AppSpec;
 export declare const MONTH_END_CLOSE_APP_0_0_1: AppSpec;
 export declare const ORDER_DESK_APP_0_0_1: AppSpec;
+export declare const ORDER_TRACKER_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 RETURNS_DESK_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 SHOP_CONCIERGE_APP_0_0_1: AppSpec;
+export declare const SHOPPING_DESK_APP_0_0_1: AppSpec;
+export declare const SIGN_IN_DESK_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;
 export declare const TRAVEL_DESK_APP_0_0_1: AppSpec;