@stage-labs/metro 0.1.0-beta.172 → 0.1.0-beta.174

package/dist/api.js

@@ -1,9 +1,11 @@
-import { localAgents, localDaemonUp, pickLocalAgent } from './local.js';
+import { localAgent, localDaemonUp } from './local.js';
 import { localUrl } from './runtime.js';
 const NO_DAEMON = `no metro daemon on ${localUrl()} — start one with: metro serve`;
-export async function whoisAuthorized(wanted) {
+export async function whoisAuthorized() {
     if (!(await localDaemonUp()))
         throw new Error(NO_DAEMON);
-    const agent = pickLocalAgent(localAgents(), wanted);
-    return { agent: agent.name, where: localUrl() };
+    const agent = localAgent();
+    if (agent === null)
+        throw new Error('no agent on this machine yet');
+    return { agent: agent.id, where: localUrl() };
 }

package/dist/claude.js

@@ -3,7 +3,7 @@ import { markOnboardingDone, seedChannels } from './onboarding.js';
 import { writeMcpConfig } from './mcp-config.js';
 import { currentRoute, permissionMode, routeModelEnv, systemPrompt } from './route.js';
 import { settingsConflicts, settingsFiles } from './claude-settings.js';
-import { localAgents, pickLocalAgent } from './local.js';
+import { localAgent } from './local.js';
 import { PROVIDER_FLAGS } from './provider-flags.js';
 import { localPort, localUrl } from './runtime.js';
 const CHANNEL_FLAGS = ['--dangerously-load-development-channels', 'server:metro'];
@@ -76,27 +76,8 @@ async function daemonServing(base = localUrl()) {
         return false;
     }
 }
