@quenty/studio-bridge 0.22.1 → 0.24.0

package/src/commands/process/list/list.test.ts

@@ -4,7 +4,8 @@
 
 import { describe, it, expect } from 'vitest';
 import type { SessionInfo } from '../../../bridge/index.js';
-import { listSessionsHandlerAsync } from './list.js';
+import { formatSessionsTable, listSessionsHandlerAsync } from './list.js';
+import type { StudioMcpSnapshot } from '../../../roblox-mcp/index.js';
 
 function createSessionInfo(overrides: Partial<SessionInfo> = {}): SessionInfo {
   return {
@@ -81,3 +82,131 @@ describe('listSessionsHandlerAsync', () => {
     expect(s.origin).toBe('managed');
   });
 });
+
+describe('listSessionsHandlerAsync with Studio processes and MCP', () => {
+  const now = Date.parse('2026-11-05T00:30:00Z');
+  const snapshot = (
+    overrides: Partial<StudioMcpSnapshot> = {}
+  ): StudioMcpSnapshot => ({
+    status: 'ok',
+    studios: [],
+    checkedAt: now,
+    latencyMs: 640,
+    ...overrides,
+  });
+  const processes = [
+    {
+      pid: 70,
+      windowTitle: 'Place1 - Roblox Studio',
+      startedAt: now - 300_000,
+    },
+    {
+      pid: 80,
+      windowTitle: 'Place1 - Roblox Studio',
+      startedAt: now - 290_000,
+    },
+  ];
+
+  it('says no Studio is open, and how long it waited', async () => {
+    const result = await listSessionsHandlerAsync(
+      createMockConnection([]),
+      {},
+      { listProcessesAsync: async () => [], elapsedSec: () => 12.34 }
+    );
+
+    expect(result.summary).toBe('No Roblox Studio processes are open (12.3s).');
+  });
+
+  it('says Studio is open without the plugin, rather than that nothing is', async () => {
+    const result = await listSessionsHandlerAsync(
+      createMockConnection([]),
+      {},
+      { listProcessesAsync: async () => processes, elapsedSec: () => 5 }
+    );
+
+    expect(result.summary).toContain(
+      '2 Studio process(es) open, but none has the studio-bridge plugin connected (5.0s)'
+    );
+  });
+
+  it('lists each Studio with its plugin session, MCP id and where it was launched', async () => {
+    const sessions = [
+      createSessionInfo({ sessionId: 'a-edit', instanceId: 'a' }),
+    ];
+
+    const result = await listSessionsHandlerAsync(
+      createMockConnection(sessions),
+      {},
+      {
+        listProcessesAsync: async () => processes,
+        resolveSessionPidsAsync: async () => new Map([['a', 70]]),
+        readLaunchesAsync: async () => [
+          {
+            pid: 70,
+            cwd: 'C:gameshub',
+            opened: 'a new Baseplate',
+            launchedAt: now - 301_000,
+          },
+        ],
+        mcpSnapshotAsync: async () =>
+          snapshot({
+            studios: [
+              {
+                studioId: 'aaaaaaaa-1',
+                placeName: 'Place1',
+                pid: 70,
+                instanceId: 'a',
+              },
+              { studioId: 'bbbbbbbb-2', placeName: 'Place1', pid: 80 },
+            ],
+          }),
+      }
+    );
+
+    expect(result.sessions[0].pid).toBe(70);
+    expect(result.studios).toEqual([
+      expect.objectContaining({
+        pid: 70,
+        instanceId: 'a',
+        mcpStudioId: 'aaaaaaaa-1',
+        launch: expect.objectContaining({ cwd: 'C:gameshub' }),
+      }),
+      expect.objectContaining({ pid: 80, mcpStudioId: 'bbbbbbbb-2' }),
+    ]);
+    const text = formatSessionsTable(result, now);
+    expect(text).toContain('a new Baseplate from C:gameshub');
+    expect(text).toContain('not by studio-bridge');
+    expect(text).toContain('5m');
+  });
+
+  it('still lists sessions and Studios when MCP is unavailable, and says why', async () => {
+    const result = await listSessionsHandlerAsync(
+      createMockConnection([createSessionInfo({ sessionId: 's1' })]),
+      {},
+      {
+        listProcessesAsync: async () => processes,
+        mcpSnapshotAsync: async () =>
+          snapshot({ status: 'timeout', message: 'tools/call timed out' }),
+      }
+    );
+
+    const text = formatSessionsTable(result, now);
+    expect(text).toContain('s1');
+    expect(text).toContain('MCP: timeout (tools/call timed out)');
+    expect(result.studios).toHaveLength(2);
+  });
+
+  it('leaves MCP out when the check gave up or the platform has none', async () => {
+    for (const mcpSnapshotAsync of [
+      async () => undefined,
+      async () => snapshot({ status: 'unsupported' }),
+    ]) {
+      const result = await listSessionsHandlerAsync(
+        createMockConnection([createSessionInfo({ sessionId: 's1' })]),
+        {},
+        { mcpSnapshotAsync }
+      );
+      expect(formatSessionsTable(result, now)).not.toContain('MCP');
+    }
+  });
+});

