@chrrxs/robloxstudio-mcp 3.1.0 → 3.1.2

package/studio-plugin/MCPPlugin.rbxmx

@@ -16,7 +16,7 @@ local cleanupEditBridgeArtifacts = _EvalBridges.cleanupEditBridgeArtifacts
 local ensureRuntimeBridgeInstalled = _EvalBridges.ensureRuntimeBridgeInstalled
 local RuntimeLogBuffer = TS.import(script, script, "modules", "RuntimeLogBuffer")
 local StopPlayMonitor = TS.import(script, script, "modules", "StopPlayMonitor")
-local StudioEventStream = TS.import(script, script, "modules", "StudioEventStream")
+local StudioWebSocket = TS.import(script, script, "modules", "StudioWebSocket")
 local BreakpointHandlers = TS.import(script, script, "modules", "handlers", "BreakpointHandlers")
 local RenderMonitor = TS.import(script, script, "modules", "RenderMonitor")
 -- Track render-loop liveness so input/screenshot tools can report "window
@@ -54,11 +54,11 @@ applyRememberedServerUrl()
 -- Play DataModels do not reliably fire Plugin.Unloading before Studio tears
 -- down their VM. Close the persistent WebStreamClient while BindToClose still
 -- gives this server peer a live execution context; otherwise each play cycle
--- can retain one native event stream until Studio itself is restarted. The
--- transport releases that native stream before yielding to unregister the
+-- can retain one native WebSocket until Studio itself is restarted. The
+-- transport releases that native socket before yielding to unregister the
 -- logical server peer.
 if startupRole == "server" then
-	game:BindToClose(StudioEventStream.suspendForShutdown)
+	game:BindToClose(StudioWebSocket.suspendForShutdown)
 end
 UI.init(plugin)
 local elements = UI.getElements()
@@ -148,8 +148,8 @@ local function autoActivatePeer()
 		-- legal, so the stop-play monitor lives here. It consumes tokenized
 		-- stop requests from plugin settings and acknowledges EndTest results.
 		StopPlayMonitor.startMonitor({
-			beforeEndTest = StudioEventStream.suspendForShutdown,
-			afterEndTestFailure = StudioEventStream.resumeAfterShutdownFailure,
+			beforeEndTest = StudioWebSocket.suspendForShutdown,
+			afterEndTestFailure = StudioWebSocket.resumeAfterShutdownFailure,
 		})
 	elseif role == "client" then
 		ClientBroker.setupClientBroker()
@@ -952,7 +952,7 @@ local EvalRuntimeHandlers = TS.import(script, script.Parent, "handlers", "EvalRu
 local ClientBroker = TS.import(script, script.Parent, "ClientBroker")
 local ServerUrlSettings = TS.import(script, script.Parent, "ServerUrlSettings")
 local PluginSession = TS.import(script, script.Parent, "PluginSession")
-local StudioEventStream = TS.import(script, script.Parent, "StudioEventStream")
+local StudioWebSocket = TS.import(script, script.Parent, "StudioWebSocket")
 local assignedRole
 local lastReadyPlaceKey
 local initialRole = PluginSession.getRole()
@@ -1028,7 +1028,7 @@ local function getConnectionStatus()
 	end
 	return "connecting"
 end
-local function dispatchStreamRequest(request, context)
+local function dispatchSocketRequest(request, context)
 	if request.peerId ~= PluginSession.peerId then
 		return ClientBroker.dispatchClientRequest(request.peerId, request.target, request.endpoint, request.data)
 	end
@@ -1123,7 +1123,7 @@ local function ensureIdentityWatchers()
 		end)
 		if signalOk and signal then
 			nameChangeConn = signal:Connect(function()
-				return StudioEventStream.refresh()
+				return StudioWebSocket.refresh()
 			end)
 		end
 	end
@@ -1135,7 +1135,7 @@ local function ensureIdentityWatchers()
 			placeIdChangeConn = signal:Connect(function()
 				PluginSession.invalidatePlaceName()
 				lastReadyPlaceKey = PluginSession.getPlaceKey()
-				StudioEventStream.refresh()
+				StudioWebSocket.refresh()
 			end)
 		end
 	end
@@ -1176,9 +1176,9 @@ local function activatePlugin()
 	ClientBroker.setServerUrl(conn.serverUrl)
 	lastReadyPlaceKey = PluginSession.getPlaceKey()
 	UI.updateUIState()
