@el4cteo/rbx-studio-mcp 0.1.0

package/dist/lib/png.js

@@ -0,0 +1,84 @@
+import { deflateSync } from "node:zlib";
+/**
+ * Writes a PNG from raw RGB bytes.
+ *
+ * The plugin used to do this itself, and could only do it badly. Studio has no
+ * deflate, so the Luau encoder emitted zlib *stored* blocks -- the format's
+ * escape hatch for "compression not applied" -- which meant every screenshot
+ * travelled and landed at full uncompressed size. For a screen of mostly flat
+ * colour that is several times larger than it needs to be, and it is spent
+ * twice: once over the bridge and again as base64 in the conversation.
+ *
+ * Node has real zlib. So the plugin now sends pixels and this writes the file,
+ * which is the right division: the side with the compressor does the
+ * compressing.
+ */
+const CRC_TABLE = (() => {
+    const table = new Int32Array(256);
+    for (let index = 0; index < 256; index += 1) {
+        let value = index;
+        for (let bit = 0; bit < 8; bit += 1) {
+            // 0xEDB88320: the reversed CRC-32 polynomial. Worth writing out, because
+            // a single wrong digit here (0xED888320) still produces a table, still
+            // produces a checksum, and still produces a PNG that every decoder
+            // rejects — with nothing in the file to say which byte was wrong.
+            value = value & 1 ? 0xedb8_8320 ^ (value >>> 1) : value >>> 1;
+        }
+        table[index] = value;
+    }
+    return table;
+})();
+function crc32(data) {
+    let crc = -1;
+    for (const byte of data) {
+        crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ -1) >>> 0;
+}
+/** One PNG chunk: length, type, payload, CRC over type+payload. */
+function chunk(kind, payload) {
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(payload.length, 0);
+    const body = Buffer.concat([Buffer.from(kind, "ascii"), payload]);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(body), 0);
+    return Buffer.concat([length, body, crc]);
+}
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/**
+ * Encodes `width` x `height` RGB triples as a PNG.
+ *
+ * Filter type 0 (None) on every scanline. The adaptive filters PNG allows would
+ * compress better, but choosing between them well is its own problem, and
+ * deflate over unfiltered rows already recovers almost all of what the old
+ * stored-block encoder was throwing away.
+ */
+export function encodePng(rgb, width, height) {
+    const stride = width * 3;
+    const expected = stride * height;
+    if (rgb.length < expected) {
+        throw new Error(`pixel data is ${rgb.length} bytes, short of the ${expected} needed for ${width}x${height}`);
+    }
+    // One leading filter byte per row is what separates the raw pixels from a
+    // PNG's idea of a scanline.
+    const raw = Buffer.alloc((stride + 1) * height);
+    for (let row = 0; row < height; row += 1) {
+        raw[row * (stride + 1)] = 0;
+        rgb.copy(raw, row * (stride + 1) + 1, row * stride, row * stride + stride);
+    }
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(width, 0);
+    header.writeUInt32BE(height, 4);
+    header[8] = 8; // bit depth
+    header[9] = 2; // colour type 2: truecolour RGB
+    header[10] = 0; // deflate
+    header[11] = 0; // adaptive filtering
+    header[12] = 0; // no interlace
+    return Buffer.concat([
+        SIGNATURE,
+        chunk("IHDR", header),
+        chunk("IDAT", deflateSync(raw, { level: 9 })),
+        chunk("IEND", Buffer.alloc(0)),
+    ]);
+}
+//# sourceMappingURL=png.js.map

package/dist/lib/png.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"png.js","sourceRoot":"","sources":["../../src/lib/png.ts"],"names":[],"mappings":"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"}

package/dist/lib/protocol.js

