benignswarm 0.0.0-stage → 0.3.0

package/dist/args.js

@@ -0,0 +1,31 @@
+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"];
+export function parse(argv) {
+    const options = {};
+    for (const f of STRING_FLAGS)
+        options[f] = { type: "string" };
+    for (const f of BOOL_FLAGS)
+        options[f] = { type: "boolean" };
+    try {
+        const { values, positionals } = parseArgs({ args: argv, options, allowPositionals: true, strict: true });
+        return { positionals, flags: values };
+    }
+    catch (e) {
+        throw new CliError("usage", e.message, "Run: bschat --help");
+    }
+}
+export function str(flags, k) {
+    const v = flags[k];
+    return typeof v === "string" ? v : undefined;
+}
+export function bool(flags, k) {
+    return flags[k] === true;
+}
+export function need(flags, k) {
+    const v = str(flags, k);
+    if (v === undefined || v === "")
+        throw new CliError("usage", `--${k} is required`);
+    return v;
+}

package/dist/client.js

@@ -0,0 +1,60 @@
+import { CliError } from "./errors.js";
+import { collectAuto } from "./git.js";
+export class Client {
+    url;
+    key;
+    auto;
+    constructor(url, key, auto) {
+        this.url = url;
+        this.key = key;
+        this.auto = auto;
+    }
+    static forAgent(c, model) {
+        return new Client(c.url, c.key, { ...collectAuto({ model, machine: c.machine }) });
+    }
+    static forAdmin(c) {
+        return new Client(c.url, c.key, null);
+    }
+    static raw(url, key) {
+        return new Client(url, key, null);
+    }
+    headers() {
+        const h = { authorization: `Bearer ${this.key}` };
+        if (this.auto)
+            h["x-bschat-auto"] = JSON.stringify(this.auto);
+        return h;
+    }
+    async call(method, path, body) {
+        const headers = this.headers();
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        let res;
+        try {
+            res = await fetch(this.url + path, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+        }
+        catch (e) {
+            throw new CliError("network", `could not reach ${this.url}: ${e.message}`);
+        }
+        const text = await res.text();
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new CliError("bad_response", `${method} ${path} returned non-JSON (${res.status}): ${text.slice(0, 200)}`);
+        }
+        if (!res.ok) {
+            const err = json;
+            throw new CliError(err.error ?? `http_${res.status}`, err.message ?? text);
+        }
+        return json;
+    }
+    wsUrl(path) {
+        return this.url.replace(/^http/, "ws") + path;
+    }
+    /** Node 22+ has a global WebSocket, but it cannot set headers; the token goes in the subprotocol. */
+    connect(path) {
+        const ws = new WebSocket(this.wsUrl(path), [`bschat-token.${this.key}`]);
+        return ws;
+    }
+}

package/dist/commands/admin.js

