agent-coord-mcp 0.9.0 → 0.13.0

package/scripts/coord-chat.mjs

@@ -43,6 +43,9 @@ import lockfile from "proper-lockfile";
 const args = parseArgs(process.argv.slice(2));
 let ID = args.id ?? process.env.USER ?? "human"; // reassignable so /nick can rebind it
 const ROOT = args.dir ?? process.env.AGENT_COORD_DIR ?? path.join(homedir(), "agent-coord");
+// Pin the env so a dynamically-imported dist tool (e.g. /doctor's doctorTool)
+// binds store.js's ROOT to the same dir when --dir overrode the default.
+process.env.AGENT_COORD_DIR = ROOT;
 
 // Message-rendering state + helpers. Declared up here (above the top-level
 // printRecent() call) so they're initialized before first use — const/let
@@ -186,6 +189,15 @@ const AGENT_COLORS = [
 ];
 // Will be initialized after ROOT is set, just below.
 
+// ---------- non-interactive --doctor ----------
+// `coord-chat --doctor [--fix]` runs the same health check as the MCP doctor
+// tool and prints its report, then exits — no registration, no TUI. Same
+// renderer as the /doctor slash command, so CLI and in-chat output match.
+if (args.doctor) {
+  const ok = await runDoctor(!!args.fix, (l) => process.stdout.write(l + "\n"));
+  process.exit(ok ? 0 : 1);
+}
+
 // ---------- register and start UI ----------
 
 await register();
@@ -219,7 +231,7 @@ const SLASH_COMMANDS = [
   "/dm", "/msg", "/list", "/who", "/whoami", "/whois", "/last", "/find",
   "/clear", "/cls", "/me", "/status", "/away", "/back", "/ignore", "/unignore",
   "/nick", "/join", "/part", "/leave", "/rooms", "/channels", "/topic", "/motd",
-  "/rules", "/prune", "/kick", "/wipe-room",
+  "/rules", "/prune", "/kick", "/wipe-room", "/doctor",
   "/help", "/?", "/quit", "/exit",
 ];
 
@@ -442,6 +454,9 @@ async function handleLine(line) {
       const term = text.slice(6).trim();
       if (!term) say(A.red("usage: /find <text>"));
       else await findInHistory(term);
+    } else if (text === "/doctor" || text.startsWith("/doctor ")) {
+      const fix = text.slice(7).trim() === "--fix";
+      await runDoctor(fix, say);
     } else if (text.startsWith("/")) {
       say(A.red(`unknown command: ${text.split(" ")[0]}`) + A.dim("  (try /help)"));
     } else {
@@ -477,10 +492,13 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === "--id") out.id = argv[++i];
     else if (argv[i] === "--dir") out.dir = argv[++i];
+    else if (argv[i] === "--doctor") out.doctor = true;
+    else if (argv[i] === "--fix") out.fix = true;
     else if (argv[i] === "-h" || argv[i] === "--help") {
       console.log("coord-chat — minimal TUI for agent-coord-mcp");
       console.log("usage: coord-chat [--id <name>] [--dir <path>]");
-      console.log("at prompt: <text>=room  /dm <id> <text>  /list  /quit");
+      console.log("       coord-chat --doctor [--fix]   health-check coord state, print report, exit");
+      console.log("at prompt: <text>=room  /dm <id> <text>  /list  /doctor  /quit");
       process.exit(0);
     }
   }
