@datalayer/agent-runtimes 1.5.89 → 1.5.91

package/lib/types/scenes.d.ts

@@ -144,7 +144,17 @@ export interface SceneStageSpec {
     /** How long the scene plays before it rests, `10m`. */
     restsAfter: string;
     pace: ScenePace;
+    /**
+     * How the stage is drawn, here and wherever the scene plays: `studio`,
+     * characters with speech balloons and each message flowing along its
+     * line; `hero`, round faces on a deep tint, thin lines and a dot that
+     * flies with each message; `plain`, boxes and arrows that do not move.
+     * `studio` when unsaid, so every scene written before draws as before.
+     */
+    backdrop?: SceneBackdropId;
 }
+/** A backdrop, by its id (agentspecs `Backdrop`). */
+export type SceneBackdropId = 'studio' | 'hero' | 'plain';
 /** Who may watch and ask, and what an ask may cost. */
 export interface SceneAudienceSpec {
     who: 'visitors' | 'signed-in' | 'nobody';
@@ -168,6 +178,50 @@ export interface SceneRecordingSpec {
     taken: string;
     note: string;
 }
+/** A line of a recording: the transcript's line as a stage exports it (`SceneTranscriptLine`). */
+export interface SceneRecordedLine {
+    key: string;
+    /** When, in milliseconds since the epoch. */
+    at: number;
+    from: string;
+    to?: string;
+    kind: 'said' | 'asked' | 'called';
+    text: string;
+    open?: boolean;
+    failed?: boolean;
+    ended?: number;
+}
+/** A beat of a recording: which of its lines it played (`first`, `count`). */
+export interface SceneRecordedBeat {
+    beat: string;
+    cue: string;
+    state: string;
+    seconds: number;
+    first: number;
+    count: number;
+}
+/**
+ * A scene's recording, as `<id>/recording.json` holds it: the transcript of
+ * a passing rehearsal (version 1, the JSON a stage exports), when it was
+ * taken, the rehearsal it came from and the beats its lines belong to.
+ */
+export interface SceneRecordingFile {
+    version: 1;
+    scene: string;
+    /** When it was taken: the label says *Recording, taken <date>*. */
+    taken: string;
+    /** What the audience is told of it. */
+    note?: string;
+    exported?: string;
+    rehearsal?: {
+        at: string;
+        where: string;
+        passed: boolean;
+        says: string;
+    };
+    beats?: SceneRecordedBeat[];
+    lines: SceneRecordedLine[];
+}
 /** The scene's tests: a passing rehearsal is the gallery's *Live*. */
 export interface SceneRehearsalSpec {
     beats: SceneRehearsalBeatSpec[];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.5.89",
+    "version": "1.5.91",
     "type": "module",
     "workspaces": [
         ".",
@@ -254,6 +254,7 @@
         "localforage": "^1.10.0",
         "lucide-react": "^0.542.0",
         "marked": "^4.0.10",
+        "mermaid": "^10.9.8",
         "mock-socket": "^9.3.1",
         "motion": "^12.23.26",
         "nanoid": "^5.1.6",

package/scripts/codegen/generate_mcp_servers.py

@@ -356,18 +356,6 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
 
 def update_init_file(specs: list[dict[str, Any]], init_file: Path) -> None:
     """Update the __init__.py file with correct imports based on generated specs."""
-    # Generate list of MCP server constant names
-    server_constants = []
-    for spec in specs:
-        server_id = spec["id"]
-        version = spec.get("version", "0.0.1")
-        const_name = (
-            server_id.upper().replace("-", "_")
-            + "_MCP_SERVER"
-            + version_suffix(version)
-        )
-        server_constants.append(const_name)
-
     # Read the current __init__.py
     init_content = init_file.read_text()
 
@@ -386,9 +374,12 @@ def update_init_file(specs: list[dict[str, Any]], init_file: Path) -> None:
         return
 
     # Generate new import lines - all names sorted alphabetically (ruff/isort order)
+    # Only the catalogue and its readers are re-exported: entries are read by
+    # id, never by a version-named constant (decided 14 October 2026), so the
+    # *_MCP_SERVER_<version> constants stay in catalog_mcp_servers alone and a
+    # version bump touches no caller (test_catalogue_by_id.py holds it).
     all_names = sorted(
-        server_constants
-        + [
+        [
             "MCP_SERVER_CATALOG",
             "check_env_vars_available",
             "get_catalog_server",
@@ -423,8 +414,6 @@ def update_init_file(specs: list[dict[str, Any]], init_file: Path) -> None:
             '    "get_catalog_server",',
             '    "list_catalog_servers",',
         ]
-        for const in sorted(server_constants):
-            all_entries.append(f'    "{const}",')
         all_entries.append("]")
 
         # Replace the section

package/scripts/codegen/generate_scenes.py

@@ -21,6 +21,12 @@ The scene spec's JSON Schema is written beside the TypeScript catalogue as
 ``generate_apps.py`` writes ``appspecSchema.ts``: what an editor of the text
 completes and explains is what the spec accepts (S-01, A-03).
 
+A scene's recording — the transcript of a passing rehearsal, kept beside
+the specs as ``<id>/recording.json`` and named by ``rehearsal.recording`` —
+is written to ``sceneRecordings.ts`` beside the catalogue, apart from it, so
+that a page that never plays one never loads one: ``SCENE_RECORDINGS``, read
+by ``useSceneRecording`` at the recorded pace.
+
 Usage:
     python generate_scenes.py \\
       --specs-dir agentspecs/agentspecs/scenes \\
@@ -290,6 +296,76 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
     return "\n".join(lines)
 
 
+def load_recordings(specs_dir: Path) -> dict[str, dict[str, Any]]:
+    """Every scene's recording its spec names, by the scene's id, as its file holds it.
+
+    A file the spec names that is not there, or is not a transcript of
+    version 1, stops the generation in a sentence (agentspecs'
+    ``scene_recording``, when the clone has it).
+    """
+    scenes_module = import_from_clone(specs_dir, "scenes")
+    read = getattr(scenes_module, "scene_recording", None)
+    recordings: dict[str, dict[str, Any]] = {}
+    for identity, scene in sorted(scenes_module.load_scenes(specs_dir).items()):
+        named = scene.rehearsal.recording
+        if named is None:
+            continue
+        path = specs_dir / named.path
+        if read is not None and path == specs_dir / identity / "recording.json":
+            found = read(identity, specs_dir)
+        else:
+            found = json.loads(path.read_text()) if path.is_file() else None
+        if not found:
+            raise SystemExit(
+                f"The recording of {identity} ({named.path}) is not there."
+            )
+        recordings[identity] = {
+            **found,
+            "scene": identity,
+            "taken": named.taken or found.get("taken") or "",
+            **({"note": named.note} if named.note else {}),
+        }
+    return recordings
+
+
+def generate_recordings_typescript_code(recordings: dict[str, dict[str, Any]]) -> str:
+    """The scenes' recordings, apart from the catalogue: a page that plays none loads none."""
+    body = json.dumps(recordings, indent=2, ensure_ascii=False)
+    return "\n".join(
+        [
+            "/*",
+            " * Copyright (c) 2025-2026 Datalayer, Inc.",
+            " * Distributed under the terms of the Modified BSD License.",
+            " */",
+            "",
+            "/**",
+            " * The scenes' recordings: each the transcript of a passing rehearsal, kept",
+            " * beside its spec as `<id>/recording.json` (`loop scenes record`) and played",
+            " * at its recorded pace when the scene cannot play live (`useSceneRecording`).",
+            " *",
+            *[f" * {line}" for line in HEADER],
+            " *",
+            " * @module specs/sceneRecordings",
+            " */",
+            "",
+            "import type { SceneRecordingFile } from '../types/scenes';",
+            "",
+            f"export const SCENE_RECORDINGS: Record<string, SceneRecordingFile> = {body};",
+            "",
+            "/** A scene's recording, by its id or `id:version`; undefined when it has none. */",
+            "export function getSceneRecording(",
+            "  ref: string,",
+            "): SceneRecordingFile | undefined {",
+            "  const id = ref.split(':')[0];",
+            "  return Object.prototype.hasOwnProperty.call(SCENE_RECORDINGS, id)",
+            "    ? SCENE_RECORDINGS[id]",
+            "    : undefined;",
+            "}",
+            "",
+        ]
+    )
+
+
 def generate_schema_typescript_code(specs_dir: Path) -> str:
     """The scene spec's JSON Schema, for the editor of its text (S-01, A-03).
 
@@ -344,6 +420,10 @@ def main() -> None:
             args.typescript_output.with_name("sceneSchema.ts"),
             generate_schema_typescript_code(args.specs_dir),
         ),
+        (
+            args.typescript_output.with_name("sceneRecordings.ts"),
+            generate_recordings_typescript_code(load_recordings(args.specs_dir)),
+        ),
     ):
         path.parent.mkdir(parents=True, exist_ok=True)
         path.write_text(text)