@el4cteo/rbx-studio-mcp 0.8.3 → 0.8.6

package/plugin/src/Config.luau

@@ -1,65 +1,65 @@
---!strict
---[[
-	Connection settings for the Studio MCP plugin.
-
-	The port must match the one the Node server was started with (`--port`, or
-	the ROBLOX_STUDIO_MCP_PORT environment variable). It is stored as a plugin
-	setting so a user running on a non-default port only has to set it once.
-]]
-
-local Config = {}
-
-Config.PLUGIN_VERSION = "0.8.3"
-
--- Fingerprint of plugin/src, stamped in by scripts/build-plugin.mjs. The server
--- computes the same hash from its own copy of the sources and compares, so a
--- plugin left running from an older build is reported rather than silently
--- answering with stale handlers. Stays "dev" when the tree is loaded unbuilt.
-Config.BUILD_ID = "dev"
-Config.PROTOCOL_VERSION = 1
-Config.DEFAULT_PORT = 44755
-
--- Header the bridge requires on every request. A web page cannot set it
--- cross-origin without a preflight the bridge never answers, which is what
--- keeps a malicious site from driving Studio through the loopback port.
-Config.CLIENT_HEADER = "x-roblox-studio-mcp"
-
--- How long to wait before retrying after the stream drops. Studio closes SSE
--- connections at the 30 minute mark, so reconnects are routine, not exceptional.
-Config.RECONNECT_DELAY = 1
-Config.MAX_RECONNECT_DELAY = 30
-
--- How long a connection has to last before it counts as having worked, rather
--- than as one more failure to back off from. Comfortably longer than a failed
--- handshake against a dead port, which resolves in milliseconds, and far shorter
--- than any connection that carried a single command.
-Config.HEALTHY_CONNECTION = 10
-
--- How long a healthy long-poll session runs before standing aside so streaming
--- can be tried again. Long enough that a Studio which genuinely cannot stream
--- is not reconnecting constantly, short enough that a session downgraded by one
--- unlucky attempt does not spend the rest of its life slower than it should be.
-Config.RESTREAM_INTERVAL = 60
-
-local port: number? = nil
-
-function Config.setPort(value: number)
-	port = value
-end
-
-function Config.getPort(): number
-	return port or Config.DEFAULT_PORT
-end
-
-function Config.baseUrl(): string
-	return string.format("http://127.0.0.1:%d", Config.getPort())
-end
-
-function Config.headers(): { [string]: string }
-	return {
-		[Config.CLIENT_HEADER] = tostring(Config.PROTOCOL_VERSION),
-		["Content-Type"] = "application/json",
-	}
-end
-
-return Config
+--!strict
+--[[
+	Connection settings for the Studio MCP plugin.
+
+	The port must match the one the Node server was started with (`--port`, or
+	the ROBLOX_STUDIO_MCP_PORT environment variable). It is stored as a plugin
+	setting so a user running on a non-default port only has to set it once.
+]]
+
+local Config = {}
+
+Config.PLUGIN_VERSION = "0.8.6"
+
+-- Fingerprint of plugin/src, stamped in by scripts/build-plugin.mjs. The server
+-- computes the same hash from its own copy of the sources and compares, so a
+-- plugin left running from an older build is reported rather than silently
+-- answering with stale handlers. Stays "dev" when the tree is loaded unbuilt.
+Config.BUILD_ID = "dev"
+Config.PROTOCOL_VERSION = 1
+Config.DEFAULT_PORT = 44755
+
+-- Header the bridge requires on every request. A web page cannot set it
+-- cross-origin without a preflight the bridge never answers, which is what
+-- keeps a malicious site from driving Studio through the loopback port.
+Config.CLIENT_HEADER = "x-roblox-studio-mcp"
+
+-- How long to wait before retrying after the stream drops. Studio closes SSE
+-- connections at the 30 minute mark, so reconnects are routine, not exceptional.
+Config.RECONNECT_DELAY = 1
+Config.MAX_RECONNECT_DELAY = 30
+
+-- How long a connection has to last before it counts as having worked, rather
+-- than as one more failure to back off from. Comfortably longer than a failed
+-- handshake against a dead port, which resolves in milliseconds, and far shorter
+-- than any connection that carried a single command.
+Config.HEALTHY_CONNECTION = 10
+
+-- How long a healthy long-poll session runs before standing aside so streaming
+-- can be tried again. Long enough that a Studio which genuinely cannot stream
+-- is not reconnecting constantly, short enough that a session downgraded by one
+-- unlucky attempt does not spend the rest of its life slower than it should be.
+Config.RESTREAM_INTERVAL = 60
+
+local port: number? = nil
+
+function Config.setPort(value: number)
+	port = value
+end
+
+function Config.getPort(): number
+	return port or Config.DEFAULT_PORT
+end
+
+function Config.baseUrl(): string
+	return string.format("http://127.0.0.1:%d", Config.getPort())
+end
+
+function Config.headers(): { [string]: string }
+	return {
+		[Config.CLIENT_HEADER] = tostring(Config.PROTOCOL_VERSION),
+		["Content-Type"] = "application/json",
+	}
+end
+
+return Config

package/plugin/src/Console.luau

@@ -1870,6 +1870,11 @@ function Console.setPromptBusy(busy: boolean)
 	Visuals.setThinking(busy)
 end
 
+-- Whether the prompt row invites sentences. See `chat` in Commands.
+function Console.setPromptChat(enabled: boolean)
+	Prompt.setChat(enabled)
+end
+
 --[[
 	Switches the whole panel to the active preset.
 

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