@stage-labs/metro 0.1.0-beta.16 → 0.1.0-beta.161

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

@@ -0,0 +1,185 @@
+import { existsSync, readdirSync, readFileSync, renameSync, rmdirSync } from 'node:fs';
+import { log } from '@metro-labs/core/log';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { AGENT_NAME_RE, ID_RE } from '@metro-labs/core/ids';
+import { STATIONS, type StationName } from '@metro-labs/core/station-names';
+import type { LoadedAccount, LoadedAgent, StationSource } from '../stations/materialize.js';
+import { isRecord } from '@metro-labs/core/is-record';
+
+export const AGENT_FILE = 'agent.json';
+
+const KEY_RE = /^[A-Za-z0-9_-]{16,128}$/;
+const STATION_NAMES = new Set<string>(STATIONS);
+
+export class AgentFileError extends Error {}
+
+export interface AgentFile {
+  version: 1;
+  id: string;
+  name: string | null;
+  key: string | null;
+  owner: string | null;
+  stations: LoadedAccount[];
+  connectors: string[];
+}
+
+export const agentFilePath = (dir = agentsDir()): string => join(dir, AGENT_FILE);
+
+export function agentsDir(): string {
+  const explicit = process.env.METRO_AGENTS_DIR?.trim();
+  return explicit !== undefined && explicit !== ''
+    ? explicit
+    : join(homedir(), '.metro', 'agents');
+}
+
+const OWNER_RE = /^(0x[0-9a-f]{40}|org_[A-Za-z0-9]{10,64})$/;
+
+function fail(path: string, reason: string): never {
+  throw new AgentFileError(`${path}: ${reason}`);
+}
+
+function isStationName(value: unknown): value is StationName {
+  return typeof value === 'string' && STATION_NAMES.has(value);
+}
+
+function allowlistOf(raw: unknown, path: string, where: string): string[] | null {
+  if (raw === null || raw === undefined) return null;
+  if (!Array.isArray(raw)) fail(path, `${where}.allowlist is not a list of strings`);
+  const list = raw.filter((entry): entry is string => typeof entry === 'string');
+  if (list.length !== raw.length)
+    fail(path, `${where}.allowlist is not a list of strings`);
+  return list;
+}
+
+function stationOf(raw: unknown, path: string, index: number): LoadedAccount {
+  const where = `stations[${String(index)}]`;
+  if (!isRecord(raw)) fail(path, `${where} is not an object`);
+  const { station, id, config } = raw;
+  if (!isStationName(station)) fail(path, `${where}.station is not a known station`);
+  if (typeof id !== 'string' || !ID_RE.test(id))
+    fail(path, `${where}.id is not an 11-character id`);
+  if (!isRecord(config)) fail(path, `${where}.config is not an object`);
+  return { station, id, allowlist: allowlistOf(raw.allowlist, path, where), enabled: raw.enabled !== false, config };
+}
+
+function optionalMatch(
+  value: unknown,
+  re: RegExp,
+  path: string,
+  what: string,
+): string | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value !== 'string' || !re.test(value)) fail(path, what);
+  return value;
+}
+
+const connectorsOf = (raw: unknown): string[] =>
+  Array.isArray(raw) ? raw.filter((id): id is string => typeof id === 'string' && ID_RE.test(id)) : [];
+
+function nameOf(raw: unknown, path: string): string | null {
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw !== 'string' || !AGENT_NAME_RE.test(raw)) fail(path, 'name is not a valid agent name');
+  return raw;
+}
+
+export function parseAgentFile(raw: string, path: string): AgentFile {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    fail(path, 'is not valid JSON');
+  }
+  if (!isRecord(parsed)) fail(path, 'is not a JSON object');
+  if (parsed.version !== 1) fail(path, 'version must be 1');
+  const { id, name, stations } = parsed;
+  if (typeof id !== 'string' || !ID_RE.test(id))
+    fail(path, 'id is not an 11-character id');
+  const label = nameOf(name, path);
+  const key = optionalMatch(parsed.key, KEY_RE, path, 'key is not an agent key');
+  const owner = optionalMatch(
+    parsed.owner,
+    OWNER_RE,
+    path,
+    'owner is neither an organization id nor a lowercase Ethereum address',
+  );
+  if (!Array.isArray(stations)) fail(path, 'stations is not a list');
+  return {
+    version: 1,
+    id,
+    name: label,
+    key,
+    owner,
+    stations: stations.map((s, i) => stationOf(s, path, i)),
+    connectors: connectorsOf(parsed.connectors),
+  };
+}
+
+export function readAgentFile(path: string): AgentFile {
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch {
+    fail(path, 'cannot be read');
+  }
+  return parseAgentFile(raw, path);
+}
+
+function legacyAgentFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(dir, entry.name, AGENT_FILE))
+    .filter((path) => existsSync(path))
+    .sort();
+}
+
+export function listAgentFiles(dir = agentsDir()): string[] {
+  const fixed = agentFilePath(dir);
+  return existsSync(fixed) ? [fixed] : legacyAgentFiles(dir);
+}
+
+export function migrateAgentLayout(dir = agentsDir()): 'moved' | 'kept' | 'none' {
+  const fixed = agentFilePath(dir);
+  if (existsSync(fixed)) return 'kept';
+  const [first, ...rest] = legacyAgentFiles(dir);
+  if (first === undefined) return 'none';
+  renameSync(first, fixed);
+  try {
+    rmdirSync(join(first, '..'));
+  } catch {
+    log.warn({ folder: join(first, '..') }, 'agent layout: the old agent folder is not empty and was left in place');
+  }
+  for (const extra of rest) log.warn({ path: extra }, 'agent layout: a second agent file is ignored; a box holds one agent');
+  log.info({ from: first, to: fixed }, 'agent layout: moved the agent file to its fixed place');
+  return 'moved';
+}
+
+function assertUnique(agents: AgentFile[], paths: string[]): void {
+  const ids = new Map<string, string>();
+  const keys = new Map<string, string>();
+  agents.forEach((agent, i) => {
+    const path = paths[i] ?? '';
+    const sameId = ids.get(agent.id);
+    if (sameId !== undefined) fail(path, `id ${agent.id} is already used by ${sameId}`);
+    ids.set(agent.id, path);
+    if (agent.key === null) return;
+    const sameKey = keys.get(agent.key);
+    if (sameKey !== undefined) fail(path, `its key is already used by ${sameKey}`);
+    keys.set(agent.key, path);
+  });
+}
+
+export function loadFileAgents(dir = agentsDir()): LoadedAgent[] {
+  const paths = listAgentFiles(dir);
+  const agents = paths.map(readAgentFile);
+  assertUnique(agents, paths);
+  return agents.map((agent) => ({
+    id: agent.id,
+    name: agent.name ?? agent.id,
+    key: agent.key,
+    accounts: agent.stations,
+  }));
+}
+
+export const fileSource: StationSource = () => Promise.resolve(loadFileAgents());

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

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto';
+import { ID_RE } from '@metro-labs/core/ids';
+
+const digest = (token: string): string =>
+  createHash('sha256').update(token).digest('hex');
+
+let agentIdByKeyHash = new Map<string, string>();
+
+export interface KeyOwner {
+  key: string;
+  agentId: string;
+}
+
+const usable = (e: KeyOwner): boolean =>
+  e.key !== '' && ID_RE.test(e.agentId);
+
+export function setKeyMap(entries: KeyOwner[]): void {
+  agentIdByKeyHash = new Map(
+    entries.filter(usable).map((e) => [digest(e.key), e.agentId]),
+  );
+}
+
+export function registerKey(key: string, agentId: string): void {
+  if (!usable({ key, agentId })) return;
+  agentIdByKeyHash.set(digest(key), agentId);
+}
+
+export function unregisterAgentKey(agentId: string): void {
+  for (const [hash, id] of agentIdByKeyHash)
+    if (id === agentId) agentIdByKeyHash.delete(hash);
+}
+
+export function agentIdForKey(token: string): string | undefined {
+  if (token === '') return undefined;
+  return agentIdByKeyHash.get(digest(token));
+}
+
+export function hasAnyKey(): boolean {
+  return agentIdByKeyHash.size > 0;
+}

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

