agent-inbox 0.2.2 → 0.2.4

package/test/mail/router-mail-integration.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { EventEmitter } from "node:events";
+import { InMemoryStorage } from "../../src/storage/memory.js";
+import {
+  MessageRouter,
+  type MailEgress,
+} from "../../src/router/message-router.js";
+import { MailGateway } from "../../src/mail/mail-gateway.js";
+import { MockMailTransport } from "./mock-mail.js";
+import type { Agent, Message } from "../../src/types.js";
+
+function agent(id: string): Agent {
+  return {
+    agent_id: id,
+    scope: "default",
+    status: "active",
+    metadata: {},
+    registered_at: new Date().toISOString(),
+    last_active_at: new Date().toISOString(),
+  };
+}
+
+const tick = () => new Promise((r) => setImmediate(r));
+
+describe("router ↔ mail integration", () => {
+  let storage: InMemoryStorage;
+  let events: EventEmitter;
+  let router: MessageRouter;
+  let transport: MockMailTransport;
+  let gateway: MailGateway;
+
+  beforeEach(async () => {
+    storage = new InMemoryStorage();
+    events = new EventEmitter();
+    router = new MessageRouter(storage, events);
+    storage.putAgent(agent("alice"));
+    storage.putAgent(agent("bob"));
+    transport = new MockMailTransport();
+    await transport.start();
+    gateway = new MailGateway({
+      transport,
+      storage,
+      router,
+      events,
+      config: {
+        identity: {
+          localDomains: ["example.com"],
+          mappings: [{ agentId: "alice", address: "alice@example.com" }],
+        },
+        routableDomains: ["external.org"],
+      },
+    });
+    router.setMail(gateway);
+  });
+
+  it("routes external mail recipients to the gateway, not local delivery", async () => {
+    const msg = await router.routeMessage({
+      from: "alice",
+      to: [{ agent_id: "user@external.org", kind: "to" }],
+      payload: "hello world",
+    });
+    await tick();
+
+    expect(transport.sent).toHaveLength(1);
+    expect(transport.sent[0].to).toEqual([{ address: "user@external.org" }]);
+    // The mail recipient is not treated as a delivered local agent.
+    const stored = storage.getMessage(msg.id)!;
+    expect(stored.recipients[0].delivered_at).toBeTruthy(); // set by gateway on send
+  });
+
+  it("delivers local recipients locally and mail recipients via the gateway", async () => {
+    await router.routeMessage({
+      from: "alice",
+      to: [
+        { agent_id: "bob", kind: "to" },
+        { agent_id: "user@external.org", kind: "to" },
+      ],
+      payload: "mixed",
+    });
+    await tick();
+
+    expect(storage.getInbox("bob")).toHaveLength(1);
+    expect(transport.sent).toHaveLength(1);
+  });
+
+  it("does not send local-only messages through mail", async () => {
+    await router.routeMessage({
+      from: "alice",
+      to: [{ agent_id: "bob", kind: "to" }],
+      payload: "local only",
+    });
+    await tick();
+    expect(transport.sent).toHaveLength(0);
+  });
+
+  it("sends non-mail remote recipients to federation, not mail", async () => {
+    const routed: Message[] = [];
+    const fakeFederation = {
+      route: async (m: Message) => {
+        routed.push(m);
+        return { delivered: false };
+      },
+    };
+    // Cast: the router only calls .route() on the federation handle.
+    router.setFederation(fakeFederation as never);
+
+    await router.routeMessage({
+      from: "alice",
+      to: [{ agent_id: "carol@system-2", kind: "to" }],
+      payload: "federated",
+    });
+    await tick();
+
+    expect(routed).toHaveLength(1);
+    expect(transport.sent).toHaveLength(0);
+  });
+
+  it("ownsRecipient distinguishes mail domains from federation systems", () => {
+    expect(gateway.ownsRecipient("user@external.org")).toBe(true);
+    expect(gateway.ownsRecipient("user@example.com")).toBe(true);
+    expect(gateway.ownsRecipient("carol@system-2")).toBe(false);
+    expect(gateway.ownsRecipient("bob")).toBe(false);
+  });
+});
+
+describe("MailEgress contract shape", () => {
+  it("MailGateway satisfies MailEgress", () => {
+    const eg: MailEgress = new MailGateway({
+      transport: new MockMailTransport(),
+      storage: new InMemoryStorage(),
+      router: new MessageRouter(new InMemoryStorage(), new EventEmitter()),
+      events: new EventEmitter(),
+      config: { identity: { localDomains: ["x.com"], mappings: [] } },
+    });
+    expect(typeof eg.ownsRecipient).toBe("function");
+    expect(typeof eg.send).toBe("function");
+  });
+});

