@stage-labs/metro 0.1.0-beta.4 → 0.1.0-beta.41

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

@@ -0,0 +1,303 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { RelayTarget } from '../db/connector-relay.js';
+import { agentIdentity, assertLease, type Fence } from './api-http.js';
+import { ApiError } from './api-error.js';
+import { errMsg, log } from './log.js';
+
+export interface RelayApiDeps {
+  target: (
+    agentId: string,
+    connectorId: string,
+    force: boolean,
+  ) => Promise<RelayTarget>;
+  fence: Fence;
+}
+
+const ID_PATH_RE = /^\/relay\/([A-Za-z0-9][A-Za-z0-9_-]{10})$/;
+const METHODS = new Set(['POST', 'GET', 'DELETE']);
+const RELAY_BODY_MAX = 8 * 1024 * 1024;
+const FIRST_BYTE_MS = 120_000;
+const PASS_REQ = [
+  'accept',
+  'content-type',
+  'mcp-session-id',
+  'mcp-protocol-version',
+  'last-event-id',
+] as const;
+const PASS_RES = [
+  'content-type',
+  'mcp-session-id',
+  'mcp-protocol-version',
+  'cache-control',
+] as const;
+
+const keepaliveMs = (): number =>
+  Number(process.env.METRO_RELAY_KEEPALIVE_MS) || 25_000;
+
+const reconnectUrl = (id: string): string =>
+  `https://metro.box/#/connector/${id}`;
+
+function answer(
+  res: ServerResponse,
+  status: number,
+  body: Record<string, unknown>,
+): void {
+  if (res.headersSent) return;
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+const signinAnswer = (res: ServerResponse, id: string): void => {
+  answer(res, 424, {
+    error: 'this connector needs signing in again',
+    reconnect: reconnectUrl(id),
+  });
+};
+
+function closeIfBodyUnread(req: IncomingMessage, res: ServerResponse): void {
+  if (req.readableEnded) return;
+  const drop = (): void => {
+    req.socket?.destroy();
+  };
+  if (res.writableFinished) drop();
+  else res.once('finish', drop);
+}
+
+async function readCapped(req: IncomingMessage): Promise<Uint8Array<ArrayBuffer>> {
+  const declared = Number(req.headers['content-length']);
+  if (Number.isFinite(declared) && declared > RELAY_BODY_MAX)
+    throw new ApiError('relay body exceeds 8 MiB', 413);
+  const chunks: Buffer[] = [];
+  let total = 0;
+  for await (const chunk of req) {
+    const buf = chunk as Buffer;
+    total += buf.length;
+    if (total > RELAY_BODY_MAX)
+      throw new ApiError('relay body exceeds 8 MiB', 413);
+    chunks.push(buf);
+  }
+  const merged = Buffer.concat(chunks);
+  const out = new Uint8Array(new ArrayBuffer(merged.byteLength));
+  out.set(merged);
+  return out;
+}
+
+function upstreamHeaders(
+  req: IncomingMessage,
+  injected: Record<string, string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const name of PASS_REQ) {
+    const value = req.headers[name];
+    if (typeof value === 'string') out[name] = value;
+  }
+  return { ...out, ...injected };
+}
+
+async function forward(
+  req: IncomingMessage,
+  target: { url: string; headers: Record<string, string> },
+  body: Uint8Array<ArrayBuffer> | null,
+  signal: AbortSignal,
+): Promise<Response> {
+  const firstByte = setTimeout(() => {
+    log.warn({ url: target.url }, 'relay: upstream sent no response in time');
+  }, FIRST_BYTE_MS);
+  firstByte.unref?.();
+  try {
+    return await fetch(target.url, {
+      method: req.method,
+      headers: upstreamHeaders(req, target.headers),
+      ...(body === null ? {} : { body }),
+      signal,
+      redirect: 'manual',
+    });
+  } finally {
+    clearTimeout(firstByte);
+  }
+}
+
+interface Keepalive {
+  touch: () => void;
+  stop: () => void;
+}
+
+function startKeepalive(res: ServerResponse): Keepalive {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const arm = (): void => {
+    timer = setTimeout(() => {
+      try {
+        res.write(': keepalive\n\n');
+      } catch {
+        log.debug('relay: keepalive write failed');
+      }
+      arm();
+    }, keepaliveMs());
+    timer.unref?.();
+  };
+  arm();
+  return {
+    touch: (): void => {
+      if (timer) clearTimeout(timer);
+      arm();
+    },
+    stop: (): void => {
+      if (timer) clearTimeout(timer);
+    },
+  };
+}
+
+async function pumpBody(
+  res: ServerResponse,
+  body: ReadableStream<Uint8Array>,
+  touch: () => void,
+): Promise<void> {
+  const reader = body.getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) return;
+    touch();
+    const ok = res.write(value);
+    if (!ok)
+      await new Promise((resolve) => {
+        res.once('drain', resolve);
+      });
+  }
+}
+
+async function pipe(res: ServerResponse, upstream: Response): Promise<void> {
+  const headers: Record<string, string> = {};
+  for (const name of PASS_RES) {
+    const value = upstream.headers.get(name);
+    if (value !== null) headers[name] = value;
+  }
+  const sse = (headers['content-type'] ?? '').includes('text/event-stream');
+  if (sse) headers['x-accel-buffering'] = 'no';
+  res.writeHead(upstream.status, headers);
+  if (upstream.body === null) {
+    res.end();
+    return;
+  }
+  const keepalive = sse ? startKeepalive(res) : null;
+  try {
+    await pumpBody(res, upstream.body, () => keepalive?.touch());
+  } finally {
+    keepalive?.stop();
+  }
+  res.end();
+}
+
+const authFailed = (status: number): boolean =>
+  status === 401 || status === 403;
+
+type Exchanged =
+  | { kind: 'response'; upstream: Response }
+  | { kind: 'missing' }
+  | { kind: 'signin' };
+
+async function exchange(
+  req: IncomingMessage,
+  agentId: string,
+  connectorId: string,
+  deps: RelayApiDeps,
+  body: Uint8Array<ArrayBuffer> | null,
+  signal: AbortSignal,
+): Promise<Exchanged> {
+  const target = await deps.target(agentId, connectorId, false);
+  if (target.kind !== 'ok') return { kind: target.kind };
+  let upstream = await forward(req, target, body, signal);
+  if (!authFailed(upstream.status)) return { kind: 'response', upstream };
+  await upstream.body?.cancel();
+  const fresh = await deps.target(agentId, connectorId, true);
+  if (fresh.kind !== 'ok') return { kind: 'signin' };
+  upstream = await forward(req, fresh, body, signal);
+  if (!authFailed(upstream.status)) return { kind: 'response', upstream };
+  await upstream.body?.cancel();
+  return { kind: 'signin' };
+}
+
+async function relayExchange(
+  req: IncomingMessage,
+  res: ServerResponse,
+  agentId: string,
+  connectorId: string,
+  deps: RelayApiDeps,
+): Promise<void> {
+  const control = new AbortController();
+  const bail = (): void => {
+    if (!res.writableEnded) control.abort();
+  };
+  res.once('close', bail);
+  res.socket?.once('close', bail);
+  res.once('finish', () => {
+    res.socket?.removeListener('close', bail);
+  });
+  const body = req.method === 'POST' ? await readCapped(req) : null;
+  const out = await exchange(
+    req,
+    agentId,
+    connectorId,
+    deps,
+    body,
+    control.signal,
+  );
+  if (out.kind === 'missing') {
+    answer(res, 404, { error: 'no such connector' });
+    return;
+  }
+  if (out.kind === 'signin') {
+    signinAnswer(res, connectorId);
+    return;
+  }
+  if (out.upstream.status >= 300 && out.upstream.status < 400) {
+    await out.upstream.body?.cancel();
+    answer(res, 502, { error: 'the connector redirected; metro does not follow' });
+    return;
+  }
+  await pipe(res, out.upstream);
+}
+
+function dispatch(
+  req: IncomingMessage,
+  res: ServerResponse,
+  connectorId: string,
+  deps: RelayApiDeps,
+): void {
+  const who = agentIdentity(req);
+  if (who === null) {
+    answer(res, 401, { error: 'unauthorized' });
+    return;
+  }
+  assertLease(who, deps.fence)
+    .then(() => relayExchange(req, res, who.agentId, connectorId, deps))
+    .catch((err: unknown) => {
+      if (err instanceof ApiError) {
+        answer(res, err.status, { error: err.message });
+      } else {
+        log.warn({ err: errMsg(err), connector: connectorId }, 'relay: failed');
+        answer(res, 502, { error: 'metro could not reach the connector' });
+        if (!res.writableEnded) res.end();
+      }
+      closeIfBodyUnread(req, res);
+    });
+}
+
+export function handleRelayRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: RelayApiDeps,
+): boolean {
+  const path = (req.url ?? '').split('?')[0] ?? '';
+  if (path !== '/relay' && !path.startsWith('/relay/')) return false;
+  const match = ID_PATH_RE.exec(path);
+  if (match?.[1] === undefined) {
+    answer(res, 404, { error: 'no such connector' });
+    return true;
+  }
+  if (!METHODS.has(req.method ?? '')) {
+    answer(res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  dispatch(req, res, match[1], deps);
+  return true;
+}

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

@@ -0,0 +1,139 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { log } from './log.js';
+import {
+  apiFailure,
+  bodyField,
+  cors,
+  readJsonBody,
+  runIdentity,
+  sendJson,
+} from './api-http.js';
+import { AGENT_CODE_RE, takeAgentCode } from './agent-pair.js';
+import { sessionTtlFromEnv } from './session-config.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>;
+  blockedStations: (agentId: string) => Promise<string[]>;
+}
+
+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 raw = bodyField(body, 'code');
+  const code = typeof raw === 'string' ? raw.trim() : '';
+  if (!AGENT_CODE_RE.test(code)) {
+    sendJson(req, res, 400, {
+      error:
+        'that does not look like an agent code — metro start wants the ma_… code from the agent page',
+    });
+    return;
+  }
+  const taken = takeAgentCode(code);
+  if (taken === undefined) {
+    sendJson(req, res, 400, {
+      error: 'that code has expired or was already used',
+    });
+    return;
+  }
+  const blocked = await deps.blockedStations(taken.agentId);
+  if (blocked.length > 0) {
+    sendJson(req, res, 409, {
+      error:
+        `this agent holds ${blocked.join(', ')}, which only runs on metro because a webhook url has to be publicly reachable. Detach it, or move it to a second agent that stays on metro, then start this one.`,
+    });
+    return;
+  }
+  const lease = await deps.claimRuntime(taken.agentId, labelOf(body));
+  const token = signRunToken(
+    { subject: taken.subject, 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/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, { subject: session.subject });
+  return true;
+}

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

@@ -0,0 +1,63 @@
+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 { handleCliPairRequest } from './cli-pair-api.js';
+import { handleRunApiRequest, type RunApiDeps } from './run-api.js';
+import type { RelayApiDeps } from './relay.js';
+import {
+  handleProjectApiRequest,
+  type ProjectApiDeps,
+} from './project-api.js';
+import {
+  handleAgentConnectorRequest,
+  type AgentConnectorApiDeps,
+} from './agent-connector-api.js';
+import type { SiweRouteDeps } from './siwe-routes.js';
+import { handleImportRequest, type ImportApiDeps } from './import-api.js';
+import {
+  handleLocalConnectorsRequest,
+  type LocalConnectorsDeps,
+} from './local-connectors-api.js';
+import type { ModeInfo } from './mode-api.js';
+
+export interface SessionApis {
+  agentApi?: AgentApiDeps;
+  agentConnectorApi?: AgentConnectorApiDeps;
+  importApi?: ImportApiDeps;
+  localConnectors?: LocalConnectorsDeps;
+  connectorApi?: ConnectorApiDeps;
+  projectApi?: ProjectApiDeps;
+  runApi?: RunApiDeps;
+  relayApi?: RelayApiDeps;
+  siwe?: SiweRouteDeps;
+  mode?: () => ModeInfo;
+}
+
+export function handleSessionApis(
+  req: IncomingMessage,
+  res: ServerResponse,
+  apis: SessionApis,
+): boolean {
+  const { agentApi, agentConnectorApi, connectorApi, projectApi, runApi, importApi } = apis;
+  const { localConnectors } = 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),
+      () => handleConnectorApiRequest(req, res, connectorApi),
+    );
+  if (importApi) routes.push(() => handleImportRequest(req, res, importApi));
+  if (localConnectors)
+    routes.push(() => handleLocalConnectorsRequest(req, res, localConnectors));
+  if (agentConnectorApi)
+    routes.push(() => handleAgentConnectorRequest(req, res, agentConnectorApi));
+  if (agentApi) routes.push(() => handleAgentApiRequest(req, res, agentApi));
+  return routes.some((run) => run());
+}