@@ -624,6 +642,7 @@ function printHelp() {
     ["/prune [days]",       "drop messages older than N days (default 7)"],
     ["/kick <agent>",       "unregister an agent + kill their pusher"],
     ["/wipe-room",          "truncate the current channel (destructive)"],
+    ["/doctor [--fix]",     "health-check coord state (--fix auto-remediates)"],
     [A.dim("---"),          ""],
     ["/help, /?",           "this list"],
     ["/quit [msg], /exit",  "unregister and leave"],
@@ -735,6 +754,44 @@ async function postStatus(status) {
   say(A.dim(`→ status posted: ${status}`));
 }
 
+// Run the shared doctor health check and render its structured report through
+// `emit` (say for the TUI, console for CLI). Delegates to the compiled MCP
+// doctorTool so the output is the single source of truth — no reimplemented,
+// drift-prone checks. Returns true when nothing is at error level. `emit` is
+// injected so the same renderer serves both /doctor and `--doctor`.
+async function runDoctor(fix, emit) {
+  let doctorTool;
+  try {
+    ({ doctorTool } = await import(new URL("../dist/tools.js", import.meta.url)));
+  } catch (e) {
+    emit(A.red(`/doctor unavailable: could not load the doctor tool (${e?.message ?? e}).`));
+    emit(A.dim("  This build may be missing dist/ — run `npm run build` in the package."));
+    return false;
+  }
+  const icon = { ok: A.green("✓"), warn: A.yellow("!"), error: A.red("✗") };
+  const res = await doctorTool({ fix });
+  emit(
+    A.bold("coord doctor") +
+      A.dim(`  root=${res.root}`) +
+      (fix ? A.dim("  (--fix applied)") : ""),
+  );
+  for (const f of res.findings) {
+    emit(`  ${icon[f.level] ?? "?"} ${A.bold(f.check)}  ${f.detail}`);
+    for (const item of f.items ?? []) emit(A.dim(`      - ${item}`));
+  }
+  for (const done of res.fixed ?? []) emit(A.green(`  fixed: ${done}`));
+  const s = res.summary;
+  emit(
+    A.dim("  ") +
+      `${A.green(`${s.ok} ok`)}  ${A.yellow(`${s.warn} warn`)}  ${A.red(`${s.error} error`)}` +
+      (res.healthy ? A.green("  — healthy") : A.red("  — needs attention")),
+  );
+  if (!fix && res.findings.some((f) => f.fixable && f.level !== "ok")) {
+    emit(A.dim("  run /doctor --fix to auto-remediate fixable findings"));
+  }
+  return res.summary.error === 0;
+}
+
 async function pruneOld(days) {
   const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
   let total = 0;

package/src/server.ts

@@ -28,6 +28,8 @@ import {
   leaveRoomTool,
   listAgentsSchema,
   listAgentsTool,
+  pingSchema,
+  pingTool,
   listRoomsSchema,
   listRoomsTool,
   postStatusSchema,
@@ -36,6 +38,8 @@ import {
   pruneTool,
   readMessagesSchema,
   readMessagesTool,
+  retrieveRoomHistorySchema,
+  retrieveRoomHistoryTool,
   registerSchema,
   registerTool,
   renameAgentSchema,
@@ -166,6 +170,13 @@ function buildServer(initialBound?: string): McpServer {
     gate("agentId", heartbeatTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  server.tool(
+    "ping",
+    "Liveness probe for another agent, answered entirely from server-side state (registry entry, transport marker, pusher pid, tmux pane) — it never touches the target's session, so a fleet-wide sweep costs zero model tokens on the targets. Returns alive (fresh heartbeat or live transport), reachable (a DM pushed now would land), granular checks, and latencyMs. Distinct from heartbeat, which is an agent refreshing its OWN activity timestamp. Pass echo:true (default off) to additionally drop a PING DM into the target's inbox — that wakes the target's model, so use it sparingly and only when you need an agent-level acknowledgement. 'from' is enforced against the session's bound identity.",
+    pingSchema,
+    gate("from", pingTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
   server.tool(
     "list_agents",
     "List all known agents and whether they appear online (heartbeat <5min).",
@@ -189,11 +200,18 @@ function buildServer(initialBound?: string): McpServer {
 
   server.tool(
     "read_messages",
-    "Read new messages from inbox|room|status. For source='room', pass 'room' to read a specific channel (default 'general'). Room reads default to 50 messages per call — pass limit to override (max 500). Inbox and status drain fully by default. Advances the per-channel cursor unless peek=true.",
+    "Read new messages from inbox|room|status. For source='room', pass 'room' to read a specific channel (default 'general'). Room and status reads return the most recent 50 entries per call — pass limit to override (max 500). When the backlog exceeds the window, the older overflow is replaced by a compact `history` digest carrying a retrieval hash; call retrieve_room_history(hash) to expand it. Inbox drains fully by default. Advances the per-channel cursor unless peek=true.",
     readMessagesSchema,
     gate("agentId", readMessagesTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  server.tool(
+    "retrieve_room_history",
+    "Expand a compressed channel-history digest returned by read_messages. Pass the `hash` from the `history` field; optionally pass `query` to return only matching messages (case-insensitive substring). Entries are scoped to the agent that produced them and expire after 30 minutes — if expired, re-read the channel with a higher limit instead.",
+    retrieveRoomHistorySchema,
+    gate("agentId", retrieveRoomHistoryTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
   server.tool(
     "post_status",
     "Append a status broadcast to the shared status stream.",

package/src/store.ts

@@ -1,4 +1,5 @@
 import { promises as fs, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import path from "node:path";
 import lockfile from "proper-lockfile";
@@ -23,6 +24,18 @@ export const LOG_DIR = path.join(ROOT, "logs");
 // `written-to-jsonl:true`, at zero added agent token cost.
 export const RECEIPTS_DIR = path.join(ROOT, "receipts");
 
+// Reversible-history cache (CCR pattern, v0.9.x). When read_messages would
+// flood an agent with a large channel backlog, the overflow (everything older
+// than the recent window) is stashed here as one entry and replaced inline by
+// a compact digest carrying a `hash`. The agent expands it on demand via
+// retrieve_room_history(hash). Entries are content+scope addressed, TTL'd, and
+// scoped to the (room, agent) they were produced for so a hash can't be
+// replayed to read a channel the caller never read itself. This is a cache of
+// data ALREADY present in rooms/<chan>.jsonl — not a new source of truth — so
+// losing it (TTL/eviction) only costs the agent a re-read at a higher limit.
+export const HISTORY_DIR = path.join(ROOT, "history");
+export const HISTORY_TTL_MS = 30 * 60_000; // session-scale; mirrors headroom DEFAULT_CCR_TTL_SECONDS
+
 // Channels. The default channel `general` keeps using the legacy single-room
 // file (room.jsonl) + the flat `roomOffset` cursor key, so existing agents and
 // the notification hooks keep working with zero migration. Every other channel
@@ -40,7 +53,7 @@ export const DEFAULT_ROOM = "general";
 export const TOKENS_FILE = path.join(ROOT, "tokens.json");
 
 export function ensureDirs(): void {
-  for (const d of [ROOT, INBOX_DIR, CURSOR_DIR, TRANSPORT_DIR, PID_DIR, LOG_DIR, ROOMS_DIR, RECEIPTS_DIR]) {
+  for (const d of [ROOT, INBOX_DIR, CURSOR_DIR, TRANSPORT_DIR, PID_DIR, LOG_DIR, ROOMS_DIR, RECEIPTS_DIR, HISTORY_DIR]) {
     if (!existsSync(d)) mkdirSync(d, { recursive: true });
   }
   for (const f of [ROOM_FILE, STATUS_FILE]) {
@@ -349,3 +362,96 @@ export async function fileSize(file: string): Promise<number> {
   const st = await fs.stat(file);
   return st.size;
 }
+
+// ---------- reversible history cache (CCR) ----------
+
+export type HistoryEntry<T = unknown> = {
+  hash: string;
+  room: string;
+  forAgent: string; // scope key — only this agent may retrieve (see HISTORY_DIR note)
+  createdTs: number;
+  messages: T[];
+};
+
+function historyFile(hash: string): string {
+  return path.join(HISTORY_DIR, `${sanitize(hash)}.json`);
+}
+
+// Content+scope address: same backlog read by two agents (or twice by one)
+// yields distinct entries, and the hash can't be guessed for a (room, agent)
+// pair the caller never read. 12 hex chars ≈ 48 bits — collision-safe at this
+// volume, short enough to sit inline in the digest marker.
+function historyHash(room: string, forAgent: string, messages: { ts: number }[]): string {
+  const first = messages[0]?.ts ?? 0;
+  const last = messages[messages.length - 1]?.ts ?? 0;
+  const sig = `${room}${forAgent}${first}${last}${messages.length}`;
+  return createHash("sha1").update(sig).digest("hex").slice(0, 12);
+}
+
+// Best-effort sweep of expired entries. Cheap (one readdir + stat per file) and
+// only the data is a disposable cache, so we swallow all errors.
+export async function pruneHistory(now = Date.now()): Promise<void> {
+  if (!existsSync(HISTORY_DIR)) return;
+  let names: string[];
+  try {
+    names = await fs.readdir(HISTORY_DIR);
+  } catch {
+    return;
+  }
+  await Promise.all(
+    names
+      .filter((n) => n.endsWith(".json"))
+      .map(async (n) => {
+        const f = path.join(HISTORY_DIR, n);
+        try {
+          const e = await readJsonNoLock<HistoryEntry | null>(f, null);
+          if (!e || now - e.createdTs > HISTORY_TTL_MS) await fs.unlink(f).catch(() => {});
+        } catch {
+          /* leave it; next sweep retries */
+        }
+      }),
+  );
+}
+
+// Stash a backlog slice and return its hash. Caller embeds the hash in the
+// digest marker it returns to the agent.
+export async function stashHistory<T extends { ts: number }>(
+  room: string,
+  forAgent: string,
+  messages: T[],
+): Promise<string> {
+  const hash = historyHash(room, forAgent, messages);
+  const entry: HistoryEntry<T> = { hash, room, forAgent, createdTs: Date.now(), messages };
+  await writeJson(historyFile(hash), entry);
+  void pruneHistory();
+  return hash;
+}
+
+export type RetrieveHistoryResult<T = unknown> =
+  | { ok: true; room: string; total: number; messages: T[] }
+  | { ok: false; reason: "not_found" | "expired" | "forbidden" };
+
+// Expand a stashed backlog. Enforces the (forAgent) scope and TTL. `query`, if
+// given, returns only entries whose serialized form contains the substring
+// (case-insensitive) — the lossless analogue of headroom's BM25 search-within.
+export async function retrieveHistory<T = unknown>(
+  hash: string,
+  forAgent: string,
+  query?: string,
+): Promise<RetrieveHistoryResult<T>> {
+  const f = historyFile(hash);
+  const entry = await readJson<HistoryEntry<T> | null>(f, null);
+  if (!entry) return { ok: false, reason: "not_found" };
+  if (Date.now() - entry.createdTs > HISTORY_TTL_MS) {
+    await deleteFile(f).catch(() => {});
+    return { ok: false, reason: "expired" };
+  }
+  if (entry.forAgent !== forAgent) return { ok: false, reason: "forbidden" };
+
+  let messages = entry.messages;
+  if (query && query.trim()) {
+    const q = query.toLowerCase();
+    messages = messages.filter((m) => JSON.stringify(m).toLowerCase().includes(q));
+  }
+  return { ok: true, room: entry.room, total: entry.messages.length, messages };
+}

package/src/tools.ts

@@ -39,6 +39,9 @@ import {
   roomFile,
   rotateAgentToken,
   setRoomMeta,
+  stashHistory,
+  retrieveHistory,
+  pruneHistory,
   transportFile,
   TRANSPORT_DIR,
   updateJson,
@@ -86,6 +89,10 @@ type Message = {
   // its operator. The tmux pushers inject these RAW (no banner/prefix) so the
   // TUI runs them as real slash commands; every other consumer ignores them.
   control?: boolean;
+  // Server-generated push-now override (e.g. the post-/clear identity
+  // reminder). Only server code can set this — send_message constructs the
+  // Message from fixed fields, so peers cannot smuggle it in.
+  urgent?: boolean;
 };
 
 type StatusEntry = {
@@ -312,6 +319,79 @@ function isPidAlive(pid: number): boolean {
   }
 }
 
+// ---------- ping ----------
+
+export const pingSchema = {
+  from: z.string().min(1),
+  to: z.string().min(1),
+  echo: z.boolean().optional(),
+};
+
+// Liveness probe answered entirely from server-side state — registry entry,
+// transport marker, pusher pid, tmux pane. It never touches the target's
+// session, so a fleet-wide sweep costs zero model tokens on the targets.
+// Distinct from `heartbeat` (the target refreshing its own activity
+// timestamp): ping is a third party asking "would a DM land right now?".
+// echo=true is the one exception — it drops a PING DM into the target's inbox
+// (normal delivery, so the target's model DOES wake); opt-in, default off.
+export async function pingTool(args: { from: string; to: string; echo?: boolean }) {
+  const t0 = process.hrtime.bigint();
+  const now = Date.now();
+  const latencyMs = () => Math.round(Number(process.hrtime.bigint() - t0) / 1e3) / 1e3;
+
+  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
+  const entry = reg[args.to];
+  if (!entry) {
+    return { ok: true, to: args.to, alive: false, reachable: false, reason: "unregistered", latencyMs: latencyMs() };
+  }
+
+  const marker = await readJson<TransportMarker | null>(transportFile(args.to), null);
+  const heartbeatAgeSec = Math.floor((now - entry.lastHeartbeat) / 1000);
+  const heartbeatFresh = now - entry.lastHeartbeat < STALE_MS;
+
+  let transportLive = false;
+  let paneAlive: boolean | undefined;
+  if (marker) {
+    transportLive = isMarkerLive(marker, reg, now);
+    if (transportLive && marker.transport === "tmux-push" && marker.tmuxTarget) {
+      // The pusher can outlive its pane (agent window closed) — probe the pane.
+      const probe = spawnSync("tmux", ["display-message", "-p", "-t", marker.tmuxTarget, "ok"]);
+      paneAlive = probe.status === 0;
+    }
+  }
+
+  const reachable = transportLive && paneAlive !== false;
+  const alive = reachable || heartbeatFresh;
+
+  let echoSent = false;
+  if (args.echo && alive) {
+    await sendMessageTool({
+      from: args.from,
+      to: args.to,
+      text: `PING: echo requested by ${args.from} — DM back if responsive.`,
+    });
+    echoSent = true;
+  }
+
+  return {
+    ok: true,
+    to: args.to,
+    alive,
+    reachable,
+    ...(alive ? {} : { reason: marker ? "transport-dead" : "heartbeat-stale" }),
+    checks: {
+      registered: true,
+      heartbeatFresh,
+      heartbeatAgeSec,
+      transport: marker?.transport ?? null,
+      transportLive,
+      ...(paneAlive !== undefined ? { paneAlive, tmuxTarget: marker?.tmuxTarget } : {}),
+    },
+    ...(args.echo ? { echoSent } : {}),
+    latencyMs: latencyMs(),
+  };
+}
+
 // ---------- send_message ----------
 
 export const sendMessageSchema = {
@@ -455,6 +535,9 @@ function scheduleReminders(
           from,
           to: r,
           text: override ?? defaultReminderText(r),
+          // A just-cleared agent is contextless until this lands — it must
+          // push immediately, never queue behind the routine tier.
+          urgent: true,
         };
         await appendJsonl(inboxFile(r), reminder);
       } catch (e) {
@@ -643,40 +726,65 @@ export async function readMessagesTool(args: {
   const file = sourceFile(args.source, args.agentId, args.room);
   const all = await readJsonl<Message | StatusEntry>(file);
 
-  let limited: (Message | StatusEntry)[] = [];
+  let entries: (Message | StatusEntry)[] = [];
   let totalNew = 0;
 
-  // Room reads default to 50 messages to prevent agents flooding themselves
-  // with full channel history on join. Inbox and status drain fully by default
-  // since they are targeted/bounded by nature.
-  const effectiveLimit = args.limit ?? (args.source === "room" ? 50 : undefined);
+  // 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<Cursor>(cursorFile(args.agentId), {});
     const startOffset = getOffset(cursor, args.source, args.room);
-    let entries = all.slice(startOffset);
+    entries = all.slice(startOffset);
     if (args.sinceTs !== undefined) entries = entries.filter((e) => e.ts > args.sinceTs!);
     totalNew = entries.length;
-    limited = effectiveLimit ? entries.slice(0, effectiveLimit) : entries;
   } else {
     await updateJson<Cursor>(cursorFile(args.agentId), {}, (current) => {
       const startOffset = getOffset(current, args.source, args.room);
-      let entries = all.slice(startOffset);
-      if (args.sinceTs !== undefined) entries = entries.filter((e) => e.ts > args.sinceTs!);
-      totalNew = entries.length;
-      limited = effectiveLimit ? entries.slice(0, effectiveLimit) : entries;
-      if (limited.length > 0) setOffset(current, args.source, args.room, startOffset + limited.length);
+      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: { digest: string; hash?: string; older: number } | undefined;
+  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"
-      ? limited.filter((e) => entryAuthor(e) !== args.agentId)
-      : limited;
+      ? recent.filter((e) => entryAuthor(e) !== args.agentId)
+      : recent;
 
   return {
     ok: true,
@@ -684,6 +792,64 @@ export async function readMessagesTool(args: {
     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: (Message | StatusEntry)[], hash: string | undefined): string {
+  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`;
+  return head + tail;
+}
+
+// ---------- 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: {
+  agentId: string;
+  hash: string;
+  query?: string;
+}) {
+  const res = await retrieveHistory<Message | StatusEntry>(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,
   };
 }
 
@@ -950,6 +1116,10 @@ export async function pruneTool(args: {
     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,