@chrrxs/robloxstudio-mcp-inspector 3.1.2 → 3.1.4

package/dist/index.js

@@ -1945,6 +1945,15 @@ import { toNodeHandler } from "@modelcontextprotocol/node";
 
 // ../core/dist/bridge-service.js
 import { createHash, randomUUID } from "crypto";
+var MultiplayerGroupInUseError = class extends Error {
+  groupId;
+  code = "multiplayer_group_in_use";
+  constructor(groupId) {
+    super(`Multiplayer Group "${groupId}" still has connected runtime peers and cannot be removed.`);
+    this.groupId = groupId;
+    this.name = "MultiplayerGroupInUseError";
+  }
+};
 function isExecutionOutcome(value) {
   return value === "success" || value === "error" || value === "not_executed" || value === "unknown";
 }
@@ -2233,6 +2242,11 @@ var BridgeService = class {
     const group = this.multiplayerGroupsById.get(groupId);
     if (!group)
       return void 0;
+    for (const peer of this.peersById.values()) {
+      if (peer.multiplayerGroupId === groupId && isRuntimeRole(peer.role)) {
+        throw new MultiplayerGroupInUseError(groupId);
+      }
+    }
     this.multiplayerGroupsById.delete(groupId);
     for (const peer of this.peersById.values()) {
       if (peer.multiplayerGroupId === groupId)
@@ -2483,6 +2497,12 @@ var BridgeService = class {
       multiplayerGroups: this.getMultiplayerGroups()
     };
   }
+  /** Local topology is authoritative; remote adapters must refresh before fanout. */
+  refreshTopologyForRouting(signal) {
+    if (signal?.aborted)
+      throw new Error("Request aborted before topology resolution");
+    return void 0;
+  }
   resolveConnectedInstanceId(instanceId) {
     const exact = this.getInstances().find((instance) => instance.id === instanceId);
     const groupedRuntime = this.getPeers().find((peer) => peer.multiplayerGroupId !== void 0 && isRuntimeRole(peer.role) && connectedRuntimeInstanceId(peer) === instanceId);
@@ -5832,20 +5852,20 @@ var StudioInstanceManager = class {
 };
 
 // ../core/dist/mcp-runtime.js
-var INTERNAL_RESULT_KEYS = /* @__PURE__ */ new Set([
-  "bundleModifiedAt",
-  "bundlePath",
-  "bundleSha256",
-  "connectedAt",
-  "debug",
-  "diagnostics",
-  "internal",
-  "lastActivity",
-  "transportPeerId",
-  "pluginVariant",
-  "pluginVersion",
-  "serverVersion"
-]);
+var INTERNAL_ENVELOPE_KEYS = {
+  bundleModifiedAt: true,
+  bundlePath: true,
+  bundleSha256: true,
+  connectedAt: true,
+  debug: true,
+  diagnostics: true,
+  internal: true,
+  lastActivity: true,
+  transportPeerId: true,
+  pluginVariant: true,
+  pluginVersion: true,
+  serverVersion: true
+};
 var TEXT_RESULT_TOOLS = /* @__PURE__ */ new Set(["get_roblox_docs"]);
 var SIDE_EFFECTING_READ_TOOLS = /* @__PURE__ */ new Set([
   "capture_micro_profiler",
@@ -5894,18 +5914,15 @@ function compactPublicValue(value) {
     return value.map(compactPublicValue);
   if (!value || typeof value !== "object")
     return value;
-  const compact = {};
-  for (const [key, child] of Object.entries(value)) {
-    if (child === void 0 || INTERNAL_RESULT_KEYS.has(key))
-      continue;
-    compact[key] = compactPublicValue(child);
-  }
-  return compact;
+  return Object.fromEntries(Object.entries(value).filter(([, child]) => child !== void 0).map(([key, child]) => [key, compactPublicValue(child)]));
+}
+function compactPublicEnvelope(value) {
+  return Object.fromEntries(Object.entries(value).filter(([key, child]) => child !== void 0 && !Object.hasOwn(INTERNAL_ENVELOPE_KEYS, key)).map(([key, child]) => [key, compactPublicValue(child)]));
 }
 function asStructuredObject(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     return void 0;
-  return compactPublicValue(value);
+  return compactPublicEnvelope(value);
 }
 function parseJsonObject(text) {
   try {
@@ -5930,6 +5947,7 @@ function normalizeToolResult(raw, era) {
       ...result.isError ? { isError: true } : {}
     };
   }
+  const isError = result.isError || structured.success === false || typeof structured.error === "string" && structured.error.length > 0;
   const content = era === "modern" ? originalContent.filter((_, index) => index !== jsonTextIndex) : [
     { type: "text", text: JSON.stringify(structured) },
     ...originalContent.filter((_, index) => index !== jsonTextIndex)
@@ -5937,7 +5955,7 @@ function normalizeToolResult(raw, era) {
   return {
     content,
     structuredContent: structured,
-    ...result.isError ? { isError: true } : {}
+    ...isError ? { isError: true } : {}
   };
 }
 function publicRoutingError(error) {
@@ -5960,8 +5978,11 @@ function publicRoutingError(error) {
   };
 }
 function publicToolErrorBody(name, error) {
+  if (error instanceof MultiplayerGroupInUseError) {
+    return { error: error.code, message: error.message, multiplayer_group_id: error.groupId };
+  }
   if (error instanceof StudioLaunchPreDispatchError) {
-    return compactPublicValue(error.toResponseBody());
+    return compactPublicEnvelope(error.toResponseBody());
   }
   if (error instanceof RoutingFailure)
     return publicRoutingError(error);
@@ -6435,6 +6456,47 @@ var WebSocketStudioTransport = class {
 };
 
 // ../core/dist/http-server.js
+var TOOL_PROXY_ENDPOINTS = {
+  get_place_info: ["/api/place-info"],
+  search_objects: ["/api/search-objects"],
+  get_instance_properties: ["/api/instance-properties"],
+  get_project_structure: ["/api/project-structure"],
+  set_properties: ["/api/set-properties"],
+  get_script_source: ["/api/get-script-source"],
+  set_script_source: ["/api/set-script-source"],
+  edit_script_lines: ["/api/edit-script-lines"],
+  insert_script_lines: ["/api/insert-script-lines"],
+  delete_script_lines: ["/api/delete-script-lines"],
+  get_attributes: ["/api/get-attributes"],
+  selection: ["/api/get-selection", "/api/set-selection", "/api/focus-viewport"],
+  execute_luau: ["/api/execute-luau"],
+  eval_server_runtime: ["/api/eval-runtime"],
+  eval_client_runtime: ["/api/eval-runtime"],
+  grep_scripts: ["/api/grep-scripts"],
+  solo_playtest: ["/api/start-playtest", "/api/stop-playtest", "/api/multiplayer-test-state"],
+  multiplayer_playtest: [
+    "/api/multiplayer-test-start",
+    "/api/multiplayer-test-add-players",
+    "/api/multiplayer-test-leave-client",
+    "/api/multiplayer-test-end",
+    "/api/multiplayer-test-state"
+  ],
+  get_runtime_logs: ["/api/get-runtime-logs"],
+  capture_script_profiler: ["/api/capture-script-profiler"],
+  capture_micro_profiler: ["/api/capture-micro-profiler"],
+  breakpoints: ["/api/breakpoints"],
+  insert_asset: ["/api/insert-asset"],
+  generate_model: ["/api/generate-model"],
+  preview_asset: ["/api/preview-asset"],
+  capture_screenshot: ["/api/capture-studio", "/api/capture-screenshot", "/api/capture-begin", "/api/capture-read"],
+  simulate_mouse_input: ["/api/simulate-mouse-input"],
+  simulate_keyboard_input: ["/api/simulate-keyboard-input"],
+  get_memory_breakdown: ["/api/get-memory-breakdown"],
+  get_scene_analysis: ["/api/get-scene-analysis"],
+  export_rbxm: ["/api/export-rbxm"],
+  import_rbxm: ["/api/import-rbxm"],
+  find_and_replace_in_scripts: ["/api/find-and-replace-in-scripts"]
+};
 function toPassivePeer(peer) {
   return {
     instanceId: peer.instanceId,
@@ -6621,6 +6683,7 @@ ${body}`);
 }
 function createHttpServer(tools, bridge, allowedTools, serverConfig, security) {
   const app = express();
+  const allowedProxyEndpoints = allowedTools ? new Set(Object.entries(TOOL_PROXY_ENDPOINTS).filter(([toolName]) => allowedTools.has(toolName)).flatMap(([, endpoints]) => endpoints)) : void 0;
   const studioLifecycleCallable = !allowedTools || allowedTools.has("manage_instance");
   const studioLifecycleCapabilities = studioLifecycleCallable ? tools.getStudioLifecycleCapabilities() : void 0;
   let mcpServerActive = false;
@@ -7028,14 +7091,27 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig, security) {
     const group = await bridge.createMultiplayerGroupEverywhere(groupId, controllerInstanceId);
     res.json({ success: true, group });
   });
-  app.post("/remove-multiplayer-group", async (req, res) => {
+  app.post("/remove-multiplayer-group", async (req, res, next) => {
     const { groupId } = req.body;
     if (typeof groupId !== "string" || groupId.length === 0) {
       res.status(400).json({ error: "groupId is required" });
       return;
     }
-    const removed = await bridge.removeMultiplayerGroupEverywhere(groupId);
-    res.json({ success: true, removed });
+    try {
+      const removed = await bridge.removeMultiplayerGroupEverywhere(groupId);
+      res.json({ success: true, removed });
+    } catch (error) {
+      if (error instanceof MultiplayerGroupInUseError) {
+        res.status(409).json({
+          success: false,
+          error: error.code,
+          message: error.message,
+          groupId: error.groupId
+        });
+        return;
+      }
+      next(error);
+    }
   });
   app.get("/status", (req, res) => {
     const peers = bridge.getPublicPeers().map(toPassivePeer);
@@ -7082,6 +7158,10 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig, security) {
       res.status(400).json({ error: "endpoint and targetPeerId are required" });
       return;
     }
+    if (allowedProxyEndpoints && !allowedProxyEndpoints.has(endpoint)) {
+      res.status(403).json({ error: "forbidden_endpoint" });
+      return;
+    }
     if (timeoutMs !== void 0 && (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 3e5)) {
       res.status(400).json({ error: "timeoutMs must be an integer between 1 and 300000" });
       return;
@@ -10880,7 +10960,10 @@ var RobloxStudioTools = class {
   _requestPeer(endpoint, data, targetPeerId, timeoutMs, signal, operationId) {
     return this.client.request(endpoint, data, targetPeerId, timeoutMs, signal, operationId);
   }
-  _request(endpoint, data, instanceId, role, timeoutMs, signal) {
+  async _request(endpoint, data, instanceId, role, timeoutMs, signal) {
+    const refresh = this.bridge.refreshTopologyForRouting(signal);
+    if (refresh)
+      await refresh;
     const peer = this._peerForRoleInScope(instanceId, role);
     if (!peer) {
       throw new RoutingFailure({
@@ -10893,6 +10976,9 @@ var RobloxStudioTools = class {
   }
   // Resolve an optional Studio process plus role to one exact Peer and dispatch.
   async _callSingle(endpoint, data, target, instance_id, timeoutMs, signal, operationId) {
+    const refresh = this.bridge.refreshTopologyForRouting(signal);
+    if (refresh)
+      await refresh;
     const resolved = this.bridge.resolveTarget({ instance_id, target });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
@@ -10924,6 +11010,7 @@ var RobloxStudioTools = class {
       clientRole: client?.role
     };
   }
+  // Resolve synchronously after the caller has refreshed and captured its topology.
   _resolveInstanceIdOnly(instance_id) {
     if (instance_id !== void 0) {
       const resolvedInstanceId = this.bridge.resolveConnectedInstanceId(instance_id);
@@ -11137,6 +11224,9 @@ var RobloxStudioTools = class {
   async _waitForRuntimeRoles(instanceId, opts, timeoutSec = 30) {
     const deadline = Date.now() + timeoutSec * 1e3;
     while (Date.now() < deadline) {
+      const refresh = this.bridge.refreshTopologyForRouting();
+      if (refresh)
+        await refresh;
       const roles = this._rolesForScope(instanceId);
       const clientRoles = this._clientRolesForScope(instanceId);
       const hasServer = !opts.server || roles.includes("server");
@@ -11158,6 +11248,9 @@ var RobloxStudioTools = class {
     const deadline = Date.now() + timeoutSec * 1e3;
     let exactSince;
     while (Date.now() < deadline) {
+      const refresh = this.bridge.refreshTopologyForRouting();
+      if (refresh)
+        await refresh;
       const roles2 = this._rolesForScope(instanceId);
       const clientCount2 = this._clientRolesForScope(instanceId).length;
       if (clientCount2 > expectedClientCount) {
@@ -11180,6 +11273,9 @@ var RobloxStudioTools = class {
   async _waitForRuntimeRolesFresh(instanceId, connectedAfter, requiredRoles, timeoutSec = 60) {
     const deadline = Date.now() + timeoutSec * 1e3;
     while (Date.now() < deadline) {
+      const refresh = this.bridge.refreshTopologyForRouting();
+      if (refresh)
+        await refresh;
       const peers = this.bridge.getPeersInScope(instanceId);
       const roles = peers.map((peer) => peer.role);
       const freshRoles = new Set(peers.filter((peer) => peer.connectedAt >= connectedAfter).map((peer) => peer.role));
@@ -11477,6 +11573,9 @@ var RobloxStudioTools = class {
     if (angleY !== void 0 && (angleY < -89 || angleY > 89)) {
       throw new Error("selection angleY must be between -89 and 89");
     }
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const { instanceId, clientRole } = this._resolveRuntime(instance_id);
     const response = await this._callSingle("/api/focus-viewport", {
       path: instancePath,
@@ -11541,6 +11640,9 @@ var RobloxStudioTools = class {
   }
   async setNetworkProfile(profile, target, overrides, instance_id) {
     const values = normalizeNetworkProfile(profile, overrides);
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const instanceId = this._resolveInstanceIdOnly(instance_id);
     const clientRoles = this._clientRolesForScope(instanceId);
     const selectedTarget = target ?? "client-1";
@@ -11607,6 +11709,9 @@ var RobloxStudioTools = class {
     const selectedInclude = this._normalizeSimulationInclude(include);
     const includeNetwork = selectedInclude === "network" || selectedInclude === "both";
     const includeDeviceSimulator = selectedInclude === "deviceSimulator" || selectedInclude === "both";
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const resolved = this._resolveSimulationTargets(target, instance_id, "get_simulation_state");
     const roleEntries = await Promise.all(resolved.roles.map(async (role) => {
       const state = {};
@@ -11653,6 +11758,9 @@ var RobloxStudioTools = class {
     if (!resetNetwork && !resetDeviceSimulator) {
       throw new Error("reset_simulation_state requires network=true and/or deviceSimulator=true; both default to true");
     }
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const resolved = this._resolveSimulationTargets(target, instance_id, "reset_simulation_state");
     const roleEntries = await Promise.all(resolved.roles.map(async (role) => {
       const result = {};
@@ -11711,6 +11819,9 @@ var RobloxStudioTools = class {
     if (deviceId !== void 0 && (typeof deviceId !== "string" || deviceId.trim() === "")) {
       throw new Error("deviceId must be a non-empty string when provided");
     }
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const resolved = this._resolveDeviceSimulatorSingleTarget(target, instance_id, "get_device_simulator_state");
     const state = await this._executeDeviceSimulatorOperation(resolved.instanceId, resolved.role, "get", {
       includeDeviceList: includeDeviceList !== false,
@@ -11735,6 +11846,9 @@ var RobloxStudioTools = class {
     if (stopSimulation !== true && !hasDeviceSimulatorSettings(settings)) {
       throw new Error("set_device_simulator requires stopSimulation=true or at least one simulator setting");
     }
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const resolved = this._resolveDeviceSimulatorSetTargets(target, instance_id);
     const responses = await Promise.allSettled(resolved.roles.map(async (role) => {
       const result = await this._executeDeviceSimulatorOperation(resolved.instanceId, role, "set", stopSimulation === true ? { stopSimulation: true } : { settings });
@@ -11793,6 +11907,9 @@ var RobloxStudioTools = class {
         label: raw.label
       };
     });
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const resolved = this._resolveDeviceSimulatorSingleTarget(target, instance_id, "capture_device_matrix");
     if (resolved.role.startsWith("client-") && await this._isMultiplayerTestRunning(resolved.instanceId)) {
       throw new Error("capture_device_matrix does not support StudioTestService multiplayer client targets because Roblox scopes temporary screenshot textures per client process");
@@ -11908,6 +12025,9 @@ var RobloxStudioTools = class {
     if (tail !== void 0 && (!Number.isInteger(tail) || tail < 0)) {
       throw new Error("get_runtime_logs tail must be a non-negative integer.");
     }
+    const refresh = this.bridge.refreshTopologyForRouting(signal);
+    if (refresh)
+      await refresh;
     const instances = this.bridge.getInstances();
     const groups = this.bridge.getMultiplayerGroups();
     let selectedGroup = multiplayer_group_id === void 0 ? void 0 : groups.find((group) => group.id === multiplayer_group_id);
@@ -12141,6 +12261,9 @@ var RobloxStudioTools = class {
     if (outputPath) {
       data.__mcp_include_raw_json = true;
     }
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const resolved = this.bridge.resolveTarget({ instance_id, target: targetRole });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
@@ -12201,6 +12324,9 @@ var RobloxStudioTools = class {
     if (summaryOutputPath || baselinePath || baseline || includeComparisonIndex) {
       data.__mcp_include_comparison_index = true;
     }
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const resolved = this.bridge.resolveTarget({ instance_id, target: targetRole });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
@@ -12255,6 +12381,9 @@ var RobloxStudioTools = class {
     const data = { ...request, action };
     delete data.target;
     delete data.instance_id;
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const resolved = this.bridge.resolveTarget({ instance_id, target: targetRole });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
@@ -12605,6 +12734,9 @@ var RobloxStudioTools = class {
       throw new Error("solo_playtest requires action=start|stop|status");
     }
     if (action === "status") {
+      const refresh = this.bridge.refreshTopologyForRouting();
+      if (refresh)
+        await refresh;
       const instanceId = this._resolveInstanceIdOnly(instance_id);
       const { roles, runtimeRoles } = this._briefRoles(instanceId);
       return this._textResult({
@@ -12628,6 +12760,8 @@ var RobloxStudioTools = class {
         });
       }
       return this._textResult({
+        // Keep lifecycle diagnostics on failures; only successful responses are brief.
+        ...body2,
         success: false,
         action,
         error: body2.error ?? "start_failed",
@@ -12644,6 +12778,7 @@ var RobloxStudioTools = class {
       });
     }
     return this._textResult({
+      ...body,
       success: false,
       action,
       error: body.error ?? "stop_failed",
@@ -12662,6 +12797,9 @@ var RobloxStudioTools = class {
     }
     const data = { mode };
     const startedAt = Date.now();
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const resolved = this.bridge.resolveTarget({ instance_id, target: void 0 });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
@@ -12712,6 +12850,9 @@ var RobloxStudioTools = class {
     };
   }
   async stopPlaytest(instance_id, timeout = 15) {
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const { instanceId } = this._resolveSingleTarget("edit", instance_id);
     let response;
     let stopRequestError;
@@ -12732,7 +12873,7 @@ var RobloxStudioTools = class {
       wait = {
         ok: false,
         roles: this._rolesForScope(instanceId),
-        timedOut: false
+        timedOut: response.timedOut === true
       };
     }
     const body = wait ? {
@@ -12747,8 +12888,8 @@ var RobloxStudioTools = class {
         ...body,
         success: false,
         error: "Playtest teardown did not complete.",
-        message: response?.success === true ? wait.timedOut ? "Stop signal was accepted, but runtime peers did not disconnect before timeout." : "Stop signal was accepted, but runtime peers are still connected." : "Edit stop request failed, and runtime peers are still connected.",
-        stopSignalAccepted: response?.success === true,
+        message: response.stopSignalAccepted === true && typeof response.message === "string" ? response.message : response?.success === true ? wait.timedOut ? "Stop signal was accepted, but runtime peers did not disconnect before timeout." : "Stop signal was accepted, but runtime peers are still connected." : "Edit stop request failed, and runtime peers are still connected.",
+        stopSignalAccepted: response?.success === true || response.stopSignalAccepted === true,
         stopRequestError,
         runtimeRoles,
         possibleCause: "A game shutdown hook such as BindToClose may be blocking Studio teardown. No runtime hard-stop or synthetic keyboard fallback was attempted."
@@ -12762,6 +12903,9 @@ var RobloxStudioTools = class {
     };
   }
   async _buildMultiplayerState(instanceId) {
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const peers = this.bridge.getPublicPeers().filter((peer) => this.bridge.getInstanceIdsInScope(instanceId).includes(peer.instanceId)).sort((a, b) => a.role.localeCompare(b.role));
     const multiplayerGroup = this.bridge.getMultiplayerGroups().find((group) => group.instanceIds.includes(instanceId));
     const body = {
@@ -12807,6 +12951,9 @@ var RobloxStudioTools = class {
   async _waitForMultiplayerEditDone(instanceId, timeoutSec = 30) {
     const deadline = Date.now() + timeoutSec * 1e3;
     while (Date.now() < deadline) {
+      const refresh = this.bridge.refreshTopologyForRouting();
+      if (refresh)
+        await refresh;
       if (!this._rolesForScope(instanceId).includes("edit"))
         return false;
       try {
@@ -12821,6 +12968,9 @@ var RobloxStudioTools = class {
     return false;
   }
   async _isMultiplayerTestRunning(instanceId) {
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     return this.bridge.getMultiplayerGroups().some((group) => group.instanceIds.includes(instanceId));
   }
   async _waitForMultiplayerStart(instanceId, clientCount, timeoutSec = 30, connectedAfter) {
@@ -12861,6 +13011,9 @@ var RobloxStudioTools = class {
       throw new Error("multiplayer_playtest requires action=start|status|add_players|leave_client|end");
     }
     const briefState = async (instanceId) => {
+      const refresh = this.bridge.refreshTopologyForRouting();
+      if (refresh)
+        await refresh;
       const state = await this._buildMultiplayerState(this._resolveInstanceIdOnly(instanceId));
       const roles = Array.isArray(state.peers) ? state.peers.flatMap((peer) => peer !== null && typeof peer === "object" && "role" in peer && typeof peer.role === "string" ? [peer.role] : []) : [];
       return {
@@ -12958,6 +13111,9 @@ var RobloxStudioTools = class {
     if (!Number.isInteger(numPlayers) || numPlayers < 1 || numPlayers > 8) {
       throw new Error("numPlayers must be an integer from 1 to 8");
     }
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const editTarget = this._resolveSingleTarget("edit", instance_id);
     const existingRuntime = this._runtimeTargetsForScope(editTarget.instanceId);
     if (existingRuntime.length > 0) {
@@ -13014,6 +13170,9 @@ var RobloxStudioTools = class {
     };
   }
   async multiplayerTestState(instance_id) {
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const instanceId = this._resolveInstanceIdOnly(instance_id);
     const state = await this._buildMultiplayerState(instanceId);
     return { content: [{ type: "text", text: JSON.stringify(state) }] };
@@ -13022,6 +13181,9 @@ var RobloxStudioTools = class {
     if (!Number.isInteger(numPlayers) || numPlayers < 1 || numPlayers > 8) {
       throw new Error("numPlayers must be an integer from 1 to 8");
     }
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const serverTarget = this._resolveSingleTarget("server", instance_id);
     const group = this.bridge.getMultiplayerGroups().find((candidate) => candidate.instanceIds.includes(serverTarget.instanceId));
     const scopeInstanceId = group?.controllerInstanceId ?? serverTarget.instanceId;
@@ -13050,6 +13212,9 @@ var RobloxStudioTools = class {
     if (!/^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 group = this.bridge.getMultiplayerGroups().find((candidate) => candidate.instanceIds.includes(clientTarget.instanceId));
     const scopeInstanceId = group?.controllerInstanceId ?? clientTarget.instanceId;
@@ -13073,6 +13238,9 @@ var RobloxStudioTools = class {
     };
   }
   async multiplayerTestEnd(value, timeout, instance_id) {
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     let serverTarget;
     try {
       serverTarget = this._resolveSingleTarget("server", instance_id);
@@ -13121,6 +13289,9 @@ var RobloxStudioTools = class {
     return result;
   }
   async getConnectedInstances() {
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     return this._textResult({
       instances: this.bridge.getConnectedInstances(),
       multiplayerGroups: this.bridge.getConnectedMultiplayerGroups()
@@ -13662,6 +13833,9 @@ var RobloxStudioTools = class {
     if (!action) {
       throw new Error("action is required for simulate_mouse_input");
     }
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const { instanceId, clientRole } = this._resolveRuntime(instance_id);
     const response = await this._callSingle("/api/simulate-mouse-input", {
       action,
@@ -13680,6 +13854,9 @@ var RobloxStudioTools = class {
     if (!keyCode && text === void 0) {
       throw new Error("keyCode or text is required for simulate_keyboard_input");
     }
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const { instanceId, clientRole } = this._resolveRuntime(instance_id);
     const response = await this._callSingle("/api/simulate-keyboard-input", {
       keyCode,
@@ -13718,6 +13895,9 @@ var RobloxStudioTools = class {
     const data = {};
     if (tags !== void 0)
       data.tags = tags;
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const resolved = this.bridge.resolveTarget({ instance_id, target: tgt });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
@@ -13751,6 +13931,9 @@ var RobloxStudioTools = class {
       data.topN = topN;
     if (raw !== void 0)
       data.raw = raw;
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const resolved = this.bridge.resolveTarget({ instance_id, target: tgt });
     if (!resolved.ok)
       throw new RoutingFailure(resolved.error);
@@ -13883,18 +14066,23 @@ var RobloxStudioTools = class {
     return { content: [{ type: "text", text: JSON.stringify(response) }] };
   }
   async _captureViewportImage(instanceId, targetRole, format, quality, maxBytes = MAX_INLINE_IMAGE_BYTES) {
-    let response;
-    if (targetRole.startsWith("client-")) {
-      const begin = await this._callSingle("/api/capture-begin", {}, targetRole, instanceId);
-      if (begin.error) {
-        return { success: false, error: begin.error };
-      }
-      if (!begin.contentId) {
-        return { success: false, error: "Screenshot capture failed: no content id returned from client." };
+    const fmt = format === "png" ? "png" : "jpeg";
+    const q = quality === void 0 ? 92 : Math.max(1, Math.min(100, Math.floor(quality)));
+    let response = await this._callSingle("/api/capture-studio", { encoding: fmt === "png" ? "png" : "rgba8" }, targetRole, instanceId);
+    const studioFastPathMissing = response.unavailable !== void 0 || (response.error?.includes("/api/capture-studio") ?? false);
+    if (studioFastPathMissing) {
+      if (targetRole.startsWith("client-")) {
+        const begin = await this._callSingle("/api/capture-begin", {}, targetRole, instanceId);
+        if (begin.error) {
+          return { success: false, error: begin.error };
+        }
+        if (!begin.contentId) {
+          return { success: false, error: "Screenshot capture failed: no content id returned from client." };
+        }
+        response = await this._callSingle("/api/capture-read", { contentId: begin.contentId }, "edit", instanceId);
+      } else {
+        response = await this._callSingle("/api/capture-screenshot", {}, "edit", instanceId);
       }
-      response = await this._callSingle("/api/capture-read", { contentId: begin.contentId }, "edit", instanceId);
-    } else {
-      response = await this._callSingle("/api/capture-screenshot", {}, "edit", instanceId);
     }
     if (response.error) {
       let text = response.error;
@@ -13908,11 +14096,19 @@ var RobloxStudioTools = class {
     if (w === void 0 || h === void 0) {
       return { success: false, error: "Screenshot response missing dimensions." };
     }
-    const fmt = format === "png" ? "png" : "jpeg";
-    const q = quality === void 0 ? 92 : Math.max(1, Math.min(100, Math.floor(quality)));
-    const encoded = encodeImageFromRgbaResponse(response, fmt, q);
-    let { buffer } = encoded;
-    const { mimeType } = encoded;
+    let buffer;
+    let mimeType;
+    if (response.encoding === "png") {
+      if (!response.data) {
+        return { success: false, error: "Screenshot response missing PNG data." };
+      }
+      buffer = Buffer.from(response.data, "base64");
+      mimeType = "image/png";
+    } else {
+      const encoded = encodeImageFromRgbaResponse(response, fmt, q);
+      buffer = encoded.buffer;
+      mimeType = encoded.mimeType;
+    }
     let usedQ = q;
     let note = "";
     if (buffer.length > maxBytes) {
@@ -13951,6 +14147,9 @@ var RobloxStudioTools = class {
     };
   }
   async captureScreenshot(instance_id, format, quality) {
+    const refresh = this.bridge.refreshTopologyForRouting();
+    if (refresh)
+      await refresh;
     const { instanceId, clientRole } = this._resolveRuntime(instance_id);
     const capture = await this._captureViewportImage(instanceId, clientRole ?? "edit", format, quality);
     if (!capture.success) {
@@ -14032,6 +14231,9 @@ var ProxyBridgeService = class _ProxyBridgeService extends BridgeService {
   initialRefresh;
   refreshTimer;
   static REFRESH_INTERVAL_MS = 1e3;
+  static TOPOLOGY_TIMEOUT_MS = 2e3;
+  topologyGeneration = 0;
+  appliedTopologyGeneration = 0;
   constructor(primaryBaseUrl, authToken) {
     super();
     this.primaryBaseUrl = primaryBaseUrl;
@@ -14049,17 +14251,33 @@ var ProxyBridgeService = class _ProxyBridgeService extends BridgeService {
       headers["X-MCP-Auth"] = this.authToken;
     return headers;
   }
-  async refreshTopology() {
+  refreshTopologyForRouting(signal) {
+    return this.refreshTopology(signal, true);
+  }
+  async refreshTopology(signal, requireFresh = false) {
+    const generation = ++this.topologyGeneration;
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal?.reason);
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted)
+      abort();
+    const timeout = setTimeout(() => controller.abort(new Error("Studio topology refresh timed out")), _ProxyBridgeService.TOPOLOGY_TIMEOUT_MS);
     try {
+      controller.signal.throwIfAborted();
       const res = await fetch(`${this.primaryBaseUrl}/topology`, {
-        headers: this.authHeaders()
+        headers: this.authHeaders(),
+        signal: controller.signal
       });
       if (!res.ok)
-        return;
+        throw new Error(`Studio topology returned HTTP ${res.status}`);
       const body = await res.json();
-      if (!Array.isArray(body.peers) || !Array.isArray(body.instances) || !Array.isArray(body.multiplayerGroups)) {
-        return;
+      controller.signal.throwIfAborted();
+      if (!body || !Array.isArray(body.peers) || !Array.isArray(body.instances) || !Array.isArray(body.multiplayerGroups)) {
+        throw new Error("Primary returned invalid Studio topology");
       }
+      if (generation < this.appliedTopologyGeneration)
+        return;
+      this.appliedTopologyGeneration = generation;
       const previousPeers = new Map(this.cachedPeers.map((peer) => [peer.peerId, peer]));
       this.cachedPeers = body.peers;
       this.cachedInstances = body.instances;
@@ -14069,7 +14287,12 @@ var ProxyBridgeService = class _ProxyBridgeService extends BridgeService {
           this.notifyPeerRegistered(toPublicPeer(peer));
         }
       }
-    } catch {
+    } catch (error) {
+      if (requireFresh)
+        throw error;
+    } finally {
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", abort);
     }
   }
   getPeers() {
@@ -14124,6 +14347,13 @@ var ProxyBridgeService = class _ProxyBridgeService extends BridgeService {
       headers: this.authHeaders({ "Content-Type": "application/json" }),
       body: JSON.stringify({ groupId })
     });
+    if (response.status === 409) {
+      const refusal = await response.json().catch(() => void 0);
+      if (refusal && typeof refusal === "object" && !Array.isArray(refusal) && "success" in refusal && refusal.success === false && "error" in refusal && refusal.error === "multiplayer_group_in_use" && "groupId" in refusal && refusal.groupId === groupId) {
+        throw new MultiplayerGroupInUseError(groupId);
+      }
+      throw new Error("Proxy Multiplayer Group removal returned an invalid refusal.");
+    }
     if (!response.ok) {
       const body = await response.text().catch(() => "");
       throw new Error(`Proxy Multiplayer Group removal failed (${response.status}): ${body || response.statusText}`);
@@ -16459,7 +16689,7 @@ var getReadOnlyTools = () => TOOL_DEFINITIONS.filter((t) => t.category === "read
 
 // ../core/dist/install-plugin-helpers.js
 var import_saxes = __toESM(require_saxes(), 1);
-import { existsSync as existsSync6, lstatSync, mkdirSync as mkdirSync4, readFileSync as readFileSync6, renameSync, rmSync as rmSync2, statSync as statSync3, unlinkSync, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync6, lstatSync, mkdirSync as mkdirSync4, readFileSync as readFileSync6, renameSync, rmSync as rmSync2, rmdirSync, statSync as statSync3, unlinkSync, writeFileSync as writeFileSync3 } from "fs";
 import { execSync } from "child_process";
 import { randomUUID as randomUUID5 } from "crypto";
 import { basename as basename3, join as join5 } from "path";
@@ -16610,7 +16840,79 @@ Delete ${otherAssetName} manually or use the default CLI installer behavior to r
 }
 var PLUGIN_INSTALL_LOCK_NAME = ".robloxstudio-mcp-plugin-install.lock";
 function errorCode(error) {
-  return error.code;
+  return error !== null && typeof error === "object" && "code" in error && typeof error.code === "string" ? error.code : void 0;
+}
+function pluginInstallLockError(lockPath, reason) {
+  return new Error(`${reason}: ${lockPath}. If no installer or lock recovery is running, remove that lock directory and retry.`);
+}
+function readPluginInstallLockOwner(lockPath) {
+  const ownerPath = join5(lockPath, "owner.json");
+  if (!lstatSync(lockPath).isDirectory() || !lstatSync(ownerPath).isFile()) {
+    throw new Error("Lock and owner metadata must be a directory and regular file");
+  }
+  const owner = JSON.parse(readFileSync6(ownerPath, "utf8"));
+  if (owner === null || typeof owner !== "object" || !("pid" in owner) || typeof owner.pid !== "number" || !Number.isSafeInteger(owner.pid) || owner.pid <= 0 || owner.pid > 2147483647 || !("token" in owner) || typeof owner.token !== "string" || !/^[a-zA-Z0-9-]{1,128}$/.test(owner.token) || !("createdAt" in owner) || typeof owner.createdAt !== "number" || !Number.isFinite(owner.createdAt) || owner.createdAt < 0) {
+    throw new Error("Invalid lock owner metadata");
+  }
+  return { pid: owner.pid, token: owner.token, createdAt: owner.createdAt };
+}
+function assertPluginInstallOwnerExited(lockPath, owner) {
+  if (owner.pid !== process.pid) {
+    try {
+      process.kill(owner.pid, 0);
+    } catch (error) {
+      if (errorCode(error) === "ESRCH")
+        return;
+      throw pluginInstallLockError(lockPath, `Cannot confirm that plugin installation owner PID ${owner.pid} has exited (${errorCode(error) ?? error})`);
+    }
+  }
+  throw pluginInstallLockError(lockPath, `Another Studio plugin installation is already in progress (owner PID ${owner.pid})`);
+}
+function recoverPluginInstallLock(lockPath, warn) {
+  let owner;
+  try {
+    owner = readPluginInstallLockOwner(lockPath);
+  } catch (error) {
+    throw pluginInstallLockError(lockPath, `Cannot safely read plugin installation lock owner (${error})`);
+  }
+  assertPluginInstallOwnerExited(lockPath, owner);
+  const claimPath = join5(lockPath, `recovery-${owner.token}`);
+  try {
+    mkdirSync4(claimPath);
+  } catch (error) {
+    throw pluginInstallLockError(lockPath, errorCode(error) === "EEXIST" ? "Plugin installation lock recovery is already in progress or was interrupted" : `Could not claim plugin installation lock recovery (${error})`);
+  }
+  const abandonedPath = `${lockPath}.${randomUUID5()}.abandoned`;
+  let moved = false;
+  try {
+    let currentOwner;
+    try {
+      currentOwner = readPluginInstallLockOwner(lockPath);
+    } catch (error) {
+      throw pluginInstallLockError(lockPath, `Cannot safely recheck plugin installation lock owner (${error})`);
+    }
+    if (currentOwner.pid !== owner.pid || currentOwner.token !== owner.token || currentOwner.createdAt !== owner.createdAt) {
+      throw pluginInstallLockError(lockPath, "Plugin installation lock owner changed; retry installation");
+    }
+    assertPluginInstallOwnerExited(lockPath, currentOwner);
+    renameSync(lockPath, abandonedPath);
+    moved = true;
+  } finally {
+    if (!moved) {
+      try {
+        rmdirSync(claimPath);
+      } catch (error) {
+        if (errorCode(error) !== "ENOENT") {
+          warn(`[install-plugin] Could not release lock recovery claim ${claimPath}: ${error}`);
+        }
+      }
+    }
+  }
+  try {
+    rmSync2(abandonedPath, { recursive: true, force: true });
+  } catch (error) {
+    warn(`[install-plugin] Could not clean abandoned install lock ${abandonedPath}: ${error}`);
+  }
 }
 function acquirePluginInstallLock(pluginsFolder, warn) {
   const lockPath = join5(pluginsFolder, PLUGIN_INSTALL_LOCK_NAME);
@@ -16625,7 +16927,14 @@ function acquirePluginInstallLock(pluginsFolder, warn) {
   } catch (error) {
     if (errorCode(error) !== "EEXIST")
       throw error;
-    throw new Error(`Another Studio plugin installation is already in progress: ${lockPath}. If no installer is running, remove that lock directory and retry.`);
+    recoverPluginInstallLock(lockPath, warn);
+    try {
+      mkdirSync4(lockPath);
+    } catch (retryError) {
+      if (errorCode(retryError) !== "EEXIST")
+        throw retryError;
+      throw pluginInstallLockError(lockPath, "Another Studio plugin installation is already in progress");
+    }
   }
   try {
     writeFileSync3(ownerPath, `${JSON.stringify(owner)}
@@ -16643,7 +16952,7 @@ function acquirePluginInstallLock(pluginsFolder, warn) {
   }
   return () => {
     try {
-      const currentOwner = JSON.parse(readFileSync6(ownerPath, "utf8"));
+      const currentOwner = readPluginInstallLockOwner(lockPath);
       if (currentOwner.pid === owner.pid && currentOwner.token === owner.token) {
         rmSync2(lockPath, { recursive: true, force: true });
       }