@stage-labs/metro 0.1.0-beta.63 → 0.1.0-beta.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.63",
+  "version": "0.1.0-beta.64",
   "description": "The metro command line. Sign in once per machine, then hand your MCP connector list to Claude Code without the credentials touching disk, argv or shell history.",
   "license": "MIT",
   "repository": {

package/runtime/node_modules/@metro-labs/mcp/package.json

@@ -2,7 +2,7 @@
   "name": "@metro-labs/mcp",
   "version": "0.1.0-beta.15",
   "private": true,
-  "description": "Event-interception wire. Supervises train subprocesses in ~/.metro/trains/, multiplexes their JSON event stream onto stdout, and routes outbound action calls back via stdin. Per-platform code is written by the agent (or user) as train scripts \u2014 metro core is pure transport.",
+  "description": "Event-interception wire. Supervises train subprocesses in ~/.metro/trains/, multiplexes their JSON event stream onto stdout, and routes outbound action calls back via stdin. Per-platform code is written by the agent (or user) as train scripts — metro core is pure transport.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -51,10 +51,12 @@
     "pino-pretty": "^13.1.3",
     "postgres": "^3.4.5",
     "viem": "2.52.2",
+    "ws": "^8.18.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@stage-labs/config": "0.1.0-beta.2",
+    "@types/ws": "^8.18.0",
     "eslint": "^10.3.0",
     "knip": "^6.15.0",
     "madge": "^8.0.0",

package/runtime/node_modules/@metro-labs/mcp/src/daemon/http.ts

@@ -28,6 +28,8 @@ import {
 import { attachmentEventUrl, handleAttachRequest } from './attach-serve.js';
 import { webhookEntry } from '@metro-labs/webhook';
 import { handleIdentityRequest } from './identity-routes.js';
+import { attachTerminalSockets } from './terminal-ws.js';
+import { DEFAULT_TERMINAL_COMMAND } from './terminal-api.js';
 import { handleModeRequest } from './mode-api.js';
 import { handleUploadRequest } from './upload-api.js';
 import {
@@ -173,6 +175,8 @@ export async function startWebhookServer(
       if (!res.headersSent) res.writeHead(500).end();
     });
   });
