@datalayer/agent-runtimes 1.3.85 → 1.3.86

package/lib/types/index.d.ts

@@ -31,6 +31,7 @@ export * from './outputs';
 export * from './personas';
 export * from './protocol';
 export * from './sandbox';
+export * from './scenes';
 export * from './skills';
 export * from './stream';
 export * from './teams';

package/lib/types/index.js

@@ -35,6 +35,7 @@ export * from './outputs';
 export * from './personas';
 export * from './protocol';
 export * from './sandbox';
+export * from './scenes';
 export * from './skills';
 export * from './stream';
 export * from './teams';

package/lib/types/scenes.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Scenes (agentspecs `scenes`, `schema: loop.scene/v1`, LOOP A-11): a team,
+ * staged. The team says who is on stage; the scene says what happens there —
+ * the setting, the script, the stage directions, the audience, the rehearsal
+ * and where it plays.
+ *
+ * In the generated catalogue the cast is resolved: every member of the team,
+ * each with its persona filled from its application, and the `entry` said.
+ *
+ * @module types/scenes
+ */
+import type { AppVerifiedSpec } from './agentspecs';
+import type { TeamLinkSpec } from './teams';
+/** How a member appears to the audience, in a scene. */
+export interface ScenePersonaSpec {
+    /** The name the audience sees. */
+    name: string;
+    /** One emoji, its face on stage. */
+    face: string;
+    /** One line of *who I am here*. */
+    line: string;
+}
+/** A member of the cast: a member of the team, with its persona and its brief. */
+export interface SceneCastMemberSpec {
+    /** Its id in the team. */
+    member: string;
+    /** The application it is, `id:version`; empty for an agent or a server. */
+    app: string;
+    /** The agent it is, when it is not an application. */
+    ref: string;
+    /** The MCP server it is, a system of the scene, when it is one. */
+    server: string;
+    /** What it is for, structurally: initiator, contributor, … */
+    role?: string;
+    /** Where its loop turns. */
+    runsIn?: 'browser' | 'runtime';
+    /** Whom it asks, and over what; absent when it asks nobody. */
+    talksTo?: TeamLinkSpec[];
+    persona: ScenePersonaSpec;
+    /** What it is for in this scene, over its application's instructions. */
+    brief: string;
+}
+/** A system on stage: an MCP server the cast reaches. */
+export interface SceneSystemSpec {
+    /** The server, `id` or `id:version`. */
+    server: string;
+    /** The name the audience reads on the graph and in the transcript. */
+    as: string;
+    /** What it holds in this scene. */
+    holds: string;
+}
+/** The stage: what is on it, and what the audience is told. */
+export interface SceneSettingSpec {
+    systems: SceneSystemSpec[];
+    /** The Frames the scene plays under, over the team's; absent when none. */
+    frames?: string[];
+    /** The data in play; absent when none. */
+    contents?: string[];
+    /** When the scene plays, in words. */
+    period: string;
+    /** The language it plays in, `en`. */
+    language: string;
+    /** What the audience is told before it starts: the line under the title. */
+    assumes: string;
+}
+/** What starts a beat: one of the three is said. */
+export interface SceneCueSpec {
+    /** An opener the audience may say: the entry's suggestion on the page. */
+    say: string;
+    schedule: string;
+    event: string;
+}
+/** What kind of answer comes back, and what the page shows. */
+export type SceneAnswerKind = 'words' | 'table' | 'chart' | 'notebook' | 'map' | 'file' | 'image';
+/** How fast a beat plays for the audience. */
+export type ScenePace = 'quick' | 'steady' | 'slow';
+/** One member asking another over a protocol, or answering the audience. */
+export interface SceneMoveSpec {
+    /** The member moving, by its id in the cast. */
+    who: string;
+    /** Whom: a member or a system; empty when it answers the audience. */
+    asks: string;
+    /** `a2a` to a member, `mcp` to a system. */
+    over?: 'a2a' | 'mcp';
+    /** What it asks for, or what it answers, in words. */
+    what: string;
+    /** Over `mcp`: the tool, by name or pattern. */
+    tool: string;
+    /** The kind of tool: `read`, `write`, … */
+    does?: string;
+    /** What kind of answer comes back. */
+    answers?: SceneAnswerKind;
+}
+/** What a beat does instead when a decision holds. */
+export interface SceneBranchSpec {
+    decision: string;
+    expect: string;
+    /** The moves then, when they differ; absent otherwise. */
+    moves?: SceneMoveSpec[];
+    /** The beat that follows, by id. */
+    then: string;
+}
+/** One beat of the script. */
+export interface SceneBeatSpec {
+    id: string;
+    cue: SceneCueSpec;
+    /** One line for the audience, read in the transcript. */
+    narration: string;
+    moves: SceneMoveSpec[];
+    /** What should happen, in words. */
+    expect: string;
+    /** What the page shows: said, or the kinds of the answers to the audience. */
+    shows: SceneAnswerKind[];
+    /** Its pace; the stage's when absent. */
+    pace?: ScenePace;
+    /** What it does instead, on a decision; absent when it never branches. */
+    branch?: SceneBranchSpec[];
+}
+/** Where a member stands: fractions of the box. */
+export interface ScenePositionSpec {
+    x: number;
+    y: number;
+}
+/** What the transcript shows. */
+export interface SceneTranscriptSpec {
+    tools: boolean;
+    narration: boolean;
+    /** Words withheld; absent when none. */
+    withhold?: ('credentials' | 'ids' | 'addresses' | 'amounts')[];
+}
+/** Directions for the page. */
+export interface SceneStageSpec {
+    positions: Record<string, ScenePositionSpec>;
+    /** Whose balloon opens first; the entry's when empty. */
+    opensFirst: string;
+    transcript: SceneTranscriptSpec;
+    inspectors: ('agent' | 'tools' | 'a2a' | 'notebook' | 'cost')[];
+    /** How long the scene plays before it rests, `10m`. */
+    restsAfter: string;
+    pace: ScenePace;
+}
+/** Who may watch and ask, and what an ask may cost. */
+export interface SceneAudienceSpec {
+    who: 'visitors' | 'signed-in' | 'nobody';
+    /** What one ask may cost, in USD; the site's when 0. */
+    ceilingPerAsk: number;
+    /** How many asks a visitor gets a day; the site's when 0. */
+    asksADay: number;
+}
+/** What a beat's transcript must look like. */
+export interface SceneRehearsalBeatSpec {
+    beat: string;
+    /** The shape, in order: `Sales → Accounting`, `Accounting → Odoo: odoo_accounting_*`, `Accounting: a table`. */
+    lines: string[];
+    mustSay?: string[];
+    mustNotSay?: string[];
+    within: string;
+}
+/** A transcript recorded once, played when the scene cannot play live (LOOP H-08). */
+export interface SceneRecordingSpec {
+    path: string;
+    taken: string;
+    note: string;
+}
+/** The scene's tests: a passing rehearsal is the gallery's *Live*. */
+export interface SceneRehearsalSpec {
+    beats: SceneRehearsalBeatSpec[];
+    within: string;
+    recording?: SceneRecordingSpec;
+    verified: AppVerifiedSpec;
+}
+/** Where the scene plays. */
+export interface SceneDeploymentSpec {
+    account: string;
+    /** The page it plays on. */
+    page: string;
+    /** For each member on a runtime, the variable its address is read from at build. */
+    addresses: Record<string, string>;
+}
+/** Specification for a scene: a team, staged. */
+export interface SceneSpec {
+    /** The version of the spec itself: `loop.scene/v1`. */
+    schema: string;
+    id: string;
+    version: string;
+    /** The tab's name. */
+    name: string;
+    description: string;
+    tags: string[];
+    icon: string;
+    /** Its face: one emoji, drawn before its name. */
+    emoji: string;
+    /** The team it stages, `id:version`; empty when the cast was written inline. */
+    team: string;
+    /** The member the audience talks to. */
+    entry: string;
+    /** The cast, resolved: every member of the team with its persona filled. */
+    cast: SceneCastMemberSpec[];
+    setting: SceneSettingSpec;
+    script: SceneBeatSpec[];
+    stage: SceneStageSpec;
+    audience: SceneAudienceSpec;
+    rehearsal: SceneRehearsalSpec;
+    deployment: SceneDeploymentSpec;
+    /** What it names that is not enabled today, in sentences. */
+    setup: string[];
+}