@@ -0,0 +1,187 @@
+import { bool, need, str } from "../args.js";
+import { Client } from "../client.js";
+import { DEFAULT_URL, loadAdmin, resolveAdminName, saveAdmin } from "../config.js";
+import { CliError } from "../errors.js";
+import { table } from "../output.js";
+function adminClient(p) {
+    return Client.forAdmin(loadAdmin(resolveAdminName(str(p.flags, "admin"))));
+}
+export async function admin(p, out) {
+    const [, group, action, ...rest] = p.positionals;
+    switch (group) {
+        case "login": {
+            const nick = str(p.flags, "as");
+            if (!nick)
+                throw new CliError("usage", "admin login --as <nickname> --key <bs_admin_...>");
+            const key = need(p.flags, "key");
+            if (!key.startsWith("bs_admin_"))
+                throw new CliError("usage", "admin login expects an admin key (bs_admin_...)");
+            const url = (str(p.flags, "url") ?? process.env.BSCHAT_URL ?? DEFAULT_URL).replace(/\/$/, "");
+            const me = await Client.raw(url, key).call("GET", "/me");
+            if (me.kind !== "admin")
+                throw new CliError("bad_key", "key is not an admin key");
+            const path = saveAdmin(nick, { url, key, account: me.account_id });
+            out.print(`Saved admin login ${nick} to ${path}\nNext: export BSCHAT_ADMIN=${nick}`, { saved: path });
+            return;
+        }
+        case "signup": {
+            const url = (str(p.flags, "url") ?? process.env.BSCHAT_URL ?? DEFAULT_URL).replace(/\/$/, "");
+            const code = need(p.flags, "key");
+            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 json = await res.json();
+            if (!res.ok)
+                throw new CliError(json.error, json.message);
+            out.print(`Account ${json.account.name} created.\nAdmin key (shown once): ${json.admin_key}\nNext: bschat admin login --as ${name} --key ${json.admin_key} --url ${url}`, json);
+            return;
+        }
+        case "project":
+            return project(action, rest, p, out);
+        case "agent":
+            return agent(action, rest, p, out);
+        case "role":
+            return role(action, rest, p, out);
+        case "channel":
+            return channel(action, rest, p, out);
+        case "enroll":
+            return enroll(action, rest, p, out);
+        case "keys": {
+            const r = await adminClient(p).call("GET", "/account/keys");
+            out.print(table(r.keys, ["id", "kind", "prefix", "agent_name", "project_name", "machine", "created_at", "revoked_at"]), r);
+            return;
+        }
+        case "delete-account": {
+            const confirm = str(p.flags, "confirm");
+            if (confirm !== "delete everything")
+                throw new CliError("usage", 'admin delete-account --confirm "delete everything"');
+            const r = await adminClient(p).call("DELETE", "/account", { confirm });
+            out.print("account deleted", r);
+            return;
+        }
+        default:
+            throw new CliError("usage", `unknown admin command ${group ?? ""}`, "Run: bschat --help");
+    }
+}
+async function project(action, rest, p, out) {
+    const c = adminClient(p);
+    if (action === "list") {
+        const r = await c.call("GET", "/projects");
+        out.print(table(r.projects, ["name", "id", "created_at"]), r);
+    }
+    else if (action === "create" && rest[0]) {
+        const r = await c.call("POST", "/projects", { name: rest[0] });
+        out.print(`created project ${r.project.name} (channel #general)`, r);
+    }
+    else if (action === "delete" && rest[0]) {
+        const r = await c.call("DELETE", `/projects/${rest[0]}`);
+        out.print(`deleted project ${rest[0]} and all its data`, r);
+    }
+    else
+        throw new CliError("usage", "admin project create|list|delete <name>");
+}
+async function agent(action, rest, p, out) {
+    const c = adminClient(p);
+    const [proj, name, extra] = rest;
+    if (action === "list" && proj) {
+        const r = await c.call("GET", `/projects/${proj}/agents`);
+        out.print(table(r.agents, ["name", "vendor", "role_name", "active_keys", "created_at"]), r);
+    }
+    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);
+    }
+    else if (action === "role" && proj && name && extra) {
+        const r = await c.call("PATCH", `/projects/${proj}/agents/${name}`, { role: extra === "none" ? null : extra });
+        out.print(`agent ${name} role is now ${r.role_name ?? "(none)"}`, r);
+    }
+    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);
+    }
+    else if (action === "delete" && proj && name) {
+        const r = await c.call("DELETE", `/projects/${proj}/agents/${name}`);
+        out.print(`deleted agent ${name}`, r);
+    }
+    else
+        throw new CliError("usage", "admin agent create|list|role|rotate-key|delete ...", "Run: bschat --help");
+}
+async function role(action, rest, p, out) {
+    const c = adminClient(p);
+    const proj = str(p.flags, "project");
+    const base = proj ? `/projects/${proj}/roles` : "/roles";
+    if (action === "list") {
+        const r = await c.call("GET", base);
+        const rows = r.roles.map((x) => ({ name: x.name, scope: x.project_id ? "project" : "account", cardinality: x.cardinality, post: x.permissions.post_channels.join(","), broadcast: x.permissions.broadcast, create_channels: x.permissions.create_channels, read_account_status: x.permissions.read_account_status }));
+        out.print(table(rows, ["name", "scope", "cardinality", "post", "broadcast", "create_channels", "read_account_status"]), r);
+    }
+    else if (action === "create" && rest[0]) {
+        let permissions = { post_channels: ["*"], broadcast: bool(p.flags, "broadcast"), create_channels: bool(p.flags, "create-channels"), read_account_status: bool(p.flags, "read-account-status") };
+        const raw = str(p.flags, "permissions");
+        if (raw) {
+            try {
+                permissions = JSON.parse(raw);
+            }
+            catch {
+                throw new CliError("usage", "--permissions must be valid JSON");
+            }
+        }
+        const r = await c.call("POST", base, { name: rest[0], description: str(p.flags, "description") ?? "", permissions, cardinality: str(p.flags, "cardinality") ?? "many" });
+        out.print(`created ${proj ? "project" : "account"} role ${r.role.name}`, r);
+    }
+    else if (action === "delete" && rest[0]) {
+        const r = await c.call("DELETE", `${base}/${rest[0]}`);
+        out.print(`deleted role ${rest[0]}`, r);
+    }
+    else
+        throw new CliError("usage", "admin role create|list|delete <name> [--project p]");
+}
+async function channel(action, rest, p, out) {
+    const c = adminClient(p);
+    const [proj, name] = rest;
+    if (action === "create" && proj && name) {
+        const r = await c.call("POST", `/projects/${proj}/channels`, { name, topic: str(p.flags, "topic") ?? "" });
+        out.print(`created #${name} in ${proj}`, r);
+    }
+    else if (action === "delete" && proj && name) {
+        const r = await c.call("DELETE", `/projects/${proj}/channels/${name}`);
+        out.print(`deleted #${name}`, r);
+    }
+    else
+        throw new CliError("usage", "admin channel create|delete <project> <name>");
+}
+async function enroll(action, rest, p, out) {
+    const c = adminClient(p);
+    const [proj, id] = rest;
+    if (action === "create" && proj) {
+        const body = {};
+        const name = str(p.flags, "name");
+        const prefix = str(p.flags, "prefix");
+        if (name)
+            body.name = name;
+        if (prefix)
+            body.name_prefix = prefix;
+        const role = str(p.flags, "role");
+        if (role)
+            body.role = role;
+        const uses = str(p.flags, "uses");
+        if (uses)
+            body.max_uses = Number(uses);
+        const hours = str(p.flags, "expires-hours");
+        if (hours)
+            body.expires_hours = Number(hours);
+        const r = await c.call("POST", `/projects/${proj}/enroll`, body);
+        out.print(`Enrollment token created (expires ${r.enroll.expires_at}, ${r.enroll.max_uses} use${r.enroll.max_uses === 1 ? "" : "s"}).\nPaste this into the agent's instructions:\n\n${r.invite}`, r);
+    }
+    else if (action === "list" && proj) {
+        const r = await c.call("GET", `/projects/${proj}/enroll`);
+        out.print(table(r.enroll.map((t) => ({ ...t, joined: t.joined.join(",") })), ["id", "prefix", "status", "fixed_name", "name_prefix", "role_name", "uses", "max_uses", "expires_at", "joined"]), r);
+    }
+    else if (action === "revoke" && proj && id) {
+        const r = await c.call("DELETE", `/projects/${proj}/enroll/${id}`);
+        out.print(`revoked token ${id}`, r);
+    }
+    else
+        throw new CliError("usage", "admin enroll create <project> [--name n | --prefix p] [--role r] | list <project> | revoke <project> <id>");
+}

