@quenty/studio-bridge 0.22.1 → 0.24.0

package/src/roblox-mcp/studio-mcp-snapshot.test.ts

@@ -0,0 +1,113 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  getStudioMcpSnapshotAsync,
+  resetStudioMcpSnapshot,
+} from './studio-mcp-snapshot.js';
+import type { StudioMcpResult, StudioMcpTarget } from './roblox-studio-mcp.js';
+
+type ListResult = StudioMcpResult<StudioMcpTarget[]>;
+
+const OK: ListResult = {
+  success: true,
+  value: [{ studioId: 'mcp-1', placeName: 'Place1' }],
+};
+
+describe('getStudioMcpSnapshotAsync', () => {
+  beforeEach(() => resetStudioMcpSnapshot());
+  afterEach(() => vi.useRealTimers());
+
+  it('waits for the first check and reports the Studios it found', async () => {
+    const listAsync = vi.fn(async () => OK);
+
+    const snapshot = await getStudioMcpSnapshotAsync({ listAsync });
+
+    expect(snapshot).toMatchObject({
+      status: 'ok',
+      studios: [{ studioId: 'mcp-1' }],
+    });
+    expect(listAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ readPlaceIds: false, timeoutMs: 3000 })
+    );
+  });
+
+  it('reuses a fresh snapshot without checking again', async () => {
+    const listAsync = vi.fn(async () => OK);
+
+    await getStudioMcpSnapshotAsync({ listAsync });
+    await getStudioMcpSnapshotAsync({ listAsync });
+
+    expect(listAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('answers with the stale snapshot at once and refreshes in the background', async () => {
+    let resolveSecond: (result: ListResult) => void = () => {};
+    const listAsync = vi
+      .fn<() => Promise<ListResult>>()
+      .mockResolvedValueOnce(OK)
+      .mockImplementationOnce(
+        () => new Promise((resolve) => (resolveSecond = resolve))
+      );
+
+    const first = await getStudioMcpSnapshotAsync({ listAsync, maxAgeMs: 0 });
+    const second = await getStudioMcpSnapshotAsync({ listAsync, maxAgeMs: 0 });
+
+    expect(second).toBe(first);
+    expect(listAsync).toHaveBeenCalledTimes(2);
+    resolveSecond({ success: false, reason: 'timeout', message: 'slow' });
+    await new Promise((resolve) => setImmediate(resolve));
+    const third = await getStudioMcpSnapshotAsync({ listAsync });
+    expect(third).toMatchObject({
+      status: 'timeout',
+      message: 'slow',
+      lastOkAt: first?.checkedAt,
+    });
+  });
+
+  it('runs one check at a time', async () => {
+    let finish: (result: ListResult) => void = () => {};
+    const listAsync = vi.fn(
+      () => new Promise<ListResult>((resolve) => (finish = resolve))
+    );
+
+    const both = Promise.all([
+      getStudioMcpSnapshotAsync({ listAsync }),
+      getStudioMcpSnapshotAsync({ listAsync }),
+    ]);
+    finish(OK);
+    await both;
+
+    expect(listAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('gives up waiting rather than hang when the first check does not finish', async () => {
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+    const listAsync = vi.fn(() => new Promise<ListResult>(() => {}));
+    let settled = false;
+
+    const pending = getStudioMcpSnapshotAsync({ listAsync }).then((s) => {
+      settled = true;
+      return s;
+    });
+    await vi.advanceTimersByTimeAsync(3000);
+    expect(settled).toBe(false);
+    await vi.advanceTimersByTimeAsync(250);
+
+    expect(await pending).toBeUndefined();
+  });
+
+  it('records a failure with its reason', async () => {
+    const listAsync = vi.fn(
+      async (): Promise<ListResult> => ({
+        success: false,
+        reason: 'unavailable',
+        message: 'not installed',
+      })
+    );
+
+    expect(await getStudioMcpSnapshotAsync({ listAsync })).toMatchObject({
+      status: 'unavailable',
+      message: 'not installed',
+      studios: [],
+    });
+  });
+});

package/src/roblox-mcp/studio-mcp-snapshot.ts

@@ -0,0 +1,104 @@
+import type { SessionInfo } from '../bridge/types.js';
+import type { StudioWindow } from './studio/studio-session.js';
+import {
+  tryListStudiosAsync,
+  type StudioMcpFailure,
+  type StudioMcpOptions,
+  type StudioMcpResult,
+  type StudioMcpTarget,
+} from './roblox-studio-mcp.js';
+
+export interface StudioMcpSnapshot {
+  status: 'ok' | StudioMcpFailure;
+  studios: StudioMcpTarget[];
+  message?: string;
+  checkedAt: number;
+  latencyMs: number;
+  lastOkAt?: number;
+  settled?: boolean;
+}
+
+export interface StudioMcpSnapshotOptions {
+  sessions?: SessionInfo[];
+  sessionPids?: Map<string, number>;
+  windows?: StudioWindow[];
+  maxWaitMs?: number;
+  maxAgeMs?: number;
+  listAsync?: (
+    options: StudioMcpOptions
+  ) => Promise<StudioMcpResult<StudioMcpTarget[]>>;
+}
+
+const DEFAULT_MAX_WAIT_MS = 3000;
+const DEFAULT_MAX_AGE_MS = 5000;
+
+let _cached: StudioMcpSnapshot | undefined;
+let _inFlight: Promise<StudioMcpSnapshot> | undefined;
+
+export async function getStudioMcpSnapshotAsync(
+  options: StudioMcpSnapshotOptions = {}
+): Promise<StudioMcpSnapshot | undefined> {
+  const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+  const maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+  if (_cached && Date.now() - _cached.checkedAt < maxAgeMs) {
+    return _cached;
+  }
+
+  _inFlight ??= _refreshAsync(options, maxWaitMs).finally(() => {
+    _inFlight = undefined;
+  });
+  if (_cached) {
+    return _cached;
+  }
+
+  let timer: NodeJS.Timeout | undefined;
+  const gaveUp = new Promise<undefined>((resolve) => {
+    timer = setTimeout(() => resolve(undefined), maxWaitMs + 250);
+  });
+  try {
+    return await Promise.race([_inFlight, gaveUp]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function resetStudioMcpSnapshot(): void {
+  _cached = undefined;
+  _inFlight = undefined;
+}
+
+async function _refreshAsync(
+  options: StudioMcpSnapshotOptions,
+  timeoutMs: number
+): Promise<StudioMcpSnapshot> {
+  const startedAt = Date.now();
+  const result = await (options.listAsync ?? tryListStudiosAsync)({
+    sessions: options.sessions,
+    sessionPids: options.sessionPids,
+    ...(options.windows
+      ? { listWindowsAsync: async () => options.windows! }
+      : {}),
+    timeoutMs,
+    readPlaceIds: false,
+  });
+  const checkedAt = Date.now();
+  const snapshot: StudioMcpSnapshot = result.success
+    ? {
+        status: 'ok',
+        studios: result.value,
+        settled: result.settled !== false,
+        checkedAt,
+        latencyMs: checkedAt - startedAt,
+        lastOkAt: checkedAt,
+      }
+    : {
+        status: result.reason,
+        studios: [],
+        message: result.message,
+        checkedAt,
+        latencyMs: checkedAt - startedAt,
+        lastOkAt: _cached?.lastOkAt,
+      };
+  _cached = snapshot;
+  return snapshot;
+}

package/src/roblox-mcp/test/fake-mcp-server.ts

@@ -0,0 +1,74 @@
+import { EventEmitter } from 'events';
+import { PassThrough } from 'stream';
+import type { ChildProcessWithoutNullStreams } from 'child_process';
+
+export type FakeHandler = (
+  method: string,
+  params: any
+) =>
+  | { result?: unknown; error?: { code: number; message: string } }
+  | undefined;
+
+export interface FakeMcpServer {
+  child: ChildProcessWithoutNullStreams;
+  requests: Array<{ method: string; params: any }>;
+  exit(code: number, stderr?: string): void;
+}
+
+export function createFakeMcpServer(handler: FakeHandler): FakeMcpServer {
+  const stdin = new PassThrough();
+  const stdout = new PassThrough();
+  const stderr = new PassThrough();
+  const child = Object.assign(new EventEmitter(), {
+    stdin,
+    stdout,
+    stderr,
+    exitCode: null as number | null,
+    killed: false,
+    kill() {
+      child.killed = true;
+      child.emit('close', null);
+      return true;
+    },
+  });
+  const requests: FakeMcpServer['requests'] = [];
+
+  let buffer = '';
+  stdin.setEncoding('utf8');
+  stdin.on('data', (chunk: string) => {
+    buffer += chunk;
+    let newline: number;
+    while ((newline = buffer.indexOf('\n')) >= 0) {
+      const message = JSON.parse(buffer.slice(0, newline));
+      buffer = buffer.slice(newline + 1);
+      requests.push({ method: message.method, params: message.params });
+      if (message.id === undefined) {
+        continue;
+      }
+      const reply = handler(message.method, message.params);
+      if (reply) {
+        stdout.write(
+          JSON.stringify({ jsonrpc: '2.0', id: message.id, ...reply }) + '\n'
+        );
+      }
+    }
+  });
+
+  return {
+    child: child as unknown as ChildProcessWithoutNullStreams,
+    requests,
+    exit(code, text) {
+      if (text) {
+        stderr.write(text);
+      }
+      setImmediate(() => {
+        child.exitCode = code;
+        child.emit('close', code);
+      });
+    },
+  };
+}
+
+export function toolText(text: string, isError = false) {
+  return { result: { content: [{ type: 'text', text }], isError } };
+}

package/src/server/web-socket-protocol.ts

@@ -23,6 +23,8 @@ export type PluginContext = 'edit' | 'client' | 'server';
  */
 export const MAX_MESSAGE_BYTES = 512 * 1024 * 1024;
 
+export const MAX_EXECUTE_INPUT_BYTES = 192 * 1024 * 1024;
+
 export type Capability =
   | 'execute'
   | 'queryState'
@@ -35,6 +37,7 @@ export type Capability =
   | 'grepScripts'
   | 'startPlaytest'
   | 'endPlaytest'
+  | 'playtestPlayers'
   | 'heartbeat'
   | 'registerAction'
   | 'syncActions';
@@ -142,6 +145,7 @@ export interface ScriptCompleteMessage extends BaseMessage {
      * which means the script ran and returned nothing.
      */
     returnValues?: SerializedReturnValue[];
+    ranAs?: RunAs;
   };
 }
 
@@ -160,6 +164,8 @@ export interface RegisterMessage extends PushMessage {
     launchId?: string;
     /** The player of a multiplayer test client. */
     playerName?: string;
+    /** The playtest studio-bridge started this session's DataModel for. */
+    playtestId?: string;
     capabilities: Capability[];
   };
 }
@@ -320,6 +326,22 @@ export interface EndPlaytestResultMessage extends RequestMessage {
   };
 }
 
+export interface PlaytestPlayerPayload {
+  name: string;
+  userId: number;
+  displayName: string;
+}
+
+export interface PlaytestPlayersResultMessage extends RequestMessage {
+  type: 'playtestPlayersResult';
+  payload: {
+    /** The players `list` found or `add` added. */
+    players?: PlaytestPlayerPayload[];
+    /** The players `remove` waited for that had not left by its timeout. */
+    remaining?: string[];
+  };
+}
+
 export interface PluginErrorMessage extends BaseMessage {
   type: 'error';
   requestId?: string;
@@ -347,6 +369,7 @@ export type PluginMessage =
   | SyncActionsResultMessage
   | PlaytestEndedMessage
   | EndPlaytestResultMessage
+  | PlaytestPlayersResultMessage
   | PluginErrorMessage;
 
 export interface ExecuteMessage extends BaseMessage {
@@ -358,9 +381,14 @@ export interface ExecuteMessage extends BaseMessage {
     timeoutMs?: number;
     /** Passed to the script as `...`. */
     args?: string[];
+    /** Base64 files, passed to the script as buffers in `...` before `args`. */
+    inputs?: string[];
+    runAs?: RunAs;
   };
 }
 
+export type RunAs = 'plugin' | 'game' | 'mcp';
+
 export interface ShutdownMessage extends PushMessage {
   type: 'shutdown';
   payload: Record<string, never>;
@@ -478,26 +506,32 @@ export interface StartPlaytestMessage extends RequestMessage {
     instanceId: string;
     /** Starts a multiplayer test, a server and a client process per player. */
     players?: number;
+    /** Plants a studio-bridge client as the playtest's server session. */
+    bridge?: PlaytestBridgePayload;
   };
 }
 
+/** The studio-bridge client a `startPlaytest` plants, see playtest-bridge.ts. */
+export interface PlaytestBridgePayload {
+  entrySource: string;
+  modules: Record<string, string>;
+  precompiled: string[];
+}
+
 export interface EndPlaytestMessage extends RequestMessage {
   type: 'endPlaytest';
   payload: Record<string, never>;
 }
 
-/** Answered with `scriptComplete`, the same reply as `execute`. */
-export interface RunPlaytestScriptMessage extends RequestMessage {
-  type: 'runPlaytestScript';
-  payload: {
-    mode: PlaytestMode;
-    script: string;
-    /** Planted in the playtest's server to run the script and end the playtest. */
-    runnerSource: string;
-    timeoutSec: number;
-    /** Passed to the script as `...`. */
-    args?: string[];
-  };
+export type PlaytestPlayersRequest =
+  | { op: 'list' }
+  | { op: 'add'; count: number; timeoutSec: number }
+  | { op: 'remove'; kick: string[]; names: string[]; timeoutSec: number }
+  | { op: 'leave' };
+
+export interface PlaytestPlayersMessage extends RequestMessage {
+  type: 'playtestPlayers';
+  payload: PlaytestPlayersRequest;
 }
 
 export interface ServerErrorMessage extends BaseMessage {
@@ -525,7 +559,7 @@ export type ServerMessage =
   | SyncActionsMessage
   | StartPlaytestMessage
   | EndPlaytestMessage
-  | RunPlaytestScriptMessage
+  | PlaytestPlayersMessage
   | ServerErrorMessage;
 
 export function encodeMessage(msg: ServerMessage): string {
@@ -616,6 +650,11 @@ export function decodePluginMessage(raw: string): PluginMessage | null {
                 : undefined,
             output,
             returnValues,
+            ...(payload.ranAs === 'plugin' ||
+            payload.ranAs === 'game' ||
+            payload.ranAs === 'mcp'
+              ? { ranAs: payload.ranAs }
+              : {}),
           },
         };
       }
@@ -657,6 +696,10 @@ export function decodePluginMessage(raw: string): PluginMessage | null {
             typeof payload.playerName === 'string'
               ? payload.playerName
               : undefined,
+          playtestId:
+            typeof payload.playtestId === 'string'
+              ? payload.playtestId
+              : undefined,
           capabilities: payload.capabilities as Capability[],
         },
       };
@@ -906,6 +949,22 @@ export function decodePluginMessage(raw: string): PluginMessage | null {
         },
       };
 
+    case 'playtestPlayersResult':
+      if (requestId === undefined) return null;
+      return {
+        type: 'playtestPlayersResult',
+        sessionId,
+        requestId,
+        payload: {
+          players: Array.isArray(payload.players)
+            ? (payload.players as PlaytestPlayerPayload[])
+            : undefined,
+          remaining: isStringArray(payload.remaining)
+            ? payload.remaining
+            : undefined,
+        },
+      };
+
     case 'error':
       if (
         typeof payload.code !== 'string' ||
@@ -974,6 +1033,12 @@ export function decodeServerMessage(raw: string): ServerMessage | null {
               ? { timeoutMs: payload.timeoutMs }
               : {}),
             ...(isStringArray(payload.args) ? { args: payload.args } : {}),
+            ...(isStringArray(payload.inputs)
+              ? { inputs: payload.inputs }
+              : {}),
+            ...(payload.runAs === 'plugin' || payload.runAs === 'game'
+              ? { runAs: payload.runAs }
+              : {}),
           },
         };
       }
@@ -1185,6 +1250,9 @@ export function decodeServerMessage(raw: string): ServerMessage | null {
           ...(typeof payload.players === 'number'
             ? { players: payload.players }
             : {}),
+          ...(isPlaytestBridge(payload.bridge)
+            ? { bridge: payload.bridge }
+            : {}),
         },
       };
 
@@ -1197,26 +1265,14 @@ export function decodeServerMessage(raw: string): ServerMessage | null {
         payload: {} as Record<string, never>,
       };
 
-    case 'runPlaytestScript':
+    case 'playtestPlayers':
       if (requestId === undefined) return null;
-      if (
-        (payload.mode !== 'play' && payload.mode !== 'run') ||
-        typeof payload.script !== 'string' ||
-        typeof payload.runnerSource !== 'string' ||
-        typeof payload.timeoutSec !== 'number'
-      )
-        return null;
+      if (!isPlaytestPlayersRequest(payload)) return null;
       return {
-        type: 'runPlaytestScript',
+        type: 'playtestPlayers',
         sessionId,
         requestId,
-        payload: {
-          mode: payload.mode,
-          script: payload.script,
-          runnerSource: payload.runnerSource,
-          timeoutSec: payload.timeoutSec,
-          ...(isStringArray(payload.args) ? { args: payload.args } : {}),
-        },
+        payload,
       };
 
     case 'error':
@@ -1240,3 +1296,37 @@ export function decodeServerMessage(raw: string): ServerMessage | null {
       return null;
   }
 }
