@princeofscale/bloxforge 2.20.2

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

@@ -0,0 +1,152 @@
+// Per-capture in-memory ring buffer for LogService.MessageOut events.
+// Powers the get_runtime_logs MCP tool. Replaces the out-of-tree LogBuffer
+// primitives + StringValue approach from chrrxs/roblox-mcp-primitives.
+//
+// Each peer's plugin attaches a MessageOut listener at plugin load (edit DM,
+// play-server DM, play-client DM all run their own copy of this module).
+// Captured entries live in plugin module-state; nothing is parented to the
+// DataModel. The buffer is bounded by a message-byte budget; oldest entries
+// drop when over budget.
+//
+// Capture caveat: returned entries reflect which plugin buffer CAPTURED the
+// entry, NOT which peer's script originated the print. LogService reflects
+// prints across peers in ordinary Studio Play (a server print can appear in
+// server and client LogService:GetLogHistory()). The MCP-side aggregator
+// exposes that as capturedBy, and only promotes it to origin peer in
+// StudioTestService multiplayer sessions where peer attribution is reliable.
+
+import { LogService, RunService } from "@rbxts/services";
+
+type LogLevel = "OUT" | "WARN" | "ERR" | "INFO";
+
+interface RuntimeLogEntry {
+	seq: number;
+	ts: number; // wall-clock seconds via DateTime, coherent across peers
+	level: LogLevel;
+	message: string;
+}
+
+const MAX_BYTES = 64 * 1024;
+const HARD_ENTRY_CAP = 50_000;
+
+const entries: RuntimeLogEntry[] = [];
+let totalBytes = 0;
+let totalDropped = 0;
+let nextSeq = 1;
+let installed = false;
+
+function levelTag(t: Enum.MessageType): LogLevel {
+	if (t === Enum.MessageType.MessageWarning) return "WARN";
+	if (t === Enum.MessageType.MessageError) return "ERR";
+	if (t === Enum.MessageType.MessageInfo) return "INFO";
+	return "OUT";
+}
+
+function nowSec(): number {
+	return DateTime.now().UnixTimestampMillis / 1000;
+}
+
+function dropOldestUntilFits(incomingBytes: number): void {
+	while (
+		entries.size() > 0 &&
+		(totalBytes + incomingBytes > MAX_BYTES || entries.size() >= HARD_ENTRY_CAP)
+	) {
+		const dropped = entries.shift()!;
+		totalBytes -= dropped.message.size();
+		totalDropped += 1;
+	}
+}
+
+function pushEntry(message: string, level: LogLevel, ts: number): void {
+	const bytes = message.size();
+	dropOldestUntilFits(bytes);
+	entries.push({ seq: nextSeq, ts, level, message });
+	nextSeq += 1;
+	totalBytes += bytes;
+}
+
+// Backfill the buffer with logs already emitted before this listener attached.
+// In ordinary Studio Play the server/client DMs start (and print, e.g. a game's
+// startup banner) before the plugin peer's MessageOut listener connects, so those
+// entries were lost (bug B8). GetLogHistory recovers them on install.
+function seedFromHistory(): void {
+	const [ok, history] = pcall(() => LogService.GetLogHistory());
+	if (!ok || !history) return;
+	for (const info of history as Array<{ message: string; messageType: Enum.MessageType; timestamp: number }>) {
+		if (info && typeIs(info.message, "string")) {
+			pushEntry(info.message, levelTag(info.messageType), info.timestamp ?? nowSec());
+		}
+	}
+}
+
+function install(): void {
+	if (installed) return;
+	if (!RunService.IsStudio()) return;
+	installed = true;
+	seedFromHistory();
+	LogService.MessageOut.Connect((msg, t) => {
+		pushEntry(msg, levelTag(t), nowSec());
+	});
+}
+
+function detectPeer(): "edit" | "server" | "client" {
+	if (!RunService.IsRunning()) return "edit";
+	if (RunService.IsServer()) return "server";
+	return "client";
+}
+
+interface QueryOptions {
+	since?: number;
+	tail?: number;
+	filter?: string; // Plain substring match, applied to message
+}
+
+interface QueryResult {
+	capturedBy: string;
+	entries: RuntimeLogEntry[];
+	totalDropped: number;
+	nextSince: number;
+}
+
+function query(opts: QueryOptions, capturedBy: string): QueryResult {
+	let result = opts.since !== undefined
+		? entries.filter((e) => e.seq > (opts.since as number))
+		: [...entries];
+
+	if (opts.filter !== undefined) {
+		// Plain substring search (4th arg = true). Pattern matching here was
+		// surprising in practice - Lua magic chars in messages would silently
+		// not match (e.g. filter="MARK-EDIT" against "MARK-EDIT-001" fails
+		// because '-' means "0+" in Lua patterns). Substring search matches
+		// most users' mental model of "filter messages containing this text".
+		const needle = opts.filter;
+		result = result.filter((e) => {
+			const [start] = string.find(e.message, needle, 1, true);
+			return start !== undefined;
+		});
+	}
+
+	if (opts.tail !== undefined && result.size() > opts.tail) {
+		// roblox-ts arrays don't expose .slice; manual tail copy.
+		const tailed: RuntimeLogEntry[] = [];
+		const start = result.size() - opts.tail;
+		for (let i = start; i < result.size(); i++) {
+			tailed.push(result[i]);
+		}
+		result = tailed;
+	}
+
+	const last = entries.size() > 0 ? entries[entries.size() - 1] : undefined;
+	return {
+		capturedBy,
+		entries: result,
+		totalDropped,
+		nextSince: last ? last.seq : (opts.since ?? 0),
+	};
+}
+
+export = {
+	install,
+	detectPeer,
+	query,
+};

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

