agent-mailbox-core 1.0.0

package/dist/index.js

@@ -0,0 +1,556 @@
+// @bun
+// src/database.ts
+import { Database } from "bun:sqlite";
+var SCHEMA_VERSION = 1;
+function initDatabase(config) {
+  const db = new Database(config.dbPath);
+  if (config.walMode) {
+    db.exec("PRAGMA journal_mode=WAL");
+    db.exec("PRAGMA synchronous=NORMAL");
+  }
+  db.exec("PRAGMA foreign_keys=ON");
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_version (
+      version INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS messages (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      from_agent TEXT NOT NULL,
+      to_agent TEXT NOT NULL,
+      subject TEXT NOT NULL,
+      body TEXT NOT NULL,
+      thread_id TEXT NOT NULL,
+      priority TEXT NOT NULL DEFAULT 'normal' CHECK (priority IN ('high', 'normal', 'low')),
+      status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'delivered', 'read', 'acked', 'expired', 'dead')),
+      ttl_seconds INTEGER NOT NULL DEFAULT 86400,
+      idempotency_key TEXT,
+      trace_id TEXT,
+      receive_count INTEGER NOT NULL DEFAULT 0,
+      visible_after TEXT,
+      session_id TEXT NOT NULL DEFAULT '',
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      read_at TEXT,
+      ack_at TEXT,
+      expires_at TEXT NOT NULL DEFAULT (datetime('now', '+86400 seconds'))
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_messages_to_agent_status ON messages(to_agent, status);
+    CREATE INDEX IF NOT EXISTS idx_messages_thread ON messages(thread_id);
+    CREATE INDEX IF NOT EXISTS idx_messages_created ON messages(created_at);
+    CREATE INDEX IF NOT EXISTS idx_messages_expires ON messages(expires_at);
+    CREATE INDEX IF NOT EXISTS idx_messages_visible ON messages(visible_after);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_messages_idempotency ON messages(idempotency_key) WHERE idempotency_key IS NOT NULL;
+
+    CREATE TABLE IF NOT EXISTS threads (
+      id TEXT PRIMARY KEY,
+      subject TEXT NOT NULL,
+      participants TEXT NOT NULL DEFAULT '[]',
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      last_message_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS dead_letters (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      original_message_id INTEGER NOT NULL,
+      from_agent TEXT NOT NULL,
+      to_agent TEXT NOT NULL,
+      subject TEXT NOT NULL,
+      body TEXT NOT NULL,
+      thread_id TEXT NOT NULL,
+      reason TEXT NOT NULL,
+      moved_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS rate_limits (
+      agent TEXT NOT NULL,
+      window_start TEXT NOT NULL,
+      message_count INTEGER NOT NULL DEFAULT 1,
+      PRIMARY KEY (agent, window_start)
+    );
+
+    CREATE TABLE IF NOT EXISTS agent_registry (
+      name TEXT PRIMARY KEY,
+      role TEXT,
+      registered_at TEXT NOT NULL DEFAULT (datetime('now')),
+      last_active TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+  try {
+    db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
+        subject, body, content=messages, content_rowid=id
+      );
+
+      CREATE TRIGGER IF NOT EXISTS messages_ai AFTER INSERT ON messages BEGIN
+        INSERT INTO messages_fts(rowid, subject, body) VALUES (new.id, new.subject, new.body);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS messages_ad AFTER DELETE ON messages BEGIN
+        INSERT INTO messages_fts(messages_fts, rowid, subject, body) VALUES ('delete', old.id, old.subject, old.body);
+      END;
+    `);
+  } catch {}
+  const currentVersion = db.prepare("SELECT version FROM schema_version LIMIT 1").get();
+  if (!currentVersion) {
+    db.prepare("INSERT INTO schema_version (version) VALUES (?)").run(SCHEMA_VERSION);
+  }
+  return db;
+}
+
+// src/mailbox.ts
+var DEFAULT_CONFIG = {
+  dbPath: ":memory:",
+  defaultTTL: 86400,
+  visibilityTimeout: 300,
+  maxRetries: 3,
+  maxBodySize: 65536,
+  rateLimitPerMinute: 60,
+  walMode: true,
+  cleanupInterval: 300
+};
+function resolveConfig(config) {
+  return { ...DEFAULT_CONFIG, ...config };
+}
+function generateThreadId() {
+  return `thread-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+class Mailbox {
+  db;
+  config;
+  cleanupTimer = null;
+  stmts;
+  constructor(config) {
+    this.config = resolveConfig(config);
+    this.db = initDatabase(this.config);
+    this.stmts = this.prepareStatements();
+    if (this.config.cleanupInterval > 0) {
+      this.cleanupTimer = setInterval(() => this.cleanup(), this.config.cleanupInterval * 1000);
+    }
+  }
+  prepareStatements() {
+    return {
+      insertMessage: this.db.prepare(`
+        INSERT INTO messages (from_agent, to_agent, subject, body, thread_id, priority, ttl_seconds, idempotency_key, trace_id, session_id, expires_at)
+        VALUES ($from, $to, $subject, $body, $thread_id, $priority, $ttl, $idem_key, $trace_id, $session_id, datetime('now', '+' || $ttl || ' seconds'))
+      `),
+      insertThread: this.db.prepare(`
+        INSERT OR IGNORE INTO threads (id, subject, participants) VALUES ($id, $subject, $participants)
+      `),
+      updateThreadTimestamp: this.db.prepare(`
+        UPDATE threads SET last_message_at = datetime('now') WHERE id = $id
+      `),
+      getInbox: this.db.prepare(`
+        SELECT * FROM messages
+        WHERE (to_agent = $agent OR to_agent = 'broadcast')
+        AND from_agent != $agent
+        AND status IN ('pending', 'delivered')
+        AND (visible_after IS NULL OR visible_after <= datetime('now'))
+        AND expires_at > datetime('now')
+        ORDER BY
+          CASE priority WHEN 'high' THEN 0 WHEN 'normal' THEN 1 WHEN 'low' THEN 2 END,
+          created_at DESC
+        LIMIT $limit
+      `),
+      getInboxIncludeRead: this.db.prepare(`
+        SELECT * FROM messages
+        WHERE (to_agent = $agent OR to_agent = 'broadcast')
+        AND from_agent != $agent
+        AND status NOT IN ('dead', 'expired')
+        AND expires_at > datetime('now')
+        ORDER BY created_at DESC
+        LIMIT $limit
+      `),
+      claimMessage: this.db.prepare(`
+        UPDATE messages
+        SET status = 'delivered',
+            receive_count = receive_count + 1,
+            visible_after = datetime('now', '+' || $timeout || ' seconds')
+        WHERE id = $id
+      `),
+      markRead: this.db.prepare(`
+        UPDATE messages SET status = 'read', read_at = datetime('now'), visible_after = NULL WHERE id = $id
+      `),
+      markAcked: this.db.prepare(`
+        UPDATE messages SET status = 'acked', ack_at = datetime('now'), visible_after = NULL WHERE id = $id
+      `),
+      getMessage: this.db.prepare(`SELECT * FROM messages WHERE id = $id`),
+      searchFTS: this.db.prepare(`
+        SELECT m.* FROM messages m
+        JOIN messages_fts fts ON m.id = fts.rowid
+        WHERE messages_fts MATCH $query
+        AND m.expires_at > datetime('now')
+        ORDER BY m.created_at DESC
+        LIMIT $limit
+      `),
+      searchLIKE: this.db.prepare(`
+        SELECT * FROM messages
+        WHERE (subject LIKE $q OR body LIKE $q)
+        AND expires_at > datetime('now')
+        ORDER BY created_at DESC
+        LIMIT $limit
+      `),
+      listThreads: this.db.prepare(`
+        SELECT t.*,
+          COUNT(m.id) as message_count,
+          SUM(CASE WHEN m.status IN ('pending', 'delivered') AND (m.to_agent = $agent OR m.to_agent = 'broadcast') THEN 1 ELSE 0 END) as unread_count
+        FROM threads t
+        LEFT JOIN messages m ON m.thread_id = t.id
+        GROUP BY t.id
+        ORDER BY t.last_message_at DESC
+        LIMIT $limit
+      `),
+      getThreadMessages: this.db.prepare(`
+        SELECT * FROM messages WHERE thread_id = $thread_id ORDER BY created_at ASC
+      `),
+      getReply: this.db.prepare(`
+        SELECT * FROM messages
+        WHERE thread_id = $thread_id AND from_agent = $from AND to_agent = $to AND id > $after_id
+        ORDER BY created_at ASC LIMIT 1
+      `),
+      moveToDLQ: this.db.prepare(`
+        INSERT INTO dead_letters (original_message_id, from_agent, to_agent, subject, body, thread_id, reason)
+        SELECT id, from_agent, to_agent, subject, body, thread_id, $reason
+        FROM messages WHERE id = $id
+      `),
+      markDead: this.db.prepare(`
+        UPDATE messages SET status = 'dead' WHERE id = $id
+      `),
+      getDeadLetters: this.db.prepare(`
+        SELECT * FROM dead_letters ORDER BY moved_at DESC LIMIT $limit
+      `),
+      replayDeadLetter: this.db.prepare(`
+        SELECT * FROM dead_letters WHERE id = $id
+      `),
+      deleteDeadLetter: this.db.prepare(`
+        DELETE FROM dead_letters WHERE id = $id
+      `),
+      checkRate: this.db.prepare(`
+        SELECT message_count FROM rate_limits
+        WHERE agent = $agent AND window_start = $window
+      `),
+      upsertRate: this.db.prepare(`
+        INSERT INTO rate_limits (agent, window_start, message_count)
+        VALUES ($agent, $window, 1)
+        ON CONFLICT(agent, window_start)
+        DO UPDATE SET message_count = message_count + 1
+      `),
+      upsertAgent: this.db.prepare(`
+        INSERT INTO agent_registry (name, role, last_active)
+        VALUES ($name, $role, datetime('now'))
+        ON CONFLICT(name)
+        DO UPDATE SET role = COALESCE($role, role), last_active = datetime('now')
+      `),
+      listAgents: this.db.prepare(`
+        SELECT ar.name, ar.role, ar.last_active,
+          (SELECT COUNT(*) FROM messages WHERE from_agent = ar.name) as message_count
+        FROM agent_registry ar
+        ORDER BY ar.last_active DESC
+      `),
+      expireMessages: this.db.prepare(`
+        UPDATE messages SET status = 'expired' WHERE expires_at <= datetime('now') AND status NOT IN ('acked', 'expired', 'dead')
+      `),
+      requeueTimedOut: this.db.prepare(`
+        UPDATE messages SET status = 'pending', visible_after = NULL
+        WHERE status = 'delivered'
+        AND visible_after IS NOT NULL
+        AND visible_after <= datetime('now')
+        AND receive_count < $max_retries
+      `),
+      moveExhaustedToDLQ: this.db.prepare(`
+        SELECT id FROM messages
+        WHERE status = 'delivered'
+        AND visible_after IS NOT NULL
+        AND visible_after <= datetime('now')
+        AND receive_count >= $max_retries
+      `),
+      cleanRateLimits: this.db.prepare(`
+        DELETE FROM rate_limits WHERE window_start < $cutoff
+      `),
+      countByStatus: this.db.prepare(`
+        SELECT status, COUNT(*) as cnt FROM messages GROUP BY status
+      `),
+      countDeadLetters: this.db.prepare(`
+        SELECT COUNT(*) as cnt FROM dead_letters
+      `),
+      countActiveThreads: this.db.prepare(`
+        SELECT COUNT(*) as cnt FROM threads WHERE last_message_at > datetime('now', '-1 hour')
+      `),
+      messagesPerAgent: this.db.prepare(`
+        SELECT from_agent, COUNT(*) as cnt FROM messages GROUP BY from_agent ORDER BY cnt DESC
+      `),
+      avgDeliveryTime: this.db.prepare(`
+        SELECT AVG((julianday(read_at) - julianday(created_at)) * 86400000) as avg_ms
+        FROM messages WHERE read_at IS NOT NULL
+      `),
+      checkIdempotency: this.db.prepare(`
+        SELECT id, thread_id FROM messages WHERE idempotency_key = $key
+      `)
+    };
+  }
+  send(opts) {
+    if (Buffer.byteLength(opts.body, "utf-8") > this.config.maxBodySize) {
+      throw new Error(`Message body exceeds max size of ${this.config.maxBodySize} bytes`);
+    }
+    this.checkRateLimit(opts.from);
+    if (opts.idempotencyKey) {
+      const existing = this.stmts.checkIdempotency.get({ $key: opts.idempotencyKey });
+      if (existing) {
+        return { messageId: existing.id, threadId: existing.thread_id, idempotencyKey: opts.idempotencyKey };
+      }
+    }
+    const threadId = opts.threadId ?? generateThreadId();
+    const ttl = opts.ttlSeconds ?? this.config.defaultTTL;
+    this.stmts.insertThread.run({
+      $id: threadId,
+      $subject: opts.subject,
+      $participants: JSON.stringify([opts.from, opts.to])
+    });
+    this.stmts.updateThreadTimestamp.run({ $id: threadId });
+    const result = this.stmts.insertMessage.run({
+      $from: opts.from,
+      $to: opts.to,
+      $subject: opts.subject,
+      $body: opts.body,
+      $thread_id: threadId,
+      $priority: opts.priority ?? "normal",
+      $ttl: ttl,
+      $idem_key: opts.idempotencyKey ?? null,
+      $trace_id: opts.traceId ?? null,
+      $session_id: opts.sessionId ?? ""
+    });
+    this.stmts.upsertAgent.run({ $name: opts.from, $role: null });
+    return {
+      messageId: Number(result.lastInsertRowid),
+      threadId,
+      idempotencyKey: opts.idempotencyKey ?? null
+    };
+  }
+  broadcast(opts) {
+    return this.send({ ...opts, to: "broadcast" });
+  }
+  readInbox(opts) {
+    const limit = opts.limit ?? 20;
+    if (opts.includeRead) {
+      return this.stmts.getInboxIncludeRead.all({ $agent: opts.agent, $limit: limit });
+    }
+    const rows = this.stmts.getInbox.all({ $agent: opts.agent, $limit: limit });
+    for (const row of rows) {
+      this.stmts.claimMessage.run({
+        $id: row.id,
+        $timeout: this.config.visibilityTimeout
+      });
+    }
+    return rows;
+  }
+  markRead(messageId) {
+    this.stmts.markRead.run({ $id: messageId });
+  }
+  acknowledge(messageId, response) {
+    this.stmts.markAcked.run({ $id: messageId });
+    if (response) {
+      const original = this.stmts.getMessage.get({ $id: messageId });
+      if (original) {
+        return this.send({
+          from: response.from,
+          to: original.from_agent,
+          subject: `Re: ${original.subject}`,
+          body: response.body,
+          threadId: original.thread_id,
+          priority: "normal",
+          sessionId: response.sessionId
+        });
+      }
+    }
+    return null;
+  }
+  search(opts) {
+    const limit = opts.limit ?? 10;
+    try {
+      const rows = this.stmts.searchFTS.all({ $query: opts.query, $limit: limit });
+      return { messages: rows, usedFallback: false };
+    } catch {
+      const rows = this.stmts.searchLIKE.all({ $q: `%${opts.query}%`, $limit: limit });
+      return { messages: rows, usedFallback: true };
+    }
+  }
+  listThreads(agent, limit = 10) {
+    return this.stmts.listThreads.all({ $agent: agent, $limit: limit });
+  }
+  getThread(threadId) {
+    return this.stmts.getThreadMessages.all({ $thread_id: threadId });
+  }
+  async request(opts) {
+    const timeout = opts.timeoutMs ?? 120000;
+    const { messageId, threadId } = this.send({
+      ...opts,
+      priority: "high",
+      body: opts.body + `
+
+---
+REPLY REQUESTED \u2014 sender is waiting.`
+    });
+    const startTime = Date.now();
+    let delay = 500;
+    while (Date.now() - startTime < timeout) {
+      const reply = this.stmts.getReply.get({
+        $thread_id: threadId,
+        $from: opts.to,
+        $to: opts.from,
+        $after_id: messageId
+      });
+      if (reply) {
+        this.markRead(reply.id);
+        return { reply };
+      }
+      await new Promise((r) => setTimeout(r, delay));
+      delay = Math.min(delay * 1.5, 1e4);
+    }
+    return { timeout: true, messageId, threadId };
+  }
+  registerAgent(name, role) {
+    this.stmts.upsertAgent.run({ $name: name, $role: role ?? null });
+  }
+  listAgents() {
+    return this.stmts.listAgents.all();
+  }
+  getDeadLetters(limit = 20) {
+    return this.stmts.getDeadLetters.all({ $limit: limit });
+  }
+  replayDeadLetter(dlqId) {
+    const dl = this.stmts.replayDeadLetter.get({ $id: dlqId });
+    if (!dl)
+      return null;
+    const result = this.send({
+      from: dl.from_agent,
+      to: dl.to_agent,
+      subject: dl.subject,
+      body: dl.body,
+      threadId: dl.thread_id
+    });
+    this.stmts.deleteDeadLetter.run({ $id: dlqId });
+    return result;
+  }
+  metrics() {
+    const statusCounts = this.stmts.countByStatus.all();
+    const statusMap = {};
+    let total = 0;
+    for (const row of statusCounts) {
+      statusMap[row.status] = row.cnt;
+      total += row.cnt;
+    }
+    const dlCount = this.stmts.countDeadLetters.get().cnt;
+    const threadCount = this.stmts.countActiveThreads.get().cnt;
+    const perAgent = this.stmts.messagesPerAgent.all();
+    const avgDel = this.stmts.avgDeliveryTime.get();
+    return {
+      totalMessages: total,
+      pendingMessages: statusMap["pending"] ?? 0,
+      deliveredMessages: statusMap["delivered"] ?? 0,
+      deadLetters: dlCount,
+      activeThreads: threadCount,
+      messagesPerAgent: Object.fromEntries(perAgent.map((r) => [r.from_agent, r.cnt])),
+      avgDeliveryTimeMs: avgDel.avg_ms
+    };
+  }
+  cleanup() {
+    const expired = this.stmts.expireMessages.run().changes;
+    const requeued = this.stmts.requeueTimedOut.run({ $max_retries: this.config.maxRetries }).changes;
+    const exhausted = this.stmts.moveExhaustedToDLQ.all({ $max_retries: this.config.maxRetries });
+    for (const { id } of exhausted) {
+      this.stmts.moveToDLQ.run({ $id: id, $reason: `Max retries (${this.config.maxRetries}) exceeded` });
+      this.stmts.markDead.run({ $id: id });
+    }
+    const cutoff = new Date(Date.now() - 120000).toISOString().slice(0, 16);
+    this.stmts.cleanRateLimits.run({ $cutoff: cutoff });
+    return { expired, requeued, deadLettered: exhausted.length };
+  }
+  close() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    this.db.close();
+  }
+  checkRateLimit(agent) {
+    const window = new Date().toISOString().slice(0, 16);
+    const current = this.stmts.checkRate.get({ $agent: agent, $window: window });
+    if (current && current.message_count >= this.config.rateLimitPerMinute) {
+      throw new Error(`Rate limit exceeded for agent '${agent}': ${this.config.rateLimitPerMinute}/min`);
+    }
+    this.stmts.upsertRate.run({ $agent: agent, $window: window });
+  }
+}
+// src/format.ts
+function formatMessages(rows) {
+  if (!rows || rows.length === 0)
+    return "No messages found.";
+  return rows.map((m) => `[#${m.id}] ${m.priority === "high" ? "!! " : m.priority === "low" ? "-- " : ""}` + `From: @${m.from_agent} -> To: @${m.to_agent}
+` + `Subject: ${m.subject}
+` + `Thread: ${m.thread_id} | Status: ${m.status} | Receives: ${m.receive_count}
+` + `Time: ${m.created_at} | Expires: ${m.expires_at}` + `${m.read_at ? ` | Read: ${m.read_at}` : ""}` + `${m.ack_at ? ` | Acked: ${m.ack_at}` : ""}
+` + `${m.trace_id ? `Trace: ${m.trace_id}
+` : ""}` + `---
+${m.body}
+`).join(`
+` + "=".repeat(50) + `
+
+`);
+}
+function formatThreads(threads) {
+  if (!threads || threads.length === 0)
+    return "No active threads.";
+  return threads.map((t) => `[${t.id}] ${t.subject}
+` + `  Messages: ${t.message_count} | Unread: ${t.unread_count}
+` + `  Last activity: ${t.last_message_at}`).join(`
+
+`);
+}
+function formatAgents(agents) {
+  if (!agents || agents.length === 0)
+    return "No registered agents.";
+  return agents.map((a) => `@${a.name} [${a.messageCount} msgs]` + `${a.lastActive ? ` last active: ${a.lastActive}` : " (never active)"}
+` + `  ${a.role ?? "No role defined"}`).join(`
+
+`);
+}
+function formatDeadLetters(dls) {
+  if (!dls || dls.length === 0)
+    return "Dead letter queue is empty.";
+  return dls.map((d) => `[DLQ #${d.id}] Original: #${d.original_message_id}
+` + `From: @${d.from_agent} -> To: @${d.to_agent}
+` + `Subject: ${d.subject}
+` + `Reason: ${d.reason}
+` + `Moved: ${d.moved_at}
+` + `---
+${d.body}
+`).join(`
+` + "=".repeat(50) + `
+
+`);
+}
+function formatMetrics(m) {
+  const lines = [
+    `Mailbox Metrics`,
+    `${"=".repeat(40)}`,
+    `Total messages: ${m.totalMessages}`,
+    `Pending: ${m.pendingMessages}`,
+    `Delivered (in-flight): ${m.deliveredMessages}`,
+    `Dead letters: ${m.deadLetters}`,
+    `Active threads (last 1h): ${m.activeThreads}`,
+    `Avg delivery time: ${m.avgDeliveryTimeMs ? `${Math.round(m.avgDeliveryTimeMs)}ms` : "N/A"}`,
+    ``,
+    `Messages per agent:`,
+    ...Object.entries(m.messagesPerAgent).map(([a, c]) => `  @${a}: ${c}`)
+  ];
+  return lines.join(`
+`);
+}
+export {
+  formatThreads,
+  formatMetrics,
+  formatMessages,
+  formatDeadLetters,
+  formatAgents,
+  Mailbox
+};

package/dist/mailbox.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Core Mailbox class — the main API for agent-mailbox
+ */
+import { Database } from "bun:sqlite";
+import type { MailboxConfig, ResolvedConfig, Message, SendOptions, SendResult, InboxOptions, SearchOptions, Thread, DeadLetter, MailboxMetrics, AgentInfo } from "./types.js";
+export declare class Mailbox {
+    readonly db: Database;
+    readonly config: ResolvedConfig;
+    private cleanupTimer;
+    private stmts;
+    constructor(config?: MailboxConfig);
+    private prepareStatements;
+    /** Send a message to an agent */
+    send(opts: SendOptions): SendResult;
+    /** Broadcast a message to all agents */
+    broadcast(opts: Omit<SendOptions, "to">): SendResult;
+    /** Read inbox with visibility timeout */
+    readInbox(opts: InboxOptions): Message[];
+    /** Mark a message as read (clears visibility timeout) */
+    markRead(messageId: number): void;
+    /** Acknowledge a message (confirms processing complete) */
+    acknowledge(messageId: number, response?: {
+        from: string;
+        body: string;
+        sessionId?: string;
+    }): SendResult | null;
+    /** Search messages using FTS5 with LIKE fallback */
+    search(opts: SearchOptions): {
+        messages: Message[];
+        usedFallback: boolean;
+    };
+    /** List conversation threads */
+    listThreads(agent: string, limit?: number): Thread[];
+    /** Get all messages in a thread */
+    getThread(threadId: string): Message[];
+    /** Send a request and poll for reply with exponential backoff */
+    request(opts: SendOptions & {
+        timeoutMs?: number;
+    }): Promise<{
+        reply: Message;
+    } | {
+        timeout: true;
+        messageId: number;
+        threadId: string;
+    }>;
+    /** Register an agent (upsert) */
+    registerAgent(name: string, role?: string): void;
+    /** List all registered agents */
+    listAgents(): AgentInfo[];
+    /** Get messages in the dead letter queue */
+    getDeadLetters(limit?: number): DeadLetter[];
+    /** Replay a dead letter (re-send the original message) */
+    replayDeadLetter(dlqId: number): SendResult | null;
+    /** Get mailbox metrics snapshot */
+    metrics(): MailboxMetrics;
+    /** Run cleanup: expire messages, requeue timed-out, move exhausted to DLQ */
+    cleanup(): {
+        expired: number;
+        requeued: number;
+        deadLettered: number;
+    };
+    /** Close the database and stop cleanup timer */
+    close(): void;
+    private checkRateLimit;
+}
+//# sourceMappingURL=mailbox.d.ts.map

package/dist/mailbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.d.ts","sourceRoot":"","sources":["../src/mailbox.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,OAAO,EACP,WAAW,EACX,UAAU,EACV,YAAY,EACZ,aAAa,EACb,MAAM,EACN,UAAU,EACV,cAAc,EACd,SAAS,EAEV,MAAM,YAAY,CAAC;AAyBpB,qBAAa,OAAO;IAClB,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,YAAY,CAA+C;IAGnE,OAAO,CAAC,KAAK,CAA4C;gBAE7C,MAAM,CAAC,EAAE,aAAa;IAalC,OAAO,CAAC,iBAAiB;IA2MzB,iCAAiC;IACjC,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU;IAoDnC,wCAAwC;IACxC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,UAAU;IAIpD,yCAAyC;IACzC,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,EAAE;IAoBxC,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIjC,2DAA2D;IAC3D,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,GAAG,IAAI;IAoBhH,oDAAoD;IACpD,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG;QAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE;IAY3E,gCAAgC;IAChC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,MAAM,EAAE;IAIhD,mCAAmC;IACnC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE;IAItC,iEAAiE;IAC3D,OAAO,CACX,IAAI,EAAE,WAAW,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GACzC,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAiCvF,iCAAiC;IACjC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAIhD,iCAAiC;IACjC,UAAU,IAAI,SAAS,EAAE;IAMzB,4CAA4C;IAC5C,cAAc,CAAC,KAAK,SAAK,GAAG,UAAU,EAAE;IAIxC,0DAA0D;IAC1D,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAkBlD,mCAAmC;IACnC,OAAO,IAAI,cAAc;IA2BzB,6EAA6E;IAC7E,OAAO,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;IAqBtE,gDAAgD;IAChD,KAAK,IAAI,IAAI;IAUb,OAAO,CAAC,cAAc;CAUvB"}