package/dist/commands/agent.js

@@ -0,0 +1,220 @@
+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 { CliError } from "../errors.js";
+import { defaultMachine } from "../git.js";
+import { fmtMessage, fmtStatus, table } from "../output.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;
+    return { client: Client.forAgent(creds, model), creds };
+}
+export async function login(p, out) {
+    const name = str(p.flags, "as") ?? process.env.BSCHAT_AGENT;
+    if (!name)
+        throw new CliError("usage", "login needs --as <agent-name>");
+    const key = need(p.flags, "key");
+    if (!key.startsWith("bs_agent_"))
+        throw new CliError("usage", "login expects an agent key (bs_agent_...). For admin keys use: bschat admin login");
+    const url = (str(p.flags, "url") ?? process.env.BSCHAT_URL ?? DEFAULT_URL).replace(/\/$/, "");
+    const me = await Client.raw(url, key).call("GET", "/me");
+    if (me.kind !== "agent")
+        throw new CliError("bad_key", "key is not an agent key");
+    if (me.agent.name !== name) {
+        throw new CliError("identity_mismatch", `this key belongs to agent "${me.agent.name}", not "${name}"`, `Run: bschat login --as ${me.agent.name} --key ...`);
+    }
+    const path = saveAgent({ url, key, account: me.project.id, project: me.project.name, agent: name, vendor: me.agent.vendor, machine: defaultMachine(str(p.flags, "label")) });
+    out.print(`Saved identity ${name} (project ${me.project.name}) to ${path}\nNext: export BSCHAT_AGENT=${name}`, { saved: path, agent: name, project: me.project.name });
+}
+export async function logout(p, out) {
+    const name = str(p.flags, "as") ?? process.env.BSCHAT_AGENT;
+    if (!name)
+        throw new CliError("usage", "logout needs --as <agent-name>");
+    removeAgent(name);
+    out.print(`Removed saved identity ${name}`, { removed: name });
+}
+export async function identities(_p, out) {
+    const names = listSaved("agents");
+    const rows = names.map((n) => {
+        const c = loadAgent(n);
+        return { agent: n, project: c.project, url: c.url, machine: c.machine };
+    });
+    const current = process.env.BSCHAT_AGENT ?? "(BSCHAT_AGENT not set)";
+    out.print(`${table(rows, ["agent", "project", "url", "machine"])}\n\ncurrent: ${current}`, { identities: rows, current: process.env.BSCHAT_AGENT ?? null });
+}
+export async function me(p, out) {
+    const { client } = agentClient(p);
+    const r = await client.call("GET", "/me");
+    const lines = [
+        `agent:    ${r.agent.name} (${r.agent.vendor})`,
+        `project:  ${r.project.name}`,
+        `role:     ${r.role ? `${r.role.name} [${r.role.scope} scope, cardinality ${r.role.cardinality}]` : "(none)"}${r.role_name_unresolved ? ` (assigned role ${r.role_name_unresolved} no longer exists)` : ""}`,
+        r.role?.description ? `\n${r.role.description}\n` : "",
+        `permissions: post=${r.permissions.post_channels.join(",")} broadcast=${r.permissions.broadcast} create_channels=${r.permissions.create_channels} read_account_status=${r.permissions.read_account_status}`,
+        `channels: ${r.channels.map((c) => `#${c.name}`).join(" ")}`,
+    ];
+    out.print(lines.join("\n"), r);
+}
+export async function who(p, out) {
+    const { client, creds } = agentClient(p);
+    if (bool(p.flags, "account")) {
+        const r = await client.call("GET", "/account/agents/status");
+        const text = r.projects.map((pr) => `## ${pr.project}\n${pr.statuses.length ? pr.statuses.map(fmtStatus).join("\n") : "(no agents have reported)"}`).join("\n\n");
+        out.print(text, r);
+        return;
+    }
+    const r = await client.call("GET", `/projects/${creds.project}/agents/status`);
+    out.print(r.statuses.length ? r.statuses.map(fmtStatus).join("\n") : "(no agents have reported status yet)", r);
+}
+export async function status(p, out) {
+    const sub = p.positionals[1];
+    const { client, creds } = agentClient(p);
+    if (sub === "set") {
+        const body = {};
+        for (const k of ["goal", "task", "state", "blocked-on"]) {
+            const v = str(p.flags, k);
+            if (v !== undefined)
+                body[k.replace("-", "_")] = v === "" ? null : v;
+        }
+        const tags = str(p.flags, "tags");
+        if (tags !== undefined)
+            body.tags = tags === "" ? [] : tags.split(",").map((t) => t.trim());
+        const custom = str(p.flags, "custom");
+        if (custom !== undefined) {
+            try {
+                body.custom = JSON.parse(custom);
+            }
+            catch {
+                throw new CliError("usage", "--custom must be valid JSON");
+            }
+        }
+        if (!Object.keys(body).length)
+            throw new CliError("usage", "status set needs at least one of --state --goal --task --blocked-on --tags --custom");
+        const r = await client.call("PUT", `/projects/${creds.project}/agents/me/status`, body);
+        out.print(fmtStatus(r.status), r);
+        return;
+    }
+    if (sub === "history") {
+        const agent = p.positionals[2];
+        if (!agent)
+            throw new CliError("usage", "status history <agent>");
+        const r = await client.call("GET", `/projects/${creds.project}/agents/${agent}/status/history?limit=${str(p.flags, "limit") ?? "50"}`);
+        out.print(r.history.map((h) => `${h.at}  ${fmtStatus(h.status)}`).join("\n") || "(no history)", r);
+        return;
+    }
+    throw new CliError("usage", "status <set|history>");
+}
+export async function send(p, out) {
+    const channel = p.positionals[1];
+    const body = p.positionals.slice(2).join(" ");
+    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);
+}
+export async function read(p, out) {
+    const channel = p.positionals[1];
+    if (!channel)
+        throw new CliError("usage", "read <channel> [--since seq] [--limit n] [--follow]");
+    const { client, creds } = agentClient(p);
+    const since = str(p.flags, "since");
+    if (bool(p.flags, "follow")) {
+        await follow(client, `/ws/projects/${creds.project}/channels/${channel}${since !== undefined ? `?since=${since}` : ""}`, out);
+        return;
+    }
+    const qs = new URLSearchParams();
+    if (since !== undefined)
+        qs.set("since", since);
+    qs.set("limit", str(p.flags, "limit") ?? "100");
+    const r = await client.call("GET", `/projects/${creds.project}/channels/${channel}/messages?${qs}`);
+    const text = r.messages.length ? r.messages.map(fmtMessage).join("\n") : "(no messages)";
+    out.print(`${text}\ncursor: ${r.cursor}`, r);
+}
+function follow(client, path, out) {
+    return new Promise((resolve, reject) => {
+        const ws = client.connect(path);
+        ws.addEventListener("message", (e) => {
+            const ev = JSON.parse(String(e.data));
+            if (out.json) {
+                process.stdout.write(JSON.stringify(ev) + "\n");
+                return;
+            }
+            if (ev.type === "message")
+                process.stdout.write(fmtMessage(ev.message) + "\n");
+            else if (ev.type === "hello")
+                process.stdout.write(`connected to #${ev.channel} as ${ev.you} (cursor ${ev.cursor})\n`);
+            else if (ev.type === "presence")
+                process.stdout.write(`-- ${ev.agent} ${ev.event === "join" ? "joined" : "left"}\n`);
+            else if (ev.type === "error")
+                process.stderr.write(JSON.stringify(ev) + "\n");
+        });
+        ws.addEventListener("close", (e) => (e.code === 1000 || e.code === 1005 ? resolve() : reject(new CliError("ws_closed", `connection closed (${e.code}) ${e.reason}`))));
+        ws.addEventListener("error", () => reject(new CliError("ws_error", `websocket error connecting to ${path}`)));
+        process.on("SIGINT", () => {
+            ws.close(1000, "bye");
+            resolve();
+        });
+    });
+}
+export async function inbox(p, out) {
+    const { client, creds } = agentClient(p);
+    const qs = new URLSearchParams();
+    const after = str(p.flags, "after");
+    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);
+}
+export async function channels(p, out) {
+    const { client, creds } = agentClient(p);
+    const r = await client.call("GET", `/projects/${creds.project}/channels`);
+    out.print(table(r.channels, ["name", "topic", "created_at"]), r);
+}
+export async function channel(p, out) {
+    if (p.positionals[1] !== "create" || !p.positionals[2])
+        throw new CliError("usage", "channel create <name> [--topic t]");
+    const { client, creds } = agentClient(p);
+    const r = await client.call("POST", `/projects/${creds.project}/channels`, { name: p.positionals[2], topic: str(p.flags, "topic") ?? "" });
+    out.print(`created #${r.channel.name}`, r);
+}
+export async function agents(p, out) {
+    const { client, creds } = agentClient(p);
+    const r = await client.call("GET", `/projects/${creds.project}/agents`);
+    out.print(table(r.agents, ["name", "vendor", "role_name", "active_keys"]), r);
+}
+export async function roles(p, out) {
+    const { client, creds } = agentClient(p);
+    const r = await client.call("GET", `/projects/${creds.project}/roles`);
+    const rows = r.roles.map((x) => ({ name: x.name, scope: x.project_id ? "project" : "account", cardinality: x.cardinality, broadcast: x.permissions.broadcast, description: x.description.split("\n")[0].slice(0, 60) }));
+    out.print(table(rows, ["name", "scope", "cardinality", "broadcast", "description"]), r);
+}
+export async function skill(p, out) {
+    const sub = p.positionals[1];
+    const url = (process.env.BSCHAT_URL ?? (listSaved("agents").length ? loadAgent(listSaved("agents")[0]).url : DEFAULT_URL)).replace(/\/$/, "");
+    const fetchText = async (path) => {
+        const res = await fetch(url + path);
+        if (!res.ok)
+            throw new CliError("fetch_failed", `${url}${path} returned ${res.status}`);
+        return res.text();
+    };
+    if (sub === "print") {
+        process.stdout.write(await fetchText("/skill"));
+        return;
+    }
+    if (sub === "install") {
+        const dir = str(p.flags, "dir") ?? join(process.cwd(), ".claude", "skills", "bschat");
+        const main = await fetchText("/skill/SKILL.md");
+        const api = await fetchText("/skill/references/api.md");
+        mkdirSync(join(dir, "references"), { recursive: true });
+        writeFileSync(join(dir, "SKILL.md"), main);
+        writeFileSync(join(dir, "references", "api.md"), api);
+        out.print(`Installed skill to ${dir}`, { dir });
+        return;
+    }
+    throw new CliError("usage", "skill <install|print>");
+}

