@runravel/ravel 0.1.0

package/src/memory/genericTools.ts

@@ -0,0 +1,276 @@
+import { z } from "zod";
+import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import { MemoryStore, type MemoryScope } from "./store.js";
+import { withLock, lockKey, readJson, json } from "./kv.js";
+
+/**
+ * Platform-level, domain-agnostic memory tools over the generic `MemoryStore`.
+ * Three shapes cover essentially any team's durable state:
+ *  - **text**  — a freeform string at a key.
+ *  - **json**  — a structured value (object/array/scalar) at a key, with merge.
+ *  - **queue** — an append-only list with optional dedup-by-field, a cap, and
+ *                clear-by-field. (Watchlists, signal logs, candidate backlogs,
+ *                etc. are all queues; cursor maps are json.)
+ *
+ * All tools are **team-scoped by default**; pass `scope` to target the agent's
+ * private memory or the org-wide store. Org *writes* are gated: they require the
+ * agent to be granted `mem_allow_org_write`.
+ */
+
+const DEFAULT_LIST_LIMIT = 50;
+const MAX_LIST_LIMIT = 500;
+
+const ScopeArg = z.enum(["agent", "team", "org"]).optional();
+
+interface MemCtx {
+  nodeId: string;
+  managerNodeId: string;
+  memory: MemoryStore;
+}
+
+/** Resolve the optional `scope` arg to a concrete MemoryScope (default: team). */
+function resolveScope(arg: string | undefined, ctx: MemCtx): MemoryScope {
+  if (arg === "agent") return { kind: "agent", nodeId: ctx.nodeId };
+  if (arg === "org") return { kind: "org" };
+  return { kind: "team", managerNodeId: ctx.managerNodeId };
+}
+
+/** Guard org writes behind an explicit grant; returns an error result if blocked. */
+function orgWriteBlocked(scope: MemoryScope, allowOrgWrite: boolean): { ok: false; error: string } | null {
+  if (scope.kind === "org" && !allowOrgWrite) {
+    return { ok: false, error: "org-scope writes require the `mem_allow_org_write` grant" };
+  }
+  return null;
+}
+
+// --- queue operations --------------------------------------------------------
+
+/** A value's dedup identity: the named field (stringified) or the whole item. */
+function itemKey(item: unknown, dedupBy?: string): string {
+  if (dedupBy && item && typeof item === "object" && dedupBy in (item as Record<string, unknown>)) {
+    return `f:${String((item as Record<string, unknown>)[dedupBy])}`;
+  }
+  return `v:${JSON.stringify(item)}`;
+}
+
+async function queueAppend(
+  memory: MemoryStore,
+  scope: MemoryScope,
+  key: string,
+  items: unknown[],
+  opts: { dedupBy?: string; cap?: number; prepend?: boolean; allowOrgWrite: boolean },
+): Promise<{ ok: boolean; appended?: number; skipped?: number; count?: number; error?: string }> {
+  const blocked = orgWriteBlocked(scope, opts.allowOrgWrite);
+  if (blocked) return blocked;
+  return withLock(lockKey(scope, key), async () => {
+    const list = await readJson<unknown[]>(memory, scope, key, []);
+    const seen = new Set(list.map((it) => itemKey(it, opts.dedupBy)));
+    const fresh: unknown[] = [];
+    let skipped = 0;
+    for (const it of items) {
+      const k = itemKey(it, opts.dedupBy);
+      if (seen.has(k)) {
+        skipped += 1;
+        continue;
+      }
+      seen.add(k);
+      fresh.push(it);
+    }
+    let next = opts.prepend ? [...fresh, ...list] : [...list, ...fresh];
+    if (opts.cap !== undefined && next.length > opts.cap) {
+      // Keep the most recent `cap`: tail when appending, head when prepending.
+      next = opts.prepend ? next.slice(0, opts.cap) : next.slice(next.length - opts.cap);
+    }
+    if (fresh.length || next.length !== list.length) await memory.set(scope, key, JSON.stringify(next), { allowOrgWrite: opts.allowOrgWrite });
+    return { ok: true, appended: fresh.length, skipped, count: next.length };
+  });
+}
+
+async function queueClear(
+  memory: MemoryStore,
+  scope: MemoryScope,
+  key: string,
+  by: string,
+  values: string[],
+  allowOrgWrite: boolean,
+): Promise<{ ok: boolean; cleared?: number; count?: number; error?: string }> {
+  const blocked = orgWriteBlocked(scope, allowOrgWrite);
+  if (blocked) return blocked;
+  return withLock(lockKey(scope, key), async () => {
+    const list = await readJson<Record<string, unknown>[]>(memory, scope, key, []);
+    const drop = new Set(values.map((v) => String(v)));
+    const kept = list.filter((it) => !(it && typeof it === "object" && drop.has(String(it[by]))));
+    await memory.set(scope, key, JSON.stringify(kept), { allowOrgWrite });
+    return { ok: true, cleared: list.length - kept.length, count: kept.length };
+  });
+}
+
+// --- MCP server --------------------------------------------------------------
+
+export const GENERIC_MEMORY_TOOL_NAMES = [
+  "mem_text_get",
+  "mem_text_set",
+  "mem_keys",
+  "mem_json_get",
+  "mem_json_set",
+  "mem_json_merge",
+  "mem_queue_append",
+  "mem_queue_list",
+  "mem_queue_clear",
+  // Not a tool itself — a capability grant that unlocks org-scope writes.
+  "mem_allow_org_write",
+];
+
+/**
+ * Build the generic memory MCP server (`mem`) for the tools an agent was granted.
+ * Scoped to the agent (private), its team (default), or org (reads open; writes
+ * gated by `mem_allow_org_write`).
+ */
+export function buildGenericMemoryServer(grantedNames: string[], ctx: MemCtx): McpServerConfig | null {
+  const granted = new Set(grantedNames);
+  const allowOrgWrite = granted.has("mem_allow_org_write");
+  const tools = [];
+
+  if (granted.has("mem_text_get")) {
+    tools.push(
+      tool("mem_text_get", "Read a freeform text value by key (team scope by default).", { key: z.string(), scope: ScopeArg }, async (a) =>
+        json({ value: await ctx.memory.get(resolveScope(a["scope"] as string | undefined, ctx), String(a["key"])) }),
+      ),
+    );
+  }
+  if (granted.has("mem_text_set")) {
+    tools.push(
+      tool(
+        "mem_text_set",
+        "Write a freeform text value at a key.",
+        { key: z.string(), value: z.string(), scope: ScopeArg },
+        async (a) => {
+          const scope = resolveScope(a["scope"] as string | undefined, ctx);
+          const blocked = orgWriteBlocked(scope, allowOrgWrite);
+          if (blocked) return json(blocked);
+          await ctx.memory.set(scope, String(a["key"]), String(a["value"]), { allowOrgWrite });
+          return json({ ok: true });
+        },
+      ),
+    );
+  }
+  if (granted.has("mem_keys")) {
+    tools.push(
+      tool("mem_keys", "List the keys stored in a scope.", { scope: ScopeArg }, async (a) =>
+        json({ keys: await ctx.memory.list(resolveScope(a["scope"] as string | undefined, ctx)) }),
+      ),
+    );
+  }
+  if (granted.has("mem_json_get")) {
+    tools.push(
+      tool("mem_json_get", "Read a JSON value by key.", { key: z.string(), scope: ScopeArg }, async (a) =>
+        json({ value: await readJson(ctx.memory, resolveScope(a["scope"] as string | undefined, ctx), String(a["key"]), null) }),
+      ),
+    );
+  }
+  if (granted.has("mem_json_set")) {
+    tools.push(
+      tool(
+        "mem_json_set",
+        "Write a JSON value (object/array/scalar) at a key.",
+        { key: z.string(), value: z.unknown(), scope: ScopeArg },
+        async (a) => {
+          const scope = resolveScope(a["scope"] as string | undefined, ctx);
+          const blocked = orgWriteBlocked(scope, allowOrgWrite);
+          if (blocked) return json(blocked);
+          await ctx.memory.set(scope, String(a["key"]), JSON.stringify(a["value"] ?? null), { allowOrgWrite });
+          return json({ ok: true });
+        },
+      ),
+    );
+  }
+  if (granted.has("mem_json_merge")) {
+    tools.push(
+      tool(
+        "mem_json_merge",
+        "Shallow-merge a patch object into the JSON object stored at a key (creates it if absent).",
+        { key: z.string(), patch: z.record(z.unknown()), scope: ScopeArg },
+        async (a) => {
+          const scope = resolveScope(a["scope"] as string | undefined, ctx);
+          const blocked = orgWriteBlocked(scope, allowOrgWrite);
+          if (blocked) return json(blocked);
+          const key = String(a["key"]);
+          const result = await withLock(lockKey(scope, key), async () => {
+            const cur = await readJson<Record<string, unknown>>(ctx.memory, scope, key, {});
+            Object.assign(cur, (a["patch"] as Record<string, unknown>) ?? {});
+            await ctx.memory.set(scope, key, JSON.stringify(cur), { allowOrgWrite });
+            return cur;
+          });
+          return json({ ok: true, value: result });
+        },
+      ),
+    );
+  }
+  if (granted.has("mem_queue_append")) {
+    tools.push(
+      tool(
+        "mem_queue_append",
+        "Append items to a list at a key in ONE call. `dedupBy` skips items whose named " +
+          "field already exists; `cap` keeps only the most recent N; `prepend` adds to the front.",
+        {
+          key: z.string(),
+          items: z.array(z.unknown()),
+          dedupBy: z.string().optional(),
+          cap: z.number().optional(),
+          prepend: z.boolean().optional(),
+          scope: ScopeArg,
+        },
+        async (a) =>
+          json(
+            await queueAppend(ctx.memory, resolveScope(a["scope"] as string | undefined, ctx), String(a["key"]), (a["items"] as unknown[]) ?? [], {
+              ...(a["dedupBy"] !== undefined ? { dedupBy: String(a["dedupBy"]) } : {}),
+              ...(a["cap"] !== undefined ? { cap: Number(a["cap"]) } : {}),
+              ...(a["prepend"] !== undefined ? { prepend: Boolean(a["prepend"]) } : {}),
+              allowOrgWrite,
+            }),
+          ),
+      ),
+    );
+  }
+  if (granted.has("mem_queue_list")) {
+    tools.push(
+      tool(
+        "mem_queue_list",
+        "List a queue's items, bounded. Returns {total, returned, items} so you process a manageable batch.",
+        { key: z.string(), limit: z.number().optional(), scope: ScopeArg },
+        async (a) => {
+          const all = await readJson<unknown[]>(ctx.memory, resolveScope(a["scope"] as string | undefined, ctx), String(a["key"]), []);
+          const limit = Math.min(Math.max(Number(a["limit"] ?? DEFAULT_LIST_LIMIT), 1), MAX_LIST_LIMIT);
+          return json({ total: all.length, returned: Math.min(limit, all.length), items: all.slice(0, limit) });
+        },
+      ),
+    );
+  }
+  if (granted.has("mem_queue_clear")) {
+    tools.push(
+      tool(
+        "mem_queue_clear",
+        "Remove items from a queue whose `by` field matches one of `values`, in one call.",
+        { key: z.string(), by: z.string(), values: z.array(z.string()), scope: ScopeArg },
+        async (a) =>
+          json(
+            await queueClear(
+              ctx.memory,
+              resolveScope(a["scope"] as string | undefined, ctx),
+              String(a["key"]),
+              String(a["by"]),
+              (a["values"] as string[]) ?? [],
+              allowOrgWrite,
+            ),
+          ),
+      ),
+    );
+  }
+
+  if (tools.length === 0) return null;
+  return createSdkMcpServer({ name: "mem", version: "1.0.0", tools });
+}
+
+// Exported for unit tests and reuse by in-tree/plugin tools.
+export { queueAppend, queueClear, resolveScope };