@@ -0,0 +1,114 @@
+import { HttpService, ServerStorage } from "@rbxts/services";
+
+const LEGACY_SETTING_KEY_PREFIX = "MCP_SERVER_URL_";
+const SETTING_KEY_PREFIX = "MCP_LAST_SUCCESSFUL_SERVER_URL_";
+const GLOBAL_SETTING_KEY = "MCP_LAST_SUCCESSFUL_SERVER_URL_GLOBAL_V1";
+
+let pluginRef: Plugin | undefined;
+
+function init(p: Plugin): void {
+	pluginRef = p;
+}
+
+function normalizeServerUrl(serverUrl: string | undefined): string {
+	let normalized = (serverUrl ?? "").gsub("^%s+", "")[0].gsub("%s+$", "")[0];
+	if (normalized === "") return "";
+
+	if (normalized.match("^%a[%w+.-]*://")[0] === undefined) {
+		normalized = `http://${normalized}`;
+	}
+
+	while (
+		normalized.size() > 0 &&
+		normalized.sub(-1) === "/" &&
+		normalized.match("^%a[%w+.-]*://$")[0] === undefined
+	) {
+		normalized = normalized.sub(1, -2);
+	}
+
+	return normalized;
+}
+
+function extractPort(serverUrl: string): number | undefined {
+	const [portStr] = serverUrl.match(":(%d+)$");
+	if (portStr === undefined) return undefined;
+	return tonumber(portStr);
+}
+
+function addUnique(values: string[], value: string): void {
+	if (!values.includes(value)) {
+		values.push(value);
+	}
+}
+
+function computeInstanceIds(): string[] {
+	const ids: string[] = [];
+	if (game.PlaceId !== 0) {
+		addUnique(ids, `place:${tostring(game.PlaceId)}`);
+	}
+	const existing = ServerStorage.GetAttribute("__MCPPlaceId");
+	if (typeIs(existing, "string") && existing !== "") {
+		addUnique(ids, `anon:${existing as string}`);
+	} else if (game.PlaceId === 0) {
+		const fresh = HttpService.GenerateGUID(false);
+		pcall(() => ServerStorage.SetAttribute("__MCPPlaceId", fresh));
+		addUnique(ids, `anon:${fresh}`);
+	}
+	return ids;
+}
+
+function settingKey(instanceId: string): string {
+	return SETTING_KEY_PREFIX + instanceId;
+}
+
+function legacySettingKey(instanceId: string): string {
+	return LEGACY_SETTING_KEY_PREFIX + instanceId;
+}
+
+function readSettingString(key: string): string | undefined {
+	if (!pluginRef) return undefined;
+	const [ok, value] = pcall(() => pluginRef!.GetSetting(key));
+	if (!ok || !typeIs(value, "string")) return undefined;
+
+	const normalized = normalizeServerUrl(value as string);
+	return normalized !== "" ? normalized : undefined;
+}
+
+function writeSettingString(key: string, serverUrl: string): void {
+	if (!pluginRef) return;
+	pcall(() => pluginRef!.SetSetting(key, serverUrl));
+}
+
+function rememberServerUrl(serverUrl: string): void {
+	const normalized = normalizeServerUrl(serverUrl);
+	if (!pluginRef || normalized === "") return;
+	writeSettingString(GLOBAL_SETTING_KEY, normalized);
+	for (const instanceId of computeInstanceIds()) {
+		writeSettingString(settingKey(instanceId), normalized);
+		writeSettingString(legacySettingKey(instanceId), normalized);
+	}
+}
+
+function readServerUrl(): string | undefined {
+	if (!pluginRef) return undefined;
+	for (const instanceId of computeInstanceIds()) {
+		const remembered = readSettingString(settingKey(instanceId));
+		if (remembered !== undefined) return remembered;
+	}
+	const globalRemembered = readSettingString(GLOBAL_SETTING_KEY);
+	if (globalRemembered !== undefined) return globalRemembered;
+	for (const instanceId of computeInstanceIds()) {
+		const legacyRemembered = readSettingString(legacySettingKey(instanceId));
+		if (legacyRemembered !== undefined) return legacyRemembered;
+	}
+
+	return undefined;
+}
+
+export = {
+	init,
+	normalizeServerUrl,
+	extractPort,
+	rememberServerUrl,
+	readServerUrl,
+};

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

