@el4cteo/rbx-studio-mcp 0.1.6 → 0.2.7

package/plugin/src/Phrase.luau

@@ -135,16 +135,29 @@ local DESCRIBERS: { [string]: Describer } = {
 		return string.format('Search scripts for "%s"', pattern)
 	end,
 
+	--[[
+		Names the class, not just whatever the caller happened to call the
+		thing. "Create MainMenu in StarterGui" was true and useless -- a name is
+		whatever someone typed, and it says nothing about what actually landed
+		in the place. `className` is required by the tool itself, so it is
+		always there; the chosen name rides along in quotes when it was given,
+		the way script.grep already quotes a search term.
+	]]
 	["instances.create"] = function(params)
 		local instances = params.instances
 		local total = count(instances)
 		if total == 1 then
 			local one = (instances :: { any })[1]
-			local name = one.name or one.className or "instance"
+			local className = if typeof(one.className) == "string" and one.className ~= ""
+				then one.className
+				else "instance"
+			local subject = if typeof(one.name) == "string" and one.name ~= ""
+				then string.format('%s "%s"', className, one.name)
+				else className
 			local where = leaf(one.parent)
 			return if where ~= nil
-				then string.format("Create %s in %s", name, where)
-				else "Create " .. name
+				then string.format("Create %s in %s", subject, where)
+				else "Create " .. subject
 		end
 		local where = if total > 0 then leaf((instances :: { any })[1].parent) else nil
 		return if where ~= nil
@@ -157,16 +170,45 @@ local DESCRIBERS: { [string]: Describer } = {
 		-- total across them rather than the number of entries.
 		local total = 0
 		local onlyName: string? = nil
+		--[[
+			Which properties/attributes actually changed, not just how many
+			instances did. "Modify Sword" said something happened and nothing
+			about what; a caller watching for "did the color change" had no way
+			to tell this apart from a rename or an attribute flip.
+		]]
+		local fields: { string } = {}
+		local seenFields: { [string]: boolean } = {}
+		local function noteFields(bag: any)
+			if typeof(bag) ~= "table" then
+				return
+			end
+			for key in bag :: { [string]: any } do
+				if not seenFields[key] then
+					seenFields[key] = true
+					table.insert(fields, key)
+				end
+			end
+		end
 		for _, target in (targets or {}) :: { { [string]: any } } do
 			local paths = count(target.paths)
 			total += paths
 			if paths >= 1 and onlyName == nil then
 				onlyName = leaf((target.paths :: { any })[1])
 			end
+			noteFields(target.properties)
+			noteFields(target.attributes)
 		end
 		if total == 1 and onlyName ~= nil then
+			if #fields == 1 then
+				return string.format("Set %s on %s", fields[1], onlyName)
+			elseif #fields > 1 then
+				return string.format("Modify %s (%s)", onlyName, table.concat(fields, ", "))
+			end
 			return "Modify " .. onlyName
 		end
+		if #fields == 1 then
+			return string.format("Set %s on %s", fields[1], plural(total, "instance"))
+		end
 		return "Modify " .. plural(total, "instance")
 	end,
 	["instances.delete"] = function(params)
@@ -181,11 +223,18 @@ local DESCRIBERS: { [string]: Describer } = {
 			local one = (items :: { any })[1]
 			local what = leaf(one.path)
 			local where = leaf(one.to)
+			-- A rename in the same call changes what actually ends up in the
+			-- place; "Clone Sword to Backpack" while it lands as "GoldSword"
+			-- described an instance that was never created under that name.
+			local rename = if typeof(one.name) == "string" and one.name ~= "" then one.name else nil
 			if what ~= nil and where ~= nil then
-				return string.format("%s %s to %s", verb, what, where)
+				local base = string.format("%s %s to %s", verb, what, where)
+				return if rename ~= nil then base .. " as " .. rename else base
 			end
 			if what ~= nil then
-				return verb .. " " .. what
+				return if rename ~= nil
+					then string.format("%s %s as %s", verb, what, rename)
+					else verb .. " " .. what
 			end
 		end
 		return string.format("%s %s", verb, plural(total, "instance"))
@@ -196,6 +245,18 @@ local DESCRIBERS: { [string]: Describer } = {
 		return if where ~= nil then "Browse " .. where else "Browse the place"
 	end,
 	["discover.inspect"] = function(params)
+		--[[
+			`inspect` (no explicit `properties`, not concise detail) and `modify`
+			(when setting properties) both probe a class before doing the thing
+			the caller actually asked for -- reading the properties that matter
+			for it, or typing the values it is about to write. That probe is a
+			second, genuine call to this same op, and unmarked it logged
+			identically to the read it precedes: two lines reading "Inspect X"
+			back to back, indistinguishable from asking twice by mistake.
+		]]
+		if params.probeOnly == true then
+			return "Check the class of " .. subjectOf(params.paths, "instance")
+		end
 		return "Inspect " .. subjectOf(params.paths, "instance")
 	end,
 	["discover.find"] = function(params)
@@ -262,6 +323,18 @@ local DESCRIBERS: { [string]: Describer } = {
 
 	["playtest.control"] = function(params)
 		local op = tostring(params.op or "state")
+		--[[
+			`stop` ends a test by polling this from the *surviving* session every
+			400ms until the teardown settles, sometimes five or six times in two
+			seconds. Labelled "Check the playtest" like an agent's own status
+			check, that read as unexplained repetition with no `stop` line anywhere
+			to explain it -- the actual stop went to the session that is by then
+			gone, and its console went with it. This name is why: waiting for the
+			teardown it just started, not asking again for no reason.
+		]]
+		if op == "state" and params.waitingForStop == true then
+			return "Wait for the playtest to stop"
+		end
 		if op == "play" then
 			return "Start a playtest"
 		elseif op == "run" then
@@ -331,6 +404,12 @@ local DESCRIBERS: { [string]: Describer } = {
 	["capture.screenshot"] = function()
 		return "Take a screenshot"
 	end,
+	["capture.playtestId"] = function()
+		return "Capture the playtest view"
+	end,
+	["capture.decode"] = function()
+		return "Read back the capture"
+	end,
 
 	["viewport.focus"] = function(params)
 		local name = leaf(params.path)
@@ -378,6 +457,8 @@ local DESCRIBERS: { [string]: Describer } = {
 			return "Create collision group " .. group
 		elseif action == "assign" then
 			return string.format("Put %s in %s", plural(count(params.paths), "instance"), group)
+		elseif action == "remove" then
+			return "Remove collision group " .. group
 		end
 		return string.format("Set %s against %s", group, tostring(params.with or "?"))
 	end,
@@ -400,6 +481,73 @@ local DESCRIBERS: { [string]: Describer } = {
 	["studio.ping"] = function()
 		return "Ping"
 	end,
+	["studio.transport"] = function(params)
+		local mode = params.mode
+		return if typeof(mode) == "string" and mode ~= ""
+			then string.format("Switch to %s transport", mode)
+			else "Check the transport"
+	end,
+
+	--[[
+		The one a person actually watches: a live playtest is the point where
+		"what is the AI doing" stops being abstract, and a console line reading
+		"Input send" says nothing a bystander could act on. One step names the
+		key or point; several collapse to a count, same as every other batch op.
+	]]
+	["input.send"] = function(params)
+		local steps = params.steps
+		local total = count(steps)
+		if total == 1 then
+			local step = (steps :: { any })[1]
+			local kind = tostring(step.kind or "key")
+			if kind == "key" then
+				local action = tostring(step.action or "tap")
+				local verb = if action == "press" then "Hold" elseif action == "release" then "Release" else "Press"
+				return string.format("%s %s", verb, tostring(step.key or "?"))
+			elseif kind == "click" then
+				return string.format("Click (%s, %s)", tostring(step.x or "?"), tostring(step.y or "?"))
+			elseif kind == "move" then
+				return "Move the pointer"
+			elseif kind == "text" then
+				return string.format('Type "%s"', tostring(step.text or ""))
+			end
+		end
+		return "Send " .. plural(total, "input step")
+	end,
+
+	["api.describe"] = function(params)
+		local className = params.className
+		return if typeof(className) == "string" and className ~= ""
+			then "Look up " .. className
+			else "Look up a class"
+	end,
+	["api.classes"] = function(params)
+		local needle = params.contains
+		return if typeof(needle) == "string" and needle ~= ""
+			then string.format('Search classes for "%s"', needle)
+			else "List classes"
+	end,
+
+	["perf.scene"] = function(params)
+		local section = params.section
+		return if typeof(section) == "string" and section ~= ""
+			then "Measure the " .. section
+			else "Measure the scene"
+	end,
+
+	["device.list"] = function()
+		return "List devices"
+	end,
+	["device.set"] = function(params)
+		local id = params.device
+		return if typeof(id) == "string" and id ~= "" then "Emulate " .. id else "Emulate a device"
+	end,
+	["device.stop"] = function()
+		return "Stop emulating a device"
+	end,
+	["device.state"] = function()
+		return "Check the emulated device"
+	end,
 }
 
 --[[
@@ -421,8 +569,13 @@ local KINDS: { [string]: string } = {
 	exec = "run",
 	playtest = "run",
 	character = "run",
+	-- Live keys and clicks into a running playtest are an action, not a read,
+	-- and belong beside character/exec rather than defaulting to "read".
+	input = "run",
 	debug = "debug",
 	perf = "debug",
+	api = "read",
+	device = "read",
 }
 
 function Phrase.kindOf(op: string): string

package/plugin/src/Transport.luau

@@ -28,6 +28,19 @@ export type Status = "disconnected" | "connecting" | "connected"
 type Callbacks = {
 	onCommand: (id: string, op: string, params: { [string]: any }?) -> (),
 	onStatus: (status: Status, detail: string?) -> (),
+	--[[
+		Anything the bridge wants to tell this plugin that is not a command.
+
+		The stream was one-way in practice -- commands down, results back over a
+		separate POST -- and there was no way for the server to say something the
+		plugin should merely know, like how many agents are now sharing it. A
+		frame carrying `event` instead of `id`/`op` is that channel.
+
+		No protocol bump: a plugin older than this drops any frame without an id
+		and an op, which is exactly the right behaviour for a frame it does not
+		understand.
+	]]
+	onEvent: (event: { [string]: any }) -> (),
 }
 
 local running = false
@@ -71,6 +84,12 @@ local function identity(transport: string): { [string]: any }
 		placeId = game.PlaceId,
 		pluginVersion = Config.PLUGIN_VERSION,
 		buildId = Config.BUILD_ID,
+		-- Alongside buildId rather than instead of it: buildId catches a plugin
+		-- left running an older *behaviour*, this catches the wire *shape*
+		-- changing under it. Compared server-side the same way buildId is, so a
+		-- mismatch surfaces through studio_status instead of failing silently
+		-- the next time PROTOCOL_VERSION actually moves.
+		protocolVersion = Config.PROTOCOL_VERSION,
 		transport = transport,
 		-- Announced at the handshake rather than left for a later status call.
 		-- The ambiguity error that forces someone to choose between two rows
@@ -81,23 +100,53 @@ local function identity(transport: string): { [string]: any }
 end
 
 --[[
-	Parses one SSE payload. `MessageReceived` hands over the event data, but the
-	exact framing is not contractual, so a stray `data:` prefix is tolerated and
-	comment/keepalive lines are dropped.
+	Parses one delivery from the stream, which may hold more than one event.
+
+	This used to assume one event per `MessageReceived` and decode the whole
+	payload as a single JSON object. That held only because the bridge had never
+	written two frames in the same tick -- and the moment it did, both were lost:
+	the two writes arrived in one chunk, so the decode saw
+	`{...}<blank>data: {...}` and returned nil for the pair. The visible symptom
+	was a client-count badge that went up and never came back down. The invisible
+	one is why this is written properly rather than patched around: nothing stops
+	a *command* from sharing a chunk with anything else, and a dropped command is
+	a tool call that disappears with no error on either side.
+
+	So the payload is split into events on blank lines, and each event's `data:`
+	lines are concatenated the way the SSE spec says they should be. Comments --
+	the `: connected` greeting and the `: ping` keepalives -- are skipped rather
+	than being allowed to poison the block they arrive with.
 ]]
-local function parseFrame(message: string): { [string]: any }?
-	local text = (string.gsub(message, "^%s+", ""))
-	if text == "" or string.sub(text, 1, 1) == ":" then
-		return nil
-	end
-	if string.sub(text, 1, 5) == "data:" then
-		text = (string.gsub(string.sub(text, 6), "^%s+", ""))
-	end
-	local decoded = Net.decode(text)
-	if typeof(decoded) ~= "table" then
-		return nil
+local function parseFrames(message: string): { { [string]: any } }
+	local frames: { { [string]: any } } = {}
+
+	-- Normalised so one split handles either line ending.
+	local normalised = (string.gsub(message, "\r\n", "\n"))
+
+	-- The appended separator gives every event, the last one included, a
+	-- trailing blank line, so a single pattern finds them all.
+	for block in string.gmatch(normalised .. "\n\n", "(.-)\n\n") do
+		local payload: string? = nil
+		for line in string.gmatch(block, "[^\n]+") do
+			if string.sub(line, 1, 1) ~= ":" then
+				local value = line
+				if string.sub(value, 1, 5) == "data:" then
+					value = (string.gsub(string.sub(value, 6), "^%s+", ""))
+				end
+				-- Several data lines in one event concatenate, per the spec.
+				payload = if payload == nil then value else payload .. "\n" .. value
+			end
+		end
+
+		if payload ~= nil and payload ~= "" then
+			local decoded = Net.decode(payload)
+			if typeof(decoded) == "table" then
+				table.insert(frames, decoded)
+			end
+		end
 	end
-	return decoded
+
+	return frames
 end
 
 local function handleFrame(callbacks: Callbacks, frame: { [string]: any })
@@ -105,6 +154,10 @@ local function handleFrame(callbacks: Callbacks, frame: { [string]: any })
 	local op = frame.op
 	if typeof(id) == "string" and typeof(op) == "string" then
 		callbacks.onCommand(id, op, frame.params)
+		return
+	end
+	if typeof(frame.event) == "string" then
+		callbacks.onEvent(frame)
 	end
 end
 
@@ -145,8 +198,7 @@ local function runStream(callbacks: Callbacks): boolean
 	table.insert(
 		connections,
 		client.MessageReceived:Connect(function(message: string)
-			local frame = parseFrame(message)
-			if frame then
+			for _, frame in parseFrames(message) do
 				handleFrame(callbacks, frame)
 			end
 		end)
@@ -218,8 +270,21 @@ local function runPolling(callbacks: Callbacks): boolean
 			return false
 		else
 			local payload = Net.decode(response.body)
-			if typeof(payload) == "table" and typeof(payload.command) == "table" then
-				handleFrame(callbacks, payload.command)
+			if typeof(payload) == "table" then
+				if typeof(payload.command) == "table" then
+					handleFrame(callbacks, payload.command)
+				end
+				--[[
+					Poll sessions get the same news, riding on the answer they were
+					already waiting for. The bridge has nowhere to push to here, so
+					every poll response carries the current value rather than only
+					the moments it changed -- the console filters out the repeats,
+					and a poll session that missed a change while it was handling a
+					command would otherwise never hear about it.
+				]]
+				if typeof(payload.clients) == "number" then
+					callbacks.onEvent({ event = "clients", count = payload.clients })
+				end
 			end
 		end