@datalayer/agent-runtimes 1.3.58 → 1.3.60

package/package.json

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

package/scripts/codegen/generate_agents.py

@@ -234,6 +234,15 @@ def load_fragments(specs_dir: Path) -> List[Dict[str, Any]]:
     return fragments
 
 
+def refuse_tools_field(spec: Dict[str, Any], path: Path) -> None:
+    """Refuse an agent spec that still says `tools`: it is `backend_tools` now."""
+    if "tools" in spec:
+        raise SystemExit(
+            f"Error: {path} says `tools`: the field is `backend_tools` — the tools "
+            "that run on the runtime, as `frontend_tools` are those that run on the page"
+        )
+
+
 def load_yaml_specs(specs_dir: Path) -> List[tuple[str, Dict[str, Any]]]:
     """
     Load all YAML agent specifications from directory and subdirectories.
@@ -254,6 +263,7 @@ def load_yaml_specs(specs_dir: Path) -> List[tuple[str, Dict[str, Any]]]:
             spec = yaml.safe_load(f)
             if spec:  # Skip empty files
                 ensure_spec_version(spec)
+                refuse_tools_field(spec, yaml_file)
                 specs.append(("", spec))
 
     # Then, load specs from subdirectories (one level deep)
@@ -264,6 +274,7 @@ def load_yaml_specs(specs_dir: Path) -> List[tuple[str, Dict[str, Any]]]:
                     spec = yaml.safe_load(f)
                     if spec:  # Skip empty files
                         ensure_spec_version(spec)
+                        refuse_tools_field(spec, yaml_file)
                         specs.append((subdir.name, spec))
 
     fragments = load_fragments(specs_dir)
@@ -399,7 +410,7 @@ from agent_runtimes.types import (
                 for skill in spec.get("skills", [])
             ]
             tool_refs = [
-                versioned_ref(*split_spec_ref(tool)) for tool in spec.get("tools", [])
+                versioned_ref(*split_spec_ref(tool)) for tool in spec.get("backend_tools", [])
             ]
             frontend_tool_refs = [
                 versioned_ref(*split_spec_ref(ft))
@@ -591,7 +602,7 @@ from agent_runtimes.types import (
 {model_additionals_py_line}    inference_provider={inference_provider_str},
     mcp_servers=[{mcp_servers_str}],
     skills={_fmt_list(skill_refs)},
-    tools={_fmt_list(tool_refs)},
+    backend_tools={_fmt_list(tool_refs)},
 {disable_tool_approvals_line}    frontend_tools={_fmt_list(frontend_tool_refs)},
 {frontend_render_tools_py_line}    environment_name="{spec.get("environment_name", "ai-agents-env")}",
     icon={icon},
@@ -740,7 +751,7 @@ def generate_typescript_code(
             used_mcp_servers.add(versioned_ref(*split_spec_ref(server)))
         for skill in spec.get("skills", []):
             used_skills.add(versioned_ref(*split_spec_ref(skill)))
-        for tool in spec.get("tools", []):
+        for tool in spec.get("backend_tools", []):
             used_tools.add(versioned_ref(*split_spec_ref(tool)))
         for ft in spec.get("frontend_tools", []):
             used_frontend_tools.add(versioned_ref(*split_spec_ref(ft)))
@@ -786,7 +797,7 @@ def generate_typescript_code(
         if tref in used_tools:
             const_name = (
                 tid.upper().replace("-", "_")
-                + "_TOOL_SPEC"
+                + "_BACKEND_TOOL_SPEC"
                 + version_suffix(spec["version"])
             )
             tool_imports.append(const_name)
@@ -830,7 +841,7 @@ def generate_typescript_code(
     types_import_path = "../../types" if is_root_layout else "../../../types"
     mcp_import_path = "../mcpServers" if is_root_layout else "../../mcpServers"
     skills_import_path = "../skills" if is_root_layout else "../../skills"
-    tools_import_path = "../tools" if is_root_layout else "../../tools"
+    tools_import_path = "../backendTools" if is_root_layout else "../../backendTools"
     frontend_tools_import_path = (
         "../frontendTools" if is_root_layout else "../../frontendTools"
     )
@@ -929,7 +940,7 @@ function toAgentSkillSpec(skill: SkillSpec) {
     if has_tools:
         code += """
 /**
- * Map tool IDs to ToolSpec objects.
+ * Map backend tool IDs to BackendToolSpec objects.
  */
 const TOOL_MAP: Record<string, any> = {
 """
@@ -1019,9 +1030,9 @@ const FRONTEND_TOOL_MAP: Record<string, any> = {
             else:
                 skills_str = ""
 
-            # Get tools - resolve to ToolSpec via TOOL_MAP
+            # Get backend tools - resolve to BackendToolSpec via TOOL_MAP
             tool_ids_list = [
-                versioned_ref(*split_spec_ref(sid)) for sid in spec.get("tools", [])
+                versioned_ref(*split_spec_ref(sid)) for sid in spec.get("backend_tools", [])
             ]
             if has_tools and tool_ids_list:
                 tools_str = ", ".join(f"TOOL_MAP['{tid}']" for tid in tool_ids_list)
@@ -1165,7 +1176,7 @@ const FRONTEND_TOOL_MAP: Record<string, any> = {
     model: {model_ts},
 {model_additionals_ts_line}{inference_provider_line}    mcpServers: [{mcp_servers_str}],
     skills: [{skills_str}].filter(Boolean) as SkillSpec[],
-    tools: [{tools_str}],
+    backendTools: [{tools_str}],
 {disable_tool_approvals_line}    frontendTools: [{frontend_tools_str}],
 {frontend_render_tools_ts_line}    environmentName: '{spec.get("environment_name", "ai-agents-env")}',
     icon: {icon},
@@ -1338,7 +1349,7 @@ def generate_subfolder_structure(specs: List[tuple[str, Dict[str, Any]]], args):
     # Get MCP and skills specs directories
     mcp_specs_dir = args.specs_dir.parent / "mcp-servers"
     skills_specs_dir = args.specs_dir.parent / "skills"
-    tools_specs_dir = args.specs_dir.parent / "tools"
+    tools_specs_dir = args.specs_dir.parent / "backend-tools"
 
     # Determine base directories
     python_base = args.python_output.parent / "agents"
@@ -1624,7 +1635,7 @@ export * from './modelProviders';
 export * from './notifications';
 export * from './outputs';
 export * from './skills';
-export * from './tools';
+export * from './backendTools';
 export * from './triggers';
 export * from './uiPlugins';
 export * from './frames';
@@ -1698,7 +1709,7 @@ def main():
         # Get MCP and skills specs directories (siblings to agents directory)
         mcp_specs_dir = args.specs_dir.parent / "mcp-servers"
         skills_specs_dir = args.specs_dir.parent / "skills"
-        tools_specs_dir = args.specs_dir.parent / "tools"
+        tools_specs_dir = args.specs_dir.parent / "backend-tools"
         typescript_code = generate_typescript_code(
             specs,
             str(mcp_specs_dir),

package/scripts/codegen/generate_apps.py

@@ -52,6 +52,7 @@ CAMEL = {
     "composed_at": "composedAt",
     "min_confidence": "minConfidence",
     "decision_model": "decisionModel",
+    "backend_tools": "backendTools",
 }
 
 #: The keys whose value is carried as it is written: a component tree, weights by name.
@@ -350,7 +351,7 @@ def generate_actions_python_code(actions: dict[str, Any]) -> str:
         f"ACTION_CLASSES: List[str] = {actions['classes']!r}",
         "",
         "#: What each tool of the tools catalogue does, by id.",
-        f"TOOL_ACTIONS: Dict[str, List[str]] = {actions['tools']!r}",
+        f"BACKEND_TOOL_ACTIONS: Dict[str, List[str]] = {actions['tools']!r}",
         "",
         "#: What each MCP server's tools do, by server id. `checked` is the day the",
         "#: names were read off the running server, or None when nobody looked.",
@@ -401,7 +402,7 @@ def generate_actions_typescript_code(actions: dict[str, Any]) -> str:
         f"export const ACTION_CLASSES: ActionClass[] = {json.dumps(actions['classes'])};",
         "",
         "/** What each tool of the tools catalogue does, by id. */",
-        "export const TOOL_ACTIONS: Record<string, ActionClass[]> = "
+        "export const BACKEND_TOOL_ACTIONS: Record<string, ActionClass[]> = "
         + json.dumps(actions["tools"], indent=2)
         + ";",
         "",

package/scripts/codegen/{generate_tools.py → generate_backend_tools.py}

@@ -88,7 +88,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
         "# Copyright (c) 2025-2026 Datalayer, Inc.",
         "# Distributed under the terms of the Modified BSD License.",
         '"""',
-        "Tool Catalog.",
+        "Backend Tool Catalog.",
         "",
         "Predefined runtime tools that can be attached to agents.",
         "",
@@ -98,11 +98,11 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
         "",
         "from typing import Dict, List",
         "",
-        "from agent_runtimes.types import ToolRuntimeSpec, ToolSpec",
+        "from agent_runtimes.types import BackendToolRuntimeSpec, BackendToolSpec",
         "",
         "",
         "# " + "=" * 76,
-        "# Tool Definitions",
+        "# Backend Tool Definitions",
         "# " + "=" * 76,
         "",
     ]
