@el4cteo/rbx-studio-mcp 0.1.6 → 0.2.7

package/plugin/src/handlers/World.luau

@@ -147,6 +147,25 @@ function World.collision(params: { [string]: any }): { [string]: any }
 		return { group = name, assigned = #assigned, parts = assigned, undoable = undoable }
 	end
 
+	if action == "remove" then
+		--[[
+			Registering a group is one line and nothing here undid it: create,
+			assign and collidable all had a way back through the ordinary undo
+			stack, and this did not, because nothing called it at all. Over a
+			session that experiments -- try a group, decide against it -- that
+			leaves the place permanently carrying a group nobody wants, with no
+			way to remove it short of `execute_luau`. `UnregisterCollisionGroup`
+			has existed the whole time; it was just never wired up.
+		]]
+		local ok, err = pcall(function()
+			PhysicsService:UnregisterCollisionGroup(name)
+		end)
+		if not ok then
+			Dispatch.fail("COLLISION_FAILED", string.format("Could not remove %q: %s", name, tostring(err)))
+		end
+		return { group = name, removed = true }
+	end
+
 	if action == "collidable" then
 		local other = params.with
 		if typeof(other) ~= "string" or other == "" then

package/plugin/src/init.server.luau

@@ -1,6 +1,6 @@
 --!strict
 --[[
-	Studio MCP -- plugin entry point.
+	rbx-studio -- plugin entry point.
 
 	Owns the toolbar UI, this window's Studio identity, and the command loop.
 	Handlers do the actual work; this file only wires them to the transport and
@@ -121,10 +121,10 @@ Input.register()
 Device.register()
 Api.register()
 
-local toolbar = plugin:CreateToolbar("Studio MCP")
+local toolbar = plugin:CreateToolbar("rbx-studio")
 local button = toolbar:CreateButton(
-	"Studio MCP",
-	"Show the Studio MCP console",
+	"rbx-studio",
+	"Show the rbx-studio console",
 	"rbxasset://textures/ui/common/robux.png"
 )
 button.ClickableWhenViewportHidden = true
@@ -136,7 +136,7 @@ local widget = plugin:CreateDockWidgetPluginGuiAsync(
 	"StudioMCP_Console",
 	DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, false, 560, 320, 360, 200)
 )
-widget.Title = "Studio MCP"
+widget.Title = "rbx-studio"
 
 local currentStatus: Transport.Status = "disconnected"
 
@@ -167,7 +167,7 @@ Console.mount(widget, {
 	end,
 })
 
-Console.log("info", string.format("Studio MCP v%s", Config.PLUGIN_VERSION), "build " .. Config.BUILD_ID)
+Console.log("info", string.format("rbx-studio v%s", Config.PLUGIN_VERSION), "build " .. Config.BUILD_ID)
 Console.log("dim", string.format("place: %s (%d)", game.Name, game.PlaceId))
 
 local function onStatus(status: Transport.Status, detail: string?)
@@ -210,12 +210,36 @@ local function onCommand(id: string, op: string, params: { [string]: any }?)
 			something needs debugging.
 		]]
 		local title = Phrase.of(op, params)
+		--[[
+			Announced synchronously, unlike the logging below.
+
+			Deferring this looked like free latency and was not. `beginCall` sets
+			two labels and some fields -- it never touches the RichText log, which
+			is where the cost actually is -- and deferring it let a call that
+			finished inside one frame record its result before the call had been
+			announced, so the bar on the trace lost the name it was supposed to
+			carry. A microsecond is not worth an ordering hazard.
+		]]
 		Console.beginCall(title, Phrase.kindOf(op))
 
 		local result = Dispatch.invoke(id, op, params)
-		local elapsed = string.format("%.0fms", (os.clock() - startedAt) * 1000)
+		local milliseconds = (os.clock() - startedAt) * 1000
 
-		Console.recordCall(result.ok, (os.clock() - startedAt) * 1000)
+		--[[
+			The answer goes out before the console hears about it.
+
+			This used to be the last line of the function, which put a
+			`table.concat` of three hundred strings, a RichText relayout of the
+			whole log, two `Instance.new` calls and a forty-bar relayout in front
+			of the reply on its way back to the agent. None of that is work the
+			caller asked for, and all of it was being billed to the round trip
+			this project measures. Drawing happens below, on time the agent is no
+			longer waiting for.
+		]]
+		Transport.sendResult(result)
+
+		local elapsed = string.format("%.0fms", milliseconds)
+		Console.recordCall(result.ok, milliseconds)
 
 		if result.ok then
 			Console.log("reply", title, elapsed)
@@ -230,11 +254,24 @@ local function onCommand(id: string, op: string, params: { [string]: any }?)
 				Console.log("dim", "   " .. err.message)
 			end
 		end
-
-		Transport.sendResult(result)
 	end)
 end
 
