agent-inbox 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inbox",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Agent Inbox — message routing, traceability, and MCP tools for multi-agent systems",
   "type": "module",
   "main": "dist/index.js",
@@ -13,6 +13,7 @@
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest",
+    "bench:growth": "vitest run --config vitest.bench.config.ts",
     "start": "node dist/index.js",
     "publish:npm": "npm publish --access public",
     "prepublishOnly": "npm run build",
@@ -25,7 +26,7 @@
     "url": "git+https://github.com/alexngai/agent-inbox.git"
   },
   "keywords": [],
-  "author": "",
+  "author": "Alex Ngai",
   "license": "ISC",
   "bugs": {
     "url": "https://github.com/alexngai/agent-inbox/issues"
@@ -40,8 +41,8 @@
     "ulid": "^2.3.0"
   },
   "peerDependencies": {
-    "@multi-agent-protocol/sdk": "^0.1.4",
-    "agentic-mesh": ">=0.2.0"
+    "@multi-agent-protocol/sdk": "*",
+    "agentic-mesh": "*"
   },
   "peerDependenciesMeta": {
     "@multi-agent-protocol/sdk": {

package/src/index.ts

@@ -119,6 +119,18 @@ export interface CreateOptions {
   httpPort?: number;
   /** Webhook URLs for push notifications */
   webhooks?: string[];
+  /** Per-agent inbox file (NDJSON) caps. Defaults: 1000 entries, 5 MiB. */
+  inboxFile?: {
+    maxEntries?: number;
+    maxBytes?: number;
+  };
+  /** Periodic retention sweep — deletes messages (and their turns) older
+   *  than `maxAgeMs`. Disabled unless configured. */
+  retention?: {
+    maxAgeMs: number;
+    /** Sweep interval. Defaults to one hour. */
+    sweepIntervalMs?: number;
+  };
   /** Enable federation with peer systems */
   enableFederation?: boolean;
   /** Use an externally-managed MAP connection instead of creating one.
@@ -173,7 +185,12 @@ export async function createAgentInbox(
 
   // 5. Push notifier (per-agent inbox files + webhooks + event emission)
   const notifier = new PushNotifier(
-    { inboxDir: defaultInboxDir(), webhooks: opts.webhooks },
+    {
+      inboxDir: defaultInboxDir(),
+      webhooks: opts.webhooks,
+      maxEntriesPerInbox: opts.inboxFile?.maxEntries,
+      maxBytesPerInbox: opts.inboxFile?.maxBytes,
+    },
     storage,
     events
   );
@@ -323,7 +340,27 @@ export async function createAgentInbox(
   const ipcServer = new IpcServer(socketPath, router, storage, jsonRpc);
   await ipcServer.start();
 
+  // 10. Retention sweep (opt-in)
+  let retentionTimer: NodeJS.Timeout | null = null;
+  if (opts.retention && opts.retention.maxAgeMs > 0) {
+    const interval = opts.retention.sweepIntervalMs ?? 60 * 60 * 1000;
+    const maxAgeMs = opts.retention.maxAgeMs;
+    const sweep = () => {
+      const cutoff = new Date(Date.now() - maxAgeMs).toISOString();
+      try {
+        storage.pruneMessagesOlderThan(cutoff);
+      } catch (err) {
+        console.error(
+          `Retention sweep failed: ${err instanceof Error ? err.message : err}`
+        );
+      }
+    };
+    retentionTimer = setInterval(sweep, interval);
+    if (typeof retentionTimer.unref === "function") retentionTimer.unref();
+  }
+
   const stop = async () => {
+    if (retentionTimer) clearInterval(retentionTimer);
     await ipcServer.stop();
     await jsonRpc.stopHttp();
     await mapClient.disconnect();

package/src/jsonrpc/mail-push-types.ts

@@ -38,6 +38,15 @@ export interface MailTurnReceivedParams {
   content: MessageContent;
   thread_id?: string;
   created_at: string;
+  /**
+   * Optional importance hint for dispatch-thread turns. When present,
+   * receivers should use this to drive wake/interrupt decisions rather
+   * than falling back to a static default.
+   *
+   * Values follow the agent-inbox Importance type:
+   * `"low"` | `"normal"` | `"high"` | `"urgent"`
+   */
+  importance?: string;
 }
 
 /**
@@ -54,5 +63,6 @@ export function buildMailTurnReceivedParams(turn: Turn): MailTurnReceivedParams
     content: turn.content,
     ...(turn.thread_id ? { thread_id: turn.thread_id } : {}),
     created_at: turn.created_at,
+    ...(turn.importance ? { importance: turn.importance } : {}),
   };
 }

package/src/jsonrpc/mail-server.ts

@@ -36,11 +36,21 @@ export class MailJsonRpcServer {
   private httpServer: http.Server | null = null;
   private subscribers = new Set<http.ServerResponse>();
 
+  /**
+   * Optional presence registry for resolving agent online/offline status.
+   * When provided, `mail/presence` enriches participants with live status.
+   */
+  private registry?: {
+    getStatus(agentId: string): string;
+  };
+
   constructor(
     private storage: Storage,
     private router: MessageRouter,
-    private events: EventEmitter
+    private events: EventEmitter,
+    registry?: { getStatus(agentId: string): string }
   ) {
+    this.registry = registry;
     this.registerMethods();
     this.setupEventForwarding();
   }
@@ -95,6 +105,20 @@ export class MailJsonRpcServer {
       return { ok: true };
     });
 
+    // mail/reopen — reopen a completed conversation
+    this.methods.set("mail/reopen", (params) => {
+      const conv = this.storage.getConversation(params.id as string);
+      if (!conv) throw rpcError(-32001, "Conversation not found");
+      conv.status = "active";
+      conv.updated_at = new Date().toISOString();
+      this.storage.putConversation(conv);
+      this.events.emit("mail.reopened", {
+        conversation_id: conv.id,
+        status: conv.status,
+      });
+      return { conversationId: conv.id, status: "active" };
+    });
+
     // mail/join — add self as participant
     this.methods.set("mail/join", (params) => {
       const conv = this.storage.getConversation(
@@ -162,6 +186,7 @@ export class MailJsonRpcServer {
       );
       if (!conv) throw rpcError(-32001, "Conversation not found");
 
+      const importance = params.importance as Turn["importance"] | undefined;
       const turn: Turn = {
         id: `turn-${ulid()}`,
         conversation_id: conv.id,
@@ -172,6 +197,7 @@ export class MailJsonRpcServer {
         thread_id: params.threadId as string | undefined,
         in_reply_to: params.inReplyTo as string | undefined,
         created_at: new Date().toISOString(),
+        ...(importance ? { importance } : {}),
       };
 
       this.storage.addTurn(turn);
@@ -220,6 +246,24 @@ export class MailJsonRpcServer {
         threads: this.storage.getThreadsByConversation(conv.id),
       };
     });
+
+    // mail/presence — list participants with live presence status
+    this.methods.set("mail/presence", (params) => {
+      const conversationId = params.conversationId as string;
+      if (!conversationId) throw rpcError(-32602, "conversationId required");
+
+      const conv = this.storage.getConversation(conversationId);
+      if (!conv) throw rpcError(-32001, "Conversation not found");
+
+      const participants = (conv.participants ?? []).map((p) => ({
+        agent_id: p.agent_id,
+        role: p.role,
+        joined_at: p.joined_at,
+        presence: this.registry?.getStatus(p.agent_id) ?? "unknown",
+      }));
+
+      return { conversationId, participants };
+    });
   }
 
   /** Process a JSON-RPC request (used by both IPC and HTTP transports) */
@@ -355,6 +399,9 @@ export class MailJsonRpcServer {
     this.events.on("mail.closed", (data) => {
       this.broadcast("mail.closed", data);
     });
+    this.events.on("mail.reopened", (data) => {
+      this.broadcast("mail.reopened", data);
+    });
   }
 
   private broadcast(eventType: string, data: unknown): void {

package/src/push/notifier.ts

@@ -21,8 +21,19 @@ export interface NotifierConfig {
   inboxDir: string;
   /** Optional webhook URLs to POST new messages to */
   webhooks?: string[];
+  /** Soft cap on entries per per-agent inbox file. The file is allowed to
+   *  grow ~10% over this before being trimmed back, to amortize trim cost
+   *  across many appends. Defaults to 1000. Set to 0 to disable. */
+  maxEntriesPerInbox?: number;
+  /** Soft cap (in bytes) on per-agent inbox file size, with the same ~10%
+   *  amortization headroom as `maxEntriesPerInbox`. Defaults to 5 MiB. Set
+   *  to 0 to disable. */
+  maxBytesPerInbox?: number;
 }
 
+const DEFAULT_MAX_ENTRIES = 1000;
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+
 export interface InboxFileEntry {
   messageId: string;
   from: string;
@@ -43,6 +54,11 @@ export interface InboxMessageEvent {
 
 export class PushNotifier {
   private webhooks: string[];
+  private maxEntries: number;
+  private maxBytes: number;
+  /** In-memory tracking so we can decide when to trim without stat/read. */
+  private entryCounts = new Map<string, number>();
+  private fileSizes = new Map<string, number>();
 
   constructor(
     private config: NotifierConfig,
@@ -50,6 +66,9 @@ export class PushNotifier {
     private events: EventEmitter
   ) {
     this.webhooks = config.webhooks ?? [];
+    this.maxEntries =
+      config.maxEntriesPerInbox ?? DEFAULT_MAX_ENTRIES;
+    this.maxBytes = config.maxBytesPerInbox ?? DEFAULT_MAX_BYTES;
 
     // Subscribe to message.created events
     events.on("message.created", (msg: Message) => this.onMessage(msg));
@@ -91,11 +110,86 @@ export class PushNotifier {
       importance: message.importance,
       timestamp: message.created_at,
     };
+    const line = JSON.stringify(entry) + "\n";
     try {
-      fs.appendFileSync(filePath, JSON.stringify(entry) + "\n");
+      fs.appendFileSync(filePath, line);
     } catch {
-      // Best-effort write
+      return; // Best-effort write
+    }
+
+    if (this.maxEntries <= 0 && this.maxBytes <= 0) return;
+    this.bumpCounters(filePath, line.length);
+    this.maybeEnforceCap(filePath);
+  }
+
+  /** Update in-memory entry/size counters after an append. Lazy-inits from
+   *  the file when first seen so caps still apply across process restarts. */
+  private bumpCounters(filePath: string, addedBytes: number): void {
+    let count = this.entryCounts.get(filePath);
+    let size = this.fileSizes.get(filePath);
+    if (count === undefined || size === undefined) {
+      try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        count = raw.split("\n").filter((l) => l.length > 0).length;
+        size = raw.length;
+      } catch {
+        count = 1;
+        size = addedBytes;
+      }
+    } else {
+      count++;
+      size += addedBytes;
+    }
+    this.entryCounts.set(filePath, count);
+    this.fileSizes.set(filePath, size);
+  }
+
+  /** Trim the file when soft caps (~1.1× the configured limits) are exceeded.
+   *  This amortizes the cost of read+rewrite across many appends. */
+  private maybeEnforceCap(filePath: string): void {
+    const count = this.entryCounts.get(filePath) ?? 0;
+    const size = this.fileSizes.get(filePath) ?? 0;
+
+    const overEntries =
+      this.maxEntries > 0 && count > this.maxEntries * 1.1;
+    const overBytes =
+      this.maxBytes > 0 && size > this.maxBytes * 1.1;
+
+    if (!overEntries && !overBytes) return;
+
+    const result = this.trimFile(filePath);
+    this.entryCounts.set(filePath, result.lines);
+    this.fileSizes.set(filePath, result.bytes);
+  }
+
+  /** Trim the file to maxEntries / maxBytes. Returns counts of what's left. */
+  private trimFile(filePath: string): { lines: number; bytes: number } {
+    let raw: string;
+    try {
+      raw = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      return { lines: 0, bytes: 0 };
+    }
+    let kept = raw.split("\n").filter((l) => l.length > 0);
+
+    if (this.maxEntries > 0 && kept.length > this.maxEntries) {
+      kept = kept.slice(kept.length - this.maxEntries);
+    }
+    let bytes = kept.reduce((acc, l) => acc + l.length + 1, 0);
+    if (this.maxBytes > 0) {
+      while (kept.length > 1 && bytes > this.maxBytes) {
+        bytes -= kept[0].length + 1;
+        kept.shift();
+      }
+    }
+
+    const out = kept.length ? kept.join("\n") + "\n" : "";
+    try {
+      fs.writeFileSync(filePath, out);
+    } catch {
+      // Best-effort
     }
+    return { lines: kept.length, bytes: out.length };
   }
 
   /** Read and format an agent's pending inbox as markdown (for hook injection) */
@@ -126,6 +220,8 @@ export class PushNotifier {
     // Clear the file
     try {
       fs.writeFileSync(filePath, "");
+      this.entryCounts.set(filePath, 0);
+      this.fileSizes.set(filePath, 0);
     } catch {
       // Best-effort clear
     }

package/src/storage/interface.ts

@@ -27,14 +27,25 @@ export interface Storage {
   // Messages
   getMessage(id: string): Message | undefined;
   putMessage(message: Message): Message;
+  /** Set the conversation_id on an existing message without rewriting the row. */
+  setMessageConversationId(messageId: string, conversationId: string): void;
   getInbox(agentId: string, opts?: InboxQuery): Message[];
   getThread(query: ThreadQuery): Message[];
   getSentMessages(agentId: string, limit?: number): Message[];
   searchMessages(query: string, scope?: string): Message[];
+  /** Delete messages older than `cutoff` (ISO timestamp). Returns the count removed. */
+  pruneMessagesOlderThan(cutoff: string): number;
 
   // Conversations
   getConversation(id: string): Conversation | undefined;
   putConversation(conversation: Conversation): Conversation;
+  /** Bump conversation updated_at without rewriting participants. */
+  touchConversation(conversationId: string, updatedAt: string): void;
+  /** Add a participant if not already present. No-op if already a participant. */
+  addParticipant(
+    conversationId: string,
+    participant: { agent_id: string; role?: string; joined_at: string }
+  ): void;
   listConversations(scope?: string): Conversation[];
 
   // Turns

package/src/storage/memory.ts

@@ -45,6 +45,29 @@ export class InMemoryStorage implements Storage {
     return message;
   }
 
+  setMessageConversationId(messageId: string, conversationId: string): void {
+    const msg = this.messages.get(messageId);
+    if (msg) msg.conversation_id = conversationId;
+  }
+
+  pruneMessagesOlderThan(cutoff: string): number {
+    let removed = 0;
+    const removedIds = new Set<string>();
+    for (const [id, msg] of this.messages) {
+      if (msg.created_at < cutoff) {
+        this.messages.delete(id);
+        removedIds.add(id);
+        removed++;
+      }
+    }
+    if (removedIds.size > 0) {
+      this.turns = this.turns.filter(
+        (t) => !t.source_message_id || !removedIds.has(t.source_message_id)
+      );
+    }
+    return removed;
+  }
+
   getInbox(agentId: string, opts?: InboxQuery): Message[] {
     const results: Message[] = [];
     for (const msg of this.messages.values()) {
@@ -108,6 +131,27 @@ export class InMemoryStorage implements Storage {
     return conversation;
   }
 
+  touchConversation(conversationId: string, updatedAt: string): void {
+    const conv = this.conversations.get(conversationId);
+    if (conv) conv.updated_at = updatedAt;
+  }
+
+  addParticipant(
+    conversationId: string,
+    participant: { agent_id: string; role?: string; joined_at: string }
+  ): void {
+    const conv = this.conversations.get(conversationId);
+    if (!conv) return;
+    if (conv.participants.some((p) => p.agent_id === participant.agent_id)) {
+      return;
+    }
+    conv.participants.push({
+      agent_id: participant.agent_id,
+      role: participant.role,
+      joined_at: participant.joined_at,
+    });
+  }
+
   listConversations(scope?: string): Conversation[] {
     const all = Array.from(this.conversations.values());
     if (!scope) return all;

package/src/storage/sqlite.ts

@@ -36,6 +36,8 @@ export class SqliteStorage implements Storage {
       this.db = new Database(path);
       this.db.pragma("journal_mode = WAL");
       this.db.pragma("foreign_keys = ON");
+      // Bound the WAL file: checkpoint after ~1000 dirty pages (~4 MiB).
+      this.db.pragma("wal_autocheckpoint = 1000");
       this.externalDb = false;
     }
 
@@ -162,7 +164,11 @@ export class SqliteStorage implements Storage {
                ELSE '' END);
       END;
 
-      CREATE TRIGGER IF NOT EXISTS ${t("messages_au")} AFTER UPDATE ON ${t("messages")} BEGIN
+      -- Drop legacy unscoped trigger if present, so we re-create it with OF clause
+      DROP TRIGGER IF EXISTS ${t("messages_au")};
+
+      CREATE TRIGGER IF NOT EXISTS ${t("messages_au")}
+      AFTER UPDATE OF subject, content ON ${t("messages")} BEGIN
         INSERT INTO ${t("messages_fts")}(${t("messages_fts")}, rowid, id, subject, text_content)
         VALUES ('delete', OLD.rowid, OLD.id, OLD.subject,
           CASE WHEN json_extract(OLD.content, '$.type') = 'text'
@@ -277,6 +283,52 @@ export class SqliteStorage implements Storage {
     return message;
   }
 
+  setMessageConversationId(messageId: string, conversationId: string): void {
+    this.db
+      .prepare(
+        `UPDATE ${this.p("messages")} SET conversation_id = ? WHERE id = ?`
+      )
+      .run(conversationId, messageId);
+  }
+
+  pruneMessagesOlderThan(cutoff: string): number {
+    const m = this.p("messages");
+    const r = this.p("recipients");
+    const turns = this.p("turns");
+    const threads = this.p("threads");
+
+    return this.db.transaction(() => {
+      const ids = (
+        this.db
+          .prepare(`SELECT id FROM ${m} WHERE created_at < ?`)
+          .all(cutoff) as { id: string }[]
+      ).map((row) => row.id);
+
+      if (ids.length === 0) return 0;
+
+      const placeholders = ids.map(() => "?").join(",");
+      this.db
+        .prepare(`DELETE FROM ${r} WHERE message_id IN (${placeholders})`)
+        .run(...ids);
+      this.db
+        .prepare(
+          `DELETE FROM ${turns} WHERE source_message_id IN (${placeholders})`
+        )
+        .run(...ids);
+      // Threads pinned to a pruned root turn are now orphans — drop them.
+      this.db
+        .prepare(
+          `DELETE FROM ${threads} WHERE root_turn_id NOT IN (SELECT id FROM ${turns})`
+        )
+        .run();
+      this.db
+        .prepare(`DELETE FROM ${m} WHERE id IN (${placeholders})`)
+        .run(...ids);
+
+      return ids.length;
+    })();
+  }
+
   getInbox(agentId: string, opts?: InboxQuery): Message[] {
     const m = this.p("messages");
     const r = this.p("recipients");
@@ -414,6 +466,31 @@ export class SqliteStorage implements Storage {
     return conversation;
   }
 
+  touchConversation(conversationId: string, updatedAt: string): void {
+    this.db
+      .prepare(
+        `UPDATE ${this.p("conversations")} SET updated_at = ? WHERE id = ?`
+      )
+      .run(updatedAt, conversationId);
+  }
+
+  addParticipant(
+    conversationId: string,
+    participant: { agent_id: string; role?: string; joined_at: string }
+  ): void {
+    this.db
+      .prepare(
+        `INSERT OR IGNORE INTO ${this.p("participants")}
+         (conversation_id, agent_id, role, joined_at) VALUES (?, ?, ?, ?)`
+      )
+      .run(
+        conversationId,
+        participant.agent_id,
+        participant.role ?? null,
+        participant.joined_at
+      );
+  }
+
   listConversations(scope?: string): Conversation[] {
     let rows: ConversationRow[];
     if (scope) {

package/src/traceability/traceability.ts

@@ -30,16 +30,15 @@ export class TraceabilityLayer {
   private onMessage(message: Message): void {
     const conversationId = this.resolveConversation(message);
 
-    // Update message's conversation_id if not already set
+    // Update message's conversation_id if not already set. Use a targeted
+    // UPDATE rather than re-upserting the whole row + recipients.
     if (!message.conversation_id) {
       message.conversation_id = conversationId;
-      this.storage.putMessage(message);
+      this.storage.setMessageConversationId(message.id, conversationId);
     }
 
-    // Ensure sender is a participant
+    // Ensure sender + recipients are participants (no-op if already present)
     this.ensureParticipant(conversationId, message.sender_id);
-
-    // Ensure recipients are participants
     for (const r of message.recipients) {
       this.ensureParticipant(conversationId, r.agent_id);
     }
@@ -64,12 +63,8 @@ export class TraceabilityLayer {
 
     this.storage.addTurn(turn);
 
-    // Update conversation updated_at
-    const conv = this.storage.getConversation(conversationId);
-    if (conv) {
-      conv.updated_at = message.created_at;
-      this.storage.putConversation(conv);
-    }
+    // Bump conversation updated_at — single column UPDATE, no participant resync.
+    this.storage.touchConversation(conversationId, message.created_at);
   }
 
   private resolveConversation(message: Message): string {
@@ -129,14 +124,10 @@ export class TraceabilityLayer {
   }
 
   private ensureParticipant(conversationId: string, agentId: string): void {
-    const conv = this.storage.getConversation(conversationId);
-    if (!conv) return;
-    if (conv.participants.some((p) => p.agent_id === agentId)) return;
-    conv.participants.push({
+    this.storage.addParticipant(conversationId, {
       agent_id: agentId,
       joined_at: new Date().toISOString(),
     });
-    this.storage.putConversation(conv);
   }
 
   private resolveThread(

package/src/types.ts

@@ -83,6 +83,7 @@ export interface Turn {
   content: MessageContent;
   thread_id?: string;
   in_reply_to?: string;
+  importance?: Importance;
   created_at: string;
 }