@datalayer/agent-runtimes 1.3.59 → 1.3.61

package/lib/stories/loop/ReferenceScreens.js

@@ -28,6 +28,8 @@ import { InputPrompt } from '../../chat/prompt/InputPrompt';
 import { PresenceFace, PresenceLine } from '../../chat/presence/Presence';
 import { AssistantStage, } from '../../chat/assistant/AssistantStage';
 import { ASSISTANT_WORDS, } from '../../chat/assistant/state';
+import { CONVERSATION_BALLOON_WIDTH, ConversationBalloonClose, balloonTailAt, conversationBalloonHeight, conversationBalloonSx, peekLine, } from '../../chat/assistant/ConversationBalloon';
+import { DecisionAsk } from '../../chat/assistant/DecisionAsk';
 import { buildReactorFromPlugins } from '@datalayer/reactor';
 import { AssistantCharactersPlugin, assistantCharacterNamed, } from '../../loop/plugins/assistant-characters';
 import { OwlCharacterPlugin } from '../../examples/utils/owlCharacterPlugin';
@@ -39,7 +41,11 @@ export const REFERENCE_SCREENS = [
     'approval',
     'tool-marks',
 ];
-/** The floating assistant's pictures (T-27): its states, and stepped aside. */
+/**
+ * The floating assistant's pictures (T-27): its states — closed, a peek
+ * where it has something to say — stepped aside, and open, the conversation
+ * as its balloon (T-23).
+ */
 export const ASSISTANT_PICTURES = [
     'idle',
     'thinking',
@@ -48,6 +54,7 @@ export const ASSISTANT_PICTURES = [
     'paused',
     'speaking',
     'aside',
+    'open',
 ];
 /**
  * The characters pictured idle, each in light and dark (T-25, T-24):
@@ -232,9 +239,10 @@ export const REFERENCE_SCREEN_COMPONENTS = {
 // The floating assistant (T-27)
 // ---------------------------------------------------------------------------
 const BALLOONS = {
+    // A new message, peeked by its first words (T-23).
     speaking: {
-        text: 'Three customers wrote about late deliveries this week: Ada, Grace and Alan.',
-        more: true,
+        ...peekLine('Three customers wrote about late deliveries this week: Ada, Grace and Alan.'),
+        onDismiss: () => undefined,
     },
     // An approval it waits on, answered in the balloon (T-23).
     waiting: {
@@ -257,9 +265,9 @@ const BALLOONS = {
  */
 export function AssistantScreen({ picture, }) {
     const stageRef = useRef(null);
-    const state = picture === 'aside' ? 'idle' : picture;
+    const state = picture === 'aside' || picture === 'open' ? 'idle' : picture;
     const balloon = BALLOONS[picture];
-    return (_jsxs(Box, { sx: { flex: 1, position: 'relative' }, children: [picture === 'aside' && (_jsxs(Box, { role: "dialog", "aria-label": "A dialog over the assistant", sx: {
+    return (_jsxs(Box, { sx: { flex: 1, position: 'relative' }, children: [picture === 'open' && _jsx(OpenConversation, {}), picture === 'aside' && (_jsxs(Box, { role: "dialog", "aria-label": "A dialog over the assistant", sx: {
                     position: 'fixed',
                     right: 24,
                     bottom: 24,
@@ -272,7 +280,56 @@ export function AssistantScreen({ picture, }) {
                     borderColor: 'border.default',
                     borderRadius: 'var(--theme-radius-card, 6px)',
                     boxShadow: 'var(--theme-shadow, none)',
-                }, children: [_jsx(Text, { sx: { fontWeight: 600 }, children: "A dialog" }), _jsx(Text, { as: "p", sx: { color: 'fg.muted', fontSize: 1 }, children: "The assistant steps aside while this is open." })] })), _jsx(AssistantStage, { character: "paperclip", state: state, place: { right: 48, bottom: 48 }, stageRef: stageRef, onDragStart: () => undefined, open: false, onToggle: () => undefined, balloon: balloon, insist: !!balloon, onDismiss: () => undefined })] }));
+                }, children: [_jsx(Text, { sx: { fontWeight: 600 }, children: "A dialog" }), _jsx(Text, { as: "p", sx: { color: 'fg.muted', fontSize: 1 }, children: "The assistant steps aside while this is open." })] })), _jsx(AssistantStage, { character: "paperclip", state: state, place: { right: 48, bottom: 48 }, stageRef: stageRef, onDragStart: () => undefined, open: picture === 'open', onToggle: () => undefined, balloon: balloon, insist: !!balloon, onDismiss: () => undefined })] }));
+}
+/** What the open picture's conversation holds. */
+const OPEN_CONVERSATION = [
+    said('w', 'assistant', 'Hello! Ask me anything about this page.'),
+    said('o1', 'user', 'Which customers wrote about late deliveries this week?'),
+    said('o2', 'assistant', 'Three of them: **Ada**, **Grace** and **Alan**. Ada’s parcel is two days late; the other two are waiting for a reply.'),
+];
+/**
+ * The conversation open, as the assistant's balloon (T-23): over the
+ * character in the page's corner, its tail toward it, the history with the
+ * welcome first, *Ask a decision* beside the composer, the Lexical composer
+ * last, and its close in the corner — no header, no footer.
+ */
+function OpenConversation() {
+    const endRef = useRef(null);
+    const [input, setInput] = useState('');
+    const height = conversationBalloonHeight(window.innerHeight);
+    const left = window.innerWidth - 48 - CONVERSATION_BALLOON_WIDTH;
+    return (_jsxs(Box, { "data-conversation-balloon": "", sx: {
+            position: 'fixed',
+            right: '48px',
+            bottom: `${48 + 88 + 16}px`,
+            width: `${CONVERSATION_BALLOON_WIDTH}px`,
+            height: `${height}px`,
+            zIndex: 1001,
+            display: 'flex',
+            flexDirection: 'column',
+            bg: 'canvas.default',
+            border: '1px solid',
+            borderColor: 'border.default',
+            boxShadow: 'shadow.extra-large',
+            ...conversationBalloonSx({
+                edge: 'bottom',
+                at: balloonTailAt(window.innerWidth - 48 - 44, left),
+            }, 'canvas.subtle'),
+        }, children: [_jsx(ConversationBalloonClose, { onClose: () => undefined }), _jsxs(Box, { sx: {
+                    flex: 1,
+                    minHeight: 0,
+                    display: 'flex',
+                    flexDirection: 'column',
+                    borderRadius: 'var(--theme-radius-bubble, 16px)',
+                    overflow: 'hidden',
+                }, children: [_jsx(Box, { sx: { flex: 1, minHeight: 0, overflow: 'auto' }, children: _jsx(ChatMessageList, { displayItems: OPEN_CONVERSATION, isLoading: false, isStreaming: false, showLoadingIndicator: false, hideMessagesAfterToolUI: false, avatarConfig: { ...AVATARS, showAvatars: true }, padding: 2, emptyContent: null, messagesEndRef: endRef, onRespond: async () => undefined }) }), _jsx(Box, { sx: {
+                            px: 3,
+                            pb: 1,
+                            display: 'flex',
+                            justifyContent: 'flex-end',
+                            fontSize: 0,
+                        }, children: _jsx(DecisionAsk, { ask: async () => ({}) }) }), _jsx(InputPrompt, { input: input, setInput: setInput, isLoading: false, connectionConfirmed: true, placeholder: "Type a message...", autoFocus: false, padding: 2, promptVariant: "lexical", onSend: () => undefined, onStop: () => undefined, showTokenUsage: false, showModelSelector: false, showToolsMenu: false, showSkillsMenu: false, showAgentsMenu: false, codemodeEnabled: false, hasConfigData: false, hasSkillsData: false, isA2AProtocol: false })] })] }));
 }
 // ---------------------------------------------------------------------------
 // The characters (T-25, T-24)

package/lib/types/agentspecs.d.ts

@@ -1,6 +1,6 @@
 import type { SkillSpec } from './skills';
 import type { MCPServer, AgentMCPServerToolConfig } from './mcp';
-import type { ToolSpec, FrontendToolSpec, FrontendRenderToolSpec } from './tools';
+import type { BackendToolSpec, FrontendToolSpec, FrontendRenderToolSpec } from './tools';
 import type { AgentTriggerConfig } from './triggers';
 import type { AgentModelConfig } from './models';
 import type { AgentOutputConfig } from './outputs';
@@ -172,7 +172,8 @@ export interface FrameSpec {
     architecture: string;
     prompts: FramePromptSpec[];
     skills: string[];
-    tools: string[];
+    /** Backend tools (agentspecs/backend-tools), `id:version`. */
+    backendTools: string[];
     mcpServers: string[];
     guards: FrameGuardSpec[];
 }
@@ -568,7 +569,8 @@ export interface AppSpec {
     instructions: string;
     model: string;
     skills: string[];
-    tools: string[];
+    /** Backend tools (agentspecs/backend-tools) it adds to its agent's. */
+    backendTools: string[];
     /** The Frames it works under. */
     context: string[];
     /** The documents and datasets it answers from. */
@@ -634,8 +636,8 @@ export interface Agentspec {
     mcpServers: MCPServer[];
     /** Skills available to this agent */
     skills: SkillSpec[];
-    /** Runtime tools available to this agent */
-    tools?: ToolSpec[];
+    /** Backend tools available to this agent: they run on the runtime */
+    backendTools?: BackendToolSpec[];
     /** Disable tool approvals for this spec (default: false). */
     disableToolApprovals?: boolean;
     /** Frontend tool sets available to this agent */

package/lib/types/chat.d.ts

@@ -964,6 +964,18 @@ export interface ChatBaseProps {
     notebookToolSurfacesId?: string;
     /** Custom footer content (rendered above input) */
     footerContent?: ReactNode;
+    /**
+     * The agent's welcome, said as the first message of the history: drawn as
+     * the chat draws the agent's messages, and never sent nor kept. The floating
+     * assistant's balloon opens on it (LOOP T-23).
+     */
+    welcome?: string;
+    /**
+     * What follows the last message, inside the history and scrolled with it:
+     * the floating assistant's balloon holds an approval there, as a message
+     * with *Approve* and *Deny* (T-23).
+     */
+    trailingContent?: ReactNode;
     /**
      * Show the information icon in the header.
      * When clicked, fires onInformationClick.

package/lib/types/config.d.ts

@@ -26,8 +26,8 @@ export interface AgentConfig {
     protocol?: Protocol;
     /** Optional agent spec ID for server-side spec-based creation. */
     agentSpecId?: string;
-    /** Optional custom tools payload. */
-    tools?: unknown[];
+    /** Backend tool ids (agentspecs/backend-tools) to enable: they run on the runtime. */
+    backendTools?: unknown[];
     /** Enable skills for this agent. */
     enableSkills?: boolean;
     /** Optional inference provider override (e.g. local, datalayer). */

package/lib/types/tools.d.ts

@@ -1,7 +1,7 @@
 /**
  * Runtime binding metadata for a tool implementation.
  */
-export interface ToolRuntimeSpec {
+export interface BackendToolRuntimeSpec {
     /** Implementation language */
     language: 'python' | 'typescript';
     /** Module/package containing the implementation */
@@ -12,7 +12,7 @@ export interface ToolRuntimeSpec {
 /**
  * Specification for a runtime tool.
  */
-export interface ToolSpec {
+export interface BackendToolSpec {
     /** Unique tool identifier */
     id: string;
     /** Version */
@@ -32,7 +32,7 @@ export interface ToolSpec {
     /** Whether tool requires human approval before execution */
     requiresApproval?: boolean;
     /** Runtime binding metadata */
-    runtime: ToolRuntimeSpec;
+    runtime: BackendToolRuntimeSpec;
     /** The icon, `<package>:<name>` — `@datalayer/icons-react:odoo` (agentspecs.marks; see `SpecMark`) */
     icon?: string;
     /** Drawn where there is no icon */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.59",
+    "version": "1.3.61",
     "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;