rogerthat 1.21.2

package/dist/channel.js

@@ -0,0 +1,526 @@
+export const PRIORITY_RANK = {
+    min: 0,
+    low: 1,
+    default: 2,
+    high: 3,
+    urgent: 4,
+};
+export function isPriority(v) {
+    return v === "min" || v === "low" || v === "default" || v === "high" || v === "urgent";
+}
+export const ATTACHMENT_MIME_ALLOWLIST = new Set([
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+    "image/gif",
+    "application/pdf",
+]);
+/** Per-message cap on TOTAL base64 size (sum across attachments). 512KB of
+ *  base64 = ~384KB of raw bytes — enough for a screenshot or a small PDF.
+ *  Worst case with ring buffer of 100 messages = 50MB RAM. */
+export const MAX_ATTACHMENTS_BYTES_PER_MESSAGE = 512 * 1024;
+export const MAX_ATTACHMENTS_PER_MESSAGE = 4;
+export const MAX_SUGGESTED_REPLIES = 4;
+export const MAX_SUGGESTED_REPLY_LENGTH = 64;
+/** Validate + normalize attachments. Returns the cleaned array (with filenames
+ *  trimmed, base64 stripped of whitespace) or throws ChannelError. Returns
+ *  undefined if input is undefined/empty (caller meant "no attachments"). */
+export function validateAttachments(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (!Array.isArray(v)) {
+        throw new ChannelError("attachments must be an array", "invalid", 400);
+    }
+    if (v.length === 0)
+        return undefined;
+    if (v.length > MAX_ATTACHMENTS_PER_MESSAGE) {
+        throw new ChannelError(`attachments: max ${MAX_ATTACHMENTS_PER_MESSAGE} per message (got ${v.length})`, "invalid", 400);
+    }
+    const out = [];
+    let totalBytes = 0;
+    for (let i = 0; i < v.length; i++) {
+        const item = v[i];
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new ChannelError(`attachments[${i}]: must be an object`, "invalid", 400);
+        }
+        const rec = item;
+        const mime = rec.mime;
+        if (typeof mime !== "string" || !ATTACHMENT_MIME_ALLOWLIST.has(mime)) {
+            throw new ChannelError(`attachments[${i}].mime: must be one of ${Array.from(ATTACHMENT_MIME_ALLOWLIST).join(", ")}`, "invalid", 400);
+        }
+        const dataRaw = rec.data_base64;
+        if (typeof dataRaw !== "string" || dataRaw.length === 0) {
+            throw new ChannelError(`attachments[${i}].data_base64: required string`, "invalid", 400);
+        }
+        // Strip whitespace from base64 (clients sometimes line-wrap).
+        const data = dataRaw.replace(/\s+/g, "");
+        if (!/^[A-Za-z0-9+/]+={0,2}$/.test(data)) {
+            throw new ChannelError(`attachments[${i}].data_base64: not valid base64`, "invalid", 400);
+        }
+        totalBytes += data.length;
+        if (totalBytes > MAX_ATTACHMENTS_BYTES_PER_MESSAGE) {
+            throw new ChannelError(`attachments total base64 size exceeds ${MAX_ATTACHMENTS_BYTES_PER_MESSAGE} bytes; host externally and paste a URL instead`, "invalid", 413);
+        }
+        // Verify decodability (catches truncation that the regex misses).
+        try {
+            Buffer.from(data, "base64");
+        }
+        catch {
+            throw new ChannelError(`attachments[${i}].data_base64: decode failed`, "invalid", 400);
+        }
+        const attachment = { mime, data_base64: data };
+        if (typeof rec.filename === "string") {
+            const fn = rec.filename.trim().slice(0, 128);
+            if (fn)
+                attachment.filename = fn;
+        }
+        out.push(attachment);
+    }
+    return out;
+}
+/** Validate + normalize a suggested_replies array. Returns the cleaned array
+ *  or throws a ChannelError describing what's wrong. Returns undefined if
+ *  the input is undefined (the caller meant "no suggestions"). */
+export function validateSuggestedReplies(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (!Array.isArray(v)) {
+        throw new ChannelError("suggested_replies must be an array of strings", "invalid", 400);
+    }
+    if (v.length === 0)
+        return undefined; // empty array = same as omitted
+    if (v.length > MAX_SUGGESTED_REPLIES) {
+        throw new ChannelError(`suggested_replies: max ${MAX_SUGGESTED_REPLIES} entries (got ${v.length})`, "invalid", 400);
+    }
+    const out = [];
+    for (const item of v) {
+        if (typeof item !== "string") {
+            throw new ChannelError("suggested_replies entries must all be strings", "invalid", 400);
+        }
+        const trimmed = item.trim();
+        if (!trimmed)
+            continue; // skip empty strings silently
+        if (trimmed.length > MAX_SUGGESTED_REPLY_LENGTH) {
+            throw new ChannelError(`suggested_replies entry too long (max ${MAX_SUGGESTED_REPLY_LENGTH} chars)`, "invalid", 400);
+        }
+        out.push(trimmed);
+    }
+    return out.length > 0 ? out : undefined;
+}
+const HISTORY_CAP = 100;
+// Default idle TTL; channels can override via session_ttl_seconds at creation (max 24h).
+const DEFAULT_ROSTER_IDLE_MS = 30 * 60 * 1000;
+const EVICTION_TOMBSTONE_MS = 60 * 60 * 1000; // remember evicted sessions for 1h so we can return 410 instead of 400
+export class ChannelError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export class Channel {
+    id;
+    callsignBySession = new Map();
+    sessionByCallsign = new Map();
+    lastSeen = new Map();
+    messages = [];
+    // Per-callsign delivery cursor: last msg id delivered to that callsign. Persists across
+    // session expiry so offline messages get delivered when the callsign rejoins.
+    cursorByCallsign = new Map();
+    // Every callsign that has joined the channel at least once. Used to allow DMing offline agents.
+    historicCallsigns = new Set();
+    listenersBySession = new Map();
+    // Persistent stream listeners (SSE). Unlike long-poll listeners, these are NOT removed
+    // after a single delivery — they keep receiving until the consumer explicitly detaches
+    // or the session is evicted. Sessions with an active streamer also count as "alive"
+    // for GC purposes, so a parked agent with an open SSE connection won't be reaped.
+    streamersBySession = new Map();
+    evictedSessions = new Map(); // sessionId -> evictedAt (tombstones)
+    // Monotonic ID generator using current epoch time. Guarantees strict-increase
+    // across restarts as long as the system clock doesn't go backwards.
+    nextMsgId = Date.now();
+    joinOrder = [];
+    firstJoinedAt = null;
+    lastActivityAt = Date.now();
+    /** Idle TTL in ms before sessions are GC'd. Settable per channel; defaults to 30 min. */
+    sessionTtlMs = DEFAULT_ROSTER_IDLE_MS;
+    constructor(id) {
+        this.id = id;
+    }
+    touch(sessionId) {
+        const now = Date.now();
+        this.lastSeen.set(sessionId, now);
+        this.lastActivityAt = now;
+    }
+    gcRoster() {
+        const now = Date.now();
+        for (const [session, last] of this.lastSeen) {
+            if (now - last > this.sessionTtlMs &&
+                !this.listenersBySession.has(session) &&
+                !this.streamersBySession.has(session)) {
+                this.evictSession(session);
+            }
+        }
+        for (const [session, evictedAt] of this.evictedSessions) {
+            if (now - evictedAt > EVICTION_TOMBSTONE_MS)
+                this.evictedSessions.delete(session);
+        }
+    }
+    ensureJoined(sessionId) {
+        if (this.callsignBySession.has(sessionId))
+            return;
+        if (this.evictedSessions.has(sessionId)) {
+            throw new ChannelError("session expired; call /join with the same callsign+token to refresh (session_id is reusable)", "session_expired", 410);
+        }
+        throw new ChannelError("not joined to channel; call /join with {callsign, token} first", "not_joined", 400);
+    }
+    /**
+     * Idempotent join.
+     * - Same `(sessionId, callsign)` is a no-op (refreshes lastSeen).
+     * - `opts.selfGenerated=true` means the caller has no prior identity (REST minted a UUID for
+     *   them); if the callsign is already taken, we return the existing session_id so the caller
+     *   can adopt it. Enables the "defensively re-join every turn" pattern.
+     * - `opts.selfGenerated=false` (default) means the caller's sessionId IS their identity (MCP
+     *   Mcp-Session-Id, or REST with X-Session-Id). If the callsign is taken by a *different*
+     *   session, throws `callsign_taken` (409) rather than silently mapping them to someone
+     *   else's session. Previous behavior silently broke send/listen for the conflicting caller.
+     */
+    join(sessionId, callsign, opts = {}) {
+        const normalized = callsign.trim().toLowerCase();
+        if (!/^[a-z0-9][a-z0-9_-]{0,31}$/.test(normalized)) {
+            throw new ChannelError("callsign must be 1-32 chars, alphanumeric/underscore/dash, starting with letter or digit", "invalid", 400);
+        }
+        if (normalized === "all") {
+            throw new ChannelError('callsign "all" is reserved for broadcast', "invalid", 400);
+        }
+        const existingSession = this.sessionByCallsign.get(normalized);
+        let idempotent = false;
+        const effectiveId = sessionId;
+        if (existingSession) {
+            if (existingSession === sessionId) {
+                idempotent = true;
+            }
+            else if (opts.selfGenerated) {
+                // Caller had no identity (REST minted a UUID for them) and the callsign is taken —
+                // hand back the existing session_id so they can adopt it.
+                this.evictedSessions.delete(sessionId);
+                this.touch(existingSession);
+                return {
+                    sessionId: existingSession,
+                    roster: this.roster(),
+                    history: this.history(20),
+                    idempotent: true,
+                };
+            }
+            else {
+                throw new ChannelError(`callsign "${normalized}" is already in use on this channel; pick a different one or have the current holder leave first`, "callsign_taken", 409);
+            }
+        }
+        const prevCallsign = this.callsignBySession.get(sessionId);
+        if (prevCallsign && prevCallsign !== normalized) {
+            this.sessionByCallsign.delete(prevCallsign);
+            this.joinOrder = this.joinOrder.filter((a) => a.callsign !== prevCallsign);
+        }
+        this.callsignBySession.set(sessionId, normalized);
+        this.sessionByCallsign.set(normalized, sessionId);
+        this.evictedSessions.delete(sessionId);
+        this.touch(sessionId);
+        if (this.firstJoinedAt === null)
+            this.firstJoinedAt = Date.now();
+        // First time we see this callsign on this channel: cursor starts at 0 so all queued
+        // offline messages to=callsign get delivered on the next listen. Subsequent joins
+        // preserve the existing cursor so we don't re-deliver.
+        if (!this.cursorByCallsign.has(normalized)) {
+            this.cursorByCallsign.set(normalized, 0);
+        }
+        this.historicCallsigns.add(normalized);
+        if (!this.joinOrder.some((a) => a.callsign === normalized)) {
+            this.joinOrder.push({ callsign: normalized, joinedAt: Date.now() });
+        }
+        return { sessionId: effectiveId, roster: this.roster(), history: this.history(20), idempotent };
+    }
+    isCallsignOnline(callsign) {
+        if (callsign === "all")
+            return true;
+        return this.sessionByCallsign.has(callsign.trim().toLowerCase());
+    }
+    knowsCallsign(callsign) {
+        const cs = callsign.trim().toLowerCase();
+        return cs === "all" || this.historicCallsigns.has(cs);
+    }
+    keepalive(sessionId) {
+        this.ensureJoined(sessionId);
+        this.touch(sessionId);
+    }
+    evictSession(sessionId) {
+        const listener = this.listenersBySession.get(sessionId);
+        if (listener) {
+            clearTimeout(listener.timer);
+            listener.resolve([]);
+            this.listenersBySession.delete(sessionId);
+        }
+        // Drop any persistent stream listener too. The SSE handler detects the next
+        // write failure (or its own abort signal) and closes the connection.
+        this.streamersBySession.delete(sessionId);
+        const cs = this.callsignBySession.get(sessionId);
+        if (cs) {
+            this.sessionByCallsign.delete(cs);
+            this.joinOrder = this.joinOrder.filter((a) => a.callsign !== cs);
+        }
+        if (this.callsignBySession.has(sessionId)) {
+            this.evictedSessions.set(sessionId, Date.now());
+        }
+        this.callsignBySession.delete(sessionId);
+        this.lastSeen.delete(sessionId);
+        // Note: do NOT delete cursorByCallsign[cs] — keeps the offline-delivery pointer alive
+        // so when this callsign rejoins, they get the messages queued for them while away.
+    }
+    leave(sessionId) {
+        this.evictSession(sessionId);
+    }
+    callsignOf(sessionId) {
+        return this.callsignBySession.get(sessionId);
+    }
+    resolveAddress(to) {
+        const trimmed = to.trim().toLowerCase();
+        if (!trimmed)
+            return "";
+        if (trimmed === "all")
+            return "all";
+        const idxMatch = /^#?(\d+)$/.exec(trimmed);
+        if (idxMatch) {
+            const idx = Number.parseInt(idxMatch[1], 10);
+            if (idx >= 1 && idx <= this.joinOrder.length) {
+                return this.joinOrder[idx - 1].callsign;
+            }
+            return trimmed;
+        }
+        return trimmed;
+    }
+    sessionExists(sessionId) {
+        return this.callsignBySession.has(sessionId);
+    }
+    send(sessionId, to, text, priority, suggestedReplies, attachments) {
+        this.ensureJoined(sessionId);
+        const from = this.callsignBySession.get(sessionId);
+        // Empty/missing `to` defaults to broadcast. Walkie-talkie physical default —
+        // press-to-talk goes to everyone on the channel. Agents that omit the field
+        // (a common first-call mistake) get sensible behavior instead of an error.
+        const dest = this.resolveAddress(to) || "all";
+        if (dest !== "all" && !this.sessionByCallsign.has(dest) && !this.historicCallsigns.has(dest)) {
+            throw new ChannelError(`no callsign "${to}" has ever been on this channel (roster: ${this.rosterWithIndex().map((a) => `#${a.idx} ${a.callsign}`).join(", ") || "empty"}). DM to historic callsigns is supported — but they must have joined at least once.`, "invalid", 400);
+        }
+        if (typeof text !== "string") {
+            throw new ChannelError("message text must be a string", "invalid", 400);
+        }
+        // Empty text is allowed when at least one attachment is present (sending
+        // just an image without a caption). Otherwise we need a non-empty body.
+        if (text.length === 0 && (!attachments || attachments.length === 0)) {
+            throw new ChannelError("message text required (or send at least one attachment)", "invalid", 400);
+        }
+        if (text.length > 8192) {
+            throw new ChannelError("message too long (max 8192 chars)", "invalid", 400);
+        }
+        this.touch(sessionId);
+        // Strictly-monotonic timestamp ID: at least one millisecond ahead of the prior id, and at
+        // least the current wall clock. Survives restarts as long as the clock advances.
+        const now = Date.now();
+        this.nextMsgId = Math.max(now, this.nextMsgId + 1);
+        const msg = { id: this.nextMsgId, from, to: dest, text, at: now };
+        // Only attach `priority` when explicitly non-default — keeps the wire format
+        // backward-compatible for consumers that don't know about priorities.
+        if (priority && priority !== "default")
+            msg.priority = priority;
+        if (suggestedReplies && suggestedReplies.length > 0) {
+            msg.suggested_replies = suggestedReplies;
+        }
+        if (attachments && attachments.length > 0) {
+            msg.attachments = attachments;
+        }
+        this.messages.push(msg);
+        if (this.messages.length > HISTORY_CAP)
+            this.messages.shift();
+        this.notify(msg);
+        return msg;
+    }
+    notify(msg) {
+        for (const [session, listener] of [...this.listenersBySession]) {
+            const cs = this.callsignBySession.get(session);
+            if (!cs)
+                continue;
+            if (msg.from === cs)
+                continue;
+            if (msg.to !== "all" && msg.to !== cs)
+                continue;
+            this.listenersBySession.delete(session);
+            clearTimeout(listener.timer);
+            this.cursorByCallsign.set(cs, msg.id);
+            listener.resolve([msg]);
+        }
+        // Persistent stream listeners (SSE). Not removed after delivery — keep firing.
+        // Refresh the per-session lastSeen so streamers count as activity for GC.
+        for (const [session, onMessage] of this.streamersBySession) {
+            const cs = this.callsignBySession.get(session);
+            if (!cs)
+                continue;
+            if (msg.from === cs)
+                continue;
+            if (msg.to !== "all" && msg.to !== cs)
+                continue;
+            this.cursorByCallsign.set(cs, msg.id);
+            this.touch(session);
+            try {
+                onMessage(msg);
+            }
+            catch (err) {
+                console.error(`[stream ${this.id}/${cs}] handler threw:`, err);
+            }
+        }
+    }
+    /**
+     * Register a persistent listener for incoming messages addressed to this session's
+     * callsign (DMs or broadcasts). Unlike `listen`, the listener is NOT removed after
+     * a single delivery — the caller keeps receiving until they call the returned
+     * cleanup function (or the session is evicted). Designed for SSE / WebSocket-style
+     * push consumers.
+     *
+     * Callers typically want to call `drainSince(sessionId, since)` immediately after
+     * registering, to flush any backlog the cursor was sitting on, then rely on this
+     * listener for everything after.
+     */
+    addStreamListener(sessionId, onMessage) {
+        this.ensureJoined(sessionId);
+        this.touch(sessionId);
+        this.streamersBySession.set(sessionId, onMessage);
+        return () => {
+            if (this.streamersBySession.get(sessionId) === onMessage) {
+                this.streamersBySession.delete(sessionId);
+            }
+        };
+    }
+    /**
+     * Return any messages already in the buffer that this session's callsign hasn't
+     * seen yet, and advance the per-callsign cursor past them. Same selection logic
+     * as `listen()` but returns immediately (no long-poll). Use with `addStreamListener`
+     * to bootstrap an SSE/streaming subscription without losing the backlog.
+     */
+    drainSince(sessionId, since) {
+        this.ensureJoined(sessionId);
+        this.touch(sessionId);
+        const cs = this.callsignBySession.get(sessionId);
+        const cursor = since !== undefined ? since : (this.cursorByCallsign.get(cs) ?? 0);
+        const pending = this.messages.filter((m) => m.id > cursor && m.from !== cs && (m.to === "all" || m.to === cs));
+        if (pending.length > 0) {
+            this.cursorByCallsign.set(cs, pending[pending.length - 1].id);
+        }
+        return pending;
+    }
+    /**
+     * Long-poll for incoming messages.
+     * - When `since` is undefined, returns messages newer than this session's per-session cursor
+     *   (default behaviour, equivalent to a read pointer the server manages for you).
+     * - When `since` is provided, returns messages with `id > since` regardless of the per-session
+     *   cursor. Useful after a session expiry/restart to catch up reliably from a known id.
+     */
+    async listen(sessionId, timeoutMs, since) {
+        this.ensureJoined(sessionId);
+        this.touch(sessionId);
+        const cs = this.callsignBySession.get(sessionId);
+        // Per-callsign cursor → offline delivery: if alpha was offline, then someone sent to=alpha,
+        // alpha rejoins, listen returns those messages because the cursor stayed at the last-delivered id.
+        const cursor = since !== undefined ? since : (this.cursorByCallsign.get(cs) ?? 0);
+        const pending = this.messages.filter((m) => m.id > cursor && m.from !== cs && (m.to === "all" || m.to === cs));
+        if (pending.length > 0) {
+            this.cursorByCallsign.set(cs, pending[pending.length - 1].id);
+            return pending;
+        }
+        const existing = this.listenersBySession.get(sessionId);
+        if (existing) {
+            clearTimeout(existing.timer);
+            existing.resolve([]);
+            this.listenersBySession.delete(sessionId);
+        }
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.listenersBySession.delete(sessionId);
+                resolve([]);
+            }, timeoutMs);
+            this.listenersBySession.set(sessionId, { resolve, timer });
+        });
+    }
+    roster() {
+        return [...this.sessionByCallsign.keys()].sort();
+    }
+    rosterWithIndex() {
+        return this.joinOrder
+            .filter((a) => this.sessionByCallsign.has(a.callsign))
+            .map((a, i) => ({ idx: i + 1, callsign: a.callsign, joined_at: a.joinedAt }));
+    }
+    /**
+     * Roster including historic (offline) callsigns with an `online` flag.
+     * Useful for "show me everyone who's ever been on this channel" — and lets
+     * a sender know who's currently reachable vs queued.
+     */
+    rosterAll() {
+        const onlineIdx = new Map();
+        const onlineList = this.rosterWithIndex();
+        for (const a of onlineList)
+            onlineIdx.set(a.callsign, a.idx);
+        const all = [...this.historicCallsigns];
+        all.sort((a, b) => a.localeCompare(b));
+        return all.map((cs) => ({
+            callsign: cs,
+            online: this.sessionByCallsign.has(cs),
+            idx: onlineIdx.get(cs) ?? null,
+        }));
+    }
+    history(n) {
+        const clamped = Math.max(1, Math.min(HISTORY_CAP, Math.floor(n)));
+        return this.messages.slice(-clamped);
+    }
+    size() {
+        return this.callsignBySession.size;
+    }
+}
+const channels = new Map();
+let sessionTtlLookup = () => DEFAULT_ROSTER_IDLE_MS;
+export function setSessionTtlLookup(fn) {
+    sessionTtlLookup = fn;
+}
+export function getOrCreateChannel(id) {
+    let ch = channels.get(id);
+    if (!ch) {
+        ch = new Channel(id);
+        ch.sessionTtlMs = sessionTtlLookup(id);
+        channels.set(id, ch);
+    }
+    return ch;
+}
+let gcTimer = null;
+export function startPeriodicGc(intervalMs = 60_000) {
+    if (gcTimer)
+        return;
+    gcTimer = setInterval(() => {
+        for (const ch of channels.values())
+            ch.gcRoster();
+    }, intervalMs);
+    gcTimer.unref?.();
+}
+export function listActiveChannels(retentionFor, requireIdentityFor, trustModeFor) {
+    return [...channels.values()]
+        .filter((c) => c.size() > 0 || c.firstJoinedAt !== null)
+        .map((c) => ({
+        id: c.id,
+        retention: retentionFor(c.id),
+        require_identity: requireIdentityFor(c.id),
+        trust_mode: trustModeFor(c.id),
+        roster: c.roster(),
+        agent_count: c.size(),
+        message_count: c.history(100).length,
+        first_joined_at: c.firstJoinedAt,
+        last_activity_at: c.lastActivityAt,
+    }))
+        .sort((a, b) => b.last_activity_at - a.last_activity_at);
+}

