@stage-labs/metro 0.1.0-beta.8 → 0.1.0-beta.80

package/runtime/node_modules/@metro-labs/daemon/src/agents/map.ts

@@ -0,0 +1,84 @@
+export type AgentMap = Record<string, string>;
+export type AgentNameMap = Record<string, string>;
+export type AllowlistMap = Record<string, string[]>;
+
+const mapKey = (station: string, accountId: string): string =>
+  `${station}/${accountId}`;
+
+let agentMap: AgentMap = {};
+let agentNames: AgentNameMap = {};
+let allowlistMap: AllowlistMap = {};
+
+export function setAgentMap(map: AgentMap, names: AgentNameMap): void {
+  agentMap = map;
+  agentNames = names;
+}
+
+export function setAllowlistMap(map: AllowlistMap): void {
+  allowlistMap = map;
+}
+
+export function accountFromLine(
+  line: string,
+): { station: string; accountId: string } | undefined {
+  const parts = line.split('/');
+  const station = parts[2];
+  const accountId = parts[3];
+  if (!station || !accountId) return undefined;
+  return { station, accountId };
+}
+
+export function agentIdForAccount(
+  station: string,
+  accountId: string,
+): string | undefined {
+  return agentMap[mapKey(station, accountId)];
+}
+
+export function agentIdForLine(line: string): string | undefined {
+  const a = accountFromLine(line);
+  return a ? agentIdForAccount(a.station, a.accountId) : undefined;
+}
+
+export function agentForLine(line: string): string | undefined {
+  const id = agentIdForLine(line);
+  return id === undefined ? undefined : agentNames[id];
+}
+
+export interface KnownAccount {
+  station: string;
+  id: string;
+  agentId: string;
+}
+
+export function knownAccounts(): KnownAccount[] {
+  return Object.entries(agentMap).flatMap(([key, agentId]) => {
+    const cut = key.indexOf('/');
+    return cut === -1 ? [] : [{ station: key.slice(0, cut), id: key.slice(cut + 1), agentId }];
+  });
+}
+
+export function stationAgentIds(station: string): string[] {
+  const prefix = `${station}/`;
+  return Object.entries(agentMap)
+    .filter(([key]) => key.startsWith(prefix))
+    .map(([, id]) => id);
+}
+
+export function allowlistForLine(line: string): string[] | undefined {
+  const a = accountFromLine(line);
+  return a ? allowlistMap[mapKey(a.station, a.accountId)] : undefined;
+}
+
+export function senderMatchesAllowlist(
+  allowlist: string[],
+  from: string,
+): boolean {
+  if (allowlist.length === 0 || allowlist.includes('*')) return true;
+  const f = (from ?? '').toLowerCase();
+  const id = f.split('/').pop() ?? f;
+  return allowlist.some((a) => {
+    const v = a.toLowerCase();
+    return v === f || v === id;
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/agents/scope.ts

@@ -0,0 +1,64 @@
+import {
+  accountFromLine,
+  agentIdForAccount,
+  stationAgentIds,
+} from './map.js';
+import { STATIONS } from '@metro-labs/core/station-names';
+
+const ACCOUNT_STATIONS = new Set<string>(STATIONS);
+
+const stationHasAccounts = (station: string): boolean =>
+  ACCOUNT_STATIONS.has(station);
+
+const accountInScope = (
+  allowed: Set<string>,
+  station: string,
+  accountId: string,
+): boolean => {
+  const agentId = agentIdForAccount(station, accountId);
+  return agentId !== undefined && allowed.has(agentId);
+};
+
+export function lineTargetDenied(
+  allowed: Set<string>,
+  args: Record<string, unknown>,
+  station?: string,
+): boolean {
+  const line = typeof args.line === 'string' ? args.line : undefined;
+  if (line === undefined) return false;
+  const acct = accountFromLine(line);
+  if (!acct) return true;
+  if (station !== undefined && acct.station !== station) return true;
+  if (!accountInScope(allowed, acct.station, acct.accountId)) return true;
+  const override = typeof args.account === 'string' ? args.account : undefined;
+  return override !== undefined
+    ? !accountInScope(allowed, acct.station, override)
+    : false;
+}
+
+export function stationFullyScoped(
+  allowed: Set<string>,
+  station: string,
+): boolean {
+  const ids = stationAgentIds(station);
+  return ids.length > 0 && ids.every((id) => allowed.has(id));
+}
+
+export function callTargetDenied(
+  allowed: Set<string>,
+  station: string,
+  args: Record<string, unknown>,
+): boolean {
+  if (typeof args.line === 'string')
+    return lineTargetDenied(allowed, args, station);
+  if (typeof args.account === 'string')
+    return !accountInScope(allowed, station, args.account);
+  return !stationFullyScoped(allowed, station);
+}
+
+export function eventInScope(allowed: Set<string>, line: string): boolean {
+  const acct = accountFromLine(line);
+  if (!acct) return false;
+  if (!stationHasAccounts(acct.station)) return true;
+  return accountInScope(allowed, acct.station, acct.accountId);
+}

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

@@ -0,0 +1,176 @@
+import { join } from 'node:path';
+import { type Server } from 'node:http';
+import { userSelf } from '@metro-labs/core/events';
+import { setTrainCallBackend } from '../stations/train-call.js';
+import { errMsg, log, logFatalSync } from '@metro-labs/core/log';
+import { acquireLock, STATE_DIR, trainsDir } from './paths.js';
+import { installCrashGuard, markDaemonReady } from './crash-guard.js';
+import { METRO_VERSION } from '@metro-labs/core/version';
+import { funnelDriver, Tunnel, tunnelWanted, webhookPort } from '../net/tunnel.js';
+import {
+  localConnectHint,
+  publicConnectHint,
+  tunnelPendingHint,
+} from './connect-hint.js';
+import { TrainSupervisor } from '../stations/supervisor.js';
+import {
+  makeEmit,
+  startWebhookServer,
+  trainEventToMetroEvent,
+} from '../routes/http.js';
+import { localAgentKey } from '../stations/materialize.js';
+import { fileSource } from '../agents/files.js';
+import { applyLocalOwner } from './local-owner.js';
+import { localOwner } from '../agents/file-admin.js';
+import { ensureStationDeps } from '../stations/runtime-deps.js';
+import { localSessionApis } from '../routes/local-mode.js';
+import type { SessionApis } from '../routes/session-apis.js';
+import {
+  agentLiveness,
+  closeAgentSession,
+  createMetroMcp,
+} from '../mcp/index.js';
+import { metroCall } from '../mcp/ctx.js';
+import { gatherAccountsForAgents } from '../mcp/accounts.js';
+import {
+  accountStationCapabilities,
+  stationByName,
+} from '../stations/registry.js';
+import { prepareAccount } from '../stations/attach.js';
+import { materializeFrom, reloadFrom } from '../stations/materialize.js';
+import type { StationName } from '@metro-labs/core/station-names';
+import { startUploadReaper } from '../files/upload-store.js';
+
+installCrashGuard();
+acquireLock(join(STATE_DIR, '.tail-lock'));
+
+log.info({ self: userSelf() }, 'user identity');
+
+process.stdout.on('error', (err) => {
+  if ((err as NodeJS.ErrnoException).code !== 'EPIPE')
+    log.warn({ err: errMsg(err) }, 'stdout error');
+});
+
+const supervisor = new TrainSupervisor();
+const emit = makeEmit();
+
+supervisor.onTrainEvent((env, train) => {
+  const entry = trainEventToMetroEvent(env, train);
+  if (entry) emit(entry);
+});
+
+let webhookServer: Server | null = null;
+const tunnel = tunnelWanted() ? new Tunnel(funnelDriver(webhookPort()), announcePublic) : null;
+
+function announcePublic(url: string): void {
+  process.stderr.write(`\n${publicConnectHint(url, localOwner())}`);
+}
+
+setTrainCallBackend((train, action, args) =>
+  supervisor.call(train, action, args),
+);
+
+function announceLocalEndpoint(): void {
+  process.stderr.write(
+    `\n${tunnel === null ? localConnectHint(webhookPort(), localOwner()) : tunnelPendingHint()}`,
+  );
+  const key = localAgentKey();
+  if (key === null) {
+    log.info('no agent on this machine yet');
+    return;
+  }
+  const url = `http://127.0.0.1:${String(webhookPort())}/mcp?token=${key}`;
+  process.stderr.write(
+    `\nConnect an agent on this machine:\n\n  claude mcp add --transport http metro "${url}"\n\n`,
+  );
+}
+
+async function syncStations(station: StationName): Promise<void> {
+  const { removed } = await reloadFrom(fileSource);
+  if (stationByName(station)?.hasTrain === false) return;
+  if (removed.includes(station)) await supervisor.stopTrain(station);
+  else {
+    ensureStationDeps(station);
+    supervisor.requestReload(station);
+  }
+}
+
+function sessionApis(): SessionApis {
+  return localSessionApis({
+      syncStations,
+      restart: () => {
+        exitCode = RESTART_EXIT;
+        onShutdown();
+      },
+      stop: () => {
+        exitCode = HOLD_EXIT;
+        onShutdown();
+      },
+      closeAgentSession,
+      gatherAccounts: gatherAccountsForAgents,
+      capabilities: accountStationCapabilities,
+      liveness: agentLiveness,
+      prepareAccount,
+    });
+}
+
+async function main(): Promise<void> {
+  applyLocalOwner();
+  await materializeFrom(fileSource, { allowEmpty: true });
+  supervisor.start();
+  const metroMcp = await createMetroMcp();
+  webhookServer = await startWebhookServer(
+    emit,
+    sessionApis(),
+    metroMcp.httpHandler,
+    metroCall,
+  );
+  metroMcp.startInbound();
+  startUploadReaper();
+  announceLocalEndpoint();
+  tunnel?.start();
+  log.info(
+    { tunnel: !!tunnel, trainsDir: trainsDir(), mcp: '/', version: METRO_VERSION },
+    'dispatcher ready',
+  );
+  markDaemonReady();
+}
+
+const SHUTDOWN_TIMEOUT_MS = 3_000;
+const RESTART_EXIT = 75;
+const HOLD_EXIT = 76;
+let exitCode = 0;
+let shuttingDown = false;
+async function shutdown(): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  log.info('dispatcher shutting down');
+  tunnel?.stop();
+  if (webhookServer) {
+    const server = webhookServer;
+    await Promise.race([
+      new Promise<void>((r) => {
+        server.close(() => {
+          r();
+        });
+      }),
+      new Promise<void>((r) => {
+        setTimeout(r, SHUTDOWN_TIMEOUT_MS).unref();
+      }),
+    ]);
+  }
+  await supervisor.stop();
+  process.exit(exitCode);
+}
+const onShutdown = (): void => {
+  shutdown().catch((err: unknown) => {
+    log.error({ err: errMsg(err) }, 'dispatcher: shutdown failed');
+    process.exit(1);
+  });
+};
+for (const sig of ['SIGINT', 'SIGTERM'] as const) process.on(sig, onShutdown);
+
+await main().catch((err: unknown) => {
+  logFatalSync({ err: errMsg(err) }, 'dispatcher failed to start');
+  process.exit(1);
+});

package/runtime/node_modules/@metro-labs/daemon/src/boot/connect-hint.ts

@@ -0,0 +1,39 @@
+import { hostname } from 'node:os';
+
+const uiBase = (): string => process.env.METRO_UI_URL ?? 'https://metro.box';
+
+const connectLink = (base: string): string =>
+  `${uiBase()}/#/${new URL(base).host}`;
+
+const ownerLine = (owner: string | null): string =>
+  owner === null
+    ? 'No owner is set, so no wallet can sign in. Restart with:  metro serve --owner <address>'
+    : `Only ${owner} can sign in.`;
+
+export function localConnectHint(port: number, owner: string | null): string {
+  const here = `http://127.0.0.1:${String(port)}`;
+  const forward = `ssh -L ${String(port)}:127.0.0.1:${String(port)} ${hostname()}`;
+  return [
+    'Manage this machine from the web UI:',
+    '',
+    `  ${connectLink(here)}`,
+    '',
+    `From another computer, forward the port first:  ${forward}`,
+    ownerLine(owner),
+    '',
+  ].join('\n');
+}
+
+export function publicConnectHint(url: string, owner: string | null): string {
+  return [
+    'Manage this machine from the web UI, from anywhere:',
+    '',
+    `  ${connectLink(url)}`,
+    '',
+    ownerLine(owner),
+    '',
+  ].join('\n');
+}
+
+export const tunnelPendingHint = (): string =>
+  'Publishing this daemon through Tailscale Funnel… (if Tailscale asks to enable Funnel, its link is in the log)\n';

package/runtime/node_modules/@metro-labs/daemon/src/boot/crash-guard.ts

@@ -0,0 +1,49 @@
+import { errMsg, log, logFatalSync } from '@metro-labs/core/log';
+
+export type CrashKind = 'unhandledRejection' | 'uncaughtException';
+
+const seen: Record<CrashKind, number> = {
+  unhandledRejection: 0,
+  uncaughtException: 0,
+};
+
+let ready = false;
+let installed = false;
+
+export function markDaemonReady(): void {
+  ready = true;
+}
+
+export function crashCount(kind: CrashKind): number {
+  return seen[kind];
+}
+
+function fields(kind: CrashKind, err: unknown): Record<string, unknown> {
+  return {
+    crash: kind,
+    seen: seen[kind],
+    err: errMsg(err),
+    errType: err instanceof Error ? err.name : typeof err,
+    stack: err instanceof Error ? err.stack : undefined,
+  };
+}
+
+function reportCrash(kind: CrashKind, err: unknown): void {
+  seen[kind] += 1;
+  if (!ready) {
+    logFatalSync(fields(kind, err), 'daemon: failed before it was ready');
+    process.exit(1);
+  }
+  log.error(fields(kind, err), 'daemon: kept running through a crash');
+}
+
+export function installCrashGuard(): void {
+  if (installed) return;
+  installed = true;
+  process.on('unhandledRejection', (reason: unknown) => {
+    reportCrash('unhandledRejection', reason);
+  });
+  process.on('uncaughtException', (err: unknown) => {
+    reportCrash('uncaughtException', err);
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/boot/local-owner.ts

@@ -0,0 +1,14 @@
+import { localOwner, setLocalOwner } from '../agents/file-admin.js';
+import { log } from '@metro-labs/core/log';
+
+export function applyLocalOwner(): string | null {
+  const wanted = process.env.METRO_OWNER?.trim() ?? '';
+  if (wanted !== '') {
+    const address = setLocalOwner(wanted);
+    log.info({ owner: address }, 'local daemon: owner set from METRO_OWNER');
+    return address;
+  }
+  const stored = localOwner();
+  if (stored === null) log.warn('local daemon: no owner set, so no wallet can sign in; restart with metro serve --owner <address>');
+  return stored;
+}

package/runtime/node_modules/@metro-labs/daemon/src/boot/paths.ts

@@ -0,0 +1,106 @@
+import { execFileSync } from 'node:child_process';
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { log } from '@metro-labs/core/log';
+
+export const STATE_DIR =
+  process.env.METRO_STATE_DIR ?? join(homedir(), '.cache', 'metro');
+mkdirSync(STATE_DIR, { recursive: true });
+
+
+export function trainsDir(): string {
+  const env = process.env.METRO_TRAINS_DIR?.trim();
+  if (env !== undefined && env !== '') return env;
+  return fileURLToPath(new URL('../../trains', import.meta.url));
+}
+
+function readLockPid(lockFile: string): number {
+  try {
+    return Number(readFileSync(lockFile, 'utf8').trim());
+  } catch {
+    return NaN;
+  }
+}
+
+function namesMetro(text: string): boolean {
+  return text.includes('server.ts') || text.includes('metro');
+}
+
+function holderIsMetro(pid: number): boolean {
+  try {
+    return namesMetro(readFileSync(`/proc/${pid}/cmdline`, 'utf8'));
+  } catch {
+    return holderCommand(pid);
+  }
+}
+
+function holderCommand(pid: number): boolean {
+  try {
+    return namesMetro(
+      execFileSync('ps', ['-o', 'command=', '-p', String(pid)], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }),
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function lockHeldByLiveDaemon(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) return false;
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return false;
+  }
+  return holderIsMetro(pid);
+}
+
+function writeOwnLock(lockFile: string): void {
+  const fd = openSync(lockFile, 'wx');
+  writeSync(fd, String(process.pid));
+  closeSync(fd);
+  process.on('exit', () => {
+    try {
+      if (readFileSync(lockFile, 'utf8').trim() === String(process.pid))
+        unlinkSync(lockFile);
+    } catch {
+    }
+  });
+}
+
+export function acquireLock(lockFile: string): void {
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      writeOwnLock(lockFile);
+      return;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+      const pid = readLockPid(lockFile);
+      if (lockHeldByLiveDaemon(pid)) {
+        log.info(
+          { pid },
+          'a healthy `metro` daemon is already running; exiting (no second dispatcher)',
+        );
+        process.exit(0);
+      }
+      try {
+        unlinkSync(lockFile);
+      } catch {
+      }
+    }
+  }
+  throw new Error(
+    `metro: could not acquire dispatcher lock (${lockFile}) after retries`,
+  );
+}

package/runtime/node_modules/@metro-labs/daemon/src/channels/addressed.ts

@@ -0,0 +1,25 @@
+import { str } from '@metro-labs/core/str';
+
+export type Addressed = 'direct' | 'mention' | 'reply';
+
+interface AddressFacts {
+  isPrivate?: unknown;
+  mentionsSelf?: unknown;
+  replyToSelf?: unknown;
+}
+
+export function addressedBy(facts: AddressFacts, replyTo: string, sent: ReadonlySet<string>): Addressed | undefined {
+  if (facts.isPrivate === true) return 'direct';
+  if (facts.mentionsSelf === true) return 'mention';
+  if (facts.replyToSelf === true || (replyTo !== '' && sent.has(replyTo))) return 'reply';
+  return undefined;
+}
+
+export function replyMeta(ev: Record<string, unknown>, sent: ReadonlySet<string>): Record<string, string> {
+  const replyTo = str(ev.replyTo);
+  const addressed = addressedBy(ev, replyTo, sent);
+  return {
+    ...(replyTo ? { reply_to: replyTo } : {}),
+    ...(addressed === undefined ? {} : { addressed }),
+  };
+}

package/runtime/node_modules/@metro-labs/daemon/src/channels/dedupe.ts

@@ -0,0 +1,24 @@
+import { accountFromLine, agentIdForAccount } from '../agents/map.js';
+
+const accountStrippedLine = (line: string): string => {
+  const parts = line.split('/');
+  if (parts.length < 5) return line;
+  return [parts[0], parts[1], parts[2], ...parts.slice(4)].join('/');
+};
+
+export const dedupeOwner = (line: string): string => {
+  const acct = accountFromLine(line);
+  if (!acct) return 'unowned';
+  const agentId = agentIdForAccount(acct.station, acct.accountId);
+  return agentId === undefined
+    ? `account:${acct.accountId}`
+    : `agent:${agentId}`;
+};
+
+export const dedupeKey = (
+  station: string,
+  line: string,
+  kind: string,
+  messageId: string,
+): string =>
+  `${dedupeOwner(line)} ${station} ${accountStrippedLine(line)} ${kind} ${messageId}`;