@reactor-team/js-sdk 2.2.1 → 2.3.1

package/dist/index.d.mts

@@ -3,6 +3,12 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode } from 'react';
 
 type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
+/**
+ * The message scope identifies the envelope layer a data channel message belongs to.
+ * - "application": model-defined commands (client->runtime) and model-emitted payloads (runtime->client).
+ * - "runtime": platform-level control messages (e.g., capabilities exchange).
+ */
+type MessageScope = "application" | "runtime";
 interface ReactorError {
     code: string;
     message: string;
@@ -45,11 +51,14 @@ declare class Reactor {
     emit(event: ReactorEvent, ...args: any[]): void;
     /**
      * Public method to send a message to the machine.
-     * Automatically wraps the message in an application message.
-     * @param message The message to send to the machine.
+     * Wraps the message in the specified channel envelope (defaults to "application").
+     * @param command The command name to send.
+     * @param data The command payload.
+     * @param scope The envelope scope – "application" (default) for model commands,
+     *              "runtime" for platform-level messages (e.g. requestCapabilities).
      * @throws Error if not in ready state
      */
-    sendCommand(command: string, data: any): Promise<void>;
+    sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
     /**
      * Public method to publish a track to the machine.
      * @param track The track to send to the machine.
@@ -111,7 +120,7 @@ interface ReactorState {
     jwtToken?: string;
 }
 interface ReactorActions {
-    sendCommand(command: string, data: any): Promise<void>;
+    sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
     connect(jwtToken?: string): Promise<void>;
     disconnect(recoverable?: boolean): Promise<void>;
     publishVideoStream(stream: MediaStream): Promise<void>;
@@ -170,9 +179,13 @@ declare function useReactor<T>(selector: (state: ReactorStore) => T): T;
 /**
  * Hook for handling message subscriptions with proper React lifecycle management.
  *
- * @param handler - The message handler function
+ * The handler receives the message payload and the scope it arrived on:
+ *   - "application" for model-defined messages (via get_ctx().send())
+ *   - "runtime" for platform-level messages (e.g., capabilities response)
+ *
+ * @param handler - The message handler function (message, scope)
  */
-declare function useReactorMessage(handler: (message: any) => void): void;
+declare function useReactorMessage(handler: (message: any, scope: MessageScope) => void): void;
 
 /**
  * ⚠️ INSECURE: Fetches a JWT token directly from the client.
@@ -187,4 +200,4 @@ declare function useReactorMessage(handler: (message: any) => void): void;
  */
 declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
 
-export { ConflictError, type Options, PROD_COORDINATOR_URL, Reactor, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, ReactorView, type ReactorViewProps, WebcamStream, fetchInsecureJwtToken, useReactor, useReactorMessage, useReactorStore };
+export { ConflictError, type MessageScope, type Options, PROD_COORDINATOR_URL, Reactor, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, ReactorView, type ReactorViewProps, WebcamStream, fetchInsecureJwtToken, useReactor, useReactorMessage, useReactorStore };

package/dist/index.d.ts

@@ -3,6 +3,12 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode } from 'react';
 
 type ReactorStatus = "disconnected" | "connecting" | "waiting" | "ready";
+/**
+ * The message scope identifies the envelope layer a data channel message belongs to.
+ * - "application": model-defined commands (client->runtime) and model-emitted payloads (runtime->client).
+ * - "runtime": platform-level control messages (e.g., capabilities exchange).
+ */
+type MessageScope = "application" | "runtime";
 interface ReactorError {
     code: string;
     message: string;
@@ -45,11 +51,14 @@ declare class Reactor {
     emit(event: ReactorEvent, ...args: any[]): void;
     /**
      * Public method to send a message to the machine.
-     * Automatically wraps the message in an application message.
-     * @param message The message to send to the machine.
+     * Wraps the message in the specified channel envelope (defaults to "application").
+     * @param command The command name to send.
+     * @param data The command payload.
+     * @param scope The envelope scope – "application" (default) for model commands,
+     *              "runtime" for platform-level messages (e.g. requestCapabilities).
      * @throws Error if not in ready state
      */
-    sendCommand(command: string, data: any): Promise<void>;
+    sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
     /**
      * Public method to publish a track to the machine.
      * @param track The track to send to the machine.
@@ -111,7 +120,7 @@ interface ReactorState {
     jwtToken?: string;
 }
 interface ReactorActions {
-    sendCommand(command: string, data: any): Promise<void>;
+    sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
     connect(jwtToken?: string): Promise<void>;
     disconnect(recoverable?: boolean): Promise<void>;
     publishVideoStream(stream: MediaStream): Promise<void>;
@@ -170,9 +179,13 @@ declare function useReactor<T>(selector: (state: ReactorStore) => T): T;
 /**
  * Hook for handling message subscriptions with proper React lifecycle management.
  *
- * @param handler - The message handler function
+ * The handler receives the message payload and the scope it arrived on:
+ *   - "application" for model-defined messages (via get_ctx().send())
+ *   - "runtime" for platform-level messages (e.g., capabilities response)
+ *
+ * @param handler - The message handler function (message, scope)
  */
-declare function useReactorMessage(handler: (message: any) => void): void;
+declare function useReactorMessage(handler: (message: any, scope: MessageScope) => void): void;
 
 /**
  * ⚠️ INSECURE: Fetches a JWT token directly from the client.
@@ -187,4 +200,4 @@ declare function useReactorMessage(handler: (message: any) => void): void;
  */
 declare function fetchInsecureJwtToken(apiKey: string, coordinatorUrl?: string): Promise<string>;
 
-export { ConflictError, type Options, PROD_COORDINATOR_URL, Reactor, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, ReactorView, type ReactorViewProps, WebcamStream, fetchInsecureJwtToken, useReactor, useReactorMessage, useReactorStore };
+export { ConflictError, type MessageScope, type Options, PROD_COORDINATOR_URL, Reactor, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, ReactorView, type ReactorViewProps, WebcamStream, fetchInsecureJwtToken, useReactor, useReactorMessage, useReactorStore };

package/dist/index.js

@@ -227,12 +227,13 @@ function waitForIceGathering(pc, timeoutMs = 5e3) {
     }, timeoutMs);
   });
 }
