@datalayer/agent-runtimes 1.3.111 → 1.3.113

package/lib/protocols/pact/index.js

@@ -0,0 +1,363 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * PACT 1.0, Personal Agent Consent & Trust, as a Reactor Plugin and a
+ * personal agent (AGENT_PROTOCOLS PR-10 to PR-13) — the twin of
+ * `agent_runtimes.protocols.pact`. Built against
+ * `openpactprotocol/openpactprotocol` `docs/spec.md` at 838c6bd
+ * (2026-10-06), reviewed 2026-10-12.
+ *
+ * The personal-agent JWT (§3.2) is signed by the host's key through
+ * `pact.signer` (ES256, the Web Bot Auth signer's contract); the delegation
+ * token (§5) is kept in `pact.delegationStore`, never handed to the agent;
+ * every receipt (§5.6) is verified with `jose` before it is kept in
+ * `pact.receiptStore`.
+ *
+ * @module protocols/pact
+ */
+import { contribution, defineContributionPoint, definePlugin, } from '@datalayer/reactor';
+import { compactVerify, importJWK } from 'jose';
+import { DEFAULT_ORDER, ProtocolDescriptions, firstContribution, } from '../core';
+export const PACT_VERSION = '1.0';
+export const PACT_PLUGIN = 'agent-runtimes.protocols.pact';
+export const DELEGATION_HEADER = 'X-A2A-User-Delegation';
+export const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+export class PactError extends Error {
+}
+export class InMemoryDelegationStore {
+    held = new Map();
+    async put(brand, user, token, scopes) {
+        this.held.set(`${brand} ${user}`, { token, scopes });
+    }
+    async get(brand, user) {
+        return this.held.get(`${brand} ${user}`);
+    }
+    async delete(brand, user) {
+        this.held.delete(`${brand} ${user}`);
+    }
+}
+export class InMemoryReceiptStore {
+    receipts = [];
+    async keep(brand, user, claims) {
+        this.receipts.push({ brand, user, claims });
+    }
+}
+export const PactSigners = defineContributionPoint('pact.signer');
+export const PactDelegationStores = defineContributionPoint('pact.delegationStore');
+export const PactReceiptStores = defineContributionPoint('pact.receiptStore');
+export const PactDelegatedProfiles = defineContributionPoint('pact.extension.delegated');
+const POINTS = [
+    PactSigners,
+    PactDelegationStores,
+    PactReceiptStores,
+    PactDelegatedProfiles,
+];
+export const PactPlugin = definePlugin({
+    name: PACT_PLUGIN,
+    version: '1.0.0',
+    description: `PACT ${PACT_VERSION}: a personal agent at a business, and what the person let it do.`,
+    contributionPoints: POINTS,
+    contributes: [
+        contribution(ProtocolDescriptions, {
+            id: 'pact',
+            name: 'Personal Agent Consent & Trust',
+            layer: 'consent',
+            version: PACT_VERSION,
+            roles: ['personal-agent', 'provider'],
+            status: 'partial',
+            specification: 'https://github.com/openpactprotocol/openpactprotocol/blob/main/docs/spec.md',
+            plugin: PACT_PLUGIN,
+            points: POINTS.map(point => point.id),
+        }, { id: 'pact', order: DEFAULT_ORDER }),
+        contribution(PactDelegatedProfiles, { grantType: DEVICE_CODE_GRANT }, { id: 'device-code', order: DEFAULT_ORDER }),
+    ],
+    // Stores are state: one per reactor, not one per module.
+    register: ctx => {
+        ctx.contribute(PactDelegationStores, new InMemoryDelegationStore(), {
+            id: 'memory',
+            order: DEFAULT_ORDER,
+        });
+        ctx.contribute(PactReceiptStores, new InMemoryReceiptStore(), {
+            id: 'memory',
+            order: DEFAULT_ORDER,
+        });
+    },
+});
+const READ_VERBS = new Set(['read', 'view', 'list', 'status', 'lookup']);
+function actionClassOf(id) {
+    const verb = id.split(':').pop()?.toLowerCase() ?? '';
+    return READ_VERBS.has(verb) ? 'read' : 'write';
+}
+function bearer(scheme) {
+    return (String(scheme?.httpAuthSecurityScheme?.scheme ?? '').toLowerCase() ===
+        'bearer');
+}
+/** A Brand's card as PACT 1.0 reads it (§2.1, §5.1); throws when it is not one. */
+export function readCard(card) {
+    const iface = (card.supportedInterfaces ?? []).find((entry) => entry.protocolBinding === 'HTTP+JSON' && entry.protocolVersion === '1.0');
+    if (!iface) {
+        throw new PactError('the card offers no HTTP+JSON 1.0 interface');
+    }
+    const schemes = card.securitySchemes ?? {};
+    const requirements = (card.securityRequirements ?? []).map((entry) => Object.keys(entry.schemes ?? {}));
+    const alone = requirements.find(names => names.length === 1 && bearer(schemes[names[0]]));
+    if (!alone) {
+        throw new PactError('the card does not ask for the personal-agent JWT alone');
+    }
+    const identity = alone[0];
+    let delegation;
+    for (const names of requirements) {
+        if (names.length !== 2 || !names.includes(identity)) {
+            continue;
+        }
+        const oauth = schemes[names.find(name => name !== identity)]?.oauth2SecurityScheme;
+        const device = oauth?.flows?.deviceCode;
+        if (!oauth || !device) {
+            continue;
+        }
+        if (!oauth.oauth2MetadataUrl) {
+            throw new PactError('the delegation names no RFC 8414 metadata');
+        }
+        delegation = {
+            deviceAuthorizationUrl: device.deviceAuthorizationUrl,
+            tokenUrl: device.tokenUrl,
+            metadataUrl: oauth.oauth2MetadataUrl,
+            scopes: Object.entries(device.scopes ?? {}).map(([id, description]) => ({
+                id,
+                description: String(description),
+                actionClass: actionClassOf(id),
+            })),
+        };
+        break;
+    }
+    return {
+        name: String(card.name ?? ''),
+        interfaceUrl: String(iface.url).replace(/\/$/, ''),
+        identityScheme: identity,
+        profile: delegation ? 'delegated' : 'identity',
+        delegation,
+    };
+}
+function b64url(bytes) {
+    let text = '';
+    for (const byte of bytes) {
+        text += String.fromCharCode(byte);
+    }
+    return btoa(text).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** One personal-agent JWT (§3.2): ES256 by the host's signer, `sub` opaque, ≤ 300 s. */
+export async function signPersonalAgentJwt(signer, claims) {
+    if (signer.algorithm !== 'ecdsa-p256-sha256') {
+        throw new PactError('a personal-agent JWT is signed ES256 here (a P-256 key)');
+    }
+    if (!claims.subject || claims.subject.includes('@')) {
+        throw new PactError('`sub` is a stable, opaque id: never an address');
+    }
+    const lifetime = claims.lifetime ?? 120;
+    if (lifetime > 300) {
+        throw new PactError('a personal-agent JWT lives at most 300 seconds');
+    }
+    const now = Math.floor(Date.now() / 1000);
+    const encode = (value) => b64url(new TextEncoder().encode(JSON.stringify(value)));
+    const input = `${encode({ alg: 'ES256', kid: signer.keyid, typ: 'JWT' })}.${encode({
+        iss: claims.issuer,
+        sub: claims.subject,
+        aud: claims.audience,
+        iat: now,
+        exp: now + lifetime,
+        jti: crypto.randomUUID(),
+    })}`;
+    const signature = await signer.sign(new TextEncoder().encode(input));
+    return `${input}.${b64url(signature)}`;
+}
+/** A personal agent at one Brand. */
+export class PactPersonalAgent {
+    options;
+    card;
+    pending = new Map();
+    jwks;
+    constructor(options) {
+        this.options = options;
+    }
+    get fetch() {
+        return this.options.fetchImpl ?? ((input, init) => fetch(input, init));
+    }
+    jwt(user) {
+        const signer = firstContribution(this.options.reactor, PactSigners, 'PACT signer');
+        return signPersonalAgentJwt(signer, {
+            issuer: this.options.issuer,
+            subject: user,
+            audience: this.options.audience,
+        });
+    }
+    delegations() {
+        return firstContribution(this.options.reactor, PactDelegationStores, 'PACT delegation store');
+    }
+    async discover() {
+        const answer = await this.fetch(this.options.cardUrl);
+        if (answer.status !== 200) {
+            throw new PactError(`the card answered ${answer.status}`);
+        }
+        this.card = readCard(await answer.json());
+        return this.card;
+    }
+    async send(user, text, options = {}) {
+        const card = this.card ?? (await this.discover());
+        const headers = {
+            Authorization: `Bearer ${await this.jwt(user)}`,
+            'A2A-Version': '1.0',
+            'Content-Type': 'application/json',
+        };
+        const held = await this.delegations().get(card.interfaceUrl, user);
+        if (held) {
+            headers[DELEGATION_HEADER] = `Bearer ${held.token}`;
+        }
+        const answer = await this.fetch(`${card.interfaceUrl}/message:send`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                message: {
+                    messageId: options.messageId ?? crypto.randomUUID(),
+                    role: 'ROLE_USER',
+                    parts: [{ text }],
+                    ...(options.contextId ? { contextId: options.contextId } : {}),
+                },
+            }),
+        });
+        if (answer.status === 401) {
+            throw new PactError('the Brand refused the personal agent’s identity or its delegation');
+        }
+        const body = await answer.json();
+        if (body.error) {
+            throw new PactError(`${body.error.details?.[0]?.reason ?? body.error.status}: ${body.error.message}`);
+        }
+        if (body.task) {
+            const meta = body.task.metadata ?? {};
+            return {
+                kind: 'step-up',
+                text: (body.task.status?.message?.parts ?? [])
+                    .map((p) => p.text)
+                    .join(' '),
+                contextId: body.task.contextId,
+                missing: meta['pact.missingScopes'] ?? [],
+                verificationUri: meta['pact.verificationUriComplete'] ?? '',
+            };
+        }
+        const reply = body.message;
+        let claims = {};
+        if (held) {
+            const receipt = reply.metadata?.['pact.receipt'];
+            if (!receipt) {
+                throw new PactError('a reply under delegation carries no receipt');
+            }
+            claims = await this.verifyReceipt(receipt);
+            await firstContribution(this.options.reactor, PactReceiptStores, 'PACT receipt store').keep(card.interfaceUrl, user, claims);
+        }
+        return {
+            kind: 'reply',
+            text: (reply.parts ?? []).map((p) => p.text).join(' '),
+            contextId: reply.contextId,
+            scopesUsed: claims.scopesUsed ?? [],
+            actions: (claims.actions ?? []).map((a) => a.tool),
+        };
+    }
+    async verifyReceipt(receipt) {
+        const card = this.card;
+        if (!this.jwks) {
+            const metadata = await (await this.fetch(card.delegation.metadataUrl)).json();
+            this.jwks = await (await this.fetch(metadata.jwks_uri)).json();
+        }
+        const kid = JSON.parse(atob(receipt.jws.split('.')[0].replace(/-/g, '+').replace(/_/g, '/'))).kid;
+        const jwk = this.jwks.keys.find(key => key.kid === kid);
+        if (!jwk) {
+            throw new PactError('no key of the Brand signs this receipt');
+        }
+        const { payload } = await compactVerify(receipt.jws, await importJWK(jwk, 'ES256'));
+        const claims = JSON.parse(new TextDecoder().decode(payload));
+        if (JSON.stringify(claims) !== JSON.stringify(receipt.claims)) {
+            throw new PactError('the receipt’s claims are not the ones it signs');
+        }
+        return claims;
+    }
+    async requestSignIn(user, scopes) {
+        const card = this.card ?? (await this.discover());
+        if (!card.delegation) {
+            throw new PactError('the Brand offers no delegation');
+        }
+        const offered = new Set(card.delegation.scopes.map(scope => scope.id));
+        const unknown = scopes.filter(scope => !offered.has(scope));
+        if (unknown.length) {
+            throw new PactError(`not on the card: ${unknown.join(', ')}`);
+        }
+        const answer = await this.fetch(card.delegation.deviceAuthorizationUrl, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${await this.jwt(user)}`,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: new URLSearchParams({
+                client_id: this.options.issuer,
+                scope: scopes.join(' '),
+            }).toString(),
+        });
+        if (answer.status !== 200) {
+            throw new PactError(`device authorization answered ${answer.status}`);
+        }
+        const body = await answer.json();
+        const reference = crypto.randomUUID();
+        this.pending.set(reference, body.device_code);
+        return {
+            verificationUri: body.verification_uri_complete ?? body.verification_uri,
+            userCode: body.user_code,
+            expiresIn: body.expires_in,
+            reference,
+        };
+    }
+    /** Ask once whether the person approved: the scopes granted, or `undefined` while pending. */
+    async pollSignIn(user, signIn) {
+        const card = this.card;
+        const deviceCode = this.pending.get(signIn.reference);
+        if (!deviceCode) {
+            throw new PactError('no sign-in pending under this reference');
+        }
+        const answer = await this.fetch(card.delegation.tokenUrl, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${await this.jwt(user)}`,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: new URLSearchParams({
+                grant_type: DEVICE_CODE_GRANT,
+                device_code: deviceCode,
+                client_id: this.options.issuer,
+            }).toString(),
+        });
+        const body = await answer.json();
+        if (body.error === 'authorization_pending' || body.error === 'slow_down') {
+            return undefined;
+        }
+        if (body.error) {
+            this.pending.delete(signIn.reference);
+            throw new PactError(`the sign-in ended: ${body.error}`);
+        }
+        const granted = String(body.scope ?? '')
+            .split(' ')
+            .filter(Boolean);
+        await this.delegations().put(card.interfaceUrl, user, body.access_token, granted);
+        this.pending.delete(signIn.reference);
+        return granted;
+    }
+    /** Poll until the person approved; the scopes they actually granted. */
+    async finishSignIn(user, signIn, intervalMs = 5000, attempts = 120) {
+        for (let i = 0; i < attempts; i++) {
+            const granted = await this.pollSignIn(user, signIn);
+            if (granted) {
+                return granted;
+            }
+            await new Promise(resolve => setTimeout(resolve, intervalMs));
+        }
+        throw new PactError('the person did not sign in in time');
+    }
+}

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

