agent-coord-mcp 0.2.1 → 0.3.1

package/src/tools.ts

@@ -1,5 +1,8 @@
 import { randomUUID } from "node:crypto";
-import { watch } from "node:fs";
+import { existsSync, openSync, watch } from "node:fs";
+import { promises as fsp } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import path from "node:path";
 import {
@@ -15,9 +18,13 @@ import {
   inboxFile,
   listCursorFiles,
   listInboxFiles,
+  listTransportFiles,
+  logFile,
+  pidFile,
   readJson,
   readJsonl,
   rewriteJsonl,
+  transportFile,
   updateJson,
 } from "./store.js";
 
@@ -27,6 +34,15 @@ type AgentEntry = {
   role?: string;
   registeredAt: number;
   lastHeartbeat: number;
+  capabilities?: string[];
+};
+
+type TransportMarker = {
+  agentId: string;
+  transport: string;
+  pid: number;
+  tmuxTarget?: string;
+  since: number;
 };
 
 type AgentRegistry = Record<string, AgentEntry>;
@@ -82,6 +98,26 @@ export async function registerTool(args: { agentId: string; project?: string; ro
   return { ok: true, agent: reg[args.agentId] };
 }
 
+// ---------- unregister ----------
+
+export const unregisterSchema = { agentId: z.string().min(1) };
+
+export async function unregisterTool(args: { agentId: string }) {
+  // If a transport is attached, take it down first so the pusher doesn't keep
+  // re-publishing the marker after we drop the registry entry.
+  const detach = await detachAgentTool(args);
+
+  let existed = false;
+  await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
+    if (current[args.agentId]) {
+      existed = true;
+      delete current[args.agentId];
+    }
+    return current;
+  });
+  return { ok: true, removed: existed, detach };
+}
+
 // ---------- heartbeat ----------
 
 export const heartbeatSchema = { agentId: z.string().min(1) };
@@ -107,8 +143,18 @@ export const listAgentsSchema = {} as const;
 export async function listAgentsTool() {
   const now = Date.now();
   const evicted: string[] = [];
+
+  // Load live transport markers first so we can refresh heartbeats for agents
+  // whose pusher (or other transport daemon) is alive — the live process IS
+  // the heartbeat, no separate ping needed.
+  const liveTransports = await loadLiveTransports();
+
   const reg = await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
     for (const [id, entry] of Object.entries(current)) {
+      if (liveTransports.has(id)) {
+        entry.lastHeartbeat = now;
+        continue;
+      }
       if (now - entry.lastHeartbeat > EVICT_MS) {
         evicted.push(id);
         delete current[id];
@@ -116,14 +162,53 @@ export async function listAgentsTool() {
     }
     return current;
   });
-  const agents = Object.values(reg).map((a) => ({
-    ...a,
-    online: now - a.lastHeartbeat < STALE_MS,
-    secondsSinceHeartbeat: Math.floor((now - a.lastHeartbeat) / 1000),
-  }));
+
+  const agents = Object.values(reg).map((a) => {
+    const transport = liveTransports.get(a.agentId);
+    const merged = [...(a.capabilities ?? [])];
+    if (transport && !merged.includes(transport.transport)) merged.push(transport.transport);
+    return {
+      ...a,
+      online: transport ? true : now - a.lastHeartbeat < STALE_MS,
+      secondsSinceHeartbeat: Math.floor((now - a.lastHeartbeat) / 1000),
+      capabilities: merged.length > 0 ? merged : undefined,
+      transport: transport
+        ? { kind: transport.transport, tmuxTarget: transport.tmuxTarget, pid: transport.pid }
+        : undefined,
+    };
+  });
   return { agents, evicted };
 }
 
+async function loadLiveTransports(): Promise<Map<string, TransportMarker>> {
+  const out = new Map<string, TransportMarker>();
+  for (const fname of await listTransportFiles()) {
+    const file = path.join(path.dirname(transportFile("x")), fname);
+    const marker = await readJson<TransportMarker | null>(file, null);
+    if (!marker) {
+      await deleteFile(file);
+      continue;
+    }
+    if (!isPidAlive(marker.pid)) {
+      await deleteFile(file);
+      continue;
+    }
+    out.set(marker.agentId, marker);
+  }
+  return out;
+}
+
+function isPidAlive(pid: number): boolean {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    return code === "EPERM"; // EPERM = exists but not ours; ESRCH = gone
+  }
+}
+
 // ---------- send_message ----------
 
 export const sendMessageSchema = {
@@ -195,7 +280,19 @@ export async function readMessagesTool(args: {
     });
   }
 
