@datalayer/agent-runtimes 1.3.86 → 1.3.87

package/lib/components/teams/A2ATeamGraph.d.ts

@@ -20,7 +20,7 @@
  * values the rows, top to bottom.
  *
  * A member's connections — the MCP servers it reaches, Odoo for Accounting —
- * hang under it, each a node half a member's size with the server's mark
+ * stand to its right, each a node half a member's size with the server's mark
  * (`SpecMark`), linked to it by an edge of its own. That edge is still until
  * the member calls one of the connection's tools: then it flows toward the
  * connection for as long as the call runs ({@link A2ATeamCall}), with the
@@ -59,7 +59,7 @@ export type A2ATeamGraphMember = {
     onToggle?: () => void;
     /** It was sent away, or called back. */
     onAway?: (away: boolean) => void;
-    /** The MCP servers it reaches, drawn under it (`teamConnectionsOf`). */
+    /** The MCP servers it reaches, drawn to its right (`teamConnectionsOf`). */
     connections?: A2ATeamConnection[];
     /**
      * How its balloon shows what it says (LOOP T-23): only what it says or

package/lib/components/teams/A2ATeamGraph.js

@@ -25,9 +25,15 @@ const WIDTH = NODE_WIDTH * 2 + GAP;
 const ROW_GAP = 48;
 /** A connection's node: half a member's. */
 const CONNECTION_WIDTH = NODE_WIDTH / 2;
-/** Between a member and its connections. */
+/** Between a member and its connections, to its right. */
 const CONNECTION_GAP = 44;
 const CONNECTIONS_APART = 16;
+/** Where a member's connections start: right of it. */
+const CONNECTION_X = NODE_WIDTH + CONNECTION_GAP;
+/** Below the character's middle, so the A2A edge leaving it passes above. */
+const CONNECTION_DROP = 12;
+/** What a member's connections take beside it. */
+const CONNECTIONS_BESIDE = CONNECTION_GAP + CONNECTION_WIDTH;
 /** Where the edge leaves and reaches a member: the middle of its character. */
 const HANDLE = (size) => ({
     opacity: 0,
@@ -118,7 +124,7 @@ const Moving = createContext({
     move: () => undefined,
     reset: () => undefined,
 });
-/** A connection's node id: under its member. */
+/** A connection's node id: beside its member. */
 const connectionNodeId = (member, connection) => `${member}/${connection}`;
 const MemberNode = memo(function MemberNode({ data, }) {
     const { id, side, size } = data;
@@ -282,7 +288,7 @@ const MemberNode = memo(function MemberNode({ data, }) {
                     stayPut: true, 
                     // Named as the member, not its character: `Sales (in your
                     // browser)`; the character describes it.
-                    agentName: member.name, label: memberLabel(member) })) }), _jsxs(Text, { sx: { fontWeight: 600, textAlign: 'center' }, children: [member.emoji ? `${member.emoji} ` : '', member.name] }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', textAlign: 'center' }, "data-member-where": "", children: member.where }), _jsx(Handle, { id: MEMBER_HANDLES.outRight, type: "source", position: Position.Right, style: HANDLE(size), isConnectable: false }), _jsx(Handle, { id: MEMBER_HANDLES.outLeft, type: "source", position: Position.Left, style: HANDLE(size), isConnectable: false }), _jsx(Handle, { id: MEMBER_HANDLES.outBottom, type: "source", position: Position.Bottom, style: { ...HANDLE(size), top: size }, isConnectable: false }), _jsx(Handle, { id: MEMBER_HANDLES.outTop, type: "source", position: Position.Top, style: { ...HANDLE(size), top: 0 }, isConnectable: false }), member.connections?.length ? (_jsx(Handle, { id: MEMBER_HANDLES.connections, type: "source", position: Position.Bottom, style: { ...HANDLE(size), top: 'auto', bottom: 0 }, isConnectable: false })) : null] }));
+                    agentName: member.name, label: memberLabel(member) })) }), _jsxs(Text, { sx: { fontWeight: 600, textAlign: 'center' }, children: [member.emoji ? `${member.emoji} ` : '', member.name] }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', textAlign: 'center' }, "data-member-where": "", children: member.where }), _jsx(Handle, { id: MEMBER_HANDLES.outRight, type: "source", position: Position.Right, style: HANDLE(size), isConnectable: false }), _jsx(Handle, { id: MEMBER_HANDLES.outLeft, type: "source", position: Position.Left, style: HANDLE(size), isConnectable: false }), _jsx(Handle, { id: MEMBER_HANDLES.outBottom, type: "source", position: Position.Bottom, style: { ...HANDLE(size), top: size }, isConnectable: false }), _jsx(Handle, { id: MEMBER_HANDLES.outTop, type: "source", position: Position.Top, style: { ...HANDLE(size), top: 0 }, isConnectable: false }), member.connections?.length ? (_jsx(Handle, { id: MEMBER_HANDLES.connections, type: "source", position: Position.Right, style: { ...HANDLE(size), left: 'auto', right: 0 }, isConnectable: false })) : null] }));
 });
 /** A member's accessible name: its name, and where it runs. */
 export function memberLabel(member) {
@@ -314,7 +320,7 @@ const ConnectionNode = memo(function ConnectionNode({ id, data, }) {
             gap: '2px',
             cursor: 'default',
             pointerEvents: 'all',
-        }, title: connection.name, "data-team-connection": connection.id, "data-connection-busy": tool ? 'true' : 'false', children: [_jsx(Handle, { type: "target", position: Position.Top, style: { ...HANDLE(0), top: 0 }, isConnectable: false }), _jsx(Box, { as: "button", type: "button", className: tool ? 'a2a-team-connection-busy' : undefined, "aria-label": connectionLabel(connection, owner?.name), "aria-expanded": told, "aria-controls": detailsId, "data-connection-figure": "", onClick: () => setTold(shown => !shown), onKeyDown: (event) => {
+        }, title: connection.name, "data-team-connection": connection.id, "data-connection-busy": tool ? 'true' : 'false', children: [_jsx(Handle, { type: "target", position: Position.Left, style: { ...HANDLE(size), left: 0 }, isConnectable: false }), _jsx(Box, { as: "button", type: "button", className: tool ? 'a2a-team-connection-busy' : undefined, "aria-label": connectionLabel(connection, owner?.name), "aria-expanded": told, "aria-controls": detailsId, "data-connection-figure": "", onClick: () => setTold(shown => !shown), onKeyDown: (event) => {
                     if (event.key === 'Escape' && told) {
                         event.stopPropagation();
                         setTold(false);
@@ -419,11 +425,19 @@ export const CallEdge = memo(function CallEdge({ id, sourceX, sourceY, targetX,
 });
 const NODE_TYPES = { member: MemberNode, connection: ConnectionNode };
 const EDGE_TYPES = { a2a: LinkEdge, mcp: CallEdge };
-/** Where a member's connections sit: under it, side by side, centred. */
-function connectionsX(memberX, count) {
-    const row = count * CONNECTION_WIDTH + (count - 1) * CONNECTIONS_APART;
-    const left = memberX + (NODE_WIDTH - row) / 2;
-    return Array.from({ length: count }, (_, at) => left + at * (CONNECTION_WIDTH + CONNECTIONS_APART));
+/** Where a member's connections sit: right of it, one under another from its character's middle. */
+function connectionsY(memberY, size, count, connectionHeight) {
+    const top = memberY + size / 2 + CONNECTION_DROP;
+    return Array.from({ length: count }, (_, at) => top + at * (connectionHeight + CONNECTIONS_APART));
+}
+/** How far down a member's connections reach, from its top; none, 0. */
+function connectionsReach(size, count, connectionHeight) {
+    return count
+        ? size / 2 +
+            CONNECTION_DROP +
+            count * connectionHeight +
+            (count - 1) * CONNECTIONS_APART
+        : 0;
 }
 /** What a member's call says, on its edge and to a screen reader. */
 export function callWords(member, connection, tool) {
@@ -502,7 +516,11 @@ export function A2ATeamGraph({ entry, peer, peers: more = NO_PEERS, flow, flows,
     // Where the members stand, as columns and rows, and the width that takes.
     const peerIds = peers.map(one => one.id);
     const placing = placeMembers(entry.id, peerIds, positions);
-    const drawn = Math.max(WIDTH, placing.columns * NODE_WIDTH + (placing.columns - 1) * GAP);
+    const hasConnections = members.some(member => member.connections?.length);
+    // The last column's connections sit beside it, inside the graph.
+    const drawn = Math.max(WIDTH, placing.columns * NODE_WIDTH +
+        (placing.columns - 1) * GAP +
+        (hasConnections ? CONNECTIONS_BESIDE : 0));
     const viewport = useMemo(() => teamViewport(width || drawn, drawn), [width, drawn]);
     // The members' height: the character, its name and where it runs.
     const memberHeight = size + 56;
@@ -516,14 +534,13 @@ export function A2ATeamGraph({ entry, peer, peers: more = NO_PEERS, flow, flows,
         connections: (member.connections ?? []).map(connection => connection.id),
     }));
     const placedKey = JSON.stringify(placed);
-    const hasConnections = placed.some(({ connections }) => connections.length);
     // A notebook in a balloon: more room above the members.
     const room = members.some(member => member.persona.notebook)
         ? Math.max(NOTEBOOK_BALLOON_ROOM, balloonRoom)
         : balloonRoom;
-    // Under a member: its connections, when any member has some.
-    const below = hasConnections ? CONNECTION_GAP + connectionHeight : 0;
-    const rowHeight = memberHeight + below;
+    // Beside a member, its connections may reach below it: the row takes them.
+    const reach = Math.max(0, ...placed.map(({ connections }) => connectionsReach(size, connections.length, connectionHeight)));
+    const rowHeight = Math.max(memberHeight, reach);
     const total = room + placing.rows * rowHeight + (placing.rows - 1) * ROW_GAP;
     const height = Math.ceil(total * viewport.zoom);
     // Where each member is laid out, before it is moved.
@@ -537,14 +554,14 @@ export function A2ATeamGraph({ entry, peer, peers: more = NO_PEERS, flow, flows,
     // Where the members were moved, kept inside the graph's box.
     const boundsOf = (id) => {
         const layout = layoutOf(id);
-        const under = placed.find(({ member }) => member === id)?.connections.length
-            ? CONNECTION_GAP + connectionHeight
-            : 0;
+        const count = placed.find(({ member }) => member === id)?.connections.length ?? 0;
+        const beside = count ? CONNECTIONS_BESIDE : 0;
+        const tall = Math.max(memberHeight, connectionsReach(size, count, connectionHeight));
         return {
             minDx: -layout.x,
-            maxDx: drawn - NODE_WIDTH - layout.x,
+            maxDx: drawn - NODE_WIDTH - beside - layout.x,
             minDy: -layout.y,
-            maxDy: total - layout.y - memberHeight - under,
+            maxDy: total - layout.y - tall,
         };
     };
     const [moved, setMoved] = useState(() => Object.fromEntries(members.map(member => [
@@ -597,13 +614,13 @@ export function A2ATeamGraph({ entry, peer, peers: more = NO_PEERS, flow, flows,
         },
         // A member's connections move with it.
         ...connections.map((connection, at) => {
-            const xs = connectionsX(x, connections.length);
+            const ys = connectionsY(y, size, connections.length, connectionHeight);
             return {
                 id: connectionNodeId(id, connection),
                 type: 'connection',
                 position: {
-                    x: xs[at],
-                    y: y + memberHeight + CONNECTION_GAP,
+                    x: x + CONNECTION_X,
+                    y: ys[at],
                 },
                 width: CONNECTION_WIDTH,
                 height: connectionHeight,

package/lib/specs/sceneSchema.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The scene spec's JSON Schema (`loop.scene/v1`), generated from agentspecs by
+ * `scripts/codegen/generate_scenes.py`. Do not edit.
+ *
+ * @module specs/sceneSchema
+ */
+import type { JsonSchema } from './appspecSchema';
+export declare const SCENE_SCHEMA: JsonSchema;

package/lib/specs/sceneSchema.js

@@ -0,0 +1,852 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export const SCENE_SCHEMA = {
+    $defs: {
+        ActionClass: {
+            description: 'What a tool does to the world.',
+            enum: ['read', 'write', 'send', 'buy', 'delete', 'publish'],
+            title: 'ActionClass',
+            type: 'string',
+        },
+        AnswerKind: {
+            description: 'What kind of answer comes back, and what the page shows.',
+            enum: ['words', 'table', 'chart', 'notebook', 'map', 'file', 'image'],
+            title: 'AnswerKind',
+            type: 'string',
+        },
+        AppVerified: {
+            additionalProperties: false,
+            description: 'What was verified, and how, each in a sentence a person reads (LOOP E-14).\n\nAn example says it on its card and on its page: what was tried live,\nwhat runs on recorded data instead, and what is not verified yet. Said\nby whoever tried it; nothing here is computed.',
+            properties: {
+                live: {
+                    description: 'What was tried live, where and when',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Live',
+                    type: 'array',
+                },
+                recorded: {
+                    description: 'What runs on recorded data, not on live calls',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Recorded',
+                    type: 'array',
+                },
+                unverified: {
+                    description: 'What is not verified yet',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Unverified',
+                    type: 'array',
+                },
+            },
+            title: 'AppVerified',
+            type: 'object',
+        },
+        Inspector: {
+            description: 'The inspectors a page may offer under a scene.',
+            enum: ['agent', 'tools', 'a2a', 'notebook', 'cost'],
+            title: 'Inspector',
+            type: 'string',
+        },
+        Pace: {
+            description: 'How fast a beat plays for the audience.',
+            enum: ['quick', 'steady', 'slow'],
+            title: 'Pace',
+            type: 'string',
+        },
+        RehearsalBeat: {
+            additionalProperties: false,
+            description: "What a beat's transcript must look like.",
+            properties: {
+                beat: {
+                    description: 'The beat, by id',
+                    title: 'Beat',
+                    type: 'string',
+                },
+                lines: {
+                    description: 'The shape, in order: `Sales → Accounting`, `Accounting → Odoo: odoo_accounting_*`, `Accounting: a table`',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Lines',
+                    type: 'array',
+                },
+                must_say: {
+                    description: 'Words that must appear',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Must Say',
+                    type: 'array',
+                },
+                must_not_say: {
+                    description: 'Words that must not',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Must Not Say',
+                    type: 'array',
+                },
+                within: {
+                    default: '',
+                    description: 'The time the beat may take',
+                    pattern: '^(?:[1-9]\\d*(?:ms|s|m|h))?$',
+                    title: 'Within',
+                    type: 'string',
+                },
+            },
+            required: ['beat'],
+            title: 'RehearsalBeat',
+            type: 'object',
+        },
+        SceneAudience: {
+            additionalProperties: false,
+            description: 'Who may watch and ask, and what an ask may cost.',
+            properties: {
+                who: {
+                    $ref: '#/$defs/Watchers',
+                    default: 'signed-in',
+                    description: '`visitors`, `signed-in`, or `nobody`',
+                },
+                ceiling_per_ask: {
+                    default: 0,
+                    description: "What one ask may cost, in USD; the site's when 0",
+                    minimum: 0,
+                    title: 'Ceiling Per Ask',
+                    type: 'number',
+                },
+                asks_a_day: {
+                    default: 0,
+                    description: "How many asks a visitor gets a day; the site's when 0",
+                    minimum: 0,
+                    title: 'Asks A Day',
+                    type: 'integer',
+                },
+            },
+            title: 'SceneAudience',
+            type: 'object',
+        },
+        SceneBeat: {
+            additionalProperties: false,
+            description: 'One beat of the script.',
+            properties: {
+                id: {
+                    description: 'Its id: what the rehearsal and a branch name',
+                    title: 'Id',
+                    type: 'string',
+                },
+                cue: {
+                    $ref: '#/$defs/SceneCue',
+                    description: 'What starts it',
+                },
+                narration: {
+                    default: '',
+                    description: 'One line for the audience, read in the transcript',
+                    title: 'Narration',
+                    type: 'string',
+                },
+                moves: {
+                    description: 'Who asks whom over what, in order',
+                    items: {
+                        $ref: '#/$defs/SceneMove',
+                    },
+                    title: 'Moves',
+                    type: 'array',
+                },
+                expect: {
+                    description: 'What should happen, in words',
+                    title: 'Expect',
+                    type: 'string',
+                },
+                shows: {
+                    description: 'What the page shows: the answers to the audience when unsaid',
+                    items: {
+                        $ref: '#/$defs/AnswerKind',
+                    },
+                    title: 'Shows',
+                    type: 'array',
+                },
+                pace: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/Pace',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: "Its pace; the stage's when unsaid",
+                },
+                branch: {
+                    description: 'What it does instead, on a decision',
+                    items: {
+                        $ref: '#/$defs/SceneBranch',
+                    },
+                    title: 'Branch',
+                    type: 'array',
+                },
+            },
+            required: ['id', 'cue', 'expect'],
+            title: 'SceneBeat',
+            type: 'object',
+        },
+        SceneBranch: {
+            additionalProperties: false,
+            description: 'What a beat does instead when a decision holds.',
+            properties: {
+                decision: {
+                    description: 'When, in words: *the books hold no open invoice*',
+                    title: 'Decision',
+                    type: 'string',
+                },
+                expect: {
+                    default: '',
+                    description: 'What happens then, in words',
+                    title: 'Expect',
+                    type: 'string',
+                },
+                moves: {
+                    description: 'The moves then, when they differ',
+                    items: {
+                        $ref: '#/$defs/SceneMove',
+                    },
+                    title: 'Moves',
+                    type: 'array',
+                },
+                then: {
+                    default: '',
+                    description: 'The beat that follows, by id, when the script goes on elsewhere',
+                    title: 'Then',
+                    type: 'string',
+                },
+            },
+            required: ['decision'],
+            title: 'SceneBranch',
+            type: 'object',
+        },
+        SceneCastMember: {
+            additionalProperties: false,
+            description: 'A member of the cast.\n\nOn a staged team, it names a member of the team (`member`) and says only\nhow it appears here (`persona`) and what it is for in this scene\n(`brief`). Written inline — a scene with no `team` — it is the member:\nwhat it is (`app`, `ref` or `server`), its `role`, where it `runs_in`\nand whom it `talks_to`, as a team member says them.',
+            properties: {
+                member: {
+                    description: 'Its id: in the team, or in this cast',
+                    title: 'Member',
+                    type: 'string',
+                },
+                app: {
+                    default: '',
+                    description: 'Inline: the application it is, `id` or `id:version`',
+                    title: 'App',
+                    type: 'string',
+                },
+                ref: {
+                    default: '',
+                    description: 'Inline: the agent it is, `id` or `id:version`',
+                    title: 'Ref',
+                    type: 'string',
+                },
+                server: {
+                    default: '',
+                    description: 'Inline: the MCP server it is, a system of the scene',
+                    title: 'Server',
+                    type: 'string',
+                },
+                role: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/TeamRole',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'Inline: what it is for, structurally',
+                },
+                runs_in: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/TeamPlace',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'Inline: `browser` or `runtime`',
+                },
+                talks_to: {
+                    description: 'Inline: whom it asks, and over what',
+                    items: {
+                        $ref: '#/$defs/TeamLink',
+                    },
+                    title: 'Talks To',
+                    type: 'array',
+                },
+                persona: {
+                    $ref: '#/$defs/ScenePersona',
+                    description: 'How it appears on stage',
+                },
+                brief: {
+                    default: '',
+                    description: "What it is for in this scene, over its application's instructions",
+                    title: 'Brief',
+                    type: 'string',
+                },
+            },
+            required: ['member'],
+            title: 'SceneCastMember',
+            type: 'object',
+        },
+        SceneCue: {
+            additionalProperties: false,
+            description: 'What starts a beat: something the audience says, a schedule, or an event.',
+            properties: {
+                say: {
+                    default: '',
+                    description: "An opener the audience may say: the entry's suggestion on the page",
+                    title: 'Say',
+                    type: 'string',
+                },
+                schedule: {
+                    default: '',
+                    description: 'A schedule, when the beat starts by itself',
+                    title: 'Schedule',
+                    type: 'string',
+                },
+                event: {
+                    default: '',
+                    description: 'An event, when something happening starts it',
+                    title: 'Event',
+                    type: 'string',
+                },
+            },
+            title: 'SceneCue',
+            type: 'object',
+        },
+        SceneDeployment: {
+            additionalProperties: false,
+            description: 'Where the scene plays.',
+            properties: {
+                account: {
+                    default: '',
+                    description: 'Under which account the scene plays: `demo`',
+                    title: 'Account',
+                    type: 'string',
+                },
+                page: {
+                    default: '',
+                    description: "The page it plays on: the entry's address",
+                    title: 'Page',
+                    type: 'string',
+                },
+                addresses: {
+                    additionalProperties: {
+                        type: 'string',
+                    },
+                    description: 'For each member on a runtime, the variable its address is read from at build',
+                    title: 'Addresses',
+                    type: 'object',
+                },
+            },
+            title: 'SceneDeployment',
+            type: 'object',
+        },
+        SceneMove: {
+            additionalProperties: false,
+            description: 'One member asking another over a protocol, or answering the audience.',
+            properties: {
+                who: {
+                    description: 'The member moving, by its id in the cast',
+                    title: 'Who',
+                    type: 'string',
+                },
+                asks: {
+                    default: '',
+                    description: 'Whom: a member or a system; nobody when it answers the audience',
+                    title: 'Asks',
+                    type: 'string',
+                },
+                over: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/TeamProtocol',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: '`a2a` to a member, `mcp` to a system',
+                },
+                what: {
+                    default: '',
+                    description: 'What it asks for, or what it answers, in words',
+                    title: 'What',
+                    type: 'string',
+                },
+                tool: {
+                    default: '',
+                    description: 'Over `mcp`: the tool, by name or pattern (`odoo_accounting_*`)',
+                    title: 'Tool',
+                    type: 'string',
+                },
+                does: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/ActionClass',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'The kind of tool: `read`, `write`, …',
+                },
+                answers: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/AnswerKind',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'What kind of answer comes back',
+                },
+            },
+            required: ['who'],
+            title: 'SceneMove',
+            type: 'object',
+        },
+        ScenePersona: {
+            additionalProperties: false,
+            description: 'How a member appears to the audience, in this scene.',
+            properties: {
+                name: {
+                    default: '',
+                    description: "The name the audience sees; its application's when unsaid",
+                    title: 'Name',
+                    type: 'string',
+                },
+                face: {
+                    default: '',
+                    description: "One emoji; its application's when unsaid",
+                    title: 'Face',
+                    type: 'string',
+                },
+                line: {
+                    default: '',
+                    description: 'One line of *who I am here*',
+                    title: 'Line',
+                    type: 'string',
+                },
+            },
+            title: 'ScenePersona',
+            type: 'object',
+        },
+        SceneRecording: {
+            additionalProperties: false,
+            description: 'A transcript recorded once, played when the scene cannot play live (LOOP H-08).',
+            properties: {
+                path: {
+                    description: 'Its file, beside the scenes: `sales-and-accounting/recording.json`',
+                    title: 'Path',
+                    type: 'string',
+                },
+                taken: {
+                    default: '',
+                    description: 'When it was recorded',
+                    title: 'Taken',
+                    type: 'string',
+                },
+                note: {
+                    default: '',
+                    description: 'What the audience is told: *recorded on 2026-10-07*',
+                    title: 'Note',
+                    type: 'string',
+                },
+            },
+            required: ['path'],
+            title: 'SceneRecording',
+            type: 'object',
+        },
+        SceneRehearsal: {
+            additionalProperties: false,
+            description: "The scene's tests: a passing rehearsal is the gallery's *Live*.",
+            properties: {
+                beats: {
+                    description: "Each beat's expected shape",
+                    items: {
+                        $ref: '#/$defs/RehearsalBeat',
+                    },
+                    title: 'Beats',
+                    type: 'array',
+                },
+                within: {
+                    default: '',
+                    description: 'The time the whole scene may take',
+                    pattern: '^(?:[1-9]\\d*(?:ms|s|m|h))?$',
+                    title: 'Within',
+                    type: 'string',
+                },
+                recording: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/SceneRecording',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    default: null,
+                    description: 'A recording, for when it cannot play live',
+                },
+                verified: {
+                    $ref: '#/$defs/AppVerified',
+                    description: 'What was verified live, what runs on recorded data, and what is not verified yet',
+                },
+            },
+            title: 'SceneRehearsal',
+            type: 'object',
+        },
+        SceneSetting: {
+            additionalProperties: false,
+            description: 'The stage: what is on it, and what the audience is told.',
+            properties: {
+                systems: {
+                    description: 'The systems the cast reaches',
+                    items: {
+                        $ref: '#/$defs/SceneSystem',
+                    },
+                    title: 'Systems',
+                    type: 'array',
+                },
+                frames: {
+                    description: "The Frames the scene plays under, over the team's",
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Frames',
+                    type: 'array',
+                },
+                contents: {
+                    description: 'The data in play: documents and datasets',
+                    items: {
+                        type: 'string',
+                    },
+                    title: 'Contents',
+                    type: 'array',
+                },
+                period: {
+                    default: '',
+                    description: 'When the scene plays, in words: *March 2026*',
+                    title: 'Period',
+                    type: 'string',
+                },
+                language: {
+                    default: '',
+                    description: 'The language it plays in, `en`',
+                    pattern: '^(?:[a-z]{2,3}(?:-[A-Z]{2})?)?$',
+                    title: 'Language',
+                    type: 'string',
+                },
+                assumes: {
+                    default: '',
+                    description: 'What the audience is told before it starts, one line',
+                    title: 'Assumes',
+                    type: 'string',
+                },
+            },
+            title: 'SceneSetting',
+            type: 'object',
+        },
+        SceneStage: {
+            additionalProperties: false,
+            description: 'Directions for the page.',
+            properties: {
+                positions: {
+                    additionalProperties: {
+                        $ref: '#/$defs/StagePosition',
+                    },
+                    description: 'Where each member stands',
+                    title: 'Positions',
+                    type: 'object',
+                },
+                opens_first: {
+                    default: '',
+                    description: "Whose balloon opens first; the entry's when unsaid",
+                    title: 'Opens First',
+                    type: 'string',
+                },
+                transcript: {
+                    $ref: '#/$defs/SceneTranscript',
+                    description: 'What the transcript shows',
+                },
+                inspectors: {
+                    description: 'The inspectors offered',
+                    items: {
+                        $ref: '#/$defs/Inspector',
+                    },
+                    title: 'Inspectors',
+                    type: 'array',
+                },
+                rests_after: {
+                    default: '',
+                    description: 'How long the scene plays before it rests',
+                    pattern: '^(?:[1-9]\\d*(?:ms|s|m|h))?$',
+                    title: 'Rests After',
+                    type: 'string',
+                },
+                pace: {
+                    $ref: '#/$defs/Pace',
+                    default: 'steady',
+                    description: 'The pace of the beats that say none',
+                },
+            },
+            title: 'SceneStage',
+            type: 'object',
+        },
+        SceneSystem: {
+            additionalProperties: false,
+            description: 'A system on stage: an MCP server of the catalogue the cast reaches.',
+            properties: {
+                server: {
+                    description: 'An MCP server of the catalogue, `id` or `id:version`',
+                    title: 'Server',
+                    type: 'string',
+                },
+                as: {
+                    default: '',
+                    description: 'The name the audience reads on the graph and in the transcript',
+                    title: 'As',
+                    type: 'string',
+                },
+                holds: {
+                    default: '',
+                    description: "What it holds in this scene: *Datalayer's own books, March 2026*",
+                    title: 'Holds',
+                    type: 'string',
+                },
+            },
+            required: ['server'],
+            title: 'SceneSystem',
+            type: 'object',
+        },
+        SceneTranscript: {
+            additionalProperties: false,
+            description: 'What the transcript shows.',
+            properties: {
+                tools: {
+                    default: true,
+                    description: 'Whether tool lines are shown',
+                    title: 'Tools',
+                    type: 'boolean',
+                },
+                narration: {
+                    default: true,
+                    description: "Whether the beats' narration is read in it",
+                    title: 'Narration',
+                    type: 'boolean',
+                },
+                withhold: {
+                    description: 'Words withheld: credentials, ids, …',
+                    items: {
+                        $ref: '#/$defs/Withheld',
+                    },
+                    title: 'Withhold',
+                    type: 'array',
+                },
+            },
+            title: 'SceneTranscript',
+            type: 'object',
+        },
+        StagePosition: {
+            additionalProperties: false,
+            description: 'Where a member stands: fractions of the box, left to right and top to bottom.',
+            properties: {
+                x: {
+                    maximum: 1,
+                    minimum: 0,
+                    title: 'X',
+                    type: 'number',
+                },
+                y: {
+                    maximum: 1,
+                    minimum: 0,
+                    title: 'Y',
+                    type: 'number',
+                },
+            },
+            required: ['x', 'y'],
+            title: 'StagePosition',
+            type: 'object',
+        },
+        TeamLink: {
+            description: 'One member asking another, directly, over a protocol.\n\nDistinct from `depends_on`, which orders work: a link says who may ask\nwhom while the work runs, in either order and as often as it needs.',
+            properties: {
+                member: {
+                    description: 'The member asked, by its id in this team',
+                    title: 'Member',
+                    type: 'string',
+                },
+                over: {
+                    $ref: '#/$defs/TeamProtocol',
+                    default: 'a2a',
+                    description: 'The protocol it is asked over: `a2a` to an agent or an application, `mcp` to a server',
+                },
+            },
+            required: ['member'],
+            title: 'TeamLink',
+            type: 'object',
+        },
+        TeamPlace: {
+            description: "Where a member's loop turns.\n\nA team of applications can be split between the person's page and a\nruntime: what reads the person's screen and talks to them turns in their\nbrowser, what reaches a company's systems turns on a runtime, where its\nconnections and its credentials are.",
+            enum: ['browser', 'runtime'],
+            title: 'TeamPlace',
+            type: 'string',
+        },
+        TeamProtocol: {
+            description: 'How one member talks to another.',
+            enum: ['a2a', 'mcp'],
+            title: 'TeamProtocol',
+            type: 'string',
+        },
+        TeamRole: {
+            description: 'What a member is *for*, structurally.\n\nDeliberately about position in the work rather than about subject matter: a\nteam of analysts and a team of reviewers have the same shape, and a runtime\nscheduling them cares which member opens the work and which closes it, not\nwhat the work is about.',
+            enum: [
+                'coordinator',
+                'initiator',
+                'contributor',
+                'reviewer',
+                'finalizer',
+            ],
+            title: 'TeamRole',
+            type: 'string',
+        },
+        Watchers: {
+            description: 'Who may watch and ask.',
+            enum: ['visitors', 'signed-in', 'nobody'],
+            title: 'Watchers',
+            type: 'string',
+        },
+        Withheld: {
+            description: 'What the transcript does not show.',
+            enum: ['credentials', 'ids', 'addresses', 'amounts'],
+            title: 'Withheld',
+            type: 'string',
+        },
+    },
+    additionalProperties: false,
+    description: 'Specification for a scene: a team, staged.',
+    properties: {
+        schema: {
+            description: 'The version of the spec itself',
+            title: 'Schema',
+            const: 'loop.scene/v1',
+            default: 'loop.scene/v1',
+        },
+        id: {
+            description: 'Unique scene identifier',
+            title: 'Id',
+            type: 'string',
+        },
+        version: {
+            default: '0.0.1',
+            description: 'Scene version',
+            title: 'Version',
+            type: 'string',
+        },
+        name: {
+            description: "Display name: the tab's",
+            title: 'Name',
+            type: 'string',
+        },
+        description: {
+            default: '',
+            description: 'What happens in it, in a sentence',
+            title: 'Description',
+            type: 'string',
+        },
+        tags: {
+            items: {
+                type: 'string',
+            },
+            title: 'Tags',
+            type: 'array',
+        },
+        icon: {
+            default: 'people',
+            description: 'Icon identifier',
+            title: 'Icon',
+            type: 'string',
+        },
+        emoji: {
+            default: '👀',
+            description: 'Its face: one emoji, drawn before its name',
+            title: 'Emoji',
+            type: 'string',
+        },
+        team: {
+            default: '',
+            description: 'The team it stages, `id` or `id:version`',
+            title: 'Team',
+            type: 'string',
+        },
+        entry: {
+            default: '',
+            description: "The member the audience talks to; the team's entry when unsaid",
+            title: 'Entry',
+            type: 'string',
+        },
+        cast: {
+            description: 'The cast: personas and briefs, or the members',
+            items: {
+                $ref: '#/$defs/SceneCastMember',
+            },
+            title: 'Cast',
+            type: 'array',
+        },
+        setting: {
+            $ref: '#/$defs/SceneSetting',
+            description: 'The stage',
+        },
+        script: {
+            description: 'The beats, in order',
+            items: {
+                $ref: '#/$defs/SceneBeat',
+            },
+            title: 'Script',
+            type: 'array',
+        },
+        stage: {
+            $ref: '#/$defs/SceneStage',
+            description: 'Directions for the page',
+        },
+        audience: {
+            $ref: '#/$defs/SceneAudience',
+            description: 'Who may watch and ask',
+        },
+        rehearsal: {
+            $ref: '#/$defs/SceneRehearsal',
+            description: 'Its tests',
+        },
+        deployment: {
+            $ref: '#/$defs/SceneDeployment',
+            description: 'Where it plays',
+        },
+    },
+    required: ['id', 'name'],
+    title: 'Scene spec',
+    type: 'object',
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://agentspecs.datalayer.tech/schemas/loop.scene/v1.json',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.86",
+    "version": "1.3.87",
     "type": "module",
     "workspaces": [
         ".",

package/scripts/codegen/generate_envvars.py

@@ -7,7 +7,7 @@ Generate Python and TypeScript code from YAML environment variable specification
 
 Usage:
     python generate_envvars.py \\
-      --specs-dir specs/envvars \\
+      --specs-dir specs/env-vars \\
       --python-output agent_runtimes/config/envvars.py \\
       --typescript-output src/config/envvars.ts
 """

package/scripts/codegen/generate_scenes.py

@@ -16,6 +16,11 @@ 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.
 
+The scene spec's JSON Schema is written beside the TypeScript catalogue as
+``sceneSchema.ts`` (``agentspecs.scenes.json_schema``), the way
+``generate_apps.py`` writes ``appspecSchema.ts``: what an editor of the text
+completes and explains is what the spec accepts (LOOP S-01, A-03).
+
 Usage:
     python generate_scenes.py \\
       --specs-dir agentspecs/agentspecs/scenes \\
@@ -273,8 +278,41 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
     return "\n".join(lines)
 
 
+def generate_schema_typescript_code(specs_dir: Path) -> str:
+    """The scene spec's JSON Schema, for the editor of its text (LOOP S-01, A-03).
+
+    Taken from the agentspecs the catalogue is generated from, so that what
+    the editor completes and explains is what the spec accepts. The
+    ``JsonSchema`` type is ``appspecSchema.ts``'s.
+    """
+    scenes_module = import_from_clone(specs_dir, "scenes")
+    schema = json.dumps(
+        scenes_module.json_schema(), indent=2, ensure_ascii=False, sort_keys=False
+    )
+    return "\n".join(
+        [
+            "/*",
+            " * Copyright (c) 2025-2026 Datalayer, Inc.",
+            " * Distributed under the terms of the Modified BSD License.",
+            " */",
+            "",
+            "/**",
+            " * The scene spec's JSON Schema (`loop.scene/v1`), generated from agentspecs by",
+            " * `scripts/codegen/generate_scenes.py`. Do not edit.",
+            " *",
+            " * @module specs/sceneSchema",
+            " */",
+            "",
+            "import type { JsonSchema } from './appspecSchema';",
+            "",
+            f"export const SCENE_SCHEMA: JsonSchema = {schema};",
+            "",
+        ]
+    )
+
+
 def main() -> None:
-    """Generate the scene catalogue."""
+    """Generate the scene catalogue, and the scene spec's JSON Schema."""
     parser = argparse.ArgumentParser(
         description="Generate Python and TypeScript code from YAML scene specifications"
     )
@@ -290,6 +328,10 @@ def main() -> None:
     for path, text in (
         (args.python_output, generate_python_code(specs)),
         (args.typescript_output, generate_typescript_code(specs)),
+        (
+            args.typescript_output.with_name("sceneSchema.ts"),
+            generate_schema_typescript_code(args.specs_dir),
+        ),
     ):
         path.parent.mkdir(parents=True, exist_ok=True)
         path.write_text(text)