agent-inbox 0.2.3 → 0.2.4

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",
+    });
+  });
+});

package/test/load.test.ts

@@ -252,7 +252,7 @@ describe("load: SQLite stays bounded", () => {
     // 5000 messages × 11 recipients ≈ 55k recipient rows + 5k turns + FTS.
     // 4 KiB per logical message is a generous ceiling.
     expect(size).toBeLessThan(N * 4096);
-  });
+  }, 30_000); // generous timeout: this asserts bounded size, not speed
 
   it("pruneMessagesOlderThan should remove old data and reduce row counts", async () => {
     const storage = new SqliteStorage({ path: ":memory:" });

package/test/mail/address-book.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from "vitest";
+import { AddressBook } from "../../src/mail/address-book.js";
+
+function book(): AddressBook {
+  return new AddressBook({
+    localDomains: ["example.com", "agents.example.com"],
+    mappings: [
+      { agentId: "alice", address: "alice@example.com" },
+      { agentId: "bob", address: "bob@example.com" },
+    ],
+    catchAllAgentId: undefined,
+  });
+}
+
+describe("AddressBook", () => {
+  it("reports the primary domain", () => {
+    expect(book().primaryDomain()).toBe("example.com");
+  });
+
+  it("recognizes owned domains and subdomains", () => {
+    const b = book();
+    expect(b.ownsDomain("example.com")).toBe(true);
+    expect(b.ownsDomain("mail.example.com")).toBe(true);
+    expect(b.ownsDomain("agents.example.com")).toBe(true);
+    expect(b.ownsDomain("notexample.com")).toBe(false);
+    expect(b.ownsDomain("other.org")).toBe(false);
+  });
+
+  it("resolves a known inbound mailbox to its agent", () => {
+    expect(book().resolveInbound("bob@example.com")).toEqual({
+      agentId: "bob",
+      scope: undefined,
+    });
+  });
+
+  it("is case-insensitive on the mailbox", () => {
+    expect(book().resolveInbound("ALICE@Example.com")?.agentId).toBe("alice");
+  });
+
+  it("extracts scope from plus-addressing", () => {
+    expect(book().resolveInbound("alice+urgent@example.com")).toEqual({
+      agentId: "alice",
+      scope: "urgent",
+    });
+  });
+
+  it("returns undefined for a foreign domain", () => {
+    expect(book().resolveInbound("alice@other.org")).toBeUndefined();
+  });
+
+  it("returns undefined for an unknown mailbox without catch-all", () => {
+    expect(book().resolveInbound("ghost@example.com")).toBeUndefined();
+  });
+
+  it("routes unknown mailboxes to catch-all when configured", () => {
+    const b = new AddressBook({
+      localDomains: ["example.com"],
+      mappings: [],
+      catchAllAgentId: "triage",
+    });
+    expect(b.resolveInbound("anyone@example.com")).toEqual({
+      agentId: "triage",
+      scope: undefined,
+    });
+  });
+
+  it("resolves a mapped agent's from-address", () => {
+    expect(book().resolveFrom("alice")).toEqual({ address: "alice@example.com" });
+  });
+
+  it("falls back to agentId@primaryDomain for an unmapped agent", () => {
+    expect(book().resolveFrom("ghost")).toEqual({
+      address: "ghost@example.com",
+    });
+  });
+
+  it("ignores malformed addresses", () => {
+    expect(book().resolveInbound("not-an-email")).toBeUndefined();
+    expect(book().resolveInbound("@example.com")).toBeUndefined();
+    expect(book().resolveInbound("foo@")).toBeUndefined();
+  });
+
+  it("rejects addresses with multiple @ (consistent with parseAddress)", () => {
+    expect(book().resolveInbound("a@b@example.com")).toBeUndefined();
+    expect(book().resolveInbound("alice@example.com@evil.com")).toBeUndefined();
+  });
+
+  it("records duplicate-address mapping conflicts and keeps the first", () => {
+    const b = new AddressBook({
+      localDomains: ["example.com"],
+      mappings: [
+        { agentId: "alice", address: "shared@example.com" },
+        { agentId: "bob", address: "shared@example.com" },
+      ],
+    });
+    expect(b.resolveInbound("shared@example.com")?.agentId).toBe("alice");
+    expect(b.conflicts).toHaveLength(1);
+    expect(b.conflicts[0]).toContain("shared@example.com");
+  });
+
+  it("does not flag a repeated identical (agent,address) pair as a conflict", () => {
+    const b = new AddressBook({
+      localDomains: ["example.com"],
+      mappings: [
+        { agentId: "alice", address: "alice@example.com" },
+        { agentId: "alice", address: "alice@example.com" },
+      ],
+    });
+    expect(b.conflicts).toHaveLength(0);
+  });
+});

package/test/mail/attachment-store-contract.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared AttachmentStore contract — both backends (SQLite BLOB + filesystem)
+ * must satisfy the same behavior, so they are interchangeable behind the
+ * opaque `contentRef`. Mirrors the mail-transport contract pattern.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import Database from "better-sqlite3";
+import type { AttachmentStore } from "../../src/mail/types.js";
+import { SqliteAttachmentStore } from "../../src/mail/attachment-store.js";
+import { FsAttachmentStore } from "../../src/mail/fs-attachment-store.js";
+
+interface Harness {
+  store: AttachmentStore;
+  cleanup: () => Promise<void> | void;
+}
+
+function runAttachmentStoreContract(
+  name: string,
+  makeHarness: () => Promise<Harness>
+): void {
+  describe(`AttachmentStore contract: ${name}`, () => {
+    let h: Harness;
+    beforeEach(async () => {
+      h = await makeHarness();
+    });
+    afterEach(async () => {
+      await h.cleanup();
+    });
+
+    it("round-trips stored bytes by ref", async () => {
+      const bytes = Buffer.from("contract bytes");
+      const ref = await h.store.put(bytes, { contentType: "text/plain" });
+      expect((await h.store.get(ref)).equals(bytes)).toBe(true);
+    });
+
+    it("produces sha256-based content-addressed refs", async () => {
+      const ref = await h.store.put(Buffer.from("x"), { contentType: "text/plain" });
+      expect(ref).toMatch(/^sha256:[0-9a-f]{64}$/);
+    });
+
+    it("dedups identical bytes to the same ref", async () => {
+      const a = await h.store.put(Buffer.from("same"), { contentType: "text/plain" });
+      const b = await h.store.put(Buffer.from("same"), { contentType: "text/plain" });
+      expect(a).toBe(b);
+    });
+
+    it("gives different refs for different bytes", async () => {
+      const a = await h.store.put(Buffer.from("one"), { contentType: "text/plain" });
+      const b = await h.store.put(Buffer.from("two"), { contentType: "text/plain" });
+      expect(a).not.toBe(b);
+    });
+
+    it("throws on a missing ref", async () => {
+      await expect(h.store.get("sha256:" + "a".repeat(64))).rejects.toThrow(/not found/);
+    });
+
+    it("rejects a malformed ref on get and delete (both backends)", async () => {
+      await expect(h.store.get("garbage")).rejects.toThrow(/Invalid attachment ref/);
+      await expect(h.store.get("sha256:../../etc/passwd")).rejects.toThrow(/Invalid attachment ref/);
+      await expect(h.store.delete("sha256:short")).rejects.toThrow(/Invalid attachment ref/);
+    });
+
+    it("deletes by ref", async () => {
+      const ref = await h.store.put(Buffer.from("gone"), { contentType: "text/plain" });
+      await h.store.delete(ref);
+      await expect(h.store.get(ref)).rejects.toThrow(/not found/);
+    });
+
+    it("round-trips arbitrary binary content exactly", async () => {
+      const bytes = Buffer.from([0x00, 0xff, 0x7f, 0x80, 0x01, 0x00]);
+      const ref = await h.store.put(bytes, { contentType: "application/octet-stream" });
+      expect((await h.store.get(ref)).equals(bytes)).toBe(true);
+    });
+  });
+}
+
+runAttachmentStoreContract("SqliteAttachmentStore", async () => {
+  const db = new Database(":memory:");
+  return { store: new SqliteAttachmentStore(db), cleanup: () => db.close() };
+});
+
+runAttachmentStoreContract("FsAttachmentStore", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "att-contract-"));
+  return {
+    store: new FsAttachmentStore(dir),
+    cleanup: () => fs.rm(dir, { recursive: true, force: true }),
+  };
+});

