@el4cteo/rbx-studio-mcp 0.8.2 → 0.8.4

package/plugin/src/handlers/Viewport.luau

@@ -67,6 +67,20 @@ function Viewport.raycast(params: { [string]: any }): { [string]: any }
 	local direction = toVector(params.direction, "direction")
 	local length = tonumber(params.maxDistance) or DEFAULT_RAY_LENGTH
 
+	--[[
+		A zero direction has no `Unit` -- it is NaN -- and a ray along NaN hits
+		nothing, which the reply then reported as "nothing within 1000 studs". That
+		is a confident answer about empty space to a question that was never asked,
+		so the input is refused instead.
+	]]
+	if direction.Magnitude == 0 then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			"`direction` cannot be zero: a ray needs a way to point.",
+			'Give a direction such as "0, -1, 0" for straight down.'
+		)
+	end
+
 	local filter: { Instance } = {}
 	for _, path in (params.ignore or {}) :: { string } do
 		table.insert(filter, Paths.resolve(path))
@@ -225,7 +239,17 @@ function Viewport.focus(params: { [string]: any }): { [string]: any }
 	-- with a flat surface where it would vanish to a line.
 	local direction: Vector3
 	if typeof(params.from) == "string" and params.from ~= "" then
-		direction = toVector(params.from, "`from`").Unit
+		local requested = toVector(params.from, "`from`")
+		-- A zero vector has no direction: its `Unit` is NaN, so the eye position was
+		-- NaN and the camera was handed a CFrame that is not a place at all.
+		if requested.Magnitude == 0 then
+			Dispatch.fail(
+				"BAD_PARAMS",
+				"`from` cannot be zero: it is the direction to view the subject from.",
+				'Give a direction such as "0, 1, 0" to look down from above.'
+			)
+		end
+		direction = requested.Unit
 	else
 		direction = Vector3.new(0.45, 0.35, 1).Unit
 	end
@@ -278,6 +302,14 @@ function Viewport.camera(params: { [string]: any }): { [string]: any }
 		local target = if params.lookAt ~= nil
 			then toVector(params.lookAt, "`lookAt`")
 			else eye + view.CFrame.LookVector
+		-- Aiming at where the camera already is has no direction to face.
+		if (target - eye).Magnitude == 0 then
+			Dispatch.fail(
+				"BAD_PARAMS",
+				"`position` and `lookAt` are the same point, so there is nothing to face.",
+				"Move `lookAt` to what the camera should be looking at."
+			)
+		end
 		view.CFrame = CFrame.lookAt(eye, target)
 		-- Same reason as focus: without this the rotation survives a frame.
 		view.Focus = CFrame.new(target)

package/plugin/src/handlers/World.luau

@@ -257,13 +257,33 @@ function World.collision(params: { [string]: any }): { [string]: any }
 			way to remove it short of `execute_luau`. `UnregisterCollisionGroup`
 			has existed the whole time; it was just never wired up.
 		]]
+		--[[
+			The engine unregisters a group that was never registered without a word,
+			so a misspelt name answered `removed = true` and removed nothing -- while
+			the group the caller meant stayed registered. Said plainly instead, and
+			not as an error: removing something already gone is a cleanup that
+			worked, and treating it as a failure would break every loop that ends
+			by tidying up.
+		]]
+		local okRegistered, registered = pcall(function()
+			return world:IsCollisionGroupRegistered(name)
+		end)
+		if okRegistered and registered == false then
+			return {
+				group = name,
+				removed = false,
+				existed = false,
+				world = Paths.of(world),
+				note = 'No group by that name is registered, so nothing was removed. Check the spelling with action="list".',
+			}
+		end
 		local ok, err = pcall(function()
 			world: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, world = Paths.of(world) }
+		return { group = name, removed = true, existed = true, world = Paths.of(world) }
 	end
 
 	if action == "collidable" then

package/plugin/src/init.server.luau

@@ -65,6 +65,9 @@ local SETTING_WIDGET_OPEN = "widgetOpen"
 ]]
 local SETTING_AUTO_OPEN = "autoOpen"
 local SETTING_PLAYTESTS = "playtestsEnabled"