package/dist/cli.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// IMPORTANT: server-side imports (`@hono/node-server`, `./app.js`) live inside
+// the `runServer()` function so they're only loaded when the user actually
+// starts the local hub. Subcommands like `listen-here` and `receive-recipe`
+// must work on Node 16+ — they only use `fetch` / `URL` / fs, no Hono. Putting
+// the server imports at top-of-file caused `npx rogerthat listen-here` to crash
+// on older Node versions with `Class extends value undefined is not a
+// constructor` from `@hono/node-server`'s `class extends GlobalRequest`.
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { runListenHere } from "./listen-here.js";
+import { runReceiveRecipe } from "./receive-recipe.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let PKG_VERSION = "?";
+try {
+    PKG_VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8")).version;
+}
+catch {
+    /* keep "?" if not found */
+}
+const HELP = `rogerthat ${PKG_VERSION} — walkie-talkie MCP hub for AI agents
+
+usage:
+  rogerthat [options]                  # run the local hub (default)
+  rogerthat listen-here [options]      # open an SSE receiver for a channel (see --help)
+  rogerthat receive-recipe [options]   # print copy-paste recipe: listener + Monitor cmd
+
+options:
+  --port <n>          port to listen on (default: 7424)
+  --host <addr>       interface to bind (default: 127.0.0.1)
+  --token <secret>    require Bearer token on /mcp/* requests
+                      (required when --host is not 127.0.0.1 or localhost)
+  --admin-token <s>   enable /admin dashboard with this token
+                      (metadata only — never exposes message content)
+  --data-dir <path>   single directory holding all rogerthat data
+                      (default: ~/.rogerthat — channels.json, accounts.json,
+                      identities.json, stats.json, webhooks.json, transcripts/
+                      all live here)
+  --data <path>       legacy: just the channels.json path (overrides data-dir)
+  --origin <url>      public origin advertised in connect snippets
+                      (default: http://<host>:<port>)
+  --help, -h          show this help
+
+examples:
+  rogerthat                                  # local only, no auth, data in ~/.rogerthat
+  rogerthat --port 9000                      # different port
+  rogerthat --host 0.0.0.0 --token sekret    # LAN with auth (bearer required)
+  rogerthat --data-dir /var/lib/rogerthat     # custom data directory
+  rogerthat --origin https://my.example      # if behind a reverse proxy
+
+after starting, install once in your AI client:
+  claude mcp add --transport http rogerthat http://127.0.0.1:7424/mcp
+
+then in any session: "create a rogerthat channel" — Claude calls the
+create_channel tool and prints a snippet to share with the other agent.
+
+docs: https://rogerthat.chat
+`;
+function isLocalHost(host) {
+    return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+async function main() {
+    // Subcommand dispatch: anything before flags. Detect by argv[2] being a
+    // non-flag word.
+    const first = process.argv[2];
+    if (first === "listen-here") {
+        const code = await runListenHere(process.argv.slice(3));
+        process.exit(code);
+    }
+    if (first === "receive-recipe") {
+        const code = runReceiveRecipe(process.argv.slice(3));
+        process.exit(code);
+    }
+    let parsed;
+    try {
+        parsed = parseArgs({
+            options: {
+                port: { type: "string" },
+                host: { type: "string" },
+                token: { type: "string" },
+                "admin-token": { type: "string" },
+                "data-dir": { type: "string" },
+                data: { type: "string" },
+                origin: { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+    }
+    catch (e) {
+        console.error(`error: ${e.message}\n`);
+        console.error(HELP);
+        process.exit(2);
+    }
+    if (parsed.values.help) {
+        console.log(HELP);
+        process.exit(0);
+    }
+    const port = Number(parsed.values.port ?? 7424);
+    const host = parsed.values.host ?? "127.0.0.1";
+    const token = parsed.values.token;
+    const adminToken = parsed.values["admin-token"];
+    const dataDir = parsed.values["data-dir"] ?? join(homedir(), ".rogerthat");
+    if (!existsSync(dataDir))
+        mkdirSync(dataDir, { recursive: true });
+    const dataPath = parsed.values.data ?? join(dataDir, "channels.json");
+    const origin = parsed.values.origin ?? `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}`;
+    if (!isLocalHost(host) && !token) {
+        console.error(`error: --token is required when binding to ${host} (non-localhost). use --token to set a shared secret, or --host 127.0.0.1 to restrict to local.`);
+        process.exit(2);
+    }
+    // Centralize all server-side state under one directory. The data-dir is the umbrella;
+    // individual --xxx flags can still override specific files for power users.
+    process.env.ROGERRAT_DB = dataPath;
+    process.env.ROGERRAT_ACCOUNTS = process.env.ROGERRAT_ACCOUNTS ?? join(dataDir, "accounts.json");
+    process.env.ROGERRAT_IDENTITIES = process.env.ROGERRAT_IDENTITIES ?? join(dataDir, "identities.json");
+    process.env.ROGERRAT_STATS = process.env.ROGERRAT_STATS ?? join(dataDir, "stats.json");
+    process.env.ROGERRAT_TRANSCRIPTS = process.env.ROGERRAT_TRANSCRIPTS ?? join(dataDir, "transcripts");
+    process.env.ROGERRAT_WEBHOOKS = process.env.ROGERRAT_WEBHOOKS ?? join(dataDir, "webhooks.json");
+    // Dynamic import keeps server-side modules (Hono, etc.) off the cold path for
+    // `listen-here` and `receive-recipe`. Those need to work on Node 16+, where
+    // `@hono/node-server`'s `class extends GlobalRequest` blows up at module-load
+    // time even if we never instantiate it.
+    const { createApp } = await import("./app.js");
+    const { serve } = await import("@hono/node-server");
+    const app = createApp({
+        publicOrigin: origin,
+        authRequired: !!token,
+        staticToken: token,
+        adminToken,
+    });
+    console.log(`rogerthat ${PKG_VERSION} — local walkie-talkie hub`);
+    console.log(`  listening on   http://${host}:${port}`);
+    console.log(`  public origin  ${origin}`);
+    console.log(`  data dir       ${dataDir}`);
+    console.log(`  auth           ${token ? "required (bearer token on /mcp/*)" : "disabled (local-only)"}`);
+    console.log(`  admin UI       ${adminToken ? `enabled at ${origin}/admin` : "disabled (pass --admin-token to enable)"}`);
+    console.log(`  email recovery ${process.env.RESEND_API_KEY ? "enabled (Resend)" : "disabled (set RESEND_API_KEY to enable)"}`);
+    console.log("");
+    console.log(`install once in your AI client:`);
+    console.log(`  claude mcp add --transport http rogerthat ${origin}/mcp${token ? ` --header "Authorization: Bearer ${token}"` : ""}`);
+    console.log("");
+    console.log(`landing  ${origin}/`);
+    console.log(`account  ${origin}/account`);
+    console.log(`policy   ${origin}/policy`);
+    if (adminToken)
+        console.log(`admin    ${origin}/admin  (token: <hidden>)`);
+    console.log("");
+    serve({ fetch: app.fetch, hostname: host, port });
+}
+main().catch((err) => {
+    console.error(`fatal:`, err);
+    process.exit(1);
+});