@datalayer/agent-runtimes 1.4.0 → 1.5.1

package/lib/examples/protocols/ucpCheckoutDemo.js

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The *UCP checkout* gallery example's work (AGENT_PROTOCOLS EX-10, after
+ * EX-04): the UCP client buying from *Example Store*, the local test
+ * merchant running in the page (`protocols/ucp/merchant`). A checkout is
+ * proposed as an exact, revisioned purchase; completing it asks the host's
+ * approver — the page's card — once, and the proposal is spent whatever the
+ * answer. The payment is the test handler's; its token is never shown.
+ *
+ * @module examples/protocols/ucpCheckoutDemo
+ */
+import { contribution, definePlugin, } from '@datalayer/reactor';
+import { buildProtocolsReactor } from '../../protocols/agentProtocols';
+import { UcpApprovers, UcpClient, UcpPaymentInstruments, checkoutSummary, proposalSummary, } from '../../protocols/ucp';
+import { EXAMPLE_STORE_HANDLER_ID, exampleStore, } from '../../protocols/ucp/merchant';
+export const STORE = 'https://store.example';
+export const AGENT_PROFILE = 'https://agent.example/.well-known/ucp';
+/** The test payment's token: held by the host, never in a summary or a proposal. */
+export const TEST_TOKEN = 'tok_test_gallery_never_shown';
+/** The client, the store, and a host whose approver is `decide`. */
+export function ucpCheckoutDemo(decide) {
+    const store = exampleStore(STORE);
+    const host = definePlugin({
+        name: 'gallery-host',
+        contributes: [
+            contribution(UcpApprovers, { approve: decide }, { id: 'person', order: 10 }),
+            contribution(UcpPaymentInstruments, {
+                instrument: async () => ({
+                    id: 'pi_1',
+                    handler_id: EXAMPLE_STORE_HANDLER_ID,
+                    type: 'card',
+                    credential: { type: 'PAYMENT_GATEWAY', token: TEST_TOKEN },
+                }),
+            }, { id: 'custody', order: 10 }),
+        ],
+    });
+    return {
+        client: new UcpClient(STORE, AGENT_PROFILE, store.fetch),
+        reactor: buildProtocolsReactor([host]),
+        orders: store.orders,
+    };
+}
+/** Find the tea, put `quantity` in a checkout with the buyer's email, and propose it. */
+export async function proposeTea(demo, quantity = 2, email = 'ana@example.com') {
+    const [product] = await demo.client.search('sencha');
+    const created = await demo.client.createCheckout([
+        { id: product.id, quantity },
+    ]);
+    await demo.client.updateCheckout(created.id, { buyer: { email } });
+    const proposal = await demo.client.proposeCompletion(created.id);
+    return { proposal, says: proposalSummary(proposal) };
+}
+/** Complete the proposal: the approver is asked; the order, or why not. */
+export async function buy(demo, proposal) {
+    try {
+        const done = checkoutSummary(await demo.client.complete(proposal, demo.reactor));
+        return {
+            ok: true,
+            says: `Bought: order ${done.order?.id}, ${done.status}.`,
+        };
+    }
+    catch (error) {
+        return { ok: false, says: `Not bought: ${error.message}.` };
+    }
+}

package/lib/protocols/a2a/index.js

@@ -56,6 +56,7 @@ export const A2APlugin = definePlugin({
             status: 'implemented',
             specification: 'https://a2a-protocol.org/latest/specification/',
             plugin: A2A_PLUGIN,
+            catalogue: 'a2a',
             points: EXTENSION_POINTS.map(point => point.id),
         }, { id: 'a2a', order: DEFAULT_ORDER }),
         contribution(A2AOrchestrationExtensions, orchestration, {

package/lib/protocols/agentic-commerce/index.js

@@ -59,6 +59,7 @@ export const AgenticCommercePlugin = definePlugin({
             status: 'partial',
             specification: `https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/tree/main/spec/${AGENTIC_COMMERCE_VERSION}`,
             plugin: AGENTIC_COMMERCE_PLUGIN,
+            catalogue: 'acp',
             points: POINTS.map(point => point.id),
         }, { id: 'agentic_commerce', order: DEFAULT_ORDER }),
     ],

package/lib/protocols/core.d.ts

@@ -26,6 +26,12 @@ export interface ProtocolDescription {
     status: 'implemented' | 'partial' | 'planned';
     specification: string;
     plugin: string;
+    /**
+     * Its id in the agentspecs protocols catalogue (`agentspecs/protocols`,
+     * AGENT_PROTOCOLS PS-01): `web-bot-auth`, `acp`… — how Studio reads a
+     * runtime's answer against the catalogue (PR-50).
+     */
+    catalogue: string;
     /** The contribution points its plugin declares, its extensions' included. */
     points: string[];
 }

package/lib/protocols/mcp/index.js

@@ -31,6 +31,7 @@ export const McpPlugin = definePlugin({
             status: 'implemented',
             specification: 'https://modelcontextprotocol.io/specification',
             plugin: MCP_PLUGIN,
+            catalogue: 'mcp',
             points: [],
         }, { id: 'mcp', order: DEFAULT_ORDER }),
     ],

