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

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

@@ -0,0 +1,218 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { ID_RE } from '../db/ids.js';
+
+export class SessionError extends Error {}
+
+const b64url = (buf: Buffer): string =>
+  buf
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+
+const b64urlJson = (v: unknown): string =>
+  b64url(Buffer.from(JSON.stringify(v)));
+
+const decodeJson = (seg: string): unknown =>
+  JSON.parse(
+    Buffer.from(seg.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString(
+      'utf8',
+    ),
+  );
+
+const HEADER = b64urlJson({ alg: 'HS256', typ: 'JWT' });
+
+function sign(payload: Record<string, unknown>, secret: string): string {
+  if (secret === '') throw new SessionError('missing signing secret');
+  const body = b64urlJson(payload);
+  const data = `${HEADER}.${body}`;
+  const sig = b64url(createHmac('sha256', secret).update(data).digest());
+  return `${data}.${sig}`;
+}
+
+function verify(token: string, secret: string): Record<string, unknown> {
+  if (secret === '') throw new SessionError('missing signing secret');
+  const parts = token.split('.');
+  if (parts.length !== 3) throw new SessionError('malformed token');
+  const data = `${parts[0]}.${parts[1]}`;
+  const expected = b64url(createHmac('sha256', secret).update(data).digest());
+  const a = Buffer.from(parts[2] ?? '');
+  const b = Buffer.from(expected);
+  if (a.length !== b.length || !timingSafeEqual(a, b))
+    throw new SessionError('bad signature');
+  let payload: unknown;
+  try {
+    payload = decodeJson(parts[1] ?? '');
+  } catch {
+    throw new SessionError('malformed payload');
+  }
+  if (typeof payload !== 'object' || payload === null)
+    throw new SessionError('malformed payload');
+  return payload as Record<string, unknown>;
+}
+
+const nowSec = (now?: number): number => Math.floor((now ?? Date.now()) / 1000);
+
+export function newNonce(): string {
+  return b64url(randomBytes(16));
+}
+
+interface StateClaims {
+  return_to: string;
+  nonce: string;
+}
+
+export function signState(
+  claims: StateClaims,
+  secret: string,
+  opts: { ttlSec?: number; now?: number } = {},
+): string {
+  const iat = nowSec(opts.now);
+  return sign(
+    {
+      typ: 'state',
+      return_to: claims.return_to,
+      nonce: claims.nonce,
+      iat,
+      exp: iat + (opts.ttlSec ?? 600),
+    },
+    secret,
+  );
+}
+
+export function verifyState(
+  token: string,
+  secret: string,
+  now?: number,
+): StateClaims {
+  const p = verify(token, secret);
+  if (p.typ !== 'state') throw new SessionError('wrong token type');
+  if (typeof p.exp !== 'number' || p.exp < nowSec(now))
+    throw new SessionError('state expired');
+  if (typeof p.return_to !== 'string' || typeof p.nonce !== 'string')
+    throw new SessionError('malformed state');
+  return { return_to: p.return_to, nonce: p.nonce };
+}
+
+interface SessionClaims {
+  email: string;
+  agentIds: string[];
+}
+
+export interface CliClaims {
+  email: string;
+  collectionId: string;
+}
+
+export interface RunClaims {
+  email: string;
+  agentId: string;
+  runtimeId: string;
+}
+
+export function signSession(
+  claims: SessionClaims,
+  secret: string,
+  opts: { ttlSec?: number; now?: number } = {},
+): string {
+  const iat = nowSec(opts.now);
+  return sign(
+    {
+      typ: 'session',
+      sub: claims.email,
+      agent_ids: claims.agentIds,
+      iat,
+      exp: iat + (opts.ttlSec ?? 30 * 24 * 3600),
+    },
+    secret,
+  );
+}
+
+export function verifySession(
+  token: string,
+  secret: string,
+  now?: number,
+): SessionClaims {
+  const p = verify(token, secret);
+  if (p.typ !== 'session') throw new SessionError('wrong token type');
+  if (typeof p.exp !== 'number' || p.exp < nowSec(now))
+    throw new SessionError('session expired');
+  const ids = p.agent_ids;
+  if (
+    typeof p.sub !== 'string' ||
+    !Array.isArray(ids) ||
+    ids.some((a) => typeof a !== 'string' || !ID_RE.test(a))
+  )
+    throw new SessionError('malformed session');
+  return { email: p.sub, agentIds: ids as string[] };
+}
+
+export function signCliToken(
+  claims: CliClaims,
+  secret: string,
+  opts: { ttlSec?: number; now?: number } = {},
+): string {
+  const iat = nowSec(opts.now);
+  return sign(
+    {
+      typ: 'cli',
+      sub: claims.email,
+      collection: claims.collectionId,
+      iat,
+      exp: iat + (opts.ttlSec ?? 30 * 24 * 3600),
+    },
+    secret,
+  );
+}
+
+export function verifyCliToken(
+  token: string,
+  secret: string,
+  now?: number,
+): CliClaims {
+  const p = verify(token, secret);
+  if (p.typ !== 'cli') throw new SessionError('wrong token type');
+  if (typeof p.exp !== 'number' || p.exp < nowSec(now))
+    throw new SessionError('cli token expired');
+  if (typeof p.sub !== 'string' || typeof p.collection !== 'string')
+    throw new SessionError('malformed cli token');
+  return { email: p.sub, collectionId: p.collection };
+}
+
+export function signRunToken(
+  claims: RunClaims,
+  secret: string,
+  opts: { ttlSec?: number; now?: number } = {},
+): string {
+  const iat = nowSec(opts.now);
+  return sign(
+    {
+      typ: 'run',
+      sub: claims.email,
+      agent: claims.agentId,
+      rt: claims.runtimeId,
+      iat,
+      exp: iat + (opts.ttlSec ?? 365 * 24 * 3600),
+    },
+    secret,
+  );
+}
+
+export function verifyRunToken(
+  token: string,
+  secret: string,
+  now?: number,
+): RunClaims {
+  const p = verify(token, secret);
+  if (p.typ !== 'run') throw new SessionError('wrong token type');
+  if (typeof p.exp !== 'number' || p.exp < nowSec(now))
+    throw new SessionError('run token expired');
+  if (
+    typeof p.sub !== 'string' ||
+    typeof p.agent !== 'string' ||
+    typeof p.rt !== 'string' ||
+    !ID_RE.test(p.agent)
+  )
+    throw new SessionError('malformed run token');
+  return { email: p.sub, agentId: p.agent, runtimeId: p.rt };
+}

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

@@ -0,0 +1,97 @@
+import { watch, type FSWatcher } from 'node:fs';
+import { join, parse as parsePath } from 'node:path';
+import { errMsg, log } from './log.js';
+import type { Pending } from './protocol.js';
+
+export const RESTART_BACKOFFS_MS = [1_000, 5_000, 30_000] as const;
+export const MAX_CONSECUTIVE_FAILS = 5;
+export const HOT_RELOAD_DEBOUNCE_MS = 300;
+export const TRAIN_EXT = /\.(ts|js|mjs)$/;
+
+export interface TrainState {
+  name: string;
+  path: string;
+  proc: ReturnType<typeof Bun.spawn> | null;
+  pending: Map<string, Pending>;
+  buf: string;
+  errBuf: string;
+  failCount: number;
+  restartTimer: ReturnType<typeof setTimeout> | null;
+  startedAt: string | null;
+  stopped: boolean;
+}
+
+export function startWatcher(
+  dir: string,
+  timers: Map<string, ReturnType<typeof setTimeout>>,
+  onChange: (name: string, path: string) => void,
+): FSWatcher | null {
+  try {
+    const w = watch(dir, (_event, filename) => {
+      if (!filename) return;
+      const base = filename;
+      if (!TRAIN_EXT.test(base) || base.startsWith('_') || base.startsWith('.'))
+        return;
+      const name = parsePath(base).name;
+      const existing = timers.get(name);
+      if (existing) clearTimeout(existing);
+      timers.set(
+        name,
+        setTimeout(() => {
+          timers.delete(name);
+          onChange(name, join(dir, base));
+        }, HOT_RELOAD_DEBOUNCE_MS),
+      );
+    });
+    w.on('error', (err) => {
+      log.warn({ err: errMsg(err) }, 'train hot-reload: watcher error');
+    });
+    log.info({ dir }, 'train hot-reload: watching');
+    return w;
+  } catch (err) {
+    log.warn(
+      { err: errMsg(err) },
+      'train hot-reload: watch unavailable (on-demand restart only)',
+    );
+    return null;
+  }
+}
+
+export function killGracefully(
+  proc: ReturnType<typeof Bun.spawn> | null,
+): Promise<unknown> | null {
+  if (proc?.exitCode !== null) return null;
+  try {
+    proc.kill('SIGTERM');
+  } catch {
+  }
+  const grace = setTimeout(() => {
+    try {
+      proc.kill('SIGKILL');
+    } catch {
+    }
+  }, 2_000);
+  return proc.exited.finally(() => {
+    clearTimeout(grace);
+  });
+}
+
+export async function pumpStream(
+  stream: unknown,
+  name: string,
+  kind: 'stdout' | 'stderr',
+  onChunk: (s: string) => void,
+): Promise<void> {
+  if (!stream || typeof stream === 'number') return;
+  const reader = (stream as ReadableStream<Uint8Array>).getReader();
+  const dec = new TextDecoder();
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      onChunk(dec.decode(value, { stream: true }));
+    }
+  } catch (err) {
+    log.debug({ name, err: errMsg(err) }, `train: ${kind} pump ended`);
+  }
+}

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

