agent-coord-mcp 0.14.0 → 0.16.0

package/src/server.ts

@@ -62,7 +62,7 @@ import {
   quitTool,
   waitForMessageSchema,
   waitForMessageTool,
-} from "./tools.js";
+} from "./tools/index.js";
 
 function jsonResult(data: unknown) {
   return {
@@ -186,7 +186,7 @@ function buildServer(initialBound?: string): McpServer {
 
   server.tool(
     "send_message",
-    "Send a message. If 'to' is set, goes to that agent's inbox (DM); otherwise to a channel — pass 'room' (e.g. 'seo' or '#seo') to target a specific channel, or omit it for the default 'general' channel. The 'from' field is enforced against the session's bound identity when binding is configured.",
+    "Send a message. If 'to' is set, goes to that agent's inbox (DM); otherwise to a channel — pass 'room' (e.g. 'seo' or '#seo') to target a specific channel, or omit it for the default 'general' channel. For channel posts, tag 'kind': 'decision' for GOs/verdicts/agreements that must outlive routine cleanup (kept ~30 days, quoted verbatim in digests), 'status' for progress notes, omit for ordinary chatter. The 'from' field is enforced against the session's bound identity when binding is configured.",
     sendMessageSchema,
     gate("from", sendMessageTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
@@ -221,7 +221,7 @@ function buildServer(initialBound?: string): McpServer {
 
   server.tool(
     "prune",
-    "Trim room/status/inbox JSONL to entries newer than `olderThanDays` (default 7). Removes inbox files for agents no longer in the registry unless removeOrphanInboxes=false. Pass dryRun=true to preview.",
+    "Trim room/status/inbox JSONL to entries newer than `olderThanDays` (default 7); kind='decision' posts keep a longer `decisionDays` retention (default 30). Nothing is lost: aged-out entries are archived under archive/ (rooms/<chan>.jsonl, status.jsonl, inbox/<agent>.jsonl) — only receipts are truly deleted. Pass `room` to prune a single channel, or `targets` (rooms|status|inbox|receipts|members) to narrow the sweep. Sweeps room members that are unregistered or haven't heartbeated since the cutoff, and archives+removes non-default rooms left empty and inactive (disable via archiveEmptyRooms=false). Removes inbox files for agents no longer in the registry unless removeOrphanInboxes=false. Pass dryRun=true to preview.",
     pruneSchema,
     gate(null, pruneTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
@@ -422,12 +422,41 @@ async function startHttp(port: number): Promise<void> {
   const bindAddr = process.env.AGENT_COORD_BIND ?? "127.0.0.1";
   const sharedExpected = sharedToken ? `Bearer ${sharedToken}` : null;
 
+  // Fail-closed network gate. A non-loopback bind is a real network listener, so
+  // it must have (a) enforced per-agent identity and (b) a secured transport. We
+  // refuse rather than warn: a shared/advisory token lets any node impersonate
+  // any agent, and plaintext leaks bearer tokens to anyone on the path.
+  const isLoopbackBind =
+    bindAddr === "127.0.0.1" || bindAddr === "localhost" || bindAddr === "::1";
+  if (!isLoopbackBind) {
+    if (!bound) {
+      console.error(
+        `[agent-coord-mcp] refusing to bind ${bindAddr} without per-agent tokens: a ` +
+          `shared/advisory token lets any node impersonate any agent. Create ` +
+          `~/agent-coord/tokens.json (per-agent, enforced identity) for network binds.`,
+      );
+      process.exit(1);
+    }
+    if (process.env.AGENT_COORD_INSECURE !== "1") {
+      console.error(
+        `[agent-coord-mcp] refusing plaintext bind to ${bindAddr}: bearer tokens would ` +
+          `travel in cleartext. Put the bus behind TLS or a private overlay ` +
+          `(Tailscale/WireGuard), then set AGENT_COORD_INSECURE=1 to acknowledge the ` +
+          `transport is secured out-of-band.`,
+      );
+      process.exit(1);
+    }
+  }
+
   // One transport+server pair per client session. The SDK exposes session
   // affinity via the `mcp-session-id` header: a new request without it is
   // an init (create new pair); follow-ups carry the id (look up the pair).
   // We cannot share one stateful transport across clients (it errors with
   // "Server already initialized"), and stateless mode rejects reuse.
   const sessions = new Map<string, StreamableHTTPServerTransport>();
+  // Which bound agent each session id belongs to, so a session can't be driven
+  // by a *different* bearer that merely presents its id (session hijack).
+  const sessionAgents = new Map<string, string | undefined>();
 
   async function makeSessionTransport(boundAgent?: string): Promise<StreamableHTTPServerTransport> {
     // `let` + explicit type lets the SDK callbacks close over the binding
@@ -435,10 +464,16 @@ async function startHttp(port: number): Promise<void> {
     let transport: StreamableHTTPServerTransport;
     transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: () => randomUUID(),
-      onsessioninitialized: (id: string) => { sessions.set(id, transport); },
+      onsessioninitialized: (id: string) => {
+        sessions.set(id, transport);
+        sessionAgents.set(id, boundAgent);
+      },
     });
     transport.onclose = () => {
-      if (transport.sessionId) sessions.delete(transport.sessionId);
+      if (transport.sessionId) {
+        sessions.delete(transport.sessionId);
+        sessionAgents.delete(transport.sessionId);
+      }
     };
     const server = buildServer(boundAgent);
     await server.connect(transport);
@@ -487,6 +522,20 @@ async function startHttp(port: number): Promise<void> {
       // bearer's agent; anything else is a protocol error.
       const sid = req.headers["mcp-session-id"];
       let transport = typeof sid === "string" ? sessions.get(sid) : undefined;
+      // Re-bind check: a session is pinned to the agent whose bearer opened it.
+      // In bound mode, reject a request whose bearer resolves to a *different*
+      // agent than the session was created for — otherwise any valid token plus
+      // a leaked session id could drive that session's identity (session hijack).
+      if (
+        transport &&
+        tokenMap &&
+        typeof sid === "string" &&
+        sessionAgents.get(sid) !== resolved.agent
+      ) {
+        res.writeHead(403, { "Content-Type": "text/plain" });
+        res.end("session/identity mismatch\n");
+        return;
+      }
       if (!transport) {
         if (req.method !== "POST") {
           res.writeHead(400, { "Content-Type": "text/plain" });

package/src/store.ts

@@ -44,6 +44,17 @@ export const ROOMS_DIR = path.join(ROOT, "rooms");
 export const ROOMS_FILE = path.join(ROOT, "rooms.json");
 export const DEFAULT_ROOM = "general";
 
+// Cold storage (v0.15.0). Nothing on the bus is ever deleted by prune or
+// compaction — aged-out entries are APPENDED here first, one file per room
+// (general included, despite its live file being the legacy room.jsonl), plus
+// status.jsonl and inbox/<agent>.jsonl. The server never reads these back;
+// they exist for offline analysis of what happened in a room. Receipts are
+// the one exception: delivery proofs carry no analysis value and are deleted.
+export const ARCHIVE_DIR = path.join(ROOT, "archive");
+export const ARCHIVE_ROOMS_DIR = path.join(ARCHIVE_DIR, "rooms");
+export const ARCHIVE_INBOX_DIR = path.join(ARCHIVE_DIR, "inbox");
+export const ARCHIVE_STATUS_FILE = path.join(ARCHIVE_DIR, "status.jsonl");
+
 // Per-agent token map for identity-bound bus auth (v0.7.0). Shape on disk:
 //   { "alice": "tk_<random-secret>", "bob": "tk_<another-secret>" }
 // HTTP transport reverse-looks-up the bearer to bind the session to an
@@ -339,6 +350,57 @@ export async function rewriteJsonl<T>(
   });
 }
 
+// Archive destinations for each live JSONL stream.
+export function archiveRoomFile(chan: string): string {
+  return path.join(ARCHIVE_ROOMS_DIR, `${sanitize(normalizeRoom(chan))}.jsonl`);
+}
+
+export function archiveInboxFile(agentId: string): string {
+  return path.join(ARCHIVE_INBOX_DIR, `${sanitize(agentId)}.jsonl`);
+}
+
+// Like rewriteJsonl, but entries failing the filter are appended to
+// archiveFile instead of discarded. The archive append happens under the
+// source-file lock and BEFORE the rewrite, so a crash mid-operation can at
+// worst duplicate entries into the archive — never lose them. Malformed
+// lines are archived verbatim rather than parsed.
+export async function archiveJsonl<T>(
+  file: string,
+  archiveFile: string,
+  filter: (entry: T) => boolean
+): Promise<{ kept: number; removed: number; archived: number }> {
+  if (!existsSync(file)) return { kept: 0, removed: 0, archived: 0 };
+  return withLock(file, async () => {
+    const raw = await fs.readFile(file, "utf8");
+    let kept = 0;
+    let removed = 0;
+    const keep: string[] = [];
+    const archive: string[] = [];
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const entry = JSON.parse(line) as T;
+        if (filter(entry)) {
+          keep.push(line);
+          kept++;
+        } else {
+          archive.push(line);
+          removed++;
+        }
+      } catch {
+        archive.push(line);
+        removed++;
+      }
+    }
+    if (archive.length) {
+      await fs.mkdir(path.dirname(archiveFile), { recursive: true });
+      await fs.appendFile(archiveFile, archive.join("\n") + "\n", "utf8");
+    }
+    await fs.writeFile(file, keep.length ? keep.join("\n") + "\n" : "", "utf8");
+    return { kept, removed, archived: archive.length };
+  });
+}
+
 export async function deleteFile(file: string): Promise<boolean> {
   if (!existsSync(file)) return false;
   await fs.unlink(file);

package/src/tools/admin.ts

@@ -0,0 +1,347 @@
+import { z } from "zod";
+import path from "node:path";
+import {
+  AGENTS_FILE,
+  ARCHIVE_STATUS_FILE,
+  CURSOR_DIR,
+  DEFAULT_ROOM,
+  INBOX_DIR,
+  ROOMS_FILE,
+  STATUS_FILE,
+  archiveInboxFile,
+  archiveJsonl,
+  archiveRoomFile,
+  deleteFile,
+  getRooms,
+  listCursorFiles,
+  listInboxFiles,
+  listReceiptFiles,
+  normalizeRoom,
+  pruneHistory,
+  readJson,
+  readJsonl,
+  rewriteJsonl,
+  roomFile,
+  updateJson,
+  type RoomRegistry,
+} from "../store.js";
+import {
+  type AgentRegistry,
+  type Cursor,
+  type Message,
+  type StatusEntry,
+} from "./shared.js";
+
+// ---------- prune ----------
+
+export const PRUNE_TARGETS = ["rooms", "status", "inbox", "receipts", "members"] as const;
+export type PruneTarget = (typeof PRUNE_TARGETS)[number];
+
+export const pruneSchema = {
+  olderThanDays: z.number().positive().max(365).optional(),
+  decisionDays: z.number().positive().max(365).optional(),
+  room: z.string().optional(),
+  targets: z.array(z.enum(PRUNE_TARGETS)).optional(),
+  removeOrphanInboxes: z.boolean().optional(),
+  archiveEmptyRooms: z.boolean().optional(),
+  dryRun: z.boolean().optional(),
+};
+
+// Retention predicate: kind="decision" messages live by the (longer)
+// decision cutoff; everything else by the standard cutoff.
+function keepEntry(e: { ts: number; kind?: string }, cutoff: number, decisionCutoff: number): boolean {
+  return e.kind === "decision" ? e.ts > decisionCutoff : e.ts > cutoff;
+}
+
+// Shift every agent's cursor offsets down by the number of entries removed
+// ahead of them (append-only + oldest-first removal ⇒ plain subtraction,
+// clamped at 0). Shared by prune and live compaction — without this, an
+// offset past the new file length makes read_messages return [] forever.
+export async function adjustCursors(removals: {
+  roomRemovedByChan?: Record<string, number>;
+  statusRemoved?: number;
+  perAgentInboxRemoved?: Record<string, number>;
+}): Promise<string[]> {
+  const roomRemovedByChan = removals.roomRemovedByChan ?? {};
+  const statusRemoved = removals.statusRemoved ?? 0;
+  const perAgentInboxRemoved = removals.perAgentInboxRemoved ?? {};
+  const cursorsAdjusted: string[] = [];
+  for (const cname of await listCursorFiles()) {
+    const id = cname.replace(/\.json$/, "");
+    const cursorPath = path.join(CURSOR_DIR, cname);
+    let touched = false;
+    await updateJson<Cursor>(cursorPath, {}, (current) => {
+      for (const [chan, removed] of Object.entries(roomRemovedByChan)) {
+        if (chan === DEFAULT_ROOM) {
+          if (current.roomOffset !== undefined) {
+            current.roomOffset = Math.max(0, current.roomOffset - removed);
+            touched = true;
+          }
+        } else if (current.roomOffsets?.[chan] !== undefined) {
+          current.roomOffsets[chan] = Math.max(0, current.roomOffsets[chan] - removed);
+          touched = true;
+        }
+      }
+      if (current.statusOffset !== undefined && statusRemoved > 0) {
+        current.statusOffset = Math.max(0, current.statusOffset - statusRemoved);
+        touched = true;
+      }
+      const myInboxRemoved = perAgentInboxRemoved[id] ?? 0;
+      if (current.inboxOffset !== undefined && myInboxRemoved > 0) {
+        current.inboxOffset = Math.max(0, current.inboxOffset - myInboxRemoved);
+        touched = true;
+      }
+      return current;
+    });
+    if (touched) cursorsAdjusted.push(id);
+  }
+  return cursorsAdjusted;
+}
+
+export async function pruneTool(args: {
+  olderThanDays?: number;
+  decisionDays?: number;
+  room?: string;
+  targets?: PruneTarget[];
+  removeOrphanInboxes?: boolean;
+  archiveEmptyRooms?: boolean;
+  dryRun?: boolean;
+}) {
+  const days = args.olderThanDays ?? 7;
+  const decisionDays = args.decisionDays ?? 30;
+  const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+  const decisionCutoff = Date.now() - decisionDays * 24 * 60 * 60 * 1000;
+  const dryRun = args.dryRun ?? false;
+  // room-scoped prune touches only that channel's messages; targets narrows
+  // the sweep otherwise. Default remains "everything".
+  const scopedRoom = args.room ? normalizeRoom(args.room) : undefined;
+  const targets = new Set<PruneTarget>(
+    scopedRoom ? ["rooms"] : args.targets ?? [...PRUNE_TARGETS]
+  );
+  const keep = (e: { ts: number; kind?: string }) => keepEntry(e, cutoff, decisionCutoff);
+
+  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
+  const knownAgents = new Set(Object.keys(reg));
+  // A member is stale when its agent is gone from the registry (orphan) or
+  // hasn't heartbeated since the cutoff (dead session).
+  const staleAgent = (m: string) => !knownAgents.has(m) || (reg[m]?.lastHeartbeat ?? 0) <= cutoff;
+
+  const channels = scopedRoom ? [scopedRoom] : Object.keys(await getRooms());
+
+  if (dryRun) {
+    let roomMessages = 0;
+    if (targets.has("rooms")) {
+      for (const chan of channels) {
+        const msgs = await readJsonl<Message>(roomFile(chan));
+        roomMessages += msgs.filter((e) => !keep(e)).length;
+      }
+    }
+    const status = targets.has("status") ? await readJsonl<StatusEntry>(STATUS_FILE) : [];
+    let inboxRemoved = 0;
+    const orphans: string[] = [];
+    if (targets.has("inbox")) {
+      for (const fname of await listInboxFiles()) {
+        const id = fname.replace(/\.jsonl$/, "");
+        if (!knownAgents.has(id) && (args.removeOrphanInboxes ?? true)) orphans.push(fname);
+        const entries = await readJsonl<Message>(path.join(INBOX_DIR, fname));
+        inboxRemoved += entries.filter((e) => e.ts <= cutoff).length;
+      }
+    }
+    const orphanMembers = new Set<string>();
+    const staleMembers = new Set<string>();
+    const emptyRooms: string[] = [];
+    if (targets.has("members")) {
+      const rooms = await getRooms();
+      for (const [chan, e] of Object.entries(rooms)) {
+        const remaining: string[] = [];
+        for (const m of e.members ?? []) {
+          if (!knownAgents.has(m)) orphanMembers.add(m);
+          else if (staleAgent(m)) staleMembers.add(m);
+          else remaining.push(m);
+        }
+        if (
+          (args.archiveEmptyRooms ?? true) &&
+          chan !== DEFAULT_ROOM &&
+          remaining.length === 0
+        ) {
+          const msgs = await readJsonl<Message>(roomFile(chan));
+          const lastTs = msgs[msgs.length - 1]?.ts ?? 0;
+          if (lastTs <= cutoff) emptyRooms.push(chan);
+        }
+      }
+    }
+    let receiptsRemoved = 0;
+    const orphanReceipts: string[] = [];
+    if (targets.has("receipts")) {
+      for (const filePath of await listReceiptFiles()) {
+        const id = path.basename(filePath).replace(/\.jsonl$/, "");
+        const entries = await readJsonl<{ ts: number }>(filePath);
+        if (!knownAgents.has(id) && (args.removeOrphanInboxes ?? true)) orphanReceipts.push(id);
+        receiptsRemoved += entries.filter((e) => e.ts <= cutoff).length;
+      }
+    }
+    return {
+      dryRun: true,
+      cutoff,
+      olderThanDays: days,
+      decisionDays,
+      ...(scopedRoom ? { room: scopedRoom } : {}),
+      wouldRemove: {
+        roomMessages,
+        statusEntries: status.filter((e) => e.ts <= cutoff).length,
+        inboxMessages: inboxRemoved,
+        orphanInboxes: orphans,
+        orphanMembers: [...orphanMembers],
+        staleMembers: [...staleMembers],
+        archivedRooms: emptyRooms,
+        receipts: receiptsRemoved,
+        orphanReceipts,
+      },
+    };
+  }
+
+  // Per-channel removed counts so we can shift the matching offset in each
+  // cursor (default channel → roomOffset, others → roomOffsets[chan]).
+  // Aged-out entries are archived to archive/rooms/<chan>.jsonl, never deleted.
+  const roomRemovedByChan: Record<string, number> = {};
+  let roomRemovedTotal = 0;
+  if (targets.has("rooms")) {
+    for (const chan of channels) {
+      const r = await archiveJsonl<Message>(roomFile(chan), archiveRoomFile(chan), keep);
+      if (r.removed > 0) {
+        roomRemovedByChan[chan] = r.removed;
+        roomRemovedTotal += r.removed;
+      }
+    }
+  }
+  const statusResult = targets.has("status")
+    ? await archiveJsonl<StatusEntry>(STATUS_FILE, ARCHIVE_STATUS_FILE, (e) => e.ts > cutoff)
+    : { kept: 0, removed: 0, archived: 0 };
+
+  let inboxRemoved = 0;
+  const deletedOrphans: string[] = [];
+  // perAgentInboxRemoved: how many entries were stripped from each *kept* agent's
+  // inbox, so we can shift only that agent's inboxOffset cursor below.
+  const perAgentInboxRemoved: Record<string, number> = {};
+  if (targets.has("inbox")) {
+    for (const fname of await listInboxFiles()) {
+      const id = fname.replace(/\.jsonl$/, "");
+      const filePath = path.join(INBOX_DIR, fname);
+      if (!knownAgents.has(id) && (args.removeOrphanInboxes ?? true)) {
+        // Orphan inbox: archive everything it held, then drop the live file.
+        const r = await archiveJsonl<Message>(filePath, archiveInboxFile(id), () => false);
+        inboxRemoved += r.removed;
+        await deleteFile(filePath);
+        deletedOrphans.push(id);
+        continue;
+      }
+      const r = await archiveJsonl<Message>(filePath, archiveInboxFile(id), (e) => e.ts > cutoff);
+      inboxRemoved += r.removed;
+      perAgentInboxRemoved[id] = r.removed;
+    }
+  }
+
+  const cursorsAdjusted = await adjustCursors({
+    roomRemovedByChan,
+    statusRemoved: statusResult.removed,
+    perAgentInboxRemoved,
+  });
+
+  // Membership sweep: drop orphans (not in registry) and stale members (no
+  // heartbeat since cutoff) so list_rooms / joinedRooms() stop surfacing
+  // ghosts. Then archive non-default rooms left with no members and no
+  // activity since the cutoff: remaining messages move to the archive, the
+  // room leaves the registry, and every cursor forgets its offset — the same
+  // cleanup delete_room performs, minus the data loss.
+  const orphanMembers = new Set<string>();
+  const staleMembers = new Set<string>();
+  const archivedRooms: string[] = [];
+  if (targets.has("members")) {
+    await updateJson<RoomRegistry>(ROOMS_FILE, {}, (current) => {
+      for (const e of Object.values(current)) {
+        if ((e.members?.length ?? 0) === 0) continue;
+        e.members = (e.members ?? []).filter((m) => {
+          if (!knownAgents.has(m)) {
+            orphanMembers.add(m);
+            return false;
+          }
+          if (staleAgent(m)) {
+            staleMembers.add(m);
+            return false;
+          }
+          return true;
+        });
+      }
+      return current;
+    });
+
+    if (args.archiveEmptyRooms ?? true) {
+      const rooms = await getRooms();
+      for (const [chan, e] of Object.entries(rooms)) {
+        if (chan === DEFAULT_ROOM || (e.members?.length ?? 0) > 0) continue;
+        const file = roomFile(chan);
+        const msgs = await readJsonl<Message>(file);
+        const lastTs = msgs[msgs.length - 1]?.ts ?? 0;
+        if (lastTs > cutoff) continue;
+        await archiveJsonl<Message>(file, archiveRoomFile(chan), () => false);
+        await deleteFile(file);
+        await updateJson<RoomRegistry>(ROOMS_FILE, {}, (current) => {
+          delete current[chan];
+          return current;
+        });
+        for (const cname of await listCursorFiles()) {
+          await updateJson<Cursor>(path.join(CURSOR_DIR, cname), {}, (current) => {
+            if (current.roomOffsets?.[chan] !== undefined) delete current.roomOffsets[chan];
+            return current;
+          });
+        }
+        archivedRooms.push(chan);
+      }
+    }
+  }
+
+  // Receipts are out-of-band proof logs with no cursor and no analysis value —
+  // trim old entries by ts and delete logs for agents no longer registered.
+  // The one stream that is genuinely deleted, not archived.
+  let receiptsRemoved = 0;
+  const deletedOrphanReceipts: string[] = [];
+  if (targets.has("receipts")) {
+    for (const filePath of await listReceiptFiles()) {
+      const id = path.basename(filePath).replace(/\.jsonl$/, "");
+      if (!knownAgents.has(id) && (args.removeOrphanInboxes ?? true)) {
+        const entries = await readJsonl<{ ts: number }>(filePath);
+        receiptsRemoved += entries.length;
+        await deleteFile(filePath);
+        deletedOrphanReceipts.push(id);
+        continue;
+      }
+      const r = await rewriteJsonl<{ ts: number }>(filePath, (e) => e.ts > cutoff);
+      receiptsRemoved += r.removed;
+    }
+  }
+
+  // Sweep expired reversible-history entries (TTL'd cache; also self-prunes on
+  // every read, so this just catches entries on a server with few reads).
+  await pruneHistory();
+
+  return {
+    dryRun: false,
+    cutoff,
+    olderThanDays: days,
+    decisionDays,
+    ...(scopedRoom ? { room: scopedRoom } : {}),
+    removed: {
+      roomMessages: roomRemovedTotal,
+      statusEntries: statusResult.removed,
+      inboxMessages: inboxRemoved,
+      orphanInboxes: deletedOrphans,
+      orphanMembers: [...orphanMembers],
+      staleMembers: [...staleMembers],
+      archivedRooms,
+      receipts: receiptsRemoved,
+      orphanReceipts: deletedOrphanReceipts,
+    },
+    archivedTo: "archive/ (rooms/<chan>.jsonl, status.jsonl, inbox/<agent>.jsonl; receipts deleted)",
+    cursorsAdjusted,
+  };
+}

package/src/tools/index.ts

@@ -0,0 +1,6 @@
+export * from "./shared.js";
+export * from "./registry.js";
+export * from "./rooms.js";
+export * from "./messaging.js";
+export * from "./transport.js";
+export * from "./admin.js";