rbxstudio-mcp 2.3.2 → 2.4.0

package/studio-plugin/plugin.luau

@@ -18,7 +18,7 @@ pcall(function()
 end)
 
 -- ============================================================================
--- TEST SESSION COMPANION
+-- TEST SESSION COMPANIONS
 --
 -- StudioTestService:EndTest() can only be called from the Server DataModel of
 -- a running test. The plugin lives in the Edit DataModel, so it cannot call
@@ -26,29 +26,54 @@ end)
 -- ServerScriptService BEFORE calling ExecutePlayModeAsync. When the test
 -- starts, that Script runs in the Server DataModel and:
 --   1. Streams LogService.MessageOut to the bridge (/test-session/log)
---   2. Polls the bridge (/test-session/poll) for an "end" command
---   3. On "end", calls StudioTestService:EndTest() — which terminates the
+--   2. Polls the bridge (/test-session/poll) for commands
+--   3. On 'end', calls StudioTestService:EndTest() — which terminates the
 --      yielding ExecutePlayModeAsync call back in the plugin.
+--   4. On 'eval', loadstring()s + xpcall()s the supplied code on its own
+--      task thread and POSTs the result to /test-session/eval-result.
+--
+-- We also inject a parallel CLIENT companion (LocalScript) into
+-- StarterPlayer.StarterPlayerScripts. StarterPlayerScripts auto-clones into
+-- each Player's PlayerScripts when they join, so every player in the test
+-- gets their own companion copy. Clients identify themselves to the bridge
+-- by userId so run_live_lua can target a specific player or pick any
+-- available one.
 --
 -- Cleanup strategy:
---   - Tagged with TEST_COMPANION_TAG so we can find orphans
+--   - Both companions tagged with TEST_COMPANION_TAG so we can find orphans
 --   - Swept on plugin activate, on every playSolo start, and after the test
 --     ends (whether via stop_play, natural end, or user clicking Stop)
+--
+-- LLM-stomp prevention:
+--   - Distinctive name + leading "(auto-generated, safe to delete)" comment
+--   - CollectionService tag
+--   - Hard refusals in destructive MCP tools (delete_object, edit_script,
+--     set_script_source, set_property Disabled, move_instance) for any
+--     instance bearing the tag or matching the name
 -- ============================================================================
 local TEST_COMPANION_NAME = "_MCPTestCompanion"
+local TEST_COMPANION_NAME_CLIENT = "_MCPTestCompanion_Client"
 local TEST_COMPANION_TAG = "_MCPTestCompanion"
 
