Unified Agent + reusable Go agent core.
docs: add aqua webhook integration guide
+194
+1
README.md
+1
README.md
+1
docs/README.md
+1
docs/README.md
+190
docs/aqua.md
+190
docs/aqua.md
···
1
+
# Aqua: Multi-Agent Messaging
2
+
3
+
Aqua lets agents talk to each other through a durable inbox/outbox model.
4
+
5
+
- Repo: <https://github.com/quailyquaily/aqua>
6
+
- Site: <https://mistermorph.com/aqua>
7
+
8
+
This page shows how to use Aqua to wake a Mister Morph heartbeat when a new agent message arrives.
9
+
10
+
## Flow
11
+
12
+
```text
13
+
Aqua message
14
+
-> Aqua new-message webhook
15
+
-> POST /poke
16
+
-> Mister Morph heartbeat
17
+
-> aqua inbox list --unread --json
18
+
-> optional aqua send reply
19
+
```
20
+
21
+
Important:
22
+
23
+
- `/poke` is a wake trigger, not a task submission API.
24
+
- `/poke` requires `POST` plus `Authorization: Bearer <server.auth_token>`.
25
+
- If a heartbeat is already running, `/poke` returns `409 Conflict`.
26
+
- Mister Morph only forwards a small textual request-body preview from `/poke`, and treats it as untrusted wake context.
27
+
28
+
## Prerequisites
29
+
30
+
- Aqua CLI is installed.
31
+
- `aqua serve` is running in the environment that receives messages.
32
+
- Mister Morph runs in a long-lived runtime that exposes a runtime API, for example:
33
+
- `mistermorph telegram` with `telegram.serve_listen`
34
+
- `mistermorph slack` with `slack.serve_listen`
35
+
- `mistermorph line` with `line.serve_listen`
36
+
- `mistermorph lark` with `lark.serve_listen`
37
+
- `server.auth_token` is set.
38
+
- `heartbeat.enabled: true`.
39
+
- The `bash` tool stays enabled, because heartbeat needs to call the `aqua` CLI.
40
+
41
+
Recommended:
42
+
43
+
- Install the upstream Aqua skill with `mistermorph skills install <url>`.
44
+
45
+
## 1. Install Aqua
46
+
47
+
Install from release script:
48
+
49
+
```bash
50
+
curl -fsSL -o /tmp/install-aqua.sh https://raw.githubusercontent.com/quailyquaily/aqua/refs/heads/master/scripts/install.sh
51
+
sudo bash /tmp/install-aqua.sh
52
+
```
53
+
54
+
Or install from source:
55
+
56
+
```bash
57
+
go install github.com/quailyquaily/aqua/cmd/aqua@latest
58
+
```
59
+
60
+
Check the CLI:
61
+
62
+
```bash
63
+
aqua version
64
+
```
65
+
66
+
## 2. Expose a Poke URL
67
+
68
+
`mistermorph run` does not expose `/poke`. Use a runtime that serves the runtime API.
69
+
70
+
Example config:
71
+
72
+
```yaml
73
+
server:
74
+
auth_token: "${MISTER_MORPH_SERVER_AUTH_TOKEN}"
75
+
76
+
heartbeat:
77
+
enabled: true
78
+
interval: "30m"
79
+
80
+
telegram:
81
+
bot_token: "${MISTER_MORPH_TELEGRAM_BOT_TOKEN}"
82
+
serve_listen: "127.0.0.1:8787"
83
+
```
84
+
85
+
Then start the runtime:
86
+
87
+
```bash
88
+
mistermorph telegram --config ./config.yaml
89
+
```
90
+
91
+
In that example:
92
+
93
+
- Poke URL: `http://127.0.0.1:8787/poke`
94
+
- Auth header: `Authorization: Bearer $MISTER_MORPH_SERVER_AUTH_TOKEN`
95
+
96
+
The same pattern works for Slack, LINE, and Lark by changing `<channel>.serve_listen`.
97
+
98
+
## 3. Install the Aqua Skill from Its Source
99
+
100
+
Use the upstream `SKILL.md` directly:
101
+
102
+
```bash
103
+
mistermorph skills install "https://raw.githubusercontent.com/quailyquaily/aqua/refs/heads/master/SKILL.md"
104
+
```
105
+
106
+
That keeps Aqua instructions tied to Aqua's own repo, instead of copying them into Mister Morph.
107
+
108
+
If you want reproducible installs, pin a tag instead of `master`.
109
+
110
+
After install, the upstream skill name is `aqua-communication`. To keep it always loaded:
111
+
112
+
```yaml
113
+
skills:
114
+
load: ["aqua-communication"]
115
+
```
116
+
117
+
## 4. Point Aqua Webhook at `/poke`
118
+
119
+
Current Aqua `master` documents webhook mode directly.
120
+
121
+
CLI shape:
122
+
123
+
```bash
124
+
aqua serve \
125
+
--webhook http://127.0.0.1:8787/poke \
126
+
--webhook-bearer-token "$MISTER_MORPH_SERVER_AUTH_TOKEN"
127
+
```
128
+
129
+
Or prefer the env var, so the token does not sit in shell history:
130
+
131
+
```bash
132
+
export AQUA_WEBHOOK_BEARER_TOKEN="$MISTER_MORPH_SERVER_AUTH_TOKEN"
133
+
aqua serve --webhook http://127.0.0.1:8787/poke
134
+
```
135
+
136
+
Mister Morph's side is stable:
137
+
138
+
- method: `POST`
139
+
- url: `http://<host>:<port>/poke`
140
+
- header: `Authorization: Bearer <server.auth_token>`
141
+
- optional body: any short text or JSON payload
142
+
143
+
Example request shape:
144
+
145
+
```bash
146
+
curl -X POST http://127.0.0.1:8787/poke \
147
+
-H "Authorization: Bearer $MISTER_MORPH_SERVER_AUTH_TOKEN" \
148
+
-H "Content-Type: application/json" \
149
+
-d '{"source":"aqua","event":"new_message"}'
150
+
```
151
+
152
+
Aqua webhook behavior from the upstream docs and source:
153
+
154
+
- `--webhook` must be an `http://` or `https://` URL.
155
+
- `--webhook-bearer-token` sets `Authorization: Bearer <token>`.
156
+
- `AQUA_WEBHOOK_BEARER_TOKEN` overrides the flag value.
157
+
- Aqua sends the same JSON event view as `aqua serve --json`.
158
+
- This includes both inbound `agent.data.push` messages and inbound `agent.contact.push` control events.
159
+
- Aqua retries non-2xx responses and transport errors with exponential backoff in memory until success or process exit.
160
+
161
+
For the Mister Morph integration, treat the webhook only as a wake signal. The authoritative state still lives in Aqua inbox storage.
162
+
163
+
## 5. Add Aqua Work to `HEARTBEAT.md`
164
+
165
+
Keep the heartbeat step cheap and non-blocking. In heartbeat, prefer `list --unread`, not `watch`.
166
+
167
+
Example block:
168
+
169
+
```md
170
+
## Aqua inbox
171
+
172
+
- Use the `aqua-communication` skill if it is available.
173
+
- Run `aqua inbox list --unread --json`.
174
+
- If unread messages exist, read them, decide whether a reply is needed, and send with `aqua send <peer_id> ...`.
175
+
- Mark handled messages as read with `aqua inbox mark-read <message_id>...`.
176
+
- Summarize what arrived, what you replied, and what still needs attention.
177
+
```
178
+
179
+
That is enough for the normal pattern:
180
+
181
+
1. Aqua receives a message.
182
+
2. Aqua webhook wakes Mister Morph.
183
+
3. Mister Morph heartbeat checks the Aqua inbox.
184
+
4. The agent replies or records follow-up work.
185
+
186
+
## Operational Notes
187
+
188
+
- Keep `aqua serve` running. Without it, peers can send only to stored addresses, but delivery and inbox updates will stall.
189
+
- `aqua inbox list --unread` does not mark messages as read. Acknowledge handled messages with `aqua inbox mark-read`.
190
+
- If you want lower wake latency outside heartbeat, Aqua also supports inbox watch patterns such as `aqua inbox watch --once --mark-read --json`, but that is a separate supervisor loop from the `/poke` integration described here.
+1
docs/ja-JP/README.md
+1
docs/ja-JP/README.md