@@ -0,0 +1,101 @@
+import { Connection } from "../types";
+
+const CURRENT_VERSION = "__VERSION__";
+const PLUGIN_VARIANT = "__PLUGIN_VARIANT__";
+const PROTOCOL_VERSION = 1;
+const MAX_CONNECTIONS = 5;
+const BASE_PORT = 58741;
+let activeTabIndex = 0;
+
+function createConnection(port: number): Connection {
+	return {
+		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: undefined,
+		isPolling: false,
+		streamOpen: false,
+		lastStreamHeartbeat: 0,
+		nextStreamRetryAt: 0,
+		heartbeatConnection: undefined,
+	};
+}
+
+const connections: Connection[] = [createConnection(BASE_PORT)];
+
+function addConnection(port?: number): number | undefined {
+	if (connections.size() >= MAX_CONNECTIONS) {
+		return undefined;
+	}
+	if (port === undefined) {
+		let maxPort = BASE_PORT - 1;
+		for (const conn of connections) {
+			if (conn.port > maxPort) maxPort = conn.port;
+		}
+		port = maxPort + 1;
+	}
+	const conn = createConnection(port);
+	connections.push(conn);
+	return connections.size() - 1;
+}
+
+function removeConnection(index: number): boolean {
+	if (connections.size() <= 1) return false;
+	if (index < 0 || index >= connections.size()) return false;
+	if (connections[index].isActive) return false;
+
+	connections.remove(index);
+
+	if (activeTabIndex >= connections.size()) {
+		activeTabIndex = connections.size() - 1;
+	} else if (activeTabIndex > index) {
+		activeTabIndex -= 1;
+	}
+	return true;
+}
+
+function getActiveConnection(): Connection {
+	return connections[activeTabIndex];
+}
+
+function getConnection(index: number): Connection | undefined {
+	return connections[index];
+}
+
+function getActiveTabIndex(): number {
+	return activeTabIndex;
+}
+
+function setActiveTabIndex(index: number): void {
+	activeTabIndex = index;
+}
+
+function getConnections(): Connection[] {
+	return connections;
+}
+
+export = {
+	CURRENT_VERSION,
+	PLUGIN_VARIANT,
+	PROTOCOL_VERSION,
+	MAX_CONNECTIONS,
+	BASE_PORT,
+	connections,
+	addConnection,
+	removeConnection,
+	getActiveConnection,
+	getConnection,
+	getActiveTabIndex,
+	setActiveTabIndex,
+	getConnections,
+};

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