@@ -0,0 +1,323 @@
+import { mkdirSync, statSync, type FSWatcher } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { errMsg, log } from './log.js';
+import { daemonSelf } from './events.js';
+import {
+  drainLines,
+  failAllPending,
+  listTrainFiles,
+  mintCallId,
+  parseTrainLine,
+  sendCall,
+  type TrainCallResponse,
+  type TrainEvent,
+} from './protocol.js';
+import {
+  HOT_RELOAD_DEBOUNCE_MS,
+  MAX_CONSECUTIVE_FAILS,
+  RESTART_BACKOFFS_MS,
+  killGracefully,
+  pumpStream,
+  startWatcher,
+  type TrainState,
+} from './supervisor-io.js';
+
+export const TRAINS_DIR =
+  process.env.METRO_TRAINS_DIR ?? join(homedir(), '.metro', 'trains');
+
+const DYLD_FALLBACK_ENV: Record<string, string> =
+  process.platform === 'darwin'
+    ? {
+        DYLD_FALLBACK_LIBRARY_PATH: [
+          '/usr/lib',
+          process.env.DYLD_FALLBACK_LIBRARY_PATH,
+        ]
+          .filter(Boolean)
+          .join(':'),
+      }
+    : {};
+
+export class TrainSupervisor {
+  private trains = new Map<string, TrainState>();
+  private onEvent: ((event: TrainEvent, train: string) => void) | null = null;
+  private nextCallId = 1;
+  private watcher: FSWatcher | null = null;
+  private reloadTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(private dir: string = TRAINS_DIR) {}
+
+  running(): string[] {
+    return [...this.trains.keys()];
+  }
+
+  onTrainEvent(handler: (event: TrainEvent, train: string) => void): void {
+    this.onEvent = handler;
+  }
+
+  start(): void {
+    mkdirSync(this.dir, { recursive: true });
+    for (const t of listTrainFiles(this.dir)) this.startTrain(t.name, t.path);
+    log.info(
+      { dir: this.dir, count: this.trains.size },
+      'train supervisor: started',
+    );
+    this.watchForReloads();
+  }
+
+  private watchForReloads(): void {
+    this.watcher = startWatcher(this.dir, this.reloadTimers, (name, path) => {
+      this.handleSourceChange(name, path);
+    });
+  }
+
+  requestReload(name: string): void {
+    const path = join(this.dir, `${name}.ts`);
+    const existing = this.reloadTimers.get(name);
+    if (existing) clearTimeout(existing);
+    this.reloadTimers.set(
+      name,
+      setTimeout(() => {
+        this.reloadTimers.delete(name);
+        this.handleSourceChange(name, path);
+      }, HOT_RELOAD_DEBOUNCE_MS),
+    );
+  }
+
+  async stopTrain(name: string): Promise<void> {
+    const t = this.trains.get(name);
+    if (!t) return;
+    const timer = this.reloadTimers.get(name);
+    if (timer) {
+      clearTimeout(timer);
+      this.reloadTimers.delete(name);
+    }
+    t.stopped = true;
+    if (t.restartTimer) {
+      clearTimeout(t.restartTimer);
+      t.restartTimer = null;
+    }
+    failAllPending(t.pending, `train '${name}' stopped`);
+    const wait = killGracefully(t.proc);
+    if (wait) await wait;
+    this.trains.delete(name);
+    log.info({ name }, 'train: stopped, last account detached');
+  }
+
+  private handleSourceChange(name: string, path: string): void {
+    try {
+      if (!statSync(path).isFile()) return;
+    } catch {
+      return;
+    }
+    if (this.trains.has(name)) {
+      log.info({ name }, 'train hot-reload: source changed, restarting');
+      this.restart(name).catch((err: unknown) => {
+        log.warn(
+          { name, err: errMsg(err) },
+          'train hot-reload: restart failed',
+        );
+      });
+      return;
+    }
+    log.info({ name }, 'train hot-reload: new train, spawning');
+    this.startTrain(name, path);
+  }
+
+  async stop(): Promise<void> {
+    if (this.watcher) {
+      try {
+        this.watcher.close();
+      } catch {
+      }
+      this.watcher = null;
+    }
+    for (const timer of this.reloadTimers.values()) clearTimeout(timer);
+    this.reloadTimers.clear();
+    const tasks: Promise<unknown>[] = [];
+    for (const t of this.trains.values()) {
+      t.stopped = true;
+      if (t.restartTimer) {
+        clearTimeout(t.restartTimer);
+        t.restartTimer = null;
+      }
+      failAllPending(t.pending, 'train shutting down');
+      const wait = killGracefully(t.proc);
+      if (wait) tasks.push(wait);
+    }
+    await Promise.all(tasks);
+  }
+
+  async restart(name: string): Promise<void> {
+    const t = this.trains.get(name);
+    if (!t) throw new Error(`no train named '${name}'`);
+    if (t.restartTimer) {
+      clearTimeout(t.restartTimer);
+      t.restartTimer = null;
+    }
+    failAllPending(t.pending, `train '${name}' restarting`);
+    t.stopped = true;
+    const wait = killGracefully(t.proc);
+    if (wait) await wait;
+    t.stopped = false;
+    t.failCount = 0;
+    t.proc = null;
+    this.spawn(t);
+  }
+
+  async call(
+    name: string,
+    action: string,
+    args: unknown,
+  ): Promise<TrainCallResponse> {
+    const t = this.trains.get(name);
+    if (!t)
+      throw new Error(
+        `no train named '${name}' (have: ${[...this.trains.keys()].join(', ') || '(none)'})`,
+      );
+    if (t.proc?.exitCode !== null)
+      throw new Error(`train '${name}' is not running`);
+    return sendCall(t as never, mintCallId(this.nextCallId++), action, args);
+  }
+
+  private startTrain(name: string, path: string): void {
+    if (this.trains.has(name)) {
+      log.warn({ name }, 'train supervisor: duplicate name, skipping');
+      return;
+    }
+    const state: TrainState = {
+      name,
+      path,
+      proc: null,
+      pending: new Map(),
+      buf: '',
+      errBuf: '',
+      failCount: 0,
+      restartTimer: null,
+      startedAt: null,
+      stopped: false,
+    };
+    this.trains.set(name, state);
+    this.spawn(state);
+  }
+
+  private spawn(state: TrainState): void {
+    if (state.stopped) return;
+    try {
+      const proc = Bun.spawn(['bun', 'run', state.path], {
+        stdin: 'pipe',
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: {
+          ...process.env,
+          ...DYLD_FALLBACK_ENV,
+          METRO_TRAIN_NAME: state.name,
+          METRO_SELF_URI: daemonSelf(),
+        },
+      });
+      state.proc = proc;
+      state.startedAt = new Date().toISOString();
+      state.buf = '';
+      state.errBuf = '';
+      log.info({ name: state.name, pid: proc.pid }, 'train: spawned');
+      const pumpFailed = (err: unknown): void => {
+        log.warn({ name: state.name, err: errMsg(err) }, 'train: pump failed');
+      };
+      this.pumpStdout(state).catch(pumpFailed);
+      this.pumpStderr(state).catch(pumpFailed);
+      proc.exited
+        .then((code) => {
+          this.onExit(state, code ?? 0);
+        })
+        .catch((err: unknown) => {
+          log.error(
+            { name: state.name, err: errMsg(err) },
+            'train: exit handler failed',
+          );
+        });
+    } catch (err) {
+      log.warn({ name: state.name, err: errMsg(err) }, 'train: spawn failed');
+      this.scheduleRestart(state);
+    }
+  }
+
+  private pumpStdout(state: TrainState): Promise<void> {
+    return pumpStream(state.proc?.stdout, state.name, 'stdout', (chunk) => {
+      state.buf += chunk;
+      state.buf = drainLines(state.name, state.buf, (line) => {
+        this.handleLine(state, line);
+      });
+    });
+  }
+
+  private pumpStderr(state: TrainState): Promise<void> {
+    return pumpStream(state.proc?.stderr, state.name, 'stderr', (chunk) => {
+      state.errBuf += chunk;
+      state.errBuf = drainLines(state.name, state.errBuf, (line) => {
+        log.warn({ train: state.name }, line);
+      });
+    });
+  }
+
+  private handleLine(state: TrainState, line: string): void {
+    const msg = parseTrainLine(state.name, line);
+    if (!msg || msg.op === 'ignore') return;
+    if (msg.op === 'response') {
+      const pending = state.pending.get(msg.id);
+      if (!pending) {
+        log.debug({ name: state.name, id: msg.id }, 'train: stale response');
+        return;
+      }
+      state.pending.delete(msg.id);
+      clearTimeout(pending.timer);
+      pending.resolve({
+        result: msg.result,
+        error: msg.error,
+        errorInfo: msg.errorInfo,
+      });
+      return;
+    }
+    if (msg.op === 'log') {
+      log.info({ name: state.name, msg: msg.text }, 'train log');
+      return;
+    }
+    this.onEvent?.(msg.event, state.name);
+  }
+
+  private onExit(state: TrainState, code: number): void {
+    log.warn({ name: state.name, code }, 'train: exited');
+    state.proc = null;
+    state.startedAt = null;
+    failAllPending(
+      state.pending,
+      `train '${state.name}' exited (code=${code}) before responding`,
+    );
+    if (state.stopped) return;
+    state.failCount++;
+    if (state.failCount >= MAX_CONSECUTIVE_FAILS) {
+      log.error(
+        { name: state.name, fails: state.failCount },
+        'train: too many consecutive failures, giving up (restart metro to retry)',
+      );
+      return;
+    }
+    this.scheduleRestart(state);
+  }
+
+  private scheduleRestart(state: TrainState): void {
+    if (state.stopped) return;
+    const idx = Math.min(state.failCount, RESTART_BACKOFFS_MS.length - 1);
+    const delay = RESTART_BACKOFFS_MS[idx];
+    log.info(
+      { name: state.name, delay, attempt: state.failCount },
+      'train: restart scheduled',
+    );
+    state.restartTimer = setTimeout(() => {
+      state.restartTimer = null;
+      this.spawn(state);
+      setTimeout(() => {
+        if (state.proc?.exitCode === null) state.failCount = 0;
+      }, 30_000);
+    }, delay);
+  }
+}

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

