@chrrxs/robloxstudio-mcp 3.2.0 → 3.2.1

package/dist/index.js

@@ -3296,7 +3296,7 @@ Tool descriptions explain selection. Input schemas explain arguments. This guide
 ## Connection and paths
 
 - Use canonical DataModel paths returned by the tools. Paths usually start with game.
-- Call get_connected_instances when more than one Studio process may be connected. Pass either a top-level Instance ID or a multiplayer group's role-suffixed Instance ID as instance_id on later calls.
+- Call get_connected_instances when more than one Studio process may be connected. Pass either a top-level Instance ID or a multiplayer group's role-suffixed Instance ID as instance_id on later calls. A role-suffixed ID selects that server or client as the default target; a conflicting single-peer target is rejected.
 - Use get_place_info for the active place identity and settings.
 
 ## Discovery and edit work
@@ -3879,6 +3879,9 @@ var ManagedInstanceRegistry = class {
       if (!options.observeProcess || !(parsed.nativeProcessId || parsed.spawnPid))
         continue;
       const observation = await options.observeProcess(parsed);
+      const previousObservationAt = parsed.lastProcessObservationAt;
+      if (previousObservationAt !== void 0 && observation.observedAt < previousObservationAt)
+        continue;
       if (observation.status === "unknown") {
         parsed.processObservationStatus = "unknown";
         parsed.lastProcessObservationAt = observation.observedAt;
@@ -3888,7 +3891,6 @@ var ManagedInstanceRegistry = class {
         await this.writeRecordUnlocked(parsed);
         continue;
       }
-      const previousObservationAt = parsed.lastProcessObservationAt;
       parsed.lastSuccessfulProcessObservationAt = observation.observedAt;
       parsed.lastProcessObservationAt = observation.observedAt;
       parsed.lastProcessObservationError = void 0;
@@ -5507,10 +5509,10 @@ var WINDOWS_STUDIO_PROCESS_QUERY = [
 function parseWindowsStudioProcesses(output) {
   const parsed = JSON.parse(output);
   const processes = Array.isArray(parsed) ? parsed : [parsed];
-  if (!processes.every((value) => value !== null && typeof value === "object" && "Id" in value && typeof value.Id === "number" && Number.isSafeInteger(value.Id) && value.Id > 0 && "Name" in value && typeof value.Name === "string" && "Path" in value && typeof value.Path === "string" && "MainWindowTitle" in value && typeof value.MainWindowTitle === "string" && "StartTimeUtcFileTime" in value && typeof value.StartTimeUtcFileTime === "string" && /^[1-9]\d*$/u.test(value.StartTimeUtcFileTime))) {
+  if (!processes.every((value) => value !== null && typeof value === "object" && "Id" in value && typeof value.Id === "number" && Number.isSafeInteger(value.Id) && value.Id > 0 && "Name" in value && typeof value.Name === "string" && "Path" in value && (typeof value.Path === "string" || value.Path === null) && "MainWindowTitle" in value && typeof value.MainWindowTitle === "string" && "StartTimeUtcFileTime" in value && typeof value.StartTimeUtcFileTime === "string" && /^[1-9]\d*$/u.test(value.StartTimeUtcFileTime))) {
     throw new Error("Malformed Roblox Studio process enumeration result.");
   }
-  return processes;
+  return processes.map(({ Path, ...processInfo }) => Path === null ? processInfo : { ...processInfo, Path });
 }
 async function observeStudioProcesses(timeoutMs = 15e3) {
   const observedAt = Date.now();
@@ -6521,6 +6523,8 @@ var StudioInstanceManager = class {
     if (record.closedAt !== void 0)
       return;
     const previousObservationAt = record.lastProcessObservationAt;
+    if (previousObservationAt !== void 0 && observation.observedAt < previousObservationAt)
+      return;
     record.lastProcessObservationAt = observation.observedAt;
     if (observation.status === "unknown") {
       record.processObservationStatus = "unknown";
@@ -6854,7 +6858,7 @@ function serverInstructions(definitions) {
   const has = (...toolNames) => toolNames.every((name) => names.has(name));
   const instructions = ["Use canonical DataModel paths returned by tools."];
   if (has("get_connected_instances")) {
-    instructions.push("When more than one Studio process scope is connected, call get_connected_instances and pass either a top-level instance id or a multiplayer group's role-suffixed instance id as instance_id.");
+    instructions.push("When more than one Studio process scope is connected, call get_connected_instances and pass either a top-level instance id or a multiplayer group's role-suffixed instance id as instance_id. A role-suffixed id selects that server or client as the default target; a conflicting single-peer target is rejected.");
   }
   if (has("get_request_status", "execute_luau", "set_properties")) {
     instructions.push("Supply a unique operation_id to execute_luau or set_properties when retry safety matters. After a timeout, query get_request_status with that ID before retrying. Identical arguments reuse a retained outcome; changed arguments are rejected. Recovery and deduplication are bounded to the current server session and five-minute retention window; result payloads may be evicted earlier. Unknown status does not mean unexecuted, and cancellation cannot roll back mutations.", "Request stages are queued, dispatched, executing (plugin handler entered), and response_delivery (handler returned or admission rejected). executionOutcome is separate from waiter state and delivery outcome; handler observations do not prove user Luau instructions ran. A waiter timeout is not an execution deadline or rollback. Neither missing progress nor connection loss proves completion.");
@@ -6995,6 +6999,7 @@ var HTTP_BODY_LIMIT_BYTES = 50 * 1024 * 1024;
 
 // ../core/dist/studio-transport.js
 var HEARTBEAT_INTERVAL_MS = 1e4;
+var PONG_TIMEOUT_MS = 3e4;
 var MAX_PENDING_ACKS = 128;
 var STUDIO_PROTOCOL_VERSION = 1;
 var MAX_ACTIVE_STUDIO_SOCKETS = 64;
@@ -7042,13 +7047,20 @@ var WebSocketStudioTransport = class {
       settling: false,
       statusPending: true,
       heartbeatPending: false,
+      lastSeenAt: Date.now(),
       acknowledgements: /* @__PURE__ */ new Map(),
       onClose: () => {
         this.closeSocket(connection);
         this.finishClose(connection);
       },
       onError: () => this.closeSocket(connection, 1011, "socket_error"),
-      onMessage: (data, isBinary) => this.receive(connection, data, isBinary)
+      onMessage: (data, isBinary) => this.receive(connection, data, isBinary),
+      onPong: () => {
+        if (!this.isCurrent(connection))
+          return;
+        connection.lastSeenAt = Date.now();
+        this.queue.updatePeerActivity(transportPeerId);
+      }
     };
     this.queue.setDeliveryActive(transportPeerId, claimOwner, true);
     const replaced = this.sockets.get(transportPeerId);
@@ -7059,10 +7071,20 @@ var WebSocketStudioTransport = class {
     socket.on("close", connection.onClose);
     socket.on("error", connection.onError);
     socket.on("message", connection.onMessage);
+    socket.on("pong", connection.onPong);
     connection.heartbeatTimer = setInterval(() => {
       if (!this.isCurrent(connection))
         return;
-      this.queue.updatePeerActivity(transportPeerId);
+      if (Date.now() - connection.lastSeenAt >= PONG_TIMEOUT_MS) {
+        this.closeSocket(connection, 1001, "pong_timeout");
+        return;
+      }
+      try {
+        connection.socket.ping();
+      } catch {
+        this.closeSocket(connection, 1011, "ping_failed");
+        return;
+      }
       connection.statusPending = true;
       connection.heartbeatPending = true;
       this.pump(connection);
@@ -7120,6 +7142,11 @@ var WebSocketStudioTransport = class {
       this.closeSocket(connection, 1007, "invalid_json");
       return;
     }
+    if (message !== null && typeof message === "object" && !Array.isArray(message) && "kind" in message && message.kind === "disconnect") {
+      this.queue.unregisterPeer(connection.transportPeerId);
+      this.closeSocket(connection, 1e3, "peer_unregistered");
+      return;
+    }
     if (message === null || typeof message !== "object" || Array.isArray(message) || !("kind" in message) || message.kind !== "response" && message.kind !== "progress" || !("requestId" in message) || typeof message.requestId !== "string" || message.requestId.length === 0 || message.requestId.length > 1024) {
       this.closeSocket(connection, 1008, "invalid_response");
       return;
@@ -7260,6 +7287,7 @@ var WebSocketStudioTransport = class {
     connection.closed = true;
     clearInterval(connection.heartbeatTimer);
     connection.socket.removeListener("message", connection.onMessage);
+    connection.socket.removeListener("pong", connection.onPong);
     connection.acknowledgements.clear();
     if (this.sockets.get(connection.transportPeerId) === connection)
       this.sockets.delete(connection.transportPeerId);
@@ -7822,9 +7850,9 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig, security) {
       });
       return;
     }
-    const isClientRole = role === "client" || /^client-[1-9]\d*$/.test(role);
+    const isClientRole2 = role === "client" || /^client-[1-9]\d*$/.test(role);
     const isProxiedPeer = transportPeerId !== peerId;
-    if (isProxiedPeer && !isClientRole || !isProxiedPeer && isClientRole || !isClientRole && role !== "edit" && role !== "server") {
+    if (isProxiedPeer && !isClientRole2 || !isProxiedPeer && isClientRole2 || !isClientRole2 && role !== "edit" && role !== "server") {
       res.status(400).json({
         success: false,
         error: "invalid_peer_topology",
@@ -12884,6 +12912,10 @@ end
 error("Unsupported device simulator operation: " .. tostring(opts.operation), 0)
 `.trim();
 }
+var isClientRole = (role) => /^client-\d+$/.test(role);
+var isRuntimeRole2 = (role) => role === "server" || isClientRole(role);
+var anyRole = () => true;
+var SCOPE_WIDE_TARGETS = /* @__PURE__ */ new Set(["all", "all-clients", "edit-and-clients"]);
 var RobloxStudioTools = class {
   client;
   bridge;
@@ -13027,7 +13059,8 @@ var RobloxStudioTools = class {
     const refresh = this.bridge.refreshTopologyForRouting(signal);
     if (refresh)
       await refresh;
-    const resolved = this.bridge.resolveTarget({ instance_id, target });
+    const role = typeof target === "object" ? this._targetForInstanceId(instance_id, target) : target;
+    const resolved = this.bridge.resolveTarget({ instance_id, target: role });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
     if (resolved.mode !== "single") {
@@ -13039,26 +13072,66 @@ var RobloxStudioTools = class {
     }
     return this._requestPeer(endpoint, data, resolved.targetPeerId, timeoutMs, signal, operationId);
   }
+  // A grouped runtime process ID, or its role-suffixed Instance ID, names exactly
+  // one Peer. Solo playtest Peers share one Instance ID, so it names none of them.
+  _peerSelectedByInstanceId(instance_id) {
+    if (instance_id === void 0)
+      return void 0;
+    const selected = this.bridge.getPeersInScope(instance_id).filter((peer) => isRuntimeRole2(peer.role) && (instance_id === peer.instanceId || instance_id === `${peer.instanceId}-${peer.role}`));
+    return selected.length === 1 ? selected[0] : void 0;
+  }
+  // Apply a Peer-naming instance_id to a tool's target after topology refresh: it
+  // replaces the tool default, and a different single-Peer target is rejected
+  // instead of silently acting on another Peer.
+  _targetForInstanceId(instance_id, choice) {
+    const requested = choice.requested || void 0;
+    const selected = this._peerSelectedByInstanceId(instance_id);
+    if (!selected || !choice.accepts(selected.role))
+      return requested ?? choice.fallback;
+    if (requested === void 0)
+      return selected.role;
+    if (requested !== selected.role && !SCOPE_WIDE_TARGETS.has(requested)) {
+      throw new RoutingFailure({
+        code: "ambiguous_target",
+        message: `instance_id "${instance_id}" selects ${selected.role}, but target=${requested}. Omit target, pass target=${selected.role}, or pass the controller Instance ID with target=${requested}.`,
+        data: this._routingErrorData()
+      });
+    }
+    return requested;
+  }
   // Honor an explicitly selected client for viewport/input operations; otherwise
   // prefer the first client in the scope, then retain the default Peer's Instance.
   _resolveRuntime(instance_id) {
     const resolved = this.bridge.resolveTarget({ instance_id, target: void 0 });
-    if (!resolved.ok)
+    let scopePeers;
+    let defaultInstanceId;
+    if (resolved.ok) {
+      if (resolved.mode !== "single") {
+        throw new RoutingFailure({
+          code: "target_role_not_present_on_instance",
+          message: "A single runtime target is required.",
+          data: this._routingErrorData()
+        });
+      }
+      scopePeers = this.bridge.getPeersInScope(resolved.targetInstanceId);
+      defaultInstanceId = resolved.targetInstanceId;
+    } else if (resolved.error.code === "target_role_required") {
+      scopePeers = instance_id !== void 0 ? this.bridge.getPeersInScope(instance_id) : this.bridge.getPeers();
+    } else {
       throw new RoutingFailure(resolved.error);
-    if (resolved.mode !== "single") {
+    }
+    const named = this._peerSelectedByInstanceId(instance_id);
+    const client = (named && isClientRole(named.role) ? named : void 0) ?? scopePeers.filter((peer) => isClientRole(peer.role)).sort((a, b) => a.role.localeCompare(b.role) || a.peerId.localeCompare(b.peerId))[0];
+    if (client)
+      return { instanceId: client.instanceId, clientRole: client.role };
+    if (defaultInstanceId === void 0) {
       throw new RoutingFailure({
         code: "target_role_not_present_on_instance",
-        message: "A single runtime target is required.",
+        message: `No edit or client viewport is connected in this scope. Connected roles: ${scopePeers.map((peer) => peer.role).join(", ")}.`,
         data: this._routingErrorData()
       });
     }
-    const clients = this.bridge.getPeersInScope(resolved.targetInstanceId).filter((peer) => /^client-\d+$/.test(peer.role));
-    const selectedClients = clients.filter((peer) => instance_id === peer.instanceId || instance_id === `${peer.instanceId}-${peer.role}`);
-    const client = selectedClients.length === 1 ? selectedClients[0] : clients.sort((a, b) => a.role.localeCompare(b.role) || a.peerId.localeCompare(b.peerId))[0];
-    return {
-      instanceId: client?.instanceId ?? resolved.targetInstanceId,
-      clientRole: client?.role
-    };
+    return { instanceId: defaultInstanceId };
   }
   // Resolve synchronously after the caller has refreshed and captured its topology.
   _resolveInstanceIdOnly(instance_id) {
@@ -13126,7 +13199,7 @@ var RobloxStudioTools = class {
     return compact;
   }
   _resolveDeviceSimulatorSingleTarget(target, instance_id, toolName) {
-    const selectedTarget = target ?? "edit";
+    const selectedTarget = this._targetForInstanceId(instance_id, { requested: target, fallback: "edit", accepts: isClientRole });
     if (selectedTarget === "server" || selectedTarget === "all" || selectedTarget === "all-clients") {
       throw new Error(`${toolName} target must be "edit" or "client-N" (got: ${selectedTarget})`);
     }
@@ -13137,7 +13210,7 @@ var RobloxStudioTools = class {
     return { ...resolved, selectedTarget };
   }
   _resolveDeviceSimulatorSetTargets(target, instance_id) {
-    const selectedTarget = target ?? "edit";
+    const selectedTarget = this._targetForInstanceId(instance_id, { requested: target, fallback: "edit", accepts: isClientRole });
     if (selectedTarget === "all-clients") {
       const instanceId = this._resolveInstanceIdOnly(instance_id);
       const roles = this._clientRolesForScope(instanceId);
@@ -13161,7 +13234,7 @@ var RobloxStudioTools = class {
     return selectedInclude;
   }
   _resolveSimulationTargets(target, instance_id, toolName) {
-    const selectedTarget = target ?? "edit-and-clients";
+    const selectedTarget = this._targetForInstanceId(instance_id, { requested: target, fallback: "edit-and-clients", accepts: isClientRole });
     if (selectedTarget === "server" || selectedTarget === "all") {
       throw new Error(`${toolName} target must be "edit", "client-N", "all-clients", or "edit-and-clients" (got: ${selectedTarget})`);
     }
@@ -13668,7 +13741,7 @@ var RobloxStudioTools = class {
     if (!code) {
       throw new Error("Code is required for execute_luau");
     }
-    const response = await this._callSingle("/api/execute-luau", { code }, target || "edit", instance_id, void 0, void 0, operation_id);
+    const response = await this._callSingle("/api/execute-luau", { code }, { requested: target, fallback: "edit", accepts: anyRole }, instance_id, void 0, void 0, operation_id);
     return {
       content: [
         {
@@ -13696,11 +13769,10 @@ var RobloxStudioTools = class {
     if (!code) {
       throw new Error("Code is required for eval_client_runtime");
     }
-    const clientTarget = target || "client-1";
-    if (!clientTarget.startsWith("client-")) {
-      throw new Error(`eval_client_runtime requires target=client-N (got: ${clientTarget})`);
+    if (target && !target.startsWith("client-")) {
+      throw new Error(`eval_client_runtime requires target=client-N (got: ${target})`);
     }
-    const response = await this._callSingle("/api/eval-runtime", { code }, clientTarget, instance_id);
+    const response = await this._callSingle("/api/eval-runtime", { code }, { requested: target, fallback: "client-1", accepts: isClientRole }, instance_id);
     return {
       content: [
         {
@@ -13717,7 +13789,7 @@ var RobloxStudioTools = class {
       await refresh;
     const instanceId = this._resolveInstanceIdOnly(instance_id);
     const clientRoles = this._clientRolesForScope(instanceId);
-    const selectedTarget = target ?? "client-1";
+    const selectedTarget = this._targetForInstanceId(instance_id, { requested: target, fallback: "client-1", accepts: isClientRole });
     let targetRoles;
     if (selectedTarget === "all-clients") {
       targetRoles = clientRoles;
@@ -14323,7 +14395,6 @@ var RobloxStudioTools = class {
     return this._textResult(result);
   }
   async captureScriptProfiler(target, request = {}, instance_id) {
-    const targetRole = target ?? "server";
     const data = { ...request };
     const outputPath = data.output_path;
     delete data.output_path;
@@ -14336,6 +14407,7 @@ var RobloxStudioTools = class {
     const refresh = this.bridge.refreshTopologyForRouting();
     if (refresh)
       await refresh;
+    const targetRole = this._targetForInstanceId(instance_id, { requested: target, fallback: "server", accepts: isRuntimeRole2 });
     const resolved = this.bridge.resolveTarget({ instance_id, target: targetRole });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
@@ -14366,7 +14438,6 @@ var RobloxStudioTools = class {
     return { content: [{ type: "text", text: JSON.stringify(body) }] };
   }
   async captureMicroProfiler(target, request = {}, instance_id) {
-    const targetRole = target ?? "server";
     const data = { ...request };
     const outputPath = data.output_path;
     const summaryOutputPath = data.summary_output_path;
@@ -14399,6 +14470,7 @@ var RobloxStudioTools = class {
     const refresh = this.bridge.refreshTopologyForRouting();
     if (refresh)
       await refresh;
+    const targetRole = this._targetForInstanceId(instance_id, { requested: target, fallback: "server", accepts: isRuntimeRole2 });
     const resolved = this.bridge.resolveTarget({ instance_id, target: targetRole });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
@@ -14449,13 +14521,13 @@ var RobloxStudioTools = class {
     if (!action || typeof action !== "string") {
       throw new Error("breakpoints requires action=set|remove|clear|list");
     }
-    const targetRole = target ?? "edit";
     const data = { ...request, action };
     delete data.target;
     delete data.instance_id;
     const refresh = this.bridge.refreshTopologyForRouting();
     if (refresh)
       await refresh;
+    const targetRole = this._targetForInstanceId(instance_id, { requested: target, fallback: "edit", accepts: isRuntimeRole2 });
     const resolved = this.bridge.resolveTarget({ instance_id, target: targetRole });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
@@ -15147,7 +15219,7 @@ var RobloxStudioTools = class {
       });
     }
     if (action === "leave_client") {
-      const body2 = this._parseTextResult(await this.multiplayerTestLeaveClient(target ?? "client-1", timeout, instance_id));
+      const body2 = this._parseTextResult(await this.multiplayerTestLeaveClient(target, timeout, instance_id));
       return this._textResult(body2.success === true && body2.left === true ? {
         success: true,
         action,
@@ -15280,14 +15352,15 @@ var RobloxStudioTools = class {
       }]
     };
   }
-  async multiplayerTestLeaveClient(target = "client-1", timeout, instance_id) {
-    if (!/^client-\d+$/.test(target)) {
+  async multiplayerTestLeaveClient(target, timeout, instance_id) {
+    if (target && !/^client-\d+$/.test(target)) {
       throw new Error(`multiplayer_test_leave_client requires target=client-N (got: ${target})`);
     }
     const refresh = this.bridge.refreshTopologyForRouting();
     if (refresh)
       await refresh;
-    const clientTarget = this._resolveSingleTarget(target, instance_id);
+    const role = this._targetForInstanceId(instance_id, { requested: target, fallback: "client-1", accepts: isClientRole });
+    const clientTarget = this._resolveSingleTarget(role, instance_id);
     const group = this.bridge.getMultiplayerGroups().find((candidate) => candidate.instanceIds.includes(clientTarget.instanceId));
     const scopeInstanceId = group?.controllerInstanceId ?? clientTarget.instanceId;
     const response = await this._requestPeer("/api/multiplayer-test-leave-client", {}, clientTarget.targetPeerId);
@@ -15909,12 +15982,13 @@ var RobloxStudioTools = class {
     if (refresh)
       await refresh;
     const { instanceId, clientRole } = this._resolveRuntime(instance_id);
+    const role = this._targetForInstanceId(instance_id, { requested: target, fallback: clientRole ?? "edit", accepts: isClientRole });
     const response = await this._callSingle("/api/simulate-mouse-input", {
       action,
       x,
       y,
       button
-    }, target || clientRole || "edit", instanceId);
+    }, role, instanceId);
     return {
       content: [{
         type: "text",
@@ -15930,12 +16004,13 @@ var RobloxStudioTools = class {
     if (refresh)
       await refresh;
     const { instanceId, clientRole } = this._resolveRuntime(instance_id);
+    const role = this._targetForInstanceId(instance_id, { requested: target, fallback: clientRole ?? "edit", accepts: isClientRole });
     const response = await this._callSingle("/api/simulate-keyboard-input", {
       keyCode,
       action,
       duration,
       text
-    }, target || clientRole || "edit", instanceId);
+    }, role, instanceId);
     return {
       content: [{
         type: "text",
@@ -15963,13 +16038,13 @@ var RobloxStudioTools = class {
     };
   }
   async getMemoryBreakdown(target, tags, instance_id) {
-    const tgt = target ?? "all";
     const data = {};
     if (tags !== void 0)
       data.tags = tags;
     const refresh = this.bridge.refreshTopologyForRouting();
     if (refresh)
       await refresh;
+    const tgt = this._targetForInstanceId(instance_id, { requested: target, fallback: "all", accepts: anyRole });
     const resolved = this.bridge.resolveTarget({ instance_id, target: tgt });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
@@ -15995,7 +16070,6 @@ var RobloxStudioTools = class {
     return { content: [{ type: "text", text: JSON.stringify(body) }] };
   }
   async getSceneAnalysis(mode, target, topN, raw, instance_id) {
-    const tgt = target ?? "all";
     const data = {};
     if (mode !== void 0)
       data.mode = mode;
@@ -16006,6 +16080,7 @@ var RobloxStudioTools = class {
     const refresh = this.bridge.refreshTopologyForRouting();
     if (refresh)
       await refresh;
+    const tgt = this._targetForInstanceId(instance_id, { requested: target, fallback: "all", accepts: anyRole });
     const resolved = this.bridge.resolveTarget({ instance_id, target: tgt });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
@@ -16037,11 +16112,10 @@ var RobloxStudioTools = class {
     if (!outputPath || typeof outputPath !== "string") {
       throw new Error("output_path is required for export_rbxm");
     }
-    const tgt = target || "edit";
-    if (tgt !== "edit" && tgt !== "server") {
-      throw new Error(`export_rbxm target must be "edit" or "server" (got: ${tgt})`);
+    if (target && target !== "edit" && target !== "server") {
+      throw new Error(`export_rbxm target must be "edit" or "server" (got: ${target})`);
     }
-    const response = await this._callSingle("/api/export-rbxm", { instance_paths: instancePaths }, tgt, instance_id);
+    const response = await this._callSingle("/api/export-rbxm", { instance_paths: instancePaths }, { requested: target, fallback: "edit", accepts: (role) => role === "server" }, instance_id);
     if (response.error) {
       return { content: [{ type: "text", text: JSON.stringify({ error: response.error }) }] };
     }
@@ -16074,9 +16148,8 @@ var RobloxStudioTools = class {
     if (!parentPath || typeof parentPath !== "string") {
       throw new Error("parent_path is required for import_rbxm");
     }
-    const tgt = target || "edit";
-    if (tgt !== "edit" && tgt !== "server") {
-      throw new Error(`import_rbxm target must be "edit" or "server" (got: ${tgt})`);
+    if (target && target !== "edit" && target !== "server") {
+      throw new Error(`import_rbxm target must be "edit" or "server" (got: ${target})`);
     }
     const modes = ["path", "url", "base64"].filter((k) => source[k] !== void 0);
     if (modes.length !== 1) {
@@ -16093,7 +16166,7 @@ var RobloxStudioTools = class {
       base64: bytes.toString("base64"),
       parent_path: parentPath,
       source_label: sourceLabel
-    }, tgt, instance_id, void 0, signal);
+    }, { requested: target, fallback: "edit", accepts: (role) => role === "server" }, instance_id, void 0, signal);
     return { content: [{ type: "text", text: JSON.stringify(response) }] };
   }
   // Even native capture must wait while another call has fitted the simulator
@@ -17538,7 +17611,7 @@ var TOOL_DEFINITIONS = [
         },
         target: {
           type: "string",
-          description: "Client peer; defaults to client-1."
+          description: "Client peer; defaults to the client named by instance_id, else client-1."
         },
         instance_id: {
           type: "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrrxs/robloxstudio-mcp",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "description": "MCP server for testing, debugging, and controlling Roblox Studio from AI coding tools",
   "main": "dist/index.js",
   "type": "module",

package/studio-plugin/MCPPlugin.rbxmx

@@ -64,8 +64,8 @@ applyRememberedServerUrl()
 -- down their VM. Close the persistent WebStreamClient while BindToClose still
 -- gives this server peer a live execution context; otherwise each play cycle
 -- can retain one native WebSocket until Studio itself is restarted. The
--- transport releases that native socket before yielding to unregister the
--- logical server peer.
+-- transport unregisters the server peer on that socket and waits at most two
+-- seconds for the server to close it, so no HTTP request can hold up shutdown.
 if startupRole == "server" then
 	game:BindToClose(StudioWebSocket.suspendForShutdown)
 end
@@ -104,8 +104,20 @@ plugin.Unloading:Connect(function()
 	Communication.deactivateAll()
 end)
 UI.updateUIState()
-Communication.checkForUpdates()
+-- Every DataModel shares Studio's five plugin HTTP request slots, and a
+-- request has no time limit. Check for updates once, from the edit DataModel,
+-- instead of again in every play server and client.
+if startupRole == "edit" then
+	Communication.checkForUpdates()
+end
 task.delay(TOOLBAR_REGISTRATION_DELAY_SECONDS, registerToolbarButton)
+--* Runs one startup step so that its failure cannot skip the steps after it. 
+local function runStartupStep(description, step)
+	local ok, err = pcall(step)
+	if not ok then
+		warn(`[robloxstudio-mcp] {description} failed: {err}`)
+	end
+end
 -- Auto-activate per Peer. Runtime plugin VMs can load before their first
 -- Heartbeat; task.delay() would then wait behind the very multiplayer startup
 -- that needs this Peer to register. Start runtime initialization immediately,
@@ -123,10 +135,13 @@ local function autoActivatePeer()
 	if role == "server" then
 		-- Yields until this playtest server knows which edit session (or
 		-- multiplayer group) it belongs to, so it registers under that identity.
-		PluginSession.resolveRuntimeTopology()
+		-- On failure the server still registers, under its own identity.
+		runStartupStep("Playtest topology resolution", function()
+			return PluginSession.resolveRuntimeTopology()
+		end)
 	end
 	if role == "edit" or role == "server" then
-		local activationOk, activationError = pcall(function()
+		runStartupStep(`Automatic {role} Peer activation`, function()
 			local conn = State.getActiveConnection()
 			if not conn.isActive then
 				if role == "server" then
@@ -155,19 +170,20 @@ local function autoActivatePeer()
 				Communication.activatePlugin()
 			end
 		end)
-		if not activationOk then
-			warn(`[robloxstudio-mcp] Automatic {role} Peer activation failed: {activationError}`)
-		end
 	end
 	if role == "server" then
-		ClientBroker.setupServerBroker()
+		runStartupStep("Client broker setup", function()
+			return ClientBroker.setupServerBroker()
+		end)
 		-- The play-server DM is the only one where StudioTestService:EndTest is
 		-- legal, so the stop-play monitor lives here. It consumes tokenized
 		-- stop requests from plugin settings and acknowledges EndTest results.
-		StopPlayMonitor.startMonitor({
-			beforeEndTest = StudioWebSocket.suspendForShutdown,
-			afterEndTestFailure = StudioWebSocket.resumeAfterShutdownFailure,
-		})
+		runStartupStep("Stop-play monitor startup", function()
+			return StopPlayMonitor.startMonitor({
+				beforeEndTest = StudioWebSocket.suspendForShutdown,
+				afterEndTestFailure = StudioWebSocket.resumeAfterShutdownFailure,
+			})
+		end)
 	elseif role == "client" then
 		ClientBroker.setupClientBroker()
 	end
@@ -1959,9 +1975,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "3.2.0" is replaced with the package version at package time
+	-- "3.2.1" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-3.2.0`
+	return `{tostring(h)}-3.2.1`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -10092,10 +10108,12 @@ local TOPOLOGY_TOKEN_ATTRIBUTE = "__MCPTopologyToken"
 -- saved or published DataModel, so edit sessions remove them on load.
 local LEGACY_TOPOLOGY_ATTRIBUTES = { TOPOLOGY_MODE_ATTRIBUTE, TOPOLOGY_INSTANCE_ID_ATTRIBUTE, TOPOLOGY_GROUP_ID_ATTRIBUTE, TOPOLOGY_TOKEN_ATTRIBUTE }
 local SESSION_IDENTITY_NAME = "__MCPSessionIdentity"
--- Attributes on the CoreGui identity value: CoreGui survives plugin reloads but
--- is never saved with the place or copied into playtest DataModels.
-local PLAY_RECORD_ATTRIBUTE = "PlayRecord"
-local RUNTIME_TOPOLOGY_ATTRIBUTE = "RuntimeTopology"
+-- JSON session state lives in StringValue children of the CoreGui identity
+-- value: CoreGui survives plugin reloads but is never saved with the place or
+-- copied into playtest DataModels. Not attributes: with NextGenerationReplication,
+-- playtest DataModels reject attribute strings longer than 50 characters.
+local PLAY_RECORD_NAME = "PlayRecord"
+local RUNTIME_TOPOLOGY_NAME = "RuntimeTopology"
 -- MCP-started solo and Run playtests carry their topology in StudioTestService
 -- test args, which never touch the DataModel.
 local TEST_ARGS_TOPOLOGY_KEY = "__mcpTopology"
@@ -10216,18 +10234,54 @@ local function optionalString(value)
 	end
 	return if _condition then value else nil
 end
-function readPlayRecord()
-	local raw = sessionIdentity:GetAttribute(PLAY_RECORD_ATTRIBUTE)
-	if not (type(raw) == "string") then
+local function readSessionState(name)
+	local holder = sessionIdentity:FindFirstChild(name)
+	if holder == nil or not holder:IsA("StringValue") then
 		return nil
 	end
 	local ok, decoded = pcall(function()
-		return HttpService:JSONDecode(raw)
+		return HttpService:JSONDecode(holder.Value)
 	end)
 	if not ok or not (type(decoded) == "table") then
 		return nil
 	end
-	local data = decoded
+	return decoded
+end
+--* Best effort: saved session state only lets a plugin reload resume where it left off. 
+local function writeSessionState(name, state)
+	local ok, err = pcall(function()
+		local existing = sessionIdentity:FindFirstChild(name)
+		if state == nil then
+			local _result = existing
+			if _result ~= nil then
+				_result:Destroy()
+			end
+			return nil
+		end
+		local encoded = HttpService:JSONEncode(state)
+		if existing ~= nil and existing:IsA("StringValue") then
+			existing.Value = encoded
+			return nil
+		end
+		local _result = existing
+		if _result ~= nil then
+			_result:Destroy()
+		end
+		local holder = Instance.new("StringValue")
+		holder.Name = name
+		holder.Value = encoded
+		holder.Archivable = false
+		holder.Parent = sessionIdentity
+	end)
+	if not ok then
+		warn(`[robloxstudio-mcp] Could not save {name} session state: {err}`)
+	end
+end
+function readPlayRecord()
+	local data = readSessionState(PLAY_RECORD_NAME)
+	if data == nil then
+		return nil
+	end
 	local phase = if data.phase == "armed" or data.phase == "active" then data.phase else nil
 	if phase == nil then
 		return nil
@@ -10243,16 +10297,7 @@ function readPlayRecord()
 	}
 end
 local function writePlayRecord(record)
-	if record == nil then
-		sessionIdentity:SetAttribute(PLAY_RECORD_ATTRIBUTE, nil)
-		return nil
-	end
-	local ok, encoded = pcall(function()
-		return HttpService:JSONEncode(record)
-	end)
-	if ok and type(encoded) == "string" then
-		sessionIdentity:SetAttribute(PLAY_RECORD_ATTRIBUTE, encoded)
-	end
+	writeSessionState(PLAY_RECORD_NAME, record)
 end
 local function createTicket(instanceId, groupId)
 	local now = PlaytestTickets.nowMs()
@@ -10544,17 +10589,10 @@ local function topologyFromTestArgs()
 	}
 end
 local function readRememberedRuntimeTopology()
-	local raw = sessionIdentity:GetAttribute(RUNTIME_TOPOLOGY_ATTRIBUTE)
-	if not (type(raw) == "string") then
+	local data = readSessionState(RUNTIME_TOPOLOGY_NAME)
+	if data == nil then
 		return nil
 	end
-	local ok, decoded = pcall(function()
-		return HttpService:JSONDecode(raw)
-	end)
-	if not ok or not (type(decoded) == "table") then
-		return nil
-	end
-	local data = decoded
 	return {
 		instanceId = optionalString(data.instanceId),
 		groupId = optionalString(data.groupId),
@@ -10564,12 +10602,7 @@ local function readRememberedRuntimeTopology()
 end
 local function adoptRuntimeTopology(topology)
 	runtimeTopology = topology
-	local ok, encoded = pcall(function()
-		return HttpService:JSONEncode(topology)
-	end)
-	if ok and type(encoded) == "string" then
-		sessionIdentity:SetAttribute(RUNTIME_TOPOLOGY_ATTRIBUTE, encoded)
-	end
+	writeSessionState(RUNTIME_TOPOLOGY_NAME, topology)
 end
 --[[
 	*
@@ -11496,7 +11529,7 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "3.2.0"
+local CURRENT_VERSION = "3.2.1"
 local PLUGIN_VARIANT = "main"
 local BASE_PORT = 58741
 local SENSITIVE_DIAGNOSTIC_TERMS = { "token", "authorization", "bearer", "password", "cookie", "secret" }
@@ -11943,6 +11976,10 @@ local MAX_PENDING_RESPONSE_BYTES = 64 * 1024 * 1024
 local RESERVED_ERROR_BYTES = 4096
 -- The bridge admits 128 UTF-16 code units; each can require three UTF-8 bytes.
 local MAX_REQUEST_ID_BYTES = 128 * 3
+-- Upper bound on BindToClose waiting for the server to close the socket after
+-- the unregister frame; it normally closes within milliseconds.
+local SHUTDOWN_UNREGISTER_WAIT_SECONDS = 2
+local SHUTDOWN_UNREGISTER_POLL_SECONDS = 0.05
 local options
 local active = false
 local shutdownSuspended = false
@@ -12985,8 +13022,13 @@ local function refresh()
 	refreshRequested = true
 	flushRefresh()
 end
--- EndTest may tear down this VM without an Unloading callback. Release the
--- native socket before yielding to unregister; a failed EndTest can resume.
+-- EndTest may tear down this VM without an Unloading callback, and BindToClose
+-- waits for this function. It unregisters on the socket itself: Studio runs at
+-- most five plugin HTTP requests at a time across the whole process, with no
+-- time limit, so a /disconnect queued behind five that never finish held
+-- shutdown until Studio's 30 s deadline. Closing right after Send can drop the
+-- frame, so it waits briefly for the server to close the socket first. A
+-- failed EndTest can resume and registers again.
 local function suspendForShutdown()
 	local currentOptions = options
 	if not active or currentOptions == nil then
@@ -12998,9 +13040,34 @@ local function suspendForShutdown()
 	cancelTransportWork()
 	refreshRequested = false
 	reconnectAttempt = 0
+	local client = socketClient
+	local unregistered = false
+	if client ~= nil and socketOpen then
+		local serverClosed = false
+		local closedConnection = client.Closed:Connect(function()
+			serverClosed = true
+		end)
+		local sent = pcall(function()
+			return client:Send(HttpService:JSONEncode({
+				kind = "disconnect",
+			}))
+		end)
+		unregistered = sent
+		local deadline = os.clock() + SHUTDOWN_UNREGISTER_WAIT_SECONDS
+		while sent and not serverClosed and os.clock() < deadline do
+			task.wait(SHUTDOWN_UNREGISTER_POLL_SECONDS)
+		end
+		closedConnection:Disconnect()
+	end
 	closeCurrentSocket()
 	cachedReady = nil
-	disconnectSession(currentOptions)
+	-- Without an open socket, unregister over HTTP on another thread rather
+	-- than wait; the server also drops a peer whose socket stays closed.
+	if not unregistered then
+		task.spawn(function()
+			return disconnectSession(currentOptions)
+		end)
+	end
 end
 local function resumeAfterShutdownFailure()
 	if not shutdownSuspended or options == nil then