@el4cteo/rbx-studio-mcp 0.8.4 → 0.8.6

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/ScriptEdit.luau

@@ -38,6 +38,70 @@ function ScriptEdit.read(target: LuaSourceContainer): string
 	return (target :: SourceContainer).Source
 end
 
+--[[
+	A short fingerprint of a script's source, for detecting that it moved.
+
+	Handed out by `script_read` and passed back to `script_edit`, and kept by
+	`sync` to tell which side of a synced script changed. `edit`, which refuses to write when
+	the live source no longer matches. That is the only thing standing between
+	two agents on one place and a silent overwrite: a line-range edit computed
+	against source somebody has since changed still applies cleanly, it just
+	applies to the wrong lines, and nothing anywhere reports it.
+
+	FNV-1a over the whole string, with the length appended. Not a security
+	hash and does not need to be -- it is guarding against ordinary concurrent
+	editing, not against someone constructing a collision. The length is there
+	because it is free and rules out the whole class of same-length accidents.
+
+	The multiply is split into 16-bit halves on purpose. `hash * 16777619` with
+	a 32-bit hash reaches 2^56, past the 2^53 where doubles stop being exact,
+	so the low bits -- the ones that carry the mixing -- would be quietly
+	rounded away.
+]]
+function ScriptEdit.fingerprint(source: string): string
+	local hash = 2166136261
+	local length = #source
+	local index = 1
+	while index <= length do
+		local last = math.min(index + 511, length)
+		local chunk = { string.byte(source, index, last) }
+		for _, byte in chunk do
+			hash = bit32.bxor(hash, byte)
+			local low = bit32.band(hash, 0xFFFF)
+			local high = bit32.rshift(hash, 16)
+			-- 16777619 == 0x01000193, so 0x0193 is 403 and 0x0100 is 256.
+			hash = bit32.band(low * 403 + bit32.lshift(bit32.band(high * 403 + low * 256, 0xFFFF), 16), 0xFFFFFFFF)
+		end
+		index = last + 1
+	end
+	return string.format("%08x-%x", hash, length)
+end
+
+--[[
+	A script's revision, computed once per distinct text.
+
+	Fingerprinting walks every byte in Luau, and `sync` asks for the revision of
+	every script in a place on each run -- so a place with megabytes of code paid
+	for hashing all of it after every save, to learn that one file changed. The
+	text is kept beside its revision per script, and a lookup whose text is the
+	same string skips the hash: Luau interns strings, so that comparison is a
+	pointer check, not a second pass over the source.
+
+	Weak keys, so a deleted script's entry goes with it.
+]]
+local revisions: { [Instance]: { source: string, revision: string } } = setmetatable({}, { __mode = "k" }) :: any
+
+function ScriptEdit.revisionOf(target: LuaSourceContainer, source: string?): string
+	local text = source or ScriptEdit.read(target)
+	local cached = revisions[target]
+	if cached ~= nil and cached.source == text then
+		return cached.revision
+	end
+	local revision = ScriptEdit.fingerprint(text)
+	revisions[target] = { source = text, revision = revision }
+	return revision
+end
+
 --[[
 	Makes sure a write that reported success actually stuck.
 
@@ -59,11 +123,16 @@ end
 	caused this is only reachable when the USER opens one in the same moment we
 	write to it -- rare, and cheap enough to cover anyway. One settle, one read,
 	and a rewrite if it did not take.
+
+	A rewrite only ever replaces `original`, the text our write replaced. That
+	is what a finishing load puts back. Anything else in the buffer is somebody
+	typing after the write landed, and rewriting it "to make ours stick" would
+	delete their work -- so that is reported instead, and their text is kept.
 ]]
 local SETTLE = 0.2
 
-local function confirm(target: LuaSourceContainer, produced: string?)
-	if produced == nil then
+local function confirm(target: LuaSourceContainer, produced: string?, original: string?)
+	if produced == nil or produced == original then
 		return
 	end
 
@@ -86,20 +155,35 @@ local function confirm(target: LuaSourceContainer, produced: string?)
 	-- repeating will not fix.
 	for _ = 1, 3 do
 		task.wait(SETTLE)
-		if ScriptEdit.read(target) == produced then
+		local current = ScriptEdit.read(target)
+		if current == produced then
 			return
 		end
