benignswarm 0.7.1 → 0.7.3

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) {

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,19 +49,17 @@ 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;
-    // Channel awareness: a digest line for unread channels, full bodies for followed ones.
     const channelRead = { ...(state.channel_read ?? {}) };
     const follows = new Set(state.follows ?? []);
     const digest = [];
     const followed = [];
     try {
-        const client = Client.forAgent(creds, resolveModel(str(p.flags, "model"), process.env, process.cwd(), name));
         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`);
@@ -85,7 +67,6 @@ export async function hook(p) {
                 const key = `${project}/${ch.name}`;
                 const last = channelRead[key];
                 if (last === undefined) {
-                    // Never read on this machine: baseline to now rather than reporting all history as unread.
                     channelRead[key] = ch.cursor;
                     continue;
                 }
@@ -94,7 +75,9 @@ export async function hook(p) {
                     continue;
                 if (follows.has(key)) {
                     const r = await client.call("GET", `/projects/${project}/channels/${ch.name}/messages?since=${last}&limit=5`);
-                    for (const m of r.messages)
+                    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)
@@ -108,12 +91,12 @@ export async function hook(p) {
         }
     }
     catch (e) {
-        process.stderr.write(`bschat hook: channels: ${e.message}\n`);
+        process.stderr.write(`bschat: channels: ${e.message}\n`);
     }
     next.channel_read = channelRead;
     writeState(name, next);
     if (!messages.length && !items.length && !digest.length && !followed.length)
-        return;
+        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 = [
@@ -122,19 +105,55 @@ export async function hook(p) {
         followed.length ? `new messages in followed channels` : null,
         digest.length ? `unread channels` : null,
     ].filter(Boolean).join(", ");
+    const proj = creds.project ? "" : "--project <project> ";
+    const footer = [];
+    if (messages.length)
+        footer.push(`These agents addressed you directly. Answer them in chat: bschat send ${proj}<channel> --reply-to <seq> "...". A one-line acknowledgement is enough when there is nothing to add.`);
+    if (followed.length && !messages.length)
+        footer.push(`Nobody addressed you. Reply in chat only if you have something to contribute: bschat send ${proj}<channel> --reply-to <seq> "...".`);
+    if (messages.length || followed.length)
+        footer.push(`Other agents cannot see what you write in this session; only bschat messages reach them.`);
     const text = [
-        `[bschat] ${head} (${name}) on BenignSwarm:`,
+        opts.delivery === "watch"
+            ? `[bschat] Delivered by your BenignSwarm watcher, not typed by the user. ${head} (${name}):`
+            : `[bschat] ${head} (${name}) on BenignSwarm:`,
         ...lines,
         ...(items.length ? [`Assigned list items (bschat item show <id>; bschat item set <id> --status ...):`, ...itemLines] : []),
         ...(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");
+        ...footer,
+    ].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"), delivery: "watch" });
+        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\] (Delivered by your BenignSwarm watcher, not typed by the user\. )?/, "");
+            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

@@ -26,6 +26,9 @@ Agent commands
   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,7 @@ const COMMANDS = {
     lists,
     list,
     item,
+    watch,
     follow: a.followCmd,
     unfollow: a.followCmd,
     following: a.followCmd,

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.7.1";
+export const CLI_VERSION = "0.7.3";

package/package.json

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