package/test/mail/attachment-store.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { SqliteAttachmentStore } from "../../src/mail/attachment-store.js";
+
+describe("SqliteAttachmentStore", () => {
+  let db: Database.Database;
+  let store: SqliteAttachmentStore;
+
+  beforeEach(() => {
+    db = new Database(":memory:");
+    store = new SqliteAttachmentStore(db);
+  });
+
+  afterEach(() => db.close());
+
+  it("stores and retrieves bytes by ref", async () => {
+    const bytes = Buffer.from("hello attachment");
+    const ref = await store.put(bytes, { contentType: "text/plain" });
+    const got = await store.get(ref);
+    expect(got.equals(bytes)).toBe(true);
+  });
+
+  it("produces content-addressed (sha256:) refs", async () => {
+    const ref = await store.put(Buffer.from("x"), { contentType: "text/plain" });
+    expect(ref).toMatch(/^sha256:[0-9a-f]{64}$/);
+  });
+
+  it("dedups identical bytes to the same ref and single row", async () => {
+    const a = await store.put(Buffer.from("same"), { contentType: "text/plain" });
+    const b = await store.put(Buffer.from("same"), { contentType: "text/plain" });
+    expect(a).toBe(b);
+    const count = db
+      .prepare("SELECT COUNT(*) AS n FROM mail_attachments")
+      .get() as { n: number };
+    expect(count.n).toBe(1);
+  });
+
+  it("gives different refs for different bytes", async () => {
+    const a = await store.put(Buffer.from("one"), { contentType: "text/plain" });
+    const b = await store.put(Buffer.from("two"), { contentType: "text/plain" });
+    expect(a).not.toBe(b);
+  });
+
+  it("deletes by ref", async () => {
+    const ref = await store.put(Buffer.from("gone"), { contentType: "text/plain" });
+    await store.delete(ref);
+    await expect(store.get(ref)).rejects.toThrow(/not found/);
+  });
+
+  it("throws on missing ref", async () => {
+    await expect(store.get("sha256:" + "0".repeat(64))).rejects.toThrow(/not found/);
+  });
+
+  it("persists filename and size metadata", async () => {
+    const bytes = Buffer.from("with-meta");
+    const ref = await store.put(bytes, {
+      contentType: "application/pdf",
+      filename: "doc.pdf",
+    });
+    const row = db
+      .prepare(
+        "SELECT content_type, filename, size_bytes FROM mail_attachments WHERE ref = ?"
+      )
+      .get(ref) as { content_type: string; filename: string; size_bytes: number };
+    expect(row.content_type).toBe("application/pdf");
+    expect(row.filename).toBe("doc.pdf");
+    expect(row.size_bytes).toBe(bytes.length);
+  });
+});