+-- Whether sentences typed at the prompt are sent to an agent. Absent means off:
+-- it only turns on when the user runs `chat on`.
+local SETTING_CHAT = "chatEnabled"
 local SETTING_WIDGET_SIZE = "widgetSize"
 local SETTING_WIDGET_TRACE = "widgetTrace"
 
@@ -261,6 +264,8 @@ local wantOpen = if typeof(storedOpen) == "boolean" then storedOpen else true
 	left exactly as it was, so turning this back on restores the panel to however
 	it was last left rather than to a default.
 ]]
+local chat = plugin:GetSetting(SETTING_CHAT) == true
+
 local storedAutoOpen = plugin:GetSetting(SETTING_AUTO_OPEN)
 local autoOpen = if typeof(storedAutoOpen) == "boolean" then storedAutoOpen else true
 if not autoOpen then
@@ -398,10 +403,21 @@ local function trace(what: string)
 	end)
 end
 
+--[[
+	Set the moment the plugin starts to unload.
+
+	`persistSize` checked a variable of this name that was never declared, so it
+	read as nil and the guard never applied. A widget that is being torn down
+	reports whatever size it collapses through, and only the minimum-size check
+	stood between that and the saved layout.
+]]
+local unloading = false
+
 if RunService:IsEdit() then
 	trace(string.format("load open=%s", tostring(storedOpen)))
 
 	plugin.Unloading:Connect(function()
+		unloading = true
 		trace("plugin.Unloading")
 	end)
 	widget.Destroying:Connect(function()
@@ -549,12 +565,21 @@ Commands.setup({
 		autoOpen = value
 		plugin:SetSetting(SETTING_AUTO_OPEN, value)
 	end,
+	chat = function()
+		return chat
+	end,
+	saveChat = function(value)
+		chat = value
+		plugin:SetSetting(SETTING_CHAT, value)
+	end,
 	status = function()
 		return currentStatus
 	end,
 	studioId = studioId,
 })
 
+Console.setPromptChat(chat)
+
 -- The saved preset, now that there is something to paint. Done immediately
 -- after mounting and before the first line is logged, so nothing is ever drawn
 -- in the wrong palette.

package/scripts/check-plugin.mjs

@@ -136,6 +136,60 @@ const kindless = new Set();
   }
 }
 
