agent-mailbox-core 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +77 -63
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,25 +1,17 @@
1
- # agent-mailbox
1
+ <p align="center">
2
+ <strong>agent-mailbox-core</strong><br>
3
+ <em>Production-grade inter-agent messaging for multi-agent AI systems</em>
4
+ </p>
2
5
 
3
- Production-grade inter-agent messaging for multi-agent AI systems. SQLite-backed with zero external dependencies.
6
+ <p align="center">
7
+ <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>
8
+ <a href="https://www.npmjs.com/package/agent-mailbox-core"><img src="https://img.shields.io/npm/v/agent-mailbox-core" alt="npm" /></a>
9
+ <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>
10
+ </p>
4
11
 
5
- ## Features
12
+ ---
6
13
 
7
- - **Embedded SQLite** — No broker, no server. Pure `bun:sqlite`.
8
- - **Visibility timeouts** — SQS-style message claiming. Un-acked messages re-appear automatically.
9
- - **Dead letter queue** — Messages that fail N times are moved to DLQ for inspection/replay.
10
- - **Idempotency** — Deduplication keys prevent duplicate message processing.
11
- - **Full-text search** — FTS5 with graceful LIKE fallback.
12
- - **Rate limiting** — Per-agent, per-minute rate limits.
13
- - **Message TTL** — Per-message expiration with automatic cleanup.
14
- - **Typed payloads** — Full TypeScript types for all operations.
15
- - **Priority ordering** — High/normal/low priority with priority-based inbox ordering.
16
- - **Threading** — Conversation threads with participant tracking.
17
- - **Broadcast** — Send to all agents at once.
18
- - **Agent registry** — Dynamic agent discovery (auto-registered on first message).
19
- - **Trace IDs** — Cross-workflow observability.
20
- - **Metrics** — Queue depths, delivery times, per-agent stats.
21
- - **OpenCode plugin** — Drop-in plugin for OpenCode CLI.
22
- - **WAL mode** — Concurrent read/write for multi-agent workloads.
14
+ 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`.
23
15
 
24
16
  ## Install
25
17
 
@@ -29,44 +21,35 @@ bun add agent-mailbox-core
29
21
 
30
22
  ## Quick Start
31
23
 
32
- ### Standalone (library)
24
+ ### Library
33
25
 
34
26
  ```ts
35
27
  import { Mailbox } from "agent-mailbox-core/lib";
36
28
 
37
29
  const mailbox = new Mailbox({ dbPath: "./mailbox.db" });
38
30
 