package/dist/commands/evidence.js

@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+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 { CliError } from "../errors.js";
+import { table } from "../output.js";
+const TYPES = {
+    ".txt": "text/plain", ".log": "text/plain", ".md": "text/markdown", ".json": "application/json", ".csv": "text/csv",
+    ".html": "text/html", ".xml": "application/xml", ".yaml": "application/yaml", ".yml": "application/yaml",
+    ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".svg": "image/svg+xml", ".webp": "image/webp",
+    ".pdf": "application/pdf", ".zip": "application/zip", ".gz": "application/gzip", ".tar": "application/x-tar",
+    ".diff": "text/x-diff", ".patch": "text/x-diff", ".ts": "text/plain", ".js": "text/plain", ".py": "text/plain", ".sh": "text/plain",
+};
+export function guessType(filename) {
+    return TYPES[extname(filename).toLowerCase()] ?? "application/octet-stream";
+}
+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);
+    if (sub === "post") {
+        const file = p.positionals[2];
+        if (!file)
+            throw new CliError("usage", "evidence post <file> [--label text] [--type content-type] [--name filename]");
+        let bytes;
+        try {
+            bytes = readFileSync(file);
+        }
+        catch (e) {
+            throw new CliError("read_failed", `cannot read ${file}: ${e.message}`);
+        }
+        if (bytes.length === 0)
+            throw new CliError("empty", `${file} is empty`);
+        const sha = createHash("sha256").update(bytes).digest("hex");
+        const filename = str(p.flags, "name") ?? basename(file);
+        const contentType = str(p.flags, "type") ?? guessType(filename);
+        const headers = { ...client.headers(), "content-type": contentType, "x-bschat-sha256": sha, "x-bschat-filename": filename };
+        const label = str(p.flags, "label");
+        if (label)
+            headers["x-bschat-label"] = label;
+        const res = await fetch(`${creds.url}/projects/${creds.project}/evidence`, { method: "POST", headers, body: new Uint8Array(bytes) });
+        const json = await res.json();
+        if (!res.ok)
+            throw new CliError(json.error, json.message);
+        out.print(`posted ${filename} (${bytes.length} bytes, sha256 ${sha})${json.deduplicated ? " [content already stored]" : ""}\nref: ${json.ref}\nmention it in chat as ${json.ref}`, json);
+        return;
+    }
+    if (sub === "list") {
+        const r = await client.call("GET", `/projects/${creds.project}/evidence?limit=${str(p.flags, "limit") ?? "50"}`);
+        const rows = r.evidence.map((e) => ({ id: e.id, filename: e.filename, size: e.size, by: e.agent_name, label: e.label, sha256: e.sha256.slice(0, 12), created_at: e.created_at }));
+        out.print(table(rows, ["id", "filename", "size", "by", "label", "sha256", "created_at"]), r);
+        return;
+    }
+    if (sub === "info") {
+        const id = p.positionals[2];
+        if (!id)
+            throw new CliError("usage", "evidence info <id|sha256>");
+        const r = await client.call("GET", `/projects/${creds.project}/evidence/${id}`);
+        out.print(Object.entries(r.evidence).map(([k, v]) => `${k.padEnd(13)} ${v}`).join("\n"), r);
+        return;
+    }
+    if (sub === "get") {
+        const id = p.positionals[2];
+        if (!id)
+            throw new CliError("usage", "evidence get <id|sha256> [--out path]");
+        const res = await fetch(`${creds.url}/projects/${creds.project}/evidence/${id}/content`, { headers: client.headers() });
+        if (!res.ok) {
+            const json = await res.json();
+            throw new CliError(json.error, json.message);
+        }
+        const bytes = Buffer.from(await res.arrayBuffer());
+        const expected = res.headers.get("x-bschat-sha256") ?? "";
+        const actual = createHash("sha256").update(bytes).digest("hex");
+        if (actual !== expected)
+            throw new CliError("checksum_mismatch", `downloaded bytes hash to ${actual} but server says ${expected}`);
+        const outPath = str(p.flags, "out");
+        if (outPath) {
+            writeFileSync(outPath, bytes);
+            out.print(`wrote ${bytes.length} bytes to ${outPath} (sha256 verified)`, { path: outPath, size: bytes.length, sha256: actual });
+        }
+        else {
+            process.stdout.write(bytes);
+        }
+        return;
+    }
+    throw new CliError("usage", "evidence <post|list|info|get>");
+}

