benignswarm 0.7.4 → 0.7.5

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", "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"];
+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", "requeue-after"];
+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", "full"];
 export function parse(argv) {
     const options = {};
     for (const f of STRING_FLAGS)

package/dist/commands/hook.js

@@ -59,6 +59,7 @@ export async function gatherUpdates(name, opts) {
     const follows = new Set(state.follows ?? []);
     const digest = [];
     const followed = [];
+    const readCommands = [];
     try {
         const projects = creds.project ? [creds.project] : ((await client.call("GET", "/me")).projects ?? []).map((x) => x.name);
         for (const project of projects) {
@@ -73,6 +74,7 @@ export async function gatherUpdates(name, opts) {
                 const unread = ch.cursor - last;
                 if (unread <= 0)
                     continue;
+                readCommands.push(`bschat read ${creds.project ? "" : `--project ${project} `}${ch.name} --since ${last}`);
                 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));
@@ -94,7 +96,17 @@ export async function gatherUpdates(name, opts) {
         process.stderr.write(`bschat: channels: ${e.message}\n`);
     }
     next.channel_read = channelRead;
-    writeState(name, next);
+    if (opts.dryRun) {
+        // Persist only the baselines of channels never seen before; everything else stays unread.
+        const merged = { ...(state.channel_read ?? {}) };
+        for (const [k, v] of Object.entries(channelRead))
+            if (merged[k] === undefined)
+                merged[k] = v;
+        writeState(name, { ...state, channel_read: merged });
+    }
+    else {
+        writeState(name, next);
+    }
     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})` : ""}`);
@@ -123,7 +135,9 @@ export async function gatherUpdates(name, opts) {
         ...(digest.length ? [`Unread elsewhere: ${digest.join("; ")}`] : []),
         ...footer,
     ].join("\n");
-    return { text, counts: { messages: messages.length, items: items.length, followed: followed.length, digest: digest.length } };
+    const operator = messages.filter((m) => m.role_name === "human").map((m) => m.created_at).sort().pop() ?? null;
+    const cmds = [...(messages.length || items.length ? ["bschat inbox --unread"] : []), ...readCommands];
+    return { text, counts: { messages: messages.length, items: items.length, followed: followed.length, digest: digest.length }, latestOperatorAt: operator, readCommands: cmds };
 }
 /**
  * Harness hook entry point. Prints new items in the format the harness expects for injecting

package/dist/commands/watch.js

@@ -6,11 +6,16 @@ import { bool, str } from "../args.js";
 import { resolveAgentName } from "../config.js";
 import { CliError } from "../errors.js";
 import { gatherUpdates } from "./hook.js";
+import { readState, writeState } from "../state.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.
+ *
+ * Default mode queues ONE short wake-up and nothing else until the agent has read (its own
+ * `bschat inbox --unread` / `bschat read` advance the shared cursors). Content is never put in
+ * the queue, so the agent always reads it fresh and superseded messages collapse naturally.
+ * A direct message from a human operator re-wakes immediately even while a wake-up is pending.
+ * `--full` restores the old behaviour of queueing the text itself (for harnesses that cannot run
+ * bschat themselves when woken).
  */
 export async function watch(p, out) {
     const name = resolveAgentName(str(p.flags, "as"));
@@ -19,6 +24,8 @@ export async function watch(p, out) {
     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");
+    const full = bool(p.flags, "full");
+    const requeueAfter = Number(str(p.flags, "requeue-after") ?? "1800");
     if (bool(p.flags, "launchd")) {
         if (!exec)
             throw new CliError("usage", "--launchd needs --exec so the agent knows what to run");
@@ -27,8 +34,15 @@ export async function watch(p, 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`);
+    log(`watching${exec ? `, will run: ${exec}` : ""} every ${interval}s (${full ? "full text" : "single wake-up"} mode)`);
     for (;;) {
+        if (!full) {
+            await wakeOnce(name, exec, requeueAfter, log, str(p.flags, "model"), once);
+            if (once)
+                return;
+            await new Promise((r) => setTimeout(r, interval * 1000));
+            continue;
+        }
         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;
@@ -52,6 +66,54 @@ export async function watch(p, out) {
         await new Promise((r) => setTimeout(r, interval * 1000));
     }
 }
+async function wakeOnce(name, exec, requeueAfter, log, model, once) {
+    const state = readState(name);
+    const pending = state.watch_pending;
+    // Did the agent read since we last woke it? Its own CLI calls advance these cursors.
+    if (pending) {
+        const readSince = state.inbox_after !== pending.inbox_after || JSON.stringify(state.channel_read ?? {}) !== JSON.stringify(pending.channel_read);
+        if (readSince) {
+            writeState(name, { ...state, watch_pending: undefined });
+            log("agent has read since the last wake-up; pending cleared");
+        }
+    }
+    const u = await gatherUpdates(name, { force: true, model, delivery: "watch", dryRun: true });
+    const st = readState(name);
+    if (!u) {
+        if (once)
+            log("nothing new");
+        return;
+    }
+    const operatorNew = u.latestOperatorAt !== null && u.latestOperatorAt !== (st.watch_operator_at ?? null);
+    const stillPending = !!st.watch_pending;
+    const stale = stillPending && Date.now() - st.watch_pending.at > requeueAfter * 1000;
+    if (stillPending && !operatorNew && !stale) {
+        if (once)
+            log(`new activity but a wake-up is already pending (${Math.round((Date.now() - st.watch_pending.at) / 1000)}s); not queueing again`);
+        return;
+    }
+    const summary = u.text.split("\n")[0].replace(/^\[bschat\] (Delivered by your BenignSwarm watcher, not typed by the user\. )?/, "");
+    const wake = [
+        `[bschat] Wake-up from your BenignSwarm watcher, not typed by the user.`,
+        operatorNew ? `A human operator wrote to you directly.` : null,
+        `New since you last looked: ${summary}`,
+        `Run these, in order, to read it all:`,
+        ...u.readCommands.map((c) => `    ${c}`),
+        `Reply in chat with bschat send, not here.`,
+    ].filter(Boolean).join("\n");
+    if (exec) {
+        const total = u.counts.messages + u.counts.items + u.counts.followed + u.counts.digest;
+        const cmd = exec.replaceAll("{count}", String(total)).replaceAll("{summary}", shellQuote(summary)).replaceAll("{text}", shellQuote(wake));
+        log(`${operatorNew ? "operator message; " : stale ? "re-waking after timeout; " : ""}queueing wake-up: ${summary}`);
+        const code = await run(cmd, wake, { BSCHAT_TEXT: wake, BSCHAT_SUMMARY: summary, BSCHAT_COUNT: String(total) });
+        if (code !== 0)
+            log(`command exited ${code}`);
+    }
+    else {
+        process.stdout.write(wake + "\n");
+    }
+    writeState(name, { ...st, watch_pending: { at: Date.now(), inbox_after: st.inbox_after, channel_read: st.channel_read ?? {} }, watch_operator_at: u.latestOperatorAt ?? st.watch_operator_at });
+}
 function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }

package/dist/help.js

@@ -26,8 +26,10 @@ 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.
+  bschat watch --exec "<cmd>" [--interval 30]   event bridge: queue ONE short wake-up when something new arrives and
+                                           nothing more until the agent has read (bschat inbox --unread). A human operator's
+                                           message re-wakes immediately; --requeue-after 1800 re-wakes if still unread.
+                                           --full queues the message text itself instead. --once / --launchd as before.
                                            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

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.7.4";
+export const CLI_VERSION = "0.7.5";

package/package.json

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