package/src/commands/process/list/list.ts

@@ -1,12 +1,15 @@
 /**
- * `process list` — list connected Studio sessions.
+ * `process list` — list connected Studio sessions and the Studio processes
+ * behind them.
  */
 
 import {
   defineCommand,
   type SessionTargeting,
 } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
 import { OutputHelper } from '@quenty/cli-output-helpers';
+import { formatDurationMs } from '@quenty/cli-output-helpers/cli-utils';
 import {
   formatTable,
   type TableColumn,
@@ -14,39 +17,195 @@ import {
 import type { BridgeConnection } from '../../../bridge/index.js';
 import type { SessionInfo } from '../../../bridge/index.js';
 import type { StudioState } from '../../../server/web-socket-protocol.js';
+import {
+  getStudioMcpSnapshotAsync,
+  type StudioMcpSnapshot,
+} from '../../../roblox-mcp/index.js';
+import {
+  listStudioProcessesAsync,
+  type RunningStudioProcess,
+} from '../../../process/studio-process-closer.js';
+import { resolveSessionPidsAsync } from '../../../process/studio-process-identity.js';
+import {
+  findStudioLaunch,
+  readStudioLaunchesAsync,
+  type StudioLaunchRecord,
+} from '../../../process/studio-launch-registry.js';
 import { colorizeState } from '../format-state.js';
 
+export interface McpStudioState {
+  status: StudioMcpSnapshot['status'];
+  message?: string;
+  latencyMs: number;
+  checkedAt: string;
+  lastOkAt?: string;
+  settled?: boolean;
+}
+
+export interface StudioProcessRow {
+  pid?: number;
+  startedAt?: string;
+  windowTitle: string;
+  instanceId?: string;
+  mcpStudioId?: string;
+  launch?: { cwd: string; opened: string; launchedAt: string };
+}
+
+export interface ListedSession extends SessionInfo {
+  pid?: number;
+}
+
 export interface SessionsResult {
-  sessions: SessionInfo[];
+  sessions: ListedSession[];
+  studios?: StudioProcessRow[];
+  mcp?: McpStudioState;
   summary: string;
 }
 
+export interface ListSessionsOptions {
+  listProcessesAsync?: () => Promise<RunningStudioProcess[]>;
+  resolveSessionPidsAsync?: (
+    processes: RunningStudioProcess[]
+  ) => Promise<Map<string, number>>;
+  readLaunchesAsync?: () => Promise<StudioLaunchRecord[]>;
+  mcpSnapshotAsync?: (
+    sessions: SessionInfo[],
+    sessionPids: Map<string, number>,
+    processes: RunningStudioProcess[] | undefined
+  ) => Promise<StudioMcpSnapshot | undefined>;
+  elapsedSec?: () => number;
+}
+
 /**
- * List all connected Studio sessions with a summary message.
+ * List the connected Studio sessions, and when the process list is available,
+ * every Studio process with its session, MCP id and where it was launched.
  */
 export async function listSessionsHandlerAsync(
   connection: BridgeConnection,
-  targeting: SessionTargeting = {}
+  targeting: SessionTargeting = {},
+  options: ListSessionsOptions = {}
 ): Promise<SessionsResult> {
-  const sessions = connection.findSessions(targeting.target, targeting.context);
+  const allSessions = connection.listSessions();
+  const processes = await options.listProcessesAsync?.().catch(() => undefined);
+  const sessionPids =
+    processes && options.resolveSessionPidsAsync
+      ? await options.resolveSessionPidsAsync(processes).catch(() => new Map())
+      : new Map<string, number>();
+  const [launches, snapshot] = await Promise.all([
+    options.readLaunchesAsync?.().catch(() => []) ?? Promise.resolve([]),
+    options.mcpSnapshotAsync?.(allSessions, sessionPids, processes),
+  ]);
 
-  if (sessions.length === 0) {
+  const sessions: ListedSession[] = connection
+    .findSessions(targeting.target, targeting.context)
+    .map((s) => {
+      const pid = sessionPids.get(s.instanceId);
+      return pid !== undefined ? { ...s, pid } : s;
+    });
+  const studios = processes
+    ? buildStudioRows(processes, sessionPids, launches, snapshot)
+    : undefined;
+  const mcp = snapshot ? toMcpStudioState(snapshot) : undefined;
+
+  return {
+    sessions,
+    ...(studios ? { studios } : {}),
+    ...(mcp ? { mcp } : {}),
+    summary: describeSummary(
+      sessions.length,
+      allSessions.length,
+      processes,
+      options.elapsedSec?.()
+    ),
+  };
+}
+
+function buildStudioRows(
+  processes: RunningStudioProcess[],
+  sessionPids: Map<string, number>,
+  launches: StudioLaunchRecord[],
+  snapshot: StudioMcpSnapshot | undefined
+): StudioProcessRow[] {
+  const instanceByPid = new Map([...sessionPids].map(([id, pid]) => [pid, id]));
+  const mcpStudios = snapshot?.status === 'ok' ? snapshot.studios : [];
+  const shown = new Set<string>();
+
+  const rows: StudioProcessRow[] = processes.map((proc) => {
+    const instanceId = instanceByPid.get(proc.pid);
+    const mcpStudio = mcpStudios.find(
+      (s) =>
+        s.pid === proc.pid ||
+        (instanceId !== undefined && s.instanceId === instanceId)
+    );
+    if (mcpStudio) shown.add(mcpStudio.studioId);
+    const launch = findStudioLaunch(launches, proc);
     return {
-      sessions: [],
-      summary:
-        connection.listSessions().length > 0
-          ? 'No sessions match --target/--context.'
-          : 'No active sessions. Is Studio running with the studio-bridge plugin?',
+      pid: proc.pid,
+      ...(proc.startedAt !== undefined
+        ? { startedAt: new Date(proc.startedAt).toISOString() }
+        : {}),
+      windowTitle: proc.windowTitle.replace(/ - Roblox Studio$/, ''),
+      ...(instanceId ? { instanceId } : {}),
+      ...(mcpStudio ? { mcpStudioId: mcpStudio.studioId } : {}),
+      ...(launch
+        ? {
+            launch: {
+              cwd: launch.cwd,
+              opened: launch.opened,
+              launchedAt: new Date(launch.launchedAt).toISOString(),
+            },
+          }
+        : {}),
     };
+  });
+
+  for (const studio of mcpStudios) {
+    if (shown.has(studio.studioId)) continue;
+    rows.push({
+      windowTitle: studio.placeName || '(loading)',
+      ...(studio.instanceId ? { instanceId: studio.instanceId } : {}),
+      mcpStudioId: studio.studioId,
+    });
   }
+  return rows;
+}
 
+function describeSummary(
+  matching: number,
+  connected: number,
+  processes: RunningStudioProcess[] | undefined,
+  elapsedSec: number | undefined
+): string {
+  if (matching > 0) {
+    return `${matching} session(s) connected.`;
+  }
+  if (connected > 0) {
+    return 'No sessions match --target/--context.';
+  }
+  const waited = elapsedSec !== undefined ? ` (${elapsedSec.toFixed(1)}s)` : '';
+  if (!processes) {
+    return `No active sessions${waited}. Is Studio running with the studio-bridge plugin?`;
+  }
+  if (processes.length === 0) {
+    return `No Roblox Studio processes are open${waited}.`;
+  }
+  return `${processes.length} Studio process(es) open, but none has the studio-bridge plugin connected${waited}. Run 'studio-bridge plugin install', and check the plugin is enabled in Studio.`;
+}
+
+export function toMcpStudioState(snapshot: StudioMcpSnapshot): McpStudioState {
   return {
-    sessions,
-    summary: `${sessions.length} session(s) connected.`,
+    status: snapshot.status,
+    ...(snapshot.message ? { message: snapshot.message } : {}),
+    latencyMs: snapshot.latencyMs,
+    checkedAt: new Date(snapshot.checkedAt).toISOString(),
+    ...(snapshot.lastOkAt
+      ? { lastOkAt: new Date(snapshot.lastOkAt).toISOString() }
+      : {}),
+    ...(snapshot.settled === false ? { settled: false } : {}),
   };
 }
 
-const sessionColumns: TableColumn<SessionInfo>[] = [
+const sessionColumns: TableColumn<ListedSession>[] = [
   {
     header: 'Session',
     value: (s) => s.sessionId,
@@ -59,25 +218,134 @@ const sessionColumns: TableColumn<SessionInfo>[] = [
     value: (s) => s.state,
     format: (v) => colorizeState(v as StudioState),
   },
+  { header: 'PID', value: (s) => (s.pid !== undefined ? String(s.pid) : '') },
 ];
 
-export function formatSessionsTable(result: SessionsResult): string {
-  if (result.sessions.length === 0) return result.summary;
-  return formatTable(result.sessions, sessionColumns);
+function studioColumns(
+  withMcp: boolean,
+  now: number
+): TableColumn<StudioProcessRow>[] {
+  const columns: TableColumn<StudioProcessRow>[] = [
+    {
+      header: 'PID',
+      value: (s) => (s.pid !== undefined ? String(s.pid) : '?'),
+    },
+    {
+      header: 'Up',
+      value: (s) =>
+        s.startedAt
+          ? formatDurationMs(Math.max(0, now - Date.parse(s.startedAt)))
+          : '',
+    },
+    { header: 'Window', value: (s) => s.windowTitle },
+    { header: 'Plugin', value: (s) => s.instanceId ?? 'none' },
+  ];
+  if (withMcp) {
+    columns.push({
+      header: 'MCP',
+      value: (s) => (s.mcpStudioId ? s.mcpStudioId.slice(0, 8) : 'none'),
+    });
+  }
+  columns.push({
+    header: 'Launched',
+    value: (s) =>
+      s.launch
+        ? `${s.launch.opened} from ${s.launch.cwd}`
+        : 'not by studio-bridge',
+  });
+  return columns;
+}
+
+export function formatMcpLine(mcp: McpStudioState, now = Date.now()): string {
+  const age = formatAgo(Date.parse(mcp.checkedAt), now);
+  if (mcp.status === 'ok') {
+    const pending =
+      mcp.settled === false
+        ? ', may be incomplete (Studios take a few seconds to reach a new MCP server)'
+        : '';
+    return `MCP: ok, answered in ${mcp.latencyMs}ms, checked ${age}${pending}`;
+  }
+  const lastOk = mcp.lastOkAt
+    ? `, last ok ${formatAgo(Date.parse(mcp.lastOkAt), now)}`
+    : '';
+  return OutputHelper.formatWarning(
+    `MCP: ${mcp.status}${
+      mcp.message ? ` (${mcp.message})` : ''
+    }, checked ${age}${lastOk}`
+  );
+}
+
+export function formatSessionsTable(
+  result: SessionsResult,
+  now = Date.now()
+): string {
+  const mcp =
+    result.mcp && result.mcp.status !== 'unsupported' ? result.mcp : undefined;
+  const lines: string[] = [];
+  if (result.sessions.length > 0) {
+    lines.push(formatTable(result.sessions, sessionColumns));
+  } else {
+    lines.push(result.summary);
+  }
+  if (result.studios && result.studios.length > 0) {
+    lines.push('');
+    lines.push(
+      formatTable(result.studios, studioColumns(mcp?.status === 'ok', now))
+    );
+  }
+  if (mcp) {
+    lines.push(formatMcpLine(mcp, now));
+  }
+  return lines.join('\n');
+}
+
+function formatAgo(at: number, now: number): string {
+  return `${formatDurationMs(Math.max(0, now - at))} ago`;
 }
 
-export const listCommand = defineCommand({
+interface ListArgs {
+  mcp?: boolean;
+}
+
+export const listCommand = defineCommand<ListArgs, SessionsResult>({
   group: 'process',
   name: 'list',
-  description: 'List connected Studio sessions',
+  description:
+    'List connected Studio sessions and every Studio process, with where each was launched',
   category: 'infrastructure',
   safety: 'read',
   scope: 'connection',
   coversAllSessions: true,
-  args: {},
+  args: {
+    mcp: arg.flag({
+      description:
+        "Ask Studio's MCP server too, which also reaches Studios without the plugin (--no-mcp to skip)",
+      default: true,
+    }),
+  },
   cli: {
     format: formatSessionsTable,
   },
-  handler: async (connection, _args, targeting) =>
-    listSessionsHandlerAsync(connection, targeting),
+  handler: async (connection, args, targeting) =>
+    listSessionsHandlerAsync(
+      connection,
+      targeting,
+      connection.isRemote
+        ? { elapsedSec: () => process.uptime() }
+        : {
+            listProcessesAsync: listStudioProcessesAsync,
+            resolveSessionPidsAsync: (processes) =>
+              resolveSessionPidsAsync(connection, processes),
+            readLaunchesAsync: () => readStudioLaunchesAsync(),
+            mcpSnapshotAsync: args.mcp
+              ? (sessions, sessionPids, processes) =>
+                  getStudioMcpSnapshotAsync({
+                    sessions,
+                    sessionPids,
+                    windows: processes,
+                  })
+              : undefined,
+            elapsedSec: () => process.uptime(),
+          }
+    ),
 });

package/src/commands/process/run/run.ts

@@ -41,7 +41,7 @@ interface ProcessRunArgs {
   code?: string;
   file?: string;
   place?: string;
-  timeout?: number;
+  scriptTimeout?: number;
   scriptArgs?: string[];
 }
 
@@ -85,8 +85,8 @@ export const processRunCommand = defineCommand<
       description: 'Path to a .rbxl place file',
       alias: 'p',
     }),
-    timeout: arg.option({
-      description: 'Execution timeout in milliseconds',
+    scriptTimeout: arg.option({
+      description: 'Cancel the script after this many milliseconds',
       type: 'number',
     }),
     scriptArgs: arg.passthrough({
@@ -107,7 +107,7 @@ export const processRunCommand = defineCommand<
       scriptContent,
       packageName: 'studio-bridge',
       placePath: args.place,
-      timeoutMs: args.timeout ?? 120_000,
+      timeoutMs: args.scriptTimeout ?? 120_000,
       verbose: OutputHelper.isVerbose(),
       showLogs: true,
       filePath,

package/src/docker/docker-delegator.test.ts

@@ -94,7 +94,7 @@ describe('buildDockerRunArgsAsync', () => {
     const bashCmd = args[args.length - 1];
     expect(bashCmd).toContain('studio-bridge linux inject-credentials');
     expect(bashCmd).toContain('studio-bridge process run');
-    expect(bashCmd).toContain('--timeout 120000');
+    expect(bashCmd).toContain('--script-timeout 120000');
     expect(bashCmd).not.toContain('--verbose');
   });
 

package/src/docker/docker-delegator.ts

@@ -198,7 +198,7 @@ export async function buildDockerRunArgsAsync(
     'run',
     '--file',
     scriptFilePath,
-    '--timeout',
+    '--script-timeout',
     String(timeoutMs),
   ];
 

package/src/plugin/playtest-bridge.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import {
+  buildPlaytestBridgeAsync,
+  wrapPrecompiledSource,
+} from './playtest-bridge.js';
+
+describe('wrapPrecompiledSource', () => {
+  it('opens the function on the first line', () => {
+    const wrapped = wrapPrecompiledSource('return 1');
+    expect(wrapped.split('\n')[0]).toBe('return { fn = function(...) return 1');
+  });
+
+  it('uses a long string level the source does not close', () => {
+    expect(wrapPrecompiledSource('return "]]"')).toContain('[=[x');
+    expect(wrapPrecompiledSource('return "]]" .. "]=]"')).toContain('[==[x');
+  });
+
+  it('does not let a trailing ] close the string early', () => {
+    const wrapped = wrapPrecompiledSource('local t = {}\nreturn t[1]');
+    expect(wrapped).toContain('[=[x');
+  });
+
+  it('keeps a leading newline in the source text', () => {
+    expect(wrapPrecompiledSource('\nreturn 1')).toContain('[[x\nreturn 1]]');
+  });
+});
+
+describe('buildPlaytestBridgeAsync', () => {
+  it('plants the Shared modules with the plugin version filled in', async () => {
+    const bridge = await buildPlaytestBridgeAsync();
+
+    expect(Object.keys(bridge.modules)).toContain('StudioBridgeClient');
+    expect(Object.keys(bridge.modules)).toContain('PrecompiledSources');
+    expect(Object.keys(bridge.modules).some((n) => n.endsWith('.spec'))).toBe(
+      false
+    );
+    expect(bridge.modules.StudioBridgeSessionUtils).not.toContain(
+      '{{PLUGIN_VERSION}}'
+    );
+    expect(bridge.entrySource).toContain('StudioBridgeClient.start');
+  });
+
+  it('precompiles every action plus the given scripts', async () => {
+    const bridge = await buildPlaytestBridgeAsync(['return "mine"']);
+
+    expect(bridge.precompiled.some((s) => s.includes('return "mine"'))).toBe(
+      true
+    );
+    expect(bridge.precompiled.some((s) => s.includes('ExecuteAction'))).toBe(
+      true
+    );
+  });
+});