@eamonpluto/agentboard 2.3.0 → 2.4.1

package/opencode/plugins/dm-watch.js

@@ -12,6 +12,13 @@
 // mixing harnesses never get a message twice.
 // Polls every 1s; that poll is the source of truth (no fs.watch dependency).
 //
+// Delivery is at-least-once: the claim wins the race between watcher
+// instances, but the marker is released (and the cursor left alone) when
+// promptAsync throws — e.g. pushing into a stale session from yesterday
+// fails with `encrypted_content was not issued to this caller`. Stale
+// session mappings are then invalidated so mail waits for pull until the
+// live session re-registers, instead of being black-holed as delivered.
+//
 // Agents with no known session are skipped — their mail waits in the inbox
 // for pull (`inbox --from <you>`), so one idle session never steals another
 // agent's mail.
@@ -108,6 +115,40 @@ export const DmWatchPlugin = async ({ client, directory }) => {
     }
   }
 
+  // Roll back a claim won above when the push itself fails: remove the
+  // on-disk marker and the in-memory entry so the next poll retries.
+  // The cursor is intentionally left alone here — it only advances on
+  // success, so a failed push never fast-forwards past undelivered mail.
+  function releaseClaim(agent, id) {
+    processed.delete(agent + "/" + id);
+    try {
+      fs.rmSync(deliveredMarker(agent, id), { force: true });
+    } catch {}
+  }
+
+  // promptAsync into a dead session throws provider errors like
+  // "[invalid_request_error] reasoning `encrypted_content` was not issued
+  // to this caller". Those mean the routing entry is stale, not the
+  // message — drop the mapping so mail waits for pull (`inbox`) until the
+  // live session re-registers via `register --session` or `dm-send`.
+  function isStaleSessionError(e) {
+    const s = String((e && e.message ? e.message : e) || "");
+    return /encrypted_content|invalid_request_error|unknown session|session not found|no such session|not issued to this caller/i.test(s);
+  }
+
+  function invalidateSession(agent, sessionID) {
+    agentToSession.delete(agent);
+    try {
+      const p = path.join(agentsDir, agent + ".json");
+      const doc = readJsonSafe(p);
+      if (doc && doc.sessionId === sessionID) {
+        delete doc.sessionId;
+        doc.lastSeen = new Date().toISOString();
+        fs.writeFileSync(p, JSON.stringify(doc, null, 2) + "\n");
+      }
+    } catch {}
+  }
+
   // Cursor file shared with agentboard-hook: hook delivery moves it, and we
   // honor it (plus our markers) so mixed-harness agents never get doubles.
   // We also advance it on our own deliveries.
@@ -151,30 +192,44 @@ 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 }] } });
       } else if (client.session && typeof client.session.prompt === "function") {
         await client.session.prompt({ path: { id: sessionID }, body: { parts: [{ type: "text", text }] } });
       }
+      advanceCursor(agent, msg.id);
     } catch (e) {
+      const detail = e && e.message ? e.message : String(e);
+      releaseClaim(agent, msg.id);
+      if (isStaleSessionError(e)) invalidateSession(agent, sessionID);
       try {
         await client.app.log({
           body: {
             service: "dm-watch",
             level: "warn",
-            message: "DM wake failed for " + agent + ": " + (e && e.message ? e.message : String(e)),
+            message: "DM push failed for " + agent + " (" + msg.id + "), released for retry: " + detail,
           },
         });
       } catch {}
@@ -226,6 +281,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,17 +29,8 @@ 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, override) {
-  if (override) return path.resolve(String(override));
-  if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
-  const base = worktree || process.cwd();
-  return findBoardUpward(base) || path.join(base, ".agentboard");
-}
-
-// Nearest ancestor (incl. start) containing a .agentboard dir, or null.
-// Harnesses sometimes run agents with a cwd below (or beside) the project;
-// walk-up keeps every session on the same board.
 function findBoardUpward(start) {
   let dir = path.resolve(start);
   for (;;) {
@@ -43,6 +43,31 @@ function findBoardUpward(start) {
   }
 }
 
+// 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) {
   if (!name) throw new Error("missing " + what);
   const c = String(name).trim().replace(/[^A-Za-z0-9_.-]/g, "-").slice(0, 40);
@@ -50,51 +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), board (optional absolute board path when your session runs outside the project).",
+    "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 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 root = boardRoot(context.worktree || context.directory || process.cwd(), boardArg);
+    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} — pass board (absolute path) or set AGENTBOARD_DIR`;
+        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 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 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;
@@ -103,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 + " [board " + root + "]";
+    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.3.0",
+  "version": "2.4.1",
   "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"
   ],