conduit-mcp 2.1.7 → 2.1.9

package/dist/{chunk-TUOCT4PR.js → chunk-2OAUC6UN.js}

@@ -40,11 +40,12 @@ var log = {
 // src/bridge.ts
 var REQUEST_TIMEOUT_MS = 6e4;
 var HEARTBEAT_CHECK_INTERVAL_MS = 5e3;
-var HEARTBEAT_TIMEOUT_MS = 15e3;
+var HEARTBEAT_TIMEOUT_MS = 2e4;
 var PING_INTERVAL_MS = 1e4;
 var LONG_POLL_TIMEOUT_MS = 25e3;
 var MAX_PORT_RETRIES = 10;
 var REGISTRATION_TIMEOUT_MS = 1e4;
+var FIRST_CONNECT_WAIT_MS = 3e3;
 var Bridge = class extends EventEmitter {
   constructor(port = 3200) {
     super();
@@ -212,18 +213,26 @@ var Bridge = class extends EventEmitter {
     const id = generateId();
     const request = { id, method, params };
     const json = JSON.stringify(request);
+    if (this.studios.size === 0 && this.httpStudios.size === 0) {
+      await this.waitForFirstStudio(FIRST_CONNECT_WAIT_MS);
+      if (this.studios.size === 0 && this.httpStudios.size === 0) {
+        throw this.buildPluginNotConnectedError(method);
+      }
+    }
     const studio = this.resolveTargetStudio();
+    const targetStudioId = this.activeStudioId;
     const effectiveTimeout = timeoutMs ?? REQUEST_TIMEOUT_MS;
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pendingRequests.delete(id);
-        reject(
-          new Error(
-            `Request ${method} timed out after ${effectiveTimeout}ms \u2014 is the Conduit plugin running in Roblox Studio?`
-          )
-        );
+        reject(this.buildTimeoutError(method, effectiveTimeout, targetStudioId));
       }, effectiveTimeout);
-      this.pendingRequests.set(id, { resolve, reject, timer });
+      this.pendingRequests.set(id, {
+        resolve,
+        reject,
+        timer,
+        studioId: targetStudioId
+      });
       if (studio) {
         studio.ws.send(json, (err) => {
           if (err) {
@@ -249,6 +258,73 @@ var Bridge = class extends EventEmitter {
       }
     });
   }
+  // Wait for any studio to register, up to timeoutMs. Resolves immediately if
+  // one is already connected. Used to absorb the startup race between MCP
+  // initialize (instant) and the plugin's WebSocket handshake (~hundreds of ms).
+  waitForFirstStudio(timeoutMs) {
+    if (this.studios.size > 0 || this.httpStudios.size > 0) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.off("studio-connected", onConnect);
+        resolve();
+      }, timeoutMs);
+      const onConnect = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      this.once("studio-connected", onConnect);
+    });
+  }
+  buildPluginNotConnectedError(method) {
+    const err = new Error(
+      `Cannot ${method}: the Roblox Studio plugin is not connected. Open Roblox Studio with the Conduit plugin enabled \u2014 it auto-connects when HttpService is allowed (Game Settings \u2192 Security \u2192 Allow HTTP Requests). Check the Conduit dashboard in Studio for connection status.`
+    );
+    err.code = "PLUGIN_NOT_CONNECTED";
+    return err;
+  }
+  /**
+   * Classify why a request timed out. Without this, three very different failure modes
+   * ("plugin isn't running", "socket is dead", "plugin got the request but its handler
+   * is stuck") all surface as the same generic "timed out" error, so callers can't
+   * decide whether to retry, reconnect, or surface the hang to the user.
+   *
+   * We inspect studio state *at timeout fire time* (not request send time) because
+   * the socket may have died mid-flight.
+   */
+  buildTimeoutError(method, timeoutMs, targetStudioId) {
+    const base = `Request ${method} timed out after ${timeoutMs}ms`;
+    if (!targetStudioId) {
+      const err2 = new Error(
+        `${base}: no Roblox Studio plugin was connected when the request was dispatched.`
+      );
+      err2.code = "PLUGIN_NOT_CONNECTED";
+      return err2;
+    }
+    const studio = this.studios.get(targetStudioId);
+    if (!studio || studio.ws.readyState !== WebSocket.OPEN) {
+      const err2 = new Error(
+        `${base}: the plugin WebSocket for studio "${targetStudioId}" closed before a response arrived.`
+      );
+      err2.code = "PLUGIN_DISCONNECTED";
+      return err2;
+    }
+    const lastBeat = this.lastHeartbeats.get(targetStudioId);
+    const age = lastBeat !== void 0 ? Date.now() - lastBeat : Infinity;
+    if (age > HEARTBEAT_TIMEOUT_MS) {
+      const err2 = new Error(
+        `${base}: the plugin stopped sending heartbeats (${Math.round(age / 1e3)}s ago) \u2014 Studio may be frozen.`
+      );
+      err2.code = "PLUGIN_UNRESPONSIVE";
+      return err2;
+    }
+    const err = new Error(
+      `${base}: the plugin is still responsive but the "${method}" handler did not return in time. This usually means user Lua is running long or the mutation queue is stalled on a prior command.`
+    );
+    err.code = "HANDLER_TIMEOUT";
+    return err;
+  }
   // ── Internal helpers ───────────────────────────────────────────
   getActiveStudio() {
     if (this.activeStudioId) {
@@ -274,6 +350,11 @@ var Bridge = class extends EventEmitter {
       studio.ws.terminate();
       this.studios.delete(studioId);
       this.lastHeartbeats.delete(studioId);
+      this.failPendingForStudio(
+        studioId,
+        "PLUGIN_UNRESPONSIVE",
+        `the plugin connection went stale and was evicted before responding`
+      );
       this.emit("studio-disconnected", studio.info);
       log.info(`Evicted stale studio: ${studioId}`);
     }
@@ -415,6 +496,11 @@ var Bridge = class extends EventEmitter {
       if (current && current.ws === ws) {
         this.studios.delete(studioId);
         this.lastHeartbeats.delete(studioId);
+        this.failPendingForStudio(
+          studioId,
+          "PLUGIN_DISCONNECTED",
+          `the plugin WebSocket closed before a response arrived`
+        );
         this.emit("studio-disconnected", info);
         log.info(`Studio disconnected: ${studioId}`);
         if (this.activeStudioId === studioId) {
@@ -434,6 +520,19 @@ var Bridge = class extends EventEmitter {
       }
     });
   }
+  failPendingForStudio(studioId, code, reason) {
+    for (const [id, pending] of this.pendingRequests) {
+      if (pending.studioId === studioId) {
+        clearTimeout(pending.timer);
+        this.pendingRequests.delete(id);
+        const err = new Error(
+          `Request aborted: ${reason} (studio: ${studioId}). The plugin should auto-reconnect \u2014 please retry.`
+        );
+        err.code = code;
+        pending.reject(err);
+      }
+    }
+  }
   handlePluginMessage(msg) {
     if (isBridgeError(msg)) {
       const pending = this.pendingRequests.get(msg.id);
@@ -475,6 +574,12 @@ var Bridge = class extends EventEmitter {
             const info = this.httpStudios.get(studioId);
             this.httpStudios.delete(studioId);
             this.lastHeartbeats.delete(studioId);
+            this.httpPendingCommands.delete(studioId);
+            this.failPendingForStudio(
+              studioId,
+              "PLUGIN_UNRESPONSIVE",
+              `the HTTP-fallback plugin stopped polling for ${Math.round(HEARTBEAT_TIMEOUT_MS / 1e3)}s`
+            );
             this.emit("studio-disconnected", info);
             if (this.activeStudioId === studioId) {
               const remaining = this.getStudios();
@@ -2601,4 +2706,4 @@ async function startServer(port = 3200, options = {}) {
 export {
   startServer
 };
-//# sourceMappingURL=chunk-TUOCT4PR.js.map
+//# sourceMappingURL=chunk-2OAUC6UN.js.map