#!/usr/bin/env node // Read the forums pi agents talk in, from outside pi: list them, show their // posts, or follow new ones as they arrive. // // pi-forum every forum: members, pin, post count // pi-forum show [-n N] its last N posts (default 20; -n 0 for all) // pi-forum tail [] [-n N] its last N posts (default 10), then new ones // as they come; with no forum, every forum's // // is a forum's name or id. This only reads: it costs no model calls, // and marks nothing read for any agent. Direct messages between agents are not // stored anywhere it could see; they are only in the two agents' transcripts. // // The forums are the pi extension config/pi/extensions/forum.ts's, under // ~/.pi/forum, or $PI_FORUM_DIR. "use strict"; const fs = require("node:fs"); const path = require("node:path"); const os = require("node:os"); const ROOT = process.env.PI_FORUM_DIR || path.join(os.homedir(), ".pi", "forum"); const AGENTS = path.join(ROOT, "agents"); const FORUMS = path.join(ROOT, "forums"); const POLL_MS = 500; const USAGE = `usage: pi-forum list forums pi-forum show [-n N] last N posts (default 20, 0 for all) pi-forum tail [] [-n N] last N posts (default 10), then follow; no forum: every forum`; const color = process.stdout.isTTY && !process.env.NO_COLOR; const sgr = (code) => (s) => (color ? `\x1b[${code}m${s}\x1b[0m` : s); const dim = sgr("2"); const bold = sgr("1"); const cyan = sgr("36"); const yellow = sgr("33"); process.stdout.on("error", (e) => { if (e.code === "EPIPE") process.exit(0); throw e; }); function die(msg) { process.stderr.write(`pi-forum: ${msg}\n`); process.exit(1); } function readJson(p) { try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return undefined; } } function alive(pid) { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } } // 2026-10-22 14:05:00, as the extension writes times. const when = (ms) => new Date(ms).toLocaleString("sv-SE"); const who = (s) => `${s.label} [${s.id}]`; function forums() { let ids; try { ids = fs.readdirSync(FORUMS); } catch { return []; } return ids .map((id) => readJson(path.join(FORUMS, id, "meta.json"))) .filter((m) => m && typeof m.id === "string" && typeof m.name === "string") .sort((a, b) => a.createdAt - b.createdAt); } // Registered agents, each marked stopped when no pi is running for it: one a // signal or crash stopped while it was in a forum, which the next pi to open // its session takes back. function agents() { let files; try { files = fs.readdirSync(AGENTS).filter((f) => f.endsWith(".json")); } catch { return []; } return files .map((f) => readJson(path.join(AGENTS, f))) .filter((a) => a && typeof a.id === "string" && typeof a.pid === "number") .map((a) => ({ ...a, stopped: a.stoppedAt !== undefined || !alive(a.pid) || !fs.existsSync(path.join(AGENTS, `${a.id}.sock`)), })) .filter((a) => !a.stopped || (a.forums || []).length); } function find(arg) { const all = forums(); const f = all.find((m) => m.id === arg) || all.find((m) => m.name === arg) || all.find((m) => m.name.toLowerCase() === arg.toLowerCase()); if (!f) die(`no forum "${arg}"${all.length ? `; there are: ${all.map((m) => m.name).join(", ")}` : ""}`); return f; } const postsPath = (id) => path.join(FORUMS, id, "posts.jsonl"); const isPost = (p) => p && typeof p.uid === "string" && typeof p.text === "string" && p.from; // Parse complete lines as the extension does, skipping what it skips, so post // numbers match the ones agents see. function parse(lines) { const posts = []; for (const line of lines) { if (!line.trim()) continue; try { const p = JSON.parse(line); if (isPost(p)) posts.push(p); } catch {} } return posts; } function mentionNames(post, byId) { return (post.mentions || []).map((m) => (m === "all" ? "@all" : `@${byId.has(m) ? who(byId.get(m)) : m}`)); } function format(post, no, forum, opts) { const byId = new Map(agents().map((a) => [a.id, a])); const head = [ opts.tagForum ? cyan(forum.name) : "", dim(`#${no}`), dim(when(post.at)), bold(who(post.from)), ].filter(Boolean); const mentions = mentionNames(post, byId); if (mentions.length) head.push(yellow(`→ ${mentions.join(" ")}`)); return `${head.join(" ")}\n${post.text.replace(/\s+$/, "")}\n`; } function memberLine(a) { if (!a.stopped) return ` ${who(a)}${dim(` ${a.cwd}`)}`; return dim(` ${who(a)} stopped${a.stoppedAt ? ` since ${when(a.stoppedAt)}` : ""}`); } function list() { const all = forums(); if (!all.length) { console.log(`No forums yet. In a pi pane, /forum starts one.`); return; } const live = agents(); for (const f of all) { const posts = parse(readLines(postsPath(f.id))); const members = live.filter((a) => (a.forums || []).includes(f.id)); const last = posts.length ? `, last ${when(posts[posts.length - 1].at)}` : ""; console.log(`${bold(f.name)} ${dim(`[${f.id}] ${posts.length} post(s)${last}`)}`); members.sort((a, b) => a.stopped - b.stopped); console.log(members.length ? members.map(memberLine).join("\n") : dim(" no members")); if (f.pin) console.log(` ${yellow("pin")}: ${f.pin.text} ${dim(`(${who(f.pin.by)}, ${when(f.pin.at)})`)}`); console.log(); } } function readLines(p) { try { return fs.readFileSync(p, "utf8").split("\n"); } catch { return []; } } function show(arg, n) { const f = find(arg); const posts = parse(readLines(postsPath(f.id))); if (!posts.length) { console.log(dim(`"${f.name}" has no posts yet.`)); return; } const from = n > 0 ? Math.max(0, posts.length - n) : 0; if (from > 0) console.log(dim(`… ${from} earlier post(s); -n 0 shows all\n`)); for (let i = from; i < posts.length; i++) console.log(format(posts[i], i + 1, f, {})); if (f.pin) console.log(`${yellow("pin")}: ${f.pin.text} ${dim(`(${who(f.pin.by)}, ${when(f.pin.at)})`)}`); } // Follow one forum, or all of them. Polls rather than watching: a forum can // appear, be deleted, or be written by any process, and fs.watch reports // those unevenly across platforms. function tail(arg, n) { const one = arg ? find(arg) : undefined; const opts = { tagForum: !one }; const state = new Map(); // forum id -> { meta, offset, rest, count, pinAt } // Start following a forum; returns the posts it has so far. function track(meta) { let buf = Buffer.alloc(0); try { buf = fs.readFileSync(postsPath(meta.id)); } catch {} // A last line without its newline is still being written: read it next time. const end = buf.lastIndexOf(0x0a) + 1; const posts = parse(buf.subarray(0, end).toString("utf8").split("\n")); state.set(meta.id, { meta, offset: end, rest: "", count: posts.length, pinAt: meta.pin ? meta.pin.at : 0 }); return posts.map((p, i) => ({ post: p, no: i + 1, meta })); } // The backlog: the last n posts of the forum, or across every forum. const backlog = []; for (const meta of one ? [one] : forums()) backlog.push(...track(meta)); backlog.sort((a, b) => a.post.at - b.post.at); const shown = n > 0 ? backlog.slice(-n) : n === 0 ? backlog : []; for (const b of shown) console.log(format(b.post, b.no, b.meta, opts)); console.log( dim(`— following ${one ? `"${one.name}"` : "every forum"}; Ctrl-C to stop —\n`), ); function poll() { const current = one ? forums().filter((m) => m.id === one.id) : forums(); const ids = new Set(current.map((m) => m.id)); for (const [id, s] of state) { if (ids.has(id)) continue; console.log(dim(`forum "${s.meta.name}" was deleted\n`)); state.delete(id); if (one) process.exit(0); } for (const meta of current) { let s = state.get(meta.id); if (!s) { console.log(dim(`new forum "${meta.name}"\n`)); // Posts already there when it was noticed: show them, it is new. for (const b of track(meta)) console.log(format(b.post, b.no, b.meta, opts)); continue; } s.meta = meta; const pinAt = meta.pin ? meta.pin.at : 0; if (pinAt !== s.pinAt) { s.pinAt = pinAt; const where = opts.tagForum ? `${cyan(meta.name)} ` : ""; console.log( meta.pin ? `${where}${yellow("pin")} ${dim(when(meta.pin.at))} ${bold(who(meta.pin.by))}\n${meta.pin.text}\n` : `${where}${dim("pin cleared")}\n`, ); } let size; try { size = fs.statSync(postsPath(meta.id)).size; } catch { continue; } if (size < s.offset) { // Rewritten from scratch: start over, without repeating the backlog. s.offset = 0; s.rest = ""; s.count = 0; } if (size === s.offset) continue; const buf = Buffer.alloc(size - s.offset); const fd = fs.openSync(postsPath(meta.id), "r"); try { fs.readSync(fd, buf, 0, buf.length, s.offset); } finally { fs.closeSync(fd); } s.offset = size; // Bytes are kept until a newline, so a character split across reads is whole. const chunk = s.rest + buf.toString("latin1"); const cut = chunk.lastIndexOf("\n"); s.rest = chunk.slice(cut + 1); const lines = Buffer.from(chunk.slice(0, cut + 1), "latin1").toString("utf8").split("\n"); for (const p of parse(lines)) { s.count += 1; console.log(format(p, s.count, meta, opts)); } } } setInterval(poll, POLL_MS); } function main(argv) { const args = []; let n; for (let i = 0; i < argv.length; i++) { const a = argv[i]; if (a === "-h" || a === "--help") { console.log(USAGE); return; } if (a === "-n") { const v = argv[++i]; if (v === undefined || !/^\d+$/.test(v)) die("-n wants a number"); n = Number(v); } else if (/^-n\d+$/.test(a)) { n = Number(a.slice(2)); } else if (a.startsWith("-")) { die(`unknown option ${a}\n${USAGE}`); } else { args.push(a); } } const [cmd, forum, extra] = args; if (!cmd || cmd === "list") { if (forum) die(USAGE); return list(); } if (cmd === "show") { if (!forum || extra) die(USAGE); return show(forum, n ?? 20); } if (cmd === "tail") { if (extra) die(USAGE); return tail(forum, n ?? 10); } die(`unknown command "${cmd}"\n${USAGE}`); } main(process.argv.slice(2));