@@ -111,7 +111,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
         tool_id = spec["id"]
         version = spec["version"]
         const_name = (
-            f"{tool_id.upper().replace('-', '_')}_TOOL_SPEC{version_suffix(version)}"
+            f"{tool_id.upper().replace('-', '_')}_BACKEND_TOOL_SPEC{version_suffix(version)}"
         )
         runtime = _require_runtime(spec)
         requires_approval = _requires_approval(spec)
@@ -122,7 +122,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
 
         lines.extend(
             [
-                f"{const_name} = ToolSpec(",
+                f"{const_name} = BackendToolSpec(",
                 f'    id="{tool_id}",',
                 f'    version="{version}",',
                 f"    name={json.dumps(spec['name'], ensure_ascii=False)},",
@@ -132,7 +132,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
                 f'    approval="{spec.get("approval", "auto")}",',
                 f"    timeout={timeout_py},",
                 f"    requires_approval={requires_approval},",
-                "    runtime=ToolRuntimeSpec(",
+                "    runtime=BackendToolRuntimeSpec(",
                 f'        language="{runtime["language"]}",',
                 f'        package="{runtime["package"]}",',
                 f'        method="{runtime["method"]}",',
@@ -147,10 +147,10 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
     lines.extend(
         [
             "# " + "=" * 76,
-            "# Tool Catalog",
+            "# Backend Tool Catalog",
             "# " + "=" * 76,
             "",
-            "TOOL_CATALOG: Dict[str, ToolSpec] = {",
+            "BACKEND_TOOL_CATALOG: Dict[str, BackendToolSpec] = {",
         ]
     )
 
@@ -158,7 +158,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
         tool_id = spec["id"]
         version = spec["version"]
         const_name = (
-            f"{tool_id.upper().replace('-', '_')}_TOOL_SPEC{version_suffix(version)}"
+            f"{tool_id.upper().replace('-', '_')}_BACKEND_TOOL_SPEC{version_suffix(version)}"
         )
         lines.append(f'    "{tool_id}": {const_name},')
 
@@ -167,20 +167,20 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
             "}",
             "",
             "",
-            "def get_tool_spec(tool_id: str) -> ToolSpec | None:",
+            "def get_backend_tool_spec(tool_id: str) -> BackendToolSpec | None:",
             '    """Get a tool specification by ID (accepts both bare and versioned refs)."""',
-            "    spec = TOOL_CATALOG.get(tool_id)",
+            "    spec = BACKEND_TOOL_CATALOG.get(tool_id)",
             "    if spec is not None:",
             "        return spec",
             "    base, _, ver = tool_id.rpartition(':')",
             "    if base and '.' in ver:",
-            "        return TOOL_CATALOG.get(base)",
+            "        return BACKEND_TOOL_CATALOG.get(base)",
             "    return None",
             "",
             "",
-            "def list_tool_specs() -> List[ToolSpec]:",
+            "def list_backend_tool_specs() -> List[BackendToolSpec]:",
             '    """List all tool specifications."""',
-            "    return list(TOOL_CATALOG.values())",
+            "    return list(BACKEND_TOOL_CATALOG.values())",
             "",
         ]
     )
