diff options
| author | Igor Soarez <igor@soarez.org> | 2026-11-12 10:20:35 +0200 |
|---|---|---|
| committer | Igor Soarez <igor@soarez.org> | 2026-11-12 10:20:35 +0200 |
| commit | 5cde8b0f37321f88b7e0b18510100bf4f9b0614b (patch) | |
| tree | 041bb6e774efe354d0615118c60886ddd134f0cb /bin/pi-forum | |
| parent | 7aa7206abc6848afb02ccaec9acfbad774b907bf (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/pi-forum')
| -rwxr-xr-x | bin/pi-forum | 317 |
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)); |