39
- // Send
40
- const { messageId, threadId } = mailbox.send({
31
+ // Send a message
32
+ const { messageId } = mailbox.send({
41
33
  from: "architect",
42
34
  to: "developer",
43
35
  subject: "API spec ready",
44
36
  body: "OpenAPI spec finalized. Proceed with implementation.",
45
37
  priority: "high",
46
- traceId: "workflow-42",
47
38
  });
48
39
 
49
40
  // Read inbox (with visibility timeout)
50
41
  const messages = mailbox.readInbox({ agent: "developer" });
51
42
 
52
- // Acknowledge (prevents re-delivery)
43
+ // Acknowledge
53
44
  mailbox.acknowledge(messages[0].id, {
54
45
  from: "developer",
55
- body: "Got it, starting implementation.",
46
+ body: "Starting implementation.",
56
47
  });
57
48
 
58
- // Search
59
- const { messages: results } = mailbox.search({ query: "API spec" });
60
-
61
- // Metrics
62
- console.log(mailbox.metrics());
63
-
64
49
  mailbox.close();
65
50
  ```
66
51
 
67
- ### OpenCode Plugin (auto-install)
68
-
69
- In your `opencode.json`:
52
+ ### OpenCode Plugin
70
53
 
71
54
  ```json
72
55
  {
@@ -74,7 +57,25 @@ In your `opencode.json`:
74
57
  }
75
58
  ```
76
59
 
77
- Configure via environment variables:
60
+ ## Features
61
+
62
+ | Feature | Description |
63
+ |---------|-------------|
64
+ | **Visibility timeouts** | SQS-style message claiming. Un-acked messages re-appear automatically |
65
+ | **Dead letter queue** | Messages that fail N times move to DLQ for inspection/replay |
66
+ | **Idempotency** | Deduplication keys prevent duplicate processing |
67
+ | **Full-text search** | FTS5 with graceful LIKE fallback |
68
+ | **Rate limiting** | Per-agent, per-minute limits |
69
+ | **Message TTL** | Per-message expiration with automatic cleanup |
70
+ | **Priority ordering** | High/normal/low with priority-based inbox |
71
+ | **Threading** | Conversation threads with participant tracking |
72
+ | **Broadcast** | Send to all agents at once |
73
+ | **Agent registry** | Dynamic agent discovery (auto-registered on first message) |
74
+ | **Trace IDs** | Cross-workflow observability |
75
+ | **Metrics** | Queue depths, delivery times, per-agent stats |
76
+ | **WAL mode** | Concurrent read/write for multi-agent workloads |
77
+
78
+ ## Configuration
78
79
 
79
80
  | Variable | Default | Description |
80
81
  |---|---|---|
@@ -87,40 +88,53 @@ Configure via environment variables:
87
88
 
88
89
  ## API
89
90
 
90
- ### `new Mailbox(config?)`
91
-
92
- Create a mailbox instance.
93
-
94
- ### `mailbox.send(opts)` — Send a message
95
- ### `mailbox.broadcast(opts)` — Send to all agents
96
- ### `mailbox.readInbox(opts)` — Read inbox (claims messages with visibility timeout)
97
- ### `mailbox.markRead(id)` — Mark as read
98
- ### `mailbox.acknowledge(id, response?)` — Acknowledge processing, optionally reply
99
- ### `mailbox.search(opts)` — Full-text search
100
- ### `mailbox.listThreads(agent, limit?)` — List conversation threads
101
- ### `mailbox.getThread(threadId)` — Get all messages in a thread
102
- ### `mailbox.request(opts)` — Send and wait for reply (exponential backoff)
103
- ### `mailbox.registerAgent(name, role?)` — Register agent in registry
104
- ### `mailbox.listAgents()` — List registered agents
105
- ### `mailbox.getDeadLetters(limit?)` — View dead letter queue
106
- ### `mailbox.replayDeadLetter(id)` — Re-send a dead letter
107
- ### `mailbox.metrics()` — Get queue metrics
108
- ### `mailbox.cleanup()` — Manual cleanup (runs automatically on interval)
109
- ### `mailbox.close()` — Close database and stop timers
91
+ | Method | Description |
92
+ |--------|-------------|
93
+ | `send(opts)` | Send a message |
94
+ | `broadcast(opts)` | Send to all agents |
95
+ | `readInbox(opts)` | Read inbox (claims with visibility timeout) |
96
+ | `acknowledge(id, response?)` | Acknowledge processing, optionally reply |
97
+ | `search(opts)` | Full-text search |
98
+ | `listThreads(agent)` | List conversation threads |
99
+ | `getThread(threadId)` | Get all messages in a thread |
100
+ | `request(opts)` | Send and wait for reply (exponential backoff) |
101
+ | `registerAgent(name, role?)` | Register agent in registry |
102
+ | `listAgents()` | List registered agents |
103
+ | `getDeadLetters(limit?)` | View dead letter queue |
104
+ | `replayDeadLetter(id)` | Re-send a dead letter |
105
+ | `metrics()` | Get queue metrics |
106
+ | `cleanup()` | Manual cleanup |
107
+ | `close()` | Close database and stop timers |
110
108
 
111
109
  ## Architecture
112
110
 
113
111
  ```
114
- Agent A ──msg_send──> SQLite ──msg_read_inbox──> Agent B
115
- │
116
- ┌────┴────┐
117
- │ FTS5 │ ← Full-text search index
118
- │ DLQ │ ← Dead letter queue
119
- │ Rate │ ← Per-agent rate limits
120
- │ Trace │ ← Cross-workflow IDs
121
- └─────────┘
112
+ Agent A --send--> SQLite --readInbox--> Agent B
113
+ |
114
+ +-----+-----+
115
+ | FTS5 index |
116
+ | DLQ |
117
+ | Rate limits|
118
+ | Trace IDs |
119
+ +------------+
122
120
  ```
123
121
 
122
+ ## Development
123
+
124
+ ```bash
125
+ bun install
126
+ bun test
127
+ bun run lint # type check
128
+ ```
129
+
130
+ ## Contributing
131
+
132
+ 1. Fork the repo
133
+ 2. Create a feature branch from `develop`: `git checkout -b feat/my-feature develop`
134
+ 3. Make your changes and add tests
135
+ 4. Run `bun test` and `bun run lint`
136
+ 5. Open a PR to `develop`
137
+
124
138
  ## License
125
139
 
126
140
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-mailbox-core",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "Production-grade inter-agent messaging for multi-agent AI systems. SQLite-backed with FTS5 search, visibility timeouts, dead letter queues, typed payloads, and more.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",