+
+function isPlaytestBridge(value: unknown): value is PlaytestBridgePayload {
+  if (typeof value !== 'object' || value === null) return false;
+  const bridge = value as Record<string, unknown>;
+  return (
+    typeof bridge.entrySource === 'string' &&
+    typeof bridge.modules === 'object' &&
+    bridge.modules !== null &&
+    Object.values(bridge.modules).every((v) => typeof v === 'string') &&
+    isStringArray(bridge.precompiled)
+  );
+}
+
+function isPlaytestPlayersRequest(
+  value: Record<string, unknown>
+): value is PlaytestPlayersRequest {
+  switch (value.op) {
+    case 'list':
+    case 'leave':
+      return true;
+    case 'add':
+      return (
+        typeof value.count === 'number' && typeof value.timeoutSec === 'number'
+      );
+    case 'remove':
+      return (
+        isStringArray(value.kick) &&
+        isStringArray(value.names) &&
+        typeof value.timeoutSec === 'number'
+      );
+    default:
+      return false;
+  }
+}

package/templates/studio-bridge-plugin/playtest/StudioBridgePlaytest.client.lua

@@ -0,0 +1,32 @@
+--!strict
+--[[
+	Entry point for the bridge planted into a playtest's client, the client twin
+	of StudioBridgePlaytest.server.lua: an ordinary LocalScript, so a play mode
+	playtest has a client session without Studio loading user plugins into it.
+	It only starts in the playtest it was planted for.
+]]
+
+local RunService = game:GetService("RunService")
+
+local PrecompiledSources = require(script.Shared.PrecompiledSources)
+local StudioBridgeClient = require(script.Shared.StudioBridgeClient)
+local StudioBridgeSessionUtils = require(script.Shared.StudioBridgeSessionUtils)
+
+if not (RunService:IsRunning() and RunService:IsClient()) then
+	return
+end
+
+local ok, testArgs = pcall(function()
+	return (game:GetService("StudioTestService") :: any):GetTestArgs()
+end)
+local playtestArgs = if ok then StudioBridgeSessionUtils.getPlaytestArgs(testArgs) else nil
+if not playtestArgs or script:GetAttribute("PlaytestId") ~= playtestArgs.playtestId then
+	return
+end
+
+local stop = StudioBridgeClient.start({
+	playtestArgs = playtestArgs,
+	compile = PrecompiledSources.createCompiler(script.Precompiled),
+})
+
+script.Destroying:Connect(stop)

