@el4cteo/rbx-studio-mcp 0.8.4 → 0.8.6

package/plugin/src/Dispatch.luau

@@ -1,90 +1,131 @@
---!strict
---[[
-	Handler registry and the single error boundary around every command.
-
-	Handlers raise failures with `Dispatch.fail(code, message, hint)`. The hint is
-	forwarded verbatim to the agent, so it should say what to do next ("call find
-	first to get a valid path"), not just what went wrong.
-]]
-
-local Dispatch = {}
-
-export type Error = {
-	code: string,
-	message: string,
-	hint: string?,
-}
-
-export type Handler = (params: { [string]: any }) -> any
-
-local handlers: { [string]: Handler } = {}
-
-function Dispatch.register(op: string, handler: Handler)
-	handlers[op] = handler
-end
-
---[[
-	Registers every entry of `map` under the prefix, e.g. `registerAll("script",
-	{ read = fn })` exposes "script.read".
-]]
-function Dispatch.registerAll(prefix: string, map: { [string]: Handler })
-	for name, handler in map do
-		handlers[prefix .. "." .. name] = handler
-	end
-end
-
---[[
-	Raises a structured failure. Always call this rather than `error("...")` so
-	the agent receives a code it can branch on and a hint it can act on.
-]]
-function Dispatch.fail(code: string, message: string, hint: string?): never
-	error({ code = code, message = message, hint = hint }, 0)
-end
-
-export type Result = {
-	id: string,
-	ok: boolean,
-	data: any?,
-	error: Error?,
-}
-
---[[
-	Runs one command and returns the frame to POST back. Never throws: an
-	unhandled error inside a handler becomes a HANDLER_ERROR result, because a
-	crashed dispatch would leave the server's promise hanging until it times out.
-]]
-function Dispatch.invoke(id: string, op: string, params: { [string]: any }?): Result
-	local handler = handlers[op]
-	if not handler then
-		return {
-			id = id,
-			ok = false,
-			error = {
-				code = "UNKNOWN_OP",
-				message = string.format('This Studio plugin has no handler for "%s".', op),
-				hint = "The plugin is older than the MCP server. Update the Studio MCP "
-					.. "plugin to the version matching your server.",
-			},
-		}
-	end
-
-	local ok, result = pcall(handler, params or {})
-	if ok then
-		return { id = id, ok = true, data = result }
-	end
-
-	if typeof(result) == "table" and (result :: any).code then
-		return { id = id, ok = false, error = result :: Error }
-	end
-
-	return {
-		id = id,
-		ok = false,
-		error = {
-			code = "HANDLER_ERROR",
-			message = string.format('"%s" failed: %s', op, tostring(result)),
-		},
-	}
-end
-
-return Dispatch
+--!strict
+--[[
+	Handler registry and the single error boundary around every command.
+
+	Handlers raise failures with `Dispatch.fail(code, message, hint)`. The hint is
+	forwarded verbatim to the agent, so it should say what to do next ("call find
+	first to get a valid path"), not just what went wrong.
+]]
+
+local Dispatch = {}
+
+export type Error = {
+	code: string,
+	message: string,
+	hint: string?,
+}
+
+export type Handler = (params: { [string]: any }) -> any
+
+local handlers: { [string]: Handler } = {}
+
+--[[
+	When the server stops waiting for each running command, keyed by the
+	command's thread.
+
+	The server drops a timed-out command it has not delivered yet, but one
+	already delivered can still be sitting behind the mutation lock, or behind
+	a slow editor write. Starting it then does work nobody will hear about --
+	and the agent, told "timed out", may be retrying it at that moment. So the
+	deadline travels with the command and is checked where work would begin.
+
+	Both clocks are this machine's, so there is no skew to allow for. Weak keys,
+	so a thread that dies mid-command does not leave its entry behind.
+]]
+local deadlines: { [thread]: number } = setmetatable({}, { __mode = "k" }) :: any
+
+function Dispatch.deadline(): number?
+	return deadlines[coroutine.running()]
+end
+
+--[[
+	Refuses to go on once the command's deadline has passed. Pass the deadline
+	explicitly from code that runs on another thread -- an engine callback, or
+	a spawned task -- which the table above cannot see.
+]]
+function Dispatch.checkDeadline(explicit: number?)
+	local deadline = explicit or Dispatch.deadline()
+	if deadline and DateTime.now().UnixTimestampMillis >= deadline then
+		Dispatch.fail(
+			"DEADLINE_EXPIRED",
+			"The request timed out before Studio started this step, so it was not done.",
+			"Earlier steps of the same request may have applied. Check the current state before retrying."
+		)
+	end
+end
+
+function Dispatch.register(op: string, handler: Handler)
+	handlers[op] = handler
+end
+
+--[[
+	Registers every entry of `map` under the prefix, e.g. `registerAll("script",
+	{ read = fn })` exposes "script.read".
+]]
+function Dispatch.registerAll(prefix: string, map: { [string]: Handler })
+	for name, handler in map do
+		handlers[prefix .. "." .. name] = handler
+	end
+end
+
+--[[
+	Raises a structured failure. Always call this rather than `error("...")` so
+	the agent receives a code it can branch on and a hint it can act on.
+]]
+function Dispatch.fail(code: string, message: string, hint: string?): never
+	error({ code = code, message = message, hint = hint }, 0)
+end
+
+export type Result = {
+	id: string,
+	ok: boolean,
+	data: any?,
+	error: Error?,
+}
+
+--[[
+	Runs one command and returns the frame to POST back. Never throws: an
+	unhandled error inside a handler becomes a HANDLER_ERROR result, because a
+	crashed dispatch would leave the server's promise hanging until it times out.
+]]
+function Dispatch.invoke(id: string, op: string, params: { [string]: any }?, deadlineMs: number?): Result
+	local handler = handlers[op]
+	if not handler then
+		return {
+			id = id,
+			ok = false,
+			error = {
+				code = "UNKNOWN_OP",
+				message = string.format('This Studio plugin has no handler for "%s".', op),
+				hint = "The plugin is older than the MCP server. Update the Studio MCP "
+					.. "plugin to the version matching your server.",
+			},
+		}
+	end
+
+	local thread = coroutine.running()
+	deadlines[thread] = deadlineMs
+	local ok, result = pcall(function()
+		Dispatch.checkDeadline()
+		return handler(params or {})
+	end)
+	deadlines[thread] = nil
+	if ok then
+		return { id = id, ok = true, data = result }
+	end
+
+	if typeof(result) == "table" and (result :: any).code then
+		return { id = id, ok = false, error = result :: Error }
+	end
+
+	return {
+		id = id,
+		ok = false,
+		error = {
+			code = "HANDLER_ERROR",
+			message = string.format('"%s" failed: %s', op, tostring(result)),
+		},
+	}
+end
+
+return Dispatch

package/plugin/src/ExecRuntime.luau

@@ -1,168 +1,190 @@
---!strict
--- Shared bounded execution results in the VM that calls run.
-local LogService = game:GetService("LogService")
-local LogBuffer = require(script.Parent.LogBuffer)
-local Serialize = require(script.Parent.Serialize)
--- A chunk that prints in a loop would otherwise return a response no context
--- window can hold.
-local MAX_OUTPUT_LINES = 200
-local MAX_RETURN_VALUES = 10
-
--- Returned tables are walked rather than counted, but not without limit: a
--- chunk that returns a whole config tree, or one with a cycle in it, must not be
--- able to produce a response nothing can read.
-local MAX_TABLE_ENTRIES = 50
-local MAX_TABLE_DEPTH = 4
-
-local function describe(value: any, depth: number?, seen: { [any]: boolean }?): any
-	local level = depth or 0
-	local visited = seen or {}
-	local kind = typeof(value)
-
-	if kind == "function" or kind == "thread" then
-		return string.format("<%s>", kind)
-	end
-	if kind ~= "table" then
-		return Serialize.value(value)
-	end
-
-	local source = value :: { [any]: any }
-	-- Named separately from the depth cap, because they mean opposite things to
-	-- a reader. The depth cap says "there is more below this"; a cycle says
-	-- "this is the table you are already inside". Reporting the second as the
-	-- first printed `t.self.self.self` as three distinct nested tables, which
-	-- reads as real structure that does not exist.
-	if visited[source] then
-		return "<circular reference>"
-	end
-	if level >= MAX_TABLE_DEPTH then
-		return "<nested table>"
-	end
-	visited[source] = true
-
-	local count = 0
-	for _ in source do
-		count += 1
-	end
-
-	-- Arrays keep their shape so they read as lists on the other side; anything
-	-- with non-sequential keys becomes a map with stringified keys.
-	if count == #source then
-		local list: { any } = {}
-		for index, item in ipairs(source) do
-			if index > MAX_TABLE_ENTRIES then
-				table.insert(list, string.format("<%d more>", count - MAX_TABLE_ENTRIES))
-				break
-			end
-			table.insert(list, describe(item, level + 1, visited))
-		end
-		-- Cleared on the way out so the same table appearing twice side by side
-		-- still renders twice; only a table containing itself is a cycle.
-		visited[source] = nil
-		return list
-	end
-
-	local map: { [string]: any } = {}
-	local shown = 0
-	for key, item in source do
-		shown += 1
-		if shown > MAX_TABLE_ENTRIES then
-			map["..."] = string.format("<%d more>", count - MAX_TABLE_ENTRIES)
-			break
-		end
-		map[tostring(key)] = describe(item, level + 1, visited)
-	end
-	visited[source] = nil
-	return map
-end
-
-local Runtime = {}
-Runtime.describe = describe
-function Runtime.run(chunk: () -> ...any, timeout: number?): { [string]: any }
-	-- Captured rather than inferred: a chunk's prints are usually the point, and
-	-- reading them back from the log afterwards would also pick up whatever else
-	-- the place logged in the meantime.
-	local output: { { [string]: any } } = {}
-	local connection = LogService.MessageOut:Connect(function(message, messageType, context)
-		if #output < MAX_OUTPUT_LINES then
-			-- A structured log's context rides on the line, as it does in `console`.
-			local encoded = LogBuffer.encodeContext(context)
-			if encoded then
-				message ..= "  " .. encoded
-			end
-			table.insert(output, {
-				message = message,
-				level = if messageType == Enum.MessageType.MessageError
-					then "error"
-					elseif messageType == Enum.MessageType.MessageWarning then "warning"
-					elseif messageType == Enum.MessageType.MessageInfo then "info"
-					else "print",
-			})
-		end
-	end)
-
-	local started = os.clock()
-	local results: any = nil
-	if timeout then
-		local worker = task.spawn(function() results = table.pack(pcall(chunk :: any)) end)
-		local deadline = started + timeout
-		while results == nil and os.clock() < deadline do task.wait() end
-		if results == nil then
-			task.cancel(worker)
-			results = table.pack(false, "CLIENT_TIMEOUT: execution exceeded " .. tostring(timeout) .. "s")
-		end
-	else
-		results = table.pack(pcall(chunk :: () -> ...any))
-	end
-	local elapsed = os.clock() - started
-
-	--[[
-		MessageOut is deferred: `print` returns before the event fires, so
-		disconnecting straight after the chunk finished captured nothing at all.
-		A short settle picks the lines up.
-
-		It is bounded and stops as soon as the flow stops, rather than waiting a
-		fixed period, so a chunk that logged nothing costs almost no time and one
-		that logged plenty is not truncated.
-	]]
-	local settleDeadline = os.clock() + 0.5
-	local seen = #output
-	local quietFrames = 0
-	while os.clock() < settleDeadline and quietFrames < 3 do
-		task.wait()
-		if #output == seen then
-			quietFrames += 1
-		else
-			seen = #output
-			quietFrames = 0
-		end
-	end
-
-	connection:Disconnect()
-
-	if not results[1] then
-		return {
-			ok = false,
-			error = tostring(results[2]),
-			output = output,
-			milliseconds = math.floor(elapsed * 1000 + 0.5),
-		}
-	end
-
-	local returned: { any } = {}
-	for index = 2, math.min(results.n, MAX_RETURN_VALUES + 1) do
-		-- A nil return is written out rather than dropped. `table.insert` of nil
-		-- does nothing, so `return a, nil, b` came back as two values and every
-		-- one after the nil shifted into the wrong position.
-		local value = results[index]
-		table.insert(returned, if value == nil then "nil" else describe(value))
-	end
-
-	return {
-		ok = true,
-		returned = returned,
-		output = output,
-		milliseconds = math.floor(elapsed * 1000 + 0.5),
-	}
-end
-return Runtime
+--!strict
+-- Shared bounded execution results in the VM that calls run.
+local LogService = game:GetService("LogService")
+local LogBuffer = require(script.Parent.LogBuffer)
+local Serialize = require(script.Parent.Serialize)
+-- A chunk that prints in a loop would otherwise return a response no context
+-- window can hold.
+local MAX_OUTPUT_LINES = 200
+local MAX_RETURN_VALUES = 10
+
+-- Returned tables are walked rather than counted, but not without limit: a
+-- chunk that returns a whole config tree, or one with a cycle in it, must not be
+-- able to produce a response nothing can read.
+local MAX_TABLE_ENTRIES = 50
+local MAX_TABLE_DEPTH = 4
+type Budget = { nodes: number, chars: number }
+
+local function describe(value: any, depth: number?, seen: { [any]: boolean }?, shared: Budget?): any
+	local budget = shared or {nodes = 300, chars = 10000}
+	budget.nodes -= 1
+	budget.chars -= 30
+	if budget.nodes < 0 or budget.chars < 100 then return "<budget exceeded>" end
+	local level = depth or 0
+	local visited = seen or {}
+	local kind = typeof(value)
+
+	if kind == "function" or kind == "thread" then
+		return string.format("<%s>", kind)
+	end
+	if kind ~= "table" then
+		local result = Serialize.value(value)
+		if typeof(result) == "string" then
+			local cap = math.min(2000, math.floor(budget.chars / 6))
+			budget.chars -= math.min(#result, cap) * 6
+			return if #result > cap then string.sub(result, 1, cap) .. "<truncated>" else result
+		end
+		return result
+	end
+
+	local source = value :: { [any]: any }
+	-- Named separately from the depth cap, because they mean opposite things to
+	-- a reader. The depth cap says "there is more below this"; a cycle says
+	-- "this is the table you are already inside". Reporting the second as the
+	-- first printed `t.self.self.self` as three distinct nested tables, which
+	-- reads as real structure that does not exist.
+	if visited[source] then
+		return "<circular reference>"
+	end
+	if level >= MAX_TABLE_DEPTH then
+		return "<nested table>"
+	end
+	visited[source] = true
+
+	local count = 0
+	local isArray = true
+	for key in source do
+		if typeof(key) ~= "number" or key < 1 or key > #source or key % 1 ~= 0 then isArray = false end
+		count += 1
+		if count > MAX_TABLE_ENTRIES then break end
+	end
+
+	-- Arrays keep their shape so they read as lists on the other side; anything
+	-- with non-sequential keys becomes a map with stringified keys.
+	if isArray and (count == #source or count > MAX_TABLE_ENTRIES) then
+		local list: { any } = {}
+		for index, item in ipairs(source) do
+			if index > MAX_TABLE_ENTRIES or budget.nodes <= 0 or budget.chars < 100 then
+				table.insert(list, "<more entries>")
+				break
+			end
+			table.insert(list, describe(item, level + 1, visited, budget))
+		end
+		-- Cleared on the way out so the same table appearing twice side by side
+		-- still renders twice; only a table containing itself is a cycle.
+		visited[source] = nil
+		return list
+	end
+
+	local map: { [string]: any } = {}
+	local shown = 0
+	for key, item in source do
+		shown += 1
+		if shown > MAX_TABLE_ENTRIES or budget.nodes <= 0 or budget.chars < 100 then
+			map["..."] = "<more entries>"
+			break
+		end
+		local name = string.sub(tostring(key), 1, 100)
+		budget.chars -= #name * 6
+		map[name] = describe(item, level + 1, visited, budget)
+	end
+	visited[source] = nil
+	return map
+end
+
+local Runtime = {}
+Runtime.describe = describe
+function Runtime.run(chunk: () -> ...any, timeout: number?): { [string]: any }
+	-- Captured rather than inferred: a chunk's prints are usually the point, and
+	-- reading them back from the log afterwards would also pick up whatever else
+	-- the place logged in the meantime.
+	local output: { { [string]: any } } = {}
+	local outputChars, outputDropped = 0, 0
+	local connection = LogService.MessageOut:Connect(function(message, messageType, context)
+		if #output < MAX_OUTPUT_LINES and outputChars < 8000 then
+			-- A structured log's context rides on the line, as it does in `console`.
+			local encoded = LogBuffer.encodeContext(context)
+			if encoded then
+				message ..= "  " .. encoded
+			end
+			if #message > math.min(2000, 8000 - outputChars) then message = string.sub(message, 1, math.min(2000, 8000 - outputChars)) .. "<truncated>" end
+			outputChars += #message
+			table.insert(output, {
+				message = message,
+				level = if messageType == Enum.MessageType.MessageError
+					then "error"
+					elseif messageType == Enum.MessageType.MessageWarning then "warning"
+					elseif messageType == Enum.MessageType.MessageInfo then "info"
+					else "print",
+			})
+		else outputDropped += 1 end
+	end)
+
+	local started = os.clock()
+	local results: any = nil
+	if timeout then
+		local worker = task.spawn(function() results = table.pack(pcall(chunk :: any)) end)
+		local deadline = started + timeout
+		while results == nil and os.clock() < deadline do task.wait() end
+		if results == nil then
+			task.cancel(worker)
+			results = table.pack(false, "CLIENT_TIMEOUT: execution exceeded " .. tostring(timeout) .. "s")
+		end
+	else
+		results = table.pack(pcall(chunk :: () -> ...any))
+	end
+	local elapsed = os.clock() - started
+
+	--[[
+		MessageOut is deferred: `print` returns before the event fires, so
+		disconnecting straight after the chunk finished captured nothing at all.
+		A short settle picks the lines up.
+
+		It is bounded and stops as soon as the flow stops, rather than waiting a
+		fixed period, so a chunk that logged nothing costs almost no time and one
+		that logged plenty is not truncated.
+	]]
+	local settleDeadline = os.clock() + 0.5
+	local seen = #output
+	local quietFrames = 0
+	while os.clock() < settleDeadline and quietFrames < 3 do
+		task.wait()
+		if #output == seen then
+			quietFrames += 1
+		else
+			seen = #output
+			quietFrames = 0
+		end
+	end
+
+	connection:Disconnect()
+
+	if not results[1] then
+		return {
+			ok = false,
+			error = string.sub(tostring(results[2]), 1, 2000),
+			output = output,
+			milliseconds = math.floor(elapsed * 1000 + 0.5),
+		}
+	end
+
+	local returned: { any } = {}
+	local budget: Budget = {nodes = 300, chars = 6000}
+	for index = 2, math.min(results.n, MAX_RETURN_VALUES + 1) do
+		-- A nil return is written out rather than dropped. `table.insert` of nil
+		-- does nothing, so `return a, nil, b` came back as two values and every
+		-- one after the nil shifted into the wrong position.
+		local value = results[index]
+		table.insert(returned, if value == nil then "nil" else describe(value, nil, nil, budget))
+	end
+
+	return {
+		ok = true,
+		returned = returned,
+		outputDropped = if outputDropped > 0 then outputDropped else nil,
+		returnsDropped = if results.n > MAX_RETURN_VALUES + 1 then results.n - MAX_RETURN_VALUES - 1 else nil,
+		output = output,
+		milliseconds = math.floor(elapsed * 1000 + 0.5),
+	}
+end
+return Runtime