@datalayer/agent-runtimes 1.3.15 → 1.3.16

package/lib/specs/uiPlugins.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export const A2UI_UI_PLUGIN_0_0_1 = {
+    id: 'a2ui',
+    version: '0.0.1',
+    name: 'A2UI',
+    description: 'An agent describes an interface — a form, a table, a card — as a tree of components from a catalogue the host allows, and the host renders it; what the user does in it comes back to the agent as an action.',
+    docsUrl: 'https://a2ui.org/',
+    enabled: true,
+};
+export const MCP_APPS_UI_PLUGIN_0_0_1 = {
+    id: 'mcp-apps',
+    version: '0.0.1',
+    name: 'MCP Apps',
+    description: "An MCP server ships an interactive app with a tool: the host renders it in a sandboxed frame beside the conversation, and the app calls the server's tools through the host.",
+    docsUrl: 'https://modelcontextprotocol.io/docs/extensions/apps',
+    enabled: false,
+};
+export const MCP_UI_UI_PLUGIN_0_0_1 = {
+    id: 'mcp-ui',
+    version: '0.0.1',
+    name: 'MCP UI',
+    description: 'An MCP tool answers with a UI resource — HTML, a remote page or a component — that the host renders in place of plain text.',
+    docsUrl: 'https://mcpui.dev/',
+    enabled: false,
+};
+export const UI_PLUGIN_CATALOGUE = {
+    a2ui: A2UI_UI_PLUGIN_0_0_1,
+    'mcp-apps': MCP_APPS_UI_PLUGIN_0_0_1,
+    'mcp-ui': MCP_UI_UI_PLUGIN_0_0_1,
+};
+/** The plugin an agent spec's `uiPlugin` names, or undefined. */
+export function getUIPlugin(pluginId) {
+    return UI_PLUGIN_CATALOGUE[pluginId];
+}
+export function listUIPlugins() {
+    return Object.values(UI_PLUGIN_CATALOGUE);
+}

package/lib/types/agentspecs.d.ts

@@ -74,6 +74,22 @@ export interface AgentCapability {
     /** Free text, for humans reading a catalogue; never matched on. */
     tags?: string[];
 }
