@statelyai/sdk 0.15.0 → 0.16.1

package/dist/{inspect-DWDTNMEc.mjs → inspect-C3Y_o_Np.mjs}

@@ -1,5 +1,5 @@
-import { a as createPendingExportManager, i as createEventRegistry, r as createWebSocketTransport } from "./transport-D2Ud05yg.mjs";
-import { INSPECTION_PROTOCOL_VERSION } from "./protocol.mjs";
+import { i as createPendingExportManager, n as createWebSocketTransport, r as createEventRegistry } from "./transport-B_ig9Znn.mjs";
+import { INSPECTION_PROTOCOL_VERSION, createInspectionRoomUrls, getInspectionRoomId } from "./protocol.mjs";
 
 //#region src/openBrowser.ts
 async function openBrowser(url) {
@@ -26,6 +26,15 @@ async function openBrowser(url) {
 	});
 }
 
+//#endregion
+//#region src/version.ts
+const SDK_VERSION = "0.16.1";
+function inspectionRuntime() {
+	if (typeof window !== "undefined") return "browser";
+	if (typeof process !== "undefined" && process.versions?.node) return "node";
+	return "unknown";
+}
+
 //#endregion
 //#region src/inspect.ts
 const defaultSerializeSnapshot = (snapshot) => ({
@@ -37,25 +46,23 @@ function isStoppedSnapshot(snapshot) {
 	const status = snapshot?.status;
 	return status === "done" || status === "stopped" || status === "error";
 }
-function generateSessionId() {
-	if (!globalThis.crypto?.randomUUID) throw new Error("createInspector() requires crypto.randomUUID() to generate a secure session capability. Pass sessionId explicitly in older runtimes.");
+function generateRoomId() {
+	if (!globalThis.crypto?.randomUUID) throw new Error("createInspector() requires crypto.randomUUID() to generate a secure room capability. Pass roomId explicitly in older runtimes.");
 	return globalThis.crypto.randomUUID();
 }
-function createInspectorLaunchUrl(websocketUrl, sessionId) {
-	try {
-		const launchUrl = new URL(websocketUrl);
-		if (launchUrl.protocol === "ws:") launchUrl.protocol = "http:";
-		else if (launchUrl.protocol === "wss:") launchUrl.protocol = "https:";
-		else return null;
-		launchUrl.searchParams.set("session", sessionId);
-		return launchUrl.toString();
-	} catch {
-		return null;
-	}
-}
 function createInspector(options = {}) {
-	const { url = "ws://localhost:4242", autoOpen = true, name, serializeSnapshot = defaultSerializeSnapshot, extractMachineConfig = defaultExtractMachineConfig, selectedActorId, panels, theme, readOnly, depth, capabilities, transport: injectedTransport } = options;
-	const sessionId = options.sessionId ?? generateSessionId();
+	const environmentUrl = typeof process !== "undefined" ? process.env?.STATELY_INSPECT_URL : void 0;
+	const url = options.url ?? environmentUrl ?? "wss://sky.stately.ai";
+	const { inspectorBaseUrl, autoOpen = true, name, serializeSnapshot = defaultSerializeSnapshot, extractMachineConfig = defaultExtractMachineConfig, selectedSessionId: configuredSelectedSessionId, selectedActorId, panels, theme, readOnly, depth, capabilities, transport: injectedTransport } = options;
+	const roomId = options.roomId ?? options.sessionId ?? getInspectionRoomId(url) ?? generateRoomId();
+	const producerId = options.producerId ?? generateRoomId();
+	const roomUrls = injectedTransport ? null : createInspectionRoomUrls({
+		url,
+		roomId,
+		inspectorBaseUrl
+	});
+	const relayUrl = roomUrls?.relayUrl ?? null;
+	const inspectorUrl = roomUrls?.inspectorUrl ?? null;
 	const displayName = name ?? "system:manual";
 	let destroyed = false;
 	let initSent = false;
@@ -63,14 +70,26 @@ function createInspector(options = {}) {
 	let pendingTransportReady = false;
 	let transportWasReady = false;
 	let didAutoOpen = false;
+	let resolveReady;
+	let rejectReady;
+	let readySettled = false;
+	const ready = new Promise((resolve, reject) => {
+		resolveReady = resolve;
+		rejectReady = reject;
+	});
+	ready.catch(() => {});
 	const pendingMessages = [];
 	const events = createEventRegistry();
 	const localListeners = {};
 	const transport = injectedTransport ?? createWebSocketTransport({
-		url,
-		role: "client",
-		sessionId,
-		metadata: { name: displayName }
+		url: relayUrl,
+		role: "producer",
+		producerId,
+		metadata: {
+			name: displayName,
+			sdkVersion: SDK_VERSION,
+			runtime: inspectionRuntime()
+		}
 	});
 	const ownsTransport = !injectedTransport;
 	const exportManager = createPendingExportManager((message) => send(message));
@@ -87,6 +106,8 @@ function createInspector(options = {}) {
 			if (!initSent) sendInit();
 			const queued = pendingMessages.splice(0);
 			for (const message of queued) transport.send(message);
+			readySettled = true;
+			resolveReady();
 		} else {
 			pendingMessages.length = 0;
 			initSent = false;
@@ -94,8 +115,7 @@ function createInspector(options = {}) {
 		}
 		if (autoOpen && !didAutoOpen && ownsTransport) {
 			didAutoOpen = true;
-			const launchUrl = createInspectorLaunchUrl(url, sessionId);
-			if (launchUrl) openBrowser(launchUrl).catch((error) => {
+			if (inspectorUrl) openBrowser(inspectorUrl).catch((error) => {
 				const failure = {
 					code: "open_failed",
 					message: error instanceof Error ? error.message : "Unable to open the inspector browser"
@@ -112,6 +132,15 @@ function createInspector(options = {}) {
 		}
 		handleTransportReady();
 	});
+	transport.onError?.((failure) => {
+		const error = new Error(failure.message);
+		if (!readySettled) {
+			readySettled = true;
+			rejectReady(error);
+		}
+		emitLocal("error", failure);
+		events.emit("error", failure);
+	});
 	transport.onMessage((msg) => {
 		if (destroyed) return;
 		switch (msg.type) {
@@ -120,6 +149,10 @@ function createInspector(options = {}) {
 				break;
 			case "@statelyai.error":
 				exportManager.reject(new Error(msg.message), msg.requestId);
+				if (!readySettled) {
+					readySettled = true;
+					rejectReady(new Error(msg.message));
+				}
 				emitLocal("error", {
 					code: msg.code,
 					message: msg.message
@@ -138,13 +171,14 @@ function createInspector(options = {}) {
 		for (const handler of set) handler(data);
 	}
 	const actors = /* @__PURE__ */ new Map();
+	const manualSessionIds = /* @__PURE__ */ new Map();
 	/** Tracks which actors we've already emitted local actor events for. */
 	const locallyRegistered = /* @__PURE__ */ new Set();
 	/** v5 emits transition facets separately; accumulate them until snapshot. */
 	const pendingTransitions = /* @__PURE__ */ new Map();
 	function emitRegisterOnce(entry) {
-		if (locallyRegistered.has(entry.actorId)) return;
-		locallyRegistered.add(entry.actorId);
+		if (locallyRegistered.has(entry.sessionId)) return;
+		locallyRegistered.add(entry.sessionId);
 		emitLocal("actor", entry);
 		emitLocal("register", entry);
 	}
@@ -164,10 +198,10 @@ function createInspector(options = {}) {
 	}
 	function toEntry(actorRef, rootActorId, details) {
 		return {
-			actorId: actorRef.sessionId,
-			parentActorId: details?.parentRef?.sessionId ?? actorRef._parent?.sessionId ?? null,
-			rootId: rootActorId,
-			id: details?.id ?? actorRef.id ?? actorRef.sessionId,
+			sessionId: actorRef.sessionId,
+			actorId: details?.id ?? actorRef.id ?? actorRef.sessionId,
+			parentSessionId: details?.parentRef?.sessionId ?? actorRef._parent?.sessionId ?? null,
+			rootSessionId: rootActorId,
 			systemId: actorRef.systemId,
 			snapshot: details?.snapshot ? serializeSnapshot(details.snapshot) : snapshotValue(actorRef),
 			stopped: stoppedValue(actorRef, details?.snapshot),
@@ -176,9 +210,9 @@ function createInspector(options = {}) {
 	}
 	function toSystemEntry(entry) {
 		return {
+			sessionId: entry.sessionId,
 			actorId: entry.actorId,
-			parentActorId: entry.parentActorId,
-			id: entry.id,
+			parentSessionId: entry.parentSessionId,
 			machine: entry.machineConfig,
 			snapshot: entry.snapshot ?? void 0,
 			...entry.stopped && { stopped: true }
@@ -195,7 +229,7 @@ function createInspector(options = {}) {
 			const snapshot = actorRef.getSnapshot();
 			existing.snapshot = serializeSnapshot(snapshot);
 			existing.stopped ||= isStoppedSnapshot(snapshot);
-		} else actors.set(entry.actorId, entry);
+		} else actors.set(entry.sessionId, entry);
 		emitRegisterOnce(entry);
 		const children = actorRef.getSnapshot()?.children ?? {};
 		for (const child of Object.values(children)) if (child) backfillActorTree(child, rootActorId);
@@ -204,12 +238,14 @@ function createInspector(options = {}) {
 	const observedRootIds = /* @__PURE__ */ new Set();
 	function sendInit() {
 		for (const [rootActorId, { actor }] of inspectedRoots) backfillActorTree(actor, rootActorId);
+		const allEntries = Array.from(actors.values());
+		const selectedSessionId = configuredSelectedSessionId ?? selectedActorId ?? observedRootIds.values().next().value ?? allEntries[0]?.sessionId;
 		send({
 			type: "@statelyai.system.init",
 			protocolVersion: INSPECTION_PROTOCOL_VERSION,
 			mode: "inspecting",
-			actors: Array.from(actors.values()).map(toSystemEntry),
-			selectedActorId: selectedActorId ?? observedRootIds.values().next().value ?? sessionId,
+			actors: allEntries.map(toSystemEntry),
+			...selectedSessionId && { selectedSessionId },
 			...theme && { theme },
 			...readOnly !== void 0 && { readOnly },
 			...depth !== void 0 && { depth },
@@ -223,13 +259,13 @@ function createInspector(options = {}) {
 	function handleActor(actorRef, rootActorId, details) {
 		if (actors.has(actorRef.sessionId)) return;
 		const entry = toEntry(actorRef, rootActorId, details);
-		actors.set(entry.actorId, entry);
+		actors.set(entry.sessionId, entry);
 		emitRegisterOnce(entry);
 		if (initSent) send({
 			type: "@statelyai.system.actorRegistered",
+			sessionId: entry.sessionId,
 			actorId: entry.actorId,
-			parentActorId: entry.parentActorId,
-			id: entry.id,
+			parentSessionId: entry.parentSessionId,
 			machine: entry.machineConfig,
 			snapshot: entry.snapshot ?? void 0
 		});
@@ -254,7 +290,7 @@ function createInspector(options = {}) {
 	}
 	function normalizeSentEvent(sentEvent) {
 		return {
-			...sentEvent.targetRef?.sessionId && { targetActorId: sentEvent.targetRef.sessionId },
+			...sentEvent.targetRef?.sessionId && { targetSessionId: sentEvent.targetRef.sessionId },
 			targetId: sentEvent.targetId,
 			event: sentEvent.event,
 			...sentEvent.delay !== void 0 && { delay: sentEvent.delay },
@@ -265,23 +301,23 @@ function createInspector(options = {}) {
 		return {
 			previousSnapshot: actors.get(actorRef.sessionId)?.snapshot ?? null,
 			event,
-			sourceActorId: sourceRef?.sessionId ?? null,
+			sourceSessionId: sourceRef?.sessionId ?? null,
 			actions: [],
 			transitions: [],
 			sent: []
 		};
 	}
-	function handleEvent(actorId, event, sourceActorId) {
+	function handleEvent(sessionId, event, sourceSessionId) {
 		const inspectedEvent = {
-			actorId,
-			sourceActorId,
+			sessionId,
+			sourceSessionId,
 			event
 		};
 		if (initSent) send({
 			type: "@statelyai.system.actorEvent",
-			actorId,
+			sessionId,
 			event,
-			sourceActorId
+			sourceSessionId
 		});
 		emitLocal("event", inspectedEvent);
 	}
@@ -298,8 +334,8 @@ function createInspector(options = {}) {
 		if (!entry) return;
 		const serialized = serializeSnapshot(snapshot);
 		const inspectedSnapshot = {
-			actorId: entry.actorId,
-			sourceActorId: transition.sourceActorId,
+			sessionId: entry.sessionId,
+			sourceSessionId: transition.sourceSessionId,
 			previousSnapshot: transition.previousSnapshot,
 			snapshot: serialized,
 			event: triggeringEvent ?? transition.event ?? null,
@@ -311,14 +347,14 @@ function createInspector(options = {}) {
 		entry.snapshot = serialized;
 		const stopped = isStoppedSnapshot(snapshot);
 		entry.stopped ||= stopped;
-		pendingTransitions.delete(entry.actorId);
+		pendingTransitions.delete(entry.sessionId);
 		if (initSent) send({
 			type: "@statelyai.system.actorSnapshot",
-			actorId: entry.actorId,
+			sessionId: entry.sessionId,
 			previousSnapshot: inspectedSnapshot.previousSnapshot,
 			snapshot: inspectedSnapshot.snapshot,
 			event: inspectedSnapshot.event,
-			sourceActorId: inspectedSnapshot.sourceActorId,
+			sourceSessionId: inspectedSnapshot.sourceSessionId,
 			actions: inspectedSnapshot.actions,
 			transitions: inspectedSnapshot.transitions,
 			sent: inspectedSnapshot.sent
@@ -326,12 +362,12 @@ function createInspector(options = {}) {
 		emitLocal("snapshot", inspectedSnapshot);
 		emitLocal("transition", inspectedSnapshot);
 		if (stopped && !wasStopped) {
-			pendingTransitions.delete(entry.actorId);
+			pendingTransitions.delete(entry.sessionId);
 			if (initSent) send({
 				type: "@statelyai.system.actorStopped",
-				actorId: entry.actorId
+				sessionId: entry.sessionId
 			});
-			const stopped = { actorId: entry.actorId };
+			const stopped = { sessionId: entry.sessionId };
 			emitLocal("stop", stopped);
 			emitLocal("stopped", stopped);
 		}
@@ -372,7 +408,7 @@ function createInspector(options = {}) {
 				handleTransition(event.actorRef, event.snapshot, event.event, rootActorId, {
 					previousSnapshot: actors.get(event.actorRef.sessionId)?.snapshot ?? null,
 					event: event.event,
-					sourceActorId: event.sourceRef?.sessionId ?? null,
+					sourceSessionId: event.sourceRef?.sessionId ?? null,
 					actions: event.actions.map(normalizeAction),
 					transitions: event.microsteps.map(normalizeTakenTransition),
 					sent: event.sent.map(normalizeSentEvent)
@@ -400,37 +436,44 @@ function createInspector(options = {}) {
 			inspectedRoots.delete(rootActorId);
 		} };
 	}
+	function getManualSessionId(actorId) {
+		return manualSessionIds.get(actorId) ?? `${producerId}:${actorId}`;
+	}
 	function manualRegister(id, opts) {
-		if (actors.has(id)) return;
+		const sessionId = getManualSessionId(id);
+		if (actors.has(sessionId)) return;
+		manualSessionIds.set(id, sessionId);
+		const parentSessionId = opts?.parent ? getManualSessionId(opts.parent) : null;
 		const entry = {
+			sessionId,
 			actorId: id,
-			parentActorId: opts?.parent ?? null,
-			rootId: sessionId,
-			id,
+			parentSessionId,
+			rootSessionId: (parentSessionId && actors.get(parentSessionId)?.rootSessionId) ?? sessionId,
 			systemId: opts?.systemId,
 			snapshot: opts?.snapshot ?? null,
 			stopped: false,
 			machineConfig: opts?.machine ?? null
 		};
-		actors.set(id, entry);
+		actors.set(sessionId, entry);
 		if (!initSent) sendInit();
 		else send({
 			type: "@statelyai.system.actorRegistered",
+			sessionId,
 			actorId: id,
-			parentActorId: entry.parentActorId,
-			id,
+			parentSessionId: entry.parentSessionId,
 			machine: entry.machineConfig,
 			snapshot: entry.snapshot ?? void 0
 		});
 		emitRegisterOnce(entry);
 	}
 	function manualSnapshot(actorId, snapshot, event) {
-		if (!actors.has(actorId)) manualRegister(actorId);
-		const entry = actors.get(actorId);
+		const sessionId = getManualSessionId(actorId);
+		if (!actors.has(sessionId)) manualRegister(actorId);
+		const entry = actors.get(sessionId);
 		const previousSnapshot = entry.snapshot;
 		const inspectedSnapshot = {
-			actorId,
-			sourceActorId: null,
+			sessionId,
+			sourceSessionId: null,
 			previousSnapshot,
 			snapshot,
 			event: event ?? null,
@@ -441,11 +484,11 @@ function createInspector(options = {}) {
 		entry.snapshot = snapshot;
 		if (initSent) send({
 			type: "@statelyai.system.actorSnapshot",
-			actorId,
+			sessionId,
 			previousSnapshot,
 			snapshot,
 			event: event ?? null,
-			sourceActorId: null,
+			sourceSessionId: null,
 			actions: [],
 			transitions: [],
 			sent: []
@@ -455,18 +498,20 @@ function createInspector(options = {}) {
 	}
 	function manualEvent(actorId, event, eventOpts) {
 		const eventObj = typeof event === "string" ? { type: event } : { ...event };
-		if (!actors.has(actorId)) manualRegister(actorId);
-		handleEvent(actorId, eventObj, eventOpts?.source ?? null);
+		const sessionId = getManualSessionId(actorId);
+		if (!actors.has(sessionId)) manualRegister(actorId);
+		handleEvent(sessionId, eventObj, eventOpts?.source ? getManualSessionId(eventOpts.source) : null);
 	}
 	function manualStop(actorId) {
-		const entry = actors.get(actorId);
+		const sessionId = getManualSessionId(actorId);
+		const entry = actors.get(sessionId);
 		if (!entry || entry.stopped) return;
 		entry.stopped = true;
 		if (initSent) send({
 			type: "@statelyai.system.actorStopped",
-			actorId
+			sessionId
 		});
-		const stopped = { actorId };
+		const stopped = { sessionId };
 		emitLocal("stop", stopped);
 		emitLocal("stopped", stopped);
 	}
@@ -477,9 +522,14 @@ function createInspector(options = {}) {
 	}
 	return {
 		actors,
+		roomId,
+		relayUrl,
+		producerId,
 		get sessionId() {
-			return sessionId;
+			return roomId;
 		},
+		inspectorUrl,
+		ready,
 		inspect: handleInspectionEvent,
 		attach: attachActor,
 		on(event, handler) {

package/dist/inspect.d.mts

@@ -1,3 +1,3 @@
 import { EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InspectionAction, InspectionSentEvent, InspectionTakenTransition } from "./protocol.mjs";
-import { a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, h as Transport, i as InspectedSnapshot, l as ManualActorOptions, n as CreateInspectorOptions, o as Inspector, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector } from "./inspect-DenVP7IE.mjs";
+import { a as InspectedTransition, c as InspectorInspectionEvent, d as createStatelyInspector, f as Transport, i as InspectedSnapshot, l as ManualActorOptions, n as CreateInspectorOptions, o as Inspector, r as InspectedEvent, s as InspectorEvents, t as AdoptedActor, u as createInspector } from "./inspect-BScvqVcM.mjs";
 export { AdoptedActor, CreateInspectorOptions, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ExportCallOptions, ExportFormat, ExportFormatMap, InspectedEvent, InspectedSnapshot, InspectedTransition, InspectionAction, InspectionSentEvent, InspectionTakenTransition, Inspector, InspectorEvents, InspectorInspectionEvent, ManualActorOptions, Transport, createInspector, createStatelyInspector };

package/dist/inspect.mjs

@@ -1,3 +1,3 @@
-import { n as createStatelyInspector, t as createInspector } from "./inspect-DWDTNMEc.mjs";
+import { n as createStatelyInspector, t as createInspector } from "./inspect-C3Y_o_Np.mjs";
 
 export { createInspector, createStatelyInspector };

package/dist/node-relay.d.mts

@@ -0,0 +1,22 @@
+//#region src/node-relay.d.ts
+interface NodeInspectionRelayOptions {
+  host?: string;
+  port?: number;
+  logger?: Pick<Console, 'info'>;
+}
+/** Local/self-hosted Node adapter for the room inspection relay. */
+declare class NodeInspectionRelayServer {
+  private readonly options;
+  private server;
+  private webSocketServer;
+  private readonly rooms;
+  private readonly connections;
+  private readonly sockets;
+  constructor(options?: NodeInspectionRelayOptions);
+  get url(): string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+declare function createNodeInspectionRelay(options?: NodeInspectionRelayOptions): NodeInspectionRelayServer;
+//#endregion
+export { NodeInspectionRelayOptions, NodeInspectionRelayServer, createNodeInspectionRelay };

package/dist/node-relay.mjs

@@ -0,0 +1,84 @@
+import { getInspectionRoomId } from "./protocol.mjs";
+import { createInspectionRelay } from "./relay.mjs";
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { WebSocket, WebSocketServer } from "ws";
+
+//#region src/node-relay.ts
+/** Local/self-hosted Node adapter for the room inspection relay. */
+var NodeInspectionRelayServer = class {
+	server = null;
+	webSocketServer = null;
+	rooms = /* @__PURE__ */ new Map();
+	connections = /* @__PURE__ */ new Map();
+	sockets = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.options = options;
+	}
+	get url() {
+		if (!this.server) throw new Error("Inspection relay is not running.");
+		const address = this.server.address();
+		if (!address || typeof address === "string") throw new Error("Inspection relay address is unavailable.");
+		return `ws://${this.options.host ?? "127.0.0.1"}:${address.port}`;
+	}
+	async start() {
+		if (this.server) return;
+		this.server = createServer();
+		this.webSocketServer = new WebSocketServer({ server: this.server });
+		this.webSocketServer.on("connection", (socket, request) => {
+			const roomId = getInspectionRoomId(new URL(request.url ?? "/", this.url));
+			if (!roomId) {
+				socket.close(1008, "Missing ?r=<roomId>");
+				return;
+			}
+			const relay = this.rooms.get(roomId) ?? createInspectionRelay();
+			this.rooms.set(roomId, relay);
+			const peerId = randomUUID();
+			this.connections.set(socket, {
+				peerId,
+				relay
+			});
+			this.sockets.set(peerId, socket);
+			socket.on("message", (raw) => {
+				for (const effect of relay.receive(peerId, raw.toString())) {
+					const target = this.sockets.get(effect.peerId);
+					if (target?.readyState === WebSocket.OPEN) target.send(JSON.stringify(effect.message));
+				}
+			});
+			socket.on("close", () => {
+				relay.disconnect(peerId);
+				this.connections.delete(socket);
+				this.sockets.delete(peerId);
+			});
+		});
+		await new Promise((resolve, reject) => {
+			this.server.once("error", reject);
+			this.server.listen(this.options.port ?? 4242, this.options.host ?? "127.0.0.1", () => {
+				this.server.off("error", reject);
+				resolve();
+			});
+		});
+		this.options.logger?.info(`Inspection relay listening on ${this.url}`);
+	}
+	async stop() {
+		for (const socket of this.connections.keys()) socket.close();
+		this.connections.clear();
+		this.sockets.clear();
+		for (const relay of this.rooms.values()) relay.clear();
+		this.rooms.clear();
+		if (this.webSocketServer) {
+			await new Promise((resolve) => this.webSocketServer.close(() => resolve()));
+			this.webSocketServer = null;
+		}
+		if (this.server) {
+			await new Promise((resolve, reject) => this.server.close((error) => error ? reject(error) : resolve()));
+			this.server = null;
+		}
+	}
+};
+function createNodeInspectionRelay(options) {
+	return new NodeInspectionRelayServer(options);
+}
+
+//#endregion
+export { NodeInspectionRelayServer, createNodeInspectionRelay };