agent-coord-mcp 0.2.1 → 0.3.1

package/hooks/tmux-pusher.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * tmux-pusher.mjs
+ *
+ * Long-running daemon that watches an agent's coord inbox (and optionally the
+ * shared room) and types new messages into a tmux pane running an interactive
+ * CLI agent. Works with any line-driven agent CLI: Claude Code, Aider, codex,
+ * gemini-cli, opencode, etc.
+ *
+ * Required env:
+ *   AGENT_COORD_ID            agentId registered with the MCP
+ *   AGENT_COORD_TMUX_TARGET   tmux target, e.g. "coord-frontend:agent.0"
+ *
+ * Optional env:
+ *   AGENT_COORD_DIR           override state dir (default ~/agent-coord)
+ *   AGENT_COORD_INCLUDE_ROOM  "1" to also inject shared-room messages
+ *   AGENT_COORD_ALLOWLIST     comma-separated peer agentIds to accept
+ *                             (default: accept all)
+ *   AGENT_COORD_DEBOUNCE_MS   coalesce window for bursts (default 1000)
+ *   AGENT_COORD_POLL_MS       fallback poll interval (default 1000)
+ *
+ * Safety:
+ *   - drops messages where from === AGENT_COORD_ID (no self-echo)
+ *   - drops messages whose text starts with "/" (avoid injected slash commands)
+ *   - if allowlist set, drops messages from peers not in it
+ *   - serializes tmux sends so two batches never overlap
+ *
+ * Cursor: shares ~/agent-coord/cursors/<id>.json with the MCP server, so the
+ * agent calling read_messages won't see anything the pusher already delivered.
+ *
+ * Do NOT enable peek-coord.mjs Stop/UserPromptSubmit hooks for the same agent
+ * while this daemon runs — both consume the same cursor and would race.
+ *
+ * Caveats:
+ *   - Pasting types into whatever pane state exists. If you're mid-typing in
+ *     the same pane, your buffer gets corrupted. Run the receiving agent in a
+ *     dedicated pane you don't normally edit in.
+ *   - The pusher can't tell if the agent is idle, mid-tool, or showing a
+ *     permission prompt. send-keys is unconditional.
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  mkdirSync,
+  unlinkSync,
+  watch,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+
+const AGENT_ID = process.env.AGENT_COORD_ID;
+const TMUX_TARGET = process.env.AGENT_COORD_TMUX_TARGET;
+if (!AGENT_ID) die("AGENT_COORD_ID is required");
+if (!TMUX_TARGET) die("AGENT_COORD_TMUX_TARGET is required");
+
+const ROOT = process.env.AGENT_COORD_DIR || path.join(homedir(), "agent-coord");
+const INCLUDE_ROOM = process.env.AGENT_COORD_INCLUDE_ROOM === "1";
+const ALLOWLIST = (process.env.AGENT_COORD_ALLOWLIST || "")
+  .split(",")
+  .map((s) => s.trim())
+  .filter(Boolean);
+const DEBOUNCE_MS = parseInt(process.env.AGENT_COORD_DEBOUNCE_MS || "1000", 10);
+const POLL_MS = parseInt(process.env.AGENT_COORD_POLL_MS || "1000", 10);
+
+const SAFE_ID = AGENT_ID.replace(/[^a-zA-Z0-9._-]/g, "_");
+const INBOX_FILE = path.join(ROOT, "inbox", `${SAFE_ID}.jsonl`);
+const ROOM_FILE = path.join(ROOT, "room.jsonl");
+const CURSOR_FILE = path.join(ROOT, "cursors", `${SAFE_ID}.json`);
+const TRANSPORT_FILE = path.join(ROOT, "transports", `${SAFE_ID}.json`);
+const BUFFER_NAME = `coord-${SAFE_ID}`;
+
+mkdirSync(path.dirname(CURSOR_FILE), { recursive: true });
+mkdirSync(path.dirname(TRANSPORT_FILE), { recursive: true });
+
+// Confirm tmux target exists at startup so we fail loudly instead of silently.
+const probe = spawnSync("tmux", ["display-message", "-p", "-t", TMUX_TARGET, "ok"]);
+if (probe.status !== 0) {
+  die(`tmux target '${TMUX_TARGET}' not found: ${(probe.stderr ?? "").toString().trim()}`);
+}
+
+let pending = [];
+let debounceTimer = null;
+let sending = false;
+
+function readCursor() {
+  if (!existsSync(CURSOR_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(CURSOR_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeCursor(c) {
+  const tmp = CURSOR_FILE + ".tmp";
+  writeFileSync(tmp, JSON.stringify(c));
+  renameSync(tmp, CURSOR_FILE);
+}
+
+function readJsonl(file) {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function shouldInject(m) {
+  if (!m || m.from === AGENT_ID) return false;
+  if (ALLOWLIST.length > 0 && !ALLOWLIST.includes(m.from)) return false;
+  if (typeof m.text === "string" && m.text.trimStart().startsWith("/")) return false;
+  return true;
+}
+
+function drainSource(label, file, cursorKey, cur) {
+  const all = readJsonl(file);
+  const off = cur[cursorKey] ?? 0;
+  const fresh = all.slice(off);
+  if (fresh.length === 0) return false;
+  for (const m of fresh) {
+    if (shouldInject(m)) pending.push({ kind: label, ...m });
+  }
+  cur[cursorKey] = off + fresh.length;
+  return true;
+}
+
+function checkOnce() {
+  const cur = readCursor();
+  let changed = false;
+  if (drainSource("DM", INBOX_FILE, "inboxOffset", cur)) changed = true;
+  if (INCLUDE_ROOM && drainSource("ROOM", ROOM_FILE, "roomOffset", cur)) changed = true;
+  if (changed) writeCursor(cur);
+  if (pending.length > 0) scheduleFlush();
+}
+
+function scheduleFlush() {
+  if (debounceTimer) return;
+  debounceTimer = setTimeout(flush, DEBOUNCE_MS);
+}
+
+async function flush() {
+  debounceTimer = null;
+  if (sending) {
+    scheduleFlush();
+    return;
+  }
+  if (pending.length === 0) return;
+  const batch = pending;
+  pending = [];
+  sending = true;
+  try {
+    await injectViaTmux(batch);
+  } catch (e) {
+    process.stderr.write(`[tmux-pusher] inject failed: ${e?.message ?? e}\n`);
+    pending = [...batch, ...pending];
+    scheduleFlush();
+  } finally {
+    sending = false;
+  }
+}
+
+function formatBatch(batch) {
+  const lines = [
+    "[agent-coord] incoming peer messages — already consumed from your inbox, do not call read_messages for them:",
+  ];
+  for (const m of batch) {
+    const tag = m.kind;
+    const ts = new Date(m.ts ?? Date.now()).toISOString();
+    lines.push(`  [${tag} ${ts} from=${m.from}] ${m.text ?? ""}`);
+  }
+  return lines.join("\n");
+}
+
+function injectViaTmux(batch) {
+  return new Promise((resolve, reject) => {
+    const payload = formatBatch(batch);
+    const load = spawn("tmux", ["load-buffer", "-b", BUFFER_NAME, "-"]);
+    load.on("error", reject);
+    load.on("exit", (code) => {
+      if (code !== 0) return reject(new Error(`tmux load-buffer exit ${code}`));
+      const paste = spawnSync("tmux", [
+        "paste-buffer",
+        "-b",
+        BUFFER_NAME,
+        "-t",
+        TMUX_TARGET,
+        "-d",
+      ]);
+      if (paste.status !== 0) {
+        return reject(new Error(`tmux paste-buffer: ${(paste.stderr ?? "").toString().trim()}`));
+      }
+      const enter = spawnSync("tmux", ["send-keys", "-t", TMUX_TARGET, "Enter"]);
+      if (enter.status !== 0) {
+        return reject(new Error(`tmux send-keys: ${(enter.stderr ?? "").toString().trim()}`));
+      }
+      resolve();
+    });
+    load.stdin.end(payload);
+  });
+}
+
+// Publish transport marker so list_agents can show this agent is push-capable.
+writeTransportMarker();
+let markerCleaned = false;
+const cleanupMarker = () => {
+  if (markerCleaned) return;
+  markerCleaned = true;
+  try {
+    unlinkSync(TRANSPORT_FILE);
+  } catch {
+    // already gone
+  }
+};
+process.on("SIGINT", () => {
+  cleanupMarker();
+  process.exit(0);
+});
+process.on("SIGTERM", () => {
+  cleanupMarker();
+  process.exit(0);
+});
+process.on("exit", cleanupMarker);
+
+function writeTransportMarker() {
+  const marker = {
+    agentId: AGENT_ID,
+    transport: "tmux-push",
+    pid: process.pid,
+    tmuxTarget: TMUX_TARGET,
+    since: Date.now(),
+  };
+  const tmp = TRANSPORT_FILE + ".tmp";
+  writeFileSync(tmp, JSON.stringify(marker));
+  renameSync(tmp, TRANSPORT_FILE);
+}
+
+// Initial drain in case messages accumulated before the daemon started.
+checkOnce();
+
+// Watch + poll fallback.
+try {
+  if (existsSync(INBOX_FILE)) watch(INBOX_FILE, () => checkOnce());
+} catch {
+  // file may not exist yet; polling covers it
+}
+if (INCLUDE_ROOM) {
+  try {
+    if (existsSync(ROOM_FILE)) watch(ROOM_FILE, () => checkOnce());
+  } catch {
+    // ignore
+  }
+}
+setInterval(checkOnce, POLL_MS);
+
+process.stderr.write(
+  `[tmux-pusher] watching inbox for '${AGENT_ID}' -> tmux ${TMUX_TARGET} (room=${INCLUDE_ROOM ? "on" : "off"})\n`,
+);
+
+function die(msg) {
+  process.stderr.write(`[tmux-pusher] ${msg}\n`);
+  process.exit(1);
+}

package/package.json

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

package/scripts/spawn-agent.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# spawn-agent.sh — start a CLI agent in a dedicated tmux session and wire
+# coord-inbox auto-delivery to its pane via hooks/tmux-pusher.mjs.
+#
+# Works with any line-driven CLI agent (Claude Code, Aider, codex, gemini-cli,
+# opencode, ...). The pusher just types into the pane; it doesn't care what's
+# on the receiving end.
+#
+# Usage:
+#   scripts/spawn-agent.sh --id frontend --cmd "claude"
+#   scripts/spawn-agent.sh --id backend  --cmd "aider --model sonnet" --include-room
+#   scripts/spawn-agent.sh --id worker   --cmd "codex" --allowlist frontend,backend
+#
+# Flags:
+#   --id <agentId>          coord agentId, also names the tmux session (coord-<id>)
+#   --cmd "<command>"       agent CLI to run in pane 0 (quote it)
+#   --include-room          also push shared-room messages into the pane
+#   --allowlist a,b,c       only deliver DMs from these peer agentIds
+#   --dir <path>            override AGENT_COORD_DIR
+#
+# After spawn, attach with: tmux attach -t coord-<id>
+# Stop with:                scripts/stop-agent.sh --id <id>
+
+set -euo pipefail
+
+ID=""
+CMD=""
+INCLUDE_ROOM=""
+ALLOWLIST=""
+COORD_DIR=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --id) ID="$2"; shift 2 ;;
+    --cmd) CMD="$2"; shift 2 ;;
+    --include-room) INCLUDE_ROOM="1"; shift ;;
+    --allowlist) ALLOWLIST="$2"; shift 2 ;;
+    --dir) COORD_DIR="$2"; shift 2 ;;
+    -h|--help)
+      sed -n '2,22p' "$0"; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+[[ -z "$ID"  ]] && { echo "--id required"  >&2; exit 2; }
+[[ -z "$CMD" ]] && { echo "--cmd required (e.g. 'claude')" >&2; exit 2; }
+
+command -v tmux >/dev/null || { echo "tmux not installed" >&2; exit 1; }
+command -v node >/dev/null || { echo "node not installed" >&2; exit 1; }
+
+SESSION="coord-$ID"
+ROOT="${COORD_DIR:-${AGENT_COORD_DIR:-$HOME/agent-coord}}"
+LOGDIR="$ROOT/logs"
+PIDDIR="$ROOT/pids"
+mkdir -p "$LOGDIR" "$PIDDIR"
+
+REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PUSHER="$REPO_DIR/hooks/tmux-pusher.mjs"
+[[ -f "$PUSHER" ]] || { echo "missing $PUSHER" >&2; exit 1; }
+
+if tmux has-session -t "$SESSION" 2>/dev/null; then
+  echo "tmux session '$SESSION' already exists — attach with: tmux attach -t $SESSION" >&2
+  exit 1
+fi
+
+PID_FILE="$PIDDIR/pusher-$ID.pid"
+if [[ -f "$PID_FILE" ]] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then
+  echo "pusher already running for '$ID' (pid $(cat "$PID_FILE"))" >&2
+  exit 1
+fi
+
+tmux new-session -d -s "$SESSION" -n agent "$CMD"
+
+# Resolve the actual pane id — globally unique, immune to base-index settings.
+TARGET="$(tmux display-message -p -t "$SESSION:agent" '#{pane_id}')"
+[[ -n "$TARGET" ]] || { echo "failed to resolve tmux pane id" >&2; exit 1; }
+
+(
+  export AGENT_COORD_ID="$ID"
+  export AGENT_COORD_TMUX_TARGET="$TARGET"
+  [[ -n "$COORD_DIR"      ]] && export AGENT_COORD_DIR="$COORD_DIR"
+  [[ -n "$INCLUDE_ROOM"   ]] && export AGENT_COORD_INCLUDE_ROOM=1
+  [[ -n "$ALLOWLIST"      ]] && export AGENT_COORD_ALLOWLIST="$ALLOWLIST"
+  nohup node "$PUSHER" >> "$LOGDIR/pusher-$ID.log" 2>&1 &
+  echo $! > "$PID_FILE"
+)
+
+echo "agent '$ID' started"
+echo "  attach: tmux attach -t $SESSION"
+echo "  pusher: pid $(cat "$PID_FILE")  log: $LOGDIR/pusher-$ID.log"
+echo "  stop:   scripts/stop-agent.sh --id $ID"

