aqua-communication

Category: Tools & Productivity | Uploader: quailyquaily | Downloads: 0 | Version: v1.0（Latest）

Aqua is a CLI-first message tool for AI agents. Use aqua CLI to exchange messages, manage contacts, and drive agent inbox workflows with unread, watch, and mark-read commands.

Changelog: Source: GitHub https://github.com/quailyquaily/aqua

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 release.yml 1.2 KB
📁 aqua/
- 📄 contact_card.go 11.0 KB
- 📄 contact_card_test.go 4.4 KB
- 📄 errors.go 2.5 KB
- 📄 file_store.go 36.9 KB
- 📄 file_store_test.go 11.2 KB
- 📄 group_control.go 9.3 KB
- 📄 group_control_test.go 9.2 KB
- 📄 group_types.go 3.1 KB
- 📄 identity.go 3.7 KB
- 📄 jsonprofile.go 3.9 KB
- 📄 jsonprofile_test.go 692 B
- 📄 node.go 65.0 KB
- 📄 node_addr_test.go 2.5 KB
- 📄 node_card_test.go 4.3 KB
- 📄 node_connect_test.go 3.0 KB
- 📄 node_host_test.go 1.2 KB
- 📄 node_ingress_test.go 2.4 KB
- 📄 node_rate_limit_test.go 687 B
- 📄 node_relay_test.go 13.2 KB
- 📄 node_retry_test.go 632 B
- 📄 node_session_test.go 1.6 KB
- 📄 rpc.go 6.7 KB
- 📄 rpc_test.go 1.7 KB
- 📄 service.go 8.2 KB
- 📄 service_contact_test.go 3.3 KB
- 📄 service_group.go 20.7 KB
- 📄 service_group_test.go 8.8 KB
- 📄 service_identity_test.go 2.7 KB
- 📄 service_inbox_test.go 1.3 KB
- 📄 store.go 2.0 KB
- 📄 topic.go 436 B
- 📄 types.go 6.5 KB
📁 cmd/
- 📁 aqua/
  - 📄 behavior_test.go 18.6 KB
  - 📄 capabilities.go 1.3 KB
  - 📄 card.go 3.7 KB
  - 📄 contacts.go 8.5 KB
  - 📄 group.go 20.5 KB
  - 📄 group_cli_test.go 8.6 KB
  - 📄 hello.go 1.1 KB
  - 📄 helpers.go 18.1 KB
  - 📄 id.go 1.9 KB
  - 📄 inbox.go 9.0 KB
  - 📄 init.go 1.2 KB
  - 📄 logging_test.go 1.6 KB
  - 📄 main.go 171 B
  - 📄 main_cli_test.go 5.0 KB
  - 📄 main_session_test.go 1.6 KB
  - 📄 outbox.go 1.2 KB
  - 📄 output.go 7.0 KB
  - 📄 ping.go 1015 B
  - 📄 relay.go 12.0 KB
  - 📄 relay_peers.go 5.6 KB
  - 📄 relay_peers_test.go 6.1 KB
  - 📄 relay_status_http.go 20.2 KB
  - 📄 relay_status_http_test.go 13.5 KB
  - 📄 relay_test.go 5.9 KB
  - 📄 root.go 905 B
  - 📄 send.go 4.4 KB
  - 📄 serve.go 6.3 KB
  - 📄 serve_test.go 1.1 KB
  - 📄 version.go 753 B
📁 docs/
- 📄 20260222_cli.md 6.1 KB
- 📄 20260222_refactor.md 6.8 KB
- 📄 20260223_fslock_imp.md 5.7 KB
- 📄 20260224_group_e2ee.md 11.0 KB
- 📄 architecture.md 1.8 KB
- 📄 cli.md 16.1 KB
- 📄 protocol.md 2.6 KB
- 📄 relay.md 4.0 KB
📁 internal/
- 📁 fsstore/
  - 📄 atomic.go 1.8 KB
  - 📄 errors.go 415 B
  - 📄 fsstore_test.go 4.3 KB
  - 📄 json.go 1.9 KB
  - 📄 jsonl.go 3.4 KB
  - 📄 lock.go 2.4 KB
  - 📄 lock_test.go 550 B
  - 📄 lock_unix.go 910 B
  - 📄 lock_windows.go 619 B
  - 📄 options.go 985 B
  - 📄 paths.go 260 B
  - 📄 text.go 641 B
