agent-coord-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Balzan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# agent-coord-mcp
+
+A tiny file-backed [MCP](https://modelcontextprotocol.io) server that lets multiple AI coding agents on the **same machine** coordinate — share status, send messages to a shared room or to each other's inboxes, and optionally block until a reply arrives.
+
+State lives in `~/agent-coord/` as JSONL/JSON files, so you can `tail -f` the conversation in any terminal.
+
+> **Local-only** — coordination happens through the local filesystem. Agents need to share the same `~/agent-coord/` directory (i.e. same machine, same user). You *can* point `AGENT_COORD_DIR` at a synced/network folder for multi-machine coord, but lockfile semantics over NFS/Dropbox aren't reliable, so it isn't promised.
+>
+> **Works with any MCP client.** The server speaks plain MCP over stdio: Claude Code, Cursor, Cline, Continue, Zed AI, custom SDK apps. Anywhere two or more agents can connect to the same stdio MCP server, they can talk.
+>
+> No auth, no encryption. Anything that can read your home directory can read the messages.
+
+## Install
+
+```sh
+git clone https://github.com/davidbalzan/agent-coord-mcp.git
+cd agent-coord-mcp
+npm install            # runs `npm run build` automatically via `prepare`
+```
+
+The built entrypoint is `dist/server.js`.
+
+## Connect a client
+
+Each client just needs to launch `node /path/to/agent-coord-mcp/dist/server.js` over stdio.
+
+### Claude Code
+
+```sh
+claude mcp add --scope user agent-coord -- node /absolute/path/to/agent-coord-mcp/dist/server.js
+```
+
+Or edit `~/.claude.json` directly:
+
+```json
+{
+  "mcpServers": {
+    "agent-coord": {
+      "command": "node",
+      "args": ["/absolute/path/to/agent-coord-mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+### Cursor / Cline / Continue / Zed / etc.
+
+These all use a similar `mcpServers` config block. Drop in the same `command` + `args` shape. Refer to your client's MCP docs for the exact file.
+
+### Custom client (Python / TS)
+
+If you're building an agent with the official MCP SDKs (`@modelcontextprotocol/sdk` in TS, `mcp` in Python), spawn the server as a stdio subprocess and call the tools below — no editor required.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `register({agentId, project?, role?})` | Announce yourself in `agents.json`. Call once per session. |
+| `heartbeat({agentId})` | Refresh your `lastHeartbeat`. |
+| `list_agents()` | See all known agents and which look online (heartbeat <5min). |
+| `send_message({from, to?, room?, text})` | If `to` set → that agent's inbox. Else → shared room. |
+| `read_messages({agentId, source, limit?, peek?, sinceTs?})` | Read new messages. `source` is `inbox`/`room`/`status`. Advances cursor unless `peek:true`. |
+| `post_status({agentId, status, detail?})` | Append to the shared status stream (separate from chat). |
+| `wait_for_message({agentId, source, timeoutMs?})` | Block (max 60s) until a new entry appears, then return it. |
+| `prune({olderThanDays?, removeOrphanInboxes?, dryRun?})` | Trim room/status/inbox JSONL to entries newer than N days (default 7). Removes inbox files for agents no longer in the registry. Pass `dryRun:true` to preview. |
+
+## Convention for agent IDs
+
+Use the project's directory name or a short stable slug (e.g. `frontend`, `api`, `worker`). Tell each agent — in its `CLAUDE.md`, system prompt, or however your client supports persistent instructions — something like:
+
+> Your coord agentId is `frontend`. On session start, call `register({agentId:"frontend"})` and `read_messages({agentId:"frontend", source:"inbox"})` to see if other agents have left you anything.
+
+## Tail it from a terminal
+
+```sh
+# shared room
+tail -f ~/agent-coord/room.jsonl
+
+# a specific agent's inbox
+tail -f ~/agent-coord/inbox/frontend.jsonl
+
+# status broadcasts
+tail -f ~/agent-coord/status.jsonl
+
+# pretty-print live
+tail -f ~/agent-coord/room.jsonl | jq -c '{ts: (.ts/1000|todate), from, to, text}'
+```
+
+## Files on disk
+
+```
+~/agent-coord/
+  agents.json            # registry
+  room.jsonl             # shared chat
+  status.jsonl           # status broadcasts
+  inbox/<agentId>.jsonl  # per-agent inboxes
+  cursors/<agentId>.json # last-read offsets
+```
+
+To reset everything: `rm -rf ~/agent-coord && mkdir -p ~/agent-coord/{inbox,cursors}`.
+
+### Cleanup
+
+The registry auto-evicts agents whose last heartbeat is older than 24h on every `list_agents` call. For chat history and inbox trimming, call `prune` periodically (e.g. weekly) — it's safe to run from any agent and supports `dryRun`.
+
+## Override location
+
+Set `AGENT_COORD_DIR=/some/other/path` in the MCP server's env to relocate state. (`CLAUDE_COORD_DIR` is also honored as a legacy alias.) Useful if you want different agent groups isolated, or to put the dir on a synced volume so agents on different machines can collaborate (caveat above).
+
+## Realtime vs. polling
+
+`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.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/server.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ensureDirs } from "./store.js";
+import { heartbeatSchema, heartbeatTool, listAgentsSchema, listAgentsTool, postStatusSchema, postStatusTool, pruneSchema, pruneTool, readMessagesSchema, readMessagesTool, registerSchema, registerTool, sendMessageSchema, sendMessageTool, waitForMessageSchema, waitForMessageTool, } from "./tools.js";
+function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+async function main() {
+    ensureDirs();
+    const server = new McpServer({
+        name: "agent-coord",
+        version: "0.1.0",
+    });
+    server.tool("register", "Register this agent in the shared registry. Call once per session.", registerSchema, async (args) => jsonResult(await registerTool(args)));
+    server.tool("heartbeat", "Refresh this agent's lastHeartbeat timestamp.", heartbeatSchema, async (args) => jsonResult(await heartbeatTool(args)));
+    server.tool("list_agents", "List all known agents and whether they appear online (heartbeat <5min).", listAgentsSchema, async () => jsonResult(await listAgentsTool()));
+    server.tool("send_message", "Send a message. If 'to' is set, goes to that agent's inbox; otherwise to the shared room.", sendMessageSchema, async (args) => jsonResult(await sendMessageTool(args)));
+    server.tool("read_messages", "Read new messages from inbox|room|status. Advances the cursor unless peek=true.", readMessagesSchema, async (args) => jsonResult(await readMessagesTool(args)));
+    server.tool("post_status", "Append a status broadcast to the shared status stream.", postStatusSchema, async (args) => jsonResult(await postStatusTool(args)));
+    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.", pruneSchema, async (args) => jsonResult(await pruneTool(args)));
+    server.tool("wait_for_message", "Block (max 60s) until a new message appears on the given source, then return it.", waitForMessageSchema, async (args) => jsonResult(await waitForMessageTool(args)));
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("[agent-coord-mcp] fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/store.js

@@ -0,0 +1,160 @@
+import { promises as fs, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import lockfile from "proper-lockfile";
+export const ROOT = process.env.AGENT_COORD_DIR ??
+    process.env.CLAUDE_COORD_DIR ??
+    path.join(homedir(), "agent-coord");
+export const AGENTS_FILE = path.join(ROOT, "agents.json");
+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 function ensureDirs() {
+    for (const d of [ROOT, INBOX_DIR, CURSOR_DIR]) {
+        if (!existsSync(d))
+            mkdirSync(d, { recursive: true });
+    }
+    for (const f of [ROOM_FILE, STATUS_FILE]) {
+        if (!existsSync(f))
+            mkdirSync(path.dirname(f), { recursive: true });
+    }
+}
+async function ensureFile(file) {
+    if (!existsSync(file)) {
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, "", "utf8");
+    }
+}
+async function withLock(file, fn) {
+    await ensureFile(file);
+    const release = await lockfile.lock(file, {
+        retries: { retries: 10, minTimeout: 20, maxTimeout: 200 },
+        stale: 5000,
+    });
+    try {
+        return await fn();
+    }
+    finally {
+        await release();
+    }
+}
+export async function appendJsonl(file, entry) {
+    await withLock(file, async () => {
+        const line = JSON.stringify(entry) + "\n";
+        await fs.appendFile(file, line, "utf8");
+    });
+}
+export async function readJsonl(file) {
+    if (!existsSync(file))
+        return [];
+    const raw = await fs.readFile(file, "utf8");
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return out;
+}
+export async function readJson(file, fallback) {
+    if (!existsSync(file))
+        return fallback;
+    try {
+        const raw = await fs.readFile(file, "utf8");
+        if (!raw.trim())
+            return fallback;
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+export async function writeJson(file, data) {
+    await withLock(file, async () => {
+        await fs.writeFile(file, JSON.stringify(data, null, 2), "utf8");
+    });
+}
+async function readJsonNoLock(file, fallback) {
+    if (!existsSync(file))
+        return fallback;
+    try {
+        const raw = await fs.readFile(file, "utf8");
+        if (!raw.trim())
+            return fallback;
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+export async function updateJson(file, fallback, mutate) {
+    return withLock(file, async () => {
+        const current = await readJsonNoLock(file, fallback);
+        const next = await mutate(current);
+        await fs.writeFile(file, JSON.stringify(next, null, 2), "utf8");
+        return next;
+    });
+}
+export function inboxFile(agentId) {
+    return path.join(INBOX_DIR, `${sanitize(agentId)}.jsonl`);
+}
+export function cursorFile(agentId) {
+    return path.join(CURSOR_DIR, `${sanitize(agentId)}.json`);
+}
+function sanitize(id) {
+    return id.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+export async function rewriteJsonl(file, filter) {
+    if (!existsSync(file))
+        return { kept: 0, removed: 0 };
+    return withLock(file, async () => {
+        const raw = await fs.readFile(file, "utf8");
+        let kept = 0;
+        let removed = 0;
+        const out = [];
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const entry = JSON.parse(line);
+                if (filter(entry)) {
+                    out.push(line);
+                    kept++;
+                }
+                else {
+                    removed++;
+                }
+            }
+            catch {
+                removed++;
+            }
+        }
+        await fs.writeFile(file, out.length ? out.join("\n") + "\n" : "", "utf8");
+        return { kept, removed };
+    });
+}
+export async function deleteFile(file) {
+    if (!existsSync(file))
+        return false;
+    await fs.unlink(file);
+    return true;
+}
+export async function listInboxFiles() {
+    if (!existsSync(INBOX_DIR))
+        return [];
+    const names = await fs.readdir(INBOX_DIR);
+    return names.filter((n) => n.endsWith(".jsonl"));
+}
+export async function fileSize(file) {
+    if (!existsSync(file))
+        return 0;
+    const st = await fs.stat(file);
+    return st.size;
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,QAAQ,MAAM,iBAAiB,CAAC;AAEvC,MAAM,CAAC,MAAM,IAAI,GACf,OAAO,CAAC,GAAG,CAAC,eAAe;IAC3B,OAAO,CAAC,GAAG,CAAC,gBAAgB;IAC5B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,CAAC,CAAC;AACtC,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;AAC1D,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AACvD,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;AAC3D,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAClD,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AAErD,MAAM,UAAU,UAAU;IACxB,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,EAAE,CAAC;QAC9C,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;YAAE,SAAS,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;YAAE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtE,CAAC;AACH,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,IAAY;IACpC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;AACH,CAAC;AAED,KAAK,UAAU,QAAQ,CAAI,IAAY,EAAE,EAAoB;IAC3D,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE;QACxC,OAAO,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE;QACzD,KAAK,EAAE,IAAI;KACZ,CAAC,CAAC;IACH,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,KAAc;IAC5D,MAAM,QAAQ,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;QAC1C,MAAM,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAc,IAAY;IACvD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,SAAS;QAC3B,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,sBAAsB;QACxB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAI,IAAY,EAAE,QAAW;IACzD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;YAAE,OAAO,QAAQ,CAAC;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY,EAAE,IAAa;IACzD,MAAM,QAAQ,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;QAC9B,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,cAAc,CAAI,IAAY,EAAE,QAAW;IACxD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;YAAE,OAAO,QAAQ,CAAC;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAI,IAAY,EAAE,QAAW,EAAE,MAAsC;IACnG,OAAO,QAAQ,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;QAC/B,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;QACnC,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QAChE,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,QAAQ,CAAC,EAAU;IAC1B,OAAO,EAAE,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,MAA6B;IAE7B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IACtD,OAAO,QAAQ,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;QAC/B,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5C,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;gBAAE,SAAS;YAC3B,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;gBACpC,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;oBAClB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACf,IAAI,EAAE,CAAC;gBACT,CAAC;qBAAM,CAAC;oBACN,OAAO,EAAE,CAAC;gBACZ,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QACD,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC1E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC1C,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY;IACzC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,EAAE,CAAC,IAAI,CAAC;AACjB,CAAC"}

package/dist/tools.js

@@ -0,0 +1,273 @@
+import { randomUUID } from "node:crypto";
+import { watch } from "node:fs";
+import { z } from "zod";
+import path from "node:path";
+import { AGENTS_FILE, INBOX_DIR, ROOM_FILE, STATUS_FILE, appendJsonl, cursorFile, deleteFile, fileSize, inboxFile, listInboxFiles, readJson, readJsonl, rewriteJsonl, updateJson, } from "./store.js";
+const STALE_MS = 5 * 60 * 1000;
+const EVICT_MS = 24 * 60 * 60 * 1000;
+const MAX_WAIT_MS = 60_000;
+// ---------- register ----------
+export const registerSchema = {
+    agentId: z.string().min(1),
+    project: z.string().optional(),
+    role: z.string().optional(),
+};
+export async function registerTool(args) {
+    const reg = await updateJson(AGENTS_FILE, {}, (current) => {
+        const now = Date.now();
+        const existing = current[args.agentId];
+        current[args.agentId] = {
+            agentId: args.agentId,
+            project: args.project ?? existing?.project,
+            role: args.role ?? existing?.role,
+            registeredAt: existing?.registeredAt ?? now,
+            lastHeartbeat: now,
+        };
+        return current;
+    });
+    return { ok: true, agent: reg[args.agentId] };
+}
+// ---------- heartbeat ----------
+export const heartbeatSchema = { agentId: z.string().min(1) };
+export async function heartbeatTool(args) {
+    let missing = false;
+    await updateJson(AGENTS_FILE, {}, (current) => {
+        if (!current[args.agentId]) {
+            missing = true;
+            return current;
+        }
+        current[args.agentId].lastHeartbeat = Date.now();
+        return current;
+    });
+    if (missing)
+        return { ok: false, error: `agent '${args.agentId}' not registered` };
+    return { ok: true };
+}
+// ---------- list_agents ----------
+export const listAgentsSchema = {};
+export async function listAgentsTool() {
+    const now = Date.now();
+    const evicted = [];
+    const reg = await updateJson(AGENTS_FILE, {}, (current) => {
+        for (const [id, entry] of Object.entries(current)) {
+            if (now - entry.lastHeartbeat > EVICT_MS) {
+                evicted.push(id);
+                delete current[id];
+            }
+        }
+        return current;
+    });
+    const agents = Object.values(reg).map((a) => ({
+        ...a,
+        online: now - a.lastHeartbeat < STALE_MS,
+        secondsSinceHeartbeat: Math.floor((now - a.lastHeartbeat) / 1000),
+    }));
+    return { agents, evicted };
+}
+// ---------- send_message ----------
+export const sendMessageSchema = {
+    from: z.string().min(1),
+    to: z.string().optional(),
+    room: z.string().optional(),
+    text: z.string().min(1),
+};
+export async function sendMessageTool(args) {
+    const msg = {
+        id: randomUUID(),
+        ts: Date.now(),
+        from: args.from,
+        to: args.to,
+        room: args.room,
+        text: args.text,
+    };
+    const target = args.to ? inboxFile(args.to) : ROOM_FILE;
+    await appendJsonl(target, msg);
+    return { ok: true, id: msg.id, target };
+}
+// ---------- read_messages ----------
+export const readMessagesSchema = {
+    agentId: z.string().min(1),
+    source: z.enum(["inbox", "room", "status"]),
+    limit: z.number().int().positive().max(500).optional(),
+    peek: z.boolean().optional(),
+    sinceTs: z.number().optional(),
+};
+export async function readMessagesTool(args) {
+    const file = sourceFile(args.source, args.agentId);
+    const offsetKey = offsetKeyFor(args.source);
+    const all = await readJsonl(file);
+    let limited = [];
+    let totalNew = 0;
+    if (args.peek) {
+        const cursor = await readJson(cursorFile(args.agentId), {});
+        const startOffset = cursor[offsetKey] ?? 0;
+        let entries = all.slice(startOffset);
+        if (args.sinceTs !== undefined)
+            entries = entries.filter((e) => e.ts > args.sinceTs);
+        totalNew = entries.length;
+        limited = args.limit ? entries.slice(0, args.limit) : entries;
+    }
+    else {
+        await updateJson(cursorFile(args.agentId), {}, (current) => {
+            const startOffset = current[offsetKey] ?? 0;
+            let entries = all.slice(startOffset);
+            if (args.sinceTs !== undefined)
+                entries = entries.filter((e) => e.ts > args.sinceTs);
+            totalNew = entries.length;
+            limited = args.limit ? entries.slice(0, args.limit) : entries;
+            if (limited.length > 0)
+                current[offsetKey] = startOffset + limited.length;
+            return current;
+        });
+    }
+    return { messages: limited, totalNew, returned: limited.length };
+}
+// ---------- post_status ----------
+export const postStatusSchema = {
+    agentId: z.string().min(1),
+    status: z.string().min(1),
+    detail: z.string().optional(),
+};
+export async function postStatusTool(args) {
+    const entry = {
+        id: randomUUID(),
+        ts: Date.now(),
+        agentId: args.agentId,
+        status: args.status,
+        detail: args.detail,
+    };
+    await appendJsonl(STATUS_FILE, entry);
+    return { ok: true, id: entry.id };
+}
+// ---------- wait_for_message ----------
+export const waitForMessageSchema = {
+    agentId: z.string().min(1),
+    source: z.enum(["inbox", "room", "status"]),
+    timeoutMs: z.number().int().positive().max(MAX_WAIT_MS).optional(),
+};
+export async function waitForMessageTool(args) {
+    const timeout = 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((resolve) => {
+        let settled = false;
+        const finish = (changed) => {
+            if (settled)
+                return;
+            settled = true;
+            clearInterval(poll);
+            try {
+                watcher?.close();
+            }
+            catch {
+                // ignore
+            }
+            clearTimeout(t);
+            resolve({ changed });
+        };
+        const check = async () => {
+            const sz = await fileSize(file);
+            if (sz > startSize)
+                finish(true);
+        };
+        let watcher;
+        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);
+    });
+    if (!result.changed) {
+        return { ok: false, timedOut: true };
+    }
+    return readMessagesTool({ agentId: args.agentId, source: args.source });
+}
+// ---------- prune ----------
+export const pruneSchema = {
+    olderThanDays: z.number().positive().max(365).optional(),
+    removeOrphanInboxes: z.boolean().optional(),
+    dryRun: z.boolean().optional(),
+};
+export async function pruneTool(args) {
+    const days = args.olderThanDays ?? 7;
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    const dryRun = args.dryRun ?? false;
+    const reg = await readJson(AGENTS_FILE, {});
+    const knownAgents = new Set(Object.keys(reg));
+    if (dryRun) {
+        const room = await readJsonl(ROOM_FILE);
+        const status = await readJsonl(STATUS_FILE);
+        const inboxFiles = await listInboxFiles();
+        let inboxRemoved = 0;
+        const orphans = [];
+        for (const fname of inboxFiles) {
+            const id = fname.replace(/\.jsonl$/, "");
+            if (!knownAgents.has(id) && (args.removeOrphanInboxes ?? true))
+                orphans.push(fname);
+            const entries = await readJsonl(path.join(INBOX_DIR, fname));
+            inboxRemoved += entries.filter((e) => e.ts <= cutoff).length;
+        }
+        return {
+            dryRun: true,
+            cutoff,
+            olderThanDays: days,
+            wouldRemove: {
+                roomMessages: room.filter((e) => e.ts <= cutoff).length,
+                statusEntries: status.filter((e) => e.ts <= cutoff).length,
+                inboxMessages: inboxRemoved,
+                orphanInboxes: orphans,
+            },
+        };
+    }
+    const roomResult = await rewriteJsonl(ROOM_FILE, (e) => e.ts > cutoff);
+    const statusResult = await rewriteJsonl(STATUS_FILE, (e) => e.ts > cutoff);
+    const inboxFiles = await listInboxFiles();
+    let inboxRemoved = 0;
+    const deletedOrphans = [];
+    for (const fname of inboxFiles) {
+        const id = fname.replace(/\.jsonl$/, "");
+        const filePath = path.join(INBOX_DIR, fname);
+        if (!knownAgents.has(id) && (args.removeOrphanInboxes ?? true)) {
+            const entries = await readJsonl(filePath);
+            inboxRemoved += entries.length;
+            await deleteFile(filePath);
+            deletedOrphans.push(id);
+            continue;
+        }
+        const r = await rewriteJsonl(filePath, (e) => e.ts > cutoff);
+        inboxRemoved += r.removed;
+    }
+    return {
+        dryRun: false,
+        cutoff,
+        olderThanDays: days,
+        removed: {
+            roomMessages: roomResult.removed,
+            statusEntries: statusResult.removed,
+            inboxMessages: inboxRemoved,
+            orphanInboxes: deletedOrphans,
+        },
+        note: "Cursors not adjusted; clients may see stale offsets but read_messages clamps via slice().",
+    };
+}
+// ---------- helpers ----------
+function sourceFile(source, agentId) {
+    if (source === "inbox")
+        return inboxFile(agentId);
+    if (source === "room")
+        return ROOM_FILE;
+    return STATUS_FILE;
+}
+function offsetKeyFor(source) {
+    if (source === "inbox")
+        return "inboxOffset";
+    if (source === "room")
+        return "roomOffset";
+    return "statusOffset";
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "agent-coord-mcp",
+  "version": "0.1.0",
+  "description": "File-backed MCP server for coordinating multiple AI coding agents (Claude Code, Cursor, Cline, etc.) on the same machine.",
+  "type": "module",
+  "bin": {
+    "agent-coord-mcp": "dist/server.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "start": "node dist/server.js",
+    "dev": "tsx src/server.ts"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/davidbalzan/agent-coord-mcp.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "proper-lockfile": "^4.1.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/src/server.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ensureDirs } from "./store.js";
+import {
+  heartbeatSchema,
+  heartbeatTool,
+  listAgentsSchema,
+  listAgentsTool,
+  postStatusSchema,
+  postStatusTool,
+  pruneSchema,
+  pruneTool,
+  readMessagesSchema,
+  readMessagesTool,
+  registerSchema,
+  registerTool,
+  sendMessageSchema,
+  sendMessageTool,
+  waitForMessageSchema,
+  waitForMessageTool,
+} from "./tools.js";
+
+function jsonResult(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+async function main() {
+  ensureDirs();
+
+  const server = new McpServer({
+    name: "agent-coord",
+    version: "0.1.0",
+  });
+
+  server.tool(
+    "register",
+    "Register this agent in the shared registry. Call once per session.",
+    registerSchema,
+    async (args) => jsonResult(await registerTool(args))
+  );
+
+  server.tool(
+    "heartbeat",
+    "Refresh this agent's lastHeartbeat timestamp.",
+    heartbeatSchema,
+    async (args) => jsonResult(await heartbeatTool(args))
+  );
+
+  server.tool(
+    "list_agents",
+    "List all known agents and whether they appear online (heartbeat <5min).",
+    listAgentsSchema,
+    async () => jsonResult(await listAgentsTool())
+  );
+
+  server.tool(
+    "send_message",
+    "Send a message. If 'to' is set, goes to that agent's inbox; otherwise to the shared room.",
+    sendMessageSchema,
+    async (args) => jsonResult(await sendMessageTool(args))
+  );
+
+  server.tool(
+    "read_messages",
+    "Read new messages from inbox|room|status. Advances the cursor unless peek=true.",
+    readMessagesSchema,
+    async (args) => jsonResult(await readMessagesTool(args))
+  );
+
+  server.tool(
+    "post_status",
+    "Append a status broadcast to the shared status stream.",
+    postStatusSchema,
+    async (args) => jsonResult(await postStatusTool(args))
+  );
+
+  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.",
+    pruneSchema,
+    async (args) => jsonResult(await pruneTool(args))
+  );
+
+  server.tool(
+    "wait_for_message",
+    "Block (max 60s) until a new message appears on the given source, then return it.",
+    waitForMessageSchema,
+    async (args) => jsonResult(await waitForMessageTool(args))
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("[agent-coord-mcp] fatal:", err);
+  process.exit(1);
+});

package/src/store.ts

@@ -0,0 +1,161 @@
+import { promises as fs, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import lockfile from "proper-lockfile";
+
+export const ROOT =
+  process.env.AGENT_COORD_DIR ??
+  process.env.CLAUDE_COORD_DIR ??
+  path.join(homedir(), "agent-coord");
+export const AGENTS_FILE = path.join(ROOT, "agents.json");
+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 function ensureDirs(): void {
+  for (const d of [ROOT, INBOX_DIR, CURSOR_DIR]) {
+    if (!existsSync(d)) mkdirSync(d, { recursive: true });
+  }
+  for (const f of [ROOM_FILE, STATUS_FILE]) {
+    if (!existsSync(f)) mkdirSync(path.dirname(f), { recursive: true });
+  }
+}
+
+async function ensureFile(file: string): Promise<void> {
+  if (!existsSync(file)) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, "", "utf8");
+  }
+}
+
+async function withLock<T>(file: string, fn: () => Promise<T>): Promise<T> {
+  await ensureFile(file);
+  const release = await lockfile.lock(file, {
+    retries: { retries: 10, minTimeout: 20, maxTimeout: 200 },
+    stale: 5000,
+  });
+  try {
+    return await fn();
+  } finally {
+    await release();
+  }
+}
+
+export async function appendJsonl(file: string, entry: unknown): Promise<void> {
+  await withLock(file, async () => {
+    const line = JSON.stringify(entry) + "\n";
+    await fs.appendFile(file, line, "utf8");
+  });
+}
+
+export async function readJsonl<T = unknown>(file: string): Promise<T[]> {
+  if (!existsSync(file)) return [];
+  const raw = await fs.readFile(file, "utf8");
+  const out: T[] = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line) as T);
+    } catch {
+      // skip malformed line
+    }
+  }
+  return out;
+}
+
+export async function readJson<T>(file: string, fallback: T): Promise<T> {
+  if (!existsSync(file)) return fallback;
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    if (!raw.trim()) return fallback;
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export async function writeJson(file: string, data: unknown): Promise<void> {
+  await withLock(file, async () => {
+    await fs.writeFile(file, JSON.stringify(data, null, 2), "utf8");
+  });
+}
+
+async function readJsonNoLock<T>(file: string, fallback: T): Promise<T> {
+  if (!existsSync(file)) return fallback;
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    if (!raw.trim()) return fallback;
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export async function updateJson<T>(file: string, fallback: T, mutate: (current: T) => T | Promise<T>): Promise<T> {
+  return withLock(file, async () => {
+    const current = await readJsonNoLock(file, fallback);
+    const next = await mutate(current);
+    await fs.writeFile(file, JSON.stringify(next, null, 2), "utf8");
+    return next;
+  });
+}
+
+export function inboxFile(agentId: string): string {
+  return path.join(INBOX_DIR, `${sanitize(agentId)}.jsonl`);
+}
+
+export function cursorFile(agentId: string): string {
+  return path.join(CURSOR_DIR, `${sanitize(agentId)}.json`);
+}
+
+function sanitize(id: string): string {
+  return id.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+export async function rewriteJsonl<T>(
+  file: string,
+  filter: (entry: T) => boolean
+): Promise<{ kept: number; removed: number }> {
+  if (!existsSync(file)) return { kept: 0, removed: 0 };
+  return withLock(file, async () => {
+    const raw = await fs.readFile(file, "utf8");
+    let kept = 0;
+    let removed = 0;
+    const out: string[] = [];
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const entry = JSON.parse(line) as T;
+        if (filter(entry)) {
+          out.push(line);
+          kept++;
+        } else {
+          removed++;
+        }
+      } catch {
+        removed++;
+      }
+    }
+    await fs.writeFile(file, out.length ? out.join("\n") + "\n" : "", "utf8");
+    return { kept, removed };
+  });
+}
+
+export async function deleteFile(file: string): Promise<boolean> {
+  if (!existsSync(file)) return false;
+  await fs.unlink(file);
+  return true;
+}
+
+export async function listInboxFiles(): Promise<string[]> {
+  if (!existsSync(INBOX_DIR)) return [];
+  const names = await fs.readdir(INBOX_DIR);
+  return names.filter((n) => n.endsWith(".jsonl"));
+}
+
+export async function fileSize(file: string): Promise<number> {
+  if (!existsSync(file)) return 0;
+  const st = await fs.stat(file);
+  return st.size;
+}

package/src/tools.ts

@@ -0,0 +1,365 @@
+import { randomUUID } from "node:crypto";
+import { watch } from "node:fs";
+import { z } from "zod";
+import path from "node:path";
+import {
+  AGENTS_FILE,
+  INBOX_DIR,
+  ROOM_FILE,
+  STATUS_FILE,
+  appendJsonl,
+  cursorFile,
+  deleteFile,
+  fileSize,
+  inboxFile,
+  listInboxFiles,
+  readJson,
+  readJsonl,
+  rewriteJsonl,
+  updateJson,
+} from "./store.js";
+
+type AgentEntry = {
+  agentId: string;
+  project?: string;
+  role?: string;
+  registeredAt: number;
+  lastHeartbeat: number;
+};
+
+type AgentRegistry = Record<string, AgentEntry>;
+
+type Message = {
+  id: string;
+  ts: number;
+  from: string;
+  to?: string;
+  room?: string;
+  text: string;
+};
+
+type StatusEntry = {
+  id: string;
+  ts: number;
+  agentId: string;
+  status: string;
+  detail?: string;
+};
+
+type Cursor = {
+  inboxOffset?: number;
+  roomOffset?: number;
+  statusOffset?: number;
+};
+
+const STALE_MS = 5 * 60 * 1000;
+const EVICT_MS = 24 * 60 * 60 * 1000;
+const MAX_WAIT_MS = 60_000;
+
+// ---------- register ----------
+
+export const registerSchema = {
+  agentId: z.string().min(1),
+  project: z.string().optional(),
+  role: z.string().optional(),
+};
+
+export async function registerTool(args: { agentId: string; project?: string; role?: string }) {
+  const reg = await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
+    const now = Date.now();
+    const existing = current[args.agentId];
+    current[args.agentId] = {
+      agentId: args.agentId,
+      project: args.project ?? existing?.project,
+      role: args.role ?? existing?.role,
+      registeredAt: existing?.registeredAt ?? now,
+      lastHeartbeat: now,
+    };
+    return current;
+  });
+  return { ok: true, agent: reg[args.agentId] };
+}
+
+// ---------- heartbeat ----------
+
+export const heartbeatSchema = { agentId: z.string().min(1) };
+
+export async function heartbeatTool(args: { agentId: string }) {
+  let missing = false;
+  await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
+    if (!current[args.agentId]) {
+      missing = true;
+      return current;
+    }
+    current[args.agentId].lastHeartbeat = Date.now();
+    return current;
+  });
+  if (missing) return { ok: false, error: `agent '${args.agentId}' not registered` };
+  return { ok: true };
+}
+
+// ---------- list_agents ----------
+
+export const listAgentsSchema = {} as const;
+
+export async function listAgentsTool() {
+  const now = Date.now();
+  const evicted: string[] = [];
+  const reg = await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
+    for (const [id, entry] of Object.entries(current)) {
+      if (now - entry.lastHeartbeat > EVICT_MS) {
+        evicted.push(id);
+        delete current[id];
+      }
+    }
+    return current;
+  });
+  const agents = Object.values(reg).map((a) => ({
+    ...a,
+    online: now - a.lastHeartbeat < STALE_MS,
+    secondsSinceHeartbeat: Math.floor((now - a.lastHeartbeat) / 1000),
+  }));
+  return { agents, evicted };
+}
+
+// ---------- send_message ----------
+
+export const sendMessageSchema = {
+  from: z.string().min(1),
+  to: z.string().optional(),
+  room: z.string().optional(),
+  text: z.string().min(1),
+};
+
+export async function sendMessageTool(args: {
+  from: string;
+  to?: string;
+  room?: string;
+  text: string;
+}) {
+  const msg: Message = {
+    id: randomUUID(),
+    ts: Date.now(),
+    from: args.from,
+    to: args.to,
+    room: args.room,
+    text: args.text,
+  };
+  const target = args.to ? inboxFile(args.to) : ROOM_FILE;
+  await appendJsonl(target, msg);
+  return { ok: true, id: msg.id, target };
+}
+
+// ---------- read_messages ----------
+
+export const readMessagesSchema = {
+  agentId: z.string().min(1),
+  source: z.enum(["inbox", "room", "status"]),
+  limit: z.number().int().positive().max(500).optional(),
+  peek: z.boolean().optional(),
+  sinceTs: z.number().optional(),
+};
+
+export async function readMessagesTool(args: {
+  agentId: string;
+  source: "inbox" | "room" | "status";
+  limit?: number;
+  peek?: boolean;
+  sinceTs?: number;
+}) {
+  const file = sourceFile(args.source, args.agentId);
+  const offsetKey = offsetKeyFor(args.source);
+  const all = await readJsonl<Message | StatusEntry>(file);
+
+  let limited: (Message | StatusEntry)[] = [];
+  let totalNew = 0;
+
+  if (args.peek) {
+    const cursor = await readJson<Cursor>(cursorFile(args.agentId), {});
+    const startOffset = cursor[offsetKey] ?? 0;
+    let entries = all.slice(startOffset);
+    if (args.sinceTs !== undefined) entries = entries.filter((e) => e.ts > args.sinceTs!);
+    totalNew = entries.length;
+    limited = args.limit ? entries.slice(0, args.limit) : entries;
+  } else {
+    await updateJson<Cursor>(cursorFile(args.agentId), {}, (current) => {
+      const startOffset = current[offsetKey] ?? 0;
+      let entries = all.slice(startOffset);
+      if (args.sinceTs !== undefined) entries = entries.filter((e) => e.ts > args.sinceTs!);
+      totalNew = entries.length;
+      limited = args.limit ? entries.slice(0, args.limit) : entries;
+      if (limited.length > 0) current[offsetKey] = startOffset + limited.length;
+      return current;
+    });
+  }
+
+  return { messages: limited, totalNew, returned: limited.length };
+}
+
+// ---------- post_status ----------
+
+export const postStatusSchema = {
+  agentId: z.string().min(1),
+  status: z.string().min(1),
+  detail: z.string().optional(),
+};
+
+export async function postStatusTool(args: { agentId: string; status: string; detail?: string }) {
+  const entry: StatusEntry = {
+    id: randomUUID(),
+    ts: Date.now(),
+    agentId: args.agentId,
+    status: args.status,
+    detail: args.detail,
+  };
+  await appendJsonl(STATUS_FILE, entry);
+  return { ok: true, id: entry.id };
+}
+
+// ---------- wait_for_message ----------
+
+export const waitForMessageSchema = {
+  agentId: z.string().min(1),
+  source: z.enum(["inbox", "room", "status"]),
+  timeoutMs: z.number().int().positive().max(MAX_WAIT_MS).optional(),
+};
+
+export async function waitForMessageTool(args: {
+  agentId: string;
+  source: "inbox" | "room" | "status";
+  timeoutMs?: number;
+}) {
+  const timeout = 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);
+      try {
+        watcher?.close();
+      } catch {
+        // ignore
+      }
+      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);
+  });
+
+  if (!result.changed) {
+    return { ok: false, timedOut: true };
+  }
+  return readMessagesTool({ agentId: args.agentId, source: args.source });
+}
+
+// ---------- prune ----------
+
+export const pruneSchema = {
+  olderThanDays: z.number().positive().max(365).optional(),
+  removeOrphanInboxes: z.boolean().optional(),
+  dryRun: z.boolean().optional(),
+};
+
+export async function pruneTool(args: {
+  olderThanDays?: number;
+  removeOrphanInboxes?: boolean;
+  dryRun?: boolean;
+}) {
+  const days = args.olderThanDays ?? 7;
+  const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+  const dryRun = args.dryRun ?? false;
+
+  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
+  const knownAgents = new Set(Object.keys(reg));
+
+  if (dryRun) {
+    const room = await readJsonl<Message>(ROOM_FILE);
+    const status = await readJsonl<StatusEntry>(STATUS_FILE);
+    const inboxFiles = await listInboxFiles();
+    let inboxRemoved = 0;
+    const orphans: string[] = [];
+    for (const fname of inboxFiles) {
+      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;
+    }
+    return {
+      dryRun: true,
+      cutoff,
+      olderThanDays: days,
+      wouldRemove: {
+        roomMessages: room.filter((e) => e.ts <= cutoff).length,
+        statusEntries: status.filter((e) => e.ts <= cutoff).length,
+        inboxMessages: inboxRemoved,
+        orphanInboxes: orphans,
+      },
+    };
+  }
+
+  const roomResult = await rewriteJsonl<Message>(ROOM_FILE, (e) => e.ts > cutoff);
+  const statusResult = await rewriteJsonl<StatusEntry>(STATUS_FILE, (e) => e.ts > cutoff);
+
+  const inboxFiles = await listInboxFiles();
+  let inboxRemoved = 0;
+  const deletedOrphans: string[] = [];
+  for (const fname of inboxFiles) {
+    const id = fname.replace(/\.jsonl$/, "");
+    const filePath = path.join(INBOX_DIR, fname);
+    if (!knownAgents.has(id) && (args.removeOrphanInboxes ?? true)) {
+      const entries = await readJsonl<Message>(filePath);
+      inboxRemoved += entries.length;
+      await deleteFile(filePath);
+      deletedOrphans.push(id);
+      continue;
+    }
+    const r = await rewriteJsonl<Message>(filePath, (e) => e.ts > cutoff);
+    inboxRemoved += r.removed;
+  }
+
+  return {
+    dryRun: false,
+    cutoff,
+    olderThanDays: days,
+    removed: {
+      roomMessages: roomResult.removed,
+      statusEntries: statusResult.removed,
+      inboxMessages: inboxRemoved,
+      orphanInboxes: deletedOrphans,
+    },
+    note: "Cursors not adjusted; clients may see stale offsets but read_messages clamps via slice().",
+  };
+}
+
+// ---------- helpers ----------
+
+function sourceFile(source: "inbox" | "room" | "status", agentId: string): string {
+  if (source === "inbox") return inboxFile(agentId);
+  if (source === "room") return ROOM_FILE;
+  return STATUS_FILE;
+}
+
+function offsetKeyFor(source: "inbox" | "room" | "status"): keyof Cursor {
+  if (source === "inbox") return "inboxOffset";
+  if (source === "room") return "roomOffset";
+  return "statusOffset";
+}