@el4cteo/rbx-studio-mcp 0.7.2 → 0.7.6

package/plugin/src/handlers/Debug.luau

@@ -1,504 +1,574 @@
---!strict
---[[
-	Breakpoints and runtime inspection, through `ScriptDebuggerService`.
-
-	Not `DebuggerManager`, which is the legacy service and refuses plugins
-	outright -- it wants the LocalUser capability. ScriptDebuggerService is
-	PluginSecurity throughout and is what Roblox shipped to replace it.
-
-	Two things shape this design, both learned rather than assumed.
-
-	The service reports "ScriptDebuggerService was never initialized" until a
-	callback is attached, in an editor session and a running playtest alike. So
-	`OnStopped` is installed before anything else is attempted.
-
-	And `OnStopped` must return its resume decision synchronously. It cannot yield
-	waiting for an agent to look at the stack and decide what to do, which rules
-	out interactive stepping over a request/response protocol entirely. What works
-	instead is a tracepoint: the callback captures the stack and variables into a
-	buffer, lets execution continue, and the agent reads the snapshots afterwards.
-	For finding out what a value was at a moment in time -- which is what a
-	debugger is usually reached for -- that is as good, and it does not leave the
-	user's Studio frozen mid-frame.
-
-	The documented return shape is contradictory -- the API dump says the callback
-	returns a Dictionary, Roblox's own announcement returns
-	`Enum.DebuggerResumeType.Resume` directly -- and this file used to hedge by
-	never stopping at all, which is worth recording because the hedge cost the
-	whole feature. `ContinueExecution = true` means the debugger does not stop;
-	not stopping means `OnStopped` never runs; and `OnStopped` is the only place
-	a stack or a variable is readable. Every capture breakpoint verified, fired,
-	and recorded nothing, while logpoints on the same lines printed normally --
-	so the half that needed no callback worked and hid that the other half was
-	dead.
-
-	The enum is the right return. It resumes cleanly: a script with a breakpoint
-	mid-loop ran to completion untouched, so stopping to capture costs the run
-	nothing and strands nothing.
-
-	There is no third option. `DebuggerResumeType` offers StepInto, StepOut,
-	StepOver and Resume, and none of them means "stay stopped", so a breakpoint
-	that holds a thread for someone to look at is not expressible here -- which
-	is why nothing in this file offers one.
-]]
-
---[[
-	Fetched defensively, because this module is required at plugin start.
-
-	Measured with the beta off and Studio restarted: `GetService` does NOT throw
-	here, it hands back a working service object. So this guard is not fixing an
-	observed crash -- it is insurance on the one call in this file that runs
-	before any tool is invoked. init.server.luau requires this module alongside
-	every other handler, so a throw at this line would take down all 29 tools
-	rather than the three that need a debugger, and it would do it silently: a
-	plugin that never loads never connects, leaving nothing to read anywhere.
-
-	The beta is NOT detected here, because nothing detects it cheaply. See the
-	note on the wholesale-refusal branch in `Debug.set` for the two probes that
-	were tried and why neither works.
-]]
-local ScriptDebuggerService: any = nil
-do
-	local ok, service = pcall(game.GetService, game, "ScriptDebuggerService")
-	if ok then
-		ScriptDebuggerService = service
-	end
-end
-
-local Dispatch = require(script.Parent.Parent.Dispatch)
-local Paths = require(script.Parent.Parent.Paths)
-
--- Snapshots are far heavier than log lines: each carries a stack and its
--- variables. A tight cap keeps a breakpoint inside a loop from exhausting memory
--- before anyone reads it.
-local MAX_SNAPSHOTS = 40
-local MAX_FRAMES = 12
-local MAX_VARIABLES = 40
-
-local Debug = {}
-
-local service = ScriptDebuggerService :: any
-
-local snapshots: { { [string]: any } } = {}
-local overflow = 0
-local installed = false
-local installError: string? = nil
-
---[[
-	Which lines currently carry a breakpoint, per script.
-
-	`ScriptDebuggerService` exposes no way to list what is set -- `AddBreakpoint`
-	and `RemoveBreakpoint` are the whole surface, one line at a time -- so
-	"clear every breakpoint in this script" needs its own record of what this
-	module put there, or it cannot be done at all without either the caller
-	naming every line back or this file falling back to `ClearBreakpoints()`,
-	which takes the whole session's breakpoints with it, including ones set by
-	someone else sharing this Studio.
-]]
-local trackedBreakpoints: { [Instance]: { [number]: boolean } } = {}
-
-local function track(target: Instance, line: number)
-	local lines = trackedBreakpoints[target]
-	if lines == nil then
-		lines = {}
-		trackedBreakpoints[target] = lines
-	end
-	lines[line] = true
-end
-
-local function untrack(target: Instance, line: number)
-	local lines = trackedBreakpoints[target]
-	if lines then
-		lines[line] = nil
-	end
-end
-
---[[
-	Flattens whatever the service hands back.
-
-	Every one of these shapes is undocumented, so nothing is indexed by a guessed
-	field name. Keys are taken as they come and values stringified, which means an
-	unfamiliar shape arrives readable instead of arriving empty.
-]]
-local function flatten(value: any, depth: number): any
-	if depth > 3 then
-		return "<nested>"
-	end
-	local kind = typeof(value)
-	if kind ~= "table" then
-		if kind == "Instance" then
-			return (value :: Instance):GetFullName()
-		end
-		if kind == "EnumItem" then
-			return tostring(value)
-		end
-		return if kind == "string" or kind == "number" or kind == "boolean"
-			then value
-			else tostring(value)
-	end
-
-	local source = value :: { [any]: any }
-	local out: { [string]: any } = {}
-	local count = 0
-	for key, item in source do
-		count += 1
-		if count > MAX_VARIABLES then
-			out["..."] = "more"
-			break
-		end
-		out[tostring(key)] = flatten(item, depth + 1)
-	end
-	return out
-end
-
---[[
-	Builds the record for one stop.
-
-	Each lookup is guarded on its own. A stop that yields a thread id but no
-	readable variables is still worth keeping, and losing the whole snapshot to
-	one failed call would waste the only moment the data existed.
-]]
-local function capture(stopped: any)
-	local record: { [string]: any } = {
-		at = os.time(),
-		stopped = flatten(stopped, 0),
-	}
-
-	--[[
-		`ThreadIds`, plural, holding an array -- measured from a real stop:
-
-			{ ThreadIds = {3002}, Reason = Enum.ScriptStoppedReason.Breakpoint }
-
-		Reading `ThreadId` instead cost nothing visible: snapshots still arrived,
-		carrying the reason and nothing else, so a breakpoint looked like it was
-		working while the stack and variables it exists to collect were never
-		fetched.
-	]]
-	local threadId: any = nil
-	if typeof(stopped) == "table" then
-		local ids = (stopped :: any).ThreadIds
-		threadId = if typeof(ids) == "table" then (ids :: { any })[1] else (stopped :: any).ThreadId
-	end
-
-	if threadId ~= nil then
-		local ok, trace = pcall(function()
-			return service:GetStackTrace(threadId)
-		end)
-		if ok then
-			record.stack = flatten(trace, 0)
-
-			-- Variables hang off a frame, so they are only reachable once the
-			-- trace has given up a frame id.
-			local frames = if typeof(trace) == "table" then (trace :: any).Frames else nil
-			if typeof(frames) == "table" then
-				local locals: { any } = {}
-				for index, frame in frames :: { any } do
-					if index > MAX_FRAMES then
-						break
-					end
-					-- `Id`, measured: a frame is {Id, Line, Name, ScriptPath}. The
-					-- StackFrame *instance* used by Studio's own debugger calls
-					-- it FrameId, which is what this read first, and the
-					-- mismatch cost only the variables -- the frame itself still
-					-- listed, so the stack looked complete.
-					local raw = frame :: any
-					local frameId = if typeof(frame) == "table" then (raw.Id or raw.FrameId) else nil
-					if frameId ~= nil then
-						local gotVars, vars = pcall(function()
-							return service:GetRootVariables(frameId)
-						end)
-						table.insert(locals, {
-							frame = flatten(frame, 1),
-							variables = if gotVars then flatten(vars, 1) else tostring(vars),
-						})
-					end
-				end
-				record.frames = locals
-			end
-		else
-			record.stackError = tostring(trace)
-		end
-	end
-
-	if #snapshots >= MAX_SNAPSHOTS then
-		table.remove(snapshots, 1)
-		overflow += 1
-	end
-	table.insert(snapshots, record)
-end
-
---[[
-	Attaches the callback, which is also what initialises the service.
-
-	The resume decision follows Roblox's own example and returns the enum rather
-	than the Dictionary the dump describes. That is settled by observation now,
-	not by preference: breakpoints stop, this returns, and the stopped script
-	carries on to its last line.
-]]
-local function install(): boolean
-	if installed then
-		return true
-	end
-
-	if ScriptDebuggerService == nil then
-		installError = "the service is not registered in this Studio"
-		return false
-	end
-
-	local ok, err = pcall(function()
-		service.OnStopped = function(stopped: any): any
-			-- Capture must never be what keeps a thread paused.
-			pcall(capture, stopped)
-			return Enum.DebuggerResumeType.Resume
-		end
-	end)
-
-	if not ok then
-		installError = tostring(err)
-		return false
-	end
-	installed = true
-	installError = nil
-	return true
-end
-
-local function requireService()
-	if not install() then
-		Dispatch.fail(
-			"NO_DEBUGGER",
-			string.format(
-				"ScriptDebuggerService is not available in this session: %s",
-				tostring(installError)
-			),
-			"Turn on \"Debugger Luau API\" in File > Beta Features and restart Studio. "
-				.. "It is off by default, and the service is not registered until it is on."
-		)
-	end
-end
-
-function Debug.set(params: { [string]: any }): { [string]: any }
-	requireService()
-
-	local requested = params.breakpoints
-	if typeof(requested) ~= "table" then
-		Dispatch.fail("BAD_PARAMS", "debug set requires a `breakpoints` array.")
-	end
-
-	local added: { { [string]: any } } = {}
-	local failed: { { [string]: any } } = {}
-
-	for _, item in requested :: { { [string]: any } } do
-		local target = Paths.resolve(item.path)
-		if not target:IsA("LuaSourceContainer") then
-			Dispatch.fail(
-				"NOT_A_SCRIPT",
-				string.format("%s is a %s, not a script.", item.path, target.ClassName)
-			)
-		end
-
-		--[[
-			Capitalised keys, from Roblox's example -- `Line`, `Condition`,
-			`LogMessage`, `ContinueExecution`. Lowercase `line` was rejected.
-
-			`ContinueExecution` decides whether the debugger stops at all, and
-			stopping is the only thing that raises `OnStopped` -- which is the
-			only place a stack or a variable can be read. So a breakpoint that
-			continues past itself captures nothing, ever.
-
-			That was this file's default, on the reasoning that not stopping was
-			the safe choice: a wrong return from the callback could strand a
-			paused thread, and never pausing made that impossible. It also made
-			the feature impossible. Measured on a line proven to fire -- the same
-			breakpoint, same condition, differing only here -- it captured
-			nothing across two sessions, while the identical breakpoint carrying
-			a LogMessage printed on cue.
-
-			Stopping is not the hazard it was assumed to be. `OnStopped` returns
-			`Resume` and the thread continues on its own: the probe script ran to
-			completion, printing every line after the breakpoint, with no one
-			touching Studio. So capture stops, and a LogMessage -- which the
-			engine prints without help -- does not need to.
-		]]
-		local logMessage = if typeof(item.logMessage) == "string" and item.logMessage ~= ""
-			then item.logMessage
-			else nil
-		local descriptor: { [string]: any } = {
-			Line = tonumber(item.line),
-			ContinueExecution = logMessage ~= nil,
-		}
-		if typeof(item.condition) == "string" and item.condition ~= "" then
-			descriptor.Condition = item.condition
-		end
-		if logMessage ~= nil then
-			descriptor.LogMessage = logMessage
-		end
-
-		local ok, result = pcall(function()
-			return service:AddBreakpoint(target, descriptor)
-		end)
-
-		if ok then
-			track(target, descriptor.Line)
-			table.insert(added, {
-				path = Paths.of(target),
-				line = descriptor.Line,
-				-- What it will do when hit, since the two kinds behave nothing
-				-- alike: one writes a line to the output, the other stops long
-				-- enough to read the stack and then resumes itself.
-				mode = if logMessage ~= nil then "log" else "capture",
-				result = flatten(result, 1),
-			})
-		else
-			table.insert(failed, { path = item.path, line = descriptor.Line, error = tostring(result) })
-		end
-	end
-
-	--[[
-		A wholesale refusal names the likely cause without asserting it.
-
-		`AddBreakpoint` is where the "Debugger Luau API" beta actually bites, and
-		its own message -- "Failed to execute AddBreakpoint request" -- names
-		nothing anyone can act on. The beta cannot be detected from here to say
-		so with certainty, and two attempts to are worth recording so they are
-		not tried a third time: with the beta OFF, `GetService`, `FindService`,
-		assigning `OnStopped` and `Enum.DebuggerResumeType` all still succeed;
-		with the beta ON, `ReflectionService` still does not list the class. The
-		first is always available and the second never is, so neither varies with
-		the thing being measured.
-
-		The only reliable test is this call, which cannot be run speculatively on
-		a user's script just to answer a status question. So the hint says what
-		to check first and what else it could be, and does not claim to know.
-	]]
-	if #added == 0 and #failed > 0 then
-		Dispatch.fail(
-			"NO_BREAKPOINTS_SET",
-			string.format("No breakpoint could be set; all %d were refused.", #failed),
-			"Check that \"Debugger Luau API\" is on in File > Beta Features and that "
-				.. "Studio has been restarted since -- that is the usual cause, it is "
-				.. "off by default, and only the user can change it. Otherwise the "
-				.. "line may not be one that runs: a `return`, an `end` or a bare "
-				.. "declaration is often refused, so try the statement above it."
-		)
-	end
-
-	return { added = added, failed = failed, installed = installed }
-end
-
-function Debug.clear(params: { [string]: any }): { [string]: any }
-	requireService()
-
-	local path = params.path
-	if typeof(path) == "string" and path ~= "" then
-		local target = Paths.resolve(path)
-		local line = tonumber(params.line)
-
-		if line ~= nil then
-			local ok, removed = pcall(function()
-				return service:RemoveBreakpoint(target, line)
-			end)
-			untrack(target, line)
-			return { removed = ok and removed == true, path = Paths.of(target), line = line }
-		end
-
-		--[[
-			`path` alone, no `line`: every breakpoint this module put in that
-			script. `ScriptDebuggerService` has no "list breakpoints in this
-			script" of its own -- only `AddBreakpoint`/`RemoveBreakpoint`, one
-			line at a time -- so `trackedBreakpoints` is what makes this
-			possible at all, and it is also the reason it can only remove what
-			this session set: a breakpoint another client or the user placed
-			by hand was never tracked here, and this cannot see it to touch it.
-		]]
-		local lines = trackedBreakpoints[target]
-		local removedLines: { number } = {}
-		if lines then
-			for lineNumber in lines do
-				local ok = pcall(function()
-					service:RemoveBreakpoint(target, lineNumber)
-				end)
-				if ok then
-					table.insert(removedLines, lineNumber)
-				end
-			end
-			trackedBreakpoints[target] = nil
-		end
-		table.sort(removedLines)
-		return { removed = #removedLines > 0, path = Paths.of(target), lines = removedLines }
-	end
-
-	local ok, err = pcall(function()
-		service:ClearBreakpoints()
-	end)
-	if not ok then
-		Dispatch.fail("REFUSED", string.format("ClearBreakpoints refused: %s", tostring(err)))
-	end
-	table.clear(trackedBreakpoints)
-	return { cleared = true }
-end
-
-function Debug.snapshots(params: { [string]: any }): { [string]: any }
-	local limit = math.clamp(tonumber(params.limit) or 10, 1, MAX_SNAPSHOTS)
-
-	local out: { { [string]: any } } = {}
-	local first = math.max(1, #snapshots - limit + 1)
-	for index = first, #snapshots do
-		table.insert(out, snapshots[index])
-	end
-
-	if params.clear == true then
-		snapshots = {}
-		overflow = 0
-	end
-
-	return {
-		items = out,
-		total = #snapshots,
-		overflow = if overflow > 0 then overflow else nil,
-		installed = installed,
-	}
-end
-
-function Debug.exceptions(params: { [string]: any }): { [string]: any }
-	requireService()
-
-	local mode = tostring(params.mode or "Unhandled")
-	local item = (Enum.DebugBreakModeType :: any)[mode]
-	if item == nil then
-		Dispatch.fail("BAD_PARAMS", string.format("unknown break mode %q", mode))
-	end
-
-	local ok, err = pcall(function()
-		service:SetExceptionBreakMode(item)
-	end)
-	if not ok then
-		Dispatch.fail("REFUSED", string.format("SetExceptionBreakMode refused: %s", tostring(err)))
-	end
-	return { mode = mode }
-end
-
-function Debug.register()
-	--[[
-		Installed at load, not on the first debug request.
-
-		A breakpoint is registered in one session and hit in another: the editor
-		holds it, the playtest's DataModel runs the code and raises the stop. That
-		second session is created by pressing play, long after any tool call
-		reached the first, so waiting for a request to install the callback leaves
-		exactly the session that does the stopping without one -- and a breakpoint
-		that verifies, fires, and records nothing.
-
-		Attaching it here costs a callback assignment per session and means every
-		session is ready before anything needs it.
-	]]
-	install()
-
-	Dispatch.registerAll("debug", {
-		set = Debug.set,
-		clear = Debug.clear,
-		snapshots = Debug.snapshots,
-		exceptions = Debug.exceptions,
-	})
-end
-
-return Debug
+--!strict
+--[[
+	Breakpoints and runtime inspection, through `ScriptDebuggerService`.
+
+	Not `DebuggerManager`, which is the legacy service and refuses plugins
+	outright -- it wants the LocalUser capability. ScriptDebuggerService is
+	PluginSecurity throughout and is what Roblox shipped to replace it.
+
+	Two things shape this design, both learned rather than assumed.
+
+	The service reports "ScriptDebuggerService was never initialized" until a
+	callback is attached, in an editor session and a running playtest alike. So
+	`OnStopped` is installed before anything else is attempted.
+
+	And `OnStopped` must return its resume decision synchronously. It cannot yield
+	waiting for an agent to look at the stack and decide what to do, which rules
+	out interactive stepping over a request/response protocol entirely. What works
+	instead is a tracepoint: the callback captures the stack and variables into a
+	buffer, lets execution continue, and the agent reads the snapshots afterwards.
+	For finding out what a value was at a moment in time -- which is what a
+	debugger is usually reached for -- that is as good, and it does not leave the
+	user's Studio frozen mid-frame.
+
+	The documented return shape is contradictory -- the API dump says the callback
+	returns a Dictionary, Roblox's own announcement returns
+	`Enum.DebuggerResumeType.Resume` directly -- and this file used to hedge by
+	never stopping at all, which is worth recording because the hedge cost the
+	whole feature. `ContinueExecution = true` means the debugger does not stop;
+	not stopping means `OnStopped` never runs; and `OnStopped` is the only place
+	a stack or a variable is readable. Every capture breakpoint verified, fired,
+	and recorded nothing, while logpoints on the same lines printed normally --
+	so the half that needed no callback worked and hid that the other half was
+	dead.
+
+	The enum is the right return. It resumes cleanly: a script with a breakpoint
+	mid-loop ran to completion untouched, so stopping to capture costs the run
+	nothing and strands nothing.
+
+	There is no third option. `DebuggerResumeType` offers StepInto, StepOut,
+	StepOver and Resume, and none of them means "stay stopped", so a breakpoint
+	that holds a thread for someone to look at is not expressible here -- which
+	is why nothing in this file offers one.
+]]
+
+--[[
+	Fetched defensively, because this module is required at plugin start.
+
+	Measured with the beta off and Studio restarted: `GetService` does NOT throw
+	here, it hands back a working service object. So this guard is not fixing an
+	observed crash -- it is insurance on the one call in this file that runs
+	before any tool is invoked. init.server.luau requires this module alongside
+	every other handler, so a throw at this line would take down all 29 tools
+	rather than the three that need a debugger, and it would do it silently: a
+	plugin that never loads never connects, leaving nothing to read anywhere.
+
+	The beta is NOT detected here, because nothing detects it cheaply. See the
+	note on the wholesale-refusal branch in `Debug.set` for the two probes that
+	were tried and why neither works.
+]]
+local ScriptDebuggerService: any = nil
+do
+	local ok, service = pcall(game.GetService, game, "ScriptDebuggerService")
+	if ok then
+		ScriptDebuggerService = service
+	end
+end
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local Paths = require(script.Parent.Parent.Paths)
+local ClientRelay = require(script.Parent.Parent.ClientRelay)
+local RemoteTrace = require(script.Parent.Parent.RemoteTrace)
+
+-- Snapshots are far heavier than log lines: each carries a stack and its
+-- variables. A tight cap keeps a breakpoint inside a loop from exhausting memory
+-- before anyone reads it.
+local MAX_SNAPSHOTS = 40
+local MAX_FRAMES = 12
+local MAX_VARIABLES = 40
+
+local Debug = {}
+
+local service = ScriptDebuggerService :: any
+
+local snapshots: { { [string]: any } } = {}
+local overflow = 0
+local installed = false
+local installError: string? = nil
+
+--[[
+	Which lines currently carry a breakpoint, per script.
+
+	`ScriptDebuggerService` exposes no way to list what is set -- `AddBreakpoint`
+	and `RemoveBreakpoint` are the whole surface, one line at a time -- so
+	"clear every breakpoint in this script" needs its own record of what this
+	module put there, or it cannot be done at all without either the caller
+	naming every line back or this file falling back to `ClearBreakpoints()`,
+	which takes the whole session's breakpoints with it, including ones set by
+	someone else sharing this Studio.
+]]
+local trackedBreakpoints: { [Instance]: { [number]: boolean } } = {}
+
+local function track(target: Instance, line: number)
+	local lines = trackedBreakpoints[target]
+	if lines == nil then
+		lines = {}
+		trackedBreakpoints[target] = lines
+	end
+	lines[line] = true
+end
+
+local function untrack(target: Instance, line: number)
+	local lines = trackedBreakpoints[target]
+	if lines then
+		lines[line] = nil
+	end
+end
+
+--[[
+	Flattens whatever the service hands back.
+
+	Every one of these shapes is undocumented, so nothing is indexed by a guessed
+	field name. Keys are taken as they come and values stringified, which means an
+	unfamiliar shape arrives readable instead of arriving empty.
+]]
+local function flatten(value: any, depth: number): any
+	if depth > 3 then
+		return "<nested>"
+	end
+	local kind = typeof(value)
+	if kind ~= "table" then
+		if kind == "Instance" then
+			return (value :: Instance):GetFullName()
+		end
+		if kind == "EnumItem" then
+			return tostring(value)
+		end
+		return if kind == "string" or kind == "number" or kind == "boolean"
+			then value
+			else tostring(value)
+	end
+
+	local source = value :: { [any]: any }
+	local out: { [string]: any } = {}
+	local count = 0
+	for key, item in source do
+		count += 1
+		if count > MAX_VARIABLES then
+			out["..."] = "more"
+			break
+		end
+		out[tostring(key)] = flatten(item, depth + 1)
+	end
+	return out
+end
+
+--[[
+	Builds the record for one stop.
+
+	Each lookup is guarded on its own. A stop that yields a thread id but no
+	readable variables is still worth keeping, and losing the whole snapshot to
+	one failed call would waste the only moment the data existed.
+]]
+local function capture(stopped: any)
+	local record: { [string]: any } = {
+		at = os.time(),
+		stopped = flatten(stopped, 0),
+	}
+
+	--[[
+		`ThreadIds`, plural, holding an array -- measured from a real stop:
+
+			{ ThreadIds = {3002}, Reason = Enum.ScriptStoppedReason.Breakpoint }
+
+		Reading `ThreadId` instead cost nothing visible: snapshots still arrived,
+		carrying the reason and nothing else, so a breakpoint looked like it was
+		working while the stack and variables it exists to collect were never
+		fetched.
+	]]
+	local threadId: any = nil
+	if typeof(stopped) == "table" then
+		local ids = (stopped :: any).ThreadIds
+		threadId = if typeof(ids) == "table" then (ids :: { any })[1] else (stopped :: any).ThreadId
+	end
+
+	if threadId ~= nil then
+		local ok, trace = pcall(function()
+			return service:GetStackTrace(threadId)
+		end)
+		if ok then
+			record.stack = flatten(trace, 0)
+
+			-- Variables hang off a frame, so they are only reachable once the
+			-- trace has given up a frame id.
+			local frames = if typeof(trace) == "table" then (trace :: any).Frames else nil
+			if typeof(frames) == "table" then
+				local locals: { any } = {}
+				for index, frame in frames :: { any } do
+					if index > MAX_FRAMES then
+						break
+					end
+					-- `Id`, measured: a frame is {Id, Line, Name, ScriptPath}. The
+					-- StackFrame *instance* used by Studio's own debugger calls
+					-- it FrameId, which is what this read first, and the
+					-- mismatch cost only the variables -- the frame itself still
+					-- listed, so the stack looked complete.
+					local raw = frame :: any
+					local frameId = if typeof(frame) == "table" then (raw.Id or raw.FrameId) else nil
+					if frameId ~= nil then
+						local gotVars, vars = pcall(function()
+							return service:GetRootVariables(frameId)
+						end)
+						table.insert(locals, {
+							frame = flatten(frame, 1),
+							variables = if gotVars then flatten(vars, 1) else tostring(vars),
+						})
+					end
+				end
+				record.frames = locals
+			end
+		else
+			record.stackError = tostring(trace)
+		end
+	end
+
+	if #snapshots >= MAX_SNAPSHOTS then
+		table.remove(snapshots, 1)
+		overflow += 1
+	end
+	table.insert(snapshots, record)
+end
+
+--[[
+	Attaches the callback, which is also what initialises the service.
+
+	The resume decision follows Roblox's own example and returns the enum rather
+	than the Dictionary the dump describes. That is settled by observation now,
+	not by preference: breakpoints stop, this returns, and the stopped script
+	carries on to its last line.
+]]
+local function install(): boolean
+	if installed then
+		return true
+	end
+
+	if ScriptDebuggerService == nil then
+		installError = "the service is not registered in this Studio"
+		return false
+	end
+
+	local ok, err = pcall(function()
+		service.OnStopped = function(stopped: any): any
+			-- Capture must never be what keeps a thread paused.
+			pcall(capture, stopped)
+			return Enum.DebuggerResumeType.Resume
+		end
+	end)
+
+	if not ok then
+		installError = tostring(err)
+		return false
+	end
+	installed = true
+	installError = nil
+	return true
+end
+
+local function requireService()
+	if not install() then
+		Dispatch.fail(
+			"NO_DEBUGGER",
+			string.format(
+				"ScriptDebuggerService is not available in this session: %s",
+				tostring(installError)
+			),
+			"Turn on \"Debugger Luau API\" in File > Beta Features and restart Studio. "
+				.. "It is off by default, and the service is not registered until it is on."
+		)
+	end
+end
+
+function Debug.set(params: { [string]: any }): { [string]: any }
+	requireService()
+
+	local requested = params.breakpoints
+	if typeof(requested) ~= "table" then
+		Dispatch.fail("BAD_PARAMS", "debug set requires a `breakpoints` array.")
+	end
+
+	local added: { { [string]: any } } = {}
+	local failed: { { [string]: any } } = {}
+
+	for _, item in requested :: { { [string]: any } } do
+		local target = Paths.resolve(item.path)
+		if not target:IsA("LuaSourceContainer") then
+			Dispatch.fail(
+				"NOT_A_SCRIPT",
+				string.format("%s is a %s, not a script.", item.path, target.ClassName)
+			)
+		end
+
+		--[[
+			Capitalised keys, from Roblox's example -- `Line`, `Condition`,
+			`LogMessage`, `ContinueExecution`. Lowercase `line` was rejected.
+
+			`ContinueExecution` decides whether the debugger stops at all, and
+			stopping is the only thing that raises `OnStopped` -- which is the
+			only place a stack or a variable can be read. So a breakpoint that
+			continues past itself captures nothing, ever.
+
+			That was this file's default, on the reasoning that not stopping was
+			the safe choice: a wrong return from the callback could strand a
+			paused thread, and never pausing made that impossible. It also made
+			the feature impossible. Measured on a line proven to fire -- the same
+			breakpoint, same condition, differing only here -- it captured
+			nothing across two sessions, while the identical breakpoint carrying
+			a LogMessage printed on cue.
+
+			Stopping is not the hazard it was assumed to be. `OnStopped` returns
+			`Resume` and the thread continues on its own: the probe script ran to
+			completion, printing every line after the breakpoint, with no one
+			touching Studio. So capture stops, and a LogMessage -- which the
+			engine prints without help -- does not need to.
+		]]
+		local logMessage = if typeof(item.logMessage) == "string" and item.logMessage ~= ""
+			then item.logMessage
+			else nil
+		local descriptor: { [string]: any } = {
+			Line = tonumber(item.line),
+			ContinueExecution = logMessage ~= nil,
+		}
+		if typeof(item.condition) == "string" and item.condition ~= "" then
+			descriptor.Condition = item.condition
+		end
+		if logMessage ~= nil then
+			descriptor.LogMessage = logMessage
+		end
+
+		local ok, result = pcall(function()
+			return service:AddBreakpoint(target, descriptor)
+		end)
+
+		if ok then
+			track(target, descriptor.Line)
+			table.insert(added, {
+				path = Paths.of(target),
+				line = descriptor.Line,
+				-- What it will do when hit, since the two kinds behave nothing
+				-- alike: one writes a line to the output, the other stops long
+				-- enough to read the stack and then resumes itself.
+				mode = if logMessage ~= nil then "log" else "capture",
+				result = flatten(result, 1),
+			})
+		else
+			table.insert(failed, { path = item.path, line = descriptor.Line, error = tostring(result) })
+		end
+	end
+
+	--[[
+		A wholesale refusal names the likely cause without asserting it.
+
+		`AddBreakpoint` is where the "Debugger Luau API" beta actually bites, and
+		its own message -- "Failed to execute AddBreakpoint request" -- names
+		nothing anyone can act on. The beta cannot be detected from here to say
+		so with certainty, and two attempts to are worth recording so they are
+		not tried a third time: with the beta OFF, `GetService`, `FindService`,
+		assigning `OnStopped` and `Enum.DebuggerResumeType` all still succeed;
+		with the beta ON, `ReflectionService` still does not list the class. The
+		first is always available and the second never is, so neither varies with
+		the thing being measured.
+
+		The only reliable test is this call, which cannot be run speculatively on
+		a user's script just to answer a status question. So the hint says what
+		to check first and what else it could be, and does not claim to know.
+	]]
+	if #added == 0 and #failed > 0 then
+		Dispatch.fail(
+			"NO_BREAKPOINTS_SET",
+			string.format("No breakpoint could be set; all %d were refused.", #failed),
+			"Check that \"Debugger Luau API\" is on in File > Beta Features and that "
+				.. "Studio has been restarted since -- that is the usual cause, it is "
+				.. "off by default, and only the user can change it. Otherwise the "
+				.. "line may not be one that runs: a `return`, an `end` or a bare "
+				.. "declaration is often refused, so try the statement above it."
+		)
+	end
+
+	return { added = added, failed = failed, installed = installed }
+end
+
+function Debug.clear(params: { [string]: any }): { [string]: any }
+	requireService()
+
+	local path = params.path
+	if typeof(path) == "string" and path ~= "" then
+		local target = Paths.resolve(path)
+		local line = tonumber(params.line)
+
+		if line ~= nil then
+			local ok, removed = pcall(function()
+				return service:RemoveBreakpoint(target, line)
+			end)
+			untrack(target, line)
+			return { removed = ok and removed == true, path = Paths.of(target), line = line }
+		end
+
+		--[[
+			`path` alone, no `line`: every breakpoint this module put in that
+			script. `ScriptDebuggerService` has no "list breakpoints in this
+			script" of its own -- only `AddBreakpoint`/`RemoveBreakpoint`, one
+			line at a time -- so `trackedBreakpoints` is what makes this
+			possible at all, and it is also the reason it can only remove what
+			this session set: a breakpoint another client or the user placed
+			by hand was never tracked here, and this cannot see it to touch it.
+		]]
+		local lines = trackedBreakpoints[target]
+		local removedLines: { number } = {}
+		if lines then
+			for lineNumber in lines do
+				local ok = pcall(function()
+					service:RemoveBreakpoint(target, lineNumber)
+				end)
+				if ok then
+					table.insert(removedLines, lineNumber)
+				end
+			end
+			trackedBreakpoints[target] = nil
+		end
+		table.sort(removedLines)
+		return { removed = #removedLines > 0, path = Paths.of(target), lines = removedLines }
+	end
+
+	local ok, err = pcall(function()
+		service:ClearBreakpoints()
+	end)
+	if not ok then
+		Dispatch.fail("REFUSED", string.format("ClearBreakpoints refused: %s", tostring(err)))
+	end
+	table.clear(trackedBreakpoints)
+	return { cleared = true }
+end
+
+function Debug.snapshots(params: { [string]: any }): { [string]: any }
+	local limit = math.clamp(tonumber(params.limit) or 10, 1, MAX_SNAPSHOTS)
+
+	local out: { { [string]: any } } = {}
+	local first = math.max(1, #snapshots - limit + 1)
+	for index = first, #snapshots do
+		table.insert(out, snapshots[index])
+	end
+
+	if params.clear == true then
+		snapshots = {}
+		overflow = 0
+	end
+
+	return {
+		items = out,
+		total = #snapshots,
+		overflow = if overflow > 0 then overflow else nil,
+		installed = installed,
+	}
+end
+
+function Debug.exceptions(params: { [string]: any }): { [string]: any }
+	requireService()
+
+	local mode = tostring(params.mode or "Unhandled")
+	local item = (Enum.DebugBreakModeType :: any)[mode]
+	if item == nil then
+		Dispatch.fail("BAD_PARAMS", string.format("unknown break mode %q", mode))
+	end
+
+	local ok, err = pcall(function()
+		service:SetExceptionBreakMode(item)
+	end)
+	if not ok then
+		Dispatch.fail("REFUSED", string.format("SetExceptionBreakMode refused: %s", tostring(err)))
+	end
+	return { mode = mode }
+end
+
+-- Additive listeners only: no RemoteFunction callbacks or game remote sends.
+function Debug.remotes(params: { [string]: any }): { [string]: any }
+	local player = ClientRelay.playerFor(params.player)
+	local seconds = math.clamp(tonumber(params.seconds) or 5, 1, 15)
+	local path = if typeof(params.path) == "string" then params.path else "game"
+	local root = if path == "game" then game else Paths.resolve(path)
+	local stopServer: (() -> { [string]: any })? = nil
+	local ok, client = pcall(function()
+		return ClientRelay.run(player, "MCPRemoteTraceRelay", [==[
+local report = script:WaitForChild("Report", 10)
+if not report then return end
+local stop, handshake, destruction
+local ok, result = pcall(function()
+	assert(game:GetService("RunService"):IsClient(), "Client VM required")
+	local Trace = require(script:WaitForChild("RemoteTrace"))
+	local Paths = require(script:WaitForChild("Paths"))
+	local path = script:GetAttribute("Path")
+	local root = if path == "game" then game else Paths.resolve(path)
+	local ready = false
+	handshake = report.OnClientEvent:Connect(function() ready = true end)
+	report:FireServer({ready = true})
+	local deadline = os.clock() + 5
+	while not ready and os.clock() < deadline do task.wait() end
+	handshake:Disconnect()
+	assert(ready, "Trace startup acknowledgement timed out")
+	stop = Trace.start(root, game:GetService("Players").LocalPlayer, true, script:GetAttribute("Seconds"), script)
+	destruction = script.Destroying:Connect(function() stop() end)
+	script:SetAttribute("Capturing", true)
+	task.wait(script:GetAttribute("Seconds"))
+	return stop()
+end)
+if handshake then handshake:Disconnect() end
+if destruction then destruction:Disconnect() end
+if stop then stop() end
+report:FireServer(if ok then {ok = true, capture = result} else {ok = false, reason = tostring(result)})
+]==], { Seconds = seconds, Path = path }, seconds + 10, function(relay)
+			for _, name in { "RemoteTrace", "Paths", "Dispatch" } do
+				local copy = script.Parent.Parent[name]:Clone()
+				copy.Parent = relay
+			end
+		end, function()
+			stopServer = RemoteTrace.start(root, player, false, seconds, nil)
+		end)
+	end)
+	local server = if stopServer then stopServer() else nil
+	if not ok then error(client, 0) end
+	if client.ok ~= true or server == nil then
+		Dispatch.fail("TRACE_FAILED", tostring(client.reason or "The client did not start the capture."))
+	end
+	local received = client.capture
+	local items = server.items
+	for _, item in received.items do table.insert(items, item) end
+	local result = { items = items, player = player.Name, requestedSeconds = seconds,
+		serverSeconds = server.seconds, clientSeconds = received.seconds,
+		events = server.events + received.events,
+		truncated = server.eventLimitReached or received.eventLimitReached or server.scanLimitReached
+			or received.scanLimitReached or server.rowsOmitted or received.rowsOmitted or server.skipped > 0 or received.skipped > 0,
+		note = "Received traffic for this player only; at most 1000 events per direction, 128 remotes per VM and 40 rows. Only visible, accessible remotes are observed. Samples show the first two shapes, not every payload. Rates use each direction's observed window." }
+	-- A byte ceiling includes JSON escaping; never silently expand the MCP response.
+	local HttpService = game:GetService("HttpService")
+	while #items > 0 and #HttpService:JSONEncode(result) > 12000 do
+		table.remove(items)
+		result.truncated = true
+	end
+	return result
+end
+
+function Debug.register()
+	--[[
+		Installed at load, not on the first debug request.
+
+		A breakpoint is registered in one session and hit in another: the editor
+		holds it, the playtest's DataModel runs the code and raises the stop. That
+		second session is created by pressing play, long after any tool call
+		reached the first, so waiting for a request to install the callback leaves
+		exactly the session that does the stopping without one -- and a breakpoint
+		that verifies, fires, and records nothing.
+
+		Attaching it here costs a callback assignment per session and means every
+		session is ready before anything needs it.
+	]]
+	install()
+
+	Dispatch.registerAll("debug", {
+		set = Debug.set,
+		clear = Debug.clear,
+		snapshots = Debug.snapshots,
+		exceptions = Debug.exceptions,
+		remotes = Debug.remotes,
+	})
+end
+
+return Debug