@@ -0,0 +1,276 @@
+// Cross-DM stop_playtest signaling via plugin:SetSetting, scoped by
+// per-instance setting key so the same Studio process can host playtests
+// for multiple places without one place's stop_playtest yanking another's.
+// During publish-after-connect, both "anon:<uuid>" and "place:<PlaceId>"
+// can refer to the same Studio place, so stop requests are mirrored across
+// both keys while the monitor waits for a matching result on either key.
+//
+// `plugin:SetSetting` / `plugin:GetSetting` is a per-plugin persistent store
+// shared across every DataModel the plugin runs in (edit DMs, play-server
+// DMs, play-client DMs). For each connected place we use a dedicated key
+// "MCP_STOP_PLAY_<instanceId>" as a tiny request/result mailbox:
+//
+//   * The edit DM's handler writes a tokenized stop request into its own key
+//     (computed from its placeId / ServerStorage anon UUID).
+//   * Each play-server DM's monitor loop polls the key matching its own
+//     instanceId at 1Hz. On a fresh token, it calls StudioTestService:EndTest
+//     and writes a matching result token. Play-server DMs for other places
+//     never touch this key.
+//   * The edit DM waits up to ~8s for its result token, confirming a matching
+//     play-server actually consumed the request.
+//
+// Earlier versions used a single shared boolean flag, which let any
+// play-server DM in the same Studio process consume any place's stop
+// request — silently yanking teammates' playtests. The per-key scoping
+// below is the fix.
+
+import { HttpService, RunService, ServerStorage } from "@rbxts/services";
+
+const StudioTestService = game.GetService("StudioTestService");
+
+const SETTING_KEY_PREFIX = "MCP_STOP_PLAY_";
+// Keep this conservative. plugin:GetSetting is backed by Studio's plugin
+// settings store, and this monitor runs during every play session, including
+// manually-started Play. The official reference implementation polls at 1s.
+const POLL_INTERVAL_SEC = 1;
+// Total time we wait for the matching play-server DM to consume the
+// signal. Must cover: monitor detection (<= POLL_INTERVAL_SEC) +
+// StudioTestService:EndTest teardown (several seconds on heavier places).
+// 8s is intentionally shorter than the MCP request timeout but long enough
+// for the 1s monitor cadence plus ordinary Studio teardown latency.
+const WAIT_FOR_CONSUMPTION_TIMEOUT_SEC = 8.0;
+const WAIT_POLL_SEC = 0.1;
+const REQUEST_TTL_SEC = 12.0;
+
+let pluginRef: Plugin | undefined;
+let endTestIssued = false;
+
+interface StopPayload {
+	kind?: string;
+	id?: string;
+	requestedAt?: number;
+	consumedAt?: number;
+	ok?: boolean;
+	error?: string;
+	alreadyEnded?: boolean;
+}
+
+interface StopRequestResult {
+	ok: boolean;
+	requestId?: string;
+}
+
+interface StopConsumptionResult {
+	ok: boolean;
+	consumed: boolean;
+	error?: string;
+	alreadyEnded?: boolean;
+}
+
+function init(p: Plugin): void {
+	pluginRef = p;
+}
+
+// Mirror of Communication.computeInstanceId(). 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
+// into the play DM).
+function addUnique(values: string[], value: string): void {
+	if (!values.includes(value)) {
+		values.push(value);
+	}
+}
+
+function computeInstanceIds(): string[] {
+	const ids: string[] = [];
+	if (game.PlaceId !== 0) {
+		addUnique(ids, `place:${tostring(game.PlaceId)}`);
+	}
+	const existing = ServerStorage.GetAttribute("__MCPPlaceId");
+	if (typeIs(existing, "string") && existing !== "") {
+		addUnique(ids, `anon:${existing as string}`);
+	} else if (game.PlaceId === 0) {
+		const fresh = HttpService.GenerateGUID(false);
+		pcall(() => ServerStorage.SetAttribute("__MCPPlaceId", fresh));
+		addUnique(ids, `anon:${fresh}`);
+	}
+	return ids;
+}
+
+function settingKey(instanceId: string): string {
+	return SETTING_KEY_PREFIX + instanceId;
+}
+
+function settingKeys(): string[] {
+	return computeInstanceIds().map((instanceId) => settingKey(instanceId));
+}
+
+function readSetting(key: string): unknown {
+	if (!pluginRef) return undefined;
+	const [ok, value] = pcall(() => pluginRef!.GetSetting(key));
+	return ok ? value : undefined;
+}
+
+function writeSetting(key: string, value: unknown): boolean {
+	if (!pluginRef) return false;
+	const [ok] = pcall(() => pluginRef!.SetSetting(key, value));
+	return ok;
+}
+
+function decodePayload(value: unknown): StopPayload | undefined {
+	let decoded = value;
+	if (typeIs(value, "string")) {
+		const [ok, result] = pcall(() => HttpService.JSONDecode(value as string));
+		if (!ok) return undefined;
+		decoded = result;
+	}
+	if (!typeIs(decoded, "table")) return undefined;
+	const payload = decoded as StopPayload;
+	if (!typeIs(payload.kind, "string") || !typeIs(payload.id, "string")) {
+		return undefined;
+	}
+	return payload;
+}
+
+function writePayload(key: string, payload: StopPayload): boolean {
+	const [encodedOk, encoded] = pcall(() => HttpService.JSONEncode(payload));
+	if (!encodedOk || !typeIs(encoded, "string")) return false;
+	return writeSetting(key, encoded);
+}
+
+function writeResult(key: string, request: StopPayload, ok: boolean, errText?: string, alreadyEnded?: boolean): void {
+	writePayload(key, {
+		kind: "result",
+		id: request.id,
+		requestedAt: request.requestedAt,
+		consumedAt: tick(),
+		ok,
+		error: errText,
+		alreadyEnded,
+	});
+}
+
+function handleStopRequest(key: string, request: StopPayload): void {
+	if (request.kind !== "request" || !typeIs(request.id, "string")) return;
+	if (!typeIs(request.requestedAt, "number")) {
+		writeSetting(key, false);
+		return;
+	}
+
+	const age = tick() - request.requestedAt;
+	if (age < -5 || age > REQUEST_TTL_SEC) {
+		writeSetting(key, false);
+		return;
+	}
+
+	if (endTestIssued) {
+		writeResult(
+			key,
+			request,
+			true,
+			undefined,
+			true,
+		);
+		return;
+	}
+
+	if (!RunService.IsRunning() || !RunService.IsServer()) {
+		writeResult(key, request, false, "StopPlayMonitor is not running in the server DataModel.");
+		return;
+	}
+
+	endTestIssued = true;
+	const [endOk, endErr] = pcall(() => StudioTestService.EndTest("stopped_by_mcp"));
+	if (!endOk && (tostring(endErr).find("EndTest can only be called once")[0] !== undefined || tostring(endErr).find("can only be called once")[0] !== undefined)) {
+		writeResult(key, request, true, undefined, true);
+		return;
+	}
+	writeResult(key, request, endOk, endOk ? undefined : tostring(endErr));
+	if (!endOk) {
+		endTestIssued = false;
+	}
+}
+
+function startMonitor(): void {
+	if (!pluginRef) {
+		warn("[BloxForge] StopPlayMonitor.startMonitor called before init; skipping");
+		return;
+	}
+	task.spawn(() => {
+		while (true) {
+			for (const myKey of settingKeys()) {
+				const value = readSetting(myKey);
+				if (value === true) {
+					// Legacy boolean requests are ambiguous and may be stale from
+					// a prior crashed session. New stop requests use token payloads.
+					writeSetting(myKey, false);
+				} else {
+					const payload = decodePayload(value);
+					if (payload) {
+						handleStopRequest(myKey, payload);
+					}
+				}
+			}
+			task.wait(POLL_INTERVAL_SEC);
+		}
+	});
+}
+
+function requestStop(): StopRequestResult {
+	if (!pluginRef) return { ok: false };
+	const requestId = HttpService.GenerateGUID(false);
+	const payload: StopPayload = {
+		kind: "request",
+		id: requestId,
+		requestedAt: tick(),
+	};
+	let ok = false;
+	for (const myKey of settingKeys()) {
+		ok = writePayload(myKey, payload) || ok;
+	}
+	return { ok, requestId: ok ? requestId : undefined };
+}
+
+function waitForConsumption(requestId: string): StopConsumptionResult {
+	if (!pluginRef) return { ok: false, consumed: false, error: "Plugin reference is not initialized." };
+	const start = tick();
+	while (tick() - start < WAIT_FOR_CONSUMPTION_TIMEOUT_SEC) {
+		for (const myKey of settingKeys()) {
+			const payload = decodePayload(readSetting(myKey));
+			if (payload && payload.kind === "result" && payload.id === requestId) {
+				return {
+					ok: payload.ok === true,
+					consumed: true,
+					error: payload.error,
+					alreadyEnded: payload.alreadyEnded,
+				};
+			}
+		}
+		task.wait(WAIT_POLL_SEC);
+	}
+	return {
+		ok: false,
+		consumed: false,
+		error: "Timed out waiting for the play-server DataModel to acknowledge stop_playtest.",
+	};
+}
+
+function clearPending(requestId?: string): void {
+	if (!pluginRef) return;
+	for (const myKey of settingKeys()) {
+		if (requestId !== undefined) {
+			const payload = decodePayload(readSetting(myKey));
+			if (payload && payload.id !== requestId) continue;
+		}
+		writeSetting(myKey, false);
+	}
+}
+
+export = {
+	init,
+	startMonitor,
+	requestStop,
+	waitForConsumption,
+	clearPending,
+};