package/test/mail/smtp-e2e.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { SmtpTransport } from "../../src/mail/smtp-transport.js";
+import { makeOutboundMail } from "./mock-mail.js";
+import type { InboundMail } from "../../src/mail/types.js";
+
+// These libs are optional peer deps; skip the real-socket e2e if absent.
+const haveLibs = await Promise.all([
+  import("smtp-server").then(() => true).catch(() => false),
+  import("nodemailer").then(() => true).catch(() => false),
+  import("mailparser").then(() => true).catch(() => false),
+]).then((r) => r.every(Boolean));
+
+const randomPort = () => 30000 + Math.floor(Math.random() * 5000);
+
+describe.skipIf(!haveLibs)("SmtpTransport e2e (loopback)", () => {
+  const transports: SmtpTransport[] = [];
+  afterEach(async () => {
+    for (const t of transports) await t.stop().catch(() => {});
+    transports.length = 0;
+  });
+
+  it("delivers a message from one transport to another and ACKs after commit", async () => {
+    const recvPort = randomPort();
+
+    // Receiver: captures inbound and resolves only after a simulated commit.
+    const received: InboundMail[] = [];
+    const committed: string[] = [];
+    const receiver = new SmtpTransport({ listenPort: recvPort });
+    receiver.onReceive(async (mail) => {
+      received.push(mail);
+      await new Promise((r) => setTimeout(r, 5)); // simulate async storage commit
+      committed.push("done");
+    });
+    transports.push(receiver);
+    await receiver.start();
+
+    // Sender: listens on a different port, relays to the receiver.
+    const sender = new SmtpTransport({
+      listenPort: randomPort(),
+      relay: { host: "127.0.0.1", port: recvPort, secure: false },
+    });
+    transports.push(sender);
+    await sender.start();
+
+    const result = await sender.send(
+      makeOutboundMail({
+        idempotencyKey: "e2e-1",
+        from: { address: "alice@example.com" },
+        to: [{ address: "bob@receiver.test" }],
+        subject: "e2e subject",
+        text: "e2e body",
+        headers: { messageId: "<e2e-1@example.com>" },
+      })
+    );
+
+    expect(result.disposition).toBe("delivered");
+
+    // Allow the receiver's onData/handler to run.
+    await new Promise((r) => setTimeout(r, 100));
+
+    expect(received).toHaveLength(1);
+    expect(received[0].subject).toBe("e2e subject");
+    expect(received[0].text?.trim()).toBe("e2e body");
+    expect(received[0].headers.messageId).toBe("<e2e-1@example.com>");
+    // The handler's commit ran (ACK happened after it).
+    expect(committed).toEqual(["done"]);
+  });
+
+  it("is idempotent on the sender for a repeated idempotencyKey", async () => {
+    const recvPort = randomPort();
+    const received: InboundMail[] = [];
+    const receiver = new SmtpTransport({ listenPort: recvPort });
+    receiver.onReceive(async (mail) => {
+      received.push(mail);
+    });
+    transports.push(receiver);
+    await receiver.start();
+
+    const sender = new SmtpTransport({
+      listenPort: randomPort(),
+      relay: { host: "127.0.0.1", port: recvPort, secure: false },
+    });
+    transports.push(sender);
+    await sender.start();
+
+    const env = makeOutboundMail({
+      idempotencyKey: "dup-key",
+      to: [{ address: "bob@receiver.test" }],
+      headers: { messageId: "<dup-key@example.com>" },
+    });
+    await sender.send(env);
+    const second = await sender.send(env);
+
+    expect(second.detail).toMatch(/idempotent|replay/i);
+    await new Promise((r) => setTimeout(r, 100));
+    expect(received).toHaveLength(1); // not delivered twice
+  });
+});

