@datalayer/agent-runtimes 1.3.111 → 1.3.113

package/lib/specs/appspecSchema.js

@@ -855,6 +855,182 @@ export const APPSPEC_SCHEMA = {
             title: 'AppPageOutput',
             type: 'object',
         },
+        AppPap: {
+            additionalProperties: false,
+            description: 'Personal Agent Protocol: the companies it works with, and whether it is one.',
+            properties: {
+                connections: {
+                    description: 'Companies, as a personal agent',
+                    items: {
+                        $ref: '#/$defs/AppPapConnection',
+                    },
+                    title: 'Connections',
+                    type: 'array',
+                },
+                company: {
+                    $ref: '#/$defs/AppPapCompany',
+                    description: 'As a company',
+                },
+            },
+            title: 'AppPap',
+            type: 'object',
+        },
+        AppPapCompany: {
+            additionalProperties: false,
+            description: 'The application is a company personal agents work with (PAP_DATALAYER S-01, U-04).',
+            properties: {
+                enabled: {
+                    default: false,
+                    description: 'Whether it publishes itself as a company at Ship',
+                    title: 'Enabled',
+                    type: 'boolean',
+                },
+                signed_out: {
+                    default: true,
+                    description: 'Whether a personal agent may ask before signing in',
+                    title: 'Signed Out',
+                    type: 'boolean',
+                },
+                interfaces: {
+                    description: 'How personal agents reach it',
+                    items: {
+                        $ref: '#/$defs/PapInterface',
+                    },
+                    title: 'Interfaces',
+                    type: 'array',
+                },
+                scopes: {
+                    description: 'The scopes it offers',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Scopes',
+                    type: 'array',
+                },
+                extensions: {
+                    description: 'Extensions it offers: `operations`',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Extensions',
+                    type: 'array',
+                },
+                personal_agents: {
+                    $ref: '#/$defs/PapAgents',
+                    default: 'any',
+                    description: '`any`, or `registered` only',
+                },
+                registered_agents: {
+                    description: "The personal agents it accepts when `registered` only: each one's `client_id` URL",
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Registered Agents',
+                    type: 'array',
+                },
+                operations: {
+                    description: 'What it does for the person once they confirm (the `operations` extension)',
+                    items: {
+                        $ref: '#/$defs/AppPapOperation',
+                    },
+                    title: 'Operations',
+                    type: 'array',
+                },
+            },
+            title: 'AppPapCompany',
+            type: 'object',
+        },
+        AppPapConnection: {
+            additionalProperties: false,
+            description: 'A company the application works with as a Personal Agent (PAP_DATALAYER S-01).\n\nThe company is named by its domain, the discovery input, and nothing else:\nits endpoints, issuer and metadata are what discovery verifies and are kept\nby the deployment, never here, and no credential is ever part of a spec.\n`access` and `as` mean what they mean for every connection.',
+            properties: {
+                id: {
+                    description: 'Stable within the application: `orders`',
+                    title: 'Id',
+                    type: 'string',
+                },
+                company: {
+                    description: "The company's domain, as discovery takes it: `example.com`",
+                    title: 'Company',
+                    type: 'string',
+                },
+                access: {
+                    $ref: '#/$defs/Access',
+                    default: 'read',
+                    description: 'How far: `read`, or `write`',
+                },
+                as: {
+                    $ref: '#/$defs/ActsAs',
+                    default: 'user',
+                    description: 'In whose account: `user` (each person signs in to their own) or `owner`',
+                },
+                scopes: {
+                    description: 'The fewest scopes the application needs',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Scopes',
+                    type: 'array',
+                },
+                interfaces: {
+                    description: 'How it reaches the company',
+                    items: {
+                        $ref: '#/$defs/PapInterface',
+                    },
+                    title: 'Interfaces',
+                    type: 'array',
+                },
+                sign_in: {
+                    description: 'Sign-in modes the application accepts, preferred first',
+                    items: {
+                        $ref: '#/$defs/PapSignIn',
+                    },
+                    title: 'Sign In',
+                    type: 'array',
+                },
+                extensions: {
+                    description: 'Extensions it uses: `operations`',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Extensions',
+                    type: 'array',
+                },
+            },
+            required: ['id', 'company'],
+            title: 'AppPapConnection',
+            type: 'object',
+        },
+        AppPapOperation: {
+            additionalProperties: false,
+            description: "Something a personal agent may ask the application to do for the person,\ndone only once they confirm its exact terms (PAP_DATALAYER B-04, Operations v1).\n\nAsked by a personal agent, the application's agent does not call `tool`:\nthe call is proposed, its arguments the terms, and the person confirms\nthat revision before the tool runs, with those arguments and only once.",
+            properties: {
+                action: {
+                    description: "The action's name at this company, e.g. `orders.exchange`",
+                    title: 'Action',
+                    type: 'string',
+                },
+                tool: {
+                    description: "The application's tool that does it, called with the terms",
+                    title: 'Tool',
+                    type: 'string',
+                },
+                summary: {
+                    description: 'What the person is shown, with `{term}` for each term, e.g. `Exchange order {order_id} for size {size}`; never written by the model',
+                    title: 'Summary',
+                    type: 'string',
+                },
+                user_approval_required: {
+                    default: true,
+                    description: 'Whether only the person may confirm it, never an approval in advance',
+                    title: 'User Approval Required',
+                    type: 'boolean',
+                },
+            },
+            required: ['action', 'tool', 'summary'],
+            title: 'AppPapOperation',
+            type: 'object',
+        },
         AppPermissions: {
             additionalProperties: false,
             description: 'What the application may reach beside its connections. Nothing, unless said.',
@@ -1790,6 +1966,24 @@ export const APPSPEC_SCHEMA = {
             title: 'Layout',
             type: 'string',
         },
+        PapAgents: {
+            description: 'Which personal agents a company application accepts.',
+            enum: ['any', 'registered'],
+            title: 'PapAgents',
+            type: 'string',
+        },
+        PapInterface: {
+            description: 'How a Personal Agent Protocol company is reached (PAP §3.1).',
+            enum: ['agent', 'openapi', 'mcp', 'web'],
+            title: 'PapInterface',
+            type: 'string',
+        },
+        PapSignIn: {
+            description: 'How a person signs in at a company, in the order the application prefers.',
+            enum: ['direct', 'device', 'mediated'],
+            title: 'PapSignIn',
+            type: 'string',
+        },
         RecordItem: {
             description: 'What an application may keep of what it did.',
             enum: [
@@ -1972,6 +2166,10 @@ export const APPSPEC_SCHEMA = {
             title: 'Connections',
             type: 'array',
         },
+        pap: {
+            $ref: '#/$defs/AppPap',
+            description: 'Personal Agent Protocol: companies it works with, or being one',
+        },
         rules: {
             description: 'When it acts alone, and when it asks',
             items: {
@@ -2081,8 +2279,8 @@ export const APPSPEC_SCHEMA = {
         },
         avatar: {
             default: '',
-            description: 'Its avatar, by name: a drawing of the set people choose theirs from on their profile. Its emoji stands for it when unsaid, and where only text goes',
-            pattern: '^\\s*([A-Z][A-Za-z0-9]{0,63})?\\s*$',
+            description: 'Its avatar, as people keep theirs on their profile: `emoji:<emoji>`, or `@datalayer/icons-react:<Name>Icon` for a drawing of the set. Its emoji stands for it when unsaid, and where only text goes',
+            pattern: '^\\s*(emoji:[^\\sA-Za-z0-9]{1,32}|@datalayer/icons-react:[A-Z][A-Za-z0-9]{0,62}Icon)?\\s*$',
             title: 'Avatar',
             type: 'string',
         },

package/lib/types/agentspecs.d.ts

@@ -458,6 +458,8 @@ export interface AppPapCompanySpec {
     extensions: string[];
     /** `any`, or `registered` personal agents only. */
     personalAgents: 'any' | 'registered';
+    /** The personal agents it accepts when `registered` only, by `client_id` URL. */
+    registeredAgents: string[];
     /**
      * What it does for the person once they confirm (PAP_DATALAYER B-04, the
      * `operations` extension): each action and each tool once.
@@ -484,6 +486,27 @@ export interface AppPapSpec {
     connections: AppPapConnectionSpec[];
     company: AppPapCompanySpec;
 }
+/**
+ * A business the application asks for each person over PACT 1.0
+ * (AGENT_PROTOCOLS PI-01): its domain, and the audience its Provider
+ * assigned. Always in each person's own name; never a credential.
+ */
+export interface AppPactConnectionSpec {
+    /** Stable within the application: `support`. */
+    id: string;
+    /** The business's domain: `example.com`; its card is at `/.well-known/agent-card.json`. */
+    brand: string;
+    /** The audience the Brand's Provider assigned (PACT §3.1). */
+    audience: string;
+    /** `read`: asks as the application alone; `write`: also for the person, delegated. */
+    access: 'read' | 'write';
+    /** The Brand's scopes it may ask the person for: `orders:read`. */
+    scopes: string[];
+}
+/** PACT: the businesses it asks for each person. */
+export interface AppPactSpec {
+    connections: AppPactConnectionSpec[];
+}
 /** When an application acts alone, and when it asks. */
 export interface AppRuleSpec {
     /** The action, in the words a person reads. */
@@ -1042,6 +1065,8 @@ export interface AppSpec {
     connections: AppConnectionSpec[];
     /** Personal Agent Protocol; absent, the application has none. */
     pap?: AppPapSpec;
+    /** PACT: the businesses it asks for each person (AGENT_PROTOCOLS PI-01). */
+    pact?: AppPactSpec;
     rules: AppRuleSpec[];
     permissions: AppPermissionsSpec;
     interface: AppInterfaceSpec;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.111",
+    "version": "1.3.113",
     "type": "module",
     "workspaces": [
         ".",
@@ -227,6 +227,7 @@
         "@tailwindcss/vite": "^4.1.13",
         "@tanstack/react-query": "^5.90.6",
         "@toon-format/toon": "^1.3.0",
+        "@ucp-js/sdk": "0.5.1",
         "@xyflow/react": "^12.10.0",
         "ai": "7.0.90",
         "ansi-to-html": "^0.7.2",
@@ -242,6 +243,7 @@
         "fuse.js": "^7.0.0",
         "html2canvas": "^1.4.1",
         "input-otp": "^1.4.2",
+        "jose": "^6.2.12",
         "jwt-decode": "^2.2.0",
         "localforage": "^1.10.0",
         "lucide-react": "^0.542.0",
@@ -278,6 +280,7 @@
         "uuid": "^13.0.0",
         "validator": "^13.7.0",
         "vaul": "^1.1.2",
+        "web-bot-auth": "0.2.0",
         "yaml": "^2.9.0",
         "zod": "^4.1.13",
         "zustand": "^4.4.1"

package/scripts/codegen/generate_agentic_commerce.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Copyright (c) 2025-2026 Datalayer, Inc.
+# Distributed under the terms of the Modified BSD License.
+#
+# The Agentic Commerce Protocol's checkout models, generated from the
+# specification's JSON Schema (AGENT_PROTOCOLS PR-41), in both languages:
+#   agent_runtimes/protocols/agentic_commerce/models.py   (datamodel-code-generator 0.34.0)
+#   src/protocols/agentic-commerce/models.ts              (json-schema-to-typescript 15.0.4)
+#
+# Usage: scripts/codegen/generate_agentic_commerce.sh [VERSION]   (default 2026-04-17)
+# Runs in a throwaway directory under ~/.cache; nothing is installed here.
+set -euo pipefail
+VERSION="${1:-2026-04-17}"
+HERE="$(cd "$(dirname "$0")/../.." && pwd)"
+WORK="${HOME}/.cache/agent-runtimes-codegen/agentic-commerce"
+mkdir -p "$WORK"
+if [ ! -d "$WORK/spec" ]; then
+  git clone -q --depth 1 https://github.com/agentic-commerce-protocol/agentic-commerce-protocol.git "$WORK/spec"
+fi
+SCHEMA="$WORK/spec/spec/$VERSION/json-schema/schema.agentic_checkout.json"
+[ -f "$SCHEMA" ] || { echo "no schema for $VERSION" >&2; exit 1; }
+[ -d "$WORK/venv" ] || python3 -m venv "$WORK/venv"
+"$WORK/venv/bin/pip" install -q "datamodel-code-generator==0.34.0"
+"$WORK/venv/bin/datamodel-codegen" --input "$SCHEMA" --input-file-type jsonschema \
+  --output-model-type pydantic_v2.BaseModel --target-python-version 3.11 \
+  --use-standard-collections --use-union-operator --disable-timestamp \
+  --output "$WORK/models.py"
+{
+  cat <<HEADER
+# Copyright (c) 2025-2026 Datalayer, Inc.
+# Distributed under the terms of the Modified BSD License.
+#
+# GENERATED — do not edit. The Agentic Commerce Protocol $VERSION, its
+# checkout models: datamodel-code-generator 0.34.0 over
+# agentic-commerce-protocol/agentic-commerce-protocol spec/$VERSION/
+# json-schema/schema.agentic_checkout.json (Apache 2.0), with
+#   --output-model-type pydantic_v2.BaseModel --target-python-version 3.11
+#   --use-standard-collections --use-union-operator --disable-timestamp
+# Regenerate with scripts/codegen/generate_agentic_commerce.sh.
+# ruff: noqa
+
+HEADER
+  sed '1,/^from __future__/{/^from __future__/!d}' "$WORK/models.py"
+} > "$HERE/agent_runtimes/protocols/agentic_commerce/models.py"
+( cd "$WORK" && [ -d node_modules/json-schema-to-typescript ] || npm i -s --no-audit --no-fund json-schema-to-typescript@15.0.4 )
+cat > "$WORK/gen.mjs" <<'JS'
+import { compile } from 'json-schema-to-typescript';
+import { readFileSync, writeFileSync } from 'fs';
+const schema = JSON.parse(readFileSync(process.argv[2], 'utf8'));
+const root = { ...schema, type: 'object', properties: Object.fromEntries(Object.keys(schema.$defs).map(k => [k, { $ref: `#/$defs/${k}` }])), additionalProperties: false };
+const ts = await compile(root, 'AgenticCheckout', { bannerComment: '', unreachableDefinitions: true, additionalProperties: false, strictIndexSignatures: true });
+writeFileSync(process.argv[3], ts);
+JS
+( cd "$WORK" && node gen.mjs "$SCHEMA" "$WORK/models.ts" )
+{
+  cat <<HEADER
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+/* eslint-disable */
+// GENERATED — do not edit. The Agentic Commerce Protocol $VERSION, its checkout
+// types: json-schema-to-typescript 15.0.4 over
+// agentic-commerce-protocol/agentic-commerce-protocol spec/$VERSION/json-schema/
+// schema.agentic_checkout.json (Apache 2.0). Regenerate with
+// scripts/codegen/generate_agentic_commerce.sh.
+
+export const AGENTIC_COMMERCE_VERSION = '$VERSION';
+
+HEADER
+  cat "$WORK/models.ts"
+} > "$HERE/src/protocols/agentic-commerce/models.ts"
+echo "generated $VERSION"

package/scripts/codegen/generate_apps.py

@@ -56,6 +56,12 @@ CAMEL = {
     "character_alone": "characterAlone",
     "settings_ui": "settingsUi",
     "custom_components": "customComponents",
+    # Personal Agent Protocol (pap.connections[], pap.company, its operations).
+    "sign_in": "signIn",
+    "signed_out": "signedOut",
+    "personal_agents": "personalAgents",
+    "registered_agents": "registeredAgents",
+    "user_approval_required": "userApprovalRequired",
 }
 
 #: The keys whose value is carried as it is written: a component tree, weights
@@ -143,6 +149,11 @@ def load_specs(specs_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
         # Components of its own: said only when it has some.
         if not spec["interface"].get("custom_components"):
             spec["interface"].pop("custom_components", None)
+        # Personal Agent Protocol only when the application says something of it:
+        # an Appspec that does not mention `pap` reads back with none (the TypeScript
+        # reader's rule), so the catalogue leaves the defaults out too.
+        if "pap" in spec and spec["pap"] == type(app.pap)().model_dump(mode="json", by_alias=True):
+            spec.pop("pap")
         for key in ("description", "instructions", "goal"):
             spec[key] = _flat(spec.get(key))
         spec["interface"]["welcome"] = _flat(spec["interface"].get("welcome"))

package/scripts/validate_pap_examples.py

@@ -1,10 +1,17 @@
 # Copyright (c) 2025-2026 Datalayer, Inc.
 # Distributed under the terms of the Modified BSD License.
 
-"""Build every Agent Runtimes PAP example and reject duplicate identifiers."""
+"""Build every Agent Runtimes PAP example, run its read tools, and reject duplicate identifiers.
+
+Each example's argument-free ``read`` tool is run once: the demo worlds are in
+process, with no network and no model. An application that is a company
+(``pap.company``) must declare each operation on a tool of its own.
+"""
 
 from __future__ import annotations
 
+import asyncio
+import json
 import sys
 from pathlib import Path
 
@@ -51,9 +58,27 @@ def main() -> int:
                 raise RuntimeError(
                     f"Host-only PAP values exposed by {app_id}/{tool.name}: {names}"
                 )
+        declared = {tool.name for tool in built.application.spec.tools}
+        for operation in built.application.spec.pap.company.operations:
+            if operation.tool not in declared:
+                raise RuntimeError(
+                    f"{app_id} declares {operation.action} on {operation.tool}, "
+                    "which is not one of its tools"
+                )
+        ran = 0
+        handlers = built.application.tools
+        for tool in built.application.spec.tools:
+            if tool.does != ["read"] or tool.parameters.get("required"):
+                continue
+            result = asyncio.run(handlers[tool.name]())
+            if not isinstance(result, dict):
+                raise RuntimeError(f"{app_id}/{tool.name} returned {type(result)!r}")
+            json.dumps(result)
+            ran += 1
+        count = len(built.application.spec.tools)
         sys.stdout.write(
             f"{path.relative_to(ROOT)}: {app_id} "
-            f"({len(built.application.spec.tools)} tool)\n"
+            f"({count} tool{'s' if count != 1 else ''}, {ran} run)\n"
         )
     return 0