package/scripts/stop-agent.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# stop-agent.sh — tear down an agent spawned by spawn-agent.sh.
+# Kills the tmux session and the tmux-pusher daemon.
+#
+# Usage:
+#   scripts/stop-agent.sh --id frontend
+#   scripts/stop-agent.sh --id frontend --dir /custom/coord/dir
+
+set -euo pipefail
+
+ID=""
+COORD_DIR=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --id) ID="$2"; shift 2 ;;
+    --dir) COORD_DIR="$2"; shift 2 ;;
+    -h|--help) sed -n '2,8p' "$0"; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+[[ -z "$ID" ]] && { echo "--id required" >&2; exit 2; }
+
+ROOT="${COORD_DIR:-${AGENT_COORD_DIR:-$HOME/agent-coord}}"
+PID_FILE="$ROOT/pids/pusher-$ID.pid"
+SESSION="coord-$ID"
+
+if [[ -f "$PID_FILE" ]]; then
+  PID="$(cat "$PID_FILE")"
+  if kill -0 "$PID" 2>/dev/null; then
+    kill "$PID" && echo "stopped pusher pid $PID"
+  fi
+  rm -f "$PID_FILE"
+else
+  echo "no pusher pid file for '$ID'"
+fi
+
+if tmux has-session -t "$SESSION" 2>/dev/null; then
+  tmux kill-session -t "$SESSION" && echo "killed tmux session $SESSION"
+else
+  echo "no tmux session '$SESSION'"
+fi