package/src/memory/kv.ts

@@ -0,0 +1,52 @@
+import { MemoryStore, type MemoryScope } from "./store.js";
+
+/**
+ * Shared, domain-agnostic helpers over the generic `MemoryStore`. Used by both
+ * the platform's generic memory tools (`genericTools.ts`) and any in-tree/plugin
+ * tools that keep durable per-team state.
+ *
+ * `MemoryStore.set` is a whole-file overwrite with no locking, so every
+ * read-modify-write goes through a per-(scope,key) async mutex to avoid lost
+ * updates when agents write concurrently.
+ */
+
+// --- per-key serialization (mutex) ------------------------------------------
+
+const chains = new Map<string, Promise<unknown>>();
+
+/** Serialize async work per key so concurrent read-modify-writes don't clobber. */
+export function withLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const prev = chains.get(key) ?? Promise.resolve();
+  const result = prev.then(fn, fn);
+  // Swallow errors on the stored chain so one failure doesn't wedge the lock.
+  chains.set(
+    key,
+    result.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return result;
+}
+
+/** A stable lock key for a (scope, key) pair. */
+export function lockKey(scope: MemoryScope, key: string): string {
+  const s = scope.kind === "team" ? `team:${scope.managerNodeId}` : scope.kind === "agent" ? `agent:${scope.nodeId}` : "org";
+  return `${s}#${key}`;
+}
+
+/** Read a JSON-serialized value from memory, falling back on missing/corrupt. */
+export async function readJson<T>(memory: MemoryStore, scope: MemoryScope, key: string, fallback: T): Promise<T> {
+  const raw = await memory.get(scope, key);
+  if (!raw) return fallback;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+/** Wrap any value as an MCP tool text result (`{content:[{type:"text",...}]}`). */
+export function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value) }] };
+}