@@ -0,0 +1,22 @@
+import type { TrainCallResponse } from './protocol.js';
+
+export type TrainCallBackend = (
+  train: string,
+  action: string,
+  args: unknown,
+) => Promise<TrainCallResponse>;
+
+let backend: TrainCallBackend | null = null;
+
+export function setTrainCallBackend(fn: TrainCallBackend): void {
+  backend = fn;
+}
+
+export function forwardTrainCall(
+  train: string,
+  action: string,
+  args: unknown,
+): Promise<TrainCallResponse> {
+  if (!backend) throw new Error('train-call backend not wired');
+  return backend(train, action, args);
+}

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

@@ -0,0 +1,53 @@
+export interface TrainErrorInfo {
+  code: string;
+  message: string;
+  retryable?: boolean;
+  retryAfterMs?: number;
+}
+
+export class TrainError extends Error {
+  readonly code: string;
+  readonly retryable?: boolean;
+  readonly retryAfterMs?: number;
+  constructor(
+    code: string,
+    message: string,
+    opts?: { retryable?: boolean; retryAfterMs?: number },
+  ) {
+    super(message);
+    this.name = 'TrainError';
+    this.code = code;
+    this.retryable = opts?.retryable;
+    this.retryAfterMs = opts?.retryAfterMs;
+  }
+  toErrorInfo(): TrainErrorInfo {
+    return {
+      code: this.code,
+      message: this.message,
+      ...(this.retryable !== undefined ? { retryable: this.retryable } : {}),
+      ...(this.retryAfterMs !== undefined
+        ? { retryAfterMs: this.retryAfterMs }
+        : {}),
+    };
+  }
+}
+
+export function serializeTrainError(err: unknown): {
+  error: string;
+  errorInfo?: TrainErrorInfo;
+} {
+  if (err instanceof TrainError)
+    return { error: err.message, errorInfo: err.toErrorInfo() };
+  return { error: err instanceof Error ? err.message : String(err) };
+}
+
+export function coerceErrorInfo(v: unknown): TrainErrorInfo | undefined {
+  if (!v || typeof v !== 'object') return undefined;
+  const o = v as Record<string, unknown>;
+  if (typeof o.code !== 'string' || typeof o.message !== 'string')
+    return undefined;
+  const info: TrainErrorInfo = { code: o.code, message: o.message };
+  if (typeof o.retryable === 'boolean') info.retryable = o.retryable;
+  if (typeof o.retryAfterMs === 'number') info.retryAfterMs = o.retryAfterMs;
+  return info;
+}