@quenty/studio-bridge 0.21.1 → 0.22.1

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

@@ -13,11 +13,18 @@ import type {
 } from '../../server/web-socket-protocol.js';
 import type { SessionInfo, SessionContext, InstanceInfo } from '../types.js';
 
+/**
+ * Raised when the host-client protocol changes, so a client can tell it is
+ * relaying through an older host. Hosts before this field have none.
+ */
+export const HOST_PROTOCOL_VERSION = 2;
+
 export interface HostEnvelope {
   type: 'host-envelope';
   requestId: string;
   targetSessionId: string;
   action: ServerMessage;
+  timeoutMs?: number;
 }
 
 export interface ListSessionsRequest {
@@ -40,6 +47,8 @@ export interface ListSessionsResponse {
   type: 'list-sessions-response';
   requestId: string;
   sessions: SessionInfo[];
+  /** Absent from hosts older than HOST_PROTOCOL_VERSION 2. */
+  protocolVersion?: number;
 }
 
 export interface ListInstancesResponse {
@@ -76,6 +85,8 @@ export type HostProtocolMessage =
 // `ServerMessageSchema` is the load-bearing one: it validates the `action`
 // payload that /client connections forward to plugins. Without it, a buggy
 // or hostile CLI client could ship malformed actions and crash the plugin.
+// Payloads keep fields they don't list, so a newer client's options reach
+// the plugin through an older host instead of being silently dropped.
 // Container fields like `result`, `sessions`, `instances`, and `session` are
 // validated only as objects/arrays — their interior shapes flow through to
 // callers that already know how to handle the typed contracts.
@@ -90,6 +101,8 @@ const ErrorCodeSchema = z.enum([
   'SCREENSHOT_FAILED',
   'SCRIPT_LOAD_ERROR',
   'SCRIPT_RUNTIME_ERROR',
+  'SCRIPT_TIMEOUT',
+  'RESULT_TOO_LARGE',
   'BUSY',
   'SESSION_MISMATCH',
   'INTERNAL_ERROR',
@@ -102,7 +115,13 @@ const ServerMessageSchema = z.discriminatedUnion('type', [
     type: z.literal('execute'),
     sessionId: z.string(),
     requestId: z.string().optional(),
-    payload: z.object({ script: z.string() }),
+    payload: z
+      .object({
+        script: z.string(),
+        timeoutMs: z.number().optional(),
+        args: z.array(z.string()).optional(),
+      })
+      .loose(),
   }),
   z.object({
     type: z.literal('shutdown'),
@@ -119,67 +138,157 @@ const ServerMessageSchema = z.discriminatedUnion('type', [
     type: z.literal('captureScreenshot'),
     sessionId: z.string(),
     requestId: z.string(),
-    payload: z.object({
-      format: z.literal('png').optional(),
-    }),
+    payload: z
+      .object({
+        format: z.literal('png').optional(),
+      })
+      .loose(),
   }),
   z.object({
     type: z.literal('queryDataModel'),
     sessionId: z.string(),
     requestId: z.string(),
-    payload: z.object({
-      path: z.string(),
-      depth: z.number().optional(),
-      properties: z.array(z.string()).optional(),
-      includeAttributes: z.boolean().optional(),
-      find: z
-        .object({
-          name: z.string(),
-          recursive: z.boolean().optional(),
-        })
-        .optional(),
-      listServices: z.boolean().optional(),
-    }),
+    payload: z
+      .object({
+        path: z.string(),
+        depth: z.number().optional(),
+        properties: z.array(z.string()).optional(),
+        includeAttributes: z.boolean().optional(),
+        find: z
+          .object({
+            name: z.string(),
+            recursive: z.boolean().optional(),
+          })
+          .optional(),
+        listServices: z.boolean().optional(),
+      })
+      .loose(),
+  }),
+  z.object({
+    type: z.literal('findInstances'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z
+      .object({
+        root: z.string().optional(),
+        name: z.string().optional(),
+        exactName: z.boolean().optional(),
+        className: z.string().optional(),
+        tag: z.string().optional(),
+        limit: z.number().optional(),
+      })
+      .loose(),
+  }),
+  z.object({
+    type: z.literal('grepScripts'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z
+      .object({
+        pattern: z.string(),
+        root: z.string().optional(),
+        luaPattern: z.boolean().optional(),
+        caseSensitive: z.boolean().optional(),
+        limit: z.number().optional(),
+      })
+      .loose(),
+  }),
+  z.object({
+    type: z.literal('exportInstances'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z.object({ paths: z.array(z.string()) }).loose(),
+  }),
+  z.object({
+    type: z.literal('importInstances'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z.object({ data: z.string(), parentPath: z.string() }).loose(),
   }),
   z.object({
     type: z.literal('queryLogs'),
     sessionId: z.string(),
     requestId: z.string(),
-    payload: z.object({
-      count: z.number().optional(),
-      direction: z.enum(['head', 'tail']).optional(),
-      levels: z.array(OutputLevelSchema).optional(),
-      includeInternal: z.boolean().optional(),
-    }),
+    payload: z
+      .object({
+        count: z.number().optional(),
+        direction: z.enum(['head', 'tail']).optional(),
+        levels: z.array(OutputLevelSchema).optional(),
+        includeInternal: z.boolean().optional(),
+        since: z.number().optional(),
+        groupRepeats: z.boolean().optional(),
+      })
+      .loose(),
   }),
   z.object({
     type: z.literal('registerAction'),
     sessionId: z.string(),
     requestId: z.string(),
-    payload: z.object({
-      name: z.string(),
-      source: z.string(),
-      hash: z.string().optional(),
-      responseType: z.string().optional(),
-    }),
+    payload: z
+      .object({
+        name: z.string(),
+        source: z.string(),
+        hash: z.string().optional(),
+        responseType: z.string().optional(),
+      })
+      .loose(),
   }),
   z.object({
     type: z.literal('syncActions'),
     sessionId: z.string(),
     requestId: z.string(),
-    payload: z.object({
-      actions: z.record(z.string(), z.string()),
-    }),
+    payload: z
+      .object({
+        actions: z.record(z.string(), z.string()),
+        verbose: z.boolean().optional(),
+      })
+      .loose(),
+  }),
+  z.object({
+    type: z.literal('startPlaytest'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z
+      .object({
+        mode: z.enum(['play', 'run']),
+        playtestId: z.string(),
+        bridgePort: z.number(),
+        instanceId: z.string(),
+        players: z.number().int().min(1).optional(),
+      })
+      .loose(),
+  }),
+  z.object({
+    type: z.literal('endPlaytest'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z.object({}).loose(),
+  }),
+  z.object({
+    type: z.literal('runPlaytestScript'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z
+      .object({
+        mode: z.enum(['play', 'run']),
+        script: z.string(),
+        runnerSource: z.string(),
+        timeoutSec: z.number(),
+        args: z.array(z.string()).optional(),
+      })
+      .loose(),
   }),
   z.object({
     type: z.literal('error'),
     sessionId: z.string(),
     requestId: z.string().optional(),
-    payload: z.object({
-      code: ErrorCodeSchema,
-      message: z.string(),
-      details: z.unknown().optional(),
-    }),
+    payload: z
+      .object({
+        code: ErrorCodeSchema,
+        message: z.string(),
+        details: z.unknown().optional(),
+      })
+      .loose(),
   }),
 ]);
 
@@ -191,6 +300,7 @@ const HostProtocolMessageSchema = z.discriminatedUnion('type', [
     requestId: z.string(),
     targetSessionId: z.string(),
     action: ServerMessageSchema,
+    timeoutMs: z.number().optional(),
   }),
   z.object({
     type: z.literal('list-sessions'),
@@ -209,6 +319,7 @@ const HostProtocolMessageSchema = z.discriminatedUnion('type', [
     type: z.literal('list-sessions-response'),
     requestId: z.string(),
     sessions: z.array(LooseObjectSchema),
+    protocolVersion: z.number().optional(),
   }),
   z.object({
     type: z.literal('list-instances-response'),

package/src/bridge/internal/instance-state.ts

@@ -0,0 +1,34 @@
+/**
+ * Every plugin registers as `Edit`, since it cannot see a playtest from the
+ * edit DataModel. The bridge can: a playtest's server and client connect as
+ * sessions of the same instance. Their place is a copy named "Game", so
+ * they take the edit session's place name too.
+ */
+
+import type { SessionInfo, StudioState } from '../types.js';
+
+export function annotateInstanceState(sessions: SessionInfo[]): SessionInfo[] {
+  const byInstance = new Map<string, SessionInfo[]>();
+  for (const session of sessions) {
+    const group = byInstance.get(session.instanceId) ?? [];
+    group.push(session);
+    byInstance.set(session.instanceId, group);
+  }
+
+  return sessions.map((session) => {
+    const group = byInstance.get(session.instanceId)!;
+    const hasServer = group.some((s) => s.context === 'server');
+    const hasClient = group.some((s) => s.context === 'client');
+    const edit = group.find((s) => s.context === 'edit');
+
+    const state: StudioState = hasServer
+      ? hasClient
+        ? 'Play'
+        : 'Run'
+      : session.state;
+    const placeName =
+      session.context !== 'edit' && edit ? edit.placeName : session.placeName;
+
+    return { ...session, state, placeName };
+  });
+}

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

@@ -6,6 +6,7 @@
 
 import { EventEmitter } from 'events';
 import { WebSocket } from 'ws';
+import { MAX_MESSAGE_BYTES } from '../../server/web-socket-protocol.js';
 
 export interface TransportClientOptions {
   /** Maximum number of reconnection attempts. Default: 10. */
@@ -98,7 +99,7 @@ export class TransportClient extends EventEmitter {
 
   private _connectInternalAsync(): Promise<void> {
     return new Promise<void>((resolve, reject) => {
-      const ws = new WebSocket(this._url);
+      const ws = new WebSocket(this._url, { maxPayload: MAX_MESSAGE_BYTES });
       this._ws = ws;
 
       const onOpen = () => {

package/src/bridge/internal/transport-server.ts

@@ -13,6 +13,7 @@ import {
 } from 'http';
 import type { Socket } from 'net';
 import { WebSocketServer, WebSocket } from 'ws';
+import { MAX_MESSAGE_BYTES } from '../../server/web-socket-protocol.js';
 import { URL } from 'url';
 
 export interface TransportServerOptions {
@@ -67,7 +68,10 @@ export class TransportServer {
       });
     });
 
-    this._wss = new WebSocketServer({ noServer: true });
+    this._wss = new WebSocketServer({
+      noServer: true,
+      maxPayload: MAX_MESSAGE_BYTES,
+    });
 
     this._httpServer.on('upgrade', (request, socket, head) => {
       const pathname = this._parsePath(request);

package/src/bridge/types.ts

@@ -12,6 +12,7 @@ import type {
   DataModelInstance,
   OutputLevel,
   SerializedReturnValue,
+  PlaytestMode,
 } from '../server/web-socket-protocol.js';
 
 // Re-export protocol types used in the public API
@@ -21,6 +22,7 @@ export type {
   DataModelInstance,
   OutputLevel,
   SerializedReturnValue,
+  PlaytestMode,
 };
 
 export type SessionContext = 'edit' | 'client' | 'server';
@@ -35,6 +37,10 @@ export interface SessionInfo {
   capabilities: Capability[];
   connectedAt: Date;
   origin: SessionOrigin;
+  /** Set on sessions of a Studio that `process run` launched. */
+  launchId?: string;
+  /** The player of a multiplayer test client session. */
+  playerName?: string;
   context: SessionContext;
   instanceId: string;
   placeId: number;
@@ -54,10 +60,11 @@ export interface ExecResult {
   success: boolean;
   output: Array<{ level: OutputLevel; body: string }>;
   error?: string;
+  /** Where a runtime error was thrown. */
+  traceback?: string;
   /**
    * Everything the script returned, in order. Absent when the plugin reported
-   * no return channel at all (older plugin build, or a run that never reached
-   * a return) — distinct from `[]`, which means it returned nothing.
+   * no return channel at all (a run that never reached a return) — distinct from `[]`, which means it returned nothing.
    */
   returnValues?: SerializedReturnValue[];
 }
@@ -67,6 +74,10 @@ export interface StateResult {
   placeId: number;
   placeName: string;
   gameId: number;
+  /** The camera's viewport in pixels. Absent without a camera. */
+  viewportSize?: [number, number];
+  /** Studio's version. Absent from older plugins. */
+  studioVersion?: string;
 }
 
 export interface ScreenshotResult {
@@ -80,6 +91,10 @@ export interface LogEntry {
   level: OutputLevel;
   body: string;
   timestamp: number;
+  /** When grouped: how many identical entries in a row this stands for. */
+  repeats?: number;
+  /** When grouped: when the last of the repeats was logged. */
+  lastTimestamp?: number;
 }
 
 export interface LogsResult {
@@ -92,11 +107,25 @@ export interface DataModelResult {
   instance: DataModelInstance;
 }
 
+export interface ExportInstancesResult {
+  /** The binary model (.rbxm), base64-encoded. */
+  data: string;
+  paths: string[];
+}
+
+export interface ImportInstancesResult {
+  paths: string[];
+}
+
 export interface LogOptions {
   count?: number;
   direction?: 'head' | 'tail';
   levels?: OutputLevel[];
   includeInternal?: boolean;
+  /** Only entries logged at or after this time, in epoch seconds. */
+  since?: number;
+  /** Collapse identical consecutive entries, before `count` applies. */
+  groupRepeats?: boolean;
 }
 
 export interface QueryDataModelOptions {
@@ -108,6 +137,22 @@ export interface QueryDataModelOptions {
   listServices?: boolean;
 }
 
+export interface PlaytestEndResult {
+  playtestId: string;
+  /** False when StudioTestService refused to start the playtest. */
+  success: boolean;
+  error?: string;
+}
+
+export interface EndPlaytestResult {
+  /** Absent when the playtest was not started by studio-bridge. */
+  playtestId?: string;
+  /** The mode the playtest ran in. Absent from older plugins. */
+  mode?: PlaytestMode;
+  /** How many players a multiplayer test started with. */
+  players?: number;
+}
+
 export interface LogFollowOptions {
   levels?: OutputLevel[];
 }

package/src/cli/adapters/cli-command-adapter-handler.test.ts

@@ -6,8 +6,14 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { buildYargsCommand } from './cli-command-adapter.js';
 import { defineCommand } from '../../commands/framework/define-command.js';
+import { arg } from '../../commands/framework/arg-builder.js';
 import type { CliLifecycleProvider } from './cli-command-adapter.js';
 
+vi.mock('../cli-output-context.js', () => ({
+  getWarnings: () => [],
+  warnIfPluginStaleAsync: vi.fn().mockResolvedValue(undefined),
+}));
+
 vi.mock('fs', async (importOriginal) => {
   const actual = await importOriginal<typeof import('fs')>();
   return {
@@ -29,6 +35,7 @@ function createMockConnection() {
       resolveSessionAsync: vi.fn().mockResolvedValue(session),
       disconnectAsync: vi.fn().mockResolvedValue(undefined),
       listSessions: vi.fn().mockReturnValue([]),
+      listInstances: vi.fn().mockReturnValue([]),
     } as any,
     session,
   };
@@ -301,6 +308,27 @@ describe('handler — standalone scope', () => {
     expect(lifecycle.connectAsync).not.toHaveBeenCalled();
     expect(output[0]).toBe('done');
   });
+
+  it('hands everything after -- to a passthrough arg as strings', async () => {
+    const handler = vi.fn(async () => ({ summary: 'done' }));
+    const cmd = defineCommand({
+      group: null,
+      name: 'standalone',
+      description: 'Standalone test',
+      category: 'infrastructure',
+      safety: 'none',
+      scope: 'standalone',
+      args: { scriptArgs: arg.passthrough({ description: 'Script args' }) },
+      handler,
+    });
+    const module = buildYargsCommand(cmd);
+
+    await captureOutput(async () => {
+      await (module.handler as any)({ format: 'text', '--': ['Player1', 3] });
+    });
+
+    expect(handler).toHaveBeenCalledWith({ scriptArgs: ['Player1', '3'] });
+  });
 });
 
 describe('handler — connection lifecycle', () => {