benignswarm 0.7.0 → 0.7.2

package/dist/args.js

@@ -1,7 +1,7 @@
 import { parseArgs } from "node:util";
 import { CliError } from "./errors.js";
-const STRING_FLAGS = ["as", "admin", "key", "url", "label", "model", "since", "limit", "after", "topic", "goal", "task", "state", "blocked-on", "tags", "custom", "vendor", "role", "description", "permissions", "cardinality", "machine", "dir", "confirm", "type", "name", "out", "token", "prefix", "uses", "expires-hours", "skill-dir", "harness", "reply-to", "event", "project", "projects", "post", "title", "body", "body-file", "handoff-to", "evidence", "agent", "parent", "parent-item", "channel", "statuses", "assign", "if-status", "status"];
-const BOOL_FLAGS = ["json", "follow", "account", "help", "version", "broadcast", "create-channels", "read-account-status", "replace-key", "mentions-me", "no-skill", "replace", "unread", "force", "no-hooks", "yes", "open", "bind-here", "peek"];
+const STRING_FLAGS = ["as", "admin", "key", "url", "label", "model", "since", "limit", "after", "topic", "goal", "task", "state", "blocked-on", "tags", "custom", "vendor", "role", "description", "permissions", "cardinality", "machine", "dir", "confirm", "type", "name", "out", "token", "prefix", "uses", "expires-hours", "skill-dir", "harness", "reply-to", "event", "project", "projects", "post", "title", "body", "body-file", "handoff-to", "evidence", "agent", "parent", "parent-item", "channel", "statuses", "assign", "if-status", "status", "exec", "interval"];
+const BOOL_FLAGS = ["json", "follow", "account", "help", "version", "broadcast", "create-channels", "read-account-status", "replace-key", "mentions-me", "no-skill", "replace", "unread", "force", "no-hooks", "yes", "open", "bind-here", "peek", "once", "launchd"];
 export function parse(argv) {
     const options = {};
     for (const f of STRING_FLAGS)

package/dist/commands/agent.js

@@ -131,7 +131,16 @@ export async function send(p, out) {
     const replyTo = str(p.flags, "reply-to");
     if (replyTo !== undefined && !/^\d+$/.test(replyTo))
         throw new CliError("usage", "--reply-to takes the seq number of the message you are answering");
-    const r = await client.call("POST", `/projects/${projectOf(p, creds)}/channels/${channel}/messages`, { body, reply_to: replyTo === undefined ? null : Number(replyTo) });
+    const project = projectOf(p, creds);
+    const r = await client.call("POST", `/projects/${project}/channels/${channel}/messages`, { body, reply_to: replyTo === undefined ? null : Number(replyTo) });
+    {
+        // Our own post must not count as unread for us; advance the cursor if we were caught up.
+        const st = readState(creds.agent);
+        const key = `${project}/${channel}`;
+        const last = st.channel_read?.[key];
+        if (last !== undefined && last >= r.message.seq - 1)
+            writeState(creds.agent, { ...st, channel_read: { ...(st.channel_read ?? {}), [key]: r.message.seq } });
+    }
     out.print(`sent #${channel} seq ${r.message.seq}${r.message.reply_to_seq ? ` (reply to #${r.message.reply_to_seq})` : ""}${r.message.mentions.length ? ` (mentions ${r.message.mentions.length})` : ""}`, r);
 }
 export async function read(p, out) {
@@ -151,6 +160,8 @@ export async function read(p, out) {
     qs.set("limit", str(p.flags, "limit") ?? "100");
     const r = await client.call("GET", `/projects/${project}/channels/${channel}/messages?${qs}`);
     const text = r.messages.length ? r.messages.map(fmtMessage).join("\n") : "(no messages)";
+    const st = readState(creds.agent);
+    writeState(creds.agent, { ...st, channel_read: { ...(st.channel_read ?? {}), [`${project}/${channel}`]: r.cursor } });
     out.print(`${text}\ncursor: ${r.cursor}`, r);
 }
 function follow(client, path, out) {
@@ -270,3 +281,26 @@ export async function projects(p, out) {
     const list = r.scope === "account" ? r.projects : [r.project];
     out.print(list.map((x) => x.name).join("\n") || "(none)", { projects: list });
 }
+/** Follow a channel: the hook then injects its new messages, not just a digest line. */
+export async function followCmd(p, out) {
+    const channel = p.positionals[1];
+    const { creds, client } = agentClient(p);
+    const unfollow = p.positionals[0] === "unfollow";
+    const st = readState(creds.agent);
+    const follows = new Set(st.follows ?? []);
+    if (p.positionals[0] === "following" || !channel) {
+        out.print(follows.size ? [...follows].join("\n") : "(following no channels; the hook shows a digest line only)", { follows: [...follows] });
+        return;
+    }
+    const project = projectOf(p, creds);
+    const key = `${project}/${channel}`;
+    if (unfollow) {
+        follows.delete(key);
+    }
+    else {
+        await client.call("GET", `/projects/${project}/channels/${channel}/messages?limit=1`); // validates access
+        follows.add(key);
+    }
+    writeState(creds.agent, { ...st, follows: [...follows] });
+    out.print(`${unfollow ? "unfollowed" : "following"} #${channel} in ${project}`, { follows: [...follows] });
+}

package/dist/commands/hook.js

@@ -21,42 +21,26 @@ function readStdinJson() {
 }
 const THROTTLE_MS = 20_000;
 /**
- * Harness hook entry point. Prints new mentions and replies addressed to this agent, in the
- * format the harness expects for injecting context, and nothing when there is nothing new.
- * Always exits 0: a hook that fails must never break the agent's session. Problems go to stderr.
+ * Collects everything new for an identity and advances its cursors. Returns null when nothing
+ * is new. Shared by the harness hook and `bschat watch`. Never throws for server/network
+ * problems: those go to stderr and yield null, so callers keep running.
  */
-export async function hook(p) {
-    const harness = p.positionals[1] ?? "plain";
-    const event = str(p.flags, "event") ?? (harness === "claude-code" ? "UserPromptSubmit" : "");
-    const name = str(p.flags, "as") ?? process.env.BSCHAT_AGENT ?? identityFromRepo();
-    if (!name)
-        return; // not configured here; silent by design
+export async function gatherUpdates(name, opts) {
     let creds;
     try {
         creds = loadAgent(name);
     }
     catch (e) {
-        process.stderr.write(`bschat hook: ${e.message}\n`);
-        return;
+        process.stderr.write(`bschat: ${e.message}\n`);
+        return null;
     }
     const state = readState(name);
-    // Model observation: hook input (SessionStart `model`, PostModelSwitch `to_model`) or the transcript tail.
-    const input = readStdinJson();
-    if (input) {
-        const observed = (typeof input.to_model === "string" && input.to_model) || (typeof input.model === "string" && input.model) || (typeof input.transcript_path === "string" ? modelFromClaudeTranscript(input.transcript_path) : null);
-        if (observed && observed !== state.model)
-            writeState(name, { ...state, model: observed, model_observed_at: Date.now() });
-        if (observed)
-            state.model = observed;
-    }
-    if (event === "PostModelSwitch")
-        return;
-    if (Date.now() - state.last_check < THROTTLE_MS && !p.flags.force)
-        return;
+    if (Date.now() - state.last_check < THROTTLE_MS && !opts.force)
+        return null;
     let messages;
     let items = [];
+    const client = Client.forAgent(creds, resolveModel(opts.model, process.env, process.cwd(), name));
     try {
-        const client = Client.forAgent(creds, resolveModel(str(p.flags, "model"), process.env, process.cwd(), name));
         const qs = new URLSearchParams({ limit: "20" });
         if (state.inbox_after)
             qs.set("after", state.inbox_after);
@@ -65,28 +49,101 @@ export async function hook(p) {
         items = r.items ?? [];
     }
     catch (e) {
-        process.stderr.write(`bschat hook: ${e.message}\n`);
-        return;
+        process.stderr.write(`bschat: ${e.message}\n`);
+        return null;
     }
     const next = { ...state, last_check: Date.now() };
     if (messages.length)
         next.inbox_after = messages[messages.length - 1].created_at;
+    const channelRead = { ...(state.channel_read ?? {}) };
+    const follows = new Set(state.follows ?? []);
+    const digest = [];
+    const followed = [];
+    try {
+        const projects = creds.project ? [creds.project] : ((await client.call("GET", "/me")).projects ?? []).map((x) => x.name);
+        for (const project of projects) {
+            const { cursors } = await client.call("GET", `/projects/${project}/channels/cursors`);
+            for (const ch of cursors) {
+                const key = `${project}/${ch.name}`;
+                const last = channelRead[key];
+                if (last === undefined) {
+                    channelRead[key] = ch.cursor;
+                    continue;
+                }
+                const unread = ch.cursor - last;
+                if (unread <= 0)
+                    continue;
+                if (follows.has(key)) {
+                    const r = await client.call("GET", `/projects/${project}/channels/${ch.name}/messages?since=${last}&limit=5`);
+                    const seen = new Set(messages.map((m) => m.id));
+                    const others = r.messages.filter((m) => m.agent_name !== name && !seen.has(m.id));
+                    for (const m of others)
+                        followed.push(`${creds.project ? "" : `[${project}] `}${fmtMessage(m)}`);
+                    const shown = r.messages.length ? r.messages[r.messages.length - 1].seq : last;
+                    if (ch.cursor > shown)
+                        followed.push(`  (+${ch.cursor - shown} more in #${ch.name}: bschat read ${ch.name} --since ${shown})`);
+                    channelRead[key] = shown;
+                }
+                else {
+                    digest.push(`#${ch.name}${creds.project ? "" : ` [${project}]`}: ${unread} unread (bschat read ${ch.name} --since ${last})`);
+                }
+            }
+        }
+    }
+    catch (e) {
+        process.stderr.write(`bschat: channels: ${e.message}\n`);
+    }
+    next.channel_read = channelRead;
     writeState(name, next);
-    if (!messages.length && !items.length)
-        return;
+    if (!messages.length && !items.length && !digest.length && !followed.length)
+        return null;
     const lines = messages.map((m) => `${creds.project ? "" : `[${m.project}] `}${fmtMessage(m)}${m.reply_to_seq ? `  (reply to #${m.reply_to_seq})` : ""}`);
     const itemLines = items.map((i) => `  list "${i.list}"${i.project && !creds.project ? ` [${i.project}]` : ""}: [${i.status}] ${i.title}  (item ${i.id}, by ${i.updated_by})`);
+    const head = [
+        messages.length ? `${messages.length} message${messages.length === 1 ? "" : "s"} for you` : null,
+        items.length ? `${items.length} list item${items.length === 1 ? "" : "s"} assigned to you` : null,
+        followed.length ? `new messages in followed channels` : null,
+        digest.length ? `unread channels` : null,
+    ].filter(Boolean).join(", ");
     const text = [
-        `[bschat] ${messages.length} new message${messages.length === 1 ? "" : "s"}${items.length ? ` and ${items.length} list item${items.length === 1 ? "" : "s"} assigned to you` : ""} (${name}) on BenignSwarm:`,
+        `[bschat] ${head} (${name}) on BenignSwarm:`,
         ...lines,
         ...(items.length ? [`Assigned list items (bschat item show <id>; bschat item set <id> --status ...):`, ...itemLines] : []),
-        `Reply with: bschat send ${creds.project ? "" : "--project <project> "}<channel> --reply-to <seq> "..."   (or just continue if no answer is needed)`,
-    ].join("\n");
+        ...(followed.length ? [`Followed channels:`, ...followed] : []),
+        ...(digest.length ? [`Unread elsewhere: ${digest.join("; ")}`] : []),
+        messages.length || followed.length ? `Reply with: bschat send ${creds.project ? "" : "--project <project> "}<channel> --reply-to <seq> "..."   (or just continue if no answer is needed)` : null,
+    ].filter((l) => l !== null).join("\n");
+    return { text, counts: { messages: messages.length, items: items.length, followed: followed.length, digest: digest.length } };
+}
+/**
+ * Harness hook entry point. Prints new items in the format the harness expects for injecting
+ * context, and nothing when there is nothing new. Always exits 0: a hook that fails must never
+ * break the agent's session. Problems go to stderr.
+ */
+export async function hook(p) {
+    const harness = p.positionals[1] ?? "plain";
+    const event = str(p.flags, "event") ?? (harness === "claude-code" ? "UserPromptSubmit" : "");
+    const name = str(p.flags, "as") ?? process.env.BSCHAT_AGENT ?? identityFromRepo();
+    if (!name)
+        return; // not configured here; silent by design
+    // Model observation: hook input (SessionStart `model`, PostModelSwitch `to_model`) or the transcript tail.
+    const input = readStdinJson();
+    if (input) {
+        const state = readState(name);
+        const observed = (typeof input.to_model === "string" && input.to_model) || (typeof input.model === "string" && input.model) || (typeof input.transcript_path === "string" ? modelFromClaudeTranscript(input.transcript_path) : null);
+        if (observed && observed !== state.model)
+            writeState(name, { ...state, model: observed, model_observed_at: Date.now() });
+    }
+    if (event === "PostModelSwitch")
+        return;
+    const u = await gatherUpdates(name, { force: !!p.flags.force, model: str(p.flags, "model") });
+    if (!u)
+        return;
     if (harness === "claude-code") {
-        process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } }) + "\n");
+        process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: u.text } }) + "\n");
     }
     else {
-        process.stdout.write(text + "\n");
+        process.stdout.write(u.text + "\n");
     }
 }
 function identityFromRepo() {

package/dist/commands/watch.js

@@ -0,0 +1,101 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { bool, str } from "../args.js";
+import { resolveAgentName } from "../config.js";
+import { CliError } from "../errors.js";
+import { gatherUpdates } from "./hook.js";
+/**
+ * Event bridge for harnesses that can be woken from outside (Codex: `codex queue --thread <id>`).
+ * Polls on an interval using the same cursors and own-message exclusion as the hook, and runs
+ * --exec when something new arrives. The command receives the text on stdin and in BSCHAT_TEXT,
+ * and {count}/{summary}/{text} placeholders are substituted in the command string.
+ */
+export async function watch(p, out) {
+    const name = resolveAgentName(str(p.flags, "as"));
+    const exec = str(p.flags, "exec");
+    const interval = Number(str(p.flags, "interval") ?? "30");
+    if (!Number.isInteger(interval) || interval < 5)
+        throw new CliError("usage", "--interval must be an integer number of seconds, at least 5");
+    const once = bool(p.flags, "once");
+    if (bool(p.flags, "launchd")) {
+        if (!exec)
+            throw new CliError("usage", "--launchd needs --exec so the agent knows what to run");
+        return installLaunchd(name, exec, interval, out);
+    }
+    if (!exec && !once)
+        throw new CliError("usage", 'watch --exec "<command>" [--interval 30] | watch --once (print and exit) | watch --exec ... --launchd');
+    const log = (m) => process.stderr.write(`${new Date().toISOString()} bschat watch[${name}]: ${m}\n`);
+    log(`watching${exec ? `, will run: ${exec}` : ""} every ${interval}s`);
+    for (;;) {
+        const u = await gatherUpdates(name, { force: true, model: str(p.flags, "model") });
+        if (u) {
+            const total = u.counts.messages + u.counts.items + u.counts.followed + u.counts.digest;
+            const summary = u.text.split("\n")[0].replace(/^\[bschat\] /, "");
+            if (exec) {
+                const cmd = exec.replaceAll("{count}", String(total)).replaceAll("{summary}", shellQuote(summary)).replaceAll("{text}", shellQuote(u.text));
+                log(`new activity (${summary}); running: ${cmd}`);
+                const code = await run(cmd, u.text, { BSCHAT_TEXT: u.text, BSCHAT_SUMMARY: summary, BSCHAT_COUNT: String(total) });
+                if (code !== 0)
+                    log(`command exited ${code}`);
+            }
+            else {
+                process.stdout.write(u.text + "\n");
+            }
+        }
+        else if (once) {
+            log("nothing new");
+        }
+        if (once)
+            return;
+        await new Promise((r) => setTimeout(r, interval * 1000));
+    }
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function run(cmd, stdin, env) {
+    return new Promise((resolve) => {
+        const child = spawn("/bin/sh", ["-c", cmd], { stdio: ["pipe", "inherit", "inherit"], env: { ...process.env, ...env } });
+        child.stdin.end(stdin);
+        child.on("close", (code) => resolve(code ?? 1));
+        child.on("error", () => resolve(1));
+    });
+}
+/** Writes a launchd agent that keeps `bschat watch` running for this identity on macOS. */
+function installLaunchd(name, exec, interval, out) {
+    if (process.platform !== "darwin")
+        throw new CliError("unsupported", "--launchd is macOS only; on Linux run `bschat watch` under a systemd user service");
+    const label = `org.benignswarm.watch.${name}`;
+    const dir = join(homedir(), "Library", "LaunchAgents");
+    const logDir = join(homedir(), ".bschat", "logs");
+    mkdirSync(dir, { recursive: true });
+    mkdirSync(logDir, { recursive: true });
+    const node = process.execPath;
+    const cli = process.argv[1];
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${label}</string>
+  <key>ProgramArguments</key><array>
+    <string>${node}</string><string>${cli}</string><string>watch</string>
+    <string>--as</string><string>${name}</string>
+    <string>--exec</string><string>${escapeXml(exec)}</string>
+    <string>--interval</string><string>${interval}</string>
+  </array>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${escapeXml(process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin")}</string><key>HOME</key><string>${homedir()}</string></dict>
+  <key>WorkingDirectory</key><string>${escapeXml(process.cwd())}</string>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${join(logDir, `watch.${name}.out.log`)}</string>
+  <key>StandardErrorPath</key><string>${join(logDir, `watch.${name}.err.log`)}</string>
+</dict></plist>
+`;
+    const path = join(dir, `${label}.plist`);
+    writeFileSync(path, plist);
+    out.print(`Wrote ${path}\nStart it:   launchctl bootstrap gui/$(id -u) ${path}\nStop it:    launchctl bootout gui/$(id -u)/${label}\nLogs:       ${logDir}/watch.${name}.*.log\nThe watcher runs from ${process.cwd()} so the repo identity file applies.`, { plist: path, label });
+}
+function escapeXml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/dist/help.js

@@ -23,7 +23,12 @@ Agent commands
   bschat send <channel> <message...> [--reply-to <seq>]   @name, @role:name, @role:* are resolved and validated
   bschat read <channel> [--since <seq>] [--limit n] [--follow]
   bschat inbox [--unread] [--after <iso-time>] [--limit n]   mentions of you and replies to your messages
+  bschat follow <channel> | unfollow <channel> | following   followed channels' new messages are injected by the hook;
+                                           other channels appear as a one-line unread digest
   bschat hook claude-code [--event E]       harness hook: prints new inbox items as hook JSON (installed by join)
+  bschat watch --exec "<cmd>" [--interval 30]   event bridge: run <cmd> when something new arrives ({count} {summary} {text};
+                                           text also on stdin and $BSCHAT_TEXT). --once prints and exits. --launchd installs a macOS agent.
+                                           Codex: bschat watch --exec "codex queue --thread <id> --message {summary}" --launchd
   bschat activity [--account] [--after <iso>] [--limit n]   merged timeline: messages, status, evidence
   bschat projects                          projects you can access
   bschat channels

package/dist/index.js

@@ -7,6 +7,7 @@ import { join, setup } from "./commands/join.js";
 import { hook } from "./commands/hook.js";
 import { handoffs, retire } from "./commands/retire.js";
 import { item, list, lists } from "./commands/lists.js";
+import { watch } from "./commands/watch.js";
 import { CliError } from "./errors.js";
 import { HELP } from "./help.js";
 import { CLI_VERSION } from "./version.js";
@@ -37,6 +38,10 @@ const COMMANDS = {
     lists,
     list,
     item,
+    watch,
+    follow: a.followCmd,
+    unfollow: a.followCmd,
+    following: a.followCmd,
     admin,
 };
 async function main(argv) {

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.7.0";
+export const CLI_VERSION = "0.7.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "benignswarm",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "bschat: chat, status board and evidence store for coding agents (benignswarm.org)",
   "license": "UNLICENSED",
   "repository": {