agent-inbox 0.2.2 → 0.2.3

package/test/load.test.ts

@@ -0,0 +1,288 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { EventEmitter } from "node:events";
+import { InMemoryStorage } from "../src/storage/memory.js";
+import { SqliteStorage } from "../src/storage/sqlite.js";
+import { MessageRouter } from "../src/router/message-router.js";
+import { TraceabilityLayer } from "../src/traceability/traceability.js";
+import { PushNotifier } from "../src/push/notifier.js";
+import type { Storage } from "../src/storage/interface.js";
+
+/**
+ * Load tests verifying the file-growth and write-amplification fixes.
+ *
+ * These tests run larger volumes (1k-10k messages) so they're slower than
+ * the unit suite but still finish in seconds. They assert on counts of
+ * side-effects (writes, rows, file size) — not wall-clock time — so they
+ * are deterministic.
+ */
+
+interface CallCounts {
+  putMessage: number;
+  setMessageConversationId: number;
+  putConversation: number;
+  touchConversation: number;
+  addParticipant: number;
+  addTurn: number;
+}
+
+function instrumentStorage(inner: Storage): { storage: Storage; counts: CallCounts } {
+  const counts: CallCounts = {
+    putMessage: 0,
+    setMessageConversationId: 0,
+    putConversation: 0,
+    touchConversation: 0,
+    addParticipant: 0,
+    addTurn: 0,
+  };
+  const storage = new Proxy(inner, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value !== "function") return value;
+      if (prop in counts) {
+        return (...args: unknown[]) => {
+          counts[prop as keyof CallCounts]++;
+          return (value as Function).apply(target, args);
+        };
+      }
+      return (value as Function).bind(target);
+    },
+  });
+  return { storage, counts };
+}
+
+describe("load: inbox file caps stay bounded under heavy writes", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "inbox-load-"));
+  });
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("should stay near maxEntries (soft cap ~1.1×) after 10000 writes", async () => {
+    const cap = 500;
+    const storage = new InMemoryStorage();
+    const events = new EventEmitter();
+    const router = new MessageRouter(storage, events, "default");
+    const notifier = new PushNotifier(
+      { inboxDir: tmpDir, maxEntriesPerInbox: cap, maxBytesPerInbox: 0 },
+      storage,
+      events
+    );
+
+    for (let i = 0; i < 10_000; i++) {
+      await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: `msg-${i}`,
+      });
+    }
+
+    const filePath = notifier.agentInboxPath("bob");
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const lines = raw.split("\n").filter((l) => l.length > 0);
+    expect(lines.length).toBeLessThanOrEqual(Math.ceil(cap * 1.1));
+    expect(lines.length).toBeGreaterThanOrEqual(cap);
+  });
+
+  it("should stay near maxBytes (soft cap ~1.1×) after 10000 writes", async () => {
+    const cap = 64 * 1024;
+    const storage = new InMemoryStorage();
+    const events = new EventEmitter();
+    const router = new MessageRouter(storage, events, "default");
+    const notifier = new PushNotifier(
+      { inboxDir: tmpDir, maxEntriesPerInbox: 0, maxBytesPerInbox: cap },
+      storage,
+      events
+    );
+
+    for (let i = 0; i < 10_000; i++) {
+      await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: `msg-${i} ${"x".repeat(50)}`,
+      });
+    }
+
+    const size = fs.statSync(notifier.agentInboxPath("bob")).size;
+    expect(size).toBeLessThanOrEqual(Math.ceil(cap * 1.1));
+  });
+
+  it("would grow unboundedly with caps disabled (control)", async () => {
+    const storage = new InMemoryStorage();
+    const events = new EventEmitter();
+    const router = new MessageRouter(storage, events, "default");
+    const notifier = new PushNotifier(
+      { inboxDir: tmpDir, maxEntriesPerInbox: 0, maxBytesPerInbox: 0 },
+      storage,
+      events
+    );
+
+    const N = 2000;
+    for (let i = 0; i < N; i++) {
+      await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: `msg-${i}`,
+      });
+    }
+
+    const raw = fs.readFileSync(notifier.agentInboxPath("bob"), "utf-8");
+    const lines = raw.split("\n").filter((l) => l.length > 0);
+    expect(lines).toHaveLength(N);
+  });
+});
+
+describe("load: traceability does not amplify writes", () => {
+  it("should call setMessageConversationId once per message and never re-putMessage", async () => {
+    const inner = new InMemoryStorage();
+    const { storage, counts } = instrumentStorage(inner);
+    const events = new EventEmitter();
+    const router = new MessageRouter(storage, events, "default");
+    new TraceabilityLayer(storage, events);
+
+    const N = 1000;
+    for (let i = 0; i < N; i++) {
+      await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: `msg-${i}`,
+        threadTag: "load-test",
+      });
+    }
+
+    // Router does the only putMessage. Traceability now uses the targeted
+    // setMessageConversationId path, so total putMessage calls === N.
+    expect(counts.putMessage).toBe(N);
+    expect(counts.setMessageConversationId).toBe(N);
+  });
+
+  it("should call touchConversation per message instead of full putConversation", async () => {
+    const inner = new InMemoryStorage();
+    const { storage, counts } = instrumentStorage(inner);
+    const events = new EventEmitter();
+    const router = new MessageRouter(storage, events, "default");
+    new TraceabilityLayer(storage, events);
+
+    const N = 1000;
+    for (let i = 0; i < N; i++) {
+      await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: `msg-${i}`,
+        threadTag: "load-test",
+      });
+    }
+
+    // Exactly one putConversation (the create), then N touchConversation bumps.
+    expect(counts.putConversation).toBe(1);
+    expect(counts.touchConversation).toBe(N);
+  });
+
+  it("should keep participant row count stable for a long-lived broadcast conversation", async () => {
+    const storage = new SqliteStorage({ path: ":memory:" });
+    const events = new EventEmitter();
+    const router = new MessageRouter(storage, events, "default");
+    new TraceabilityLayer(storage, events);
+
+    const recipients = Array.from({ length: 10 }, (_, i) => `agent-${i}`);
+    const N = 1000;
+
+    for (let i = 0; i < N; i++) {
+      await router.routeMessage({
+        from: "alice",
+        to: recipients,
+        payload: `msg-${i}`,
+        threadTag: "broadcast",
+      });
+    }
+
+    const conversations = storage.listConversations("default");
+    expect(conversations).toHaveLength(1);
+
+    // alice + 10 recipients = 11 participants — must not balloon with N.
+    expect(conversations[0].participants).toHaveLength(11);
+
+    // Sanity: turns table grows linearly with messages (expected — that's the audit log).
+    expect(storage.getTurns(conversations[0].id)).toHaveLength(N);
+
+    storage.close();
+  });
+});
+
+describe("load: SQLite stays bounded", () => {
+  let dbPath: string;
+
+  beforeEach(() => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "inbox-sqlite-load-"));
+    dbPath = path.join(tmp, "inbox.db");
+  });
+  afterEach(() => {
+    const dir = path.dirname(dbPath);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("should keep DB file growth bounded under heavy load", async () => {
+    const storage = new SqliteStorage({ path: dbPath });
+    const events = new EventEmitter();
+    const router = new MessageRouter(storage, events, "default");
+    new TraceabilityLayer(storage, events);
+
+    const recipients = Array.from({ length: 10 }, (_, i) => `agent-${i}`);
+    const N = 5000;
+
+    for (let i = 0; i < N; i++) {
+      await router.routeMessage({
+        from: "alice",
+        to: recipients,
+        payload: `msg-${i}`,
+        threadTag: "broadcast",
+      });
+    }
+
+    // After close, WAL checkpoints into the main DB. The fix's main impact
+    // is on write *churn* (no per-message participant resyncs); this is a
+    // smoke test that the on-disk size scales reasonably with the data.
+    storage.close();
+    const size = fs.statSync(dbPath).size;
+    // 5000 messages × 11 recipients ≈ 55k recipient rows + 5k turns + FTS.
+    // 4 KiB per logical message is a generous ceiling.
+    expect(size).toBeLessThan(N * 4096);
+  });
+
+  it("pruneMessagesOlderThan should remove old data and reduce row counts", async () => {
+    const storage = new SqliteStorage({ path: ":memory:" });
+    const events = new EventEmitter();
+    const router = new MessageRouter(storage, events, "default");
+    new TraceabilityLayer(storage, events);
+
+    const N = 1000;
+    for (let i = 0; i < N; i++) {
+      const old = i < N / 2;
+      const ts = old ? "2024-01-01T00:00:00Z" : "2026-12-01T00:00:00Z";
+      const msg = await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: `msg-${i}`,
+        threadTag: "load",
+      });
+      // Backdate by overriding via storage to simulate aged messages
+      const stored = storage.getMessage(msg.id)!;
+      stored.created_at = ts;
+      storage.putMessage(stored);
+    }
+
+    const removed = storage.pruneMessagesOlderThan("2025-01-01T00:00:00Z");
+    expect(removed).toBe(N / 2);
+
+    // Recent half remains
+    const conv = storage.listConversations("default")[0];
+    expect(storage.getTurns(conv.id)).toHaveLength(N / 2);
+
+    storage.close();
+  });
+});

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[] = [