@@ -0,0 +1,22 @@
+/**
+ * Wire protocol shared between the Node bridge and the Studio plugin.
+ *
+ * Transport is deliberately dumb: the server pushes `Command` frames down an
+ * SSE stream (or hands them out via long-poll when SSE is unavailable) and the
+ * plugin POSTs a matching `CommandResult` back to /result. Every frame is
+ * correlated by `id`, so both transports behave identically from the tool side.
+ */
+/**
+ * Bumped whenever `Command`/`CommandResult` shapes change incompatibly. The
+ * plugin sends its own value at handshake so we can tell the user to update
+ * rather than failing with a confusing schema error later.
+ */
+export const PROTOCOL_VERSION = 1;
+/**
+ * Custom header every plugin request must carry. Browsers cannot set it on a
+ * cross-origin request without a preflight the bridge never answers, which is
+ * what stops a malicious web page from driving the user's Studio via DNS
+ * rebinding. Cheaper and less fragile than a token the user has to copy.
+ */
+export const CLIENT_HEADER = "x-roblox-studio-mcp";
+//# sourceMappingURL=protocol.js.map

package/dist/lib/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/lib/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAqDH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,qBAAqB,CAAC"}

package/dist/lib/tool.js

@@ -0,0 +1,27 @@
+import { toToolError } from "./errors.js";
+import { errorText } from "./format.js";
+export function defineTool(context, spec, handler) {
+    const readOnly = spec.readOnly ?? false;
+    context.server.registerTool(spec.name, {
+        title: spec.title,
+        description: spec.description,
+        inputSchema: spec.inputSchema,
+        annotations: {
+            title: spec.title,
+            readOnlyHint: readOnly,
+            destructiveHint: spec.destructive ?? !readOnly,
+            idempotentHint: spec.idempotent ?? readOnly,
+            // Studio is a live external process whose state we do not control.
+            openWorldHint: true,
+        },
+    }, (async (args) => {
+        try {
+            return await handler(args);
+        }
+        catch (cause) {
+            const error = toToolError(cause);
+            return errorText(`[${error.code}] ${error.message}`);
+        }
+    }));
+}
+//# sourceMappingURL=tool.js.map

package/dist/lib/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/lib/tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAmB,MAAM,aAAa,CAAC;AAwCzD,MAAM,UAAU,UAAU,CACxB,OAAoB,EACpB,IAAqB,EACrB,OAAuD;IAEvD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;IACxC,OAAO,CAAC,MAAM,CAAC,YAAY,CACzB,IAAI,CAAC,IAAI,EACT;QACE,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,YAAY,EAAE,QAAQ;YACtB,eAAe,EAAE,IAAI,CAAC,WAAW,IAAI,CAAC,QAAQ;YAC9C,cAAc,EAAE,IAAI,CAAC,UAAU,IAAI,QAAQ;YAC3C,mEAAmE;YACnE,aAAa,EAAE,IAAI;SACpB;KACF,EACD,CAAC,KAAK,EAAE,IAAqB,EAAE,EAAE;QAC/B,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;YACjC,OAAO,SAAS,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC,CAAU,CACZ,CAAC;AACJ,CAAC"}

package/dist/resources.js