-function sendMessage(channel, command, data) {
+function sendMessage(channel, command, data, scope = "application") {
   if (channel.readyState !== "open") {
     throw new Error(`Data channel not open: ${channel.readyState}`);
   }
   const jsonData = typeof data === "string" ? JSON.parse(data) : data;
-  const payload = { type: command, data: jsonData };
+  const inner = { type: command, data: jsonData };
+  const payload = { scope, data: inner };
   channel.send(JSON.stringify(payload));
 }
 function parseMessage(data) {
@@ -614,6 +615,7 @@ var LocalCoordinatorClient = class extends CoordinatorClient {
 };
 
 // src/core/GPUMachineClient.ts
+var PING_INTERVAL_MS = 5e3;
 var GPUMachineClient = class {
   constructor(config) {
     this.eventListeners = /* @__PURE__ */ new Map();
@@ -696,6 +698,7 @@ var GPUMachineClient = class {
    */
   disconnect() {
     return __async(this, null, function* () {
+      this.stopPing();
       if (this.publishedTrack) {
         yield this.unpublishTrack();
       }
@@ -736,13 +739,14 @@ var GPUMachineClient = class {
    * Sends a command to the GPU machine via the data channel.
    * @param command The command to send
    * @param data The data to send with the command. These are the parameters for the command, matching the scheme in the capabilities dictionary.
+   * @param scope The message scope – "application" (default) for model commands, "runtime" for platform-level messages.
    */
-  sendCommand(command, data) {
+  sendCommand(command, data, scope = "application") {
     if (!this.dataChannel) {
       throw new Error("[GPUMachineClient] Data channel not available");
     }
     try {
-      sendMessage(this.dataChannel, command, data);
+      sendMessage(this.dataChannel, command, data, scope);
     } catch (error) {
       console.warn("[GPUMachineClient] Failed to send message:", error);
     }
@@ -823,6 +827,34 @@ var GPUMachineClient = class {
     return new MediaStream(tracks);
   }
   // ─────────────────────────────────────────────────────────────────────────────
+  // Ping (Client Liveness)
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Starts sending periodic "ping" messages on the runtime channel so the
+   * server can detect stale connections quickly.
+   */
+  startPing() {
+    this.stopPing();
+    this.pingInterval = setInterval(() => {
+      var _a;
+      if (((_a = this.dataChannel) == null ? void 0 : _a.readyState) === "open") {
+        try {
+          sendMessage(this.dataChannel, "ping", {}, "runtime");
+        } catch (e) {
+        }
+      }
+    }, PING_INTERVAL_MS);
+  }
+  /**
+   * Stops the periodic ping.
+   */
+  stopPing() {
+    if (this.pingInterval !== void 0) {
+      clearInterval(this.pingInterval);
+      this.pingInterval = void 0;
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
   // Private Helpers
   // ─────────────────────────────────────────────────────────────────────────────
   setStatus(newStatus) {
@@ -876,18 +908,29 @@ var GPUMachineClient = class {
     if (!this.dataChannel) return;
     this.dataChannel.onopen = () => {
       console.debug("[GPUMachineClient] Data channel open");
+      this.startPing();
     };
     this.dataChannel.onclose = () => {
       console.debug("[GPUMachineClient] Data channel closed");
+      this.stopPing();
     };
     this.dataChannel.onerror = (error) => {
       console.error("[GPUMachineClient] Data channel error:", error);
     };
     this.dataChannel.onmessage = (event) => {
-      const data = parseMessage(event.data);
-      console.debug("[GPUMachineClient] Received message:", data);
+      const rawData = parseMessage(event.data);
+      console.debug("[GPUMachineClient] Received message:", rawData);
       try {
-        this.emit("application", data);
+        if ((rawData == null ? void 0 : rawData.scope) === "application" && (rawData == null ? void 0 : rawData.data) !== void 0) {
+          this.emit("message", rawData.data, "application");
+        } else if ((rawData == null ? void 0 : rawData.scope) === "runtime" && (rawData == null ? void 0 : rawData.data) !== void 0) {
+          this.emit("message", rawData.data, "runtime");
+        } else {
+          console.warn(
+            "[GPUMachineClient] Received message without envelope, treating as application"
+          );
+          this.emit("message", rawData, "application");
+        }
       } catch (error) {
         console.error(
           "[GPUMachineClient] Failed to parse/validate message:",
@@ -937,11 +980,14 @@ var Reactor = class {
   }
   /**
    * Public method to send a message to the machine.
-   * Automatically wraps the message in an application message.
-   * @param message The message to send to the machine.
+   * Wraps the message in the specified channel envelope (defaults to "application").
+   * @param command The command name to send.
+   * @param data The command payload.
+   * @param scope The envelope scope – "application" (default) for model commands,
+   *              "runtime" for platform-level messages (e.g. requestCapabilities).
    * @throws Error if not in ready state
    */
-  sendCommand(command, data) {
+  sendCommand(command, data, scope = "application") {
     return __async(this, null, function* () {
       var _a;
       if (process.env.NODE_ENV !== "development" && this.status !== "ready") {
@@ -950,7 +996,7 @@ var Reactor = class {
         return;
       }
       try {
-        (_a = this.machineClient) == null ? void 0 : _a.sendCommand(command, data);
+        (_a = this.machineClient) == null ? void 0 : _a.sendCommand(command, data, scope);
       } catch (error) {
         console.error("[Reactor] Failed to send message:", error);
         this.createError(
@@ -1100,10 +1146,8 @@ var Reactor = class {
    */
   setupMachineClientHandlers() {
     if (!this.machineClient) return;
-    this.machineClient.on("application", (message) => {
-      if ((message == null ? void 0 : message.type) === "application" && (message == null ? void 0 : message.data) !== void 0) {
-        this.emit("newMessage", message.data);
-      }
+    this.machineClient.on("message", (message, scope) => {
+      this.emit("newMessage", message, scope);
     });
     this.machineClient.on("statusChanged", (status) => {
       switch (status) {
@@ -1310,10 +1354,14 @@ var createReactorStore = (initProps, publicState = defaultInitState) => {
           get().internal.reactor.off("newMessage", handler);
         };
       },
-      sendCommand: (command, data) => __async(null, null, function* () {
-        console.debug("[ReactorStore] Sending command", { command, data });
+      sendCommand: (command, data, scope) => __async(null, null, function* () {
+        console.debug("[ReactorStore] Sending command", {
+          command,
+          data,
+          scope
+        });
         try {
-          yield get().internal.reactor.sendCommand(command, data);
+          yield get().internal.reactor.sendCommand(command, data, scope);
           console.debug("[ReactorStore] Command sent successfully");
         } catch (error) {
           console.error("[ReactorStore] Failed to send command:", error);
@@ -1516,9 +1564,12 @@ function useReactorMessage(handler) {
   }, [handler]);
   (0, import_react4.useEffect)(() => {
     console.debug("[useReactorMessage] Setting up message subscription");
-    const stableHandler = (message) => {
-      console.debug("[useReactorMessage] Message received", { message });
-      handlerRef.current(message);
+    const stableHandler = (message, scope) => {
+      console.debug("[useReactorMessage] Message received", {
+        message,
+        scope
+      });
+      handlerRef.current(message, scope);
     };
     reactor.on("newMessage", stableHandler);
     console.debug("[useReactorMessage] Message handler registered");
@@ -1647,7 +1698,7 @@ function ReactorController({
   }, [status]);
   const requestCapabilities = (0, import_react6.useCallback)(() => {
     if (status === "ready") {
-      sendCommand("requestCapabilities", {});
+      sendCommand("requestCapabilities", {}, "runtime");
     }
   }, [status, sendCommand]);
   import_react6.default.useEffect(() => {
@@ -1664,9 +1715,9 @@ function ReactorController({
     }, 5e3);
     return () => clearInterval(interval);
   }, [status, commands, requestCapabilities]);
-  useReactorMessage((message) => {
-    if (message && typeof message === "object" && "commands" in message) {
-      const commandsMessage = message;
+  useReactorMessage((message, scope) => {
+    if (scope === "runtime" && message && typeof message === "object" && message.type === "modelCapabilities" && message.data && "commands" in message.data) {
+      const commandsMessage = message.data;
       setCommands(commandsMessage.commands);
       const initialValues = {};
       const initialExpanded = {};