--- The companion script source. Two placeholders are substituted at injection
--- time: __MCP_SERVER_URL__ and __MCP_SESSION_ID__. We use distinctive
--- placeholders (not %%...%% or {{...}}) to avoid collisions with Lua's own
--- pattern syntax during gsub.
+-- ----------------------------------------------------------------------------
+-- SERVER companion template. Runs as a regular Script in ServerScriptService.
+-- Placeholders __MCP_SERVER_URL__ and __MCP_SESSION_ID__ are substituted at
+-- injection time. We use distinctive placeholders (not %%...%% or {{...}}) to
+-- avoid collisions with Lua's own pattern syntax.
+-- ----------------------------------------------------------------------------
 local COMPANION_SCRIPT_TEMPLATE = [[-- _MCPTestCompanion (auto-generated, safe to delete)
 -- Runs in the Server DataModel of a Studio test session started by the MCP
--- plugin. Pipes output back to the local MCP bridge and listens for an "end"
--- command to terminate the test cleanly via StudioTestService:EndTest().
+-- plugin. Pipes output back to the local MCP bridge, listens for an "end"
+-- command to terminate the test cleanly via StudioTestService:EndTest(), and
+-- runs run_live_lua "eval" commands on the test's actual server.
+--
+-- DO NOT modify or delete while a play test is running — it will be cleaned
+-- up automatically by the MCP plugin.
 
 local HttpService = game:GetService("HttpService")
 local LogService = game:GetService("LogService")
+local Players = game:GetService("Players")
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
 local StudioTestService
 do
 	local ok, svc = pcall(function() return game:GetService("StudioTestService") end)
@@ -66,6 +91,57 @@ local outputBuffer = {}
 local stopRequested = false
 local consecutiveFailures = 0
 
+-- Probe loadstring availability ONCE up front. Result goes into the hello
+-- payload so the bridge can refuse run_live_lua with a clear error if the
+-- user hasn't enabled ServerScriptService.LoadStringEnabled.
+local LOADSTRING_READY = false
+do
+	local ok, fn = pcall(loadstring, "return 1")
+	if ok and type(fn) == "function" then
+		local execOk, execVal = pcall(fn)
+		if execOk and execVal == 1 then
+			LOADSTRING_READY = true
+		end
+	end
+end
+
+-- ---------------------------------------------------------------------------
+-- CLIENT RELAY (server-side gateway)
+-- ---------------------------------------------------------------------------
+-- HttpService:RequestAsync is server-only in Roblox: LocalScripts can't make
+-- HTTP requests. So the server companion is the only HTTP gateway, and the
+-- client companion talks to us through these Remotes:
+--
+--   _MCPClientHello  RemoteEvent     client -> server, register/loadstring info
+--   _MCPClientLogs   RemoteEvent     client -> server, batched LogService output
+--   _MCPClientRelay  RemoteFunction  server -> client, dispatch run_live_lua eval
+--
+-- We keep these in ReplicatedStorage with Archivable=false so they don't get
+-- saved into the place file, and they're cleaned up automatically when the
+-- test session ends and the cloned DataModel is torn down.
+-- ---------------------------------------------------------------------------
+local clientRelay
+local clientHello
+local clientLogs
+do
+	local function makeRemote(className, name)
+		local existing = ReplicatedStorage:FindFirstChild(name)
+		if existing and existing.ClassName == className then
+			return existing
+		elseif existing then
+			pcall(function() existing:Destroy() end)
+		end
+		local inst = Instance.new(className)
+		inst.Name = name
+		inst.Archivable = false
+		inst.Parent = ReplicatedStorage
+		return inst
+	end
+	clientRelay = makeRemote("RemoteFunction", "_MCPClientRelay")
+	clientHello = makeRemote("RemoteEvent", "_MCPClientHello")
+	clientLogs  = makeRemote("RemoteEvent", "_MCPClientLogs")
+end
+
 local function postJSON(path, body)
 	local ok, response = pcall(function()
 		return HttpService:RequestAsync({
@@ -84,6 +160,147 @@ local function postJSON(path, body)
 	end
 end
 
+-- ---------------------------------------------------------------------------
+-- Client gateway: forward client-side Remote events into the bridge over HTTP.
+-- Clients can't make HTTP requests themselves (HttpService is server-only), so
+-- they fire RemoteEvents at us and we forward.
+-- ---------------------------------------------------------------------------
+clientHello.OnServerEvent:Connect(function(player, payload)
+	-- payload = { loadstringReady = bool }
+	-- Register the client with the bridge by issuing a single poll on its
+	-- behalf with a hello field. The bridge populates its clients map from
+	-- this poll, which is what run_live_lua's target='client' resolution
+	-- looks at.
+	local loadstringReady = false
+	if type(payload) == "table" and payload.loadstringReady ~= nil then
+		loadstringReady = payload.loadstringReady and true or false
+	end
+	task.spawn(function()
+		postJSON("/test-session/poll", {
+			sessionId = SESSION_ID,
+			target = "client",
+			userId = player.UserId,
+			playerName = player.Name,
+			hello = { loadstringReady = loadstringReady },
+		})
+	end)
+end)
+
+clientLogs.OnServerEvent:Connect(function(player, messages)
+	-- messages: array of { message, messageType, timestamp }
+	if type(messages) ~= "table" then return end
+	-- Tag each message with the player's name so multi-client tests are
+	-- legible in get_playtest_output.
+	local tagged = {}
+	for i, m in ipairs(messages) do
+		if type(m) == "table" then
+			tagged[i] = {
+				message = "[" .. player.Name .. "] " .. tostring(m.message or ""),
+				messageType = m.messageType or "MessageOutput",
+				timestamp = m.timestamp or os.time(),
+			}
+		end
+	end
+	if #tagged == 0 then return end
+	task.spawn(function()
+		postJSON("/test-session/log", {
+			sessionId = SESSION_ID,
+			source = "client",
+			messages = tagged,
+		})
+	end)
+end)
+
+-- ---------------------------------------------------------------------------
+-- Result serializer (mirrors the plugin's executeLua serializer so MCP
+-- clients see the same shapes whether they're running edit-mode execute_lua
+-- or runtime run_live_lua). Depth + cycle guarded.
+-- ---------------------------------------------------------------------------
+local function serializeValue(value, depth, seen)
+	depth = depth or 0
+	seen = seen or {}
+	if depth > 8 then return "<max depth>" end
+
+	local t = typeof(value)
+	if value == nil then
+		return nil
+	elseif t == "string" then
+		-- Cap very long strings so a runaway print doesn't pollute the wire.
+		if #value > 65536 then
+			return string.sub(value, 1, 65536) .. "...<truncated>"
+		end
+		return value
+	elseif t == "number" then
+		-- JSON can't represent NaN/Infinity; coerce to string.
+		if value ~= value then return "NaN" end
+		if value == math.huge then return "Infinity" end
+		if value == -math.huge then return "-Infinity" end
+		return value
+	elseif t == "boolean" then
+		return value
+	elseif t == "Vector3" then
+		return { type = "Vector3", X = value.X, Y = value.Y, Z = value.Z }
+	elseif t == "Vector2" then
+		return { type = "Vector2", X = value.X, Y = value.Y }
+	elseif t == "CFrame" then
+		return { type = "CFrame", components = { value:GetComponents() } }
+	elseif t == "Color3" then
+		return { type = "Color3", R = value.R, G = value.G, B = value.B }
+	elseif t == "BrickColor" then
+		return { type = "BrickColor", Name = value.Name }
+	elseif t == "UDim" then
+		return { type = "UDim", Scale = value.Scale, Offset = value.Offset }
+	elseif t == "UDim2" then
+		return {
+			type = "UDim2",
+			X = { Scale = value.X.Scale, Offset = value.X.Offset },
+			Y = { Scale = value.Y.Scale, Offset = value.Y.Offset },
+		}
+	elseif t == "Rect" then
+		return { type = "Rect", Min = { X = value.Min.X, Y = value.Min.Y }, Max = { X = value.Max.X, Y = value.Max.Y } }
+	elseif t == "Ray" then
+		return {
+			type = "Ray",
+			Origin = { X = value.Origin.X, Y = value.Origin.Y, Z = value.Origin.Z },
+			Direction = { X = value.Direction.X, Y = value.Direction.Y, Z = value.Direction.Z },
+		}
+	elseif t == "NumberRange" then
+		return { type = "NumberRange", Min = value.Min, Max = value.Max }
+	elseif t == "EnumItem" then
+		return { type = "EnumItem", Name = tostring(value), Value = value.Value }
+	elseif t == "Instance" then
+		local fullName = "<unparented>"
+		pcall(function() fullName = value:GetFullName() end)
+		return { type = "Instance", ClassName = value.ClassName, Name = value.Name, Path = fullName }
+	elseif t == "table" then
+		if seen[value] then return "<cycle>" end
+		seen[value] = true
+		local result = {}
+		local count = 0
+		for k, v in pairs(value) do
+			count += 1
+			if count > 200 then
+				result["__truncated__"] = true
+				break
+			end
+			local keyStr = type(k) == "string" and k or tostring(k)
+			result[keyStr] = serializeValue(v, depth + 1, seen)
+		end
+		seen[value] = nil
+		return result
+	elseif t == "function" then
+		return "<function>"
+	elseif t == "thread" then
+		return "<thread>"
+	elseif t == "buffer" then
+		return "<buffer>"
+	else
+		-- Fallback: stringify whatever it is.
+		local ok, str = pcall(tostring, value)
+		return ok and str or ("<" .. t .. ">")
+	end
+end
+
 LogService.MessageOut:Connect(function(message, messageType)
 	if #outputBuffer >= MAX_BUFFER then
 		-- Drop oldest to keep buffer bounded; we'd rather lose stale output
@@ -105,6 +322,7 @@ task.spawn(function()
 			outputBuffer = {}
 			local ok = postJSON("/test-session/log", {
 				sessionId = SESSION_ID,
+				source = "server",
 				messages = toSend,
 			})
 			if not ok then
@@ -120,10 +338,294 @@ task.spawn(function()
 	end
 end)
 
+-- ---------------------------------------------------------------------------
+-- Eval handler. Compiles user code via loadstring, runs under xpcall on its
+-- own task thread, captures LogService output during the call window, and
+-- POSTs the result back to /test-session/eval-result. A task.delay watchdog
+-- forces a 'timeout' reply if the user code yields too long.
+-- ---------------------------------------------------------------------------
+local function buildEvalEnv()
+	-- Mirror executeLua's sandbox so the same conveniences are available
+	-- on the in-test side. We expose game/services so the AI can mutate
+	-- live state, fire RemoteEvents, etc.
+	return setmetatable({
+		game = game,
+		workspace = workspace,
+		Players = Players,
+		Workspace = workspace,
+		ReplicatedStorage = ReplicatedStorage,
+		ServerStorage = game:GetService("ServerStorage"),
+		ServerScriptService = game:GetService("ServerScriptService"),
+		StarterGui = game:GetService("StarterGui"),
+		StarterPack = game:GetService("StarterPack"),
+		StarterPlayer = game:GetService("StarterPlayer"),
+		Lighting = game:GetService("Lighting"),
+		SoundService = game:GetService("SoundService"),
+		TweenService = game:GetService("TweenService"),
+		RunService = game:GetService("RunService"),
+		UserInputService = game:GetService("UserInputService"),
+		HttpService = HttpService,
+		CollectionService = game:GetService("CollectionService"),
+		PhysicsService = game:GetService("PhysicsService"),
+		PathfindingService = game:GetService("PathfindingService"),
+		TextService = game:GetService("TextService"),
+		MarketplaceService = game:GetService("MarketplaceService"),
+		TeleportService = game:GetService("TeleportService"),
+		DataStoreService = game:GetService("DataStoreService"),
+		MemoryStoreService = game:GetService("MemoryStoreService"),
+		MessagingService = game:GetService("MessagingService"),
+		BadgeService = game:GetService("BadgeService"),
+		Instance = Instance,
+		Vector3 = Vector3, Vector2 = Vector2, CFrame = CFrame, Color3 = Color3,
+		BrickColor = BrickColor, UDim = UDim, UDim2 = UDim2, Rect = Rect, Ray = Ray,
+		Region3 = Region3, NumberSequence = NumberSequence,
+		NumberSequenceKeypoint = NumberSequenceKeypoint, ColorSequence = ColorSequence,
+		ColorSequenceKeypoint = ColorSequenceKeypoint, NumberRange = NumberRange,
+		TweenInfo = TweenInfo, Font = Font, Enum = Enum,
+		print = print, warn = warn, error = error, assert = assert,
+		type = type, typeof = typeof, tostring = tostring, tonumber = tonumber,
+		pairs = pairs, ipairs = ipairs, next = next, select = select, unpack = unpack,
+		pcall = pcall, xpcall = xpcall,
+		rawget = rawget, rawset = rawset, rawequal = rawequal,
+		setmetatable = setmetatable, getmetatable = getmetatable, newproxy = newproxy,
+		table = table, string = string, math = math,
+		os = { time = os.time, date = os.date, difftime = os.difftime, clock = os.clock },
+		coroutine = coroutine, bit32 = bit32, utf8 = utf8, buffer = buffer,
+		task = task, wait = task.wait, delay = task.delay, spawn = task.spawn, defer = task.defer,
+		loadstring = loadstring,
+		require = require,
+		debug = debug,
+		tick = tick,
+	}, { __index = _G })
+end
+
+local function postEvalResult(replyId, payload)
+	payload.sessionId = SESSION_ID
+	payload.replyId = replyId
+	postJSON("/test-session/eval-result", payload)
+end
+
+local function handleEvalCommand(args)
+	if not args or type(args.replyId) ~= "string" or type(args.code) ~= "string" then
+		return -- malformed; bridge will time out, no point replying without replyId
+	end
+	local replyId = args.replyId
+	local code = args.code
+	local timeoutMs = type(args.timeoutMs) == "number" and args.timeoutMs or 5000
+	local captureLogs = args.captureLogs ~= false -- default true
+
+	-- Run the eval on its own task so this command poller can keep going
+	-- (a slow eval shouldn't block log streaming or further commands).
+	task.spawn(function()
+		local startedAt = os.clock()
+		local replied = false
+		local function safeReply(payload)
+			if replied then return end
+			replied = true
+			payload.durationMs = math.floor((os.clock() - startedAt) * 1000)
+			postEvalResult(replyId, payload)
+		end
+
+		-- ----------------------------------------------------------------
+		-- forwardTo path: run_live_lua with target='client' enqueues on the
+		-- server queue with forwardTo metadata; we dispatch via InvokeClient
+		-- through _MCPClientRelay. The client's OnClientInvoke handler does
+		-- the actual eval and returns the payload.
+		-- ----------------------------------------------------------------
+		if type(args.forwardTo) == "table" then
+			local targetUserId = args.forwardTo.userId
+			local targetName = args.forwardTo.playerName
+			local target = nil
+			if type(targetUserId) == "number" then
+				for _, p in ipairs(Players:GetPlayers()) do
+					if p.UserId == targetUserId then target = p; break end
+				end
+			end
+			if not target and type(targetName) == "string" and #targetName > 0 then
+				target = Players:FindFirstChild(targetName)
+			end
+			if not target then
+				safeReply({
+					ok = false,
+					errorType = "no_such_player",
+					error = string.format(
+						"Could not resolve target client (userId=%s, playerName=%s) — they may have left the test.",
+						tostring(targetUserId), tostring(targetName)
+					),
+				})
+				return
+			end
+
+			-- Server-side watchdog: InvokeClient blocks until the client
+			-- returns, but if the client hangs we still want a bounded reply.
+			task.delay(timeoutMs / 1000 + 1, function()
+				if replied then return end
+				safeReply({
+					ok = false,
+					errorType = "timeout",
+					error = string.format(
+						"Client eval did not return within %d ms (server-side watchdog).",
+						timeoutMs
+					),
+				})
+			end)
+
+			local invokeOk, payload = pcall(function()
+				return clientRelay:InvokeClient(target, {
+					replyId = replyId,
+					code = code,
+					timeoutMs = timeoutMs,
+					captureLogs = captureLogs,
+				})
+			end)
+			if not invokeOk then
+				safeReply({
+					ok = false,
+					errorType = "client_disconnected",
+					error = "InvokeClient failed (client likely left the test): " .. tostring(payload),
+				})
+				return
+			end
+			if type(payload) ~= "table" then
+				safeReply({
+					ok = false,
+					errorType = "client_protocol_error",
+					error = "Client returned a non-table payload: " .. typeof(payload),
+				})
+				return
+			end
+			safeReply(payload)
+			return
+		end
+
+		if not LOADSTRING_READY then
+			safeReply({
+				ok = false,
+				errorType = "loadstring_disabled",
+				error = "loadstring is disabled. Enable ServerScriptService.LoadStringEnabled in the Properties pane (it has the NotScriptable tag so it cannot be flipped from code) and start a new play test.",
+			})
+			return
+		end
+
+		-- Capture logs scoped to this eval call. We collect into a private
+		-- buffer via a fresh LogService connection, then disconnect once
+		-- we've replied.
+		local localLogs = {}
+		local logConn = nil
+		if captureLogs then
+			logConn = LogService.MessageOut:Connect(function(message, messageType)
+				if #localLogs >= 200 then return end
+				table.insert(localLogs, {
+					message = tostring(message),
+					messageType = messageType.Name,
+					timestamp = os.time(),
+				})
+			end)
+		end
+
+		local function detachLogs()
+			if logConn then
+				pcall(function() logConn:Disconnect() end)
+				logConn = nil
+			end
+		end
+
+		-- Compile. NOTE: loadstring returns (nil, errorMessage) on syntax
+		-- failure rather than throwing — wrapping in pcall would discard the
+		-- error message into pcall's third return slot and leave fnOrErr=nil.
+		-- Calling loadstring directly captures both function and error cleanly.
+		local fnOrErr, compileErr = loadstring(code, "run_live_lua")
+		if type(fnOrErr) ~= "function" then
+			detachLogs()
+			safeReply({
+				ok = false,
+				errorType = "compile_error",
+				error = "Failed to compile: " .. tostring(compileErr or fnOrErr or "<unknown>"),
+				logs = captureLogs and localLogs or nil,
+			})
+			return
+		end
+
+		setfenv(fnOrErr, buildEvalEnv())
+
+		-- Watchdog: if the user code yields longer than timeoutMs, reply
+		-- with a synthetic timeout. The user thread will keep running
+		-- (we can't kill a yielded thread cleanly) but the AI gets a
+		-- bounded response.
+		task.delay(timeoutMs / 1000, function()
+			if replied then return end
+			detachLogs()
+			safeReply({
+				ok = false,
+				errorType = "timeout",
+				error = string.format("Eval did not return within %d ms (the spawned thread may still be running in the test).", timeoutMs),
+				logs = captureLogs and localLogs or nil,
+			})
+		end)
+
+		-- Execute. Pack multi-return into an array so the bridge can
+		-- preserve `return a, b, c` semantics.
+		local results = table.pack(xpcall(fnOrErr, function(err)
+			return { error = tostring(err), traceback = debug.traceback(nil, 2) }
+		end))
+		local execOk = results[1]
+		if replied then
+			-- Watchdog already responded.
+			detachLogs()
+			return
+		end
+
+		-- LogService.MessageOut events are deferred and need TWO Heartbeats
+		-- to actually invoke listeners (verified empirically — one task.wait
+		-- isn't enough). Yield twice so prints fired during the eval land
+		-- in localLogs before we detach + reply. Total cost ~32ms.
+		if captureLogs then
+			task.wait()
+			task.wait()
+		end
+
+		if not execOk then
+			detachLogs()
+			local err = results[2] or {}
+			safeReply({
+				ok = false,
+				errorType = "runtime_error",
+				error = (type(err) == "table" and err.error) or tostring(err),
+				traceback = (type(err) == "table") and err.traceback or nil,
+				logs = captureLogs and localLogs or nil,
+			})
+			return
+		end
+
+		-- Pack remaining values (results[2..n]) as the multi-return array.
+		local values = {}
+		for i = 2, results.n do
+			values[i - 1] = serializeValue(results[i], 0, {})
+		end
+
+		detachLogs()
+		safeReply({
+			ok = true,
+			values = values,
+			logs = captureLogs and localLogs or nil,
+		})
+	end)
+end
+
 -- Command poller
 task.spawn(function()
+	-- First poll includes hello so the bridge can record loadstring
+	-- readiness for later run_live_lua callers.
+	local helloSent = false
 	while not stopRequested and consecutiveFailures < MAX_CONSECUTIVE_FAILURES do
-		local ok, response = postJSON("/test-session/poll", { sessionId = SESSION_ID })
+		local pollBody = { sessionId = SESSION_ID, target = "server" }
+		if not helloSent then
+			pollBody.hello = { loadstringReady = LOADSTRING_READY }
+		end
+		local ok, response = postJSON("/test-session/poll", pollBody)
+		if ok then
+			helloSent = true
+		end
 		if ok and response and response.Body then
 			local decodeOk, body = pcall(function()
 				return HttpService:JSONDecode(response.Body)
@@ -143,6 +645,7 @@ task.spawn(function()
 						outputBuffer = {}
 						postJSON("/test-session/log", {
 							sessionId = SESSION_ID,
+							source = "server",
 							messages = final,
 						})
 					end
@@ -160,6 +663,8 @@ task.spawn(function()
 						end)
 					end
 					return
+				elseif body.command and body.command.cmd == "eval" then
+					handleEvalCommand(body.command.args)
 				end
 			end
 		end
@@ -168,6 +673,362 @@ task.spawn(function()
 end)
 ]]
 
+-- ----------------------------------------------------------------------------
+-- CLIENT companion template. Runs as a LocalScript in StarterPlayerScripts
+-- (which auto-clones into each Player's PlayerScripts on join). Each Player
+-- gets their own copy and identifies to the bridge by userId. Only handles
+-- 'eval' commands and streams its local LogService.
+--
+-- It does NOT call EndTest (only the server can do that), so the only stop
+-- signal it cares about is the bridge's `ended` flag.
+-- ----------------------------------------------------------------------------
+local CLIENT_COMPANION_SCRIPT_TEMPLATE = [[-- _MCPTestCompanion_Client (auto-generated, safe to delete)
+-- Runs in each Player's PlayerScripts during a Studio test session started by
+-- the MCP plugin. Streams local LogService output to the server companion via
+-- RemoteEvents and runs run_live_lua eval commands dispatched through a
+-- RemoteFunction.
+--
+-- IMPORTANT: HttpService is server-only in Roblox. LocalScripts CANNOT make
+-- HTTP requests (they'll silently fail with HttpError). So everything goes
+-- through Remotes. The server companion in ServerScriptService is the only
+-- HTTP gateway and forwards messages on our behalf.
+--
+-- DO NOT modify or delete while a play test is running — it will be cleaned
+-- up automatically by the MCP plugin.
+
+local LogService = game:GetService("LogService")
+local Players = game:GetService("Players")
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local LOG_FLUSH_INTERVAL = 0.25
+local MAX_BUFFER = 5000
+local REMOTE_WAIT_TIMEOUT = 30 -- seconds
+
+local localPlayer = Players.LocalPlayer
+if not localPlayer then return end -- LocalScript guarantees LocalPlayer; bail otherwise
+local PLAYER_NAME = localPlayer.Name
+
+-- Wait for the server companion to create the Remotes in ReplicatedStorage.
+-- The server companion runs slightly before us in test mode (Server scripts
+-- start before LocalScripts), but we still WaitForChild defensively.
+local clientRelay = ReplicatedStorage:WaitForChild("_MCPClientRelay", REMOTE_WAIT_TIMEOUT)
+local clientHello = ReplicatedStorage:WaitForChild("_MCPClientHello", REMOTE_WAIT_TIMEOUT)
+local clientLogs  = ReplicatedStorage:WaitForChild("_MCPClientLogs",  REMOTE_WAIT_TIMEOUT)
+if not (clientRelay and clientHello and clientLogs) then
+	-- Server companion didn't set up Remotes in time. Nothing we can do.
+	warn("[_MCPTestCompanion_Client] Remotes not found in ReplicatedStorage — server companion missing or slow")
+	return
+end
+
+-- Probe loadstring availability ONCE up front. Note: client-side gating may
+-- differ from server's ServerScriptService.LoadStringEnabled, so we probe.
+local LOADSTRING_READY = false
+do
+	local ok, fn = pcall(loadstring, "return 1")
+	if ok and type(fn) == "function" then
+		local execOk, execVal = pcall(fn)
+		if execOk and execVal == 1 then
+			LOADSTRING_READY = true
+		end
+	end
+end
+
+-- Announce ourselves to the server companion, which will register us with
+-- the bridge over HTTP on our behalf.
+clientHello:FireServer({ loadstringReady = LOADSTRING_READY })
+
+-- ---------------------------------------------------------------------------
+-- Result serializer (matches the server companion's serializer 1:1).
+-- ---------------------------------------------------------------------------
+local function serializeValue(value, depth, seen)
+	depth = depth or 0
+	seen = seen or {}
+	if depth > 8 then return "<max depth>" end
+	local t = typeof(value)
+	if value == nil then
+		return nil
+	elseif t == "string" then
+		if #value > 65536 then return string.sub(value, 1, 65536) .. "...<truncated>" end
+		return value
+	elseif t == "number" then
+		if value ~= value then return "NaN" end
+		if value == math.huge then return "Infinity" end
+		if value == -math.huge then return "-Infinity" end
+		return value
+	elseif t == "boolean" then
+		return value
+	elseif t == "Vector3" then
+		return { type = "Vector3", X = value.X, Y = value.Y, Z = value.Z }
+	elseif t == "Vector2" then
+		return { type = "Vector2", X = value.X, Y = value.Y }
+	elseif t == "CFrame" then
+		return { type = "CFrame", components = { value:GetComponents() } }
+	elseif t == "Color3" then
+		return { type = "Color3", R = value.R, G = value.G, B = value.B }
+	elseif t == "BrickColor" then
+		return { type = "BrickColor", Name = value.Name }
+	elseif t == "UDim" then
+		return { type = "UDim", Scale = value.Scale, Offset = value.Offset }
+	elseif t == "UDim2" then
+		return {
+			type = "UDim2",
+			X = { Scale = value.X.Scale, Offset = value.X.Offset },
+			Y = { Scale = value.Y.Scale, Offset = value.Y.Offset },
+		}
+	elseif t == "Rect" then
+		return { type = "Rect", Min = { X = value.Min.X, Y = value.Min.Y }, Max = { X = value.Max.X, Y = value.Max.Y } }
+	elseif t == "Ray" then
+		return {
+			type = "Ray",
+			Origin = { X = value.Origin.X, Y = value.Origin.Y, Z = value.Origin.Z },
+			Direction = { X = value.Direction.X, Y = value.Direction.Y, Z = value.Direction.Z },
+		}
+	elseif t == "NumberRange" then
+		return { type = "NumberRange", Min = value.Min, Max = value.Max }
+	elseif t == "EnumItem" then
+		return { type = "EnumItem", Name = tostring(value), Value = value.Value }
+	elseif t == "Instance" then
+		local fullName = "<unparented>"
+		pcall(function() fullName = value:GetFullName() end)
+		return { type = "Instance", ClassName = value.ClassName, Name = value.Name, Path = fullName }
+	elseif t == "table" then
+		if seen[value] then return "<cycle>" end
+		seen[value] = true
+		local result = {}
+		local count = 0
+		for k, v in pairs(value) do
+			count += 1
+			if count > 200 then result["__truncated__"] = true; break end
+			local keyStr = type(k) == "string" and k or tostring(k)
+			result[keyStr] = serializeValue(v, depth + 1, seen)
+		end
+		seen[value] = nil
+		return result
+	elseif t == "function" then
+		return "<function>"
+	elseif t == "thread" then
+		return "<thread>"
+	elseif t == "buffer" then
+		return "<buffer>"
+	else
+		local ok, str = pcall(tostring, value)
+		return ok and str or ("<" .. t .. ">")
+	end
+end
+
+-- ---------------------------------------------------------------------------
+-- LogService streaming → batched FireServer
+-- ---------------------------------------------------------------------------
+local outputBuffer = {}
+LogService.MessageOut:Connect(function(message, messageType)
+	if #outputBuffer >= MAX_BUFFER then
+		table.remove(outputBuffer, 1)
+	end
+	table.insert(outputBuffer, {
+		message = tostring(message),
+		messageType = messageType.Name,
+		timestamp = os.time(),
+	})
+end)
+
+task.spawn(function()
+	while true do
+		if #outputBuffer > 0 then
+			local toSend = outputBuffer
+			outputBuffer = {}
+			-- FireServer is fire-and-forget; the server companion will tag
+			-- with our PLAYER_NAME and forward to /test-session/log.
+			pcall(function() clientLogs:FireServer(toSend) end)
+		end
+		task.wait(LOG_FLUSH_INTERVAL)
+	end
+end)
+
+-- ---------------------------------------------------------------------------
+-- Eval handler. The server companion calls clientRelay:InvokeClient(player,
+-- args), which suspends the server until we return a payload table. We do
+-- the same setfenv/xpcall sandbox dance as the server, with our own watchdog.
+-- ---------------------------------------------------------------------------
+local function buildEvalEnv()
+	return setmetatable({
+		game = game,
+		workspace = workspace,
+		Players = Players,
+		Workspace = workspace,
+		ReplicatedStorage = ReplicatedStorage,
+		StarterGui = game:GetService("StarterGui"),
+		StarterPlayer = game:GetService("StarterPlayer"),
+		Lighting = game:GetService("Lighting"),
+		SoundService = game:GetService("SoundService"),
+		TweenService = game:GetService("TweenService"),
+		RunService = game:GetService("RunService"),
+		UserInputService = game:GetService("UserInputService"),
+		ContextActionService = game:GetService("ContextActionService"),
+		CollectionService = game:GetService("CollectionService"),
+		GuiService = game:GetService("GuiService"),
+		TextService = game:GetService("TextService"),
+		MarketplaceService = game:GetService("MarketplaceService"),
+		Instance = Instance,
+		Vector3 = Vector3, Vector2 = Vector2, CFrame = CFrame, Color3 = Color3,
+		BrickColor = BrickColor, UDim = UDim, UDim2 = UDim2, Rect = Rect, Ray = Ray,
+		Region3 = Region3, NumberSequence = NumberSequence,
+		NumberSequenceKeypoint = NumberSequenceKeypoint, ColorSequence = ColorSequence,
+		ColorSequenceKeypoint = ColorSequenceKeypoint, NumberRange = NumberRange,
+		TweenInfo = TweenInfo, Font = Font, Enum = Enum,
+		print = print, warn = warn, error = error, assert = assert,
+		type = type, typeof = typeof, tostring = tostring, tonumber = tonumber,
+		pairs = pairs, ipairs = ipairs, next = next, select = select, unpack = unpack,
+		pcall = pcall, xpcall = xpcall,
+		rawget = rawget, rawset = rawset, rawequal = rawequal,
+		setmetatable = setmetatable, getmetatable = getmetatable, newproxy = newproxy,
+		table = table, string = string, math = math,
+		os = { time = os.time, date = os.date, difftime = os.difftime, clock = os.clock },
+		coroutine = coroutine, bit32 = bit32, utf8 = utf8, buffer = buffer,
+		task = task, wait = task.wait, delay = task.delay, spawn = task.spawn, defer = task.defer,
+		loadstring = loadstring,
+		require = require,
+		debug = debug,
+		tick = tick,
+		LocalPlayer = localPlayer,
+		PlayerGui = localPlayer:FindFirstChildOfClass("PlayerGui"),
+	}, { __index = _G })
+end
+
+local function runEval(args)
+	-- args = { replyId, code, timeoutMs, captureLogs }
+	if type(args) ~= "table" or type(args.code) ~= "string" then
+		return { ok = false, errorType = "client_protocol_error", error = "Invalid eval args" }
+	end
+	local code = args.code
+	local timeoutMs = type(args.timeoutMs) == "number" and args.timeoutMs or 5000
+	local captureLogs = args.captureLogs ~= false
+
+	local startedAt = os.clock()
+	local replied = false
+	local resultPayload = nil
+	local function reply(payload)
+		if replied then return end
+		replied = true
+		payload.durationMs = math.floor((os.clock() - startedAt) * 1000)
+		resultPayload = payload
+	end
+
+	if not LOADSTRING_READY then
+		reply({
+			ok = false,
+			errorType = "loadstring_disabled",
+			error = "loadstring is disabled on this client. (LocalScript loadstring depends on Studio settings; ServerScriptService.LoadStringEnabled may also be required.)",
+		})
+		return resultPayload
+	end
+
+	local localLogs = {}
+	local logConn = nil
+	if captureLogs then
+		logConn = LogService.MessageOut:Connect(function(message, messageType)
+			if #localLogs >= 200 then return end
+			table.insert(localLogs, {
+				message = tostring(message),
+				messageType = messageType.Name,
+				timestamp = os.time(),
+			})
+		end)
+	end
+	local function detachLogs()
+		if logConn then
+			pcall(function() logConn:Disconnect() end)
+			logConn = nil
+		end
+	end
+
+	-- Capture both return values directly (loadstring returns nil + error
+	-- message on syntax failure rather than throwing).
+	local fnOrErr, compileErr = loadstring(code, "run_live_lua_client")
+	if type(fnOrErr) ~= "function" then
+		detachLogs()
+		reply({
+			ok = false,
+			errorType = "compile_error",
+			error = "Failed to compile: " .. tostring(compileErr or fnOrErr or "<unknown>"),
+			logs = captureLogs and localLogs or nil,
+		})
+		return resultPayload
+	end
+	setfenv(fnOrErr, buildEvalEnv())
+
+	-- Local watchdog: if user code yields longer than timeoutMs, the watchdog
+	-- pre-fills resultPayload with a timeout response, then the slow code
+	-- still finishes (we can't kill it cleanly) but its result is discarded.
+	task.delay(timeoutMs / 1000, function()
+		if replied then return end
+		detachLogs()
+		reply({
+			ok = false,
+			errorType = "timeout",
+			error = string.format("Eval did not return within %d ms (the spawned thread may still be running in the client).", timeoutMs),
+			logs = captureLogs and localLogs or nil,
+		})
+	end)
+
+	local results = table.pack(xpcall(fnOrErr, function(err)
+		return { error = tostring(err), traceback = debug.traceback(nil, 2) }
+	end))
+	local execOk = results[1]
+	if replied then
+		detachLogs()
+		return resultPayload
+	end
+
+	-- LogService.MessageOut events are deferred and need TWO Heartbeats
+	-- to actually invoke listeners (verified empirically — one task.wait
+	-- isn't enough). Yield twice so prints fired during the eval land
+	-- in localLogs before we detach + reply. Total cost ~32ms.
+	if captureLogs then
+		task.wait()
+		task.wait()
+	end
+
+	if not execOk then
+		detachLogs()
+		local err = results[2] or {}
+		reply({
+			ok = false,
+			errorType = "runtime_error",
+			error = (type(err) == "table" and err.error) or tostring(err),
+			traceback = (type(err) == "table") and err.traceback or nil,
+			logs = captureLogs and localLogs or nil,
+		})
+		return resultPayload
+	end
+
+	local values = {}
+	for i = 2, results.n do
+		values[i - 1] = serializeValue(results[i], 0, {})
+	end
+	detachLogs()
+	reply({
+		ok = true,
+		values = values,
+		logs = captureLogs and localLogs or nil,
+	})
+	return resultPayload
+end
+
+clientRelay.OnClientInvoke = function(args)
+	-- pcall the whole thing so a runtime crash inside runEval still produces
+	-- a deterministic reply for the server-side InvokeClient caller.
+	local ok, payloadOrErr = pcall(runEval, args)
+	if ok and type(payloadOrErr) == "table" then
+		return payloadOrErr
+	end
+	return {
+		ok = false,
+		errorType = "client_protocol_error",
+		error = "runEval crashed: " .. tostring(payloadOrErr),
+	}
+end
+]]
+
 -- gsub-safe replacement (treat replacement as plain string, not a pattern).
 local function plainReplace(haystack, needle, replacement)
 	-- Use string.find with plain=true to avoid pattern interpretation in needle.
@@ -194,31 +1055,44 @@ local function cleanupTestCompanions()
 			count += 1
 		end
 	end)
-	-- Belt & suspenders: also remove any name-matching script in
-	-- ServerScriptService in case the tag was somehow stripped.
+	-- Belt & suspenders: also remove any name-matching scripts in the
+	-- two known parents in case the tag was somehow stripped.
 	pcall(function()
 		local sss = game:GetService("ServerScriptService")
 		for _, child in ipairs(sss:GetChildren()) do
-			if child.Name == TEST_COMPANION_NAME then
+			if child.Name == TEST_COMPANION_NAME or child.Name == TEST_COMPANION_NAME_CLIENT then
 				pcall(function() child:Destroy() end)
 				count += 1
 			end
 		end
 	end)
+	pcall(function()
+		local starterPlayer = game:GetService("StarterPlayer")
+		local sps = starterPlayer and starterPlayer:FindFirstChild("StarterPlayerScripts")
+		if sps then
+			for _, child in ipairs(sps:GetChildren()) do
+				if child.Name == TEST_COMPANION_NAME or child.Name == TEST_COMPANION_NAME_CLIENT then
+					pcall(function() child:Destroy() end)
+					count += 1
+				end
+			end
+		end
+	end)
 	return count
 end
 
 local function injectTestCompanion(serverUrl, sessionId)
-	-- Always sweep before creating to guarantee at most one companion exists.
+	-- Always sweep before creating to guarantee at most one of each companion exists.
 	cleanupTestCompanions()
 
-	local source = COMPANION_SCRIPT_TEMPLATE
-	source = plainReplace(source, "__MCP_SERVER_URL__", serverUrl)
-	source = plainReplace(source, "__MCP_SESSION_ID__", sessionId)
+	-- ----- SERVER companion -----
+	local serverSource = COMPANION_SCRIPT_TEMPLATE
+	serverSource = plainReplace(serverSource, "__MCP_SERVER_URL__", serverUrl)
+	serverSource = plainReplace(serverSource, "__MCP_SESSION_ID__", sessionId)
 
-	local script = Instance.new("Script")
-	script.Name = TEST_COMPANION_NAME
-	script.Source = source
+	local serverScript = Instance.new("Script")
+	serverScript.Name = TEST_COMPANION_NAME
+	serverScript.Source = serverSource
 	-- IMPORTANT: Archivable MUST stay true (the default).
 	-- ExecutePlayModeAsync builds the test DataModel by Clone()-ing the Edit
 	-- DataModel, and Instance:Clone() silently returns nil for any instance
@@ -231,14 +1105,42 @@ local function injectTestCompanion(serverUrl, sessionId)
 	-- We rely on the cleanup sweeps (on plugin activate, before each test,
 	-- after each test) to keep companions out of the saved file. The script
 	-- is also tagged with TEST_COMPANION_TAG so any orphan is easy to find.
-	script.Archivable = true
-	script.Parent = game:GetService("ServerScriptService")
+	serverScript.Archivable = true
+	serverScript.Parent = game:GetService("ServerScriptService")
+	pcall(function()
+		CollectionService:AddTag(serverScript, TEST_COMPANION_TAG)
+	end)
 
+	-- ----- CLIENT companion -----
+	-- LocalScripts in StarterPlayer.StarterPlayerScripts auto-clone into
+	-- each Player's PlayerScripts on join, so this single LocalScript
+	-- yields one companion per player in the test.
+	local clientScript = nil
 	pcall(function()
-		CollectionService:AddTag(script, TEST_COMPANION_TAG)
+		local clientSource = CLIENT_COMPANION_SCRIPT_TEMPLATE
+		clientSource = plainReplace(clientSource, "__MCP_SERVER_URL__", serverUrl)
+		clientSource = plainReplace(clientSource, "__MCP_SESSION_ID__", sessionId)
+
+		local sp = game:GetService("StarterPlayer")
+		local sps = sp:FindFirstChild("StarterPlayerScripts")
+		if not sps then
+			-- Some empty places ship without StarterPlayerScripts. Create it.
+			sps = Instance.new("StarterPlayerScripts")
+			sps.Parent = sp
+		end
+
+		local ls = Instance.new("LocalScript")
+		ls.Name = TEST_COMPANION_NAME_CLIENT
+		ls.Source = clientSource
+		ls.Archivable = true
+		ls.Parent = sps
+		pcall(function()
+			CollectionService:AddTag(ls, TEST_COMPANION_TAG)
+		end)
+		clientScript = ls
 	end)
 
-	return script
+	return serverScript, clientScript
 end
 
 -- Track output log for get_output
@@ -282,18 +1184,41 @@ local function serializeValue(value)
 	end
 end
 
--- Helper to log an action for undo tracking
-local function logAction(actionType, target, summary, details)
-	-- Clear redo history when a new action is performed
-	redoHistory = {}
+-- ============================================
+-- DEFERRED ACTION LOGGING
+-- ============================================
+-- Handlers call logAction() to record what they just did for the
+-- get_history / undo / redo tools. We don't want a tracked entry sitting
+-- in actionHistory unless Studio's ChangeHistoryService actually committed
+-- a waypoint for the same operation — otherwise undo() will pop our
+-- tracked entry while Studio reverts something completely different.
+--
+-- Architecture: logAction() stashes the entry in `_pendingActionLog`.
+-- processRequest() snapshots GetCanUndo / GetCanRedo around the
+-- TryBeginRecording / FinishRecording window, then calls
+-- commitPendingLog() iff a real waypoint was added. Otherwise it calls
+-- discardPendingLog().
+local _pendingActionLog = nil  -- single-slot buffer for current request
 
-	table.insert(actionHistory, {
+local function logAction(actionType, target, summary, details)
+	-- Stash; processRequest decides whether to keep it.
+	_pendingActionLog = {
 		action = actionType,
 		target = target,
 		summary = summary,
 		details = details or {},
-		timestamp = os.time()
-	})
+		timestamp = os.time(),
+	}
+end
+
+local function commitPendingLog()
+	if not _pendingActionLog then return end
+	local entry = _pendingActionLog
+	_pendingActionLog = nil
+
+	-- A new committed action clears the redo branch.
+	redoHistory = {}
+	table.insert(actionHistory, entry)
 
 	-- Keep history from growing too large
 	if #actionHistory > MAX_ACTION_HISTORY then
@@ -301,6 +1226,10 @@ local function logAction(actionType, target, summary, details)
 	end
 end
 
+local function discardPendingLog()
+	_pendingActionLog = nil
+end
+
 -- Connect to LogService to capture output
 LogService.MessageOut:Connect(function(message, messageType)
 	table.insert(outputBuffer, {
@@ -1014,9 +1943,6 @@ local mutationEndpoints = {
 	["/api/set-calculated-property"] = "Set Calculated Property",
 	["/api/set-relative-property"] = "Set Relative Property",
 	["/api/set-script-source"] = "Set Script Source",
-	["/api/edit-script-lines"] = "Edit Script Lines",
-	["/api/insert-script-lines"] = "Insert Script Lines",
-	["/api/delete-script-lines"] = "Delete Script Lines",
 	["/api/set-attribute"] = "Set Attribute",
 	["/api/delete-attribute"] = "Delete Attribute",
 	["/api/add-tag"] = "Add Tag",
@@ -1024,6 +1950,14 @@ local mutationEndpoints = {
 	["/api/clone-instance"] = "Clone Instance",
 	["/api/move-instance"] = "Move Instance",
 	["/api/insert-asset"] = "Insert Asset",
+	-- Script editing: modern recording API (migrated from legacy SetWaypoint)
+	["/api/edit-script"] = "Edit Script",
+	["/api/find-and-replace-in-scripts"] = "Find and Replace in Scripts",
+	-- Arbitrary Lua: wraps the WHOLE execution in one waypoint. Auto-rolls
+	-- back on error via FinishRecording(Cancel). Mutations from yielded /
+	-- task.spawn'd code that runs AFTER the handler returns are NOT captured
+	-- (documented limitation).
+	["/api/execute-lua"] = "Execute Lua",
 }
 
 -- Endpoint to handler mapping (populated after handlers are defined below)
@@ -1048,18 +1982,118 @@ processRequest = function(request)
 	-- Check if this is a mutation endpoint
 	local recordingName = mutationEndpoints[endpoint]
 	if recordingName then
-		-- Wrap in ChangeHistoryService recording for proper undo
+		-- ─────────────────────────────────────────────────────────────────
+		-- Two parallel undo channels — CHS waypoints AND plugin-side log
+		-- ─────────────────────────────────────────────────────────────────
+		-- Most mutations flow through ChangeHistoryService (CHS) waypoints:
+		-- create_object, set_property, delete_object, etc. — these we track
+		-- BOTH in CHS (so Ctrl+Z and our undo tool work) AND in actionHistory
+		-- (so get_history can show readable summaries).
+		--
+		-- BUT script `Source` property changes are architecturally decoupled
+		-- from CHS in Studio: the script editor maintains its OWN undo stack
+		-- separate from CHS. A direct `instance.Source = "..."` assignment
+		-- changes the value, but CHS will NOT capture it in a waypoint — so
+		-- CHS:Undo() won't revert it (it'll skip ahead and revert the previous
+		-- waypoint, destroying something unrelated). This is the root cause
+		-- of "Bug 1: edit_script undo doesn't actually revert source".
+		--
+		-- Fix: for source-only handlers (edit_script / set_script_source /
+		-- find_and_replace_in_scripts) we Cancel the CHS recording (no empty
+		-- waypoint) and instead store a pre/post-Source snapshot inside the
+		-- tracked action's `details.scriptEdits`. Our undo handler detects
+		-- these entries and restores the source manually via direct
+		-- assignment, bypassing CHS entirely. Real undo, no side effects.
+		--
+		-- Result sentinels that drive the decision:
+		--   • result._isSourceEditOnly == true →
+		--       Script source changes only, no CHS waypoint to keep.
+		--       Cancel recording, KEEP tracked log (with snapshots).
+		--   • result._didNotMutate == true →
+		--       Handler knows it did nothing (e.g. find_and_replace 0 matches).
+		--       Cancel recording, DROP tracked log.
+		--   • result._mutatesUnknown == true →
+		--       Arbitrary user code (execute_lua). Use a synchronous
+		--       descendant-count delta to decide.
+		--   • Otherwise →
+		--       Trusted mutator. Commit recording, KEEP tracked log.
+		--
+		-- Why synchronous descendant-count delta (and NOT DescendantAdded)?
+		-- The DescendantAdded / DescendantRemoving signals fire DEFERRED in
+		-- Studio plugins — by the time the handler returns and we'd read a
+		-- counter, no events have fired yet. Earlier v2 used those signals
+		-- and silently rolled back every execute_lua mutation. Synchronous
+		-- snapshot via #game:GetDescendants() works around the deferral —
+		-- it's O(N) but only runs for the unknown-mutator case.
+		_pendingActionLog = nil  -- start clean
+
+		-- Snapshot tree size BEFORE handler, only when we'll need it.
+		-- For execute_lua (the only _mutatesUnknown source) we need the
+		-- before/after delta; everything else trusts the handler's sentinel.
+		local descCountBefore
+		if endpoint == "/api/execute-lua" then
+			descCountBefore = #game:GetDescendants()
+		end
+
 		local recording = ChangeHistoryService:TryBeginRecording("MCP: " .. recordingName)
 		local success, result = pcall(handler, data)
 
+		local handlerOK = success and not (result and result.error)
+
+		-- commitCHS: should we keep the CHS waypoint?
+		-- commitLog: should we keep the tracked action entry?
+		local commitCHS = false
+		local commitLog = false
+
+		if handlerOK then
+			local r = type(result) == "table" and result or nil
+			if r and r._isSourceEditOnly == true then
+				-- Source-only: Cancel CHS (no real waypoint), keep tracked log
+				-- with snapshots for plugin-side undo.
+				commitCHS = false
+				commitLog = true
+			elseif r and r._didNotMutate == true then
+				-- Genuine no-op: drop both.
+				commitCHS = false
+				commitLog = false
+			elseif r and r._mutatesUnknown == true then
+				-- execute_lua: synchronous tree-size delta tells us if
+				-- user code added/removed instances. Property-only mutations
+				-- (e.g. just changing Position) won't be detected — that's an
+				-- accepted edge case; users wanting full tracking should use
+				-- the dedicated set_property tool.
+				local treeChanged = (#game:GetDescendants() ~= descCountBefore)
+				commitCHS = treeChanged
+				commitLog = treeChanged
+			else
+				-- Trusted mutator (create_object, set_property, etc.) →
+				-- always commit on handler success.
+				commitCHS = true
+				commitLog = true
+			end
+		end
+
 		if recording then
-			if success and not (result and result.error) then
+			if commitCHS then
 				ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
 			else
 				ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
 			end
 		end
 
+		if commitLog then
+			commitPendingLog()
+		else
+			discardPendingLog()
+		end
+
+		-- Strip internal sentinels from the response so callers don't see them.
+		if type(result) == "table" then
+			result._mutatesUnknown = nil
+			result._didNotMutate = nil
+			result._isSourceEditOnly = nil
+		end
+
 		if success then
 			return result
 		else
@@ -2719,55 +3753,62 @@ handlers.setScriptSource = function(requestData)
 	sourceToSet = sourceToSet:gsub("\\t", "\t")
 	sourceToSet = sourceToSet:gsub("\\r", "\r")
 	sourceToSet = sourceToSet:gsub("\\\\", "\\")
-	local updateSuccess, updateResult = pcall(function()
-		local oldSourceLength = string.len(instance.Source)
 
-		ScriptEditorService:UpdateSourceAsync(instance, function(oldContent)
-			return sourceToSet
-		end)
-
-		ChangeHistoryService:SetWaypoint("Set script source: " .. instance.Name)
-
-		return {
-			success = true,
-			instancePath = instancePath,
-			oldSourceLength = oldSourceLength,
-			newSourceLength = string.len(sourceToSet),
-			method = "UpdateSourceAsync",
-			message = "Script source updated successfully (editor-safe)"
-		}
-	end)
-
-	if updateSuccess then
-		return updateResult
-	end
+	-- Primary path: direct property assignment. Roblox's script editor
+	-- maintains its own undo stack separate from ChangeHistoryService — so
+	-- CHS waypoints will NOT capture this Source change. We work around
+	-- this by snapshotting pre/post source into the tracked action entry;
+	-- the undo handler restores the snapshot directly. The processRequest
+	-- wrapper sees `_isSourceEditOnly` and Cancels the (empty) CHS
+	-- recording so it doesn't pollute Studio's undo stack.
+	--
+	-- Caveat: if the user has unsaved buffer edits in Studio's script
+	-- editor for this script, those edits will be replaced. Intentional —
+	-- consistent with previous behavior, and predictable for callers.
+	local preSource = instance.Source
 
-	-- Fallback to direct assignment if UpdateSourceAsync fails
 	local directSuccess, directResult = pcall(function()
-		local oldSource = instance.Source
+		local oldSourceLength = string.len(preSource)
 		instance.Source = sourceToSet
 
-		ChangeHistoryService:SetWaypoint("Set script source: " .. instance.Name)
-
 		return {
 			success = true,
 			instancePath = instancePath,
-			oldSourceLength = string.len(oldSource),
+			oldSourceLength = oldSourceLength,
 			newSourceLength = string.len(sourceToSet),
 			method = "direct",
-			message = "Script source updated successfully (direct assignment)"
+			message = "Script source updated successfully"
 		}
 	end)
 
 	if directSuccess then
-		-- Log for undo tracking
-		logAction("set_script_source", instancePath, "Script source replaced (" .. directResult.newSourceLength .. " chars)", {
-			method = "direct"
-		})
+		-- Snapshot for plugin-side undo restoration. Stored as a list so the
+		-- same code path also handles find_and_replace's batch edits.
+		logAction(
+			"set_script_source",
+			instancePath,
+			"Script source replaced (" .. directResult.newSourceLength .. " chars)",
+			{
+				method = "direct",
+				scriptEdits = {
+					{
+						instancePath = instancePath,
+						preSource = preSource,
+						postSource = sourceToSet,
+					},
+				},
+			}
+		)
+		-- Source-only change: tell processRequest to Cancel the CHS
+		-- recording but keep our tracked log entry (which has the snapshots).
+		directResult._isSourceEditOnly = true
 		return directResult
 	end
 
-	-- Final fallback: replace the script entirely
+	-- Fallback: replace the script entirely (used when direct assignment
+	-- throws — e.g. for some plugin-managed script kinds). This DOES
+	-- mutate the tree (Destroy + Instance.new), so CHS captures it.
+	-- That makes the action a regular CHS-backed mutation, not source-only.
 	local replaceSuccess, replaceResult = pcall(function()
 		local parent = instance.Parent
 		local name = instance.Name
@@ -2788,8 +3829,6 @@ handlers.setScriptSource = function(requestData)
 		newScript.Parent = parent
 		instance:Destroy()
 
-		ChangeHistoryService:SetWaypoint("Replace script: " .. name)
-
 		return {
 			success = true,
 			instancePath = getInstancePath(newScript),
@@ -2799,254 +3838,28 @@ handlers.setScriptSource = function(requestData)
 	end)
 
 	if replaceSuccess then
-		-- Log for undo tracking
 		logAction("set_script_source", replaceResult.instancePath, "Script replaced entirely", {
 			method = "replace"
 		})
+		-- Replace path mutates the tree (Destroy + Instance.new) — CHS
+		-- captures this naturally, so we let processRequest Commit normally.
 		return replaceResult
 	else
 		return {
-			error = "Failed to set script source. UpdateSourceAsync failed: " .. tostring(updateResult) ..
-			        ". Direct assignment failed: " .. tostring(directResult) ..
+			error = "Failed to set script source. Direct assignment failed: " .. tostring(directResult) ..
 			        ". Replace method failed: " .. tostring(replaceResult)
 		}
 	end
 end
 
--- Partial Script Editing: Edit specific lines
-handlers.editScriptLines = function(requestData)
-	local instancePath = requestData.instancePath
-	local startLine = requestData.startLine
-	local endLine = requestData.endLine
-	local newContent = requestData.newContent
-
-	if not instancePath or not startLine or not endLine or not newContent then
-		return { error = "Instance path, startLine, endLine, and newContent are required" }
-	end
-
-	-- Normalize escape sequences that may have been double-escaped
-	newContent = newContent:gsub("\\n", "\n")
-	newContent = newContent:gsub("\\t", "\t")
-	newContent = newContent:gsub("\\r", "\r")
-	newContent = newContent:gsub("\\\\", "\\")
-
-	local instance = getInstanceByPath(instancePath)
-	if not instance then
-		return { error = "Instance not found: " .. instancePath }
-	end
-
-	if not instance:IsA("LuaSourceContainer") then
-		return { error = "Instance is not a script-like object: " .. instance.ClassName }
-	end
-
-	local success, result = pcall(function()
-		local lines, hadTrailingNewline = splitLines(instance.Source)
-		local totalLines = #lines
-
-		if startLine < 1 or startLine > totalLines then
-			error("startLine out of range (1-" .. totalLines .. ")")
-		end
-		if endLine < startLine or endLine > totalLines then
-			error("endLine out of range (" .. startLine .. "-" .. totalLines .. ")")
-		end
-
-		-- Split new content into lines
-		local newLines = select(1, splitLines(newContent))
-
-		-- Build new source: lines before + new content + lines after
-		local resultLines = {}
-
-		-- Lines before the edit
-		for i = 1, startLine - 1 do
-			table.insert(resultLines, lines[i])
-		end
-
-		-- New content lines
-		for _, line in ipairs(newLines) do
-			table.insert(resultLines, line)
-		end
-
-		-- Lines after the edit
-		for i = endLine + 1, totalLines do
-			table.insert(resultLines, lines[i])
-		end
-
-		local newSource = joinLines(resultLines, hadTrailingNewline)
-
-		-- Use UpdateSourceAsync for editor compatibility
-		ScriptEditorService:UpdateSourceAsync(instance, function(oldContent)
-			return newSource
-		end)
-
-		ChangeHistoryService:SetWaypoint("Edit script lines " .. startLine .. "-" .. endLine .. ": " .. instance.Name)
-
-		return {
-			success = true,
-			instancePath = instancePath,
-			editedLines = { startLine = startLine, endLine = endLine },
-			linesRemoved = endLine - startLine + 1,
-			linesAdded = #newLines,
-			newLineCount = #resultLines,
-			message = "Script lines edited successfully"
-		}
-	end)
-
-	if success then
-		return result
-	else
-		return { error = "Failed to edit script lines: " .. tostring(result) }
-	end
-end
-
--- Partial Script Editing: Insert lines after a specific line
-handlers.insertScriptLines = function(requestData)
-	local instancePath = requestData.instancePath
-	local afterLine = requestData.afterLine or 0 -- 0 means insert at beginning
-	local newContent = requestData.newContent
-
-	if not instancePath or not newContent then
-		return { error = "Instance path and newContent are required" }
-	end
-
-	-- Normalize escape sequences that may have been double-escaped
-	newContent = newContent:gsub("\\n", "\n")
-	newContent = newContent:gsub("\\t", "\t")
-	newContent = newContent:gsub("\\r", "\r")
-	newContent = newContent:gsub("\\\\", "\\")
-
-	local instance = getInstanceByPath(instancePath)
-	if not instance then
-		return { error = "Instance not found: " .. instancePath }
-	end
-
-	if not instance:IsA("LuaSourceContainer") then
-		return { error = "Instance is not a script-like object: " .. instance.ClassName }
-	end
-
-	local success, result = pcall(function()
-		local lines, hadTrailingNewline = splitLines(instance.Source)
-		local totalLines = #lines
-
-		if afterLine < 0 or afterLine > totalLines then
-			error("afterLine out of range (0-" .. totalLines .. ")")
-		end
-
-		-- Split new content into lines
-		local newLines = select(1, splitLines(newContent))
-
-		-- Build new source
-		local resultLines = {}
-
-		-- Lines before insertion point
-		for i = 1, afterLine do
-			table.insert(resultLines, lines[i])
-		end
-
-		-- New content lines
-		for _, line in ipairs(newLines) do
-			table.insert(resultLines, line)
-		end
-
-		-- Lines after insertion point
-		for i = afterLine + 1, totalLines do
-			table.insert(resultLines, lines[i])
-		end
-
-		local newSource = joinLines(resultLines, hadTrailingNewline)
-
-		-- Use UpdateSourceAsync for editor compatibility
-		ScriptEditorService:UpdateSourceAsync(instance, function(oldContent)
-			return newSource
-		end)
-
-		ChangeHistoryService:SetWaypoint("Insert script lines after line " .. afterLine .. ": " .. instance.Name)
-
-		return {
-			success = true,
-			instancePath = instancePath,
-			insertedAfterLine = afterLine,
-			linesInserted = #newLines,
-			newLineCount = #resultLines,
-			message = "Script lines inserted successfully"
-		}
-	end)
-
-	if success then
-		return result
-	else
-		return { error = "Failed to insert script lines: " .. tostring(result) }
-	end
-end
-
--- Partial Script Editing: Delete specific lines
-handlers.deleteScriptLines = function(requestData)
-	local instancePath = requestData.instancePath
-	local startLine = requestData.startLine
-	local endLine = requestData.endLine
-
-	if not instancePath or not startLine or not endLine then
-		return { error = "Instance path, startLine, and endLine are required" }
-	end
-
-	local instance = getInstanceByPath(instancePath)
-	if not instance then
-		return { error = "Instance not found: " .. instancePath }
-	end
-
-	if not instance:IsA("LuaSourceContainer") then
-		return { error = "Instance is not a script-like object: " .. instance.ClassName }
-	end
-
-	local success, result = pcall(function()
-		local lines, hadTrailingNewline = splitLines(instance.Source)
-		local totalLines = #lines
-
-		if startLine < 1 or startLine > totalLines then
-			error("startLine out of range (1-" .. totalLines .. ")")
-		end
-		if endLine < startLine or endLine > totalLines then
-			error("endLine out of range (" .. startLine .. "-" .. totalLines .. ")")
-		end
-
-		-- Build new source without the deleted lines
-		local resultLines = {}
-
-		for i = 1, startLine - 1 do
-			table.insert(resultLines, lines[i])
-		end
-
-		for i = endLine + 1, totalLines do
-			table.insert(resultLines, lines[i])
-		end
-
-		local newSource = joinLines(resultLines, hadTrailingNewline)
-
-		-- Use UpdateSourceAsync for editor compatibility
-		ScriptEditorService:UpdateSourceAsync(instance, function(oldContent)
-			return newSource
-		end)
-
-		ChangeHistoryService:SetWaypoint("Delete script lines " .. startLine .. "-" .. endLine .. ": " .. instance.Name)
-
-		return {
-			success = true,
-			instancePath = instancePath,
-			deletedLines = { startLine = startLine, endLine = endLine },
-			linesDeleted = endLine - startLine + 1,
-			newLineCount = #resultLines,
-			message = "Script lines deleted successfully"
-		}
-	end)
-
-	if success then
-		return result
-	else
-		return { error = "Failed to delete script lines: " .. tostring(result) }
-	end
-end
-
 -- ============================================
 -- CLAUDE CODE-STYLE SCRIPT EDITING TOOLS
+--
+-- The legacy line-based partial editors (editScriptLines /
+-- insertScriptLines / deleteScriptLines) were removed. They've been
+-- superseded by handlers.editScript below: string-based edits don't
+-- suffer from line-number drift after each modification, and the
+-- companion validation step rejects edits that break syntax.
 -- ============================================
 
 -- Helper: Count occurrences of a substring
@@ -3166,12 +3979,20 @@ handlers.editScript = function(requestData)
 			end
 		end
 
-		-- Apply the change
-		ScriptEditorService:UpdateSourceAsync(instance, function(oldContent)
-			return newSource
-		end)
-
-		ChangeHistoryService:SetWaypoint("Edit script: " .. instance.Name)
+		-- Apply via direct property assignment. NOTE: this does NOT produce
+		-- a ChangeHistoryService waypoint (Studio's script editor maintains
+		-- its own undo stack disjoint from CHS) — so undo support for this
+		-- edit comes from the pre/post-source SNAPSHOT we attach to the
+		-- tracked action entry below. The processRequest wrapper sees
+		-- `_isSourceEditOnly = true` in our return value and Cancels the
+		-- (empty) CHS recording.
+		--
+		-- We do NOT use ScriptEditorService:UpdateSourceAsync — same
+		-- reason (and it has the same CHS limitation), with the added
+		-- downside of being yield-only and harder to reason about.
+		-- (Caveat: unsaved buffer edits in Studio's script editor will be
+		-- replaced — same trade-off as set_script_source.)
+		instance.Source = newSource
 
 		-- Prepare summary for logging
 		local shortOld = #searchStr > 30 and (string.sub(searchStr, 1, 30) .. "...") or searchStr
@@ -3187,17 +4008,37 @@ handlers.editScript = function(requestData)
 			message = replaceAll
 				and ("Replaced " .. occurrences .. " occurrence(s) successfully")
 				or "Edit applied successfully",
-			_logSummary = shortOld:gsub("\n", "\\n") .. " → " .. shortNew:gsub("\n", "\\n")
+			_logSummary = shortOld:gsub("\n", "\\n") .. " → " .. shortNew:gsub("\n", "\\n"),
+			_preSource = source,
+			_postSource = newSource,
 		}
 	end)
 
 	if success then
 		if result.success then
-			-- Log for undo tracking
-			logAction("edit_script", instancePath, result._logSummary or "Script edited", {
-				replacements = result.replacements
-			})
-			result._logSummary = nil  -- Remove internal field
+			-- Log for undo tracking. The pre/post-source snapshots live in
+			-- details.scriptEdits — undo restores from preSource, redo from
+			-- postSource.
+			logAction(
+				"edit_script",
+				instancePath,
+				result._logSummary or "Script edited",
+				{
+					replacements = result.replacements,
+					scriptEdits = {
+						{
+							instancePath = instancePath,
+							preSource = result._preSource,
+							postSource = result._postSource,
+						},
+					},
+				}
+			)
+			result._logSummary = nil
+			result._preSource = nil
+			result._postSource = nil
+			-- Source-only change: Cancel CHS recording, keep tracked log.
+			result._isSourceEditOnly = true
 		end
 		return result
 	else
@@ -3276,6 +4117,217 @@ handlers.searchScript = function(requestData)
 	end
 end
 
+-- grep: Claude Code-style search across the instance tree.
+--
+-- Walks descendants of `path`, pre-filters by `type` (IsA) and `glob`
+-- (Lua pattern over Name), then scans script Source for `pattern` (either
+-- line-by-line or whole-source if `multiline`). Three output modes mirror
+-- `grep -l` / `grep` / `grep -c`.
+--
+-- Request shape:
+--   { pattern, path, glob?, type? (array), caseInsensitive?, after?, before?,
+--     context?, outputMode? ("files_with_matches"|"content"|"count"),
+--     headLimit?, multiline? }
+--
+-- Response shapes:
+--   files_with_matches: { mode, pattern, scanned, matches = [{path, className, name}] }
+--   content:            { mode, pattern, scanned, matches = [{path, className, name,
+--                          lines = [{lineNumber, content, context = [{lineNumber, content, type}]}]}],
+--                          totalMatches }
+--   count:              { mode, pattern, scanned, matches = [{path, className, name, count}], totalMatches }
+handlers.grep = function(requestData)
+	local pattern = requestData.pattern
+	if type(pattern) ~= "string" or #pattern == 0 then
+		return { error = "pattern is required (use \".*\" for name-only searches)" }
+	end
+
+	local rootPath = requestData.path
+	if type(rootPath) ~= "string" or #rootPath == 0 then
+		rootPath = "game"
+	end
+
+	local glob = requestData.glob
+	if type(glob) ~= "string" or #glob == 0 then glob = nil end
+
+	local typeFilter = requestData.type
+	if typeof(typeFilter) ~= "table" or #typeFilter == 0 then
+		typeFilter = { "LuaSourceContainer" }
+	end
+
+	local caseInsensitive = requestData.caseInsensitive == true
+	local outputMode = requestData.outputMode or "files_with_matches"
+	if outputMode ~= "files_with_matches" and outputMode ~= "content" and outputMode ~= "count" then
+		return { error = "outputMode must be one of: files_with_matches, content, count" }
+	end
+
+	local contextAround = tonumber(requestData.context) or 0
+	local contextAfter = tonumber(requestData.after) or 0
+	local contextBefore = tonumber(requestData.before) or 0
+	if contextAround > 0 then
+		-- -C overrides -A/-B, matching grep semantics
+		contextAfter = contextAround
+		contextBefore = contextAround
+	end
+
+	local headLimit = tonumber(requestData.headLimit) or 0
+	local multiline = requestData.multiline == true
+
+	-- Resolve the root instance.
+	local rootInstance
+	if rootPath == "game" or rootPath == "" then
+		rootInstance = game
+	else
+		rootInstance = getInstanceByPath(rootPath)
+		if not rootInstance then
+			return { error = "Path not found: " .. rootPath }
+		end
+	end
+
+	-- Helper: case-insensitive find/match by lowercasing both inputs. We
+	-- can't use a "(?i)" prefix in Lua patterns, so this is the standard
+	-- workaround. We keep the original case of the matched line in the
+	-- output for readability.
+	local function caseFold(s)
+		if caseInsensitive then return string.lower(s) else return s end
+	end
+
+	local patternFolded = caseFold(pattern)
+	local globFolded = glob and caseFold(glob) or nil
+
+	-- Walk descendants and apply filters.
+	local descendants = rootInstance:GetDescendants()
+	-- Include the root itself so e.g. grep on a specific Script path works.
+	table.insert(descendants, 1, rootInstance)
+
+	local scanned = 0
+	local matches = {}
+	local totalMatches = 0
+	local hitLimit = false
+
+	for _, inst in ipairs(descendants) do
+		-- Type filter: pass if `inst:IsA(name)` for ANY name in typeFilter.
+		local typeOk = false
+		for _, t in ipairs(typeFilter) do
+			local ok, isA = pcall(function() return inst:IsA(t) end)
+			if ok and isA then
+				typeOk = true
+				break
+			end
+		end
+		if not typeOk then continue end
+
+		-- Glob filter: Lua-pattern match against Name.
+		if globFolded then
+			local nameFolded = caseFold(inst.Name)
+			if not string.find(nameFolded, globFolded) then
+				continue
+			end
+		end
+
+		scanned += 1
+
+		-- Read Source only if applicable. Non-script instances that pass
+		-- the filters are reported as name-only hits (no line content).
+		local isScript = inst:IsA("LuaSourceContainer")
+		local sourceOk, source = false, ""
+		if isScript then
+			sourceOk, source = pcall(function() return inst.Source end)
+			if not sourceOk then source = "" end
+		end
+
+		-- Apply the content pattern.
+		local instMatchCount = 0
+		local lineHits = nil  -- only populated in "content" mode
+
+		if isScript and #source > 0 then
+			if multiline then
+				-- Whole-source match; report a single virtual line (line 1)
+				-- containing the start of the match for simplicity.
+				local hay = caseFold(source)
+				local s, e = string.find(hay, patternFolded)
+				if s then
+					instMatchCount = 1
+					if outputMode == "content" then
+						-- For multiline mode, return the matched substring
+						-- as the "line" content (truncated to keep payload sane).
+						local snippet = string.sub(source, s, math.min(e, s + 500))
+						lineHits = { { lineNumber = 1, content = snippet, context = {} } }
+					end
+				end
+			else
+				local lines, _ = splitLines(source)
+				for lineNum, line in ipairs(lines) do
+					local hay = caseFold(line)
+					if string.find(hay, patternFolded) then
+						instMatchCount += 1
+						if outputMode == "content" then
+							if not lineHits then lineHits = {} end
+							local hit = {
+								lineNumber = lineNum,
+								content = line,
+								context = {},
+							}
+							if contextBefore > 0 then
+								for i = math.max(1, lineNum - contextBefore), lineNum - 1 do
+									table.insert(hit.context, { lineNumber = i, content = lines[i], type = "before" })
+								end
+							end
+							if contextAfter > 0 then
+								for i = lineNum + 1, math.min(#lines, lineNum + contextAfter) do
+									table.insert(hit.context, { lineNumber = i, content = lines[i], type = "after" })
+								end
+							end
+							table.insert(lineHits, hit)
+						end
+					end
+				end
+			end
+		end
+
+		-- Decide whether this instance counts as a "hit".
+		-- For non-script instances that passed name/class filters, we treat
+		-- them as a name-only hit so callers can use grep as a unified search.
+		local isHit = (instMatchCount > 0) or (not isScript)
+		if not isHit then continue end
+
+		totalMatches += instMatchCount
+
+		local entry = {
+			path = getInstancePath(inst),
+			className = inst.ClassName,
+			name = inst.Name,
+		}
+		if outputMode == "content" then
+			entry.lines = lineHits or {}
+		elseif outputMode == "count" then
+			entry.count = instMatchCount
+		end
+		table.insert(matches, entry)
+
+		if headLimit > 0 and #matches >= headLimit then
+			hitLimit = true
+			break
+		end
+	end
+
+	local response = {
+		mode = outputMode,
+		pattern = pattern,
+		path = rootPath,
+		scanned = scanned,
+		matchCount = #matches,
+		matches = matches,
+	}
+	if outputMode ~= "files_with_matches" then
+		response.totalMatches = totalMatches
+	end
+	if hitLimit then
+		response.truncated = true
+		response.note = string.format("Output truncated at head_limit=%d. Increase head_limit or narrow with `glob`/`path`/`type`.", headLimit)
+	end
+	return response
+end
+
 -- get_script_function: Extract a specific function by name
 handlers.getScriptFunction = function(requestData)
 	local instancePath = requestData.instancePath
@@ -3429,6 +4481,10 @@ handlers.findAndReplaceInScripts = function(requestData)
 	local successCount = 0
 	local failCount = 0
 	local skippedCount = 0
+	-- Per-script pre/post-source snapshots. Used by the undo handler to
+	-- revert source-only edits (direct Source = is invisible to CHS — see
+	-- edit_script for the full explanation).
+	local scriptEdits = {}
 
 	for _, path in ipairs(paths) do
 		local instance = getInstanceByPath(path)
@@ -3451,31 +4507,82 @@ handlers.findAndReplaceInScripts = function(requestData)
 			else
 				local newSource = string.gsub(source, searchStr:gsub("([^%w])", "%%%1"), replaceStr)
 
+				-- Direct property assignment. Captured into scriptEdits so
+				-- the undo handler can revert it (CHS doesn't see Source
+				-- changes — see edit_script for the full rationale).
 				if validateAfter then
 					local isValid, syntaxErrors = validateLuaSyntax(newSource)
 					if not isValid then
 						table.insert(results, { path = path, success = false, error = "Would create invalid syntax", syntaxErrors = syntaxErrors })
 						failCount = failCount + 1
 					else
-						pcall(function()
-							ScriptEditorService:UpdateSourceAsync(instance, function() return newSource end)
+						local assignOk, assignErr = pcall(function()
+							instance.Source = newSource
 						end)
-						table.insert(results, { path = path, success = true, replacements = occurrences })
-						successCount = successCount + 1
+						if assignOk then
+							table.insert(results, { path = path, success = true, replacements = occurrences })
+							table.insert(scriptEdits, {
+								instancePath = path,
+								preSource = source,
+								postSource = newSource,
+							})
+							successCount = successCount + 1
+						else
+							table.insert(results, { path = path, success = false, error = "Source assignment failed: " .. tostring(assignErr) })
+							failCount = failCount + 1
+						end
 					end
 				else
-					pcall(function()
-						ScriptEditorService:UpdateSourceAsync(instance, function() return newSource end)
+					local assignOk, assignErr = pcall(function()
+						instance.Source = newSource
 					end)
-					table.insert(results, { path = path, success = true, replacements = occurrences })
-					successCount = successCount + 1
+					if assignOk then
+						table.insert(results, { path = path, success = true, replacements = occurrences })
+						table.insert(scriptEdits, {
+							instancePath = path,
+							preSource = source,
+							postSource = newSource,
+						})
+						successCount = successCount + 1
+					else
+						table.insert(results, { path = path, success = false, error = "Source assignment failed: " .. tostring(assignErr) })
+						failCount = failCount + 1
+					end
 				end
 			end
 		end
 	end
 
+	-- Source edits aren't captured by ChangeHistoryService (see edit_script
+	-- comment). The pre/post-source snapshots stored in details.scriptEdits
+	-- are what the undo handler uses to revert. processRequest sees
+	-- `_isSourceEditOnly = true` and Cancels the empty CHS recording.
+
+	-- Log to MCP action history for get_history visibility (only when at
+	-- least one script was actually modified)
 	if successCount > 0 then
-		ChangeHistoryService:SetWaypoint("Batch replace in " .. successCount .. " scripts")
+		local searchPreview = oldString
+		if #searchPreview > 30 then
+			searchPreview = string.sub(searchPreview, 1, 30) .. "..."
+		end
+		local replacePreview = newString
+		if #replacePreview > 30 then
+			replacePreview = string.sub(replacePreview, 1, 30) .. "..."
+		end
+		searchPreview = searchPreview:gsub("\n", "\\n")
+		replacePreview = replacePreview:gsub("\n", "\\n")
+		logAction(
+			"find_and_replace_in_scripts",
+			tostring(successCount) .. " scripts",
+			searchPreview .. " → " .. replacePreview,
+			{
+				total = #paths,
+				successful = successCount,
+				failed = failCount,
+				skipped = skippedCount,
+				scriptEdits = scriptEdits,
+			}
+		)
 	end
 
 	return {
@@ -3486,7 +4593,13 @@ handlers.findAndReplaceInScripts = function(requestData)
 			successful = successCount,
 			failed = failCount,
 			skipped = skippedCount
-		}
+		},
+		-- Source-only edits: Cancel CHS (it doesn't see Source changes
+		-- anyway), keep tracked log so undo can restore from snapshots.
+		-- If nothing actually changed, fall back to _didNotMutate so the
+		-- log entry doesn't get committed either.
+		_isSourceEditOnly = (successCount > 0),
+		_didNotMutate = (successCount == 0),
 	}
 end
 
@@ -4169,28 +5282,116 @@ end
 -- UNDO/REDO HANDLERS (Enhanced with action tracking)
 -- ============================================
 
+-- Build a compact summary string for an action entry (used in `undone` /
+-- `redone` and in the `entries` array). Falls back gracefully when the entry
+-- came from outside MCP (action == nil).
+local function formatActionEntry(entry)
+	if not entry then
+		return "Unknown action (possibly manual change)"
+	end
+	return entry.action .. " → " .. entry.target .. " (" .. entry.summary .. ")"
+end
+
+-- Helper: does this tracked entry represent a pure script-source edit?
+-- Pure script edits don't produce CHS waypoints (Studio's script editor has
+-- its own undo stack disjoint from CHS), so the entry will have an
+-- attached scriptEdits snapshot list AND no other tree/property mutation.
+-- For these we restore source manually and DO NOT call CHS:Undo() — that
+-- would skip past the next real waypoint and revert something unrelated.
+local function entryIsSourceOnly(entry)
+	if not entry or not entry.details or not entry.details.scriptEdits then
+		return false
+	end
+	return #entry.details.scriptEdits > 0
+end
+
+-- Restore each script's pre-edit source. Tolerates instances that have
+-- been re-parented or destroyed since the edit (skips with a warning so
+-- one missing script doesn't poison the whole undo).
+local function restoreScriptEdits(scriptEdits, useField)
+	for _, edit in ipairs(scriptEdits) do
+		local instance = getInstanceByPath(edit.instancePath)
+		if instance and instance:IsA("LuaSourceContainer") then
+			pcall(function()
+				instance.Source = edit[useField]
+			end)
+		end
+	end
+end
+
+-- Stepwise undo. Calls ChangeHistoryService:Undo() up to `count` times,
+-- popping one entry off actionHistory per step (matched into redoHistory).
+-- Studio's undo stack is the source of truth — we stop early if it runs out.
+-- `count` defaults to 1; agents pass higher values to roll back several
+-- recent operations in one call without N round-trips.
+--
+-- Special case: pure script-source edits (edit_script, find_and_replace,
+-- set_script_source via direct assignment) don't create CHS waypoints, so
+-- we restore from the snapshot in details.scriptEdits and SKIP CHS:Undo().
 handlers.undo = function(requestData)
+	local count = tonumber(requestData and requestData.count) or 1
+	if count < 1 then count = 1 end
+	if count > 100 then count = 100 end  -- safety clamp
+
 	local success, result = pcall(function()
-		-- Pop the last action from history
-		local lastAction = nil
-		if #actionHistory > 0 then
-			lastAction = table.remove(actionHistory)
-			-- Move it to redo history
-			table.insert(redoHistory, lastAction)
-		end
+		local entries = {}    -- actions actually undone, in undo order
+		local stoppedReason = nil
+
+		for i = 1, count do
+			-- Peek at the next tracked entry. If it's a pure source edit
+			-- we MUST handle it without calling CHS:Undo() (CHS has no
+			-- corresponding waypoint, so :Undo() would revert the wrong
+			-- thing).
+			local top = actionHistory[#actionHistory]
+			if entryIsSourceOnly(top) then
+				local entry = table.remove(actionHistory)
+				restoreScriptEdits(entry.details.scriptEdits, "preSource")
+				table.insert(redoHistory, entry)
+				table.insert(entries, entry)
+			else
+				-- Tree/property mutation (or unknown out-of-band waypoint):
+				-- defer to Studio's undo stack.
+				local canUndo = ChangeHistoryService:GetCanUndo()
+				if not canUndo then
+					stoppedReason = "no_more_studio_undo"
+					break
+				end
 
-		ChangeHistoryService:Undo()
+				local entry = nil
+				if #actionHistory > 0 then
+					entry = table.remove(actionHistory)
+					table.insert(redoHistory, entry)
+				end
 
+				ChangeHistoryService:Undo()
+				table.insert(entries, entry)  -- may be nil for out-of-band waypoints
+			end
+		end
+
+		local primary = entries[1]
 		return {
 			success = true,
-			undone = lastAction and (lastAction.action .. " → " .. lastAction.target .. " (" .. lastAction.summary .. ")") or "Unknown action (possibly manual change)",
-			action = lastAction and lastAction.action or nil,
-			target = lastAction and lastAction.target or nil,
-			summary = lastAction and lastAction.summary or nil,
-			details = lastAction and lastAction.details or nil,
+			undone_count = #entries,
+			requested_count = count,
+			-- Top-level fields describe the FIRST entry undone (for
+			-- backward compatibility with callers expecting one undo).
+			undone = formatActionEntry(primary),
+			action = primary and primary.action or nil,
+			target = primary and primary.target or nil,
+			summary = primary and primary.summary or nil,
+			details = primary and primary.details or nil,
+			-- Full ordered list of entries undone this call.
+			entries = entries,
 			remaining_undos = #actionHistory,
 			available_redos = #redoHistory,
-			message = lastAction and ("Undone: " .. lastAction.summary) or "Undo executed"
+			stopped_early = stoppedReason ~= nil,
+			stopped_reason = stoppedReason,
+			message = string.format(
+				"Undone %d/%d action(s)%s",
+				#entries,
+				count,
+				stoppedReason and (" (stopped: " .. stoppedReason .. ")") or ""
+			),
 		}
 	end)
 
@@ -4201,33 +5402,68 @@ handlers.undo = function(requestData)
 			success = false,
 			error = "Failed to undo: " .. tostring(result),
 			remaining_undos = #actionHistory,
-			available_redos = #redoHistory
+			available_redos = #redoHistory,
 		}
 	end
 end
 
 handlers.redo = function(requestData)
+	local count = tonumber(requestData and requestData.count) or 1
+	if count < 1 then count = 1 end
+	if count > 100 then count = 100 end
+
 	local success, result = pcall(function()
-		-- Pop the last undone action from redo history
-		local redoneAction = nil
-		if #redoHistory > 0 then
-			redoneAction = table.remove(redoHistory)
-			-- Move it back to action history
-			table.insert(actionHistory, redoneAction)
-		end
+		local entries = {}
+		local stoppedReason = nil
+
+		for i = 1, count do
+			-- Mirror of undo: pure source edits redo by re-applying the
+			-- postSource snapshot and SKIP CHS:Redo() (no waypoint to redo).
+			local top = redoHistory[#redoHistory]
+			if entryIsSourceOnly(top) then
+				local entry = table.remove(redoHistory)
+				restoreScriptEdits(entry.details.scriptEdits, "postSource")
+				table.insert(actionHistory, entry)
+				table.insert(entries, entry)
+			else
+				local canRedo = ChangeHistoryService:GetCanRedo()
+				if not canRedo then
+					stoppedReason = "no_more_studio_redo"
+					break
+				end
+
+				local entry = nil
+				if #redoHistory > 0 then
+					entry = table.remove(redoHistory)
+					table.insert(actionHistory, entry)
+				end
 
-		ChangeHistoryService:Redo()
+				ChangeHistoryService:Redo()
+				table.insert(entries, entry)
+			end
+		end
 
+		local primary = entries[1]
 		return {
 			success = true,
-			redone = redoneAction and (redoneAction.action .. " → " .. redoneAction.target .. " (" .. redoneAction.summary .. ")") or "Unknown action",
-			action = redoneAction and redoneAction.action or nil,
-			target = redoneAction and redoneAction.target or nil,
-			summary = redoneAction and redoneAction.summary or nil,
-			details = redoneAction and redoneAction.details or nil,
+			redone_count = #entries,
+			requested_count = count,
+			redone = formatActionEntry(primary),
+			action = primary and primary.action or nil,
+			target = primary and primary.target or nil,
+			summary = primary and primary.summary or nil,
+			details = primary and primary.details or nil,
+			entries = entries,
 			remaining_undos = #actionHistory,
 			available_redos = #redoHistory,
-			message = redoneAction and ("Redone: " .. redoneAction.summary) or "Redo executed"
+			stopped_early = stoppedReason ~= nil,
+			stopped_reason = stoppedReason,
+			message = string.format(
+				"Redone %d/%d action(s)%s",
+				#entries,
+				count,
+				stoppedReason and (" (stopped: " .. stoppedReason .. ")") or ""
+			),
 		}
 	end)
 
@@ -4238,11 +5474,68 @@ handlers.redo = function(requestData)
 			success = false,
 			error = "Failed to redo: " .. tostring(result),
 			remaining_undos = #actionHistory,
-			available_redos = #redoHistory
+			available_redos = #redoHistory,
 		}
 	end
 end
 
+-- ============================================
+-- HISTORY INTROSPECTION
+-- ============================================
+
+-- Read-only view of the recent action history + Studio's authoritative
+-- can_undo/can_redo flags. Useful for agents that want to peek before calling
+-- undo/redo (e.g. "what am I about to undo?") or to recover state after a
+-- session resume.
+handlers.getHistory = function(requestData)
+	local limit = tonumber(requestData and requestData.limit) or 20
+	if limit < 1 then limit = 1 end
+	if limit > MAX_ACTION_HISTORY then limit = MAX_ACTION_HISTORY end
+	local includeDetails = requestData and requestData.includeDetails == true
+
+	local now = os.time()
+
+	-- Slice the top `limit` entries of each stack. Index 0 = the one that
+	-- would be popped next (top of stack); larger indices reach further back.
+	local function sliceStack(stack)
+		local out = {}
+		local n = #stack
+		local take = math.min(limit, n)
+		for i = 0, take - 1 do
+			local entry = stack[n - i]
+			if entry then
+				local sliced = {
+					index = i,
+					action = entry.action,
+					target = entry.target,
+					summary = entry.summary,
+					timestamp = entry.timestamp,
+					age_seconds = now - (entry.timestamp or now),
+				}
+				if includeDetails then
+					sliced.details = entry.details
+				end
+				table.insert(out, sliced)
+			end
+		end
+		return out
+	end
+
+	local canUndo = ChangeHistoryService:GetCanUndo()
+	local canRedo = ChangeHistoryService:GetCanRedo()
+
+	return {
+		success = true,
+		can_undo = canUndo,
+		can_redo = canRedo,
+		tracked_undo_count = #actionHistory,
+		tracked_redo_count = #redoHistory,
+		max_history = MAX_ACTION_HISTORY,
+		undo_stack = sliceStack(actionHistory),
+		redo_stack = sliceStack(redoHistory),
+	}
+end
+
 -- ============================================
 -- EXECUTE LUA HANDLER (Run arbitrary Lua code)
 -- ============================================
@@ -4453,11 +5746,31 @@ handlers.executeLua = function(requestData)
 		end
 	end
 
+	-- Log to MCP action history for get_history visibility. We can't know
+	-- whether arbitrary user code actually mutated the DataModel, so we
+	-- tag the result with `_mutatesUnknown=true` — processRequest uses
+	-- this sentinel to be conservative: if CHS state didn't visibly
+	-- advance (no canUndo flip, no canRedo clear), the pending log gets
+	-- DISCARDED instead of polluting actionHistory with a phantom entry.
+	local codeLines = 1
+	for _ in string.gmatch(code, "\n") do
+		codeLines = codeLines + 1
+	end
+	local codePreview = code:gsub("^%s+", ""):gsub("\n.*$", "")
+	if #codePreview > 60 then
+		codePreview = string.sub(codePreview, 1, 60) .. "..."
+	end
+	logAction("execute_lua", "<inline>", codePreview, {
+		code_length = #code,
+		line_count = codeLines,
+	})
+
 	return {
 		success = true,
 		result = serializeResult(execResult),
 		resultType = typeof(execResult),
-		message = "Code executed successfully"
+		message = "Code executed successfully",
+		_mutatesUnknown = true,  -- stripped by processRequest
 	}
 end
 
@@ -4609,7 +5922,7 @@ handlers.playSolo = function(requestData)
 	cleanupTestCompanions()
 
 	local success, result = pcall(function()
-		local companion = injectTestCompanion(pluginState.serverUrl, sessionId)
+		local serverCompanion, clientCompanion = injectTestCompanion(pluginState.serverUrl, sessionId)
 
 		-- ExecutePlayModeAsync yields until the test ends. Run it on its
 		-- own thread so the HTTP response for play_solo returns now,
@@ -4646,8 +5959,9 @@ handlers.playSolo = function(requestData)
 			success = true,
 			sessionId = sessionId,
 			method = "StudioTestService:ExecutePlayModeAsync",
-			companionPath = getInstancePath(companion),
-			message = "Started Play Solo with MCP companion. Use stop_play to end, get_playtest_output to read logs.",
+			companionPath = getInstancePath(serverCompanion),
+			clientCompanionPath = clientCompanion and getInstancePath(clientCompanion) or nil,
+			message = "Started Play Solo with MCP server + client companions. Use stop_play to end, get_playtest_output to read logs, run_live_lua to execute code in the running test.",
 		}
 	end)
 
@@ -5375,6 +6689,366 @@ handlers.renderObjectView = function(requestData)
 	end
 end
 
+-- ============================================
+-- GUI RENDERING SYSTEM
+-- ============================================
+
+-- render_gui: capture a 2D GUI to an image. ViewportFrame is 3D-only, so we
+-- clone the GUI into an off-screen ScreenGui in CoreGui, take a full-screen
+-- CaptureService screenshot, then crop.
+--
+-- region:
+--   "element" (default) → crop tight to the target's on-screen rect.
+--   "screen"            → return the whole viewport, so you can verify where
+--                         the element actually lands relative to the screen.
+--
+-- Placement is faithful: when the target lives under a ScreenGui we clone the
+-- WHOLE ScreenGui (preserving siblings, layout, and GUI inset) and locate the
+-- cloned target by its child-index path, instead of reparenting the element to
+-- (0,0). StarterGui elements report AbsolutePosition = 0 until rendered in their
+-- real context, so this is what makes screen-mode placement accurate.
+handlers.renderGui = function(requestData)
+	local CaptureService = game:GetService("CaptureService")
+	local AssetService = game:GetService("AssetService")
+	local CoreGui = game:GetService("CoreGui")
+
+	-- Walk up to the nearest ScreenGui ancestor (2D overlay LayerCollector).
+	local function findAncestorScreenGui(inst)
+		local node = inst.Parent
+		while node do
+			if node:IsA("ScreenGui") then
+				return node
+			end
+			node = node.Parent
+		end
+		return nil
+	end
+
+	-- Child-index path from ancestor down to descendant (1-based GetChildren idx).
+	local function indexPath(ancestor, descendant)
+		local path = {}
+		local node = descendant
+		while node and node ~= ancestor do
+			local parent = node.Parent
+			if not parent then
+				return nil
+			end
+			local idx = nil
+			local siblings = parent:GetChildren()
+			for i = 1, #siblings do
+				if siblings[i] == node then
+					idx = i
+					break
+				end
+			end
+			if not idx then
+				return nil
+			end
+			table.insert(path, 1, idx)
+			node = parent
+		end
+		if node ~= ancestor then
+			return nil
+		end
+		return path
+	end
+
+	-- Follow a child-index path from root (clone order matches the original).
+	local function followPath(root, path)
+		local node = root
+		for _, idx in ipairs(path) do
+			local children = node:GetChildren()
+			node = children[idx]
+			if not node then
+				return nil
+			end
+		end
+		return node
+	end
+
+	local success, result = pcall(function()
+		-- ──────────── parse params ────────────
+		local instancePath = requestData.instancePath
+		if not instancePath then
+			return { success = false, error = "instancePath is required" }
+		end
+
+		local maxWidth  = tonumber(requestData.maxWidth)
+		local maxHeight = tonumber(requestData.maxHeight)
+		local region = (requestData.region == "screen") and "screen" or "element"
+
+		-- ──────────── resolve target ────────────
+		local target = getInstanceByPath(instancePath)
+		if not target then
+			return { success = false, error = "Instance not found: " .. instancePath }
+		end
+
+		-- ──────────── build off-screen host ────────────
+		-- hostGui is whatever we parent into CoreGui; cropElements drive the
+		-- element-mode bounding box; placement records how we positioned things.
+		local hostGui
+		local cropElements = {}
+		local placement = "synthetic"
+
+		if target:IsA("GuiObject") then
+			local ancestorGui = findAncestorScreenGui(target)
+			local path = ancestorGui and indexPath(ancestorGui, target) or nil
+
+			if ancestorGui and path then
+				-- Faithful: clone the whole ScreenGui so siblings/layout/inset
+				-- are intact, then find the cloned target via its index path.
+				local clonedGui = ancestorGui:Clone()
+				clonedGui.Name = "MCPRenderGui"
+				clonedGui.Enabled = true
+				clonedGui.DisplayOrder = 2147483647
+				local clonedTarget = followPath(clonedGui, path)
+				if not clonedTarget then
+					clonedGui:Destroy()
+					return {
+						success = false,
+						error = "Failed to locate cloned target inside ScreenGui clone",
+					}
+				end
+				clonedTarget.Visible = true
+				hostGui = clonedGui
+				table.insert(cropElements, clonedTarget)
+				placement = "faithful"
+			else
+				-- No ScreenGui context (e.g. element parked in ReplicatedStorage):
+				-- drop a synthetic host and park the clone at the origin.
+				hostGui = Instance.new("ScreenGui")
+				hostGui.Name = "MCPRenderGui"
+				hostGui.IgnoreGuiInset = true
+				hostGui.ResetOnSpawn = false
+				hostGui.DisplayOrder = 2147483647
+				hostGui.ZIndexBehavior = Enum.ZIndexBehavior.Sibling
+
+				local cloned = target:Clone()
+				cloned.Visible = true
+				cloned.AnchorPoint = Vector2.new(0, 0)
+				cloned.Position = UDim2.fromOffset(0, 0)
+				cloned.Parent = hostGui
+				table.insert(cropElements, cloned)
+			end
+		elseif target:IsA("ScreenGui") then
+			-- Faithful: render the whole ScreenGui as it would appear.
+			hostGui = target:Clone()
+			hostGui.Name = "MCPRenderGui"
+			hostGui.Enabled = true
+			hostGui.DisplayOrder = 2147483647
+			placement = "faithful"
+			for _, child in ipairs(hostGui:GetChildren()) do
+				if child:IsA("GuiObject") then
+					child.Visible = true
+					table.insert(cropElements, child)
+				end
+			end
+			if #cropElements == 0 then
+				hostGui:Destroy()
+				return {
+					success = false,
+					error = "GUI has no GuiObject children to render: " .. instancePath,
+				}
+			end
+		elseif target:IsA("LayerCollector") then
+			-- SurfaceGui / BillboardGui render in 3D, not as a 2D overlay, so we
+			-- can't place them faithfully — copy their children into a synthetic
+			-- ScreenGui host instead.
+			hostGui = Instance.new("ScreenGui")
+			hostGui.Name = "MCPRenderGui"
+			hostGui.IgnoreGuiInset = true
+			hostGui.ResetOnSpawn = false
+			hostGui.DisplayOrder = 2147483647
+			hostGui.ZIndexBehavior = Enum.ZIndexBehavior.Sibling
+			for _, child in ipairs(target:GetChildren()) do
+				if child:IsA("GuiObject") then
+					local cloned = child:Clone()
+					cloned.Visible = true
+					cloned.Parent = hostGui
+					table.insert(cropElements, cloned)
+				end
+			end
+			if #cropElements == 0 then
+				hostGui:Destroy()
+				return {
+					success = false,
+					error = "GUI has no GuiObject children to render: " .. instancePath,
+				}
+			end
+		else
+			return {
+				success = false,
+				error = "render_gui target must be a GuiObject or a ScreenGui/SurfaceGui/BillboardGui, got "
+					.. target.ClassName,
+			}
+		end
+
+		hostGui.Parent = CoreGui
+
+		-- Let layout / AbsolutePosition settle.
+		RunService.Heartbeat:Wait()
+		RunService.Heartbeat:Wait()
+
+		-- ──────────── union bounding box (screen px) ────────────
+		local minX, minY = math.huge, math.huge
+		local maxX, maxY = -math.huge, -math.huge
+		for _, el in ipairs(cropElements) do
+			local pos = el.AbsolutePosition
+			local size = el.AbsoluteSize
+			minX = math.min(minX, pos.X)
+			minY = math.min(minY, pos.Y)
+			maxX = math.max(maxX, pos.X + size.X)
+			maxY = math.max(maxY, pos.Y + size.Y)
+		end
+
+		-- ──────────── capture ────────────
+		local captureComplete = Instance.new("BindableEvent")
+		local captureResult, captureError = nil, nil
+
+		local pcOk, pcErr = pcall(function()
+			CaptureService:CaptureScreenshot(function(contentId)
+				if contentId then
+					captureResult = contentId
+				else
+					captureError = "CaptureScreenshot returned nil"
+				end
+				captureComplete:Fire()
+			end)
+		end)
+
+		if not pcOk then
+			hostGui:Destroy()
+			return { success = false, error = "CaptureScreenshot threw: " .. tostring(pcErr) }
+		end
+
+		local timeoutThread = task.delay(8, function()
+			if not captureResult and not captureError then
+				captureError = "Capture timed out (8s)"
+				captureComplete:Fire()
+			end
+		end)
+		captureComplete.Event:Wait()
+		task.cancel(timeoutThread)
+		captureComplete:Destroy()
+
+		hostGui:Destroy()
+
+		if captureError then
+			return { success = false, error = "Failed to capture screen: " .. captureError }
+		end
+
+		-- ──────────── crop ────────────
+		local sourceImage = AssetService:CreateEditableImageAsync(Content.fromUri(tostring(captureResult)))
+		local sourceSize = sourceImage.Size
+
+		local cropX, cropY, cropW, cropH
+		if region == "screen" then
+			-- Whole viewport: keep the element in its real on-screen context.
+			cropX, cropY = 0, 0
+			cropW, cropH = sourceSize.X, sourceSize.Y
+		else
+			-- Tight crop to the element's on-screen rect.
+			local rx = math.max(math.floor(minX), 0)
+			local ry = math.max(math.floor(minY), 0)
+			local rw = math.max(math.ceil(maxX - rx), 1)
+			local rh = math.max(math.ceil(maxY - ry), 1)
+			cropX = math.clamp(rx, 0, math.max(sourceSize.X - 1, 0))
+			cropY = math.clamp(ry, 0, math.max(sourceSize.Y - 1, 0))
+			cropW = math.clamp(rw, 1, sourceSize.X - cropX)
+			cropH = math.clamp(rh, 1, sourceSize.Y - cropY)
+		end
+
+		local croppedImage = AssetService:CreateEditableImage({ Size = Vector2.new(cropW, cropH) })
+		croppedImage:DrawImageTransformed(
+			Vector2.new(cropW / 2, cropH / 2),
+			Vector2.new(1, 1),
+			0,
+			sourceImage,
+			{
+				CombineType = Enum.ImageCombineType.Overwrite,
+				PivotPoint = Vector2.new(cropX + cropW / 2, cropY + cropH / 2),
+			}
+		)
+		sourceImage:Destroy()
+
+		-- ──────────── downscale (aspect preserved, no upscale) ────────────
+		-- Two independent reasons to shrink, folded into ONE resize pass:
+		--   1. Caller's optional maxWidth/maxHeight clamp.
+		--   2. The HTTP-bridge raw-pixel cap (MAX_RAW_PIXEL_BYTES) — mirrors
+		--      captureScreenshot. region="screen" on a hi-DPI display can blow
+		--      past the cap, so this guard is what keeps the POST safe.
+		local scaleW = maxWidth and (maxWidth / cropW) or 1
+		local scaleH = maxHeight and (maxHeight / cropH) or 1
+		local scale = math.min(scaleW, scaleH, 1)
+		local outW = math.max(math.floor(cropW * scale), 1)
+		local outH = math.max(math.floor(cropH * scale), 1)
+
+		local autoShrunk = false
+		local requiredBytes = outW * outH * 4
+		if requiredBytes > MAX_RAW_PIXEL_BYTES then
+			local shrink = math.sqrt(MAX_RAW_PIXEL_BYTES / requiredBytes)
+			outW = math.max(math.floor(outW * shrink), 1)
+			outH = math.max(math.floor(outH * shrink), 1)
+			scale = scale * shrink
+			autoShrunk = true
+		end
+
+		local outputImage = croppedImage
+		if (outW ~= cropW) or (outH ~= cropH) then
+			outputImage = AssetService:CreateEditableImage({ Size = Vector2.new(outW, outH) })
+			outputImage:DrawImageTransformed(
+				Vector2.new(outW / 2, outH / 2),
+				Vector2.new(scale, scale),
+				0,
+				croppedImage,
+				{
+					CombineType = Enum.ImageCombineType.Overwrite,
+					PivotPoint = Vector2.new(cropW / 2, cropH / 2),
+				}
+			)
+			croppedImage:Destroy()
+		end
+
+		local rgbaBuffer = outputImage:ReadPixelsBuffer(Vector2.new(0, 0), outputImage.Size)
+		local rgbaString = buffer.tostring(rgbaBuffer)
+		local base64Data = base64encode(rgbaString)
+		outputImage:Destroy()
+
+		return {
+			success = true,
+			base64 = base64Data,
+			width = outW,
+			height = outH,
+			format = "RGBA",
+			encoding = "base64",
+			guiInfo = {
+				objectName       = target.Name,
+				objectClass      = target.ClassName,
+				renderedElements = #cropElements,
+				region           = region,
+				placement        = placement,
+				autoShrunk       = autoShrunk,
+				rect = { x = cropX, y = cropY, width = cropW, height = cropH },
+				sourceWidth  = sourceSize.X,
+				sourceHeight = sourceSize.Y,
+			},
+			message = string.format(
+				"Rendered GUI %s at %dx%d (region=%s, placement=%s, from %dx%d screen)",
+				target.Name, outW, outH, region, placement, sourceSize.X, sourceSize.Y
+			),
+		}
+	end)
+
+	if success then
+		return result
+	else
+		return {
+			success = false,
+			error = "Failed to render GUI: " .. tostring(result),
+		}
+	end
+end
+
 -- ============================================
 -- CAMERA CONTROL SYSTEM
 -- ============================================
@@ -5512,12 +7186,11 @@ endpointHandlers = {
 	["/api/set-relative-property"] = handlers.setRelativeProperty,
 	["/api/get-script-source"] = handlers.getScriptSource,
 	["/api/set-script-source"] = handlers.setScriptSource,
-	["/api/edit-script-lines"] = handlers.editScriptLines,
-	["/api/insert-script-lines"] = handlers.insertScriptLines,
-	["/api/delete-script-lines"] = handlers.deleteScriptLines,
 	-- Claude Code-style script editing tools
 	["/api/edit-script"] = handlers.editScript,
 	["/api/search-script"] = handlers.searchScript,
+	-- Claude Code-style grep across the entire instance tree
+	["/api/grep"] = handlers.grep,
 	["/api/get-script-function"] = handlers.getScriptFunction,
 	["/api/find-and-replace-in-scripts"] = handlers.findAndReplaceInScripts,
 	["/api/get-attribute"] = handlers.getAttribute,
@@ -5536,6 +7209,7 @@ endpointHandlers = {
 	["/api/insert-asset"] = handlers.insertAsset,
 	["/api/undo"] = handlers.undo,
 	["/api/redo"] = handlers.redo,
+	["/api/get-history"] = handlers.getHistory,
 	-- Execute Lua
 	["/api/execute-lua"] = handlers.executeLua,
 	-- Playtest control
@@ -5545,6 +7219,8 @@ endpointHandlers = {
 	["/api/capture-screenshot"] = handlers.captureScreenshot,
 	-- ViewportFrame rendering
 	["/api/render-object-view"] = handlers.renderObjectView,
+	-- 2D GUI rendering
+	["/api/render-gui"] = handlers.renderGui,
 	-- Camera control
 	["/api/focus-camera"] = handlers.focusCamera,
 }