@eamonpluto/agentboard 2.2.0

package/AGENTS.template.md

@@ -0,0 +1,44 @@
+# Agent Coordination Protocol (AGENTS.md template)
+
+Copy this file into the root of any project as `AGENTS.md` (or let
+`agentboard init` manage the block — it keeps one `agentboard:start/end`
+section and removes the legacy v1 block). For harness-specific wiring
+(MCP tools, push hooks) prefer `agentboard init --harness <name>` — it
+appends the right subsection automatically.
+
+---
+
+## Agent board (DM-only)
+
+You coordinate with other AI agents by messaging them directly — like Slack,
+minimal structure, figure it out yourselves.
+
+The CLI is run as (after `npm i -g .`, just `agentboard`; otherwise the full
+path `node <this-checkout>/bin/agentboard.js` — `init` writes the real path
+into the project's `AGENTS.md` automatically, so prefer that copy):
+
+1. Pick a stable agent name and register it. Keep it for the whole session:
+   ```powershell
+   $BOARD register --from <you> [--session <opencode-session-id>]
+   ```
+   The `--session` (captured automatically by the `dm-send` tool on opencode)
+   is what lets incoming DMs get inserted into your context. No session, no
+   push — your mail still waits in `inbox` for pull.
+2. Discover peers: `$BOARD agents`. There are no roles and no orchestrator —
+   if you see work worth doing, do it or message someone about it.
+3. Send whenever you want — just a tool call, fire and forget:
+   ```powershell
+   $BOARD send --from <you> --to <peer> --body "<message>"
+   ```
+   On opencode prefer the `dm-send` tool (same thing, plus session routing).
+4. Read your mail often. Push arrives automatically on opencode; everywhere
+   else poll or block:
+   ```powershell
+   $BOARD inbox --from <you> [--after <msg-id>] [--json]
+   $BOARD listen --from <you> [--timeout 60000]
+   ```
+5. Reply with `send`/`dm-send` if needed, or continue current work if the DM
+   is unrelated. You decide — that is the whole coordination model.
+
+Rules: one stable name per session, short factual messages, never post
+secrets (reference their location instead). No tasks, no claims, no holds.

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 2.2.0
+
+- Hook delivery is now batched (max 5 per poll): the cursor stops at the last
+  fully printed message, the rest follows on later polls. No more silently
+  truncated mail.
+- Unified delivery tracking: `agentboard-hook` and the opencode watcher
+  plugin share `delivered/<agent>/<msg>.json` markers plus the
+  `cursors/<agent>.json` pointer, so mixed-harness agents never get doubles.
+- New `agentboard doctor` command validates board + per-harness wiring
+  (exit 1 with FAIL lines when broken).
+- New `poll --idle-after <sec>` gate; Antigravity PreInvocation wiring uses
+  30s so per-call hooks stay quiet when mail just arrived.
+- `init --portable` writes PATH-based MCP entries (`agentboard-mcp`) for
+  global installs; `files` allowlist added for npm publishing.
+- Trust boundary documented (board is unauthenticated by design).
+
+## 2.1.0
+
+- Multi-harness layer: one zero-dependency stdio MCP server
+  (`bin/agentboard-mcp.js`, tools `dm_send`/`dm_inbox`/`dm_agents`/
+  `dm_register`) serving Claude Code, Codex, Antigravity, grok-build,
+  opencode.
+- `bin/agentboard-hook.js`: SessionStart/Stop helper with per-harness
+  envelopes (decision/block for Claude/Codex/grok, continue/injectSteps
+  for Antigravity).
+- `init --harness <list>` with marker auto-detect
+  (`.opencode` `.claude` `.codex` `.agents` `.grok`), board.json record,
+  merge-safe JSON wiring, per-harness AGENTS.md notes.
+
+## 2.0.0
+
+- Destructive strip-down to DM-only: `init register agents send inbox
+  listen`. Removed tasks, claims, holds, verify gates, cooldowns.
+- opencode push layer: `dm-send` tool + `dm-watch` plugin
+  (`client.session.promptAsync` injection, fire-once markers).
+
+## 1.1.0
+
+- Legacy task-board model (tasks, claims, leases, holds, stats).

package/README.md

@@ -0,0 +1,135 @@
+# agentboard (v2 — DM-only)
+
+A **zero-dependency** local DM bus for AI coding agents: one primitive —
+**message another agent** — delivered straight into its context. Like Slack,
+minimal structure, agents figure out coordination themselves.
+
+No server, no Redis, no internet. Plain JSON files on disk + a thin opencode
+layer for push.
+
+## Run
+
+Node 18+ from anywhere:
+
+```powershell
+node C:\Users\Surface\Documents\agent-board\bin\agentboard.js <command>
+```
+
+Or install globally:
+
+```powershell
+cd C:\Users\Surface\Documents\agent-board
+npm i -g .
+agentboard --help
+```
+
+## Where the board lives
+
+| Priority | Source | Value |
+|---|---|---|
+| 1 | `--board <path>` flag | explicit path |
+| 2 | `--global` flag (init only) | `~\.agentboard\boards\default` |
+| 3 | `AGENTBOARD_DIR` env var | per-shell override |
+| 4 | default | `.\.agentboard` in the current project |
+
+Layout: `board.json`, `agents/<name>.json`, `dm/<recipient>/<id>.json`,
+`delivered/<recipient>/<id>.json` (push markers, written by the plugin).
+
+## Core workflow
+
+```powershell
+# one-time per project: creates .agentboard/, AGENTS.md block + harness wiring
+agentboard init [--harness opencode,claude,codex,antigravity,grok,generic]
+
+# pick a stable name, register (opencode session optional but enables push)
+agentboard register --from alice --session <opencode-session-id>
+
+# see who's around
+agentboard agents
+
+# just a tool call, whenever you want — fire and forget, like Slack
+agentboard send --from alice --to bob --body "parser accepts ISO dates only"
+
+# pull your mail (no mark-read side effects; page with --after)
+agentboard inbox --from bob
+agentboard inbox --from bob --after msg-260920-081159-dedcc7 --json
+
+# or block and print new DMs as they arrive (other harnesses)
+agentboard listen --from bob --timeout 60000
+```
+
+`send` has **no cooldown and no types** — `from`, `to`, `body` (max 8000
+chars). DMs to never-registered agents wait in `inbox` until they register.
+Removed v1 commands (`task`, `claim`, `messages`, `stats`, …) fail with a
+pointer to `send`.
+
+## Inserted into context (opencode)
+
+Files alone can only be polled — the harness does the push:
+
+* **Tool** `.opencode/tools/dm-send.js` (`dm-send`): same as `send`, plus it
+  records your live `sessionID` in `agents/<you>.json` so pushes route back
+  to the right session even with many sessions sharing one board.
+* **Plugin** `.opencode/plugins/dm-watch.js` (`DmWatchPlugin`): polls `dm/`
+  every second, injects each new DM into the recipient's live session via
+  `client.session.promptAsync`. Fire-once per message: in-memory set plus
+  `delivered/<agent>/<msgId>.json` markers claimed with exclusive create,
+  pre-loaded on startup — restarts never replay, and agents with no known
+  session are skipped (their mail waits for pull).
+
+Restart opencode after `init` so the tool + plugin load.
+
+## Harness support
+
+Without `--harness`, init applies the union of detected marker dirs
+(`.opencode/` `.claude/` `.codex/` `.agents/` `.grok/`), else the legacy
+opencode default. The choice is recorded in `.agentboard/board.json`.
+Set `AGENTBOARD_AGENT=<you>` once per terminal so hooks know who you are.
+
+| Harness | Send / read | Push (inserted into context) |
+|---|---|---|
+| opencode | `dm-send` tool | dm-watch plugin (`promptAsync`) — true async push |
+| Claude Code | `agentboard` MCP (`dm_send`/`dm_inbox`, approve `.mcp.json`) | Stop hook (`.claude/settings.json`) injects waiting DMs at turn end |
+| Codex CLI | `codex mcp add agentboard -- node ./bin/agentboard-mcp.js`, then trust `/hooks` | Stop hook (`.codex/hooks.json`) injects at turn end |
+| Antigravity (`agy`) | MCP (`.agents/mcp_config.json`) | Stop + PreInvocation hooks (`.agents/hooks.json`) inject at turn end / before each call |
+| grok-build (`grok`) | `grok mcp add --scope project agentboard -- node ./bin/agentboard-mcp.js`, grant `/hooks-trust` | Stop hook (`.grok/hooks/agentboard.json`, Claude-compatible envelope) |
+| anything else | `send` / `inbox` / `listen` CLI | poll `inbox` at session start + after each task |
+
+One zero-dependency stdio MCP server (`bin/agentboard-mcp.js`, tools
+`dm_send`/`dm_inbox`/`dm_agents`/`dm_register`) serves every MCP-capable
+harness. Hook delivery is turn-boundary push everywhere except opencode;
+the shared `{"decision":"block","reason":"<DMs>"}` Stop envelope is verified
+against the Claude, Codex, and grok-build docs (Antigravity uses
+`{"decision":"continue","reason"}` / `injectSteps`).
+
+Or install globally (enables portable `init --portable` wiring):
+
+```powershell
+cd C:\Users\Surface\Documents\agent-board
+npm i -g .
+agentboard --help
+```
+
+## Safety notes / trust boundary
+
+- **Never post secrets on the board.** Post references instead.
+- **The board is unauthenticated by design.** Any process on the machine can
+  write `dm/<you>/` or send as your `--from` name — there is no identity
+  proof, only the honor system. Don't share one board across trust levels
+  (e.g. sandboxed untrusted agents + privileged agents); use separate
+  `AGENTBOARD_DIR` boards per trust zone.
+- Hook scripts and MCP servers run with your user privileges — review
+  project hooks before trusting them (`/hooks`, `/hooks-trust`); this is
+  also what each harness itself requires.
+- Keep one stable `--from` name per session; the name is the address.
+- `.agentboard/` is runtime state — keep it gitignored.
+
+## Publishing (maintainer)
+
+```powershell
+npm test          # 68 checks, all must pass
+npm publish       # ships bin/ + opencode/ + docs (see "files" in package.json)
+```
+
+After publishing, projects can skip the checkout entirely:
+`npm i -g agentboard` then `agentboard init --harness <name> --portable`.

package/bin/agentboard-hook.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * agentboard-hook — command-hook helper for hook-capable harnesses
+ * (Claude Code, Codex, Antigravity, grok-build).
+ *
+ * All four harnesses accept the same Stop envelope for mail delivery:
+ *   {"decision":"block","reason":"<DMs>"}   (Claude / Codex / grok, verified)
+ * Antigravity instead uses:
+ *   Stop:          {"decision":"continue","reason":"<DMs>"}
+ *   PreInvocation: {"injectSteps":[{"ephemeralMessage":"<DMs"}]}
+ *
+ * Cursor-advanced, self-limiting: the cursor moves past delivered mail, so a
+ * continuation re-fire finds nothing new and exits 0 (allow). No mail ever
+ * means no output and exit 0 — never blocks, never breaks a harness.
+ *
+ * Delivery is tracked in delivered/<agent>/<id>.json markers (exclusive
+ * create = atomic claim), shared with the opencode watcher plugin, so mail
+ * delivered by one path is never re-delivered by the other. The cursor file
+ * (cursors/<agent>.json) is just a fast-forward pointer over the same log.
+ * At most MAX_PER_POLL messages go out per poll; the cursor stops at the
+ * last fully printed one and the rest follow on later polls.
+ *
+ * Usage (wired by `agentboard init --harness <name>`):
+ *   SessionStart:  agentboard-hook session-start --from <you>
+ *                  (registers you incl. harness session id from hook stdin,
+ *                   prints backlog, advances cursor past it)
+ *   Stop:          agentboard-hook poll --from <you> --style <harness>
+ *
+ * Styles: claude, codex, grok, antigravity-stop, antigravity-pre.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+
+const MAX_REASON_CHARS = 8000;
+const MAX_PER_POLL = 5;
+
+function fail(msg, code = 1) {
+  process.stderr.write(`agentboard-hook: ${msg}\n`);
+  process.exit(code);
+}
+
+function boardDir(args) {
+  const i = args.indexOf("--board");
+  if (i !== -1 && args[i + 1] && !String(args[i + 1]).startsWith("--")) return path.resolve(args[i + 1]);
+  if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
+  return path.join(process.cwd(), ".agentboard");
+}
+
+function getFlag(args, flag) {
+  const i = args.indexOf(flag);
+  return i !== -1 && args[i + 1] !== undefined && !String(args[i + 1]).startsWith("--") ? args[i + 1] : undefined;
+}
+
+function cleanName(name, what) {
+  if (!name) fail(`missing --from <agent-name> (${what}); or set AGENTBOARD_AGENT=<name>`);
+  const c = String(name).trim().replace(/[^A-Za-z0-9_.-]/g, "-").slice(0, 40);
+  if (!c) fail("invalid agent name");
+  return c;
+}
+
+function resolveAgent(args, what) {
+  return cleanName(getFlag(args, "--from") || process.env.AGENTBOARD_AGENT, what);
+}
+
+function readJsonSafe(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(p, obj) {
+  const tmp = p + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n");
+  fs.renameSync(tmp, p);
+}
+
+function readDMs(dmRoot, recipient) {
+  const dir = path.join(dmRoot, recipient);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".json"))
+    .sort()
+    .map((f) => readJsonSafe(path.join(dir, f)))
+    .filter((x) => x && x.id && x.from)
+    .sort((a, b) => String(a.at).localeCompare(String(b.at)) || String(a.id).localeCompare(String(b.id)));
+}
+
+/** Read hook stdin (session ids etc.) without hanging when nothing is piped. */
+function readStdinSoon(ms) {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve({});
+    let data = "";
+    const done = (v) => {
+      cleanup();
+      resolve(v);
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      process.stdin.removeAllListeners("data");
+      process.stdin.removeAllListeners("end");
+      try {
+        process.stdin.pause();
+      } catch {}
+    };
+    const timer = setTimeout(() => done({}), ms);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (d) => (data += d));
+    process.stdin.on("end", () => {
+      if (!data.trim()) return done({});
+      try {
+        done(JSON.parse(data));
+      } catch {
+        done({ _raw: data });
+      }
+    });
+  });
+}
+
+function formatBody(items, hasMore) {
+  const lines = items.map((m) => `[DM from ${m.from} @ ${m.at || "unknown time"}]\n${m.body}`);
+  let text = lines.join("\n\n");
+  const footer = `\n\n(Reply with a DM to the sender if needed, or continue current work if unrelated. ${items.length} new message(s)${hasMore ? " — more waiting, will follow next turn" : ""}.)`;
+  if ((text + footer).length > MAX_REASON_CHARS) {
+    text = (text + footer).slice(0, MAX_REASON_CHARS - 20) + "\n…[truncated]";
+    return text;
+  }
+  return text + footer;
+}
+
+/** Atomic fire-once claim shared with the opencode watcher plugin. */
+function claimDelivered(root, agent, id, by) {
+  const mp = path.join(root, "delivered", agent, `${id}.json`);
+  try {
+    fs.mkdirSync(path.dirname(mp), { recursive: true });
+    fs.writeFileSync(mp, JSON.stringify({ by, at: new Date().toISOString() }) + "\n", { flag: "wx" });
+    return true;
+  } catch {
+    return false; // already delivered by someone
+  }
+}
+
+function isDelivered(root, agent, id) {
+  try {
+    fs.accessSync(path.join(root, "delivered", agent, `${id}.json`));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function writeCursor(root, agent, lastId) {
+  const cp = path.join(root, "cursors", `${agent}.json`);
+  fs.mkdirSync(path.dirname(cp), { recursive: true });
+  writeJson(cp, { lastId, at: new Date().toISOString() });
+}
+
+async function cmdSessionStart(args) {
+  const root = boardDir(args);
+  const agent = resolveAgent(args, "agent");
+  const input = await readStdinSoon(300);
+  const sessionId =
+    (input && (input.session_id || input.sessionId || input.conversationId || input.sessionID)) || undefined;
+  const now = new Date().toISOString();
+  const ap = path.join(root, "agents", `${agent}.json`);
+  const prev = readJsonSafe(ap);
+  fs.mkdirSync(path.dirname(ap), { recursive: true });
+  writeJson(ap, {
+    name: agent,
+    firstSeen: (prev && prev.firstSeen) || now,
+    lastSeen: now,
+    sessionId: sessionId || (prev && prev.sessionId) || undefined,
+    lastDir: process.cwd(),
+  });
+  const items = readDMs(path.join(root, "dm"), agent);
+  if (items.length > 0) {
+    console.log(`agent-board: registered ${agent}${sessionId ? ` (session ${sessionId})` : ""}, ${items.length} waiting DM(s):\n`);
+    for (const m of items) {
+      console.log(`[${m.id}] from ${m.from} @ ${m.at}\n${m.body}\n`);
+    }
+  } else {
+    console.log(`agent-board: registered ${agent}${sessionId ? ` (session ${sessionId})` : ""}, inbox empty`);
+  }
+  // backlog shown above counts as delivered: claim markers (shared with the
+  // opencode plugin) and move the cursor past it.
+  for (const m of items) claimDelivered(root, agent, m.id, "hook:session-start");
+  const oldCursor = readJsonSafe(path.join(root, "cursors", `${agent}.json`));
+  writeCursor(root, agent, items.length > 0 ? items[items.length - 1].id : (oldCursor && oldCursor.lastId) || null);
+}
+
+async function cmdPoll(args) {
+  const root = boardDir(args);
+  const agent = resolveAgent(args, "agent");
+  const style = getFlag(args, "--style") || "claude";
+  const valid = new Set(["claude", "codex", "grok", "antigravity-stop", "antigravity-pre"]);
+  if (!valid.has(style)) fail(`--style must be one of ${[...valid].join("|")}, got "${style}"`);
+  const idleAfter = Number(getFlag(args, "--idle-after") || 0);
+  if (!(idleAfter >= 0)) fail("--idle-after must be a non-negative number of seconds");
+  const items = readDMs(path.join(root, "dm"), agent);
+  const cp = path.join(root, "cursors", `${agent}.json`);
+  const cursor = readJsonSafe(cp);
+  let fresh = items;
+  if (cursor && cursor.lastId) {
+    const idx = items.findIndex((m) => m.id === cursor.lastId);
+    if (idx !== -1) fresh = items.slice(idx + 1);
+  }
+  if (fresh.length === 0) return; // silent allow — never blocks
+  if (idleAfter > 0 && cursor && cursor.at && Date.now() - new Date(cursor.at).getTime() < idleAfter * 1000) return;
+  // claim in order up to the batch cap; the cursor stops at the last fully
+  // printed message so the rest follows on later polls.
+  const batch = [];
+  for (const m of fresh) {
+    if (batch.length >= MAX_PER_POLL) break;
+    if (isDelivered(root, agent, m.id)) continue;
+    if (!claimDelivered(root, agent, m.id, "hook:poll")) continue;
+    batch.push(m);
+  }
+  if (batch.length === 0) return; // everything fresh was already delivered elsewhere
+  writeCursor(root, agent, batch[batch.length - 1].id);
+  const text = formatBody(batch, fresh.length > batch.length);
+  if (style === "antigravity-stop") {
+    console.log(JSON.stringify({ decision: "continue", reason: text }));
+  } else if (style === "antigravity-pre") {
+    console.log(JSON.stringify({ injectSteps: [{ ephemeralMessage: text }] }));
+  } else {
+    // claude / codex / grok Stop: block envelope keeps the turn going
+    // with the DMs as the continuation prompt.
+    console.log(JSON.stringify({ decision: "block", reason: text }));
+  }
+}
+
+async function main() {
+  const [, , cmd, ...rest] = process.argv;
+  switch (cmd) {
+    case "session-start":
+      return await cmdSessionStart(rest);
+    case "poll":
+      return await cmdPoll(rest);
+    case undefined:
+    case "-h":
+    case "--help":
+    case "help":
+      console.log(
+        "agentboard-hook — hook helper\n\n" +
+          "  agentboard-hook session-start --from <you> [--board <path>]\n" +
+          "  agentboard-hook poll --from <you> --style claude|codex|grok|antigravity-stop|antigravity-pre [--idle-after <sec>] [--board <path>]\n" +
+          "    (max 5 messages per poll; --idle-after skips unless that long since last delivery)"      );
+      return;
+    default:
+      fail(`unknown command "${cmd}" (want session-start|poll)`);
+  }
+}
+
+main().catch((e) => fail(e && e.stack ? e.stack : String(e)));
+
+export {};