agent-inbox 0.2.2 → 0.2.4

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;
     }
 
@@ -126,6 +128,13 @@ export class SqliteStorage implements Storage {
         FOREIGN KEY (conversation_id) REFERENCES ${t("conversations")}(id)
       );
 
+      -- External-id mapping (mail dedup + bounce correlation)
+      CREATE TABLE IF NOT EXISTS ${t("external_ids")} (
+        external_id TEXT PRIMARY KEY,
+        message_id TEXT NOT NULL,
+        recorded_at TEXT NOT NULL
+      );
+
       -- Indexes for common queries
       CREATE INDEX IF NOT EXISTS idx_${t("messages")}_scope ON ${t("messages")}(scope);
       CREATE INDEX IF NOT EXISTS idx_${t("messages")}_sender ON ${t("messages")}(sender_id);
@@ -162,7 +171,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'
@@ -177,6 +190,12 @@ export class SqliteStorage implements Storage {
     `);
   }
 
+  /** Expose the underlying handle so sibling features (mail queue/attachments)
+   *  can co-locate their tables. Caller must not close it. */
+  getDatabase(): Database.Database {
+    return this.db;
+  }
+
   // --- Agents ---
 
   getAgent(agentId: string): Agent | undefined {
@@ -277,6 +296,75 @@ 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);
+  }
+
+  recordExternalId(externalId: string, messageId: string): void {
+    this.db
+      .prepare(
+        `INSERT INTO ${this.p("external_ids")} (external_id, message_id, recorded_at)
+         VALUES (?, ?, ?)
+         ON CONFLICT(external_id) DO NOTHING`
+      )
+      .run(externalId, messageId, new Date().toISOString());
+  }
+
+  getMessageIdByExternalId(externalId: string): string | undefined {
+    const row = this.db
+      .prepare(
+        `SELECT message_id FROM ${this.p("external_ids")} WHERE external_id = ?`
+      )
+      .get(externalId) as { message_id: string } | undefined;
+    return row?.message_id;
+  }
+
+  hasSeenExternalId(externalId: string): boolean {
+    return this.getMessageIdByExternalId(externalId) !== undefined;
+  }
+
+  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 +502,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;
 }
 
@@ -210,6 +211,11 @@ export interface FederationPeerConfig {
   url?: string;
   /** Mesh peer ID for agentic-mesh transport connections. */
   meshPeerId?: string;
+  /**
+   * Dotted addresses (e.g. "team.corp.internal") routed to this peer rather
+   * than treated as external mail. See destination classification (§1).
+   */
+  domains?: string[];
   auth?: FederationAuth;
   exposure?: ExposurePolicy;
 }
@@ -310,6 +316,73 @@ export interface QueuedMessage {
   nextRetry?: string;
 }
 
+// --- Mail interop ---
+
+/** Maps between agent ids and email addresses; declares owned domains. */
+export interface MailIdentityConfig {
+  /** Domains we receive for; inbound RCPT TO outside these is rejected. */
+  localDomains: string[];
+  /** agent_id ↔ primary email. Plus-addressing (agent+scope@domain) aware. */
+  mappings: Array<{ agentId: string; address: string }>;
+  /** Default mailbox for accepted-but-unmatched inbound (e.g. a triage agent). */
+  catchAllAgentId?: string;
+}
+
+export interface MailConfig {
+  enabled: boolean;
+  backend: "smtp" | "provider";
+  identity: MailIdentityConfig;
+  /**
+   * Domains we will SEND to without erroring (destination classification §1).
+   * Receiving uses identity.localDomains. Anything outside both → error.
+   */
+  routableDomains?: string[];
+  smtp?: {
+    listenPort?: number;
+    relay?: {
+      host: string;
+      port: number;
+      auth?: { user: string; pass: string };
+    };
+    dkim?: { domain: string; selector: string; privateKeyRef: string };
+  };
+  provider?: {
+    name: "ses" | "postmark" | "mailgun";
+    apiKeyRef: string;
+    webhookPath?: string;
+  };
+  /** Delivery queue overrides; defaults to sqlite persistence when mail enabled. */
+  queue?: Partial<DeliveryQueueConfig>;
+  /**
+   * Attachment byte storage. Defaults to "sqlite" (content-addressed BLOBs in
+   * the DB). Use "fs" to keep bytes on disk for large/high-volume deployments.
+   */
+  attachments?: {
+    backend?: "sqlite" | "fs";
+    /** Directory for the "fs" backend. Defaults to <home>/.claude/agent-inbox/attachments. */
+    dir?: string;
+  };
+  /** Inbound sender allow-list (domains). Empty/undefined = allow all. */
+  allowedSenderDomains?: string[];
+  /** Drop inbound whose DMARC verdict is "fail". */
+  rejectDmarcFail?: boolean;
+  /** Max attachments on an inbound message before rejection. */
+  maxAttachments?: number;
+  /** Inbound rate limiting (abuse control). Disabled if unset. */
+  rateLimit?: {
+    windowMs?: number;
+    perSenderDomain?: number;
+    global?: number;
+  };
+  /** Bounce handling (both default on). See §8. */
+  bounce?: {
+    /** Emit the mail.bounced event. */
+    emitEvent?: boolean;
+    /** Inject a synthetic bounce Message into the original sender's inbox. */
+    synthesizeInboxMessage?: boolean;
+  };
+}
+
 // --- Config ---
 
 export interface InboxConfig {
@@ -326,4 +399,5 @@ export interface InboxConfig {
     };
   };
   federation?: FederationConfig;
+  mail?: MailConfig;
 }

package/test/federation/delivery-queue-sqlite.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { EventEmitter } from "node:events";
+import Database from "better-sqlite3";
+import { DeliveryQueue } from "../../src/federation/delivery-queue.js";
+import { SqliteQueueStore } from "../../src/federation/queue-store.js";
+import type { DeliveryQueueConfig, Message } from "../../src/types.js";
+
+function makeMessage(id: string): Message {
+  return {
+    id,
+    scope: "default",
+    sender_id: "sender",
+    recipients: [{ agent_id: "remote@peer", kind: "to" }],
+    content: { type: "text", text: `msg-${id}` },
+    importance: "normal",
+    metadata: {},
+    created_at: new Date().toISOString(),
+  };
+}
+
+const baseConfig: DeliveryQueueConfig = {
+  persistence: "sqlite",
+  maxTTL: 10_000,
+  maxQueueSize: 3,
+  retryStrategy: "exponential",
+  retryBaseInterval: 100,
+  retryMaxAttempts: 0,
+  flushOnReconnect: true,
+  overflow: "drop-oldest",
+};
+
+describe("DeliveryQueue (sqlite persistence)", () => {
+  let db: Database.Database;
+  let events: EventEmitter;
+
+  beforeEach(() => {
+    db = new Database(":memory:");
+    events = new EventEmitter();
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  function makeQueue(config: Partial<DeliveryQueueConfig> = {}) {
+    return new DeliveryQueue(
+      events,
+      { ...baseConfig, ...config },
+      { store: new SqliteQueueStore(db) }
+    );
+  }
+
+  it("persists enqueued messages to the store", () => {
+    const q = makeQueue();
+    q.enqueue("peer-1", makeMessage("m1"));
+    q.enqueue("peer-1", makeMessage("m2"));
+
+    const rows = db.prepare("SELECT * FROM delivery_queue").all();
+    expect(rows).toHaveLength(2);
+  });
+
+  it("survives a restart by hydrating from the store", () => {
+    const q1 = makeQueue();
+    q1.enqueue("peer-1", makeMessage("m1"));
+    q1.enqueue("peer-2", makeMessage("m2"));
+    expect(q1.totalSize()).toBe(2);
+
+    // Simulate restart: new queue + new store over the same db handle.
+    const q2 = new DeliveryQueue(events, baseConfig, {
+      store: new SqliteQueueStore(db),
+    });
+    expect(q2.totalSize()).toBe(2);
+    expect(q2.size("peer-1")).toBe(1);
+    expect(q2.size("peer-2")).toBe(1);
+    expect(q2.peers().sort()).toEqual(["peer-1", "peer-2"]);
+  });
+
+  it("removes entries from the store on removeEntry", () => {
+    const q = makeQueue();
+    const id = q.enqueue("peer-1", makeMessage("m1"))!;
+    q.removeEntry("peer-1", id);
+
+    expect(db.prepare("SELECT * FROM delivery_queue").all()).toHaveLength(0);
+  });
+
+  it("clears the store for a peer on flush", () => {
+    const q = makeQueue();
+    q.enqueue("peer-1", makeMessage("m1"));
+    q.enqueue("peer-1", makeMessage("m2"));
+    q.flush("peer-1");
+
+    expect(
+      db.prepare("SELECT * FROM delivery_queue WHERE peer_id = ?").all("peer-1")
+    ).toHaveLength(0);
+  });
+
+  it("drops the oldest entry from the store on overflow", () => {
+    const q = makeQueue({ maxQueueSize: 2, overflow: "drop-oldest" });
+    q.enqueue("peer-1", makeMessage("m1"));
+    q.enqueue("peer-1", makeMessage("m2"));
+    q.enqueue("peer-1", makeMessage("m3")); // evicts m1
+
+    const messages = (
+      db.prepare("SELECT message FROM delivery_queue").all() as Array<{
+        message: string;
+      }>
+    ).map((r) => JSON.parse(r.message).id);
+    expect(messages.sort()).toEqual(["m2", "m3"]);
+  });
+
+  it("updates attempt/next-retry state in the store on recordAttempt", () => {
+    const q = makeQueue({ retryMaxAttempts: 5 });
+    const id = q.enqueue("peer-1", makeMessage("m1"))!;
+    q.recordAttempt("peer-1", id);
+
+    const row = db
+      .prepare("SELECT attempts, next_retry FROM delivery_queue WHERE id = ?")
+      .get(id) as { attempts: number; next_retry: string | null };
+    expect(row.attempts).toBe(1);
+    expect(row.next_retry).toBeTruthy();
+  });
+
+  it("removes the entry from the store when max attempts are exceeded", () => {
+    const q = makeQueue({ retryMaxAttempts: 1 });
+    const id = q.enqueue("peer-1", makeMessage("m1"))!;
+    const kept = q.recordAttempt("peer-1", id);
+    expect(kept).toBe(false);
+    expect(db.prepare("SELECT * FROM delivery_queue").all()).toHaveLength(0);
+  });
+
+  it("removes expired entries from the store on tick", () => {
+    const q = makeQueue({ maxTTL: -1 }); // everything is immediately expired
+    q.enqueue("peer-1", makeMessage("m1"));
+    const expired = q.tick();
+    expect(expired).toBe(1);
+    expect(db.prepare("SELECT * FROM delivery_queue").all()).toHaveLength(0);
+  });
+
+  it("round-trips the full message payload through the store", () => {
+    const q1 = makeQueue();
+    const msg = makeMessage("m1");
+    msg.subject = "hello";
+    msg.thread_tag = "thread-xyz";
+    q1.enqueue("peer-1", msg);
+
+    const q2 = new DeliveryQueue(events, baseConfig, {
+      store: new SqliteQueueStore(db),
+    });
+    const flushed = q2.flush("peer-1");
+    expect(flushed).toHaveLength(1);
+    expect(flushed[0].message.subject).toBe("hello");
+    expect(flushed[0].message.thread_tag).toBe("thread-xyz");
+    expect(flushed[0].message.content).toEqual({
+      type: "text",
+      text: "msg-m1",
+    });
+  });
+});