@mono-agent/whatsapp-adapter 0.12.0 → 0.14.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.
- package/README.md +112 -15
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,12 +1,24 @@
|
|
|
1
1
|
# @mono-agent/whatsapp-adapter
|
|
2
2
|
|
|
3
|
+
Connect a mono-agent responder to allowed WhatsApp chats through a
|
|
4
|
+
Baileys-compatible linked-device socket.
|
|
5
|
+
|
|
3
6
|
## Category
|
|
4
7
|
|
|
8
|
+
<!-- package-metadata:start -->
|
|
9
|
+
<!-- Generated by scripts/generate-package-docs.mjs. Do not edit by hand. -->
|
|
10
|
+
|
|
5
11
|
Category: `communication`
|
|
12
|
+
Tier: `plugin`
|
|
13
|
+
Catalog responsibility: Adapts WhatsApp messages to structural agent requests and buffered final-only replies.
|
|
14
|
+
|
|
15
|
+
<!-- package-metadata:end -->
|
|
6
16
|
|
|
7
17
|
## Responsibility
|
|
8
18
|
|
|
9
|
-
WhatsApp
|
|
19
|
+
Normalize WhatsApp text messages, authorize chats, apply direct/group trigger
|
|
20
|
+
rules, queue work per chat, support cancellation, and deliver each completed
|
|
21
|
+
agent response through a Baileys-compatible socket.
|
|
10
22
|
|
|
11
23
|
This is a **plugin-tier** package: it publishes to npm in the mono-agent lockstep at the same version as the core packages, but it is not part of the core `@mono-agent/agent-app` dependency closure. `@mono-agent/agent-app` loads it only when a host declares it under `channels.plugins[]`.
|
|
12
24
|
|
|
@@ -16,21 +28,16 @@ The adapter is opt-in: plugin `config.enabled` / `MONO_AGENT_WHATSAPP_ENABLED` d
|
|
|
16
28
|
|
|
17
29
|
## Install / Usage
|
|
18
30
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
31
|
+
This plugin is outside the core `@mono-agent/agent-app` dependency closure.
|
|
32
|
+
Install the matching lockstep version, then declare it under
|
|
33
|
+
`channels.plugins[]`:
|
|
22
34
|
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
WhatsAppAdapter,
|
|
26
|
-
WhatsAppEventRunner,
|
|
27
|
-
createBaileysWhatsAppSocket,
|
|
28
|
-
loadWhatsAppAdapterConfig,
|
|
29
|
-
WHATSAPP_CONFIG_FIELDS,
|
|
30
|
-
} from "@mono-agent/whatsapp-adapter";
|
|
35
|
+
```bash
|
|
36
|
+
pnpm add @mono-agent/agent-app@latest @mono-agent/whatsapp-adapter@latest
|
|
31
37
|
```
|
|
32
38
|
|
|
33
|
-
|
|
39
|
+
The lockstep `latest` tags resolve to the same framework version. If the host
|
|
40
|
+
pins an older release, replace both `latest` tags with that same version.
|
|
34
41
|
|
|
35
42
|
```json
|
|
36
43
|
{
|
|
@@ -49,12 +56,93 @@ Config-loaded channel usage:
|
|
|
49
56
|
}
|
|
50
57
|
```
|
|
51
58
|
|
|
52
|
-
|
|
59
|
+
On first `mono-agent start`, scan the logged QR code from WhatsApp's **Linked
|
|
60
|
+
devices** screen. Baileys writes credentials under
|
|
61
|
+
`.mono-agent/whatsapp-auth/`. The adapter does not enforce filesystem modes, so
|
|
62
|
+
create and keep that directory accessible only to the OS owner, treat it as a
|
|
63
|
+
login secret, and keep it out of version control.
|
|
64
|
+
|
|
65
|
+
Authorization happens after message normalization and before commands or group
|
|
66
|
+
trigger checks. An unlisted chat receives a default denial response; it is not
|
|
67
|
+
silently ignored. The config-first plugin has no `unauthorizedText` setting.
|
|
68
|
+
Programmatic hosts can override that copy with
|
|
69
|
+
`messages: { unauthorizedText: "..." }` when constructing `WhatsAppAdapter` or
|
|
70
|
+
calling `startWhatsAppAdapter()`. Use `allowAllChats: true` only when every chat
|
|
71
|
+
attached to the linked account may invoke the agent.
|
|
72
|
+
|
|
73
|
+
The response stream buffers `append` and `replace` calls in memory. Apart from
|
|
74
|
+
an optional one-time status such as `Thinking…`, WhatsApp receives no partial
|
|
75
|
+
answer: `finish()` splits and sends only the final text. This avoids exposing
|
|
76
|
+
reasoning or tool progress as chat messages.
|
|
77
|
+
|
|
78
|
+
Custom hosts can compose the socket, adapter, and event runner directly:
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
import {
|
|
82
|
+
WhatsAppAdapter,
|
|
83
|
+
WhatsAppEventRunner,
|
|
84
|
+
createBaileysWhatsAppSocket,
|
|
85
|
+
} from "@mono-agent/whatsapp-adapter";
|
|
86
|
+
|
|
87
|
+
const { socket, saveCreds } = await createBaileysWhatsAppSocket({
|
|
88
|
+
authDir: ".mono-agent/whatsapp-auth",
|
|
89
|
+
});
|
|
90
|
+
const adapter = new WhatsAppAdapter({
|
|
91
|
+
socket,
|
|
92
|
+
responder,
|
|
93
|
+
allowedChatJids: ["123@s.whatsapp.net"],
|
|
94
|
+
});
|
|
95
|
+
const runner = new WhatsAppEventRunner({ socket, adapter, saveCreds });
|
|
96
|
+
runner.start();
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The base responder, stream, response, and cancellation contracts come from
|
|
100
|
+
`@mono-agent/agent-contracts`.
|
|
53
101
|
|
|
54
102
|
The bundled `WhatsAppEventRunner` derives a queue from each usable, trimmed `remoteJid`; messages without one share a fallback queue. Within a queue it awaits both the message handler and its result callback before starting the next message. Different queues can enter the adapter concurrently, so one chat is not held behind another by the event runner, although host runtime limits can still serialize the underlying agent work. Completion and result-callback order across different chats is not guaranteed to match global receive order. A later message in the same chat, including `/cancel`, does not overtake the in-flight handler.
|
|
55
103
|
|
|
104
|
+
## Architecture
|
|
105
|
+
|
|
106
|
+
### Data flow
|
|
107
|
+
|
|
108
|
+
1. The channel driver layers plugin JSON and environment settings, then starts a
|
|
109
|
+
Baileys socket using the agent-local auth directory.
|
|
110
|
+
2. The event runner listens for socket updates, persists credential changes,
|
|
111
|
+
and serializes `messages.upsert` work per trimmed chat JID while allowing
|
|
112
|
+
different chats to proceed concurrently.
|
|
113
|
+
3. The normalizer extracts a safe text message and chat/sender metadata. The
|
|
114
|
+
adapter rejects unauthorized chats with its default or programmatic denial
|
|
115
|
+
text, then applies direct or group-mention trigger policy and handles
|
|
116
|
+
commands/cancellation.
|
|
117
|
+
4. Allowed prompts enter the host-owned structural responder. The message stream
|
|
118
|
+
buffers deltas and sends final answer chunks only when the turn finishes.
|
|
119
|
+
|
|
120
|
+
### Package structure
|
|
121
|
+
|
|
122
|
+
| Source module | Responsibility |
|
|
123
|
+
| --- | --- |
|
|
124
|
+
| [`channel-driver.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/whatsapp-adapter/src/channel-driver.ts) | Config-first plugin lifecycle and agent-local auth-directory selection. |
|
|
125
|
+
| [`config.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/whatsapp-adapter/src/config.ts) | JSON/env layering, allowlist validation, and redacted config metadata. |
|
|
126
|
+
| [`baileys-socket.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/whatsapp-adapter/src/baileys-socket.ts) | Baileys socket creation and linked-device credential persistence. |
|
|
127
|
+
| [`event-runner.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/whatsapp-adapter/src/event-runner.ts) | Socket event subscription and per-chat processing queues. |
|
|
128
|
+
| [`message-normalizer.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/whatsapp-adapter/src/message-normalizer.ts) | Supported-message extraction and JID/chat metadata normalization. |
|
|
129
|
+
| [`adapter.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/whatsapp-adapter/src/adapter.ts) | Authorization, trigger policy, commands, cancellation, and responder invocation. |
|
|
130
|
+
| [`message-stream.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/whatsapp-adapter/src/message-stream.ts) | Buffered final-only answer delivery and message-size splitting. |
|
|
131
|
+
|
|
56
132
|
## Public API
|
|
57
133
|
|
|
134
|
+
### Start here
|
|
135
|
+
|
|
136
|
+
| API | Use it for |
|
|
137
|
+
| --- | --- |
|
|
138
|
+
| `createChannelDriver` / `createWhatsAppChannelDriver` | Load the adapter through a config-first `channels.plugins[]` entry. |
|
|
139
|
+
| `startWhatsAppAdapter` | Start socket, adapter, and event lifecycle together in a custom host. |
|
|
140
|
+
| `WhatsAppAdapter` | Apply authorization, trigger, command, cancellation, and responder behavior to messages. |
|
|
141
|
+
| `createBaileysWhatsAppSocket` | Create the production linked-device socket and credential store. |
|
|
142
|
+
| `WhatsAppEventRunner` | Subscribe a socket to adapter handling with deterministic per-chat ordering. |
|
|
143
|
+
| `WhatsAppMessageStream` | Reuse buffered final-answer delivery for a compatible socket. |
|
|
144
|
+
| `loadWhatsAppAdapterConfig` | Validate and redact plugin/env config without starting the channel. |
|
|
145
|
+
|
|
58
146
|
<!-- public-api-inventory:start -->
|
|
59
147
|
<!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
|
|
60
148
|
|
|
@@ -134,7 +222,16 @@ This adapter depends on Baileys plus shared `@mono-agent/agent-contracts` primit
|
|
|
134
222
|
|
|
135
223
|
## What This Package Does Not Own
|
|
136
224
|
|
|
137
|
-
It does not
|
|
225
|
+
It does not own the linked WhatsApp account, provide encryption or backup for
|
|
226
|
+
the auth directory, build prompts, run models, store memory, expose an operator
|
|
227
|
+
UI, or add an unsolicited WhatsApp notification destination.
|
|
228
|
+
|
|
229
|
+
## Related Documentation
|
|
230
|
+
|
|
231
|
+
- [WhatsApp channel guide](https://mono-agent-docs.vercel.app/channels/whatsapp/)
|
|
232
|
+
- [Channels overview](https://mono-agent-docs.vercel.app/channels/)
|
|
233
|
+
- [Sessions and concurrency](https://mono-agent-docs.vercel.app/runtime/sessions-concurrency/)
|
|
234
|
+
- [Delivery and send tools](https://mono-agent-docs.vercel.app/channels/delivery-and-send-tools/)
|
|
138
235
|
|
|
139
236
|
## Verification
|
|
140
237
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mono-agent/whatsapp-adapter",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
4
4
|
"description": "WhatsApp communication adapter for host-compatible runtimes using Baileys.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "GPL-3.0-only",
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"README.md"
|
|
27
27
|
],
|
|
28
28
|
"dependencies": {
|
|
29
|
-
"@mono-agent/agent-contracts": "0.
|
|
29
|
+
"@mono-agent/agent-contracts": "0.14.0",
|
|
30
30
|
"@whiskeysockets/baileys": "^7.0.0-rc11"
|
|
31
31
|
},
|
|
32
32
|
"publishConfig": {
|