rogerrat 1.4.1 → 1.19.0

package/dist/listen-here.js

@@ -0,0 +1,402 @@
+// `npx rogerrat listen-here` — turnkey SSE receiver.
+//
+// Opens a Server-Sent-Events connection to GET /api/channels/<id>/stream,
+// keeps it alive indefinitely (outbound HTTPS — no inbound port, no tunnel),
+// and on each delivered message either:
+//   - executes a shell command with the message in env vars (--on-message),
+//   - appends a JSON line to a file (--inbox), or
+//   - prints to stdout (default).
+//
+// Designed so a parked agent (Claude Code or any turn-based harness) can keep
+// receiving messages between operator turns at zero token cost. The agent calls
+// the bootstrap MCP tool, gets back a one-line `receiver_command`, runs it
+// detached via Bash, and lets the loop sit there waiting.
+//
+// Reconnect: exponential backoff (1s/3s/9s/27s, capped at 60s). On each reconnect
+// the last seen message id is sent as `?since=` so the server replays anything
+// that piled up while we were away.
+import { spawn } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { dirname } from "node:path";
+import { parseArgs } from "node:util";
+const HELP = `rogerrat listen-here — open an SSE receiver for a channel
+
+usage:
+  rogerrat listen-here --channel <id> --token <t> --session <sid> [options]
+
+required:
+  --channel <id>      channel id (returned by /join or create_channel)
+  --token <t>         channel bearer token
+  --session <sid>     X-Session-Id from /join (the calling agent's session)
+
+options:
+  --origin <url>      RogerRat origin (default: https://rogerrat.chat)
+  --since <msg_id>    resume from a known message id (skips per-session cursor)
+  --on-message <cmd>  shell command to run for each delivered message; env vars
+                      RR_MESSAGE, RR_FROM, RR_TO, RR_MSG_ID, RR_CHANNEL,
+                      RR_PRIORITY are set (RR_PRIORITY = "default" when omitted)
+  --inbox <file>      append each message to this file (parent dir created if
+                      missing). Format controlled by --format.
+  --format <fmt>      output format for stdout and --inbox lines:
+                        jsonl (default) — one JSON object per line: {id,from,to,text,at,priority?}
+                        text            — one line per message:
+                                          "[<priority>] [<from>] <text>" if priority set,
+                                          "[<from>] <text>" otherwise.
+                                          newlines in text collapsed to spaces.
+                                          Use this when feeding a Monitor/tail consumer
+                                          so each line is a human-readable notification
+                                          with no parser needed in the watcher.
+  --min-priority <p>  drop messages below this priority (min|low|default|high|urgent).
+                      Filtered messages do NOT write to --inbox, fire --on-message,
+                      or print to stdout. Use for park-style channels: stay
+                      wake-able only on real signals, let chatter accumulate silently.
+  --quiet             suppress the default stdout dump of each message
+
+if neither --on-message nor --inbox is given, messages print to stdout (one
+line per message in the chosen --format).
+
+NOTE: --on-message env vars (RR_MESSAGE, etc.) are always the raw structured
+values regardless of --format. The format flag only affects what gets written
+to stdout / --inbox.
+
+cost: zero idle tokens. The process holds one long-lived HTTPS connection
+to RogerRat and only fires --on-message when a real message arrives. Polling
+agents pay tokens on every wake-up; this pays none.
+
+examples:
+  # Dump to a file the agent's Monitor tool can tail (human-readable lines):
+  rogerrat listen-here --channel ch1 --token t --session s \\
+    --inbox /tmp/rr.log --format text
+
+  # Same, but JSONL for programmatic consumers:
+  rogerrat listen-here --channel ch1 --token t --session s --inbox /tmp/rr.jsonl
+
+  # Wake a parked Claude Code session each time a message arrives:
+  rogerrat listen-here --channel ch1 --token t --session s \\
+    --on-message 'claude -p "rogerrat msg from $RR_FROM: $RR_MESSAGE"'
+`;
+const PRIORITY_RANK = {
+    min: 0,
+    low: 1,
+    default: 2,
+    high: 3,
+    urgent: 4,
+};
+function parseFlags(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            options: {
+                channel: { type: "string" },
+                token: { type: "string" },
+                session: { type: "string" },
+                origin: { type: "string" },
+                since: { type: "string" },
+                "on-message": { type: "string" },
+                inbox: { type: "string" },
+                format: { type: "string" },
+                "min-priority": { type: "string" },
+                quiet: { type: "boolean" },
+                help: { type: "boolean", short: "h" },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+    }
+    catch (e) {
+        return { error: e.message };
+    }
+    if (parsed.values.help)
+        return { help: true };
+    const channel = parsed.values.channel;
+    const token = parsed.values.token;
+    const session = parsed.values.session;
+    if (!channel || !token || !session) {
+        return { error: "missing required flag(s): --channel, --token, --session" };
+    }
+    let since;
+    if (parsed.values.since !== undefined) {
+        const n = Number(parsed.values.since);
+        if (!Number.isFinite(n))
+            return { error: "--since must be numeric" };
+        since = n;
+    }
+    let format = "jsonl";
+    if (parsed.values.format !== undefined) {
+        if (parsed.values.format !== "jsonl" && parsed.values.format !== "text") {
+            return { error: "--format must be 'jsonl' or 'text'" };
+        }
+        format = parsed.values.format;
+    }
+    let minPriority;
+    if (parsed.values["min-priority"] !== undefined) {
+        const v = parsed.values["min-priority"];
+        if (v !== "min" && v !== "low" && v !== "default" && v !== "high" && v !== "urgent") {
+            return { error: "--min-priority must be one of min|low|default|high|urgent" };
+        }
+        minPriority = v;
+    }
+    return {
+        channel,
+        token,
+        session,
+        origin: parsed.values.origin ?? "https://rogerrat.chat",
+        since,
+        onMessage: parsed.values["on-message"],
+        inbox: parsed.values.inbox,
+        format,
+        quiet: parsed.values.quiet === true,
+        minPriority,
+    };
+}
+/** Yield one SSE block (the lines between two blank-line separators) at a time.
+ *  Takes a Node IncomingMessage rather than a Fetch-style ReadableStream so we
+ *  don't need global `fetch` — listen-here must run on Node 16, which lacks
+ *  it. IncomingMessage is async-iterable since Node 10. */
+async function* readSseBlocks(body) {
+    body.setEncoding("utf8");
+    let buffer = "";
+    for await (const chunk of body) {
+        buffer += chunk;
+        let idx;
+        while ((idx = buffer.indexOf("\n\n")) !== -1) {
+            const block = buffer.slice(0, idx);
+            buffer = buffer.slice(idx + 2);
+            if (block.length > 0)
+                yield block;
+        }
+    }
+    if (buffer.length > 0)
+        yield buffer;
+}
+function parseSseBlock(block) {
+    let event = "";
+    const dataLines = [];
+    for (const line of block.split("\n")) {
+        if (line.startsWith(":"))
+            continue; // comment / heartbeat
+        if (line.startsWith("event: "))
+            event = line.slice(7);
+        else if (line.startsWith("data: "))
+            dataLines.push(line.slice(6));
+    }
+    if (!event && dataLines.length === 0)
+        return null;
+    return { event: event || "message", data: dataLines.join("\n") };
+}
+function formatLine(args, msg) {
+    if (args.format === "text") {
+        // Collapse any newlines in the body so Monitor/tail consumers get exactly
+        // one notification per message. Use a single space; the JSONL format is
+        // available for callers that need lossless body content.
+        const flat = msg.text.replace(/\r?\n/g, " ").trim();
+        // Surface non-default priority as a leading tag so a Monitor tail of the
+        // inbox file can grep for urgency without parsing JSON. e.g. `[urgent] `
+        const prio = msg.priority && msg.priority !== "default" ? `[${msg.priority}] ` : "";
+        return `${prio}[${msg.from}] ${flat}`;
+    }
+    return JSON.stringify(msg);
+}
+async function dispatch(args, msg) {
+    // --min-priority filter: drop messages below the threshold entirely (no
+    // inbox write, no hook spawn, no stdout). Missing priority counts as
+    // "default" (rank 2).
+    if (args.minPriority) {
+        const incomingRank = PRIORITY_RANK[msg.priority ?? "default"];
+        if (incomingRank < PRIORITY_RANK[args.minPriority])
+            return;
+    }
+    const line = formatLine(args, msg);
+    if (args.inbox) {
+        const dir = dirname(args.inbox);
+        if (dir && !existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        appendFileSync(args.inbox, line + "\n", { mode: 0o600 });
+    }
+    if (!args.inbox && !args.onMessage && !args.quiet) {
+        process.stdout.write(line + "\n");
+    }
+    if (args.onMessage) {
+        // child stdio inherits so the agent can see whatever the hook prints.
+        // We DON'T await — the hook can be slow (e.g. `claude -p ...`); we want
+        // to keep consuming the SSE stream in parallel so backed-up messages
+        // don't block live ones. The shell command can itself sequence if needed.
+        const child = spawn(args.onMessage, {
+            shell: true,
+            stdio: "inherit",
+            env: {
+                ...process.env,
+                RR_MESSAGE: msg.text,
+                RR_FROM: msg.from,
+                RR_TO: msg.to,
+                RR_MSG_ID: String(msg.id),
+                RR_CHANNEL: args.channel,
+                RR_PRIORITY: msg.priority ?? "default",
+            },
+        });
+        child.on("error", (err) => {
+            console.error(`[listen-here] --on-message spawn failed:`, err.message);
+        });
+    }
+}
+/** Issue a GET request and return the IncomingMessage. We use node:https/http
+ *  directly (instead of global `fetch`) so listen-here works on Node 16. */
+function openHttpStream(url, headers, abortSignal) {
+    return new Promise((resolve, reject) => {
+        const reqFn = url.protocol === "https:" ? httpsRequest : httpRequest;
+        const req = reqFn({
+            method: "GET",
+            host: url.hostname,
+            port: url.port ? Number(url.port) : url.protocol === "https:" ? 443 : 80,
+            path: url.pathname + url.search,
+            headers,
+        }, (res) => resolve(res));
+        req.on("error", reject);
+        if (abortSignal.aborted) {
+            req.destroy();
+            reject(new Error("AbortError: signal was already aborted"));
+            return;
+        }
+        const onAbort = () => {
+            req.destroy();
+            reject(new Error("AbortError"));
+        };
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+        req.end();
+    });
+}
+/** Open one SSE connection and consume events until it closes. Returns the last
+ *  seen message id (so the reconnect loop can resume from there) and the reason
+ *  the connection ended ("aborted" for user-initiated, "ended" for network/server). */
+async function runOneConnection(args, sinceCursor, abortSignal) {
+    const url = new URL(`${args.origin.replace(/\/$/, "")}/api/channels/${args.channel}/stream`);
+    if (sinceCursor !== undefined)
+        url.searchParams.set("since", String(sinceCursor));
+    let res;
+    try {
+        res = await openHttpStream(url, {
+            authorization: `Bearer ${args.token}`,
+            "x-session-id": args.session,
+            accept: "text/event-stream",
+        }, abortSignal);
+    }
+    catch (err) {
+        if (abortSignal.aborted)
+            return { lastId: sinceCursor, reason: "aborted" };
+        throw err;
+    }
+    const status = res.statusCode ?? 0;
+    if (status < 200 || status >= 300) {
+        // Drain so the socket is freed.
+        res.resume();
+        return { lastId: sinceCursor, reason: "ended", statusError: status };
+    }
+    let lastId = sinceCursor;
+    // If the operator aborts mid-stream, destroy() the response to unblock the
+    // for-await on it.
+    const onAbort = () => res.destroy();
+    abortSignal.addEventListener("abort", onAbort, { once: true });
+    try {
+        for await (const block of readSseBlocks(res)) {
+            if (abortSignal.aborted)
+                return { lastId, reason: "aborted" };
+            const parsed = parseSseBlock(block);
+            if (!parsed)
+                continue;
+            if (parsed.event === "message") {
+                let msg;
+                try {
+                    msg = JSON.parse(parsed.data);
+                }
+                catch {
+                    continue;
+                }
+                lastId = msg.id;
+                await dispatch(args, msg);
+            }
+            else if (parsed.event === "error") {
+                console.error(`[listen-here] server error:`, parsed.data);
+            }
+            // "hello" event ignored — we don't need the initial channel metadata
+        }
+    }
+    catch (err) {
+        if (abortSignal.aborted)
+            return { lastId, reason: "aborted" };
+        throw err;
+    }
+    finally {
+        abortSignal.removeEventListener("abort", onAbort);
+    }
+    return { lastId, reason: "ended" };
+}
+export async function runListenHere(argv) {
+    const parsed = parseFlags(argv);
+    if ("help" in parsed) {
+        console.log(HELP);
+        return 0;
+    }
+    if ("error" in parsed) {
+        console.error(`error: ${parsed.error}\n`);
+        console.error(HELP);
+        return 2;
+    }
+    const args = parsed;
+    const ac = new AbortController();
+    const shutdown = (sig) => {
+        if (!args.quiet)
+            console.error(`[listen-here] received ${sig}, closing stream`);
+        ac.abort();
+    };
+    process.once("SIGINT", () => shutdown("SIGINT"));
+    process.once("SIGTERM", () => shutdown("SIGTERM"));
+    if (!args.quiet) {
+        console.error(`[listen-here] connecting to ${args.origin}/api/channels/${args.channel}/stream`);
+    }
+    let cursor = args.since;
+    let backoffMs = 1000;
+    while (!ac.signal.aborted) {
+        let result;
+        try {
+            result = await runOneConnection(args, cursor, ac.signal);
+        }
+        catch (err) {
+            if (ac.signal.aborted)
+                return 0;
+            console.error(`[listen-here] connection error:`, err.message);
+            result = { lastId: cursor, reason: "ended" };
+        }
+        if (result.lastId !== undefined)
+            cursor = result.lastId;
+        if (result.reason === "aborted")
+            return 0;
+        if (result.statusError !== undefined) {
+            const status = result.statusError;
+            // 4xx (except 408/429) are permanent — bail rather than spin.
+            if (status >= 400 && status < 500 && status !== 408 && status !== 429) {
+                console.error(`[listen-here] server returned ${status} — auth or session invalid; exiting`);
+                return 1;
+            }
+            console.error(`[listen-here] server returned ${status} — will retry`);
+        }
+        // Connection closed cleanly or with retryable error. Backoff then reconnect.
+        if (ac.signal.aborted)
+            return 0;
+        const wait = backoffMs;
+        backoffMs = Math.min(60_000, Math.floor(backoffMs * 3));
+        if (!args.quiet) {
+            console.error(`[listen-here] reconnecting in ${wait}ms (cursor=${cursor ?? "none"})`);
+        }
+        await new Promise((resolve) => {
+            const t = setTimeout(resolve, wait);
+            ac.signal.addEventListener("abort", () => {
+                clearTimeout(t);
+                resolve();
+            }, { once: true });
+        });
+    }
+    return 0;
+}