package/templates/studio-bridge-plugin/playtest/StudioBridgePlaytest.server.lua

@@ -0,0 +1,40 @@
+--!strict
+--[[
+	Entry point for the bridge planted into a playtest's server, so the playtest
+	has a server session without Studio loading user plugins into playtests.
+
+	The `startPlaytest` action plants this as a Script in the edit DataModel's
+	ServerScriptService, with the plugin's Shared modules and the sources
+	compiled for it ahead of time under it. The playtest copies the edit
+	DataModel, so it starts in the playtest's server as an ordinary Script. It
+	only starts in the playtest it was planted for: anywhere else, such as a
+	place saved while it was planted, it does nothing.
+
+	Built from the plugin template, so like the plugin it cannot use the
+	Nevermore loader.
+]]
+
+local RunService = game:GetService("RunService")
+
+local PrecompiledSources = require(script.Shared.PrecompiledSources)
+local StudioBridgeClient = require(script.Shared.StudioBridgeClient)
+local StudioBridgeSessionUtils = require(script.Shared.StudioBridgeSessionUtils)
+
+if not (RunService:IsRunning() and RunService:IsServer()) then
+	return
+end
+
+local ok, testArgs = pcall(function()
+	return (game:GetService("StudioTestService") :: any):GetTestArgs()
+end)
+local playtestArgs = if ok then StudioBridgeSessionUtils.getPlaytestArgs(testArgs) else nil
+if not playtestArgs or StudioBridgeSessionUtils.findPlantedBridge(script.Parent, playtestArgs.playtestId) ~= script then
+	return
+end
+
+local stop = StudioBridgeClient.start({
+	playtestArgs = playtestArgs,
+	compile = PrecompiledSources.createCompiler(script.Precompiled),
+})
+
+script.Destroying:Connect(stop)

