benignswarm 0.3.1 → 0.4.0

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"];
-const BOOL_FLAGS = ["json", "follow", "account", "help", "version", "broadcast", "create-channels", "read-account-status", "replace-key", "mentions-me", "no-skill"];
+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/commands/admin.js

@@ -90,7 +90,7 @@ async function agent(action, rest, p, out) {
     }
     else if (action === "create" && proj && name) {
         const r = await c.call("POST", `/projects/${proj}/agents`, { name, vendor: need(p.flags, "vendor"), role: str(p.flags, "role") ?? null, machine: str(p.flags, "machine") ?? null });
-        out.print(`created agent ${name} in ${proj}${r.agent.role_name ? ` with role ${r.agent.role_name}` : ""}\nKey (shown once): ${r.key}\nOn the agent's machine: bschat login --as ${name} --key ${r.key}`, r);
+        out.print(`created agent ${name} in ${proj}${r.agent.role_name ? ` with role ${r.agent.role_name}` : ""}. Key shown once.\nPaste this into the agent's instructions:\n\n${r.instructions}`, r);
     }
     else if (action === "role" && proj && name && extra) {
         const r = await c.call("PATCH", `/projects/${proj}/agents/${name}`, { role: extra === "none" ? null : extra });
@@ -98,7 +98,7 @@ async function agent(action, rest, p, out) {
     }
     else if (action === "rotate-key" && proj && name) {
         const r = await c.call("POST", `/projects/${proj}/agents/${name}/keys`, { machine: str(p.flags, "machine") ?? null });
-        out.print(`previous keys revoked. New key (shown once): ${r.key}\nOn the agent's machine: bschat login --as ${name} --key ${r.key}`, r);
+        out.print(`previous keys revoked. New key shown once.\nPaste this into the agent's instructions:\n\n${r.instructions}`, r);
     }
     else if (action === "delete" && proj && name) {
         const r = await c.call("DELETE", `/projects/${proj}/agents/${name}`);

package/dist/commands/agent.js

@@ -2,14 +2,15 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { bool, need, str } from "../args.js";
 import { Client } from "../client.js";
-import { DEFAULT_URL, listSaved, loadAgent, removeAgent, resolveAgentName, saveAgent } from "../config.js";
+import { DEFAULT_URL, listSaved, loadAgent, removeAgent, resolveAgentName, resolveModel, saveAgent } from "../config.js";
 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);
-    const model = str(p.flags, "model") ?? process.env.BSCHAT_MODEL;
+    const model = resolveModel(str(p.flags, "model"));
     return { client: Client.forAgent(creds, model), creds };
 }
 export async function login(p, out) {
@@ -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/evidence.js

@@ -3,7 +3,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename, extname } from "node:path";
 import { str } from "../args.js";
 import { Client } from "../client.js";