@@ -196,7 +196,7 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
         " */",
         "",
         "/**",
-        " * Tool Catalog",
+        " * Backend Tool Catalog",
         " *",
         " * Predefined runtime tools that can be attached to agents.",
         " *",
@@ -204,10 +204,10 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
         " * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",
         " */",
         "",
-        "import type { ToolSpec } from '../types';",
+        "import type { BackendToolSpec } from '../types';",
         "",
         "// " + "=" * 76,
-        "// Tool Definitions",
+        "// Backend Tool Definitions",
         "// " + "=" * 76,
         "",
     ]
@@ -216,7 +216,7 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
         tool_id = spec["id"]
         version = spec["version"]
         const_name = (
-            f"{tool_id.upper().replace('-', '_')}_TOOL_SPEC{version_suffix(version)}"
+            f"{tool_id.upper().replace('-', '_')}_BACKEND_TOOL_SPEC{version_suffix(version)}"
         )
         runtime = _require_runtime(spec)
         requires_approval = _requires_approval(spec)
@@ -228,7 +228,7 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
 
         lines.extend(
             [
-                f"export const {const_name}: ToolSpec = {{",
+                f"export const {const_name}: BackendToolSpec = {{",
                 f"  id: '{tool_id}',",
                 f"  version: '{version}',",
                 # JSON-escaped: an apostrophe in a description is not a syntax error.
@@ -254,10 +254,10 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
     lines.extend(
         [
             "// " + "=" * 76,
-            "// Tool Catalog",
+            "// Backend Tool Catalog",
             "// " + "=" * 76,
             "",
-            "export const TOOL_CATALOG: Record<string, ToolSpec> = {",
+            "export const BACKEND_TOOL_CATALOG: Record<string, BackendToolSpec> = {",
         ]
     )
 
@@ -265,7 +265,7 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
         tool_id = spec["id"]
         version = spec["version"]
         const_name = (
-            f"{tool_id.upper().replace('-', '_')}_TOOL_SPEC{version_suffix(version)}"
+            f"{tool_id.upper().replace('-', '_')}_BACKEND_TOOL_SPEC{version_suffix(version)}"
         )
         lines.append(f"  '{tool_id}': {const_name},")
 
@@ -273,22 +273,22 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
         [
             "};",
             "",
-            "export function getToolSpecs(): ToolSpec[] {",
-            "  return Object.values(TOOL_CATALOG);",
+            "export function getBackendToolSpecs(): BackendToolSpec[] {",
+            "  return Object.values(BACKEND_TOOL_CATALOG);",
             "}",
             "",
-            "function resolveToolId(toolId: string): string {",
-            "  if (toolId in TOOL_CATALOG) return toolId;",
+            "function resolveBackendToolId(toolId: string): string {",
+            "  if (toolId in BACKEND_TOOL_CATALOG) return toolId;",
             "  const idx = toolId.lastIndexOf(':');",
             "  if (idx > 0) {",
             "    const base = toolId.slice(0, idx);",
-            "    if (base in TOOL_CATALOG) return base;",
+            "    if (base in BACKEND_TOOL_CATALOG) return base;",
             "  }",
             "  return toolId;",
             "}",
             "",
-            "export function getToolSpec(toolId: string): ToolSpec | undefined {",
-            "  return TOOL_CATALOG[resolveToolId(toolId)];",
+            "export function getBackendToolSpec(toolId: string): BackendToolSpec | undefined {",
+            "  return BACKEND_TOOL_CATALOG[resolveBackendToolId(toolId)];",
             "}",
             "",
         ]

package/scripts/codegen/generate_cogs.py

@@ -168,7 +168,7 @@ def generate_typescript_code(specs: list[dict[str, Any]], specs_dir: Path) -> st
         [("", spec) for spec in specs],
         str(root / "mcp-servers"),
         str(root / "skills"),
-        str(root / "tools"),
+        str(root / "backend-tools"),
     )
     marker = "// ============================================================================\n// Agent Specs Registry"
     if marker not in code:
@@ -208,7 +208,7 @@ def generate_typescript_code(specs: list[dict[str, Any]], specs_dir: Path) -> st
     # is one directory up, beside the catalogues it imports.
     head = head.replace("from '../../types'", "from '../types'")
     head = re.sub(
-        r"from '\.\./(mcpServers|skills|tools|frontendTools)'", r"from './\1'", head
+        r"from '\.\./(mcpServers|skills|backendTools|frontendTools)'", r"from './\1'", head
     )
 
     lines = [

package/scripts/codegen/generate_frames.py

@@ -53,13 +53,13 @@ FIELDS = (
     "architecture",
     "prompts",
     "skills",
-    "tools",
+    "backend_tools",
     "mcp_servers",
     "guards",
 )
 
 #: Python field → TypeScript property, where they differ.
-CAMEL = {"mcp_servers": "mcpServers"}
+CAMEL = {"mcp_servers": "mcpServers", "backend_tools": "backendTools"}
 
 
 def load_frame_specs(specs_dir: Path) -> list[dict[str, Any]]:

package/lib/specs/tools.d.ts

@@ -1,31 +0,0 @@
-/**
- * Tool Catalog
- *
- * Predefined runtime tools that can be attached to agents.
- *
- * This file is AUTO-GENERATED from YAML specifications.
- * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.
- */
-import type { ToolSpec } from '../types';
-export declare const CREATE_PLAN_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const CURRENT_TIME_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const DECIDE_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const DISPLAY_RECIPE_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const EXAMPLE_CREATE_PLAN_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const EXAMPLE_CURRENT_TIME_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const EXAMPLE_DISPLAY_RECIPE_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const EXAMPLE_GENERATE_HAIKU_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const EXAMPLE_GENERATE_TASK_STEPS_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const EXAMPLE_GET_WEATHER_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const EXAMPLE_RENDER_A2UI_SURFACE_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const EXAMPLE_UPDATE_PLAN_STEP_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const GENERATE_HAIKU_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const GENERATE_TASK_STEPS_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const GET_WEATHER_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const RUNTIME_ECHO_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const RUNTIME_SEND_MAIL_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const RUNTIME_SENSITIVE_ECHO_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const UPDATE_PLAN_STEP_TOOL_SPEC_0_0_1: ToolSpec;
-export declare const TOOL_CATALOG: Record<string, ToolSpec>;
-export declare function getToolSpecs(): ToolSpec[];
-export declare function getToolSpec(toolId: string): ToolSpec | undefined;