package/test/mail/smtp-transport.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect } from "vitest";
+import {
+  smtpErrorToResult,
+  parsedToInboundMail,
+  toNodemailerMessage,
+  mailauthToResults,
+} from "../../src/mail/smtp-transport.js";
+import { makeOutboundMail } from "./mock-mail.js";
+
+describe("smtpErrorToResult", () => {
+  it("maps 5xx to permanent", () => {
+    expect(smtpErrorToResult({ responseCode: 550, response: "no user" })).toEqual({
+      disposition: "permanent",
+      code: 550,
+      detail: "no user",
+    });
+  });
+
+  it("maps 4xx to transient", () => {
+    expect(smtpErrorToResult({ responseCode: 451 }).disposition).toBe("transient");
+  });
+
+  it("maps connection/DNS errors (no code) to transient", () => {
+    expect(smtpErrorToResult({ message: "ECONNREFUSED" })).toEqual({
+      disposition: "transient",
+      detail: "ECONNREFUSED",
+    });
+  });
+});
+
+describe("parsedToInboundMail", () => {
+  it("builds an InboundMail from parsed fields", () => {
+    const mail = parsedToInboundMail(
+      {
+        from: { value: [{ address: "ext@other.org", name: "Ext" }] },
+        to: { value: [{ address: "alice@example.com" }] },
+        cc: { value: [{ address: "bob@example.com" }] },
+        subject: "hi",
+        text: "body",
+        messageId: "<m1@other.org>",
+        inReplyTo: "<p0@other.org>",
+        references: "<root@other.org> <p0@other.org>",
+        date: new Date("2026-01-01T00:00:00Z"),
+        headers: new Map([["x-priority", "1"]]),
+      },
+      {
+        envelopeFrom: "ext@other.org",
+        envelopeTo: ["alice@example.com"],
+        remote: { ip: "203.0.113.5" },
+        sizeBytes: 200,
+      }
+    );
+
+    expect(mail.from).toEqual({ address: "ext@other.org", name: "Ext" });
+    expect(mail.to).toEqual([{ address: "alice@example.com", name: undefined }]);
+    expect(mail.cc).toEqual([{ address: "bob@example.com", name: undefined }]);
+    expect(mail.headers.messageId).toBe("<m1@other.org>");
+    expect(mail.headers.references).toEqual([
+      "<root@other.org>",
+      "<p0@other.org>",
+    ]);
+    expect(mail.headers.raw["x-priority"]).toBe("1");
+    expect(mail.remote).toEqual({ ip: "203.0.113.5" });
+    expect(mail.receivedAt).toBe("2026-01-01T00:00:00.000Z");
+  });
+
+  it("falls back to the envelope sender when From is missing", () => {
+    const mail = parsedToInboundMail(
+      { to: { value: [{ address: "alice@example.com" }] } },
+      { envelopeFrom: "bounce@mta.net", envelopeTo: [], sizeBytes: 1 }
+    );
+    expect(mail.from).toEqual({ address: "bounce@mta.net" });
+  });
+});
+
+describe("toNodemailerMessage", () => {
+  it("maps an OutboundMail to nodemailer fields", () => {
+    const msg = toNodemailerMessage(
+      makeOutboundMail({
+        from: { address: "alice@example.com", name: "Alice" },
+        to: [{ address: "ext@other.org" }],
+        cc: [{ address: "c@other.org" }],
+        subject: "subject",
+        text: "text body",
+        headers: {
+          messageId: "<m@example.com>",
+          inReplyTo: "<p@other.org>",
+          references: ["<r@other.org>"],
+        },
+      })
+    );
+    expect(msg.from).toEqual({ name: "Alice", address: "alice@example.com" });
+    expect(msg.to).toEqual(["ext@other.org"]);
+    expect(msg.cc).toEqual(["c@other.org"]);
+    expect(msg.messageId).toBe("<m@example.com>");
+    expect(msg.inReplyTo).toBe("<p@other.org>");
+    expect(msg.references).toEqual(["<r@other.org>"]);
+  });
+
+  it("includes dkim options when provided", () => {
+    const msg = toNodemailerMessage(makeOutboundMail(), {
+      domainName: "example.com",
+      keySelector: "s1",
+      privateKey: "KEY",
+    });
+    expect(msg.dkim).toEqual({
+      domainName: "example.com",
+      keySelector: "s1",
+      privateKey: "KEY",
+    });
+  });
+});
+
+describe("mailauthToResults", () => {
+  it("normalizes a full pass verdict", () => {
+    expect(
+      mailauthToResults({
+        spf: { status: { result: "pass" } },
+        dkim: { results: [{ status: { result: "pass" } }] },
+        dmarc: { status: { result: "pass" } },
+      })
+    ).toEqual({ spf: "pass", dkim: "pass", dmarc: "pass" });
+  });
+
+  it("defaults missing verdicts to none", () => {
+    expect(mailauthToResults({})).toEqual({
+      spf: "none",
+      dkim: "none",
+      dmarc: "none",
+    });
+  });
+
+  it("maps dmarc fail through", () => {
+    expect(
+      mailauthToResults({ dmarc: { status: { result: "fail" } } }).dmarc
+    ).toBe("fail");
+  });
+});

