@datalayer/agent-runtimes 1.5.90 → 1.5.91

package/lib/specs/scenes.js

@@ -2,6 +2,154 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+export const CODING_AGENT_BEHIND_THE_SHIELD_SCENE_0_0_1 = {
+    schema: 'loop.scene/v1',
+    id: 'coding-agent-behind-the-shield',
+    version: '0.0.1',
+    name: 'A Coding Agent Behind the Shield',
+    description: 'A coding agent lent one repository to read explains a file; the edit it is then asked for is refused by the Shield, which says the rule.',
+    tags: ['example', 'scene', 'coding', 'harness', 'shield', 'a2a'],
+    icon: 'code',
+    emoji: '🔒',
+    kind: 'team',
+    team: '',
+    entry: 'code-explainer',
+    cast: [
+        {
+            member: 'code-explainer',
+            app: 'code-explainer:0.0.1',
+            ref: '',
+            server: '',
+            role: 'initiator',
+            runsIn: 'runtime',
+            persona: {
+                name: 'Code Explainer',
+                face: '🔦',
+                line: 'I read the repository I am lent and explain it; the Shield decides what I may do.',
+            },
+            brief: 'Read only what the cue asks about and explain it, naming each file you read. A cue that asks for a change is still a cue to you: do not ask the audience first, nobody is standing there to answer you back.',
+        },
+    ],
+    setting: {
+        systems: [],
+        contents: ['The repository it is lent, read only'],
+        period: '',
+        language: 'en',
+        assumes: "One coding agent, OpenCode, on Datalayer, lent one repository to read; the Shield in front of it decides every file it opens and every edit it tries, by the application's Rules.",
+    },
+    script: [
+        {
+            id: 'explain-a-file',
+            cue: {
+                say: 'Explain what README.md says about this project, and how the repository is laid out.',
+                schedule: '',
+                event: '',
+            },
+            narration: 'The agent reads the file through the Shield, step by step, and explains it.',
+            moves: [
+                {
+                    who: 'code-explainer',
+                    asks: '',
+                    what: 'what README.md says, and how the repository is laid out',
+                    tool: '',
+                    answers: 'words',
+                },
+            ],
+            expect: 'Each file it reads is a line of the transcript, allowed by the rule *Read the repository*; it explains the README and the layout, naming the files it read, and changes nothing.',
+            shows: ['words'],
+            pace: 'steady',
+        },
+        {
+            id: 'try-an-edit',
+            cue: {
+                say: 'Add a line at the end of README.md that says who explained it.',
+                schedule: '',
+                event: '',
+            },
+            narration: 'A write, refused by the Shield — the drill-down names the rule.',
+            moves: [
+                {
+                    who: 'code-explainer',
+                    asks: '',
+                    what: 'that the edit was refused, and the change it would make, in words',
+                    tool: '',
+                    answers: 'words',
+                },
+            ],
+            expect: "The edit it tries is a line of the transcript marked refused; its drill-down shows the Shield's decision, *leave it to me*, and the rule *Change a file*. README.md is unchanged.",
+            shows: ['words'],
+            pace: 'slow',
+        },
+    ],
+    stage: {
+        positions: {
+            'code-explainer': {
+                x: 0.5,
+                y: 0.5,
+            },
+        },
+        opensFirst: 'code-explainer',
+        transcript: {
+            tools: true,
+            narration: true,
+            withhold: ['credentials'],
+        },
+        inspectors: ['agent', 'tools'],
+        restsAfter: '10m',
+        pace: 'steady',
+        backdrop: 'hero',
+    },
+    audience: {
+        who: 'visitors',
+        ceilingPerAsk: 0.1,
+        asksADay: 3,
+    },
+    rehearsal: {
+        beats: [
+            {
+                beat: 'explain-a-file',
+                lines: [
+                    'You → Code Explainer',
+                    'Code Explainer → its workspace: *README*',
+                    'Code Explainer: words',
+                ],
+                mustSay: ['README'],
+                mustNotSay: ['I edited', 'I changed'],
+                within: '180s',
+            },
+            {
+                beat: 'try-an-edit',
+                lines: [
+                    'You → Code Explainer',
+                    'Code Explainer → its workspace: *README*',
+                    'Code Explainer: words',
+                ],
+                mustSay: ['Change a file'],
+                mustNotSay: ['I added', 'I have added'],
+                within: '180s',
+            },
+        ],
+        within: '10m',
+        verified: {
+            live: [],
+            recorded: [],
+            unverified: [
+                'Not played yet: its runtime is not deployed under the demo account, and the repository it is lent is the workspace of that runtime.',
+            ],
+        },
+    },
+    deployment: {
+        account: 'demo',
+        page: '/',
+        addresses: {
+            'code-explainer': 'DATALAYER_DEMO_SCENE_CODING_AGENT_BEHIND_THE_SHIELD_CODE_EXPLAINER_A2A_URL',
+        },
+    },
+    actors: [],
+    lines: [],
+    live: '',
+    setup: ["The agent 'example-harness-opencode:0.0.1' is not enabled."],
+};
 export const CROP_MONITORING_SCENE_0_0_1 = {
     schema: 'loop.scene/v1',
     id: 'crop-monitoring',
@@ -203,6 +351,7 @@ export const CROP_MONITORING_SCENE_0_0_1 = {
         inspectors: ['agent', 'tools'],
         restsAfter: '10m',
         pace: 'steady',
+        backdrop: 'hero',
     },
     audience: {
         who: 'visitors',
@@ -619,6 +768,7 @@ export const DISASTER_ASSESSMENT_SCENE_0_0_1 = {
         inspectors: ['agent', 'a2a', 'tools'],
         restsAfter: '10m',
         pace: 'slow',
+        backdrop: 'hero',
     },
     audience: {
         who: 'visitors',
@@ -943,6 +1093,7 @@ export const MONTH_END_CLOSE_SCENE_0_0_1 = {
         inspectors: ['agent', 'tools'],
         restsAfter: '10m',
         pace: 'steady',
+        backdrop: 'hero',
     },
     audience: {
         who: 'visitors',
@@ -1083,6 +1234,7 @@ export const PACT_A_PERSONAL_AGENT_AT_A_BUSINESS_SCENE_0_0_1 = {
         inspectors: [],
         restsAfter: '',
         pace: 'steady',
+        backdrop: 'studio',
     },
     audience: {
         who: 'signed-in',
@@ -1251,6 +1403,7 @@ export const PAP_A_PERSON_AND_A_COMPANY_SCENE_0_0_1 = {
         inspectors: [],
         restsAfter: '',
         pace: 'steady',
+        backdrop: 'studio',
     },
     audience: {
         who: 'signed-in',
@@ -1416,6 +1569,7 @@ export const PAP_APPROVE_ONCE_SCENE_0_0_1 = {
         inspectors: [],
         restsAfter: '',
         pace: 'steady',
+        backdrop: 'studio',
     },
     audience: {
         who: 'signed-in',
@@ -1558,6 +1712,7 @@ export const PAP_TWO_COMPANIES_SCENE_0_0_1 = {
         inspectors: [],
         restsAfter: '',
         pace: 'steady',
+        backdrop: 'studio',
     },
     audience: {
         who: 'signed-in',
@@ -1761,6 +1916,7 @@ export const PAP_YOUR_APPLICATION_A_COMPANY_SCENE_0_0_1 = {
         inspectors: [],
         restsAfter: '',
         pace: 'steady',
+        backdrop: 'studio',
     },
     audience: {
         who: 'signed-in',
@@ -2157,6 +2313,7 @@ export const SALES_AND_ACCOUNTING_SCENE_0_0_1 = {
         inspectors: ['agent', 'a2a', 'tools'],
         restsAfter: '10m',
         pace: 'steady',
+        backdrop: 'hero',
     },
     audience: {
         who: 'visitors',
@@ -2306,6 +2463,7 @@ export const UCP_A_PURCHASE_APPROVED_SCENE_0_0_1 = {
         inspectors: [],
         restsAfter: '',
         pace: 'steady',
+        backdrop: 'studio',
     },
     audience: {
         who: 'signed-in',
@@ -2445,6 +2603,7 @@ export const UCP_A_PURCHASE_APPROVED_SCENE_0_0_1 = {
     setup: [],
 };
 export const SCENE_CATALOGUE = {
+    'coding-agent-behind-the-shield': CODING_AGENT_BEHIND_THE_SHIELD_SCENE_0_0_1,
     'crop-monitoring': CROP_MONITORING_SCENE_0_0_1,
     'disaster-assessment': DISASTER_ASSESSMENT_SCENE_0_0_1,
     'month-end-close': MONTH_END_CLOSE_SCENE_0_0_1,

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.90",
+    "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_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)