agent-mailbox-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lleontor705
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# agent-mailbox
+
+Production-grade inter-agent messaging for multi-agent AI systems. SQLite-backed with zero external dependencies.
+
+## Features
+
+- **Embedded SQLite** — No broker, no server. Pure `bun:sqlite`.
+- **Visibility timeouts** — SQS-style message claiming. Un-acked messages re-appear automatically.
+- **Dead letter queue** — Messages that fail N times are moved to DLQ for inspection/replay.
+- **Idempotency** — Deduplication keys prevent duplicate message processing.
+- **Full-text search** — FTS5 with graceful LIKE fallback.
+- **Rate limiting** — Per-agent, per-minute rate limits.
+- **Message TTL** — Per-message expiration with automatic cleanup.
+- **Typed payloads** — Full TypeScript types for all operations.
+- **Priority ordering** — High/normal/low priority with priority-based inbox ordering.
+- **Threading** — Conversation threads with participant tracking.
+- **Broadcast** — Send to all agents at once.
+- **Agent registry** — Dynamic agent discovery (auto-registered on first message).
+- **Trace IDs** — Cross-workflow observability.
+- **Metrics** — Queue depths, delivery times, per-agent stats.
+- **OpenCode plugin** — Drop-in plugin for OpenCode CLI.
+- **WAL mode** — Concurrent read/write for multi-agent workloads.
+
+## Install
+
+```bash
+bun add agent-mailbox
+```
+
+## Quick Start
+
+### Standalone (library)
+
+```ts
+import { Mailbox } from "agent-mailbox";
+
+const mailbox = new Mailbox({ dbPath: "./mailbox.db" });
+
+// Send
+const { messageId, threadId } = mailbox.send({
+  from: "architect",
+  to: "developer",
+  subject: "API spec ready",
+  body: "OpenAPI spec finalized. Proceed with implementation.",
+  priority: "high",
+  traceId: "workflow-42",
+});
+
+// Read inbox (with visibility timeout)
+const messages = mailbox.readInbox({ agent: "developer" });
+
+// Acknowledge (prevents re-delivery)
+mailbox.acknowledge(messages[0].id, {
+  from: "developer",
+  body: "Got it, starting implementation.",
+});
+
+// Search
+const { messages: results } = mailbox.search({ query: "API spec" });
+
+// Metrics
+console.log(mailbox.metrics());
+
+mailbox.close();
+```
+
+### OpenCode Plugin
+
+In your `opencode.json`:
+
+```json
+{
+  "plugin": ["agent-mailbox/plugin"]
+}
+```
+
+Configure via environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `AGENT_MAILBOX_DB` | `~/.agent-mailbox/mailbox.db` | Database path |
+| `AGENT_MAILBOX_TTL` | `86400` | Default message TTL (seconds) |
+| `AGENT_MAILBOX_VIS_TIMEOUT` | `300` | Visibility timeout (seconds) |
+| `AGENT_MAILBOX_MAX_RETRIES` | `3` | Max retries before DLQ |
+| `AGENT_MAILBOX_MAX_BODY` | `65536` | Max message body size (bytes) |
+| `AGENT_MAILBOX_RATE_LIMIT` | `60` | Messages per agent per minute |
+
+## API
+
+### `new Mailbox(config?)`
+
+Create a mailbox instance.
+
+### `mailbox.send(opts)` — Send a message
+### `mailbox.broadcast(opts)` — Send to all agents
+### `mailbox.readInbox(opts)` — Read inbox (claims messages with visibility timeout)
+### `mailbox.markRead(id)` — Mark as read
+### `mailbox.acknowledge(id, response?)` — Acknowledge processing, optionally reply
+### `mailbox.search(opts)` — Full-text search
+### `mailbox.listThreads(agent, limit?)` — List conversation threads
+### `mailbox.getThread(threadId)` — Get all messages in a thread
+### `mailbox.request(opts)` — Send and wait for reply (exponential backoff)
+### `mailbox.registerAgent(name, role?)` — Register agent in registry
+### `mailbox.listAgents()` — List registered agents
+### `mailbox.getDeadLetters(limit?)` — View dead letter queue
+### `mailbox.replayDeadLetter(id)` — Re-send a dead letter
+### `mailbox.metrics()` — Get queue metrics
+### `mailbox.cleanup()` — Manual cleanup (runs automatically on interval)
+### `mailbox.close()` — Close database and stop timers
+
+## Architecture
+
+```
+Agent A ──msg_send──> SQLite ──msg_read_inbox──> Agent B
+                        │
+                   ┌────┴────┐
+                   │  FTS5   │  ← Full-text search index
+                   │  DLQ    │  ← Dead letter queue
+                   │  Rate   │  ← Per-agent rate limits
+                   │  Trace  │  ← Cross-workflow IDs
+                   └─────────┘
+```
+
+## License
+
+MIT

package/dist/database.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Database initialization and schema management for Agent Mailbox
+ */
+import { Database } from "bun:sqlite";
+import type { ResolvedConfig } from "./types.js";
+export declare function initDatabase(config: ResolvedConfig): Database;
+//# sourceMappingURL=database.d.ts.map

package/dist/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CAuG7D"}

package/dist/format.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Message formatting utilities
+ */
+import type { Message, Thread, AgentInfo, DeadLetter, MailboxMetrics } from "./types.js";
+export declare function formatMessages(rows: Message[]): string;
+export declare function formatThreads(threads: Thread[]): string;
+export declare function formatAgents(agents: AgentInfo[]): string;
+export declare function formatDeadLetters(dls: DeadLetter[]): string;
+export declare function formatMetrics(m: MailboxMetrics): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEzF,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAgBtD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAUvD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAUxD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,MAAM,CAa3D;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAevD"}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * agent-mailbox — Production-grade inter-agent messaging for multi-agent AI systems
+ *
+ * @example
+ * ```ts
+ * import { Mailbox } from "agent-mailbox";
+ *
+ * const mailbox = new Mailbox({ dbPath: "./mailbox.db" });
+ *
+ * // Send a message
+ * const { messageId, threadId } = mailbox.send({
+ *   from: "architect",
+ *   to: "developer",
+ *   subject: "API schema ready",
+ *   body: "The OpenAPI spec is finalized. Proceed with implementation.",
+ *   priority: "high",
+ * });
+ *
+ * // Read inbox
+ * const messages = mailbox.readInbox({ agent: "developer" });
+ *
+ * // Acknowledge
+ * mailbox.acknowledge(messages[0].id);
+ *
+ * // Search
+ * const { messages: results } = mailbox.search({ query: "API schema" });
+ *
+ * // Metrics
+ * console.log(mailbox.metrics());
+ *
+ * mailbox.close();
+ * ```
+ */
+export { Mailbox } from "./mailbox.js";
+export { formatMessages, formatThreads, formatAgents, formatDeadLetters, formatMetrics } from "./format.js";
+export type { Priority, DeliveryStatus, MailboxConfig, Message, SendOptions, SendResult, InboxOptions, SearchOptions, Thread, DeadLetter, MailboxMetrics, AgentInfo, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5G,YAAY,EACV,QAAQ,EACR,cAAc,EACd,aAAa,EACb,OAAO,EACP,WAAW,EACX,UAAU,EACV,YAAY,EACZ,aAAa,EACb,MAAM,EACN,UAAU,EACV,cAAc,EACd,SAAS,GACV,MAAM,YAAY,CAAC"}