@stage-labs/metro 0.1.0-beta.14 → 0.1.0-beta.15

package/dist/broker/claims.js

@@ -91,7 +91,7 @@ export function classifyLine(line) {
     }
     return 'unknown';
 }
-/** Most-recent inbound on `line`. Walks `history.jsonl` from the tail; returns undefined if missing. */
+/** Most-recent inbound (from-someone-else) on `line`. Walks `history.jsonl` from the tail. */
 function readRecentInbound(line) {
     if (!existsSync(HISTORY_FILE))
         return undefined;
@@ -101,7 +101,7 @@ function readRecentInbound(line) {
             continue;
         try {
             const e = JSON.parse(lines[i]);
-            if (e.line === line && e.kind === 'inbound')
+            if (e.line === line && !Line.isLocal(e.from))
                 return e;
         }
         catch { /* skip */ }

package/dist/broker/history-stream.js

@@ -117,6 +117,8 @@ export function drainTail(offset, opts, onEntry) {
             continue;
         if (opts.stationFilter && entry.station !== opts.stationFilter)
             continue;
+        if (opts.excludeFrom && opts.excludeFrom.includes(entry.from))
+            continue;
         if (!passesMode(entry, opts.mode, opts.self, claims, { includeWebhooks: opts.includeWebhooks }))
             continue;
         if (onEntry(entry) === true)

package/dist/cli/index.js

@@ -1,13 +1,32 @@
 #!/usr/bin/env bun
 /** Metro CLI: parses argv, dispatches to subcommands. Bun runtime required (uses Bun.spawn for trains). */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import pkg from '../../package.json' with { type: 'json' };
-import { errMsg } from '../log.js';
-import { listLines, loadMetroEnv } from '../paths.js';
+import { errMsg, log } from '../log.js';
+import { listLines, loadMetroEnv, STATE_DIR } from '../paths.js';
 import { readHistory } from '../history.js';
 import { cmdDoctor, cmdSetup, cmdUpdate } from './config.js';
 import { cmdClaim, cmdClaims, cmdRelease, cmdTail } from './tail.js';
 import { cmdCall, cmdTrains, cmdTunnel, cmdWebhook } from './webhook.js';
 import { flagOne, isJson, parseArgs, writeJson, } from './util.js';
+/** True if another live process owns the dispatcher lockfile. Mirrors paths.acquireLock'
+ *  s detection but as a peek — no claim, no exit. */
+function anotherDispatcherRunning() {
+    const lockFile = join(STATE_DIR, '.tail-lock');
+    if (!existsSync(lockFile))
+        return false;
+    const pid = Number(readFileSync(lockFile, 'utf8').trim());
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 const USAGE = `metro — event-interception wire. Trains in ~/.metro/trains/ produce events;
 metro multiplexes them onto stdout. Outbound action calls flow back via \`metro call\`.
 
@@ -22,7 +41,7 @@ Usage:
   metro trains new <name>                     Scaffold ~/.metro/trains/<name>.ts from the example.
   metro call <train> <action> [args]          Forward an action call to a train via its stdin.
                                               [args] is JSON, '@file', '-' (stdin), or a bare string.
-  metro history [--limit=N] [--line=…] [--station=…] [--kind=…] [--from=…] [--text=…] [--since=…]
+  metro history [--limit=N] [--line=…] [--station=…] [--from=…] [--text=…] [--since=…]
                                               Read the universal message log (newest first).
   metro tail [--as=<user-uri>] [--follow] [--strict | --unclaimed | --all] [--include-webhooks]
              [--chat=<line>] [--station=…] [--since=<offset|tail>] [--limit=N]
@@ -75,7 +94,6 @@ async function cmdHistory(_, f) {
     const entries = readHistory({
         line: flagOne(f, 'line'),
         station: flagOne(f, 'station'),
-        kind: flagOne(f, 'kind'),
         from: flagOne(f, 'from'),
         textContains: flagOne(f, 'text'),
         since: since ? new Date(since) : undefined,
@@ -87,14 +105,14 @@ async function cmdHistory(_, f) {
         process.stdout.write('(no matching history entries)\n');
         return;
     }
-    process.stdout.write('time      id            kind          from                      → to                        body\n');
+    process.stdout.write('time      id            from                      → to                        body\n');
     for (const e of entries.reverse()) {
         const ts = e.ts.slice(11, 19);
         const from = pad(fmtActor(e.from, e.fromName), 24);
         const to = pad(fmtActor(e.to), 24);
-        const body = e.text ?? (e.emoji ? `[react ${e.emoji}]` : '');
+        const body = e.text ?? '';
         const text = body.length > 60 ? body.slice(0, 59) + '…' : body;
-        process.stdout.write(`${ts}  ${e.id.padEnd(12)}  ${e.kind.padEnd(12)}  ${from} → ${to}  ${text}\n`);
+        process.stdout.write(`${ts}  ${e.id.padEnd(12)}  ${from} → ${to}  ${text}\n`);
     }
 }
 /** Compact display: fromName if known; else `station:@<id>` (user) or `station:<id>`. */
@@ -126,6 +144,13 @@ async function main() {
     if (cmd === '--help' || cmd === '-h')
         return void process.stdout.write(USAGE);
     if (!cmd) {
+        /** Multi-agent: another `metro` already owns the dispatcher → drop into tail mode so
+         *  a second agent (e.g. Codex while Claude is running) still gets the event stream. */
+        if (anotherDispatcherRunning()) {
+            log.info({}, 'dispatcher already running; subscribing as tail (--follow --json --since=tail)');
+            await cmdTail([], { follow: true, json: true, since: 'tail' });
+            return;
+        }
         await import('../dispatcher.js');
         return;
     }

package/dist/cli/messenger-api.js

@@ -0,0 +1,214 @@
+/** Messenger endpoints: send + react + register, plus Expo push delivery. Upload/serve in messenger-uploads.ts. */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { mintId, readHistory, userSelf } from '../history.js';
+import { errMsg, log } from '../log.js';
+import { STATE_DIR } from '../paths.js';
+import { handleMessengerFile, handleMessengerUpload } from './messenger-uploads.js';
+import { transcribeAudio } from './messenger-transcribe.js';
+const UPLOADS_DIR = join(STATE_DIR, 'messenger-uploads');
+const MESSENGER_LINE = 'metro://messenger/owner';
+const MESSENGER_USER = 'metro://messenger/user/owner';
+const PUSH_TOKENS_FILE = join(STATE_DIR, 'push-tokens.json');
+function readPushTokens() {
+    try {
+        return existsSync(PUSH_TOKENS_FILE) ? JSON.parse(readFileSync(PUSH_TOKENS_FILE, 'utf8')) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writePushTokens(tokens) {
+    writeFileSync(PUSH_TOKENS_FILE, JSON.stringify([...new Set(tokens)]));
+}
+async function pushExpo(tokens, title, body, replyTo) {
+    if (tokens.length === 0)
+        return;
+    /** `categoryId: 'messenger.reply'` opts the notification into the inline Reply
+     *  action the app registered at startup; `data.replyTo` lets the response
+     *  listener thread the answer back to the originating message. */
+    const messages = tokens.map(to => ({
+        to, title, body, sound: 'default',
+        categoryId: 'messenger.reply',
+        ...(replyTo ? { data: { replyTo } } : {}),
+    }));
+    try {
+        await fetch('https://exp.host/--/api/v2/push/send', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'Accept-Encoding': 'gzip, deflate' },
+            body: JSON.stringify(messages),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err) }, 'expo push failed');
+    }
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+    const raw = Buffer.concat(chunks).toString('utf8').trim();
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        return { __error: `bad JSON body: ${errMsg(err)}` };
+    }
+}
+/** Route all /api/messenger/* paths. Returns true if handled. */
+export function routeMessenger(req, res, path, emit, send) {
+    const guard = (p, label, methodOk = true) => {
+        if (!methodOk) {
+            send(res, req, 405, { error: 'method not allowed' });
+            return true;
+        }
+        Promise.resolve(p()).catch(err => {
+            log.warn({ err: errMsg(err) }, `monitor: ${label} error`);
+            try {
+                send(res, req, 500, { error: errMsg(err) });
+            }
+            catch { /* ignore */ }
+        });
+        return true;
+    };
+    if (path === '/api/messenger/send') {
+        if (!emit) {
+            send(res, req, 500, { error: 'emit not wired' });
+            return true;
+        }
+        return guard(() => handleMessengerSend(req, res, emit, send), 'messenger-send', req.method === 'POST');
+    }
+    if (path === '/api/messenger/react') {
+        if (!emit) {
+            send(res, req, 500, { error: 'emit not wired' });
+            return true;
+        }
+        return guard(() => handleMessengerReact(req, res, emit, send), 'messenger-react', req.method === 'POST');
+    }
+    if (path === '/api/messenger/register') {
+        return guard(() => handleMessengerRegister(req, res, send), 'messenger-register', req.method === 'POST');
+    }
+    if (path === '/api/messenger/upload') {
+        return guard(() => handleMessengerUpload(req, res, send), 'messenger-upload', req.method === 'POST');
+    }
+    const fileMatch = path.match(/^\/api\/messenger\/files\/([^/]+)$/);
+    if (fileMatch) {
+        if (req.method !== 'GET') {
+            send(res, req, 405, { error: 'method not allowed' });
+            return true;
+        }
+        handleMessengerFile(req, res, decodeURIComponent(fileMatch[1]), send);
+        return true;
+    }
+    return false;
+}
+export async function handleMessengerSend(req, res, emit, send) {
+    const body = await readJsonBody(req);
+    if ('__error' in body)
+        return send(res, req, 400, { error: body.__error });
+    const text = (body.text ?? '').trim();
+    const attachments = Array.isArray(body.attachments) ? body.attachments : [];
+    const question = body.question && Array.isArray(body.question.options) && body.question.options.length > 0
+        ? body.question : undefined;
+    if (!text && attachments.length === 0 && !question) {
+        return send(res, req, 400, { error: 'text, attachments, or question required' });
+    }
+    const fromAgent = body.as === 'agent';
+    const agent = userSelf();
+    const replyTo = typeof body.replyTo === 'string' && body.replyTo ? body.replyTo : undefined;
+    /** Merge attachments + question into a single payload object so the client can read
+     *  both off `payload.attachments` and `payload.question`. */
+    const payload = (attachments.length > 0 || question)
+        ? { ...(attachments.length > 0 ? { attachments } : {}), ...(question ? { question } : {}) }
+        : undefined;
+    const entry = {
+        id: mintId(),
+        ts: new Date().toISOString(),
+        station: 'messenger',
+        line: MESSENGER_LINE,
+        from: fromAgent ? agent : MESSENGER_USER,
+        to: fromAgent ? MESSENGER_USER : agent,
+        text: text || undefined,
+        ...(replyTo ? { replyTo } : {}),
+        ...(payload ? { payload } : {}),
+    };
+    emit(entry);
+    /** Agent → user: push to registered tokens. User → agent: their own message; skip. */
+    if (fromAgent) {
+        const a = attachments[0];
+        const kindLabel = a?.kind === 'image' ? '📷 Photo'
+            : a?.kind === 'audio' ? '🎤 Voice message'
+                : a?.kind === 'video' ? '🎬 Video'
+                    : a ? `📎 ${a.name ?? 'File'}` : '';
+        const questionLabel = question ? `❓ ${question.header ?? 'Choose an option'}` : '';
+        const summary = text || kindLabel || questionLabel || '(empty)';
+        void pushExpo(readPushTokens(), 'Metro', summary.slice(0, 200), entry.id);
+    }
+    /** Fire-and-forget: transcribe any audio attachments and emit a follow-up event. */
+    for (const att of attachments) {
+        if (att.kind !== 'audio')
+            continue;
+        const filename = basename(att.url);
+        void transcribeAudio(join(UPLOADS_DIR, filename)).then(transcript => {
+            if (!transcript)
+                return;
+            emit({
+                id: mintId(), ts: new Date().toISOString(),
+                station: 'messenger', line: MESSENGER_LINE,
+                from: entry.from, to: entry.to,
+                payload: { transcribeFor: entry.id, transcript },
+            });
+        });
+    }
+    send(res, req, 200, { id: entry.id, line: entry.line });
+}
+/** Toggle a reaction; if already-active, emit `{removed: true}` so the client folds pairs. */
+export async function handleMessengerReact(req, res, emit, send) {
+    const body = await readJsonBody(req);
+    if ('__error' in body)
+        return send(res, req, 400, { error: body.__error });
+    const messageId = (body.messageId ?? '').trim();
+    const emoji = (body.emoji ?? '').trim();
+    if (!messageId || !emoji)
+        return send(res, req, 400, { error: 'messageId + emoji required' });
+    const fromAgent = body.as === 'agent';
+    const agent = userSelf();
+    const sender = fromAgent ? agent : MESSENGER_USER;
+    /** Scan recent messenger history for an already-active reaction from this sender. */
+    /** readHistory returns newest-first; break on first match so we get the latest event's state. */
+    const recent = readHistory({ limit: 500, station: 'messenger' });
+    let active = false;
+    for (const e of recent) {
+        const p = e.payload;
+        if (!p?.reactTo || p.reactTo !== messageId || p.emoji !== emoji || e.from !== sender)
+            continue;
+        active = !p.removed;
+        break;
+    }
+    const entry = {
+        id: mintId(),
+        ts: new Date().toISOString(),
+        station: 'messenger',
+        line: MESSENGER_LINE,
+        from: sender,
+        to: fromAgent ? MESSENGER_USER : agent,
+        payload: { reactTo: messageId, emoji, ...(active ? { removed: true } : {}) },
+    };
+    emit(entry);
+    send(res, req, 200, { id: entry.id, removed: active });
+}
+export async function handleMessengerRegister(req, res, send) {
+    const body = await readJsonBody(req);
+    if ('__error' in body)
+        return send(res, req, 400, { error: body.__error });
+    const token = (body.pushToken ?? '').trim();
+    if (!token)
+        return send(res, req, 400, { error: 'pushToken is required' });
+    const tokens = readPushTokens();
+    if (!tokens.includes(token))
+        writePushTokens([...tokens, token]);
+    send(res, req, 200, { ok: true, count: tokens.includes(token) ? tokens.length : tokens.length + 1 });
+}

package/dist/cli/messenger-transcribe.js

@@ -0,0 +1,43 @@
+/** Local whisper.cpp audio transcription. Opt-in: requires whisper-cli + ggml model on disk. */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { basename, extname, join } from 'node:path';
+import { errMsg, log } from '../log.js';
+const WHISPER_BIN = process.env.METRO_WHISPER_BIN ?? 'whisper-cli';
+const WHISPER_MODEL = process.env.METRO_WHISPER_MODEL
+    ?? join(homedir(), '.cache', 'whisper-cpp', 'ggml-base.bin');
+const FFMPEG_BIN = process.env.METRO_FFMPEG_BIN ?? 'ffmpeg';
+function runCmd(bin, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { stdio: 'ignore' });
+        child.on('error', reject);
+        child.on('exit', code => (code === 0 ? resolve() : reject(new Error(`${bin} exited ${code}`))));
+    });
+}
+/** Transcribe a local audio file to text. Returns null on any failure (incl. missing tooling). */
+export async function transcribeAudio(filePath) {
+    if (!existsSync(WHISPER_MODEL) || !existsSync(filePath))
+        return null;
+    const base = basename(filePath, extname(filePath));
+    const wav = join(tmpdir(), `metro-tx-${base}.wav`);
+    const outPrefix = join(tmpdir(), `metro-tx-${base}`);
+    try {
+        await runCmd(FFMPEG_BIN, ['-y', '-i', filePath, '-ar', '16000', '-ac', '1', wav]);
+        await runCmd(WHISPER_BIN, ['-m', WHISPER_MODEL, '-f', wav, '--output-txt', '-of', outPrefix]);
+        const text = readFileSync(`${outPrefix}.txt`, 'utf8').trim();
+        return text || null;
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err) }, 'messenger transcribe failed');
+        return null;
+    }
+    finally {
+        for (const f of [wav, `${outPrefix}.txt`]) {
+            try {
+                unlinkSync(f);
+            }
+            catch { /* ignore */ }
+        }
+    }
+}

package/dist/cli/messenger-uploads.js

@@ -0,0 +1,116 @@
+/** Messenger upload + serve: POST /api/messenger/upload, GET /api/messenger/files/:name. */
+import { createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { mintId } from '../history.js';
+import { errMsg, log } from '../log.js';
+import { STATE_DIR } from '../paths.js';
+const UPLOADS_DIR = join(STATE_DIR, 'messenger-uploads');
+const UPLOAD_MAX = 25 * 1024 * 1024;
+/** Tunable via env: how long uploaded files stick around before they're pruned (ms). */
+const UPLOAD_TTL_MS = Number(process.env.METRO_UPLOAD_TTL_MS ?? String(90 * 24 * 60 * 60 * 1000));
+mkdirSync(UPLOADS_DIR, { recursive: true });
+/** Best-effort: delete uploads older than UPLOAD_TTL_MS. Called once at module load + periodically. */
+function pruneOldUploads() {
+    const cutoff = Date.now() - UPLOAD_TTL_MS;
+    let removed = 0;
+    try {
+        for (const name of readdirSync(UPLOADS_DIR)) {
+            const path = join(UPLOADS_DIR, name);
+            try {
+                if (statSync(path).mtimeMs < cutoff) {
+                    unlinkSync(path);
+                    removed += 1;
+                }
+            }
+            catch { /* ignore individual file errors */ }
+        }
+    }
+    catch { /* dir missing — nothing to prune */ }
+    if (removed > 0)
+        log.info({ removed, dir: UPLOADS_DIR }, 'messenger-uploads: pruned old files');
+}
+pruneOldUploads();
+setInterval(pruneOldUploads, 12 * 60 * 60 * 1000).unref();
+/** Map MIME prefix → attachment kind. */
+export function kindFromMime(mime) {
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('audio/'))
+        return 'audio';
+    if (mime.startsWith('video/'))
+        return 'video';
+    return 'file';
+}
+const MIME_TO_EXT = {
+    'image/png': '.png', 'image/jpeg': '.jpg', 'image/jpg': '.jpg',
+    'image/webp': '.webp', 'image/gif': '.gif', 'image/heic': '.heic',
+    'audio/mp4': '.m4a', 'audio/m4a': '.m4a', 'audio/aac': '.aac',
+    'audio/mpeg': '.mp3', 'audio/ogg': '.ogg', 'audio/webm': '.webm', 'audio/wav': '.wav',
+    'video/mp4': '.mp4', 'video/webm': '.webm', 'video/quicktime': '.mov',
+    'application/pdf': '.pdf', 'application/zip': '.zip',
+    'text/plain': '.txt', 'text/markdown': '.md',
+};
+/** mime → file extension. Best-effort, falls back to '.bin'. */
+function extFromMime(mime) {
+    return MIME_TO_EXT[mime.toLowerCase().split(';')[0]] ?? '.bin';
+}
+/** ext → mime, used when serving uploads so browsers / image tags interpret them correctly. */
+function mimeFromExt(ext) {
+    const reverse = Object.entries(MIME_TO_EXT).find(([, e]) => e === ext.toLowerCase());
+    return reverse ? reverse[0] : 'application/octet-stream';
+}
+/** Raw binary upload: body = file bytes, headers `Content-Type` and `X-Filename` (optional). */
+export async function handleMessengerUpload(req, res, send) {
+    const mime = (req.headers['content-type'] ?? 'application/octet-stream').toString().split(';')[0].trim();
+    const declared = Number(req.headers['content-length'] ?? '0');
+    if (declared > UPLOAD_MAX)
+        return send(res, req, 413, { error: `upload exceeds ${UPLOAD_MAX} bytes` });
+    const name = req.headers['x-filename']?.toString().slice(0, 256);
+    const id = mintId();
+    const ext = name ? extname(name) || extFromMime(mime) : extFromMime(mime);
+    const filename = `${id}${ext}`;
+    const dest = join(UPLOADS_DIR, filename);
+    let total = 0;
+    const out = createWriteStream(dest);
+    req.on('data', (chunk) => {
+        total += chunk.length;
+        if (total > UPLOAD_MAX) {
+            req.destroy(new Error('upload too large'));
+            out.destroy();
+        }
+    });
+    try {
+        await pipeline(req, out);
+    }
+    catch (err) {
+        try {
+            send(res, req, 413, { error: errMsg(err) });
+        }
+        catch { /* ignore */ }
+        return;
+    }
+    /** Path-only URL; the client adds host + token. Stable, host-independent across tunnels. */
+    send(res, req, 200, {
+        id, url: `/api/messenger/files/${filename}`, kind: kindFromMime(mime), mime, size: total, name,
+    });
+}
+/** GET /api/messenger/files/:filename — stream a previously uploaded file back. */
+export function handleMessengerFile(req, res, filename, send) {
+    /** Guard path traversal — only basenames allowed. */
+    if (filename.includes('/') || filename.includes('..') || !filename) {
+        return send(res, req, 400, { error: 'bad filename' });
+    }
+    const path = join(UPLOADS_DIR, filename);
+    if (!existsSync(path))
+        return send(res, req, 404, { error: 'not found' });
+    const stat = statSync(path);
+    const dot = filename.lastIndexOf('.');
+    const ext = dot >= 0 ? filename.slice(dot) : '';
+    res.writeHead(200, {
+        'content-type': mimeFromExt(ext),
+        'content-length': stat.size.toString(),
+        'cache-control': 'private, max-age=31536000',
+    });
+    createReadStream(path).pipe(res);
+}

package/dist/cli/monitor-api.js

@@ -0,0 +1,205 @@
+/** HTTP monitor endpoints: GET /api/state, GET /api/tail (SSE), POST /api/call/<train>/<action>. */
+import { timingSafeEqual } from 'node:crypto';
+import pkg from '../../package.json' with { type: 'json' };
+import { readClaims } from '../broker/claims.js';
+import { drainTail, followTail, historySize, } from '../broker/history-stream.js';
+import { readHistory } from '../history.js';
+import { ipcCall } from '../ipc.js';
+import { asLine } from '../lines.js';
+import { errMsg, log } from '../log.js';
+import { readBotIds } from '../paths.js';
+import { routeMessenger } from './messenger-api.js';
+/** Monitor endpoints answer only on dedicated hostnames so webhook tunnel can't double-serve them. */
+const MONITOR_HOSTS = new Set((process.env.METRO_MONITOR_HOSTS ?? 'monitor.metro.box,localhost,127.0.0.1')
+    .toLowerCase().split(',').map(s => s.trim()).filter(Boolean));
+const CALL_BODY_MAX = 256 * 1024;
+/** Reflect request Origin so browsers (Netlify, custom domains, file://) can call cross-origin. */
+function cors(req) {
+    return {
+        'access-control-allow-origin': req.headers.origin ?? '*',
+        'access-control-allow-methods': 'GET, POST, OPTIONS',
+        'access-control-allow-headers': 'Authorization, Content-Type',
+        'access-control-max-age': '86400',
+        vary: 'Origin',
+    };
+}
+function send(res, req, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json', ...cors(req) });
+    res.end(JSON.stringify(body));
+}
+function tokenEq(given, want) {
+    const g = Buffer.from(given), w = Buffer.from(want);
+    return g.length === w.length && timingSafeEqual(g, w);
+}
+function authorized(req, q) {
+    const token = process.env.METRO_MONITOR_TOKEN;
+    if (!token)
+        return { status: 503, msg: 'monitor endpoints not configured (METRO_MONITOR_TOKEN unset)' };
+    const header = [].concat(req.headers['authorization'] ?? [])[0];
+    if (header?.startsWith('Bearer ') && tokenEq(header.slice(7), token))
+        return null;
+    /** Query-token path is for media tags (img/audio) that can't send Authorization headers. */
+    const qt = q?.get('token');
+    if (qt && tokenEq(qt, token))
+        return null;
+    return { status: 401, msg: 'unauthorized' };
+}
+/** Mode picker — shared with CLI tail. Conflict/strict-no-self routed through `onErr`. */
+export function pickMode(strict, unclaimed, all, self, onErr) {
+    if ([strict, unclaimed, all].filter(Boolean).length > 1) {
+        return onErr('strict/unclaimed/all are mutually exclusive');
+    }
+    if (strict)
+        return self ? 'mine-only' : onErr('strict requires --as <user-uri>');
+    if (unclaimed)
+        return 'unclaimed';
+    if (all || !self)
+        return 'all';
+    return 'mine-or-unclaimed';
+}
+export function handleMonitorRequest(req, res, emit) {
+    const url = req.url ?? '';
+    if (!url.startsWith('/api/'))
+        return false;
+    const host = req.headers[':authority'] ?? req.headers.host;
+    if (host && !MONITOR_HOSTS.has(host.split(':')[0].toLowerCase()))
+        return false;
+    /** CORS preflight — short-circuit before auth so browsers can OPTIONS without a token. */
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204, cors(req));
+        res.end();
+        return true;
+    }
+    const [path, qs = ''] = url.split('?', 2);
+    const q = new URLSearchParams(qs);
+    const auth = authorized(req, q);
+    if (auth) {
+        send(res, req, auth.status, { error: auth.msg });
+        return true;
+    }
+    if (req.method === 'GET' && path === '/api/state') {
+        handleState(res, req, q);
+        return true;
+    }
+    if (req.method === 'GET' && path === '/api/tail') {
+        handleTail(req, res, q).catch(err => {
+            log.warn({ err: errMsg(err) }, 'monitor: tail handler error');
+            try {
+                if (!res.headersSent)
+                    res.writeHead(500).end();
+                else
+                    res.end();
+            }
+            catch { /* ignore */ }
+        });
+        return true;
+    }
+    /** POST /api/call/<train>/<action> — JSON body {args} forwarded to train via IPC forward-call. */
+    const callMatch = path.match(/^\/api\/call\/([^/]+)\/([^/]+)$/);
+    if (callMatch) {
+        if (req.method !== 'POST') {
+            send(res, req, 405, { error: 'method not allowed' });
+            return true;
+        }
+        handleCall(req, res, callMatch[1], callMatch[2]).catch(err => {
+            log.warn({ err: errMsg(err) }, 'monitor: call handler error');
+            try {
+                send(res, req, 500, { error: errMsg(err) });
+            }
+            catch { /* ignore */ }
+        });
+        return true;
+    }
+    /** /api/messenger/* — send, register, upload, files/:name. */
+    if (path.startsWith('/api/messenger/') && routeMessenger(req, res, path, emit, send))
+        return true;
+    /** GET-only paths reject other verbs with 405. Anything else → 404. */
+    if (req.method !== 'GET' && (path === '/api/state' || path === '/api/tail')) {
+        send(res, req, 405, { error: 'method not allowed' });
+        return true;
+    }
+    send(res, req, 404, { error: 'not found' });
+    return true;
+}
+function nonNegInt(raw) {
+    const n = raw == null ? NaN : Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : null;
+}
+function handleState(res, req, q) {
+    const before = nonNegInt(q.get('before'));
+    const limit = Math.min(nonNegInt(q.get('limit')) ?? 100, 500);
+    if (before !== null)
+        return send(res, req, 200, { recent_history: readHistory({ limit, skip: before }) });
+    const recent = readHistory({ limit }), claims = readClaims();
+    const lines = new Set([...recent.map(e => e.line), ...Object.keys(claims)]);
+    send(res, req, 200, {
+        claims, lines: [...lines], recent_history: recent, bot_ids: readBotIds(), version: pkg.version,
+    });
+}
+async function handleTail(req, res, q) {
+    const asParam = q.get('as');
+    const self = asParam ? asLine(asParam) : null;
+    const isOn = (k) => q.get(k) === 'true' || q.get('mode') === k;
+    const mode = pickMode(isOn('strict'), isOn('unclaimed'), isOn('all'), self, () => 'all');
+    const excludeFromCsv = q.get('exclude_from');
+    const opts = {
+        mode, self, chatFilter: q.get('chat') ?? undefined,
+        stationFilter: q.get('station') ?? undefined,
+        includeWebhooks: q.get('include_webhooks') === 'true',
+        excludeFrom: excludeFromCsv ? excludeFromCsv.split(',').map(s => s.trim()).filter(Boolean) : undefined,
+    };
+    res.writeHead(200, {
+        'content-type': 'text/event-stream', 'cache-control': 'no-cache, no-transform',
+        'connection': 'keep-alive', ...cors(req),
+        /** Cloudflare/proxies buffer SSE without this hint. */
+        'x-accel-buffering': 'no',
+    });
+    /** `since=tail` (default) starts at EOF; `since=0` replays the full file; numeric = byte offset. */
+    const since = q.get('since');
+    const sinceN = since && since !== 'tail' ? Number(since) : NaN;
+    let offset = Number.isFinite(sinceN) && sinceN >= 0 ? sinceN : historySize();
+    /** 4 KiB padding so Cloudflare's HTTP/2 buffer flushes (else holds 30+ s on free tier). */
+    res.write(`: metro monitor tail (mode=${opts.mode}${self ? `, as=${self}` : ''})\n: ${'-'.repeat(4096)}\n\n`);
+    const sse = (e) => {
+        res.write(`id: ${e.id}\nevent: history\ndata: ${JSON.stringify(e)}\n\n`);
+    };
+    offset = drainTail(offset, opts, sse);
+    const stop = followTail(offset, opts, sse, 1_000);
+    const keepalive = setInterval(() => res.write(': keepalive\n\n'), 25_000);
+    const cleanup = () => { stop(); clearInterval(keepalive); try {
+        res.end();
+    }
+    catch { /* ignore */ } };
+    req.on('close', cleanup);
+    req.on('error', cleanup);
+}
+async function handleCall(req, res, train, action) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > CALL_BODY_MAX)
+            throw new Error(`request body exceeds ${CALL_BODY_MAX} bytes`);
+        chunks.push(buf);
+    }
+    const raw = Buffer.concat(chunks).toString('utf8').trim();
+    let args = {};
+    if (raw) {
+        try {
+            const parsed = JSON.parse(raw);
+            args = parsed && typeof parsed === 'object' && 'args' in parsed ? parsed.args : parsed;
+        }
+        catch (err) {
+            return send(res, req, 400, { error: `bad JSON body: ${errMsg(err)}` });
+        }
+    }
+    const resp = await ipcCall({ op: 'forward-call', train, action, args });
+    if (!resp.ok)
+        return send(res, req, 502, { error: resp.error });
+    if (!('response' in resp))
+        return send(res, req, 502, { error: 'malformed daemon response' });
+    if (resp.response.error)
+        return send(res, req, 502, { error: resp.response.error });
+    send(res, req, 200, { result: resp.response.result ?? null });
+}

package/dist/cli/tail.js

@@ -1,36 +1,26 @@
-/** CLI tail/claim/release/claims + read-only /api/state + /api/tail HTTP. Share drain/watch primitives. */
-import { timingSafeEqual } from 'node:crypto';
+/** CLI: `metro tail / claim / release / claims`. HTTP monitor endpoints live in monitor-api.ts. */
 import { existsSync } from 'node:fs';
-import pkg from '../../package.json' with { type: 'json' };
 import { CLAIMS_FILE, claimLine, readClaims, releaseLine } from '../broker/claims.js';
 import { cursorKey, drainTail, followTail, historySize, readCursor, writeCursor, } from '../broker/history-stream.js';
-import { readHistory, userSelf } from '../history.js';
+import { userSelf } from '../history.js';
 import { asLine } from '../lines.js';
-import { errMsg, log } from '../log.js';
-import { loadMetroEnv, readBotIds } from '../paths.js';
+import { loadMetroEnv } from '../paths.js';
+import { pickMode } from './monitor-api.js';
 import { emit, exitErr, flagOne, isJson, need, writeJson } from './util.js';
-/* ──────────── CLI: metro tail / claim / release / claims ──────────── */
-/** Pick mode from 3 booleans + optional self. Conflict/strict-no-self routed through `onErr`. */
-function pickMode(strict, unclaimed, all, self, onErr) {
-    if ([strict, unclaimed, all].filter(Boolean).length > 1)
-        return onErr('strict/unclaimed/all are mutually exclusive');
-    if (strict)
-        return self ? 'mine-only' : onErr('strict requires --as <user-uri>');
-    if (unclaimed)
-        return 'unclaimed';
-    if (all || !self)
-        return 'all';
-    return 'mine-or-unclaimed';
-}
+export { handleMonitorRequest } from './monitor-api.js';
 export async function cmdTail(_, f) {
     loadMetroEnv();
     const raw = flagOne(f, 'as');
     const auto = userSelf();
     const self = raw !== undefined ? asLine(raw) : auto === 'metro://user' ? null : auto;
     const mode = pickMode(f.strict === true, f.unclaimed === true, f.all === true, self, msg => { throw exitErr(`--${msg}`, 1); });
+    const excludeFromFlag = flagOne(f, 'exclude-from');
     const tail = {
         mode, self, chatFilter: flagOne(f, 'chat'), stationFilter: flagOne(f, 'station'),
         includeWebhooks: f['include-webhooks'] === true,
+        excludeFrom: excludeFromFlag
+            ? excludeFromFlag.split(',').map(s => s.trim()).filter(Boolean)
+            : undefined,
     };
     const follow = f.follow === true;
     const limit = Number(flagOne(f, 'limit')) || 0;
@@ -64,11 +54,11 @@ export async function cmdTail(_, f) {
     });
 }
 function fmtRow(e) {
-    const body = e.text ?? (e.emoji ? `[react ${e.emoji}]` : '');
+    const body = e.text ?? '';
     const text = body.length > 80 ? body.slice(0, 79) + '…' : body;
     const who = (e.fromName ?? e.from).padEnd(28).slice(0, 28);
     const where = e.line.padEnd(40).slice(0, 40);
-    return `${e.ts.slice(11, 19)}  ${e.id.padEnd(12)}  ${e.kind.padEnd(8)}  ${who}  ${where}  ${text}`;
+    return `${e.ts.slice(11, 19)}  ${e.id.padEnd(12)}  ${who}  ${where}  ${text}`;
 }
 export async function cmdClaim(p, f) {
     loadMetroEnv();
@@ -93,7 +83,8 @@ export async function cmdClaims(_, f) {
     if (isJson(f))
         return writeJson({ claims });
     if (!entries.length) {
-        process.stdout.write(`(no claims — every tail with matching filters receives every event)\nfile: ${CLAIMS_FILE}${existsSync(CLAIMS_FILE) ? '' : ' (not created yet)'}\n`);
+        process.stdout.write('(no claims — every tail with matching filters receives every event)\n'
+            + `file: ${CLAIMS_FILE}${existsSync(CLAIMS_FILE) ? '' : ' (not created yet)'}\n`);
         return;
     }
     const w = Math.max(...entries.map(([l]) => l.length));
@@ -102,111 +93,3 @@ export async function cmdClaims(_, f) {
         process.stdout.write(`  ${l.padEnd(w)}  →  ${o}\n`);
     process.stdout.write(`\n${entries.length} claim${entries.length === 1 ? '' : 's'} · ${CLAIMS_FILE}\n`);
 }
-/* ──────────── HTTP: /api/state + /api/tail (mounted on webhook server) ──────────── */
-/** Monitor endpoints answer only on dedicated hostnames so webhook tunnel can't double-serve them. */
-const MONITOR_HOSTS = new Set((process.env.METRO_MONITOR_HOSTS ?? 'monitor.metro.box,localhost,127.0.0.1').toLowerCase().split(',').map(s => s.trim()).filter(Boolean));
-const JSON_CT = { 'content-type': 'application/json' };
-function jsonRes(res, status, body) {
-    res.writeHead(status, JSON_CT);
-    res.end(JSON.stringify(body));
-}
-function authorized(req) {
-    const token = process.env.METRO_MONITOR_TOKEN;
-    if (!token)
-        return { status: 503, msg: 'monitor endpoints not configured (METRO_MONITOR_TOKEN unset)' };
-    const value = [].concat(req.headers['authorization'] ?? [])[0];
-    if (!value?.startsWith('Bearer '))
-        return { status: 401, msg: 'unauthorized' };
-    const given = Buffer.from(value.slice(7)), want = Buffer.from(token);
-    if (given.length !== want.length || !timingSafeEqual(given, want))
-        return { status: 401, msg: 'unauthorized' };
-    return null;
-}
-export function handleMonitorRequest(req, res) {
-    const url = req.url ?? '';
-    if (!url.startsWith('/api/'))
-        return false;
-    const host = req.headers[':authority'] ?? req.headers.host;
-    if (host && !MONITOR_HOSTS.has(host.split(':')[0].toLowerCase()))
-        return false;
-    if (req.method !== 'GET') {
-        jsonRes(res, 405, { error: 'method not allowed' });
-        return true;
-    }
-    const auth = authorized(req);
-    if (auth) {
-        jsonRes(res, auth.status, { error: auth.msg });
-        return true;
-    }
-    const [path, qs = ''] = url.split('?', 2);
-    const q = new URLSearchParams(qs);
-    if (path === '/api/state') {
-        handleState(res, q);
-        return true;
-    }
-    if (path === '/api/tail') {
-        handleTail(req, res, q).catch(err => {
-            log.warn({ err: errMsg(err) }, 'monitor: tail handler error');
-            try {
-                if (!res.headersSent)
-                    res.writeHead(500).end();
-                else
-                    res.end();
-            }
-            catch { /* ignore */ }
-        });
-        return true;
-    }
-    jsonRes(res, 404, { error: 'not found' });
-    return true;
-}
-function nonNegInt(raw) {
-    const n = raw == null ? NaN : Number(raw);
-    return Number.isInteger(n) && n >= 0 ? n : null;
-}
-function handleState(res, q) {
-    const before = nonNegInt(q.get('before'));
-    const limit = Math.min(nonNegInt(q.get('limit')) ?? 100, 500);
-    if (before !== null)
-        return jsonRes(res, 200, { recent_history: readHistory({ limit, skip: before }) });
-    const recent = readHistory({ limit }), claims = readClaims();
-    const lines = new Set([...recent.map(e => e.line), ...Object.keys(claims)]);
-    jsonRes(res, 200, {
-        claims, lines: [...lines], recent_history: recent, bot_ids: readBotIds(), version: pkg.version,
-    });
-}
-async function handleTail(req, res, q) {
-    const asParam = q.get('as');
-    const self = asParam ? asLine(asParam) : null;
-    const isOn = (k) => q.get(k) === 'true' || q.get('mode') === k;
-    const mode = pickMode(isOn('strict'), isOn('unclaimed'), isOn('all'), self, () => 'all');
-    const opts = {
-        mode, self, chatFilter: q.get('chat') ?? undefined,
-        stationFilter: q.get('station') ?? undefined,
-        includeWebhooks: q.get('include_webhooks') === 'true',
-    };
-    res.writeHead(200, {
-        'content-type': 'text/event-stream', 'cache-control': 'no-cache, no-transform',
-        'connection': 'keep-alive', 'access-control-allow-origin': '*',
-        /** Cloudflare/proxies buffer SSE without this hint. */
-        'x-accel-buffering': 'no',
-    });
-    /** `since=tail` (default) starts at EOF; `since=0` replays the full file; numeric = byte offset. */
-    const since = q.get('since');
-    const sinceN = since && since !== 'tail' ? Number(since) : NaN;
-    let offset = Number.isFinite(sinceN) && sinceN >= 0 ? sinceN : historySize();
-    /** 4 KiB padding so Cloudflare's HTTP/2 buffer flushes (else holds 30+ s on free tier). */
-    res.write(`: metro monitor tail (mode=${opts.mode}${self ? `, as=${self}` : ''})\n: ${'-'.repeat(4096)}\n\n`);
-    const sse = (e) => {
-        res.write(`id: ${e.id}\nevent: history\ndata: ${JSON.stringify(e)}\n\n`);
-    };
-    offset = drainTail(offset, opts, sse);
-    const stop = followTail(offset, opts, sse, 1_000);
-    const keepalive = setInterval(() => res.write(': keepalive\n\n'), 25_000);
-    const cleanup = () => { stop(); clearInterval(keepalive); try {
-        res.end();
-    }
-    catch { /* ignore */ } };
-    req.on('close', cleanup);
-    req.on('error', cleanup);
-}

package/dist/dispatcher/server.js

@@ -23,14 +23,6 @@ export function makeEmit(codexRc) {
 }
 /** Translate the snake_case train wire envelope to a camelCase `HistoryEntry`. */
 /** Trains can omit `id`/`station`/`to`; metro fills sensible defaults. */
-/** Forgive trains that use platform-flavored kinds (`message`, `reaction`) — map to the canonical enum. */
-function normalizeKind(k) {
-    if (k === 'message' || k === undefined || k === null)
-        return 'inbound';
-    if (k === 'reaction')
-        return 'react';
-    return k;
-}
 export function trainEventToHistoryEntry(env, trainName) {
     const line = env.line;
     if (typeof line !== 'string') {
@@ -39,18 +31,18 @@ export function trainEventToHistoryEntry(env, trainName) {
     }
     const station = env.station ?? Line.station(line) ?? trainName;
     const isPrivate = env.is_private === true;
+    /** Trains may still emit `emoji` for reactions — fold it into text so the new envelope stays minimal. */
+    const text = env.text ?? (env.emoji ? `[react ${env.emoji}]` : undefined);
     return {
         id: env.id ?? mintId(),
         ts: env.ts ?? new Date().toISOString(),
-        kind: normalizeKind(env.kind),
         station,
         line: line,
         lineName: env.line_name,
         from: (env.from ?? `metro://${station}`),
         fromName: env.from_name,
         to: (env.to ?? (isPrivate ? userSelf() : line)),
-        text: env.text,
-        emoji: env.emoji,
+        text,
         messageId: env.message_id,
         replyTo: env.reply_to,
         payload: env.payload,
@@ -75,7 +67,7 @@ export async function startWebhookServer(emit) {
     return server;
 }
 async function handleRequest(req, res, emit) {
-    if (handleMonitorRequest(req, res))
+    if (handleMonitorRequest(req, res, emit))
         return;
     const m = req.url?.match(/^\/wh\/([A-Za-z0-9_-]+)/);
     if (!m) {
@@ -113,7 +105,7 @@ async function handleRequest(req, res, emit) {
     catch { /* keep as string */ }
     const line = Line.webhook(endpointId);
     emit({
-        id: mintId(), ts: new Date().toISOString(), kind: 'inbound', station: 'webhook',
+        id: mintId(), ts: new Date().toISOString(), station: 'webhook',
         line, lineName: endpoint.label, from: line, to: line,
         messageId: headers['x-github-delivery'] || headers['x-request-id'] || randomUUID(),
         text: `${headers['x-github-event'] ?? headers['x-intercom-topic'] ?? 'event'} ${req.method} ${req.url}`,

package/dist/dispatcher.js

@@ -42,7 +42,7 @@ const ipc = startIpcServer(async (req) => {
     if (req.op === 'notify') {
         const line = req.line;
         emit({
-            id: mintId(), ts: new Date().toISOString(), kind: 'inbound',
+            id: mintId(), ts: new Date().toISOString(),
             station: Line.station(line) ?? '?', line,
             from: (req.from ?? userSelf()), to: line, text: req.text,
         });

package/dist/history.js

@@ -6,21 +6,20 @@ import { errMsg, log } from './log.js';
 import { STATE_DIR } from './paths.js';
 import { Line } from './lines.js';
 import { claudeUserId, claudeSessionId, codexUserId, codexSessionId } from './local-identity.js';
-/** Pre-render a chat-bubble line — the user echoes `event.display` verbatim instead of composing markdown itself. */
+/** Pre-render a chat-bubble line. Direction is derived: from === local agent → outbound (📤), else inbound (📩). */
 export function formatDisplay(e) {
     const headerFor = (icon, parts) => `**${icon} ${parts.filter(Boolean).join(' · ')}**`;
-    const body = e.text ?? (e.emoji ? `[react ${e.emoji}]` : '');
-    if (e.kind === 'inbound' && e.station === 'webhook') {
+    const body = e.text ?? '';
+    if (e.station === 'webhook' && !Line.isLocal(e.from)) {
         const ev = e.payload
             ?.headers?.['x-github-event'] ?? e.payload
             ?.headers?.['x-intercom-topic'];
         return `${headerFor('🪝', ['webhook', e.lineName, ev])}\n> ${body}`;
     }
-    if (e.kind === 'inbound' || (e.kind === 'react' && !Line.isLocal(e.from))) {
-        const reactBody = e.kind === 'react' ? `reacted ${e.emoji ?? ''}`.trim() : body;
-        return `${headerFor('📩', [e.station, e.fromName ?? e.from, e.lineName])}\n> ${reactBody}`;
+    if (Line.isLocal(e.from)) {
+        return `${headerFor('📤', [e.station, '→', e.fromName ?? e.to])}\n> ${body}`;
     }
-    return `${headerFor('📤', [e.station, '→', e.fromName ?? e.to])}\n> ${body}`;
+    return `${headerFor('📩', [e.station, e.fromName ?? e.from, e.lineName])}\n> ${body}`;
 }
 const FILE = join(STATE_DIR, 'history.jsonl');
 /** Mint a universal metro message ID. Short, prefixed, URL-safe. */
@@ -71,8 +70,6 @@ function matches(e, f) {
         return false;
     if (f.station && e.station !== f.station)
         return false;
-    if (f.kind && e.kind !== f.kind)
-        return false;
     if (f.from && e.from !== f.from)
         return false;
     if (f.textContains && !(e.text ?? '').toLowerCase().includes(f.textContains.toLowerCase()))

package/docs/broker.md

@@ -10,7 +10,7 @@ One concept — a **claim** — and three on-disk files you can `cat`:
 
 | Concern              | File                                    | Role                                                                                                              |
 |----------------------|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------|
-| Event log            | `$METRO_STATE_DIR/history.jsonl`        | Append-only JSONL — every inbound/outbound/edit/react. Single source of truth.                                    |
+| Event log            | `$METRO_STATE_DIR/history.jsonl`        | Append-only JSONL — every event (chat messages, webhooks, reactions, transcripts, …). Single source of truth.     |
 | Claims               | `$METRO_STATE_DIR/claims.json`          | `{ <line>: <user-id> }` — flat map. A line in here is *exclusively* owned by that user. Absence = broadcast.      |
 | Per-mode cursor      | `$METRO_STATE_DIR/cursors/<key>`        | Byte offset into `history.jsonl` — last-emitted position for one tail mode. Updated atomically after each emit.   |
 

package/docs/monitor.md

@@ -6,20 +6,26 @@ directly.
 
 These endpoints mount on the **existing** webhook HTTP server (default port `8420`).
 There is no separate daemon, no separate port, no extra process to launch. The
-implementation lives in [`src/cli/tail.ts`](../src/cli/tail.ts) (the same module that
-backs the `metro tail` CLI) and is wired into the HTTP server in
+implementation lives in [`src/cli/monitor-api.ts`](../src/cli/monitor-api.ts) (re-exported
+by `src/cli/tail.ts` for backwards compatibility) and is wired into the HTTP server in
 [`src/dispatcher/server.ts`](../src/dispatcher/server.ts) via `handleMonitorRequest`.
 
 ## Routes
 
-| Method | Path         | Returns                                                                                  |
-|--------|--------------|------------------------------------------------------------------------------------------|
-| GET    | `/api/state` | JSON snapshot — `{ claims, lines, recent_history (last 100), bot_ids }`.                 |
-| GET    | `/api/tail`  | Server-Sent Events stream — `history.jsonl` entries, claim-aware filtered.                |
-
-Both routes are **read-only**. The daemon never mutates state on receipt. The handlers
-read the same files the broker reads (`history.jsonl`, `claims.json`, `bot-ids.json`)
-under whatever `METRO_STATE_DIR` resolves to.
+| Method | Path                            | Returns                                                                                  |
+|--------|---------------------------------|------------------------------------------------------------------------------------------|
+| GET    | `/api/state`                    | JSON snapshot — `{ claims, lines, recent_history (last 100), bot_ids }`.                 |
+| GET    | `/api/tail`                     | Server-Sent Events stream — `history.jsonl` entries, claim-aware filtered.                |
+| POST   | `/api/call/<train>/<action>`    | Forward an action call to a train via `forward-call` IPC; returns `{result}`.            |
+| POST   | `/api/messenger/send`           | In-daemon chat: emits a history entry on `metro://messenger/owner`. Accepts `{text?, attachments?[], as?}`. |
+| POST   | `/api/messenger/register`       | Store an Expo push token so agent replies push to the phone.                              |
+| POST   | `/api/messenger/upload`         | Raw binary upload (up to 25 MiB). Body = file bytes; headers `Content-Type`, optional `X-Filename`. Returns `{id, url, kind, mime, size, name?}`. |
+| GET    | `/api/messenger/files/<name>`   | Stream a previously uploaded attachment. Accepts `?token=…` as an alternative to the bearer header for `<img>` / `<audio>` tags. |
+
+`/api/state` and `/api/tail` are read-only. `/api/call/<train>/<action>` is the single
+write endpoint — it never touches the on-disk history; the train running on the daemon
+emits its own outbound event after delivering the message, which then flows through the
+normal SSE stream like any other entry.
 
 ## Authentication
 
@@ -134,6 +140,61 @@ curl -N \
   "https://monitor.metro.box/api/tail?since=0"
 ```
 
+## `POST /api/call/<train>/<action>`
+
+Forwards an action call to a train (same as `metro call <train> <action> <args>` on the
+command line) via the daemon's existing `forward-call` IPC. Use this from the mobile or
+web app to send a message, react, edit, etc. without needing shell access.
+
+### Request
+
+```http
+POST /api/call/discord/send HTTP/1.1
+Host: monitor.metro.box
+Authorization: Bearer <METRO_MONITOR_TOKEN>
+Content-Type: application/json
+
+{"args": {"line": "metro://discord/123", "text": "hello from the web"}}
+```
+
+The body is one of:
+
+- `{"args": <object|array|string>}` — explicit `args` wrapper (recommended).
+- `<object>` — any other JSON object is forwarded as the args verbatim (useful for terse
+  clients).
+- Empty body — forwarded as `{}`.
+
+`<train>` must match a train running under `~/.metro/trains/`; `<action>` is whatever
+that train expects (`send`, `react`, `edit`, …).
+
+### Response
+
+| Status | Body                                                | Meaning                                                  |
+|--------|-----------------------------------------------------|----------------------------------------------------------|
+| 200    | `{"result": <whatever the train returned>}`         | Train accepted the call and returned a result.           |
+| 400    | `{"error": "bad JSON body: …"}`                      | Body was not valid JSON.                                 |
+| 401    | `{"error": "unauthorized"}`                          | Missing / wrong bearer token.                            |
+| 405    | `{"error": "method not allowed"}`                    | Wrong verb (only `POST` is accepted on this path).       |
+| 500    | `{"error": "…"}`                                     | Daemon IPC unavailable (e.g. socket missing).            |
+| 502    | `{"error": "…"}`                                     | Train returned an error or the IPC handshake malformed.  |
+
+Request bodies larger than 256 KiB are rejected with HTTP 500.
+
+### Example: send a message
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer $METRO_MONITOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"args":{"line":"metro://discord/123","text":"hi"}}' \
+  https://monitor.metro.box/api/call/discord/send
+```
+
+Because the daemon's `send` adapter writes a history entry once the message lands, an
+active `/api/tail` subscriber will receive the corresponding event a moment later
+(`from` = local user). UIs typically clear the input on HTTP 200 and let the SSE replay
+show the sent message.
+
 ## Exposing publicly via Cloudflare tunnel
 
 The daemon listens on `127.0.0.1:8420` only. To reach `/api/*` from a phone or a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.14",
+  "version": "0.1.0-beta.15",
   "private": false,
   "description": "Event-interception wire. Supervises train subprocesses in ~/.metro/trains/, multiplexes their JSON event stream onto stdout, and routes outbound action calls back via stdin. Per-platform code is written by the agent (or user) as train scripts — metro core is pure transport.",
   "license": "MIT",

package/skills/metro/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: metro
-description: Run the metro train-supervisor in this session — launch `metro` in the background, watch its stdout for inbound JSON events, and act on each. Use when the user asks to start/run/launch metro, when you see JSON lines on stdout shaped `{"kind":"inbound","station":...,"line":"metro://...","message_id":...,"text":...}`, or when handling a chat/webhook reply/edit/react/send via `metro call`.
+description: Run the metro train-supervisor in this session — launch `metro` in the background, watch its stdout for inbound JSON events, and act on each. Use when the user asks to start/run/launch metro, when you see JSON lines on stdout shaped `{"station":"…","line":"metro://…","from":"…","to":"…","text":"…"}`, or when handling a chat/webhook reply/edit/react/send via `metro call`.
 ---
 
 # Metro — event-interception wire
@@ -13,8 +13,8 @@ replace on demand.
 
 1. Spawns each file in `~/.metro/trains/*.{ts,js,mjs}` as a long-running Bun subprocess.
 2. Multiplexes their stdout (JSON lines) into one unified event stream on metro's stdout.
-3. Routes `metro call <train> <action> <args>` requests back to the matching train's stdin and prints the response.
-4. Two builtin event sources stay in core: **webhooks** (HTTP receiver) and cross-user **notify** IPC.
+3. Routes `metro call <train> <action> <args>` requests back to the matching train's stdin.
+4. Two builtin event sources stay in core: **webhooks** (HTTP receiver) and **messenger** (in-daemon chat).
 
 ## Starting metro
 
@@ -24,19 +24,19 @@ replace on demand.
 
 `metro doctor` reports trains found, deps installed, dispatcher running, codex-rc, skill install.
 
-## Train protocol
+## Envelope
 
-**Inbound (train → metro stdout)** — one JSON line per event:
+Every event on stdout is a single JSON line:
 
 ```json
-{"kind":"inbound","station":"discord","line":"metro://discord/123","from":"metro://discord/user/456","from_name":"alice","message_id":"789","text":"hi","is_private":false,"ts":"2026-05-17T18:00:00Z","payload":{...}}
+{"id":"msg_…","ts":"2026-05-17T18:00:00Z","station":"discord","line":"metro://discord/123","line_name":"infra","from":"metro://discord/user/456","from_name":"alice","to":"metro://claude/user/9bfc…","text":"hi","message_id":"789","reply_to":"…","payload":{…}}
 ```
 
-Wire fields are `snake_case` on the train protocol: `from_name`, `message_id`, `line_name`, `is_private`, `reply_to`. The dispatcher translates these to camelCase for `history.jsonl` and the broker. Trains supply `line`, `from`, `from_name`, `text`, `is_private`. Metro mints `id` + `display` if missing and appends to `history.jsonl`. `payload` is the platform's native message shape — use it for mentions, replies, embeds.
+Wire fields are `snake_case` on the train protocol; the dispatcher translates to camelCase for `history.jsonl`. Trains supply `line`, `from`, `to`, `text`, plus `payload` (the platform's native message). Metro mints `id` + `display` if missing.
 
-**Canonical `kind` enum**: `inbound | outbound | edit | react`. The dispatcher normalizes legacy aliases (`message` → `inbound`, `reaction` → `react`), but new trains should emit the canonical values directly. Anything else is passed through unchanged.
+**No `kind` field.** Direction is derived: `Line.isLocal(from)` → outbound (📤), else inbound (📩). Reactions and edits are train-specific — encode them in `text` (e.g. `[react 👀]`) plus whatever you need in `payload`.
 
-**Outbound (`metro call <train> <action> <args>`)**:
+## Outbound: `metro call <train> <action> <args>`
 
 ```
 metro call discord send '{"line":"metro://discord/123","text":"hi","replyTo":"789"}'
@@ -44,21 +44,19 @@ metro call telegram react '{"line":"metro://telegram/-100/1","messageId":"42","e
 metro call discord edit  '{"line":"metro://discord/123","messageId":"999","text":"new"}'
 ```
 
-`[args]` can be JSON, `@path/to/args.json`, `-` (stdin), or a bare string. Action names are whatever the train exposes — metro core knows nothing about them. The shipped example train (`telegram.ts`) exposes `send` and `react`; trains you write can expose anything.
+`[args]` can be JSON, `@path/to/args.json`, `-` (stdin), or a bare string. Action names are whatever the train exposes — metro core knows nothing about them.
 
 ## Writing a new train
 
-1. Start from `node_modules/@stage-labs/metro/examples/telegram.ts` (the only shipped example — pattern is platform-independent).
-2. Copy → `~/.metro/trains/<name>.ts` and edit. Keep the inbound shape and the `op:"call"` → `op:"response"` protocol.
+1. Start from `node_modules/@stage-labs/metro/examples/telegram.ts`.
+2. Copy → `~/.metro/trains/<name>.ts` and edit. Keep the inbound envelope shape and the `op:"call"` → `op:"response"` protocol.
 3. Deps (if needed): `cd ~/.metro && bun add <pkg>`. Credentials: `echo 'FOO_TOKEN=…' >> ~/.metro/.env`.
-4. Restart the metro daemon to pick up the new train.
+4. Restart the metro daemon (or just `metro trains restart <name>`) to pick up the new train.
 
 Trains are throwaway — if the user asks for new functionality, rewrite the train rather than adding glue in core.
 
 ## First-run setup (once per machine)
 
-Telegram (no npm deps — uses native fetch + long polling):
-
 ```
 mkdir -p ~/.metro && cd ~/.metro && bun init -y
 cp node_modules/@stage-labs/metro/examples/telegram.ts ~/.metro/trains/
@@ -67,11 +65,6 @@ metro setup skill    # optional — installs this SKILL.md into ~/.claude / ~/.c
 metro
 ```
 
-Discord port: copy `telegram.ts` to `~/.metro/trains/discord.ts`, swap the API
-base for `https://discord.com/api/v10` with `Authorization: Bot $TOKEN`,
-`bun add discord.js` for the gateway, and keep the envelope + call/response
-protocol unchanged.
-
 ## Detecting "is this for me?"
 
 Trains should set `is_private: true` for DMs. For groups, narrow on `payload`:
@@ -79,26 +72,39 @@ Trains should set `is_private: true` for DMs. For groups, narrow on `payload`:
 - **discord** — DM when `payload.guildId == null`; otherwise look at `payload.mentions.users`.
 - **telegram** — DM when `payload.chat.type === 'private'`; otherwise look at `payload.entities` mentions.
 - **webhook** — every POST is for you by design. Route on `payload.headers['x-github-event']` / `x-intercom-topic`.
+- **messenger** — every event on the messenger line is between the user and the agent. No filtering needed.
 
 ## CLI cheat sheet
 
 ```
-metro                                    # start the daemon
-metro trains list                        # list trains + state
-metro trains new <name>                  # scaffold ~/.metro/trains/<name>.ts from the example
-metro trains restart <name>              # kill + respawn a train (resets backoff)
-metro call <train> <action> <args>       # forward an action call
-metro tail --as=<user-uri> [--follow]    # subscribe to the event log
-metro history --limit=50                 # recent history (newest first)
-metro webhook add <label>                # register an HTTP receive endpoint
-metro tunnel setup <name> <hostname>     # configure a Cloudflare named tunnel
-metro doctor                             # health check (trains, deps, tunnel, webhooks, env vars)
+metro                                       # start the daemon
+metro trains [list]                         # list trains + state
+metro trains new <name>                     # scaffold ~/.metro/trains/<name>.ts
+metro trains restart <name>                 # kill + respawn a train (resets backoff)
+metro call <train> <action> <args>          # forward an action call
+metro tail [--as=<user-uri>] [--follow]     # subscribe to the event log
+metro history [--limit=N] [--line=…] [--from=…] [--text=…] [--since=…]
+metro webhook add <label>                   # register an HTTP receive endpoint
+metro tunnel setup <name> <hostname>        # configure a Cloudflare named tunnel
+metro doctor                                # health check
 ```
 
 ## Webhooks (builtin source)
 
-Webhooks stay in core because they're shared HTTP infra (one Cloudflare tunnel routes many endpoints). `metro webhook add <label>` issues an endpoint id; the full URL is `https://<tunnel-host>/wh/<id>` (or `http://127.0.0.1:8420/wh/<id>` locally). Events arrive with `kind:"inbound", station:"webhook"`.
+Webhooks stay in core because they're shared HTTP infra (one Cloudflare tunnel routes many endpoints). `metro webhook add <label>` issues an endpoint id; the full URL is `https://<tunnel-host>/wh/<id>` (or `http://127.0.0.1:8420/wh/<id>` locally). Events arrive on `metro://webhook/<id>`.
+
+## Messenger (builtin source)
+
+Direct chat between the agent and the device. Five endpoints — all under the same bearer-token guard as `/api/state`:
+
+- `POST /api/messenger/send {text?, attachments?, as?}` — emit an envelope on `metro://messenger/owner`. Either text or attachments required.
+- `POST /api/messenger/react {messageId, emoji, as?}` — emit a slim `payload.reactTo` envelope. If the sender already has an active reaction with this emoji on this target, emits `{removed: true}` instead — reactions are toggleable.
+- `POST /api/messenger/upload` — raw binary upload (≤ 25 MiB, body = file bytes, `Content-Type` + optional `X-Filename` headers). Returns `{id, url, kind, mime, size, name?}`; files land in `$METRO_STATE_DIR/messenger-uploads/`.
+- `GET /api/messenger/files/<name>` — stream a stored upload. Accepts `Authorization: Bearer …` header *or* `?token=…` query (for `<img>` / `<audio>` tags). Content-Type derived from extension.
+- `POST /api/messenger/register {pushToken}` — store an Expo push token so agent replies push to the device.
+
+The mobile + web companion apps use these for chat with the agent. The envelope is the standard slim shape — no `kind` / `emoji` fields, direction derived from `Line.isLocal(from)`.
 
 ## Crashes
 
-If a train crashes, metro restarts it with backoff (1s → 5s → 30s, then gives up after 5 consecutive failures). Use `metro trains list` to check state.
+If a train crashes, metro restarts it with backoff (1s → 5s → 30s, then gives up after 5 consecutive failures). Use `metro trains` to check state.