+--[[
+	Bridge news that is not a command.
+
+	Kept deliberately narrow: an unknown event is ignored rather than logged,
+	because a newer server talking to an older plugin is a supported situation
+	and "unknown event" rows would be the only symptom of it working correctly.
+]]
+local function onEvent(event: { [string]: any })
+	if event.event == "clients" and typeof(event.count) == "number" then
+		Console.setClients(event.count)
+	elseif event.event == "agent" and event.state == "finished" then
+		Console.agentFinished()
+	end
+end
+
 function connect()
 	local allowed, reason = canConnect()
 	if not allowed then
@@ -249,7 +286,7 @@ function connect()
 		Console.setCaption("switch to the Server view to watch this playtest")
 		return
 	end
-	Transport.start(studioId(), { onCommand = onCommand, onStatus = onStatus })
+	Transport.start(studioId(), { onCommand = onCommand, onStatus = onStatus, onEvent = onEvent })
 	plugin:SetSetting(SETTING_AUTOCONNECT, true)
 end
 

package/scripts/check-plugin.mjs

@@ -72,14 +72,34 @@ for (const file of files) {
  * filtering to this one diagnostic gets the signal without needing a
  * definitions file that would then have to be kept current with the engine.
  */
+/*
+ * Diagnostics about a table this file declares its own type for.
+ *
+ * The LocalShadow filter was the only thing let through, and that let a whole
+ * class of error ship: a field read or written on a `--!strict` table type that
+ * does not declare it. The plugin failed to load on the first line it logged --
+ * "attempt to perform arithmetic on nil" -- because a batch of edits added five
+ * uses of `state.entries` and the edit declaring it never landed. The analyser
+ * had said so, four times, and this script threw it away.
+ *
+ * These two patterns are safe to surface where the rest is not. Without Roblox
+ * type definitions the analyser cannot know what `Instance` or `Color3` are, so
+ * it reports engine globals in their hundreds -- but those come out as unknown
+ * *globals* and unknown *types*. A key missing from a named table type can only
+ * be a table this file declared itself.
+ */
+const TYPE_PATTERNS = [/Key '[^']+' not found in table/, /Cannot add property '[^']+' to table/];
+
 const analyser = locateLuau("LUAU_ANALYZE", ["luau-analyze.exe", "luau-analyze"]);
 const shadowed = [];
+const mistyped = [];
 if (analyser !== null) {
   for (const file of files) {
     const result = spawnSync(analyser, [file], { encoding: "utf8" });
     const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
     for (const line of output.split("\n")) {
       if (line.includes("LocalShadow:")) shadowed.push(line.trim());
+      else if (TYPE_PATTERNS.some((pattern) => pattern.test(line))) mistyped.push(line.trim());
     }
   }
 }
@@ -94,4 +114,12 @@ if (shadowed.length > 0) {
       `${shadowed.join("\n")}\n`,
   );
 }
-process.exit(failures.length > 0 || shadowed.length > 0 ? 1 : 0);
+if (mistyped.length > 0) {
+  process.stderr.write(
+    "\nA field is used on a table whose type does not declare it. It is nil at " +
+      "runtime, and the plugin fails the first time that line runs:\n" +
+      `${mistyped.join("\n")}
+`,
+  );
+}
+process.exit(failures.length > 0 || shadowed.length > 0 || mistyped.length > 0 ? 1 : 0);

package/scripts/test-bridge.mjs

@@ -20,6 +20,7 @@ const identity = (studioId, placeId) => ({
   placeId,
   pluginVersion: "test",
   buildId: "test",
+  protocolVersion: 1,
   transport: "poll",
   context: "edit",
 });
@@ -105,3 +106,106 @@ function twoStudios() {
     "but the survivor was never chosen",
   );
 }