-import { loadAgent, resolveAgentName } from "../config.js";
+import { loadAgent, resolveAgentName, resolveModel } from "../config.js";
 import { CliError } from "../errors.js";
 import { table } from "../output.js";
 const TYPES = {
@@ -20,7 +20,7 @@ export async function evidence(p, out) {
     const sub = p.positionals[1];
     const name = resolveAgentName(str(p.flags, "as"));
     const creds = loadAgent(name);
-    const client = Client.forAgent(creds, str(p.flags, "model") ?? process.env.BSCHAT_MODEL);
+    const client = Client.forAgent(creds, resolveModel(str(p.flags, "model")));
     if (sub === "post") {
         const file = p.positionals[2];
         if (!file)

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,10 +1,48 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join as pjoin } from "node:path";
+import { spawnSync } from "node:child_process";
 import { need, str, bool } from "../args.js";
-import { DEFAULT_URL, saveAgent } from "../config.js";
+import { DEFAULT_URL, loadAgent, resolveModel, saveAgent } from "../config.js";
 import { CliError } from "../errors.js";
 import { defaultMachine } from "../git.js";
+import { HARNESSES, findIdentityFile, installForHarness, normalizeVendor, readIdentityFile, writeIdentity } from "../harness.js";
 import { detectVendor } from "../vendor.js";
+function repoRoot() {
+    const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return r.status === 0 ? r.stdout.trim() : process.cwd();
+}
+async function fetchSkill(url) {
+    const get = async (p) => {
+        const res = await fetch(url + p);
+        if (!res.ok)
+            throw new CliError("fetch_failed", `${url}${p} returned ${res.status}`);
+        return res.text();
+    };
+    return { skill: await get("/skill/SKILL.md"), api: await get("/skill/references/api.md") };
+}
+function harnessList(p, vendor) {
+    const flag = str(p.flags, "harness");
+    if (!flag)
+        return [vendor];
+    if (flag === "all")
+        return [...HARNESSES];
+    return flag.split(",").map((h) => normalizeVendor(h.trim()));
+}
+/** Writes identity + harness files for an identity already saved on this machine. */
+export async function setup(p, out) {
+    const name = str(p.flags, "as") ?? process.env.BSCHAT_AGENT;
+    if (!name)
+        throw new CliError("usage", "setup needs --as <agent-name> (an identity already saved with join or login)");
+    const creds = loadAgent(name);
+    const vendor = normalizeVendor(str(p.flags, "vendor") ?? creds.vendor);
+    const root = str(p.flags, "dir") ?? repoRoot();
+    const model = resolveModel(str(p.flags, "model"));
+    const idPath = writeIdentity(root, vendor, name, model, bool(p.flags, "replace"));
+    const files = await fetchSkill(creds.url);
+    const written = [];
+    for (const h of harnessList(p, vendor))
+        written.push(...installForHarness(root, h, files, name, creds.url));
+    const uniq = [...new Set(written)];
+    out.print(`Recorded ${vendor} -> ${name} in ${idPath}\nWrote: ${uniq.join(", ")}`, { identity: idPath, written: uniq });
+}
 export async function join(p, out) {
     const name = str(p.flags, "as") ?? process.env.BSCHAT_AGENT;
     if (!name)
@@ -12,11 +50,16 @@ export async function join(p, out) {
     const token = need(p.flags, "token");
     if (!token.startsWith("bs_enroll_"))
         throw new CliError("usage", "--token must be an enrollment token (bs_enroll_...)");
-    const vendor = str(p.flags, "vendor") ?? detectVendor();
-    if (!vendor)
-        throw new CliError("usage", "could not detect which agent product you are; pass --vendor <claude-code|codex|gemini-cli|cursor|aider|...>");
+    const rawVendor = str(p.flags, "vendor") ?? detectVendor();
+    if (!rawVendor)
+        throw new CliError("usage", `could not detect which agent product you are; pass --vendor <${HARNESSES.join("|")}>`);
+    const vendor = normalizeVendor(rawVendor);
     const url = (str(p.flags, "url") ?? process.env.BSCHAT_URL ?? DEFAULT_URL).replace(/\/$/, "");
     const machine = defaultMachine(str(p.flags, "label"));
+    const root = str(p.flags, "dir") ?? repoRoot();
+    const model = str(p.flags, "model") ?? process.env.BSCHAT_MODEL;
+    // Fail before touching the server if this repo already binds this vendor to another agent.
+    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 }) });
@@ -28,27 +71,35 @@ export async function join(p, out) {
     if (!res.ok)
         throw new CliError(json.error ?? `http_${res.status}`, json.message ?? "join failed");
     const path = saveAgent({ url, key: json.key, account: json.project.id, project: json.project.name, agent: name, vendor, machine });
-    let skillDir = null;
+    const idPath = writeIdentity(root, vendor, name, model, bool(p.flags, "replace"));
+    let written = [];
     if (!bool(p.flags, "no-skill")) {
-        skillDir = str(p.flags, "skill-dir") ?? pjoin(process.cwd(), ".claude", "skills", "bschat");
-        const main = await (await fetch(`${url}/skill/SKILL.md`)).text();
-        const api = await (await fetch(`${url}/skill/references/api.md`)).text();
-        mkdirSync(pjoin(skillDir, "references"), { recursive: true });
-        writeFileSync(pjoin(skillDir, "SKILL.md"), main);
-        writeFileSync(pjoin(skillDir, "references", "api.md"), api);
+        const files = await fetchSkill(url);
+        for (const h of harnessList(p, vendor))
+            written.push(...installForHarness(root, h, files, name, url));
+        written = [...new Set(written)];
     }
-    const model = str(p.flags, "model") ?? process.env.BSCHAT_MODEL ?? "<your model id, e.g. claude-fable-5-1>";
     const human = [
         `Joined project "${json.project.name}" as agent "${name}" (${vendor})${json.agent.role_name ? ` with role ${json.agent.role_name}` : ""}.`,
         `Credentials saved to ${path} (private to this machine).`,
-        skillDir ? `Skill installed to ${skillDir}.` : null,
+        `This repo now maps ${vendor} -> ${name} in ${idPath}, so bschat commands here know who you are, even after a reboot.`,
+        written.length ? `Harness files written: ${written.join(", ")}` : null,
         ``,
-        `Now run these in your shell for the rest of this session:`,
+        `Optional for this shell session (the identity file already covers you in this repo):`,
         ``,
         `    export BSCHAT_AGENT=${name}`,
-        `    export BSCHAT_MODEL=${model}`,
+        `    export BSCHAT_MODEL=${model ?? "<your model id, e.g. claude-fable-5-1>"}`,
         ``,
-        `Then: bschat me && bschat who && bschat read general`,
+        `Next: bschat me && bschat who && bschat read general`,
     ].filter((l) => l !== null).join("\n");
-    out.print(human, { agent: json.agent, project: json.project, saved: path, skill_dir: skillDir, export: { BSCHAT_AGENT: name, BSCHAT_MODEL: model } });
+    out.print(human, { agent: json.agent, project: json.project, saved: path, identity: idPath, written, export: { BSCHAT_AGENT: name, BSCHAT_MODEL: model ?? null } });
+}
+function writeIdentityDryRun(root, vendor, name, replace) {
+    const p = findIdentityFile(root);
+    if (!p || !p.startsWith(root))
+        return;
+    const existing = readIdentityFile(p).agents[vendor];
+    if (existing && existing.name !== name && !replace) {
+        throw new CliError("identity_exists", `${p} already maps ${vendor} to agent "${existing.name}"`, `Pass --replace to switch this repo's ${vendor} identity to "${name}", or join from a different repo.`);
+    }
 }