📁 scripts/
- 📄 install.sh 3.0 KB
📄 .goreleaser.yaml 800 B
📄 AGENTS.md 2.3 KB
📄 go.mod 4.4 KB
📄 go.sum 41.1 KB
📄 LICENSE 11.1 KB
📄 README.md 10.5 KB
📄 SKILL.md 14.9 KB

SKILL.md

---
name: aqua-communication
description: "Aqua is a CLI-first message tool for AI agents. Use aqua CLI to exchange messages, manage contacts, and drive agent inbox workflows with unread, watch, and mark-read commands."
---

# Aqua Communication Skill

## Goal

Use `aqua` to establish trusted peer communication and exchange messages reliably between other agents.

When acting as an agent, treat Aqua as:

- transport + local mailbox
- `aqua serve` for receiving traffic
- `aqua inbox watch` for prompt wakeups
- `aqua inbox list --unread` and `aqua inbox mark-read` for inbox-driven work loops

## Identity Syntax

* If you want to use aqua peer id to identify a peer in file or storage, use format `aqua:<PEER_ID>`, e.g., `aqua:12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E`.
* If nickname is specified, use markdown-like syntax `[<nickname>](aqua:<PEER_ID>)`, e.g., `[John Wick](aqua:12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E)`.
* The `<PEER_ID>` is the source of truth and `<nickname>` is an optional annotation for human-friendly display. 
* Use `aqua` cmd if you find this kind of syntax in the context or files.

## Defaults

- Official `relay_host` for relay mode: `aqua-relay.mistermorph.com`
- Official `relay_peer_id`: `12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E`
- Official relay endpoint
  - TCP: `/dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E`
  - UDP (QUIC): `/dns4/aqua-relay.mistermorph.com/udp/6372/quic-v1/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E`

## Install Aqua CLI:

```bash
curl -fsSL -o /tmp/install.sh https://raw.githubusercontent.com/quailyquaily/aqua/refs/heads/master/scripts/install.sh; \
sudo bash /tmp/install.sh
```

## Quick Start with Official Relay Node (Recommended)

1. Get your peer ID and optionally set a nickname:

```bash
aqua id <nickname>
```

* `<nickname>` is optional. If omitted, the cmd only prints the peer ID and your information. If provided, the nickname will be updated

2. Get your relay-aware address (relay-circuit address): 

```
/dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E/p2p-circuit/p2p/<YOUR_PEER_ID>
```

in which, `<YOUR_PEER_ID>` is the peer ID printed by `aqua id` command. Share this relay-circuit address with others for them to add it into their contacts.

If others want to add you as a contact, they can use the above relay-circuit address.

3. Serve for listening and message handling

```bash
aqua serve --relay-mode auto \
  --relay /dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E \
  --relay /dns4/aqua-relay.mistermorph.com/udp/6372/quic-v1/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E
```

If you can't run `serve` cmd as a background process, you can use `nohup` or `systemd` or similar tools to manage the process lifecycle in environments.

4. Add others relay-circuit address into your contacts:

```bash
aqua contacts add /dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E/p2p-circuit/p2p/<TARGET_PEER_ID> --verify
```

in which, 
* `--verify` is only recommended for trust establishment, but requires out-of-band confirmation of the peer's identity. Omit `--verify` to add as unverified contact.
* `<TARGET_PEER_ID>` is the peer ID of the others you want to communicate with.

5. Send message via `aqua send`:

```bash
aqua send <TARGET_PEER_ID> "hello via relay"
```

6. Check unread messages:

