@eamonpluto/agentboard 2.2.0

package/opencode/plugins/dm-watch.js

@@ -0,0 +1,233 @@
+// .opencode/plugins/dm-watch.js — inject DMs into context (agent-board DM-only v2).
+// Watches <board>/dm/<agent>/*.json and delivers new messages to the live
+// opencode session registered for <agent> via client.session.promptAsync.
+//
+// Routing: .agentboard/agents/<name>.json holds { sessionId }. The dm-send
+// tool writes it on every send; register --session writes it from the CLI.
+// Fire-once: in-memory Set + on-disk delivered/<agent>/<msgId>.json markers
+// claimed with exclusive create ('wx'), pre-populated on startup (survives
+// restarts, same idea as bgrun's .notify -> .notified rename). Markers are
+// shared with agentboard-hook, and the hook's cursors/<agent>.json fast-
+// forward pointer is honored (and advanced on our deliveries), so agents
+// mixing harnesses never get a message twice.
+// Polls every 1s; that poll is the source of truth (no fs.watch dependency).
+//
+// 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.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const POLL_MS = 1000;
+
+function boardRoot(directory) {
+  if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
+  return path.join(directory, ".agentboard");
+}
+
+function readJsonSafe(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export const DmWatchPlugin = async ({ client, directory }) => {
+  const root = boardRoot(directory);
+  const dmDir = path.join(root, "dm");
+  const agentsDir = path.join(root, "agents");
+  const deliveredDir = path.join(root, "delivered");
+
+  const agentToSession = new Map(); // agent -> sessionID
+  const processed = new Set(); // "<agent>/<msgId>"
+
+  try {
+    fs.mkdirSync(deliveredDir, { recursive: true });
+  } catch {}
+
+  // pre-populate from delivered markers so restarts don't replay
+  try {
+    for (const agent of fs.readdirSync(deliveredDir)) {
+      const ad = path.join(deliveredDir, agent);
+      try {
+        if (!fs.statSync(ad).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      for (const f of fs.readdirSync(ad)) {
+        if (f.endsWith(".json")) processed.add(agent + "/" + f.replace(/\.json$/, ""));
+      }
+    }
+  } catch {}
+
+  function refreshAgentMap() {
+    let files = [];
+    try {
+      files = fs.readdirSync(agentsDir);
+    } catch {
+      return;
+    }
+    for (const f of files) {
+      if (!f.endsWith(".json")) continue;
+      const doc = readJsonSafe(path.join(agentsDir, f));
+      if (doc && doc.name && doc.sessionId) agentToSession.set(doc.name, doc.sessionId);
+    }
+  }
+
+  function deliveredMarker(agent, id) {
+    return path.join(deliveredDir, agent, id + ".json");
+  }
+
+  function claim(agent, id, sessionID) {
+    const key = agent + "/" + id;
+    if (processed.has(key)) return false;
+    processed.add(key);
+    try {
+      fs.mkdirSync(path.dirname(deliveredMarker(agent, id)), { recursive: true });
+      fs.writeFileSync(deliveredMarker(agent, id), JSON.stringify({ sessionID, at: new Date().toISOString() }) + "\n", {
+        flag: "wx",
+      });
+      return true;
+    } catch {
+      return false; // already delivered by another instance
+    }
+  }
+
+  // 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.
+  function readCursor(agent) {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(root, "cursors", agent + ".json"), "utf8"));
+    } catch {
+      return null;
+    }
+  }
+
+  function orderIds(agent) {
+    try {
+      return fs.readdirSync(path.join(dmDir, agent)).filter((f) => f.endsWith(".json")).sort().map((f) => f.replace(/\.json$/, ""));
+    } catch {
+      return [];
+    }
+  }
+
+  function advanceCursor(agent, id) {
+    try {
+      const order = orderIds(agent);
+      const cur = readCursor(agent);
+      const curIdx = cur && cur.lastId ? order.indexOf(cur.lastId) : -1;
+      if (order.indexOf(id) > curIdx) {
+        fs.mkdirSync(path.join(root, "cursors"), { recursive: true });
+        fs.writeFileSync(
+          path.join(root, "cursors", agent + ".json"),
+          JSON.stringify({ lastId: id, at: new Date().toISOString() }) + "\n"
+        );
+      }
+    } catch {}
+  }
+
+  function coveredByCursor(agent, id) {
+    const order = orderIds(agent);
+    const cur = readCursor(agent);
+    if (!cur || !cur.lastId) return false;
+    const curIdx = order.indexOf(cur.lastId);
+    const idx = order.indexOf(id);
+    return curIdx !== -1 && idx !== -1 && idx <= curIdx;
+  }
+
+  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.)";
+    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 }] } });
+      }
+    } catch (e) {
+      try {
+        await client.app.log({
+          body: {
+            service: "dm-watch",
+            level: "warn",
+            message: "DM wake failed for " + agent + ": " + (e && e.message ? e.message : String(e)),
+          },
+        });
+      } catch {}
+    }
+  }
+
+  async function poll() {
+    refreshAgentMap();
+    let agents = [];
+    try {
+      agents = fs.readdirSync(dmDir).filter((e) => {
+        try {
+          return fs.statSync(path.join(dmDir, e)).isDirectory();
+        } catch {
+          return false;
+        }
+      });
+    } catch {
+      return;
+    }
+    for (const agent of agents) {
+      const sessionID = agentToSession.get(agent);
+      if (!sessionID) continue; // nobody live for this name — mail waits for pull
+      let files = [];
+      try {
+        files = fs.readdirSync(path.join(dmDir, agent)).filter((f) => f.endsWith(".json")).sort();
+      } catch {
+        continue;
+      }
+      for (const f of files) {
+        const id = f.replace(/\.json$/, "");
+        const key = agent + "/" + id;
+        if (processed.has(key)) continue;
+        if (fs.existsSync(deliveredMarker(agent, id))) {
+          processed.add(key);
+          continue;
+        }
+        if (coveredByCursor(agent, id)) {
+          processed.add(key);
+          continue;
+        }
+        const msg = readJsonSafe(path.join(dmDir, agent, f));
+        if (!msg || !msg.id || !msg.from || !msg.body) {
+          processed.add(key);
+          continue;
+        }
+        await deliver(agent, agentToSession.get(agent) || sessionID, {
+          id: msg.id,
+          from: msg.from,
+          body: String(msg.body),
+          at: msg.at || "",
+        });
+      }
+    }
+  }
+
+  const timer = setInterval(() => {
+    poll().catch(() => {});
+  }, POLL_MS);
+  poll().catch(() => {});
+
+  return {
+    dispose: async () => {
+      clearInterval(timer);
+    },
+  };
+};
+
+export default DmWatchPlugin;