+  if (apis.terminalApi !== undefined)
+    attachTerminalSockets(server, { command: apis.terminalApi.command ?? DEFAULT_TERMINAL_COMMAND });
   await new Promise<void>((resolve, reject) => {
     server.once('error', reject);
     const host = process.env.METRO_HTTP_HOST ?? '127.0.0.1';

package/runtime/node_modules/@metro-labs/mcp/src/daemon/local-mode.ts

@@ -191,6 +191,7 @@ export function localSessionApis(deps: LocalModeDeps): SessionApis {
     claudeApi: { authorize: (subject) => { assertLocalOwner(subject); } },
     updateApi: { authorize: (subject) => { assertLocalOwner(subject); }, restart: deps.restart },
     machineApi: { authorize: (subject) => { assertLocalOwner(subject); } },
+    terminalApi: { authorize: (subject) => { assertLocalOwner(subject); } },
     identity: { owner: localOwner },
     mode: localModeInfo,
   };

package/runtime/node_modules/@metro-labs/mcp/src/daemon/session-apis.ts

@@ -19,6 +19,7 @@ import { handleServersApiRequest, type ServersApiDeps } from './servers-api.js';
 import { handleBundleRequest, type BundleApiDeps } from './bundle-api.js';
 import { handleUpdateRequest, type UpdateApiDeps } from './update-api.js';
 import { handleMachineRequest, type MachineApiDeps } from './machine-api.js';
+import { handleTerminalRequest, type TerminalApiDeps } from './terminal-api.js';
 
 export interface SessionApis {
   agentApi?: AgentApiDeps;
@@ -28,6 +29,7 @@ export interface SessionApis {
   serversApi?: ServersApiDeps;
   updateApi?: UpdateApiDeps;
   machineApi?: MachineApiDeps;
+  terminalApi?: TerminalApiDeps;
   localCli?: LocalCliDeps;
   claudeApi?: ClaudeApiDeps;
   connectorApi?: ConnectorApiDeps;
@@ -53,6 +55,7 @@ export function handleSessionApis(
     ...when(apis.serversApi, (d) => handleServersApiRequest(req, res, d)),
     ...when(apis.updateApi, (d) => handleUpdateRequest(req, res, d)),
     ...when(apis.machineApi, (d) => handleMachineRequest(req, res, d)),
+    ...when(apis.terminalApi, (d) => handleTerminalRequest(req, res, d)),
     ...when(apis.claudeApi, (d) => handleClaudeRequest(req, res, d)),
     ...when(apis.agentConnectorApi, (d) => handleAgentConnectorRequest(req, res, d)),
     ...when(apis.agentApi, (d) => handleAgentApiRequest(req, res, d)),

package/runtime/node_modules/@metro-labs/mcp/src/daemon/terminal-api.ts

@@ -0,0 +1,54 @@
+import { spawnSync } from 'node:child_process';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ApiError } from './api-error.js';
+import { apiFailure, apiSession, cors, sendJson } from './api-http.js';
+import { log } from './log.js';
+import { mintTerminalTicket } from './terminal-tickets.js';
+
+const PREFIX = '/api/terminal';
+const TICKETS = `${PREFIX}/tickets`;
+export const TMUX_SESSION = 'metro';
+export const DEFAULT_TERMINAL_COMMAND = ['tmux', 'new-session', '-A', '-s', TMUX_SESSION];
+
+export interface TerminalApiDeps {
+  authorize: (subject: string) => void;
+  command?: string[];
+}
+
+function tmuxAvailable(command: string[]): boolean {
+  const bin = command[0] ?? '';
+  if (bin !== 'tmux') return true;
+  const run = spawnSync('tmux', ['-V'], { stdio: 'ignore' });
+  return run.error === undefined && run.status === 0;
+}
+
+export function handleTerminalRequest(req: IncomingMessage, res: ServerResponse, deps: TerminalApiDeps): boolean {
+  const path = (req.url ?? '').split('?')[0] ?? '';
+  if (path !== PREFIX && path !== TICKETS) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  const wanted = path === TICKETS ? 'POST' : 'GET';
+  if (req.method !== wanted) {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  apiSession(req)
+    .then((session) => {
+      if (!session) throw new ApiError('unauthorized', 401);
+      deps.authorize(session.subject);
+      const command = deps.command ?? DEFAULT_TERMINAL_COMMAND;
+      if (path === PREFIX) {
+        sendJson(req, res, 200, { available: tmuxAvailable(command), session: TMUX_SESSION, command });
+        return;
+      }
+      const minted = mintTerminalTicket(session.subject);
+      log.info({ subject: session.subject }, 'terminal: ticket minted');
+      sendJson(req, res, 200, { ...minted, path: `${PREFIX}/${minted.ticket}` });
+    })
+    .catch((err: unknown) => {
+      apiFailure(req, res, err, 'terminal-api');
+    });
+  return true;
+}

package/runtime/node_modules/@metro-labs/mcp/src/daemon/terminal-tickets.ts

@@ -0,0 +1,36 @@
+import { randomBytes } from 'node:crypto';
+
+const TTL_MS = 30_000;
+const MAX_OPEN = 20;
+
+interface Pending {
+  subject: string;
+  expiresAt: number;
+}
+
+const pending = new Map<string, Pending>();
+
+function prune(now: number): void {
+  for (const [ticket, entry] of pending) if (entry.expiresAt <= now) pending.delete(ticket);
+  while (pending.size >= MAX_OPEN) {
+    const oldest = pending.keys().next().value;
+    if (oldest === undefined) break;
+    pending.delete(oldest);
+  }
+}
+
+export function mintTerminalTicket(subject: string, now = Date.now()): { ticket: string; expiresAt: number } {
+  prune(now);
+  const ticket = randomBytes(32).toString('base64url');
+  const expiresAt = now + TTL_MS;
+  pending.set(ticket, { subject, expiresAt });
+  return { ticket, expiresAt };
+}
+
+export function takeTerminalTicket(ticket: string, now = Date.now()): string | null {
+  const entry = pending.get(ticket);
+  pending.delete(ticket);
+  return entry !== undefined && entry.expiresAt > now ? entry.subject : null;
+}
+
+export const pendingTerminalTickets = (): number => pending.size;

package/runtime/node_modules/@metro-labs/mcp/src/daemon/terminal-ws.ts

@@ -0,0 +1,91 @@
+import type { IncomingMessage, Server } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocketServer, type RawData, type WebSocket } from 'ws';
+import { errMsg, log } from './log.js';
+import { isRecord } from './is-record.js';
+import { takeTerminalTicket } from './terminal-tickets.js';
+
+const TICKET_PATH = /^\/api\/terminal\/([A-Za-z0-9_-]{43})$/;
+const MAX_MESSAGE = 1024 * 1024;
+const DEFAULT_COLS = 120;
+const DEFAULT_ROWS = 36;
+const MAX_DIMENSION = 500;
+
+export interface TerminalSocketDeps {
+  command: string[];
+  takeTicket?: (ticket: string) => string | null;
+}
+
+const rawBytes = (data: RawData): Buffer =>
+  Buffer.isBuffer(data) ? data : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+
+const dimension = (raw: unknown, fallback: number): number =>
+  typeof raw === 'number' && Number.isInteger(raw) && raw > 1 && raw <= MAX_DIMENSION ? raw : fallback;
+
+function runTerminal(ws: WebSocket, command: string[], subject: string): void {
+  const terminal = new Bun.Terminal({
+    cols: DEFAULT_COLS,
+    rows: DEFAULT_ROWS,
+    data: (_term, chunk) => {
+      if (ws.readyState === ws.OPEN) ws.send(chunk);
+    },
+  });
+  const proc = Bun.spawn(command, {
+    terminal,
+    env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' },
+  });
+  log.info({ subject, pid: proc.pid, command: command[0] }, 'terminal: opened');
+  ws.on('message', (data, isBinary) => {
+    const bytes = rawBytes(data);
+    if (isBinary) {
+      terminal.write(bytes);
+      return;
+    }
+    try {
+      const control: unknown = JSON.parse(bytes.toString('utf8'));
+      if (isRecord(control) && 'cols' in control)
+        terminal.resize(dimension(control.cols, DEFAULT_COLS), dimension(control.rows, DEFAULT_ROWS));
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'terminal: bad control frame');
+    }
+  });
+  ws.on('close', () => {
+    proc.kill();
+    terminal.close();
+    log.info({ subject, pid: proc.pid }, 'terminal: closed by the page');
+  });
+  proc.exited
+    .then((code) => {
+      if (ws.readyState === ws.OPEN) ws.close(1000, `exit ${String(code)}`);
+      terminal.close();
+    })
+    .catch((err: unknown) => {
+      log.warn({ err: errMsg(err) }, 'terminal: exit watch failed');
+    });
+}
+
+function refuse(socket: Duplex, status: number, text: string): void {
+  socket.write(`HTTP/1.1 ${String(status)} ${text}\r\nConnection: close\r\n\r\n`);
+  socket.destroy();
+}
+
+export function attachTerminalSockets(server: Server, deps: TerminalSocketDeps): void {
+  const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_MESSAGE });
+  const take = deps.takeTicket ?? takeTerminalTicket;
+  server.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+    const path = (req.url ?? '').split('?')[0] ?? '';
+    const found = TICKET_PATH.exec(path);
+    if (!found) {
+      refuse(socket, 404, 'Not Found');
+      return;
+    }
+    const subject = take(found[1] ?? '');
+    if (subject === null) {
+      refuse(socket, 401, 'Unauthorized');
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      runTerminal(ws, deps.command, subject);
+    });
+  });
+}

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.63"
+  "version": "0.1.0-beta.64"
 }

package/runtime/stations.json

@@ -5,6 +5,7 @@
     "pino": "^9.5.0",
     "pino-pretty": "^13.1.3",
     "viem": "2.52.2",
+    "ws": "^8.18.0",
     "zod": "^3.23.8"
   },
   "stations": {