@stage-labs/metro 0.1.0-beta.2 → 0.1.0-beta.21

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

@@ -0,0 +1,224 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join, parse as parsePath } from 'node:path';
+import { errMsg, log } from './log.js';
+import { coerceErrorInfo, type TrainErrorInfo } from './train-error.js';
+import type { StructuredEvent } from './events.js';
+import type { CallMsg } from '../stations/station-runtime.js';
+
+export {
+  TrainError,
+  serializeTrainError,
+  type TrainErrorInfo,
+} from './train-error.js';
+
+export const CALL_TIMEOUT_MS = 60_000;
+
+export interface Pending {
+  resolve: (r: TrainCallResponse) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+export interface CallTarget {
+  name: string;
+  pending: Map<string, Pending>;
+  proc: ({ stdin?: unknown } & Record<string, unknown>) | null;
+}
+
+export const STDOUT_LINE_MAX = 4 * 1024 * 1024;
+
+export type TrainEvent = {
+  station?: string;
+  line?: string;
+  line_name?: string;
+  from?: string;
+  from_name?: string;
+  from_display_name?: string;
+  to?: string;
+  message_id?: string;
+  reply_to?: string;
+  is_private?: boolean;
+  text?: string;
+  emoji?: string;
+  payload?: unknown;
+  ts?: string;
+  id?: string;
+  event?: StructuredEvent;
+} & Record<string, unknown>;
+
+export interface TrainCallResponse {
+  result?: unknown;
+  error?: string;
+  errorInfo?: TrainErrorInfo;
+}
+
+export type TrainMessage =
+  | {
+      op: 'response';
+      id: string;
+      result?: unknown;
+      error?: string;
+      errorInfo?: TrainErrorInfo;
+    }
+  | { op: 'log'; text?: string }
+  | { op: 'event'; event: TrainEvent }
+  | { op: 'ignore' };
+
+export function parseTrainLine(
+  name: string,
+  line: string,
+): TrainMessage | null {
+  let msg: {
+    op?: string;
+    id?: string;
+    result?: unknown;
+    error?: string;
+    errorInfo?: unknown;
+    text?: string;
+  } & Record<string, unknown>;
+  try {
+    msg = JSON.parse(line) as typeof msg;
+  } catch (err) {
+    log.warn(
+      { name, err: errMsg(err), line: line.slice(0, 200) },
+      'train: bad JSON',
+    );
+    return null;
+  }
+  if (msg.op === 'response') {
+    if (typeof msg.id !== 'string') return { op: 'ignore' };
+    return {
+      op: 'response',
+      id: msg.id,
+      result: msg.result,
+      error: msg.error,
+      errorInfo: coerceErrorInfo(msg.errorInfo),
+    };
+  }
+  if (msg.op === 'log') return { op: 'log', text: msg.text };
+  if (typeof msg.line !== 'string') {
+    log.warn(
+      { name, line: line.slice(0, 200) },
+      'train: event missing `line` (string) — dropped',
+    );
+    return { op: 'ignore' };
+  }
+  return { op: 'event', event: msg };
+}
+
+export function drainLines(
+  name: string,
+  buf: string,
+  onLine: (line: string) => void,
+): string {
+  if (buf.length > STDOUT_LINE_MAX && !buf.includes('\n')) {
+    log.warn(
+      { name, bytes: buf.length },
+      'train: dropping oversized stdout line',
+    );
+    return '';
+  }
+  let nl;
+  while ((nl = buf.indexOf('\n')) !== -1) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    onLine(line);
+  }
+  return buf;
+}
+
+export function readCalls(
+  name: string,
+  handleCall: (msg: CallMsg) => Promise<void>,
+): void {
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk: Buffer | string) => {
+    buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+    buf = drainLines(name, buf, (line) => {
+      try {
+        const msg = JSON.parse(line) as Partial<CallMsg>;
+        if (msg.op === 'call')
+          handleCall(msg as CallMsg).catch((e: unknown) => {
+            process.stderr.write(`call failed: ${errMsg(e)}\n`);
+          });
+      } catch (err: unknown) {
+        process.stderr.write(`bad stdin line: ${errMsg(err)}\n`);
+      }
+    });
+  });
+}
+
+export function encodeCall(id: string, action: string, args: unknown): string {
+  return JSON.stringify({ op: 'call', id, action, args }) + '\n';
+}
+
+function isTrainFile(name: string): boolean {
+  return (
+    /\.(ts|js|mjs)$/.test(name) &&
+    !name.startsWith('_') &&
+    !name.startsWith('.')
+  );
+}
+
+export function listTrainFiles(dir: string): { name: string; path: string }[] {
+  return readdirSync(dir)
+    .filter(isTrainFile)
+    .map((f) => ({ name: parsePath(f).name, path: join(dir, f) }))
+    .filter((t) => {
+      try {
+        return statSync(t.path).isFile();
+      } catch {
+        return false;
+      }
+    });
+}
+
+export function mintCallId(seq: number): string {
+  return `req_${seq}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function failAllPending(
+  pending: Map<string, Pending>,
+  reason: string,
+): void {
+  for (const p of pending.values()) {
+    clearTimeout(p.timer);
+    p.reject(new Error(reason));
+  }
+  pending.clear();
+}
+
+export function sendCall(
+  t: CallTarget,
+  id: string,
+  action: string,
+  args: unknown,
+): Promise<TrainCallResponse> {
+  return new Promise<TrainCallResponse>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      t.pending.delete(id);
+      reject(
+        new Error(
+          `train '${t.name}' call '${action}' timed out after ${CALL_TIMEOUT_MS}ms`,
+        ),
+      );
+    }, CALL_TIMEOUT_MS);
+    t.pending.set(id, { resolve, reject, timer });
+    try {
+      const stdin = (
+        t.proc as {
+          stdin?: { write: (s: string) => void; flush: () => void };
+        } | null
+      )?.stdin;
+      if (!stdin || typeof stdin === 'number')
+        throw new Error('stdin not piped');
+      stdin.write(encodeCall(id, action, args));
+      stdin.flush();
+    } catch (err) {
+      clearTimeout(timer);
+      t.pending.delete(id);
+      reject(new Error(`train '${t.name}' stdin write failed: ${errMsg(err)}`));
+    }
+  });
+}

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

@@ -0,0 +1,125 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { log } from './log.js';
+import {
+  apiFailure,
+  bodyField,
+  cors,
+  readJsonBody,
+  runIdentity,
+  sendJson,
+} from './api-http.js';
+import { RUN_CODE_RE, takeRunCode } from './run-pair.js';
+import { sessionTtlFromEnv } from './google-oauth.js';
+import { signRunToken } from './session.js';
+import type { LoadedAgent } from '../db/materialize.js';
+import type { RuntimeLease } from '../db/runtimes.js';
+
+const CLAIM_PATH = '/api/run/claim';
+const CONFIG_PATH = '/api/run/config';
+
+const ALLOWED: Record<string, string> = {
+  [CLAIM_PATH]: 'POST',
+  [CONFIG_PATH]: 'GET',
+};
+
+export interface RunApiDeps {
+  claimRuntime: (agentId: string, label: string) => Promise<RuntimeLease>;
+  fenceRuntime: (runtimeId: string, agentId: string) => Promise<void>;
+  touchRuntime: (runtimeId: string) => Promise<void>;
+  loadAgent: (agentId: string) => Promise<LoadedAgent>;
+}
+
+function secretOrNull(): string | null {
+  const secret = process.env.METRO_SESSION_SECRET?.trim() ?? '';
+  return secret === '' ? null : secret;
+}
+
+function labelOf(body: unknown): string {
+  const raw = bodyField(body, 'label');
+  const label = typeof raw === 'string' ? raw.trim().slice(0, 64) : '';
+  return label === '' ? 'unnamed machine' : label;
+}
+
+async function handleClaim(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: RunApiDeps,
+): Promise<void> {
+  const secret = secretOrNull();
+  if (secret === null) {
+    sendJson(req, res, 503, { error: 'sign-in is not configured' });
+    return;
+  }
+  const body = await readJsonBody(req);
+  const code = bodyField(body, 'code');
+  const taken =
+    typeof code === 'string' && RUN_CODE_RE.test(code)
+      ? takeRunCode(code)
+      : undefined;
+  if (taken === undefined) {
+    sendJson(req, res, 400, {
+      error: 'that code has expired or was already used',
+    });
+    return;
+  }
+  const lease = await deps.claimRuntime(taken.agentId, labelOf(body));
+  const token = signRunToken(
+    { email: taken.email, agentId: lease.agentId, runtimeId: lease.runtimeId },
+    secret,
+    { ttlSec: sessionTtlFromEnv() },
+  );
+  log.info(
+    { agent: lease.agentId, runtime: lease.runtimeId, label: lease.label },
+    'run: agent claimed by a local runtime',
+  );
+  sendJson(req, res, 200, {
+    token,
+    agent: lease.agentId,
+    label: lease.label,
+  });
+}
+
+async function handleConfig(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: RunApiDeps,
+): Promise<void> {
+  const who = runIdentity(req);
+  if (who === null) {
+    sendJson(req, res, 401, { error: 'unauthorized' });
+    return;
+  }
+  await deps.fenceRuntime(who.runtimeId, who.agentId);
+  await deps.touchRuntime(who.runtimeId);
+  sendJson(req, res, 200, { agent: await deps.loadAgent(who.agentId) });
+}
+
+export function handleRunApiRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: RunApiDeps,
+): boolean {
+  const path = (req.url ?? '').split('?')[0] ?? '';
+  const method = ALLOWED[path];
+  if (method === undefined) {
+    if (!path.startsWith('/api/run/') && path !== '/api/run') return false;
+    sendJson(req, res, 404, { error: 'no such route' });
+    return true;
+  }
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (req.method !== method) {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  const work =
+    path === CLAIM_PATH
+      ? handleClaim(req, res, deps)
+      : handleConfig(req, res, deps);
+  work.catch((err: unknown) => {
+    apiFailure(req, res, err, 'run-api');
+  });
+  return true;
+}

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

@@ -0,0 +1,18 @@
+import { makeCodeStore } from './pair-codes.js';
+
+export interface RunCode {
+  email: string;
+  agentId: string;
+}
+
+const store = makeCodeStore<RunCode>('mr');
+
+export const RUN_CODE_RE = store.pattern;
+
+export const mintRunCode = (
+  entry: RunCode,
+  now?: number,
+): { code: string; expiresAt: number } => store.mint(entry, now);
+
+export const takeRunCode = (code: string, now?: number): RunCode | undefined =>
+  store.take(code, now);

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

@@ -0,0 +1,105 @@
+import { errMsg, log } from './log.js';
+import type { LoadedAgent, StationSource } from '../db/materialize.js';
+
+const POLL_MS = 30_000;
+const BACKOFF_MS = 5 * 60_000;
+const FETCH_TIMEOUT_MS = 15_000;
+
+export class RuntimeRevoked extends Error {}
+
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost']);
+
+export function carriesSecretsSafely(base: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(base);
+  } catch {
+    return false;
+  }
+  if (url.protocol === 'https:') return true;
+  return url.protocol === 'http:' && LOOPBACK.has(url.hostname);
+}
+
+export interface RuntimeConfig {
+  url: string;
+  token: string;
+}
+
+export function runtimeConfigFromEnv(): RuntimeConfig | null {
+  const token = process.env.METRO_RUN_TOKEN?.trim() ?? '';
+  if (token === '') return null;
+  const raw = (process.env.METRO_URL?.trim() ?? '').replace(/\/+$/, '');
+  const url = raw === '' ? 'https://mcp.metro.box' : raw;
+  if (!carriesSecretsSafely(url))
+    throw new Error(
+      `refusing to fetch station credentials from ${url} in the clear — ` +
+        'use https, or a loopback address',
+    );
+  return { url, token };
+}
+
+export function httpSource(cfg: RuntimeConfig): StationSource {
+  return async () => {
+    const res = await fetch(`${cfg.url}/api/run/config`, {
+      headers: { authorization: `Bearer ${cfg.token}` },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      redirect: 'manual',
+    });
+    if (res.status === 401 || res.status === 403 || res.status === 409)
+      throw new RuntimeRevoked(
+        `metro no longer recognises this machine as the holder (${String(res.status)})`,
+      );
+    if (!res.ok)
+      throw new Error(`metro answered ${String(res.status)} for the run config`);
+    const body = (await res.json()) as { agent?: LoadedAgent };
+    if (!body.agent) throw new Error('metro returned no agent');
+    return [body.agent];
+  };
+}
+
+export interface PollerDeps {
+  sync: () => Promise<void>;
+  stopAll: () => Promise<void>;
+  everyMs?: number;
+  backoffMs?: number;
+}
+
+export function startRuntimePoller(deps: PollerDeps): () => void {
+  const everyMs = deps.everyMs ?? POLL_MS;
+  const backoffMs = deps.backoffMs ?? BACKOFF_MS;
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const arm = (ms: number): void => {
+    if (stopped) return;
+    timer = setTimeout(() => {
+      tick().catch((err: unknown) => {
+        log.error({ err: errMsg(err) }, 'runtime: poller failed');
+      });
+    }, ms);
+    timer.unref?.();
+  };
+
+  async function tick(): Promise<void> {
+    if (stopped) return;
+    try {
+      await deps.sync();
+      arm(everyMs);
+    } catch (err) {
+      if (err instanceof RuntimeRevoked) {
+        stopped = true;
+        log.error({ reason: err.message }, 'runtime: revoked — stopping stations');
+        await deps.stopAll();
+        return;
+      }
+      log.warn({ err: errMsg(err) }, 'runtime: could not reach metro; retrying');
+      arm(backoffMs);
+    }
+  }
+
+  arm(everyMs);
+  return () => {
+    stopped = true;
+    if (timer !== null) clearTimeout(timer);
+  };
+}

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

@@ -0,0 +1,57 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+import { errMsg, log } from './log.js';
+
+export function ensureSecureDir(dir: string): void {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    chmodSync(dir, 0o700);
+  } catch {
+  }
+}
+
+export function chmodIfExists(path: string, mode = 0o600): void {
+  if (!existsSync(path)) return;
+  try {
+    if ((statSync(path).mode & 0o777) !== mode) chmodSync(path, mode);
+  } catch {
+  }
+}
+
+export function writeSecure(path: string, data: string): void {
+  ensureSecureDir(dirname(path));
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, data, { mode: 0o600 });
+  try {
+    chmodSync(tmp, 0o600);
+  } catch {
+  }
+  renameSync(tmp, path);
+  chmodIfExists(path, 0o600);
+}
+
+export function readJson<T>(
+  path: string,
+  fallback: T,
+  opts?: { warn?: string },
+): T {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch (err) {
+    if (opts?.warn) log.warn({ err: errMsg(err), path }, opts.warn);
+    return fallback;
+  }
+}
+
+export function writeJson(path: string, value: unknown): void {
+  writeFileSync(path, JSON.stringify(value, null, 2));
+}

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

@@ -0,0 +1,27 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { apiSession, cors, sendJson } from './api-http.js';
+
+const PATH = '/api/session';
+
+export function handleSessionApiRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+): boolean {
+  const path = (req.url ?? '').split('?')[0] ?? '';
+  if (path !== PATH) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (req.method !== 'GET') {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  const session = apiSession(req);
+  if (!session) {
+    sendJson(req, res, 401, { error: 'unauthorized' });
+    return true;
+  }
+  sendJson(req, res, 200, { email: session.email });
+  return true;
+}

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

@@ -0,0 +1,41 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { handleSessionApiRequest } from './session-api.js';
+import { handleAgentApiRequest, type AgentApiDeps } from './agent-api.js';
+import {
+  handleConnectorApiRequest,
+  type ConnectorApiDeps,
+} from './connector-api.js';
+import { handleCollectionApiRequest } from './collection-api.js';
+import { handleCliPairRequest } from './cli-pair-api.js';
+import { handleRunApiRequest, type RunApiDeps } from './run-api.js';
+import {
+  handleProjectApiRequest,
+  type ProjectApiDeps,
+} from './project-api.js';
+
+export interface SessionApis {
+  agentApi?: AgentApiDeps;
+  connectorApi?: ConnectorApiDeps;
+  projectApi?: ProjectApiDeps;
+  runApi?: RunApiDeps;
+}
+
+export function handleSessionApis(
+  req: IncomingMessage,
+  res: ServerResponse,
+  apis: SessionApis,
+): boolean {
+  const { agentApi, connectorApi, projectApi, runApi } = apis;
+  const routes: (() => boolean)[] = [() => handleSessionApiRequest(req, res)];
+  if (runApi) routes.push(() => handleRunApiRequest(req, res, runApi));
+  if (projectApi)
+    routes.push(() => handleProjectApiRequest(req, res, projectApi));
+  if (connectorApi)
+    routes.push(
+      () => handleCliPairRequest(req, res, connectorApi),
+      () => handleCollectionApiRequest(req, res, connectorApi),
+      () => handleConnectorApiRequest(req, res, connectorApi),
+    );
+  if (agentApi) routes.push(() => handleAgentApiRequest(req, res, agentApi));
+  return routes.some((run) => run());
+}