package/test/mail-presence.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Tests for the mail/presence JSON-RPC method.
+ *
+ * Verifies participant presence resolution from an optional registry,
+ * error handling for missing conversations, and fallback to 'unknown'
+ * when no registry is provided.
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { EventEmitter } from "node:events";
+import { InMemoryStorage } from "../src/storage/memory.js";
+import { MessageRouter } from "../src/router/message-router.js";
+import { MailJsonRpcServer } from "../src/jsonrpc/mail-server.js";
+
+describe("mail/presence", () => {
+  let storage: InMemoryStorage;
+  let events: EventEmitter;
+  let router: MessageRouter;
+
+  beforeEach(() => {
+    storage = new InMemoryStorage();
+    events = new EventEmitter();
+    router = new MessageRouter(storage, events, "default");
+  });
+
+  function rpc(server: MailJsonRpcServer, method: string, params: Record<string, unknown> = {}) {
+    return server.handleRequest({
+      jsonrpc: "2.0",
+      id: 1,
+      method,
+      params,
+    });
+  }
+
+  async function seedConversationWithParticipants(server: MailJsonRpcServer) {
+    const createResp = await rpc(server, "mail/create", {
+      subject: "Dispatch thread",
+      scope: "dispatch-thread",
+    });
+    const convId = (createResp.result as { id: string }).id;
+
+    await rpc(server, "mail/invite", {
+      conversationId: convId,
+      agentId: "user_abc",
+      role: "initiator",
+    });
+    await rpc(server, "mail/invite", {
+      conversationId: convId,
+      agentId: "executor-1",
+      role: "executor",
+    });
+
+    return convId;
+  }
+
+  it("returns participants with presence from registry", async () => {
+    const registry = {
+      getStatus(agentId: string): string {
+        if (agentId === "user_abc") return "active";
+        if (agentId === "executor-1") return "away";
+        return "unknown";
+      },
+    };
+    const server = new MailJsonRpcServer(storage, router, events, registry);
+    const convId = await seedConversationWithParticipants(server);
+
+    const resp = await rpc(server, "mail/presence", { conversationId: convId });
+
+    expect(resp.error).toBeUndefined();
+    const result = resp.result as {
+      conversationId: string;
+      participants: Array<{ agent_id: string; role: string; presence: string }>;
+    };
+    expect(result.conversationId).toBe(convId);
+    expect(result.participants).toHaveLength(2);
+
+    const user = result.participants.find((p) => p.agent_id === "user_abc")!;
+    expect(user.role).toBe("initiator");
+    expect(user.presence).toBe("active");
+
+    const executor = result.participants.find((p) => p.agent_id === "executor-1")!;
+    expect(executor.role).toBe("executor");
+    expect(executor.presence).toBe("away");
+  });
+
+  it("returns 'unknown' presence when no registry is provided", async () => {
+    const server = new MailJsonRpcServer(storage, router, events);
+    const convId = await seedConversationWithParticipants(server);
+
+    const resp = await rpc(server, "mail/presence", { conversationId: convId });
+
+    const result = resp.result as {
+      participants: Array<{ agent_id: string; presence: string }>;
+    };
+    expect(result.participants).toHaveLength(2);
+    expect(result.participants.every((p) => p.presence === "unknown")).toBe(true);
+  });
+
+  it("returns error for non-existent conversation", async () => {
+    const server = new MailJsonRpcServer(storage, router, events);
+
+    const resp = await rpc(server, "mail/presence", {
+      conversationId: "nonexistent",
+    });
+
+    expect(resp.error).toBeDefined();
+    expect(resp.error!.code).toBe(-32001);
+    expect(resp.error!.message).toContain("not found");
+  });
+
+  it("returns error when conversationId is missing", async () => {
+    const server = new MailJsonRpcServer(storage, router, events);
+
+    const resp = await rpc(server, "mail/presence", {});
+
+    expect(resp.error).toBeDefined();
+    expect(resp.error!.code).toBe(-32602);
+  });
+
+  it("returns empty participants for conversation with no members", async () => {
+    const server = new MailJsonRpcServer(storage, router, events);
+    const createResp = await rpc(server, "mail/create", {
+      subject: "Empty thread",
+    });
+    const convId = (createResp.result as { id: string }).id;
+
+    const resp = await rpc(server, "mail/presence", { conversationId: convId });
+
+    const result = resp.result as {
+      participants: Array<{ agent_id: string }>;
+    };
+    expect(result.participants).toHaveLength(0);
+  });
+
+  it("includes joined_at timestamp for each participant", async () => {
+    const server = new MailJsonRpcServer(storage, router, events);
+    const convId = await seedConversationWithParticipants(server);
+
+    const resp = await rpc(server, "mail/presence", { conversationId: convId });
+
+    const result = resp.result as {
+      participants: Array<{ agent_id: string; joined_at: string }>;
+    };
+    for (const p of result.participants) {
+      expect(p.joined_at).toBeDefined();
+      expect(typeof p.joined_at).toBe("string");
+    }
+  });
+});