@@ -0,0 +1,95 @@
+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 = {};
+let disabledAccounts = new Set<string>();
+
+export function setAgentMap(map: AgentMap, names: AgentNameMap): void {
+  agentMap = map;
+  agentNames = names;
+}
+
+export function setAllowlistMap(map: AllowlistMap): void {
+  allowlistMap = map;
+}
+
+export function setDisabledAccounts(ids: Set<string>): void {
+  disabledAccounts = ids;
+}
+
+export const accountEnabled = (station: string, accountId: string): boolean => !disabledAccounts.has(mapKey(station, accountId));
+
+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 allowlistForAccount(station: string, accountId: string): string[] | undefined {
+  return allowlistMap[mapKey(station, accountId)];
+}
+
+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/agents/senders.ts

@@ -0,0 +1,38 @@
+import { bufferedSince, type MetroEvent } from '@metro-labs/core/events';
+import { accountFromLine } from './map.js';
+
+export interface RecentSender {
+  id: string;
+  name: string;
+  at: string;
+}
+
+const DEFAULT_LIMIT = 20;
+
+const SKIP = new Set(['', 'self', 'unknown']);
+
+function sameAccount(from: string, station: string, accountId: string): boolean {
+  const account = accountFromLine(from);
+  return account?.station === station && account.accountId === accountId;
+}
+
+function senderOf(event: MetroEvent, station: string, accountId: string): { id: string; name: string } | null {
+  const from = String(event.from);
+  if (event.station !== station || !sameAccount(from, station, accountId)) return null;
+  const id = from.split('/').pop() ?? '';
+  if (SKIP.has(id)) return null;
+  return { id, name: event.fromDisplayName ?? event.fromName ?? '' };
+}
+
+export function recentSenders(station: string, accountId: string, limit = DEFAULT_LIMIT): RecentSender[] {
+  const seen = new Set<string>();
+  const out: RecentSender[] = [];
+  for (const { event } of bufferedSince(0).reverse()) {
+    const sender = senderOf(event, station, accountId);
+    if (sender === null || seen.has(sender.id.toLowerCase())) continue;
+    seen.add(sender.id.toLowerCase());
+    out.push({ ...sender, at: event.ts });
+    if (out.length >= limit) break;
+  }
+  return out;
+}

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