package/opencode/tools/dm-send.js

@@ -0,0 +1,85 @@
+// .opencode/tools/dm-send.js — primitive DM tool for agent-board (DM-only v2).
+// Filename becomes the tool name: dm-send.
+// Loaded by opencode alongside built-in tools. Zero extra deps.
+//
+// Usage from the agent (just a tool call, whenever you want):
+//   dm-send({ from: "alice", to: "bob", body: "the parser accepts ISO dates only" })
+//
+// 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)
+//   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.
+//
+// Delivery ("inserted into context") is done by ../plugins/dm-watch.js, which
+// polls dm/ and injects via client.session.promptAsync. This tool never blocks
+// waiting for a reply — fire and forget, like Slack.
+
+import { tool } from "@opencode-ai/plugin";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+function boardRoot(worktree) {
+  if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
+  return path.join(worktree, ".agentboard");
+}
+
+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);
+  if (!c) throw new Error("invalid " + what);
+  return c;
+}
+
+function writeJsonAtomic(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = p + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n");
+  fs.renameSync(tmp, p);
+}
+
+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).",
+  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."),
+    body: tool.schema.string().describe("Message text, 1..8000 chars."),
+  },
+  async execute(args, context) {
+    const from = clean(args.from, "from");
+    const to = clean(args.to, "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 });
+    // upsert sender with live session routing for the watcher plugin
+    const ap = path.join(root, "agents", from + ".json");
+    let prev = null;
+    try {
+      prev = JSON.parse(fs.readFileSync(ap, "utf8"));
+    } catch {}
+    writeJsonAtomic(ap, {
+      name: from,
+      firstSeen: (prev && prev.firstSeen) || now,
+      lastSeen: now,
+      sessionId: (context && context.sessionID) || (prev && prev.sessionId) || undefined,
+      lastDir: context.worktree || context.directory || undefined,
+    });
+    return "sent " + id + " -> " + to;
+  },
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@eamonpluto/agentboard",
+  "version": "2.2.0",
+  "description": "Zero-dependency local DM bus for AI coding agents: message another agent, inserted into context, just a tool call.",
+  "type": "module",
+  "bin": {
+    "agentboard": "bin/agentboard.js",
+    "agentboard-mcp": "bin/agentboard-mcp.js",
+    "agentboard-hook": "bin/agentboard-hook.js"
+  },
+  "scripts": {
+    "test": "node test/agentboard.smoke.mjs && node test/agentboard.harness.mjs"
+  },
+  "files": [
+    "bin/",
+    "opencode/",
+    "AGENTS.template.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}