+		if current ~= original then
+			break
+		end
 		pcall(function()
-			ScriptEditorService:UpdateSourceAsync(target, function()
-				return produced
+			ScriptEditorService:UpdateSourceAsync(target, function(source)
+				-- Checked again at commit time: the user may have typed since the read.
+				return if source == original then produced :: string else source
 			end)
 		end)
 	end
+
+	if ScriptEdit.read(target) ~= produced then
+		Dispatch.fail(
+			"VERIFY_FAILED",
+			string.format("%s changed while the write was being confirmed.", target:GetFullName()),
+			"The newer text was kept, not overwritten. Read the script again before retrying."
+		)
+	end
 end
 
 --[[
-	Replaces source through the editor. `transform` receives the current text and
-	returns the replacement; returning the input unchanged is a no-op.
+	Replaces source through the editor. `transform` receives the current text --
+	read at commit time, so it is where a "has this changed since I read it"
+	check belongs -- and returns the replacement; returning the input unchanged
+	is a no-op.
 
 	`transform` is allowed to raise a structured Dispatch failure -- a bad line
 	range is only discoverable once the authoritative source is in hand. Such a
@@ -115,10 +199,12 @@ function ScriptEdit.write(target: LuaSourceContainer, transform: (string) -> str
 	local pending: any = nil
 
 	local produced: string? = nil
+	local original: string? = nil
 	local ok, err = pcall(function()
 		ScriptEditorService:UpdateSourceAsync(target, function(source)
 			local applied, result = pcall(transform, source)
 			if applied then
+				original = source
 				produced = result
 				return result
 			end
@@ -131,7 +217,7 @@ function ScriptEdit.write(target: LuaSourceContainer, transform: (string) -> str
 		error(pending, 0)
 	end
 	if ok then
-		confirm(target, produced)
+		confirm(target, produced, original)
 		return
 	end
 

package/plugin/src/Serialize.luau

@@ -413,7 +413,22 @@ function Serialize.parse(text: any, valueType: string): (boolean, any, string?)
 		end
 		-- 0-255 is a common mistake and unambiguous to detect, so accept it.
 		local scale = if numbers[1] > 1 or numbers[2] > 1 or numbers[3] > 1 then 255 else 1
-		return true, Color3.new(numbers[1] / scale, numbers[2] / scale, numbers[3] / scale), nil
+		--[[
+			Snapped back to an exact 1/255 step when the text is that step
+			rounded to PRECISION places.
+
+			Part colours are stored as bytes. "0.7686" is how 196/255 prints,
+			but it is a hair under it, and the engine truncates on the way in
+			-- so a colour read and written back came out as 195, one step
+			darker each round trip. A value genuinely between steps, like 0.5,
+			is further than half a printed digit from one and is left alone.
+		]]
+		local function component(value: number): number
+			local unit = value / scale
+			local step = math.round(unit * 255) / 255
+			return if math.abs(unit - step) <= 0.5 * 10 ^ -PRECISION then step else unit
+		end
+		return true, Color3.new(component(numbers[1]), component(numbers[2]), component(numbers[3])), nil
 	end
 	if valueType == "BrickColor" then
 		-- Cast because the API definitions type this overload as a literal union

package/plugin/src/Transport.luau

@@ -26,7 +26,9 @@ local Transport = {}
 export type Status = "disconnected" | "connecting" | "connected"
 
 type Callbacks = {
-	onCommand: (id: string, op: string, params: { [string]: any }?) -> (),
+	-- `deadlineMs` is when the server stops waiting for the reply, on this
+	-- machine's clock: the server sends a duration, never a time (see Command.timeoutMs).
+	onCommand: (id: string, op: string, params: { [string]: any }?, deadlineMs: number?) -> (),
 	onStatus: (status: Status, detail: string?) -> (),
 	--[[
 		Anything the bridge wants to tell this plugin that is not a command.
@@ -243,7 +245,8 @@ local function handleFrame(callbacks: Callbacks, frame: { [string]: any })
 	local id = frame.id
 	local op = frame.op
 	if typeof(id) == "string" and typeof(op) == "string" then
-		callbacks.onCommand(id, op, frame.params)
+		local deadline = if typeof(frame.timeoutMs) == "number" then DateTime.now().UnixTimestampMillis + frame.timeoutMs else nil
+		callbacks.onCommand(id, op, frame.params, deadline)
 		return
 	end
 	if typeof(frame.event) == "string" then

package/plugin/src/Undo.luau

@@ -18,6 +18,8 @@
 
 local ChangeHistoryService = game:GetService("ChangeHistoryService")
 
+local Dispatch = require(script.Parent.Dispatch)
+
 local Undo = {}
 
 --[[
@@ -132,13 +134,57 @@ end
 	is something tools tell the agent, and therefore the user, so it has to be
 	observed rather than assumed: a claim of "one Ctrl+Z" that silently degrades
 	to no undo entry at all is worse than no claim.
+
+	Refusing instead is not an option either: Studio opens no recording at all
+	inside a running playtest (measured), so a refusal would make every write
+	tool unusable against the runtime session.
+]]
+
+-- Opens a recording, or nil. Guarded because an engine error here must not
+-- escape with the lock held.
+local function begin(name: string, displayName: string): string?
+	local ok, identifier = pcall(function()
+		return ChangeHistoryService:TryBeginRecording(name, displayName)
+	end)
+	return if ok then identifier else nil
+end
+
+--[[
+	Runs `body` after the lock is ours, unless the request expired while it
+	waited. The server stops waiting at its timeout, so work that starts later
+	would be reported to nobody -- and an agent told "timed out" is likely to
+	retry it.
 ]]
+local function run<T>(body: () -> T): (boolean, any)
+	return pcall(function()
+		Dispatch.checkDeadline()
+		return body()
+	end)
+end
+
+-- Closes a recording. A failure here is reported, with the lock released, as
+-- an outcome the agent must check rather than assume.
+local function finish(identifier: string, operation: Enum.FinishRecordingOperation, acquired: boolean)
+	local ok, err = pcall(function()
+		ChangeHistoryService:FinishRecording(identifier, operation)
+	end)
+	if ok then
+		return
+	end
+	release(acquired)
+	Dispatch.fail(
+		"UNDO_FAILED",
+		string.format("Studio could not close the undo recording: %s", tostring(err)),
+		"The change may or may not have applied. Inspect the affected instances before retrying."
+	)
+end
+
 function Undo.record<T>(name: string, displayName: string, body: () -> T): (T, boolean)
 	local acquired = acquire()
 
-	local identifier = ChangeHistoryService:TryBeginRecording(name, displayName)
+	local identifier = begin(name, displayName)
 	if not identifier then
-		local ok, result = pcall(body)
+		local ok, result = run(body)
 		release(acquired)
 		if not ok then
 			error(result, 0)
@@ -146,15 +192,15 @@ function Undo.record<T>(name: string, displayName: string, body: () -> T): (T, b
 		return result, false
 	end
 
-	local ok, result = pcall(body)
+	local ok, result = run(body)
 	if ok then
-		ChangeHistoryService:FinishRecording(identifier, Enum.FinishRecordingOperation.Commit)
+		finish(identifier, Enum.FinishRecordingOperation.Commit, acquired)
 		release(acquired)
 		return result, true
 	end
 
-	ChangeHistoryService:FinishRecording(identifier, Enum.FinishRecordingOperation.Cancel)
-	dropRedo()
+	finish(identifier, Enum.FinishRecordingOperation.Cancel, acquired)
+	pcall(dropRedo)
 	release(acquired)
 	error(result, 0)
 end
@@ -167,9 +213,9 @@ end
 function Undo.recordPartial<T>(name: string, displayName: string, body: () -> T): (T, boolean)
 	local acquired = acquire()
 
-	local identifier = ChangeHistoryService:TryBeginRecording(name, displayName)
+	local identifier = begin(name, displayName)
 	if not identifier then
-		local ok, result = pcall(body)
+		local ok, result = run(body)
 		release(acquired)
 		if not ok then
 			error(result, 0)
@@ -177,8 +223,8 @@ function Undo.recordPartial<T>(name: string, displayName: string, body: () -> T)
 		return result, false
 	end
 
-	local ok, result = pcall(body)
-	ChangeHistoryService:FinishRecording(identifier, Enum.FinishRecordingOperation.Commit)
+	local ok, result = run(body)
+	finish(identifier, Enum.FinishRecordingOperation.Commit, acquired)
 	release(acquired)
 	if not ok then
 		error(result, 0)
@@ -186,4 +232,22 @@ function Undo.recordPartial<T>(name: string, displayName: string, body: () -> T)
 	return result, true
 end
 
+--[[
+	Holds the mutation lock without opening a recording.
+
+	For script source, whose undo is the script editor's own, per document --
+	a recording would add an empty step, not make the edit undoable. The lock
+	is what matters: two batches writing the same scripts must not interleave
+	their writes and their rollbacks.
+]]
+function Undo.exclusive<T>(body: () -> T): T
+	local acquired = acquire()
+	local ok, result = run(body)
+	release(acquired)
+	if not ok then
+		error(result, 0)
+	end
+	return result
+end
+
 return Undo