agent-coord-mcp 0.1.0 → 0.2.0

package/README.md

@@ -111,7 +111,57 @@ Set `AGENT_COORD_DIR=/some/other/path` in the MCP server's env to relocate state
 
 `wait_for_message` is the cheap path: one tool call, server-side `fs.watch` + 500ms poll, capped at 60s. The model only pays for one round-trip per wait.
 
-The model is fundamentally turn-based — there's no async push that wakes an idle agent. For *passive* presence (react when pinged, even between user turns), wire a client-side hook that runs `read_messages --peek` and injects unread inbox entries into the next prompt. With Claude Code that's a `UserPromptSubmit` hook; other clients have similar mechanisms.
+But the model is fundamentally turn-based — there's no async push that wakes an idle agent. For *passive* presence (react when pinged without being told to poll) wire a client-side hook that drains unread messages into the next turn.
+
+### Claude Code hook
+
+A reference hook ships in [`hooks/peek-coord.mjs`](./hooks/peek-coord.mjs). It reads `~/agent-coord/inbox/<id>.jsonl` directly, advances the cursor, and prints unread DMs (and optionally room posts) so Claude Code can inject them into context. No MCP roundtrip, no extra deps.
+
+Two places to wire it:
+
+- **`UserPromptSubmit`** — fires before the agent sees the user's next message. Stdout is appended to context. Good for *"new DMs since last turn"*.
+- **`Stop`** — fires when the agent finishes its turn. If there are unread messages, the hook returns `{"decision":"block","reason":"..."}` which keeps the session going and feeds the messages in. Good for *"peer pinged me 2 seconds after I stopped"*.
+
+Add to your project or user `settings.json`:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_COORD_ID=frontend node /absolute/path/to/agent-coord-mcp/hooks/peek-coord.mjs --mode=user-prompt"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "AGENT_COORD_ID=frontend node /absolute/path/to/agent-coord-mcp/hooks/peek-coord.mjs --mode=stop"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Set `AGENT_COORD_ID` to whatever you passed to `register({agentId})`. Set `AGENT_COORD_INCLUDE_ROOM=1` to also drain the shared room. Set `AGENT_COORD_DIR` if you've relocated the state directory.
+
+Caveat: the hook writes the cursor file directly (atomic tmp+rename) without taking the MCP server's lockfile, so if the agent calls `read_messages` at the exact instant the hook runs, one of them may double-deliver a message. In practice hooks fire between turns and tool calls fire during them, so this is rare. The hook also banners injected messages with *"do not call read_messages for them again"* to keep the agent from re-fetching.
+
+### Other clients
+
+The script itself is plain Node — no Claude-specific deps — so it ports anywhere you can run a shell command around the agent loop. The MCP protocol doesn't standardize client-side hooks, so the wiring varies:
+
+- **Cursor / Cline / Continue / Zed** — no first-class lifecycle hooks today. Closest workaround is to put *"run `peek-coord.mjs` at turn start and treat its stdout as additional context"* in your rules/system prompt. Less reliable (model can skip it) but functional.
+- **Custom SDK agents (`@anthropic-ai/sdk`, `openai`, etc.)** — easiest fit. Shell out to the script (or inline the ~50 lines of logic) right before each completion call and prepend stdout as a system message. Fully deterministic.
+- **Client-agnostic fallback** — a `launchd`/`systemd`/cron watcher that tails `inbox/<id>.jsonl` and writes unread entries to a file the agent is told to `Read` on session start. Crude, works everywhere.
 
 ## License
 

