@quenty/studio-bridge 0.21.0 → 0.22.0

package/src/bridge/bridge-session.ts

@@ -19,13 +19,22 @@ import type {
   ScreenshotResult,
   LogsResult,
   DataModelResult,
+  ExportInstancesResult,
+  ImportInstancesResult,
   LogOptions,
   QueryDataModelOptions,
+  PlaytestMode,
+  PlaytestEndResult,
+  EndPlaytestResult,
 } from './types.js';
 import { SessionDisconnectedError } from './types.js';
 import type {
   PluginMessage,
   OutputLevel,
+  FindInstancesMessage,
+  FindInstancesResultMessage,
+  GrepScriptsMessage,
+  GrepScriptsResultMessage,
 } from '../server/web-socket-protocol.js';
 import {
   loadActionSourcesAsync,
@@ -33,14 +42,64 @@ import {
 } from '../commands/framework/action-loader.js';
 import { OutputHelper } from '@quenty/cli-output-helpers';
 
+const EXECUTE_REPLY_GRACE_MS = 5_000;
+
 const DEFAULT_TIMEOUTS: Record<string, number> = {
   execute: 120_000,
   queryState: 5_000,
   captureScreenshot: 30_000,
   queryDataModel: 10_000,
+  exportInstances: 60_000,
+  importInstances: 60_000,
+  findInstances: 60_000,
+  grepScripts: 60_000,
   queryLogs: 10_000,
+  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') {
+    const output = (result.payload.output ?? []).map((entry) => ({
+      level: entry.level as OutputLevel,
+      body: entry.body,
+    }));
+    return {
+      success: result.payload.success,
+      output,
+      error: result.payload.error,
+      traceback: result.payload.traceback,
+      returnValues: result.payload.returnValues,
+    };
+  }
+
+  if (result.type === 'error') {
+    return {
+      success: false,
+      output: [],
+      error: result.payload?.message ?? 'Unknown plugin error',
+    };
+  }
+
+  return {
+    success: false,
+    output: [],
+    error: pluginError('scriptComplete', result).message,
+  };
+}
+
 /**
  * Build a descriptive error from a plugin response that didn't match the
  * expected type. Extracts error details from error-typed responses.
@@ -94,47 +153,65 @@ export class BridgeSession extends EventEmitter {
     return this._handle.isConnected;
   }
 
-  async execAsync(code: string, timeout?: number): Promise<ExecResult> {
+  async execAsync(
+    code: string,
+    timeout?: number,
+    args?: string[]
+  ): Promise<ExecResult> {
     this._assertConnected();
     await this._ensureActionsAsync();
 
+    // The plugin cancels the script at the timeout and replies, so wait a
+    // little longer than that for the reply
     const timeoutMs = timeout ?? DEFAULT_TIMEOUTS.execute;
     const result = await this._handle.sendActionAsync<PluginMessage>(
       {
         type: 'execute',
         sessionId: this._info.sessionId,
         requestId: randomUUID(),
-        payload: { script: code },
+        payload: {
+          script: code,
+          timeoutMs,
+          ...(args && args.length > 0 ? { args } : {}),
+        },
       },
-      timeoutMs
+      timeoutMs + EXECUTE_REPLY_GRACE_MS
     );
 
-    if (result.type === 'scriptComplete') {
-      const output = (result.payload.output ?? []).map((entry) => ({
-        level: entry.level as OutputLevel,
-        body: entry.body,
-      }));
-      return {
-        success: result.payload.success,
-        output,
-        error: result.payload.error,
-        returnValues: result.payload.returnValues,
-      };
-    }
+    return toExecResult(result);
+  }
 
-    if (result.type === 'error') {
-      return {
-        success: false,
-        output: [],
-        error: result.payload?.message ?? 'Unknown plugin error',
-      };
-    }
+  /**
+   * 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();
 
-    return {
-      success: false,
-      output: [],
-      error: pluginError('scriptComplete', result).message,
-    };
+    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 }
+            : {}),
+        },
+      },
+      options.timeoutSec * 1000 + PLAYTEST_STARTUP_ALLOWANCE_MS
+    );
+
+    return toExecResult(result);
   }
 
   async queryStateAsync(): Promise<StateResult> {
@@ -158,6 +235,8 @@ export class BridgeSession extends EventEmitter {
         placeId: result.payload.placeId,
         placeName: result.payload.placeName,
         gameId: result.payload.gameId,
+        viewportSize: result.payload.viewportSize,
+        studioVersion: result.payload.studioVersion,
       };
     }
 
@@ -206,6 +285,8 @@ export class BridgeSession extends EventEmitter {
           direction: options?.direction,
           levels: options?.levels,
           includeInternal: options?.includeInternal,
+          ...(options?.since !== undefined ? { since: options.since } : {}),
+          ...(options?.groupRepeats ? { groupRepeats: true } : {}),
         },
       },
       timeoutMs
@@ -255,6 +336,170 @@ export class BridgeSession extends EventEmitter {
     throw pluginError('dataModelResult', result);
   }
 
+  /** Search the DataModel for instances by name, class and tag. */
+  async findInstancesAsync(
+    options: FindInstancesMessage['payload']
+  ): Promise<FindInstancesResultMessage['payload']> {
+    this._assertConnected();
+    await this._ensureActionsAsync();
+
+    const result = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'findInstances',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: options,
+      },
+      DEFAULT_TIMEOUTS.findInstances
+    );
+
+    if (result.type === 'findInstancesResult') {
+      return result.payload;
+    }
+
+    throw pluginError('findInstancesResult', result);
+  }
+
+  /** Search the source of every script for a pattern. */
+  async grepScriptsAsync(
+    options: GrepScriptsMessage['payload']
+  ): Promise<GrepScriptsResultMessage['payload']> {
+    this._assertConnected();
+    await this._ensureActionsAsync();
+
+    const result = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'grepScripts',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: options,
+      },
+      DEFAULT_TIMEOUTS.grepScripts
+    );
+
+    if (result.type === 'grepScriptsResult') {
+      return result.payload;
+    }
+
+    throw pluginError('grepScriptsResult', result);
+  }
+
+  /** Serialize the instances at `paths` into one binary model (.rbxm). */
+  async exportInstancesAsync(paths: string[]): Promise<ExportInstancesResult> {
+    this._assertConnected();
+    await this._ensureActionsAsync();
+
+    const result = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'exportInstances',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: { paths },
+      },
+      DEFAULT_TIMEOUTS.exportInstances
+    );
+
+    if (result.type === 'exportInstancesResult') {
+      return { data: result.payload.data, paths: result.payload.paths };
+    }
+
+    throw pluginError('exportInstancesResult', result);
+  }
+
+  /** Insert a binary model (.rbxm), base64-encoded, under `parentPath`. */
+  async importInstancesAsync(
+    data: string,
+    parentPath: string
+  ): Promise<ImportInstancesResult> {
+    this._assertConnected();
+    await this._ensureActionsAsync();
+
+    const result = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'importInstances',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: { data, parentPath },
+      },
+      DEFAULT_TIMEOUTS.importInstances
+    );
+
+    if (result.type === 'importInstancesResult') {
+      return { paths: result.payload.paths };
+    }
+
+    throw pluginError('importInstancesResult', result);
+  }
+
+  /**
+   * Start a playtest from this edit session. Resolves when the playtest
+   * ends, not when it starts: StudioTestService only reports a refusal to
+   * start (a playtest already running) by failing the call that would have
+   * waited for the end.
+   */
+  async runPlaytestAsync(
+    mode: PlaytestMode,
+    playtestId: string,
+    bridgePort: number,
+    timeoutMs: number,
+    players?: number
+  ): Promise<PlaytestEndResult> {
+    this._assertConnected();
+    await this._ensureActionsAsync();
+
+    const result = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'startPlaytest',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: {
+          mode,
+          playtestId,
+          bridgePort,
+          instanceId: this._info.instanceId,
+          ...(players !== undefined ? { players } : {}),
+        },
+      },
+      timeoutMs
+    );
+
+    if (result.type === 'playtestEnded') {
+      return {
+        playtestId: result.payload.playtestId,
+        success: result.payload.success,
+        error: result.payload.error,
+      };
+    }
+
+    throw pluginError('playtestEnded', result);
+  }
+
+  /** End the playtest this server session belongs to. */
+  async endPlaytestAsync(): Promise<EndPlaytestResult> {
+    this._assertConnected();
+    await this._ensureActionsAsync();
+
+    const result = await this._handle.sendActionAsync<PluginMessage>(
+      {
+        type: 'endPlaytest',
+        sessionId: this._info.sessionId,
+        requestId: randomUUID(),
+        payload: {} as Record<string, never>,
+      },
+      DEFAULT_TIMEOUTS.endPlaytest
+    );
+
+    if (result.type === 'endPlaytestResult') {
+      return {
+        playtestId: result.payload.playtestId,
+        mode: result.payload.mode,
+        players: result.payload.players,
+      };
+    }
+
+    throw pluginError('endPlaytestResult', result);
+  }
+
   private _assertConnected(): void {
     if (!this._handle.isConnected) {
       throw new SessionDisconnectedError(this._info.sessionId);
@@ -300,7 +545,7 @@ export class BridgeSession extends EventEmitter {
         type: 'syncActions',
         sessionId: this._info.sessionId,
         requestId: randomUUID(),
-        payload: { actions },
+        payload: { actions, verbose: OutputHelper.isVerbose() },
       },
       10_000
     );

package/src/bridge/index.ts

@@ -26,6 +26,9 @@ export type {
   LogOptions,
   QueryDataModelOptions,
   LogFollowOptions,
+  PlaytestMode,
+  PlaytestEndResult,
+  EndPlaytestResult,
   StudioState,
   DataModelInstance,
   OutputLevel,

package/src/bridge/internal/bridge-client.test.ts

@@ -316,6 +316,29 @@ describe('BridgeClient', () => {
     });
   });
 
