@stage-labs/metro 0.1.0-beta.20 → 0.1.0-beta.201

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/schedules.ts

@@ -0,0 +1,252 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg, log } from '@metro-labs/core/log';
+import { asUser, type AgentUser } from './user.js';
+import { metroRun, writeDropIn } from './unit-files.js';
+
+const UNIT_DIR = '/etc/systemd/system';
+const defaultBackups = (): string => join(homedir(), '.metro', 'agents');
+const DROP_IN = '10-metro-agent.conf';
+const OWN_UNITS = /^metro(-claude-\d+)?\.(service|scope)$/;
+
+export type JobKind = 'timer' | 'cron-root' | 'cron-agent';
+
+export interface ScheduledJob {
+  id: string;
+  kind: JobKind;
+  name: string;
+  schedule: string;
+  command: string;
+  runsAs: string;
+  next: string | null;
+  last: string | null;
+  lastResult: string | null;
+  usesRoot: boolean;
+  converted: boolean;
+  problem?: string | null;
+}
+
+export interface Runner {
+  run: (file: string, args: string[], input?: string) => { status: number | null; stdout: string };
+}
+
+export const realRunner: Runner = {
+  run: (file, args, input) => {
+    const viaHelper = metroRun(file, args, input);
+    if (viaHelper !== null) return viaHelper;
+    const done = spawnSync(file, args, { encoding: 'utf8', input, stdio: ['pipe', 'pipe', 'ignore'], timeout: 20_000 });
+    return { status: done.error === undefined ? done.status : null, stdout: done.stdout ?? '' };
+  },
+};
+
+const ROOT_RE = /(^|[\s="'=:])\/root(?=\/|$|[\s"';:])/;
+export const usesRootHome = (text: string): boolean => ROOT_RE.test(text);
+export const rehome = (text: string, home: string): string => text.replace(/(^|[\s="'=:])\/root(?=\/|$|[\s"';:])/g, `$1${home}`);
+
+const stamp = (micros: unknown): string | null =>
+  typeof micros === 'number' && micros > 0 ? new Date(micros / 1000).toISOString() : null;
+
+export function showProps(runner: Runner, unit: string, props: string[]): Record<string, string> {
+  const out = runner.run('systemctl', ['show', unit, '--no-pager', ...props.map((p) => `-p${p}`)]).stdout;
+  const found: Record<string, string> = {};
+  for (const line of out.split('\n')) {
+    const at = line.indexOf('=');
+    if (at > 0) found[line.slice(0, at)] = line.slice(at + 1);
+  }
+  return found;
+}
+
+export function execArgv(execStart: string): string[] {
+  const m = /argv\[\]=(.*?) ;/.exec(execStart);
+  return m?.[1] === undefined ? [] : m[1].split(' ').filter((a) => a !== '');
+}
+
+export const calendarOf = (timers: string): string =>
+  /OnCalendar=([^;]*?) ;/.exec(timers)?.[1]?.trim() ?? /(OnUnitActiveUSec|OnBootUSec|OnActiveUSec)=([^;]*?) ;/.exec(timers)?.[0]?.replace(/ ;$/, '') ?? '';
+
+function listTimers(runner: Runner): Record<string, unknown>[] {
+  try {
+    const raw: unknown = JSON.parse(runner.run('systemctl', ['list-timers', '--all', '--output=json', '--no-pager']).stdout);
+    return Array.isArray(raw) ? raw.filter(isRecord) : [];
+  } catch {
+    return [];
+  }
+}
+
+const text = (v: unknown): string => (typeof v === 'string' ? v : '');
+const orRoot = (user: string | undefined): string => (user === undefined || user === '' ? 'root' : user);
+
+function timerJob(runner: Runner, t: Record<string, unknown>): ScheduledJob | null {
+  const unit = text(t.unit);
+  const service = text(t.activates);
+  if (unit === '' || service === '' || OWN_UNITS.test(service)) return null;
+  const timer = showProps(runner, unit, ['FragmentPath', 'TimersCalendar', 'TimersMonotonic']);
+  if (!text(timer.FragmentPath).startsWith(`${UNIT_DIR}/`)) return null;
+  const svc = showProps(runner, service, ['ExecStart', 'User', 'Result', 'DropInPaths', 'Environment', 'WorkingDirectory']);
+  const command = execArgv(text(svc.ExecStart)).join(' ');
+  return {
+    id: `timer:${unit}`,
+    kind: 'timer',
+    name: unit.replace(/\.timer$/, ''),
+    schedule: calendarOf(`${text(timer.TimersCalendar)} ${text(timer.TimersMonotonic)}`),
+    command,
+    runsAs: orRoot(svc.User),
+    next: stamp(t.next),
+    last: stamp(t.last),
+    lastResult: svc.Result ?? null,
+    usesRoot: usesRootHome(`${command} ${text(svc.Environment)} ${text(svc.WorkingDirectory)}`),
+    converted: text(svc.DropInPaths).includes(DROP_IN),
+  };
+}
+
+const timerJobs = (runner: Runner): ScheduledJob[] =>
+  listTimers(runner).flatMap((t) => {
+    const job = timerJob(runner, t);
+    return job === null ? [] : [job];
+  });
+
+export interface CronLine {
+  schedule: string;
+  command: string;
+}
+
+export function parseCronLine(line: string): CronLine | null {
+  const text = line.trim();
+  if (text === '' || text.startsWith('#') || /^[A-Za-z_][A-Za-z0-9_]*=/.test(text)) return null;
+  if (text.startsWith('@')) {
+    const [at = '', ...rest] = text.split(/\s+/);
+    return rest.length === 0 ? null : { schedule: at, command: rest.join(' ') };
+  }
+  const parts = text.split(/\s+/);
+  if (parts.length < 6) return null;
+  return { schedule: parts.slice(0, 5).join(' '), command: parts.slice(5).join(' ') };
+}
+
+const lineId = (kind: JobKind, line: string): string => `${kind}:${createHash('sha256').update(line.trim()).digest('hex').slice(0, 16)}`;
+
+function crontabOf(runner: Runner, user: string): string[] {
+  const out = runner.run('crontab', ['-l', '-u', user]);
+  return out.status === 0 ? out.stdout.split('\n') : [];
+}
+
+function cronJobs(runner: Runner, user: string, kind: JobKind): ScheduledJob[] {
+  return crontabOf(runner, user).flatMap((line): ScheduledJob[] => {
+    const parsed = parseCronLine(line);
+    if (parsed === null) return [];
+    return [{
+      id: lineId(kind, line),
+      kind,
+      name: parsed.command.split(/\s+/)[0]?.split('/').pop() ?? 'cron',
+      schedule: parsed.schedule,
+      command: parsed.command,
+      runsAs: user,
+      next: null,
+      last: null,
+      lastResult: null,
+      usesRoot: usesRootHome(parsed.command),
+      converted: false,
+    }];
+  });
+}
+
+function allJobs(user: AgentUser | null, runner: Runner): ScheduledJob[] {
+  return [...timerJobs(runner), ...cronJobs(runner, 'root', 'cron-root'), ...(user === null ? [] : cronJobs(runner, user.name, 'cron-agent'))];
+}
+
+const quote = (arg: string): string => `"${arg.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+export function dropInText(user: AgentUser, argv: string[], environment: string): string {
+  const env = environment.split(' ').filter((pair) => pair.includes('=') && !pair.startsWith('HOME=') && !pair.startsWith('PATH='));
+  return [
+    '[Service]',
+    `User=${user.name}`,
+    `Group=${String(user.gid)}`,
+    `WorkingDirectory=${user.home}`,
+    `Environment=HOME=${user.home}`,
+    `Environment=PATH=${user.home}/.local/bin:/usr/local/bin:/usr/bin:/bin`,
+    ...env.map((pair) => `Environment=${quote(rehome(pair, user.home))}`),
+    'ExecStart=',
+    `ExecStart=${argv.map((a) => quote(rehome(a, user.home))).join(' ')}`,
+    '',
+  ].join('\n');
+}
+
+function agentSees(user: AgentUser, path: string): boolean {
+  if (existsSync(path)) return true;
+  const [file, args] = asUser(user, 'test', ['-e', path]);
+  return spawnSync(file, args, { stdio: 'ignore' }).status === 0;
+}
+
+function convertTimer(job: ScheduledJob, user: AgentUser, runner: Runner): void {
+  const unit = job.id.slice('timer:'.length);
+  const service = showProps(runner, unit, ['Unit']).Unit ?? unit.replace(/\.timer$/, '.service');
+  const svc = showProps(runner, service, ['ExecStart', 'Environment']);
+  const argv = execArgv(svc.ExecStart ?? '');
+  if (argv.length === 0) throw new ApiError('that timer runs no command metro can read', 400);
+  const missing = argv.map((a) => rehome(a, user.home)).find((a) => a.startsWith(`${user.home}/`) && !agentSees(user, a));
+  if (missing !== undefined) throw new ApiError(`${missing} does not exist; move it to the agent first`, 409);
+  writeDropIn(service, DROP_IN, dropInText(user, argv, svc.Environment ?? ''));
+  runner.run('systemctl', ['daemon-reload']);
+  log.info({ unit, service, user: user.name }, 'schedules: a timer now runs as the agent user');
+}
+
+function convertCron(job: ScheduledJob, user: AgentUser, backups: string, runner: Runner): void {
+  const lines = crontabOf(runner, 'root');
+  const line = lines.find((l) => lineId('cron-root', l) === job.id);
+  if (line === undefined) throw new ApiError('that cron line is gone', 404);
+  mkdirSync(backups, { recursive: true });
+  writeFileSync(join(backups, `crontab-root.${new Date().toISOString().replace(/[:.]/g, '-')}.bak`), lines.join('\n'), { mode: 0o600 });
+  const agentLines = crontabOf(runner, user.name).filter((l) => l !== '');
+  const moved = runner.run('crontab', ['-u', user.name, '-'], `${[...agentLines, rehome(line, user.home)].join('\n')}\n`);
+  if (moved.status !== 0) throw new ApiError("the agent's crontab refused the line", 500);
+  const kept = lines.filter((l) => l !== line && l !== '');
+  runner.run('crontab', ['-u', 'root', '-'], `${kept.join('\n')}\n`);
+  log.info({ user: user.name }, "schedules: a root cron line moved to the agent's crontab");
+}
+
+function toAgent(job: ScheduledJob, user: AgentUser, backups: string, runner: Runner): void {
+  if (job.kind === 'timer') convertTimer(job, user, runner);
+  else if (job.kind === 'cron-root') convertCron(job, user, backups, runner);
+  else throw new ApiError('that job already runs as the agent', 400);
+}
+
+const problems = new Map<string, string>();
+
+const needsAgent = (job: ScheduledJob): boolean => job.kind !== 'cron-agent' && job.runsAs === 'root' && job.usesRoot;
+
+function tryAgent(job: ScheduledJob, user: AgentUser, backups: string, runner: Runner): boolean {
+  try {
+    toAgent(job, user, backups, runner);
+    problems.delete(job.id);
+    return true;
+  } catch (err) {
+    problems.set(job.id, errMsg(err));
+    log.warn({ job: job.name, err: errMsg(err) }, 'schedules: a job still pointing into /root could not be switched to the agent user');
+    return false;
+  }
+}
+
+export function convertRootJobs(user: AgentUser | null, backups = defaultBackups(), runner: Runner = realRunner): number {
+  if (user === null) return 0;
+  const pending = allJobs(user, runner).filter(needsAgent);
+  return pending.filter((job) => tryAgent(job, user, backups, runner)).length;
+}
+
+export const listSchedules = (user: AgentUser | null, runner: Runner = realRunner): ScheduledJob[] =>
+  allJobs(user, runner)
+    .filter((job) => job.runsAs !== 'root' || job.usesRoot)
+    .map((job) => ({ ...job, problem: problems.get(job.id) ?? null }));
+
+export function retrySchedule(id: string, user: AgentUser | null, backups = defaultBackups(), runner: Runner = realRunner): ScheduledJob[] {
+  if (user === null) throw new ApiError('Claude Code does not run as its own user on this machine', 409);
+  const job = allJobs(user, runner).find((j) => j.id === id);
+  if (job === undefined) throw new ApiError('no such scheduled job', 404);
+  if (needsAgent(job)) toAgent(job, user, backups, runner);
+  problems.delete(id);
+  return listSchedules(user, runner);
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/unit-files.ts

@@ -0,0 +1,61 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { mustHelper, rootHelper, runningAsMetro } from '../metro-user/privilege.js';
+import { agentUser, asUser } from './user.js';
+
+const UNIT_DIR = '/etc/systemd/system';
+
+export function writeDropIn(service: string, name: string, text: string): void {
+  if (runningAsMetro()) {
+    mustHelper(['dropin-write', service, name], text);
+    return;
+  }
+  mkdirSync(join(UNIT_DIR, `${service}.d`), { recursive: true });
+  writeFileSync(join(UNIT_DIR, `${service}.d`, name), text, { mode: 0o644 });
+}
+
+export function removeDropIn(service: string, name: string): boolean {
+  const file = join(UNIT_DIR, `${service}.d`, name);
+  if (!existsSync(file)) return false;
+  if (runningAsMetro()) mustHelper(['dropin-remove', service, name]);
+  else rmSync(file, { force: true });
+  return true;
+}
+
+const lineHash = (line: string): string => createHash('sha256').update(line.trim()).digest('hex').slice(0, 16);
+
+function asAgentRun(args: string[], input?: string): { status: number | null; stdout: string } {
+  const [file, argv] = asUser(agentUser(), 'crontab', args);
+  const run = spawnSync(file, argv, { encoding: 'utf8', input, stdio: ['pipe', 'pipe', 'ignore'], timeout: 20_000 });
+  return { status: run.error === undefined ? run.status : null, stdout: run.stdout ?? '' };
+}
+
+function rootCrontabWrite(input: string): { status: number | null; stdout: string } {
+  const wanted = new Set(input.split('\n').filter((l) => l.trim() !== '').map(lineHash));
+  const current = rootHelper(['root-crontab']).stdout.split('\n').filter((l) => l.trim() !== '');
+  for (const line of current) if (!wanted.has(lineHash(line))) mustHelper(['root-crontab-drop', lineHash(line)]);
+  return { status: 0, stdout: '' };
+}
+
+function crontab(args: string[], input?: string): { status: number | null; stdout: string } {
+  const at = args.indexOf('-u');
+  const who = at >= 0 ? args[at + 1] : undefined;
+  const rest = args.filter((_, i) => i !== at && i !== at + 1);
+  if (who === 'root') return rest[0] === '-l' ? { status: 0, stdout: rootHelper(['root-crontab']).stdout } : rootCrontabWrite(input ?? '');
+  return asAgentRun(rest, input);
+}
+
+function systemctl(args: string[]): { status: number | null; stdout: string } | null {
+  if (args[0] === 'daemon-reload') return { status: rootHelper(['daemon-reload']).status, stdout: '' };
+  if (args[0] === 'start') return { status: rootHelper(['start-job', args[args.length - 1] ?? '']).status, stdout: '' };
+  return null;
+}
+
+export function metroRun(file: string, args: string[], input?: string): { status: number | null; stdout: string } | null {
+  if (!runningAsMetro()) return null;
+  if (file === 'crontab') return crontab(args, input);
+  if (file === 'systemctl') return systemctl(args);
+  return null;
+}

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

@@ -0,0 +1,91 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { runningAsMetro } from '../metro-user/privilege.js';
+
+export const AGENT_NAME = 'agent';
+const AGENT_PATH = ['.local/bin', '/usr/local/sbin', '/usr/local/bin', '/usr/sbin', '/usr/bin', '/sbin', '/bin'];
+
+export interface AgentUser {
+  name: string;
+  uid: number;
+  gid: number;
+  home: string;
+}
+
+export interface UserHost {
+  platform: string;
+  uid: number | undefined;
+  lookup: (name: string) => AgentUser | null;
+}
+
+export function lookupUser(name: string): AgentUser | null {
+  const run = spawnSync('getent', ['passwd', name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  if (run.error !== undefined || run.status !== 0) return null;
+  const [, , uid = '', gid = '', , home = ''] = run.stdout.trim().split(':');
+  const u = Number(uid);
+  const g = Number(gid);
+  return Number.isInteger(u) && u > 0 && Number.isInteger(g) && home.startsWith('/') ? { name, uid: u, gid: g, home } : null;
+}
+
+const realHost: UserHost = { platform: process.platform, uid: process.getuid?.(), lookup: lookupUser };
+
+export const agentUserExpected = (host: UserHost = realHost): boolean => host.platform === 'linux' && (host.uid === 0 || runningAsMetro());
+
+let cached: AgentUser | null = null;
+
+export function agentUser(host: UserHost = realHost): AgentUser | null {
+  if (!agentUserExpected(host)) return null;
+  cached ??= host.lookup(AGENT_NAME);
+  return cached;
+}
+
+export function forgetAgentUser(): void {
+  cached = null;
+}
+
+let extraEnv: Record<string, string> = {};
+
+export function setAgentExtraEnv(env: Record<string, string>): void {
+  extraEnv = { ...env };
+}
+
+export const agentExtraEnv = (): Record<string, string> => ({ ...extraEnv });
+
+export function agentEnv(user: AgentUser, extra: Record<string, string> = {}): Record<string, string> {
+  return {
+    HOME: user.home,
+    USER: user.name,
+    LOGNAME: user.name,
+    SHELL: '/bin/bash',
+    LANG: process.env.LANG ?? 'C.UTF-8',
+    TERM: process.env.TERM ?? 'xterm-256color',
+    PATH: AGENT_PATH.map((p) => (p.startsWith('/') ? p : join(user.home, p))).join(':'),
+    ...extraEnv,
+    ...extra,
+  };
+}
+
+export function asUser(user: AgentUser | null, file: string, args: readonly string[], extra: Record<string, string> = {}): [string, string[]] {
+  if (user === null) return [file, [...args]];
+  const env = Object.entries(agentEnv(user, extra)).map(([k, v]) => `${k}=${v}`);
+  if (runningAsMetro()) return ['sudo', ['-n', '-u', user.name, '--', 'env', '-i', ...env, file, ...args]];
+  return ['setpriv', [`--reuid=${String(user.uid)}`, `--regid=${String(user.gid)}`, '--init-groups', 'env', '-i', ...env, file, ...args]];
+}
+
+export const asAgent = (file: string, args: readonly string[], extra: Record<string, string> = {}): [string, string[]] =>
+  asUser(agentUser(), file, args, extra);
+
+export const agentCommand = (command: readonly string[], extra: Record<string, string> = {}): string[] => {
+  const [file = '', ...args] = command;
+  const [bin, argv] = asAgent(file, args, extra);
+  return [bin, ...argv];
+};
+
+export function claudeBin(user = agentUser()): string {
+  return user === null ? 'claude' : join(user.home, '.local', 'bin', 'claude');
+}
+
+export const claudeHome = (user = agentUser()): string | null => (user === null ? null : user.home);
+
+export const agentMarketplaceDir = (user: AgentUser): string => join(user.home, '.metro', 'marketplace');
+export const agentViewDir = (user: AgentUser): string => join(user.home, '.metro', 'agents');

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/view.ts

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { agentsDir } from '../agents/files.js';
+import { removeHome, writeHomeText } from './home-fs.js';
+import { agentUser, agentViewDir, type AgentUser } from './user.js';
+
+const COPIED = ['policy.json', 'claude-setup.json', 'system-prompt.md'] as const;
+const SYNC_MS = 5_000;
+
+const readText = (path: string): string | null => {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+};
+
+const readRecord = (path: string): Record<string, unknown> | null => {
+  const text = readText(path);
+  if (text === null) return null;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+
+const json = (value: unknown): string => `${JSON.stringify(value, null, 2)}\n`;
+
+function agentFile(dir: string): string | null {
+  const file = readRecord(join(dir, 'agent.json'));
+  if (file === null || typeof file.id !== 'string' || typeof file.key !== 'string') return null;
+  return json({ version: 1, id: file.id, key: file.key });
+}
+
+function modelFile(dir: string): string | null {
+  const cfg = readRecord(join(dir, 'model.json'));
+  if (cfg === null || !Array.isArray(cfg.connections)) return null;
+  const connections = cfg.connections.filter(isRecord).map((c) => ({ id: c.id, provider: c.provider, model: c.model }));
+  return json({ version: 2, route: cfg.route, connections });
+}
+
+export function viewFiles(dir = agentsDir()): Map<string, string | null> {
+  const files = new Map<string, string | null>([
+    ['agent.json', agentFile(dir)],
+    ['model.json', modelFile(dir)],
+  ]);
+  for (const name of COPIED) files.set(name, existsSync(join(dir, name)) ? readText(join(dir, name)) : null);
+  return files;
+}
+
+const written = new Map<string, string | null>();
+
+export function syncAgentView(user: AgentUser | null = agentUser(), dir = agentsDir()): number {
+  if (user === null) return 0;
+  const target = agentViewDir(user);
+  let changed = 0;
+  for (const [name, text] of viewFiles(dir)) {
+    const path = join(target, name);
+    if (written.has(path) && written.get(path) === text) continue;
+    if (text === null) removeHome(path, false, user);
+    else writeHomeText(path, text, 0o600, undefined, user);
+    written.set(path, text);
+    changed += 1;
+  }
+  return changed;
+}
+
+let timer: ReturnType<typeof setInterval> | null = null;
+
+export function watchAgentView(everyMs = SYNC_MS): void {
+  if (timer !== null) return;
+  const tick = (): void => {
+    try {
+      const changed = syncAgentView();
+      if (changed > 0) log.info({ changed }, 'agent-user: refreshed the Metro files the agent may read');
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'agent-user: could not refresh the Metro files the agent may read');
+    }
+  };
+  tick();
+  timer = setInterval(tick, everyMs);
+  timer.unref();
+}

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

@@ -0,0 +1,19 @@
+import { STATIONS, type StationName } from '@metro-labs/core/station-names';
+
+const ACCOUNT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+
+export interface AccountRef {
+  agentId: string;
+  station: StationName;
+  accountId: string;
+}
+
+export function isStationName(raw: unknown): raw is StationName {
+  return (
+    typeof raw === 'string' && (STATIONS as readonly string[]).includes(raw)
+  );
+}
+
+export function parseAccountId(raw: string): string | null {
+  return ACCOUNT_ID_RE.test(raw) ? raw : null;
+}

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

@@ -0,0 +1,55 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { StationName } from '@metro-labs/core/station-names';
+import { ApiError } from '@metro-labs/http/api-error';
+import { bodyField, readJsonBody, sendJson } from '@metro-labs/http/api-http';
+import { stationByName } from '../stations/registry.js';
+import type { AccountRoute } from './account-routes.js';
+import { handleSenderCards, type SenderCardDeps } from './sender-cards.js';
+
+interface Target {
+  station: StationName;
+  accountId: string;
+}
+
+export interface LookupDeps extends SenderCardDeps {
+  resolveSender: (station: StationName, accountId: string, query: string) => Promise<unknown>;
+}
+
+type Lookup = (req: IncomingMessage, res: ServerResponse, deps: LookupDeps, target: Target) => Promise<void>;
+
+function lookupQuery(req: IncomingMessage): string {
+  const params = new URLSearchParams((req.url ?? '').split('?')[1] ?? '');
+  return (params.get('q') ?? '').trim();
+}
+
+async function handleResolve(req: IncomingMessage, res: ServerResponse, deps: LookupDeps, target: Target): Promise<void> {
+  if (stationByName(target.station)?.resolvesSenders !== true)
+    throw new ApiError(`metro cannot look a sender up on ${target.station}`, 400);
+  const query = lookupQuery(req);
+  if (query === '') throw new ApiError('a number to look up is required', 400);
+  sendJson(req, res, 200, await deps.resolveSender(target.station, target.accountId, query));
+}
+
+async function handleName(req: IncomingMessage, res: ServerResponse, deps: LookupDeps, target: Target): Promise<void> {
+  if (stationByName(target.station)?.claimsName !== true)
+    throw new ApiError(`${target.station} accounts have no name to claim`, 400);
+  if (req.method === 'GET') {
+    sendJson(req, res, 200, await deps.accountCall(target.station, 'name', { account: target.accountId }));
+    return;
+  }
+  const label = bodyField(await readJsonBody(req), 'label');
+  if (typeof label !== 'string' || label.trim() === '') throw new ApiError('a label is required', 400);
+  sendJson(req, res, 200, await deps.accountCall(target.station, 'claim_name', { account: target.accountId, label }));
+}
+
+function handleRecent(req: IncomingMessage, res: ServerResponse, deps: LookupDeps, target: Target): Promise<void> {
+  sendJson(req, res, 200, { senders: deps.recentSenders(target.station, target.accountId) });
+  return Promise.resolve();
+}
+
+export const LOOKUPS: Partial<Record<AccountRoute['kind'], Lookup>> = {
+  profiles: handleSenderCards,
+  resolve: handleResolve,
+  name: handleName,
+  senders: handleRecent,
+};

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

@@ -0,0 +1,76 @@
+import { isStationName, parseAccountId } from './account-attach.js';
+import type { StationName } from '@metro-labs/core/station-names';
+import { ATTACH_ID_RE } from '../stations/attach-session.js';
+
+export type AccountRoute =
+  | { kind: 'start' }
+  | { kind: 'session'; attachId: string }
+  | { kind: 'step'; attachId: string }
+  | { kind: 'account'; station: StationName; accountId: string }
+  | { kind: 'allowlist'; station: StationName; accountId: string }
+  | { kind: 'senders'; station: StationName; accountId: string }
+  | { kind: 'resolve'; station: StationName; accountId: string }
+  | { kind: 'enabled'; station: StationName; accountId: string }
+  | { kind: 'policy'; station: StationName; accountId: string }
+  | { kind: 'profiles'; station: StationName; accountId: string }
+  | { kind: 'name'; station: StationName; accountId: string };
+
+const ROUTE_METHODS: Record<AccountRoute['kind'], string[]> = {
+  start: ['POST'],
+  session: ['GET', 'DELETE'],
+  step: ['POST'],
+  account: ['DELETE'],
+  allowlist: ['PUT'],
+  senders: ['GET'],
+  resolve: ['GET'],
+  enabled: ['PUT'],
+  policy: ['PUT'],
+  profiles: ['GET'],
+  name: ['GET', 'POST'],
+};
+
+const SUB_ROUTES = ['allowlist', 'senders', 'resolve', 'enabled', 'name', 'policy', 'profiles'] as const;
+
+type SubRoute = (typeof SUB_ROUTES)[number];
+
+const isSubRoute = (value: string | undefined): value is SubRoute =>
+  SUB_ROUTES.some((sub) => sub === value);
+
+function twoSegmentRoute(head: string, tail: string): AccountRoute | null {
+  if (ATTACH_ID_RE.test(head))
+    return tail === 'step' ? { kind: 'step', attachId: head } : null;
+  if (!isStationName(head)) return null;
+  const accountId = parseAccountId(tail);
+  return accountId === null ? null : { kind: 'account', station: head, accountId };
+}
+
+function accountSubRoute(
+  head: string,
+  tail: string,
+  sub: string | undefined,
+): AccountRoute | null {
+  if (!isStationName(head) || !isSubRoute(sub)) return null;
+  const accountId = parseAccountId(tail);
+  return accountId === null ? null : { kind: sub, station: head, accountId };
+}
+
+export function accountRoute(rest: string[]): AccountRoute | null {
+  const [head, tail] = rest;
+  if (head === undefined) return null;
+  if (rest.length === 1)
+    return head === 'start'
+      ? { kind: 'start' }
+      : ATTACH_ID_RE.test(head)
+        ? { kind: 'session', attachId: head }
+        : null;
+  if (rest.length === 3 && tail !== undefined) return accountSubRoute(head, tail, rest[2]);
+  if (rest.length !== 2 || tail === undefined) return null;
+  return twoSegmentRoute(head, tail);
+}
+
+export function accountRouteAllows(
+  route: AccountRoute,
+  method: string | undefined,
+): boolean {
+  return ROUTE_METHODS[route.kind].includes(method ?? '');
+}