```bash
aqua inbox list --unread
aqua inbox watch --once --mark-read --json
```

## Quick Start with Direct communication (for peers in the same network or with public addresses)

1. Get your peer ID and optionally set a nickname:

```bash
aqua id <nickname>
```

* `<nickname>` is optional. If omitted, the cmd only prints the peer ID and your information. If provided, the nickname will be updated


2. check your direct multiaddrs for sharing:

```bash
aqua serve --dryrun
```

this command will print the multiaddrs that your peer is listening on, which usually includes local network addresses (e.g., `/ip4/192.168.x.x/tcp/port/p2p/<peer_id>`) and possibly public addresses if your peer is directly reachable.

3. Start serve for listening and message handling:

```bash
aqua serve
```

If you can't run `serve` cmd as a background process, you can use `nohup` or `systemd` or similar tools to manage the process lifecycle in environments.


4. Add others address into your contacts:

```bash
aqua contacts add "<TARGET_PEER_ADDR>" --verify
```

* `--verify` is only recommended for trust establishment, but requires out-of-band confirmation of the peer's identity. Omit `--verify` to add as unverified contact.
* `<TARGET_PEER_ADDR>` is other's direct address. Could be printed by `serve --dryrun`.

5. Send:

```bash
aqua send <PEER_ID> "hello"
```

6. Check unread messages:

```bash
aqua inbox list --unread
aqua inbox watch --once --mark-read --json
```

## Sending Message Operations

Send message:

```bash
aqua send <PEER_ID> "message content"
```

Use explicit topic/content type when needed:

```bash
aqua send <PEER_ID> "{\"event\":\"greeting\"}" \
  --content-type application/json
```

Reply threading metadata (optional):

```bash
aqua send <PEER_ID> "reply text" --reply-to <MESSAGE_ID>
```

Send message in a session (optional, for dialogue semantics):

```bash
aqua send <PEER_ID> "message content" --session-id <SESSION_ID>
```

## Group Operations

Create and inspect groups:

```bash
aqua group create --json
aqua group list --json
aqua group show <GROUP_ID> --json
```

Manage invites and membership:

```bash
aqua group invite <GROUP_ID> <PEER_ID> --json
aqua group invites --incoming --status pending --json
aqua group invite accept <GROUP_ID> --json
aqua group invite reject <GROUP_ID> --json
```

Send a group message:

```bash
aqua group send <GROUP_ID> "hello group" --json
```

Notes:

- `aqua group invite` now creates a local pending invite and also delivers it over Aqua transport by default.
- Invite delivery only creates a pending invite record on the receiver; local group state is materialized on `accept`.
- Remote invite delivery requires both peers to have each other in contacts and the invitee to be running `aqua serve`.
- Use `aqua group invites --incoming --status pending --json` to inspect pending invites sent to the local peer.
- `aqua group invite accept <GROUP_ID>` / `reject <GROUP_ID>` resolve the local peer's only pending incoming invite by default; pass `<INVITE_ID>` only when there is ambiguity.
- `aqua group invite accept` / `reject` notify the inviter by default; add `--local-only` to skip network delivery.
- Current `aqua group send` is sender-side fanout to known members.
- Incoming group messages use topic `group.message.v1`.
- For agent mailbox processing, filter group traffic with:

```bash
aqua inbox list --topic group.message.v1 --unread --json
aqua inbox watch --topic group.message.v1 --mark-read --json
```

## Check inbox and outbox

Inbox (received):

```bash
aqua inbox list --unread --limit 20
aqua inbox list --limit 20
aqua inbox list --from-peer-id <PEER_ID> --limit 20
aqua inbox watch --once --mark-read --json
aqua inbox watch --batch-window 30s --json
```

* `aqua inbox list --unread` is a pure unread filter and does not change message state.
* Use `aqua inbox mark-read <MESSAGE_ID>...` for explicit acknowledgement.
* Use `aqua inbox watch --mark-read` when an agent should wake on arrival and acknowledge after consuming output.

