@el4cteo/rbx-studio-mcp 0.7.6 → 0.7.8

package/plugin/src/handlers/Playtest.luau

@@ -67,13 +67,18 @@ local function editModeActive(): boolean?
 end
 
 local function state(): { [string]: any }
+	local players = {}
+	for _, player in game:GetService("Players"):GetPlayers() do
+		table.insert(players, { name = player.Name, userId = player.UserId })
+	end
 	return {
 		playtestsAllowed = Playtest.isAllowed(),
 		isEdit = RunService:IsEdit(),
 		isRunning = RunService:IsRunning(),
 		isRunMode = RunService:IsRunMode(),
 		editModeActive = editModeActive(),
-		playerCount = #game:GetService("Players"):GetPlayers(),
+		playerCount = #players,
+		players = if #players > 0 then players else nil,
 		testPending = pending,
 		-- Kept from the previous test rather than discarded, since whatever
 		-- EndTest returned is the only thing a test session can hand back.

package/plugin/src/init.server.luau

@@ -17,6 +17,7 @@ local Console = require(script.Console)
 local Dispatch = require(script.Dispatch)
 local History = require(script.History)
 local LogBuffer = require(script.LogBuffer)
+local ClientRelay = require(script.ClientRelay)
 local Mirror = require(script.Mirror)
 local Phrase = require(script.Phrase)
 local ScriptEdit = require(script.ScriptEdit)
@@ -130,6 +131,7 @@ end
 -- is unrecoverable. This runs even in a client session that will never connect,
 -- since the console tool reads it and connectivity is a separate question.
 LogBuffer.start()
+ClientRelay.startDiagnostics()
 
 local storedPort = plugin:GetSetting(SETTING_PORT)
 if typeof(storedPort) == "number" then
@@ -887,6 +889,7 @@ button.Click:Connect(function()
 end)
 
 plugin.Unloading:Connect(function()
+	ClientRelay.stopDiagnostics()
 	Transport.stop()
 end)
 

package/scripts/test-bridge.mjs

@@ -297,7 +297,7 @@ function twoStudios() {
       probe.close(() => resolve(free));
     });
   });