package/src/server.ts

@@ -3,8 +3,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ensureDirs } from "./store.js";
 import {
+  attachAgentSchema,
+  attachAgentTool,
+  detachAgentSchema,
+  detachAgentTool,
   heartbeatSchema,
   heartbeatTool,
+  joinSchema,
+  joinTool,
   listAgentsSchema,
   listAgentsTool,
   postStatusSchema,
@@ -17,6 +23,10 @@ import {
   registerTool,
   sendMessageSchema,
   sendMessageTool,
+  statusSchema,
+  statusTool,
+  unregisterSchema,
+  unregisterTool,
   waitForMessageSchema,
   waitForMessageTool,
 } from "./tools.js";
@@ -35,13 +45,34 @@ async function main() {
     version: "0.1.0",
   });
 
+  server.tool(
+    "join",
+    "Recommended session-start call. Does register + auto-attach (if running inside tmux) + read inbox in one round-trip. Pass attach=false to skip the transport, attach={...overrides} to customize, or omit it to let the server auto-detect $TMUX_PANE. Returns the registration, attach result, and any unread inbox messages.",
+    joinSchema,
+    async (args) => jsonResult(await joinTool(args))
+  );
+
   server.tool(
     "register",
-    "Register this agent in the shared registry. Call once per session.",
+    "Register this agent in the shared registry. Lower-level than `join` — does not attach a transport or drain the inbox. Prefer `join` unless you need explicit control.",
     registerSchema,
     async (args) => jsonResult(await registerTool(args))
   );
 