@@ -0,0 +1,79 @@
+/**
+ * The Universal Commerce Protocol, `2026-08-25`, as a Reactor Plugin and a
+ * shopping client (AGENT_PROTOCOLS PR-30, PR-31) — the twin of
+ * `agent_runtimes.protocols.ucp`.
+ *
+ * Checkouts are read through the protocol's own TypeScript SDK
+ * (`@ucp-js/sdk` 0.5.1, zod schemas generated from the same JSON Schemas).
+ * A purchase is an exact, revisioned proposal (`proposeCompletion`), approved
+ * by the person through the host's `ucp.approver`, paid with the host's
+ * `ucp.paymentInstruments`, completed once (`ucp.proposalStore`).
+ *
+ * @module protocols/ucp
+ */
+import { type ReactorPlatformView } from '@datalayer/reactor';
+import { type CheckoutApprover, type CheckoutProposal, type ProposalStore } from '../commerce';
+export declare const UCP_VERSION = "2026-08-25";
+export declare const SHOPPING_SERVICE = "dev.ucp.shopping";
+export declare const CHECKOUT_CAPABILITY = "dev.ucp.shopping.checkout";
+export declare const PROFILE_PATH = "/.well-known/ucp";
+export declare const UCP_PLUGIN = "agent-runtimes.protocols.ucp";
+/** Each operation's action class (F-10), for Rules (R-05). */
+export declare const UCP_ACTION_CLASSES: {
+    readonly search: "read";
+    readonly proposeCompletion: "read";
+    readonly getCheckout: "read";
+    readonly createCheckout: "write";
+    readonly updateCheckout: "write";
+    readonly cancelCheckout: "write";
+    readonly complete: "buy";
+};
+export { InMemoryProposalStore, proposalSummary, type CheckoutApprover, type CheckoutProposal, type ProposalStore, } from '../commerce';
+export declare class UcpError extends Error {
+}
+type Json = Record<string, any>;
+export interface PaymentInstruments {
+    instrument(proposal: CheckoutProposal, handlers: Json): Promise<Json>;
+}
+export interface UcpExtension {
+    capability: string;
+    version: string;
+}
+export declare const UcpApprovers: import("@datalayer/reactor").ContributionPoint<CheckoutApprover>;
+export declare const UcpPaymentInstruments: import("@datalayer/reactor").ContributionPoint<PaymentInstruments>;
+export declare const UcpProposalStores: import("@datalayer/reactor").ContributionPoint<ProposalStore>;
+export declare const UcpFulfillmentExtensions: import("@datalayer/reactor").ContributionPoint<UcpExtension>;
+export declare const UcpDiscountExtensions: import("@datalayer/reactor").ContributionPoint<UcpExtension>;
+export declare const UcpBuyerConsentExtensions: import("@datalayer/reactor").ContributionPoint<UcpExtension>;
+export declare const UcpPlugin: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;
+/** The capabilities in use with a business: checkout, and the extensions both support. */
+export declare function negotiateCapabilities(profile: Json, reactor: ReactorPlatformView): string[];
+/** The revision of what a checkout buys; the same digest as Python's `revision_of`. */
+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;
+/** A platform's client of one business, over the REST binding. */
+export declare class UcpClient {
+    private readonly business;
+    private readonly agentProfile;
+    private readonly fetchImpl;
+    private endpoint?;
+    private domain;
+    constructor(business: string, agentProfile: string, fetchImpl?: typeof fetch);
+    private headers;
+    /** Read the business's profile: the version, shopping over REST, checkout. */
+    discover(): Promise<Json>;
+    private call;
+    search(query: string, limit?: number): Promise<Json[]>;
+    createCheckout(lines: Array<{
+        id: string;
+        quantity?: number;
+    }>, buyer?: Json): Promise<Json>;
+    updateCheckout(id: string, update: Json): Promise<Json>;
+    getCheckout(id: string): Promise<Json>;
+    cancelCheckout(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. */
+    complete(proposal: CheckoutProposal, reactor: ReactorPlatformView): Promise<Json>;
+}