agent-inbox 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inbox",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Agent Inbox — message routing, traceability, and MCP tools for multi-agent systems",
   "type": "module",
   "main": "dist/index.js",
@@ -13,9 +13,10 @@
     "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",
+    "prepublishOnly": "npm run build && publint",
     "version:patch": "npm version patch && git push && git push --tags",
     "version:minor": "npm version minor && git push && git push --tags",
     "version:major": "npm version major && git push && git push --tags"
@@ -41,7 +42,12 @@
   },
   "peerDependencies": {
     "@multi-agent-protocol/sdk": "*",
-    "agentic-mesh": "*"
+    "agentic-mesh": "*",
+    "mailauth": "*",
+    "mailparser": "*",
+    "nodemailer": "*",
+    "postmark": "*",
+    "smtp-server": "*"
   },
   "peerDependenciesMeta": {
     "@multi-agent-protocol/sdk": {
@@ -49,12 +55,32 @@
     },
     "agentic-mesh": {
       "optional": true
+    },
+    "mailauth": {
+      "optional": true
+    },
+    "mailparser": {
+      "optional": true
+    },
+    "nodemailer": {
+      "optional": true
+    },
+    "postmark": {
+      "optional": true
+    },
+    "smtp-server": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.0.0",
     "agentic-mesh": "^0.2.0",
+    "mailauth": "^4.6.6",
+    "mailparser": "^3.6.6",
+    "nodemailer": "^6.9.0",
+    "publint": "^0.3.21",
+    "smtp-server": "^3.13.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/renovate.json5

@@ -0,0 +1,6 @@
+{
+  // Dependency-update policy is shared across the swarm/openhive ecosystem.
+  // See github.com/alexngai/swarm-renovate-config.
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["github>alexngai/swarm-renovate-config"]
+}

package/rules/agent-inbox.md

@@ -60,6 +60,7 @@ read_thread({ threadTag: "deploy-v2" })
 - `"bob"` — local agent on this system
 - `"bob@system-2"` — agent on a federated remote system
 - `"@system-2"` — broadcast to all agents on a remote system
+- `"person@example.com"` — an external email address (only when email interop is enabled for that domain; otherwise the send is rejected). Replies from that person arrive back in your inbox like any other message, and threading is preserved.
 
 ## Discovering other agents
 

package/src/federation/connection-manager.ts

@@ -59,6 +59,8 @@ export class ConnectionManager {
   private meshConnector: MeshConnector | null;
   private meshPeer: MeshPeerLike | null;
   private onIncoming: IncomingMessageHandler | null;
+  /** Optional predicate marking recipients owned by the mail gateway (skipped). */
+  private mailFilter: ((agentId: string) => boolean) | null = null;
   readonly routing: RoutingEngine;
   readonly queue: DeliveryQueue;
   readonly trust: TrustManager;
@@ -110,6 +112,15 @@ export class ConnectionManager {
     return this.systemId;
   }
 
+  /**
+   * Register a predicate identifying recipients handled by the mail gateway.
+   * Those recipients are skipped by route() so a `bob@example.com` address is
+   * not mistaken for a federation peer.
+   */
+  setMailRecipientFilter(fn: (agentId: string) => boolean): void {
+    this.mailFilter = fn;
+  }
+
   /**
    * Establish federation with a peer. Uses MAP federation/connect protocol.
    * If an SDK class was injected, opens a real MAP connection to the peer.
@@ -264,6 +275,7 @@ export class ConnectionManager {
   async route(message: Message): Promise<DeliveryResult> {
     // Determine target for each recipient
     for (const recipient of message.recipients) {
+      if (this.mailFilter?.(recipient.agent_id)) continue; // handled by mail gateway
       const addr = parseAddress(recipient.agent_id);
       if (!isRemoteAddress(addr)) continue;
 

package/src/federation/delivery-queue.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from "node:events";
 import { ulid } from "ulid";
 import type { Message, DeliveryQueueConfig, QueuedMessage } from "../types.js";
+import type { QueueStore } from "./queue-store.js";
 
 const DEFAULT_CONFIG: DeliveryQueueConfig = {
   persistence: "memory",
@@ -16,19 +17,37 @@ const DEFAULT_CONFIG: DeliveryQueueConfig = {
 /**
  * Delivery queue for messages to offline or unreachable federation peers.
  *
- * Supports configurable TTL, overflow policy, and retry strategy.
- * Currently memory-only; SQLite persistence is a future enhancement.
+ * Supports configurable TTL, overflow policy, and retry strategy. Keeps an
+ * in-memory index for fast reads; when a durable QueueStore is supplied, every
+ * mutation is write-through journaled and the index is hydrated from the store
+ * on construction so queued messages survive a restart.
  */
 export class DeliveryQueue {
   private queues = new Map<string, QueuedMessage[]>();
   private config: DeliveryQueueConfig;
   private tickTimer?: ReturnType<typeof setInterval>;
+  private store: QueueStore | null;
 
   constructor(
     private events: EventEmitter,
-    config?: Partial<DeliveryQueueConfig>
+    config?: Partial<DeliveryQueueConfig>,
+    opts?: { store?: QueueStore }
   ) {
     this.config = { ...DEFAULT_CONFIG, ...config };
+    this.store = opts?.store ?? null;
+    if (this.store) this.hydrate(this.store);
+  }
+
+  /** Load persisted entries into the in-memory index (durable mode). */
+  private hydrate(store: QueueStore): void {
+    for (const entry of store.loadAll()) {
+      let queue = this.queues.get(entry.peerId);
+      if (!queue) {
+        queue = [];
+        this.queues.set(entry.peerId, queue);
+      }
+      queue.push(entry);
+    }
   }
 
   /**
@@ -44,9 +63,11 @@ export class DeliveryQueue {
     // Check queue size limit
     if (queue.length >= this.config.maxQueueSize) {
       switch (this.config.overflow) {
-        case "drop-oldest":
-          queue.shift();
+        case "drop-oldest": {
+          const dropped = queue.shift();
+          if (dropped) this.store?.remove(peerId, dropped.id);
           break;
+        }
         case "drop-newest":
           return null; // Don't enqueue
         case "reject-new":
@@ -65,6 +86,7 @@ export class DeliveryQueue {
     };
 
     queue.push(entry);
+    this.store?.upsert(entry);
     this.events.emit("queue.enqueued", { peerId, messageId: entry.id });
     return entry.id;
   }
@@ -79,6 +101,7 @@ export class DeliveryQueue {
 
     const messages = [...queue];
     this.queues.delete(peerId);
+    this.store?.removePeer(peerId);
     this.events.emit("queue.flushed", { peerId, count: messages.length });
     return messages;
   }
@@ -123,6 +146,7 @@ export class DeliveryQueue {
         ? this.config.retryBaseInterval * Math.pow(2, entry.attempts - 1)
         : this.config.retryBaseInterval;
     entry.nextRetry = new Date(Date.now() + delay).toISOString();
+    this.store?.upsert(entry);
     return true;
   }
 
@@ -137,6 +161,7 @@ export class DeliveryQueue {
     if (idx === -1) return false;
 
     queue.splice(idx, 1);
+    this.store?.remove(peerId, messageId);
     if (queue.length === 0) this.queues.delete(peerId);
     return true;
   }
@@ -150,10 +175,15 @@ export class DeliveryQueue {
 
     for (const [peerId, queue] of this.queues.entries()) {
       const before = queue.length;
-      const remaining = queue.filter((entry) => {
+      const remaining: QueuedMessage[] = [];
+      for (const entry of queue) {
         const age = now - new Date(entry.enqueuedAt).getTime();
-        return age < this.config.maxTTL;
-      });
+        if (age < this.config.maxTTL) {
+          remaining.push(entry);
+        } else {
+          this.store?.remove(peerId, entry.id);
+        }
+      }
       expired += before - remaining.length;
 
       if (remaining.length === 0) {

package/src/federation/queue-store.ts

@@ -0,0 +1,124 @@
+/**
+ * Durable persistence for the delivery queue.
+ *
+ * The DeliveryQueue keeps an in-memory index for fast reads and write-through
+ * journals every mutation to a QueueStore. On construction it hydrates the
+ * in-memory index from the store, so queued messages survive a restart.
+ *
+ * Two impls: the default in-memory behavior needs no store (pass none), and
+ * SqliteQueueStore backs durable mode (DeliveryQueueConfig.persistence = "sqlite").
+ */
+
+import type Database from "better-sqlite3";
+import type { QueuedMessage } from "../types.js";
+
+export interface QueueStore {
+  /** Insert or replace an entry. */
+  upsert(entry: QueuedMessage): void;
+  /** Remove a single entry by peer + message id. */
+  remove(peerId: string, messageId: string): void;
+  /** Remove all entries for a peer (e.g. on flush). */
+  removePeer(peerId: string): void;
+  /** Load all persisted entries (called once on hydrate). */
+  loadAll(): QueuedMessage[];
+}
+
+/** SQLite-backed durable queue store using a borrowed better-sqlite3 handle. */
+export class SqliteQueueStore implements QueueStore {
+  private table: string;
+  private upsertStmt: Database.Statement;
+  private removeStmt: Database.Statement;
+  private removePeerStmt: Database.Statement;
+  private loadStmt: Database.Statement;
+
+  /**
+   * @param db     A better-sqlite3 handle (lifecycle owned by the caller).
+   * @param prefix Table name prefix to match the Storage convention. Default "".
+   */
+  constructor(
+    private db: Database.Database,
+    prefix: string = ""
+  ) {
+    this.table = `${prefix}delivery_queue`;
+    this.migrate();
+    this.upsertStmt = this.db.prepare(
+      `INSERT INTO ${this.table}
+         (id, peer_id, message, enqueued_at, attempts, last_attempt, next_retry)
+       VALUES (@id, @peer_id, @message, @enqueued_at, @attempts, @last_attempt, @next_retry)
+       ON CONFLICT(id) DO UPDATE SET
+         peer_id = excluded.peer_id,
+         message = excluded.message,
+         enqueued_at = excluded.enqueued_at,
+         attempts = excluded.attempts,
+         last_attempt = excluded.last_attempt,
+         next_retry = excluded.next_retry`
+    );
+    this.removeStmt = this.db.prepare(
+      `DELETE FROM ${this.table} WHERE peer_id = ? AND id = ?`
+    );
+    this.removePeerStmt = this.db.prepare(
+      `DELETE FROM ${this.table} WHERE peer_id = ?`
+    );
+    this.loadStmt = this.db.prepare(
+      `SELECT id, peer_id, message, enqueued_at, attempts, last_attempt, next_retry
+         FROM ${this.table} ORDER BY enqueued_at ASC`
+    );
+  }
+
+  private migrate(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.table} (
+        id TEXT PRIMARY KEY,
+        peer_id TEXT NOT NULL,
+        message TEXT NOT NULL,
+        enqueued_at TEXT NOT NULL,
+        attempts INTEGER NOT NULL DEFAULT 0,
+        last_attempt TEXT,
+        next_retry TEXT
+      );
+      CREATE INDEX IF NOT EXISTS ${this.table}_peer_idx
+        ON ${this.table}(peer_id);
+    `);
+  }
+
+  upsert(entry: QueuedMessage): void {
+    this.upsertStmt.run({
+      id: entry.id,
+      peer_id: entry.peerId,
+      message: JSON.stringify(entry.message),
+      enqueued_at: entry.enqueuedAt,
+      attempts: entry.attempts,
+      last_attempt: entry.lastAttempt ?? null,
+      next_retry: entry.nextRetry ?? null,
+    });
+  }
+
+  remove(peerId: string, messageId: string): void {
+    this.removeStmt.run(peerId, messageId);
+  }
+
+  removePeer(peerId: string): void {
+    this.removePeerStmt.run(peerId);
+  }
+
+  loadAll(): QueuedMessage[] {
+    const rows = this.loadStmt.all() as Array<{
+      id: string;
+      peer_id: string;
+      message: string;
+      enqueued_at: string;
+      attempts: number;
+      last_attempt: string | null;
+      next_retry: string | null;
+    }>;
+    return rows.map((r) => ({
+      id: r.id,
+      peerId: r.peer_id,
+      message: JSON.parse(r.message),
+      enqueuedAt: r.enqueued_at,
+      attempts: r.attempts,
+      lastAttempt: r.last_attempt ?? undefined,
+      nextRetry: r.next_retry ?? undefined,
+    }));
+  }
+}

package/src/index.ts

@@ -16,6 +16,14 @@ import { DeliveryBridge } from "./mesh/delivery-bridge.js";
 import type { MeshContextLike } from "./mesh/mesh-transport.js";
 import type { MeshPeerLike, MeshMapServer } from "./map/map-client.js";
 import { WarmRegistry } from "./registry/warm-registry.js";
+import { MailGateway } from "./mail/mail-gateway.js";
+import { SmtpTransport } from "./mail/smtp-transport.js";
+import { PostmarkTransport } from "./mail/provider-transport.js";
+import type { MailTransport } from "./mail/types.js";
+import { SqliteAttachmentStore } from "./mail/attachment-store.js";
+import { FsAttachmentStore } from "./mail/fs-attachment-store.js";
+import { SqliteQueueStore } from "./federation/queue-store.js";
+import { findDomainConflicts } from "./router/destination.js";
 import type { InboxConfig } from "./types.js";
 import type { Storage } from "./storage/interface.js";
 
@@ -62,6 +70,52 @@ export type { MeshDeliveryHandler } from "./mesh/delivery-bridge.js";
 export { mapMessageToInbox, inboxMessageToMap } from "./mesh/type-mapper.js";
 export type { MapMessage as MeshMapMessage, MapAddress as MeshMapAddress } from "./mesh/type-mapper.js";
 export type { MeshPeerLike, MeshAgentConnection, MeshMapServer } from "./map/map-client.js";
+// Mail interop
+export { MailGateway, RateLimitedError } from "./mail/mail-gateway.js";
+export type { MailGatewayConfig } from "./mail/mail-gateway.js";
+export { RateLimiter } from "./mail/rate-limiter.js";
+export { SmtpTransport, parseDsnFromParsed } from "./mail/smtp-transport.js";
+export type { SmtpTransportOptions } from "./mail/smtp-transport.js";
+export {
+  PostmarkTransport,
+  outboundToPostmark,
+  postmarkInboundToMail,
+  postmarkBounceToInbound,
+  postmarkResponseToResult,
+  postmarkErrorToResult,
+} from "./mail/provider-transport.js";
+export type {
+  PostmarkTransportOptions,
+  PostmarkClient,
+  PostmarkInbound,
+  PostmarkBounce,
+} from "./mail/provider-transport.js";
+export { AddressBook } from "./mail/address-book.js";
+export { SqliteAttachmentStore } from "./mail/attachment-store.js";
+export { FsAttachmentStore } from "./mail/fs-attachment-store.js";
+export {
+  inboundMailToMessage,
+  messageToOutboundMail,
+  UnknownRecipientError,
+} from "./mail/email-mapper.js";
+export {
+  classifyDestination,
+  UnknownDestinationError,
+  domainMatches,
+  findDomainConflicts,
+} from "./router/destination.js";
+export type { Destination, DestinationContext } from "./router/destination.js";
+export type {
+  MailTransport,
+  MailCapabilities,
+  OutboundMail,
+  InboundMail,
+  MailSendResult,
+  InboundBounce,
+  InboundAuthResults,
+  AttachmentStore,
+} from "./mail/types.js";
+export type { MailEgress } from "./router/message-router.js";
 export type * from "./types.js";
 export type { Storage, InboxQuery, ThreadQuery } from "./storage/interface.js";
 
@@ -103,6 +157,7 @@ export interface AgentInbox {
   notifier: PushNotifier;
   federation: ConnectionManager | null;
   registry: WarmRegistry | null;
+  mail: MailGateway | null;
   events: EventEmitter;
   stop(): Promise<void>;
 }
@@ -119,6 +174,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 +240,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
   );
@@ -311,6 +383,97 @@ export async function createAgentInbox(
     federation.queue.startTicking();
   }
 
+  // 7b. Mail interop (inbound + outbound email)
+  let mail: MailGateway | null = null;
+  if (config.mail?.enabled) {
+    const mailConfig = config.mail;
+
+    // Surface domains claimed by both a federation peer and mail config —
+    // federation wins (see classifyDestination), but operators should know.
+    const mailDomains = [
+      ...mailConfig.identity.localDomains,
+      ...(mailConfig.routableDomains ?? []),
+    ];
+    const domainConflicts = findDomainConflicts({
+      isLocalAgent: () => false,
+      federationPeers: config.federation?.peers ?? [],
+      mailDomains,
+    });
+    if (domainConflicts.length > 0) {
+      events.emit("mail.config.conflict", {
+        kind: "domain",
+        conflicts: domainConflicts,
+      });
+      console.error(
+        `Mail config warning: domain(s) claimed by both federation and mail — federation wins: ${domainConflicts.join(", ")}`
+      );
+    }
+
+    // Durable queue + attachment storage when backed by SQLite.
+    const db =
+      storage instanceof SqliteStorage ? storage.getDatabase() : undefined;
+    const queueStore = db ? new SqliteQueueStore(db) : undefined;
+
+    // Attachment storage: filesystem (opt-in) or SQLite BLOBs (default).
+    let attachmentStore: SqliteAttachmentStore | FsAttachmentStore | undefined;
+    if (mailConfig.attachments?.backend === "fs") {
+      const dir =
+        mailConfig.attachments.dir ??
+        path.join(os.homedir(), ".claude", "agent-inbox", "attachments");
+      attachmentStore = new FsAttachmentStore(dir);
+    } else if (db) {
+      attachmentStore = new SqliteAttachmentStore(db);
+    }
+
+    const transport: MailTransport =
+      mailConfig.backend === "provider"
+        ? new PostmarkTransport({
+            serverToken: mailConfig.provider?.apiKeyRef,
+            webhook: mailConfig.provider?.webhookPath
+              ? { port: 0, inboundPath: mailConfig.provider.webhookPath }
+              : undefined,
+            attachmentStore,
+          })
+        : new SmtpTransport({
+            listenPort: mailConfig.smtp?.listenPort,
+            relay: mailConfig.smtp?.relay,
+            dkim: mailConfig.smtp?.dkim
+              ? {
+                  domainName: mailConfig.smtp.dkim.domain,
+                  keySelector: mailConfig.smtp.dkim.selector,
+                  privateKey: mailConfig.smtp.dkim.privateKeyRef,
+                }
+              : undefined,
+            attachmentStore,
+          });
+
+    mail = new MailGateway({
+      transport,
+      storage,
+      router,
+      events,
+      queueStore,
+      config: {
+        identity: mailConfig.identity,
+        routableDomains: mailConfig.routableDomains,
+        allowedSenderDomains: mailConfig.allowedSenderDomains,
+        rejectDmarcFail: mailConfig.rejectDmarcFail,
+        maxAttachments: mailConfig.maxAttachments,
+        rateLimit: mailConfig.rateLimit,
+        bounce: mailConfig.bounce,
+        defaultScope: config.scope,
+        queue: mailConfig.queue,
+      },
+    });
+
+    router.setMail(mail);
+    federation?.setMailRecipientFilter((id) => mail!.ownsRecipient(id));
+    await mail.start();
+    console.error(
+      `Mail interop enabled (${mailConfig.backend}) for domains: ${mailConfig.identity.localDomains.join(", ")}`
+    );
+  }
+
   // 8. JSON-RPC server (mail/* methods)
   const jsonRpc = new MailJsonRpcServer(storage, router, events);
   if (opts.httpPort && opts.httpPort > 0) {
@@ -323,9 +486,30 @@ 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();
+    if (mail) await mail.stop();
     await mapClient.disconnect();
     if (federation) await federation.destroy();
     if (registry) registry.destroy();
@@ -344,6 +528,7 @@ export async function createAgentInbox(
     notifier,
     federation,
     registry,
+    mail,
     events,
     stop,
   };

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 } : {}),
   };
 }