package/test/mail-push.test.ts

@@ -200,6 +200,38 @@ describe("createMailPushBridge", () => {
     expect(sendNotification).not.toHaveBeenCalled();
   });
 
+  it("includes importance in params when turn has importance set", () => {
+    const events = new EventEmitter();
+    const sendNotification = vi.fn();
+
+    createMailPushBridge({
+      mailEvents: events,
+      getSubscribers: () => [{ id: "swarm-1" }],
+      sendNotification,
+    });
+
+    events.emit("mail.turn.added", makeTurn({ importance: "high" }));
+    expect(sendNotification).toHaveBeenCalledOnce();
+    const params = sendNotification.mock.calls[0][2];
+    expect(params.importance).toBe("high");
+  });
+
+  it("omits importance from params when turn has no importance", () => {
+    const events = new EventEmitter();
+    const sendNotification = vi.fn();
+
+    createMailPushBridge({
+      mailEvents: events,
+      getSubscribers: () => [{ id: "swarm-1" }],
+      sendNotification,
+    });
+
+    events.emit("mail.turn.added", makeTurn());
+    expect(sendNotification).toHaveBeenCalledOnce();
+    const params = sendNotification.mock.calls[0][2];
+    expect(params).not.toHaveProperty("importance");
+  });
+
   it("stop() is idempotent", () => {
     const events = new EventEmitter();
     const bridge = createMailPushBridge({
@@ -212,3 +244,15 @@ describe("createMailPushBridge", () => {
     expect(() => bridge.stop()).not.toThrow();
   });
 });
+
+describe("buildMailTurnReceivedParams", () => {
+  it("maps importance from Turn when present", () => {
+    const params = buildMailTurnReceivedParams(makeTurn({ importance: "urgent" }));
+    expect(params.importance).toBe("urgent");
+  });
+
+  it("omits importance when Turn has no importance", () => {
+    const params = buildMailTurnReceivedParams(makeTurn());
+    expect(params).not.toHaveProperty("importance");
+  });
+});

package/test/mail-server.test.ts

@@ -94,6 +94,31 @@ describe("MailJsonRpcServer", () => {
     });
   });
 
