@eamonpluto/agentboard 2.2.0 → 2.4.0

package/bin/agentboard-mcp.js

@@ -27,18 +27,33 @@ import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import readline from "node:readline";
+import { execFileSync } from "node:child_process";
 
 const MAX_BODY_CHARS = 8000;
-const SERVER_VERSION = "2.1.0";
+const SERVER_VERSION = "2.2.0";
 const KNOWN_PROTOCOL_VERSIONS = new Set(["2024-11-05", "2025-03-26", "2025-06-18"]);
 
 // ---------------------------------------------------------------------------
 // board (mirrors bin/agentboard.js layout v2; no import to stay dep-free)
 // ---------------------------------------------------------------------------
 
-function boardRoot() {
+function boardRoot(override) {
+  if (override) return path.resolve(String(override));
   if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
-  return path.join(process.cwd(), ".agentboard");
+  return findBoardUpward(process.cwd()) || path.join(process.cwd(), ".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 dirs(root) {
@@ -68,9 +83,49 @@ function readJson(p) {
 }
 
 function writeJson(p, obj) {
-  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;
+    }
+  }
+}
+
+// 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 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 = cleanName(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 cleanName(name, what) {
@@ -91,7 +146,7 @@ function newId(prefix) {
     String(t.getUTCHours()).padStart(2, "0") +
     String(t.getUTCMinutes()).padStart(2, "0") +
     String(t.getUTCSeconds()).padStart(2, "0");
-  return `${prefix}-${stamp}-${crypto.randomBytes(3).toString("hex")}`;
+  return `${prefix}-${stamp}-${crypto.randomBytes(4).toString("hex")}`;
 }
 
 function listDMs(d, recipient) {
@@ -136,13 +191,16 @@ const TOOLS = [
   {
     name: "dm_send",
     description:
-      "Send a direct message to another AI agent via agent-board. Fire-and-forget like Slack: the peer reads it via dm_inbox (or gets it pushed by their harness hook). Use whenever you want to coordinate, share a finding, or ask a peer.",
+      "Send a direct message to another AI agent via agent-board. Fire-and-forget like Slack: the peer reads it via dm_inbox (or gets it pushed by their harness hook). `to` accepts a comma list for broadcast (one copy each, shared batch id) to fan work out to N agents — the DM is the task. Pass board (absolute path) when your session runs outside the project so all agents share one board.",
     inputSchema: {
       type: "object",
       properties: {
         from: { type: "string", description: "Your stable agent name, e.g. alice. Keep it constant for the session." },
-        to: { type: "string", description: "Recipient agent name, e.g. bob." },
+        to: { type: "string", description: "Recipient agent name, e.g. bob — or comma list for broadcast: alice,bob,carol." },
         body: { type: "string", description: "Message text, 1..8000 chars." },
+        subject: { type: "string", description: "Optional mission line, e.g. 'brief: borderless cards'. Shown above the body." },
+        replyTo: { type: "string", description: "Optional message id you are answering (threads the reply)." },
+        board: { type: "string", description: "Optional absolute board path, e.g. C:/proj/.agentboard. Overrides AGENTBOARD_DIR and auto-detection." },
       },
       required: ["from", "to", "body"],
     },
@@ -150,31 +208,38 @@ const TOOLS = [
   {
     name: "dm_inbox",
     description:
-      "Read your direct messages on agent-board. No mark-read side effects; page with after. Poll this often when your harness has no push hook.",
+      "Read your direct messages on agent-board. No mark-read side effects; page with after. Poll this often when your harness has no push hook. Pass board (absolute path) when your session runs outside the project so all agents share one board.",
     inputSchema: {
       type: "object",
       properties: {
         agent: { type: "string", description: "Your agent name." },
         limit: { type: "number", description: "Max messages, newest last. Default 20." },
         after: { type: "string", description: "Only messages after this message id." },
+        board: { type: "string", description: "Optional absolute board path, e.g. C:/proj/.agentboard. Overrides AGENTBOARD_DIR and auto-detection." },
       },
       required: ["agent"],
     },
   },
   {
     name: "dm_agents",
-    description: "List agents known to this agent-board (registered names for addressing DMs).",
-    inputSchema: { type: "object", properties: {} },
+    description: "List agents known to this agent-board (registered names for addressing DMs). Pass board when your session runs outside the project.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        board: { type: "string", description: "Optional absolute board path. Overrides AGENTBOARD_DIR and auto-detection." },
+      },
+    },
   },
   {
     name: "dm_register",
     description:
-      "Register your agent name on this agent-board (optionally binding a harness session id for push routing). Do this once per session.",
+      "Register your agent name on this agent-board (optionally binding a harness session id for push routing). Do this once per session. Pass board when your session runs outside the project.",
     inputSchema: {
       type: "object",
       properties: {
         agent: { type: "string", description: "Your stable agent name." },
         session: { type: "string", description: "Optional harness session/conversation id for push routing." },
+        board: { type: "string", description: "Optional absolute board path. Overrides AGENTBOARD_DIR and auto-detection." },
       },
       required: ["agent"],
     },
@@ -185,24 +250,77 @@ function toolResult(text) {
   return { content: [{ type: "text", text }] };
 }
 
+function isDriveRootMissing(root, explicit) {
+  if (explicit) return false;
+  try {
+    if (fs.statSync(root).isDirectory()) return false;
+  } catch {}
+  return path.dirname(root) === path.parse(root).root;
+}
+
+// Read-side tools must never plant a board: without board.json, report the
+// resolved path so the caller spots the split-board instead of an empty room.
+function requireBoard(root) {
+  let meta = null;
+  try {
+    meta = readJson(path.join(root, "board.json"));
+  } catch {}
+  if (!meta || meta.version !== 2) {
+    throw new Error(
+      `no board at ${root} (cwd "${process.cwd()}"). Run from your project, pass board (absolute path to .agentboard), or set AGENTBOARD_DIR.`
+    );
+  }
+  return dirs(root);
+}
+
+function formatInbox(m) {
+  const bits = [`from ${m.from}`, `@ ${m.at || "unknown time"}`];
+  if (m.rev) bits.push(`rev ${m.rev}`);
+  if (m.replyTo) bits.push(`re: ${m.replyTo}`);
+  if (m.batch) bits.push(`batch ${m.batch}`);
+  return `[${m.id}] ${bits.join(" ")}${m.subject ? `\nsubj: ${m.subject}` : ""}\n${m.body}`;
+}
+
 function callTool(name, args) {
-  const d = ensureBoard(boardRoot());
   const a = args && typeof args === "object" ? args : {};
+  const boardArg = a.board === undefined || a.board === null || String(a.board).trim() === "" ? undefined : String(a.board);
+  const root = boardRoot(boardArg);
+  if (isDriveRootMissing(root, boardArg || process.env.AGENTBOARD_DIR)) {
+    throw new Error(
+      `refusing to create a board at drive root ${root} (cwd "${process.cwd()}") — no project board found above cwd. Pass board (absolute path to .agentboard) or set AGENTBOARD_DIR.`
+    );
+  }
   switch (name) {
     case "dm_send": {
+      const d = ensureBoard(root);
       const from = cleanName(a.from, "from");
-      const to = cleanName(a.to, "to");
+      const recipients = parseRecipients(a.to);
       const body = String(a.body ?? "").trim();
       if (!body) throw new Error("empty body");
       if (body.length > MAX_BODY_CHARS) throw new Error(`body too large (max ${MAX_BODY_CHARS} chars)`);
+      const subject = a.subject === undefined || a.subject === null || String(a.subject).trim() === "" ? undefined : String(a.subject).trim().slice(0, 120);
+      const replyTo = a.replyTo === undefined || a.replyTo === null || String(a.replyTo).trim() === "" ? undefined : String(a.replyTo).trim().slice(0, 80);
       touchAgent(d, from);
-      const id = newId("msg");
-      const msg = { id, from, to, body, at: new Date().toISOString() };
-      fs.mkdirSync(path.join(d.dm, to), { recursive: true });
-      writeJson(path.join(d.dm, to, `${id}.json`), msg);
-      return toolResult(`sent ${id} -> ${to}`);
+      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;
+        fs.mkdirSync(path.join(d.dm, to), { recursive: true });
+        writeJson(path.join(d.dm, to, `${id}.json`), msg);
+        sent.push(`${id} -> ${to}`);
+      }
+      if (sent.length === 1) return toolResult(`sent ${sent[0]} [board ${d.root}]`);
+      return toolResult(`sent ${sent.length} messages [board ${d.root}]: ${sent.join(", ")}`);
     }
     case "dm_inbox": {
+      const d = requireBoard(root);
       const agent = cleanName(a.agent, "agent");
       let items = listDMs(d, agent);
       if (a.after !== undefined && a.after !== null && String(a.after) !== "") {
@@ -212,12 +330,13 @@ function callTool(name, args) {
       const limit = a.limit === undefined || a.limit === null ? 20 : Number(a.limit);
       if (!(limit >= 0)) throw new Error("limit must be a non-negative number");
       items = items.slice(-limit);
-      if (items.length === 0) return toolResult(`no messages for ${agent}`);
-      return toolResult(items.map((m) => `[${m.id}] from ${m.from} @ ${m.at}\n${m.body}`).join("\n\n"));
+      if (items.length === 0) return toolResult(`no messages for ${agent} [board ${d.root}]`);
+      return toolResult(items.map(formatInbox).join("\n\n"));
     }
     case "dm_agents": {
+      const d = requireBoard(root);
       const dir = d.agents;
-      if (!fs.existsSync(dir)) return toolResult("no agents registered");
+      if (!fs.existsSync(dir)) return toolResult(`no agents registered [board ${d.root}]`);
       const names = fs
         .readdirSync(dir)
         .filter((f) => f.endsWith(".json"))
@@ -230,14 +349,15 @@ function callTool(name, args) {
         })
         .filter(Boolean)
         .sort();
-      if (names.length === 0) return toolResult("no agents registered (dm_register -- your name)");
-      return toolResult(names.join("\n"));
+      if (names.length === 0) return toolResult(`no agents registered (dm_register -- your name) [board ${d.root}]`);
+      return toolResult(names.join("\n") + `\n[board ${d.root}]`);
     }
     case "dm_register": {
+      const d = ensureBoard(root);
       const agent = cleanName(a.agent, "agent");
       const session = a.session === undefined || a.session === null ? undefined : String(a.session);
       touchAgent(d, agent, session || undefined);
-      return toolResult(`registered ${agent}${session ? ` (session ${session})` : ""}`);
+      return toolResult(`registered ${agent}${session ? ` (session ${session})` : ""} [board ${d.root}]`);
     }
     default:
       throw new Error(`unknown tool "${name}"`);