-  return { messages: limited, totalNew, returned: limited.length };
+  // Drop the agent's own posts on shared channels — reading your own broadcast
+  // back is never useful and confuses turn-based agents into self-replies.
+  // Cursor has already advanced past them, so they won't reappear.
+  const visible =
+    args.source === "room" || args.source === "status"
+      ? limited.filter((e) => entryAuthor(e) !== args.agentId)
+      : limited;
+
+  return { messages: visible, totalNew, returned: visible.length };
+}
+
+function entryAuthor(e: Message | StatusEntry): string | undefined {
+  return "from" in e ? e.from : e.agentId;
 }
 
 // ---------- post_status ----------
@@ -231,46 +328,57 @@ export async function waitForMessageTool(args: {
   source: "inbox" | "room" | "status";
   timeoutMs?: number;
 }) {
-  const timeout = Math.min(args.timeoutMs ?? 30_000, MAX_WAIT_MS);
+  const totalTimeout = Math.min(args.timeoutMs ?? 30_000, MAX_WAIT_MS);
   const file = sourceFile(args.source, args.agentId);
-  const startSize = await fileSize(file);
-
-  const result = await new Promise<{ changed: boolean }>((resolve) => {
-    let settled = false;
-    const finish = (changed: boolean) => {
-      if (settled) return;
-      settled = true;
-      clearInterval(poll);
+  const deadline = Date.now() + totalTimeout;
+
+  // Loop so that file growth caused only by the agent's own self-posts (which
+  // readMessagesTool now filters out for room/status) doesn't return an empty
+  // result — keep waiting until we have something to deliver or time out.
+  while (Date.now() < deadline) {
+    const startSize = await fileSize(file);
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+
+    const changed = await new Promise<boolean>((resolve) => {
+      let settled = false;
+      const finish = (v: boolean) => {
+        if (settled) return;
+        settled = true;
+        clearInterval(poll);
+        try {
+          watcher?.close();
+        } catch {
+          // ignore
+        }
+        clearTimeout(t);
+        resolve(v);
+      };
+
+      const check = async () => {
+        const sz = await fileSize(file);
+        if (sz > startSize) finish(true);
+      };
+
+      let watcher: ReturnType<typeof watch> | undefined;
       try {
-        watcher?.close();
+        watcher = watch(file, () => {
+          void check();
+        });
       } catch {
-        // ignore
+        // file may not exist; polling will handle
       }
-      clearTimeout(t);
-      resolve({ changed });
-    };
-
-    const check = async () => {
-      const sz = await fileSize(file);
-      if (sz > startSize) finish(true);
-    };
-
-    let watcher: ReturnType<typeof watch> | undefined;
-    try {
-      watcher = watch(file, () => {
-        void check();
-      });
-    } catch {
-      // file may not exist; polling will handle
-    }
-    const poll = setInterval(() => void check(), 500);
-    const t = setTimeout(() => finish(false), timeout);
-  });
+      const poll = setInterval(() => void check(), 500);
+      const t = setTimeout(() => finish(false), remaining);
+    });
 
-  if (!result.changed) {
-    return { ok: false, timedOut: true };
+    if (!changed) break;
+    const result = await readMessagesTool({ agentId: args.agentId, source: args.source });
+    if (result.returned > 0) return result;
+    // otherwise, only self-posts arrived; keep waiting on the remaining budget
   }
-  return readMessagesTool({ agentId: args.agentId, source: args.source });
+
+  return { ok: false, timedOut: true };
 }
 
 // ---------- prune ----------
@@ -384,6 +492,255 @@ export async function pruneTool(args: {
   };
 }
 
+// ---------- attach_agent / detach_agent (tmux push transport) ----------
+
+export const attachAgentSchema = {
+  agentId: z.string().min(1),
+  tmuxTarget: z.string().optional(),
+  includeRoom: z.boolean().optional(),
+  allowlist: z.array(z.string()).optional(),
+  debounceMs: z.number().int().positive().max(60_000).optional(),
+};
+
+export async function attachAgentTool(args: {
+  agentId: string;
+  tmuxTarget?: string;
+  includeRoom?: boolean;
+  allowlist?: string[];
+  debounceMs?: number;
+}) {
+  // Resolve target: explicit arg > MCP server's own TMUX_PANE env.
+  const target = args.tmuxTarget ?? process.env.TMUX_PANE;
+  if (!target) {
+    return {
+      ok: false,
+      error:
+        "tmuxTarget not provided and the MCP server is not running inside tmux (no $TMUX_PANE). Pass tmuxTarget explicitly (e.g. '%42' or 'session:window.pane').",
+    };
+  }
+
+  // Validate target exists.
+  const probe = spawnSync("tmux", ["display-message", "-p", "-t", target, "ok"]);
+  if (probe.status !== 0) {
+    return {
+      ok: false,
+      error: `tmux target '${target}' not found: ${(probe.stderr ?? "").toString().trim()}`,
+    };
+  }
+
+  // If something's already attached, refuse rather than spawn a second pusher.
+  const existing = await readJson<TransportMarker | null>(transportFile(args.agentId), null);
+  if (existing && isPidAlive(existing.pid)) {
+    return {
+      ok: false,
+      error: `agent '${args.agentId}' already has a live ${existing.transport} attached (pid ${existing.pid}). Call detach_agent first.`,
+      existing,
+    };
+  }
+  // Clean up dead marker, if any.
+  if (existing) await deleteFile(transportFile(args.agentId));
+
+  const pusher = resolvePusherPath();
+  if (!existsSync(pusher)) {
+    return { ok: false, error: `tmux-pusher not found at ${pusher}` };
+  }
+
+  // Detached spawn so the pusher outlives this MCP request/process.
+  const log = logFile(args.agentId, "pusher");
+  await fsp.mkdir(path.dirname(log), { recursive: true });
+  await fsp.mkdir(path.dirname(pidFile(args.agentId, "pusher")), { recursive: true });
+  await fsp.mkdir(path.dirname(transportFile(args.agentId)), { recursive: true });
+  const out = openSync(log, "a");
+  const err = openSync(log, "a");
+  const child = spawn("node", [pusher], {
+    detached: true,
+    stdio: ["ignore", out, err],
+    env: {
+      ...process.env,
+      AGENT_COORD_ID: args.agentId,
+      AGENT_COORD_TMUX_TARGET: target,
+      ...(args.includeRoom ? { AGENT_COORD_INCLUDE_ROOM: "1" } : {}),
+      ...(args.allowlist && args.allowlist.length > 0
+        ? { AGENT_COORD_ALLOWLIST: args.allowlist.join(",") }
+        : {}),
+      ...(args.debounceMs ? { AGENT_COORD_DEBOUNCE_MS: String(args.debounceMs) } : {}),
+    },
+  });
+  child.unref();
+  const pid = child.pid;
+  if (!pid) return { ok: false, error: "spawn returned no pid" };
+
+  // Write pid file (for scripts) and transport marker (for list_agents).
+  await fsp.writeFile(pidFile(args.agentId, "pusher"), String(pid), "utf8");
+  const marker: TransportMarker = {
+    agentId: args.agentId,
+    transport: "tmux-push",
+    pid,
+    tmuxTarget: target,
+    since: Date.now(),
+  };
+  // Use updateJson so it lockfile-protects and creates the file atomically.
+  await updateJson<TransportMarker>(transportFile(args.agentId), marker, () => marker);
+
+  // Best-effort scan for a peek-coord.mjs hook wired to the same agentId —
+  // both consumers share the cursor file and would race / double-deliver.
+  const conflictingHook = await detectPeekCoordHook(args.agentId);
+
+  return {
+    ok: true,
+    agentId: args.agentId,
+    transport: "tmux-push",
+    tmuxTarget: target,
+    pid,
+    log,
+    ...(conflictingHook
+      ? {
+          warnings: [
+            `peek-coord.mjs hook for agentId='${args.agentId}' detected in ${conflictingHook}. ` +
+              `Running both transports causes double-delivery — disable one. ` +
+              `Recommend removing the peek-coord hook entry since tmux-push supersedes it.`,
+          ],
+        }
+      : {}),
+  };
+}
+
+async function detectPeekCoordHook(agentId: string): Promise<string | undefined> {
+  const home = process.env.HOME ?? "";
+  const cwd = process.cwd();
+  const candidates = [
+    path.join(home, ".claude", "settings.json"),
+    path.join(home, ".claude", "settings.local.json"),
+    path.join(cwd, ".claude", "settings.json"),
+    path.join(cwd, ".claude", "settings.local.json"),
+  ];
+  for (const file of candidates) {
+    if (!existsSync(file)) continue;
+    try {
+      const raw = await fsp.readFile(file, "utf8");
+      if (raw.includes("peek-coord.mjs") && raw.includes(`AGENT_COORD_ID=${agentId}`)) {
+        return file;
+      }
+    } catch {
+      // unreadable, skip
+    }
+  }
+  return undefined;
+}
+
+export const detachAgentSchema = {
+  agentId: z.string().min(1),
+};
+
+export async function detachAgentTool(args: { agentId: string }) {
+  const marker = await readJson<TransportMarker | null>(transportFile(args.agentId), null);
+  let killed = false;
+  if (marker && isPidAlive(marker.pid)) {
+    try {
+      process.kill(marker.pid, "SIGTERM");
+      killed = true;
+    } catch {
+      // already gone
+    }
+  }
+  await deleteFile(transportFile(args.agentId));
+  await deleteFile(pidFile(args.agentId, "pusher"));
+  return { ok: true, agentId: args.agentId, killed, hadMarker: marker !== null };
+}
+
+function resolvePusherPath(): string {
+  // tools.js (compiled) lives in dist/; pusher lives in hooks/ at repo root.
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "..", "hooks", "tmux-pusher.mjs");
+}
+
+// ---------- status / whoami ----------
+
+export const statusSchema = { agentId: z.string().min(1) };
+
+export async function statusTool(args: { agentId: string }) {
+  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
+  const entry = reg[args.agentId];
+  const transports = await loadLiveTransports();
+  const transport = transports.get(args.agentId);
+  const inbox = await readJsonl<Message>(inboxFile(args.agentId));
+  const cursor = await readJson<Cursor>(cursorFile(args.agentId), {});
+  const inboxOffset = cursor.inboxOffset ?? 0;
+  const unread = Math.max(0, inbox.length - inboxOffset);
+  return {
+    agentId: args.agentId,
+    registered: !!entry,
+    entry,
+    attached: !!transport,
+    transport,
+    inboxDepth: inbox.length,
+    inboxUnread: unread,
+    inTmux: !!process.env.TMUX_PANE,
+    tmuxPane: process.env.TMUX_PANE,
+  };
+}
+
+// ---------- join (combo: register + auto-attach + read inbox) ----------
+
+const joinAttachOptionsSchema = z.object({
+  tmuxTarget: z.string().optional(),
+  includeRoom: z.boolean().optional(),
+  allowlist: z.array(z.string()).optional(),
+  debounceMs: z.number().int().positive().max(60_000).optional(),
+});
+
+export const joinSchema = {
+  agentId: z.string().min(1),
+  project: z.string().optional(),
+  role: z.string().optional(),
+  // attach: undefined → auto-attach if $TMUX_PANE is set; true → always try;
+  // false → never; object → attach with overrides.
+  attach: z.union([z.boolean(), joinAttachOptionsSchema]).optional(),
+  readInbox: z.boolean().optional(),
+};
+
+export async function joinTool(args: {
+  agentId: string;
+  project?: string;
+  role?: string;
+  attach?: boolean | { tmuxTarget?: string; includeRoom?: boolean; allowlist?: string[]; debounceMs?: number };
+  readInbox?: boolean;
+}) {
+  const reg = await registerTool({
+    agentId: args.agentId,
+    project: args.project,
+    role: args.role,
+  });
+
+  // Decide attach behavior.
+  const wantAttach = args.attach === false
+    ? false
+    : args.attach === true || typeof args.attach === "object"
+      ? true
+      : !!process.env.TMUX_PANE; // undefined → auto-detect
+
+  let attach: Awaited<ReturnType<typeof attachAgentTool>> | undefined;
+  if (wantAttach) {
+    const opts = typeof args.attach === "object" ? args.attach : {};
+    attach = await attachAgentTool({ agentId: args.agentId, ...opts });
+  }
+
+  const readInbox = args.readInbox ?? true;
+  let inbox: Awaited<ReturnType<typeof readMessagesTool>> | undefined;
+  if (readInbox) {
+    inbox = await readMessagesTool({ agentId: args.agentId, source: "inbox" });
+  }
+
+  return {
+    ok: true,
+    registered: reg.agent,
+    attached: !!attach && attach.ok !== false,
+    attach,
+    inbox,
+    inTmux: !!process.env.TMUX_PANE,
+  };
+}
+
 // ---------- helpers ----------
 
 function sourceFile(source: "inbox" | "room" | "status", agentId: string): string {