+  server.tool(
+    "unregister",
+    "Tear down this agent: detach any attached transport (kills the pusher) and remove the registry entry. Clean shutdown counterpart to `join`.",
+    unregisterSchema,
+    async (args) => jsonResult(await unregisterTool(args))
+  );
+
+  server.tool(
+    "status",
+    "Introspect this agent's coord state: registration, attached transport, inbox depth and unread count, and whether this MCP server is running inside tmux. Useful for debugging 'why isn't my DM landing'.",
+    statusSchema,
+    async (args) => jsonResult(await statusTool(args))
+  );
+
   server.tool(
     "heartbeat",
     "Refresh this agent's lastHeartbeat timestamp.",
@@ -91,6 +122,20 @@ async function main() {
     async (args) => jsonResult(await waitForMessageTool(args))
   );
 
+  server.tool(
+    "attach_agent",
+    "Start the tmux-push transport for an agent: spawns hooks/tmux-pusher.mjs as a background process so peer DMs (and optionally room messages) get typed into the agent's tmux pane in real time. tmuxTarget defaults to the MCP server's own $TMUX_PANE if this server is running inside tmux. allowlist restricts which peer agentIds can push. Updates list_agents to show transport=tmux-push.",
+    attachAgentSchema,
+    async (args) => jsonResult(await attachAgentTool(args))
+  );
+
+  server.tool(
+    "detach_agent",
+    "Stop the tmux-push transport for an agent: kills the pusher process and clears the transport marker.",
+    detachAgentSchema,
+    async (args) => jsonResult(await detachAgentTool(args))
+  );
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/src/store.ts

@@ -12,9 +12,12 @@ export const ROOM_FILE = path.join(ROOT, "room.jsonl");
 export const STATUS_FILE = path.join(ROOT, "status.jsonl");
 export const INBOX_DIR = path.join(ROOT, "inbox");
 export const CURSOR_DIR = path.join(ROOT, "cursors");
+export const TRANSPORT_DIR = path.join(ROOT, "transports");
+export const PID_DIR = path.join(ROOT, "pids");
+export const LOG_DIR = path.join(ROOT, "logs");
 
 export function ensureDirs(): void {
-  for (const d of [ROOT, INBOX_DIR, CURSOR_DIR]) {
+  for (const d of [ROOT, INBOX_DIR, CURSOR_DIR, TRANSPORT_DIR, PID_DIR, LOG_DIR]) {
     if (!existsSync(d)) mkdirSync(d, { recursive: true });
   }
   for (const f of [ROOM_FILE, STATUS_FILE]) {
@@ -22,6 +25,24 @@ export function ensureDirs(): void {
   }
 }
 
+export function transportFile(agentId: string): string {
+  return path.join(TRANSPORT_DIR, `${sanitize(agentId)}.json`);
+}
+
+export function pidFile(agentId: string, kind: string): string {
+  return path.join(PID_DIR, `${kind}-${sanitize(agentId)}.pid`);
+}
+
+export function logFile(agentId: string, kind: string): string {
+  return path.join(LOG_DIR, `${kind}-${sanitize(agentId)}.log`);
+}
+
+export async function listTransportFiles(): Promise<string[]> {
+  if (!existsSync(TRANSPORT_DIR)) return [];
+  const names = await fs.readdir(TRANSPORT_DIR);
+  return names.filter((n) => n.endsWith(".json"));
+}
+
 async function ensureFile(file: string): Promise<void> {
   if (!existsSync(file)) {
     await fs.mkdir(path.dirname(file), { recursive: true });