package/dist/config.js

@@ -2,6 +2,8 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { CliError } from "./errors.js";
+import { findIdentityFile, readIdentityFile } from "./harness.js";
+import { detectVendor } from "./vendor.js";
 export const DEFAULT_URL = "https://api.benignswarm.org";
 export function configRoot(env = process.env) {
     return env.BSCHAT_HOME ?? join(homedir(), ".bschat");
@@ -40,15 +42,26 @@ export function listSaved(kind, env = process.env) {
     return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => f.slice(0, -5)).sort();
 }
 /**
- * Resolves which agent identity to use. Only --as or BSCHAT_AGENT count. There is deliberately no
- * default and no "only one configured" shortcut: several agents share this machine and cwd.
+ * Resolves which agent identity to use, in order: --as, BSCHAT_AGENT, then the repo-local
+ * `.bschat/identity.json` entry for the detected vendor (written by `bschat join`). There is
+ * no "only one saved identity" shortcut: several agents share this machine and cwd, so the
+ * only file-based answer accepted is an explicit per-vendor mapping for this repo.
  */
-export function resolveAgentName(asFlag, env = process.env) {
-    const name = asFlag ?? env.BSCHAT_AGENT;
+export function resolveAgentName(asFlag, env = process.env, cwd = process.cwd()) {
+    let name = asFlag ?? env.BSCHAT_AGENT;
+    if (!name) {
+        const file = findIdentityFile(cwd);
+        const vendor = detectVendor(env);
+        if (file && vendor) {
+            const entry = readIdentityFile(file).agents[vendor];
+            if (entry)
+                name = entry.name;
+        }
+    }
     if (!name) {
         const saved = listSaved("agents", env);
         throw new CliError("no_identity", "BSCHAT_AGENT is not set and --as was not given; bschat cannot tell which agent you are", saved.length
-            ? `Saved identities on this machine: ${saved.join(", ")}. Ask the user which one is yours, then: export BSCHAT_AGENT=<name>`
+            ? `Saved identities on this machine: ${saved.join(", ")}. Ask the user which one is yours, then: export BSCHAT_AGENT=<name> (or run: bschat setup --as <name> to record it for this repo)`
             : "No identities are saved here. The account admin creates one with: bschat admin agent create <project> <name> --vendor <vendor>, then you run: bschat login --as <name> --key <key>");
     }
     return name;
@@ -75,3 +88,15 @@ export function loadAdmin(name, env = process.env) {
         throw new CliError("not_logged_in", `no saved admin credentials named ${name}`, "Run: bschat admin login --as <name> --key <bs_admin_...>");
     return JSON.parse(readFileSync(p, "utf8"));
 }
+/** Model id: --model, BSCHAT_MODEL, then the repo identity file's entry for the detected vendor. */
+export function resolveModel(flag, env = process.env, cwd = process.cwd()) {
+    if (flag)
+        return flag;
+    if (env.BSCHAT_MODEL)
+        return env.BSCHAT_MODEL;
+    const file = findIdentityFile(cwd);
+    const vendor = detectVendor(env);
+    if (file && vendor)
+        return readIdentityFile(file).agents[vendor]?.model;
+    return undefined;
+}

package/dist/harness.js

@@ -0,0 +1,170 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CliError } from "./errors.js";
+/** Canonical vendor ids and the aliases people type. */
+const VENDOR_ALIASES = {
+    "claude-code": "claude-code", claude: "claude-code", anthropic: "claude-code",
+    codex: "codex", chatgpt: "codex", openai: "codex", gpt: "codex",
+    antigravity: "antigravity", google: "antigravity", gemini: "gemini-cli", "gemini-cli": "gemini-cli",
+    dsh: "dsh", deepseek: "dsh", "deepseek-harness": "dsh",
+    cursor: "cursor", aider: "aider", copilot: "copilot",
+};
+export const HARNESSES = ["claude-code", "codex", "antigravity", "dsh", "gemini-cli", "cursor", "aider", "copilot"];
+export function normalizeVendor(v) {
+    return VENDOR_ALIASES[v.toLowerCase()] ?? v.toLowerCase();
+}
+export const IDENTITY_FILE = join(".bschat", "identity.json");
+/** Walks up from cwd to find the repo-local identity file. */
+export function findIdentityFile(start = process.cwd()) {
+    let dir = start;
+    for (;;) {
+        const p = join(dir, IDENTITY_FILE);
+        if (existsSync(p))
+            return p;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function readIdentityFile(path) {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    if (!raw.agents || typeof raw.agents !== "object")
+        throw new CliError("bad_identity_file", `${path} is not a bschat identity file`);
+    return raw;
+}
+/**
+ * Records which agent name a given vendor uses in this repo. Refuses to silently replace an
+ * existing different name: two agents of one vendor in one worktree must use BSCHAT_AGENT.
+ */
+export function writeIdentity(root, vendor, name, model, replace) {
+    const p = join(root, IDENTITY_FILE);
+    let file = { agents: {} };
+    if (existsSync(p))
+        file = readIdentityFile(p);
+    const existing = file.agents[vendor];
+    if (existing && existing.name !== name && !replace) {
+        throw new CliError("identity_exists", `${p} already maps ${vendor} to agent "${existing.name}"`, `Pass --replace to switch this repo's ${vendor} identity to "${name}", or set BSCHAT_AGENT per session.`);
+    }
+    file.agents[vendor] = { name, ...(model ? { model } : {}) };
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(file, null, 2) + "\n");
+    ensureGitignore(root, [".bschat/", ".claude/settings.local.json"]);
+    return p;
+}
+export function ensureGitignore(root, entries) {
+    if (!existsSync(join(root, ".git")))
+        return;
+    const p = join(root, ".gitignore");
+    const current = existsSync(p) ? readFileSync(p, "utf8") : "";
+    const lines = current.split("\n");
+    const missing = entries.filter((e) => !lines.includes(e));
+    if (!missing.length)
+        return;
+    writeFileSync(p, (current.endsWith("\n") || current === "" ? current : current + "\n") + "# bschat (per-machine agent identity)\n" + missing.join("\n") + "\n");
+}
+const START = "<!-- bschat:start -->";
+const END = "<!-- bschat:end -->";
+/** Replaces or appends a marked block in a markdown file. Idempotent. */
+export function upsertBlock(path, body) {
+    const block = `${START}\n${body.trim()}\n${END}\n`;
+    if (!existsSync(path)) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, block);
+        return;
+    }
+    const cur = readFileSync(path, "utf8");
+    const s = cur.indexOf(START);
+    const e = cur.indexOf(END);
+    if (s >= 0 && e > s)
+        writeFileSync(path, cur.slice(0, s) + block + cur.slice(e + END.length).replace(/^\n/, ""));
+    else
+        writeFileSync(path, (cur.endsWith("\n") || cur === "" ? cur : cur + "\n") + "\n" + block);
+}
+function pointer(_name, apiUrl) {
+    return [
+        `## bschat: agent chat for this project`,
+        ``,
+        `This repo's agents coordinate on BenignSwarm. Your identity for this repo is recorded in`,
+        `\`.bschat/identity.json\` (vendor -> agent name); the CLI reads it, so \`npx -y benignswarm <cmd>\``,
+        `works without env vars. If you are told you are a different agent, export BSCHAT_AGENT=<name>.`,
+        ``,
+        `Start of session: \`npx -y benignswarm me\`, \`npx -y benignswarm who\`, \`npx -y benignswarm inbox\`.`,
+        `Full instructions: \`.bschat/SKILL.md\` in this repo, or ${apiUrl}/skill.`,
+    ].join("\n");
+}
+/**
+ * Writes the files a given harness needs to discover bschat in this repo.
+ * Returns the paths written. Each writer is idempotent.
+ */
+export function installForHarness(root, harness, files, agentName, apiUrl) {
+    const written = [];
+    const neutral = join(root, ".bschat");
+    mkdirSync(join(neutral, "references"), { recursive: true });
+    writeFileSync(join(neutral, "SKILL.md"), files.skill);
+    writeFileSync(join(neutral, "references", "api.md"), files.api);
+    written.push(join(neutral, "SKILL.md"));
+    switch (harness) {
+        case "claude-code": {
+            const dir = join(root, ".claude", "skills", "bschat");
+            mkdirSync(join(dir, "references"), { recursive: true });
+            writeFileSync(join(dir, "SKILL.md"), files.skill);
+            writeFileSync(join(dir, "references", "api.md"), files.api);
+            written.push(join(dir, "SKILL.md"));
+            const sp = join(root, ".claude", "settings.local.json");
+            let settings = {};
+            if (existsSync(sp)) {
+                try {
+                    settings = JSON.parse(readFileSync(sp, "utf8"));
+                }
+                catch {
+                    throw new CliError("bad_settings", `${sp} is not valid JSON; fix it or remove it`);
+                }
+            }
+            const env = { ...(settings.env ?? {}), BSCHAT_AGENT: agentName };
+            const hooks = withBschatHooks(settings.hooks ?? {});
+            writeFileSync(sp, JSON.stringify({ ...settings, env, hooks }, null, 2) + "\n");
+            written.push(sp);
+            break;
+        }
+        case "codex":
+        case "dsh":
+        case "aider":
+        case "copilot":
+        case "cursor": {
+            const p = join(root, "AGENTS.md");
+            upsertBlock(p, pointer(agentName, apiUrl));
+            written.push(p);
+            break;
+        }
+        case "antigravity": {
+            const p = join(root, ".agents", "rules", "bschat.md");
+            mkdirSync(dirname(p), { recursive: true });
+            writeFileSync(p, `---\ntrigger: always_on\ndescription: "How to use bschat, the agent chat for this project"\n---\n\n${pointer(agentName, apiUrl)}\n`);
+            written.push(p);
+            break;
+        }
+        case "gemini-cli": {
+            const p = join(root, "GEMINI.md");
+            upsertBlock(p, pointer(agentName, apiUrl));
+            written.push(p);
+            break;
+        }
+        default:
+            throw new CliError("unknown_harness", `no harness integration for "${harness}"`, `Known: ${HARNESSES.join(", ")}. The neutral copy at .bschat/SKILL.md was still written.`);
+    }
+    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

@@ -5,7 +5,10 @@ Model (recommended):                    --model <id> or BSCHAT_MODEL=<id>
 Output:                                 --json for machine-readable output
 
 Joining (first time on a machine, with an enrollment token from the account owner)
-  bschat join --as <name> --token <bs_enroll_...> [--vendor v] [--model m] [--label l] [--skill-dir d] [--no-skill]
+  bschat join --as <name> --token <bs_enroll_...> [--vendor v] [--model m] [--label l] [--harness h1,h2|all] [--no-skill] [--replace]
+  bschat setup --as <name> [--harness ...] [--replace]   (re)write this repo's identity file and harness files
+      Harnesses: claude-code (.claude/skills + settings env), codex and dsh (AGENTS.md), antigravity (.agents/rules),
+      gemini-cli (GEMINI.md). Identity persists in .bschat/identity.json per repo and vendor, surviving reboots.
 
 Agent commands
   bschat login --as <name> --key <bs_agent_...> [--url <api>] [--label <machine-label>]
@@ -15,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

@@ -3,12 +3,14 @@ import { bool, parse } from "./args.js";
 import { admin } from "./commands/admin.js";
 import * as a from "./commands/agent.js";
 import { evidence } from "./commands/evidence.js";
-import { join } from "./commands/join.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 { makeOut } from "./output.js";
 const COMMANDS = {
     join,
+    setup,
     login: a.login,
     logout: a.logout,
     identities: a.identities,
@@ -24,13 +26,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.1\n");
+        process.stdout.write("bschat 0.4.0\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/vendor.js

@@ -1,10 +1,11 @@
+import { normalizeVendor } from "./harness.js";
 /**
  * Detects which agent product is running the CLI from signals those products set themselves.
  * Returns null when nothing is recognised; the caller must then require --vendor.
  */
 export function detectVendor(env = process.env) {
     if (env.BSCHAT_VENDOR)
-        return env.BSCHAT_VENDOR;
+        return normalizeVendor(env.BSCHAT_VENDOR);
     if (env.CLAUDECODE === "1" || env.CLAUDE_CODE_ENTRYPOINT)
         return "claude-code";
     if (env.CODEX_SANDBOX || env.CODEX_THREAD_ID || env.OPENAI_CODEX)
@@ -15,6 +16,10 @@ export function detectVendor(env = process.env) {
         return "cursor";
     if (env.AIDER_MODEL)
         return "aider";
+    if (env.ANTIGRAVITY_AGENT || env.ANTIGRAVITY_SESSION_ID)
+        return "antigravity";
+    if (env.DSH_SESSION_ID || env.DEEPSEEK_HARNESS)
+        return "dsh";
     if (env.COPILOT_AGENT || env.GITHUB_COPILOT_CLI)
         return "copilot";
     return null;

package/package.json

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