@eamonpluto/agentboard 2.2.0 → 2.4.0

package/opencode/plugins/dm-watch.js

@@ -23,7 +23,20 @@ const POLL_MS = 1000;
 
 function boardRoot(directory) {
   if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
-  return path.join(directory, ".agentboard");
+  return findBoardUpward(directory) || path.join(directory, ".agentboard");
+}
+
+// Nearest ancestor (incl. start) containing a .agentboard dir, or null.
+function findBoardUpward(start) {
+  let dir = path.resolve(start);
+  for (;;) {
+    try {
+      if (fs.statSync(path.join(dir, ".agentboard")).isDirectory()) return path.join(dir, ".agentboard");
+    } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
 }
 
 function readJsonSafe(p) {
@@ -138,17 +151,28 @@ export const DmWatchPlugin = async ({ client, directory }) => {
     return curIdx !== -1 && idx !== -1 && idx <= curIdx;
   }
 
+  function formatDm(msg) {
+    let head = "[DM from " + msg.from + " @ " + (msg.at || "unknown time");
+    if (msg.rev) head += ` (rev ${msg.rev})`;
+    if (msg.batch) head += ` [batch ${msg.batch}]`;
+    if (msg.replyTo) head += ` re: ${msg.replyTo}`;
+    head += "]";
+    const subj = msg.subject ? `subj: ${msg.subject}\n` : "";
+    return (
+      head +
+      "\n" +
+      subj +
+      msg.body +
+      "\n\n(Reply with dm-send (replyTo: \"" +
+      msg.id +
+      "\") if needed, or continue current work if unrelated. Re-read cited files vs your checkout before flagging — the rev above tells you if the sender's file:line numbers are stale.)"
+    );
+  }
+
   async function deliver(agent, sessionID, msg) {
     if (!claim(agent, msg.id, sessionID)) return;
     advanceCursor(agent, msg.id);
-    const text =
-      "[DM from " +
-      msg.from +
-      " @ " +
-      msg.at +
-      "]\n" +
-      msg.body +
-      "\n\n(Reply with dm-send if needed, or continue current work if unrelated.)";
+    const text = formatDm(msg);
     try {
       if (client.session && typeof client.session.promptAsync === "function") {
         await client.session.promptAsync({ path: { id: sessionID }, body: { parts: [{ type: "text", text }] } });
@@ -213,6 +237,10 @@ export const DmWatchPlugin = async ({ client, directory }) => {
           from: msg.from,
           body: String(msg.body),
           at: msg.at || "",
+          subject: msg.subject,
+          replyTo: msg.replyTo,
+          batch: msg.batch,
+          rev: msg.rev,
         });
       }
     }

package/opencode/tools/dm-send.js

@@ -4,13 +4,22 @@
 //
 // Usage from the agent (just a tool call, whenever you want):
 //   dm-send({ from: "alice", to: "bob", body: "the parser accepts ISO dates only" })
+//   dm-send({ from: "lead", to: "alice,bob,carol", subject: "brief: cards", body: "..." })
+//
+// Fanning out work ("assign N agents"): there is no task object — the DM *is*
+// the task. `to` accepts a comma list (one copy each, shared batch id); each
+// agent owns its scope and DMs a summary back. Thread answers with `replyTo`.
 //
 // What it does:
-//   1. resolves the board (AGENTBOARD_DIR env, else <worktree>/.agentboard)
-//   2. writes .agentboard/dm/<to>/<msg-id>.json (atomic write-then-rename)
+//   1. resolves the board (board arg, AGENTBOARD_DIR env, else walk-up from
+//      worktree/directory/cwd to the project .agentboard)
+//   2. writes .agentboard/dm/<to>/<msg-id>.json per recipient (atomic
+//      write-then-rename, unique id each, shared batch id on fan-out)
 //   3. upserts .agentboard/agents/<from>.json with { lastSeen, sessionId }
 //      so the watcher plugin can route pushes back to the right session.
-//   4. returns "sent <id> -> <to>" for the calling agent to see.
+//   4. stamps the sender's git rev (when inside a checkout) so recipients
+//      can tell whether cited file:line numbers are stale.
+//   5. returns "sent <id> -> <to> [board <path>]" for the calling agent.
 //
 // Delivery ("inserted into context") is done by ../plugins/dm-watch.js, which
 // polls dm/ and injects via client.session.promptAsync. This tool never blocks
@@ -20,10 +29,43 @@ import { tool } from "@opencode-ai/plugin";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { execFileSync } from "node:child_process";
 
-function boardRoot(worktree) {
-  if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
-  return path.join(worktree, ".agentboard");
+function findBoardUpward(start) {
+  let dir = path.resolve(start);
+  for (;;) {
+    try {
+      if (fs.statSync(path.join(dir, ".agentboard")).isDirectory()) return path.join(dir, ".agentboard");
+    } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// Try every base the harness gives us (worktree, directory, cwd): harnesses
+// sometimes run agents with a cwd below (or beside) the project, or with an
+// empty worktree. First walk-up hit wins; otherwise fall back to
+// <primary>/.agentboard so the caller gets the drive-root guard instead of a
+// silent stray board.
+function boardRoot(candidates, override) {
+  if (override) return { root: path.resolve(String(override)), tried: [path.resolve(String(override))] };
+  if (process.env.AGENTBOARD_DIR) return { root: path.resolve(process.env.AGENTBOARD_DIR), tried: [path.resolve(process.env.AGENTBOARD_DIR)] };
+  const tried = [];
+  for (const base of candidates) {
+    if (!base) continue;
+    let dir;
+    try {
+      dir = path.resolve(String(base));
+    } catch {
+      continue;
+    }
+    tried.push(dir);
+    const hit = findBoardUpward(dir);
+    if (hit) return { root: hit, tried };
+  }
+  const primary = path.resolve(String(candidates[0] || process.cwd()));
+  return { root: path.join(primary, ".agentboard"), tried };
 }
 
 function clean(name, what) {
@@ -33,40 +75,122 @@ function clean(name, what) {
   return c;
 }
 
+function parseRecipients(raw) {
+  if (raw === undefined || raw === null || String(raw).trim() === "") {
+    throw new Error("missing to (recipient); or comma-separate for broadcast: alice,bob,carol");
+  }
+  const out = [];
+  for (const part of String(raw).split(",")) {
+    if (part.trim() === "") continue;
+    const c = clean(part, "to");
+    if (!out.includes(c)) out.push(c);
+  }
+  if (out.length === 0) throw new Error("missing to (recipient)");
+  if (out.length > 20) throw new Error(`too many recipients (max 20, got ${out.length})`);
+  return out;
+}
+
+function cleanSubject(raw) {
+  if (raw === undefined || raw === null) return undefined;
+  const s = String(raw).trim().slice(0, 120);
+  return s || undefined;
+}
+
+function cleanReply(raw) {
+  if (raw === undefined || raw === null || String(raw).trim() === "") return undefined;
+  return String(raw).trim().slice(0, 80);
+}
+
+// Best-effort git rev of the project containing the board. Never throws.
+function gitRev(root) {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+      cwd: path.dirname(root),
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3000,
+    });
+    return String(out).trim().slice(0, 40) || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function writeJsonAtomic(p, obj) {
   fs.mkdirSync(path.dirname(p), { recursive: true });
-  const tmp = p + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
+  const tmp = p + "." + process.pid + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
   fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n");
-  fs.renameSync(tmp, p);
+  try {
+    fs.renameSync(tmp, p);
+  } catch (e) {
+    const start = Date.now();
+    while (Date.now() - start < 50) { /* brief spin for Windows AV holds */ }
+    try {
+      fs.renameSync(tmp, p);
+    } catch (e2) {
+      try { fs.rmSync(tmp, { force: true }); } catch {}
+      throw e2;
+    }
+  }
+}
+
+function newId(prefix) {
+  const t = new Date();
+  const stamp =
+    String(t.getUTCFullYear()).slice(2) +
+    String(t.getUTCMonth() + 1).padStart(2, "0") +
+    String(t.getUTCDate()).padStart(2, "0") +
+    "-" +
+    String(t.getUTCHours()).padStart(2, "0") +
+    String(t.getUTCMinutes()).padStart(2, "0") +
+    String(t.getUTCSeconds()).padStart(2, "0");
+  return `${prefix}-${stamp}-${crypto.randomBytes(4).toString("hex")}`;
 }
 
 export default tool({
   description:
-    "Send a direct message to another AI agent via agent-board. Use whenever you want to coordinate, share a finding, or ask a peer. Fire-and-forget like Slack — the peer's session gets it injected into context. Args: from (your stable agent name), to (peer's agent name), body (message text).",
+    "Send a direct message to another AI agent via agent-board. Use whenever you want to coordinate, share a finding, or ask a peer. Fire-and-forget like Slack — the peer's session gets it injected into context. `to` accepts a comma list (broadcast: one copy each, shared batch id) for fanning work out to N agents. Args: from (your stable agent name), to (peer's agent name), body (message text), subject (optional mission line), replyTo (optional msg id you are answering), board (optional absolute board path when your session runs outside the project).",
   args: {
     from: tool.schema.string().describe("Your stable agent name, e.g. alice. Keep it constant for the session."),
-    to: tool.schema.string().describe("Recipient agent name, e.g. bob. They receive it on inbox/listen even before registering."),
+    to: tool.schema.string().describe("Recipient agent name, e.g. bob — or comma list for broadcast: alice,bob,carol. They receive it on inbox/listen even before registering."),
     body: tool.schema.string().describe("Message text, 1..8000 chars."),
+    subject: tool.schema.string().optional().describe("Optional mission line, e.g. 'brief: borderless cards'. Shown above the body."),
+    replyTo: tool.schema.string().optional().describe("Optional message id you are answering (threads the reply)."),
+    board: tool.schema.string().optional().describe("Optional absolute board path, e.g. C:/proj/.agentboard. Overrides AGENTBOARD_DIR and auto-detection."),
   },
   async execute(args, context) {
     const from = clean(args.from, "from");
-    const to = clean(args.to, "to");
+    const recipients = parseRecipients(args.to);
     const body = String(args.body || "").trim();
     if (!body) return "error: empty body";
     if (body.length > 8000) return "error: body too large (max 8000 chars)";
-    const root = boardRoot(context.worktree || context.directory || process.cwd());
-    const now = new Date().toISOString();
-    const t = new Date();
-    const stamp =
-      String(t.getUTCFullYear()).slice(2) +
-      String(t.getUTCMonth() + 1).padStart(2, "0") +
-      String(t.getUTCDate()).padStart(2, "0") +
-      "-" +
-      String(t.getUTCHours()).padStart(2, "0") +
-      String(t.getUTCMinutes()).padStart(2, "0") +
-      String(t.getUTCSeconds()).padStart(2, "0");
-    const id = "msg-" + stamp + "-" + crypto.randomBytes(3).toString("hex");
-    writeJsonAtomic(path.join(root, "dm", to, id + ".json"), { id, from, to, body, at: now });
+    const subject = cleanSubject(args.subject);
+    const replyTo = cleanReply(args.replyTo);
+    const boardArg = args.board === undefined || args.board === null || String(args.board).trim() === "" ? undefined : String(args.board);
+    const worktree = context.worktree || context.directory || process.cwd();
+    const { root, tried } = boardRoot([worktree, context.directory, process.cwd()], boardArg);
+    if (!boardArg && !process.env.AGENTBOARD_DIR) {
+      let exists = false;
+      try {
+        exists = fs.statSync(root).isDirectory();
+      } catch {}
+      if (!exists && path.dirname(root) === path.parse(root).root) {
+        return `error: refusing to create a board at drive root ${root} — no project board found. Tried walk-up from: ${tried.join(" | ") || "(nothing)"}. Run from your project (the dir containing .agentboard/), pass board (absolute path to .agentboard), or set AGENTBOARD_DIR.`;
+      }
+    }
+    const rev = gitRev(root);
+    const at = new Date().toISOString();
+    const batch = recipients.length > 1 ? newId("batch") : undefined;
+    const sent = [];
+    for (const to of recipients) {
+      const id = newId("msg");
+      const msg = { id, from, to, body, at };
+      if (subject) msg.subject = subject;
+      if (replyTo) msg.replyTo = replyTo;
+      if (batch) msg.batch = batch;
+      if (rev) msg.rev = rev;
+      writeJsonAtomic(path.join(root, "dm", to, id + ".json"), msg);
+      sent.push(`${id} -> ${to}`);
+    }
     // upsert sender with live session routing for the watcher plugin
     const ap = path.join(root, "agents", from + ".json");
     let prev = null;
@@ -75,11 +199,12 @@ export default tool({
     } catch {}
     writeJsonAtomic(ap, {
       name: from,
-      firstSeen: (prev && prev.firstSeen) || now,
-      lastSeen: now,
+      firstSeen: (prev && prev.firstSeen) || new Date().toISOString(),
+      lastSeen: new Date().toISOString(),
       sessionId: (context && context.sessionID) || (prev && prev.sessionId) || undefined,
       lastDir: context.worktree || context.directory || undefined,
     });
-    return "sent " + id + " -> " + to;
+    if (sent.length === 1) return "sent " + sent[0] + " [board " + root + "]";
+    return `sent ${sent.length} messages [board ${root}]: ${sent.join(", ")}`;
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eamonpluto/agentboard",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Zero-dependency local DM bus for AI coding agents: message another agent, inserted into context, just a tool call.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "bin/",
     "opencode/",
     "AGENTS.template.md",
+    "AGENTBOARD.html",
     "README.md",
     "CHANGELOG.md"
   ],