-	StudioEventStream.start({
+	StudioWebSocket.start({
 		serverUrl = conn.serverUrl,
-		dispatchRequest = dispatchStreamRequest,
+		dispatchRequest = dispatchSocketRequest,
 		onStatus = handleStatus,
 		onHeartbeat = handleHeartbeat,
 		onReady = handleReady,
@@ -1195,7 +1195,7 @@ local function activatePlugin()
 			if lastReadyPlaceKey ~= nil and currentPlaceKey ~= lastReadyPlaceKey then
 				lastReadyPlaceKey = currentPlaceKey
 				PluginSession.invalidatePlaceName()
-				StudioEventStream.refresh()
+				StudioWebSocket.refresh()
 			end
 		end)
 	end
@@ -1213,7 +1213,7 @@ function deactivatePlugin()
 	conn.lastHttpOk = false
 	conn.lastMcpOk = false
 	conn.mcpWaitStartTime = nil
-	StudioEventStream.stop()
+	StudioWebSocket.stop()
 	disconnectIdentityWatchers()
 	if initialRole == "server" then
 		ClientBroker.disconnectAllProxies()
@@ -1472,9 +1472,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "3.1.0" is replaced with the package version at package time
+	-- "3.1.2" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-3.1.0`
+	return `{tostring(h)}-3.1.2`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -3682,16 +3682,33 @@ end
 -- camera's own field of view so any subject fills a similar share of frame.
 local function focusViewport(requestData)
 	local instancePath = requestData.path
-	if not (instancePath ~= "" and instancePath) then
-		return {
-			error = "path is required (the instance to frame)",
-		}
-	end
-	local instance = getInstanceByPath(instancePath)
-	if not instance then
-		return {
-			error = `Instance not found: {instancePath}`,
-		}
+	local instance
+	if instancePath == nil then
+		local selection = Selection:Get()
+		if #selection == 0 then
+			return {
+				error = "No objects selected. Select a BasePart or Model, or provide path.",
+			}
+		end
+		if #selection ~= 1 then
+			return {
+				error = "Select exactly one BasePart or Model to frame, or provide path.",
+			}
+		end
+		instance = selection[1]
+	else
+		if not (type(instancePath) == "string") or instancePath == "" then
+			return {
+				error = "path must be a non-empty instance path when provided",
+			}
+		end
+		local resolved = getInstanceByPath(instancePath)
+		if not resolved then
+			return {
+				error = `Instance not found: {instancePath}`,
+			}
+		end
+		instance = resolved
 	end
 	local workspace = game:GetService("Workspace")
 	local camera = workspace.CurrentCamera
@@ -3722,6 +3739,7 @@ local function focusViewport(requestData)
 			error = "angleY must be between -89 and 89",
 		}
 	end
+	local originalCameraType = camera.CameraType
 	local ok, err = pcall(function()
 		local boundsCF
 		local boundsSize
@@ -3765,6 +3783,14 @@ local function focusViewport(requestData)
 		end
 		camera.Focus = CFrame.new(center)
 	end)
+	local restored, restoreError = pcall(function()
+		camera.CameraType = originalCameraType
+	end)
+	if not restored then
+		return {
+			error = `{if ok then "focus completed" else `focus failed: {tostring(err)}`}; failed to restore camera type: {tostring(restoreError)}`,
+		}
+	end
 	if not ok then
 		return {
 			error = `focus failed: {tostring(err)}`,
@@ -5569,6 +5595,8 @@ local convertPropertyValue = _binding.convertPropertyValue
 local _binding_1 = Recording
 local beginRecording = _binding_1.beginRecording
 local finishRecording = _binding_1.finishRecording
+-- Native StringValue rejects UTF-8 strings of 200000 bytes or more.
+local STRING_VALUE_MAX_BYTES = 199999
 local function setProperties(requestData)
 	local instancePath = requestData.instancePath
 	local properties = requestData.properties
@@ -5616,15 +5644,28 @@ local function setProperties(requestData)
 			table.insert(results, _arg0)
 		else
 			failureCount += 1
-			local _arg0 = {
+			local failure = {
 				property = propName,
 				success = false,
 				error = tostring(err),
 			}
-			table.insert(results, _arg0)
+			if instance:IsA("StringValue") and propName == "Value" and type(propValue) == "string" then
+				local _object = table.clone(failure)
+				setmetatable(_object, nil)
+				_object.details = {
+					stage = "property_write",
+					bytes = #propValue,
+					limitBytes = STRING_VALUE_MAX_BYTES,
+				}
+				table.insert(results, _object)
+			else
+				table.insert(results, failure)
+			end
 		end
 	end
-	finishRecording(recordingId, successCount > 0)
+	-- This tool is not a rollback transaction. Cancel can undo earlier unrecorded
+	-- execute_luau edits as well, even when every assignment in this call failed.
+	finishRecording(recordingId, true)
 	return {
 		instancePath = instancePath,
 		summary = {
@@ -8794,13 +8835,34 @@ local ServerStorage = _services.ServerStorage
 local State = TS.import(script, script.Parent, "State")
 local PeerRole = TS.import(script, script.Parent, "PeerRole")
 local TopologyId = TS.import(script, script.Parent, "TopologyId")
+local CoreGui = game:GetService("CoreGui")
 local MCP_PLACE_ID_ATTRIBUTE = "__MCPPlaceId"
 local TOPOLOGY_MODE_ATTRIBUTE = "__MCPTopologyMode"
 local TOPOLOGY_INSTANCE_ID_ATTRIBUTE = "__MCPTopologyInstanceId"
 local TOPOLOGY_GROUP_ID_ATTRIBUTE = "__MCPTopologyGroupId"
 local TOPOLOGY_TOKEN_ATTRIBUTE = "__MCPTopologyToken"
+local SESSION_IDENTITY_NAME = "__MCPSessionIdentity"
 local peerId = TopologyId.createPeerId()
-local processInstanceId = TopologyId.currentProcessInstanceId()
+local isEditSession = PeerRole.detect() == "edit"
+local existingSessionIdentity = CoreGui:FindFirstChild(SESSION_IDENTITY_NAME)
+local sessionInstanceId
+local createdSessionIdentity = false
+if existingSessionIdentity ~= nil and existingSessionIdentity:IsA("StringValue") and not existingSessionIdentity.Archivable and (string.match(existingSessionIdentity.Value, "^instance:[0-9a-z][0-9a-z][0-9a-z]%-[0-9a-z][0-9a-z][0-9a-z]$")) ~= nil then
+	sessionInstanceId = existingSessionIdentity.Value
+else
+	local _result = existingSessionIdentity
+	if _result ~= nil then
+		_result:Destroy()
+	end
+	sessionInstanceId = TopologyId.createInstanceId()
+	local sessionIdentity = Instance.new("StringValue")
+	sessionIdentity.Name = SESSION_IDENTITY_NAME
+	sessionIdentity.Value = sessionInstanceId
+	sessionIdentity.Archivable = false
+	sessionIdentity.Parent = CoreGui
+	createdSessionIdentity = true
+end
+local inheritedInstanceId
 local cachedPlaceName
 local cachedPlaceNamePlaceId
 local function getMarkerMode()
@@ -8808,13 +8870,17 @@ local function getMarkerMode()
 	return if mode == "shared" or mode == "multiplayer" then mode else nil
 end
 local function getInstanceId()
-	if getMarkerMode() == "shared" then
+	if inheritedInstanceId ~= nil then
+		return inheritedInstanceId
+	end
+	if not isEditSession and getMarkerMode() == "shared" then
 		local sharedInstanceId = ReplicatedStorage:GetAttribute(TOPOLOGY_INSTANCE_ID_ATTRIBUTE)
 		if type(sharedInstanceId) == "string" and sharedInstanceId ~= "" then
+			inheritedInstanceId = sharedInstanceId
 			return sharedInstanceId
 		end
 	end
-	return processInstanceId
+	return sessionInstanceId
 end
 local function getMultiplayerGroupId()
 	if getMarkerMode() ~= "multiplayer" then
@@ -8847,7 +8913,7 @@ local function setTopologyMarker(mode, instanceId, groupId)
 	return token
 end
 local function prepareSharedTopology()
-	return setTopologyMarker("shared", processInstanceId, nil)
+	return setTopologyMarker("shared", sessionInstanceId, nil)
 end
 local function prepareMultiplayerTopology(groupId)
 	return setTopologyMarker("multiplayer", nil, groupId)
@@ -8856,6 +8922,10 @@ local function clearTopologyMarker(token)
 	if ReplicatedStorage:GetAttribute(TOPOLOGY_TOKEN_ATTRIBUTE) ~= token then
 		return nil
 	end
+	if isEditSession then
+		prepareSharedTopology()
+		return nil
+	end
 	ReplicatedStorage:SetAttribute(TOPOLOGY_MODE_ATTRIBUTE, nil)
 	ReplicatedStorage:SetAttribute(TOPOLOGY_INSTANCE_ID_ATTRIBUTE, nil)
 	ReplicatedStorage:SetAttribute(TOPOLOGY_GROUP_ID_ATTRIBUTE, nil)
@@ -8916,6 +8986,15 @@ local function createReadyPayload(readyPeerId, role, instanceId, multiplayerGrou
 		timestamp = tick(),
 	}
 end
+-- CoreGui survives plugin reloads without saving or replicating this identity.
+-- Preserve active test markers on reload; fresh edits replace saved place markers.
+if isEditSession then
+	if createdSessionIdentity or getMarkerMode() == nil then
+		prepareSharedTopology()
+	end
+else
+	getInstanceId()
+end
 return {
 	peerId = peerId,
 	getInstanceId = getInstanceId,
@@ -9736,7 +9815,7 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "3.1.0"
+local CURRENT_VERSION = "3.1.2"
 local PLUGIN_VARIANT = "main"
 local BASE_PORT = 58741
 local function createConnection(port)
@@ -10001,40 +10080,56 @@ return {
       </Item>
       <Item class="ModuleScript" referent="36">
         <Properties>
-          <string name="Name">StudioEventStream</string>
+          <string name="Name">StudioWebSocket</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
 local TS = require(script.Parent.Parent.include.RuntimeLib)
 local HttpService = TS.import(script, script.Parent.Parent, "node_modules", "@rbxts", "services").HttpService
 local HttpDiagnostics = TS.import(script, script.Parent, "HttpDiagnostics")
 local PluginSession = TS.import(script, script.Parent, "PluginSession")
-local INITIAL_RECONNECT_DELAY_SECONDS = 0.5
-local MAX_RECONNECT_DELAY_SECONDS = 5
-local INITIAL_RESPONSE_RETRY_DELAY_SECONDS = 0.5
-local MAX_RESPONSE_RETRY_DELAY_SECONDS = 5
-local MAX_TERMINAL_RESPONSES = 256
-local STREAM_SILENCE_TIMEOUT_SECONDS = 20
+local PROTOCOL_VERSION = 1
+local INITIAL_RETRY_DELAY_SECONDS = 0.5
+local MAX_RETRY_DELAY_SECONDS = 5
+local SOCKET_SILENCE_TIMEOUT_SECONDS = 20
+local RESPONSE_RETENTION_SECONDS = 5 * 60
+local RESPONSE_ACK_TIMEOUT_SECONDS = 120
+local MAX_TERMINAL_RESPONSES = 32768
+local MAX_ACTIVE_RESPONSES = 128
+local MAX_ADMISSION_REJECTIONS = 128
+local MAX_FRAME_BYTES = 64 * 1024 * 1024
+local MAX_PENDING_RESPONSE_BYTES = 64 * 1024 * 1024
+local RESERVED_ERROR_BYTES = 4096
+-- The bridge admits 128 UTF-16 code units; each can require three UTF-8 bytes.
+local MAX_REQUEST_ID_BYTES = 128 * 3
 local options
 local active = false
 local shutdownSuspended = false
 local generation = 0
 local reconnectAttempt = 0
-local streamClient
-local streamConnections = {}
+local socketClient
+local socketOpen = false
+local socketConnections = {}
 local lastValidEventAt = 0
+local cachedReady
+local readyRefreshPending = false
+local pendingResponseBytes = 0
+local inFlightRequestBytes = 0
+local pendingRejectionCount = 0
 local inFlightRequests = {}
 local pendingResponses = {}
 local terminalResponseIds = {}
 local terminalResponseOrder = {}
+local terminalHead = 0
+local terminalCount = 0
 local readyFailureLogKeys = {}
-local function decodeMessage(message)
-	-- Studio versions in the supported channel have surfaced either the SSE
-	-- data payload or the complete single-line `data:` frame. The bridge emits
-	-- one JSON data line per event, so normalize both forms before decoding.
-	local payload = message
-	local normalized = (string.gsub((string.gsub(message, "\r\n", "\n")), "\r", "\n"))
-	if string.sub(normalized, 1, 5) == "data:" then
-		payload = (string.gsub((string.gsub(string.sub(normalized, 6), "^%s+", "")), "%s+$", ""))
+local function validRequestId(value)
+	local _value = value
+	local _condition = type(_value) == "string"
+	if _condition then
+		_condition = #value > 0 and #value <= MAX_REQUEST_ID_BYTES
 	end
+	return _condition
+end
+local function decodeMessage(payload)
 	local decodeOk, decoded = pcall(function()
 		return HttpService:JSONDecode(payload)
 	end)
@@ -10078,13 +10173,21 @@ local function decodeMessage(message)
 		_object[_left_2] = if type(_pluginVariant) == "string" then envelope.pluginVariant else nil
 		return _object
 	end
-	if envelope.kind == "cancel" then
-		local _requestId = envelope.requestId
-		local _condition = not (type(_requestId) == "string")
-		if not _condition then
-			_condition = (envelope.reason ~= "timeout" and envelope.reason ~= "aborted" and envelope.reason ~= "connection_closed")
+	if not validRequestId(envelope.requestId) then
+		return nil
+	end
+	if envelope.kind == "ack" then
+		if envelope.disposition ~= "accepted" and envelope.disposition ~= "already_settled" and envelope.disposition ~= "unknown" then
+			return nil
 		end
-		if _condition then
+		return {
+			kind = "ack",
+			requestId = envelope.requestId,
+			disposition = envelope.disposition,
+		}
+	end
+	if envelope.kind == "cancel" then
+		if envelope.reason ~= "timeout" and envelope.reason ~= "aborted" and envelope.reason ~= "connection_closed" then
 			return nil
 		end
 		return {
@@ -10094,23 +10197,19 @@ local function decodeMessage(message)
 		}
 	end
 	if envelope.kind == "request" then
-		local _requestId = envelope.requestId
-		local _condition = not (type(_requestId) == "string")
+		local _peerId = envelope.peerId
+		local _condition = not (type(_peerId) == "string")
 		if not _condition then
-			local _peerId = envelope.peerId
-			_condition = not (type(_peerId) == "string")
+			local _target = envelope.target
+			_condition = not (type(_target) == "string")
 			if not _condition then
-				local _target = envelope.target
-				_condition = not (type(_target) == "string")
+				local _endpoint = envelope.endpoint
+				_condition = not (type(_endpoint) == "string")
 				if not _condition then
-					local _endpoint = envelope.endpoint
-					_condition = not (type(_endpoint) == "string")
+					local _remainingMs = envelope.remainingMs
+					_condition = not (type(_remainingMs) == "number")
 					if not _condition then
-						local _remainingMs = envelope.remainingMs
-						_condition = not (type(_remainingMs) == "number")
-						if not _condition then
-							_condition = envelope.remainingMs < 0
-						end
+						_condition = envelope.remainingMs < 0 or envelope.remainingMs ~= envelope.remainingMs or envelope.remainingMs == math.huge
 					end
 				end
 			end
@@ -10118,30 +10217,35 @@ local function decodeMessage(message)
 		if _condition then
 			return nil
 		end
-		local data
-		local _data = envelope.data
-		if type(_data) == "table" then
-			data = envelope.data
-		end
-		return {
+		local _object = {
 			kind = "request",
 			requestId = envelope.requestId,
 			peerId = envelope.peerId,
 			target = envelope.target,
 			endpoint = envelope.endpoint,
-			data = data,
 			remainingMs = envelope.remainingMs,
 		}
+		local _left = "data"
+		local _data = envelope.data
+		_object[_left] = if type(_data) == "table" then envelope.data else nil
+		return _object
 	end
 	return nil
 end
-local function closeCurrentStream()
-	local current = streamClient
-	streamClient = nil
-	for _, connection in streamConnections do
+local function closeCurrentSocket()
+	local current = socketClient
+	socketClient = nil
+	socketOpen = false
+	for _, connection in socketConnections do
 		connection:Disconnect()
 	end
-	streamConnections = {}
+	socketConnections = {}
+	for _, entry in pendingResponses do
+		if entry.ackTimer ~= nil then
+			task.cancel(entry.ackTimer)
+		end
+		entry.ackTimer = nil
+	end
 	if current ~= nil then
 		pcall(function()
 			return current:Close()
@@ -10162,42 +10266,39 @@ local function disconnectSession(currentOptions)
 		})
 	end)
 end
-local function responseRetryDelay(attempt)
-	return math.min(INITIAL_RESPONSE_RETRY_DELAY_SECONDS * math.pow(2, math.max(attempt - 1, 0)), MAX_RESPONSE_RETRY_DELAY_SECONDS)
+local function retryDelay(attempt)
+	return math.min(INITIAL_RETRY_DELAY_SECONDS * math.pow(2, math.max(attempt - 1, 0)), MAX_RETRY_DELAY_SECONDS)
 end
-local function parseResponseDisposition(success, body)
-	local decodeOk, decoded = pcall(function()
-		return HttpService:JSONDecode(body)
-	end)
-	if not decodeOk or not (type(decoded) == "table") then
-		return nil
-	end
-	local acknowledgement = decoded
-	local disposition = acknowledgement.disposition
-	if disposition == "accepted" or disposition == "already_settled" or disposition == "unknown" then
-		return disposition
-	end
-	if success and acknowledgement.success == true and disposition == nil then
-		return "accepted"
+local function pruneTerminalResponses()
+	local now = os.clock()
+	while terminalCount > 0 do
+		local oldest = terminalResponseOrder[terminalHead + 1]
+		if oldest == nil or oldest.expiresAt > now then
+			break
+		end
+		local _requestId = oldest.requestId
+		terminalResponseIds[_requestId] = nil
+		terminalResponseOrder[terminalHead + 1] = nil
+		terminalHead = (terminalHead + 1) % MAX_TERMINAL_RESPONSES
+		terminalCount -= 1
 	end
-	return nil
 end
 local function rememberTerminalResponse(requestId)
+	pruneTerminalResponses()
 	local _requestId = requestId
 	if terminalResponseIds[_requestId] ~= nil then
 		return nil
 	end
+	-- Admission reserves this tombstone before any side effects can execute.
+	terminalResponseOrder[(terminalHead + terminalCount) % MAX_TERMINAL_RESPONSES + 1] = {
+		requestId = requestId,
+		expiresAt = os.clock() + RESPONSE_RETENTION_SECONDS,
+	}
+	terminalCount += 1
 	local _requestId_1 = requestId
 	terminalResponseIds[_requestId_1] = true
-	local _requestId_2 = requestId
-	table.insert(terminalResponseOrder, _requestId_2)
-	while #terminalResponseOrder > MAX_TERMINAL_RESPONSES do
-		local oldest = table.remove(terminalResponseOrder, 1)
-		if oldest ~= nil then
-			terminalResponseIds[oldest] = nil
-		end
-	end
 end
+local scheduleReconnect
 local function settleResponse(requestId, entry, disposition)
 	local _requestId = requestId
 	if pendingResponses[_requestId] ~= entry then
@@ -10205,66 +10306,145 @@ local function settleResponse(requestId, entry, disposition)
 	end
 	local _requestId_1 = requestId
 	pendingResponses[_requestId_1] = nil
+	if entry.admissionRejection then
+		pendingRejectionCount -= 1
+	else
+		pendingResponseBytes -= #entry.body
+	end
+	if entry.ackTimer ~= nil then
+		task.cancel(entry.ackTimer)
+	end
+	if entry.expiryTimer ~= nil then
+		task.cancel(entry.expiryTimer)
+	end
+	entry.ackTimer = nil
+	entry.expiryTimer = nil
+	-- Release a queued native frame before making its capacity available again.
+	if disposition == "expired" and socketOpen and entry.sentGeneration == generation then
+		scheduleReconnect(generation, `WebSocket response {requestId} expired without acknowledgement`)
+	end
+	entry.body = ""
 	rememberTerminalResponse(requestId)
-	if disposition == "unknown" then
-		warn(`[robloxstudio-mcp] Server no longer recognizes response {requestId}; dropping stored result`)
+	if disposition == "unknown" or disposition == "expired" then
+		warn(`[robloxstudio-mcp] Response {requestId} outcome unknown ({disposition}); stored result released, mutation must not be replayed`)
 	end
 end
-local function postPendingResponse(requestId, entry)
-	local currentOptions = options
-	local _condition = not active or currentOptions == nil
+local function sendProgress(requestId, progress)
+	local client = socketClient
+	local _condition = not active or not socketOpen or client == nil
 	if not _condition then
-		local _requestId = requestId
-		_condition = pendingResponses[_requestId] ~= entry
+		local _result = options
+		if _result ~= nil then
+			_result = _result.serverUrl
+		end
+		_condition = _result ~= progress.serverUrl
 		if not _condition then
-			_condition = entry.posting
+			_condition = progress.phase == nil
 		end
 	end
 	if _condition then
 		return nil
 	end
-	entry.posting = true
-	entry.retryToken += 1
-	task.spawn(function()
-		local _condition_1 = not active or options ~= currentOptions
-		if not _condition_1 then
-			local _requestId = requestId
-			_condition_1 = pendingResponses[_requestId] ~= entry
+	if progress.sentGeneration == generation and progress.sentPhase == progress.phase then
+		return nil
+	end
+	local expectedGeneration = generation
+	progress.sentGeneration = expectedGeneration
+	progress.sentPhase = progress.phase
+	local sent = pcall(function()
+		return client:Send(HttpService:JSONEncode({
+			kind = "progress",
+			requestId = requestId,
+			phase = progress.phase,
+			outcome = progress.outcome,
+		}))
+	end)
+	if not sent then
+		scheduleReconnect(expectedGeneration, "WebSocket progress send failed; current observation retained for reconnect")
+	end
+end
+local function completeProgress(requestId, progress, outcome)
+	progress.phase = "response_delivery"
+	progress.outcome = outcome
+	sendProgress(requestId, progress)
+end
+local function handlerOutcome(response)
+	local _response = response
+	if not (type(_response) == "table") then
+		return "success"
+	end
+	local result = response
+	if result.error ~= nil or result.success == false or result.ok == false then
+		return "error"
+	end
+	local _summary = result.summary
+	if type(_summary) == "table" then
+		local summary = result.summary
+		local _failed = summary.failed
+		local _condition = type(_failed) == "number"
+		if _condition then
+			_condition = summary.failed > 0
 		end
-		if _condition_1 then
-			entry.posting = false
-			return nil
+		if _condition then
+			return "error"
 		end
-		local responseUrl = `{currentOptions.serverUrl}/response`
-		local requestOk, requestResult = pcall(function()
-			return HttpService:RequestAsync({
-				Url = responseUrl,
-				Method = "POST",
-				Headers = {
-					["Content-Type"] = "application/json",
-				},
-				Body = entry.body,
-			})
-		end)
-		local _requestId = requestId
-		if pendingResponses[_requestId] ~= entry then
-			return nil
+	end
+	return "success"
+end
+local function sendPendingResponse(requestId, entry)
+	sendProgress(requestId, entry.progress)
+	local client = socketClient
+	local _condition = not active or not socketOpen or client == nil
+	if not _condition then
+		local _result = options
+		if _result ~= nil then
+			_result = _result.serverUrl
 		end
-		entry.posting = false
-		local failure
-		if not requestOk then
-			failure = HttpDiagnostics.formatRequestFailure(responseUrl, false, requestResult)
-		else
-			local disposition = parseResponseDisposition(requestResult.Success, requestResult.Body)
-			if disposition ~= nil then
-				settleResponse(requestId, entry, disposition)
-				return nil
-			end
-			failure = if requestResult.Success then "Invalid /response acknowledgement" else HttpDiagnostics.formatRequestFailure(responseUrl, true, requestResult)
+		_condition = _result ~= entry.serverUrl
+		if not _condition then
+			local _requestId = requestId
+			_condition = pendingResponses[_requestId] ~= entry
 		end
-		warn(`[robloxstudio-mcp] Failed to deliver response {requestId}: {failure}`)
-		entry.retryAttempt += 1
-		local _condition_2 = not active
+	end
+	if _condition then
+		return nil
+	end
+	if os.clock() >= entry.expiresAt then
+		settleResponse(requestId, entry, "expired")
+		return nil
+	end
+	if entry.sentGeneration == generation then
+		return nil
+	end
+	local expectedGeneration = generation
+	entry.sentGeneration = expectedGeneration
+	local sendOk, sendError = pcall(function()
+		return client:Send(entry.body)
+	end)
+	if not sendOk then
+		warn(`[robloxstudio-mcp] WebSocket response send failed for {requestId} ({#entry.body} bytes, stage=socket_send): {tostring(sendError)}`)
+		scheduleReconnect(expectedGeneration, "WebSocket response send failed; retained for reconnect")
+		return nil
+	end
+	local _requestId = requestId
+	local _condition_1 = pendingResponses[_requestId] ~= entry
+	if not _condition_1 then
+		_condition_1 = generation ~= expectedGeneration or socketClient ~= client
+	end
+	if _condition_1 then
+		return nil
+	end
+	-- Send only queues bytes. A heartbeat does not prove that this upload drained.
+	-- Give large transfers a generous window, growing after reconnect; never put
+	-- a second copy on the same socket, even when an acknowledgement is lost.
+	entry.sendAttempt += 1
+	local ackDelay = RESPONSE_ACK_TIMEOUT_SECONDS * math.pow(2, math.min(entry.sendAttempt - 1, 2))
+	if os.clock() + ackDelay >= entry.expiresAt then
+		return nil
+	end
+	entry.ackTimer = task.delay(ackDelay, function()
+		entry.ackTimer = nil
+		local _condition_2 = generation ~= expectedGeneration
 		if not _condition_2 then
 			local _requestId_1 = requestId
 			_condition_2 = pendingResponses[_requestId_1] ~= entry
@@ -10272,62 +10452,145 @@ local function postPendingResponse(requestId, entry)
 		if _condition_2 then
 			return nil
 		end
-		entry.retryToken += 1
-		local retryToken = entry.retryToken
-		local delay = responseRetryDelay(entry.retryAttempt)
-		task.delay(delay, function()
-			local _condition_3 = not active
-			if not _condition_3 then
-				local _requestId_1 = requestId
-				_condition_3 = pendingResponses[_requestId_1] ~= entry
-				if not _condition_3 then
-					_condition_3 = entry.retryToken ~= retryToken
-				end
-			end
-			if _condition_3 then
-				return nil
-			end
-			postPendingResponse(requestId, entry)
-		end)
+		scheduleReconnect(expectedGeneration, `WebSocket response {requestId} acknowledgement timed out; retained for reconnect`)
 	end)
 end
 local function resumePendingResponses()
+	for requestId, entry in inFlightRequests do
+		sendProgress(requestId, entry.progress)
+	end
 	for requestId, entry in pendingResponses do
-		postPendingResponse(requestId, entry)
+		sendPendingResponse(requestId, entry)
 	end
 end
-local function encodeResponse(requestId, response)
+local function encodeError(requestId, detail, executionOutcome)
 	local encodeOk, encoded = pcall(function()
 		return HttpService:JSONEncode({
+			kind = "response",
 			requestId = requestId,
-			response = response,
+			executionOutcome = executionOutcome,
+			error = `Request {requestId}: {detail}`,
 		})
 	end)
-	if encodeOk then
+	if encodeOk and #encoded <= RESERVED_ERROR_BYTES then
 		return encoded
 	end
-	warn(`[robloxstudio-mcp] Failed to serialize response {requestId}: {tostring(encoded)}`)
 	return HttpService:JSONEncode({
+		kind = "response",
 		requestId = requestId,
-		error = `Plugin response serialization failed: {tostring(encoded)}`,
+		executionOutcome = executionOutcome,
+		error = `Request {requestId}: Plugin error could not be encoded within its reserved response capacity (stage=error_encode); handler outcome={executionOutcome}`,
 	})
 end
+local function encodeResponse(requestId, response, executionOutcome)
+	local encodeOk, encoded = pcall(function()
+		return HttpService:JSONEncode({
+			kind = "response",
+			requestId = requestId,
+			response = response,
+			executionOutcome = executionOutcome,
+		})
+	end)
+	if not encodeOk then
+		return encodeError(requestId, `Plugin response serialization failed (stage=response_encode): {string.sub(tostring(encoded), 1, 512)}`, executionOutcome)
+	end
+	if #encoded > MAX_FRAME_BYTES then
+		return encodeError(requestId, `Plugin response exceeds WebSocket frame limit (stage=response_encode, bytes={#encoded}, maxBytes={MAX_FRAME_BYTES}); execution completed but result cannot be delivered`, executionOutcome)
+	end
+	return encoded
+end
+local function retainResponse(requestId, body, serverUrl, progress, admissionRejection)
+	if admissionRejection == nil then
+		admissionRejection = false
+	end
+	-- Admission errors have their own bounded 128 x 4KiB reserve so a full-size
+	-- result never consumes the capacity required to retain a rejection.
+	-- ▼ ReadonlyMap.size ▼
+	local _size = 0
+	for _ in inFlightRequests do
+		_size += 1
+	end
+	-- ▲ ReadonlyMap.size ▲
+	-- ▼ ReadonlyMap.size ▼
+	local _size_1 = 0
+	for _ in pendingResponses do
+		_size_1 += 1
+	end
+	-- ▲ ReadonlyMap.size ▲
+	local reservedBytes = (_size + _size_1 - pendingRejectionCount) * RESERVED_ERROR_BYTES
+	if not admissionRejection and pendingResponseBytes + #body + reservedBytes > MAX_PENDING_RESPONSE_BYTES then
+		body = encodeError(requestId, `Plugin response exceeds retained-result capacity (stage=response_retention, bytes={#body}, retainedBytes={pendingResponseBytes}, maxBytes={MAX_PENDING_RESPONSE_BYTES}); execution completed but result cannot be retained`, progress.outcome or "unknown")
+	end
+	local entry = {
+		body = body,
+		serverUrl = serverUrl,
+		progress = progress,
+		expiresAt = os.clock() + RESPONSE_RETENTION_SECONDS,
+		admissionRejection = admissionRejection,
+		sendAttempt = 0,
+	}
+	local _requestId = requestId
+	pendingResponses[_requestId] = entry
+	if admissionRejection then
+		pendingRejectionCount += 1
+	else
+		pendingResponseBytes += #body
+	end
+	entry.expiryTimer = task.delay(RESPONSE_RETENTION_SECONDS, function()
+		entry.expiryTimer = nil
+		local _requestId_1 = requestId
+		if pendingResponses[_requestId_1] == entry then
+			settleResponse(requestId, entry, "expired")
+		end
+	end)
+	sendPendingResponse(requestId, entry)
+end
+local function rejectAdmission(requestId, detail)
+	local currentOptions = options
+	if currentOptions == nil then
+		return nil
+	end
+	local _condition = pendingRejectionCount >= MAX_ADMISSION_REJECTIONS
+	if not _condition then
+		local _exp = terminalCount
+		-- ▼ ReadonlyMap.size ▼
+		local _size = 0
+		for _ in inFlightRequests do
+			_size += 1
+		end
+		-- ▲ ReadonlyMap.size ▲
+		local _exp_1 = _exp + _size
+		-- ▼ ReadonlyMap.size ▼
+		local _size_1 = 0
+		for _ in pendingResponses do
+			_size_1 += 1
+		end
+		-- ▲ ReadonlyMap.size ▲
+		_condition = _exp_1 + _size_1 >= MAX_TERMINAL_RESPONSES
+	end
+	if _condition then
+		-- No execution and no unretained "result". Reconnect drains existing
+		-- outcomes so their acknowledgements can release rejection reservations.
+		scheduleReconnect(generation, "Plugin admission rejection reserve exhausted; execution not started")
+		return nil
+	end
+	local progress = {
+		serverUrl = currentOptions.serverUrl,
+	}
+	completeProgress(requestId, progress, "not_executed")
+	retainResponse(requestId, encodeError(requestId, detail, "not_executed"), currentOptions.serverUrl, progress, true)
+end
 local function cancelRequest(event)
 	local _requestId = event.requestId
 	local inFlight = inFlightRequests[_requestId]
 	if inFlight ~= nil then
 		inFlight.cancelled = true
 	end
-	local _requestId_1 = event.requestId
-	local pending = pendingResponses[_requestId_1]
-	if pending ~= nil then
-		pending.retryToken += 1
-		local _requestId_2 = event.requestId
-		pendingResponses[_requestId_2] = nil
-	end
-	rememberTerminalResponse(event.requestId)
+	-- Cancellation only changes execution context. Completed results still need
+	-- recording, including results produced by already-running side effects.
 end
-local function dispatchRequest(request)
+local function dispatchRequest(request, requestBytes)
+	pruneTerminalResponses()
 	local _requestId = request.requestId
 	local _condition = terminalResponseIds[_requestId] ~= nil
 	if not _condition then
@@ -10345,8 +10608,28 @@ local function dispatchRequest(request)
 	if not active or dispatchOptions == nil then
 		return nil
 	end
+	-- ▼ ReadonlyMap.size ▼
+	local _size = 0
+	for _ in inFlightRequests do
+		_size += 1
+	end
+	-- ▲ ReadonlyMap.size ▲
+	-- ▼ ReadonlyMap.size ▼
+	local _size_1 = 0
+	for _ in pendingResponses do
+		_size_1 += 1
+	end
+	-- ▲ ReadonlyMap.size ▲
+	local activeCount = _size + _size_1 - pendingRejectionCount
+	if activeCount >= MAX_ACTIVE_RESPONSES or terminalCount + activeCount + MAX_ADMISSION_REJECTIONS >= MAX_TERMINAL_RESPONSES or pendingResponseBytes + (activeCount + 1) * RESERVED_ERROR_BYTES > MAX_PENDING_RESPONSE_BYTES or inFlightRequestBytes + requestBytes > MAX_FRAME_BYTES then
+		rejectAdmission(request.requestId, `Plugin request admission capacity exceeded (stage=request_admission, bytes={requestBytes}, inFlightBytes={inFlightRequestBytes}, activeResponses={activeCount}, maxActiveResponses={MAX_ACTIVE_RESPONSES}, terminalIds={terminalCount}, maxTerminalIds={MAX_TERMINAL_RESPONSES}, retainedBytes={pendingResponseBytes}, maxBytes={MAX_PENDING_RESPONSE_BYTES}); execution not started`)
+		return nil
+	end
 	local inFlight = {
 		cancelled = false,
+		progress = {
+			serverUrl = dispatchOptions.serverUrl,
+		},
 	}
 	local context = {
 		requestId = request.requestId,
@@ -10357,50 +10640,31 @@ local function dispatchRequest(request)
 	}
 	local _requestId_1 = request.requestId
 	inFlightRequests[_requestId_1] = inFlight
+	inFlightRequestBytes += requestBytes
 	task.spawn(function()
-		local _condition_1 = inFlight.cancelled
-		if not _condition_1 then
+		if inFlight.cancelled or not active or os.clock() >= context.deadlineAt then
+			completeProgress(request.requestId, inFlight.progress, "not_executed")
 			local _requestId_2 = request.requestId
-			_condition_1 = terminalResponseIds[_requestId_2] ~= nil
-		end
-		if _condition_1 then
-			local _requestId_2 = request.requestId
-			if inFlightRequests[_requestId_2] == inFlight then
-				local _requestId_3 = request.requestId
-				inFlightRequests[_requestId_3] = nil
-			end
+			inFlightRequests[_requestId_2] = nil
+			inFlightRequestBytes -= requestBytes
+			retainResponse(request.requestId, encodeError(request.requestId, "Request cancelled or admission deadline expired before execution started", "not_executed"), dispatchOptions.serverUrl, inFlight.progress)
 			return nil
 		end
+		-- This observes handler entry, including broker dispatch, not a user Luau
+		-- instruction. The waiter's deadline/cancellation is not a rollback.
+		inFlight.progress.phase = "executing"
+		sendProgress(request.requestId, inFlight.progress)
 		local dispatchOk, response = pcall(function()
 			return dispatchOptions.dispatchRequest(request, context)
 		end)
-		local _condition_2 = inFlight.cancelled
-		if not _condition_2 then
-			local _requestId_2 = request.requestId
-			_condition_2 = terminalResponseIds[_requestId_2] ~= nil
-		end
-		if _condition_2 then
-			local _requestId_2 = request.requestId
-			if inFlightRequests[_requestId_2] == inFlight then
-				local _requestId_3 = request.requestId
-				inFlightRequests[_requestId_3] = nil
-			end
-			return nil
-		end
-		local responseData = if dispatchOk then response else {
-			error = tostring(response),
-		}
-		local entry = {
-			body = encodeResponse(request.requestId, responseData),
-			retryAttempt = 0,
-			posting = false,
-			retryToken = 0,
-		}
+		local executionOutcome = if dispatchOk then handlerOutcome(response) else "error"
+		-- Report handler return before JSON encoding or result retention can fail.
+		completeProgress(request.requestId, inFlight.progress, executionOutcome)
+		local body = if dispatchOk then encodeResponse(request.requestId, response, executionOutcome) else encodeError(request.requestId, `Plugin request execution failed: {string.sub(tostring(response), 1, 512)}`, executionOutcome)
 		local _requestId_2 = request.requestId
-		pendingResponses[_requestId_2] = entry
-		local _requestId_3 = request.requestId
-		inFlightRequests[_requestId_3] = nil
-		postPendingResponse(request.requestId, entry)
+		inFlightRequests[_requestId_2] = nil
+		inFlightRequestBytes -= requestBytes
+		retainResponse(request.requestId, body, dispatchOptions.serverUrl, inFlight.progress)
 	end)
 end
 local function invokeCallback(name, callback)
@@ -10412,24 +10676,13 @@ end
 local function reportTransport(update)
 	local currentOptions = options
 	if active and currentOptions ~= nil then
-		invokeCallback("event stream transport", function()
+		invokeCallback("WebSocket transport", function()
 			return currentOptions.onTransportUpdate(update)
 		end)
 	end
 end
-local function reconnectDelay(attempt)
-	return math.min(INITIAL_RECONNECT_DELAY_SECONDS * math.pow(2, math.max(attempt - 1, 0)), MAX_RECONNECT_DELAY_SECONDS)
-end
 local connect
-local function connectAfter(delaySeconds, expectedGeneration)
-	task.delay(delaySeconds, function()
-		if not active or generation ~= expectedGeneration then
-			return nil
-		end
-		connect(expectedGeneration)
-	end)
-end
-local function scheduleReconnect(expectedGeneration, detail, duplicate)
+function scheduleReconnect(expectedGeneration, detail, duplicate)
 	if duplicate == nil then
 		duplicate = false
 	end
@@ -10437,27 +10690,31 @@ local function scheduleReconnect(expectedGeneration, detail, duplicate)
 		return nil
 	end
 	generation += 1
-	closeCurrentStream()
+	closeCurrentSocket()
 	reconnectAttempt += 1
-	local delay = if duplicate then 1 else reconnectDelay(reconnectAttempt)
+	local delay = if duplicate then 1 else retryDelay(reconnectAttempt)
 	reportTransport({
 		state = if duplicate then "waiting-duplicate" else "retrying",
 		attempt = reconnectAttempt,
 		retryDelay = delay,
 		detail = detail,
 	})
-	connectAfter(delay, generation)
+	local nextGeneration = generation
+	task.delay(delay, function()
+		if active and generation == nextGeneration then
+			connect(nextGeneration)
+		end
+	end)
 end
 local function watchForSilence(expectedGeneration, expectedClient)
 	local elapsed = tick() - lastValidEventAt
-	local delay = math.max(STREAM_SILENCE_TIMEOUT_SECONDS - elapsed, 0.1)
-	task.delay(delay, function()
-		if not active or generation ~= expectedGeneration or streamClient ~= expectedClient then
+	task.delay(math.max(SOCKET_SILENCE_TIMEOUT_SECONDS - elapsed, 0.1), function()
+		if not active or generation ~= expectedGeneration or socketClient ~= expectedClient then
 			return nil
 		end
 		local silentFor = tick() - lastValidEventAt
-		if silentFor >= STREAM_SILENCE_TIMEOUT_SECONDS then
-			scheduleReconnect(expectedGeneration, `Event stream silent for {math.floor(silentFor)} seconds`)
+		if silentFor >= SOCKET_SILENCE_TIMEOUT_SECONDS then
+			scheduleReconnect(expectedGeneration, `WebSocket silent for {math.floor(silentFor)} seconds`)
 			return nil
 		end
 		watchForSilence(expectedGeneration, expectedClient)
@@ -10486,14 +10743,21 @@ local function parseReadyResponse(body)
 						local _instanceId = value.instanceId
 						_condition = not (type(_instanceId) == "string")
 						if not _condition then
-							_condition = value.instanceId == ""
+							_condition = value.instanceId == "" or value.protocolVersion ~= PROTOCOL_VERSION
 							if not _condition then
-								local _condition_1 = value.multiplayerGroupId ~= nil
-								if _condition_1 then
-									local _multiplayerGroupId = value.multiplayerGroupId
-									_condition_1 = not (type(_multiplayerGroupId) == "string")
+								local _transportToken = value.transportToken
+								_condition = not (type(_transportToken) == "string")
+								if not _condition then
+									_condition = value.transportToken == ""
+									if not _condition then
+										local _condition_1 = value.multiplayerGroupId ~= nil
+										if _condition_1 then
+											local _multiplayerGroupId = value.multiplayerGroupId
+											_condition_1 = not (type(_multiplayerGroupId) == "string")
+										end
+										_condition = _condition_1
+									end
 								end
-								_condition = _condition_1
 							end
 						end
 					end
@@ -10510,9 +10774,64 @@ local function parseReadyResponse(body)
 		peerId = value.peerId,
 		instanceId = value.instanceId,
 		multiplayerGroupId = value.multiplayerGroupId,
+		protocolVersion = PROTOCOL_VERSION,
+		transportToken = value.transportToken,
 	}
 end
-local refresh
+local function registerReady(currentOptions, expectedGeneration, reconnectOnFailure)
+	local instanceId = PluginSession.getInstanceId()
+	local multiplayerGroupId = PluginSession.getMultiplayerGroupId()
+	local transportRole = PluginSession.getRole()
+	local readyUrl = `{currentOptions.serverUrl}/ready`
+	local readyPayload = PluginSession.createReadyPayload(PluginSession.peerId, transportRole, instanceId, multiplayerGroupId)
+	if not active or generation ~= expectedGeneration or options ~= currentOptions then
+		return nil
+	end
+	local readyOk, readyResult = pcall(function()
+		return HttpService:RequestAsync({
+			Url = readyUrl,
+			Method = "POST",
+			Headers = {
+				["Content-Type"] = "application/json",
+			},
+			Body = HttpService:JSONEncode(readyPayload),
+		})
+	end)
+	if not active or generation ~= expectedGeneration or options ~= currentOptions then
+		return nil
+	end
+	local readyLogKey = `{currentOptions.serverUrl}|{PluginSession.peerId}`
+	if not readyOk or not readyResult.Success then
+		local detail = if readyOk then HttpDiagnostics.formatRequestFailure(readyUrl, true, readyResult) else HttpDiagnostics.formatRequestFailure(readyUrl, false, readyResult)
+		if not (readyFailureLogKeys[readyLogKey] ~= nil) then
+			readyFailureLogKeys[readyLogKey] = true
+			warn(`[robloxstudio-mcp] /ready failed for {instanceId}/{transportRole}: {detail}`)
+		end
+		if reconnectOnFailure then
+			scheduleReconnect(expectedGeneration, detail, readyOk and readyResult.StatusCode == 409)
+		end
+		return nil
+	end
+	local readyData = parseReadyResponse(readyResult.Body)
+	if readyData == nil or readyData.peerId ~= PluginSession.peerId or readyData.instanceId ~= instanceId or readyData.multiplayerGroupId ~= multiplayerGroupId then
+		if reconnectOnFailure then
+			scheduleReconnect(expectedGeneration, "Invalid /ready response: expected Peer topology and WebSocket protocol credentials")
+		end
+		return nil
+	end
+	if readyFailureLogKeys[readyLogKey] ~= nil then
+		readyFailureLogKeys[readyLogKey] = nil
+		print(`[robloxstudio-mcp] /ready connected for {instanceId}/{readyData.assignedRole} via {currentOptions.serverUrl}`)
+	end
+	cachedReady = readyData
+	invokeCallback("WebSocket ready", function()
+		return currentOptions.onReady(readyData)
+	end)
+	return readyData
+end
+local function credentialsRejected(statusCode)
+	return statusCode == 401 or statusCode == 403 or statusCode == 404
+end
 function connect(expectedGeneration)
 	local currentOptions = options
 	if not active or generation ~= expectedGeneration or currentOptions == nil then
@@ -10524,69 +10843,21 @@ function connect(expectedGeneration)
 		retryDelay = 0,
 	})
 	task.spawn(function()
-		local instanceId = PluginSession.getInstanceId()
-		local multiplayerGroupId = PluginSession.getMultiplayerGroupId()
-		local readyUrl = `{currentOptions.serverUrl}/ready`
-		local transportRole = PluginSession.getRole()
-		local readyPayload = PluginSession.createReadyPayload(PluginSession.peerId, transportRole, instanceId, multiplayerGroupId)
-		if not active or generation ~= expectedGeneration or options ~= currentOptions then
-			return nil
-		end
-		local readyOk, readyResult = pcall(function()
-			return HttpService:RequestAsync({
-				Url = readyUrl,
-				Method = "POST",
-				Headers = {
-					["Content-Type"] = "application/json",
-				},
-				Body = HttpService:JSONEncode(readyPayload),
-			})
-		end)
-		if not active or generation ~= expectedGeneration or options ~= currentOptions then
-			return nil
-		end
-		local readyLogKey = `{currentOptions.serverUrl}|{PluginSession.peerId}`
-		if not readyOk then
-			local detail = HttpDiagnostics.formatRequestFailure(readyUrl, false, readyResult)
-			if not (readyFailureLogKeys[readyLogKey] ~= nil) then
-				readyFailureLogKeys[readyLogKey] = true
-				warn(`[robloxstudio-mcp] /ready failed for {instanceId}/{transportRole}: {detail}`)
-			end
-			scheduleReconnect(expectedGeneration, detail)
-			return nil
-		end
-		if not readyResult.Success then
-			local detail = HttpDiagnostics.formatRequestFailure(readyUrl, true, readyResult)
-			if not (readyFailureLogKeys[readyLogKey] ~= nil) then
-				readyFailureLogKeys[readyLogKey] = true
-				warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{transportRole}: {detail}`)
-			end
-			scheduleReconnect(expectedGeneration, detail, readyResult.StatusCode == 409)
+		local readyData = cachedReady or registerReady(currentOptions, expectedGeneration, true)
+		if readyData == nil or not active or generation ~= expectedGeneration or options ~= currentOptions then
 			return nil
 		end
-		local readyData = parseReadyResponse(readyResult.Body)
-		if readyData == nil or readyData.peerId ~= PluginSession.peerId or readyData.instanceId ~= instanceId or readyData.multiplayerGroupId ~= multiplayerGroupId then
-			scheduleReconnect(expectedGeneration, "Invalid /ready response: expected the registered Peer topology")
-			return nil
-		end
-		if readyFailureLogKeys[readyLogKey] ~= nil then
-			readyFailureLogKeys[readyLogKey] = nil
-			print(`[robloxstudio-mcp] /ready connected for {instanceId}/{readyData.assignedRole} via {currentOptions.serverUrl}`)
-		end
-		invokeCallback("event stream ready", function()
-			return currentOptions.onReady(readyData)
-		end)
+		local socketBaseUrl = string.gsub(currentOptions.serverUrl, "^http", "ws")
 		local createOk, createdClient = pcall(function()
-			return HttpService:CreateWebStreamClient(Enum.WebStreamClientType.SSE, {
-				Url = `{currentOptions.serverUrl}/events?peerId={PluginSession.peerId}`,
-				Method = "GET",
+			return HttpService:CreateWebStreamClient(Enum.WebStreamClientType.WebSocket, {
+				Url = `{socketBaseUrl}/studio?peerId={HttpService:UrlEncode(PluginSession.peerId)}&protocolVersion={PROTOCOL_VERSION}`,
 				Headers = {
-					Accept = "text/event-stream",
+					["X-Studio-Token"] = readyData.transportToken,
 				},
 			})
 		end)
 		if not createOk then
-			scheduleReconnect(expectedGeneration, `Failed to create event stream: {tostring(createdClient)}`)
+			scheduleReconnect(expectedGeneration, `Failed to create WebSocket: {tostring(createdClient)}`)
 			return nil
 		end
 		if not active or generation ~= expectedGeneration or options ~= currentOptions then
@@ -10595,16 +10866,20 @@ function connect(expectedGeneration)
 			end)
 			return nil
 		end
-		streamClient = createdClient
-		streamConnections = { createdClient.Opened:Connect(function(statusCode, _headers)
-			if not active or generation ~= expectedGeneration or streamClient ~= createdClient then
+		socketClient = createdClient
+		socketConnections = { createdClient.Opened:Connect(function(statusCode, _headers)
+			if not active or generation ~= expectedGeneration or socketClient ~= createdClient then
 				return nil
 			end
-			lastValidEventAt = tick()
-			if statusCode < 200 or statusCode >= 300 then
-				scheduleReconnect(expectedGeneration, `Event stream opened with HTTP {statusCode}`)
+			if statusCode ~= 101 and (statusCode < 200 or statusCode >= 300) then
+				if credentialsRejected(statusCode) then
+					cachedReady = nil
+				end
+				scheduleReconnect(expectedGeneration, `WebSocket opened with HTTP {statusCode}`)
 				return nil
 			end
+			socketOpen = true
+			lastValidEventAt = tick()
 			reconnectAttempt = 0
 			reportTransport({
 				state = "open",
@@ -10613,7 +10888,18 @@ function connect(expectedGeneration)
 			})
 			resumePendingResponses()
 		end), createdClient.MessageReceived:Connect(function(message)
-			if not active or generation ~= expectedGeneration or streamClient ~= createdClient then
+			if not active or generation ~= expectedGeneration or socketClient ~= createdClient then
+				return nil
+			end
+			local _message = message
+			if not (type(_message) == "string") then
+				scheduleReconnect(expectedGeneration, "Unsupported binary WebSocket frame (stage=request_receive); text JSON required")
+				return nil
+			end
+			if #message > MAX_FRAME_BYTES then
+				local detail = `WebSocket request frame exceeds limit (stage=request_receive, bytes={#message}, maxBytes={MAX_FRAME_BYTES}); execution not started`
+				warn(`[robloxstudio-mcp] {detail}`)
+				scheduleReconnect(expectedGeneration, detail)
 				return nil
 			end
 			local event = decodeMessage(message)
@@ -10621,37 +10907,42 @@ function connect(expectedGeneration)
 				return nil
 			end
 			lastValidEventAt = tick()
-			if event.kind == "heartbeat" then
-				invokeCallback("event stream heartbeat", function()
+			if event.kind == "ack" then
+				local _requestId = event.requestId
+				local pending = pendingResponses[_requestId]
+				if pending ~= nil and pending.serverUrl == currentOptions.serverUrl then
+					settleResponse(event.requestId, pending, event.disposition)
+				end
+			elseif event.kind == "heartbeat" then
+				invokeCallback("WebSocket heartbeat", function()
 					return currentOptions.onHeartbeat(event.timestamp)
 				end)
-				return nil
-			end
-			if event.kind == "cancel" then
+			elseif event.kind == "cancel" then
 				cancelRequest(event)
-				return nil
-			end
-			if event.kind == "request" then
-				dispatchRequest(event)
-				return nil
-			end
-			invokeCallback("event stream status", function()
-				return currentOptions.onStatus(event)
-			end)
-			if not event.knownPeer then
-				refresh()
+			elseif event.kind == "request" then
+				dispatchRequest(event, #message)
+			else
+				invokeCallback("WebSocket status", function()
+					return currentOptions.onStatus(event)
+				end)
+				if not event.knownPeer then
+					cachedReady = nil
+					scheduleReconnect(expectedGeneration, "WebSocket session is no longer registered")
+				end
 			end
 		end), createdClient.Error:Connect(function(statusCode, message)
-			if not active or generation ~= expectedGeneration or streamClient ~= createdClient then
+			if not active or generation ~= expectedGeneration or socketClient ~= createdClient then
 				return nil
 			end
-			local detail = if statusCode == 404 then `Event stream session is not registered: {message}` else `Event stream error {statusCode}: {message}`
-			scheduleReconnect(expectedGeneration, detail)
+			if credentialsRejected(statusCode) then
+				cachedReady = nil
+			end
+			scheduleReconnect(expectedGeneration, `WebSocket error {statusCode}: {message}`)
 		end), createdClient.Closed:Connect(function()
-			if not active or generation ~= expectedGeneration or streamClient ~= createdClient then
+			if not active or generation ~= expectedGeneration or socketClient ~= createdClient then
 				return nil
 			end
-			scheduleReconnect(expectedGeneration, "Event stream closed")
+			scheduleReconnect(expectedGeneration, "WebSocket closed")
 		end) }
 		lastValidEventAt = tick()
 		watchForSilence(expectedGeneration, createdClient)
@@ -10669,19 +10960,22 @@ local function start(newOptions)
 	generation += 1
 	connect(generation)
 end
-function refresh()
-	if not active or options == nil then
+local function refresh()
+	local currentOptions = options
+	if not active or currentOptions == nil or readyRefreshPending then
 		return nil
 	end
-	generation += 1
-	closeCurrentStream()
-	reconnectAttempt = 0
-	connect(generation)
+	-- Metadata changes must not close a healthy socket or make its reconnect
+	-- depend on RequestAsync quota. Proxy registration remains independent.
+	readyRefreshPending = true
+	local expectedGeneration = generation
+	task.spawn(function()
+		registerReady(currentOptions, expectedGeneration, false)
+		readyRefreshPending = false
+	end)
 end
--- EndTest can tear down a play DataModel without giving Plugin.Unloading a
--- usable execution window. Release the native WebStreamClient before the
--- yielding unregister request, but retain local request state and connection
--- options so a failed EndTest can register again and reconnect.
+-- EndTest may tear down this VM without an Unloading callback. Release the
+-- native socket before yielding to unregister; a failed EndTest can resume.
 local function suspendForShutdown()
 	local currentOptions = options
 	if not active or currentOptions == nil then
@@ -10691,7 +10985,8 @@ local function suspendForShutdown()
 	shutdownSuspended = true
 	generation += 1
 	reconnectAttempt = 0
-	closeCurrentStream()
+	closeCurrentSocket()
+	cachedReady = nil
 	disconnectSession(currentOptions)
 end
 local function resumeAfterShutdownFailure()
@@ -10715,9 +11010,8 @@ function stop()
 	for _, inFlight in inFlightRequests do
 		inFlight.cancelled = true
 	end
-	table.clear(inFlightRequests)
-	table.clear(pendingResponses)
-	closeCurrentStream()
+	closeCurrentSocket()
+	cachedReady = nil
 	table.clear(readyFailureLogKeys)
 	options = nil
 	reconnectAttempt = 0
@@ -10773,16 +11067,9 @@ end
 local function createInstanceId()
 	return formatId("instance", randomValue())
 end
-local function currentProcessInstanceId()
-	-- Roblox exposes process uptime through os.clock(). Quantizing the recovered
-	-- launch wall-clock to 10 ms gives every VM in one Studio process the same ID.
-	local launchTick = math.round((DateTime.now().UnixTimestampMillis - os.clock() * 1000) / 10)
-	return formatId("instance", launchTick)
-end
 return {
 	createPeerId = createPeerId,
 	createInstanceId = createInstanceId,
-	currentProcessInstanceId = currentProcessInstanceId,
 }
 ]]></string>
         </Properties>