@@ -0,0 +1,200 @@
+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 { agentsDir, fileSource } from '../agents/files.js';
+import { syncPluginServers } from '../connectors/plugin-sync.js';
+import { readLocalConnectors } from '../connectors/store.js';
+import { ensureMetroPlugin } from '../claude/plugin-install.js';
+import { unwatchSession, watchSession } from '../claude/session.js';
+import { tryClaudeSetup } from '../claude/setup.js';
+import { applyLocalOwner } from './local-owner.js';
+import { installBearerSessions } from '../routes/bearer.js';
+import { ensureLocalAgent, localOwner } from '../agents/file-admin.js';
+import { migrateAgentLayout } from '../agents/files.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,
+  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,
+      reloadAgents: async () => {
+        await reloadFrom(fileSource);
+      },
+      restart: () => {
+        exitCode = RESTART_EXIT;
+        onShutdown();
+      },
+      stop: () => {
+        exitCode = HOLD_EXIT;
+        onShutdown();
+      },
+      gatherAccounts: gatherAccountsForAgents,
+      capabilities: accountStationCapabilities,
+      liveness: agentLiveness,
+      prepareAccount,
+    });
+}
+
+
+async function main(): Promise<void> {
+  applyLocalOwner();
+installBearerSessions(agentsDir(), localOwner);
+  migrateAgentLayout();
+  log.info({ agent: await ensureLocalAgent() }, 'local daemon: agent');
+  await materializeFrom(fileSource, { allowEmpty: true });
+  supervisor.start();
+  const metroMcp = await createMetroMcp();
+  webhookServer = await startWebhookServer(
+    emit,
+    sessionApis(),
+    metroMcp.httpHandler,
+    metroCall,
+  );
+  metroMcp.startInbound();
+  syncPluginServers(readLocalConnectors());
+  startUploadReaper();
+  announceLocalEndpoint();
+  tunnel?.start();
+  log.info(
+    { tunnel: !!tunnel, trainsDir: trainsDir(), mcp: '/', version: METRO_VERSION },
+    'dispatcher ready',
+  );
+  markDaemonReady();
+  ensureMetroPlugin()
+    .then((outcome) => {
+      log.info({ outcome }, 'plugin: metro plugin for Claude Code');
+      if (outcome !== 'skipped') syncPluginServers(readLocalConnectors());
+    })
+    .catch((err: unknown) => {
+      log.warn({ err: errMsg(err) }, 'plugin: could not ensure the Claude Code plugin');
+    });
+  tryClaudeSetup();
+  watchSession();
+}
+
+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');
+  unwatchSession();
+  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';