@princeofscale/bloxforge-inspector 3.0.0-rc.1 → 3.0.0

package/studio-plugin/src/modules/ClientBroker.ts

@@ -75,6 +75,7 @@ const BROKER_OWNER_ATTRIBUTE = "__MCPBrokerOwner";
 interface ProxyEntry {
 	pluginSessionId: string;
 	role: string;
+	sessionToken: string;
 }
 
 interface BrokerEnvelope {
@@ -111,10 +112,14 @@ const CLIENT_BROKER_ALLOWED_ENDPOINTS = new Set<string>([
 
 interface ReadyResponseBody {
 	assignedRole?: string;
+	sessionToken?: string;
 }
 
 interface PollResponseBody {
 	requestId?: string;
+	serverEpoch?: string;
+	deliveryAttempt?: number;
+	leaseToken?: string;
 	request?: {
 		endpoint: string;
 		data?: Record<string, unknown>;
@@ -125,17 +130,42 @@ interface PollResponseBody {
 	knownInstance?: boolean;
 }
 
+interface DeliveryFence {
+	serverEpoch: string;
+	deliveryAttempt: number;
+	leaseToken: string;
+}
+
 // Throttle re-ready calls per proxyId so a brief window of unknownInstance
 // polls doesn't cause a re-register stampede.
 const lastReadyByProxy = new Map<string, number>();
+const completedProxyRequests = new Map<string, { response: unknown }>();
+const completedProxyRequestOrder: string[] = [];
+const COMPLETED_PROXY_REQUEST_LIMIT = 500;
+
+function rememberCompletedProxyRequest(requestId: string, response: unknown): void {
+	completedProxyRequests.set(requestId, { response });
+	completedProxyRequestOrder.push(requestId);
+	if (completedProxyRequestOrder.size() > COMPLETED_PROXY_REQUEST_LIMIT) {
+		completedProxyRequests.delete(completedProxyRequestOrder.shift()!);
+	}
+}
+
+function sendProxyResponse(requestId: string, response: unknown, proxy: ProxyEntry, fence: DeliveryFence): void {
+	const [ok, result] = postJson("/response", { requestId, pluginSessionId: proxy.pluginSessionId, response, ...fence }, proxy.sessionToken);
+	if (!ok || !result || !result.Success) {
+		warn(`[BloxForge] proxy response delivery failed: ${formatPostJsonFailure("/response", ok, result)}`);
+	}
+}
 
-function reRegisterProxy(proxyId: string, role: string): void {
+function reRegisterProxy(proxy: ProxyEntry, role: string): void {
+	const proxyId = proxy.pluginSessionId;
 	const now = tick();
 	const last = lastReadyByProxy.get(proxyId) ?? 0;
 	if (now - last < 2) return;
 	lastReadyByProxy.set(proxyId, now);
-	pcall(() =>
-		postJson("/ready", {
+	pcall(() => {
+		const [ok, result] = postJson("/ready", {
 			pluginSessionId: proxyId,
 			instanceId: computeInstanceId(),
 			role,
@@ -146,8 +176,12 @@ function reRegisterProxy(proxyId: string, role: string): void {
 			pluginVersion: State.CURRENT_VERSION,
 			pluginVariant: State.PLUGIN_VARIANT,
 			protocolVersion: State.PROTOCOL_VERSION,
-		}),
-	);
+		});
+		if (ok && result && result.Success) {
+			const body = HttpService.JSONDecode(result.Body) as ReadyResponseBody;
+			if (body.sessionToken !== undefined) proxy.sessionToken = body.sessionToken;
+		}
+	});
 }
 
 function forkRole(): "edit" | "server" | "client" {
@@ -156,12 +190,14 @@ function forkRole(): "edit" | "server" | "client" {
 	return "client";
 }
 
-function postJson(endpoint: string, body: Record<string, unknown>) {
+function postJson(endpoint: string, body: Record<string, unknown>, sessionToken?: string) {
+	const headers: Record<string, string> = { "Content-Type": "application/json" };
+	if (sessionToken !== undefined && sessionToken !== "") headers.Authorization = `Bearer ${sessionToken}`;
 	return pcall(() =>
 		HttpService.RequestAsync({
 			Url: `${mcpUrl}${endpoint}`,
 			Method: "POST",
-			Headers: { "Content-Type": "application/json" },
+			Headers: headers,
 			Body: HttpService.JSONEncode(body),
 		}),
 	);
@@ -312,7 +348,7 @@ function unregisterProxy(player: Player, entry?: ProxyEntry): void {
 	if (!proxy) return;
 	proxyByPlayer.delete(player);
 	proxyRegisterFailuresByPlayer.delete(player);
-	postJson("/disconnect", { pluginSessionId: proxy.pluginSessionId });
+	postJson("/disconnect", { pluginSessionId: proxy.pluginSessionId }, proxy.sessionToken);
 }
 
 function disconnectAllProxies(): void {
@@ -323,7 +359,8 @@ function disconnectAllProxies(): void {
 	proxyRegisterFailuresByPlayer.clear();
 }
 
-function pollProxy(proxyId: string, player: Player, rf: RemoteFunction) {
+function pollProxy(proxy: ProxyEntry, player: Player, rf: RemoteFunction) {
+	const proxyId = proxy.pluginSessionId;
 	while (player.Parent !== undefined && proxyByPlayer.has(player)) {
 		if (!RunService.IsRunning()) {
 			unregisterProxy(player);
@@ -333,18 +370,32 @@ function pollProxy(proxyId: string, player: Player, rf: RemoteFunction) {
 			HttpService.RequestAsync({
 				Url: `${mcpUrl}/poll?pluginSessionId=${proxyId}`,
 				Method: "GET",
-				Headers: { "Content-Type": "application/json" },
+				Headers: proxy.sessionToken !== ""
+					? { "Content-Type": "application/json", Authorization: `Bearer ${proxy.sessionToken}` }
+					: { "Content-Type": "application/json" },
 			}),
 		);
+		if (ok && res && res.StatusCode === 401) {
+			reRegisterProxy(proxy, "client");
+		}
 		if (ok && res && (res.Success || res.StatusCode === 503)) {
 			const [okJson, body] = pcall(() => HttpService.JSONDecode(res.Body) as PollResponseBody);
 			if (okJson && body) {
 				// Server lost our proxy registration (process restart, etc.) -
 				// re-register so the next poll cycle starts routing again.
 				if (body.knownInstance === false) {
-					reRegisterProxy(proxyId, "client");
+					reRegisterProxy(proxy, "client");
 				}
 				if (body.request && body.requestId !== undefined) {
+					if (!body.serverEpoch || body.deliveryAttempt === undefined || !body.leaseToken) continue;
+					const fence = { serverEpoch: body.serverEpoch, deliveryAttempt: body.deliveryAttempt, leaseToken: body.leaseToken };
+					const cached = completedProxyRequests.get(body.requestId);
+					if (cached !== undefined) {
+						sendProxyResponse(body.requestId, cached.response, proxy, fence);
+						task.wait(0.5);
+						continue;
+					}
+					postJson("/ack", { requestId: body.requestId, pluginSessionId: proxyId, ...fence }, proxy.sessionToken);
 					const request = body.request;
 					let response: unknown;
 					if (CLIENT_BROKER_ALLOWED_ENDPOINTS.has(request.endpoint)) {
@@ -366,7 +417,8 @@ function pollProxy(proxyId: string, player: Player, rf: RemoteFunction) {
 								`Allowed: ${allowed.join(", ")}.`,
 						};
 					}
-					postJson("/response", { requestId: body.requestId, response });
+					rememberCompletedProxyRequest(body.requestId, response);
+					sendProxyResponse(body.requestId, response, proxy, fence);
 				}
 			}
 		}
@@ -396,12 +448,13 @@ function registerProxy(player: Player, rf: RemoteFunction) {
 	}
 	const body = HttpService.JSONDecode(res.Body) as ReadyResponseBody;
 	const assigned = body.assignedRole ?? "client";
-	proxyByPlayer.set(player, { pluginSessionId: proxyId, role: assigned });
+	const entry = { pluginSessionId: proxyId, role: assigned, sessionToken: body.sessionToken ?? "" };
+	proxyByPlayer.set(player, entry);
 	if (proxyRegisterFailuresByPlayer.has(player)) {
 		proxyRegisterFailuresByPlayer.delete(player);
 		print(`[BloxForge] proxy registered for ${player.Name} as ${assigned} via ${mcpUrl}`);
 	}
-	task.spawn(pollProxy, proxyId, player, rf);
+	task.spawn(pollProxy, entry, player, rf);
 }
 
 // (Removed: startEditProxyLoop. The play-server DM no longer registers an

package/studio-plugin/src/modules/Communication.ts

@@ -98,6 +98,20 @@ function detectRole(): string {
 
 const initialRole = detectRole();
 
+const activeRequests = new Set<string>();
+const completedRequests = new Map<string, { response: unknown }>();
+const completedRequestOrder: string[] = [];
+const COMPLETED_REQUEST_LIMIT = 500;
+
+const syncThreadRequests = new Map<thread, string>();
+const cancelledSyncRequests = new Set<string>();
+
+function isCancelledForThread(co: thread): boolean {
+	const reqId = syncThreadRequests.get(co);
+	if (reqId === undefined) return false;
+	return cancelledSyncRequests.has(reqId);
+}
+
 type Handler = (data: Record<string, unknown>) => unknown;
 
 const routeMap: Record<string, Handler> = {
@@ -202,14 +216,92 @@ function processRequest(request: RequestPayload): unknown {
 	}
 }
 
-function sendResponse(conn: Connection, requestId: string, responseData: unknown) {
-	pcall(() => {
-		HttpService.RequestAsync({
+function sendResponse(conn: Connection, requestId: string, responseData: unknown, serverEpoch?: string, deliveryAttempt?: number, leaseToken?: string) {
+	const body: Record<string, unknown> = { requestId, response: responseData };
+	if (serverEpoch !== undefined) body.serverEpoch = serverEpoch;
+	if (deliveryAttempt !== undefined) body.deliveryAttempt = deliveryAttempt;
+	if (leaseToken !== undefined) body.leaseToken = leaseToken;
+
+	const [ok, result] = pcall(() => {
+		return HttpService.RequestAsync({
 			Url: `${conn.serverUrl}/response`,
 			Method: "POST",
-			Headers: { "Content-Type": "application/json" },
-			Body: HttpService.JSONEncode({ requestId, response: responseData }),
+			Headers: { 
+				"Content-Type": "application/json",
+				...(conn.sessionToken ? { "Authorization": `Bearer ${conn.sessionToken}` } : {})
+			},
+			Body: HttpService.JSONEncode(body),
+		});
+	});
+
+	if (!ok) {
+		warn(`[BloxForge] Plugin response serialization failed for ${requestId}: ${tostring(result)}`);
+	} else if (!result.Success) {
+		warn(`[BloxForge] Failed to deliver response for ${requestId}: HTTP ${result.StatusCode}`);
+	}
+}
+
+function handleRequestOnce(
+	conn: Connection,
+	requestId: string,
+	request: RequestPayload,
+	serverEpoch?: string,
+	deliveryAttempt?: number,
+	leaseToken?: string
+) {
+	// If we've already completed this request, just re-deliver the cached response
+	const completed = completedRequests.get(requestId);
+	if (completed) {
+		sendResponse(conn, requestId, completed.response, serverEpoch, deliveryAttempt, leaseToken);
+		return;
+	}
+
+	// If it's actively being processed, do nothing. The running thread will deliver
+	// the response when it finishes.
+	if (activeRequests.has(requestId)) return;
+
+	// Acknowledge the fenced request so the server knows we've started work.
+	// This prevents the lease from expiring while we're executing long-running operations.
+	if (serverEpoch !== undefined && deliveryAttempt !== undefined && leaseToken !== undefined) {
+		task.spawn(() => {
+			pcall(() => {
+				HttpService.RequestAsync({
+					Url: `${conn.serverUrl}/ack`,
+					Method: "POST",
+					Headers: { 
+						"Content-Type": "application/json",
+						...(conn.sessionToken ? { "Authorization": `Bearer ${conn.sessionToken}` } : {})
+					},
+					Body: HttpService.JSONEncode({
+						pluginSessionId,
+						requestId,
+						serverEpoch,
+						deliveryAttempt,
+						leaseToken
+					}),
+				});
+			});
 		});
+	}
+
+	activeRequests.add(requestId);
+	task.spawn(() => {
+		const co = coroutine.running();
+		syncThreadRequests.set(co, requestId);
+		const [ok, result] = pcall(() => processRequest(request));
+		syncThreadRequests.delete(co);
+		
+		const response = ok ? result : { error: tostring(result) };
+		activeRequests.delete(requestId);
+		
+		if (completedRequestOrder.size() >= COMPLETED_REQUEST_LIMIT) {
+			const oldest = completedRequestOrder.remove(0);
+			if (oldest !== undefined) completedRequests.delete(oldest);
+		}
+		completedRequests.set(requestId, { response });
+		completedRequestOrder.push(requestId);
+		
+		sendResponse(conn, requestId, response, serverEpoch, deliveryAttempt, leaseToken);
 	});
 }
 
@@ -312,12 +404,34 @@ function sendReady(conn: Connection): void {
 		const [parseOk, readyData] = pcall(
 			() => HttpService.JSONDecode(readyResult.Body) as ReadyResponse,
 		);
+		if (parseOk && readyData.sessionToken) {
+			conn.sessionToken = readyData.sessionToken;
+		}
 		if (parseOk && readyData.assignedRole) {
 			assignedRole = readyData.assignedRole;
 		}
 		lastReadyInstanceId = parseOk && typeIs(readyData.instanceId, "string") && readyData.instanceId !== ""
 			? readyData.instanceId
 			: instanceId;
+			
+		if (parseOk && readyData.serverEpoch && completedRequests.size() > 0) {
+			const receipts: { requestId: string; completedAt: number }[] = [];
+			for (const [id, _] of completedRequests) {
+				receipts.push({ requestId: id, completedAt: tick() * 1000 });
+			}
+			task.spawn(() => {
+				pcall(() => HttpService.RequestAsync({
+					Url: `${conn.serverUrl}/reconcile`,
+					Method: "POST",
+					Headers: { "Content-Type": "application/json" },
+					Body: HttpService.JSONEncode({
+						pluginSessionId,
+						serverEpoch: readyData.serverEpoch,
+						receipts,
+					}),
+				}));
+			});
+		}
 		ServerUrlSettings.rememberServerUrl(conn.serverUrl);
 		const connectedRole = assignedRole ?? detectRole();
 		if (readyFailureLogKeys.has(readyLogKey)) {
@@ -332,16 +446,30 @@ function streamUrl(serverUrl: string): string {
 	return `${websocketUrl}/stream?pluginSessionId=${pluginSessionId}`;
 }
 
-function sendStreamResponse(conn: Connection, requestId: string, response: unknown) {
+function sendStreamResponse(conn: Connection, requestId: string, response: unknown, serverEpoch?: string, deliveryAttempt?: number, leaseToken?: string) {
 	if (!conn.streamOpen || !conn.streamClient) return;
-	pcall(() => conn.streamClient!.Send(HttpService.JSONEncode({ type: "response", requestId, response })));
+	
+	const body: Record<string, unknown> = { type: "response", requestId, response };
+	if (serverEpoch !== undefined) body.serverEpoch = serverEpoch;
+	if (deliveryAttempt !== undefined) body.deliveryAttempt = deliveryAttempt;
+	if (leaseToken !== undefined) body.leaseToken = leaseToken;
+	
+	const [ok, result] = pcall(() => conn.streamClient!.Send(HttpService.JSONEncode(body)));
+	if (!ok) warn(`[BloxForge] Failed to send stream response for ${requestId}: ${tostring(result)}`);
 }
 
 function startRequestStream(conn: Connection) {
 	if (!conn.isActive || conn.streamClient) return;
 	const [ok, stream] = pcall(() => HttpService.CreateWebStreamClient(
 		Enum.WebStreamClientType.WebSocket,
-		{ Url: streamUrl(conn.serverUrl), Method: "GET", Headers: { "Content-Type": "application/json" } },
+		{ 
+			Url: streamUrl(conn.serverUrl), 
+			Method: "GET", 
+			Headers: { 
+				"Content-Type": "application/json",
+				...(conn.sessionToken ? { "Authorization": `Bearer ${conn.sessionToken}` } : {})
+			} 
+		},
 	));
 	if (!ok || !stream) return;
 
@@ -354,12 +482,10 @@ function startRequestStream(conn: Connection) {
 	});
 	stream.MessageReceived.Connect((message) => {
 		if (conn.streamClient !== stream) return;
-		const [parsed, frame] = pcall(() => HttpService.JSONDecode(message) as { type?: string; requestId?: string; request?: RequestPayload });
+		const [parsed, frame] = pcall(() => HttpService.JSONDecode(message) as { type?: string; requestId?: string; request?: RequestPayload; serverEpoch?: string; deliveryAttempt?: number; leaseToken?: string });
 		if (!parsed || frame.type !== "request" || !frame.requestId || !frame.request) return;
-		task.spawn(() => {
-			const [handled, response] = pcall(() => processRequest(frame.request!));
-			sendStreamResponse(conn, frame.requestId!, handled ? response : { error: tostring(response) });
-		});
+		
+		handleRequestOnce(conn, frame.requestId!, frame.request!, frame.serverEpoch, frame.deliveryAttempt, frame.leaseToken);
 	});
 	const close = () => {
 		if (conn.streamClient !== stream) return;
@@ -382,7 +508,10 @@ function pollForRequests(connIndex: number) {
 		return HttpService.RequestAsync({
 			Url: `${conn.serverUrl}/poll?pluginSessionId=${pluginSessionId}`,
 			Method: "GET",
-			Headers: { "Content-Type": "application/json" },
+			Headers: { 
+				"Content-Type": "application/json",
+				...(conn.sessionToken ? { "Authorization": `Bearer ${conn.sessionToken}` } : {})
+			},
 		});
 	});
 
@@ -489,15 +618,14 @@ function pollForRequests(connIndex: number) {
 			}
 		}
 
+		if (data.cancellations) {
+			for (const c of data.cancellations) {
+				cancelledSyncRequests.add(c);
+			}
+		}
+
 		if (data.request && mcpConnected) {
-			task.spawn(() => {
-				const [ok, response] = pcall(() => processRequest(data.request!));
-				if (ok) {
-					sendResponse(conn, data.requestId!, response);
-				} else {
-					sendResponse(conn, data.requestId!, { error: tostring(response) });
-				}
-			});
+			handleRequestOnce(conn, data.requestId!, data.request, data.serverEpoch, data.deliveryAttempt, data.leaseToken);
 		}
 	} else if (conn.isActive) {
 		conn.consecutiveFailures++;
@@ -710,6 +838,7 @@ function checkForUpdates() {
 
 export = {
 	getConnectionStatus,
+	isCancelledForThread,
 	activatePlugin,
 	deactivatePlugin,
 	deactivateAll,

package/studio-plugin/src/modules/RuntimeLogBuffer.ts

@@ -46,6 +46,30 @@ function nowSec(): number {
 	return DateTime.now().UnixTimestampMillis / 1000;
 }
 
+// Studio can expose binary-bearing Output messages that JSONEncode rejects.
+// Preserve valid UTF-8 and make only malformed bytes visible and JSON-safe.
+function escapeInvalidUtf8(message: string): string {
+	const [valid] = utf8.len(message);
+	if (typeIs(valid, "number")) return message;
+
+	const parts: string[] = [];
+	let cursor = 1;
+	while (cursor <= message.size()) {
+		const [suffixValid, invalidPosition] = utf8.len(message, cursor);
+		if (typeIs(suffixValid, "number")) {
+			parts.push(string.sub(message, cursor));
+			break;
+		}
+		if (!typeIs(invalidPosition, "number")) break;
+		if (invalidPosition > cursor) parts.push(string.sub(message, cursor, invalidPosition - 1));
+
+		const [invalidByte] = string.byte(message, invalidPosition);
+		parts.push(string.format("\\x%02X", invalidByte));
+		cursor = invalidPosition + 1;
+	}
+	return parts.join("");
+}
+
 function dropOldestUntilFits(incomingBytes: number): void {
 	while (
 		entries.size() > 0 &&
@@ -58,9 +82,14 @@ function dropOldestUntilFits(incomingBytes: number): void {
 }
 
 function pushEntry(message: string, level: LogLevel, ts: number): void {
-	const bytes = message.size();
+	const safeMessage = escapeInvalidUtf8(message);
+	const bytes = safeMessage.size();
+	if (bytes > MAX_BYTES) {
+		totalDropped += 1;
+		return;
+	}
 	dropOldestUntilFits(bytes);
-	entries.push({ seq: nextSeq, ts, level, message });
+	entries.push({ seq: nextSeq, ts, level, message: safeMessage });
 	nextSeq += 1;
 	totalBytes += bytes;
 }

package/studio-plugin/src/modules/State.ts

@@ -2,7 +2,7 @@ import { Connection } from "../types";
 
 const CURRENT_VERSION = "__VERSION__";
 const PLUGIN_VARIANT = "__PLUGIN_VARIANT__";
-const PROTOCOL_VERSION = 1;
+const PROTOCOL_VERSION = 3;
 const MAX_CONNECTIONS = 5;
 const BASE_PORT = 58741;
 let activeTabIndex = 0;

package/studio-plugin/src/modules/handlers/JobHandlers.ts

@@ -7,6 +7,7 @@
 
 import LuauExec from "../LuauExec";
 import JobRegistry from "../JobRegistry";
+import Communication from "../Communication";
 
 // Install a sanctioned progress/cancel API once. Server-generated long-running
 // Luau (terrain/template/batch builders) can call _G.__mcp.progress(done,total,msg)
@@ -19,7 +20,7 @@ function installMcpGlobal(): void {
 		progress: (done: number, total?: number, message?: string, stage?: string) => {
 			JobRegistry.reportProgress(coroutine.running(), done, total, message, stage);
 		},
-		checkCancelled: () => JobRegistry.isCancelledForThread(coroutine.running()),
+		checkCancelled: () => JobRegistry.isCancelledForThread(coroutine.running()) || Communication.isCancelledForThread(coroutine.running()),
 	};
 }
 installMcpGlobal();

package/studio-plugin/src/types/index.d.ts

@@ -3,6 +3,7 @@
 export interface Connection {
 	port: number;
 	serverUrl: string;
+	sessionToken?: string;
 	isActive: boolean;
 	pollInterval: number;
 	lastPoll: number;
@@ -43,10 +44,14 @@ export interface PollResponse {
 	protocolMismatch?: boolean;
 	request?: RequestPayload;
 	requestId?: string;
+	serverEpoch?: string;
+	deliveryAttempt?: number;
+	leaseToken?: string;
 	// Server signals knownInstance=false when its in-memory instances map
 	// doesn't contain our pluginSessionId (typically after an MCP process
 	// restart). The plugin re-issues /ready when it sees this.
 	knownInstance?: boolean;
+	cancellations?: string[];
 }
 
 export interface Job {
@@ -74,6 +79,8 @@ export interface ReadyResponse {
 	serverProtocolVersion?: number;
 	versionMismatch?: boolean;
 	protocolMismatch?: boolean;
+	sessionToken?: string;
+	serverEpoch?: string;
 	error?: string;
 	message?: string;
 }