@quenty/studio-bridge 0.22.1 → 0.24.0

package/docs/playtest-bridge.md

@@ -0,0 +1,21 @@
+# The planted playtest bridge
+
+With Studio's **Load user plugins on playtest** off, the studio-bridge plugin never loads into a playtest. So `startPlaytest` plants the same client (`templates/studio-bridge-plugin/src/Shared/StudioBridgeClient.lua`) into the edit place's ServerScriptService. The playtest copies the edit place, so the client starts in the playtest's server as an ordinary Script and connects as its server session. In play mode it also plants the client's twin as a LocalScript in StarterPlayerScripts, which every player's client runs and connects as its client session; a LocalScript there can open the WebSocket to the bridge and read the test args, measured in a Studio playtest client. With the setting on, nothing is planted and the plugin is the playtest's sessions.
+
+## What an ordinary playtest Script can do
+
+These limits shape the design. They were measured in a Studio playtest server:
+
+| Capability | Result |
+|---|---|
+| WebSocket to the bridge on localhost (`CreateWebStreamClient`) | Works, even with Allow HTTP Requests off |
+| `HttpService:GetAsync` to localhost | Refused, so the port comes from the StudioTestService test args instead of a scan |
+| `loadstring` | Off. `LoadStringEnabled` isn't scriptable, not even from a plugin |
+| Setting `ModuleScript.Source` | Needs the `PluginOrOpenCloud` capability |
+| `SerializationService` | `GetService` returns `nil` |
+
+So the planted client can't compile code. The edit session compiles everything ahead of time: each action, and any script `playtest run` will send, becomes a ModuleScript returning its function and its own source text. The router finds a source by its exact text (`PrecompiledSources.lua`, built by `src/plugin/playtest-bridge.ts`). New code sent to a planted session fails and asks for the setting. Privileged compiling, for example through Studio's MCP `execute_luau`, would plug in at `ActionRouter:SetCompiler`.
+
+A precompiled source that fails to load is skipped, which would hide its compile error. So `startPlaytest` compiles every one in the edit session before planting.
+
+`LogService.MessageOut` fires a frame or two after a `print` in a playtest server, later than in a plugin. That's why `execute.lua` waits several frames before it stops capturing output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/studio-bridge",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "WebSocket-based bridge for running Luau scripts in Roblox Studio",
   "type": "module",
   "main": "dist/src/index.js",
@@ -15,10 +15,10 @@
     "studio-bridge": "./dist/src/cli/cli.js"
   },
   "dependencies": {
-    "@quenty/cli-output-helpers": "1.19.1",
-    "@quenty/nevermore-cli-helpers": "1.20.1",
+    "@quenty/cli-output-helpers": "1.20.0",
+    "@quenty/nevermore-cli-helpers": "1.21.0",
     "@quenty/nevermore-deploy": "1.1.1",
-    "@quenty/nevermore-template-helpers": "1.21.1",
+    "@quenty/nevermore-template-helpers": "1.22.0",
     "execa": "^9.6.1",
     "ws": "^8.18.0",
     "yargs": "^18.0.0",
@@ -41,5 +41,5 @@
     "test:watch": "vitest",
     "test:integration": "node dist/test/integration/smoke-test.js"
   },
-  "gitHead": "e663d6c2e0577e2831040d2a922a3c636fb62007"
+  "gitHead": "2d4d5cbd9339e7be7e36d30aa91f7146225cb500"
 }

package/src/bridge/bridge-connection.ts

