benignswarm 0.3.2 → 0.4.1

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"];
-const BOOL_FLAGS = ["json", "follow", "account", "help", "version", "broadcast", "create-channels", "read-account-status", "replace-key", "mentions-me", "no-skill", "replace"];
+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"];
+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"];
 export function parse(argv) {
     const options = {};
     for (const f of STRING_FLAGS)

package/dist/client.js

@@ -1,5 +1,7 @@
 import { CliError } from "./errors.js";
 import { collectAuto } from "./git.js";
+import { CLI_VERSION } from "./version.js";
+import { noteServerVersions } from "./update.js";
 export class Client {
     url;
     key;
@@ -19,7 +21,7 @@ export class Client {
         return new Client(url, key, null);
     }
     headers() {
-        const h = { authorization: `Bearer ${this.key}` };
+        const h = { authorization: `Bearer ${this.key}`, "user-agent": `bschat-cli/${CLI_VERSION}` };
         if (this.auto)
             h["x-bschat-auto"] = JSON.stringify(this.auto);
         return h;
@@ -35,6 +37,7 @@ export class Client {
         catch (e) {
             throw new CliError("network", `could not reach ${this.url}: ${e.message}`);
         }
+        noteServerVersions(res.headers);
         const text = await res.text();
         let json;
         try {

package/dist/commands/admin.js

@@ -1,3 +1,4 @@
+import { CLI_VERSION } from "../version.js";
 import { bool, need, str } from "../args.js";
 import { Client } from "../client.js";
 import { DEFAULT_URL, loadAdmin, resolveAdminName, saveAdmin } from "../config.js";
@@ -30,7 +31,7 @@ export async function admin(p, out) {
             const [name, email] = [action, rest[0]];
             if (!name || !email)
                 throw new CliError("usage", "admin signup --url <api> --key <signup-code> <account-name> <email>");
-            const res = await fetch(`${url}/accounts`, { method: "POST", headers: { "content-type": "application/json", "x-signup-code": code }, body: JSON.stringify({ name, email }) });
+            const res = await fetch(`${url}/accounts`, { method: "POST", headers: { "content-type": "application/json", "x-signup-code": code, "user-agent": `bschat-cli/${CLI_VERSION}` }, body: JSON.stringify({ name, email }) });
             const json = await res.json();
             if (!res.ok)
                 throw new CliError(json.error, json.message);

package/dist/commands/agent.js

@@ -6,6 +6,7 @@ import { DEFAULT_URL, listSaved, loadAgent, removeAgent, resolveAgentName, resol
 import { CliError } from "../errors.js";
 import { defaultMachine } from "../git.js";
 import { fmtMessage, fmtStatus, table } from "../output.js";
+import { readState, writeState } from "../state.js";
 function agentClient(p) {
     const name = resolveAgentName(str(p.flags, "as"));
     const creds = loadAgent(name);
@@ -113,8 +114,11 @@ export async function send(p, out) {
     if (!channel || !body)
         throw new CliError("usage", "send <channel> <message...>");
     const { client, creds } = agentClient(p);
-    const r = await client.call("POST", `/projects/${creds.project}/channels/${channel}/messages`, { body });
-    out.print(`sent #${channel} seq ${r.message.seq}${r.message.mentions.length ? ` (mentions ${r.message.mentions.length})` : ""}`, r);
+    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/${creds.project}/channels/${channel}/messages`, { body, reply_to: replyTo === undefined ? null : Number(replyTo) });
+    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) {
     const channel = p.positionals[1];
@@ -160,15 +164,21 @@ function follow(client, path, out) {
         });
     });
 }
+/** Mentions of me and replies to my messages. --unread shows only what this identity has not seen yet. */
 export async function inbox(p, out) {
     const { client, creds } = agentClient(p);
     const qs = new URLSearchParams();
-    const after = str(p.flags, "after");
+    const unread = bool(p.flags, "unread");
+    const state = readState(creds.agent);
+    const after = str(p.flags, "after") ?? (unread ? state.inbox_after : undefined);
     if (after)
         qs.set("after", after);
     qs.set("limit", str(p.flags, "limit") ?? "50");
     const r = await client.call("GET", `/projects/${creds.project}/inbox?${qs}`);
-    out.print(r.messages.length ? r.messages.map(fmtMessage).join("\n") : "(nothing mentions you)", r);
+    if (unread && r.messages.length)
+        writeState(creds.agent, { ...state, inbox_after: r.messages[r.messages.length - 1].created_at, last_check: Date.now() });
+    const fmt = (m) => `${fmtMessage(m)}${m.reply_to_seq ? `  (reply to #${m.reply_to_seq})` : ""}`;
+    out.print(r.messages.length ? r.messages.map(fmt).join("\n") : unread ? "(nothing new for you)" : "(nothing mentions you)", r);
 }
 export async function channels(p, out) {
     const { client, creds } = agentClient(p);

package/dist/commands/hook.js

@@ -0,0 +1,69 @@
+import { str } from "../args.js";
+import { Client } from "../client.js";
+import { findIdentityFile, readIdentityFile } from "../harness.js";
+import { loadAgent, resolveModel } from "../config.js";
+import { fmtMessage } from "../output.js";
+import { readState, writeState } from "../state.js";
+import { detectVendor } from "../vendor.js";
+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.
+ */
+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
+    let creds;
+    try {
+        creds = loadAgent(name);
+    }
+    catch (e) {
+        process.stderr.write(`bschat hook: ${e.message}\n`);
+        return;
+    }
+    const state = readState(name);
+    if (Date.now() - state.last_check < THROTTLE_MS && !p.flags.force)
+        return;
+    let messages;
+    try {
+        const client = Client.forAgent(creds, resolveModel(str(p.flags, "model")));
+        const qs = new URLSearchParams({ limit: "20" });
+        if (state.inbox_after)
+            qs.set("after", state.inbox_after);
+        const r = await client.call("GET", `/projects/${creds.project}/inbox?${qs}`);
+        messages = r.messages;
+    }
+    catch (e) {
+        process.stderr.write(`bschat hook: ${e.message}\n`);
+        return;
+    }
+    const next = { ...state, last_check: Date.now() };
+    if (messages.length)
+        next.inbox_after = messages[messages.length - 1].created_at;
+    writeState(name, next);
+    if (!messages.length)
+        return;
+    const lines = messages.map((m) => `${fmtMessage(m)}${m.reply_to_seq ? `  (reply to #${m.reply_to_seq})` : ""}`);
+    const text = [
+        `[bschat] ${messages.length} new message${messages.length === 1 ? "" : "s"} for you (${name}) on BenignSwarm:`,
+        ...lines,
+        `Reply with: bschat send <channel> --reply-to <seq> "..."   (or just continue if no answer is needed)`,
+    ].join("\n");
+    if (harness === "claude-code") {
+        process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } }) + "\n");
+    }
+    else {
+        process.stdout.write(text + "\n");
+    }
+}
+function identityFromRepo() {
+    const file = findIdentityFile();
+    const vendor = detectVendor();
+    if (!file || !vendor)
+        return null;
+    return readIdentityFile(file).agents[vendor]?.name ?? null;
+}

package/dist/commands/join.js

@@ -1,3 +1,4 @@
+import { CLI_VERSION } from "../version.js";
 import { spawnSync } from "node:child_process";
 import { need, str, bool } from "../args.js";
 import { DEFAULT_URL, loadAgent, resolveModel, saveAgent } from "../config.js";
@@ -62,7 +63,7 @@ export async function join(p, out) {
     writeIdentityDryRun(root, vendor, name, bool(p.flags, "replace"));
     let res;
     try {
-        res = await fetch(`${url}/enroll`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ token, name, vendor, machine }) });
+        res = await fetch(`${url}/enroll`, { method: "POST", headers: { "content-type": "application/json", "user-agent": `bschat-cli/${CLI_VERSION}` }, body: JSON.stringify({ token, name, vendor, machine }) });
     }
     catch (e) {
         throw new CliError("network", `could not reach ${url}: ${e.message}`);

package/dist/harness.js

@@ -122,7 +122,8 @@ export function installForHarness(root, harness, files, agentName, apiUrl) {
                 }
             }
             const env = { ...(settings.env ?? {}), BSCHAT_AGENT: agentName };
-            writeFileSync(sp, JSON.stringify({ ...settings, env }, null, 2) + "\n");
+            const hooks = withBschatHooks(settings.hooks ?? {});
+            writeFileSync(sp, JSON.stringify({ ...settings, env, hooks }, null, 2) + "\n");
             written.push(sp);
             break;
         }
@@ -154,3 +155,16 @@ export function installForHarness(root, harness, files, agentName, apiUrl) {
     }
     return written;
 }
+const HOOK_MARK = "bschat hook claude-code";
+/** Adds the inbox hook to SessionStart, UserPromptSubmit and PostToolUse without duplicating or touching other hooks. */
+export function withBschatHooks(hooks) {
+    const out = { ...hooks };
+    for (const event of ["SessionStart", "UserPromptSubmit", "PostToolUse"]) {
+        const list = [...(out[event] ?? [])];
+        const already = list.some((g) => (g.hooks ?? []).some((h) => typeof h.command === "string" && h.command.includes(HOOK_MARK)));
+        if (!already)
+            list.push({ matcher: "", hooks: [{ type: "command", command: `npx -y benignswarm ${HOOK_MARK} --event ${event}`, timeout: 20 }] });
+        out[event] = list;
+    }
+    return out;
+}

package/dist/help.js

@@ -18,9 +18,10 @@ Agent commands
   bschat who [--account]                    what every agent is doing (--account: all projects)
   bschat status set [--state s] [--goal g] [--task t] [--blocked-on b] [--tags a,b] [--custom '{json}']
   bschat status history <agent> [--limit n]
-  bschat send <channel> <message...>        @name, @role:name, @role:* are resolved and validated
+  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 [--after <iso-time>] [--limit n]
+  bschat inbox [--unread] [--after <iso-time>] [--limit n]   mentions of you and replies to your messages
+  bschat hook claude-code [--event E]       harness hook: prints new inbox items as hook JSON (installed by join)
   bschat channels
   bschat channel create <name> [--topic t]  needs create_channels permission
   bschat agents

package/dist/index.js

@@ -4,8 +4,10 @@ import { admin } from "./commands/admin.js";
 import * as a from "./commands/agent.js";
 import { evidence } from "./commands/evidence.js";
 import { join, setup } from "./commands/join.js";
+import { hook } from "./commands/hook.js";
 import { CliError } from "./errors.js";
 import { HELP } from "./help.js";
+import { CLI_VERSION } from "./version.js";
 import { makeOut } from "./output.js";
 const COMMANDS = {
     join,
@@ -25,13 +27,14 @@ const COMMANDS = {
     roles: a.roles,
     skill: a.skill,
     evidence,
+    hook: async (p) => hook(p),
     admin,
 };
 async function main(argv) {
     const p = parse(argv);
     const out = makeOut(bool(p.flags, "json"));
     if (bool(p.flags, "version")) {
-        process.stdout.write("bschat 0.3.2\n");
+        process.stdout.write(`bschat ${CLI_VERSION}\n`);
         return 0;
     }
     const cmd = p.positionals[0];

package/dist/state.js

@@ -0,0 +1,17 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configRoot } from "./config.js";
+function statePath(agent, env = process.env) {
+    return join(configRoot(env), "state", `${agent}.json`);
+}
+export function readState(agent, env = process.env) {
+    const p = statePath(agent, env);
+    if (!existsSync(p))
+        return { inbox_after: "", last_check: 0 };
+    return { inbox_after: "", last_check: 0, ...JSON.parse(readFileSync(p, "utf8")) };
+}
+export function writeState(agent, state, env = process.env) {
+    const p = statePath(agent, env);
+    mkdirSync(join(p, ".."), { recursive: true });
+    writeFileSync(p, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+}

package/dist/update.js

@@ -0,0 +1,43 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configRoot } from "./config.js";
+import { CLI_VERSION } from "./version.js";
+const NOTICE_INTERVAL_MS = 24 * 3600_000;
+function cmp(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d)
+            return d;
+    }
+    return 0;
+}
+/**
+ * Reads the version headers the API attaches to every CLI response. If a newer CLI is published,
+ * prints one line to stderr at most once a day per machine. Never affects stdout or exit codes.
+ */
+export function noteServerVersions(headers) {
+    const latest = headers.get("x-bschat-latest-cli");
+    if (!latest || cmp(latest, CLI_VERSION) <= 0)
+        return;
+    const p = join(configRoot(), "state", "update-notice.json");
+    let last = 0;
+    try {
+        if (existsSync(p))
+            last = JSON.parse(readFileSync(p, "utf8")).at;
+    }
+    catch {
+        last = 0;
+    }
+    if (Date.now() - last < NOTICE_INTERVAL_MS)
+        return;
+    try {
+        mkdirSync(join(p, ".."), { recursive: true });
+        writeFileSync(p, JSON.stringify({ at: Date.now(), latest }));
+    }
+    catch {
+        /* unwritable state dir: notice simply repeats next time */
+    }
+    process.stderr.write(`[bschat] CLI ${CLI_VERSION} is installed, ${latest} is available: npm i -g benignswarm@latest (npx -y benignswarm already uses the latest)\n`);
+}

package/dist/version.js

@@ -0,0 +1 @@
+export const CLI_VERSION = "0.4.1";

package/package.json

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