package/templates/studio-bridge-plugin/src/Shared/ActionRouter.lua

@@ -30,6 +30,13 @@ export type Handler = (payload: { [string]: any }, requestId: string, sessionId:
 
 export type SendMessage = (message: { [string]: any }) -> ()
 
+--[=[
+	Compiles Luau source into a function, or returns nil and why it could not.
+	@type Compiler (source: string, chunkName: string?) -> (any, string?)
+	@within ActionRouter
+]=]
+export type Compiler = (source: string, chunkName: string?) -> (any, string?)
+
 export type ActionInfo = {
 	module: any,
 	hash: string,
@@ -42,6 +49,7 @@ export type ActionRouter = typeof(setmetatable(
 		_responseTypes: { [string]: string },
 		_actions: { [string]: ActionInfo },
 		_vendorPng: any?,
+		_compiler: Compiler?,
 	},
 	{} :: typeof({ __index = ActionRouter })
 ))
@@ -58,6 +66,7 @@ function ActionRouter.new(): ActionRouter
 
 	-- The screenshot action reads its PNG encoder off this field
 	self._vendorPng = nil
+	self._compiler = nil
 
 	return self
 end
@@ -83,6 +92,15 @@ function ActionRouter.SetVendorPng(self: ActionRouter, png: any)
 	self._vendorPng = png
 end
 
+--[=[
+	Sets how source compiles where `loadstring` is off, in place of compiling
+	through a ModuleScript. The bridge planted into a playtest cannot set a
+	ModuleScript's source, so it looks up sources compiled for it ahead of time.
+]=]
+function ActionRouter.SetCompiler(self: ActionRouter, compiler: Compiler)
+	self._compiler = compiler
+end
+
 --[=[
 	Dispatches a message to its handler and returns the response message, if any.
 ]=]
@@ -130,15 +148,19 @@ end
 
 --[=[
 	Compiles Luau source into a function, like `loadstring`. A playtest's client
-	has no `loadstring`, so there the source compiles through a ModuleScript
-	instead. Returns nil and the compile error when the source does not compile.
+	has no `loadstring`, so there the source compiles through the compiler set
+	with `SetCompiler`, or else a ModuleScript. Returns nil and the compile error
+	when the source does not compile.
 ]=]
-function ActionRouter.Compile(_self: ActionRouter, source: string, chunkName: string?): (any, string?)
+function ActionRouter.Compile(self: ActionRouter, source: string, chunkName: string?): (any, string?)
 	local loadstringOk, fn, compileErr = pcall(loadstring :: any, source, chunkName)
 	if loadstringOk then
 		return fn, compileErr
 	end
 
+	if self._compiler then
+		return self._compiler(source, chunkName)
+	end
 	return ActionRouter._compileWithModuleScript(source, chunkName)
 end