-  const server = await startBridgeServer({ port });
+  const server = await startBridgeServer({ port, bridge: new Bridge({ reconnectGraceMs: 100 }) });
   const open = () =>
     new Promise((resolve) => {
       const req = request(
@@ -312,7 +312,7 @@ function twoStudios() {
   const count = async () =>
     (await (await fetch(`http://127.0.0.1:${port}/sessions`, { headers: { "x-roblox-studio-mcp": "test" } })).json())
       .list.length;
-  const settle = () => new Promise((resolve) => setTimeout(resolve, 150));
+  const settle = () => new Promise((resolve) => setTimeout(resolve, 250));
 
   const first = await open();
   const second = await open();
@@ -321,7 +321,48 @@ function twoStudios() {
   assert.equal(await count(), 1, "the old stream closing leaves the new session alone");
   second.destroy();
   await settle();
-  assert.equal(await count(), 0, "a stream that dies without a goodbye is dropped");
+  assert.equal(await count(), 0, "a stream that dies without a goodbye is dropped after the grace");
+
+  // A stream that closes and redials inside the grace keeps its session, its
+  // agent's chosen target, and a call issued during the gap.
+  {
+    const before = await open();
+    await server.bridge.setActive("crashy");
+    before.destroy();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    const during = server.bridge.call("studio.ping", {}, { timeoutMs: 2_000 });
+    const events = [];
+    const after = await new Promise((resolve) => {
+      const req = request(
+        { host: "127.0.0.1", port, path: "/events", method: "POST", headers: { "x-roblox-studio-mcp": "test" } },
+        (res) => {
+          res.setEncoding("utf8");
+          res.on("data", (chunk) => {
+            for (const block of chunk.split("\n\n")) {
+              if (!block.startsWith("data: ")) continue;
+              const frame = JSON.parse(block.slice(6));
+              if (typeof frame.id !== "string") continue;
+              events.push(frame);
+              void fetch(`http://127.0.0.1:${port}/result?studioId=crashy`, {
+                method: "POST",
+                headers: { "x-roblox-studio-mcp": "test" },
+                body: JSON.stringify({ id: frame.id, ok: true, data: "pong" }),
+              });
+            }
+          });
+          resolve(req);
+        },
+      );
+      req.end(JSON.stringify({ studioId: "crashy", placeName: "p", placeId: 1 }));
+    });
+    assert.equal(await during, "pong", "a call made while redialling is delivered on the new stream");
+    assert.equal(events.length, 1);
+    await settle();
+    const view = await server.bridge.sessions();
+    assert.equal(view.list.length, 1, "the redialled session is still listed after the grace");
+    assert.equal(view.activeIsChosen, true, "and the agent's chosen target survived");
+    after.destroy();
+  }
 
   // A command far bigger than one socket read goes down the stream as ONE
   // event, and its answer comes back. The plugin half of this -- joining the
@@ -402,4 +443,41 @@ function twoStudios() {
  }
 }
 
+// A poll whose socket closed while parked must not swallow the next command.
+{
+  const bridge = new Bridge();
+  bridge.attach(identity("poll-drop", 1), null);
+  const released = new AbortController();
+  const parked = bridge.waitForCommand("poll-drop", released.signal);
+  released.abort();
+  assert.equal(await parked, null, "an abandoned poll resolves empty");
+  assert.equal(bridge.sessions.get("poll-drop").waiter, null, "and leaves no waiter behind");
+
+  const result = bridge.call("studio.ping", {}, { clientId: "test", studioId: "poll-drop" });
+  assert.equal(bridge.sessions.get("poll-drop").queue.length, 1, "the command waits in the queue");
+
+  // One handed to a poll that died anyway goes back to the front.
+  const command = await bridge.waitForCommand("poll-drop");
+  bridge.requeue("poll-drop", command);
+  const again = await bridge.waitForCommand("poll-drop");
+  assert.equal(again.id, command.id, "the requeued command is picked up next");
+  bridge.settle("poll-drop", { id: again.id, ok: true, data: "pong" });
+  assert.equal(await result, "pong");
+
+  // Nothing is requeued for a call that already settled.
+  bridge.requeue("poll-drop", command);
+  assert.equal(bridge.sessions.get("poll-drop").queue.length, 0, "settled calls are not resent");
+  bridge.detach("poll-drop");
+}
+
+// A resolved published name survives the plugin reconnecting.
+{
+  const bridge = new Bridge();
+  bridge.attach(identity("named", 1), null);
+  bridge.notePlaceName("named", "My Game");
+  bridge.attach({ ...identity("named", 1), placeName: "Place3" }, null);
+  assert.equal(bridge.list()[0].placeName, "My Game", "reconnect keeps the published name");
+  bridge.detach("named");
+}
+
 process.stdout.write("bridge: ok\n");

package/scripts/test-live.mjs

@@ -12,7 +12,7 @@
  * Everything it makes is named `__mcp_live_*` under ServerScriptService and is
  * deleted before it exits, pass or fail.
  *
- * Usage: node scripts/test-live.mjs [--port 44755] [--sizes 1000,16000,64000,256000] [--client] [--remotes] [--playtests-off] [--studio-id ID] [--player NAME]
+ * Usage: node scripts/test-live.mjs [--port 44755] [--sizes 1000,16000,64000,256000] [--client] [--remotes] [--playtest-start] [--playtest-op play|multiplayer] [--stale-cursor CURSOR] [--playtests-off] [--studio-id ID] [--player NAME]
  */
 import { expectedPluginBuildId } from "../dist/lib/pluginbuild.js";
 
@@ -42,6 +42,16 @@ async function call(op, params, timeoutMs = 20_000) {
   return body.data;
 }
 
+async function callTo(studioId, op, params, timeoutMs = 20_000) {
+  const response = await fetch(`${base}/call`, {
+    method: "POST", headers: HEADERS,
+    body: JSON.stringify({ op, params, timeoutMs, studioId }),
+  });
+  const body = await response.json();
+  if (!body.ok) throw new Error(`${op}: [${body.error?.code}] ${body.error?.message}`);
+  return body.data;
+}
+
 /** Luau source of about `size` bytes, with quotes and non-ASCII so escaping is exercised. */
 function sourceOf(size) {
   const lines = [];
@@ -125,6 +135,40 @@ if (args.includes("--client")) {
     try {
       const identity = await client('return game:GetService("RunService"):IsClient(), game:GetService("Players").LocalPlayer.Name');
       check(identity.ok && identity.returned[0] === true && typeof identity.returned[1] === "string", "exec runs in the actual client VM");
+      const playerName = identity.returned[1];
+      const baseline = await call("perf.console", {target:"client",player:playerName,limit:10});
+      check(baseline.capturing === true && typeof baseline.nextCursor === "string", "persistent client diagnostics relay is ready");
+      const diagnosticPath = `Players.${playerName}.PlayerGui.__mcp_live_diagnostics`;
+      try {
+        await call("script.create", {scripts:[{parent:`Players.${playerName}.PlayerGui`,name:"__mcp_live_diagnostics",className:"LocalScript",source:'print("mcp live client print"); warn("mcp live client warning"); error("mcp live client error")'}]});
+        let captured;
+        for (let attempt = 0; attempt < 20; attempt += 1) {
+          captured = await call("perf.console", {target:"client",player:playerName,since:baseline.nextCursor,limit:20});
+          if (captured.items.some(item => item.message.includes("mcp live client error"))) break;
+          await new Promise(resolve => setTimeout(resolve, 200));
+        }
+        check(captured.items.some(item => item.message.includes("mcp live client print") && item.level === "print") &&
+          captured.items.some(item => item.message.includes("mcp live client warning") && item.level === "warning") &&
+          captured.items.some(item => item.message.includes("mcp live client error") && item.level === "error"),
+          "console captures LocalScript output outside execute_luau");
+        check(captured.items.some(item => item.level === "error" && item.stack && item.source), "client errors include stack and source");
+        const incremental = await call("perf.console", {target:"client",player:playerName,since:captured.nextCursor,limit:20});
+        check(incremental.items.length === 0, "client console cursor does not repeat old output");
+        const runtimeState = await call("playtest.control", {op:"state"});
+        const other = runtimeState.state.players?.find(player => player.name !== playerName);
+        if (other) {
+          const second = await call("perf.console", {target:"client",player:other.name,limit:20});
+          check(!second.items.some(item => item.message.includes("mcp live client error")), "multiplayer client logs stay with their player");
+          try {
+            await call("perf.console", {target:"client",player:other.name,since:captured.nextCursor});
+            check(false, "a cursor from another player is rejected");
+          } catch (cause) {
+            check(cause.message.includes("BAD_CURSOR"), "a cursor from another player is rejected");
+          }
+        }
+      } finally {
+        await call("instances.delete", {paths:[diagnosticPath]}).catch(() => {});
+      }
       const values = await client('print("client print"); warn("client warning"); local t = {}; t.self = t; return 1, nil, t, Vector3.new(1,2,3)');
       check(values.ok && values.returned[1] === "nil" && values.returned[2].self === "<circular reference>", "client structured values preserve nil and cycles");
       check(values.output.some(v => v.message.includes("client print")) && values.output.some(v => v.level === "warning"), "client prints and warnings captured");
@@ -279,5 +323,66 @@ if (args.includes("--playtests-off")) {
   }
 }
 
+// Starts a real playtest through the public tool handler, proving its returned
+// ID is the attached server session. Run only from an edit session, opt in.
+if (args.includes("--playtest-start")) {
+  const { z } = await import("zod");
+  const { registerPlaytestTools } = await import("../dist/tools/playtest.js");
+  let handler, spec;
+  const bridge = {
+    sessions: async () => (await (await fetch(`${base}/sessions`, {headers:HEADERS})).json()),
+    call: (op, params, options = {}) => callTo(options.studioId ?? studio.studioId, op, params, options.timeoutMs),
+    notePlaceName: async () => {},
+  };
+  registerPlaytestTools({bridge,server:{registerTool(_name, definition, invoke) {spec = definition; handler = invoke;}}});
+  let startedId;
+  let started = false;
+  const startOp = flag("playtest-op", "play");
+  if (!["play", "multiplayer"].includes(startOp)) throw new Error("--playtest-op must be play or multiplayer");
+  try {
+    const before = await callTo(studio.studioId, "playtest.control", {op:"state"});
+    if (!before.state.isEdit || before.state.playtestsAllowed === false) {
+      check(false, "--playtest-start needs an edit session with playtests enabled");
+    } else {
+      started = true;
+      const result = await handler(z.object(spec.inputSchema).parse({op:startOp,players:2,studioId:studio.studioId}));
+      const id = /"studioId": "([^"]+)"/.exec(result.content[0].text)?.[1];
+      startedId = id;
+      const sessions = await bridge.sessions();
+      check(Boolean(id && id !== studio.studioId && sessions.list.some(s => s.studioId === id && s.context?.includes("playtest"))), "playtest returns its connected server studioId directly");
+      const state = id ? await callTo(id, "playtest.control", {op:"state"}) : null;
+      if (state?.state.players?.length && !result.content[0].text.includes("players are still joining"))
+        check(/"players": \[/.test(result.content[0].text), "playtest includes available player identities");
+      if (startOp === "multiplayer") {
+        const reply = result.content[0].text;
+        const named = state?.state.players?.length === 2 && state.state.players.every(player => reply.includes(`"name": "${player.name}"`));
+        check(named || reply.includes("players are still joining"), "multiplayer returns player names when connected, or identifies late joins");
+      }
+      const staleCursor = flag("stale-cursor", undefined);
+      if (id && staleCursor) {
+        let players = state?.state.players;
+        for (let attempt = 0; !players?.length && attempt < 20; attempt += 1) {
+          await new Promise(resolve => setTimeout(resolve, 250));
+          players = (await callTo(id, "playtest.control", {op:"state"})).state.players;
+        }
+        if (players?.length) {
+          try {
+            await callTo(id, "perf.console", {target:"client",player:players[0].name,since:staleCursor});
+            check(false, "a client cursor from the prior playtest is rejected");
+          } catch (cause) {
+            check(cause.message.includes("BAD_CURSOR"), "a client cursor from the prior playtest is rejected");
+          }
+        } else check(false, "a player must join to check the prior playtest cursor");
+      }
+    }
+  } catch (cause) {
+    check(false, `playtest returned ID: ${cause.message}`);
+  } finally {
+    const sessions = await bridge.sessions().catch(() => ({list:[]}));
+    const target = startedId ?? (started ? sessions.list.find(s => s.studioId !== studio.studioId && s.context?.includes("playtest"))?.studioId : undefined);
+    if (target) await callTo(target, "playtest.control", {op:"endTest",value:"live check complete"}).catch(() => {});
+  }
+}
+
 process.stdout.write(failures === 0 ? "live: ok\n" : `live: ${failures} failure(s)\n`);
 process.exit(failures === 0 ? 0 : 1);

package/scripts/test-plugin.mjs

@@ -33,6 +33,8 @@ const suites = [
   { module: "plugin/src/RemoteTrace.luau", test: "tests/remote-trace.luau", prelude: "tests/remote-trace-stub.luau" },
   { module: "plugin/src/ExecRuntime.luau", test: "tests/exec-runtime.luau", prelude: "tests/exec-runtime-stub.luau" },
   { module: "plugin/src/ClientRelay.luau", test: "tests/client-relay.luau", prelude: "tests/client-relay-stub.luau" },
+  { module: "plugin/src/LogBuffer.luau", test: "tests/log-buffer.luau", prelude: "tests/log-buffer-stub.luau" },
+  { module: "plugin/src/handlers/Perf.luau", test: "tests/perf-console.luau", prelude: "tests/perf-console-stub.luau" },
   { module: "plugin/src/TextEdit.luau", test: "tests/textedit.luau" },
   { module: "plugin/src/Format.luau", test: "tests/format.luau" },
 ];

package/scripts/test-tools.mjs

@@ -46,7 +46,7 @@ const registered = new Map();
 const calls = [];
 const context = {
   server: { registerTool(name, spec, handler) { registered.set(name, { spec, handler }); } },
-  bridge: { async call(op, params, options) {
+  bridge: { async sessions() { return {list:[]}; }, async call(op, params, options) {
     calls.push({op, params, options});
     return op === "exec.run" ? {ok:true,returned:["nil",{answer:42}],output:[],milliseconds:1} : {delivered:true,steps:1,player:"Alice"};
   } },
@@ -118,6 +118,36 @@ assert.ok(!stateResult.isError);
 context.bridge.call = normalCall;
 process.stdout.write("playtest lock errors and instruction precedence: ok\n");
 
+// A successful start includes the newly attached runtime session and player
+// names, using the same discovery path as stop. The editor ID is excluded.
+{
+ let started = false;
+ let operation = "play";
+ const originalSessions = context.bridge.sessions;
+ const originalCall = context.bridge.call;
+ context.bridge.sessions = async () => ({list: started
+   ? [{studioId:"editor",context:"edit"},{studioId:"runtime",context:"playtest server"}]
+   : [{studioId:"editor",context:"edit"}]});
+ context.bridge.call = async (op, params, options) => {
+  assert.equal(op, "playtest.control");
+  if (params.op === operation) {
+   started = true;
+   return {changed:true,state:{testPending:true,isRunning:false}};
+  }
+  assert.equal(options.studioId, "runtime");
+  return {changed:false,state:{players:operation === "multiplayer" ? [{name:"Alice",userId:123},{name:"Bob",userId:456}] : [{name:"Alice",userId:123}]}};
+ };
+ for (operation of ["play", "multiplayer"]) {
+  started = false;
+  const result = await playtest.handler(z.object(playtest.spec.inputSchema).parse({op:operation,studioId:"editor"}));
+  assert.match(result.content[0].text, /"studioId": "runtime"/);
+  assert.match(result.content[0].text, /"name": "Alice"/);
+ }
+ context.bridge.sessions = originalSessions;
+ context.bridge.call = originalCall;
+}
+process.stdout.write("playtest runtime identity: ok\n");
+
 // OFF affects simulation starts, not the ordinary edit-mode tool paths.
 const { registerDiscoverTools } = await import("../dist/tools/discover.js");
 const { registerScriptTools } = await import("../dist/tools/scripts.js");
@@ -160,3 +190,27 @@ for (const [name, args, expected] of [
 assert.ok(!editOps.includes("playtest.control"), "edit-mode tools never start or probe a simulation");
 context.bridge.call = normalCall;
 process.stdout.write("playtest lock leaves edit-mode tools available: ok\n");
+
+const { registerPerfTools } = await import("../dist/tools/perf.js");
+registerPerfTools(context);
+const consoleTool = registered.get("console");
+const consoleArgs = z.object(consoleTool.spec.inputSchema).parse({target:"client",player:"Alice",studioId:"runtime",since:"cursor-1",limit:10});
+context.bridge.call = async (op, params, options) => {
+ assert.equal(op, "perf.console");
+ assert.equal(params.target, "client");
+ assert.equal(params.player, "Alice");
+ assert.equal(params.since, "cursor-1");
+ assert.equal(options.studioId, "runtime");
+ return {items:[],total:0,dropped:0,evicted:2,nextCursor:"cursor-2",capturing:true};
+};
+const consoleResult = await consoleTool.handler(consoleArgs);
+assert.match(consoleResult.content[0].text, /2 older lines were evicted/);
+assert.match(consoleResult.content[0].text, /nextCursor: cursor-2/);
+context.bridge.call = async () => ({
+ items: Array.from({length:60}, (_, index) => ({level:"print",message:`${index} ${"x".repeat(1000)}`})),
+ total:60,dropped:0,nextCursor:"cursor-3",
+});
+const boundedConsole = await consoleTool.handler(z.object(consoleTool.spec.inputSchema).parse({}));
+assert.ok(boundedConsole.content[0].text.length < 25_000);
+assert.match(boundedConsole.content[0].text, /older matching lines omitted/);
+process.stdout.write("client console schema and cursor forwarding: ok\n");