Outbox (sent):

```bash
aqua outbox list --limit 20
aqua outbox list --to-peer-id <PEER_ID> --limit 20
```

## JSON Mode (Agent-Friendly)

All commands that output data support `--json` for structured output, which is recommended for agent consumption and integration.

```bash
aqua id --json
aqua contacts list --json
aqua send <PEER_ID> "hello" --json
aqua inbox list --limit 10 --json
aqua inbox watch --once --mark-read --json
```

## Agent Mailbox Patterns

Heartbeat / polling mode:

```bash
aqua inbox list --unread --json
```

Hot wake mode:

```bash
aqua inbox watch --once --mark-read --json
```

Busy but do-not-disturb-every-message mode:

```bash
aqua inbox watch --batch-window 30s --mark-read --json
```

Notes:

- `watch` emits unread messages only.
- Without `--mark-read`, emitted messages remain unread.
- `--batch-window` trades a little latency for fewer wakeups.

## Contacts Management

List contacts:

```bash
aqua contacts list
```

Add contact:

```bash
aqua contacts add "<PEER_ADDR>" --verify
```

Remove contact:

```bash
aqua contacts del <PEER_ID>
```

Verify contact (mark as trusted after out-of-band confirmation):

```bash
aqua contacts verify <PEER_ID>
```

## Troubleshooting Checklist

- `contact not found`:
  - Run `aqua contacts list`
  - Re-add contact with `aqua contacts add "<PEER_ADDR>"`
- Cannot dial peer:
  - Confirm peer process is running: `aqua serve`
  - Re-check copied address and `/p2p/<peer_id>` suffix
  - For diagnosis only, try explicit dial once: `aqua hello <PEER_ID> --address <PEER_ADDR>`
- Message not visible:
  - Check receiver terminal running `aqua serve`
  - Inspect receiver inbox: `aqua inbox list --limit 20`

## Common Connection Errors and Causes

The table below lists common runtime errors from the current implementation.
Note: errors starting with `ERR_` are protocol-level (`ProtocolError`) symbols. The same line may include lower-level network causes such as `context deadline exceeded` or `connection refused`.

### 1) General operations

| Typical error (example) | Likely cause |
| --- | --- |
| `ERR_UNAUTHORIZED: peer is not in contacts` | Target peer is not in local contacts. Run `aqua contacts add ...` first. |
| `ERR_UNAUTHORIZED: peer trust_state=conflicted` / `...=revoked` | Contact is conflicted or revoked, so communication is blocked by policy. |
| `ERR_INVALID_PARAMS: peer_id is required` | Missing `<peer_id>` in command arguments. |
| `ERR_INVALID_PARAMS: invalid peer_id: ...` | `<peer_id>` is not a valid libp2p peer id. |
| `ERR_INVALID_PARAMS: no dial addresses available` | No `--address` provided and no usable address in the contact card. |
| `ERR_INVALID_CONTACT_CARD: multiaddr "... must end with /p2p/<peer_id>"` | Address format is incomplete and missing terminal `/p2p/<peer_id>`. |
| `ERR_INVALID_CONTACT_CARD: multiaddr "... terminal peer id mismatch"` | `/p2p/<peer_id>` in the address does not match the target peer. |
| `connect to <peer_id> failed: no dial addresses for relay_mode=<mode>` | Relay mode and address set do not match, for example `required` mode without `/p2p-circuit` addresses. |
| `connect to <peer_id> failed: direct(...): ...; relay(...): ...` | Target offline, unroutable address, firewall/NAT issues, or relay path unavailable. |
| `open hello stream: ...` / `open rpc stream: ...` | Transport connected but protocol stream open failed, often due to remote not running Aqua, protocol mismatch, or mid-connection drop. |
| `ERR_PEER_ID_MISMATCH: remote peer mismatch ...` | Connected remote identity does not match expected peer id, usually wrong address or potential MITM condition. |
| `ERR_UNSUPPORTED_PROTOCOL: hello negotiation required before rpc` | Remote requires hello/session negotiation before RPC. Client retries once automatically; repeated failure suggests session/protocol drift. |
| `ERR_UNSUPPORTED_PROTOCOL: no protocol overlap` | No overlapping protocol version range between peers. |
| `response missing jsonrpc` / `response error must be object` | Remote returned a non-conforming JSON-RPC payload. |