package/lib/protocols/pact/index.js

@@ -69,6 +69,7 @@ export const PactPlugin = definePlugin({
             status: 'partial',
             specification: 'https://github.com/openpactprotocol/openpactprotocol/blob/main/docs/spec.md',
             plugin: PACT_PLUGIN,
+            catalogue: 'pact',
             points: POINTS.map(point => point.id),
         }, { id: 'pact', order: DEFAULT_ORDER }),
         contribution(PactDelegatedProfiles, { grantType: DEVICE_CODE_GRANT }, { id: 'device-code', order: DEFAULT_ORDER }),

package/lib/protocols/ucp/index.js

@@ -64,6 +64,7 @@ export const UcpPlugin = definePlugin({
             status: 'partial',
             specification: `https://ucp.dev/${UCP_VERSION}/specification/overview`,
             plugin: UCP_PLUGIN,
+            catalogue: 'ucp',
             points: UCP_POINTS.map(point => point.id),
         }, { id: 'ucp', order: DEFAULT_ORDER }),
     ],

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

@@ -0,0 +1,15 @@
+/** The store's products, as the Python store lists them. */
+export declare const EXAMPLE_STORE_CATALOG: Record<string, {
+    title: string;
+    price: number;
+}>;
+/** The one payment handler it takes, and the prefix of its test tokens. */
+export declare const EXAMPLE_STORE_HANDLER_ID = "test_pay_1";
+/** The store: its `fetch`, and the orders it took. */
+export declare function exampleStore(base?: string): {
+    fetch: typeof fetch;
+    orders: Array<{
+        order: string;
+        checkout: string;
+    }>;
+};

package/lib/protocols/ucp/merchant.js