package/test/mail/destination.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from "vitest";
+import {
+  classifyDestination,
+  findDomainConflicts,
+  UnknownDestinationError,
+  type DestinationContext,
+} from "../../src/router/destination.js";
+
+function ctx(overrides: Partial<DestinationContext> = {}): DestinationContext {
+  return {
+    isLocalAgent: (id) => ["alice", "bob"].includes(id),
+    federationPeers: [{ systemId: "system-2" }],
+    mailDomains: ["example.com"],
+    ...overrides,
+  };
+}
+
+describe("classifyDestination", () => {
+  it("classifies a bare id as local", () => {
+    expect(classifyDestination("alice", ctx())).toEqual({
+      class: "local",
+      agentId: "alice",
+    });
+  });
+
+  it("classifies an unknown bare id as local (no domain to disambiguate)", () => {
+    // No @ means there is no domain to route on — it is a local-namespace id.
+    expect(classifyDestination("charlie", ctx())).toEqual({
+      class: "local",
+      agentId: "charlie",
+    });
+  });
+
+  it("classifies a configured federation peer system as federation", () => {
+    const d = classifyDestination("bob@system-2", ctx());
+    expect(d.class).toBe("federation");
+    if (d.class === "federation") {
+      expect(d.address).toEqual({ agent: "bob", system: "system-2" });
+    }
+  });
+
+  it("classifies a configured mail domain as mail", () => {
+    expect(classifyDestination("bob@example.com", ctx())).toEqual({
+      class: "mail",
+      email: "bob@example.com",
+    });
+  });
+
+  it("matches subdomains of a configured mail domain", () => {
+    expect(classifyDestination("bob@mail.example.com", ctx())).toEqual({
+      class: "mail",
+      email: "bob@mail.example.com",
+    });
+  });
+
+  it("does not match a domain that merely shares a suffix string", () => {
+    // notexample.com must NOT match example.com
+    expect(() => classifyDestination("bob@notexample.com", ctx())).toThrow(
+      UnknownDestinationError
+    );
+  });
+
+  it("throws UnknownDestinationError for an unlisted domain", () => {
+    expect(() => classifyDestination("bob@gmail.com", ctx())).toThrow(
+      UnknownDestinationError
+    );
+  });
+
+  it("lets a federation peer's declared domain win over mail config", () => {
+    // corp.internal is claimed by BOTH a peer and mail config — federation wins.
+    const c = ctx({
+      federationPeers: [{ systemId: "system-2", domains: ["corp.internal"] }],
+      mailDomains: ["example.com", "corp.internal"],
+    });
+    const d = classifyDestination("team@corp.internal", c);
+    expect(d.class).toBe("federation");
+  });
+
+  it("routes a dotted federation domain that is not in mail config", () => {
+    const c = ctx({
+      federationPeers: [{ systemId: "hub", domains: ["team.corp.internal"] }],
+      mailDomains: ["example.com"],
+    });
+    expect(classifyDestination("svc@team.corp.internal", c).class).toBe(
+      "federation"
+    );
+  });
+
+  it("strips a trailing /scope from a mail address", () => {
+    expect(classifyDestination("bob@example.com/work", ctx())).toEqual({
+      class: "mail",
+      email: "bob@example.com",
+    });
+  });
+
+  it("is case-insensitive on domain matching", () => {
+    expect(classifyDestination("bob@Example.COM", ctx()).class).toBe("mail");
+  });
+});
+
+describe("findDomainConflicts", () => {
+  it("reports domains claimed by both a peer and mail config", () => {
+    const conflicts = findDomainConflicts(
+      ctx({
+        federationPeers: [{ systemId: "s", domains: ["corp.internal", "ok.net"] }],
+        mailDomains: ["example.com", "corp.internal"],
+      })
+    );
+    expect(conflicts).toEqual(["corp.internal"]);
+  });
+
+  it("returns empty when there is no overlap", () => {
+    expect(findDomainConflicts(ctx())).toEqual([]);
+  });
+});