package/src/memory/store.ts

@@ -0,0 +1,76 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+/**
+ * Where a piece of memory lives. The hierarchy keeps agents from re-learning
+ * everything and contradicting each other:
+ * - `agent`: private to one agent (alongside its working dir).
+ * - `team`:  shared among the direct reports of one manager.
+ * - `org`:   company-wide facts/policies/glossary — read widely, written rarely.
+ */
+export type MemoryScope =
+  | { kind: "agent"; nodeId: string }
+  | { kind: "team"; managerNodeId: string }
+  | { kind: "org" };
+
+function sanitize(id: string): string {
+  return id === "" ? "_root" : id.replace(/\//g, "__");
+}
+
+/**
+ * File-backed memory keyed by scope + name. Values are plain text (markdown).
+ * `org` writes are gated: callers must pass `{ allowOrgWrite: true }` so a
+ * worker can't casually rewrite company-wide facts.
+ */
+export class MemoryStore {
+  constructor(private readonly root: string) {}
+
+  private dir(scope: MemoryScope): string {
+    switch (scope.kind) {
+      case "agent":
+        return path.join(this.root, "agent", sanitize(scope.nodeId));
+      case "team":
+        return path.join(this.root, "team", sanitize(scope.managerNodeId));
+      case "org":
+        return path.join(this.root, "org");
+    }
+  }
+
+  private file(scope: MemoryScope, key: string): string {
+    const safeKey = key.replace(/[^a-zA-Z0-9._-]/g, "_");
+    return path.join(this.dir(scope), `${safeKey}.md`);
+  }
+
+  async get(scope: MemoryScope, key: string): Promise<string | null> {
+    try {
+      return await fs.readFile(this.file(scope, key), "utf8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw err;
+    }
+  }
+
+  async set(
+    scope: MemoryScope,
+    key: string,
+    value: string,
+    opts: { allowOrgWrite?: boolean } = {},
+  ): Promise<void> {
+    if (scope.kind === "org" && !opts.allowOrgWrite) {
+      throw new Error("org memory is write-gated; pass { allowOrgWrite: true }");
+    }
+    const file = this.file(scope, key);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, value, "utf8");
+  }
+
+  async list(scope: MemoryScope): Promise<string[]> {
+    try {
+      const entries = await fs.readdir(this.dir(scope));
+      return entries.filter((e) => e.endsWith(".md")).map((e) => e.slice(0, -3)).sort();
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+      throw err;
+    }
+  }
+}

package/src/messaging/bus.ts

@@ -0,0 +1,143 @@
+import path from "node:path";
+import type { RegistryNode, RegistrySnapshot } from "../control-plane/registry.js";
+import type { AgentMessage, MessageDirection } from "../domain/types.js";
+import { newId, systemClock, type Clock } from "../domain/ids.js";
+import type { AuditSink } from "../trust/audit.js";
+import { Inbox, InboxFullError } from "./inbox.js";
+
+export interface MessageBusDeps {
+  audit: AuditSink;
+  /** Directory for durable inbox files; omit for in-memory inboxes. */
+  messagesDir?: string;
+  clock?: Clock;
+  inboxCap?: number;
+}
+
+export interface DeadLetter {
+  message: AgentMessage;
+  reason: string;
+}
+
+type Relation = MessageDirection | "invalid";
+
+/**
+ * Routes messages between agents through durable per-agent inboxes.
+ *
+ * Communication is constrained to the org topology: an agent may message DOWN
+ * (a direct report), UP (its manager), or SIDEWAYS (a peer under the same
+ * manager). Anything else is dead-lettered. When a recipient's inbox is full,
+ * the bus escalates an overflow note to that agent's manager rather than
+ * silently dropping work — backpressure that surfaces, not hides.
+ */
+export class MessageBus {
+  private nodes: ReadonlyMap<string, RegistryNode> = new Map();
+  private readonly inboxes = new Map<string, Inbox>();
+  readonly deadLetters: DeadLetter[] = [];
+  private readonly clock: Clock;
+
+  constructor(private readonly deps: MessageBusDeps) {
+    this.clock = deps.clock ?? systemClock;
+  }
+
+  /** Update the topology the bus validates against (called on each new snapshot). */
+  updateTopology(snapshot: RegistrySnapshot): void {
+    this.nodes = snapshot.nodes;
+  }
+
+  inbox(nodeId: string): Inbox {
+    let box = this.inboxes.get(nodeId);
+    if (!box) {
+      box = new Inbox(nodeId, {
+        ...(this.deps.inboxCap !== undefined ? { cap: this.deps.inboxCap } : {}),
+        ...(this.deps.messagesDir
+          ? { filePath: path.join(this.deps.messagesDir, `${nodeId === "" ? "_root" : nodeId.replace(/\//g, "__")}.json`) }
+          : {}),
+      });
+      this.inboxes.set(nodeId, box);
+    }
+    return box;
+  }
+
+  /** Build a message with id/timestamp filled in. */
+  compose(fields: Omit<AgentMessage, "id" | "enqueuedAt">): AgentMessage {
+    return { ...fields, id: newId("msg"), enqueuedAt: this.clock.iso() };
+  }
+
+  private relation(from: string, to: string): Relation {
+    const fromNode = this.nodes.get(from);
+    const toNode = this.nodes.get(to);
+    if (!fromNode || !toNode) return "invalid";
+    if (fromNode.parentId === to) return "up";
+    if (toNode.parentId === from) return "down";
+    if (fromNode.parentId !== null && fromNode.parentId === toNode.parentId) return "sideways";
+    return "invalid";
+  }
+
+  private async deadLetter(message: AgentMessage, reason: string): Promise<void> {
+    this.deadLetters.push({ message, reason });
+    await this.deps.audit.append("message.deadletter", {
+      nodeId: message.toNodeId,
+      data: { messageId: message.id, from: message.fromNodeId, reason },
+    });
+  }
+
+  /**
+   * Deliver a message. Returns the outcome so callers can react. Idempotent on
+   * message id (duplicate redelivery is a successful no-op).
+   */
+  async send(message: AgentMessage): Promise<"delivered" | "duplicate" | "deadletter" | "escalated"> {
+    const relation = this.relation(message.fromNodeId, message.toNodeId);
+    if (relation === "invalid") {
+      await this.deadLetter(message, "invalid_route");
+      return "deadletter";
+    }
+    if (relation !== message.direction) {
+      await this.deadLetter(message, `direction_mismatch (declared ${message.direction}, actual ${relation})`);
+      return "deadletter";
+    }
+
+    try {
+      const inserted = await this.inbox(message.toNodeId).enqueue(message);
+      if (!inserted) return "duplicate";
+      await this.deps.audit.append("message.delivered", {
+        nodeId: message.toNodeId,
+        data: { messageId: message.id, from: message.fromNodeId, kind: message.kind },
+      });
+      return "delivered";
+    } catch (err) {
+      if (!(err instanceof InboxFullError)) throw err;
+      return this.escalateOverflow(message);
+    }
+  }
+
+  /** On a full inbox, send an overflow note up to the recipient's manager. */
+  private async escalateOverflow(message: AgentMessage): Promise<"escalated" | "deadletter"> {
+    const recipient = this.nodes.get(message.toNodeId);
+    const managerId = recipient?.parentId ?? null;
+    if (managerId === null) {
+      await this.deadLetter(message, "inbox_full_no_manager");
+      return "deadletter";
+    }
+    const note = this.compose({
+      fromNodeId: message.toNodeId,
+      toNodeId: managerId,
+      direction: "up",
+      kind: "note",
+      subject: `Inbox overflow for ${message.toNodeId}`,
+      body: `Inbox is full; a message from ${message.fromNodeId} ("${message.subject}") could not be delivered and needs attention.`,
+      priority: 10,
+    });
+    await this.deps.audit.append("message.backpressure", {
+      nodeId: message.toNodeId,
+      data: { droppedMessageId: message.id, escalatedTo: managerId },
+    });
+    // Best-effort escalation; if the manager is also full, dead-letter the note.
+    try {
+      await this.inbox(managerId).enqueue(note);
+    } catch {
+      await this.deadLetter(note, "manager_inbox_full");
+    }
+    await this.deadLetter(message, "inbox_full_escalated");
+    return "escalated";
+  }
+}

package/src/messaging/inbox.ts

@@ -0,0 +1,119 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import type { AgentMessage } from "../domain/types.js";
+
+/**
+ * A durable, per-agent message queue. Delivery is at-least-once with
+ * idempotency by message id (a redelivered message with a known id is ignored).
+ * Messages are ordered by priority (desc) then enqueue time (asc) so the most
+ * urgent surface first when injected into the agent's context.
+ *
+ * Persistence is a simple rewrite-on-change of the pending set — queues are
+ * small (an agent that accumulates hundreds of messages is a design smell the
+ * backpressure cap is meant to catch).
+ */
+export class Inbox {
+  private pending: AgentMessage[] = [];
+  private readonly seen = new Set<string>();
+
+  constructor(
+    readonly nodeId: string,
+    private readonly opts: { cap?: number; filePath?: string } = {},
+  ) {}
+
+  get cap(): number {
+    return this.opts.cap ?? 100;
+  }
+
+  size(): number {
+    return this.pending.length;
+  }
+
+  isFull(): boolean {
+    return this.pending.length >= this.cap;
+  }
+
+  /** Load persisted messages from disk, if a file path was configured. */
+  async load(): Promise<void> {
+    if (!this.opts.filePath) return;
+    try {
+      const raw = await fs.readFile(this.opts.filePath, "utf8");
+      const parsed = JSON.parse(raw) as AgentMessage[];
+      this.pending = parsed;
+      for (const m of parsed) this.seen.add(m.id);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+  }
+
+  /**
+   * Enqueue a message. Returns false if it was a duplicate (already seen) — the
+   * caller can treat that as a successful no-op (idempotent redelivery).
+   * Throws if the inbox is full so the bus can apply backpressure.
+   */
+  async enqueue(message: AgentMessage): Promise<boolean> {
+    if (this.seen.has(message.id)) return false;
+    if (this.isFull()) throw new InboxFullError(this.nodeId);
+    this.seen.add(message.id);
+    this.pending.push(message);
+    this.sort();
+    await this.persist();
+    return true;
+  }
+
+  /** Remove and return up to `n` highest-priority messages. */
+  async dequeue(n = 1): Promise<AgentMessage[]> {
+    const taken = this.pending.splice(0, n);
+    if (taken.length) await this.persist();
+    return taken;
+  }
+
+  /** Non-destructive view, highest priority first. */
+  peek(): readonly AgentMessage[] {
+    return this.pending;
+  }
+
+  private sort(): void {
+    this.pending.sort((a, b) => b.priority - a.priority || a.enqueuedAt.localeCompare(b.enqueuedAt));
+  }
+
+  private async persist(): Promise<void> {
+    if (!this.opts.filePath) return;
+    await fs.mkdir(path.dirname(this.opts.filePath), { recursive: true });
+    await fs.writeFile(this.opts.filePath, JSON.stringify(this.pending), "utf8");
+  }
+}
+
+export class InboxFullError extends Error {
+  constructor(readonly nodeId: string) {
+    super(`inbox for ${nodeId} is full`);
+    this.name = "InboxFullError";
+  }
+}
+
+/**
+ * Turn a set of inbox messages into a bounded, prioritized context block for an
+ * agent's prompt. Messages are NEVER raw-replayed wholesale — they are ranked
+ * by priority and truncated to `maxChars`, with an explicit note about any that
+ * were omitted, so a flooded inbox can't blow the context window.
+ */
+export function summarizeInbox(messages: readonly AgentMessage[], maxChars = 4000): string {
+  if (messages.length === 0) return "(no new messages)";
+  const sorted = [...messages].sort(
+    (a, b) => b.priority - a.priority || a.enqueuedAt.localeCompare(b.enqueuedAt),
+  );
+  const lines: string[] = [];
+  let used = 0;
+  let included = 0;
+  for (const m of sorted) {
+    const body = m.body.length > 280 ? `${m.body.slice(0, 277)}...` : m.body;
+    const line = `- [${m.kind} ${m.direction} from ${m.fromNodeId}] ${m.subject}: ${body}`;
+    if (used + line.length > maxChars && included > 0) break;
+    lines.push(line);
+    used += line.length + 1;
+    included += 1;
+  }
+  const omitted = sorted.length - included;
+  if (omitted > 0) lines.push(`- (+${omitted} more lower-priority message(s) omitted)`);
+  return lines.join("\n");
+}