@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

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

@@ -0,0 +1,212 @@
+import { mintId } from '../ids.js';
+import { Line } from '../lines.js';
+import { TrainError } from '../train-error.js';
+import { capText } from './mail-text.js';
+
+export type MailStation = 'outlook' | 'gmail';
+
+type Args = Record<string, unknown>;
+
+export interface MailItem {
+  id: string;
+  threadId: string;
+  subject: string;
+  from: string;
+  fromName: string;
+  to: string[];
+  cc: string[];
+  date: string | null;
+  preview: string;
+  text: string;
+  hasAttachments: boolean;
+  isRead: boolean;
+  internetMessageId: string | null;
+}
+
+export interface AttachmentMeta {
+  kind: string;
+  name: string;
+  mime: string;
+  size?: number;
+}
+
+export interface OutgoingFile {
+  path: string;
+  mime: string;
+  name: string;
+}
+
+export interface ReadQuery {
+  threadId: string | null;
+  query: string;
+  from: string;
+  since: string;
+  until: string;
+  before: string;
+  unreadOnly: boolean;
+  limit: number;
+}
+
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 50;
+const SEEN_MAX = 500;
+const SUBJECT_MAX = 255;
+const ADDRESS_RE = /^[^@\s/]+@[^@\s/]+\.[^@\s/]+$/;
+
+export interface MailService {
+  station: MailStation;
+  company: string;
+  product: string;
+  api: string;
+  apiCode: string;
+}
+
+export function refusalOf(s: MailService, status: number, detail: string): TrainError {
+  const refuse = (code: string, text: string, retryable = false): TrainError => new TrainError(`${s.station}_${code}`, text, { retryable });
+  if (status === 401) return refuse('signed_out', `${s.company} refused this mailbox's sign-in (${detail}); connect ${s.product} again from the page`);
+  if (status === 403) return refuse('forbidden', `${s.company} does not let Metro do that on this mailbox (${detail})`);
+  if (status === 404) return refuse('not_found', `${s.product} has no such message or conversation (${detail})`);
+  if (status === 413) return refuse('too_large', `${s.product} refused the size of that request (${detail})`);
+  if (status === 429) return refuse('throttled', `${s.company} asked Metro to slow down (${detail}); try again in a minute`, true);
+  return refuse(s.apiCode, `${s.api} answered ${String(status)} (${detail})`, status >= 500);
+}
+
+export const str = (v: unknown): string => (typeof v === 'string' ? v.trim() : '');
+
+const encodeResource = (id: string): string => id.replace(/%/g, '%25').replace(/\//g, '%2F').replace(/\+/g, '%2B');
+
+export const mailLine = (station: MailStation, accountId: string, threadId: string): string =>
+  `metro://${station}/${accountId}/${encodeResource(threadId)}`;
+
+const mailUser = (station: MailStation, accountId: string, address: string): string =>
+  `metro://${station}/${accountId}/user/${address.toLowerCase()}`;
+
+export function threadOfLine(station: MailStation, line: string): { accountId: string; threadId: string } | null {
+  const parsed = Line.parseMail(line, station);
+  if (parsed === null) return null;
+  try {
+    return { accountId: parsed.accountId, threadId: decodeURIComponent(parsed.resource) };
+  } catch {
+    return null;
+  }
+}
+
+const isPrivateTo = (m: MailItem, self: string): boolean => m.to.length === 1 && m.to[0] === self && m.cc.length === 0;
+
+export function mailEnvelope(station: MailStation, accountId: string, self: string, m: MailItem, attachments: AttachmentMeta[], verified: boolean): Record<string, unknown> {
+  const body = capText(m.text);
+  return {
+    id: mintId(),
+    ts: m.date ?? new Date().toISOString(),
+    station,
+    line: mailLine(station, accountId, m.threadId),
+    line_name: m.subject === '' ? '(no subject)' : m.subject,
+    from: mailUser(station, accountId, m.from === '' ? 'unknown' : m.from),
+    from_name: m.fromName || m.from,
+    from_display_name: m.fromName || undefined,
+    message_id: m.id,
+    text: m.subject === '' ? body : `Subject: ${m.subject}\n\n${body}`,
+    is_private: isPrivateTo(m, self),
+    sender_verified: verified,
+    payload: {
+      from: m.from,
+      to: m.to,
+      cc: m.cc,
+      subject: m.subject,
+      internetMessageId: m.internetMessageId,
+      ...(attachments.length === 0 ? {} : { attachments }),
+    },
+  };
+}
+
+const heading = (station: MailStation, accountId: string, m: MailItem): Record<string, unknown> => ({
+  message_id: m.id,
+  line: mailLine(station, accountId, m.threadId),
+  from: m.from,
+  from_name: m.fromName,
+  date: m.date,
+  title: m.subject,
+});
+
+export const mailSummary = (station: MailStation, accountId: string, m: MailItem): Record<string, unknown> => ({
+  ...heading(station, accountId, m),
+  text_preview: m.preview,
+  has_attachments: m.hasAttachments,
+  is_read: m.isRead,
+});
+
+export const mailFull = (station: MailStation, accountId: string, m: MailItem): Record<string, unknown> => ({
+  ...heading(station, accountId, m),
+  has_attachments: m.hasAttachments,
+  is_read: m.isRead,
+  to: m.to,
+  cc: m.cc,
+  text: capText(m.text),
+});
+
+export const isAddress = (target: string): boolean => target.includes('@');
+
+export const isEmailAddress = (value: string): boolean => ADDRESS_RE.test(value);
+
+export function checkAddress(station: MailStation, to: string): void {
+  if (!isEmailAddress(to)) throw new TrainError(`${station}_bad_address`, `not an email address: ${to}`, { retryable: false });
+}
+
+export function subjectOf(station: MailStation, subject: string, text: string): string {
+  const chosen = subject !== '' ? subject : (text.split('\n').find((l) => l.trim() !== '') ?? '').trim();
+  if (chosen === '') throw new TrainError(`${station}_subject_required`, 'a new email needs a subject or some text', { retryable: false });
+  return chosen.length > SUBJECT_MAX ? `${chosen.slice(0, SUBJECT_MAX - 3)}...` : chosen;
+}
+
+export const filesOf = (raw: unknown): OutgoingFile[] =>
+  (Array.isArray(raw) ? raw : [])
+    .map((a) => (a ?? {}) as Record<string, unknown>)
+    .filter((a) => typeof a.path === 'string' && a.path !== '')
+    .map((a) => ({
+      path: String(a.path),
+      mime: typeof a.mime === 'string' && a.mime !== '' ? a.mime : 'application/octet-stream',
+      name: typeof a.name === 'string' && a.name !== '' ? a.name : 'file',
+    }));
+
+function isoOf(station: MailStation, raw: string, field: string): string {
+  if (raw === '') return '';
+  const at = Date.parse(raw);
+  if (Number.isNaN(at)) throw new TrainError(`${station}_bad_date`, `${field} must be a date, for example 2026-09-24 or 2026-09-24T10:00:00Z`, { retryable: false });
+  return new Date(at).toISOString();
+}
+
+export function readQueryOf(station: MailStation, args: Args): ReadQuery {
+  const line = str(args.line);
+  const thread = line === '' ? null : threadOfLine(station, line);
+  if (line !== '' && thread === null) throw new TrainError(`${station}_bad_line`, `not a valid ${station} line: ${line}`, { retryable: false });
+  return {
+    threadId: thread?.threadId ?? null,
+    query: str(args.query),
+    from: str(args.from).toLowerCase(),
+    since: isoOf(station, str(args.since), 'since'),
+    until: isoOf(station, str(args.until), 'until'),
+    before: str(args.before),
+    unreadOnly: args.unreadOnly === true,
+    limit: typeof args.limit === 'number' && args.limit > 0 ? Math.min(Math.floor(args.limit), MAX_LIMIT) : DEFAULT_LIMIT,
+  };
+}
+
+export const seenOf = (raw: unknown): string[] => (Array.isArray(raw) ? raw.filter((s): s is string => typeof s === 'string') : []);
+
+export function noteSeen(seen: string[], messageId: string): void {
+  seen.push(messageId);
+  if (seen.length > SEEN_MAX) seen.splice(0, seen.length - SEEN_MAX);
+}
+
+export function pollForever(tag: string, once: () => Promise<unknown>, intervalMs: number): void {
+  const tick = (): void => {
+    once()
+      .catch((err: unknown) => {
+        process.stderr.write(`${tag} mail check failed: ${err instanceof Error ? err.message : String(err)}\n`);
+      })
+      .finally(() => {
+        setTimeout(tick, intervalMs);
+      });
+  };
+  tick();
+}

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

@@ -0,0 +1,16 @@
+type Args = Record<string, unknown>;
+
+export interface Normalized {
+  action: string;
+  args: Args;
+}
+
+export type Normalize = (action: string, args: Args) => Normalized;
+
+export const messagingAliases =
+  (removal: Args = { emoji: '' }): Normalize =>
+  (action, args) => {
+    if (action === 'reply') return { action: 'send', args };
+    if (action === 'unreact') return { action: 'react', args: { ...args, ...removal } };
+    return { action, args };
+  };

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

@@ -0,0 +1,126 @@
+import { createHash, randomBytes } from 'node:crypto';
+
+export class SignInError extends Error {}
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export type OAuthBody = Record<string, unknown>;
+
+export interface Tokens {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+}
+
+export interface Pkce {
+  verifier: string;
+  challenge: string;
+}
+
+const RENEW_BEFORE_MS = 5 * 60_000;
+const MAILBOX_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+const text = (v: unknown): string => (typeof v === 'string' ? v : '');
+
+export const seconds = (v: unknown, fallback: number): number =>
+  typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : fallback;
+
+export function envValue(name: string, fallback: string): string {
+  const value = (process.env[name] ?? '').trim();
+  return value === '' ? fallback : value;
+}
+
+export const envUrl = (name: string, fallback: string): string => envValue(name, fallback).replace(/\/+$/, '');
+
+export function pkcePair(verifier = randomBytes(32).toString('base64url')): Pkce {
+  return { verifier, challenge: createHash('sha256').update(verifier).digest('base64url') };
+}
+
+export const newState = (): string => randomBytes(24).toString('base64url');
+
+export function parseMailbox(value: unknown): string | null {
+  const mailbox = (typeof value === 'string' ? value.trim() : '').toLowerCase();
+  if (mailbox === '') return null;
+  if (!MAILBOX_RE.test(mailbox))
+    throw new SignInError('Type the whole address of the mailbox, like andy@company.com, or leave it blank.');
+  return mailbox;
+}
+
+export async function postForm(url: string, fields: Record<string, string>, fetchImpl: FetchLike, provider: string): Promise<{ status: number; body: OAuthBody }> {
+  let res: Response;
+  try {
+    res = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+      body: new URLSearchParams(fields).toString(),
+    });
+  } catch (err) {
+    throw new SignInError(`Metro could not reach ${provider}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const raw: unknown = await res.json().catch(() => ({}));
+  return { status: res.status, body: typeof raw === 'object' && raw !== null ? (raw as OAuthBody) : {} };
+}
+
+export function tokensOf(body: OAuthBody, now: number, provider: string, previous?: string): Tokens {
+  const accessToken = text(body.access_token);
+  const refreshToken = text(body.refresh_token) || (previous ?? '');
+  if (accessToken === '' || refreshToken === '') throw new SignInError(`${provider} answered without the tokens Metro needs.`);
+  return { accessToken, refreshToken, expiresAt: now + seconds(body.expires_in, 3600) * 1000 };
+}
+
+export function tokenStateOf(saved: OAuthBody, seed: Partial<Tokens>): Tokens {
+  const fromFile = text(saved.refreshToken) !== '';
+  return {
+    refreshToken: fromFile ? text(saved.refreshToken) : text(seed.refreshToken),
+    accessToken: fromFile ? text(saved.accessToken) : text(seed.accessToken),
+    expiresAt: fromFile ? Number(saved.expiresAt) || 0 : Number(seed.expiresAt) || 0,
+  };
+}
+
+export class TokenKeeper {
+  private refreshing: Promise<string> | null = null;
+
+  constructor(
+    private readonly state: Tokens,
+    private readonly renewWith: (refreshToken: string) => Promise<Tokens>,
+    private readonly renewed: () => void,
+  ) {}
+
+  token(force = false): Promise<string> {
+    const fresh = this.state.accessToken !== '' && this.state.expiresAt - RENEW_BEFORE_MS > Date.now();
+    if (fresh && !force) return Promise.resolve(this.state.accessToken);
+    this.refreshing ??= this.renew().finally(() => {
+      this.refreshing = null;
+    });
+    return this.refreshing;
+  }
+
+  private async renew(): Promise<string> {
+    Object.assign(this.state, await this.renewWith(this.state.refreshToken));
+    this.renewed();
+    return this.state.accessToken;
+  }
+}
+
+export interface BrowserFlow<R> {
+  authorize: (challenge: string, state: string) => string;
+  redeem: (code: string, verifier: string) => Promise<R>;
+}
+
+export class BrowserSignIn<R> {
+  readonly state = newState();
+  readonly authorizeUrl: string;
+  private readonly pkce = pkcePair();
+  private used = false;
+
+  constructor(private readonly flow: BrowserFlow<R>) {
+    this.authorizeUrl = flow.authorize(this.pkce.challenge, this.state);
+  }
+
+  async finish(code: string, state: string): Promise<R> {
+    if (state !== this.state) throw new SignInError('This sign-in link belongs to another attempt. Start again from the Channels page.');
+    if (this.used) throw new SignInError('This sign-in was already used. Start again from the Channels page.');
+    this.used = true;
+    return this.flow.redeem(code, this.pkce.verifier);
+  }
+}

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

@@ -0,0 +1,58 @@
+import { TrainError } from '../train-error.js';
+
+export const PROFILE_FIELDS = ['name', 'bio', 'avatar'] as const;
+export type ProfileField = (typeof PROFILE_FIELDS)[number];
+
+export const NAME_MAX = 64;
+export const BIO_MAX = 512;
+
+export interface ProfileAvatar {
+  path: string;
+  mime: string;
+  name: string;
+}
+
+export interface ProfileChange {
+  name?: string;
+  bio?: string;
+  avatar?: ProfileAvatar;
+}
+
+export interface ProfileApplied {
+  account: string;
+  applied: ProfileField[];
+}
+
+const text = (value: unknown, field: string, max: number): string | undefined => {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string') throw new TrainError('bad_request', `${field} must be a string`);
+  const trimmed = value.trim();
+  if (trimmed === '') throw new TrainError('bad_request', `${field} cannot be empty`);
+  if (trimmed.length > max) throw new TrainError('bad_request', `${field} is over ${String(max)} characters`);
+  return trimmed;
+};
+
+function avatarOf(value: unknown): ProfileAvatar | undefined {
+  if (value === undefined) return undefined;
+  const raw = (value ?? {}) as Record<string, unknown>;
+  if (typeof raw.path !== 'string' || raw.path === '') throw new TrainError('bad_request', 'avatar needs a local file');
+  return { path: raw.path, mime: typeof raw.mime === 'string' ? raw.mime : 'application/octet-stream', name: typeof raw.name === 'string' ? raw.name : 'avatar' };
+}
+
+export function parseProfileChange(args: Record<string, unknown>): ProfileChange {
+  const change: ProfileChange = {};
+  const name = text(args.name, 'name', NAME_MAX);
+  const bio = text(args.bio, 'bio', BIO_MAX);
+  const avatar = avatarOf(args.avatar);
+  if (name !== undefined) change.name = name;
+  if (bio !== undefined) change.bio = bio;
+  if (avatar !== undefined) change.avatar = avatar;
+  if (Object.keys(change).length === 0) throw new TrainError('bad_request', 'set_profile needs at least one of name, bio, avatar');
+  return change;
+}
+
+export const fieldsOf = (change: ProfileChange): ProfileField[] => PROFILE_FIELDS.filter((f) => change[f] !== undefined);
+
+export const assertImage = (avatar: ProfileAvatar): void => {
+  if (!avatar.mime.startsWith('image/')) throw new TrainError('bad_request', `avatar must be an image, not ${avatar.mime}`);
+};

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

@@ -0,0 +1,64 @@
+export interface SenderProfile {
+  id: string;
+  name?: string;
+  display_name?: string;
+  about?: string;
+  avatar?: string;
+  address?: string;
+}
+
+export interface ProfileCacheOptions {
+  ttlMs?: number;
+  max?: number;
+  onError: (key: string, err: unknown) => void;
+}
+
+export interface ProfileCache<T> {
+  get(key: string): Promise<T | null>;
+  peek(key: string): T | null;
+}
+
+const TTL_MS = 10 * 60_000;
+const MAX = 2000;
+
+interface Held<T> {
+  at: number;
+  value: Promise<T | null>;
+  settled: T | null;
+}
+
+export const nonEmpty = (v: unknown): string | undefined => (typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined);
+
+export function makeProfileCache<T>(lookup: (key: string) => Promise<T | null>, opts: ProfileCacheOptions): ProfileCache<T> {
+  const ttl = opts.ttlMs ?? TTL_MS;
+  const max = opts.max ?? MAX;
+  const cache = new Map<string, Held<T>>();
+  const fresh = (key: string): Held<T> | undefined => {
+    const held = cache.get(key);
+    return held !== undefined && Date.now() - held.at < ttl ? held : undefined;
+  };
+  const start = (key: string): Held<T> => {
+    const held: Held<T> = { at: Date.now(), settled: null, value: Promise.resolve(null) };
+    held.value = lookup(key)
+      .then((value) => {
+        held.settled = value;
+        return value;
+      })
+      .catch((err: unknown) => {
+        opts.onError(key, err);
+        cache.delete(key);
+        return null;
+      });
+    cache.set(key, held);
+    while (cache.size > max) {
+      const oldest = cache.keys().next();
+      if (oldest.done) break;
+      cache.delete(oldest.value);
+    }
+    return held;
+  };
+  return {
+    get: (key) => (fresh(key) ?? start(key)).value,
+    peek: (key) => (fresh(key) ?? start(key)).settled,
+  };
+}

package/runtime/node_modules/@metro-labs/{mcp → core}/src/stations/station-runtime.ts

@@ -1,5 +1,5 @@
-import { serializeTrainError, type TrainErrorInfo } from '../daemon/train-error.js';
-import type { Normalized } from './messaging-normalize.js';
+import { serializeTrainError, type TrainErrorInfo } from '../train-error.js';
+import type { Normalize } from './messaging-normalize.js';
 
 export const emit = (e: unknown): void =>
   void process.stdout.write(JSON.stringify(e) + '\n');
@@ -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>;
 
@@ -28,30 +27,26 @@ 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;
+  normalize?: Normalize;
 }
 
 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;
     let action = msg.action;
     let args: Args = msg.args;
     try {
-      ({ action, args } = normalize(msg.action, msg.args));
-      emit({ op: 'log', text: `call ${action} recv (line=${lineTag(args)})` });
-      if (preDispatch?.(id, action)) return;
+      if (normalize && !handlers[action]) ({ action, args } = normalize(action, args));
       const handler = handlers[action];
       if (!handler) {
         respond(id, { error: `unknown action '${action}' (have: ${known})` });
         return;
       }
       await handler(id, args);
-      emit({ op: 'log', text: `call ${action} done (line=${lineTag(args)})` });
     } catch (err) {
       const info = serializeTrainError(err);
       emit({

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

@@ -0,0 +1,63 @@
+import { errMsg, logFatalSync } 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>;
+  disconnectClient?: (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>();
+  let stopping = false;
+  if (train.disconnectClient) {
+    const disconnect = train.disconnectClient;
+    const shutdown = (): void => {
+      if (stopping) return;
+      stopping = true;
+      process.stdin.pause();
+      Promise.allSettled([...clients.values()].map(async (client) => { await disconnect(client); })).then((results) => {
+        const errors = results.flatMap((result) => result.status === 'rejected' ? [errMsg(result.reason)] : []);
+        if (errors.length) logFatalSync({ station: train.station, errors }, 'train: shutdown failed');
+        process.exit(errors.length ? 1 : 0);
+      }).catch((err: unknown) => {
+        logFatalSync({ station: train.station, err: errMsg(err) }, 'train: shutdown failed');
+        process.exit(1);
+      });
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+  }
+  const clientFor = (accountId: string): C => {
+    if (stopping) throw new TrainError('train_stopping', `${train.station} is shutting down`);
+    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,84 @@
+import { mintId } from '../ids.js';
+import { emit } from './station-runtime.js';
+
+type Fields = Record<string, unknown>;
+type Out = (e: unknown) => void;
+
+export const selfUri = (): string => process.env.METRO_SELF_URI ?? 'metro://user';
+
+export function emitInbound(account: string, e: Fields, out: Out = emit): void {
+  out({
+    ...e,
+    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;
+  bytes?: number;
+}
+
+function attachmentEvent(at: AttachmentAt, text: string, payload: Fields): Fields {
+  return {
+    id: mintId(),
+    ts: new Date().toISOString(),
+    station: at.station,
+    line: at.line,
+    from: at.from ?? selfUri(),
+    text,
+    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.saved.bytes === undefined ? {} : { size: at.saved.bytes }),
+    ...at.extra,
+    attachmentPath: 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`);
+    });
+}