agent-mailbox-core 1.0.1 → 1.2.0

package/README.md

@@ -1,80 +1,81 @@
-# agent-mailbox
+<p align="center">
+  <strong>agent-mailbox-core</strong><br>
+  <em>Production-grade inter-agent messaging for multi-agent AI systems</em>
+</p>
 
-Production-grade inter-agent messaging for multi-agent AI systems. SQLite-backed with zero external dependencies.
+<p align="center">
+  <a href="https://github.com/lleontor705/agent-mailbox/actions/workflows/ci.yml"><img src="https://github.com/lleontor705/agent-mailbox/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://www.npmjs.com/package/agent-mailbox-core"><img src="https://img.shields.io/npm/v/agent-mailbox-core" alt="npm" /></a>
+  <a href="https://github.com/lleontor705/agent-mailbox/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
+</p>
 
-## 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.
+SQLite-backed inter-agent messaging with zero external dependencies. Visibility timeouts, dead letter queues, FTS5 search, rate limiting, typed payloads, threading, and broadcast — all powered by `bun:sqlite`.
 
 ## Install
 
 ```bash
-bun add agent-mailbox
+bun add agent-mailbox-core
 ```
 
 ## Quick Start
 
-### Standalone (library)
+### Library
 
 ```ts
-import { Mailbox } from "agent-mailbox";
+import { Mailbox } from "agent-mailbox-core/lib";
 
 const mailbox = new Mailbox({ dbPath: "./mailbox.db" });
 
-// Send
-const { messageId, threadId } = mailbox.send({
+// Send a message
+const { messageId } = 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)
+// Acknowledge
 mailbox.acknowledge(messages[0].id, {
   from: "developer",
-  body: "Got it, starting implementation.",
+  body: "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"]
+  "plugin": ["agent-mailbox-core@latest"]
 }
 ```
 
-Configure via environment variables:
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Visibility timeouts** | SQS-style message claiming. Un-acked messages re-appear automatically |
+| **Dead letter queue** | Messages that fail N times move to DLQ for inspection/replay |
+| **Idempotency** | Deduplication keys prevent duplicate processing |
+| **Full-text search** | FTS5 with graceful LIKE fallback |
+| **Rate limiting** | Per-agent, per-minute limits |
+| **Message TTL** | Per-message expiration with automatic cleanup |
+| **Priority ordering** | High/normal/low with priority-based inbox |
+| **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 |
+| **WAL mode** | Concurrent read/write for multi-agent workloads |
+
+## Configuration
 
 | Variable | Default | Description |
 |---|---|---|
@@ -87,40 +88,53 @@ Configure via environment variables:
 
 ## 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
+| Method | Description |
+|--------|-------------|
+| `send(opts)` | Send a message |
+| `broadcast(opts)` | Send to all agents |
+| `readInbox(opts)` | Read inbox (claims with visibility timeout) |
+| `acknowledge(id, response?)` | Acknowledge processing, optionally reply |
+| `search(opts)` | Full-text search |
+| `listThreads(agent)` | List conversation threads |
+| `getThread(threadId)` | Get all messages in a thread |
+| `request(opts)` | Send and wait for reply (exponential backoff) |
+| `registerAgent(name, role?)` | Register agent in registry |
+| `listAgents()` | List registered agents |
+| `getDeadLetters(limit?)` | View dead letter queue |
+| `replayDeadLetter(id)` | Re-send a dead letter |
+| `metrics()` | Get queue metrics |
+| `cleanup()` | Manual cleanup |
+| `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
-                   └─────────┘
+Agent A --send--> SQLite --readInbox--> Agent B
+                    |
+              +-----+-----+
+              | FTS5 index |
+              | DLQ        |
+              | Rate limits|
+              | Trace IDs  |
+              +------------+
 ```
 
+## Development
+
+```bash
+bun install
+bun test
+bun run lint     # type check
+```
+
+## Contributing
+
+1. Fork the repo
+2. Create a feature branch from `develop`: `git checkout -b feat/my-feature develop`
+3. Make your changes and add tests
+4. Run `bun test` and `bun run lint`
+5. Open a PR to `develop`
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,37 +1,8 @@
 /**
- * agent-mailbox — Production-grade inter-agent messaging for multi-agent AI systems
+ * agent-mailbox-core — 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();
- * ```
+ * Default export is the OpenCode Plugin (for auto-install: "agent-mailbox-core@latest")
+ * Library exports available at "agent-mailbox-core/lib"
  */
-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";
+export { default } from "./plugin.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC"}