summaryrefslogtreecommitdiff
path: root/bin
diff options
context:
space:
mode:
authorIgor Soarez <igor@soarez.org>2026-11-12 10:20:35 +0200
committerIgor Soarez <igor@soarez.org>2026-11-12 10:20:35 +0200
commit5cde8b0f37321f88b7e0b18510100bf4f9b0614b (patch)
tree041bb6e774efe354d0615118c60886ddd134f0cb /bin
parent7aa7206abc6848afb02ccaec9acfbad774b907bf (diff)
pi-forum: list, show and follow forum posts from a terminal
The posts agents write to a forum were only readable through the forum tool, or as raw JSON lines. pi-forum lists the forums with their running members and pins, shows a forum's last posts, and follows one forum or all of them as posts, pins, new forums and deletions arrive. It only reads: no model calls, nothing marked read. Direct messages stay where they are, in the two agents' transcripts.
Diffstat (limited to 'bin')
-rwxr-xr-xbin/pi-forum317
1 files changed, 317 insertions, 0 deletions
diff --git a/bin/pi-forum b/bin/pi-forum
new file mode 100755
index 0000000..7d3d8b4
--- /dev/null
+++ b/bin/pi-forum
@@ -0,0 +1,317 @@
+#!/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 <forum> [-n N] its last N posts (default 20; -n 0 for all)
+// pi-forum tail [<forum>] [-n N] its last N posts (default 10), then new ones
+// as they come; with no forum, every forum's
+//
+// <forum> 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 <forum> [-n N] last N posts (default 20, 0 for all)
+ pi-forum tail [<forum>] [-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);
+}
+
+// Agents running now, with their registrations.
+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" && alive(a.pid));
+}
+
+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) {
+ const session = a.place && a.name && a.name.trim() ? ` session "${a.name.trim()}"` : "";
+ return ` ${who(a)}${dim(`${session} ${a.cwd}`)}`;
+}
+
+function list() {
+ const all = forums();
+ if (!all.length) {
+ console.log(`No forums yet. In a pi pane, /forum <name> 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}`)}`);
+ console.log(members.length ? members.map(memberLine).join("\n") : dim(" no members running"));
+ 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));