@datalayer/agent-runtimes 1.3.111 → 1.3.112

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

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+// GENERATED — do not edit. The Agentic Commerce Protocol 2026-04-17, its checkout
+// types: json-schema-to-typescript 15.0.4 over
+// agentic-commerce-protocol/agentic-commerce-protocol spec/2026-04-17/json-schema/
+// schema.agentic_checkout.json (Apache 2.0). Regenerate with
+// scripts/codegen/generate_agentic_commerce.sh.
+export const AGENTIC_COMMERCE_VERSION = '2026-04-17';

package/lib/protocols/commerce.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What every commerce protocol shares (AGENT_PROTOCOLS §3, one approval
+ * model) — the twin of `agent_runtimes.protocols.commerce`. A purchase over
+ * UCP or the Agentic Commerce Protocol is an exact, revisioned
+ * {@link CheckoutProposal}, approved by the person through the host's
+ * {@link CheckoutApprover} (contributed to each plugin's `<protocol>.approver`),
+ * and completed once ({@link ProposalStore}).
+ *
+ * @module protocols/commerce
+ */
+type Json = Record<string, any>;
+/** One exact purchase, proposed to a person before it is made. */
+export interface CheckoutProposal {
+    id: string;
+    merchant: string;
+    checkoutId: string;
+    /** SHA-256 of what is bought: lines, prices, quantities, totals, currency. */
+    revision: string;
+    currency: string;
+    total: number;
+    lines: Array<{
+        title: string;
+        quantity: number;
+        price: number;
+    }>;
+    expiresAt?: string;
+}
+/** A proposal in words, for the person and the model: never a credential. */
+export declare function proposalSummary(proposal: CheckoutProposal): string;
+export interface CheckoutApprover {
+    approve(proposal: CheckoutProposal): Promise<boolean>;
+}
+export interface ProposalStore {
+    take(proposalId: string): Promise<boolean>;
+}
+export declare class InMemoryProposalStore implements ProposalStore {
+    private taken;
+    take(proposalId: string): Promise<boolean>;
+}
+/** The SHA-256 of a canonical JSON (sorted keys, no spaces): a proposal's revision. */
+export declare function digest(what: Json): Promise<string>;
+export {};

package/lib/protocols/commerce.js

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** A proposal in words, for the person and the model: never a credential. */
+export function proposalSummary(proposal) {
+    const items = proposal.lines
+        .map(line => `${line.quantity} × ${line.title}`)
+        .join(', ');
+    const amount = (proposal.total / 100).toLocaleString('en-US', {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+    });
+    return `Buy ${items} at ${proposal.merchant} for ${proposal.currency} ${amount}`;
+}
+export class InMemoryProposalStore {
+    taken = new Set();
+    async take(proposalId) {
+        if (this.taken.has(proposalId)) {
+            return false;
+        }
+        this.taken.add(proposalId);
+        return true;
+    }
+}
+/** The SHA-256 of a canonical JSON (sorted keys, no spaces): a proposal's revision. */
+export function digest(what) {
+    return sha256(canonical(what));
+}
+async function sha256(text) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return [...new Uint8Array(digest)]
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+function canonical(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonical).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        return `{${Object.keys(value)
+            .sort()
+            .map(key => `${JSON.stringify(key)}:${canonical(value[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value ?? null);
+}

package/lib/protocols/core.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The agent protocols, each a Reactor Plugin (AGENT_PROTOCOLS §3.1, decided
+ * 2026-10-12) — the TypeScript twin of `agent_runtimes.protocols`.
+ *
+ * Every protocol is a Plugin declaring its Contribution Points
+ * (`<protocol>.<point>`), its defaults contributed at order 100 that a host
+ * replaces with a lower order; every extension a protocol defines is a
+ * Contribution Point of its plugin (`<protocol>.extension.<name>`), an
+ * implementation a Contribution to it. The `agent-protocols` Reactor
+ * Extension only groups the plugins for delivery. Each protocol's
+ * `reactor-points.json` holds both languages to the same points.
+ *
+ * @module protocols/core
+ */
+import { type ContributionPoint, type ReactorPlatformView } from '@datalayer/reactor';
+/** The order of a plugin's own defaults; a host contributes lower to replace one. */
+export declare const DEFAULT_ORDER = 100;
+/** One protocol as its plugin implements it. */
+export interface ProtocolDescription {
+    id: string;
+    name: string;
+    layer: 'transport' | 'consent' | 'identity' | 'commerce';
+    /** The specification version implemented. */
+    version: string;
+    roles: string[];
+    status: 'implemented' | 'partial' | 'planned';
+    specification: string;
+    plugin: string;
+    /** The contribution points its plugin declares, its extensions' included. */
+    points: string[];
+}
+/** Where each protocol plugin says what it is. */
+export declare const ProtocolDescriptions: ContributionPoint<ProtocolDescription>;
+/** The plugin that declares {@link ProtocolDescriptions}; it contributes nothing. */
+export declare const ProtocolsCorePlugin: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;
+/**
+ * The lowest-order contribution to a single-provider point. None, or two at
+ * the same winning order, fails closed.
+ */
+export declare function firstContribution<T>(reactor: ReactorPlatformView, point: ContributionPoint<T>, label: string): T;
+/** As {@link firstContribution}, `undefined` when nothing is contributed. */
+export declare function optionalContribution<T>(reactor: ReactorPlatformView, point: ContributionPoint<T>, label: string): T | undefined;
+/** What the protocol plugins say they are, one per protocol, by id. */
+export declare function listProtocols(reactor: ReactorPlatformView): ProtocolDescription[];

package/lib/protocols/core.js

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The agent protocols, each a Reactor Plugin (AGENT_PROTOCOLS §3.1, decided
+ * 2026-10-12) — the TypeScript twin of `agent_runtimes.protocols`.
+ *
+ * Every protocol is a Plugin declaring its Contribution Points
+ * (`<protocol>.<point>`), its defaults contributed at order 100 that a host
+ * replaces with a lower order; every extension a protocol defines is a
+ * Contribution Point of its plugin (`<protocol>.extension.<name>`), an
+ * implementation a Contribution to it. The `agent-protocols` Reactor
+ * Extension only groups the plugins for delivery. Each protocol's
+ * `reactor-points.json` holds both languages to the same points.
+ *
+ * @module protocols/core
+ */
+import { defineContributionPoint, definePlugin, } from '@datalayer/reactor';
+/** The order of a plugin's own defaults; a host contributes lower to replace one. */
+export const DEFAULT_ORDER = 100;
+/** Where each protocol plugin says what it is. */
+export const ProtocolDescriptions = defineContributionPoint('protocols.description');
+/** The plugin that declares {@link ProtocolDescriptions}; it contributes nothing. */
+export const ProtocolsCorePlugin = definePlugin({
+    name: 'agent-runtimes.protocols',
+    version: '1.0.0',
+    description: 'What the agent protocols say they are.',
+    contributionPoints: [ProtocolDescriptions],
+});
+/**
+ * The lowest-order contribution to a single-provider point. None, or two at
+ * the same winning order, fails closed.
+ */
+export function firstContribution(reactor, point, label) {
+    const contributions = reactor.getContributions(point);
+    const [first, second] = contributions;
+    if (!first) {
+        throw new Error(`no ${label} is contributed (${point.id})`);
+    }
+    if (second && second.order === first.order) {
+        throw new Error(`two ${label}s are contributed at the same order (${point.id})`);
+    }
+    return first.value;
+}
+/** As {@link firstContribution}, `undefined` when nothing is contributed. */
+export function optionalContribution(reactor, point, label) {
+    if (!reactor.getContributions(point).length) {
+        return undefined;
+    }
+    return firstContribution(reactor, point, label);
+}
+/** What the protocol plugins say they are, one per protocol, by id. */
+export function listProtocols(reactor) {
+    const byId = new Map();
+    for (const contribution of [
+        ...reactor.getContributions(ProtocolDescriptions),
+    ].reverse()) {
+        byId.set(contribution.value.id, contribution.value);
+    }
+    return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}

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

@@ -0,0 +1,4 @@
+export declare const MCP_PLUGIN = "agent-runtimes.protocols.mcp";
+/** The MCP specification version of the `@modelcontextprotocol/sdk` installed (1.32: `LATEST_PROTOCOL_VERSION`); Python's `mcp` 2.1 speaks 2026-07-28. */
+export declare const MCP_SPECIFICATION_VERSION = "2025-11-25";
+export declare const McpPlugin: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;

package/lib/protocols/mcp/index.js

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * MCP as a Reactor Plugin. It says what it is on `protocols.description` and
+ * declares no point yet: MCP's optional capabilities and extensions become
+ * `mcp.extension.<name>` points when the MCP client and server read them
+ * from contributions (AGENT_PROTOCOLS PR-01). The twin of
+ * `agent_runtimes.protocols.mcp`.
+ *
+ * @module protocols/mcp
+ */
+import { contribution, definePlugin } from '@datalayer/reactor';
+import { DEFAULT_ORDER, ProtocolDescriptions } from '../core';
+export const MCP_PLUGIN = 'agent-runtimes.protocols.mcp';
+/** The MCP specification version of the `@modelcontextprotocol/sdk` installed (1.32: `LATEST_PROTOCOL_VERSION`); Python's `mcp` 2.1 speaks 2026-07-28. */
+export const MCP_SPECIFICATION_VERSION = '2025-11-25';
+export const McpPlugin = definePlugin({
+    name: MCP_PLUGIN,
+    version: '1.0.0',
+    description: 'Model Context Protocol: tools, resources and prompts.',
+    contributionPoints: [],
+    contributes: [
+        contribution(ProtocolDescriptions, {
+            id: 'mcp',
+            name: 'Model Context Protocol',
+            layer: 'transport',
+            version: MCP_SPECIFICATION_VERSION,
+            roles: ['client', 'server'],
+            status: 'implemented',
+            specification: 'https://modelcontextprotocol.io/specification',
+            plugin: MCP_PLUGIN,
+            points: [],
+        }, { id: 'mcp', order: DEFAULT_ORDER }),
+    ],
+});

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

@@ -0,0 +1,139 @@
+/**
+ * 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 { type ReactorPlatformView } from '@datalayer/reactor';
+import type { HttpSigner } from '../web-bot-auth';
+export declare const PACT_VERSION = "1.0";
+export declare const PACT_PLUGIN = "agent-runtimes.protocols.pact";
+export declare const DELEGATION_HEADER = "X-A2A-User-Delegation";
+export declare const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+type Json = Record<string, any>;
+export declare class PactError extends Error {
+}
+/** A scope a Brand offers, and its action class (F-10): unknown is the most restricted. */
+export interface PactScope {
+    id: string;
+    description: string;
+    actionClass: 'read' | 'write';
+}
+export interface PactCard {
+    name: string;
+    interfaceUrl: string;
+    identityScheme: string;
+    profile: 'identity' | 'delegated';
+    delegation?: {
+        deviceAuthorizationUrl: string;
+        tokenUrl: string;
+        metadataUrl: string;
+        scopes: PactScope[];
+    };
+}
+export interface DelegationStore {
+    put(brand: string, user: string, token: string, scopes: string[]): Promise<void>;
+    get(brand: string, user: string): Promise<{
+        token: string;
+        scopes: string[];
+    } | undefined>;
+    delete(brand: string, user: string): Promise<void>;
+}
+export interface ReceiptStore {
+    keep(brand: string, user: string, claims: Json): Promise<void>;
+}
+export interface DelegatedProfile {
+    grantType: string;
+}
+export declare class InMemoryDelegationStore implements DelegationStore {
+    private held;
+    put(brand: string, user: string, token: string, scopes: string[]): Promise<void>;
+    get(brand: string, user: string): Promise<{
+        token: string;
+        scopes: string[];
+    } | undefined>;
+    delete(brand: string, user: string): Promise<void>;
+}
+export declare class InMemoryReceiptStore implements ReceiptStore {
+    readonly receipts: Array<{
+        brand: string;
+        user: string;
+        claims: Json;
+    }>;
+    keep(brand: string, user: string, claims: Json): Promise<void>;
+}
+export declare const PactSigners: import("@datalayer/reactor").ContributionPoint<HttpSigner>;
+export declare const PactDelegationStores: import("@datalayer/reactor").ContributionPoint<DelegationStore>;
+export declare const PactReceiptStores: import("@datalayer/reactor").ContributionPoint<ReceiptStore>;
+export declare const PactDelegatedProfiles: import("@datalayer/reactor").ContributionPoint<DelegatedProfile>;
+export declare const PactPlugin: import("@datalayer/reactor").ReactorPlugin<Record<string, never>, unknown, unknown>;
+/** A Brand's card as PACT 1.0 reads it (§2.1, §5.1); throws when it is not one. */
+export declare function readCard(card: Json): PactCard;
+/** One personal-agent JWT (§3.2): ES256 by the host's signer, `sub` opaque, ≤ 300 s. */
+export declare function signPersonalAgentJwt(signer: HttpSigner | {
+    keyid: string;
+    algorithm: string;
+    sign(data: Uint8Array): Promise<Uint8Array>;
+}, claims: {
+    issuer: string;
+    subject: string;
+    audience: string;
+    lifetime?: number;
+}): Promise<string>;
+export type Reply = {
+    kind: 'reply';
+    text: string;
+    contextId: string;
+    scopesUsed: string[];
+    actions: string[];
+};
+export type StepUp = {
+    kind: 'step-up';
+    text: string;
+    contextId: string;
+    missing: string[];
+    verificationUri: string;
+};
+/** What the person is shown to sign in at the Brand: never the device code. */
+export type SignIn = {
+    verificationUri: string;
+    userCode: string;
+    expiresIn: number;
+    reference: string;
+};
+/** A personal agent at one Brand. */
+export declare class PactPersonalAgent {
+    private readonly options;
+    card?: PactCard;
+    private pending;
+    private jwks?;
+    constructor(options: {
+        cardUrl: string;
+        issuer: string;
+        audience: string;
+        reactor: ReactorPlatformView;
+        fetchImpl?: typeof fetch;
+    });
+    private get fetch();
+    private jwt;
+    private delegations;
+    discover(): Promise<PactCard>;
+    send(user: string, text: string, options?: {
+        contextId?: string;
+        messageId?: string;
+    }): Promise<Reply | StepUp>;
+    private verifyReceipt;
+    requestSignIn(user: string, scopes: string[]): Promise<SignIn>;
+    /** Poll until the person approved; the scopes they actually granted. */
+    finishSignIn(user: string, signIn: SignIn, intervalMs?: number, attempts?: number): Promise<string[]>;
+}
+export {};