@el4cteo/rbx-studio-mcp 0.8.0 → 0.8.3

package/plugin/src/handlers/Terrain.luau

@@ -130,6 +130,16 @@ end
 	something smaller.
 ]]
 local function guard(size: Vector3, what: string)
+	-- An empty extent is not a small fill, it is no fill: the engine raised
+	-- "Extents cannot be empty" from inside the recording, and that came back as
+	-- an unstructured HANDLER_ERROR with no hint which side was zero.
+	if size.X <= 0 or size.Y <= 0 or size.Z <= 0 then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			string.format("%s has a size of %s, which is empty.", what, tostring(size)),
+			"Every side of the size has to be greater than zero."
+		)
+	end
 	local voxels = math.ceil(size.X / RESOLUTION)
 		* math.ceil(size.Y / RESOLUTION)
 		* math.ceil(size.Z / RESOLUTION)
@@ -319,43 +329,28 @@ end
 	What is there, without reading a voxel.
 
 	`CountCells` is the cheap answer to "does this place even use terrain",
-	which is the question worth asking before any of the above. The bounding box
-	tells an agent where to aim without guessing at the origin.
+	which is the question worth asking before any of the above.
 ]]
 function Terrain.stats(_params: { [string]: any }): { [string]: any }
 	local field = terrain()
 
 	--[[
-		Formatted here rather than through `Serialize.value`.
-
-		`MaxExtents` is a Region3int16 and its corners are Vector3int16, which is
-		a type `Serialize.value` has no case for -- it would have fallen through
-		to the generic tail and reported whatever `tostring` makes of it. The
-		extents are also in VOXELS, not studs, which is the sort of unit
-		confusion that produces a fill a thousand studs from where it was meant,
-		so they are converted and named for what they are.
-	]]
-	--[[
-		`MaxExtents` is deliberately not reported.
+		No bounds, and no limit.
 
-		It reads like the bounding box of the terrain that exists, and it is
-		not: it is the fixed limit of where terrain is allowed to go, and it
-		answers -32000, -32000, -32000 to 32000, 32000, 32000 on an empty place
-		and on a full one alike. Reporting it as "where the terrain sits" was a
-		misreading of the name -- checked against a place with 2220 cells in a
-		160-stud patch, which returned exactly the same numbers as one with
-		none.
+		`MaxExtents` reads like the bounding box of the terrain that exists and is
+		not: it answers -32000..32000 on an empty place and a full one alike. Nor
+		is it a limit in studs -- a fill at 140,000 studs out still landed -- so
+		the `limitStuds = 32000` this used to report was wrong as well.
 
 		There is no engine call for the occupied box, and finding it means
 		reading every voxel in the world, which is far too expensive for a
-		question meant to be cheap. `cells` already answers the one that
-		matters: whether this place uses terrain at all.
+		question meant to be cheap. `cells` answers the one that matters.
 	]]
 	return {
 		cells = field:CountCells(),
 		waterColor = Serialize.value(field.WaterColor),
-		waterWaveSize = field.WaterWaveSize,
-		limitStuds = 32000,
+		-- Through Serialize so a float32 reads 0.15, not 0.15000000596046448.
+		waterWaveSize = Serialize.value(field.WaterWaveSize),
 	}
 end
 

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))
@@ -92,7 +106,7 @@ function Viewport.raycast(params: { [string]: any }): { [string]: any }
 		position = Serialize.value(cast.Position),
 		normal = Serialize.value(cast.Normal),
 		distance = math.floor(cast.Distance * 1000 + 0.5) / 1000,
-		material = Serialize.value(cast.Material),
+		material = cast.Material.Name,
 	}
 end
 
@@ -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)
@@ -287,9 +319,9 @@ function Viewport.camera(params: { [string]: any }): { [string]: any }
 	end
 
 	return {
-		position = tostring(view.CFrame.Position),
-		lookVector = tostring(view.CFrame.LookVector),
-		fieldOfView = view.FieldOfView,
+		position = Serialize.value(view.CFrame.Position),
+		lookVector = Serialize.value(view.CFrame.LookVector),
+		fieldOfView = Serialize.value(view.FieldOfView),
 	}
 end
 

package/plugin/src/handlers/World.luau

@@ -213,6 +213,19 @@ function World.collision(params: { [string]: any }): { [string]: any }
 		if typeof(paths) ~= "table" or #(paths :: { any }) == 0 then
 			Dispatch.fail("BAD_PARAMS", "assign needs a `paths` array.")
 		end
+		-- The engine takes any string here, registered or not, and a part in an
+		-- unregistered group collides as Default: a typo that changes nothing
+		-- and reports success. Measured, so refused up front.
+		local okRegistered, registered = pcall(function()
+			return world:IsCollisionGroupRegistered(name)
+		end)
+		if okRegistered and registered == false then
+			Dispatch.fail(
+				"NO_SUCH_GROUP",
+				string.format("No collision group %q is registered in %s.", name, Paths.of(world)),
+				'Create it first with action="create", or check the name with action="list".'
+			)
+		end
 		local assigned: { string } = {}
 		local _, undoable = Undo.record("MCPCollision", "MCP collision group", function()
 			for _, path in paths :: { string } do
@@ -228,7 +241,10 @@ function World.collision(params: { [string]: any }): { [string]: any }
 				end
 			end
 		end)
-		return { group = name, assigned = #assigned, parts = assigned, undoable = undoable, world = Paths.of(world) }
+		-- A model can hold thousands of parts; the count is the answer and a
+		-- sample of names is enough to see it landed where intended.
+		local sample = if #assigned > 20 then table.move(assigned, 1, 20, 1, {}) else assigned
+		return { group = name, assigned = #assigned, parts = sample, undoable = undoable, world = Paths.of(world) }
 	end
 
 	if action == "remove" then
@@ -241,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

@@ -398,10 +398,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()

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);