agent-coord-mcp 0.14.0 → 0.15.0

package/dist/tools/admin.js

@@ -0,0 +1,296 @@
+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, } from "../store.js";
+// ---------- prune ----------
+export const PRUNE_TARGETS = ["rooms", "status", "inbox", "receipts", "members"];
+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, cutoff, decisionCutoff) {
+    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) {
+    const roomRemovedByChan = removals.roomRemovedByChan ?? {};
+    const statusRemoved = removals.statusRemoved ?? 0;
+    const perAgentInboxRemoved = removals.perAgentInboxRemoved ?? {};
+    const cursorsAdjusted = [];
+    for (const cname of await listCursorFiles()) {
+        const id = cname.replace(/\.json$/, "");
+        const cursorPath = path.join(CURSOR_DIR, cname);
+        let touched = false;
+        await updateJson(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) {
+    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(scopedRoom ? ["rooms"] : args.targets ?? [...PRUNE_TARGETS]);
+    const keep = (e) => keepEntry(e, cutoff, decisionCutoff);
+    const reg = await readJson(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) => !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(roomFile(chan));
+                roomMessages += msgs.filter((e) => !keep(e)).length;
+            }
+        }
+        const status = targets.has("status") ? await readJsonl(STATUS_FILE) : [];
+        let inboxRemoved = 0;
+        const orphans = [];
+        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(path.join(INBOX_DIR, fname));
+                inboxRemoved += entries.filter((e) => e.ts <= cutoff).length;
+            }
+        }
+        const orphanMembers = new Set();
+        const staleMembers = new Set();
+        const emptyRooms = [];
+        if (targets.has("members")) {
+            const rooms = await getRooms();
+            for (const [chan, e] of Object.entries(rooms)) {
+                const remaining = [];
+                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(roomFile(chan));
+                    const lastTs = msgs[msgs.length - 1]?.ts ?? 0;
+                    if (lastTs <= cutoff)
+                        emptyRooms.push(chan);
+                }
+            }
+        }
+        let receiptsRemoved = 0;
+        const orphanReceipts = [];
+        if (targets.has("receipts")) {
+            for (const filePath of await listReceiptFiles()) {
+                const id = path.basename(filePath).replace(/\.jsonl$/, "");
+                const entries = await readJsonl(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 = {};
+    let roomRemovedTotal = 0;
+    if (targets.has("rooms")) {
+        for (const chan of channels) {
+            const r = await archiveJsonl(roomFile(chan), archiveRoomFile(chan), keep);
+            if (r.removed > 0) {
+                roomRemovedByChan[chan] = r.removed;
+                roomRemovedTotal += r.removed;
+            }
+        }
+    }
+    const statusResult = targets.has("status")
+        ? await archiveJsonl(STATUS_FILE, ARCHIVE_STATUS_FILE, (e) => e.ts > cutoff)
+        : { kept: 0, removed: 0, archived: 0 };
+    let inboxRemoved = 0;
+    const deletedOrphans = [];
+    // 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 = {};
+    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(filePath, archiveInboxFile(id), () => false);
+                inboxRemoved += r.removed;
+                await deleteFile(filePath);
+                deletedOrphans.push(id);
+                continue;
+            }
+            const r = await archiveJsonl(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();
+    const staleMembers = new Set();
+    const archivedRooms = [];
+    if (targets.has("members")) {
+        await updateJson(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(file);
+                const lastTs = msgs[msgs.length - 1]?.ts ?? 0;
+                if (lastTs > cutoff)
+                    continue;
+                await archiveJsonl(file, archiveRoomFile(chan), () => false);
+                await deleteFile(file);
+                await updateJson(ROOMS_FILE, {}, (current) => {
+                    delete current[chan];
+                    return current;
+                });
+                for (const cname of await listCursorFiles()) {
+                    await updateJson(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 = [];
+    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(filePath);
+                receiptsRemoved += entries.length;
+                await deleteFile(filePath);
+                deletedOrphanReceipts.push(id);
+                continue;
+            }
+            const r = await rewriteJsonl(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,
+    };
+}
+//# sourceMappingURL=admin.js.map

package/dist/tools/admin.js.map

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

package/dist/tools/index.js

@@ -0,0 +1,7 @@
+export * from "./shared.js";
+export * from "./registry.js";
+export * from "./rooms.js";
+export * from "./messaging.js";
+export * from "./transport.js";
+export * from "./admin.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}

package/dist/tools/messaging.js

@@ -0,0 +1,317 @@
+import { adjustCursors } from "./admin.js";
+import { ARCHIVE_STATUS_FILE, archiveJsonl, archiveRoomFile } from "../store.js";
+import { randomUUID } from "node:crypto";
+import { watch } from "node:fs";
+import { z } from "zod";
+import { AGENTS_FILE, DEFAULT_ROOM, STATUS_FILE, appendJsonl, cursorFile, ensureRoom, fileSize, inboxFile, normalizeRoom, readJson, readJsonl, roomFile, stashHistory, retrieveHistory, updateJson, } from "../store.js";
+import { sourceFile, getOffset, setOffset, MAX_WAIT_MS, } from "./shared.js";
+// ---------- send_message ----------
+export const sendMessageSchema = {
+    from: z.string().min(1),
+    to: z.string().optional(),
+    room: z.string().optional(),
+    text: z.string().min(1),
+    kind: z.enum(["decision", "status", "chatter"]).optional(),
+};
+export async function sendMessageTool(args) {
+    // DM → inbox. Otherwise resolve the channel (default `general`), make sure it
+    // exists in the registry, and tag the message with its channel.
+    if (args.to) {
+        const msg = {
+            id: randomUUID(),
+            ts: Date.now(),
+            from: args.from,
+            to: args.to,
+            text: args.text,
+        };
+        const target = inboxFile(args.to);
+        await appendJsonl(target, msg);
+        // Offline delivery is intentional (the inbox is created on demand), but a
+        // typo'd recipient shouldn't vanish silently — surface a warning when the
+        // target isn't a known agent so the caller can catch the mistake.
+        const reg = await readJson(AGENTS_FILE, {});
+        const warning = reg[args.to]
+            ? undefined
+            : `recipient '${args.to}' is not a registered agent — message stored in their inbox but no one may be listening`;
+        return { ok: true, id: msg.id, target, room: undefined, warning };
+    }
+    const chan = normalizeRoom(args.room);
+    if (chan !== DEFAULT_ROOM)
+        await ensureRoom(chan, args.from);
+    const msg = {
+        id: randomUUID(),
+        ts: Date.now(),
+        from: args.from,
+        room: chan,
+        text: args.text,
+        ...(args.kind ? { kind: args.kind } : {}),
+    };
+    const target = roomFile(chan);
+    await appendJsonl(target, msg);
+    await maybeCompactRoom(chan);
+    return { ok: true, id: msg.id, target, room: chan };
+}
+// ---------- live compaction (self-limiting streams) ----------
+// Rooms and the status stream compact themselves on write: once a live file
+// grows past its threshold, the oldest entries move to the archive (never
+// deleted) and every cursor shifts down. Fresh decisions (< decisionDays old)
+// are exempt — they stay in the live file. Cursor adjustment subtracts the
+// full removed count, so an agent parked behind a kept decision may re-read
+// it once; at-least-once beats silently skipping.
+function envInt(name, fallback) {
+    const n = Number(process.env[name]);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+const ROOM_COMPACT_THRESHOLD = envInt("AGENT_COORD_ROOM_MAX", 1000);
+const ROOM_COMPACT_KEEP = envInt("AGENT_COORD_ROOM_KEEP", 500);
+const STATUS_COMPACT_THRESHOLD = envInt("AGENT_COORD_STATUS_MAX", 2000);
+const STATUS_COMPACT_KEEP = envInt("AGENT_COORD_STATUS_KEEP", 1000);
+// Skip the entry count entirely while the file is small — the common case on
+// every send. ~150 bytes/entry means the threshold can't be hit below this.
+const COMPACT_SIZE_GATE = 100 * 1024;
+const DECISION_FRESH_MS = 30 * 24 * 60 * 60 * 1000;
+async function maybeCompactRoom(chan) {
+    const file = roomFile(chan);
+    if ((await fileSize(file)) < COMPACT_SIZE_GATE)
+        return;
+    const entries = await readJsonl(file);
+    if (entries.length <= ROOM_COMPACT_THRESHOLD)
+        return;
+    const boundaryTs = entries[entries.length - ROOM_COMPACT_KEEP].ts;
+    const decisionCutoff = Date.now() - DECISION_FRESH_MS;
+    const r = await archiveJsonl(file, archiveRoomFile(chan), (e) => e.ts >= boundaryTs || (e.kind === "decision" && e.ts > decisionCutoff));
+    if (r.removed > 0)
+        await adjustCursors({ roomRemovedByChan: { [chan]: r.removed } });
+}
+async function maybeCompactStatus() {
+    if ((await fileSize(STATUS_FILE)) < COMPACT_SIZE_GATE)
+        return;
+    const entries = await readJsonl(STATUS_FILE);
+    if (entries.length <= STATUS_COMPACT_THRESHOLD)
+        return;
+    const boundaryTs = entries[entries.length - STATUS_COMPACT_KEEP].ts;
+    const r = await archiveJsonl(STATUS_FILE, ARCHIVE_STATUS_FILE, (e) => e.ts >= boundaryTs);
+    if (r.removed > 0)
+        await adjustCursors({ statusRemoved: r.removed });
+}
+// ---------- read_messages ----------
+export const readMessagesSchema = {
+    agentId: z.string().min(1),
+    source: z.enum(["inbox", "room", "status"]),
+    room: z.string().optional(),
+    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, args.room);
+    const all = await readJsonl(file);
+    let entries = [];
+    let totalNew = 0;
+    // Room and status reads default to 50 entries to prevent agents flooding
+    // themselves with full history on join — the status stream grows unbounded
+    // across the fleet. Inbox drains fully since it is targeted by nature.
+    const effectiveLimit = args.limit ?? (args.source === "inbox" ? undefined : 50);
+    if (args.peek) {
+        const cursor = await readJson(cursorFile(args.agentId), {});
+        const startOffset = getOffset(cursor, args.source, args.room);
+        entries = all.slice(startOffset);
+        if (args.sinceTs !== undefined)
+            entries = entries.filter((e) => e.ts > args.sinceTs);
+        totalNew = entries.length;
+    }
+    else {
+        await updateJson(cursorFile(args.agentId), {}, (current) => {
+            const startOffset = getOffset(current, args.source, args.room);
+            let e = all.slice(startOffset);
+            if (args.sinceTs !== undefined)
+                e = e.filter((x) => x.ts > args.sinceTs);
+            totalNew = e.length;
+            entries = e;
+            // Advance past EVERYTHING we account for here (recent window + any
+            // overflow we stash below). The overflow is recoverable via the history
+            // hash, so it must not requeue for the next read — that would re-flood.
+            if (e.length > 0)
+                setOffset(current, args.source, args.room, startOffset + e.length);
+            return current;
+        });
+    }
+    // CCR overflow handling (room and status sources). When the backlog exceeds
+    // the window, return the RECENT slice raw and replace the older overflow with
+    // a compact digest carrying a retrieval hash. The agent expands it on demand
+    // via retrieve_room_history. Peek is side-effect-free, so it never stashes —
+    // it reports the count and tells the agent to do a real read to get a hash.
+    let recent = entries;
+    let history;
+    if (args.source !== "inbox" && effectiveLimit && entries.length > effectiveLimit) {
+        const overflow = entries.slice(0, entries.length - effectiveLimit);
+        recent = entries.slice(entries.length - effectiveLimit);
+        const stashKey = args.source === "room" ? normalizeRoom(args.room) : "status";
+        if (args.peek) {
+            history = { digest: digestOverflow(overflow, undefined), older: overflow.length };
+        }
+        else {
+            const hash = await stashHistory(stashKey, args.agentId, overflow);
+            history = { digest: digestOverflow(overflow, hash), hash, older: overflow.length };
+        }
+    }
+    else if (effectiveLimit && entries.length > effectiveLimit) {
+        // Inbox keeps the legacy oldest-first chunking (no stash) — targeted
+        // messages must never be skipped over.
+        recent = entries.slice(0, effectiveLimit);
+    }
+    // Drop the agent's own posts on shared channels — reading your own broadcast
+    // back is never useful and confuses turn-based agents into self-replies.
+    // Cursor has already advanced past them, so they won't reappear.
+    const visible = args.source === "room" || args.source === "status"
+        ? recent.filter((e) => entryAuthor(e) !== args.agentId)
+        : recent;
+    return {
+        ok: true,
+        messages: visible,
+        totalNew,
+        returned: visible.length,
+        room: args.source === "room" ? normalizeRoom(args.room) : undefined,
+        ...(history ? { history } : {}),
+    };
+}
+// Lossless summary of a stashed backlog slice: surfaces error/failure posts
+// verbatim (the lines that usually matter most in a flood) and collapses the
+// rest to counts. Mirrors headroom's content-aware digest, kept deliberately
+// simple — the full originals are one retrieve_room_history call away.
+function digestOverflow(over, hash) {
+    const authors = new Set(over.map(entryAuthor).filter(Boolean));
+    const errorRe = /\b(error|fatal|fail(ed|ure)?|panic|exception)\b/i;
+    const errors = over.filter((m) => errorRe.test(JSON.stringify(m)));
+    const first = over[0]?.ts;
+    const last = over[over.length - 1]?.ts;
+    const span = first && last && last > first ? ` over ${Math.round((last - first) / 60000)}m` : "";
+    const parts = [
+        `[${over.length} earlier message${over.length === 1 ? "" : "s"} compressed`,
+        `${authors.size} agent${authors.size === 1 ? "" : "s"}${span}`,
+    ];
+    if (errors.length)
+        parts.push(`${errors.length} error post${errors.length === 1 ? "" : "s"}`);
+    const head = parts.join(", ");
+    const tail = hash
+        ? ` hash=${hash}] — call retrieve_room_history(hash="${hash}") to expand`
+        : `] — read without peek to get an expandable hash`;
+    // Decisions are the one thing a digest must not bury — quote them verbatim
+    // (capped) below the summary line.
+    const decisions = over.filter((m) => m.kind === "decision");
+    const quoted = decisions
+        .slice(-5)
+        .map((d) => `  [decision] ${d.from}: ${d.text.length > 200 ? d.text.slice(0, 200) + "…" : d.text}`);
+    const decisionBlock = decisions.length
+        ? `\n${quoted.join("\n")}${decisions.length > 5 ? `\n  (+${decisions.length - 5} earlier decisions in hash)` : ""}`
+        : "";
+    return head + tail + decisionBlock;
+}
+// ---------- retrieve_room_history ----------
+export const retrieveRoomHistorySchema = {
+    agentId: z.string().min(1),
+    hash: z.string().min(1),
+    query: z.string().optional(),
+};
+export async function retrieveRoomHistoryTool(args) {
+    const res = await retrieveHistory(args.hash, args.agentId, args.query);
+    if (!res.ok) {
+        const reason = res.reason === "expired"
+            ? "That history entry has expired (30m TTL). Re-read the channel with a higher limit to fetch it again."
+            : res.reason === "forbidden"
+                ? "That history hash was produced for a different agent and cannot be retrieved by you."
+                : "No history entry for that hash. It may have expired or never existed.";
+        return { ok: false, reason: res.reason, message: reason };
+    }
+    return {
+        ok: true,
+        room: res.room,
+        hash: args.hash,
+        total: res.total,
+        returned: res.messages.length,
+        messages: res.messages,
+    };
+}
+function entryAuthor(e) {
+    return "from" in e ? e.from : e.agentId;
+}
+// ---------- 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);
+    await maybeCompactStatus();
+    return { ok: true, id: entry.id };
+}
+// ---------- wait_for_message ----------
+export const waitForMessageSchema = {
+    agentId: z.string().min(1),
+    source: z.enum(["inbox", "room", "status"]),
+    room: z.string().optional(),
+    timeoutMs: z.number().int().positive().max(MAX_WAIT_MS).optional(),
+};
+export async function waitForMessageTool(args) {
+    const totalTimeout = Math.min(args.timeoutMs ?? 30_000, MAX_WAIT_MS);
+    const file = sourceFile(args.source, args.agentId, args.room);
+    const deadline = Date.now() + totalTimeout;
+    // Loop so that file growth caused only by the agent's own self-posts (which
+    // readMessagesTool now filters out for room/status) doesn't return an empty
+    // result — keep waiting until we have something to deliver or time out.
+    while (Date.now() < deadline) {
+        const startSize = await fileSize(file);
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        const changed = await new Promise((resolve) => {
+            let settled = false;
+            const finish = (v) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearInterval(poll);
+                try {
+                    watcher?.close();
+                }
+                catch {
+                    // ignore
+                }
+                clearTimeout(t);
+                resolve(v);
+            };
+            const check = async () => {
+                const sz = await fileSize(file);
+                if (sz > startSize)
+                    finish(true);
+            };
+            let watcher;
+            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), remaining);
+        });
+        if (!changed)
+            break;
+        const result = await readMessagesTool({ agentId: args.agentId, source: args.source, room: args.room });
+        if (result.returned > 0)
+            return result;
+        // otherwise, only self-posts arrived; keep waiting on the remaining budget
+    }
+    return { ok: false, timedOut: true };
+}
+//# sourceMappingURL=messaging.js.map