@datalayer/agent-runtimes 1.3.28 → 1.3.30

package/lib/specs/appspecSchema.js

@@ -311,6 +311,18 @@ export const APPSPEC_SCHEMA = {
                     default: null,
                     description: 'The component tree, when there is one',
                 },
+                assistant: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/AssistantCharacter',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'The character its floating assistant shows: `paperclip`, `wizard`, `cat` or `eyes`. The paper clip when unsaid; a person may choose another in their settings',
+                },
             },
             title: 'AppInterface',
             type: 'object',
@@ -553,7 +565,7 @@ export const APPSPEC_SCHEMA = {
                 },
                 composed_by: {
                     default: '',
-                    description: "Who composed it: a model's id, `developer`, `template`",
+                    description: "Who composed it: a model's id, `canvas` (a person on the Canvas), `developer`, `template`",
                     title: 'Composed By',
                     type: 'string',
                 },
@@ -659,6 +671,12 @@ export const APPSPEC_SCHEMA = {
             title: 'AppTrigger',
             type: 'object',
         },
+        AssistantCharacter: {
+            description: "The character an application's floating assistant shows (LOOP T-24):\none of those a UI plugin contributes. Datalayer's are these four.",
+            enum: ['paperclip', 'wizard', 'cat', 'eyes'],
+            title: 'AssistantCharacter',
+            type: 'string',
+        },
         Behaviour: {
             description: 'What an application does when it meets an action: the four a person chooses from.',
             enum: ['do_it', 'if_asked', 'ask_first', 'leave_to_me'],
@@ -673,7 +691,7 @@ export const APPSPEC_SCHEMA = {
         },
         EmbedMode: {
             description: "How an application sits in another product's page.",
-            enum: ['inline', 'bubble', 'panel'],
+            enum: ['inline', 'bubble', 'panel', 'assistant'],
             title: 'EmbedMode',
             type: 'string',
         },
@@ -684,7 +702,7 @@ export const APPSPEC_SCHEMA = {
                 mode: {
                     $ref: '#/$defs/EmbedMode',
                     default: 'inline',
-                    description: '`inline`, `bubble` or `panel`',
+                    description: '`inline`, `bubble`, `panel` or `assistant`',
                 },
                 origins: {
                     description: 'The origins allowed to embed it',

package/lib/types/agentspecs.d.ts

@@ -372,11 +372,24 @@ export interface ServerActionsSpec {
 }
 /** What kind of application it is: what its user meets. */
 export type AppKind = 'chat' | 'widget' | 'decision' | 'worker';
+/**
+ * How an application was built: in Python (its `app.py`), on the Canvas (its
+ * page composed there) or written out as its spec. Carried beside the
+ * catalogue (`APP_BUILT`), since an Appspec does not hold it.
+ */
+export type AppBuilt = 'python' | 'canvas' | 'written';
 /** 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';
+/**
+ * The character an application's floating assistant shows (LOOP T-24): one of
+ * those Datalayer's plugin contributes.
+ */
+export type AppAssistantCharacter = 'paperclip' | 'wizard' | 'cat' | 'eyes';
+/** How an application sits in another product's page (LOOP D-07). */
+export type AppEmbedMode = 'inline' | 'bubble' | 'panel' | 'assistant';
 /** Something an application reaches. */
 export interface AppConnectionSpec {
     /** An MCP server, `id` or `id:version`. */
@@ -443,6 +456,8 @@ export interface AppInterfaceSpec {
     /** The components of the catalog the surface may use. */
     components: string[];
     surface?: AppSurfaceSpec;
+    /** The character its floating assistant shows; the paper clip when unsaid. */
+    assistant?: AppAssistantCharacter;
 }
 export interface AppTestCaseSpec {
     ask: string;
@@ -474,7 +489,7 @@ export interface AppDeploymentSpec {
         slug: string;
     };
     embedded?: {
-        mode: 'inline' | 'bubble' | 'panel';
+        mode: AppEmbedMode;
         origins: string[];
     };
 }
@@ -586,6 +601,11 @@ export interface Agentspec {
     enabled: boolean;
     /** AI model identifier to use for this agent */
     model?: string;
+    /**
+     * Other models of the catalogue this agent may be switched to, beside its
+     * `model`. The runtime offers those of them its inference serves.
+     */
+    modelAdditionals?: string[];
     /** Inference provider routing strategy */
     inferenceProvider?: 'local' | 'datalayer';
     /** MCP servers used by this agent */

package/lib/types/chat.d.ts

@@ -66,7 +66,7 @@ export interface ToolCallCompleteContext {
  * - 'floating-draggable': The popup with a handle, movable anywhere in the viewport
  * - 'sidebar': Docked sidebar panel — offered only where the host has a mount point for it
  */
-export type ChatViewMode = 'floating' | 'floating-small' | 'floating-draggable' | 'sidebar';
+export type ChatViewMode = 'floating' | 'floating-small' | 'floating-draggable' | 'assistant' | 'sidebar';
 /**
  * Companion "ephemeral surface" shown next to the chat.
  * - 'none': chat only, no companion surface

package/lib/types/config.d.ts

@@ -45,7 +45,19 @@ export interface AgentConfig {
  * Remote configuration from server
  */
 export interface RemoteConfig {
+    /**
+     * The models on offer — for an agent, its `model` and `model_additionals` —
+     * each saying whether it can be used.
+     */
     models: ModelConfig[];
+    /**
+     * Who decided which models can be used: ai-inference's own list, or the
+     * runtime's configuration when it did not route through ai-inference or
+     * ai-inference did not answer.
+     */
+    modelsSource?: 'ai-inference' | 'local';
+    /** That decision in a sentence. */
+    modelsNote?: string;
     defaultModel?: string;
     builtinTools: BuiltinTool[];
     mcpServers?: MCPServerConfig[];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.28",
+    "version": "1.3.30",
     "type": "module",
     "workspaces": [
         ".",
@@ -56,6 +56,7 @@
         "build": "npm run clean && gulp resources-to-lib && tsc -b && cross-env NODE_OPTIONS=--max-old-space-size=8192 vite build",
         "build-storybook": "storybook build",
         "build:all": "npm run build && npm run build:examples",
+        "build:embed": "cross-env NODE_OPTIONS=--max-old-space-size=8192 vite build --config vite.embed.config.ts",
         "build:examples": "npm run build:nextjs",
         "build:lib": "npm run clean:lib && gulp resources-to-lib && tsc -b",
         "build:nextjs": "npm run build --workspace=nextjs-notebook-example",

package/scripts/codegen/generate_agents.py

@@ -276,9 +276,44 @@ def load_yaml_specs(specs_dir: Path) -> List[tuple[str, Dict[str, Any]]]:
             spec = resolve_spec(spec, by_id, fragments_by_id)
         resolved.append((subfolder, spec))
 
+    check_model_additionals(resolved, load_model_ids(specs_dir))
     return resolved
 
 
+def load_model_ids(specs_dir: Path) -> set[str]:
+    """Every id the models catalogue answers to: its ids and their aliases."""
+    ids: set[str] = set()
+    for yaml_file in sorted((specs_dir.parent / "models").glob("*.yaml")):
+        with open(yaml_file, "r") as f:
+            model = yaml.safe_load(f) or {}
+        if model.get("id"):
+            ids.add(str(model["id"]))
+        ids.update(str(alias) for alias in model.get("aliases") or [])
+    return ids
+
+
+def check_model_additionals(
+    specs: List[tuple[str, Dict[str, Any]]], model_ids: set[str]
+) -> None:
+    """Refuse an agent whose `model_additionals` names a model the catalogue does not know."""
+    problems = []
+    for _, spec in specs:
+        additionals = spec.get("model_additionals")
+        if additionals is None:
+            continue
+        if not isinstance(additionals, list):
+            problems.append(f"{spec.get('id')}: model_additionals is not a list")
+            continue
+        unknown = [str(m) for m in additionals if str(m) not in model_ids]
+        if unknown:
+            problems.append(
+                f"{spec.get('id')}: model_additionals names models the catalogue "
+                f"does not know: {', '.join(unknown)}"
+            )
+    if problems:
+        raise SystemExit("\n".join(problems))
+
+
 def generate_python_code(specs: List[tuple[str, Dict[str, Any]]]) -> str:
     """Generate Python code from agent specifications."""
     # Header
@@ -423,6 +458,12 @@ from agent_runtimes.types import (
             # Model field
             model_id = spec.get("model")
             model_str = f'"{model_id}"' if model_id else "None"
+            model_additionals = spec.get("model_additionals") or []
+            model_additionals_py_line = (
+                f"    model_additionals={_fmt_list(model_additionals)},\n"
+                if model_additionals
+                else ""
+            )
             inference_provider = spec.get("inference_provider")
             inference_provider_str = (
                 f'"{inference_provider}"' if inference_provider else "None"
@@ -547,7 +588,7 @@ from agent_runtimes.types import (
     domain={f'"{domain_value}"' if domain_value else "None"},
     enabled={spec.get("enabled", True)},
     model={model_str},
-    inference_provider={inference_provider_str},
+{model_additionals_py_line}    inference_provider={inference_provider_str},
     mcp_servers=[{mcp_servers_str}],
     skills={_fmt_list(skill_refs)},
     tools={_fmt_list(tool_refs)},
@@ -1045,6 +1086,12 @@ const FRONTEND_TOOL_MAP: Record<string, any> = {
             # Model field
             model_id = spec.get("model")
             model_ts = f"'{model_id}'" if model_id else "undefined"
+            model_additionals = spec.get("model_additionals") or []
+            model_additionals_ts_line = (
+                f"    modelAdditionals: {_fmt_ts_literal(model_additionals)},\n"
+                if model_additionals
+                else ""
+            )
             inference_provider = spec.get("inference_provider")
             inference_provider_ts = (
                 f"'{inference_provider}'" if inference_provider else "undefined"
@@ -1116,7 +1163,7 @@ const FRONTEND_TOOL_MAP: Record<string, any> = {
     domain: {domain_ts},
     enabled: {str(spec.get("enabled", True)).lower()},
     model: {model_ts},
-{inference_provider_line}    mcpServers: [{mcp_servers_str}],
+{model_additionals_ts_line}{inference_provider_line}    mcpServers: [{mcp_servers_str}],
     skills: [{skills_str}].filter(Boolean) as SkillSpec[],
     tools: [{tools_str}],
 {disable_tool_approvals_line}    frontendTools: [{frontend_tools_str}],
@@ -1588,6 +1635,7 @@ export * from './tracks';
 export * from './ops';
 export * from './apps';
 export * from './actions';
+export * from './appspecSchema';
 """
     )
 

package/scripts/codegen/generate_apps.py

@@ -17,6 +17,11 @@ read, write, send, buy, delete, publish — read from ``agentspecs.actions``.
 Each application is validated here, by ``agentspecs`` itself, and arrives
 with its layout said and with what it names that is not enabled (`setup`).
 
+How each was built travels beside it (``APP_BUILT``), since an Appspec does
+not hold it: ``python`` when ``apps/<id>/app.py`` sits beside its spec
+(agentspecs >= 0.0.15), ``canvas`` when its page says it was composed on the
+Canvas (``composed_by: canvas``, agentspecs >= 0.0.23), else ``written``.
+
 Usage:
     python generate_apps.py \\
       --specs-dir agentspecs/agentspecs/apps \\
@@ -57,6 +62,16 @@ def _flat(text: Any) -> str:
     return " ".join(str(text or "").split())
 
 
+def built_of(specs_dir: Path, identity: str, app: Any) -> str:
+    """How an application was built: `python`, `canvas` or `written`."""
+    if (specs_dir / identity / "app.py").is_file():
+        return "python"
+    surface = app.interface.surface
+    if surface is not None and surface.composed_by == "canvas":
+        return "canvas"
+    return "written"
+
+
 def load_specs(specs_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
     """Every application, validated, as plain data — and the action classes."""
     apps_module = import_from_clone(specs_dir, "apps")
@@ -66,6 +81,7 @@ def load_specs(specs_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
     behaviours: dict[str, dict[str, str]] = {}
     escalations: dict[str, dict[str, Any]] = {}
     sources: dict[str, Any] = {}
+    built: dict[str, str] = {}
     for identity in sorted(apps):
         app = apps[identity]
         spec = app.model_dump(mode="json", by_alias=True)
@@ -78,6 +94,7 @@ def load_specs(specs_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
         }
         escalations[identity] = dict(sorted(apps_module.tool_escalations(app).items()))
         sources[identity] = apps_module.dump_app(app)
+        built[identity] = built_of(specs_dir, identity, app)
         for rule in spec["rules"]:
             rule["applies_to"] = (
                 [rule["applies_to"]]
@@ -129,6 +146,7 @@ def load_specs(specs_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
         "behaviours": behaviours,
         "escalations": escalations,
         "sources": sources,
+        "built": built,
     }
     return specs, actions
 
@@ -174,7 +192,7 @@ ABOUT_ACTIONS = [
 ]
 
 
-def generate_python_code(specs: list[dict[str, Any]]) -> str:
+def generate_python_code(specs: list[dict[str, Any]], built: dict[str, str]) -> str:
     """Generate the Python application catalogue."""
     lines = [
         "# Copyright (c) 2025-2026 Datalayer, Inc.",
@@ -185,7 +203,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
         *HEADER,
         '"""',
         "",
-        "from typing import Dict",
+        "from typing import Dict, Literal",
         "",
         "from agent_runtimes.types import AppSpec",
         "",
@@ -215,6 +233,10 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
         [
             "}",
             "",
+            "#: How each application was built: `python` (its `app.py`), `canvas` (its",
+            "#: page composed on the Canvas) or `written` (its spec written out).",
+            f"APP_BUILT: Dict[str, Literal['python', 'canvas', 'written']] = {built!r}",
+            "",
             "",
             "def get_app(app_id: str) -> AppSpec | None:",
             '    """An application, by `id` or `id:version`, or None."""',
@@ -235,7 +257,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
 
 
 def generate_typescript_code(
-    specs: list[dict[str, Any]], sources: dict[str, Any]
+    specs: list[dict[str, Any]], sources: dict[str, Any], built: dict[str, str]
 ) -> str:
     """Generate the TypeScript application catalogue."""
     lines = [
@@ -250,7 +272,7 @@ def generate_typescript_code(
         *[f" * {line}" for line in HEADER],
         " */",
         "",
-        "import type { AppKind, AppSpec } from '../types/agentspecs';",
+        "import type { AppBuilt, AppKind, AppSpec } from '../types/agentspecs';",
         "",
     ]
     for spec in specs:
@@ -288,6 +310,14 @@ def generate_typescript_code(
             + json.dumps(sources, indent=2, ensure_ascii=False)
             + ";",
             "",
+            "/**",
+            " * How each application was built: `python` (its `app.py`), `canvas` (its",
+            " * page composed on the Canvas) or `written` (its spec written out).",
+            " */",
+            "export const APP_BUILT: Record<string, AppBuilt> = "
+            + json.dumps(built, indent=2)
+            + ";",
+            "",
             "/** Every application of the catalogue, or those of a kind. */",
             "export function listApps(kind?: AppKind): AppSpec[] {",
             "  return Object.values(APP_CATALOGUE).filter(",
@@ -475,10 +505,10 @@ def main() -> None:
         sys.exit(1)
     specs, actions = load_specs(args.specs_dir)
     outputs = [
-        (args.python_output, generate_python_code(specs)),
+        (args.python_output, generate_python_code(specs, actions["built"])),
         (
             args.typescript_output,
-            generate_typescript_code(specs, actions["sources"]),
+            generate_typescript_code(specs, actions["sources"], actions["built"]),
         ),
         (args.actions_python_output, generate_actions_python_code(actions)),
         (args.actions_typescript_output, generate_actions_typescript_code(actions)),