@@ -0,0 +1,70 @@
+/**
+ * MCP resources: place state an agent can read without spending a tool call.
+ *
+ * Tools cost schema tokens in every request, whether or not they are used.
+ * Resources cost nothing until read, which makes them the right home for the
+ * three questions asked at the start of almost every session — what is
+ * connected, what is in the place, what is selected — and lets a client attach
+ * them as context rather than making the model ask.
+ *
+ * Everything here is read-only by construction: resources have no parameters to
+ * validate and no way to express a mutation, which is exactly why the state
+ * queries belong here and the actions do not.
+ */
+export function registerResources(context) {
+    const { server, bridge } = context;
+    const readJson = async (op, params = {}) => {
+        // Resources have nowhere to put an error, so a failure is returned as the
+        // content itself rather than thrown: a client attaching this to a prompt
+        // should see why it is empty, not a blank block.
+        try {
+            const result = await bridge.call(op, params, {});
+            return JSON.stringify(result, null, 2);
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            return JSON.stringify({ unavailable: message }, null, 2);
+        }
+    };
+    server.registerResource("studio-status", "studio://status", {
+        title: "Studio session",
+        description: "Which place is open, whether it is playing, what is selected, and " +
+            "which scripts the user has on screen. The cheapest orientation there is.",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: "application/json", text: await readJson("studio.status") }],
+    }));
+    server.registerResource("studio-tree", "studio://tree", {
+        title: "Place hierarchy",
+        description: "The authored containers and what is directly inside them, two levels " +
+            "deep. A map of the place, without the ~120 engine services that would " +
+            "bury it.",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                // Two levels and a modest cap: this is orientation, not an inventory,
+                // and a resource that dumps a large place would cost more than the
+                // tool call it saves.
+                text: await readJson("discover.tree", { depth: 2, limit: 150, detail: "concise" }),
+            },
+        ],
+    }));
+    server.registerResource("studio-console", "studio://console", {
+        title: "Recent output",
+        description: "The last 100 lines Studio printed, warnings and errors included. " +
+            "Reading this after a playtest is usually the first useful thing to do.",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: await readJson("perf.console", { limit: 100 }),
+            },
+        ],
+    }));
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAoB;IACpD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAEnC,MAAM,QAAQ,GAAG,KAAK,EAAE,EAAU,EAAE,MAAM,GAA4B,EAAE,EAAmB,EAAE;QAC3F,0EAA0E;QAC1E,yEAAyE;QACzE,iDAAiD;QACjD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAU,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;YAC1D,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,CAAC,gBAAgB,CACrB,eAAe,EACf,iBAAiB,EACjB;QACE,KAAK,EAAE,gBAAgB;QACvB,WAAW,EACT,oEAAoE;YACpE,0EAA0E;QAC5E,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QACd,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;KACnG,CAAC,CACH,CAAC;IAEF,MAAM,CAAC,gBAAgB,CACrB,aAAa,EACb,eAAe,EACf;QACE,KAAK,EAAE,iBAAiB;QACxB,WAAW,EACT,uEAAuE;YACvE,wEAAwE;YACxE,UAAU;QACZ,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QACd,QAAQ,EAAE;YACR;gBACE,GAAG,EAAE,GAAG,CAAC,IAAI;gBACb,QAAQ,EAAE,kBAAkB;gBAC5B,sEAAsE;gBACtE,mEAAmE;gBACnE,sBAAsB;gBACtB,IAAI,EAAE,MAAM,QAAQ,CAAC,eAAe,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;aACnF;SACF;KACF,CAAC,CACH,CAAC;IAEF,MAAM,CAAC,gBAAgB,CACrB,gBAAgB,EAChB,kBAAkB,EAClB;QACE,KAAK,EAAE,eAAe;QACtB,WAAW,EACT,mEAAmE;YACnE,wEAAwE;QAC1E,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QACd,QAAQ,EAAE;YACR;gBACE,GAAG,EAAE,GAAG,CAAC,IAAI;gBACb,QAAQ,EAAE,kBAAkB;gBAC5B,IAAI,EAAE,MAAM,QAAQ,CAAC,cAAc,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;aACrD;SACF;KACF,CAAC,CACH,CAAC;AACJ,CAAC"}