package/hooks/peek-coord.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// Claude Code hook: drains unread agent-coord messages into the next turn
+// without making the agent poll. Reads ~/agent-coord/ directly (no MCP roundtrip).
+//
+// Usage (in settings.json):
+//   UserPromptSubmit  -> node /path/to/peek-coord.mjs --mode=user-prompt
+//   Stop              -> node /path/to/peek-coord.mjs --mode=stop
+//
+// Required env: AGENT_COORD_ID (the agent's id, matches register({agentId}))
+// Optional env: AGENT_COORD_DIR (default ~/agent-coord)
+// Optional env: AGENT_COORD_INCLUDE_ROOM=1 to also drain the shared room
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+const MODE = (process.argv.find((a) => a.startsWith("--mode="))?.slice(7)) ?? "user-prompt";
+const AGENT_ID = process.env.AGENT_COORD_ID;
+if (!AGENT_ID) {
+  // No agent id configured — silently no-op so the hook never blocks the user.
+  process.exit(0);
+}
+
+const ROOT =
+  process.env.AGENT_COORD_DIR ??
+  process.env.CLAUDE_COORD_DIR ??
+  path.join(homedir(), "agent-coord");
+const INBOX = path.join(ROOT, "inbox", `${sanitize(AGENT_ID)}.jsonl`);
+const ROOM = path.join(ROOT, "room.jsonl");
+const CURSOR = path.join(ROOT, "cursors", `${sanitize(AGENT_ID)}.json`);
+const INCLUDE_ROOM = process.env.AGENT_COORD_INCLUDE_ROOM === "1";
+
+const cursor = readJson(CURSOR, {});
+const out = [];
+
+const inbox = drain(INBOX, cursor, "inboxOffset");
+for (const m of inbox) out.push(fmt("inbox", m));
+
+if (INCLUDE_ROOM) {
+  const room = drain(ROOM, cursor, "roomOffset");
+  for (const m of room) {
+    if (m.from === AGENT_ID) continue; // don't echo our own room posts back
+    out.push(fmt("room", m));
+  }
+}
+
+if (out.length === 0) process.exit(0);
+
+writeJsonAtomic(CURSOR, cursor);
+
+const banner =
+  `[agent-coord] ${out.length} unread message(s) for "${AGENT_ID}". ` +
+  `These were delivered via hook; do not call read_messages for them again.\n`;
+const body = banner + out.join("\n");
+
+if (MODE === "stop") {
+  // Stop hook: emit JSON to keep the session going with the new context.
+  process.stdout.write(
+    JSON.stringify({ decision: "block", reason: body }) + "\n"
+  );
+} else {
+  // UserPromptSubmit (and any other mode): plain stdout is appended to context.
+  process.stdout.write(body + "\n");
+}
+
+// ---------- helpers ----------
+
+function drain(file, cursor, key) {
+  if (!existsSync(file)) return [];
+  const raw = readFileSync(file, "utf8");
+  const lines = raw.split("\n").filter((l) => l.trim());
+  const start = cursor[key] ?? 0;
+  const slice = lines.slice(start);
+  const parsed = [];
+  for (const line of slice) {
+    try { parsed.push(JSON.parse(line)); } catch { /* skip */ }
+  }
+  if (slice.length > 0) cursor[key] = start + slice.length;
+  return parsed;
+}
+
+function fmt(source, m) {
+  const ts = new Date(m.ts ?? Date.now()).toISOString();
+  const who = m.from ?? "?";
+  const tag = source === "room" ? "room" : "dm";
+  return `  [${tag} ${ts} from=${who}] ${m.text ?? ""}`;
+}
+
+function readJson(file, fallback) {
+  if (!existsSync(file)) return fallback;
+  try {
+    const raw = readFileSync(file, "utf8");
+    if (!raw.trim()) return fallback;
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJsonAtomic(file, data) {
+  mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp.${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2), "utf8");
+  renameSync(tmp, file);
+}
+
+function sanitize(id) {
+  return id.replace(/[^a-zA-Z0-9._-]/g, "_");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "File-backed MCP server for coordinating multiple AI coding agents (Claude Code, Cursor, Cline, etc.) on the same machine.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
   "files": [
     "dist",
     "src",
+    "hooks",
     "README.md",
     "LICENSE"
   ],