@el4cteo/rbx-studio-mcp 0.8.3 → 0.8.6

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

package/plugin/src/LogBuffer.luau

@@ -41,6 +41,8 @@ local MAX_CONTEXT = 1000
 
 export type Entry = {
 	sequence: number?,
+	id: number?,
+	updated: boolean?,
 	level: string,
 	message: string,
 	timestamp: number,
@@ -101,6 +103,10 @@ local collecting: { string }? = nil
 local function pushEntry(entry: Entry)
 	nextSequence += 1
 	entry.sequence = nextSequence
+	entry.id = nextSequence
+	entry.message = string.sub(entry.message, 1, 2000)
+	if entry.stack then entry.stack = string.sub(entry.stack, 1, 4000) end
+	if entry.source then entry.source = string.sub(entry.source, 1, 500) end
 	table.insert(entries, entry)
 
 	if #entries > CAPACITY + SLACK then
@@ -133,18 +139,24 @@ function LogBuffer.pushClient(player: Player, payload: any)
 	if payload.kind == "ready" then buffer.ready = true; return end
 	if payload.kind == "trace" then
 		if typeof(payload.message) ~= "string" or typeof(payload.stack) ~= "string" then return end
+		local traceMessage = string.sub(payload.message, 1, 2000)
 		for index = #buffer.entries, math.max(1, #buffer.entries - CORRELATION_WINDOW + 1), -1 do
 			local item = buffer.entries[index]
-			if item.level == "error" and item.message == payload.message and item.stack == nil then
+			if item.level == "error" and item.message == string.sub(payload.message, 1, 2000) and item.stack == nil then
 				item.stack = string.sub(payload.stack, 1, 4000)
 				item.source = if typeof(payload.source) == "string" then string.sub(payload.source, 1, 500) else nil
+				buffer.sequence += 1
+				item.sequence = buffer.sequence
+				item.updated = true
+				table.remove(buffer.entries, index)
+				table.insert(buffer.entries, item)
 				return
 			end
 		end
 		local orphanCount = 0
 		for _ in buffer.orphan do orphanCount += 1 end
-		if orphanCount < 20 or buffer.orphan[payload.message] ~= nil then
-			buffer.orphan[payload.message] = { stack = string.sub(payload.stack, 1, 4000), source = if typeof(payload.source) == "string" then string.sub(payload.source, 1, 500) else nil }
+		if orphanCount < 20 or buffer.orphan[traceMessage] ~= nil then
+			buffer.orphan[traceMessage] = { stack = string.sub(payload.stack, 1, 4000), source = if typeof(payload.source) == "string" then string.sub(payload.source, 1, 500) else nil }
 		end
 		return
 	end
@@ -154,6 +166,7 @@ function LogBuffer.pushClient(player: Player, payload: any)
 	buffer.sequence += 1
 	local entry: Entry = {
 		sequence = buffer.sequence,
+		id = buffer.sequence,
 		level = level,
 		message = string.sub(payload.message, 1, 2000),
 		timestamp = if typeof(payload.timestamp) == "number" and payload.timestamp >= 0 and payload.timestamp < 100000000000 then payload.timestamp else os.time(),
@@ -202,17 +215,20 @@ end
 ]]
 -- JSONEncode writes a Vector3 or an Instance as `null` without complaint, so
 -- anything JSON has no shape for is turned into its text first.
-local function plain(value: any, depth: number): any
+local function plain(value: any, depth: number, budget: { nodes: number }): any
+	budget.nodes -= 1
+	if budget.nodes <= 0 then return "<truncated>" end
 	local kind = typeof(value)
 	if kind == "string" or kind == "number" or kind == "boolean" then
-		return value
+		return if kind == "string" then string.sub(value, 1, MAX_CONTEXT) else value
 	elseif kind == "table" then
 		if depth >= 4 then
 			return "<table>"
 		end
 		local copy = {}
 		for key, item in value do
-			copy[if typeof(key) == "number" then key else tostring(key)] = plain(item, depth + 1)
+			if budget.nodes <= 0 then copy["..."] = "<truncated>"; break end
+			copy[if typeof(key) == "number" then key else string.sub(tostring(key), 1, 100)] = plain(item, depth + 1, budget)
 		end
 		return copy
 	elseif kind == "Instance" then