package/dist/tools/api.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { json, text } from "../lib/format.js";
+import { defineTool } from "../lib/tool.js";
+export function registerApiTools(context) {
+    const { bridge } = context;
+    defineTool(context, {
+        name: "api",
+        title: "What a class can do",
+        description: "Lists the properties, methods and events of any Roblox class, read " +
+            "from the engine that is running.\n\n" +
+            "Use it before writing Luau against a class you are not certain of. " +
+            "Guessing a method name costs a runtime error and a round trip; this " +
+            "costs one call and is never out of date, because the answer comes from " +
+            "the running binary rather than from a published dump or from training " +
+            "data. That matters most for exactly the classes worth checking — new " +
+            "ones, and ones that changed recently.\n\n" +
+            "Members come back as signatures rather than bare names — " +
+            "`AddAccessory(accessory: Instance)`, `HoldDuration: number` — because a " +
+            "name tells you something exists and a signature tells you how to call " +
+            "it, which is the actual question.\n\n" +
+            "`describe` takes a class name and gives the members it declares itself, " +
+            "counting the inherited ones separately. `classes` searches class names, " +
+            "which is how to find one whose exact spelling you do not have.\n\n" +
+            "Deprecated members are never listed, only counted — `Instance` has " +
+            "eight, including `clone`, `remove` and `getChildren`. They still run, " +
+            "so picking one from a list gives you working code and a deprecation " +
+            "warning in the user's output.\n\n" +
+            "This is not the same as `inspect`. `inspect` reads the values on an " +
+            "instance that exists; this reads the shape of a class whether or not " +
+            "anything in the place is one — which is what you need when deciding " +
+            "what to create in the first place.",
+        inputSchema: {
+            op: z
+                .enum(["describe", "classes"])
+                .default("describe")
+                .describe("'describe' details one class, 'classes' searches class names."),
+            className: z
+                .string()
+                .optional()
+                .describe('describe only: the class, e.g. "TweenService", "ProximityPrompt", "Humanoid". Case-sensitive.'),
+            contains: z
+                .string()
+                .optional()
+                .describe('classes only: substring to match, case-insensitive, e.g. "constraint" or "gui". Omit to list everything.'),
+            include: z
+                .array(z.enum(["properties", "methods", "events"]))
+                .optional()
+                .describe("describe only: which member kinds to return. Defaults to all " +
+                "three; narrow it when you only need one and the class is large."),
+            inherited: z
+                .boolean()
+                .default(false)
+                .describe("describe only: include members inherited from Instance and Object. " +
+                "Off by default because they swamp the answer — ProximityPrompt has " +
+                "2 methods of its own and 42 inherited, and the two you want are not " +
+                "the ones you already know. The inherited count is reported either way."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        readOnly: true,
+    }, async (args) => {
+        if (args.op === "classes") {
+            const response = await bridge.call("api.classes", { contains: args.contains }, { studioId: args.studioId });
+            if (response.matched === 0) {
+                return text(`No class name contains ${JSON.stringify(args.contains ?? "")}.\n` +
+                    "The match is a plain substring, case-insensitive — try a shorter one.");
+            }
+            return json(response.classes, response.truncated
+                ? `${response.matched} matched; ${response.truncated} not shown. Narrow with \`contains\`.`
+                : `${response.matched} matched.`);
+        }
+        if (args.className === undefined || args.className === "") {
+            return text('describe needs a `className`. Use `op: "classes"` to search for one.');
+        }
+        const response = await bridge.call("api.describe", { className: args.className, include: args.include, inherited: args.inherited }, { studioId: args.studioId });
+        return json(response);
+    });
+}
+//# sourceMappingURL=api.js.map

package/dist/tools/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/tools/api.ts"],"names":[],"mappings":"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"}

package/dist/tools/character.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { json } from "../lib/format.js";
+import { defineTool } from "../lib/tool.js";
+export function registerCharacterTools(context) {
+    const { bridge } = context;
+    defineTool(context, {
+        name: "character",
+        title: "Drive the player during a playtest",
+        description: "Moves and acts as the player character in a running playtest, so " +
+            "gameplay can be tested without asking the user to play it.\n\n" +
+            "`moveTo` walks to a position or to an instance, following a path " +
+            "computed around walls and gaps rather than a straight line into them. " +
+            "It reports whether it ACTUALLY ARRIVED and how far short it stopped — " +
+            "a route blocked by something you did not know about otherwise looks " +
+            "identical to a successful walk.\n\n" +
+            "`act` does the one-shot things worth testing: jump, sit, stand, " +
+            "respawn, kill (to exercise the death and respawn path), teleport, and " +
+            "`equip`/`activate` to use a Tool — which is how combat gets tested, " +
+            "since Activate is exactly what a mouse click triggers. Note " +
+            "that teleport skips everything in between, so triggers and collisions " +
+            "along the route do not fire — walk if you are testing those.\n\n" +
+            "`state` reports position, health, walk speed and what the humanoid is " +
+            "doing. Call it before and after anything else here.\n\n" +
+            "This drives the Humanoid directly rather than simulating keystrokes, " +
+            "which is the right tool for going places: pathfinding around a wall is " +
+            "one call here and a sequence of guessed key presses otherwise. For " +
+            "anything bound to a control rather than to movement — does E open the " +
+            "door, does the sprint key work, does Escape close the menu — use " +
+            "`input`, which sends real key and mouse events.\n\n" +
+            "REQUIRES A RUNNING PLAYTEST, and the character lives in the playtest's " +
+            "data model — address these to the playtest's studioId from " +
+            "`list_studios`, not the editor's. Run mode has no character at all; " +
+            "use `playtest op=play`.",
+        inputSchema: {
+            op: z
+                .enum(["moveTo", "act", "state"])
+                .describe("'moveTo' walks somewhere, 'act' performs an action, 'state' only reports."),
+            to: z
+                .string()
+                .optional()
+                .describe('Target position, e.g. "25, 5, -10". Used by moveTo and by teleport.'),
+            path: z
+                .string()
+                .optional()
+                .describe("moveTo only: walk to this instance instead of a coordinate."),
+            direct: z
+                .boolean()
+                .default(false)
+                .describe("moveTo only: walk straight at the target without pathfinding. Use " +
+                "when a route is reported unreachable but you want to see what happens."),
+            canJump: z.boolean().default(true).describe("moveTo only: allow the path to include jumps."),
+            action: z
+                .enum([
+                "jump", "stop", "sit", "stand", "respawn", "kill", "teleport",
+                "equip", "activate", "unequip",
+            ])
+                .optional()
+                .describe("act only: what to do. 'equip' takes a Tool from the Backpack or " +
+                "StarterPack, 'activate' uses it (what a mouse click triggers)."),
+            tool: z.string().optional().describe("equip only: the Tool's name."),
+            player: z
+                .string()
+                .optional()
+                .describe("Which player, by name. Omit for the only one; needed in a multiplayer test."),
+            studioId: z
+                .string()
+                .optional()
+                .describe("The PLAYTEST session's id — not the editor's. See list_studios."),
+        },
+        destructive: false,
+    }, async (args) => {
+        if (args.op === "moveTo") {
+            const response = await bridge.call("character.moveTo", { to: args.to, path: args.path, direct: args.direct, canJump: args.canJump, player: args.player }, 
+            // Walking a long route is genuinely slow, and the handler waits for
+            // each waypoint rather than returning before it arrives.
+            { studioId: args.studioId, timeoutMs: 60_000 });
+            const notes = [];
+            if (response.note)
+                notes.push(response.note);
+            if (!response.arrived && response.pathStatus === "Enum.PathStatus.Success") {
+                notes.push("The path was valid but the character did not reach the end — something " +
+                    "is physically in the way, or it fell. Take a `screenshot` to see where it stopped.");
+            }
+            return json(response, notes.length > 0 ? notes.join(" ") : undefined);
+        }
+        if (args.op === "act") {
+            const response = await bridge.call("character.act", { action: args.action ?? "jump", to: args.to, tool: args.tool, player: args.player }, { studioId: args.studioId });
+            return json(response);
+        }
+        const response = await bridge.call("character.state", { player: args.player }, { studioId: args.studioId });
+        return json(response);
+    });
+}
+//# sourceMappingURL=character.js.map

package/dist/tools/character.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"character.js","sourceRoot":"","sources":["../../src/tools/character.ts"],"names":[],"mappings":"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"}

package/dist/tools/debug.js

@@ -0,0 +1,211 @@
+import { z } from "zod";
+import { json, text } from "../lib/format.js";
+import { defineTool } from "../lib/tool.js";
+/**
+ * Locals the debugger reports in every frame regardless of the code.
+ *
+ * `_G`, `shared` and `script` are in scope everywhere and `...` is the empty
+ * varargs tuple; none of them is ever the value someone set a breakpoint to see.
+ * Left in, they were four of the six rows in each frame -- so on a loop with two
+ * locals, two thirds of a capture was boilerplate repeated once per hit.
+ */
+const AMBIENT_LOCALS = new Set(["_G", "shared", "script", "..."]);
+/** Trims a debugger value string to something readable in a list. */
+function briefly(value) {
+    const single = value.replace(/\s+/g, " ").trim();
+    return single.length > 160 ? `${single.slice(0, 159)}…` : single;
+}
+function frameLabel(frame) {
+    if (!frame) {
+        return "(unknown)";
+    }
+    const where = `${frame.ScriptPath ?? "?"}:${frame.Line ?? "?"}`;
+    return frame.Name ? `${where} in ${frame.Name}` : where;
+}
+/**
+ * Renders captured frames as a readable outline rather than raw JSON.
+ *
+ * The raw payload is Roblox's, and it is shaped for a debugger UI: variables are
+ * a numbered map rather than a list, the call stack is repeated both inside each
+ * frame and again alongside it, and every variable carries a reference id the
+ * caller has no way to follow. Passed straight through, nine hits of a two-line
+ * loop came back as roughly eight thousand tokens. This keeps what a person
+ * reading the capture is actually after -- where it stopped, and what the values
+ * were -- and drops the rest.
+ */
+function renderSnapshots(items) {
+    const blocks = [];
+    let droppedAmbient = false;
+    items.forEach((item, index) => {
+        const frames = (item.frames ?? []);
+        const stack = item.stack;
+        const reason = item.stopped?.Reason;
+        const lines = [];
+        const head = frameLabel(frames[0]?.frame);
+        const depth = stack?.TotalFrames ?? frames.length;
+        lines.push(`#${index + 1}  ${head}${depth > 1 ? `  (${depth} frames)` : ""}` +
+            (reason && !reason.endsWith("Breakpoint") ? `  [${reason}]` : ""));
+        for (const entry of frames) {
+            if (frames.length > 1) {
+                lines.push(`  ${frameLabel(entry.frame)}`);
+            }
+            const variables = Object.values(entry.variables ?? {});
+            const shown = variables.filter((variable) => {
+                if (variable.Name !== undefined && AMBIENT_LOCALS.has(variable.Name)) {
+                    droppedAmbient = true;
+                    return false;
+                }
+                return true;
+            });
+            if (shown.length === 0) {
+                lines.push("    (no locals in scope)");
+                continue;
+            }
+            for (const variable of shown) {
+                const type = variable.Type ? ` : ${variable.Type}` : "";
+                lines.push(`    ${variable.Name ?? "?"} = ${briefly(variable.Value ?? "nil")}${type}`);
+            }
+        }
+        // Frames below the top one, when the capture only carried the stack for them.
+        if (stack?.Frames && frames.length <= 1 && (stack.TotalFrames ?? 0) > 1) {
+            const rest = Object.values(stack.Frames).slice(1);
+            for (const frame of rest) {
+                lines.push(`  called from ${frameLabel(frame)}`);
+            }
+        }
+        blocks.push(lines.join("\n"));
+    });
+    if (droppedAmbient) {
+        blocks.push("(_G, shared, script and ... are omitted -- they are in scope everywhere.)");
+    }
+    return blocks.join("\n\n");
+}
+export function registerDebugTools(context) {
+    const { bridge } = context;
+    defineTool(context, {
+        name: "debug",
+        title: "Breakpoints and runtime inspection",
+        description: "Sets breakpoints that record the stack and variables when they are hit, " +
+            "then reads back what they caught.\n\n" +
+            "These are tracepoints, not a step debugger. A breakpoint fires, captures " +
+            "the call stack and the variables in scope, and lets execution continue; " +
+            "`op: \"snapshots\"` returns what was captured. Studio's debugger has to " +
+            "decide whether to resume the instant it stops, and cannot wait for a " +
+            "tool call to come back with an answer, so stepping through code line by " +
+            "line is not possible this way — but 'what was this value when it got " +
+            "here' is, which is usually the actual question.\n\n" +
+            "`condition` is a Luau expression evaluated where the breakpoint sits, so " +
+            "a breakpoint can fire only on the case that matters — `health < 0`, " +
+            "`player.Name == \"someone\"`.\n\n" +
+            "`logMessage` is ALSO a Luau expression, not a template string: its value " +
+            'is printed when the breakpoint is hit, so write `"index=" .. index` ' +
+            "rather than `index={index}`. Prose is a syntax error and the breakpoint " +
+            "is skipped. The engine prints it without stopping the thread at all, " +
+            "which makes it the cheapest way to watch a value change on a hot path " +
+            "or inside a tight loop — read the lines back with `console`.\n\n" +
+            "So the two kinds cost different things: a `logMessage` breakpoint never " +
+            "stops and gives you one line you composed in advance, while one without " +
+            "it stops briefly and gives you the whole frame — every local and its " +
+            "type, without having to guess beforehand which value would matter. " +
+            "Reach for the log when you know what to watch, the capture when you do " +
+            "not.\n\n" +
+            "Only one breakpoint exists per line, so the same line cannot both log " +
+            "and capture.\n\n" +
+            "Put the breakpoint on a line that does something. A `return`, an `end` " +
+            "or a bare declaration can verify and then never fire — measured, not " +
+            "guessed: the same breakpoint moved from `return squared, tag` to the " +
+            "assignment above it went from silent to firing on every pass. If one " +
+            "verifies but catches nothing, suspect the line before suspecting the " +
+            "condition.\n\n" +
+            "Breakpoints belong to the session that holds them. Set them in the " +
+            "editor session BEFORE starting a playtest, since code that already ran " +
+            "cannot be caught retroactively.\n\n" +
+            "Nothing here leaves a thread stopped waiting for you. A capture " +
+            "breakpoint stops for as long as it takes to read the frame and then " +
+            "resumes itself, so a script with one mid-loop still runs to its last " +
+            "line, and the user is never left with a frozen Studio to rescue.",
+        inputSchema: {
+            op: z
+                .enum(["set", "clear", "snapshots", "exceptions"])
+                .describe("'set' adds breakpoints, 'clear' removes one or all, 'snapshots' " +
+                "reads what has been captured, 'exceptions' controls breaking on errors."),
+            breakpoints: z
+                .array(z.object({
+                path: z.string().describe('Script path, e.g. "ServerScriptService.Combat".'),
+                line: z.number().int().min(1).describe("Line to break on."),
+                condition: z
+                    .string()
+                    .optional()
+                    .describe("Luau expression; the breakpoint only fires when it is true, " +
+                    'evaluated in scope at that line, e.g. "count > 100".'),
+                logMessage: z
+                    .string()
+                    .optional()
+                    .describe("Write this to the output when hit, instead of capturing a snapshot."),
+            }))
+                .max(50)
+                .optional()
+                .describe("set only: breakpoints to add."),
+            path: z
+                .string()
+                .optional()
+                .describe("clear only: remove breakpoints from this script. Omit to clear everything."),
+            line: z.number().int().min(1).optional().describe("clear only: which line to remove."),
+            mode: z
+                .enum(["Never", "Always", "Unhandled"])
+                .optional()
+                .describe("exceptions only: break on every error, only unhandled ones, or never. " +
+                "Defaults to Unhandled."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(40)
+                .default(10)
+                .describe("snapshots only: how many of the most recent to return."),
+            clear: z
+                .boolean()
+                .default(false)
+                .describe("snapshots only: discard what is returned, so the next read starts fresh."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        destructive: false,
+    }, async (args) => {
+        if (args.op === "snapshots") {
+            const response = await bridge.call("debug.snapshots", { limit: args.limit, clear: args.clear }, { studioId: args.studioId });
+            if (response.items.length === 0) {
+                return text("No breakpoints have been hit.\n" +
+                    "Breakpoints only catch code that runs after they are set, and they " +
+                    "belong to one session — if the code runs in a playtest, set them " +
+                    "before starting it and read them back from that playtest's studioId.");
+            }
+            const shown = response.items.length;
+            const footer = [
+                `${shown} of ${response.total} captured`,
+                response.overflow ? `${response.overflow} older snapshots were dropped` : undefined,
+            ]
+                .filter(Boolean)
+                .join(", ");
+            return text(`${renderSnapshots(response.items)}\n\n[${footer}]`);
+        }
+        if (args.op === "set") {
+            if (!args.breakpoints || args.breakpoints.length === 0) {
+                return text("set needs a `breakpoints` array.");
+            }
+            const response = await bridge.call("debug.set", { breakpoints: args.breakpoints }, { studioId: args.studioId });
+            const notes = [];
+            if (response.failed.length > 0) {
+                notes.push("Refused:\n" +
+                    response.failed.map((f) => `  ${f.path}:${f.line} — ${f.error}`).join("\n"));
+            }
+            return json(response.added, notes.length > 0 ? notes.join("\n\n") : undefined);
+        }
+        if (args.op === "exceptions") {
+            const response = await bridge.call("debug.exceptions", { mode: args.mode ?? "Unhandled" }, { studioId: args.studioId });
+            return text(`Breaking on exceptions: ${response.mode}.`);
+        }
+        const response = await bridge.call("debug.clear", { path: args.path, line: args.line }, { studioId: args.studioId });
+        return json(response);
+    });
+}
+//# sourceMappingURL=debug.js.map