agent-coord-mcp 0.7.1 → 0.8.0

package/src/tools.ts

@@ -10,6 +10,9 @@ import {
   CURSOR_DIR,
   DEFAULT_ROOM,
   INBOX_DIR,
+  ROOT,
+  ROOM_FILE,
+  ROOMS_DIR,
   ROOMS_FILE,
   STATUS_FILE,
   addMember,
@@ -71,6 +74,10 @@ type Message = {
   text: string;
   // System notices (join/part/topic/nick) — rendered distinctly by clients.
   system?: boolean;
+  // Control commands (`/clear`, `/compact`) addressed at the agent's CLI, not
+  // its operator. The tmux pushers inject these RAW (no banner/prefix) so the
+  // TUI runs them as real slash commands; every other consumer ignores them.
+  control?: boolean;
 };
 
 type StatusEntry = {
@@ -245,26 +252,12 @@ export async function listAgentsTool() {
 
 async function loadLiveTransports(): Promise<Map<string, TransportMarker>> {
   const out = new Map<string, TransportMarker>();
-  // For remote markers we can't pid-check the foreign process — instead we trust
-  // the registry's lastHeartbeat, which the remote pusher refreshes every minute.
   const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
   const now = Date.now();
   for (const fname of await listTransportFiles()) {
     const file = path.join(TRANSPORT_DIR, fname);
     const marker = await readJson<TransportMarker | null>(file, null);
-    if (!marker) {
-      await deleteFile(file);
-      continue;
-    }
-    const isRemote = marker.transport === "tmux-push-remote";
-    if (isRemote) {
-      const entry = reg[marker.agentId];
-      const fresh = !!entry && now - entry.lastHeartbeat < STALE_MS;
-      if (!fresh) {
-        await deleteFile(file);
-        continue;
-      }
-    } else if (!isPidAlive(marker.pid)) {
+    if (!marker || !isMarkerLive(marker, reg, now)) {
       await deleteFile(file);
       continue;
     }
@@ -273,6 +266,17 @@ async function loadLiveTransports(): Promise<Map<string, TransportMarker>> {
   return out;
 }
 
+// Liveness for a transport marker. Local markers carry a real pid we can probe;
+// remote markers (tmux-push-remote, pid 0 on a foreign host) can't be — so we
+// trust the registry heartbeat the remote pusher refreshes (within STALE_MS).
+function isMarkerLive(marker: TransportMarker, reg: AgentRegistry, now: number): boolean {
+  if (marker.transport === "tmux-push-remote") {
+    const entry = reg[marker.agentId];
+    return !!entry && now - entry.lastHeartbeat < STALE_MS;
+  }
+  return isPidAlive(marker.pid);
+}
+
 function isPidAlive(pid: number): boolean {
   if (!pid || pid <= 0) return false;
   try {
@@ -335,6 +339,123 @@ export async function sendMessageTool(args: {
   return { ok: true, id: msg.id, target, room: chan };
 }
 
+// ---------- send_command (context-management control commands) ----------
+
+// The only slash commands a lead may inject into a sub-agent's CLI. Locked on
+// purpose: these wipe/compact context (cheap, reversible-by-the-agent), nothing
+// that mutates the repo or the bus. Stored WITHOUT the leading slash; the wire
+// text is `/${cmd}`.
+export const CONTROL_COMMANDS = ["clear", "compact"] as const;
+
+// Transports whose pusher can actually TYPE a slash command into a live CLI.
+// A control command is meaningless to a plain MCP poller, so send_command is
+// gated to agents currently attached over one of these.
+const TMUX_TRANSPORTS = new Set(["tmux-push", "tmux-push-remote"]);
+
+// Normalize "clear" / "/clear" / "  /Clear " → "clear"; null if not allowlisted.
+function normalizeControlCommand(raw: string): string | null {
+  const c = raw.trim().replace(/^\/+/, "").toLowerCase();
+  return (CONTROL_COMMANDS as readonly string[]).includes(c) ? c : null;
+}
+
+// Live transports filtered to the tmux-push family (local + remote).
+async function liveTmuxTargets(): Promise<Map<string, TransportMarker>> {
+  const all = await loadLiveTransports();
+  const out = new Map<string, TransportMarker>();
+  for (const [id, m] of all) if (TMUX_TRANSPORTS.has(m.transport)) out.set(id, m);
+  return out;
+}
+
+export const sendCommandSchema = {
+  from: z.string().min(1),
+  to: z.string().optional(),
+  room: z.string().optional(),
+  command: z.string().min(1),
+};
+
+// Inject a context-management slash command into a sub-agent's live tmux
+// session. Writes a control-flagged message the pushers deliver RAW (no banner,
+// no `[DM …]` prefix) so the receiving CLI runs it as a real slash command.
+// Hard-gated to tmux: refuses unless the target(s) have a live tmux-push(-remote)
+// transport, so a command never rots unexecuted in an offline inbox.
+export async function sendCommandTool(args: {
+  from: string;
+  to?: string;
+  room?: string;
+  command: string;
+}) {
+  const cmd = normalizeControlCommand(args.command);
+  if (!cmd) {
+    return {
+      ok: false,
+      error: `unsupported command '${args.command}'. Allowed: ${CONTROL_COMMANDS.map((c) => "/" + c).join(", ")}`,
+    };
+  }
+  if (!args.to && !args.room) {
+    return { ok: false, error: "specify 'to' (a single agent) or 'room' (a channel's tmux-attached members)" };
+  }
+  if (args.to && args.room) {
+    return { ok: false, error: "specify only one of 'to' or 'room'" };
+  }
+
+  const text = `/${cmd}`;
+  const liveTmux = await liveTmuxTargets();
+
+  // DM: target must itself be tmux-attached.
+  if (args.to) {
+    const marker = liveTmux.get(args.to);
+    if (!marker) {
+      return {
+        ok: false,
+        error: `'${args.to}' has no live tmux-push transport — control commands can only be injected into a tmux session. Attach it (join/attach_agent) or target an attached agent.`,
+      };
+    }
+    const msg: Message = {
+      id: randomUUID(),
+      ts: Date.now(),
+      from: args.from,
+      to: args.to,
+      text,
+      control: true,
+    };
+    const target = inboxFile(args.to);
+    await appendJsonl(target, msg);
+    return { ok: true, id: msg.id, command: text, target, delivered: [args.to], transport: marker.transport };
+  }
+
+  // Room: broadcast to every tmux-attached member (never the sender itself).
+  const chan = normalizeRoom(args.room);
+  const rooms = await getRooms();
+  const members = rooms[chan]?.members ?? [];
+  const delivered = members.filter((m) => m !== args.from && liveTmux.has(m));
+  if (delivered.length === 0) {
+    return {
+      ok: false,
+      error: `no tmux-attached members in #${chan} to receive '${text}' (${members.length} member(s) total). Control commands only fire in a live tmux session.`,
+    };
+  }
+  const skipped = members.filter((m) => m !== args.from && !liveTmux.has(m));
+  const msg: Message = {
+    id: randomUUID(),
+    ts: Date.now(),
+    from: args.from,
+    room: chan,
+    text,
+    control: true,
+  };
+  const target = roomFile(chan);
+  await appendJsonl(target, msg);
+  return {
+    ok: true,
+    id: msg.id,
+    command: text,
+    target,
+    room: chan,
+    delivered,
+    skipped: skipped.length ? skipped : undefined,
+  };
+}
+
 // ---------- read_messages ----------
 
 export const readMessagesSchema = {
@@ -1121,6 +1242,379 @@ export async function clearTransportTool(args: { agentId: string }) {
   return { ok: true, removed };
 }
 
+// ---------- doctor (bus-wide health check) ----------
+
+type DoctorLevel = "ok" | "warn" | "error";
+type DoctorFinding = {
+  check: string;
+  level: DoctorLevel;
+  detail: string;
+  fixable: boolean;
+  items?: string[];
+};
+
+// Count non-empty lines vs successfully-parsed entries in a JSONL file.
+// Offsets index the PARSED entries (see readJsonl), so `parsed` is the figure
+// cursor math is compared against; `malformed` is the desync risk.
+async function scanJsonl(file: string): Promise<{ lines: number; parsed: number; malformed: number }> {
+  if (!existsSync(file)) return { lines: 0, parsed: 0, malformed: 0 };
+  const raw = await fsp.readFile(file, "utf8");
+  let lines = 0;
+  let parsed = 0;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    lines++;
+    try {
+      JSON.parse(line);
+      parsed++;
+    } catch {
+      // malformed
+    }
+  }
+  return { lines, parsed, malformed: lines - parsed };
+}
+
+// Find leftover proper-lockfile lock dirs (`<file>.lock`) across the state
+// dirs. Anything older than the threshold is almost certainly orphaned by a
+// crashed writer (withLock's stale window is 5s).
+async function scanStaleLocks(olderThanMs: number, now: number): Promise<{ path: string; ageMs: number }[]> {
+  const out: { path: string; ageMs: number }[] = [];
+  const dirs = [ROOT, INBOX_DIR, CURSOR_DIR, ROOMS_DIR, TRANSPORT_DIR];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    let names: string[];
+    try {
+      names = await fsp.readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      if (!name.endsWith(".lock")) continue;
+      const p = path.join(dir, name);
+      try {
+        const st = await fsp.stat(p);
+        const ageMs = now - st.mtimeMs;
+        if (ageMs > olderThanMs) out.push({ path: p, ageMs });
+      } catch {
+        // vanished mid-scan
+      }
+    }
+  }
+  return out;
+}
+
+export const doctorSchema = {
+  fix: z.boolean().optional(),
+  maxFileBytes: z.number().int().positive().optional(),
+};
+
+export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number }) {
+  const fix = args.fix ?? false;
+  const maxBytes = args.maxFileBytes ?? 5 * 1024 * 1024;
+  const now = Date.now();
+  const findings: DoctorFinding[] = [];
+  const fixed: string[] = [];
+
+  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
+  const known = new Set(Object.keys(reg));
+  const rooms = await getRooms();
+  const channels = Object.keys(rooms);
+
+  // 1. Orphan transport markers (dead local pid, or stale remote heartbeat).
+  {
+    const dead: string[] = [];
+    for (const fname of await listTransportFiles()) {
+      const file = path.join(TRANSPORT_DIR, fname);
+      const marker = await readJson<TransportMarker | null>(file, null);
+      if (!marker || !isMarkerLive(marker, reg, now)) {
+        dead.push(file);
+        if (fix) {
+          await deleteFile(file);
+          fixed.push(`deleted stale transport marker ${fname}`);
+        }
+      }
+    }
+    findings.push({
+      check: "orphan-transport-markers",
+      level: dead.length ? "warn" : "ok",
+      detail: dead.length ? `${dead.length} stale transport marker(s) (dead pid or expired remote heartbeat)` : "no stale transport markers",
+      fixable: true,
+      items: dead.length ? dead.map((f) => path.basename(f)) : undefined,
+    });
+  }
+
+  // 2. Orphan room memberships (member not in the registry).
+  {
+    const orphans = new Set<string>();
+    for (const e of Object.values(rooms)) {
+      for (const m of e.members ?? []) if (!known.has(m)) orphans.add(m);
+    }
+    if (fix && orphans.size) {
+      await updateJson<RoomRegistry>(ROOMS_FILE, {}, (cur) => {
+        for (const e of Object.values(cur)) {
+          if (e.members?.length) e.members = e.members.filter((m) => known.has(m));
+        }
+        return cur;
+      });
+      fixed.push(`dropped ${orphans.size} orphan membership(s): ${[...orphans].join(", ")}`);
+    }
+    findings.push({
+      check: "orphan-room-memberships",
+      level: orphans.size ? "warn" : "ok",
+      detail: orphans.size ? `${orphans.size} channel member(s) not in the registry` : "all channel members are registered",
+      fixable: true,
+      items: orphans.size ? [...orphans] : undefined,
+    });
+  }
+
+  // 3. Orphan inbox / cursor files (owner not registered).
+  {
+    const orphanInbox: string[] = [];
+    for (const fname of await listInboxFiles()) {
+      const id = fname.replace(/\.jsonl$/, "");
+      if (!known.has(id)) {
+        orphanInbox.push(id);
+        if (fix) {
+          await deleteFile(path.join(INBOX_DIR, fname));
+          fixed.push(`deleted orphan inbox ${fname}`);
+        }
+      }
+    }
+    const orphanCursor: string[] = [];
+    for (const fname of await listCursorFiles()) {
+      const id = fname.replace(/\.json$/, "");
+      if (!known.has(id)) {
+        orphanCursor.push(id);
+        if (fix) {
+          await deleteFile(path.join(CURSOR_DIR, fname));
+          fixed.push(`deleted orphan cursor ${fname}`);
+        }
+      }
+    }
+    const total = orphanInbox.length + orphanCursor.length;
+    findings.push({
+      check: "orphan-inboxes-cursors",
+      level: total ? "warn" : "ok",
+      detail: total
+        ? `${orphanInbox.length} inbox + ${orphanCursor.length} cursor file(s) for unregistered ids`
+        : "no orphan inbox/cursor files",
+      fixable: true,
+      items: total ? [...new Set([...orphanInbox, ...orphanCursor])] : undefined,
+    });
+  }
+
+  // Precompute parsed line counts for cursor + malformed checks.
+  const counts = new Map<string, { lines: number; parsed: number; malformed: number }>();
+  const countFor = async (file: string) => {
+    if (!counts.has(file)) counts.set(file, await scanJsonl(file));
+    return counts.get(file)!;
+  };
+
+  // 4. Cursor offsets past end-of-file (would return [] forever).
+  {
+    const broken: string[] = [];
+    for (const fname of await listCursorFiles()) {
+      const id = fname.replace(/\.json$/, "");
+      const cursorPath = path.join(CURSOR_DIR, fname);
+      const cursor = await readJson<Cursor>(cursorPath, {});
+      const overflow: string[] = [];
+      const inboxMax = (await countFor(inboxFile(id))).parsed;
+      if ((cursor.inboxOffset ?? 0) > inboxMax) overflow.push(`inboxOffset ${cursor.inboxOffset}>${inboxMax}`);
+      const roomMax = (await countFor(ROOM_FILE)).parsed;
+      if ((cursor.roomOffset ?? 0) > roomMax) overflow.push(`roomOffset ${cursor.roomOffset}>${roomMax}`);
+      const statusMax = (await countFor(STATUS_FILE)).parsed;
+      if ((cursor.statusOffset ?? 0) > statusMax) overflow.push(`statusOffset ${cursor.statusOffset}>${statusMax}`);
+      for (const [chan, off] of Object.entries(cursor.roomOffsets ?? {})) {
+        const max = (await countFor(roomFile(chan))).parsed;
+        if (off > max) overflow.push(`roomOffsets[${chan}] ${off}>${max}`);
+      }
+      if (overflow.length) {
+        broken.push(`${id}: ${overflow.join(", ")}`);
+        if (fix) {
+          await updateJson<Cursor>(cursorPath, {}, (c) => {
+            if ((c.inboxOffset ?? 0) > inboxMax) c.inboxOffset = inboxMax;
+            if ((c.roomOffset ?? 0) > roomMax) c.roomOffset = roomMax;
+            if ((c.statusOffset ?? 0) > statusMax) c.statusOffset = statusMax;
+            if (c.roomOffsets) {
+              for (const chan of Object.keys(c.roomOffsets)) {
+                const max = counts.get(roomFile(chan))?.parsed ?? 0;
+                if (c.roomOffsets[chan] > max) c.roomOffsets[chan] = max;
+              }
+            }
+            return c;
+          });
+          fixed.push(`clamped cursor offsets for ${id}`);
+        }
+      }
+    }
+    findings.push({
+      check: "cursor-past-eof",
+      level: broken.length ? "error" : "ok",
+      detail: broken.length ? `${broken.length} cursor(s) with an offset past EOF — delivery stalled` : "all cursor offsets are within bounds",
+      fixable: true,
+      items: broken.length ? broken : undefined,
+    });
+  }
+
+  // 5. Malformed JSONL lines (silently desync offset math between server + hooks).
+  {
+    const jsonlFiles = [
+      ROOM_FILE,
+      STATUS_FILE,
+      ...channels.filter((c) => c !== DEFAULT_ROOM).map((c) => roomFile(c)),
+      ...(await listInboxFiles()).map((f) => path.join(INBOX_DIR, f)),
+    ];
+    const bad: string[] = [];
+    for (const file of jsonlFiles) {
+      const c = await countFor(file);
+      if (c.malformed > 0) {
+        bad.push(`${path.basename(file)} (${c.malformed})`);
+        if (fix) {
+          await fsp.copyFile(file, file + ".bak");
+          await rewriteJsonl(file, () => true); // drops unparseable lines
+          fixed.push(`rewrote ${path.basename(file)} dropping ${c.malformed} malformed line(s) (backup: ${path.basename(file)}.bak)`);
+        }
+      }
+    }
+    findings.push({
+      check: "malformed-jsonl",
+      level: bad.length ? "warn" : "ok",
+      detail: bad.length ? `${bad.length} file(s) contain unparseable lines` : "no malformed JSONL lines",
+      fixable: true,
+      items: bad.length ? bad : undefined,
+    });
+  }
+
+  // 6. Stale agents (registered, no live transport, heartbeat past EVICT_MS). Report only.
+  {
+    // Compute liveness WITHOUT deleting dead markers — loadLiveTransports
+    // prunes as a side effect, which would make this read-only check mutate
+    // state (and pre-empt the orphan-marker fix in check 1).
+    const live = new Set<string>();
+    for (const fname of await listTransportFiles()) {
+      const marker = await readJson<TransportMarker | null>(path.join(TRANSPORT_DIR, fname), null);
+      if (marker && isMarkerLive(marker, reg, now)) live.add(marker.agentId);
+    }
+    const stale: string[] = [];
+    for (const [id, a] of Object.entries(reg)) {
+      if (live.has(id)) continue;
+      if (now - a.lastHeartbeat > EVICT_MS) stale.push(`${id} (${Math.floor((now - a.lastHeartbeat) / 3600000)}h)`);
+    }
+    findings.push({
+      check: "stale-agents",
+      level: stale.length ? "warn" : "ok",
+      detail: stale.length ? `${stale.length} agent(s) past the eviction window — next list_agents will drop them` : "no stale agents",
+      fixable: false,
+      items: stale.length ? stale : undefined,
+    });
+  }
+
+  // 7. Oversized JSONL files. Report only (suggest prune).
+  {
+    const big: string[] = [];
+    const candidates = [
+      ROOM_FILE,
+      STATUS_FILE,
+      ...channels.filter((c) => c !== DEFAULT_ROOM).map((c) => roomFile(c)),
+      ...(await listInboxFiles()).map((f) => path.join(INBOX_DIR, f)),
+    ];
+    for (const file of candidates) {
+      const sz = await fileSize(file);
+      if (sz > maxBytes) big.push(`${path.basename(file)} (${(sz / 1024 / 1024).toFixed(1)}MB)`);
+    }
+    findings.push({
+      check: "oversized-files",
+      level: big.length ? "warn" : "ok",
+      detail: big.length ? `${big.length} file(s) over ${(maxBytes / 1024 / 1024).toFixed(0)}MB — consider prune` : "no oversized files",
+      fixable: false,
+      items: big.length ? big : undefined,
+    });
+  }
+
+  // 8. Stale lock dirs from crashed writers.
+  {
+    const locks = await scanStaleLocks(60_000, now);
+    for (const l of locks) {
+      if (fix) {
+        try {
+          await fsp.rm(l.path, { recursive: true, force: true });
+          fixed.push(`removed stale lock ${path.basename(l.path)}`);
+        } catch {
+          // ignore
+        }
+      }
+    }
+    findings.push({
+      check: "stale-locks",
+      level: locks.length ? "warn" : "ok",
+      detail: locks.length ? `${locks.length} lock dir(s) older than 60s — likely from a crashed writer` : "no stale locks",
+      fixable: true,
+      items: locks.length ? locks.map((l) => `${path.basename(l.path)} (${Math.floor(l.ageMs / 1000)}s)`) : undefined,
+    });
+  }
+
+  // 9. Channel/registry consistency: rooms/<chan>.jsonl files without a registry entry.
+  {
+    const orphanFiles: string[] = [];
+    if (existsSync(ROOMS_DIR)) {
+      let names: string[] = [];
+      try {
+        names = await fsp.readdir(ROOMS_DIR);
+      } catch {
+        // ignore
+      }
+      for (const name of names) {
+        if (!name.endsWith(".jsonl")) continue;
+        const chan = name.replace(/\.jsonl$/, "");
+        if (!rooms[chan]) {
+          orphanFiles.push(name);
+          if (fix) {
+            await ensureRoom(chan, "doctor");
+            fixed.push(`registered channel '${chan}' (had a JSONL file but no registry entry)`);
+          }
+        }
+      }
+    }
+    findings.push({
+      check: "channel-registry-consistency",
+      level: orphanFiles.length ? "warn" : "ok",
+      detail: orphanFiles.length ? `${orphanFiles.length} channel file(s) with no registry entry` : "channel files and registry agree",
+      fixable: true,
+      items: orphanFiles.length ? orphanFiles : undefined,
+    });
+  }
+
+  // 10. Environment sanity. Report only.
+  {
+    const tmuxProbe = spawnSync("tmux", ["-V"]);
+    const tmuxOk = tmuxProbe.status === 0;
+    findings.push({
+      check: "environment",
+      level: tmuxOk ? "ok" : "warn",
+      detail: tmuxOk
+        ? `root=${ROOT}; node=${process.execPath}; tmux=${(tmuxProbe.stdout ?? "").toString().trim() || "present"}`
+        : `root=${ROOT}; node=${process.execPath}; tmux NOT on PATH — the tmux-push transport will not work`,
+      fixable: false,
+      items: [`root=${ROOT}`, `execPath=${process.execPath}`, `inTmux=${!!process.env.TMUX_PANE}`],
+    });
+  }
+
+  const summary = {
+    ok: findings.filter((f) => f.level === "ok").length,
+    warn: findings.filter((f) => f.level === "warn").length,
+    error: findings.filter((f) => f.level === "error").length,
+  };
+  return {
+    ok: true,
+    healthy: summary.warn === 0 && summary.error === 0,
+    fixApplied: fix,
+    root: ROOT,
+    findings,
+    fixed: fix ? fixed : undefined,
+    summary,
+  };
+}
+
 // ---------- helpers ----------
 
 async function moveFile(from: string, to: string): Promise<boolean> {