@chrrxs/robloxstudio-mcp 3.0.2 → 3.0.3

package/studio-plugin/MCPPlugin.rbxmx

@@ -12,7 +12,7 @@ local Communication = TS.import(script, script, "modules", "Communication")
 local ClientBroker = TS.import(script, script, "modules", "ClientBroker")
 local ServerUrlSettings = TS.import(script, script, "modules", "ServerUrlSettings")
 local _EvalBridges = TS.import(script, script, "modules", "EvalBridges")
-local cleanupLegacyEditBridges = _EvalBridges.cleanupLegacyEditBridges
+local cleanupEditBridgeArtifacts = _EvalBridges.cleanupEditBridgeArtifacts
 local ensureRuntimeBridgeInstalled = _EvalBridges.ensureRuntimeBridgeInstalled
 local RuntimeLogBuffer = TS.import(script, script, "modules", "RuntimeLogBuffer")
 local StopPlayMonitor = TS.import(script, script, "modules", "StopPlayMonitor")
@@ -93,7 +93,7 @@ task.delay(TOOLBAR_REGISTRATION_DELAY_SECONDS, registerToolbarButton)
 task.delay(2, function()
 	local role = ClientBroker.forkRole()
 	if role == "edit" then
-		cleanupLegacyEditBridges()
+		cleanupEditBridgeArtifacts()
 	else
 		local result = ensureRuntimeBridgeInstalled()
 		if not result.installed then
@@ -265,7 +265,6 @@ local HttpService = _services.HttpService
 local Players = _services.Players
 local ReplicatedStorage = _services.ReplicatedStorage
 local RunService = _services.RunService
-local ServerStorage = _services.ServerStorage
 local RuntimeLogBuffer = TS.import(script, script.Parent, "RuntimeLogBuffer")
 local MemoryHandlers = TS.import(script, script.Parent, "handlers", "MemoryHandlers")
 local SceneAnalysisHandlers = TS.import(script, script.Parent, "handlers", "SceneAnalysisHandlers")
@@ -277,60 +276,15 @@ local BreakpointHandlers = TS.import(script, script.Parent, "handlers", "Breakpo
 local ScriptProfilerHandlers = TS.import(script, script.Parent, "handlers", "ScriptProfilerHandlers")
 local MicroProfilerHandlers = TS.import(script, script.Parent, "handlers", "MicroProfilerHandlers")
 local LuauExec = TS.import(script, script.Parent, "LuauExec")
-local State = TS.import(script, script.Parent, "State")
 local HttpDiagnostics = TS.import(script, script.Parent, "HttpDiagnostics")
+local PluginSession = TS.import(script, script.Parent, "PluginSession")
 local StudioTestService = game:GetService("StudioTestService")
--- Mirror of Communication.computeInstanceId() — duplicated here because the
--- client broker runs in the play-server DM where it can't easily import from
--- the edit-side module, and the place identifier must match what the edit-DM
--- plugin reports. Both use the same algorithm against the shared DataModel.
-local function computeInstanceId()
-	if game.PlaceId ~= 0 then
-		return `place:{tostring(game.PlaceId)}`
-	end
-	local existing = ServerStorage:GetAttribute("__MCPPlaceId")
-	if type(existing) == "string" and existing ~= "" then
-		return `anon:{existing}`
-	end
-	local fresh = HttpService:GenerateGUID(false)
-	pcall(function()
-		return ServerStorage:SetAttribute("__MCPPlaceId", fresh)
-	end)
-	return `anon:{fresh}`
-end
-local cachedPlaceName
-local function resolvePlaceName()
-	if cachedPlaceName ~= nil then
-		return cachedPlaceName
-	end
-	if game.PlaceId == 0 then
-		cachedPlaceName = game.Name
-		return cachedPlaceName
-	end
-	local MarketplaceService = game:GetService("MarketplaceService")
-	local ok, info = pcall(function()
-		return MarketplaceService:GetProductInfo(game.PlaceId)
-	end)
-	if ok and info ~= nil then
-		local name = info.Name
-		if type(name) == "string" and name ~= "" then
-			cachedPlaceName = name
-			return cachedPlaceName
-		end
-	end
-	return game.Name
-end
 -- The client peer cannot reach the MCP HTTP server - Roblox forbids
 -- HttpService:RequestAsync from the client DM even under PluginSecurity, and
 -- HttpEnabled reads as false there regardless of identity. So the server peer
--- brokers execute_luau requests to the client via a RemoteFunction it places
--- in ReplicatedStorage; each player gets a proxy "client" registration on the
--- MCP side, polled and dispatched by the server peer.
---
--- (Previously the server peer also registered an "edit-proxy" role to
--- intercept /api/stop-playtest and call StudioTestService:EndTest. That hack
--- is gone: stop now uses StopPlayMonitor with plugin:SetSetting cross-DM
--- signaling, which works regardless of MCP server state.)
+-- brokers client-targeted requests through a RemoteFunction it places
+-- in ReplicatedStorage; each player gets a logical proxy registration on the
+-- MCP side, multiplexed over the play-server peer's physical event stream.
 local DEFAULT_MCP_URL = "http://localhost:58741"
 local mcpUrl = DEFAULT_MCP_URL
 local BROKER_NAME = "__MCPClientBroker"
@@ -354,37 +308,6 @@ local CLIENT_BROKER_ALLOWED_ENDPOINTS = {
 	["/api/simulate-keyboard-input"] = true,
 	["/api/focus-viewport"] = true,
 }
--- Throttle re-ready calls per proxyId so a brief window of unknownInstance
--- polls doesn't cause a re-register stampede.
-local lastReadyByProxy = {}
-local postJson
-local function reRegisterProxy(proxyId, role)
-	local now = tick()
-	local _proxyId = proxyId
-	local _condition = lastReadyByProxy[_proxyId]
-	if _condition == nil then
-		_condition = 0
-	end
-	local last = _condition
-	if now - last < 2 then
-		return nil
-	end
-	local _proxyId_1 = proxyId
-	lastReadyByProxy[_proxyId_1] = now
-	pcall(function()
-		return postJson("/ready", {
-			pluginSessionId = proxyId,
-			instanceId = computeInstanceId(),
-			role = role,
-			placeId = game.PlaceId,
-			placeName = resolvePlaceName(),
-			dataModelName = game.Name,
-			isRunning = RunService:IsRunning(),
-			pluginVersion = State.CURRENT_VERSION,
-			pluginVariant = State.PLUGIN_VARIANT,
-		})
-	end)
-end
 local function forkRole()
 	if not RunService:IsRunning() then
 		return "edit"
@@ -394,7 +317,7 @@ local function forkRole()
 	end
 	return "client"
 end
-function postJson(endpoint, body)
+local function postJson(endpoint, body)
 	return pcall(function()
 		return HttpService:RequestAsync({
 			Url = `{mcpUrl}{endpoint}`,
@@ -414,9 +337,6 @@ local function setServerUrl(serverUrl)
 		mcpUrl = serverUrl
 	end
 end
-local function getServerUrl()
-	return mcpUrl
-end
 local function handleExecuteLuau(data)
 	local code = data and (data.code)
 	if type(code) == "string" == false or code == "" then
@@ -522,12 +442,16 @@ local function setupClientBroker()
 		return nil
 	end
 	rf.OnClientInvoke = function(payload)
-		-- Two payload shapes in the wild:
-		-- - {endpoint, data} from v2.10+ server-peer broker (this is the new
-		--   discriminated form that lets us dispatch on endpoint)
-		-- - {code} from pre-v2.10 server-peer broker (raw execute-luau payload)
-		-- The shapes coexist gracefully because we fall back to execute-luau
-		-- when endpoint is missing.
+		local _condition = not payload
+		if not _condition then
+			local _endpoint = payload.endpoint
+			_condition = not (type(_endpoint) == "string")
+		end
+		if _condition then
+			return {
+				error = "Client broker request is missing its endpoint.",
+			}
+		end
 		if payload and payload.endpoint == "/api/get-runtime-logs" then
 			return handleGetRuntimeLogs(payload.data)
 		end
@@ -570,13 +494,19 @@ local function setupClientBroker()
 		if payload and payload.endpoint == "/api/eval-runtime" then
 			return EvalRuntimeHandlers.evalRuntime(payload.data or {})
 		end
-		-- Legacy: raw execute-luau payload at the top level.
-		return handleExecuteLuau(payload)
+		return {
+			error = `Unsupported client broker endpoint: {payload.endpoint}`,
+		}
 	end
 end
+local INITIAL_PROXY_RETRY_DELAY_SECONDS = 0.5
+local MAX_PROXY_RETRY_DELAY_SECONDS = 5
 local proxyByPlayer = {}
+local proxyBySessionId = {}
 local proxyRegisterFailuresByPlayer = {}
+local pendingProxyDisconnects = {}
 local serverBrokerStarted = false
+local queueProxyDisconnect
 local function unregisterProxy(player, entry)
 	local _condition = entry
 	if _condition == nil then
@@ -587,122 +517,154 @@ local function unregisterProxy(player, entry)
 	if not proxy then
 		return nil
 	end
+	proxy.generation += 1
 	local _player = player
 	proxyByPlayer[_player] = nil
+	local _pluginSessionId = proxy.pluginSessionId
+	proxyBySessionId[_pluginSessionId] = nil
 	local _player_1 = player
 	proxyRegisterFailuresByPlayer[_player_1] = nil
-	postJson("/disconnect", {
-		pluginSessionId = proxy.pluginSessionId,
-	})
+	queueProxyDisconnect(proxy.pluginSessionId)
 end
 local function disconnectAllProxies()
 	for player, entry in proxyByPlayer do
 		unregisterProxy(player, entry)
 	end
 	table.clear(proxyByPlayer)
+	table.clear(proxyBySessionId)
 	table.clear(proxyRegisterFailuresByPlayer)
 end
-local function pollProxy(proxyId, player, rf)
-	while true do
-		local _condition = player.Parent ~= nil
-		if _condition then
-			local _player = player
-			_condition = proxyByPlayer[_player] ~= nil
-		end
+local function proxyRetryDelay(attempt)
+	return math.min(INITIAL_PROXY_RETRY_DELAY_SECONDS * math.pow(2, math.max(attempt - 1, 0)), MAX_PROXY_RETRY_DELAY_SECONDS)
+end
+local function deliverProxyDisconnect(pluginSessionId, attempt)
+	local _pluginSessionId = pluginSessionId
+	if not (pendingProxyDisconnects[_pluginSessionId] ~= nil) then
+		return nil
+	end
+	local ok, response = postJson("/disconnect", {
+		pluginSessionId = pluginSessionId,
+	})
+	if ok and response and response.Success then
+		local _pluginSessionId_1 = pluginSessionId
+		pendingProxyDisconnects[_pluginSessionId_1] = nil
+		return nil
+	end
+	task.delay(proxyRetryDelay(attempt + 1), function()
+		deliverProxyDisconnect(pluginSessionId, attempt + 1)
+	end)
+end
+function queueProxyDisconnect(pluginSessionId)
+	local _pluginSessionId = pluginSessionId
+	if pendingProxyDisconnects[_pluginSessionId] ~= nil then
+		return nil
+	end
+	local _pluginSessionId_1 = pluginSessionId
+	pendingProxyDisconnects[_pluginSessionId_1] = true
+	task.spawn(deliverProxyDisconnect, pluginSessionId, 0)
+end
+local function parseAssignedRole(body)
+	local decodeOk, decoded = pcall(function()
+		return HttpService:JSONDecode(body)
+	end)
+	if not decodeOk or not (type(decoded) == "table") then
+		return nil
+	end
+	local ready = decoded
+	if ready.success ~= true then
+		return nil
+	end
+	local _assignedRole = ready.assignedRole
+	local _condition = type(_assignedRole) == "string"
+	if _condition then
+		_condition = ready.assignedRole ~= ""
+	end
+	return if _condition then ready.assignedRole else nil
+end
+local registerProxyEntry
+local function scheduleProxyRetry(entry)
+	entry.retryAttempt += 1
+	local expectedGeneration = entry.generation
+	task.delay(proxyRetryDelay(entry.retryAttempt), function()
+		local _player = entry.player
+		local _condition = proxyByPlayer[_player] ~= entry
 		if not _condition then
-			break
+			_condition = entry.generation ~= expectedGeneration or entry.registered or entry.registering or entry.player.Parent == nil or not RunService:IsRunning()
 		end
-		if not RunService:IsRunning() then
-			unregisterProxy(player)
-			break
+		if _condition then
+			return nil
 		end
-		local nextPollDelay = 0.5
-		local ok, res = pcall(function()
-			local requestOptions = {
-				Url = `{mcpUrl}/poll?pluginSessionId={proxyId}&pollMode=long`,
-				Method = "GET",
-				Headers = {
-					["Content-Type"] = "application/json",
-				},
-				Timeout = State.POLL_REQUEST_TIMEOUT_SECONDS,
-			}
-			return HttpService:RequestAsync(requestOptions)
-		end)
-		-- RequestAsync may yield for the full long-poll window. Never apply a
-		-- stale response to a player whose proxy was removed or replaced.
-		local _player = player
-		local currentProxy = proxyByPlayer[_player]
-		local _condition_1 = player.Parent == nil
-		if not _condition_1 then
-			local _result = currentProxy
-			if _result ~= nil then
-				_result = _result.pluginSessionId
-			end
-			_condition_1 = _result ~= proxyId
+		registerProxyEntry(entry)
+	end)
+end
+local function failProxyRegistration(entry, detail)
+	entry.registered = false
+	local _player = entry.player
+	if not (proxyRegisterFailuresByPlayer[_player] ~= nil) then
+		local _player_1 = entry.player
+		proxyRegisterFailuresByPlayer[_player_1] = true
+		warn(`[robloxstudio-mcp] proxy register failed for {entry.player.Name}: {detail}`)
+	end
+	scheduleProxyRetry(entry)
+end
+function registerProxyEntry(entry)
+	local _condition = entry.registering
+	if not _condition then
+		local _player = entry.player
+		_condition = proxyByPlayer[_player] ~= entry
+		if not _condition then
+			_condition = entry.player.Parent == nil or not RunService:IsRunning()
 		end
-		if _condition_1 then
-			break
+	end
+	if _condition then
+		return nil
+	end
+	entry.registering = true
+	local expectedGeneration = entry.generation
+	local requestedRole = if entry.role == "client" then "client" else entry.role
+	local readyPayload = PluginSession.createReadyPayload(entry.pluginSessionId, requestedRole)
+	local _player = entry.player
+	if proxyByPlayer[_player] ~= entry then
+		return nil
+	end
+	if entry.generation ~= expectedGeneration then
+		if not entry.registering then
+			task.spawn(registerProxyEntry, entry)
 		end
-		if ok and res and (res.Success or res.StatusCode == 503) then
-			local okJson, body = pcall(function()
-				return HttpService:JSONDecode(res.Body)
-			end)
-			if okJson and body then
-				-- Server lost our proxy registration (process restart, etc.) -
-				-- re-register so the next poll cycle starts routing again.
-				if body.knownInstance == false then
-					reRegisterProxy(proxyId, "client")
-				end
-				if body.request and body.requestId ~= nil then
-					local request = body.request
-					local response
-					local _endpoint = request.endpoint
-					if CLIENT_BROKER_ALLOWED_ENDPOINTS[_endpoint] ~= nil then
-						-- Forward as a discriminated envelope so the client-side
-						-- OnClientInvoke knows which endpoint it's serving.
-						local envelope = {
-							endpoint = request.endpoint,
-							data = request.data,
-						}
-						local okInvoke, invokeRes = pcall(function()
-							return rf:InvokeClient(player, envelope)
-						end)
-						if okInvoke then
-							response = if invokeRes ~= nil then invokeRes else {
-								success = false,
-								error = "nil response",
-							}
-						else
-							response = {
-								success = false,
-								error = `InvokeClient failed: {tostring(invokeRes)}`,
-							}
-						end
-					else
-						local allowed = {}
-						for ep in CLIENT_BROKER_ALLOWED_ENDPOINTS do
-							table.insert(allowed, ep)
-						end
-						response = {
-							error = `Client-proxy does not forward {tostring(request.endpoint)}. ` .. `Allowed: {table.concat(allowed, ", ")}.`,
-						}
-					end
-					postJson("/response", {
-						requestId = body.requestId,
-						response = response,
-					})
-				end
-				if res.Success and body.pollMode == "long" and body.knownInstance ~= false and body.request == nil then
-					nextPollDelay = 0
-				end
-			end
+		return nil
+	end
+	local ok, res = postJson("/ready", readyPayload)
+	local _player_1 = entry.player
+	if proxyByPlayer[_player_1] ~= entry then
+		if ok and res and res.Success then
+			queueProxyDisconnect(entry.pluginSessionId)
 		end
-		if nextPollDelay > 0 then
-			task.wait(nextPollDelay)
-		else
-			-- Yield one scheduler turn before replacing a completed long poll.
-			task.wait()
+		return nil
+	end
+	if entry.generation ~= expectedGeneration then
+		if not entry.registering then
+			task.spawn(registerProxyEntry, entry)
 		end
+		return nil
+	end
+	entry.registering = false
+	if not ok or not res or not res.Success then
+		failProxyRegistration(entry, formatPostJsonFailure("/ready", ok, res))
+		return nil
+	end
+	local assignedRole = parseAssignedRole(res.Body)
+	if assignedRole == nil then
+		failProxyRegistration(entry, "invalid /ready response: expected success=true and a non-empty assignedRole")
+		return nil
+	end
+	entry.role = assignedRole
+	entry.registered = true
+	entry.retryAttempt = 0
+	local _player_2 = entry.player
+	if proxyRegisterFailuresByPlayer[_player_2] ~= nil then
+		local _player_3 = entry.player
+		proxyRegisterFailuresByPlayer[_player_3] = nil
+		print(`[robloxstudio-mcp] proxy registered for {entry.player.Name} as {assignedRole} via {mcpUrl}`)
 	end
 end
 local function registerProxy(player, rf)
@@ -710,48 +672,89 @@ local function registerProxy(player, rf)
 	if proxyByPlayer[_player] ~= nil then
 		return nil
 	end
-	local proxyId = HttpService:GenerateGUID(false)
-	local ok, res = postJson("/ready", {
-		pluginSessionId = proxyId,
-		instanceId = computeInstanceId(),
+	local entry = {
+		player = player,
+		remote = rf,
+		pluginSessionId = HttpService:GenerateGUID(false),
 		role = "client",
-		placeId = game.PlaceId,
-		placeName = resolvePlaceName(),
-		dataModelName = game.Name,
-		isRunning = RunService:IsRunning(),
-		pluginVersion = State.CURRENT_VERSION,
-		pluginVariant = State.PLUGIN_VARIANT,
-	})
-	if not ok or not res or not res.Success then
-		local _player_1 = player
-		proxyRegisterFailuresByPlayer[_player_1] = true
-		warn(`[robloxstudio-mcp] proxy register failed for {player.Name}: {formatPostJsonFailure("/ready", ok, res)}`)
-		return nil
+		registered = false,
+		registering = false,
+		retryAttempt = 0,
+		generation = 0,
+	}
+	local _player_1 = player
+	proxyByPlayer[_player_1] = entry
+	local _pluginSessionId = entry.pluginSessionId
+	proxyBySessionId[_pluginSessionId] = entry
+	task.spawn(registerProxyEntry, entry)
+end
+local function refreshAllLogicalRegistrations()
+	for _, entry in proxyByPlayer do
+		entry.generation += 1
+		entry.registered = false
+		entry.registering = false
+		entry.retryAttempt = 0
+		task.spawn(registerProxyEntry, entry)
+	end
+end
+local function dispatchClientRequest(logicalSessionId, target, endpoint, data)
+	local _logicalSessionId = logicalSessionId
+	local entry = proxyBySessionId[_logicalSessionId]
+	local _condition = not entry
+	if not _condition then
+		local _player = entry.player
+		_condition = proxyByPlayer[_player] ~= entry
 	end
-	local body = HttpService:JSONDecode(res.Body)
-	local _condition = body.assignedRole
-	if _condition == nil then
-		_condition = "client"
+	if _condition then
+		return {
+			error = `Client proxy {target} ({logicalSessionId}) is not registered.`,
+		}
 	end
-	local assigned = _condition
-	local _player_1 = player
-	local _arg1 = {
-		pluginSessionId = proxyId,
-		role = assigned,
+	if entry.role == "client" then
+		local assignedClientRole = string.match(target, "^client%-%d+$")
+		if assignedClientRole ~= nil then
+			entry.role = target
+		end
+	end
+	if entry.role ~= target then
+		return {
+			error = `Client proxy {logicalSessionId} is registered as {entry.role}, not {target}.`,
+		}
+	end
+	if entry.player.Parent == nil or not RunService:IsRunning() then
+		unregisterProxy(entry.player, entry)
+		return {
+			error = `Client proxy {target} is no longer available.`,
+		}
+	end
+	local _endpoint = endpoint
+	if not (CLIENT_BROKER_ALLOWED_ENDPOINTS[_endpoint] ~= nil) then
+		local allowed = {}
+		for allowedEndpoint in CLIENT_BROKER_ALLOWED_ENDPOINTS do
+			table.insert(allowed, allowedEndpoint)
+		end
+		return {
+			error = `Client-proxy does not forward {endpoint}. Allowed: {table.concat(allowed, ", ")}.`,
+		}
+	end
+	local envelope = {
+		endpoint = endpoint,
+		data = data,
 	}
-	proxyByPlayer[_player_1] = _arg1
-	local _player_2 = player
-	if proxyRegisterFailuresByPlayer[_player_2] ~= nil then
-		local _player_3 = player
-		proxyRegisterFailuresByPlayer[_player_3] = nil
-		print(`[robloxstudio-mcp] proxy registered for {player.Name} as {assigned} via {mcpUrl}`)
+	local invokeOk, invokeResult = pcall(function()
+		return entry.remote:InvokeClient(entry.player, envelope)
+	end)
+	if not invokeOk then
+		return {
+			success = false,
+			error = `InvokeClient failed: {tostring(invokeResult)}`,
+		}
 	end
-	task.spawn(pollProxy, proxyId, player, rf)
+	return if invokeResult ~= nil then invokeResult else {
+		success = false,
+		error = "nil response",
+	}
 end
--- (Removed: startEditProxyLoop. The play-server DM no longer registers an
--- "edit-proxy" peer with the MCP server. stop_playtest now uses a cross-DM
--- plugin:SetSetting request consumed by StopPlayMonitor in the play-server DM,
--- which doesn't depend on MCP server state or peer registration at all.)
 local function setupServerBroker()
 	if serverBrokerStarted then
 		return nil
@@ -782,11 +785,11 @@ local function setupServerBroker()
 	end)
 end
 return {
-	MCP_URL = DEFAULT_MCP_URL,
 	DEFAULT_MCP_URL = DEFAULT_MCP_URL,
-	getServerUrl = getServerUrl,
 	setServerUrl = setServerUrl,
 	disconnectAllProxies = disconnectAllProxies,
+	refreshAllLogicalRegistrations = refreshAllLogicalRegistrations,
+	dispatchClientRequest = dispatchClientRequest,
 	forkRole = forkRole,
 	setupClientBroker = setupClientBroker,
 	setupServerBroker = setupServerBroker,
@@ -802,11 +805,10 @@ local TS = require(script.Parent.Parent.include.RuntimeLib)
 local _services = TS.import(script, script.Parent.Parent, "node_modules", "@rbxts", "services")
 local HttpService = _services.HttpService
 local RunService = _services.RunService
-local ServerStorage = _services.ServerStorage
 local State = TS.import(script, script.Parent, "State")
 local Utils = TS.import(script, script.Parent, "Utils")
 local UI = TS.import(script, script.Parent, "UI")
-local cleanupLegacyEditBridges = TS.import(script, script.Parent, "EvalBridges").cleanupLegacyEditBridges
+local cleanupEditBridgeArtifacts = TS.import(script, script.Parent, "EvalBridges").cleanupEditBridgeArtifacts
 local QueryHandlers = TS.import(script, script.Parent, "handlers", "QueryHandlers")
 local PropertyHandlers = TS.import(script, script.Parent, "handlers", "PropertyHandlers")
 local ScriptHandlers = TS.import(script, script.Parent, "handlers", "ScriptHandlers")
@@ -826,79 +828,11 @@ local GenerateModelHandlers = TS.import(script, script.Parent, "handlers", "Gene
 local EvalRuntimeHandlers = TS.import(script, script.Parent, "handlers", "EvalRuntimeHandlers")
 local ClientBroker = TS.import(script, script.Parent, "ClientBroker")
 local ServerUrlSettings = TS.import(script, script.Parent, "ServerUrlSettings")
-local HttpDiagnostics = TS.import(script, script.Parent, "HttpDiagnostics")
--- Per-plugin-load random GUID. Used as the /poll URL param so the server
--- can tell our polls apart from any other plugin's polls. Not user-facing —
--- MCP tools and the LLM operate on instanceId (the place identifier).
-local pluginSessionId = HttpService:GenerateGUID(false)
--- Place-level identifier shared by every plugin running in DataModels of
--- the same place file (edit DM + playtest server DM + playtest clients).
--- Format: "place:<PlaceId>" when published, "anon:<UUID>" for unpublished
--- places where the UUID lives on ServerStorage's __MCPPlaceId attribute
--- and travels with the .rbxl.
-local MCP_PLACE_ID_ATTRIBUTE = "__MCPPlaceId"
-local function computeInstanceId()
-	if game.PlaceId ~= 0 then
-		return `place:{tostring(game.PlaceId)}`
-	end
-	local existing = ServerStorage:GetAttribute(MCP_PLACE_ID_ATTRIBUTE)
-	if type(existing) == "string" and existing ~= "" then
-		return `anon:{existing}`
-	end
-	local fresh = HttpService:GenerateGUID(false)
-	pcall(function()
-		return ServerStorage:SetAttribute(MCP_PLACE_ID_ATTRIBUTE, fresh)
-	end)
-	return `anon:{fresh}`
-end
+local PluginSession = TS.import(script, script.Parent, "PluginSession")
+local StudioEventStream = TS.import(script, script.Parent, "StudioEventStream")
 local assignedRole
-local hasVersionMismatch = false
-local lastVersionMismatchWarningKey
 local lastReadyInstanceId
-local readyFailureLogKeys = {}
-local retryingDuplicateReady = false
-local pollEpoch = 0
--- Cache the published place name from MarketplaceService:GetProductInfo so
--- /ready can carry a friendly identifier (e.g. "Natural Disasters") distinct
--- from game.Name (the DataModel name, often "Place1" in edit). We only fetch
--- once per plugin load; the published name doesn't change mid-session.
-local cachedPlaceName
-local cachedPlaceNamePlaceId
-local function resolvePlaceName()
-	if cachedPlaceName ~= nil and cachedPlaceNamePlaceId == game.PlaceId then
-		return cachedPlaceName
-	end
-	cachedPlaceName = nil
-	cachedPlaceNamePlaceId = game.PlaceId
-	if game.PlaceId == 0 then
-		cachedPlaceName = game.Name
-		return cachedPlaceName
-	end
-	local MarketplaceService = game:GetService("MarketplaceService")
-	local ok, info = pcall(function()
-		return MarketplaceService:GetProductInfo(game.PlaceId)
-	end)
-	if ok and info ~= nil then
-		local name = info.Name
-		if type(name) == "string" and name ~= "" then
-			cachedPlaceName = name
-			return cachedPlaceName
-		end
-	end
-	-- Don't cache failures — could be transient (offline, rate-limited).
-	-- Next /ready will retry. Return game.Name as fallback.
-	return game.Name
-end
-local function detectRole()
-	if not RunService:IsRunning() then
-		return "edit"
-	end
-	if RunService:IsServer() then
-		return "server"
-	end
-	return "client"
-end
-local initialRole = detectRole()
+local initialRole = PluginSession.getRole()
 local routeMap = {
 	["/api/file-tree"] = QueryHandlers.getFileTree,
 	["/api/search-files"] = QueryHandlers.searchFiles,
@@ -958,35 +892,6 @@ local function processRequest(request)
 		}
 	end
 end
-local function sendResponse(conn, requestId, responseData)
-	local responseUrl = `{conn.serverUrl}/response`
-	local encodeOk, encoded = pcall(function()
-		return HttpService:JSONEncode({
-			requestId = requestId,
-			response = responseData,
-		})
-	end)
-	local body = if encodeOk then encoded else HttpService:JSONEncode({
-		requestId = requestId,
-		error = `Plugin response serialization failed: {tostring(encoded)}`,
-	})
-	if not encodeOk then
-		warn(`[robloxstudio-mcp] Failed to serialize response {requestId}: {tostring(encoded)}`)
-	end
-	local requestOk, requestResult = pcall(function()
-		return HttpService:RequestAsync({
-			Url = responseUrl,
-			Method = "POST",
-			Headers = {
-				["Content-Type"] = "application/json",
-			},
-			Body = body,
-		})
-	end)
-	if not requestOk or not requestResult.Success then
-		warn(`[robloxstudio-mcp] Failed to deliver response {requestId}: {HttpDiagnostics.formatRequestFailure(responseUrl, requestOk, requestResult)}`)
-	end
-end
 local function getConnectionStatus()
 	local conn = State.getActiveConnection()
 	if not conn.isActive then
@@ -1000,341 +905,141 @@ local function getConnectionStatus()
 	end
 	return "connecting"
 end
--- Throttle for re-issuing /ready after the server reports knownInstance=false.
--- Without this, every poll during the brief window where the server has just
--- restarted but hasn't seen our re-ready yet would fire a duplicate /ready.
-local lastReadyPostAt = 0
--- game.Name and game.PlaceId can both settle after plugin load. PlaceId also
--- changes when an unpublished file is published while MCP is already active.
--- Re-fire /ready so the bridge can migrate anon:<uuid> to place:<PlaceId>.
-local nameChangeConn
-local placeIdChangeConn
-local sendReady
-local function ensureIdentityWatcher(conn)
-	if not nameChangeConn then
-		local okSig, signal = pcall(function()
-			return game:GetPropertyChangedSignal("Name")
-		end)
-		if okSig and signal then
-			nameChangeConn = signal:Connect(function()
-				-- sendReady has its own 2s throttle, so rapid burst changes coalesce.
-				sendReady(conn)
-			end)
-		end
+local function dispatchStreamRequest(request)
+	if request.logicalSessionId ~= PluginSession.id then
+		return ClientBroker.dispatchClientRequest(request.logicalSessionId, request.target, request.endpoint, request.data)
 	end
-	if not placeIdChangeConn then
-		local okSig, signal = pcall(function()
-			return game:GetPropertyChangedSignal("PlaceId")
-		end)
-		if okSig and signal then
-			placeIdChangeConn = signal:Connect(function()
-				cachedPlaceName = nil
-				cachedPlaceNamePlaceId = nil
-				sendReady(conn)
-			end)
-		end
+	local _condition = assignedRole
+	if _condition == nil then
+		_condition = PluginSession.getRole()
+	end
+	local localRole = _condition
+	if request.target ~= localRole then
+		return {
+			error = `Physical plugin session is registered as {localRole}, not {request.target}.`,
+		}
 	end
+	return processRequest({
+		endpoint = request.endpoint,
+		data = request.data,
+	})
 end
-function sendReady(conn)
-	local now = tick()
-	-- Normal identity refreshes stay conservatively throttled. Once a stale
-	-- predecessor causes 409, retry once per second so takeover follows the
-	-- server's short inactivity lease without another two seconds of jitter.
-	local readyInterval = if retryingDuplicateReady then 1 else 2
-	if now - lastReadyPostAt < readyInterval then
+local function handleReady(response)
+	local conn = State.getActiveConnection()
+	if not conn.isActive then
 		return nil
 	end
-	lastReadyPostAt = now
-	local instanceId = computeInstanceId()
-	task.spawn(function()
-		local readyOk, readyResult = pcall(function()
-			return HttpService:RequestAsync({
-				Url = `{conn.serverUrl}/ready`,
-				Method = "POST",
-				Headers = {
-					["Content-Type"] = "application/json",
-				},
-				Body = HttpService:JSONEncode({
-					pluginSessionId = pluginSessionId,
-					instanceId = instanceId,
-					role = detectRole(),
-					placeId = game.PlaceId,
-					placeName = resolvePlaceName(),
-					dataModelName = game.Name,
-					isRunning = RunService:IsRunning(),
-					pluginVersion = State.CURRENT_VERSION,
-					pluginVariant = State.PLUGIN_VARIANT,
-					pluginReady = true,
-					timestamp = tick(),
-				}),
-			})
-		end)
-		local readyUrl = `{conn.serverUrl}/ready`
-		local readyRole = detectRole()
-		local readyLogKey = `{conn.serverUrl}|{instanceId}|{readyRole}`
-		if not readyOk then
-			local shouldLog = not (readyFailureLogKeys[readyLogKey] ~= nil)
-			readyFailureLogKeys[readyLogKey] = true
-			if shouldLog then
-				warn(`[robloxstudio-mcp] /ready failed for {instanceId}/{readyRole}: {HttpDiagnostics.formatRequestFailure(readyUrl, readyOk, readyResult)}`)
-			end
-			return nil
-		end
-		if not readyResult.Success then
-			local reason = HttpDiagnostics.formatRequestFailure(readyUrl, true, readyResult)
-			local shouldLog = not (readyFailureLogKeys[readyLogKey] ~= nil)
-			readyFailureLogKeys[readyLogKey] = true
-			-- A predecessor can remain registered briefly when Studio exits before
-			-- its asynchronous /disconnect completes. Keep polling and retrying
-			-- /ready: the server will take us over once the predecessor has stopped
-			-- polling, while a genuinely active duplicate continues to hold routing.
-			if readyResult.StatusCode == 409 then
-				retryingDuplicateReady = true
-				local ui = UI.getElements()
-				ui.statusLabel.Text = "Waiting for previous instance"
-				ui.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
-				ui.detailStatusLabel.Text = reason
-				ui.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
-				if shouldLog then
-					warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{readyRole}: {reason}`)
-				end
-				return nil
-			end
-			if shouldLog then
-				warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{readyRole}: {reason}`)
-			end
-			return nil
-		end
-		retryingDuplicateReady = false
-		local parseOk, readyData = pcall(function()
-			return HttpService:JSONDecode(readyResult.Body)
-		end)
-		local _value = parseOk and readyData.assignedRole
-		if _value ~= "" and _value then
-			assignedRole = readyData.assignedRole
-		end
-		local _condition = parseOk
-		if _condition then
-			local _instanceId = readyData.instanceId
-			_condition = type(_instanceId) == "string"
-			if _condition then
-				_condition = readyData.instanceId ~= ""
-			end
-		end
-		lastReadyInstanceId = if _condition then readyData.instanceId else instanceId
-		ServerUrlSettings.rememberServerUrl(conn.serverUrl)
-		local _condition_1 = assignedRole
-		if _condition_1 == nil then
-			_condition_1 = detectRole()
-		end
-		local connectedRole = _condition_1
-		if readyFailureLogKeys[readyLogKey] ~= nil then
-			readyFailureLogKeys[readyLogKey] = nil
-			print(`[robloxstudio-mcp] /ready connected for {instanceId}/{connectedRole} via {conn.serverUrl}`)
-		end
-	end)
+	assignedRole = response.assignedRole
+	lastReadyInstanceId = response.instanceId
+	ServerUrlSettings.rememberServerUrl(conn.serverUrl)
+	ClientBroker.refreshAllLogicalRegistrations()
 end
-local function pollForRequests()
+local function handleStatus(status)
 	local conn = State.getActiveConnection()
 	if not conn.isActive then
 		return nil
 	end
-	if conn.isPolling then
+	conn.lastHttpOk = true
+	conn.lastMcpOk = status.mcpConnected
+	conn.consecutiveFailures = 0
+	conn.currentRetryDelay = 0.5
+	if status.mcpConnected then
+		conn.mcpWaitStartTime = nil
+	elseif conn.mcpWaitStartTime == nil then
+		conn.mcpWaitStartTime = tick()
+	end
+	UI.updateUIState()
+	UI.updateToolbarIcon()
+end
+local function handleHeartbeat(_timestamp)
+	if not State.getActiveConnection().isActive then
 		return nil
 	end
-	local epoch = pollEpoch
-	conn.isPolling = true
-	local success, result = pcall(function()
-		local requestOptions = {
-			Url = `{conn.serverUrl}/poll?pluginSessionId={pluginSessionId}&pollMode=long`,
-			Method = "GET",
-			Headers = {
-				["Content-Type"] = "application/json",
-			},
-			Timeout = State.POLL_REQUEST_TIMEOUT_SECONDS,
-		}
-		return HttpService:RequestAsync(requestOptions)
-	end)
-	-- A held request can finish after deactivate/reactivate. Only the current
-	-- lifecycle epoch may mutate connection state or clear a newer poll's lock.
-	if epoch ~= pollEpoch or not conn.isActive then
+	UI.updateUIState()
+end
+local function handleTransportUpdate(update)
+	local conn = State.getActiveConnection()
+	if not conn.isActive then
 		return nil
 	end
-	conn.isPolling = false
-	local ui = UI.getElements()
-	UI.updateToolbarIcon()
-	if success and (result.Success or result.StatusCode == 503) then
+	if update.state == "open" then
+		conn.lastHttpOk = true
+		conn.lastMcpOk = false
 		conn.consecutiveFailures = 0
 		conn.currentRetryDelay = 0.5
-		conn.lastSuccessfulConnection = tick()
-		local data = HttpService:JSONDecode(result.Body)
-		conn.lastPoll = tick()
-		if result.Success and data.pollMode == "long" and data.knownInstance ~= false and data.request == nil then
-			-- The server held this request until work or timeout, so immediately
-			-- replace it instead of reintroducing the legacy 500 ms idle gap.
-			conn.lastPoll = 0
+		conn.mcpWaitStartTime = tick()
+	else
+		conn.lastHttpOk = false
+		conn.lastMcpOk = false
+		conn.consecutiveFailures = update.attempt
+		if update.retryDelay > 0 then
+			conn.currentRetryDelay = update.retryDelay
 		end
-		local mcpConnected = data.mcpConnected == true
-		conn.lastHttpOk = true
-		conn.lastMcpOk = mcpConnected
-		local _condition = data.serverVersion
+		conn.mcpWaitStartTime = nil
+	end
+	UI.updateUIState()
+	UI.updateToolbarIcon()
+	if update.state == "waiting-duplicate" then
+		local ui = UI.getElements()
+		ui.statusLabel.Text = "Waiting for previous instance"
+		ui.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
+		local _condition = update.detail
 		if _condition == nil then
-			_condition = "unknown"
-		end
-		local serverVersion = _condition
-		if data.versionMismatch == true then
-			hasVersionMismatch = true
-			local warningKey = `{State.CURRENT_VERSION}:{serverVersion}`
-			if lastVersionMismatchWarningKey ~= warningKey then
-				lastVersionMismatchWarningKey = warningKey
-				warn(`[robloxstudio-mcp] Version mismatch: Studio plugin v{State.CURRENT_VERSION} / MCP v{serverVersion}. Run npx -y @chrrxs/robloxstudio-mcp@latest --auto-install-plugin and restart Studio.`)
-			end
-			UI.showBanner("version-mismatch", `Plugin v{State.CURRENT_VERSION} / MCP v{serverVersion} mismatch`)
-		elseif hasVersionMismatch then
-			hasVersionMismatch = false
-			UI.hideBanner("version-mismatch")
-		end
-		-- Server tells us when its in-memory instances map doesn't have us
-		-- (e.g. after an MCP process restart). Re-issue /ready immediately so
-		-- target=server/client-N start routing again. The throttle inside
-		-- sendReady() prevents duplicate registrations while the server
-		-- catches up.
-		if data.knownInstance == false then
-			sendReady(conn)
-		end
-		local el = ui
-		el.step1Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
-		el.step1Label.Text = "HTTP server (OK)"
-		local _condition_1 = mcpConnected
-		if _condition_1 then
-			local _value = (string.find(el.statusLabel.Text, "Connected"))
-			_condition_1 = not (_value ~= 0 and _value == _value and _value)
+			_condition = "The previous plugin instance is still active."
 		end
-		if _condition_1 then
-			el.statusLabel.Text = "Connected"
-			el.statusLabel.TextColor3 = Color3.fromRGB(34, 197, 94)
-			el.statusIndicator.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
-			el.statusPulse.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
-			el.statusText.Text = "ONLINE"
-			el.detailStatusLabel.Text = "HTTP: OK  MCP: OK"
-			el.detailStatusLabel.TextColor3 = Color3.fromRGB(34, 197, 94)
-			el.step2Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
-			el.step2Label.Text = "MCP bridge (OK)"
-			el.step3Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
-			el.step3Label.Text = "Commands (OK)"
-			conn.mcpWaitStartTime = nil
-			el.troubleshootLabel.Visible = false
-			UI.stopPulseAnimation()
-		elseif not mcpConnected then
-			el.statusLabel.Text = "Waiting for MCP server"
-			el.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
-			el.statusIndicator.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.statusPulse.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.statusText.Text = "WAITING"
-			el.detailStatusLabel.Text = "HTTP: OK  MCP: ..."
-			el.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
-			el.step2Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.step2Label.Text = "MCP bridge (waiting...)"
-			el.step3Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.step3Label.Text = "Commands (waiting...)"
-			if conn.mcpWaitStartTime == nil then
-				conn.mcpWaitStartTime = tick()
-			end
-			local _exp = tick()
-			local _condition_2 = conn.mcpWaitStartTime
-			if _condition_2 == nil then
-				_condition_2 = tick()
-			end
-			local elapsed = _exp - _condition_2
-			el.troubleshootLabel.Visible = elapsed > 8
-			UI.startPulseAnimation()
-		end
-		if data.request and mcpConnected then
-			task.spawn(function()
-				local ok, response = pcall(function()
-					return processRequest(data.request)
-				end)
-				if ok then
-					sendResponse(conn, data.requestId, response)
-				else
-					sendResponse(conn, data.requestId, {
-						error = tostring(response),
-					})
-				end
+		ui.detailStatusLabel.Text = _condition
+		ui.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
+	end
+end
+local nameChangeConn
+local placeIdChangeConn
+local function ensureIdentityWatchers()
+	if not nameChangeConn then
+		local signalOk, signal = pcall(function()
+			return game:GetPropertyChangedSignal("Name")
+		end)
+		if signalOk and signal then
+			nameChangeConn = signal:Connect(function()
+				return StudioEventStream.refresh()
 			end)
 		end
-	elseif conn.isActive then
-		conn.lastPoll = tick()
-		conn.consecutiveFailures += 1
-		if conn.consecutiveFailures > 1 then
-			conn.currentRetryDelay = math.min(conn.currentRetryDelay * conn.retryBackoffMultiplier, conn.maxRetryDelay)
-		end
-		local el = ui
-		if conn.consecutiveFailures >= conn.maxFailuresBeforeError then
-			el.statusLabel.Text = "Server unavailable"
-			el.statusLabel.TextColor3 = Color3.fromRGB(239, 68, 68)
-			el.statusIndicator.BackgroundColor3 = Color3.fromRGB(239, 68, 68)
-			el.statusPulse.BackgroundColor3 = Color3.fromRGB(239, 68, 68)
-			el.statusText.Text = "ERROR"
-			el.detailStatusLabel.Text = "HTTP: X  MCP: X"
-			el.detailStatusLabel.TextColor3 = Color3.fromRGB(239, 68, 68)
-			el.step1Dot.BackgroundColor3 = Color3.fromRGB(239, 68, 68)
-			el.step1Label.Text = "HTTP server (error)"
-			el.step2Dot.BackgroundColor3 = Color3.fromRGB(239, 68, 68)
-			el.step2Label.Text = "MCP bridge (error)"
-			el.step3Dot.BackgroundColor3 = Color3.fromRGB(239, 68, 68)
-			el.step3Label.Text = "Commands (error)"
-			conn.mcpWaitStartTime = nil
-			el.troubleshootLabel.Visible = false
-			UI.stopPulseAnimation()
-		elseif conn.consecutiveFailures > 5 then
-			local waitTime = math.ceil(conn.currentRetryDelay)
-			el.statusLabel.Text = `Retrying ({waitTime}s)`
-			el.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
-			el.statusIndicator.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.statusPulse.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.statusText.Text = "RETRY"
-			el.detailStatusLabel.Text = "HTTP: ...  MCP: ..."
-			el.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
-			el.step1Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.step1Label.Text = "HTTP server (retrying...)"
-			el.step2Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.step2Label.Text = "MCP bridge (retrying...)"
-			el.step3Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.step3Label.Text = "Commands (retrying...)"
-			conn.mcpWaitStartTime = nil
-			el.troubleshootLabel.Visible = false
-			UI.startPulseAnimation()
-		elseif conn.consecutiveFailures > 1 then
-			el.statusLabel.Text = `Connecting (attempt {conn.consecutiveFailures})`
-			el.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
-			el.statusIndicator.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.statusPulse.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.statusText.Text = "CONNECTING"
-			el.detailStatusLabel.Text = "HTTP: ...  MCP: ..."
-			el.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
-			el.step1Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.step1Label.Text = "HTTP server (connecting...)"
-			el.step2Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.step2Label.Text = "MCP bridge (connecting...)"
-			el.step3Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-			el.step3Label.Text = "Commands (connecting...)"
-			conn.mcpWaitStartTime = nil
-			el.troubleshootLabel.Visible = false
-			UI.startPulseAnimation()
+	end
+	if not placeIdChangeConn then
+		local signalOk, signal = pcall(function()
+			return game:GetPropertyChangedSignal("PlaceId")
+		end)
+		if signalOk and signal then
+			placeIdChangeConn = signal:Connect(function()
+				PluginSession.invalidatePlaceName()
+				lastReadyInstanceId = PluginSession.getInstanceId()
+				StudioEventStream.refresh()
+			end)
 		end
 	end
 end
+local function disconnectIdentityWatchers()
+	if nameChangeConn then
+		nameChangeConn:Disconnect()
+		nameChangeConn = nil
+	end
+	if placeIdChangeConn then
+		placeIdChangeConn:Disconnect()
+		placeIdChangeConn = nil
+	end
+end
 local deactivatePlugin
 local function activatePlugin()
 	local conn = State.getActiveConnection()
+	if conn.isActive then
+		return nil
+	end
 	local ui = UI.getElements()
-	pollEpoch += 1
-	conn.isPolling = false
-	conn.lastPoll = 0
 	conn.isActive = true
 	conn.consecutiveFailures = 0
 	conn.currentRetryDelay = 0.5
+	conn.lastHttpOk = false
+	conn.lastMcpOk = false
+	conn.mcpWaitStartTime = nil
 	local normalizedUrl = ServerUrlSettings.normalizeServerUrl(ui.urlInput.Text)
 	conn.serverUrl = if normalizedUrl ~= "" then normalizedUrl else conn.serverUrl
 	if conn.serverUrl == "" then
@@ -1345,65 +1050,60 @@ local function activatePlugin()
 	if port ~= nil then
 		conn.port = port
 	end
+	ClientBroker.setServerUrl(conn.serverUrl)
+	lastReadyInstanceId = PluginSession.getInstanceId()
 	UI.updateUIState()
+	StudioEventStream.start({
+		serverUrl = conn.serverUrl,
+		dispatchRequest = dispatchStreamRequest,
+		onStatus = handleStatus,
+		onHeartbeat = handleHeartbeat,
+		onReady = handleReady,
+		onTransportUpdate = handleTransportUpdate,
+	})
 	if not conn.heartbeatConnection then
 		conn.heartbeatConnection = RunService.Heartbeat:Connect(function()
-			local now = tick()
 			if initialRole == "server" and not RunService:IsRunning() then
 				ClientBroker.disconnectAllProxies()
 				deactivatePlugin()
 				return nil
 			end
-			local currentInstanceId = computeInstanceId()
+			local currentInstanceId = PluginSession.getInstanceId()
 			if lastReadyInstanceId ~= nil and currentInstanceId ~= lastReadyInstanceId then
-				cachedPlaceName = nil
-				cachedPlaceNamePlaceId = nil
-				sendReady(conn)
-			end
-			local currentInterval = if conn.consecutiveFailures > 5 then conn.currentRetryDelay else conn.pollInterval
-			if now - conn.lastPoll > currentInterval then
-				conn.lastPoll = now
-				pollForRequests()
+				lastReadyInstanceId = currentInstanceId
+				PluginSession.invalidatePlaceName()
+				StudioEventStream.refresh()
 			end
 		end)
 	end
-	-- Initial /ready; pollForRequests will also re-fire ready if the server
-	-- later reports knownInstance=false (process restart, etc).
-	sendReady(conn)
-	-- Remove legacy edit-mode eval bridge scripts from older plugin builds.
-	-- Current bridges are created only in running play DataModels.
 	if not RunService:IsRunning() then
-		task.spawn(cleanupLegacyEditBridges)
+		task.spawn(cleanupEditBridgeArtifacts)
 	end
-	-- Watch identity fields so stale name or anon instance ids are refreshed.
-	ensureIdentityWatcher(conn)
+	ensureIdentityWatchers()
 end
 function deactivatePlugin()
 	local conn = State.getActiveConnection()
-	pollEpoch += 1
-	conn.isPolling = false
+	if not conn.isActive then
+		return nil
+	end
 	conn.isActive = false
+	conn.lastHttpOk = false
 	conn.lastMcpOk = false
-	UI.updateUIState()
-	pcall(function()
-		HttpService:RequestAsync({
-			Url = `{conn.serverUrl}/disconnect`,
-			Method = "POST",
-			Headers = {
-				["Content-Type"] = "application/json",
-			},
-			Body = HttpService:JSONEncode({
-				pluginSessionId = pluginSessionId,
-				timestamp = tick(),
-			}),
-		})
-	end)
+	conn.mcpWaitStartTime = nil
+	StudioEventStream.stop()
+	disconnectIdentityWatchers()
+	if initialRole == "server" then
+		ClientBroker.disconnectAllProxies()
+	end
 	if conn.heartbeatConnection then
 		conn.heartbeatConnection:Disconnect()
 		conn.heartbeatConnection = nil
 	end
+	lastReadyInstanceId = nil
+	assignedRole = nil
 	conn.consecutiveFailures = 0
 	conn.currentRetryDelay = 0.5
+	UI.updateUIState()
 end
 local function deactivateAll()
 	local conn = State.getActiveConnection()
@@ -1437,9 +1137,7 @@ local function checkForUpdates()
 			if _condition ~= "" and _condition then
 				local latestVersion = data.version
 				if Utils.compareVersions(State.CURRENT_VERSION, latestVersion) < 0 then
-					if not hasVersionMismatch then
-						UI.showBanner("update", `v{latestVersion} available - github.com/chrrxs/robloxstudio-mcp`)
-					end
+					UI.showBanner("update", `v{latestVersion} available - github.com/chrrxs/robloxstudio-mcp`)
 				end
 			end
 		end
@@ -1575,9 +1273,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "3.0.2" is replaced with the package version at package time
+	-- "3.0.3" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-3.0.2`
+	return `{tostring(h)}-3.0.3`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -1593,7 +1291,7 @@ local function setSource(scriptInst, source)
 		scriptInst.Source = source
 	end
 end
-local function findLegacyEditBridges()
+local function findEditBridgeArtifacts()
 	local sps = getStarterPlayerScripts()
 	return {
 		server = ServerScriptService:FindFirstChild(SERVER_SCRIPT_NAME),
@@ -1608,11 +1306,11 @@ local function destroyIfPresent(parent, name)
 		end)
 	end
 end
-local function cleanupLegacyEditBridges()
+local function cleanupEditBridgeArtifacts()
 	if RunService:IsRunning() then
 		return nil
 	end
-	local _binding = findLegacyEditBridges()
+	local _binding = findEditBridgeArtifacts()
 	local server = _binding.server
 	local client = _binding.client
 	if server then
@@ -1723,7 +1421,7 @@ local function ensureRuntimeBridgeInstalled()
 	return installClientRuntimeBridge()
 end
 return {
-	cleanupLegacyEditBridges = cleanupLegacyEditBridges,
+	cleanupEditBridgeArtifacts = cleanupEditBridgeArtifacts,
 	ensureRuntimeBridgeInstalled = ensureRuntimeBridgeInstalled,
 	BRIDGE_NAMES = BRIDGE_NAMES,
 }
@@ -2702,6 +2400,8 @@ local RenderMonitor = TS.import(script, script.Parent.Parent, "RenderMonitor")
 local CaptureService = game:GetService("CaptureService")
 local AssetService = game:GetService("AssetService")
 local MAX_TILE_SIZE = 1024
+local MAX_RAW_PIXEL_BYTES = 36 * 1024 * 1024
+local MAX_CREATED_IMAGE_DIM = 2048
 local BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
 local PAD_BYTE = (string.byte("="))
 local B64 = {}
@@ -2853,14 +2553,39 @@ local function readContentToBase64(contentId)
 			error = `Failed to create EditableImage from screenshot. Enable EditableImage API: Game Settings > Security > 'Allow Mesh / Image APIs'. ({tostring(editableResult)})`,
 		}
 	end
-	local editableImage = editableResult
-	local imgSize = editableImage.Size
-	local w = math.floor(imgSize.X)
-	local h = math.floor(imgSize.Y)
+	local sourceImage = editableResult
+	local imgSize = sourceImage.Size
+	local nativeW = math.floor(imgSize.X)
+	local nativeH = math.floor(imgSize.Y)
+	local w = nativeW
+	local h = nativeH
+	if nativeW * nativeH * 4 > MAX_RAW_PIXEL_BYTES then
+		local scale = math.min(math.sqrt(MAX_RAW_PIXEL_BYTES / (nativeW * nativeH * 4)), MAX_CREATED_IMAGE_DIM / math.max(nativeW, nativeH))
+		w = math.max(1, math.floor(nativeW * scale))
+		h = math.max(1, math.floor(nativeH * scale))
+		local scaleOk, scaledResult = pcall(function()
+			local target = AssetService:CreateEditableImage({
+				Size = Vector2.new(w, h),
+			})
+			target:DrawImageTransformed(Vector2.new(0, 0), Vector2.new(w / nativeW, h / nativeH), 0, sourceImage, {
+				CombineType = Enum.ImageCombineType.AlphaBlend,
+				SamplingMode = Enum.ResamplerMode.Default,
+				PivotPoint = Vector2.new(0, 0),
+			})
+			return target
+		end)
+		sourceImage:Destroy()
+		if not scaleOk then
+			return {
+				error = `Screenshot is {nativeW}x{nativeH} (too large to transfer raw) and downscaling failed: {tostring(scaledResult)}`,
+			}
+		end
+		sourceImage = scaledResult
+	end
 	local readOk, pixelBuffer = pcall(function()
-		return readPixelsTiled(editableImage, w, h)
+		return readPixelsTiled(sourceImage, w, h)
 	end)
-	editableImage:Destroy()
+	sourceImage:Destroy()
 	if not readOk then
 		return {
 			error = `Failed to read pixel data: {tostring(pixelBuffer)}`,
@@ -2872,6 +2597,8 @@ local function readContentToBase64(contentId)
 		width = w,
 		height = h,
 		data = base64Data,
+		nativeWidth = nativeW,
+		nativeHeight = nativeH,
 	}
 end
 -- Edit-mode single shot: capture and read back in the same (edit) context.
@@ -7014,7 +6741,7 @@ local function setScriptSource(requestData)
 			error = `Instance is not a script-like object: {instance.ClassName}`,
 		}
 	end
-	-- Communication has already JSON-decoded the poll payload; source text is exact at this boundary.
+	-- Communication has already JSON-decoded the transport payload; source text is exact at this boundary.
 	local sourceToSet = newSource
 	local recordingId = beginRecording(`Set script source: {instance.Name}`)
 	local readSuccess, readResult = pcall(function()
@@ -9067,6 +8794,98 @@ return {
         </Properties>
       </Item>
       <Item class="ModuleScript" referent="26">
+        <Properties>
+          <string name="Name">PluginSession</string>
+          <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+local TS = require(script.Parent.Parent.include.RuntimeLib)
+local _services = TS.import(script, script.Parent.Parent, "node_modules", "@rbxts", "services")
+local HttpService = _services.HttpService
+local RunService = _services.RunService
+local ServerStorage = _services.ServerStorage
+local State = TS.import(script, script.Parent, "State")
+local MCP_PLACE_ID_ATTRIBUTE = "__MCPPlaceId"
+local id = HttpService:GenerateGUID(false)
+local cachedPlaceName
+local cachedPlaceNamePlaceId
+local function getInstanceId()
+	if game.PlaceId ~= 0 then
+		return `place:{tostring(game.PlaceId)}`
+	end
+	local existing = ServerStorage:GetAttribute(MCP_PLACE_ID_ATTRIBUTE)
+	if type(existing) == "string" and existing ~= "" then
+		return `anon:{existing}`
+	end
+	local fresh = HttpService:GenerateGUID(false)
+	pcall(function()
+		return ServerStorage:SetAttribute(MCP_PLACE_ID_ATTRIBUTE, fresh)
+	end)
+	return `anon:{fresh}`
+end
+local function getRole()
+	if not RunService:IsRunning() then
+		return "edit"
+	end
+	if RunService:IsServer() then
+		return "server"
+	end
+	return "client"
+end
+local function invalidatePlaceName()
+	cachedPlaceName = nil
+	cachedPlaceNamePlaceId = nil
+end
+local function getPlaceName()
+	if cachedPlaceName ~= nil and cachedPlaceNamePlaceId == game.PlaceId then
+		return cachedPlaceName
+	end
+	invalidatePlaceName()
+	cachedPlaceNamePlaceId = game.PlaceId
+	if game.PlaceId == 0 then
+		cachedPlaceName = game.Name
+		return cachedPlaceName
+	end
+	local MarketplaceService = game:GetService("MarketplaceService")
+	local ok, info = pcall(function()
+		return MarketplaceService:GetProductInfo(game.PlaceId)
+	end)
+	if ok and info ~= nil then
+		-- GetProductInfo's generated type is broader than the place metadata returned here.
+		local placeInfo = info
+		local name = placeInfo.Name
+		if type(name) == "string" and name ~= "" then
+			cachedPlaceName = name
+			return cachedPlaceName
+		end
+	end
+	return game.Name
+end
+local function createReadyPayload(pluginSessionId, role)
+	return {
+		pluginSessionId = pluginSessionId,
+		physicalSessionId = id,
+		instanceId = getInstanceId(),
+		role = role,
+		placeId = game.PlaceId,
+		placeName = getPlaceName(),
+		dataModelName = game.Name,
+		isRunning = RunService:IsRunning(),
+		pluginVersion = State.CURRENT_VERSION,
+		pluginVariant = State.PLUGIN_VARIANT,
+		timestamp = tick(),
+	}
+end
+return {
+	id = id,
+	getInstanceId = getInstanceId,
+	getRole = getRole,
+	getPlaceName = getPlaceName,
+	invalidatePlaceName = invalidatePlaceName,
+	createReadyPayload = createReadyPayload,
+}
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="27">
         <Properties>
           <string name="Name">Recording</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9096,7 +8915,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="27">
+      <Item class="ModuleScript" referent="28">
         <Properties>
           <string name="Name">RenderMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9164,7 +8983,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="28">
+      <Item class="ModuleScript" referent="29">
         <Properties>
           <string name="Name">RuntimeLogBuffer</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9419,7 +9238,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="29">
+      <Item class="ModuleScript" referent="30">
         <Properties>
           <string name="Name">ServerUrlSettings</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9427,7 +9246,6 @@ local TS = require(script.Parent.Parent.include.RuntimeLib)
 local _services = TS.import(script, script.Parent.Parent, "node_modules", "@rbxts", "services")
 local HttpService = _services.HttpService
 local ServerStorage = _services.ServerStorage
-local LEGACY_SETTING_KEY_PREFIX = "MCP_SERVER_URL_"
 local SETTING_KEY_PREFIX = "MCP_LAST_SUCCESSFUL_SERVER_URL_"
 local GLOBAL_SETTING_KEY = "MCP_LAST_SUCCESSFUL_SERVER_URL_GLOBAL_V1"
 local pluginRef
@@ -9497,9 +9315,6 @@ end
 local function settingKey(instanceId)
 	return SETTING_KEY_PREFIX .. instanceId
 end
-local function legacySettingKey(instanceId)
-	return LEGACY_SETTING_KEY_PREFIX .. instanceId
-end
 local function readSettingString(key)
 	if not pluginRef then
 		return nil
@@ -9531,7 +9346,6 @@ local function rememberServerUrl(serverUrl)
 		createAnonymous = true,
 	}) do
 		writeSettingString(settingKey(instanceId), normalized)
-		writeSettingString(legacySettingKey(instanceId), normalized)
 	end
 end
 local function readServerUrl()
@@ -9551,12 +9365,6 @@ local function readServerUrl()
 	if globalRemembered ~= nil then
 		return globalRemembered
 	end
-	for _, instanceId in computeInstanceIds() do
-		local legacyRemembered = readSettingString(legacySettingKey(instanceId))
-		if legacyRemembered ~= nil then
-			return legacyRemembered
-		end
-	end
 	return nil
 end
 return {
@@ -9569,31 +9377,24 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="30">
+      <Item class="ModuleScript" referent="31">
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "3.0.2"
+local CURRENT_VERSION = "3.0.3"
 local PLUGIN_VARIANT = "main"
 local BASE_PORT = 58741
-local POLL_REQUEST_TIMEOUT_SECONDS = 20
 local function createConnection(port)
 	return {
 		port = port,
 		serverUrl = `http://localhost:{port}`,
 		isActive = false,
-		pollInterval = 0.5,
-		lastPoll = 0,
 		consecutiveFailures = 0,
 		maxFailuresBeforeError = 50,
-		lastSuccessfulConnection = 0,
 		currentRetryDelay = 0.5,
-		maxRetryDelay = 5,
-		retryBackoffMultiplier = 1.2,
 		lastHttpOk = false,
 		lastMcpOk = false,
 		mcpWaitStartTime = nil,
-		isPolling = false,
 		heartbeatConnection = nil,
 	}
 end
@@ -9605,13 +9406,12 @@ return {
 	CURRENT_VERSION = CURRENT_VERSION,
 	PLUGIN_VARIANT = PLUGIN_VARIANT,
 	BASE_PORT = BASE_PORT,
-	POLL_REQUEST_TIMEOUT_SECONDS = POLL_REQUEST_TIMEOUT_SECONDS,
 	getActiveConnection = getActiveConnection,
 }
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="31">
+      <Item class="ModuleScript" referent="32">
         <Properties>
           <string name="Name">StopPlayMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9664,7 +9464,7 @@ local endTestIssued = false
 local function init(p)
 	pluginRef = p
 end
--- Mirror of Communication.computeInstanceId(). Duplicated here because
+-- Mirror of PluginSession's place identity rules. Duplicated here because
 -- StopPlayMonitor runs in both edit and play-server DMs, and both must
 -- agree on the place identifier (published places: placeId; unpublished:
 -- UUID on ServerStorage's __MCPPlaceId attribute, travels with the .rbxl
@@ -9820,16 +9620,9 @@ local function startMonitor()
 	task.spawn(function()
 		while true do
 			for _, myKey in settingKeys() do
-				local value = readSetting(myKey)
-				if value == true then
-					-- Legacy boolean requests are ambiguous and may be stale from
-					-- a prior crashed session. New stop requests use token payloads.
-					writeSetting(myKey, false)
-				else
-					local payload = decodePayload(value)
-					if payload then
-						handleStopRequest(myKey, payload)
-					end
+				local payload = decodePayload(readSetting(myKey))
+				if payload then
+					handleStopRequest(myKey, payload)
 				end
 			end
 			task.wait(POLL_INTERVAL_SEC)
@@ -9909,7 +9702,618 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="32">
+      <Item class="ModuleScript" referent="33">
+        <Properties>
+          <string name="Name">StudioEventStream</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 options
+local active = false
+local generation = 0
+local reconnectAttempt = 0
+local streamClient
+local streamConnections = {}
+local lastValidEventAt = 0
+local inFlightRequestIds = {}
+local pendingResponses = {}
+local terminalResponseIds = {}
+local terminalResponseOrder = {}
+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+$", ""))
+	end
+	local decodeOk, decoded = pcall(function()
+		return HttpService:JSONDecode(payload)
+	end)
+	if not decodeOk or not (type(decoded) == "table") then
+		return nil
+	end
+	local envelope = decoded
+	if envelope.kind == "heartbeat" then
+		local _timestamp = envelope.timestamp
+		if not (type(_timestamp) == "number") then
+			return nil
+		end
+		return {
+			kind = "heartbeat",
+			timestamp = envelope.timestamp,
+		}
+	end
+	if envelope.kind == "status" then
+		local _knownInstance = envelope.knownInstance
+		local _condition = not (type(_knownInstance) == "boolean")
+		if not _condition then
+			local _mcpConnected = envelope.mcpConnected
+			_condition = not (type(_mcpConnected) == "boolean")
+		end
+		if _condition then
+			return nil
+		end
+		local _object = {
+			kind = "status",
+			knownInstance = envelope.knownInstance,
+			mcpConnected = envelope.mcpConnected,
+		}
+		local _left = "serverVersion"
+		local _serverVersion = envelope.serverVersion
+		_object[_left] = if type(_serverVersion) == "string" then envelope.serverVersion else nil
+		local _left_1 = "pluginVersion"
+		local _pluginVersion = envelope.pluginVersion
+		_object[_left_1] = if type(_pluginVersion) == "string" then envelope.pluginVersion else nil
+		local _left_2 = "pluginVariant"
+		local _pluginVariant = envelope.pluginVariant
+		_object[_left_2] = if type(_pluginVariant) == "string" then envelope.pluginVariant else nil
+		return _object
+	end
+	if envelope.kind == "request" then
+		local _requestId = envelope.requestId
+		local _condition = not (type(_requestId) == "string")
+		if not _condition then
+			local _logicalSessionId = envelope.logicalSessionId
+			_condition = not (type(_logicalSessionId) == "string")
+			if not _condition then
+				local _target = envelope.target
+				_condition = not (type(_target) == "string")
+				if not _condition then
+					local _endpoint = envelope.endpoint
+					_condition = not (type(_endpoint) == "string")
+				end
+			end
+		end
+		if _condition then
+			return nil
+		end
+		local data
+		local _data = envelope.data
+		if type(_data) == "table" then
+			data = envelope.data
+		end
+		return {
+			kind = "request",
+			requestId = envelope.requestId,
+			logicalSessionId = envelope.logicalSessionId,
+			target = envelope.target,
+			endpoint = envelope.endpoint,
+			data = data,
+		}
+	end
+	return nil
+end
+local function closeCurrentStream()
+	local current = streamClient
+	streamClient = nil
+	for _, connection in streamConnections do
+		connection:Disconnect()
+	end
+	streamConnections = {}
+	if current ~= nil then
+		pcall(function()
+			return current:Close()
+		end)
+	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)
+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"
+	end
+	return nil
+end
+local function rememberTerminalResponse(requestId)
+	local _requestId = requestId
+	if terminalResponseIds[_requestId] ~= nil then
+		return nil
+	end
+	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 function settleResponse(requestId, entry, disposition)
+	local _requestId = requestId
+	if pendingResponses[_requestId] ~= entry then
+		return nil
+	end
+	local _requestId_1 = requestId
+	pendingResponses[_requestId_1] = nil
+	rememberTerminalResponse(requestId)
+	if disposition == "unknown" then
+		warn(`[robloxstudio-mcp] Server no longer recognizes response {requestId}; dropping stored result`)
+	end
+end
+local function postPendingResponse(requestId, entry)
+	local currentOptions = options
+	local _condition = not active or currentOptions == nil
+	if not _condition then
+		local _requestId = requestId
+		_condition = pendingResponses[_requestId] ~= entry
+		if not _condition then
+			_condition = entry.posting
+		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
+		end
+		if _condition_1 then
+			entry.posting = false
+			return nil
+		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
+		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)
+		end
+		warn(`[robloxstudio-mcp] Failed to deliver response {requestId}: {failure}`)
+		entry.retryAttempt += 1
+		local _condition_2 = not active
+		if not _condition_2 then
+			local _requestId_1 = requestId
+			_condition_2 = pendingResponses[_requestId_1] ~= entry
+		end
+		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)
+	end)
+end
+local function resumePendingResponses()
+	for requestId, entry in pendingResponses do
+		postPendingResponse(requestId, entry)
+	end
+end
+local function encodeResponse(requestId, response)
+	local encodeOk, encoded = pcall(function()
+		return HttpService:JSONEncode({
+			requestId = requestId,
+			response = response,
+		})
+	end)
+	if encodeOk then
+		return encoded
+	end
+	warn(`[robloxstudio-mcp] Failed to serialize response {requestId}: {tostring(encoded)}`)
+	return HttpService:JSONEncode({
+		requestId = requestId,
+		error = `Plugin response serialization failed: {tostring(encoded)}`,
+	})
+end
+local function dispatchRequest(request)
+	local _requestId = request.requestId
+	local _condition = terminalResponseIds[_requestId] ~= nil
+	if not _condition then
+		local _requestId_1 = request.requestId
+		_condition = pendingResponses[_requestId_1] ~= nil
+		if not _condition then
+			local _requestId_2 = request.requestId
+			_condition = inFlightRequestIds[_requestId_2] ~= nil
+		end
+	end
+	if _condition then
+		return nil
+	end
+	local dispatchOptions = options
+	if not active or dispatchOptions == nil then
+		return nil
+	end
+	local _requestId_1 = request.requestId
+	inFlightRequestIds[_requestId_1] = true
+	task.spawn(function()
+		local dispatchOk, response = pcall(function()
+			return dispatchOptions.dispatchRequest(request)
+		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 _requestId_2 = request.requestId
+		pendingResponses[_requestId_2] = entry
+		local _requestId_3 = request.requestId
+		inFlightRequestIds[_requestId_3] = nil
+		postPendingResponse(request.requestId, entry)
+	end)
+end
+local function invokeCallback(name, callback)
+	local callbackOk, callbackError = pcall(callback)
+	if not callbackOk then
+		warn(`[robloxstudio-mcp] {name} callback failed: {tostring(callbackError)}`)
+	end
+end
+local function reportTransport(update)
+	local currentOptions = options
+	if active and currentOptions ~= nil then
+		invokeCallback("event stream 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)
+	if duplicate == nil then
+		duplicate = false
+	end
+	if not active or generation ~= expectedGeneration then
+		return nil
+	end
+	generation += 1
+	closeCurrentStream()
+	reconnectAttempt += 1
+	local delay = if duplicate then 1 else reconnectDelay(reconnectAttempt)
+	reportTransport({
+		state = if duplicate then "waiting-duplicate" else "retrying",
+		attempt = reconnectAttempt,
+		retryDelay = delay,
+		detail = detail,
+	})
+	connectAfter(delay, generation)
+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
+			return nil
+		end
+		local silentFor = tick() - lastValidEventAt
+		if silentFor >= STREAM_SILENCE_TIMEOUT_SECONDS then
+			scheduleReconnect(expectedGeneration, `Event stream silent for {math.floor(silentFor)} seconds`)
+			return nil
+		end
+		watchForSilence(expectedGeneration, expectedClient)
+	end)
+end
+local function parseReadyResponse(body)
+	local decodeOk, decoded = pcall(function()
+		return HttpService:JSONDecode(body)
+	end)
+	if not decodeOk or not (type(decoded) == "table") then
+		return nil
+	end
+	local value = decoded
+	local _condition = value.success ~= true
+	if not _condition then
+		local _assignedRole = value.assignedRole
+		_condition = not (type(_assignedRole) == "string")
+		if not _condition then
+			_condition = value.assignedRole == ""
+			if not _condition then
+				local _instanceId = value.instanceId
+				_condition = not (type(_instanceId) == "string")
+				if not _condition then
+					_condition = value.instanceId == ""
+					if not _condition then
+						local _serverVersion = value.serverVersion
+						_condition = not (type(_serverVersion) == "string")
+						if not _condition then
+							_condition = value.serverVersion == ""
+						end
+					end
+				end
+			end
+		end
+	end
+	if _condition then
+		return nil
+	end
+	return {
+		success = true,
+		assignedRole = value.assignedRole,
+		instanceId = value.instanceId,
+		serverVersion = value.serverVersion,
+	}
+end
+local refresh
+function connect(expectedGeneration)
+	local currentOptions = options
+	if not active or generation ~= expectedGeneration or currentOptions == nil then
+		return nil
+	end
+	reportTransport({
+		state = "connecting",
+		attempt = reconnectAttempt,
+		retryDelay = 0,
+	})
+	task.spawn(function()
+		local instanceId = PluginSession.getInstanceId()
+		local readyUrl = `{currentOptions.serverUrl}/ready`
+		local physicalRole = PluginSession.getRole()
+		local readyPayload = PluginSession.createReadyPayload(PluginSession.id, physicalRole)
+		readyPayload.pluginReady = true
+		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}|{instanceId}|{physicalRole}`
+		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}/{physicalRole}: {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}/{physicalRole}: {detail}`)
+			end
+			scheduleReconnect(expectedGeneration, detail, readyResult.StatusCode == 409)
+			return nil
+		end
+		local readyData = parseReadyResponse(readyResult.Body)
+		if readyData == nil then
+			scheduleReconnect(expectedGeneration, "Invalid /ready response: expected the bundled server protocol")
+			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 createOk, createdClient = pcall(function()
+			return HttpService:CreateWebStreamClient(Enum.WebStreamClientType.SSE, {
+				Url = `{currentOptions.serverUrl}/events?pluginSessionId={PluginSession.id}`,
+				Method = "GET",
+				Headers = {
+					Accept = "text/event-stream",
+				},
+			})
+		end)
+		if not createOk then
+			scheduleReconnect(expectedGeneration, `Failed to create event stream: {tostring(createdClient)}`)
+			return nil
+		end
+		if not active or generation ~= expectedGeneration or options ~= currentOptions then
+			pcall(function()
+				return createdClient:Close()
+			end)
+			return nil
+		end
+		streamClient = createdClient
+		streamConnections = { createdClient.Opened:Connect(function(statusCode, _headers)
+			if not active or generation ~= expectedGeneration or streamClient ~= createdClient then
+				return nil
+			end
+			lastValidEventAt = tick()
+			if statusCode < 200 or statusCode >= 300 then
+				scheduleReconnect(expectedGeneration, `Event stream opened with HTTP {statusCode}`)
+				return nil
+			end
+			reconnectAttempt = 0
+			reportTransport({
+				state = "open",
+				attempt = 0,
+				retryDelay = 0,
+			})
+			resumePendingResponses()
+		end), createdClient.MessageReceived:Connect(function(message)
+			if not active or generation ~= expectedGeneration or streamClient ~= createdClient then
+				return nil
+			end
+			local event = decodeMessage(message)
+			if event == nil then
+				return nil
+			end
+			lastValidEventAt = tick()
+			if event.kind == "heartbeat" then
+				invokeCallback("event stream heartbeat", function()
+					return currentOptions.onHeartbeat(event.timestamp)
+				end)
+				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.knownInstance then
+				refresh()
+			end
+		end), createdClient.Error:Connect(function(statusCode, message)
+			if not active or generation ~= expectedGeneration or streamClient ~= 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)
+		end), createdClient.Closed:Connect(function()
+			if not active or generation ~= expectedGeneration or streamClient ~= createdClient then
+				return nil
+			end
+			scheduleReconnect(expectedGeneration, "Event stream closed")
+		end) }
+		lastValidEventAt = tick()
+		watchForSilence(expectedGeneration, createdClient)
+	end)
+end
+local stop
+local function start(newOptions)
+	if active then
+		stop()
+	end
+	options = newOptions
+	active = true
+	reconnectAttempt = 0
+	generation += 1
+	connect(generation)
+end
+function refresh()
+	if not active or options == nil then
+		return nil
+	end
+	generation += 1
+	closeCurrentStream()
+	reconnectAttempt = 0
+	connect(generation)
+end
+function stop()
+	if not active then
+		return nil
+	end
+	local currentOptions = options
+	active = false
+	generation += 1
+	closeCurrentStream()
+	table.clear(readyFailureLogKeys)
+	options = nil
+	reconnectAttempt = 0
+	if currentOptions ~= nil then
+		pcall(function()
+			return HttpService:RequestAsync({
+				Url = `{currentOptions.serverUrl}/disconnect`,
+				Method = "POST",
+				Headers = {
+					["Content-Type"] = "application/json",
+				},
+				Body = HttpService:JSONEncode({
+					pluginSessionId = PluginSession.id,
+					timestamp = tick(),
+				}),
+			})
+		end)
+	end
+end
+return {
+	start = start,
+	refresh = refresh,
+	stop = stop,
+}
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="34">
         <Properties>
           <string name="Name">UI</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -10461,7 +10865,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="33">
+      <Item class="ModuleScript" referent="35">
         <Properties>
           <string name="Name">Utils</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -11306,11 +11710,11 @@ return {
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="38">
+    <Item class="Folder" referent="40">
       <Properties>
         <string name="Name">include</string>
       </Properties>
-      <Item class="ModuleScript" referent="34">
+      <Item class="ModuleScript" referent="36">
         <Properties>
           <string name="Name">LibMP</string>
           <string name="Source"><![CDATA[-- =============================================================================
@@ -167694,7 +168098,7 @@ return LibMP
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="35">
+      <Item class="ModuleScript" referent="37">
         <Properties>
           <string name="Name">Promise</string>
           <string name="Source"><![CDATA[--[[
@@ -169768,7 +170172,7 @@ return Promise
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="36">
+      <Item class="ModuleScript" referent="38">
         <Properties>
           <string name="Name">RuntimeLib</string>
           <string name="Source"><![CDATA[local Promise = require(script.Parent.Promise)
@@ -170035,15 +170439,15 @@ return TS
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="39">
+    <Item class="Folder" referent="41">
       <Properties>
         <string name="Name">node_modules</string>
       </Properties>
-      <Item class="Folder" referent="40">
+      <Item class="Folder" referent="42">
         <Properties>
           <string name="Name">@rbxts</string>
         </Properties>
-      <Item class="ModuleScript" referent="37">
+      <Item class="ModuleScript" referent="39">
         <Properties>
           <string name="Name">services</string>
           <string name="Source"><![CDATA[return setmetatable({}, {