@@ -0,0 +1,257 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * *Example Store*, the local UCP test merchant, as a `fetch` (AGENT_PROTOCOLS
+ * EX-04, EX-10): the same catalogue, totals, email gate, idempotency and
+ * test payment as `agent_runtimes.protocols.ucp.merchant.ExampleStore`, so a
+ * page or a test buys from it with no network. A test merchant only: it keeps
+ * nothing beyond the page, and refuses any payment but its test handler's.
+ *
+ * @module protocols/ucp/merchant
+ */
+import { CHECKOUT_CAPABILITY, SHOPPING_SERVICE, UCP_VERSION } from './index';
+/** The store's products, as the Python store lists them. */
+export const EXAMPLE_STORE_CATALOG = {
+    tea_sencha: { title: 'Sencha green tea, 100 g', price: 1250 },
+    tea_assam: { title: 'Assam black tea, 250 g', price: 1800 },
+    mug: { title: 'Stoneware mug', price: 2400 },
+};
+/** The one payment handler it takes, and the prefix of its test tokens. */
+export const EXAMPLE_STORE_HANDLER_ID = 'test_pay_1';
+const TEST_TOKEN_PREFIX = 'tok_test_';
+const json = (body, status = 200) => new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+});
+const refuse = (status, code, content) => json({
+    ucp: { version: UCP_VERSION, status: 'error' },
+    messages: [{ type: 'error', code, content, severity: 'recoverable' }],
+}, status);
+const meta = () => ({
+    version: UCP_VERSION,
+    status: 'success',
+    capabilities: { [CHECKOUT_CAPABILITY]: [{ version: UCP_VERSION }] },
+    payment_handlers: {
+        'com.example.test_pay': [
+            {
+                id: EXAMPLE_STORE_HANDLER_ID,
+                version: UCP_VERSION,
+                available_instruments: [{ type: 'card' }],
+                config: {},
+            },
+        ],
+    },
+});
+async function fingerprint(path, body) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(path + body));
+    return Array.from(new Uint8Array(digest), b => b.toString(16).padStart(2, '0')).join('');
+}
+/** The store: its `fetch`, and the orders it took. */
+export function exampleStore(base = 'https://store.example') {
+    const checkouts = new Map();
+    const replies = new Map();
+    const orders = [];
+    const render = (checkout) => {
+        let subtotal = 0;
+        const lines = checkout.lines.map((line, index) => {
+            const product = EXAMPLE_STORE_CATALOG[line.id];
+            const amount = product.price * line.quantity;
+            subtotal += amount;
+            return {
+                id: `li_${index + 1}`,
+                item: { id: line.id, title: product.title, price: product.price },
+                quantity: line.quantity,
+                totals: [
+                    { type: 'subtotal', amount },
+                    { type: 'total', amount },
+                ],
+            };
+        });
+        const tax = Math.round(subtotal * 0.08);
+        const messages = [];
+        if (['incomplete', 'ready_for_complete'].includes(checkout.status)) {
+            checkout.status = checkout.buyer?.email
+                ? 'ready_for_complete'
+                : 'incomplete';
+            if (!checkout.buyer?.email) {
+                messages.push({
+                    type: 'error',
+                    code: 'missing',
+                    path: '$.buyer.email',
+                    content: 'Buyer email is required',
+                    severity: 'recoverable',
+                });
+            }
+        }
+        return {
+            ucp: meta(),
+            id: checkout.id,
+            status: checkout.status,
+            currency: 'USD',
+            line_items: lines,
+            totals: [
+                { type: 'subtotal', amount: subtotal },
+                { type: 'tax', amount: tax },
+                { type: 'total', amount: subtotal + tax },
+            ],
+            links: [{ type: 'terms_of_service', url: `${base}/terms` }],
+            expires_at: checkout.expiresAt,
+            ...(messages.length ? { messages } : {}),
+            ...(checkout.buyer?.email ? { buyer: checkout.buyer } : {}),
+            ...(checkout.order ? { order: checkout.order } : {}),
+        };
+    };
+    const linesOf = (body) => {
+        const lines = [];
+        for (const line of body.line_items ?? []) {
+            const id = line?.item?.id;
+            if (!(id in EXAMPLE_STORE_CATALOG)) {
+                return `No product ${id}`;
+            }
+            lines.push({ id, quantity: Number(line.quantity ?? 1) });
+        }
+        return lines;
+    };
+    const handle = (method, path, body) => {
+        if (method === 'POST' && path === '/checkout-sessions') {
+            const lines = linesOf(body);
+            if (typeof lines === 'string') {
+                return { status: 404, body: { messages: [{ content: lines }] } };
+            }
+            const checkout = {
+                id: `chk_${crypto.randomUUID().slice(0, 12)}`,
+                status: 'incomplete',
+                lines,
+                buyer: body.buyer ?? {},
+                expiresAt: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
+            };
+            checkouts.set(checkout.id, checkout);
+            return { status: 201, body: render(checkout) };
+        }
+        const [, , id, action] = path.split('/');
+        const checkout = checkouts.get(id);
+        if (!checkout) {
+            return { status: 404, body: { messages: [{ content: 'No checkout' }] } };
+        }
+        if (method === 'PUT' && !action) {
+            if (!['incomplete', 'ready_for_complete'].includes(checkout.status)) {
+                return { status: 409, body: render(checkout) };
+            }
+            if (body.buyer) {
+                checkout.buyer = body.buyer;
+            }
+            if (body.line_items) {
+                const lines = linesOf(body);
+                if (typeof lines === 'string') {
+                    return { status: 404, body: { messages: [{ content: lines }] } };
+                }
+                checkout.lines = lines;
+            }
+            return { status: 200, body: render(checkout) };
+        }
+        if (method === 'POST' && action === 'complete') {
+            if (checkout.status !== 'ready_for_complete') {
+                return { status: 200, body: render(checkout) };
+            }
+            const [instrument] = body.payment?.instruments ?? [{}];
+            const token = String(instrument?.credential?.token ?? '');
+            if (instrument?.handler_id !== EXAMPLE_STORE_HANDLER_ID ||
+                !token.startsWith(TEST_TOKEN_PREFIX)) {
+                return {
+                    status: 402,
+                    body: {
+                        ucp: { version: UCP_VERSION, status: 'error' },
+                        messages: [
+                            {
+                                type: 'error',
+                                code: 'payment_declined',
+                                content: 'The payment was declined',
+                            },
+                        ],
+                    },
+                };
+            }
+            const order = {
+                id: `ord_${crypto.randomUUID().slice(0, 10)}`,
+                permalink_url: `${base}/orders/${checkout.id}`,
+            };
+            checkout.status = 'completed';
+            checkout.order = order;
+            orders.push({ order: order.id, checkout: checkout.id });
+            return { status: 200, body: render(checkout) };
+        }
+        if (method === 'POST' && action === 'cancel') {
+            if (checkout.status !== 'completed') {
+                checkout.status = 'canceled';
+            }
+            return { status: 200, body: render(checkout) };
+        }
+        if (method === 'GET' && !action) {
+            return { status: 200, body: render(checkout) };
+        }
+        return { status: 405, body: {} };
+    };
+    const fetchImpl = (async (input, init) => {
+        const url = new URL(String(input));
+        if (url.pathname === '/.well-known/ucp') {
+            return json({
+                ucp: {
+                    version: UCP_VERSION,
+                    services: {
+                        [SHOPPING_SERVICE]: [
+                            {
+                                version: UCP_VERSION,
+                                transport: 'rest',
+                                endpoint: `${base}/ucp/v1`,
+                            },
+                        ],
+                    },
+                    capabilities: { [CHECKOUT_CAPABILITY]: [{ version: UCP_VERSION }] },
+                    payment_handlers: meta().payment_handlers,
+                },
+            });
+        }
+        const headers = new Headers(init?.headers);
+        const agent = headers.get('UCP-Agent') ?? '';
+        if (!/^profile="https:\/\/[^"]+"$/.test(agent)) {
+            return refuse(400, 'invalid_ucp_agent', 'UCP-Agent names its profile over https');
+        }
+        if (!headers.get('Request-Id')) {
+            return refuse(400, 'missing_request_id', 'Request-Id is required');
+        }
+        const method = (init?.method ?? 'GET').toUpperCase();
+        const path = url.pathname.replace(/^\/ucp\/v1/, '');
+        const raw = typeof init?.body === 'string' ? init.body : '';
+        const body = raw ? JSON.parse(raw) : {};
+        if (path === '/catalog/search') {
+            const query = String(body.query ?? '').toLowerCase();
+            return json({
+                ucp: { version: UCP_VERSION },
+                products: Object.entries(EXAMPLE_STORE_CATALOG)
+                    .filter(([, product]) => product.title.toLowerCase().includes(query))
+                    .map(([id, product]) => ({ id, title: product.title })),
+            });
+        }
+        if (method === 'GET') {
+            const answer = handle(method, path, body);
+            return json(answer.body, answer.status);
+        }
+        const key = headers.get('Idempotency-Key');
+        if (!key) {
+            return refuse(400, 'missing_idempotency_key', 'Idempotency-Key is required');
+        }
+        const seen = await fingerprint(url.pathname, raw);
+        const replied = replies.get(key);
+        if (replied) {
+            return replied.seen === seen
+                ? json(replied.body, replied.status)
+                : refuse(409, 'idempotency_conflict', 'the key was used for another request');
+        }
+        const answer = handle(method, path, body);
+        replies.set(key, { seen, ...answer });
+        return json(answer.body, answer.status);
+    });
+    return { fetch: fetchImpl, orders };
+}

package/lib/protocols/web-bot-auth/index.js

@@ -324,6 +324,7 @@ export const WebBotAuthPlugin = definePlugin({
             status: 'implemented',
             specification: 'https://datatracker.ietf.org/doc/draft-ietf-webbotauth-httpsig-protocol/',
             plugin: WEB_BOT_AUTH_PLUGIN,
+            catalogue: 'web-bot-auth',
             points: WEB_BOT_AUTH_POINTS.map(point => point.id),
         }, { id: 'web_bot_auth', order: DEFAULT_ORDER }),
         contribution(WebBotAuthDirectoryDiscoveries, directoryDiscovery(), {