@quenty/studio-bridge 0.23.0 → 0.24.0

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

@@ -0,0 +1,330 @@
+import type { SessionContext, SessionInfo } from '../bridge/types.js';
+import { listStudioProcessesAsync } from '../process/studio-process-closer.js';
+import {
+  McpStdioClient,
+  McpTimeoutError,
+  type SpawnMcpProcess,
+} from './mcp/mcp-stdio-client.js';
+import {
+  findStudioMcpLaunchAsync,
+  StudioMcpUnsupportedError,
+} from './studio-mcp-locator.js';
+import {
+  cleanToolError,
+  DATAMODEL_TYPES,
+  listMcpStudiosAsync,
+  matchStudiosAsync,
+  resolveStudio,
+  StudioNotFoundError,
+  type MatchedStudio,
+  type McpStudio,
+  type StudioWindow,
+} from './studio/studio-session.js';
+
+export type StudioMcpTarget = MatchedStudio;
+
+export type StudioMcpFailure =
+  | 'unsupported'
+  | 'unavailable'
+  | 'no-studio'
+  | 'failed'
+  | 'timeout';
+
+export type StudioMcpResult<T> =
+  | { success: true; value: T; studio?: StudioMcpTarget; settled?: boolean }
+  | {
+      success: false;
+      reason: StudioMcpFailure;
+      message: string;
+      studio?: StudioMcpTarget;
+    };
+
+export interface StudioMcpOptions {
+  target?: string;
+  sessions?: SessionInfo[];
+  timeoutMs?: number;
+  executablePath?: string;
+  spawnProcess?: SpawnMcpProcess;
+  listWindowsAsync?: () => Promise<StudioWindow[]>;
+  readPlaceIds?: boolean;
+  sessionPids?: Map<string, number>;
+}
+
+export interface StudioMcpLuauOptions extends StudioMcpOptions {
+  context?: SessionContext;
+}
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const STEP_TIMEOUT_MS = 5_000;
+const STUDIO_RECONNECT_MS = 4_000;
+const RECONNECT_POLL_MS = 250;
+const SETTLE_RESERVE_MS = 2_500;
+const IDLE_CLOSE_MS = 15_000;
+
+interface SharedClient {
+  client: McpStdioClient;
+  startedAt: number;
+  key: string;
+  spawnProcess?: SpawnMcpProcess;
+  idleTimer?: NodeJS.Timeout;
+}
+
+let _shared: SharedClient | undefined;
+
+export async function tryListStudiosAsync(
+  options: StudioMcpOptions = {}
+): Promise<StudioMcpResult<StudioMcpTarget[]>> {
+  return _withMcpAsync(options, async (shared, remainingMs) => {
+    const { studios, settled } = await _listSettledAsync(
+      shared,
+      remainingMs,
+      options.sessions
+    );
+    return { value: await _matchAsync(shared, options, studios), settled };
+  });
+}
+
+export async function tryExecuteLuauAsync(
+  code: string,
+  options: StudioMcpLuauOptions = {}
+): Promise<StudioMcpResult<string>> {
+  return tryCallStudioToolAsync('execute_luau', { code }, options);
+}
+
+export async function tryCallStudioToolAsync(
+  tool: string,
+  args: Record<string, unknown> = {},
+  options: StudioMcpLuauOptions = {}
+): Promise<StudioMcpResult<string>> {
+  return _withMcpAsync(options, async (shared, remainingMs) => {
+    const { studios } = await _listSettledAsync(
+      shared,
+      remainingMs,
+      options.sessions
+    );
+    const studio = resolveStudio(
+      await _matchAsync(shared, options, studios),
+      options.target
+    );
+    const reply = await shared.client.callToolAsync(
+      tool,
+      {
+        ...args,
+        studio_id: studio.studioId,
+        ...(options.context
+          ? { datamodel_type: DATAMODEL_TYPES[options.context] }
+          : tool === 'execute_luau'
+          ? { datamodel_type: DATAMODEL_TYPES.edit }
+          : {}),
+      },
+      remainingMs()
+    );
+    if (reply.isError) {
+      throw new StudioMcpError(
+        'failed',
+        cleanToolError(reply.text) || `${tool} failed`,
+        studio
+      );
+    }
+    return { value: reply.text, studio };
+  });
+}
+
+export async function closeStudioMcpAsync(): Promise<void> {
+  const shared = _shared;
+  _shared = undefined;
+  if (shared) {
+    clearTimeout(shared.idleTimer);
+    await shared.client.closeAsync();
+  }
+}
+
+class StudioMcpError extends Error {
+  constructor(
+    public readonly reason: StudioMcpFailure,
+    message: string,
+    public readonly studio?: StudioMcpTarget
+  ) {
+    super(message);
+  }
+}
+
+async function _withMcpAsync<T>(
+  options: StudioMcpOptions,
+  runAsync: (
+    shared: SharedClient,
+    remainingMs: () => number
+  ) => Promise<{ value: T; studio?: StudioMcpTarget; settled?: boolean }>
+): Promise<StudioMcpResult<T>> {
+  const totalMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const endsAt = Date.now() + totalMs;
+  const remainingMs = () => Math.max(1, endsAt - Date.now());
+  let shared: SharedClient | undefined;
+  let timer: NodeJS.Timeout | undefined;
+
+  const work = (async (): Promise<StudioMcpResult<T>> => {
+    shared = await _acquireAsync(options, remainingMs);
+    return { success: true, ...(await runAsync(shared, remainingMs)) };
+  })();
+  work.catch(() => {});
+
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () =>
+        reject(
+          new McpTimeoutError(
+            `Studio's MCP server did not finish within ${totalMs}ms`
+          )
+        ),
+      totalMs
+    );
+  });
+
+  try {
+    const result = await Promise.race([work, deadline]);
+    _scheduleIdleClose(shared);
+    return result;
+  } catch (err) {
+    const failure = _toFailure(err);
+    if (failure.reason === 'timeout' || failure.reason === 'unavailable') {
+      await _discardAsync(shared);
+    } else {
+      _scheduleIdleClose(shared);
+    }
+    return failure;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function _acquireAsync(
+  options: StudioMcpOptions,
+  remainingMs: () => number
+): Promise<SharedClient> {
+  const key = options.executablePath ?? 'auto';
+  if (
+    _shared &&
+    _shared.client.isRunning &&
+    _shared.key === key &&
+    _shared.spawnProcess === options.spawnProcess
+  ) {
+    clearTimeout(_shared.idleTimer);
+    return _shared;
+  }
+  await closeStudioMcpAsync();
+
+  try {
+    const launch = options.executablePath
+      ? { command: options.executablePath, args: [] }
+      : await findStudioMcpLaunchAsync();
+    const client = await McpStdioClient.startAsync(launch.command, {
+      args: launch.args,
+      env: 'env' in launch ? launch.env : undefined,
+      spawnProcess: options.spawnProcess,
+      requestTimeoutMs: STEP_TIMEOUT_MS,
+    });
+    _shared = {
+      client,
+      startedAt: Date.now(),
+      key,
+      spawnProcess: options.spawnProcess,
+    };
+    return _shared;
+  } catch (err) {
+    if (err instanceof StudioMcpUnsupportedError) {
+      throw new StudioMcpError('unsupported', err.message);
+    }
+    throw new StudioMcpError(
+      'unavailable',
+      `Studio's MCP server is unavailable: ${_message(err)}`
+    );
+  }
+}
+
+async function _listSettledAsync(
+  shared: SharedClient,
+  remainingMs: () => number,
+  sessions: SessionInfo[] = []
+): Promise<{ studios: McpStudio[]; settled: boolean }> {
+  const editSessions = sessions.filter((s) => s.context === 'edit').length;
+  const isEnough = (found: McpStudio[]) =>
+    found.length > 0 && found.length >= editSessions;
+  const settlesAt = shared.startedAt + STUDIO_RECONNECT_MS;
+  let studios = await listMcpStudiosAsync(shared.client);
+  while (
+    !isEnough(studios) &&
+    Date.now() < settlesAt &&
+    remainingMs() > SETTLE_RESERVE_MS
+  ) {
+    await new Promise((resolve) => setTimeout(resolve, RECONNECT_POLL_MS));
+    studios = await listMcpStudiosAsync(shared.client);
+  }
+  return { studios, settled: isEnough(studios) || Date.now() >= settlesAt };
+}
+
+async function _matchAsync(
+  shared: SharedClient,
+  options: StudioMcpOptions,
+  studios: McpStudio[]
+): Promise<MatchedStudio[]> {
+  const windows = await (options.listWindowsAsync ?? _listWindowsAsync)().catch(
+    () => []
+  );
+  return matchStudiosAsync(shared.client, options.sessions ?? [], windows, {
+    readPlaceIds: options.readPlaceIds,
+    studios,
+    sessionPids: options.sessionPids,
+  });
+}
+
+function _scheduleIdleClose(shared: SharedClient | undefined) {
+  if (!shared || shared !== _shared) {
+    return;
+  }
+  clearTimeout(shared.idleTimer);
+  shared.idleTimer = setTimeout(() => {
+    if (_shared === shared) {
+      void closeStudioMcpAsync();
+    }
+  }, IDLE_CLOSE_MS);
+  shared.idleTimer.unref();
+}
+
+async function _discardAsync(shared: SharedClient | undefined) {
+  if (shared && shared === _shared) {
+    await closeStudioMcpAsync();
+  } else {
+    await shared?.client.closeAsync();
+  }
+}
+
+function _toFailure(
+  err: unknown
+): Extract<StudioMcpResult<never>, { success: false }> {
+  if (err instanceof StudioMcpError) {
+    return {
+      success: false,
+      reason: err.reason,
+      message: err.message,
+      ...(err.studio ? { studio: err.studio } : {}),
+    };
+  }
+  const message = _message(err);
+  if (err instanceof McpTimeoutError) {
+    return { success: false, reason: 'timeout', message };
+  }
+  if (err instanceof StudioNotFoundError) {
+    return { success: false, reason: 'no-studio', message };
+  }
+  return { success: false, reason: 'unavailable', message };
+}
+
+async function _listWindowsAsync(): Promise<StudioWindow[]> {
+  return (await listStudioProcessesAsync()).map(
+    ({ pid, windowTitle, startedAt }) => ({ pid, windowTitle, startedAt })
+  );
+}
+
+function _message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

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

@@ -0,0 +1,284 @@
+import { describe, expect, it } from 'vitest';
+import type { SessionInfo } from '../../bridge/types.js';
+import { McpStdioClient } from '../mcp/mcp-stdio-client.js';
+import { createFakeMcpServer, toolText } from '../test/fake-mcp-server.js';
+import {
+  cleanToolError,
+  matchStudiosAsync,
+  resolveStudio,
+  runLuauAsync,
+  type MatchedStudio,
+} from './studio-session.js';
+
+interface FakeStudio {
+  id: string;
+  name: string;
+  placeId: number;
+  gameId: number;
+  uptime?: number;
+}
+
+async function startAsync(studios: FakeStudio[]) {
+  const server = createFakeMcpServer((method, params) => {
+    if (method === 'initialize') {
+      return { result: { protocolVersion: '2025-06-18', capabilities: {} } };
+    }
+    if (params?.name === 'list_roblox_studios') {
+      return toolText(
+        JSON.stringify({
+          studios: studios.map(({ id, name }) => ({ id, name })),
+        })
+      );
+    }
+    if (params?.name === 'execute_luau') {
+      const studio = studios.find((s) => s.id === params.arguments.studio_id);
+      if (params.arguments.datamodel_type !== 'Edit') {
+        return toolText(
+          `${params.arguments.datamodel_type} datamodel is not available in Edit mode`,
+          true
+        );
+      }
+      return studio
+        ? toolText(`${studio.uptime ?? 0},${studio.placeId},${studio.gameId}`)
+        : toolText('not connected', true);
+    }
+    return undefined;
+  });
+  const client = await McpStdioClient.startAsync('StudioMCP.exe', {
+    spawnProcess: () => server.child,
+  });
+  return { server, client };
+}
+
+function session(overrides: Partial<SessionInfo>): SessionInfo {
+  return {
+    sessionId: 'place1-aaaa-edit',
+    instanceId: 'place1-aaaa',
+    placeName: 'Place1',
+    state: 'Edit',
+    pluginVersion: '1',
+    capabilities: [],
+    connectedAt: new Date(0),
+    origin: 'user',
+    context: 'edit',
+    placeId: 0,
+    gameId: 0,
+    ...overrides,
+  };
+}
+
+const luauCalls = (server: { requests: Array<{ params: any }> }) =>
+  server.requests.filter((r) => r.params?.name === 'execute_luau').length;
+
+describe('matchStudiosAsync', () => {
+  it('matches a uniquely named Studio to its session without running anything', async () => {
+    const { server, client } = await startAsync([
+      { id: 'mcp-1', name: 'Place1', placeId: 0, gameId: 0 },
+    ]);
+
+    const [studio] = await matchStudiosAsync(
+      client,
+      [session({})],
+      [{ pid: 7, windowTitle: 'Place1 - Roblox Studio' }]
+    );
+
+    expect(studio).toMatchObject({
+      studioId: 'mcp-1',
+      sessionId: 'place1-aaaa-edit',
+      instanceId: 'place1-aaaa',
+      pid: 7,
+    });
+    expect(luauCalls(server)).toBe(0);
+    await client.closeAsync();
+  });
+
+  it('tells same-named Studios apart by place id', async () => {
+    const { client } = await startAsync([
+      { id: 'mcp-1', name: 'Game', placeId: 111, gameId: 1 },
+      { id: 'mcp-2', name: 'Game', placeId: 222, gameId: 2 },
+    ]);
+
+    const studios = await matchStudiosAsync(client, [
+      session({
+        sessionId: 'a-edit',
+        instanceId: 'a',
+        placeName: 'Game',
+        placeId: 222,
+      }),
+      session({
+        sessionId: 'b-edit',
+        instanceId: 'b',
+        placeName: 'Game',
+        placeId: 111,
+      }),
+    ]);
+
+    expect(studios.map((s) => [s.studioId, s.sessionId])).toEqual([
+      ['mcp-1', 'b-edit'],
+      ['mcp-2', 'a-edit'],
+    ]);
+    await client.closeAsync();
+  });
+
+  it('leaves two unsaved places with the same name unmatched rather than guess', async () => {
+    const { client } = await startAsync([
+      { id: 'mcp-1', name: 'Place1', placeId: 0, gameId: 0 },
+      { id: 'mcp-2', name: 'Place1', placeId: 0, gameId: 0 },
+    ]);
+
+    const studios = await matchStudiosAsync(client, [
+      session({ sessionId: 'a-edit' }),
+      session({ sessionId: 'b-edit' }),
+    ]);
+
+    expect(studios.every((s) => s.sessionId === undefined)).toBe(true);
+    await client.closeAsync();
+  });
+
+  it('reads place ids for a Studio the bridge has no session for', async () => {
+    const { client } = await startAsync([
+      { id: 'mcp-1', name: 'Hub', placeId: 333, gameId: 3 },
+    ]);
+
+    const [studio] = await matchStudiosAsync(client, []);
+
+    expect(studio).toMatchObject({
+      studioId: 'mcp-1',
+      placeId: 333,
+      gameId: 3,
+    });
+    expect(studio.sessionId).toBeUndefined();
+    await client.closeAsync();
+  });
+});
+
+describe('cleanToolError', () => {
+  it("drops the Assistant's own frames from an execute_luau error", () => {
+    expect(
+      cleanToolError(
+        'sabuiltin_Assistant.rbxm.Assistant.Packages._Index.AssistantUI.AssistantUI.Tools.ExecuteLuauTool:125: sabuiltin_Assistant.rbxm.Assistant.Packages._Index.AssistantUI.AssistantUI.Util.CommandExecution:54: AssistantCommand:1: boom'
+      )
+    ).toBe('boom');
+  });
+
+  it('leaves other errors alone', () => {
+    expect(
+      cleanToolError('Server datamodel is not available in Edit mode')
+    ).toBe('Server datamodel is not available in Edit mode');
+  });
+});
+
+describe('resolveStudio', () => {
+  const studios: MatchedStudio[] = [
+    {
+      studioId: '1268b6c6-aaaa',
+      placeName: 'Place1',
+      sessionId: 'place1-3d83-edit',
+      instanceId: 'place1-3d83',
+      pid: 10,
+    },
+    { studioId: '99f00000-bbbb', placeName: 'Hub' },
+  ];
+
+  it('picks the only Studio without a target', () => {
+    expect(resolveStudio([studios[1]]).studioId).toBe('99f00000-bbbb');
+  });
+
+  it('asks for --target when several are open', () => {
+    expect(() => resolveStudio(studios)).toThrow('Pick one with --target');
+  });
+
+  it.each([
+    ['a bridge session id', 'place1-3d83-edit'],
+    ['a bridge instance id', 'place1-3d83'],
+    ['an instance id prefix', 'place1'],
+    ['an MCP studio id prefix', '1268b6c6'],
+    ['a pid', '10'],
+  ])('resolves %s', (_label, target) => {
+    expect(resolveStudio(studios, target).studioId).toBe('1268b6c6-aaaa');
+  });
+
+  it('resolves a place name for a Studio the bridge has no session for', () => {
+    expect(resolveStudio(studios, 'hub').studioId).toBe('99f00000-bbbb');
+  });
+
+  it('names the open Studios when nothing matches', () => {
+    expect(() => resolveStudio(studios, 'nope')).toThrow(
+      "No Studio matches 'nope'"
+    );
+  });
+});
+
+describe('runLuauAsync', () => {
+  it('maps a bridge context to the MCP data model and reports its error', async () => {
+    const { server, client } = await startAsync([
+      { id: 'mcp-1', name: 'Place1', placeId: 0, gameId: 0 },
+    ]);
+
+    const result = await runLuauAsync(client, 'mcp-1', 'return 1', 'server');
+
+    expect(server.requests.at(-1)?.params.arguments.datamodel_type).toBe(
+      'Server'
+    );
+    expect(result).toEqual({
+      success: false,
+      error: 'Server datamodel is not available in Edit mode',
+    });
+    await client.closeAsync();
+  });
+});
+
+describe('matchStudiosAsync by uptime', () => {
+  it('tells same-named unsaved Studios apart by how long each has run', async () => {
+    const now = Date.now();
+    const { client } = await startAsync([
+      { id: 'mcp-old', name: 'Place1', placeId: 0, gameId: 0, uptime: 300 },
+      { id: 'mcp-new', name: 'Place1', placeId: 0, gameId: 0, uptime: 290 },
+    ]);
+    const windows = [
+      {
+        pid: 70,
+        windowTitle: 'Place1 - Roblox Studio',
+        startedAt: now - 300_000,
+      },
+      {
+        pid: 80,
+        windowTitle: 'Place1 - Roblox Studio',
+        startedAt: now - 290_000,
+      },
+    ];
+
+    const studios = await matchStudiosAsync(
+      client,
+      [
+        session({ sessionId: 'a-edit', instanceId: 'a' }),
+        session({ sessionId: 'b-edit', instanceId: 'b' }),
+      ],
+      windows,
+      {
+        sessionPids: new Map([
+          ['a', 80],
+          ['b', 70],
+        ]),
+      }
+    );
+
+    expect(studios.map((s) => [s.studioId, s.pid, s.sessionId])).toEqual([
+      ['mcp-old', 70, 'b-edit'],
+      ['mcp-new', 80, 'a-edit'],
+    ]);
+    await client.closeAsync();
+  });
+
+  it('never gives one session to two Studios', async () => {
+    const { client } = await startAsync([
+      { id: 'mcp-1', name: 'Place1', placeId: 0, gameId: 0 },
+      { id: 'mcp-2', name: 'Place1', placeId: 0, gameId: 0 },
+    ]);
+
+    const studios = await matchStudiosAsync(client, [session({})]);
+
+    expect(studios.filter((s) => s.sessionId).length).toBe(0);
+    await client.closeAsync();
+  });
+});