+/**
+ * How an agent's answer becomes an interface: a protocol the host renders
+ * (`agentspecs/ui-plugins`). An agent spec's `uiPlugin` names one.
+ */
+export interface UIPluginSpec {
+    /** What an agent spec's `uiPlugin` names (e.g. 'a2ui'). */
+    id: string;
+    version: string;
+    name: string;
+    /** What the plugin renders, and how the user's action comes back. */
+    description: string;
+    /** The protocol's own documentation. */
+    docsUrl: string;
+    /** Whether an agent spec may name it today. */
+    enabled: boolean;
+}
 export interface Agentspec {
     /** Unique agent identifier */
     id: string;
@@ -154,8 +170,8 @@ export interface Agentspec {
     delegable?: AgentCapability[];
     /** Communication protocol (e.g., 'ag-ui', 'acp', 'a2a', 'vercel-ai') */
     protocol?: string;
-    /** UI extension type (e.g., 'a2ui', 'mcp-apps') */
-    uiExtension?: string;
+    /** UI plugin (e.g., 'a2ui', 'mcp-apps'), one of the `UI_PLUGIN_CATALOGUE`. */
+    uiPlugin?: string;
     /** Trigger configuration (type, cron, event source, prompt) */
     trigger?: AgentTriggerConfig;
     /** Model configuration (temperature, max_tokens) */

package/lib/types/memory.d.ts

@@ -16,6 +16,8 @@ export interface MemorySpec {
     scope: string;
     /** Storage backend identifier */
     backend: string;
+    /** Whether an agent spec is offered this memory */
+    enabled: boolean;
     /** Icon identifier */
     icon: string;
     /** Emoji representation */

package/lib/types/models.d.ts

@@ -13,6 +13,8 @@ export interface AIModel {
     description: string;
     /** Provider name (anthropic, openai, bedrock, azure-openai) */
     provider: string;
+    /** The page on the provider's website that describes this model. */
+    providerUrl?: string;
     /** Whether this is the default model */
     default: boolean;
     /**
@@ -46,6 +48,56 @@ export interface AIModel {
      * 'thinking'. Empty means unstated rather than incapable.
      */
     capabilities?: string[];
+    /** How the provider bills it, when worth telling: 'standard' or 'credits'. */
+    billing?: 'standard' | 'credits';
+    /**
+     * How a Cloudflare model is reached: 'workers-ai' (a model Cloudflare
+     * hosts, ids 'cloudflare:wrk/…') or 'ai-gateway' (a third-party model its
+     * gateway fronts, ids 'cloudflare:gtw/…').
+     */
+    route?: 'workers-ai' | 'ai-gateway';
+    /** The tokens a request may carry, input and output together. */
+    contextWindow?: number;
+    /** Whether the provider keeps nothing of a request once it is answered. */
+    zeroDataRetention?: boolean;
+    /** The provider's list price per million tokens, when a service meters by it. */
+    pricing?: {
+        inputUsdPerMillion: number;
+        outputUsdPerMillion: number;
+    };
+    /**
+     * Where the route keeps a log of the requests it carries, apart from what
+     * the provider retains: 'none', or 'gateway' (AI Gateway's request logs).
+     * Read beside zeroDataRetention.
+     */
+    requestLogging?: 'none' | 'gateway';
+    /** Older ids this spec answers to, kept when an id had to move. */
+    aliases?: string[];
+}
+/**
+ * Who serves a model: the vendor's own API, a cloud that hosts it, or the
+ * user's machine — with what a person choosing it has to be able to read
+ * (`agentspecs/model-providers`).
+ */
+export interface ModelProvider {
+    /** What a model spec's `provider` names (e.g. 'anthropic'). */
+    id: string;
+    version: string;
+    name: string;
+    /** What the provider is, and what is worth knowing before choosing it. */
+    description: string;
+    /** The provider's product page. */
+    website?: string;
+    /** The provider's documentation. */
+    docsUrl?: string;
+    /** The terms of service a call is made under. */
+    termsUrl?: string;
+    /** The provider's privacy policy. */
+    privacyUrl?: string;
+    /** What the provider says about the data a request carries, when it has a page for it. */
+    dataUsageUrl?: string;
+    /** Where the model runs: the provider's cloud, or the user's machine. */
+    hosting: 'cloud' | 'local';
 }
 /**
  * Configuration for an AI model runtime (as returned by the server).

package/package.json

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

package/scripts/check-cloudflare-models.py

@@ -0,0 +1,122 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+# Distributed under the terms of the Modified BSD License.
+
+"""Hold the Cloudflare model specs to what Cloudflare serves.
+
+The catalogue moves — a model the specs could have named in September had
+been deprecated in May — so this reads the account's own listing and says
+which spec names a model no longer served, which served model with tool
+calling has no spec, and where a spec's context differs from the listing's.
+Run by hand, with the account's token::
+
+    CLOUDFLARE_ACCOUNT_ID=… CLOUDFLARE_API_TOKEN=… python scripts/check-cloudflare-models.py
+
+The names are the ones datalayer-ai-inference reads (``DATALAYER_CLOUDFLARE_*``
+are read too). Exits 1 when a spec names a model that is not served.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.request
+from pathlib import Path
+
+import yaml
+
+SPECS = Path(__file__).resolve().parent.parent / "agentspecs" / "agentspecs" / "models"
+API = "https://api.cloudflare.com/client/v4/accounts"
+
+
+def env(*names: str) -> str:
+    for name in names:
+        value = (os.environ.get(name) or "").strip()
+        if value:
+            return value
+    return ""
+
+
+def served(account: str, token: str) -> dict[str, dict]:
+    """Every text-generation model Cloudflare lists for the account, by name."""
+    models: dict[str, dict] = {}
+    page = 1
+    while True:
+        request = urllib.request.Request(
+            f"{API}/{account}/ai/models/search?task=Text%20Generation&per_page=100&page={page}",
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        # The address is the constant https `API` above, never caller input.
+        with urllib.request.urlopen(request, timeout=60) as response:  # nosec B310
+            answer = json.load(response)
+        if not answer.get("success"):
+            raise SystemExit(f"Cloudflare refused the listing: {answer.get('errors')}")
+        for model in answer.get("result") or []:
+            properties = {
+                p.get("property_id"): p.get("value")
+                for p in model.get("properties") or []
+            }
+            models[model["name"]] = {
+                # The listing says it as a string: "true".
+                "tools": str(properties.get("function_calling")).lower() == "true",
+                "context": properties.get("context_window"),
+            }
+        if len(answer.get("result") or []) < 100:
+            return models
+        page += 1
+
+
+def specs() -> list[dict]:
+    """The Workers AI specs (``cloudflare-wrk-*.yaml``) that name a model Cloudflare
+    hosts under ``@cf/``. The gateway flavour (``cloudflare-gtw-*``) and the typed
+    judgment models (``typesafe/jev``, with no ``@cf/`` namespace) are not in the
+    account's model listing and are left out.
+    """
+    found = []
+    for path in sorted(SPECS.glob("cloudflare-wrk-*.yaml")):
+        with open(path) as handle:
+            data = yaml.safe_load(handle) or {}
+        if "judgments" in (data.get("capabilities") or []):
+            continue
+        found.append({"file": path.name, **data})
+    return found
+
+
+def main() -> int:
+    account = env("CLOUDFLARE_ACCOUNT_ID", "DATALAYER_CLOUDFLARE_ACCOUNT_ID")
+    token = env(
+        "CLOUDFLARE_API_TOKEN",
+        "DATALAYER_CLOUDFLARE_API_TOKEN",
+        "DATALAYER_CLOUDFLARE_ACCOUNT_API_TOKEN",
+    )
+    if not account or not token:
+        print(
+            "CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN are needed", file=sys.stderr
+        )
+        return 2
+    listing = served(account, token)
+    named = {}
+    failures = 0
+    for spec in specs():
+        name = "@cf/" + spec["id"].split(":", 1)[1]
+        named[name] = spec
+        entry = listing.get(name)
+        if entry is None:
+            failures += 1
+            print(f"NOT SERVED  {spec['file']}: Cloudflare no longer lists {name}")
+            continue
+        if "tools" in (spec.get("capabilities") or []) and not entry["tools"]:
+            print(
+                f"NO TOOLS    {spec['file']}: the listing says {name} has no function calling"
+            )
+        print(f"ok          {spec['file']}: {name} (context {entry['context']})")
+    for name, entry in sorted(listing.items()):
+        if entry["tools"] and name not in named:
+            print(
+                f"unlisted    {name} has tool calling and no spec (context {entry['context']})"
+            )
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/codegen/generate_agents.py

@@ -455,7 +455,7 @@ from agent_runtimes.types import (
             protocol_val = spec.get("protocol")
             protocol_str = f'"{protocol_val}"' if protocol_val else "None"
             delegable_str = _fmt_py_delegable(spec.get("delegable", []))
-            ui_ext = spec.get("ui_extension")
+            ui_ext = spec.get("ui_plugin") or spec.get("ui_extension")
             ui_ext_str = f'"{ui_ext}"' if ui_ext else "None"
             trigger_val = spec.get("trigger")
             model_cfg = spec.get("model_config")
@@ -567,7 +567,7 @@ from agent_runtimes.types import (
     goal={goal_str},
     delegable={delegable_str},
     protocol={protocol_str},
-    ui_extension={ui_ext_str},
+    ui_plugin={ui_ext_str},
     trigger={_fmt_py_literal(trigger_val)},
     model_configuration={_fmt_py_literal(model_cfg)},
     mcp_server_tools={_fmt_py_literal(mcp_srv_tools)},
@@ -1075,7 +1075,7 @@ const FRONTEND_TOOL_MAP: Record<string, any> = {
             protocol_val = spec.get("protocol")
             protocol_ts = f"'{protocol_val}'" if protocol_val else "undefined"
             delegable_ts = _fmt_ts_delegable(spec.get("delegable", []))
-            ui_ext = spec.get("ui_extension")
+            ui_ext = spec.get("ui_plugin") or spec.get("ui_extension")
             ui_ext_ts = f"'{ui_ext}'" if ui_ext else "undefined"
             trigger_val = spec.get("trigger")
             model_cfg = spec.get("model_config")
@@ -1135,7 +1135,7 @@ const FRONTEND_TOOL_MAP: Record<string, any> = {
     goal: {goal_ts},
     delegable: {delegable_ts},
     protocol: {protocol_ts},
-    uiExtension: {ui_ext_ts},
+    uiPlugin: {ui_ext_ts},
     trigger: {_fmt_ts_literal(trigger_val)},
     modelConfig: {_fmt_ts_literal(model_cfg)},
     mcpServerTools: {_fmt_ts_literal(mcp_srv_tools)},
@@ -1573,11 +1573,13 @@ export * from './loops';
 export * from './mcpServers';
 export * from './memory';
 export * from './models';
+export * from './modelProviders';
 export * from './notifications';
 export * from './outputs';
 export * from './skills';
 export * from './tools';
 export * from './triggers';
+export * from './uiPlugins';
 """
     )
 

package/scripts/codegen/generate_memory.py

@@ -119,6 +119,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
                 f'    persistence="{spec.get("persistence", "none")}",',
                 f'    scope="{spec.get("scope", "agent")}",',
                 f'    backend="{spec.get("backend", "in-memory")}",',
+                f"    enabled={bool(spec.get('enabled', False))},",
                 f"    icon={icon},",
                 f"    emoji={emoji},",
                 ")",
@@ -268,6 +269,7 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
                 f"  persistence: '{spec.get('persistence', 'none')}',",
                 f"  scope: '{spec.get('scope', 'agent')}',",
                 f"  backend: '{spec.get('backend', 'in-memory')}',",
+                f"  enabled: {'true' if spec.get('enabled', False) else 'false'},",
                 f"  icon: '{spec.get('icon', 'database')}',",
                 f"  emoji: '{spec.get('emoji', '🧠')}',",
                 "};",

package/scripts/codegen/generate_model_providers.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026 Datalayer, Inc.
+# Distributed under the terms of the Modified BSD License.
+
+"""
+Generate Python and TypeScript code from YAML model-provider specifications.
+
+A model provider is who serves a model (Anthropic, Amazon Bedrock, Cloudflare,
+Ollama…): its site, its documentation, its terms of service, its privacy
+policy, what it says about the data a request carries, and whether it runs
+the model or the user's machine does. One YAML per provider under
+``agentspecs/model-providers``; a model spec's ``provider`` names one.
+
+Usage:
+    python generate_model_providers.py \\
+      --specs-dir agentspecs/agentspecs/model-providers \\
+      --python-output agent_runtimes/specs/model_providers.py \\
+      --typescript-output src/specs/modelProviders.ts
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+from versioning import ensure_spec_version, version_suffix
+
+FIELDS = ("website", "docs_url", "terms_url", "privacy_url", "data_usage_url")
+CAMEL = {
+    "website": "website",
+    "docs_url": "docsUrl",
+    "terms_url": "termsUrl",
+    "privacy_url": "privacyUrl",
+    "data_usage_url": "dataUsageUrl",
+}
+
+
+def load_provider_specs(specs_dir: Path) -> list[dict[str, Any]]:
+    """Load all model-provider YAML specifications from a directory."""
+    specs = []
+    for yaml_file in sorted(specs_dir.glob("*.yaml")):
+        with open(yaml_file) as f:
+            spec = yaml.safe_load(f)
+            ensure_spec_version(spec)
+            if spec["id"] != yaml_file.stem:
+                raise ValueError(
+                    f"{yaml_file.name}: the file is named for id {yaml_file.stem!r}, the spec says {spec['id']!r}"
+                )
+            specs.append(spec)
+    return specs
+
+
+def _const_name(provider_id: str) -> str:
+    return provider_id.replace("-", "_").replace(".", "_").upper()
+
+
+def _py(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _ts(value: str) -> str:
+    return "'" + value.replace("\\", "\\\\").replace("'", "\\'") + "'"
+
+
+def generate_python_code(specs: list[dict[str, Any]]) -> str:
+    """Generate Python code from model-provider specifications."""
+    lines = [
+        "# Copyright (c) 2025-2026 Datalayer, Inc.",
+        "# Distributed under the terms of the Modified BSD License.",
+        '"""',
+        "Model Provider Catalog.",
+        "",
+        "Who serves a model: the vendor's own API, a cloud that hosts it, or the",
+        "user's machine — with its site, documentation, terms, privacy policy and",
+        "what it says about the data a request carries.",
+        "",
+        "This file is AUTO-GENERATED from YAML specifications.",
+        "DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",
+        '"""',
+        "",
+        "from typing import Dict",
+        "",
+        "from agent_runtimes.types import ModelProvider",
+        "",
+        "",
+        "# " + "=" * 76,
+        "# Model Provider Definitions",
+        "# " + "=" * 76,
+        "",
+    ]
+    for spec in specs:
+        const = _const_name(spec["id"]) + version_suffix(spec["version"])
+        lines.extend(
+            [
+                f"{const} = ModelProvider(",
+                f"    id={_py(spec['id'])},",
+                f"    version={_py(str(spec['version']))},",
+                f"    name={_py(spec['name'])},",
+                f"    description={_py(str(spec.get('description', '')).strip())},",
+            ]
+        )
+        for field in FIELDS:
+            value = spec.get(field)
+            if value:
+                lines.append(f"    {field}={_py(str(value))},")
+        lines.append(f"    hosting={_py(spec.get('hosting', 'cloud'))},")
+        lines.extend([")", ""])
+    lines.extend(
+        [
+            "",
+            "# " + "=" * 76,
+            "# Model Provider Catalog",
+            "# " + "=" * 76,
+            "",
+            "MODEL_PROVIDER_CATALOGUE: Dict[str, ModelProvider] = {",
+        ]
+    )
+    for spec in specs:
+        lines.append(
+            f"    {_py(spec['id'])}: {_const_name(spec['id']) + version_suffix(spec['version'])},"
+        )
+    lines.extend(
+        [
+            "}",
+            "",
+            "",
+            "def get_model_provider(provider_id: str) -> ModelProvider | None:",
+            '    """The provider a model spec\'s `provider` names, or None."""',
+            "    return MODEL_PROVIDER_CATALOGUE.get(provider_id)",
+            "",
+            "",
+            "def list_model_providers() -> list[ModelProvider]:",
+            "    return list(MODEL_PROVIDER_CATALOGUE.values())",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
+    """Generate TypeScript code from model-provider specifications."""
+    lines = [
+        "/*",
+        " * Copyright (c) 2025-2026 Datalayer, Inc.",
+        " * Distributed under the terms of the Modified BSD License.",
+        " */",
+        "",
+        "/**",
+        " * Model Provider Catalog.",
+        " *",
+        " * Who serves a model: the vendor's own API, a cloud that hosts it, or the",
+        " * user's machine — with its site, documentation, terms, privacy policy and",
+        " * what it says about the data a request carries.",
+        " *",
+        " * This file is AUTO-GENERATED from YAML specifications.",
+        " * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",
+        " */",
+        "",
+        "import type { ModelProvider } from '../types/models';",
+        "",
+    ]
+    for spec in specs:
+        const = _const_name(spec["id"]) + version_suffix(spec["version"])
+        lines.extend(
+            [
+                f"export const {const}: ModelProvider = {{",
+                f"  id: {_ts(spec['id'])},",
+                f"  version: {_ts(str(spec['version']))},",
+                f"  name: {_ts(spec['name'])},",
+                f"  description: {_ts(str(spec.get('description', '')).strip())},",
+            ]
+        )
+        for field in FIELDS:
+            value = spec.get(field)
+            if value:
+                lines.append(f"  {CAMEL[field]}: {_ts(str(value))},")
+        lines.append(f"  hosting: {_ts(spec.get('hosting', 'cloud'))},")
+        lines.extend(["};", ""])
+    lines.append(
+        "export const MODEL_PROVIDER_CATALOGUE: Record<string, ModelProvider> = {"
+    )
+    for spec in specs:
+        lines.append(
+            f"  {_ts(spec['id'])}: {_const_name(spec['id']) + version_suffix(spec['version'])},"
+        )
+    lines.extend(
+        [
+            "};",
+            "",
+            "/** The provider a model spec's `provider` names, or undefined. */",
+            "export function getModelProvider(providerId: string): ModelProvider | undefined {",
+            "  return MODEL_PROVIDER_CATALOGUE[providerId];",
+            "}",
+            "",
+            "export function listModelProviders(): ModelProvider[] {",
+            "  return Object.values(MODEL_PROVIDER_CATALOGUE);",
+            "}",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate Python and TypeScript code from YAML model-provider specifications"
+    )
+    parser.add_argument(
+        "--specs-dir",
+        type=Path,
+        required=True,
+        help="Directory containing model-provider YAML files",
+    )
+    parser.add_argument(
+        "--python-output", type=Path, required=True, help="Output path for Python file"
+    )
+    parser.add_argument(
+        "--typescript-output",
+        type=Path,
+        required=True,
+        help="Output path for TypeScript file",
+    )
+    args = parser.parse_args()
+
+    if not args.specs_dir.exists():
+        print(f"Error: Specs directory not found: {args.specs_dir}", file=sys.stderr)
+        sys.exit(1)
+    specs = load_provider_specs(args.specs_dir)
+    if not specs:
+        print(
+            f"Warning: No model-provider specifications found in {args.specs_dir}",
+            file=sys.stderr,
+        )
+        return
+    args.python_output.parent.mkdir(parents=True, exist_ok=True)
+    args.python_output.write_text(generate_python_code(specs))
+    print(f"Generated Python code: {args.python_output}")
+    args.typescript_output.parent.mkdir(parents=True, exist_ok=True)
+    args.typescript_output.write_text(generate_typescript_code(specs))
+    print(f"Generated TypeScript code: {args.typescript_output}")
+    print(f"\n✓ Successfully generated code from {len(specs)} model-provider specs")
+
+
+if __name__ == "__main__":
+    main()