feat(tools): notify — the first client tool

Desktop notifications are the wave-1 built-in the resident has no
native way to send: the daemon's pushes land in the poll queue, and
this is the program that turns one into an OS notification —
`notify push --title --body [--device]` on the shared plumbing, the
claw's `POST /v1/notifications` on the far end.

The binary is the template for every later client: connection from
the environment the daemon provisions, one contract-headered call,
JSON or error shape, exit code. The e2e test drives the real binary
against a mock claw — a wrong token is a 401 with the code to match,
a consent route is a 403, a good push prints the row — so a packaging
regression cannot pass silently. `skills/` ships the markdown that
teaches the agent the tool exists and what its answers mean.
This commit is contained in:
vhaudiquet committed 2026-10-24 01:02:28 +02:00
1 parent 29099add9d
commit 2fbd93fd79
7 files changed
+1199

No files matched your search

+28
View File
@@ -0,0 +1,28 @@
---
description: Push a notification to the user's devices — reminders and heads-up messages that reach them outside this chat, delivered at the device's next poll
---
# notify
`notify` queues one notification on the daemon: a device polls for it and
acks it on delivery. Use it when the user must hear something when this
conversation is not in front of them — "remind me", "tell me when X", or a
finding from a scheduled turn.
## Push one notification
```bash
notify push --title "CI is red" --body "acme/widgets: main failed on unit tests"
```
Add `--device <name>` to target a device other than the default phone.
The answer is the queued row as one JSON line; `"id"` addresses it on the
daemon (`DELETE /v1/notifications/{id}` over the API, by a human client).
## Notes
- Failures print `{"error": "..."}` and exit non-zero: exit 2 means the
daemon is unreachable (`RHEMA_URL`), 3 means the credential was refused.
- The queue is at-least-once: an unacked row keeps coming back until the
device acks it. Do not re-push to "make sure" — ask the user first.