+  describe("mail/reopen", () => {
+    it("should reopen a closed conversation", async () => {
+      const createResp = await rpc("mail/create", { subject: "Test" });
+      const convId = (createResp.result as { id: string }).id;
+
+      // Close first
+      await rpc("mail/close", { id: convId });
+      expect(storage.getConversation(convId)!.status).toBe("completed");
+
+      // Reopen
+      const reopenResp = await rpc("mail/reopen", { id: convId });
+      const result = reopenResp.result as { conversationId: string; status: string };
+      expect(result.conversationId).toBe(convId);
+      expect(result.status).toBe("active");
+
+      const conv = storage.getConversation(convId)!;
+      expect(conv.status).toBe("active");
+    });
+
+    it("should error on non-existent conversation", async () => {
+      const resp = await rpc("mail/reopen", { id: "nonexistent" });
+      expect(resp.error).toBeDefined();
+    });
+  });
+
   describe("mail/join & mail/leave", () => {
     it("should add and remove participants", async () => {
       const createResp = await rpc("mail/create", { subject: "Test" });

package/test/push-notifier.test.ts

@@ -84,6 +84,87 @@ describe("PushNotifier", () => {
   });
 });
 
+describe("PushNotifier inbox file caps", () => {
+  let capDir: string;
+  let capStorage: InMemoryStorage;
+  let capEvents: EventEmitter;
+  let capRouter: MessageRouter;
+
+  beforeEach(() => {
+    capDir = fs.mkdtempSync(path.join(os.tmpdir(), "inbox-cap-test-"));
+    capStorage = new InMemoryStorage();
+    capEvents = new EventEmitter();
+    capRouter = new MessageRouter(capStorage, capEvents, "default");
+  });
+
+  afterEach(() => {
+    fs.rmSync(capDir, { recursive: true, force: true });
+  });
+
+  it("should cap inbox file at maxEntries by dropping oldest entries", async () => {
+    const capped = new PushNotifier(
+      { inboxDir: capDir, maxEntriesPerInbox: 3 },
+      capStorage,
+      capEvents
+    );
+
+    for (let i = 0; i < 6; i++) {
+      await capRouter.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: `msg-${i}`,
+      });
+    }
+
+    const raw = fs.readFileSync(capped.agentInboxPath("bob"), "utf-8");
+    const lines = raw.split("\n").filter((l) => l.length > 0);
+    expect(lines).toHaveLength(3);
+
+    const entries = lines.map((l) => JSON.parse(l) as InboxFileEntry);
+    const texts = entries.map((e) => (e.content as { text: string }).text);
+    expect(texts).toEqual(["msg-3", "msg-4", "msg-5"]);
+  });
+
+  it("should cap inbox file at maxBytes (soft cap, ~1.1× headroom)", async () => {
+    const capped = new PushNotifier(
+      { inboxDir: capDir, maxBytesPerInbox: 400, maxEntriesPerInbox: 0 },
+      capStorage,
+      capEvents
+    );
+
+    for (let i = 0; i < 20; i++) {
+      await capRouter.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: `m${i}`,
+      });
+    }
+
+    const size = fs.statSync(capped.agentInboxPath("bob")).size;
+    expect(size).toBeLessThanOrEqual(Math.ceil(400 * 1.1));
+  });
+
+  it("should disable cap when both limits are 0", async () => {
+    const capped = new PushNotifier(
+      { inboxDir: capDir, maxEntriesPerInbox: 0, maxBytesPerInbox: 0 },
+      capStorage,
+      capEvents
+    );
+
+    for (let i = 0; i < 50; i++) {
+      await capRouter.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: `m${i}`,
+      });
+    }
+
+    const raw = fs.readFileSync(capped.agentInboxPath("bob"), "utf-8");
+    const lines = raw.split("\n").filter((l) => l.length > 0);
+    expect(lines).toHaveLength(50);
+  });
+});
+
 describe("formatInboxMarkdown", () => {
   it("should format text messages as markdown", () => {
     const entries: InboxFileEntry[] = [