@@ -687,6 +687,7 @@ export class BridgeConnection extends EventEmitter {
         origin: info.launchId ? 'managed' : 'user',
         launchId: info.launchId,
         playerName: info.playerName,
+        playtestId: info.playtestId,
         context,
         instanceId: info.instanceId ?? info.sessionId,
         placeId: 0,

package/src/bridge/bridge-session.test.ts

@@ -162,6 +162,57 @@ describe('BridgeSession', () => {
       expect(timeout).toBe(10_000);
     });
 
+    it('sends inputs base64-encoded', async () => {
+      const handle = new MockTransportHandle();
+      handle.sendActionAsync.mockResolvedValueOnce({
+        type: 'scriptComplete',
+        sessionId: 'session-1',
+        payload: { success: true },
+      });
+
+      const session = new BridgeSession(createSessionInfo(), handle);
+      await session.execAsync('return ...', undefined, undefined, [
+        Buffer.from('hello'),
+      ]);
+
+      const [msg] = handle.sendActionAsync.mock.calls[0];
+      expect((msg as any).payload.inputs).toEqual(['aGVsbG8=']);
+    });
+
+    it('sends --run-as and carries back where the code ran', async () => {
+      const handle = new MockTransportHandle();
+      handle.sendActionAsync.mockResolvedValueOnce({
+        type: 'scriptComplete',
+        sessionId: 'session-1',
+        payload: { success: true, ranAs: 'game' },
+      });
+
+      const session = new BridgeSession(createSessionInfo(), handle);
+      const result = await session.execAsync(
+        'return 1',
+        undefined,
+        undefined,
+        undefined,
+        'game'
+      );
+
+      const [msg] = handle.sendActionAsync.mock.calls[0];
+      expect((msg as any).payload.runAs).toBe('game');
+      expect(result.ranAs).toBe('game');
+    });
+
+    it('refuses inputs over the size limit without sending them', async () => {
+      const handle = new MockTransportHandle();
+      const session = new BridgeSession(createSessionInfo(), handle);
+
+      await expect(
+        session.execAsync('return ...', undefined, undefined, [
+          Buffer.alloc(192 * 1024 * 1024 + 1),
+        ])
+      ).rejects.toThrow('that can be sent to Studio with a script');
+      expect(handle.sendActionAsync).not.toHaveBeenCalled();
+    });
+
     it('returns error info from error response', async () => {
       const handle = new MockTransportHandle();
       handle.sendActionAsync.mockResolvedValueOnce({

package/src/bridge/bridge-session.ts

@@ -41,6 +41,17 @@ import {
   type ActionSource,
 } from '../commands/framework/action-loader.js';
 import { OutputHelper } from '@quenty/cli-output-helpers';
+import {
+  MAX_EXECUTE_INPUT_BYTES,
+  type PlaytestBridgePayload,
+  type PlaytestPlayerPayload,
+  type PlaytestPlayersRequest,
+} from '../server/web-socket-protocol.js';
+
+export interface PlaytestPlayersResult {
+  players: PlaytestPlayerPayload[];
+  remaining: string[];
+}
 
 const EXECUTE_REPLY_GRACE_MS = 5_000;
 
@@ -57,18 +68,6 @@ const DEFAULT_TIMEOUTS: Record<string, number> = {
   endPlaytest: 5_000,
 };
 
-/** Time a playtest gets to start and stop on top of its script's own timeout. */
-const PLAYTEST_STARTUP_ALLOWANCE_MS = 60_000;
-
-export interface RunPlaytestScriptOptions {
-  mode: PlaytestMode;
-  script: string;
-  runnerSource: string;
-  timeoutSec: number;
-  /** Passed to the script as `...`. */
-  args?: string[];
-}
-
 /** Map an `execute`-style reply onto an ExecResult. */
 function toExecResult(result: PluginMessage): ExecResult {
   if (result.type === 'scriptComplete') {
@@ -82,6 +81,7 @@ function toExecResult(result: PluginMessage): ExecResult {
       error: result.payload.error,
       traceback: result.payload.traceback,
       returnValues: result.payload.returnValues,
+      ...(result.payload.ranAs ? { ranAs: result.payload.ranAs } : {}),
     };
   }
 
@@ -156,8 +156,19 @@ export class BridgeSession extends EventEmitter {
   async execAsync(
     code: string,
     timeout?: number,
-    args?: string[]
+    args?: string[],
+    inputs?: Buffer[],
+    runAs?: 'plugin' | 'game'
   ): Promise<ExecResult> {
+    const inputBytes = (inputs ?? []).reduce((sum, b) => sum + b.length, 0);
+    if (inputBytes > MAX_EXECUTE_INPUT_BYTES) {
+      throw new Error(
+        `The inputs are ${_formatMiB(inputBytes)}, over the ${_formatMiB(
+          MAX_EXECUTE_INPUT_BYTES
+        )} that can be sent to Studio with a script`
+      );
+    }
+
     this._assertConnected();
     await this._ensureActionsAsync();
 
@@ -173,42 +184,13 @@ export class BridgeSession extends EventEmitter {
           script: code,
           timeoutMs,
           ...(args && args.length > 0 ? { args } : {}),
-        },
-      },
-      timeoutMs + EXECUTE_REPLY_GRACE_MS
-    );
-
-    return toExecResult(result);
-  }
-
-  /**
-   * Run a script in a fresh playtest's server, started from this edit
-   * session, and resolve with its result once the playtest has ended. Works
-   * without the playtest's own sessions connecting: the plugin plants
-   * `runnerSource` in the playtest to run the script and end the playtest.
-   */
-  async runPlaytestScriptAsync(
-    options: RunPlaytestScriptOptions
-  ): Promise<ExecResult> {
-    this._assertConnected();
-    await this._ensureActionsAsync();
-
-    const result = await this._handle.sendActionAsync<PluginMessage>(
-      {
-        type: 'runPlaytestScript',
-        sessionId: this._info.sessionId,
-        requestId: randomUUID(),
-        payload: {
-          mode: options.mode,
-          script: options.script,
-          runnerSource: options.runnerSource,
-          timeoutSec: options.timeoutSec,
-          ...(options.args && options.args.length > 0
-            ? { args: options.args }
+          ...(inputs && inputs.length > 0
+            ? { inputs: inputs.map((input) => input.toString('base64')) }
             : {}),
+          ...(runAs ? { runAs } : {}),
         },
       },
-      options.timeoutSec * 1000 + PLAYTEST_STARTUP_ALLOWANCE_MS
+      timeoutMs + EXECUTE_REPLY_GRACE_MS
     );
 
     return toExecResult(result);
@@ -442,7 +424,8 @@ export class BridgeSession extends EventEmitter {
     playtestId: string,
     bridgePort: number,
     timeoutMs: number,
-    players?: number
+    players?: number,
+    bridge?: PlaytestBridgePayload
   ): Promise<PlaytestEndResult> {
     this._assertConnected();
     await this._ensureActionsAsync();
@@ -458,6 +441,7 @@ export class BridgeSession extends EventEmitter {
           bridgePort,
           instanceId: this._info.instanceId,
           ...(players !== undefined ? { players } : {}),
+          ...(bridge ? { bridge } : {}),
         },
       },
       timeoutMs
@@ -500,6 +484,37 @@ export class BridgeSession extends EventEmitter {
     throw pluginError('endPlaytestResult', result);
   }
 
+  /**
+   * Read or change the players of the playtest this session belongs to.
+   * `timeoutMs` bounds the whole request, including any wait in the plugin.
+   */
+  async playtestPlayersAsync(
+    request: PlaytestPlayersRequest,
+    timeoutMs: number
+  ): Promise<PlaytestPlayersResult> {
+    this._assertConnected();
+    await this._ensureActionsAsync();
+
+    const result = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'playtestPlayers',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: request,
+      },
+      timeoutMs
+    );
+
+    if (result.type === 'playtestPlayersResult') {
+      return {
+        players: result.payload.players ?? [],
+        remaining: result.payload.remaining ?? [],
+      };
+    }
+
+    throw pluginError('playtestPlayersResult', result);
+  }
+
   private _assertConnected(): void {
     if (!this._handle.isConnected) {
       throw new SessionDisconnectedError(this._info.sessionId);
@@ -609,3 +624,7 @@ export class BridgeSession extends EventEmitter {
     OutputHelper.verbose('[actions] Action sync complete');
   }
 }
+
+function _formatMiB(bytes: number): string {
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}

package/src/bridge/internal/bridge-host.ts

@@ -51,6 +51,8 @@ export interface PluginSessionInfo {
   launchId?: string;
   /** Player name from register, for a multiplayer test client. */
   playerName?: string;
+  /** Playtest id from register, for a playtest studio-bridge started. */
+  playtestId?: string;
 }
 
 const SHUTDOWN_TIMEOUT_MS = 2_000;
@@ -427,6 +429,7 @@ export class BridgeHost extends EventEmitter {
         placeFile: msg.payload.placeFile,
         launchId: msg.payload.launchId,
         playerName: msg.payload.playerName,
+        playtestId: msg.payload.playtestId,
       });
     };
 

package/src/bridge/internal/host-protocol.ts

@@ -255,6 +255,13 @@ const ServerMessageSchema = z.discriminatedUnion('type', [
         bridgePort: z.number(),
         instanceId: z.string(),
         players: z.number().int().min(1).optional(),
+        bridge: z
+          .object({
+            entrySource: z.string(),
+            modules: z.record(z.string(), z.string()),
+            precompiled: z.array(z.string()),
+          })
+          .optional(),
       })
       .loose(),
   }),
@@ -265,18 +272,24 @@ const ServerMessageSchema = z.discriminatedUnion('type', [
     payload: z.object({}).loose(),
   }),
   z.object({
-    type: z.literal('runPlaytestScript'),
+    type: z.literal('playtestPlayers'),
     sessionId: z.string(),
     requestId: z.string(),
-    payload: z
-      .object({
-        mode: z.enum(['play', 'run']),
-        script: z.string(),
-        runnerSource: z.string(),
+    payload: z.discriminatedUnion('op', [
+      z.object({ op: z.literal('list') }),
+      z.object({
+        op: z.literal('add'),
+        count: z.number().int().min(1),
         timeoutSec: z.number(),
-        args: z.array(z.string()).optional(),
-      })
-      .loose(),
+      }),
+      z.object({
+        op: z.literal('remove'),
+        kick: z.array(z.string()),
+        names: z.array(z.string()),
+        timeoutSec: z.number(),
+      }),
+      z.object({ op: z.literal('leave') }),
+    ]),
   }),
   z.object({
     type: z.literal('error'),

package/src/bridge/types.ts

@@ -13,6 +13,7 @@ import type {
   OutputLevel,
   SerializedReturnValue,
   PlaytestMode,
+  RunAs,
 } from '../server/web-socket-protocol.js';
 
 // Re-export protocol types used in the public API
@@ -23,6 +24,7 @@ export type {
   OutputLevel,
   SerializedReturnValue,
   PlaytestMode,
+  RunAs,
 };
 
 export type SessionContext = 'edit' | 'client' | 'server';
@@ -41,6 +43,8 @@ export interface SessionInfo {
   launchId?: string;
   /** The player of a multiplayer test client session. */
   playerName?: string;
+  /** The playtest studio-bridge started this session's DataModel for. */
+  playtestId?: string;
   context: SessionContext;
   instanceId: string;
   placeId: number;
@@ -67,6 +71,7 @@ export interface ExecResult {
    * no return channel at all (a run that never reached a return) — distinct from `[]`, which means it returned nothing.
    */
   returnValues?: SerializedReturnValue[];
+  ranAs?: RunAs;
 }
 
 export interface StateResult {

package/src/commands/console/exec/exec.test.ts

@@ -6,6 +6,7 @@ import { describe, it, expect, vi } from 'vitest';
 import {
   execCommand,
   execHandlerAsync,
+  formatExecText,
   runHandlerAsync,
   type ExecResult,
 } from './exec.js';
@@ -15,14 +16,25 @@ vi.mock('fs/promises', () => ({
   readFile: vi.fn(),
 }));
 
+vi.mock('../../../roblox-mcp/index.js', () => ({
+  tryExecuteLuauAsync: vi.fn(),
+}));
+
 import * as fs from 'fs/promises';
+import { tryExecuteLuauAsync } from '../../../roblox-mcp/index.js';
 
 function createMockSession(execResult: {
   success: boolean;
   output: Array<{ level: string; body: string }>;
   error?: string;
+  ranAs?: string;
 }) {
   return {
+    info: {
+      sessionId: 'place1-aaaa-edit',
+      instanceId: 'place1-aaaa',
+      context: 'edit',
+    },
     execAsync: vi.fn().mockResolvedValue(execResult),
   } as any;
 }
@@ -96,6 +108,88 @@ describe('execHandlerAsync', () => {
     ]);
   });
 
+  it('forwards inputs to session.execAsync', async () => {
+    const session = createMockSession({
+      success: true,
+      output: [],
+    });
+    const input = Buffer.from('hello');
+
+    await execHandlerAsync(session, {
+      scriptContent: 'return ...',
+      args: ['Player1'],
+      inputs: [input],
+    });
+
+    expect(session.execAsync).toHaveBeenCalledWith(
+      'return ...',
+      undefined,
+      ['Player1'],
+      [input]
+    );
+  });
+
+  it('forwards --run-as and reports where the code ran', async () => {
+    const session = createMockSession({
+      success: true,
+      output: [],
+      ranAs: 'game',
+    });
+
+    const result = await execHandlerAsync(session, {
+      scriptContent: 'return 1',
+      runAs: 'game',
+    });
+
+    expect(session.execAsync).toHaveBeenCalledWith(
+      'return 1',
+      undefined,
+      undefined,
+      undefined,
+      'game'
+    );
+    expect(result.ranAs).toBe('game');
+    expect(formatExecText({ ...result, output: [] })).toContain(
+      '(ran as game)'
+    );
+  });
+
+  it('runs --run-as mcp through Studio MCP, targeting the session Studio', async () => {
+    const session = createMockSession({ success: true, output: [] });
+    vi.mocked(tryExecuteLuauAsync).mockResolvedValueOnce({
+      success: true,
+      value: '42',
+    });
+
+    const result = await execHandlerAsync(session, {
+      scriptContent: 'return 42',
+      runAs: 'mcp',
+    });
+
+    expect(session.execAsync).not.toHaveBeenCalled();
+    expect(tryExecuteLuauAsync).toHaveBeenCalledWith(
+      'return 42',
+      expect.objectContaining({ target: session.info.instanceId })
+    );
+    expect(result).toMatchObject({
+      success: true,
+      returnValues: ['42'],
+      ranAs: 'mcp',
+    });
+  });
+
+  it('refuses args with --run-as mcp, which only takes the code', async () => {
+    const session = createMockSession({ success: true, output: [] });
+
+    await expect(
+      execHandlerAsync(session, {
+        scriptContent: 'return ...',
+        args: ['a'],
+        runAs: 'mcp',
+      })
+    ).rejects.toThrow("--run-as mcp can't pass args");
+  });
+
   it('passes undefined timeout when not specified', async () => {
     const session = createMockSession({
       success: true,