package/lib/types/scenes.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.85",
+    "version": "1.3.86",
     "type": "module",
     "workspaces": [
         ".",
@@ -69,7 +69,7 @@
         "clean:dist": "rimraf dist",
         "clean:lib": "rimraf lib tsconfig.tsbuildinfo",
         "create:patches": "bash scripts/create-patches.sh",
-        "examples": "run-p server:start server:start:codemode server:start:accounting server:accounting jupyter:start examples:vite",
+        "examples": "run-p server:start server:start:codemode server:start:accounting server:scenes jupyter:start examples:vite",
         "examples2": "run-p server:start server:start:codemode jupyter:start examples2:vite",
         "example-local": "make example-local",
         "examples:fresh": "npm run clean:cache && npm run examples",
@@ -99,7 +99,7 @@
         "server:start:agent-node": "AGENT_NODE_JUPYTER_URL=${AGENT_NODE_JUPYTER_URL:-http://127.0.0.1:8888/api/jupyter-server} AGENT_NODE_JUPYTER_TOKEN=${AGENT_NODE_JUPYTER_TOKEN:-60c1661cc408f978c309d04157af55c9588ff9557c9380e4fb50785750703da6} PYTHONIOENCODING=utf-8 AGENT_RUNTIMES_DEBUG=false AGENT_RUNTIMES_LOG_LEVEL=info DATALAYER_EVALS_MODE=interactive DATALAYER_EVALS_EMIT_LIVE_EVENTS=true AGENT_RUNTIMES_INFERENCE_PROVIDER_OVERRIDE=${AGENT_RUNTIMES_INFERENCE_PROVIDER_OVERRIDE:-datalayer} python -m agent_runtimes serve --node --port 8765 --log-level info",
         "server:start:codemode": "PYTHONIOENCODING=utf-8 AGENT_RUNTIMES_DEBUG=false AGENT_RUNTIMES_LOG_LEVEL=info DATALAYER_EVALS_MODE=interactive DATALAYER_EVALS_EMIT_LIVE_EVENTS=true python -m agent_runtimes serve --port 8766 --log-level info",
         "server:start:accounting": "PYTHONIOENCODING=utf-8 AGENT_RUNTIMES_DEBUG=false AGENT_RUNTIMES_LOG_LEVEL=info python -m agent_runtimes serve --port 8767 --log-level info",
-        "server:accounting": "python examples/sales-accounting-a2a/serve_accounting.py --url http://127.0.0.1:8767 --wait 300 || echo 'Accounting was not served on 8767: the Agent A2A Team example will say it is not reachable.'",
+        "server:scenes": "python examples/sales-accounting-a2a/serve_scenes.py --url http://127.0.0.1:8767 --wait 300 || echo 'The scenes were not served: the Agent A2A Team and Scenes examples will say which member is not reachable.'",
         "examples:codemode": "run-p server:start server:start:codemode examples:vite",
         "start": "vite",
         "start:acp": "run-p server:start start:acp:vite",

package/scripts/codegen/generate_agents.py

@@ -1647,6 +1647,7 @@ export * from './gates';
 export * from './tracks';
 export * from './ops';
 export * from './apps';
+export * from './scenes';
 export * from './actions';
 export * from './appspecSchema';
 """

package/scripts/codegen/generate_scenes.py

@@ -0,0 +1,301 @@
+#!/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 scene specifications.
+
+A scene (agentspecs >= 0.0.61, LOOP A-11) stages a team: the team says who
+is on stage, the scene says what happens there — the setting, the script,
+the stage directions, the audience, the rehearsal and where it plays. One
+YAML per scene under ``agentspecs/scenes``.
+
+Each scene is validated here, by ``agentspecs`` itself (``scene_problems``),
+and arrives with its cast resolved — every member of the team, its persona
+filled from its application (``cast_of``) — its ``entry`` said, what each
+beat ``shows`` said, and what it names that is not enabled (``setup``).
+Empty optional lists are dropped, as ``generate_apps.py`` drops them.
+
+Usage:
+    python generate_scenes.py \\
+      --specs-dir agentspecs/agentspecs/scenes \\
+      --python-output agent_runtimes/specs/scenes.py \\
+      --typescript-output src/specs/scenes.ts
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from agentspecs_clone import import_from_clone
+from versioning import ensure_spec_version, version_suffix
+
+#: The keys of a scene spec, as TypeScript spells them.
+CAMEL = {
+    "runs_in": "runsIn",
+    "talks_to": "talksTo",
+    "opens_first": "opensFirst",
+    "rests_after": "restsAfter",
+    "ceiling_per_ask": "ceilingPerAsk",
+    "asks_a_day": "asksADay",
+    "must_say": "mustSay",
+    "must_not_say": "mustNotSay",
+}
+
+#: The lists written only when they hold something: TypeScript reads them as optional.
+OPTIONAL_LISTS = (
+    "talks_to",
+    "frames",
+    "contents",
+    "branch",
+    "withhold",
+    "must_say",
+    "must_not_say",
+)
+
+
+def _flat(text: Any) -> str:
+    """A text on one line."""
+    return " ".join(str(text or "").split())
+
+
+def _trim(value: Any, key: str = "") -> Any:
+    """A value without the empty optional lists and the keys that hold nothing."""
+    if isinstance(value, dict):
+        trimmed = {}
+        for name, item in value.items():
+            if item is None or (name in OPTIONAL_LISTS and item == []):
+                continue
+            trimmed[name] = _trim(item, name)
+        return trimmed
+    if isinstance(value, list):
+        return [_trim(item) for item in value]
+    return value
+
+
+def load_specs(specs_dir: Path) -> list[dict[str, Any]]:
+    """Every scene, validated, as plain data: its cast resolved, its entry said."""
+    scenes_module = import_from_clone(specs_dir, "scenes")
+    scenes = scenes_module.load_scenes(specs_dir)
+    specs: list[dict[str, Any]] = []
+    for identity in sorted(scenes):
+        scene = scenes[identity]
+        spec = scene.model_dump(mode="json", by_alias=True)
+        spec["entry"] = scene.entry_of()
+        spec["cast"] = [
+            member.model_dump(mode="json", by_alias=True) for member in scene.cast_of()
+        ]
+        for beat, data in zip(scene.script, spec["script"]):
+            data["shows"] = [kind.value for kind in beat.shown]
+        spec["setup"] = scenes_module.scene_setup(scene)
+        for key in ("description",):
+            spec[key] = _flat(spec.get(key))
+        spec["setting"]["assumes"] = _flat(spec["setting"].get("assumes"))
+        for member in spec["cast"]:
+            member["brief"] = _flat(member.get("brief"))
+        for beat in spec["script"]:
+            beat["expect"] = _flat(beat.get("expect"))
+            for branch in beat.get("branch") or []:
+                branch["expect"] = _flat(branch.get("expect"))
+        ensure_spec_version(spec)
+        specs.append(_trim(spec))
+    return specs
+
+
+def _const_name(spec: dict[str, Any]) -> str:
+    """`sales-and-accounting` 0.0.1 → `SALES_AND_ACCOUNTING_SCENE_0_0_1`."""
+    base = spec["id"].upper().replace("-", "_").replace(".", "_")
+    return f"{base}_SCENE" + version_suffix(spec["version"])
+
+
+def _typescript_value(value: Any) -> Any:
+    """A scene as the TypeScript interfaces read it."""
+    if isinstance(value, dict):
+        return {
+            CAMEL.get(key, key): _typescript_value(item) for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [_typescript_value(item) for item in value]
+    return value
+
+
+HEADER = [
+    "This file is AUTO-GENERATED from YAML specifications.",
+    "DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",
+]
+
+ABOUT = [
+    "Scene Catalog.",
+    "",
+    "A team, staged: the setting, the script, the stage directions, the",
+    "audience, the rehearsal and where it plays. The cast is resolved.",
+]
+
+
+def generate_python_code(specs: list[dict[str, Any]]) -> str:
+    """Generate the Python scene catalogue."""
+    lines = [
+        "# Copyright (c) 2025-2026 Datalayer, Inc.",
+        "# Distributed under the terms of the Modified BSD License.",
+        '"""',
+        *ABOUT,
+        "",
+        *HEADER,
+        '"""',
+        "",
+        "from typing import Dict",
+        "",
+        "from agent_runtimes.types import SceneSpec",
+        "",
+        "# " + "=" * 76,
+        "# Scene Definitions",
+        "# " + "=" * 76,
+        "",
+    ]
+    for spec in specs:
+        lines.extend(
+            [
+                f"{_const_name(spec)} = SceneSpec.model_validate(",
+                f"    {spec!r}",
+                ")",
+                "",
+            ]
+        )
+    lines.extend(
+        [
+            "",
+            "# " + "=" * 76,
+            "# Scene Catalog",
+            "# " + "=" * 76,
+            "",
+            "SCENE_CATALOGUE: Dict[str, SceneSpec] = {",
+        ]
+    )
+    for spec in specs:
+        lines.append(f"    {spec['id']!r}: {_const_name(spec)},")
+    lines.extend(
+        [
+            "}",
+            "",
+            "",
+            "def get_scene_spec(scene_id: str) -> SceneSpec | None:",
+            '    """A scene, by `id` or `id:version`, or None."""',
+            "    found = SCENE_CATALOGUE.get(scene_id)",
+            "    if found is not None:",
+            "        return found",
+            '    base, _, version = scene_id.rpartition(":")',
+            '    return SCENE_CATALOGUE.get(base) if base and "." in version else None',
+            "",
+            "",
+            "def list_scene_specs(tag: str | None = None) -> list[SceneSpec]:",
+            '    """Every scene of the catalogue, or those carrying a tag."""',
+            "    return [",
+            "        scene for scene in SCENE_CATALOGUE.values() if tag is None or tag in scene.tags",
+            "    ]",
+            "",
+            "",
+            "def scenes_staging(team_id: str) -> list[SceneSpec]:",
+            '    """Every scene that stages a team, by its id with or without a version."""',
+            '    wanted = team_id.split(":")[0]',
+            "    return [",
+            "        scene",
+            "        for scene in SCENE_CATALOGUE.values()",
+            '        if scene.team and scene.team.split(":")[0] == wanted',
+            "    ]",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
+    """Generate the TypeScript scene catalogue."""
+    lines = [
+        "/*",
+        " * Copyright (c) 2025-2026 Datalayer, Inc.",
+        " * Distributed under the terms of the Modified BSD License.",
+        " */",
+        "",
+        "/**",
+        *[f" * {line}".rstrip() for line in ABOUT],
+        " *",
+        *[f" * {line}" for line in HEADER],
+        " */",
+        "",
+        "import type { SceneSpec } from '../types/scenes';",
+        "",
+    ]
+    for spec in specs:
+        body = json.dumps(_typescript_value(spec), indent=2, ensure_ascii=False)
+        lines.extend([f"export const {_const_name(spec)}: SceneSpec = {body};", ""])
+    lines.append("export const SCENE_CATALOGUE: Record<string, SceneSpec> = {")
+    for spec in specs:
+        lines.append(f"  {json.dumps(spec['id'])}: {_const_name(spec)},")
+    lines.extend(
+        [
+            "};",
+            "",
+            "/** A scene, by `id` or `id:version`, or undefined. */",
+            "export function getSceneSpec(ref: string): SceneSpec | undefined {",
+            "  // Own entries only: `constructor` and `toString` are not scenes.",
+            "  const own = (id: string): SceneSpec | undefined =>",
+            "    Object.prototype.hasOwnProperty.call(SCENE_CATALOGUE, id)",
+            "      ? SCENE_CATALOGUE[id]",
+            "      : undefined;",
+            "  const at = ref.lastIndexOf(':');",
+            "  return (",
+            "    own(ref) ??",
+            "    (at > 0 && ref.slice(at + 1).includes('.')",
+            "      ? own(ref.slice(0, at))",
+            "      : undefined)",
+            "  );",
+            "}",
+            "",
+            "/** Every scene of the catalogue, in the catalogue's order, or those carrying a tag. */",
+            "export function listSceneSpecs(tag?: string): SceneSpec[] {",
+            "  return Object.values(SCENE_CATALOGUE).filter(",
+            "    scene => tag === undefined || scene.tags.includes(tag),",
+            "  );",
+            "}",
+            "",
+            "/** Every scene that stages a team, by its id with or without a version. */",
+            "export function scenesStaging(teamId: string): SceneSpec[] {",
+            "  const wanted = teamId.split(':')[0];",
+            "  return Object.values(SCENE_CATALOGUE).filter(",
+            "    scene => scene.team !== '' && scene.team.split(':')[0] === wanted,",
+            "  );",
+            "}",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def main() -> None:
+    """Generate the scene catalogue."""
+    parser = argparse.ArgumentParser(
+        description="Generate Python and TypeScript code from YAML scene specifications"
+    )
+    parser.add_argument("--specs-dir", type=Path, required=True)
+    parser.add_argument("--python-output", type=Path, required=True)
+    parser.add_argument("--typescript-output", type=Path, required=True)
+    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_specs(args.specs_dir)
+    for path, text in (
+        (args.python_output, generate_python_code(specs)),
+        (args.typescript_output, generate_typescript_code(specs)),
+    ):
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text)
+        print(f"Generated: {path}")
+    print(f"\n✓ Successfully generated code from {len(specs)} scene specs")
+
+
+if __name__ == "__main__":
+    main()