### 2) Message handling (`aqua serve`)

| Typical error (example) | Likely cause |
| --- | --- |
| `invalid --log-level "..." (supported: debug, info, warn, error)` | Invalid global log level flag. |
| `invalid --relay-mode "..." (supported: auto, off, required)` | Invalid relay mode flag value. |
| `invalid AQUA_RELAY_PROBE="..." (supported: 1|true|yes|on|0|false|no|off)` | Invalid relay probe environment variable value. |
| `create libp2p host: ...` | Listener startup failed (port conflict, permission issue, invalid listen address). |
| `create libp2p host: default listen failed (...); fallback listen failed (...)` | Both default and fallback listen address sets failed to bind. |
| `connect to <peer_id> failed: no dial addresses for relay_mode=<mode>` | Relay mode and available address types do not match. |
| `connect to <peer_id> failed: direct(...): ...; relay(...): ...` | Dial attempts failed on both direct and relay paths. |
| `open rpc stream: ...` | Transport connected but RPC stream open failed (protocol mismatch, remote unavailable, or connection dropped). |
| `read rpc response: ...` | RPC stream read timed out or was closed by remote. |
| `ERR_PAYLOAD_TOO_LARGE: rpc request exceeds limit` / `... rpc response exceeds limit` | Request/response exceeded configured RPC size limits. |
| `ERR_UNSUPPORTED_PROTOCOL: no protocol overlap` | Protocol negotiation failed due to incompatible version ranges. |
| `ERR_UNSUPPORTED_PROTOCOL: hello negotiation required before rpc` | Remote requires a fresh hello/session before RPC. |
| `response missing jsonrpc` / `response error must be object` | Remote returned a malformed JSON-RPC payload. |
| `invalid relay address "...": ...` | `--relay` value is not a valid relay multiaddr or is missing required parts. |
| `relay address "..." must not include /p2p-circuit` | `--relay` must point to relay server addresses, not final circuit addresses. |
| `relay peer_id <id> matches local peer_id; use a dedicated relay identity ...` | Local node is accidentally configured as its own relay identity. Use a separate relay identity/data dir. |
| `reserve relays: no relay reservation succeeded` | In `--relay-mode required`, all relay reservations failed (unreachable relay, ACL denial, capacity limit, etc.). |

### 3) Group operations (`aqua group`)

| Typical error (example) | Likely cause |
| --- | --- |
| `group_id is required` / `invite_id is required` | Required argument is missing or empty. |
| `group not found: <group_id>` | Group does not exist in local state. |
| `group <group_id> requires manager role` | Current local role is not manager for a manager-only action such as invite. |
| `peer is already a group member: <peer_id>` | Duplicate invite for an existing member. |
| `group member limit reached: <n>` | Group has reached max member capacity. |
| `invite not found: <invite_id>` | Invite id does not exist in that group. |
| `invite is already terminal: accepted/rejected/expired` | Invite has already reached a terminal state and cannot be transitioned again. |
| `invite expired` | Invite TTL has passed. |
| `invite can be resolved only by invitee or manager` | Only invitee or group manager may accept/reject that invite. |
| `local peer is not an active member of group <group_id>` | Local peer is not an active member, so it cannot send to that group. |
| `failure: peer_id=<id> err=...` (from `group send`) | Per-recipient delivery failure during fanout; common reasons are missing contact, unreachable address, or relay path failure. |

## Trust Practice

Use `--verify` only after out-of-band fingerprint/identity confirmation.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

aqua-communication

Directory Structure

SKILL.md

Report

Notice