+
+/**
+ * Counting the agents that share one bridge, and noticing when one leaves.
+ *
+ * The Studio console shows this count and announces the departure, so getting
+ * it wrong is not a cosmetic fault -- it either claims a second agent is
+ * editing the user's place when none is, or stays silent when one really has
+ * gone. Both are the kind of wrong that is only visible from outside the
+ * process, which is what this covers.
+ */
+{
+  const bridge = new Bridge();
+  const seen = [];
+  bridge.watchClients((count) => seen.push(count));
+
+  assert.equal(bridge.clientCount(), 0, "a fresh bridge has no clients");
+
+  const alice = new LocalBridge(bridge);
+  assert.equal(bridge.clientCount(), 1, "constructing a local bridge registers it");
+
+  bridge.noteClient("peer-1");
+  assert.equal(bridge.clientCount(), 2, "a peer counts too");
+
+  bridge.noteClient("peer-1");
+  assert.equal(bridge.clientCount(), 2, "and saying hello twice is not two peers");
+
+  assert.deepEqual(seen, [1, 2], "only real changes are announced");
+
+  assert.equal(bridge.forgetClient("peer-1"), true, "goodbye drops the peer");
+  assert.equal(bridge.clientCount(), 1, "leaving one behind");
+  assert.equal(
+    bridge.forgetClient("peer-1"),
+    false,
+    "a repeated goodbye is not a second departure",
+  );
+  assert.deepEqual(seen, [1, 2, 1], "and is not announced twice");
+
+  // A client's chosen Studio goes with it, which is the leak forgetClient was
+  // written for and never called to fix.
+  bridge.attach(identity("studio-a", 111), null);
+  bridge.attach(identity("studio-b", 222), null);
+  await alice.setActive("studio-b");
+  assert.equal((await alice.sessions()).activeIsChosen, true, "alice chose one");
+  alice.goodbye();
+  assert.equal(bridge.clientCount(), 0, "and left");
+  assert.equal(
+    (await alice.sessions()).activeIsChosen,
+    false,
+    "taking her choice with her",
+  );
+}
+
+/** A client killed rather than closed is swept by the reaper. */
+{
+  const bridge = new Bridge();
+  bridge.noteClient("ghost");
+  assert.equal(bridge.clientCount(), 1, "the ghost registered");
+
+  bridge.reapStale();
+  assert.equal(bridge.clientCount(), 1, "a fresh client survives a sweep");
+
+  // Reach past the clock rather than wait ninety seconds for it.
+  const original = Date.now;
+  Date.now = () => original() + 120_000;
+  try {
+    bridge.reapStale();
+  } finally {
+    Date.now = original;
+  }
+  assert.equal(bridge.clientCount(), 0, "a silent one does not");
+}
+
+/**
+ * The bridge must not sweep away the process it is running inside.
+ *
+ * It did. `LocalBridge` announced itself once at construction and nothing ever
+ * refreshed it, so ninety seconds later the reaper -- which cannot tell an
+ * absent client from a quiet one -- dropped the owner from its own client list
+ * while it was actively serving. The count then read one short, and the drop
+ * was broadcast to the Studio console as an agent having finished. Found by a
+ * user asking why the panel said three clients when there was one.
+ */
+{
+  const bridge = new Bridge();
+  const owner = new LocalBridge(bridge);
+  bridge.attach(identity("studio-a", 111), null);
+  assert.equal(bridge.clientCount(), 1, "the owner counts as a client");
+
+  const real = Date.now;
+  Date.now = () => real() + 120_000;
+  try {
+    // Working is what proves it is here, and the owner works constantly.
+    await owner.sessions();
+    bridge.reapStale();
+  } finally {
+    Date.now = real;
+  }
+  assert.equal(bridge.clientCount(), 1, "an owner that is working is not stale");
+
+  // And it still goes when it actually goes.
+  owner.goodbye();
+  assert.equal(bridge.clientCount(), 0, "goodbye still drops it");
+}

package/scripts/test-transport.mjs

@@ -0,0 +1,58 @@
+/**
+ * Exercises the plugin's SSE frame parser outside Studio.
+ *
+ * `Transport.luau` cannot be loaded whole by the interpreter -- it reaches for
+ * HttpService at module scope -- and `parseFrames` is a local, so neither the
+ * existing bundling harness nor a plain require can get at it. It is lifted out
+ * of the real file by name instead, so this cannot quietly drift from what ships:
+ * rename or delete the function and the extraction fails the test run.
+ *
+ * The bug it covers cost a session to find and would have been invisible in
+ * review. Two SSE writes in the same tick arrive as one chunk, and the old
+ * parser JSON-decoded the whole chunk, so BOTH frames were dropped. It showed up
+ * as a client-count badge that would not come back down; the part that mattered
+ * is that a command sharing a chunk with a keepalive would have vanished the
+ * same way, losing a tool call with no error at either end.
+ *
+ * Usage: node scripts/test-transport.mjs
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { locateLuau, missingLuau } from "./locate-luau.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const luau = locateLuau("LUAU", ["luau.exe", "luau"]);
+if (luau === null) {
+  process.stderr.write(missingLuau("luau", "LUAU"));
+  process.exit(1);
+}
+
+/** Lifts one top-level `local function` out of a module, body and all. */
+function extractFunction(source, name) {
+  // Normalised first: the plugin sources are CRLF and every anchor here is LF.
+  const text = source.split(String.fromCharCode(13, 10)).join(String.fromCharCode(10));
+  const opener = `local function ${name}(`;
+  const start = text.indexOf(opener);
+  if (start === -1) throw new Error(`${name} is not in Transport.luau any more`);
+  const closer = String.fromCharCode(10) + 'end' + String.fromCharCode(10);
+  const end = text.indexOf(closer, start);
+  if (end === -1) throw new Error(`could not find the end of ${name}`);
+  return text.slice(start, end + closer.length).replace(opener, `function ${name}(`);
+}
+const transport = readFileSync(join(root, "plugin", "src", "Transport.luau"), "utf8");
+const stub = readFileSync(join(root, "tests", "jsonstub.luau"), "utf8").replace(/^return Net$/m, "");
+const cases = readFileSync(join(root, "tests", "sseframes.luau"), "utf8");
+
+const bundle = [stub, extractFunction(transport, "parseFrames"), cases].join("\n");
+const bundlePath = join(mkdtempSync(join(tmpdir(), "studio-mcp-sse-")), "bundle.luau");
+writeFileSync(bundlePath, bundle, "utf8");
+
+const result = spawnSync(luau, [bundlePath], { stdio: "inherit" });
+if (result.error) {
+  process.stderr.write(`could not run '${luau}': ${result.error.message}\n`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);