@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.300

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/runner-activity.ts

@@ -0,0 +1,263 @@
+import { isRecord } from './is-record.js';
+
+const PHASES = ['starting', 'idle', 'working', 'approval', 'compacting', 'stopped', 'error'] as const;
+const TASK_STATES = ['pending', 'running', 'completed', 'failed', 'stopped', 'paused', 'unknown'] as const;
+const EVENTS = ['turn_started', 'turn_finished', 'turn_failed', 'tool_started', 'tool_finished', 'tool_failed', 'task_started', 'task_completed', 'task_failed', 'task_stopped', 'task_updated', 'compacting', 'compacted', 'compact_failed', 'api_retry', 'approval_waiting', 'approval_ended', 'permission_denied', 'session_failed'] as const;
+export type RunnerPhase = (typeof PHASES)[number];
+export type RunnerTaskState = (typeof TASK_STATES)[number];
+export type RunnerEventKind = (typeof EVENTS)[number];
+
+const FAILURE = {
+  authentication: 'The provider refused authentication. Check the Model page.',
+  billing: 'The provider refused billing. Check the Model page.',
+  rate_limit: 'The provider rate limit was reached. Retry later or check the Model page.',
+  provider_unavailable: 'The provider is unavailable. Retry later or check the Model page.',
+  invalid_request: 'The provider rejected the request. Check Conversations and the Model page.',
+  output_limit: 'The model reached its output token limit. Check Conversations.',
+  provider_error: 'SDK turn failed (provider_error). Check Conversations and the Model page.',
+  error_during_execution: 'SDK turn failed (error_during_execution). Check Conversations and the Model page.',
+  error_max_turns: 'SDK turn failed (error_max_turns). Check Conversations and the Model page.',
+  error_max_budget_usd: 'SDK turn failed (error_max_budget_usd). Check Conversations and the Model page.',
+  error_max_structured_output_retries: 'SDK turn failed (error_max_structured_output_retries). Check Conversations and the Model page.',
+  read_token_limit: 'Read exceeded its token limit. Read a smaller range with offset and limit, or search the file.',
+  tool_error: 'A tool failed. See its result in Conversations.',
+  task_error: 'A background task failed. See Conversations and Terminal.',
+  compact_error: 'Conversation compaction failed.',
+  status_unavailable: 'The SDK status file cannot be written. Check its path and permissions before starting.',
+  saved_state: 'The saved Agent SDK state cannot be read. Restore it before starting.',
+  executable: 'The SDK executable could not start. Prepare the SDK runtime again.',
+  module: 'The SDK runtime could not load a required module. Prepare the SDK runtime again.',
+  configuration: 'The SDK launch configuration is missing or invalid. Check Harness and the Model page before starting.',
+  process_exit: 'The SDK process exited unexpectedly. Check its reported exit code or signal before retrying.',
+  connection: 'The SDK connection failed. Check the server and provider connection.',
+  session_ended: 'The Agent SDK session ended unexpectedly.',
+  interrupted: 'The SDK stopped before finishing a chat request. Check Conversations before retrying; actions may already have run.',
+  session_error: 'The Agent SDK session failed. Check Terminal and the Model page.',
+} as const;
+export type RunnerFailureCode = keyof typeof FAILURE;
+
+const ERROR_CODES = ['ENOENT', 'EACCES', 'EPERM', 'ENOEXEC', 'ENOMEM', 'ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND', 'ERR_DLOPEN_FAILED', 'ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'EAI_AGAIN', 'ETIMEDOUT', 'CERT_HAS_EXPIRED', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'] as const;
+const SIGNALS = ['SIGTERM', 'SIGKILL', 'SIGSEGV', 'SIGABRT', 'SIGBUS', 'SIGILL', 'SIGINT', 'SIGHUP', 'SIGPIPE'] as const;
+
+export interface RunnerDiagnostic {
+  source: 'exception' | 'stderr';
+  errorCode?: (typeof ERROR_CODES)[number];
+  httpStatus?: number;
+  exitCode?: number;
+  signal?: (typeof SIGNALS)[number];
+}
+
+const boundedNumber = (value: unknown, min: number, max: number): number | undefined => typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max ? value : undefined;
+
+export function runnerDiagnostic(raw: unknown): RunnerDiagnostic | undefined {
+  if (!isRecord(raw) || (raw.source !== 'exception' && raw.source !== 'stderr')) return undefined;
+  const errorCode = ERROR_CODES.find((code) => code === raw.errorCode);
+  const signal = SIGNALS.find((value) => value === raw.signal);
+  const httpStatus = boundedNumber(raw.httpStatus, 400, 599);
+  const exitCode = boundedNumber(raw.exitCode, 0, 255);
+  return {
+    source: raw.source,
+    ...(errorCode === undefined ? {} : { errorCode }),
+    ...(httpStatus === undefined ? {} : { httpStatus }),
+    ...(exitCode === undefined ? {} : { exitCode }),
+    ...(signal === undefined ? {} : { signal }),
+  };
+}
+
+export function runnerFailureSummary(code: RunnerFailureCode, tool: string | null = null, diagnostic?: RunnerDiagnostic): string {
+  const summary = code === 'tool_error' && name(tool) !== null ? `${tool} failed. See its result in Conversations.` : FAILURE[code];
+  const safe = runnerDiagnostic(diagnostic);
+  if (safe === undefined) return summary;
+  const details = [safe.errorCode, safe.httpStatus === undefined ? null : `HTTP ${safe.httpStatus}`, safe.exitCode === undefined ? null : `exit ${safe.exitCode}`, safe.signal].filter((value) => value !== undefined && value !== null);
+  return details.length === 0 ? summary : `${summary} Observed: ${details.join(', ')} (${safe.source === 'stderr' ? 'startup stderr' : 'exception'}).`;
+}
+
+export interface RunnerTask {
+  id: string;
+  kind: string | null;
+  agent: string | null;
+  description?: string | null;
+  lastObservedModel?: string | null;
+  status: RunnerTaskState;
+  background: boolean;
+  startedAt: number;
+  firstStartedAt?: number;
+  updatedAt: number;
+  endedAt: number | null;
+  lastTool: string | null;
+  toolUses: number;
+  durationMs: number;
+}
+
+export interface RunnerTool {
+  id: string;
+  name: string;
+  taskId: string | null;
+  worker?: boolean;
+  startedAt: number;
+}
+
+export interface RunnerEvent {
+  id?: string;
+  at: number;
+  kind: RunnerEventKind;
+  tool: string | null;
+  toolUseId?: string;
+  taskId: string | null;
+  code?: RunnerFailureCode;
+  diagnostic?: RunnerDiagnostic;
+}
+
+export interface RunnerFailure extends RunnerEvent {
+  id: string;
+  code: RunnerFailureCode;
+}
+
+export interface RunnerInput {
+  id: string;
+  kind: 'chat' | 'call' | 'note';
+  state: 'accepted' | 'consumed' | 'output' | 'completed' | 'cancelled';
+  acceptedAt: number;
+  dispatchedAt: number | null;
+  consumedAt: number | null;
+  firstOutputAt: number | null;
+  completedAt: number | null;
+}
+
+export interface RunnerActivity {
+  pid: number;
+  procStart?: string;
+  cancelSignal?: 'SIGUSR2';
+  runner: 'sdk';
+  phase: RunnerPhase;
+  mainPhase: RunnerPhase;
+  mainStartedAt: number | null;
+  sessionId: string | null;
+  updatedAt: number;
+  pending: number;
+  queueOldestAt?: number | null;
+  inputs?: RunnerInput[];
+  callState?: 'started' | 'ended' | 'accepted' | 'queued' | 'speaking' | 'completed' | 'interrupted' | 'failed';
+  workers: number;
+  approvals: number;
+  tools: string[];
+  activeTools: RunnerTool[];
+  tasks: RunnerTask[];
+  events: RunnerEvent[];
+  lastError: string | null;
+  activeFailure?: RunnerFailure | null;
+  lastFailure?: RunnerFailure | null;
+}
+
+const count = (value: unknown): number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+const phase = (value: unknown): value is RunnerPhase => PHASES.some((p) => p === value);
+const taskState = (value: unknown): value is RunnerTaskState => TASK_STATES.some((s) => s === value);
+const eventKind = (value: unknown): value is RunnerEventKind => EVENTS.some((e) => e === value);
+const name = (value: unknown): string | null => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,128}$/.test(value) ? value : null;
+const sessionId = (value: unknown): string | null => typeof value === 'string' && /^[0-9a-f-]{36}$/.test(value) ? value : null;
+
+export function runnerTaskDescription(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const line = value.split(/\r|\n|\p{Zl}|\p{Zp}/u, 1)[0] ?? '';
+  const description = line.replace(/[\p{Cc}\p{Cf}]/gu, ' ').replace(/\s+/g, ' ').trim().slice(0, 160).trim();
+  return description.length > 0 ? description : null;
+}
+
+export const runnerTaskModel = (value: unknown): string | null => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:/@+[\]-]{0,127}$/.test(value) ? value : null;
+
+function task(raw: unknown): RunnerTask | null {
+  if (!isRecord(raw) || !name(raw.id) || !taskState(raw.status)) return null;
+  return {
+    id: String(raw.id), kind: name(raw.kind), agent: name(raw.agent), status: raw.status, background: raw.background === true,
+    startedAt: count(raw.startedAt), updatedAt: count(raw.updatedAt), endedAt: count(raw.endedAt) || null,
+    lastTool: name(raw.lastTool), toolUses: count(raw.toolUses), durationMs: count(raw.durationMs),
+    ...(count(raw.firstStartedAt) > 0 ? { firstStartedAt: count(raw.firstStartedAt) } : {}),
+    ...(raw.description === undefined ? {} : { description: runnerTaskDescription(raw.description) }),
+    ...(raw.lastObservedModel === undefined ? {} : { lastObservedModel: runnerTaskModel(raw.lastObservedModel) }),
+  };
+}
+
+function tool(raw: unknown): RunnerTool | null {
+  if (!isRecord(raw) || !name(raw.id) || !name(raw.name)) return null;
+  return { id: String(raw.id), name: String(raw.name), taskId: name(raw.taskId), startedAt: count(raw.startedAt), ...(typeof raw.worker === 'boolean' ? { worker: raw.worker } : {}) };
+}
+
+export const runnerFailureCode = (value: unknown): value is RunnerFailureCode => typeof value === 'string' && Object.hasOwn(FAILURE, value);
+const failureKind = (value: RunnerEventKind): boolean => ['turn_failed', 'tool_failed', 'task_failed', 'compact_failed', 'session_failed'].includes(value);
+
+function event(raw: unknown): RunnerEvent | null {
+  if (!isRecord(raw) || !eventKind(raw.kind) || count(raw.at) === 0) return null;
+  const diagnostic = runnerDiagnostic(raw.diagnostic);
+  return {
+    at: count(raw.at), kind: raw.kind, tool: name(raw.tool), taskId: name(raw.taskId),
+    ...(name(raw.id) === null ? {} : { id: String(raw.id) }),
+    ...(name(raw.toolUseId) === null ? {} : { toolUseId: String(raw.toolUseId) }),
+    ...(failureKind(raw.kind) && runnerFailureCode(raw.code) ? { code: raw.code, ...(diagnostic === undefined ? {} : { diagnostic }) } : {}),
+  };
+}
+
+function failure(raw: unknown): RunnerFailure | null {
+  const parsed = event(raw);
+  return parsed?.id !== undefined && parsed.code !== undefined ? { ...parsed, id: parsed.id, code: parsed.code } : null;
+}
+
+function safeError(raw: unknown): string | null {
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  const known = Object.values(FAILURE).find((text) => text === raw);
+  if (known !== undefined) return known;
+  const tool = /^([A-Za-z0-9_.:-]{1,128}) failed\. See its result in Conversations\.$/.exec(raw)?.[1];
+  return tool === undefined ? FAILURE.session_error : runnerFailureSummary('tool_error', tool);
+}
+
+function list<T>(raw: unknown, parse: (item: unknown) => T | null, max: number): T[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.map(parse).filter((item): item is T => item !== null).slice(0, max);
+}
+
+function processIdentity(value: unknown): Pick<RunnerActivity, 'procStart'> {
+  return typeof value === 'string' && /^\d{1,32}$/.test(value) ? { procStart: value } : {};
+}
+
+function failureFields(raw: Record<string, unknown>): Pick<RunnerActivity, 'lastError' | 'activeFailure' | 'lastFailure'> {
+  const activeFailure = failure(raw.activeFailure);
+  return {
+    lastError: Object.hasOwn(raw, 'activeFailure') ? activeFailure === null ? null : runnerFailureSummary(activeFailure.code, activeFailure.tool, activeFailure.diagnostic) : safeError(raw.lastError),
+    ...(Object.hasOwn(raw, 'activeFailure') ? { activeFailure } : {}),
+    ...(Object.hasOwn(raw, 'lastFailure') ? { lastFailure: failure(raw.lastFailure) } : {}),
+  };
+}
+
+function input(raw: unknown): RunnerInput | null {
+  if (!isRecord(raw) || sessionId(raw.id) === null) return null;
+  const kind = (['chat', 'call', 'note'] as const).find((value) => value === raw.kind);
+  const state = (['accepted', 'consumed', 'output', 'completed', 'cancelled'] as const).find((value) => value === raw.state);
+  if (kind === undefined || state === undefined) return null;
+  return {
+    id: String(raw.id), kind, state, acceptedAt: count(raw.acceptedAt),
+    dispatchedAt: count(raw.dispatchedAt) || null, consumedAt: count(raw.consumedAt) || null,
+    firstOutputAt: count(raw.firstOutputAt) || null, completedAt: count(raw.completedAt) || null,
+  };
+}
+
+function inputFields(raw: Record<string, unknown>): Pick<RunnerActivity, 'inputs' | 'queueOldestAt' | 'callState'> {
+  const states = ['started', 'ended', 'accepted', 'queued', 'speaking', 'completed', 'interrupted', 'failed'] as const;
+  const callState = states.find((state) => state === raw.callState);
+  return {
+    ...(raw.inputs === undefined ? {} : { inputs: list(raw.inputs, input, 40) }),
+    ...(raw.queueOldestAt === undefined ? {} : { queueOldestAt: count(raw.queueOldestAt) || null }),
+    ...(callState === undefined ? {} : { callState }),
+  };
+}
+
+export function parseRunnerActivity(raw: unknown): RunnerActivity | null {
+  if (!isRecord(raw) || raw.runner !== 'sdk' || !phase(raw.phase) || count(raw.pid) === 0 || count(raw.updatedAt) === 0) return null;
+  return {
+    runner: 'sdk', pid: count(raw.pid), ...processIdentity(raw.procStart), phase: raw.phase, mainPhase: phase(raw.mainPhase) ? raw.mainPhase : raw.phase,
+    ...(raw.cancelSignal === 'SIGUSR2' ? { cancelSignal: raw.cancelSignal } : {}),
+    mainStartedAt: count(raw.mainStartedAt) || null, sessionId: sessionId(raw.sessionId), updatedAt: count(raw.updatedAt),
+    pending: count(raw.pending), workers: count(raw.workers), approvals: count(raw.approvals),
+    tools: list(raw.tools, name, 20), activeTools: list(raw.activeTools, tool, 20),
+    tasks: list(raw.tasks, task, 30), events: list(raw.events, event, 40),
+    ...failureFields(raw), ...inputFields(raw),
+  };
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/secure-fs.ts

@@ -0,0 +1,74 @@
+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);
+}
+
+function modeOf(path: string): number | null {
+  try {
+    return statSync(path).mode & 0o777;
+  } catch {
+    return null;
+  }
+}
+
+export function writeAtomic(path: string, data: string, mode?: number): void {
+  const chosen = mode ?? modeOf(path) ?? 0o644;
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.metro-${String(process.pid)}.tmp`;
+  writeFileSync(tmp, data, { mode: chosen });
+  chmodSync(tmp, chosen);
+  renameSync(tmp, path);
+}
+
+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/sdk-runner/node_modules/@metro-labs/core/src/skill-source.ts

@@ -0,0 +1,96 @@
+import { join } from 'node:path';
+import { isRecord } from './is-record.js';
+
+export const SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const SKILL_HASH = /^[a-f0-9]{64}$/;
+export const SKILL_COMMIT = /^[a-f0-9]{40}$/;
+export const SKILL_FILE_MAX = 256 * 1024;
+export const SKILL_TOTAL_MAX = 8 * 1024 * 1024;
+export const SKILL_FILES_MAX = 256;
+export const SKILL_MANIFEST_MAX = 128 * 1024;
+
+export interface SkillSource {
+  repository: string;
+  ref: string;
+  folder: string;
+}
+
+export interface SkillFile {
+  path: string;
+  size: number;
+  sha256: string;
+  executable?: boolean;
+}
+
+export interface SkillGeneration {
+  id: string;
+  source: (SkillSource & { repositoryId: number; commit: string }) | null;
+  createdAt: string;
+  skills: { name: string; description: string }[];
+  files: SkillFile[];
+}
+
+export interface SkillActivation {
+  generation: string | null;
+  loading: string | null;
+  rollback?: string | null;
+  appliedAt: string | null;
+  problem: string | null;
+  shadowed: string[];
+}
+
+export const skillSourceRoot = (claudeDir: string): string => join(claudeDir, 'metro-github');
+export const skillRelease = (root: string, id: string): string => {
+  if (!SKILL_HASH.test(id)) throw new Error('Invalid skills generation.');
+  return join(root, 'releases', id);
+};
+
+export function skillPath(path: string): boolean {
+  const parts = path.split('/');
+  return path.length <= 240 && parts.length >= 2 && parts.length <= 8 && SKILL_NAME.test(parts[0] ?? '') &&
+    parts.every((part) => /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(part)) &&
+    !parts.slice(1, -1).includes('SKILL.md') && !(parts.length > 2 && parts.at(-1) === 'SKILL.md');
+}
+
+function manifestSkill(value: unknown): SkillGeneration['skills'][number] {
+  if (!isRecord(value) || typeof value.name !== 'string' || !SKILL_NAME.test(value.name) || typeof value.description !== 'string' || value.description.length > 1024) throw new Error('Invalid skill name or description.');
+  return { name: value.name, description: value.description };
+}
+
+function fileSize(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > SKILL_FILE_MAX) throw new Error('Invalid skills file size.');
+  return value;
+}
+
+function manifestFile(value: unknown): SkillFile {
+  if (!isRecord(value)) throw new Error('Invalid skills file.');
+  if (typeof value.path !== 'string' || !skillPath(value.path) || typeof value.sha256 !== 'string' || !SKILL_HASH.test(value.sha256)) throw new Error('Invalid skills file path or hash.');
+  return { path: value.path, size: fileSize(value.size), sha256: value.sha256, ...(value.executable === true ? { executable: true } : {}) };
+}
+
+function manifestSource(s: unknown): SkillGeneration['source'] {
+  if (s === null) return null;
+  if (!isRecord(s) || typeof s.repository !== 'string' || typeof s.ref !== 'string' || typeof s.folder !== 'string' || typeof s.repositoryId !== 'number' || typeof s.commit !== 'string' || !SKILL_COMMIT.test(s.commit)) throw new Error('Invalid skills provenance.');
+  return { repository: s.repository, ref: s.ref, folder: s.folder, repositoryId: s.repositoryId, commit: s.commit };
+}
+
+function checkFiles(skills: SkillGeneration['skills'], files: SkillFile[]): void {
+  if (files.reduce((sum, file) => sum + file.size, 0) > SKILL_TOTAL_MAX || new Set(files.map((f) => f.path.toLowerCase())).size !== files.length || new Set(skills.map((s) => s.name)).size !== skills.length) throw new Error('Duplicate or oversized skills files.');
+  if (files.some((f) => !skills.some((s) => f.path.startsWith(`${s.name}/`))) || skills.some((s) => !files.some((f) => f.path === `${s.name}/SKILL.md`))) throw new Error('Every skill needs its own SKILL.md.');
+}
+
+function boundedGeneration(generation: SkillGeneration): SkillGeneration {
+  if (Buffer.byteLength(JSON.stringify(generation)) > SKILL_MANIFEST_MAX) throw new Error('Skills manifest is too large.');
+  return generation;
+}
+
+export function skillGeneration(raw: unknown): SkillGeneration {
+  if (!isRecord(raw) || typeof raw.id !== 'string' || !SKILL_HASH.test(raw.id) || typeof raw.createdAt !== 'string' || !Array.isArray(raw.skills) || !Array.isArray(raw.files)) throw new Error('Invalid skills manifest.');
+  if (raw.skills.length > 64 || raw.files.length > SKILL_FILES_MAX) throw new Error('Skills manifest is too large.');
+  const skills = raw.skills.map(manifestSkill);
+  const files = raw.files.map(manifestFile);
+  const source = manifestSource(raw.source);
+  checkFiles(skills, files);
+  if (source === null) checkFiles([], files);
+  return boundedGeneration({ id: raw.id, source, createdAt: raw.createdAt, skills, files });
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/station-names.ts

@@ -0,0 +1,14 @@
+export const STATIONS = [
+  'xmtp',
+  'telegram-bot',
+  'telegram',
+  'discord-bot',
+  'whatsapp',
+  'threema',
+  'outlook',
+  'gmail',
+  'webhook',
+] as const;
+
+export type StationName = (typeof STATIONS)[number];
+

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/account-files.ts

@@ -0,0 +1,41 @@
+import { readdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { log } from '../log.js';
+
+export interface AccountFiles {
+  path: (accountId: string) => string;
+  forget: (accountId: string) => void;
+  forgetExcept: (keptAccountIds: readonly string[]) => void;
+}
+
+const safeSegment = (s: string): string => s.replace(/[^A-Za-z0-9_-]/g, '_');
+
+function listed(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+export function accountFiles(dirEnv: string, prefix: string): AccountFiles {
+  const dir = (): string => process.env[dirEnv] ?? join(homedir(), '.metro');
+  const name = (accountId: string): string => `${prefix}${safeSegment(accountId)}.json`;
+  const remove = (file: string, reason: string): void => {
+    rmSync(join(dir(), file), { force: true });
+    log.info({ file: join(dir(), file) }, reason);
+  };
+  return {
+    path: (accountId) => join(dir(), name(accountId)),
+    forget: (accountId) => {
+      remove(name(accountId), 'station: removed the files of a detached account');
+    },
+    forgetExcept: (keptAccountIds) => {
+      const kept = new Set(keptAccountIds.map(name));
+      for (const file of listed(dir()))
+        if (file.startsWith(prefix) && file.endsWith('.json') && !kept.has(file))
+          remove(file, 'station: removed the files of an account that is no longer attached');
+    },
+  };
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/account-store.ts

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { errMsg } from '../log.js';
+import { chmodIfExists } from '../secure-fs.js';
+
+export type Die = (msg: string) => never;
+
+export interface AccountStoreOpts<T> {
+  prefix: string;
+  validate?: (raw: T[], die: Die) => void;
+}
+
+export interface Loader<T> {
+  die: Die;
+  loadAccounts: () => T[];
+}
+
+const envName = (prefix: string): string =>
+  `${prefix.toUpperCase().replace(/-/g, '_')}_ACCOUNTS_FILE`;
+
+const accountsFile = (prefix: string): string =>
+  process.env[envName(prefix)] ?? join(homedir(), '.metro', `${prefix}-accounts.json`);
+
+function checkIds(raw: { id: string }[], die: Die): void {
+  const seen = new Set<string>();
+  for (const a of raw) {
+    if (!a.id) die('account missing id');
+    if (seen.has(a.id)) die(`duplicate account id '${a.id}'`);
+    seen.add(a.id);
+  }
+}
+
+function readList<T>(file: string, die: Die): T[] {
+  if (!existsSync(file))
+    return die(
+      `no accounts file ${file} — the daemon writes it from ~/.metro/agents/agent.json at boot; attach an account to this station from the page first`,
+    );
+  chmodIfExists(file);
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    return die(`bad ${file}: ${errMsg(e)}`);
+  }
+  if (!Array.isArray(raw) || raw.length === 0)
+    return die(`${file} must be a non-empty array`);
+  return raw as T[];
+}
+
+export function makeAccountStore<T extends { id: string }>(
+  opts: AccountStoreOpts<T>,
+): Loader<T> {
+  const die: Die = (msg) => {
+    process.stderr.write(`${opts.prefix}: ${msg}\n`);
+    process.exit(2);
+  };
+
+  function loadAccounts(): T[] {
+    const raw = readList<T>(accountsFile(opts.prefix), die);
+    checkIds(raw, die);
+    opts.validate?.(raw, die);
+    return raw;
+  }
+
+  return { die, loadAccounts };
+}
+
+export function resolveAccountId(
+  accounts: Map<string, unknown>,
+  args: { account?: string; line?: string },
+  parseAccountId: (line: string) => string | undefined,
+): string {
+  const have = [...accounts.keys()];
+  let id = args.account;
+  id ??= args.line ? parseAccountId(args.line) : undefined;
+  id ??= have.length === 1 ? have[0] : undefined;
+  if (id === undefined)
+    throw new Error(`name an account (have: ${have.join(', ')})`);
+  if (!accounts.has(id))
+    throw new Error(`unknown account '${id}' (have: ${have.join(', ')})`);
+  return id;
+}