+/*
+ * A module cloned into a client relay has to bring everything it requires.
+ *
+ * The relay is a LocalScript in the player's client VM, where the plugin's own
+ * module tree does not exist, so `require(script.Parent.X)` inside a cloned module
+ * finds only what was cloned beside it. ExecRuntime gained a `LogBuffer` require
+ * and the list of modules the exec relay clones did not, so every
+ * `execute_luau target="client"` failed with "Requested module experienced an
+ * error while loading" -- from a client VM nothing offline ever runs, and not
+ * noticed until a live playtest. Each clone list is checked here against the
+ * `require(script.Parent.X)` calls of the modules it names, transitively.
+ */
+const missingClones = [];
+{
+  const modules = new Map(
+    files.map((file) => [
+      file.replace(/\\/g, "/").replace(/^.*plugin\/src\//, "").replace(/\.luau$/, ""),
+      readFileSync(file, "utf8"),
+    ]),
+  );
+  const requiresOf = (name) =>
+    [...(modules.get(name) ?? "").matchAll(/require\(script\.Parent\.(\w+)\)/g)].map((m) => m[1]);
+
+  for (const [where, source] of modules) {
+    for (const list of source.matchAll(
+      /for _, name in \{([^}]*)\} do\s*local copy = script\.Parent\.Parent\[name\]:Clone\(\)/g,
+    )) {
+      const cloned = new Set([...list[1].matchAll(/"(\w+)"/g)].map((m) => m[1]));
+      const needed = new Set();
+      const pending = [...cloned];
+      while (pending.length > 0) {
+        for (const dependency of requiresOf(pending.pop())) {
+          if (!needed.has(dependency)) {
+            needed.add(dependency);
+            pending.push(dependency);
+          }
+        }
+      }
+      for (const dependency of needed) {
+        if (!cloned.has(dependency)) {
+          missingClones.push(`${where}: clones ${[...cloned].join(", ")} but they require ${dependency}`);
+        }
+      }
+    }
+  }
+}
+if (missingClones.length > 0) {
+  failures.push(
+    "A client relay clones modules that require others it does not clone, so the " +
+      "relay fails to load in the client VM:\n  " +
+      missingClones.sort().join("\n  "),
+  );
+}
+
 if (unnamed.length > 0) {
   failures.push(
     "These operations have no entry in Phrase.luau, so the Studio panel shows " +

package/scripts/test-apidump.mjs

@@ -0,0 +1,170 @@
+/**
+ * The API dump: its cache, how a long-lived server keeps it current, and what
+ * the discovery tools say from it.
+ *
+ * Run against a tiny fixture in a private temp directory, so nothing here reads
+ * the real cache or touches the network -- and so it cannot pass or fail on
+ * whether Roblox happened to be reachable.
+ *
+ * Usage: node scripts/test-apidump.mjs
+ */
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Redirected before anything is imported: the cache path is built from
+// os.tmpdir() at call time, and this keeps every read and write in the sandbox.
+const sandbox = mkdtempSync(join(tmpdir(), "rbx-apidump-test-"));
+for (const name of ["TMPDIR", "TEMP", "TMP"]) process.env[name] = sandbox;
+const cacheDir = join(sandbox, "roblox-studio-mcp");
+const cacheFile = join(cacheDir, "api-dump.json");
+
+const property = (name, type, extra = {}) => ({
+  MemberType: "Property",
+  Name: name,
+  ValueType: { Name: type, Category: "Primitive" },
+  ...extra,
+});
+const dumpOf = (extraClasses = []) => ({
+  Classes: [
+    { Name: "Instance", Superclass: "", Members: [property("Name", "string"), property("Archivable", "bool")] },
+    { Name: "Model", Superclass: "Instance", Members: [property("PrimaryPart", "BasePart")] },
+    {
+      Name: "Part",
+      Superclass: "Instance",
+      Members: [
+        property("Size", "Vector3"),
+        property("Anchored", "bool"),
+        // Above plugin identity: present in the dump, not reachable from here.
+        property("Secret", "string", { Security: { Read: "RobloxScriptSecurity", Write: "RobloxScriptSecurity" } }),
+      ],
+    },
+    ...extraClasses,
+  ],
+  Enums: [],
+});
+const widget = { Name: "Widget", Superclass: "Instance", Members: [property("Gizmo", "number")] };
+const seed = (dump, fetchedAt = Date.now()) => {
+  mkdirSync(cacheDir, { recursive: true });
+  writeFileSync(cacheFile, JSON.stringify({ fetchedAt, dump }));
+};
+const until = async (test, what) => {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (await test()) return;
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+  assert.fail(`timed out waiting for ${what}`);
+};
+
+const realFetch = globalThis.fetch;
+const realNow = Date.now;
+try {
+  // ---- what the dump answers ----------------------------------------------------
+  seed(dumpOf());
+  const dump = await import("../dist/lib/apidump.js");
+  const names = (await dump.propertiesOf("Part")).map((entry) => entry.name);
+  assert.deepEqual([...names].sort(), ["Anchored", "Archivable", "Name", "Size"], "own and inherited, nothing above plugin identity");
+  assert.ok((await dump.restrictionsOf("Part")).has("Secret"), "a restricted property is known about, separately");
+  assert.deepEqual(await dump.suggestProperty("Part", "size"), ["Size"], "a wrong-case name is suggested");
+  assert.deepEqual(await dump.suggestClass("Prat"), ["Part"], "a mistyped class is suggested");
+
+  // ---- what the tools say from it ----------------------------------------------------
+  const { z } = await import("zod");
+  const { registerDiscoverTools } = await import("../dist/tools/discover.js");
+  const registered = new Map();
+  const replies = {};
+  registerDiscoverTools({
+    server: { registerTool: (name, spec, handler) => registered.set(name, { spec, handler }) },
+    bridge: {
+      sessions: async () => ({ list: [], activeId: null, activeIsChosen: false }),
+      call: async (op) => replies[op],
+      notePlaceName: async () => {},
+    },
+  });
+  const run = (name, args) => {
+    const tool = registered.get(name);
+    return tool.handler(z.object(tool.spec.inputSchema).parse(args));
+  };
+  const textOf = (result) => result.content.map((part) => part.text ?? "").join("\n");
+
+  replies["discover.inspect"] = {
+    items: [{ path: "Workspace.P", className: "Part", childCount: 0, properties: { Name: "P", Size: "1, 1, 1" } }],
+    failures: [],
+  };
+  const inspected = textOf(await run("inspect", {
+    paths: ["Workspace.P"],
+    properties: ["Name", "Size", "Sizee", "Anchored", "Secret"],
+  }));
+  assert.match(inspected, /Requested but not returned:/);
+  assert.match(inspected, /Sizee \(not a property of Part; did you mean Size\?\)/, "a typo is named as one");
+  assert.match(inspected, /Anchored \(unset, or not readable in this session\)/, "a real property with no value is not called a typo");
+  assert.match(inspected, /Secret \(exists, but a plugin cannot read it\)/, "a restricted one says so");
+  assert.doesNotMatch(inspected.split("Requested but not returned:")[1], /\bName\b|\bSize \(/, "what did come back is not listed");
+
+  const complete = textOf(await run("inspect", { paths: ["Workspace.P"], properties: ["Name", "Size"] }));
+  assert.doesNotMatch(complete, /Requested but not returned/, "nothing to say when everything came back");
+
+  replies["discover.find"] = { items: [], total: 0, offset: 0, searched: 12 };
+  const misspelt = textOf(await run("find", { className: "Prat" }));
+  assert.match(misspelt, /"Prat" is not a Roblox class/);
+  assert.match(misspelt, /Did you mean: Part\?/);
+  const genuine = textOf(await run("find", { className: "Part" }));
+  assert.doesNotMatch(genuine, /is not a Roblox class/, "a real class that simply matched nothing is not accused");
+  const bare = textOf(await run("find", { nameContains: "zzz" }));
+  assert.doesNotMatch(bare, /is not a Roblox class/);
+
+  replies["discover.tree"] = { items: [], total: 0, offset: 0 };
+  assert.match(textOf(await run("tree", { className: "Prat" })), /"Prat" is not a Roblox class/);
+
+  // ---- a stale cache is served at once, then replaced in the running process ------------
+  // Each case gets its own copy of the module: the state under test is per process.
+  const fresh = (tag) => import(`../dist/lib/apidump.js?${tag}`);
+  const dayMs = 24 * 60 * 60 * 1000;
+  let downloads = 0;
+  const serve = (value) => {
+    globalThis.fetch = async () => {
+      downloads += 1;
+      return { ok: true, json: async () => value };
+    };
+  };
+
+  seed(dumpOf(), Date.now() - 3 * dayMs);
+  serve(dumpOf([widget]));
+  const stale = await fresh("stale");
+  assert.equal((await stale.propertiesOf("Widget")).length, 0, "the stale copy is what answers first");
+  await until(async () => (await stale.propertiesOf("Widget")).length > 0, "the refreshed dump to replace the stale one");
+  assert.equal(downloads, 1, "one download, however many calls were made meanwhile");
+  assert.ok((await stale.propertiesOf("Widget")).some((entry) => entry.name === "Gizmo"), "and the answers come from the new one");
+  assert.deepEqual(readdirSync(cacheDir), ["api-dump.json"], "the cache was replaced whole, leaving no staging file behind");
+  assert.ok(Date.now() - JSON.parse(readFileSync(cacheFile, "utf8")).fetchedAt < dayMs, "and is stamped as fresh");
+
+  // A fresh cache is not refreshed... until the process outlives it.
+  seed(dumpOf());
+  downloads = 0;
+  serve(dumpOf([widget]));
+  const longLived = await fresh("long-lived");
+  assert.equal((await longLived.propertiesOf("Widget")).length, 0);
+  assert.equal(downloads, 0, "a fresh cache needs no download");
+  Date.now = () => realNow() + 2 * dayMs;
+  await longLived.loadApiDump();
+  await until(async () => (await longLived.propertiesOf("Widget")).length > 0, "a process that outlived the cache to refresh it");
+  Date.now = realNow;
+  assert.equal(downloads, 1);
+
+  // A failed refresh leaves the old dump answering rather than emptying it.
+  seed(dumpOf(), Date.now() - 3 * dayMs);
+  globalThis.fetch = async () => {
+    throw new Error("offline");
+  };
+  const offline = await fresh("offline");
+  assert.ok((await offline.propertiesOf("Part")).length > 0, "no network, still answers from the stale copy");
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  assert.ok((await offline.propertiesOf("Part")).length > 0, "and still does after the refresh failed");
+
+  process.stdout.write("apidump: ok\n");
+} finally {
+  globalThis.fetch = realFetch;
+  Date.now = realNow;
+  rmSync(sandbox, { recursive: true, force: true });
+}

package/scripts/test-bridge.mjs

@@ -273,10 +273,16 @@ function twoStudios() {
   bridge.setActiveForAll("studio-b");
   const late = new LocalBridge(bridge);
   assert.equal((await late.sessions()).activeId, "studio-b");
-  await late.call("studio.ping", {}, { timeoutMs: 50 }).catch((cause) => {
-    assert.notEqual(cause.code, "AMBIGUOUS_STUDIO", "the user's pick routes the call");
-  });
+  const routed = late.call("studio.ping", {}, { timeoutMs: 50 });
+  // Read while the call is outstanding: once it times out the command is taken
+  // back off the queue, so the queue is only evidence of routing until then.
   assert.equal(bridge.sessions.get("studio-b").queue.length, 1, "the call went to the pick");
+  assert.equal(bridge.sessions.get("studio-a").queue.length, 0, "and not to the other one");
+  await assert.rejects(
+    routed,
+    (cause) => cause.code === "TIMEOUT",
+    "the user's pick routes the call, so it fails by timing out and not as ambiguous",
+  );
 
   await assert.rejects(
     async () => late.call("studio.ping", {}, { studioId: "gone", timeoutMs: 50 }),
@@ -285,6 +291,83 @@ function twoStudios() {
   );
 }
 
+/**
+ * A call that has timed out must not be run afterwards.
+ *
+ * The timeout answered the agent with a failure and dropped the request from the
+ * in-flight table, but left the command on the queue. The plugin's next poll --
+ * or the next stream to connect -- then picked it up and ran it: a create or a
+ * delete nobody was waiting for any more, usually after the agent had retried it.
+ */
+{
+  const bridge = new Bridge();
+  bridge.attach(identity("studio-a", 111), null);
+
+  await assert.rejects(
+    bridge.call("studio.ping", {}, { clientId: "c", timeoutMs: 20 }),
+    (cause) => cause.code === "TIMEOUT" && /never reached Studio/.test(cause.message),
+    "nothing collected it, and the error says so",
+  );
+  assert.equal(bridge.sessions.get("studio-a").queue.length, 0, "the abandoned command is gone");
+
+  // A poll arriving now has nothing to take, rather than the command that failed.
+  const held = new AbortController();
+  const waiting = bridge.waitForCommand("studio-a", held.signal);
+  setTimeout(() => held.abort(), 20);
+  assert.equal(await waiting, null, "a later poll is not handed the dead command");
+
+  // The same for a stream that connects after the deadline: nothing to flush.
+  const written = [];
+  const stream = {
+    writableEnded: false,
+    write(chunk) {
+      written.push(chunk);
+      return true;
+    },
+    end() {
+      this.writableEnded = true;
+    },
+  };
+  bridge.attach(identity("studio-a", 111), stream);
+  assert.deepEqual(written, [], "a reconnecting stream is not sent the dead command");
+
+  // And a live one is still delivered, so the queue is not simply being dropped.
+  const live = bridge.call("studio.ping", {}, { clientId: "c", timeoutMs: 1000 });
+  assert.equal(written.length, 1, "a command issued to an open stream is written at once");
+  const frame = JSON.parse(written[0].replace(/^data: /, ""));
+  bridge.settle("studio-a", { id: frame.id, ok: true, data: "pong" });
+  assert.equal(await live, "pong");
+}
+
+/**
+ * `call` returns a promise, so every way it can fail is a rejection.
+ *
+ * NO_STUDIO and UNKNOWN_STUDIO used to be thrown from inside `call`, before a
+ * promise existed. `bridge.call(...).catch(...)` -- how `playtest stop` shrugs
+ * off a session that closed under it -- never got the chance to catch them.
+ */
+{
+  const bridge = new Bridge();
+  let pending;
+  assert.doesNotThrow(() => {
+    pending = bridge.call("studio.ping", {}, { clientId: "c" });
+  }, "no Studio connected does not throw synchronously");
+  await assert.rejects(pending, (cause) => cause.code === "NO_STUDIO");
+
+  bridge.attach(identity("studio-a", 111), null);
+  assert.doesNotThrow(() => {
+    pending = bridge.call("studio.ping", {}, { clientId: "c", timeoutMs: -1 });
+  }, "a bad timeout does not throw synchronously");
+  await assert.rejects(pending, (cause) => cause.code === "BAD_TIMEOUT");
+
+  const local = new LocalBridge(bridge);
+  let caught = false;
+  await local.call("studio.ping", {}, { studioId: "gone" }).catch(() => {
+    caught = true;
+  });
+  assert.equal(caught, true, "a `.catch` on the local bridge sees an unknown Studio");
+}
+
 // A stream that dies without /bye (a crashed Studio) removes its session, and a
 // replaced stream closing late does not remove the session that replaced it.
 {
@@ -314,6 +397,28 @@ function twoStudios() {
       .list.length;
   const settle = () => new Promise((resolve) => setTimeout(resolve, 250));
 
+  // A page that rebinds its own hostname to 127.0.0.1 is same-origin as far as
+  // the browser is concerned: it can send the custom header without a preflight,
+  // and a same-origin GET carries no Origin to reject. What it cannot do is make
+  // the Host header say 127.0.0.1, so that is what is checked.
+  const statusFor = (host) =>
+    new Promise((resolve, reject) => {
+      const req = request(
+        { host: "127.0.0.1", port, path: "/sessions", method: "GET", headers: { host, "x-roblox-studio-mcp": "test" } },
+        (res) => {
+          res.resume();
+          resolve(res.statusCode);
+        },
+      );
+      req.on("error", reject);
+      req.end();
+    });
+  assert.equal(await statusFor(`127.0.0.1:${port}`), 200, "the address the plugin uses is served");
+  assert.equal(await statusFor(`localhost:${port}`), 200, "and so is localhost");
+  assert.equal(await statusFor(`evil.example:${port}`), 403, "a rebound hostname is refused");
+  assert.equal(await statusFor(`127.0.0.1.evil.example:${port}`), 403, "even one that merely starts like loopback");
+  assert.equal(await statusFor("127.0.0.1"), 403, "and a Host that names no port is not this server");
+
   const first = await open();
   const second = await open();
   first.destroy();
@@ -432,7 +537,9 @@ function twoStudios() {
   }
   const before = delays.length;
   for (const timeoutMs of [NaN, Infinity, -Infinity, -1, 0, null, "1000", {}, 2 ** 31, Number.MAX_SAFE_INTEGER]) {
-   assert.throws(() => bridge.call("studio.ping", {}, {clientId:"test",timeoutMs}), {code:"BAD_TIMEOUT"});
+   // A rejection rather than a throw: `call` returns a promise, so a caller's
+   // `.catch` has to be able to see this one too.
+   await assert.rejects(bridge.call("studio.ping", {}, {clientId:"test",timeoutMs}), {code:"BAD_TIMEOUT"});
   }
   assert.equal(delays.length, before, "invalid deadlines never create timers");
   assert.equal(bridge.sessions.get("timeout-test").pending.size, 0);