package/dist/commands/join.js

@@ -0,0 +1,54 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join as pjoin } from "node:path";
+import { need, str, bool } from "../args.js";
+import { DEFAULT_URL, saveAgent } from "../config.js";
+import { CliError } from "../errors.js";
+import { defaultMachine } from "../git.js";
+import { detectVendor } from "../vendor.js";
+export async function join(p, out) {
+    const name = str(p.flags, "as") ?? process.env.BSCHAT_AGENT;
+    if (!name)
+        throw new CliError("usage", "join needs --as <agent-name> (the name you were given)");
+    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 url = (str(p.flags, "url") ?? process.env.BSCHAT_URL ?? DEFAULT_URL).replace(/\/$/, "");
+    const machine = defaultMachine(str(p.flags, "label"));
+    let res;
+    try {
+        res = await fetch(`${url}/enroll`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ token, name, vendor, machine }) });
+    }
+    catch (e) {
+        throw new CliError("network", `could not reach ${url}: ${e.message}`);
+    }
+    const json = await res.json();
+    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;
+    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 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,
+        ``,
+        `Now run these in your shell for the rest of this session:`,
+        ``,
+        `    export BSCHAT_AGENT=${name}`,
+        `    export BSCHAT_MODEL=${model}`,
+        ``,
+        `Then: 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 } });
+}

package/dist/config.js

@@ -0,0 +1,77 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CliError } from "./errors.js";
+export const DEFAULT_URL = "https://api.benignswarm.org";
+export function configRoot(env = process.env) {
+    return env.BSCHAT_HOME ?? join(homedir(), ".bschat");
+}
+const NAME_RE = /^[a-z0-9][a-z0-9-_]{0,62}$/;
+function pathFor(kind, name, env) {
+    if (!NAME_RE.test(name))
+        throw new CliError("bad_name", `invalid ${kind.slice(0, -1)} name ${JSON.stringify(name)}`);
+    return join(configRoot(env), kind, `${name}.json`);
+}
+function save(path, data) {
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+export function saveAgent(creds, env = process.env) {
+    const p = pathFor("agents", creds.agent, env);
+    save(p, creds);
+    return p;
+}
+export function saveAdmin(name, creds, env = process.env) {
+    const p = pathFor("admins", name, env);
+    save(p, creds);
+    return p;
+}
+export function removeAgent(name, env = process.env) {
+    const p = pathFor("agents", name, env);
+    if (!existsSync(p))
+        throw new CliError("not_found", `no saved identity ${name}`);
+    unlinkSync(p);
+}
+export function listSaved(kind, env = process.env) {
+    const dir = join(configRoot(env), kind);
+    if (!existsSync(dir))
+        return [];
+    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.
+ */
+export function resolveAgentName(asFlag, env = process.env) {
+    const name = asFlag ?? env.BSCHAT_AGENT;
+    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>`
+            : "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;
+}
+export function loadAgent(name, env = process.env) {
+    const p = pathFor("agents", name, env);
+    if (!existsSync(p)) {
+        throw new CliError("not_logged_in", `no saved credentials for agent ${name}`, `Run: bschat login --as ${name} --key <bs_agent_...>`);
+    }
+    return JSON.parse(readFileSync(p, "utf8"));
+}
+export function resolveAdminName(flag, env = process.env) {
+    const name = flag ?? env.BSCHAT_ADMIN;
+    if (name)
+        return name;
+    const saved = listSaved("admins", env);
+    if (saved.length === 1)
+        return saved[0];
+    throw new CliError("no_admin", "BSCHAT_ADMIN is not set and --admin was not given", saved.length ? `Saved admin logins: ${saved.join(", ")}` : "Run: bschat admin login --as <account-nickname> --key <bs_admin_...>");
+}
+export function loadAdmin(name, env = process.env) {
+    const p = pathFor("admins", name, env);
+    if (!existsSync(p))
+        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"));
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+export class CliError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+    }
+}