@@ -229,15 +245,17 @@ function LogBuffer.encodeContext(context: any): string?
 		return nil
 	end
 	local ok, encoded = pcall(function()
-		return HttpService:JSONEncode(plain(context, 0))
+		return HttpService:JSONEncode(plain(context, 0, {nodes = 50}))
 	end)
 	if not ok then
 		return nil
 	end
-	return string.sub(encoded :: string, 1, MAX_CONTEXT)
+	if #encoded > MAX_CONTEXT then return HttpService:JSONEncode({truncated = string.sub(encoded, 1, 100)}) end
+	return encoded
 end
 
 local function push(message: string, messageType: Enum.MessageType, timestamp: number?, context: any?)
+	message = string.sub(message, 1, 2000)
 	local level = LEVELS[messageType.Value] or "print"
 	local entry: Entry = {
 		level = level,
@@ -270,12 +288,20 @@ end
 	two identical lines.
 ]]
 local function attachStack(message: string, stack: string, source: string?)
+	message = string.sub(message, 1, 2000)
+	stack = string.sub(stack, 1, 4000)
+	if source then source = string.sub(source, 1, 500) end
 	local first = math.max(1, #entries - CORRELATION_WINDOW + 1)
 	for index = #entries, first, -1 do
 		local entry = entries[index]
 		if entry.level == "error" and entry.message == message and entry.stack == nil then
 			entry.stack = stack
 			entry.source = source
+			nextSequence += 1
+			entry.sequence = nextSequence
+			entry.updated = true
+			table.remove(entries, index)
+			table.insert(entries, entry)
 			return
 		end
 	end
@@ -336,7 +362,10 @@ function LogBuffer.start()
 						local existing = recent.stack
 						local existingFrames = if existing then #string.split(existing, "\n") else 0
 						if existing == nil or #buffered > existingFrames then
-							recent.stack = table.concat(buffered, "\n")
+							recent.stack = string.sub(table.concat(buffered, "\n"), 1, 4000)
+							nextSequence += 1
+							recent.sequence = nextSequence
+							recent.updated = true
 						end
 					end
 				end

package/plugin/src/Paths.luau

@@ -67,6 +67,40 @@ local function childrenByName(parent: Instance, memo: NameIndex?): { [string]: {
 		table.insert(list, child)
 	end
 
+	--[[
+		Same-named siblings put into a fixed order.
+
+		`GetChildren` does not return a stable order (see `stableOrder` in
+		Discover), so `Part[2]` could name a different part on the call that
+		reads the path back than on the one that printed it. The engine's debug
+		id is fixed for an instance's lifetime, which makes it the tiebreak.
+
+		Guarded, because this module also runs in the client relay, where
+		`GetDebugId` is not callable -- there the order is simply the engine's,
+		as it always was, rather than an error on every path.
+	]]
+	for _, list in byName do
+		if #list > 1 then
+			local ids: { [Instance]: string } = {}
+			local stable = true
+			for _, child in list do
+				local ok, id = pcall(function()
+					return child:GetDebugId()
+				end)
+				if not ok then
+					stable = false
+					break
+				end
+				ids[child] = id
+			end
+			if stable then
+				table.sort(list, function(a: Instance, b: Instance): boolean
+					return ids[a] < ids[b]
+				end)
+			end
+		end
+	end
+
 	if memo then
 		memo[parent] = byName
 	end
@@ -315,6 +349,14 @@ end
 	The index is positional, so it shifts if same-named siblings are inserted or
 	removed between calls. Read a fresh path after any structural change.
 ]]
+--[[
+	The position among same-named siblings, or nil when the name is unique --
+	the `n` in `Name[n]`. Exposed for `sync`, which names files after it.
+]]
+function Paths.ordinal(instance: Instance, memo: NameIndex?): number?
+	return siblingIndex(instance, memo)
+end
+
 function Paths.of(instance: Instance, memo: NameIndex?): string
 	--[[
 		Refuses anything that is not an Instance, rather than duck-typing it.

package/plugin/src/Phrase.luau

@@ -91,6 +91,42 @@ type Describer = (params: { [string]: any }) -> string
 	playtest is about a mode, a find is about what was searched for.
 ]]
 local DESCRIBERS: { [string]: Describer } = {
+	["sync.scan"] = function(params)
+		return if params.revisions == false then "Check script layout for sync" else "Scan scripts for sync"
+	end,
+	["sync.read"] = function(params)
+		return "Read " .. subjectOf(params.paths, "script") .. " for sync"
+	end,
+	["sync.apply"] = function(params)
+		local total = count(params.writes) + count(params.creates) + count(params.deletes) + count(params.moves)
+		return string.format("Sync %d change%s from files", total, if total == 1 then "" else "s")
+	end,
+	["sync.shape"] = function()
+		return "Check script layout for sync"
+	end,
+	["sync.revisions"] = function()
+		return "Check script revisions"
+	end,
+	["sync.changes"] = function()
+		return "Check for script changes"
+	end,
+	["sync.stop"] = function()
+		return "Stop sync tracking"
+	end,
+	["sync.log"] = function()
+		return "Sync note"
+	end,
+	["sync.classes"] = function(params)
+		return "List classes in " .. (leaf(params.path) or "tree")
+	end,
+	["sync.export"] = function(params)
+		return "Export " .. (leaf(params.path) or "tree") .. " to a build file"
+	end,
+	["sync.build"] = function(params)
+		local spec = params.spec
+		local name = if typeof(spec) == "table" then spec.name or spec.className else nil
+		return "Build " .. tostring(name or "tree") .. " from a build file"
+	end,
 	["script.read"] = function(params)
 		return "Read " .. subjectOf(params.paths, "script")
 	end,
@@ -756,6 +792,8 @@ local KINDS: { [string]: string } = {
 	terrain = "write",
 	generate = "write",
 	data = "write",
+	-- Applies files to the place; the reads inside the group are carved out below.
+	sync = "write",
 }
 
 function Phrase.kindOf(op: string): string
@@ -770,6 +808,9 @@ function Phrase.kindOf(op: string): string
 	if op == "audio.inspect" then
 		return "read"
 	end
+	if op == "sync.scan" or op == "sync.shape" or op == "sync.revisions" or op == "sync.read" or op == "sync.changes" or op == "sync.classes" or op == "sync.export" then
+		return "read"
+	end
 	return KINDS[group] or "read"
 end
 

package/plugin/src/Prompt.luau

@@ -162,6 +162,10 @@ type Runtime = {
 	-- back returns it rather than an empty line.
 	draft: string,
 	busy: boolean,
+	-- Whether a line that is not a command goes to an agent. Off until the user
+	-- runs `chat on`; only used to word the placeholder, since `Commands` is what
+	-- actually refuses the line.
+	chat: boolean,
 	--[[
 		What is selected in Studio right now, already worded for display.
 
@@ -195,6 +199,7 @@ local runtime: Runtime = {
 	offset = 0,
 	draft = "",
 	busy = false,
+	chat = false,
 	selection = "",
 	complete = nil,
 	suggest = nil,
@@ -218,9 +223,12 @@ local function paintCaret()
 end
 
 local function placeholder(): string
-	return if runtime.busy
-		then "running -- type stop to cancel"
-		else "type a command, or ask for something"
+	if runtime.busy then
+		return "running -- type stop to cancel"
+	end
+	return if runtime.chat
+		then "type a command, or ask for something"
+		else "type a command -- `chat on` lets an agent answer"
 end
 
 --[[
@@ -903,6 +911,18 @@ function Prompt.setBusy(busy: boolean)
 	end
 end
 
+--[[
+	Reports whether sentences are answered, so the placeholder does not invite
+	a request the console is about to decline.
+]]
+function Prompt.setChat(enabled: boolean)
+	runtime.chat = enabled
+	local field = runtime.field
+	if field ~= nil then
+		field.PlaceholderText = placeholder()
+	end
+end
+
 --[[
 	Reports what Studio has selected, as a phrase rather than a list.