@datalayer/agent-runtimes 1.3.113 → 1.3.114

package/lib/specs/appspecSchema.js

@@ -28,6 +28,54 @@ export const APPSPEC_SCHEMA = {
             title: 'ActsAs',
             type: 'string',
         },
+        AppA2A: {
+            additionalProperties: false,
+            description: "A2A: what the application's Agent Card says beside its name and skill (AGENT_PROTOCOLS PR-02).",
+            properties: {
+                extensions: {
+                    description: "Extensions its card advertises, besides the runtime's own",
+                    items: {
+                        $ref: '#/$defs/AppA2AExtension',
+                    },
+                    title: 'Extensions',
+                    type: 'array',
+                },
+            },
+            title: 'AppA2A',
+            type: 'object',
+        },
+        AppA2AExtension: {
+            additionalProperties: false,
+            description: "An A2A extension the application's Agent Card advertises (A2A 1.0\n*Extensions*, AGENT_PROTOCOLS PR-02), beside the runtime's own.\n\nNamed by its URI, as `capabilities.extensions` writes it; its params are\npublished on the card as they are, so they never hold a credential.\nDatalayer's own extensions (orchestration, the face) are the runtime's,\nnever declared here.",
+            properties: {
+                uri: {
+                    description: "The extension's URI: `https://example.com/ext/gift-wrap/v1`",
+                    title: 'Uri',
+                    type: 'string',
+                },
+                description: {
+                    default: '',
+                    description: 'What it adds, for whoever reads the card',
+                    title: 'Description',
+                    type: 'string',
+                },
+                required: {
+                    default: false,
+                    description: 'Whether a client must support it to talk to the application at all',
+                    title: 'Required',
+                    type: 'boolean',
+                },
+                params: {
+                    additionalProperties: true,
+                    description: 'Its parameters on the card, as the extension defines them; public',
+                    title: 'Params',
+                    type: 'object',
+                },
+            },
+            required: ['uri'],
+            title: 'AppA2AExtension',
+            type: 'object',
+        },
         AppChecks: {
             additionalProperties: false,
             description: "Optional: checks from the catalogue, for a builder who wants them — and its code's own.",
@@ -772,6 +820,59 @@ export const APPSPEC_SCHEMA = {
             title: 'AppOptionTranslation',
             type: 'object',
         },
+        AppPact: {
+            additionalProperties: false,
+            description: 'PACT: the businesses it asks for each person (AGENT_PROTOCOLS PI-01).',
+            properties: {
+                connections: {
+                    description: 'Businesses, over PACT',
+                    items: {
+                        $ref: '#/$defs/AppPactConnection',
+                    },
+                    title: 'Connections',
+                    type: 'array',
+                },
+            },
+            title: 'AppPact',
+            type: 'object',
+        },
+        AppPactConnection: {
+            additionalProperties: false,
+            description: "A business the application asks for each person, over PACT 1.0 (AGENT_PROTOCOLS PI-01).\n\nThe Brand is named by its domain — its Agent Card is at\n`https://<brand>/.well-known/agent-card.json` (PACT §2.1) — and its\nProvider's `audience`, which the Provider assigns at registration and\nthe personal-agent JWT carries (§3.1). Always in each person's own name:\nPACT acts for a person. No credential is ever part of a spec.",
+            properties: {
+                id: {
+                    description: 'Stable within the application: `support`',
+                    title: 'Id',
+                    type: 'string',
+                },
+                brand: {
+                    description: "The business's domain: `example.com`",
+                    title: 'Brand',
+                    type: 'string',
+                },
+                audience: {
+                    description: 'The audience its Provider assigned (PACT §3.1)',
+                    title: 'Audience',
+                    type: 'string',
+                },
+                access: {
+                    $ref: '#/$defs/Access',
+                    default: 'read',
+                    description: 'How far: `read` (asks as the application alone), or `write` (also for the person, delegated)',
+                },
+                scopes: {
+                    description: "The Brand's scopes it may ask the person for: `orders:read`",
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Scopes',
+                    type: 'array',
+                },
+            },
+            required: ['id', 'brand', 'audience'],
+            title: 'AppPactConnection',
+            type: 'object',
+        },
         AppPage: {
             additionalProperties: false,
             description: "A widget's page written in its code (LOOP P-05): `@app.page`.\n\nIts inputs are a form, drawn on the page; as one changes, the function\nof its code runs again on them and the page shows what it returned, in\nplace. Without its file nothing runs it, and validation says so.",
@@ -2170,6 +2271,14 @@ export const APPSPEC_SCHEMA = {
             $ref: '#/$defs/AppPap',
             description: 'Personal Agent Protocol: companies it works with, or being one',
         },
+        pact: {
+            $ref: '#/$defs/AppPact',
+            description: 'PACT: businesses it asks for each person',
+        },
+        a2a: {
+            $ref: '#/$defs/AppA2A',
+            description: 'A2A: the extensions its Agent Card advertises',
+        },
         rules: {
             description: 'When it acts alone, and when it asks',
             items: {

package/lib/types/agentspecs.d.ts

@@ -507,6 +507,25 @@ export interface AppPactConnectionSpec {
 export interface AppPactSpec {
     connections: AppPactConnectionSpec[];
 }
+/**
+ * An A2A extension the application's Agent Card advertises, beside the
+ * runtime's own (AGENT_PROTOCOLS PR-02). Its params are public: never a
+ * credential.
+ */
+export interface AppA2AExtensionSpec {
+    /** The extension's URI: an `https://` URL or a `urn:`. */
+    uri: string;
+    /** What it adds, for whoever reads the card. */
+    description: string;
+    /** Whether a client must support it to talk to the application at all. */
+    required: boolean;
+    /** Its parameters on the card, as the extension defines them. */
+    params: Record<string, unknown>;
+}
+/** A2A: the extensions its Agent Card advertises. */
+export interface AppA2ASpec {
+    extensions: AppA2AExtensionSpec[];
+}
 /** When an application acts alone, and when it asks. */
 export interface AppRuleSpec {
     /** The action, in the words a person reads. */
@@ -1067,6 +1086,8 @@ export interface AppSpec {
     pap?: AppPapSpec;
     /** PACT: the businesses it asks for each person (AGENT_PROTOCOLS PI-01). */
     pact?: AppPactSpec;
+    /** A2A: the extensions its Agent Card advertises (AGENT_PROTOCOLS PR-02). */
+    a2a?: AppA2ASpec;
     rules: AppRuleSpec[];
     permissions: AppPermissionsSpec;
     interface: AppInterfaceSpec;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.113",
+    "version": "1.3.114",
     "type": "module",
     "workspaces": [
         ".",

package/scripts/codegen/generate_apps.py

@@ -152,8 +152,16 @@ def load_specs(specs_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
         # 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):
+        if "pap" in spec and spec["pap"] == type(app.pap)().model_dump(
+            mode="json", by_alias=True
+        ):
             spec.pop("pap")
+        # PACT and A2A's extensions the same way (AGENT_PROTOCOLS PI-01, PR-02).
+        for block in ("pact", "a2a"):
+            if block in spec and spec[block] == type(getattr(app, block))().model_dump(
+                mode="json", by_alias=True
+            ):
+                spec.pop(block)
         for key in ("description", "instructions", "goal"):
             spec[key] = _flat(spec.get(key))
         spec["interface"]["welcome"] = _flat(spec["interface"].get("welcome"))
@@ -198,8 +206,24 @@ def load_specs(specs_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
                 if (signs := actions_module.server_tool_signs(server, name))
             },
         }
+    # The agent protocols' tools (AGENT_PROTOCOLS PR-54): by protocol, the
+    # connection prefix its connections take and what each tool can do.
+    protocols = {
+        identity: {
+            "connection": spec["connection"],
+            "tools": {
+                name: [
+                    item.value
+                    for item in actions_module.protocol_tool_classes(identity, name)
+                ]
+                for name in actions_module.protocol_tool_names(identity)
+            },
+        }
+        for identity, spec in sorted(actions_module.protocol_tool_specs().items())
+    }
     actions = {
         "classes": [item.value for item in actions_module.ActionClass],
+        "protocols": protocols,
         "tools": tools,
         "servers": servers,
         "behaviours": behaviours,
@@ -419,6 +443,10 @@ def generate_actions_python_code(actions: dict[str, Any]) -> str:
         [
             "}",
             "",
+            "#: What each agent protocol's tools do, by protocol id: the prefix its",
+            "#: connections take (`pap:<domain>`) and each tool's classes (PR-54).",
+            f"PROTOCOL_TOOL_CLASSES: Dict[str, Dict[str, Any]] = {actions['protocols']!r}",
+            "",
             "#: What each application of the catalogue does about each classed tool of the",
             "#: servers it connects to, as agentspecs decides it: `do_it`, `if_asked`,",
             "#: `ask_first` or `leave_to_me`. What the rules engine has to reproduce.",
@@ -471,6 +499,15 @@ def generate_actions_typescript_code(actions: dict[str, Any]) -> str:
         + ";",
         "",
         "/**",
+        " * What each agent protocol's tools do, by protocol id: the prefix its",
+        " * connections take (`pap:<domain>`) and each tool's classes (PR-54).",
+        " */",
+        "export const PROTOCOL_TOOL_CLASSES: Record<",
+        "  string,",
+        "  { connection: string; tools: Record<string, ActionClass[]> }",
+        "> = " + json.dumps(actions["protocols"], indent=2) + ";",
+        "",
+        "/**",
         " * What each application of the catalogue does about each classed tool of the",
         " * servers it connects to, as agentspecs decides it. What the rules engine has",
         " * to reproduce.",