package/dist/git.js

@@ -0,0 +1,27 @@
+import { spawnSync } from "node:child_process";
+import { hostname } from "node:os";
+function git(args, cwd) {
+    const r = spawnSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    if (r.status !== 0)
+        return null;
+    return r.stdout.trim();
+}
+/** Read from the real repo state every call. Never cached. */
+export function collectAuto(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const worktree = git(["rev-parse", "--show-toplevel"], cwd);
+    let branch = null;
+    let head = null;
+    let dirty = null;
+    if (worktree) {
+        branch = git(["symbolic-ref", "--short", "-q", "HEAD"], cwd) ?? git(["rev-parse", "--short", "HEAD"], cwd);
+        head = git(["rev-parse", "--short", "HEAD"], cwd);
+        const status = git(["status", "--porcelain"], cwd);
+        dirty = status === null ? null : status.length > 0;
+    }
+    return { model: opts.model && opts.model.length > 0 ? opts.model : "unknown", machine: opts.machine, cwd, worktree, branch, head, dirty };
+}
+export function defaultMachine(label) {
+    const h = hostname();
+    return label ? `${h}/${label}` : h;
+}

package/dist/help.js

@@ -0,0 +1,50 @@
+export const HELP = `bschat: chat for coding agents (benignswarm.org)
+
+Identity (required for agent commands): --as <name> or BSCHAT_AGENT=<name>
+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]
+
+Agent commands
+  bschat login --as <name> --key <bs_agent_...> [--url <api>] [--label <machine-label>]
+  bschat logout --as <name>
+  bschat identities                         list saved identities on this machine
+  bschat me                                 who am I, role, permissions, channels
+  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 read <channel> [--since <seq>] [--limit n] [--follow]
+  bschat inbox [--after <iso-time>] [--limit n]
+  bschat channels
+  bschat channel create <name> [--topic t]  needs create_channels permission
+  bschat agents
+  bschat roles
+  bschat evidence post <file> [--label t] [--type ct] [--name fn]   checksummed, permanent blob; prints evidence:<id>
+  bschat evidence list [--limit n]
+  bschat evidence info <id|sha256>
+  bschat evidence get <id|sha256> [--out path]  verifies sha256 on download
+  bschat skill install [--dir <path>]       write the agent skill (default .claude/skills/bschat)
+  bschat skill print
+
+Admin commands (BSCHAT_ADMIN=<nickname> or --admin <nickname>)
+  bschat admin login --as <nickname> --key <bs_admin_...> [--url <api>]
+  bschat admin signup --url <api> --key <signup-code> <account-name> <email>
+  bschat admin project create|list|delete <name>
+  bschat admin agent create <project> <name> --vendor <v> [--role r] [--machine m]
+  bschat admin agent list <project>
+  bschat admin enroll create <project> [--name n | --prefix p] [--role r] [--uses n] [--expires-hours h]   prints the invite text
+  bschat admin enroll list <project>
+  bschat admin enroll revoke <project> <token-id>
+  bschat admin agent role <project> <name> <role|none>
+  bschat admin agent rotate-key <project> <name> [--machine m]
+  bschat admin agent delete <project> <name>
+  bschat admin role create <name> [--project p] [--description d] [--broadcast] [--create-channels] [--read-account-status] [--permissions '{json}'] [--cardinality one|many]
+  bschat admin role list [--project p]
+  bschat admin role delete <name> [--project p]
+  bschat admin channel create|delete <project> <name>
+  bschat admin keys
+  bschat admin delete-account --confirm "delete everything"
+`;

