@el4cteo/rbx-studio-mcp 0.7.7 → 0.8.0

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)
@@ -41,7 +42,6 @@ local Viewport = require(script.handlers.Viewport)
 local Input = require(script.handlers.Input)
 local Device = require(script.handlers.Device)
 local Data = require(script.handlers.Data)
-local Anim = require(script.handlers.Anim)
 local Api = require(script.handlers.Api)
 local Scripts = require(script.handlers.Scripts)
 local Session = require(script.handlers.Session)
@@ -130,6 +130,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
@@ -195,7 +196,6 @@ Scripts.register()
 Input.register()
 Device.register()
 Data.register()
-Anim.register()
 Api.register()
 
 --[[
@@ -887,6 +887,7 @@ button.Click:Connect(function()
 end)
 
 plugin.Unloading:Connect(function()
+	ClientRelay.stopDiagnostics()
 	Transport.stop()
 end)
 

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

@@ -1,162 +1,259 @@
-/**
- * Offline checks for tool output shaping that needs no Studio.
- *
- * Usage: node scripts/test-tools.mjs
- */
-import assert from "node:assert/strict";
-import { CHARACTER_LIMIT } from "../dist/lib/format.js";
-import { clipListing, numbered } from "../dist/tools/scripts.js";
-
-const item = (path, lineCount) => ({ path, className: "ModuleScript", lineCount, startLine: 1, source: "" });
-const listing = (path, lines) =>
-  `${path}  (ModuleScript, ${lines} lines)\n` +
-  numbered(Array.from({ length: lines }, (_, index) => `local v${index} = ${index}`).join("\n"), 1);
-
-// Small reads pass through untouched.
-{
-  const blocks = [listing("A", 3)];
-  assert.equal(clipListing(blocks, [item("A", 3)], null), blocks[0]);
-}
-
-// A big read is cut on a whole line and names the exact next window.
-{
-  const out = clipListing([listing("Big", 5000), listing("After", 5)], [item("Big", 5000), item("After", 5)], null);
-  assert.ok(out.length <= CHARACTER_LIMIT, "fits the limit");
-  const match = /Big stops at line (\d+) of 5000\. Continue with \{ path: "Big", startLine: (\d+) \}/.exec(out);
-  assert.ok(match, "names where to continue");
-  assert.equal(Number(match[2]), Number(match[1]) + 1);
-  const lastShown = out.split("\n\n[clipped")[0].split("\n").pop();
-  assert.match(lastShown, new RegExp(`^\s*${match[1]}│ local v${Number(match[1]) - 1} = ${Number(match[1]) - 1}$`), "last line is whole");
-  assert.match(out, /1 more script\(s\) after it were not shown/);
-}
-
-// Failures are never the part that gets clipped away.
-{
-  const out = clipListing([listing("Big", 5000)], [item("Big", 5000)], "Could not read 1 path(s):\n  - Nope");
-  assert.ok(out.startsWith("Could not read 1 path(s)"));
-}
-
-process.stdout.write("tools: ok\n");
-
-// Exercise the public schemas and forwarding through the real tool handlers.
-const { z } = await import("zod");
-const { registerExecTools } = await import("../dist/tools/exec.js");
-const { registerInputTools } = await import("../dist/tools/input.js");
-const registered = new Map();
-const calls = [];
-const context = {
-  server: { registerTool(name, spec, handler) { registered.set(name, { spec, handler }); } },
-  bridge: { 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"};
-  } },
-};
-registerExecTools(context);
-registerInputTools(context);
-const execute = registered.get("execute_luau");
-const parsed = z.object(execute.spec.inputSchema).parse({source:"return nil",target:"client",player:"Alice",timeoutSeconds:2});
-await execute.handler(parsed);
-assert.equal(calls.at(-1).params.target, "client");
-assert.equal(calls.at(-1).params.player, "Alice");
-assert.equal(calls.at(-1).options.timeoutMs, 12000);
-await execute.handler(z.object(execute.spec.inputSchema).parse({source:"return 1"}));
-assert.equal(calls.at(-1).params.target, "studio");
-assert.equal(calls.at(-1).options.timeoutMs, 60000);
-const input = registered.get("input");
-for (const step of [{kind:"click",target:"PlayerGui.HUD.BuyButton"},{kind:"text",target:"PlayerGui.HUD.NameBox",text:"hello"},{kind:"click",x:100,y:200}]) {
- await input.handler(z.object(input.spec.inputSchema).parse({steps:[step]}));
- assert.deepEqual(calls.at(-1).params.steps[0], step);
-}
-// Issue #4: ordinary decimal holds/waits retain padding and yield whole milliseconds.
-for (const steps of [
- [{kind:"key",key:"E",hold:0.1,after:4.1}, ...Array.from({length:24}, () => ({kind:"key",key:"Left",hold:0.05,after:1.065}))],
- [{kind:"key",key:"E",hold:0.05,after:1.0651}],
-]) {
- await input.handler(z.object(input.spec.inputSchema).parse({steps}));
- const raw = (35 + steps.reduce((sum, step) => sum + step.hold + step.after + 0.5, 0)) * 1000;
- assert.equal(calls.at(-1).options.timeoutMs, Math.ceil(raw));
- assert.ok(Number.isInteger(calls.at(-1).options.timeoutMs));
- assert.deepEqual(calls.at(-1).params.steps, steps, "step timing itself is unchanged");
-}
-assert.deepEqual([...registered.keys()].sort(), ["execute_luau", "input", "viewport"]);
-process.stdout.write("client tool schemas: ok\n");
-
-const { registerDebugTools } = await import("../dist/tools/debug.js");
-registerDebugTools(context);
-const debug = registered.get("debug");
-const remoteArgs = z.object(debug.spec.inputSchema).parse({op:"remotes",path:"ReplicatedStorage",player:"Alice",seconds:3});
-await debug.handler(remoteArgs);
-assert.equal(calls.at(-1).op, "debug.remotes");
-assert.deepEqual(calls.at(-1).params, {path:"ReplicatedStorage",player:"Alice",seconds:3});
-assert.equal(calls.at(-1).options.timeoutMs, 18000);
-assert.throws(() => z.object(debug.spec.inputSchema).parse({op:"remotes",seconds:16}));
-assert.deepEqual([...registered.keys()].sort(), ["debug", "execute_luau", "input", "viewport"]);
-process.stdout.write("remote trace schema: ok\n");
-
-const { registerPlaytestTools } = await import("../dist/tools/playtest.js");
-registerPlaytestTools(context);
-const playtest = registered.get("playtest");
-for (const guidance of ["AGENTS.md", "CLAUDE.md", "user instructions", "project guidance", "even when ON", "Do not bypass"]) {
- assert.ok(playtest.spec.description.includes(guidance), `playtest guidance preserves ${guidance}`);
-}
-const normalCall = context.bridge.call;
-context.bridge.call = async (op, params) => {
- if (["play", "run", "multiplayer"].includes(params.op)) {
-  const { ToolError } = await import("../dist/lib/errors.js");
-  throw new ToolError("PLAYTEST_DISABLED", "Playtests are disabled by the user.", "Do not start or simulate a playtest. Continue using edit-mode tools and static inspection where possible.\nRun `playtests on` in the Studio MCP panel to re-enable playtesting.");
- }
- return {changed:false,state:{playtestsAllowed:false}};
-};
-for (const op of ["play", "run", "multiplayer"]) {
- const result = await playtest.handler(z.object(playtest.spec.inputSchema).parse({op}));
- assert.equal(result.isError, true);
- assert.match(result.content[0].text, /PLAYTEST_DISABLED/);
- assert.match(result.content[0].text, /playtests on/);
-}
-const stateResult = await playtest.handler(z.object(playtest.spec.inputSchema).parse({op:"state"}));
-assert.ok(!stateResult.isError);
-context.bridge.call = normalCall;
-process.stdout.write("playtest lock errors and instruction precedence: 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");
-const { registerScreenshotTools } = await import("../dist/tools/screenshot.js");
-registerDiscoverTools(context);
-registerScriptTools(context);
-registerScreenshotTools(context);
-const editOps = [];
-context.bridge.sessions = async () => ({list:[{studioId:"edit",context:"edit"}],activeId:"edit"});
-context.bridge.call = async (op, params) => {
- editOps.push(op);
- if (op === "playtest.control") {
-  if (["play", "run", "multiplayer"].includes(params.op)) throw new Error("PLAYTEST_DISABLED");
-  return {changed:false,state:{playtestsAllowed:false}};
- }
- const results = {
-  "exec.run": {ok:true,returned:[42],output:[],milliseconds:1},
-  "discover.tree": {items:[],total:0,offset:0},
-  "discover.inspect": {items:[],failures:[]},
-  "script.read": {items:[],failures:[]},
-  "viewport.ui": {findings:[],checked:0,hidden:0,root:"StarterGui",screen:"800x600"},
-  "capture.screenshot": {encoding:"png",data:"AA==",width:1,height:1,sourceWidth:1,sourceHeight:1,bytes:1,context:"edit"},
- };
- assert.ok(op in results, `unexpected edit-mode operation ${op}`);
- return results[op];
-};
-for (const [name, args, expected] of [
- ["execute_luau",{source:"return 42",target:"studio"},"exec.run"],
- ["tree",{},"discover.tree"],
- ["inspect",{paths:["Workspace"],detail:"concise"},"discover.inspect"],
- ["script_read",{paths:["ServerScriptService.Example"]},"script.read"],
- ["viewport",{op:"ui",path:"StarterGui"},"viewport.ui"],
- ["screenshot",{},"capture.screenshot"],
-]) {
- const tool = registered.get(name);
- const result = await tool.handler(z.object(tool.spec.inputSchema).parse(args));
- assert.ok(!result.isError, `${name} remains usable with playtests OFF: ${JSON.stringify(result)}`);
- assert.equal(editOps.at(-1),expected);
-}
-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");
+/**
+ * Offline checks for tool output shaping that needs no Studio.
+ *
+ * Usage: node scripts/test-tools.mjs
+ */
+import assert from "node:assert/strict";
+import { CHARACTER_LIMIT } from "../dist/lib/format.js";
+import { clipListing, numbered } from "../dist/tools/scripts.js";
+
+const item = (path, lineCount) => ({ path, className: "ModuleScript", lineCount, startLine: 1, source: "" });
+const listing = (path, lines) =>
+  `${path}  (ModuleScript, ${lines} lines)\n` +
+  numbered(Array.from({ length: lines }, (_, index) => `local v${index} = ${index}`).join("\n"), 1);
+
+// Small reads pass through untouched.
+{
+  const blocks = [listing("A", 3)];
+  assert.equal(clipListing(blocks, [item("A", 3)], null), blocks[0]);
+}
+
+// A big read is cut on a whole line and names the exact next window.
+{
+  const out = clipListing([listing("Big", 5000), listing("After", 5)], [item("Big", 5000), item("After", 5)], null);
+  assert.ok(out.length <= CHARACTER_LIMIT, "fits the limit");
+  const match = /Big stops at line (\d+) of 5000\. Continue with \{ path: "Big", startLine: (\d+) \}/.exec(out);
+  assert.ok(match, "names where to continue");
+  assert.equal(Number(match[2]), Number(match[1]) + 1);
+  const lastShown = out.split("\n\n[clipped")[0].split("\n").pop();
+  assert.match(lastShown, new RegExp(`^\s*${match[1]}│ local v${Number(match[1]) - 1} = ${Number(match[1]) - 1}$`), "last line is whole");
+  assert.match(out, /1 more script\(s\) after it were not shown/);
+}
+
+// Failures are never the part that gets clipped away.
+{
+  const out = clipListing([listing("Big", 5000)], [item("Big", 5000)], "Could not read 1 path(s):\n  - Nope");
+  assert.ok(out.startsWith("Could not read 1 path(s)"));
+}
+
+process.stdout.write("tools: ok\n");
+
+// Exercise the public schemas and forwarding through the real tool handlers.
+const { z } = await import("zod");
+const { registerExecTools } = await import("../dist/tools/exec.js");
+const { registerInputTools } = await import("../dist/tools/input.js");
+const registered = new Map();
+const calls = [];
+const context = {
+  server: { registerTool(name, spec, handler) { registered.set(name, { spec, handler }); } },
+  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"};
+  } },
+};
+registerExecTools(context);
+registerInputTools(context);
+const execute = registered.get("execute_luau");
+const parsed = z.object(execute.spec.inputSchema).parse({source:"return nil",target:"client",player:"Alice",timeoutSeconds:2});
+await execute.handler(parsed);
+assert.equal(calls.at(-1).params.target, "client");
+assert.equal(calls.at(-1).params.player, "Alice");
+assert.equal(calls.at(-1).options.timeoutMs, 12000);
+await execute.handler(z.object(execute.spec.inputSchema).parse({source:"return 1"}));
+assert.equal(calls.at(-1).params.target, "studio");
+assert.equal(calls.at(-1).options.timeoutMs, 60000);
+const input = registered.get("input");
+for (const step of [{kind:"click",target:"PlayerGui.HUD.BuyButton"},{kind:"text",target:"PlayerGui.HUD.NameBox",text:"hello"},{kind:"click",x:100,y:200}]) {
+ await input.handler(z.object(input.spec.inputSchema).parse({steps:[step]}));
+ assert.deepEqual(calls.at(-1).params.steps[0], step);
+}
+// Issue #4: ordinary decimal holds/waits retain padding and yield whole milliseconds.
+for (const steps of [
+ [{kind:"key",key:"E",hold:0.1,after:4.1}, ...Array.from({length:24}, () => ({kind:"key",key:"Left",hold:0.05,after:1.065}))],
+ [{kind:"key",key:"E",hold:0.05,after:1.0651}],
+]) {
+ await input.handler(z.object(input.spec.inputSchema).parse({steps}));
+ const raw = (35 + steps.reduce((sum, step) => sum + step.hold + step.after + 0.5, 0)) * 1000;
+ assert.equal(calls.at(-1).options.timeoutMs, Math.ceil(raw));
+ assert.ok(Number.isInteger(calls.at(-1).options.timeoutMs));
+ assert.deepEqual(calls.at(-1).params.steps, steps, "step timing itself is unchanged");
+}
+assert.deepEqual([...registered.keys()].sort(), ["execute_luau", "input", "viewport"]);
+process.stdout.write("client tool schemas: ok\n");
+
+const { registerDebugTools } = await import("../dist/tools/debug.js");
+registerDebugTools(context);
+const debug = registered.get("debug");
+const remoteArgs = z.object(debug.spec.inputSchema).parse({op:"remotes",path:"ReplicatedStorage",player:"Alice",seconds:3});
+await debug.handler(remoteArgs);
+assert.equal(calls.at(-1).op, "debug.remotes");
+assert.deepEqual(calls.at(-1).params, {path:"ReplicatedStorage",player:"Alice",seconds:3});
+assert.equal(calls.at(-1).options.timeoutMs, 18000);
+assert.throws(() => z.object(debug.spec.inputSchema).parse({op:"remotes",seconds:16}));
+assert.deepEqual([...registered.keys()].sort(), ["debug", "execute_luau", "input", "viewport"]);
+process.stdout.write("remote trace schema: ok\n");
+
+const { registerPlaytestTools } = await import("../dist/tools/playtest.js");
+registerPlaytestTools(context);
+const playtest = registered.get("playtest");
+for (const guidance of ["AGENTS.md", "CLAUDE.md", "user instructions", "project guidance", "even when ON", "Do not bypass"]) {
+ assert.ok(playtest.spec.description.includes(guidance), `playtest guidance preserves ${guidance}`);
+}
+const normalCall = context.bridge.call;
+context.bridge.call = async (op, params) => {
+ if (["play", "run", "multiplayer"].includes(params.op)) {
+  const { ToolError } = await import("../dist/lib/errors.js");
+  throw new ToolError("PLAYTEST_DISABLED", "Playtests are disabled by the user.", "Do not start or simulate a playtest. Continue using edit-mode tools and static inspection where possible.\nRun `playtests on` in the Studio MCP panel to re-enable playtesting.");
+ }
+ return {changed:false,state:{playtestsAllowed:false}};
+};
+for (const op of ["play", "run", "multiplayer"]) {
+ const result = await playtest.handler(z.object(playtest.spec.inputSchema).parse({op}));
+ assert.equal(result.isError, true);
+ assert.match(result.content[0].text, /PLAYTEST_DISABLED/);
+ assert.match(result.content[0].text, /playtests on/);
+}
+const stateResult = await playtest.handler(z.object(playtest.spec.inputSchema).parse({op:"state"}));
+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");
+const { registerScreenshotTools } = await import("../dist/tools/screenshot.js");
+registerDiscoverTools(context);
+registerScriptTools(context);
+registerScreenshotTools(context);
+const editOps = [];
+context.bridge.sessions = async () => ({list:[{studioId:"edit",context:"edit"}],activeId:"edit"});
+context.bridge.call = async (op, params) => {
+ editOps.push(op);
+ if (op === "playtest.control") {
+  if (["play", "run", "multiplayer"].includes(params.op)) throw new Error("PLAYTEST_DISABLED");
+  return {changed:false,state:{playtestsAllowed:false}};
+ }
+ const results = {
+  "exec.run": {ok:true,returned:[42],output:[],milliseconds:1},
+  "discover.tree": {items:[],total:0,offset:0},
+  "discover.inspect": {items:[],failures:[]},
+  "script.read": {items:[],failures:[]},
+  "viewport.ui": {findings:[],checked:0,hidden:0,root:"StarterGui",screen:"800x600"},
+  "capture.screenshot": {encoding:"png",data:"AA==",width:1,height:1,sourceWidth:1,sourceHeight:1,bytes:1,context:"edit"},
+ };
+ assert.ok(op in results, `unexpected edit-mode operation ${op}`);
+ return results[op];
+};
+for (const [name, args, expected] of [
+ ["execute_luau",{source:"return 42",target:"studio"},"exec.run"],
+ ["tree",{},"discover.tree"],
+ ["inspect",{paths:["Workspace"],detail:"concise"},"discover.inspect"],
+ ["script_read",{paths:["ServerScriptService.Example"]},"script.read"],
+ ["viewport",{op:"ui",path:"StarterGui"},"viewport.ui"],
+ ["screenshot",{},"capture.screenshot"],
+]) {
+ const tool = registered.get(name);
+ const result = await tool.handler(z.object(tool.spec.inputSchema).parse(args));
+ assert.ok(!result.isError, `${name} remains usable with playtests OFF: ${JSON.stringify(result)}`);
+ assert.equal(editOps.at(-1),expected);
+}
+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");
+
+// `create` must not advertise a recursive schema -- Gemini / Vertex AI reject a
+// `$ref` with HTTP 400 -- yet a bad nested child is still refused by name.
+{
+ const { registerInstanceTools } = await import("../dist/tools/instances.js");
+ const tools = new Map();
+ registerInstanceTools({ server: { registerTool(name, spec, handler) { tools.set(name, { spec, handler }); } }, bridge: { async call() { throw new Error("must not reach Studio"); } } });
+ const create = tools.get("create");
+ const schema = JSON.stringify(z.toJSONSchema(z.object(create.spec.inputSchema)));
+ assert.ok(!schema.includes("$ref") && !schema.includes("$defs") && !schema.includes("definitions"), "create schema is not recursive");
+ const bad = await create.handler(z.object(create.spec.inputSchema).parse({ instances: [{ parent: "Workspace", className: "Model", children: [{ className: "Part", children: [{ name: "NoClass" }] }] }] }));
+ assert.equal(bad.isError, true);
+ assert.match(bad.content[0].text, /BAD_PARAMS\] instances\[0\]\.children\[0\]\.children\[0\]\.className/);
+ process.stdout.write("create schema without recursion, nested validation: ok\n");
+}
+
+// Compact JSON: short structures on one line, and always parsed back identical.
+{
+ const { stringify } = await import("../dist/lib/format.js");
+ const value = { rows: [{ path: "Workspace.A", className: "Part" }], nested: { list: [1, "two", null, undefined], skip: undefined, when: new Date(0) }, long: "x".repeat(150) };
+ assert.deepEqual(JSON.parse(stringify(value)), JSON.parse(JSON.stringify(value)));
+ assert.match(stringify(value), /\n  "rows": \[\{"path":"Workspace.A","className":"Part"\}\],\n/, "a short row stays on one line");
+ assert.equal(stringify([]), "[]");
+ assert.equal(stringify(undefined), "null");
+ process.stdout.write("compact json: ok\n");
+}
+
+// Screenshot scaling: box filter averages everything under a pixel; enlarging copies blocks.
+{
+ const { boxResample, upscaleNearest } = await import("../dist/lib/png.js");
+ const stripes = Buffer.from([0,0,0, 200,200,200, 0,0,0, 200,200,200, 0,0,0, 200,200,200, 0,0,0, 200,200,200]);
+ assert.deepEqual([...boxResample(stripes, 4, 2, 2).rgb], [100,100,100, 100,100,100], "averages, never samples");
+ const W = 1661, H = 719, line = Buffer.alloc(W * H * 3);
+ for (let y = 0; y < H; y += 1) line[(y * W + 831) * 3] = 255;
+ const scaled = boxResample(line, W, H, 800);
+ assert.equal(scaled.width, 800);
+ assert.equal(scaled.height, 346);
+ let red = 0; for (let i = 0; i < scaled.rgb.length; i += 3) red = Math.max(red, scaled.rgb[i]);
+ assert.ok(red > 100, "a one-pixel line survives a 2x reduction");
+ assert.equal(boxResample(stripes, 4, 2, 8).width, 4, "never scales up");
+ assert.deepEqual([...upscaleNearest(Buffer.from([1,2,3,4,5,6]), 2, 1, 2).rgb], [1,2,3,1,2,3,4,5,6,4,5,6,1,2,3,1,2,3,4,5,6,4,5,6]);
+ process.stdout.write("screenshot scaling: ok\n");
+}