@adea-ai/spatial 0.112.0 → 0.113.0

package/dist/sim-bridge/scene.js

@@ -0,0 +1,528 @@
+import { boundedString, isPlainRecord, strictRecord } from './record';
+import { SIM_BRIDGE_CHANNEL, SIM_BRIDGE_VERSION } from './messages';
+/**
+ * The workspace scene channel of the Agent Sim bridge (M26, #24, #25, #489, #27). The host feeds
+ * the engine the workspace scene that Virtual view already draws: areas, agents, lead turn and
+ * child-job markers, and lead routes, as a full snapshot and then as diffs against the last
+ * revision the engine acknowledged. The engine renders it and never writes it back: there is no
+ * scene message from the frame other than an acknowledgement, a refusal and a measurement.
+ *
+ * Spec: docs/specs/sim-bridge-scene.md. Rules the code holds:
+ * - Scene messages share the bridge envelope (channel, version, per-mount bridgeId) and its
+ *   origin/source checks, with their own size budget (`MAX_SCENE_MESSAGE_BYTES`).
+ * - One revision is in flight at a time. While it is unacknowledged, newer scene states coalesce:
+ *   the next diff is computed from the acknowledged state to the newest one.
+ * - A diff names the revision it applies to. The engine refuses a diff whose base is not its
+ *   current revision (`revision_gap`), and the host answers with a full snapshot.
+ * - An ack that names any revision other than the one in flight is ignored.
+ * - No ack within `ackTimeoutMs`, an `invalid` or `too_large` refusal, or a gap, resends a full
+ *   snapshot, backing off; `busy` waits `retryAfterMs` (bounded) and resends; `version_unsupported`
+ *   stops the feed.
+ */
+export const SIM_SCENE_VERSION = 1;
+/** A scene message, JSON-encoded, may not exceed this. Snapshots are split into parts. */
+export const MAX_SCENE_MESSAGE_BYTES = 64 * 1024;
+export const MAX_SCENE_ENTITIES_PER_MESSAGE = 200;
+/** The largest scene the host transmits or records as acknowledged. */
+export const MAX_SCENE_ENTITIES = 5_000;
+const encoder = new TextEncoder();
+const encodedBytes = (value) => encoder.encode(JSON.stringify(value)).byteLength;
+export const SIM_SCENE_KINDS = ['workspace', 'area', 'agent', 'turn', 'child_job', 'route'];
+export const SIM_SCENE_STATUSES = [
+    'error',
+    'awaiting_input',
+    'working',
+    'queued',
+    'offline',
+    'unavailable',
+    'idle',
+    'completed',
+    'cancelled',
+    'archived',
+];
+export const SIM_SCENE_ANIMATIONS = ['rest', 'work', 'wait', 'alert', 'celebrate', 'sleep'];
+export const SIM_SCENE_TONES = [
+    'neutral',
+    'active',
+    'attention',
+    'danger',
+    'success',
+    'muted',
+];
+export const SIM_SCENE_REFUSALS = [
+    'revision_gap',
+    'invalid',
+    'too_large',
+    'version_unsupported',
+    'busy',
+];
+const REVISION_MAX = Number.MAX_SAFE_INTEGER;
+const isRevision = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= REVISION_MAX;
+const isMeasure = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1e13;
+const PERF_REQUIRED = [
+    'revision',
+    'sampleWindowMs',
+    'frames',
+    'frameP50Ms',
+    'frameP95Ms',
+    'frameMaxMs',
+    'longFrames',
+    'loadMs',
+    'applyMs',
+    'entities',
+];
+/** Reads the payload of a `frame.scene.*` message; null when it is not exactly that shape. */
+export function parseFrameScenePayload(type, payload) {
+    switch (type) {
+        case 'frame.scene.ack': {
+            const body = strictRecord(payload, ['revision']);
+            return body && isRevision(body.revision)
+                ? { type, payload: { revision: body.revision } }
+                : null;
+        }
+        case 'frame.scene.nack': {
+            const body = strictRecord(payload, ['revision', 'code'], ['retryAfterMs']);
+            const code = SIM_SCENE_REFUSALS.find((item) => item === body?.code);
+            if (!body || !code || !isRevision(body.revision))
+                return null;
+            if ('retryAfterMs' in body && (code !== 'busy' || !isMeasure(body.retryAfterMs)))
+                return null;
+            return {
+                type,
+                payload: {
+                    revision: body.revision,
+                    code,
+                    ...(typeof body.retryAfterMs === 'number' ? { retryAfterMs: body.retryAfterMs } : {}),
+                },
+            };
+        }
+        case 'frame.scene.perf': {
+            const body = strictRecord(payload, PERF_REQUIRED, ['heapBytes', 'gpuBytes']);
+            if (!body || !isRevision(body.revision))
+                return null;
+            for (const key of [...PERF_REQUIRED, 'heapBytes', 'gpuBytes'])
+                if (key in body && !isMeasure(body[key]))
+                    return null;
+            return { type, payload: body };
+        }
+        default:
+            return null;
+    }
+}
+function sceneEnvelope(bridgeId, message) {
+    return {
+        channel: SIM_BRIDGE_CHANNEL,
+        version: SIM_BRIDGE_VERSION,
+        bridgeId,
+        type: message.type,
+        payload: message.payload,
+    };
+}
+/** Host to frame, for scene messages. Same origin rule as `postToFrame`, and a size bound. */
+export function postSceneToFrame(frameWindow, frameOrigin, origins, bridgeId, message) {
+    if (!origins.has(frameOrigin))
+        throw new Error('Refusing to post to an unlisted Agent Sim origin');
+    const envelope = sceneEnvelope(bridgeId, message);
+    if (encodedBytes(envelope) > MAX_SCENE_MESSAGE_BYTES)
+        throw new Error('Agent Sim scene message is over its size budget');
+    frameWindow.postMessage(envelope, frameOrigin);
+}
+const ID = /^[a-z_]+:[A-Za-z0-9_.:-]{1,160}$/;
+const LABEL_MAX = 200;
+const REF = /^[\x21-\x7e]{1,512}$/;
+const COORD_MAX = 1e6;
+const isCoord = (value) => typeof value === 'number' && Number.isFinite(value) && Math.abs(value) <= COORD_MAX;
+function readEntity(value) {
+    const body = strictRecord(value, ['id', 'kind', 'label', 'status', 'animation', 'tone'], ['parentId', 'rect', 'at', 'role', 'characterRef', 'fallback', 'from', 'to', 'lead']);
+    if (!body)
+        return null;
+    const kind = SIM_SCENE_KINDS.find((item) => item === body.kind);
+    const status = SIM_SCENE_STATUSES.find((item) => item === body.status);
+    const animation = SIM_SCENE_ANIMATIONS.find((item) => item === body.animation);
+    const tone = SIM_SCENE_TONES.find((item) => item === body.tone);
+    const id = boundedString(body.id, ID);
+    if (!kind || !status || !animation || !tone || !id)
+        return null;
+    if (typeof body.label !== 'string' || body.label.length > LABEL_MAX)
+        return null;
+    if ('parentId' in body && !boundedString(body.parentId, ID))
+        return null;
+    if ('rect' in body) {
+        const rect = strictRecord(body.rect, ['x', 'y', 'width', 'height']);
+        if (!rect || ![rect.x, rect.y, rect.width, rect.height].every(isCoord))
+            return null;
+    }
+    if ('at' in body) {
+        const at = strictRecord(body.at, ['x', 'y']);
+        if (!at || !isCoord(at.x) || !isCoord(at.y))
+            return null;
+    }
+    if ('role' in body && body.role !== 'lead' && body.role !== 'agent')
+        return null;
+    if ('characterRef' in body && !boundedString(body.characterRef, REF))
+        return null;
+    if ('fallback' in body && typeof body.fallback !== 'boolean')
+        return null;
+    if ('lead' in body && typeof body.lead !== 'boolean')
+        return null;
+    for (const key of ['from', 'to'])
+        if (key in body && !boundedString(body[key], ID))
+            return null;
+    if (kind === 'route' && (!('from' in body) || !('to' in body)))
+        return null;
+    return body;
+}
+function readEntities(value) {
+    if (!Array.isArray(value) || value.length > MAX_SCENE_ENTITIES_PER_MESSAGE)
+        return null;
+    const entities = [];
+    for (let index = 0; index < value.length; index++) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, index);
+        if (!descriptor || !('value' in descriptor))
+            return null;
+        const entity = readEntity(descriptor.value);
+        if (!entity)
+            return null;
+        entities.push(entity);
+    }
+    return entities;
+}
+/**
+ * Engine side: accepts a host scene message only from the embedding window at its exact origin,
+ * on this mount's bridge id, in a supported scene version, within budget and with every entity in
+ * shape. The engine answers `invalid`, `too_large` or `version_unsupported` with a `nack`.
+ */
+export function parseHostSceneMessage(event, context) {
+    const fail = (reason) => ({ ok: false, reason });
+    if (event.origin !== context.parentOrigin)
+        return fail('origin_refused');
+    if (event.source == null || event.source !== context.parentWindow)
+        return fail('source_mismatch');
+    const data = strictRecord(event.data, ['channel', 'version', 'bridgeId', 'type', 'payload']);
+    if (!data || data.channel !== SIM_BRIDGE_CHANNEL)
+        return fail('not_a_scene_message');
+    if (data.type !== 'host.scene.snapshot' && data.type !== 'host.scene.diff')
+        return fail('not_a_scene_message');
+    if (data.version !== SIM_BRIDGE_VERSION)
+        return fail('version_unsupported');
+    if (data.bridgeId !== context.bridgeId)
+        return fail('bridge_mismatch');
+    if (!isPlainRecord(data.payload))
+        return fail('invalid');
+    let size;
+    try {
+        size = encodedBytes(data);
+    }
+    catch {
+        return fail('invalid');
+    }
+    if (size > MAX_SCENE_MESSAGE_BYTES)
+        return fail('too_large');
+    if (data.payload.sceneVersion !== SIM_SCENE_VERSION)
+        return fail('version_unsupported');
+    if (data.type === 'host.scene.snapshot') {
+        const body = strictRecord(data.payload, [
+            'sceneVersion',
+            'workspaceId',
+            'revision',
+            'part',
+            'parts',
+            'entities',
+        ]);
+        const entities = readEntities(body?.entities);
+        if (!body ||
+            !entities ||
+            typeof body.workspaceId !== 'string' ||
+            !isRevision(body.revision) ||
+            !Number.isSafeInteger(body.parts) ||
+            !Number.isSafeInteger(body.part) ||
+            body.part < 1 ||
+            body.part > body.parts ||
+            body.parts > MAX_SCENE_ENTITIES)
+            return fail('invalid');
+        return {
+            ok: true,
+            message: {
+                type: 'host.scene.snapshot',
+                payload: {
+                    sceneVersion: SIM_SCENE_VERSION,
+                    workspaceId: body.workspaceId,
+                    revision: body.revision,
+                    part: body.part,
+                    parts: body.parts,
+                    entities,
+                },
+            },
+        };
+    }
+    const body = strictRecord(data.payload, [
+        'sceneVersion',
+        'workspaceId',
+        'baseRevision',
+        'revision',
+        'upserts',
+        'removes',
+    ]);
+    const upserts = readEntities(body?.upserts);
+    const removes = body?.removes;
+    if (!body ||
+        !upserts ||
+        typeof body.workspaceId !== 'string' ||
+        !isRevision(body.baseRevision) ||
+        !isRevision(body.revision) ||
+        body.revision <= body.baseRevision ||
+        !Array.isArray(removes) ||
+        removes.length > MAX_SCENE_ENTITIES_PER_MESSAGE ||
+        !removes.every((id) => boundedString(id, ID)))
+        return fail('invalid');
+    return {
+        ok: true,
+        message: {
+            type: 'host.scene.diff',
+            payload: {
+                sceneVersion: SIM_SCENE_VERSION,
+                workspaceId: body.workspaceId,
+                baseRevision: body.baseRevision,
+                revision: body.revision,
+                upserts,
+                removes: removes,
+            },
+        },
+    };
+}
+const DEFAULT_ACK_TIMEOUT_MS = 5_000;
+const BACKOFF_MIN_MS = 500;
+const BACKOFF_MAX_MS = 30_000;
+function defaultSchedule(run, ms) {
+    const id = setTimeout(run, ms);
+    return () => clearTimeout(id);
+}
+function sameEntity(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * The host side of the scene channel: keeps what the engine acknowledged, sends one revision at a
+ * time, and recovers from refusals, gaps and silence by resending a full snapshot with backoff.
+ */
+export function createSimSceneFeed(options) {
+    const schedule = options.schedule ?? defaultSchedule;
+    const ackTimeoutMs = Math.min(Math.max(options.ackTimeoutMs ?? DEFAULT_ACK_TIMEOUT_MS, 250), 60_000);
+    let desired = null;
+    let acked = new Map();
+    let ackedRevision = 0;
+    let nextRevision = 1;
+    let needSnapshot = true;
+    let inFlight = null;
+    let cancelTimer;
+    let state = 'idle';
+    let failures = 0;
+    const counts = { snapshots: 0, diffs: 0, timeouts: 0, refusals: 0, ignoredAcks: 0 };
+    let lastPerf = null;
+    const clearTimer = () => {
+        cancelTimer?.();
+        cancelTimer = undefined;
+    };
+    const backOff = (ms) => {
+        clearTimer();
+        state = 'backing_off';
+        cancelTimer = schedule(() => {
+            cancelTimer = undefined;
+            state = 'idle';
+            pump();
+        }, ms);
+    };
+    const retryLater = () => {
+        const delay = Math.min(BACKOFF_MAX_MS, BACKOFF_MIN_MS * 2 ** failures);
+        failures += 1;
+        backOff(delay);
+    };
+    function pump() {
+        if (state === 'disposed' || state === 'stopped' || state === 'backing_off')
+            return;
+        if (inFlight || !desired)
+            return;
+        const target = desired;
+        const messages = [];
+        const revision = nextRevision;
+        if (needSnapshot) {
+            const entities = [...target.values()];
+            const chunks = [[]];
+            // Reserve the maximum bridge id (64 characters) and part-number widths.
+            // Count each entity once, rather than serializing every growing candidate chunk.
+            const overhead = encodedBytes(sceneEnvelope('x'.repeat(64), {
+                type: 'host.scene.snapshot',
+                payload: {
+                    sceneVersion: SIM_SCENE_VERSION,
+                    workspaceId: options.workspaceId,
+                    revision,
+                    part: MAX_SCENE_ENTITIES,
+                    parts: MAX_SCENE_ENTITIES,
+                    entities: [],
+                },
+            }));
+            let chunk = chunks[0];
+            let bytes = overhead;
+            for (const entity of entities) {
+                const entityBytes = encodedBytes(entity);
+                if (overhead + entityBytes > MAX_SCENE_MESSAGE_BYTES)
+                    throw new Error('Agent Sim scene entity is over its size budget');
+                if (chunk.length > 0 &&
+                    (chunk.length === MAX_SCENE_ENTITIES_PER_MESSAGE ||
+                        bytes + 1 + entityBytes > MAX_SCENE_MESSAGE_BYTES)) {
+                    chunk = [];
+                    chunks.push(chunk);
+                    bytes = overhead;
+                }
+                bytes += entityBytes + (chunk.length > 0 ? 1 : 0);
+                chunk.push(entity);
+            }
+            for (const [index, partEntities] of chunks.entries())
+                messages.push({
+                    type: 'host.scene.snapshot',
+                    payload: {
+                        sceneVersion: SIM_SCENE_VERSION,
+                        workspaceId: options.workspaceId,
+                        revision,
+                        part: index + 1,
+                        parts: chunks.length,
+                        entities: partEntities,
+                    },
+                });
+        }
+        else {
+            const upserts = [];
+            const removes = [];
+            for (const [id, entity] of target) {
+                const old = acked.get(id);
+                if (!old || !sameEntity(old, entity))
+                    upserts.push(entity);
+            }
+            for (const id of acked.keys())
+                if (!target.has(id))
+                    removes.push(id);
+            if (upserts.length === 0 && removes.length === 0) {
+                state = 'synced';
+                return;
+            }
+            // A change too big for one message is cheaper as a snapshot than as a split diff.
+            if (upserts.length > MAX_SCENE_ENTITIES_PER_MESSAGE ||
+                removes.length > MAX_SCENE_ENTITIES_PER_MESSAGE) {
+                needSnapshot = true;
+                pump();
+                return;
+            }
+            const message = {
+                type: 'host.scene.diff',
+                payload: {
+                    sceneVersion: SIM_SCENE_VERSION,
+                    workspaceId: options.workspaceId,
+                    baseRevision: ackedRevision,
+                    revision,
+                    upserts,
+                    removes,
+                },
+            };
+            if (encodedBytes(sceneEnvelope('x'.repeat(64), message)) > MAX_SCENE_MESSAGE_BYTES) {
+                needSnapshot = true;
+                pump();
+                return;
+            }
+            messages.push(message);
+        }
+        nextRevision += 1;
+        // In flight before the first post: an engine may answer synchronously.
+        inFlight = { revision, target };
+        state = 'sending';
+        clearTimer();
+        cancelTimer = schedule(() => {
+            cancelTimer = undefined;
+            if (!inFlight || inFlight.revision !== revision)
+                return;
+            counts.timeouts += 1;
+            inFlight = null;
+            needSnapshot = true;
+            retryLater();
+        }, ackTimeoutMs);
+        if (messages[0].type === 'host.scene.snapshot')
+            counts.snapshots += 1;
+        else
+            counts.diffs += 1;
+        try {
+            for (const message of messages) {
+                // An answer that arrived mid-snapshot ended this revision; stop sending its parts.
+                if (inFlight?.revision !== revision && messages.length > 1)
+                    break;
+                options.send(message);
+            }
+        }
+        catch {
+            if (inFlight?.revision === revision) {
+                clearTimer();
+                inFlight = null;
+                needSnapshot = true;
+                retryLater();
+            }
+        }
+    }
+    return {
+        update(entities) {
+            if (state === 'disposed')
+                return;
+            const next = new Map(entities.map((entity) => [entity.id, entity]));
+            // Acknowledgements must describe exactly the bounded scene sent to the engine.
+            desired =
+                next.size <= MAX_SCENE_ENTITIES ? next : new Map([...next].slice(0, MAX_SCENE_ENTITIES));
+            pump();
+        },
+        receive(message) {
+            if (state === 'disposed')
+                return;
+            if (message.type === 'frame.scene.perf') {
+                lastPerf = message.payload;
+                options.onPerf?.(message.payload);
+                return;
+            }
+            if (!inFlight || message.payload.revision !== inFlight.revision) {
+                counts.ignoredAcks += 1;
+                return;
+            }
+            clearTimer();
+            const { revision, target } = inFlight;
+            inFlight = null;
+            if (message.type === 'frame.scene.ack') {
+                acked = new Map(target);
+                ackedRevision = revision;
+                needSnapshot = false;
+                failures = 0;
+                state = 'idle';
+                pump();
+                if (!inFlight && state === 'idle')
+                    state = 'synced';
+                return;
+            }
+            counts.refusals += 1;
+            switch (message.payload.code) {
+                case 'version_unsupported':
+                    state = 'stopped';
+                    return;
+                case 'busy':
+                    backOff(Math.min(Math.max(message.payload.retryAfterMs ?? BACKOFF_MIN_MS, 100), 10_000));
+                    return;
+                default:
+                    needSnapshot = true;
+                    retryLater();
+            }
+        },
+        stats: () => ({
+            state,
+            ackedRevision,
+            ...counts,
+            lastPerf,
+        }),
+        dispose() {
+            clearTimer();
+            inFlight = null;
+            state = 'disposed';
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/spatial",
-  "version": "0.112.0",
+  "version": "0.113.0",
   "description": "Scene and asset manifest contracts plus the shell-to-engine spatial protocol for Adea workspaces: scene mount manifests, spawn URL helpers, and scene telemetry schemas. Pure types — no rendering, no binaries.",
   "keywords": [
     "assets",

package/src/index.ts

@@ -1,15 +1,6 @@
 import { isSerializedSimCharacter } from './sim-bridge/character'
 
 export * from './asset-manifests'
-export {
-  agentSimEngineManifestUrl,
-  isLocalDevHost,
-  isOfficialAgentSimWebOrigin,
-  parseAgentSimEngineManifest,
-  OFFICIAL_AGENT_SIM_WEB_HOSTS,
-  type AgentSimEngineManifest,
-  type AgentSimEngineSurface,
-} from './engine'
 export { hqHomeManifest, hqWorkManifest } from './manifests'
 export {
   appRouteHref,

package/src/sim-bridge/index.ts

@@ -6,3 +6,4 @@ export * from './messages'
 export * from './origin'
 export * from './save-client'
 export * from './service'
+export * from './scene'

package/src/sim-bridge/messages.ts

@@ -3,6 +3,7 @@ import type { OriginAllowlist } from './origin'
 import { SIM_SURFACES, type SimSurface } from './launch'
 import { parseSimCharacterValue } from './character'
 import { SIM_UNAVAILABLE_REASONS, type SimUnavailableReason } from './availability'
+import { parseFrameScenePayload, type SimFrameSceneMessage } from './scene'
 
 /**
  * Versioned message schema between the Adea host window and the hosted Agent Sim frame.
@@ -59,7 +60,8 @@ export type SimFrameRequestMessage =
       payload: Readonly<{ requestId: string; character: string }>
     }>
 
-export type SimFrameMessage = SimFrameStatusMessage | SimFrameRequestMessage
+/** The scene channel's acknowledgements, refusals and measurements (see `scene.ts`). */
+export type SimFrameMessage = SimFrameStatusMessage | SimFrameRequestMessage | SimFrameSceneMessage
 
 export type SimHostMessage =
   | Readonly<{
@@ -209,6 +211,12 @@ export function parseFrameMessage(
         ? { ok: true, message: { type, payload: { requestId, character } } }
         : fail('invalid_payload')
     }
+    case 'frame.scene.ack':
+    case 'frame.scene.nack':
+    case 'frame.scene.perf': {
+      const message = parseFrameScenePayload(type, payload)
+      return message ? { ok: true, message } : fail('invalid_payload')
+    }
     default:
       return fail('unknown_type')
   }