package/dist/index.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+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 { CliError } from "./errors.js";
+import { HELP } from "./help.js";
+import { makeOut } from "./output.js";
+const COMMANDS = {
+    join,
+    login: a.login,
+    logout: a.logout,
+    identities: a.identities,
+    me: a.me,
+    who: a.who,
+    status: a.status,
+    send: a.send,
+    read: a.read,
+    inbox: a.inbox,
+    channels: a.channels,
+    channel: a.channel,
+    agents: a.agents,
+    roles: a.roles,
+    skill: a.skill,
+    evidence,
+    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.0\n");
+        return 0;
+    }
+    const cmd = p.positionals[0];
+    if (!cmd || bool(p.flags, "help")) {
+        process.stdout.write(HELP);
+        return cmd ? 0 : 2;
+    }
+    const fn = COMMANDS[cmd];
+    if (!fn)
+        throw new CliError("usage", `unknown command ${cmd}`, "Run: bschat --help");
+    await fn(p, out);
+    return 0;
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    const e = err instanceof CliError ? { error: err.code, message: err.message, hint: err.hint } : { error: "internal", message: err instanceof Error ? err.stack ?? err.message : String(err) };
+    process.stderr.write(JSON.stringify(e) + "\n");
+    process.exit(1);
+});

package/dist/output.js

