@datalayer/agent-runtimes 1.3.15 → 1.3.17

package/lib/types/agentspecs.d.ts

@@ -74,6 +74,457 @@ 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;
+}
+/** A check a Frame requires of the output of work done under it. */
+export interface FrameGuardSpec {
+    id: string;
+    /**
+     * What kind of check it is: algorithmic, source-grounding, consensus,
+     * expert, policy-safety, regression-drift or outcome.
+     */
+    category: string;
+    description: string;
+    /** Whether the output counts only once this Guard has passed. */
+    required: boolean;
+}
+/** A reusable prompt fragment a Cog loads into its context. */
+export interface FramePromptSpec {
+    id: string;
+    text: string;
+}
+/**
+ * The context work happens in, written down (`agentspecs/frames`): owned,
+ * scoped, versioned and inherited. A Frame in the generated catalogue is
+ * resolved — what it inherits through `extends` is already in it.
+ */
+export interface FrameSpec {
+    id: string;
+    version: string;
+    name: string;
+    description: string;
+    /** organization, department, team, project, role or relationship. */
+    scope: string;
+    /** Who manages the Frame and answers for it. */
+    owner: string;
+    /** The parent Frame, as the spec names it. */
+    extends?: string;
+    /** The Frames it inherits from, nearest parent first. */
+    lineage: string[];
+    tags: string[];
+    /** Whether a Cog may name it today. */
+    enabled: boolean;
+    icon?: string;
+    emoji?: string;
+    rules: string[];
+    terminology: Record<string, string>;
+    goals: string[];
+    style: string[];
+    norms: string[];
+    process: string[];
+    architecture: string;
+    prompts: FramePromptSpec[];
+    skills: string[];
+    tools: string[];
+    mcpServers: string[];
+    guards: FrameGuardSpec[];
+}
+/**
+ * An AI worker you can hold to account (`agentspecs/cogs`): a Cog extends an
+ * agent spec and is equipped with Frames. In the generated catalogue it is
+ * resolved — `spec` is the agent with the Cog's changes and its Frames.
+ */
+export interface CogSpec {
+    id: string;
+    version: string;
+    name: string;
+    description: string;
+    /** The id of the agent spec it extends. */
+    agent: string;
+    /** The Frames it works under, in order. */
+    frames: string[];
+    /** Every Frame that contributed: the named ones and those they inherit from. */
+    lineage: string[];
+    /** What the Cog packages: context, model or combined. */
+    kind: string;
+    /** Whether it is offered today. */
+    enabled: boolean;
+    /** The Guards its Frames declare: what its output answers to. */
+    guards: FrameGuardSpec[];
+    /** The Cog as an agent spec, resolved and ready to launch. */
+    spec: Agentspec;
+}
+/** Something a Guard reports, which a Gate's condition reads. */
+export interface GuardSignalSpec {
+    name: string;
+    /** boolean, number or string. */
+    type: string;
+    description: string;
+}
+/**
+ * A reusable check (`agentspecs/guards`): a Guard extends a guardrail. The
+ * guardrail is the policy; the Guard verifies that the work stayed within
+ * it. Resolved: it carries the guardrail's policy under its own identity.
+ */
+export interface GuardSpec extends GuardrailSpec {
+    id: string;
+    version: string;
+    name: string;
+    description: string;
+    /** The id of the guardrail it extends. */
+    guardrail: string;
+    /**
+     * algorithmic, source-grounding, consensus, expert, policy-safety,
+     * regression-drift or outcome.
+     */
+    category: string;
+    /** preflight, in_flight, post_run, continuous: where it may run. */
+    stages: string[];
+    /** algorithmic, cog or human. */
+    method: string;
+    /** What is verified. */
+    check: string;
+    /** What it reports for a Gate to decide on. */
+    signals: GuardSignalSpec[];
+    /** Whether the work counts only once it has passed. */
+    required: boolean;
+    enabled: boolean;
+    tags: string[];
+    icon?: string;
+    emoji?: string;
+}
+/** A decision point of an Op (`agentspecs/gates`): Guards check, Gates decide. */
+export interface GateSpec {
+    id: string;
+    version: string;
+    name: string;
+    description: string;
+    /** The stage it decides at. */
+    stage: string;
+    /** The Guards whose results it reads. */
+    guards: string[];
+    /** The condition on its Guards' signals, or `always`. */
+    when: string;
+    /** What happens when the condition holds. */
+    then: string;
+    /** What happens when it does not. */
+    otherwise: string;
+    /** The signals the condition reads. */
+    signals: string[];
+    /** The roles a decision is handed to. */
+    reviewers: string[];
+    maxRetries: number;
+    enabled: boolean;
+    tags: string[];
+    icon?: string;
+    emoji?: string;
+}
+/** What evidence a run keeps, and for how long (`agentspecs/tracks`). */
+export interface TrackSpec {
+    id: string;
+    version: string;
+    name: string;
+    description: string;
+    /** The retention, e.g. `7_years`. */
+    retainFor: string;
+    retentionDays: number;
+    /** What a record has to include. */
+    include: string[];
+    /** The roles that may read a record. */
+    readers: string[];
+    /** Field patterns kept out of the record. */
+    redact: string[];
+    /** Whether corrections and overrides feed Organizational Memory. */
+    feedsMemory: boolean;
+    /** Whether a record may leave the Hub that produced it: it may not. */
+    exchangeable: boolean;
+    enabled: boolean;
+    tags: string[];
+    icon?: string;
+    emoji?: string;
+}
+/** A Cog as an Op names it. */
+export interface OpCogSpec {
+    id: string;
+    /** The agent spec the Cog extends. */
+    agent: string;
+    frames: string[];
+    kind: string;
+}
+/** The Guards of an Op, by the stage they run at, each resolved. */
+export interface OpGuardsSpec {
+    preflight: GuardSpec[];
+    inFlight: GuardSpec[];
+    postRun: GuardSpec[];
+    continuous: GuardSpec[];
+}
+/**
+ * An orchestrated, supervised workflow (`agentspecs/ops`): Cogs do the work,
+ * and a validation strategy says how it is verified — Guards by stage, the
+ * Gates that decide, the Track kept as evidence. Resolved: everything it
+ * names is in it.
+ */
+export interface OpSpec {
+    id: string;
+    version: string;
+    name: string;
+    description: string;
+    /** Who is accountable for the outcome. */
+    owner: string;
+    goal: string;
+    cogs: OpCogSpec[];
+    /** Frames applied at the workflow level. */
+    frames: string[];
+    /** Every Frame that orients the Op, its Cogs' included. */
+    lineage: string[];
+    supervisor: {
+        model: string;
+        instructions: string;
+    };
+    guards: OpGuardsSpec;
+    /** The checks its Frames declare. */
+    frameGuards: FrameGuardSpec[];
+    /** The Gates, in the order they are met. */
+    gates: GateSpec[];
+    track: TrackSpec;
+    /** launcher, command, button, schedule. */
+    triggers: string[];
+    enabled: boolean;
+    tags: string[];
+    icon?: string;
+    emoji?: string;
+    color?: string;
+}
+/** What a tool does to the world (`agentspecs.actions`). */
+export type ActionClass = 'read' | 'write' | 'send' | 'buy' | 'delete' | 'publish';
+/** An argument that makes a tool do something more than its own class. */
+export interface ActionConditionSpec {
+    /** The argument of the call. */
+    argument: string;
+    /** Holds when the argument is any of these: a word, a number, true or false. */
+    equals?: Array<string | number | boolean>;
+    /** Holds when the argument's values include any of these. */
+    includes?: Array<string | number | boolean>;
+    /** What the tool is then, besides its own. */
+    classes: ActionClass[];
+}
+/** A condition, and what an application does when it holds. */
+export interface AppEscalation extends ActionConditionSpec {
+    behaviour: AppBehaviour;
+}
+/** What the tools of an MCP server do. */
+export interface ServerActionsSpec {
+    /** The day the tool names were read off the running server; absent when nobody looked. */
+    checked?: string;
+    /** The classes of a tool nothing else names; empty means unknown. */
+    default: ActionClass[];
+    /** What each tool does of its own, by name or pattern. */
+    tools: Record<string, ActionClass[]>;
+    /** What an argument makes a tool do besides, by tool. */
+    conditions: Record<string, ActionConditionSpec[]>;
+}
+/** What kind of application it is: what its user meets. */
+export type AppKind = 'chat' | 'widget' | 'decision' | 'worker';
+/** What an application does when it meets an action. */
+export type AppBehaviour = 'do_it' | 'if_asked' | 'ask_first' | 'leave_to_me';
+export type AppLayout = 'chat' | 'page' | 'split';
+/** The one colour of an application; everything else is neutral. */
+export type AppAccent = 'green' | 'rose' | 'sky' | 'lime' | 'sun' | 'violet';
+/** Something an application reaches. */
+export interface AppConnectionSpec {
+    /** An MCP server, `id` or `id:version`. */
+    server: string;
+    access: 'read' | 'write';
+    /** In whose name: the builder's account, or each user's own. */
+    as: 'owner' | 'user';
+    /** The tools it may use, by name or pattern; all when empty. */
+    only: string[];
+}
+/** When an application acts alone, and when it asks. */
+export interface AppRuleSpec {
+    /** The action, in the words a person reads. */
+    action: string;
+    /** Classes of action, or tools (`server.tool`), the rule applies to. */
+    appliesTo: string[];
+    behaviour: AppBehaviour;
+}
+/** What an application may reach beside its connections. Nothing, unless said. */
+export interface AppPermissionsSpec {
+    /** The Spaces it reads or writes. */
+    spaces: Array<{
+        space: string;
+        access: 'read' | 'write';
+    }>;
+    /** Its computer; each off until it is turned on. */
+    computer: {
+        browse: boolean;
+        files: boolean;
+        shell: boolean;
+    };
+}
+export interface AppStarterSpec {
+    label: string;
+    message: string;
+}
+export interface AppSettingSpec {
+    id: string;
+    type: 'select' | 'text' | 'toggle' | 'slider' | 'number';
+    label: string;
+    options: string[];
+    default?: string | boolean | number;
+    min?: number;
+    max?: number;
+}
+/** The component tree a user meets, over the approved catalog (A2UI). */
+export interface AppSurfaceSpec {
+    protocol: string;
+    components: Array<{
+        id: string;
+        component: string;
+        [property: string]: unknown;
+    }>;
+    composedBy: string;
+    composedAt: string;
+}
+/** What the user of an application sees. */
+export interface AppInterfaceSpec {
+    layout: AppLayout;
+    accent: AppAccent;
+    welcome: string;
+    starters: AppStarterSpec[];
+    settings: AppSettingSpec[];
+    /** The components of the catalog the surface may use. */
+    components: string[];
+    surface?: AppSurfaceSpec;
+}
+export interface AppTestCaseSpec {
+    ask: string;
+    expect: string;
+}
+/** How an application is verified. */
+export interface AppTestsSpec {
+    /** The share of tests that has to pass for it to be ready. */
+    readyAt: number;
+    evalset: string;
+    cases: AppTestCaseSpec[];
+}
+/** What is kept of what an application did, and for how long. */
+export interface AppRecordSpec {
+    /** The retention, e.g. `1_years`. */
+    keepFor: string;
+    retentionDays: number;
+    include: string[];
+}
+/** Optional checks from the catalogue. */
+export interface AppChecksSpec {
+    guards: string[];
+    gates: string[];
+    track: string;
+}
+export interface AppDeploymentSpec {
+    hosted?: {
+        visibility: 'private' | 'invited' | 'organization' | 'link' | 'public';
+        slug: string;
+    };
+    embedded?: {
+        mode: 'inline' | 'bubble' | 'panel';
+        origins: string[];
+    };
+}
+/** What starts a worker's work. */
+export interface AppTriggerSpec {
+    type: 'schedule' | 'event' | 'once';
+    cron: string;
+    event: string;
+    at: string;
+    description: string;
+    prompt: string;
+}
+export interface AppCriterionSpec {
+    name: string;
+    kind: 'metric' | 'noul' | 'choice' | 'score';
+    weight: number;
+    instructions: string;
+    options: string[];
+    direction: 'higher' | 'lower';
+    measure: '' | 'pass_rate' | 'cost_per_task' | 'seconds_per_task';
+}
+export interface AppScenarioSpec {
+    name: string;
+    weights: Record<string, number>;
+}
+/** What a decision application decides. */
+export interface AppDecisionSpec {
+    question: string;
+    alternatives: string[];
+    criteria: AppCriterionSpec[];
+    minConfidence: number;
+    scenarios: AppScenarioSpec[];
+    judgmentModel: string;
+}
+/**
+ * An application (`agentspecs/apps`): the Appspec. An agent with an interface,
+ * rules, tests and a place to run — a chat, a widget, a decision or a worker.
+ * It stands alone: Guards, Gates and a Track are optional, under `checks`.
+ * In the generated catalogue it carries its layout, and what it names that
+ * is not enabled (`setup`).
+ */
+export interface AppSpec {
+    /** The version of the spec itself: `loop.app/v1`. */
+    schema: string;
+    id: string;
+    version: string;
+    name: string;
+    kind: AppKind;
+    description: string;
+    owner: string;
+    /** The agent or the Cog that does the work; empty when a team does. */
+    agent: string;
+    team: string;
+    instructions: string;
+    model: string;
+    skills: string[];
+    tools: string[];
+    /** The Frames it works under. */
+    context: string[];
+    /** The documents and datasets it answers from. */
+    contents: string[];
+    connections: AppConnectionSpec[];
+    rules: AppRuleSpec[];
+    permissions: AppPermissionsSpec;
+    interface: AppInterfaceSpec;
+    tests: AppTestsSpec;
+    record: AppRecordSpec;
+    checks: AppChecksSpec;
+    deployment: AppDeploymentSpec;
+    /** For a worker: what it works toward. */
+    goal: string;
+    triggers: AppTriggerSpec[];
+    memory: string;
+    notifications: string[];
+    decision?: AppDecisionSpec;
+    /** What it names that is not enabled today, in sentences. */
+    setup: string[];
+    enabled: boolean;
+    tags: string[];
+    icon?: string;
+    /** Its face: one emoji, shown wherever the application appears. */
+    emoji: string;
+}
 export interface Agentspec {
     /** Unique agent identifier */
     id: string;
@@ -154,8 +605,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.17",
     "type": "module",
     "workspaces": [
         ".",
@@ -264,6 +264,7 @@
         "uuid": "^13.0.0",
         "validator": "^13.7.0",
         "vaul": "^1.1.2",
+        "yaml": "^2.9.0",
         "zod": "^4.1.13",
         "zustand": "^4.4.1"
     },

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())