+  describe('host loss', () => {
+    it('fails a pending request at once when the host drops without replying', async () => {
+      host = await createMockHostWithSessions([createSessionInfo()]);
+      host.wss.on('connection', (ws) => {
+        ws.on('message', (raw) => {
+          const msg = decodeHostMessage(raw.toString());
+          if (msg?.type === 'host-envelope') {
+            ws.terminate();
+          }
+        });
+      });
+
+      client = new BridgeClient();
+      await client.connectAsync(host.port);
+
+      const started = Date.now();
+      await expect(
+        client.getSession('session-1')!.queryStateAsync()
+      ).rejects.toThrow('The bridge host shut down before replying');
+      expect(Date.now() - started).toBeLessThan(2_000);
+    });
+  });
+
   describe('session events', () => {
     it('handles session-connected event from host', async () => {
       host = await createMockHost();

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

@@ -80,9 +80,13 @@ class RelayedTransportHandle extends EventEmitter implements TransportHandle {
   }
 }
 
+/** Lets the host's own timeout error, which says what timed out, arrive first. */
+const HOST_REPLY_GRACE_MS = 2_000;
+
 export class BridgeClient extends EventEmitter {
   private _transport = new TransportClient();
   private _sessions = new Map<string, SessionInfo>();
+  private _hostProtocolVersion: number | undefined;
   private _sessionHandles = new Map<string, RelayedTransportHandle>();
   private _bridgeSessions = new Map<string, BridgeSession>();
   private _pendingRequests = new Map<
@@ -111,6 +115,10 @@ export class BridgeClient extends EventEmitter {
 
     this._transport.on('disconnected', () => {
       this._isConnected = false;
+      // Replies to these went to the old host, so none will arrive
+      this._rejectPendingRequests(
+        'The bridge host shut down before replying. Studio may still have run the request.'
+      );
       this.emit('disconnected');
 
       // Trigger failover detection
@@ -134,6 +142,14 @@ export class BridgeClient extends EventEmitter {
     await this._fetchSessionsAsync();
   }
 
+  private _rejectPendingRequests(message: string): void {
+    for (const [, entry] of this._pendingRequests) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error(message));
+    }
+    this._pendingRequests.clear();
+  }
+
   /**
    * Disconnect from the bridge host.
    */
@@ -144,12 +160,7 @@ export class BridgeClient extends EventEmitter {
     this._transport.disconnect();
     this._isConnected = false;
 
-    // Cancel all pending requests
-    for (const [, entry] of this._pendingRequests) {
-      clearTimeout(entry.timer);
-      entry.reject(new Error('Client disconnected'));
-    }
-    this._pendingRequests.clear();
+    this._rejectPendingRequests('Client disconnected');
 
     // Mark all handles as disconnected
     for (const handle of this._sessionHandles.values()) {
@@ -163,6 +174,11 @@ export class BridgeClient extends EventEmitter {
   /**
    * List all known sessions.
    */
+  /** The host's HOST_PROTOCOL_VERSION, or undefined for hosts older than it. */
+  get hostProtocolVersion(): number | undefined {
+    return this._hostProtocolVersion;
+  }
+
   listSessions(): SessionInfo[] {
     return Array.from(this._sessions.values());
   }
@@ -228,6 +244,7 @@ export class BridgeClient extends EventEmitter {
       requestId,
       targetSessionId,
       action,
+      timeoutMs,
     };
 
     return new Promise<PluginMessage>((resolve, reject) => {
@@ -236,7 +253,7 @@ export class BridgeClient extends EventEmitter {
         reject(
           new Error(`Request "${requestId}" timed out after ${timeoutMs}ms`)
         );
-      }, timeoutMs);
+      }, timeoutMs + HOST_REPLY_GRACE_MS);
 
       this._pendingRequests.set(requestId, { resolve, reject, timer });
 
@@ -306,6 +323,7 @@ export class BridgeClient extends EventEmitter {
   }
 
   private _handleListSessionsResponse(msg: ListSessionsResponse): void {
+    this._hostProtocolVersion = msg.protocolVersion;
     const pending = this._pendingRequests.get(msg.requestId);
     if (pending) {
       clearTimeout(pending.timer);

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

@@ -254,6 +254,44 @@ describe('BridgeHost', () => {
     });
   });
 
+  describe('client relay', () => {
+    it('answers an envelope it cannot decode instead of dropping it', async () => {
+      host = new BridgeHost();
+      const port = await host.startAsync({ port: 0 });
+      const ws = await new Promise<WebSocket>((resolve, reject) => {
+        const client = new WebSocket(`ws://localhost:${port}/client`);
+        client.on('open', () => resolve(client));
+        client.on('error', reject);
+      });
+      openClients.push(ws);
+
+      const reply = new Promise<any>((resolve) => {
+        ws.once('message', (raw) => resolve(JSON.parse(raw.toString())));
+      });
+      ws.send(
+        JSON.stringify({
+          type: 'host-envelope',
+          requestId: 'req-1',
+          targetSessionId: 'session-1',
+          action: {
+            type: 'fromTheFuture',
+            sessionId: 'session-1',
+            payload: {},
+          },
+          timeoutMs: 1000,
+        })
+      );
+
+      const response = await reply;
+      expect(response.type).toBe('host-response');
+      expect(response.requestId).toBe('req-1');
+      expect(response.result.type).toBe('error');
+      expect(response.result.payload.message).toContain(
+        "could not relay 'fromTheFuture'"
+      );
+    });
+  });
+
   describe('health endpoint', () => {
     it('responds with valid JSON on /health', async () => {
       host = new BridgeHost();

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

@@ -20,6 +20,7 @@ import {
   decodePluginMessage,
   encodeMessage,
   type Capability,
+  type PluginContext,
   type ServerMessage,
 } from '../../server/web-socket-protocol.js';
 import { PendingRequestMap } from '../../server/pending-request-map.js';
@@ -42,8 +43,14 @@ export interface PluginSessionInfo {
   placeName?: string;
   /** Studio state from register. */
   state?: string;
+  /** DataModel context from register. */
+  context?: PluginContext;
   /** Place file from register. */
   placeFile?: string;
+  /** Launch id from register, for a Studio that `process run` launched. */
+  launchId?: string;
+  /** Player name from register, for a multiplayer test client. */
+  playerName?: string;
 }
 
 const SHUTDOWN_TIMEOUT_MS = 2_000;
@@ -122,6 +129,7 @@ export class BridgeHost extends EventEmitter {
         const data = typeof raw === 'string' ? raw : raw.toString('utf-8');
         const msg = decodeHostMessage(data);
         if (!msg) {
+          this._replyUndecodable(ws, data);
           return;
         }
         this.emit('client-message', msg, (reply: HostProtocolMessage) => {
@@ -357,6 +365,42 @@ export class BridgeHost extends EventEmitter {
     }
   }
 
+  /**
+   * Answers an envelope this host cannot decode with an error, so the client
+   * fails fast instead of waiting out its timeout. That is usually a newer
+   * client relaying an action this host does not know.
+   */
+  private _replyUndecodable(ws: WebSocket, data: string): void {
+    let parsed: any;
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (
+      parsed?.type !== 'host-envelope' ||
+      typeof parsed.requestId !== 'string'
+    ) {
+      return;
+    }
+
+    const actionType = String(parsed.action?.type ?? 'unknown');
+    ws.send(
+      encodeHostMessage({
+        type: 'host-response',
+        requestId: parsed.requestId,
+        result: {
+          type: 'error',
+          sessionId: String(parsed.targetSessionId ?? ''),
+          payload: {
+            code: 'INVALID_PAYLOAD',
+            message: `The bridge host could not relay '${actionType}'. It may run an older studio-bridge than this command; restart it (e.g. stop 'studio-bridge serve').`,
+          },
+        },
+      })
+    );
+  }
+
   private _handlePluginConnection(
     ws: WebSocket,
     _request: IncomingMessage
@@ -379,7 +423,10 @@ export class BridgeHost extends EventEmitter {
         instanceId: msg.payload.instanceId,
         placeName: msg.payload.placeName,
         state: msg.payload.state,
+        context: msg.payload.context,
         placeFile: msg.payload.placeFile,
+        launchId: msg.payload.launchId,
+        playerName: msg.payload.playerName,
       });
     };
 

package/src/bridge/internal/hand-off.ts

@@ -12,6 +12,7 @@
 
 import { createServer, type Server } from 'net';
 import { WebSocket } from 'ws';
+import { MAX_MESSAGE_BYTES } from '../../server/web-socket-protocol.js';
 import { HostUnreachableError } from '../types.js';
 
 export type TakeoverState =
@@ -79,7 +80,9 @@ function tryConnectAsClientDefaultAsync(port: number): Promise<boolean> {
   const CONNECT_TIMEOUT_MS = 2_000;
 
   return new Promise<boolean>((resolve) => {
-    const ws = new WebSocket(`ws://localhost:${port}/client`);
+    const ws = new WebSocket(`ws://localhost:${port}/client`, {
+      maxPayload: MAX_MESSAGE_BYTES,
+    });
 
     const timer = setTimeout(() => {
       ws.removeAllListeners();

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

@@ -41,6 +41,21 @@ function createSessionInfo(overrides: Partial<SessionInfo> = {}): SessionInfo {
 
 describe('host-protocol', () => {
   describe('HostEnvelope', () => {
+    it('keeps payload fields it does not list, for newer clients', () => {
+      const decoded = roundTrip({
+        type: 'host-envelope',
+        requestId: 'req-1',
+        targetSessionId: 'session-1',
+        action: {
+          type: 'execute',
+          sessionId: 'session-1',
+          payload: { script: 'return ...', futureOption: true },
+        },
+      } as any) as HostEnvelope;
+
+      expect((decoded.action.payload as any).futureOption).toBe(true);
+    });
+
     it('round-trips correctly', () => {
       const msg: HostEnvelope = {
         type: 'host-envelope',