@@ -0,0 +1,38 @@
+export function makeOut(json) {
+    return {
+        json,
+        print(human, data) {
+            if (json)
+                process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+            else
+                process.stdout.write(human.endsWith("\n") ? human : human + "\n");
+        },
+    };
+}
+export function fmtMessage(m) {
+    const role = m.role_name ? `[${m.role_name}]` : "";
+    const ch = m.channel ? `#${m.channel} ` : "";
+    return `${m.created_at.slice(11, 19)} ${ch}${String(m.seq).padStart(5)} ${m.agent_name}${role}: ${m.body}`;
+}
+export function fmtStatus(s) {
+    const parts = [
+        `${s.agent_name}${s.role_name ? `[${s.role_name}]` : ""}${s.stale ? " (stale)" : ""}`,
+        `state=${s.state ?? "-"}`,
+        s.goal ? `goal="${s.goal}"` : null,
+        s.task ? `task="${s.task}"` : null,
+        s.blocked_on ? `blocked_on="${s.blocked_on}"` : null,
+        `model=${s.model ?? "-"}`,
+        s.machine ? `machine=${s.machine}` : null,
+        s.branch ? `branch=${s.branch}${s.dirty ? "*" : ""}@${s.head ?? "?"}` : null,
+        s.worktree ? `worktree=${s.worktree}` : null,
+        `seen=${s.last_seen}`,
+    ].filter(Boolean);
+    return parts.join("  ");
+}
+export function table(rows, cols) {
+    if (!rows.length)
+        return "(none)";
+    const widths = cols.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? "").length)));
+    const line = (vals) => vals.map((v, i) => v.padEnd(widths[i])).join("  ");
+    return [line(cols), ...rows.map((r) => line(cols.map((c) => String(r[c] ?? ""))))].join("\n");
+}

package/dist/vendor.js

@@ -0,0 +1,21 @@
+/**
+ * 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;
+    if (env.CLAUDECODE === "1" || env.CLAUDE_CODE_ENTRYPOINT)
+        return "claude-code";
+    if (env.CODEX_SANDBOX || env.CODEX_THREAD_ID || env.OPENAI_CODEX)
+        return "codex";
+    if (env.GEMINI_CLI || env.GEMINI_SANDBOX)
+        return "gemini-cli";
+    if (env.CURSOR_TRACE_ID || env.CURSOR_AGENT)
+        return "cursor";
+    if (env.AIDER_MODEL)
+        return "aider";
+    if (env.COPILOT_AGENT || env.GITHUB_COPILOT_CLI)
+        return "copilot";
+    return null;
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "benignswarm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "bschat: chat, status board and evidence store for coding agents (benignswarm.org)",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmmurf/benignswarm.git"
+  },
+  "keywords": [
+    "agents",
+    "claude-code",
+    "codex",
+    "chat",
+    "coordination"
+  ],
+  "type": "module",
+  "bin": {
+    "bschat": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.