-export function agentKey(agents, wanted) {
-    if (agents.length === 0)
-        return { skip: 'no agent lives on this machine yet, so Claude Code talks to Anthropic directly' };
-    try {
-        return { key: pickLocalAgent(agents, wanted).key };
-    }
-    catch {
-        return {
-            skip: wanted === undefined || wanted === ''
-                ? 'this box has no agent yet (or several old ones), so Claude Code talks to Anthropic directly for now'
-                : `no agent named '${wanted}' lives here, so Claude Code talks to Anthropic directly`,
-        };
-    }
-}
-function localAgentList() {
-    try {
-        return localAgents();
-    }
-    catch {
-        return [];
-    }
+export function agentKey(agent) {
+    return agent === null ? { skip: 'no agent lives on this machine yet, so Claude Code talks to Anthropic directly' } : { key: agent.key };
 }
 async function verdict() {
     const pinned = pinnedBy(process.env);
@@ -105,7 +86,7 @@ async function verdict() {
     const conflicts = settingsConflicts(settingsFiles());
     if (conflicts.length > 0)
         return { skip: `a settings file pins the provider (${conflicts.join(', ')}), so Claude Code keeps it` };
-    const picked = agentKey(localAgentList(), undefined);
+    const picked = agentKey(localAgent());
     if ('skip' in picked)
         return picked;
     if (await daemonServing())
@@ -131,7 +112,7 @@ export function runClaude(args, env) {
 async function servedKey(decision) {
     if ('key' in decision)
         return decision.key;
-    const picked = agentKey(localAgentList(), undefined);
+    const picked = agentKey(localAgent());
     if ('skip' in picked)
         return null;
     return (await daemonServing()) ? picked.key : null;

package/dist/cli.js

@@ -22,7 +22,7 @@ const USAGE = `metro — run your agent on this machine
                   starts at boot and after a crash, so the page can stop, start and
                   restart it with no shell; metro service uninstall and status as well
   metro stop      stop metro on this machine, metro serve included
-  metro tail <agent-id>
+  metro tail [agent-id]
                   follow this machine's inbound events, one JSON line each
   metro whoami    print the agent this machine runs
   metro claude [args...]
@@ -53,8 +53,8 @@ async function stopDaemon() {
 const HELP = new Set([undefined, 'help', '--help', '-h']);
 const COMMANDS = {
     whoami: async () => {
-        const { agent, where } = await whoisAuthorized(process.argv[3]);
-        process.stdout.write(`agent '${agent}' on ${where}\n`);
+        const { agent, where } = await whoisAuthorized();
+        process.stdout.write(`agent ${agent} on ${where}\n`);
         return 0;
     },
     serve: () => serve(process.argv.slice(3)),

package/dist/local.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { localUrl } from './runtime.js';
@@ -7,64 +7,30 @@ export function agentsDir() {
     const explicit = process.env.METRO_AGENTS_DIR?.trim();
     return explicit !== undefined && explicit !== '' ? explicit : join(homedir(), '.metro', 'agents');
 }
-function agentFiles(dir) {
-    const fixed = join(dir, 'agent.json');
-    if (existsSync(fixed))
-        return [fixed];
-    if (!existsSync(dir))
-        return [];
-    return readdirSync(dir, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory())
-        .map((entry) => join(dir, entry.name, 'agent.json'))
-        .filter((path) => existsSync(path));
-}
-export function localAgents(dir = agentsDir()) {
-    const out = [];
-    for (const path of agentFiles(dir)) {
-        try {
-            const file = JSON.parse(readFileSync(path, 'utf8'));
-            if (typeof file.id === 'string' && typeof file.key === 'string')
-                out.push({ id: file.id, name: typeof file.name === 'string' ? file.name : 'agent', key: file.key });
-        }
-        catch {
-            continue;
-        }
+function agentFile(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, 'agent.json'), 'utf8'));
+    }
+    catch {
+        return null;
     }
-    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function localAgent(dir = agentsDir()) {
+    const file = agentFile(dir);
+    return typeof file?.id === 'string' && typeof file.key === 'string' ? { id: file.id, key: file.key } : null;
 }
 export function localStations(dir = agentsDir()) {
+    const stations = agentFile(dir)?.stations;
+    if (!Array.isArray(stations))
+        return [];
     const out = new Set();
-    for (const path of agentFiles(dir)) {
-        try {
-            const file = JSON.parse(readFileSync(path, 'utf8'));
-            if (!Array.isArray(file.stations))
-                continue;
-            for (const s of file.stations) {
-                const station = s.station;
-                if (typeof station === 'string')
-                    out.add(station);
-            }
-        }
-        catch {
-            continue;
-        }
+    for (const s of stations) {
+        const station = s.station;
+        if (typeof station === 'string')
+            out.add(station);
     }
     return [...out].sort();
 }
-export function pickLocalAgent(agents, wanted) {
-    if (wanted !== undefined && wanted !== '') {
-        const found = agents.find((a) => a.name === wanted || a.id === wanted);
-        if (found === undefined)
-            throw new Error(`no local agent named '${wanted}'`);
-        return found;
-    }
-    const only = agents[0];
-    if (only !== undefined && agents.length === 1)
-        return only;
-    throw new Error(agents.length === 0
-        ? 'no agent on this machine yet'
-        : `several agents on this machine — name one: ${agents.map((a) => a.name).join(', ')}`);
-}
 export async function localDaemonUp(base = localUrl()) {
     try {
         const res = await fetch(`${base}/api/mode`, { signal: AbortSignal.timeout(PROBE_MS) });

package/dist/serve.js

@@ -8,7 +8,7 @@ import { findBun, localPort, spawnPlan } from './runtime.js';
 import { prepareRuntime } from './runtime-install.js';
 import { ensureNodeName } from './node-name.js';
 import { holdUntilStart } from './hold.js';
-const SCRUBBED = new Set(['METRO_RUN_TOKEN', 'METRO_AGENT', 'DATABASE_URL']);
+const SCRUBBED = new Set(['DATABASE_URL']);
 const PORT_FLAG = /^--port=(.*)$/;
 const OWNER_FLAG = /^--owner=(.*)$/;
 const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
@@ -24,14 +24,14 @@ function portOf(raw) {
 const ORGANIZATION = /^org_[A-Za-z0-9]{10,64}$/;
 function ownerOf(raw) {
     if (raw !== undefined && ORGANIZATION.test(raw))
-        return raw;
-    if (raw === undefined || !ADDRESS.test(raw))
-        throw new Error(`'${raw ?? ''}' is neither an organization id (org_…) nor an Ethereum address — ${USAGE}`);
-    return raw.toLowerCase();
+        return { owner: raw };
+    if (raw !== undefined && ADDRESS.test(raw))
+        return { owner: null, ignoredOwner: raw };
+    throw new Error(`'${raw ?? ''}' is not an organization id (org_…) — ${USAGE}`);
 }
 export function parseServeArgs(argv) {
     let port = localPort();
-    let owner = null;
+    let owner = { owner: null };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i] ?? '';
         if (TUNNEL_FLAG.test(arg))
@@ -58,10 +58,14 @@ export function parseServeArgs(argv) {
         }
         throw new Error(`unknown argument '${arg}' — ${USAGE}`);
     }
-    return { port, owner };
+    return { port, ...owner };
 }
-export function requireOwner(owner, dir = agentsDir()) {
-    if (owner !== null || existsSync(join(dir, '.owner')))
+export function requireOwner(args, dir = agentsDir()) {
+    if (args.ignoredOwner !== undefined) {
+        process.stderr.write(`--owner ${args.ignoredOwner} is a wallet address, which metro ignores: the organization id in ${join(dir, '.owner')} decides who signs in\n`);
+        return;
+    }
+    if (args.owner !== null || existsSync(join(dir, '.owner')))
         return;
     throw new Error('no owner is set for this machine, so nobody could sign in.\n' +
         'Pass the organization that owns it once; it is remembered in ' +
@@ -71,9 +75,7 @@ export function requireOwner(owner, dir = agentsDir()) {
 export function readOwner(dir = agentsDir()) {
     try {
         const raw = readFileSync(join(dir, '.owner'), 'utf8').trim();
-        if (ORGANIZATION.test(raw))
-            return raw;
-        return ADDRESS.test(raw.toLowerCase()) ? raw.toLowerCase() : null;
+        return ORGANIZATION.test(raw) ? raw : null;
     }
     catch {
         return null;
@@ -142,12 +144,13 @@ export function servePlan(opts) {
     };
 }
 export function serve(argv) {
-    const { port, owner } = parseServeArgs(argv);
+    const args = parseServeArgs(argv);
+    const { port, owner } = args;
     const running = serveLockedBy();
     if (running !== null)
         throw new Error(`a metro serve daemon is already running on this machine (pid ${String(running)}). ` +
             'Stop it first: metro stop');
-    requireOwner(owner);
+    requireOwner(args);
     const tailscaleBin = findTailscale();
     const node = ensureNodeName(tailscaleBin);
     process.stderr.write(`Starting a metro daemon of your own on http://127.0.0.1:${String(port)}, published as ${node} on your tailnet\n`);

package/dist/service.js

@@ -126,13 +126,13 @@ export function servicePlan(host, serveArgs) {
     throw new Error(`metro service supports Linux (systemd) and macOS (launchd), not ${host.platform}`);
 }
 function install(serveArgs, deps) {
-    const { owner } = parseServeArgs(serveArgs);
+    const args = parseServeArgs(serveArgs);
     const plan = servicePlan(deps.host, serveArgs);
     if (deps.exists(plan.file)) {
         deps.out(`metro is already installed as a ${plan.kind} service (${plan.file}) and restarts on its own; metro service status says whether it is running. To change its arguments: metro service uninstall, then install again`);
         return 0;
     }
-    deps.preflight(owner);
+    deps.preflight(args);
     const pid = deps.running();
     if (pid !== null)
         throw new Error(`a metro serve is running on this machine (pid ${String(pid)}). Stop it first (metro stop), then install: the service takes over from there`);
@@ -209,8 +209,8 @@ function realDeps() {
             return { status: code, output: `${result.stdout}${result.stderr}` };
         },
         running: serveLockedBy,
-        preflight: (owner) => {
-            requireOwner(owner);
+        preflight: (args) => {
+            requireOwner(args);
             findBun();
             findTailscale();
         },

package/dist/tail.js

@@ -1,4 +1,4 @@
-import { localAgents } from './local.js';
+import { localAgent } from './local.js';
 import { assertAgentId, localUrl } from './runtime.js';
 const BACKOFF_MS = [1_000, 2_000, 5_000];
 const STALL_MS = 90_000;
@@ -22,9 +22,9 @@ function keySource(agentId) {
         return { resolve: () => Promise.resolve(fromEnv), fixed: true };
     return {
         resolve: () => {
-            const agent = localAgents().find((a) => a.id === agentId);
-            if (agent === undefined)
-                throw new Error(`no agent ${agentId} on this machine — create or restore it in the web UI of metro serve, or set METRO_AGENT_KEY`);
+            const agent = localAgent();
+            if (agent === null || (agentId !== undefined && agent.id !== agentId))
+                throw new Error(`no agent ${agentId === undefined ? '' : `${agentId} `}on this machine — start metro serve, or set METRO_AGENT_KEY`);
             return Promise.resolve(agent.key);
         },
         fixed: false,
@@ -89,7 +89,7 @@ function note(state, message) {
     process.stderr.write(`metro: ${message}\n`);
 }
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-async function settle(end, source, key, agentId, state) {
+async function settle(end, source, key, state) {
     if (end === 'unauthorized') {
         if (source.fixed)
             throw new Error('the key in METRO_AGENT_KEY was refused by the local daemon');
@@ -97,13 +97,13 @@ async function settle(end, source, key, agentId, state) {
         return source.resolve();
     }
     if (end === 'unreachable')
-        note(state, `no metro daemon on ${localUrl()} — run 'metro serve' (agent ${agentId})`);
+        note(state, `no metro daemon on ${localUrl()} — run 'metro serve'`);
     else
         note(state, 'stream ended — reconnecting');
     return key;
 }
 export async function tailEvents(argv) {
-    const agentId = assertAgentId(argv[0]);
+    const agentId = argv[0] === undefined ? undefined : assertAgentId(argv[0]);
     const source = keySource(agentId);
     let key = await source.resolve();
     const state = { last: '' };
@@ -112,7 +112,7 @@ export async function tailEvents(argv) {
         const end = await streamOnce(key);
         if (end === 'ended')
             attempt = 0;
-        key = await settle(end, source, key, agentId, state);
+        key = await settle(end, source, key, state);
         await delay(backoffAt(attempt));
         attempt += 1;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.172",
+  "version": "0.1.0-beta.174",
   "description": "The metro command line. Sign in once per machine, then hand your MCP connector list to Claude Code without the credentials touching disk, argv or shell history.",
   "license": "MIT",
   "repository": {

package/runtime/marketplace/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "metro",
-  "version": "0.1.0-beta.172",
+  "version": "0.1.0-beta.174",
   "description": "Metro for Claude Code, installed by the metro daemon on this machine: every connector the agent holds as its own MCP server relayed through the daemon, the orchestrator-only guard on the main thread, and the standing rules loaded at each session start. No vendor credential ever sits in a config file.",
   "author": {
     "name": "Bonustrack",

package/runtime/marketplace/plugin/bin/metro-plugin.mjs

@@ -1,30 +1,20 @@
 #!/usr/bin/env node
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 const agentsDir = () => process.env.METRO_AGENTS_DIR || join(homedir(), '.metro', 'agents');
 
-function readAgent(path) {
+function readAgent() {
+  const path = join(agentsDir(), 'agent.json');
+  let parsed;
   try {
-    const parsed = JSON.parse(readFileSync(path, 'utf8'));
-    return typeof parsed?.key === 'string' ? parsed : null;
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
   } catch {
-    return null;
+    throw new Error(`no agent on this machine yet (${path})`);
   }
-}
-
-function pickAgent() {
-  const dir = agentsDir();
-  const fixed = readAgent(join(dir, 'agent.json'));
-  if (fixed !== null) return fixed;
-  if (!existsSync(dir)) throw new Error(`no agent on this machine yet (${dir})`);
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const found = readAgent(join(dir, entry.name, 'agent.json'));
-    if (found !== null) return found;
-  }
-  throw new Error(`no agent on this machine yet (${dir})`);
+  if (typeof parsed?.key !== 'string') throw new Error(`no agent key in ${path}`);
+  return parsed;
 }
 
 if (process.argv[2] !== 'headers') {
@@ -33,7 +23,7 @@ if (process.argv[2] !== 'headers') {
 }
 
 try {
-  process.stdout.write(`${JSON.stringify({ Authorization: `Bearer ${pickAgent().key}` })}\n`);
+  process.stdout.write(`${JSON.stringify({ Authorization: `Bearer ${readAgent().key}` })}\n`);
 } catch (err) {
   process.stderr.write(`metro: ${err.message}\n`);
   process.stdout.write('{}\n');

package/runtime/node_modules/@metro-labs/core/package.json

@@ -7,14 +7,13 @@
   "exports": {
     "./log": "./src/log.ts",
     "./events": "./src/events.ts",
-    "./identity": "./src/identity.ts",
     "./is-record": "./src/is-record.ts",
     "./secure-fs": "./src/secure-fs.ts",
     "./version": "./src/version.ts",
     "./train-error": "./src/train-error.ts",
     "./trains/protocol": "./src/protocol.ts",
     "./ids": "./src/ids.ts",
-    "./address": "./src/address.ts",
+    "./tickets": "./src/tickets.ts",
     "./station-names": "./src/station-names.ts",
     "./str": "./src/str.ts",
     "./lines": "./src/lines.ts",
@@ -25,7 +24,9 @@
     "./stations/attachments": "./src/stations/attachments.ts",
     "./stations/messaging-normalize": "./src/stations/messaging-normalize.ts",
     "./stations/profile": "./src/stations/profile.ts",
-    "./stations/sender-profile": "./src/stations/sender-profile.ts"
+    "./stations/sender-profile": "./src/stations/sender-profile.ts",
+    "./stations/train-events": "./src/stations/train-events.ts",
+    "./stations/train-boot": "./src/stations/train-boot.ts"
   },
   "scripts": {
     "build": "tsc",

package/runtime/node_modules/@metro-labs/core/src/events.ts

@@ -1,4 +1,3 @@
-import { randomBytes } from 'node:crypto';
 import { Line } from './lines.js';
 
 export { userSelf, daemonSelf } from './identity.js';
@@ -74,8 +73,7 @@ export function formatDisplay(e: MetroEvent): string {
   return `${headerFor('📩', [e.station, e.fromName ?? e.from, e.lineName])}\n> ${body}`;
 }
 
-export const mintId = (): string =>
-  `msg_${randomBytes(6).toString('base64url')}`;
+export { mintId } from './ids.js';
 
 export type BusListener = (event: MetroEvent, busSeq: number) => void;
 

package/runtime/node_modules/@metro-labs/core/src/ids.ts

@@ -5,6 +5,9 @@ const REROLLS = 16;
 
 export const ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{10}$/;
 
+export const mintId = (): string =>
+  `msg_${randomBytes(6).toString('base64url')}`;
+
 export function newId(): string {
   for (let attempt = 0; attempt < REROLLS; attempt += 1) {
     const id = randomBytes(ID_BYTES).toString('base64url');

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

@@ -38,6 +38,23 @@ export function writeSecure(path: string, data: string): void {
   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,

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

@@ -10,4 +10,3 @@ export const STATIONS = [
 
 export type StationName = (typeof STATIONS)[number];
 
-export type ConnectorTransport = 'http' | 'sse';

package/runtime/node_modules/@metro-labs/core/src/stations/station-runtime.ts

@@ -12,8 +12,7 @@ export const respond = (
     JSON.stringify({ op: 'response', id, ...body }) + '\n',
   );
 
-export const mintId = (): string =>
-  `msg_${Math.random().toString(36).slice(2, 10)}`;
+export { mintId } from '../ids.js';
 
 type Args = Record<string, unknown>;
 
@@ -29,13 +28,12 @@ export type StationHandler = (id: string, args: Args) => void | Promise<void>;
 export interface StationConfig {
   handlers: Record<string, StationHandler>;
   normalize: (action: string, args: Args) => Normalized;
-  preDispatch?: (id: string, action: string) => boolean;
 }
 
 const lineTag = (args: Args): string =>
   typeof args.line === 'string' ? args.line : '?';
 
-export function makeStation({ handlers, normalize, preDispatch }: StationConfig) {
+export function makeStation({ handlers, normalize }: StationConfig) {
   const known = Object.keys(handlers).join(', ');
   return async function handleCall(msg: CallMsg): Promise<void> {
     const { id } = msg;
@@ -44,7 +42,6 @@ export function makeStation({ handlers, normalize, preDispatch }: StationConfig)
     try {
       ({ action, args } = normalize(msg.action, msg.args));
       emit({ op: 'log', text: `call ${action} recv (line=${lineTag(args)})` });
-      if (preDispatch?.(id, action)) return;
       const handler = handlers[action];
       if (!handler) {
         respond(id, { error: `unknown action '${action}' (have: ${known})` });

package/runtime/node_modules/@metro-labs/core/src/stations/train-boot.ts

@@ -0,0 +1,42 @@
+import { errMsg } from '../log.js';
+import { readCalls } from '../protocol.js';
+import { TrainError } from '../train-error.js';
+import type { CallMsg } from './station-runtime.js';
+
+export function announceAccounts(station: string, ids: Iterable<string>): void {
+  const list = [...ids];
+  if (list.length === 0) {
+    process.stderr.write(`${station}: no accounts booted, exiting\n`);
+    process.exit(2);
+  }
+  process.stderr.write(`${station} train ready — ${String(list.length)} account(s): ${list.join(', ')}\n`);
+}
+
+export interface ClientTrain<A extends { id: string }, C> {
+  station: string;
+  accounts: Map<string, A>;
+  loadAccounts: () => A[];
+  createClient: (account: A) => C;
+  startInbound: (client: C) => Promise<void>;
+  makeHandleCall: (clientFor: (accountId: string) => C) => (msg: CallMsg) => Promise<void>;
+}
+
+export function runClientTrain<A extends { id: string }, C>(train: ClientTrain<A, C>): void {
+  const clients = new Map<string, C>();
+  const clientFor = (accountId: string): C => {
+    const known = clients.get(accountId);
+    if (known !== undefined) return known;
+    const account = train.accounts.get(accountId);
+    if (!account) throw new TrainError('not_implemented', `unknown account '${accountId}'`);
+    const client = train.createClient(account);
+    clients.set(accountId, client);
+    return client;
+  };
+  readCalls(train.station, train.makeHandleCall(clientFor));
+  for (const cfg of train.loadAccounts()) train.accounts.set(cfg.id, cfg);
+  for (const id of train.accounts.keys())
+    train.startInbound(clientFor(id)).catch((err: unknown) => {
+      process.stderr.write(`${train.station}[${id}] inbound failed: ${errMsg(err)}\n`);
+    });
+  announceAccounts(train.station, train.accounts.keys());
+}

package/runtime/node_modules/@metro-labs/core/src/stations/train-events.ts

@@ -0,0 +1,89 @@
+import { mintId } from '../ids.js';
+import { emit } from './station-runtime.js';
+
+type Fields = Record<string, unknown>;
+type Out = (e: unknown) => void;
+
+export const selfUri = (station: string, account?: string): string =>
+  process.env.METRO_SELF_URI ??
+  (account === undefined ? `metro://${station}/self` : `metro://${station}/${account}/self`);
+
+export function emitInbound(account: string, e: Fields, out: Out = emit): void {
+  out({
+    kind: 'inbound',
+    ...e,
+    account,
+    payload: { ...(e.payload as Fields | undefined), account },
+  });
+}
+
+export interface AttachmentAt {
+  station: string;
+  account: string;
+  line: string;
+  forId: string;
+  index: number;
+  from?: string;
+}
+
+export interface SavedFile {
+  path: string;
+  mime?: string;
+  name?: string;
+}
+
+function attachmentEvent(at: AttachmentAt, text: string, payload: Fields): Fields {
+  return {
+    kind: 'inbound',
+    id: mintId(),
+    ts: new Date().toISOString(),
+    station: at.station,
+    line: at.line,
+    from: at.from ?? selfUri(at.station, at.account),
+    text,
+    account: at.account,
+    payload: { account: at.account, attachmentFor: at.forId, index: at.index, ...payload },
+  };
+}
+
+export const attachmentSavedEvent = (at: AttachmentAt & { saved: SavedFile; extra?: Fields }): Fields =>
+  attachmentEvent(at, `📎 saved: ${at.saved.path}`, {
+    contentType: 'attachmentSaved',
+    ...at.extra,
+    attachmentPath: at.saved.path,
+    localPath: at.saved.path,
+    mime: at.saved.mime,
+    name: at.saved.name,
+  });
+
+export const attachmentFailedEvent = (at: AttachmentAt & { reason: string; extra?: Fields }): Fields =>
+  attachmentEvent(at, `📎 not fetched: ${at.reason}`, {
+    contentType: 'attachmentFailed',
+    ...at.extra,
+    reason: at.reason,
+  });
+
+const reasonOf = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+export function reportAttachment(
+  save: Promise<SavedFile>,
+  at: AttachmentAt,
+  extra: { saved?: Fields; failed?: Fields } = {},
+  out: Out = emit,
+): void {
+  const tag = `${at.station}[${at.account}]`;
+  save
+    .then(
+      (saved) => {
+        out(attachmentSavedEvent({ ...at, saved, extra: extra.saved }));
+      },
+      (err: unknown) => {
+        const reason = reasonOf(err);
+        process.stderr.write(`${tag} attachment save failed: ${reason}\n`);
+        out(attachmentFailedEvent({ ...at, reason, extra: extra.failed }));
+      },
+    )
+    .catch((err: unknown) => {
+      process.stderr.write(`${tag} attachment event not emitted: ${reasonOf(err)}\n`);
+    });
+}