@pingroom/cli 0.6.2 → 0.7.2

package/README.md

@@ -6,10 +6,10 @@ from CI, scripts, and agents. Delivered as push straight to your phone.
 One dependency (`qrcode-terminal`, used only to draw the pairing QR). Works
 anywhere Node ≥ 20 runs.
 
-> **Release status:** npm currently serves 0.6.1. The corrected attachment
-> limits are in the tested 0.6.2 release candidate on `main`; the public GitHub
-> Action remains pinned to 0.6.1 until 0.6.2 is published and clean-install
-> verified.
+> **Release status:** 0.7.2 is prepared for publish — the room grant, the
+> `attachments:write` scope `--attach` always needed, and actionable text on the
+> refusals you can fix. The GitHub Action pins 0.7.2, so publish before relying
+> on it.
 
 ## Install and first run
 
@@ -27,8 +27,10 @@ npx --yes @pingroom/cli
 ```
 
 Either command starts the same connection prompt. QR pairing stores the selected
-account, credential, and delivery room in `~/.pingroom`; later commands reuse
+account, credential, and room grant in `~/.pingroom`; later commands reuse
 them, so a local invocation needs neither `PINGROOM_TOKEN` nor `PINGROOM_ROOM`.
+On the phone you grant one room, several, or every room on the account — the
+first room you pick is the delivery room, where Questions and Handoffs land.
 The email fallback stores the credential only. Setting
 `pingroom config set default_room <invite-code>` enables room-addressed commands,
 but private Agent Inbox and Handoff delivery require a connection approved with
@@ -41,16 +43,17 @@ pingroom ping -m "Deploy succeeded ✅"
 
 Commands: `ping` (send), `ask` (ask a human), `watch` (block on an existing
 question), `list`, `cancel`, `handoff` (hand a decision to a specific human),
-`handoffs` (list open or recent Handoffs), `live` (lock-screen progress card),
-`hook` (Claude Code), `mcp` (client setup), `activate` (retry the Agent Inbox
-test), `config`, and `logout`.
+`handoffs` (list open or recent Handoffs), `listen` (hear pings as they land),
+`live` (lock-screen progress card),
+`hook` (Claude Code), `mcp` (client setup), `activate` (send an optional test
+Question), `config`, and `logout`.
 Run `pingroom --help` for the full reference.
 
 ## Connecting
 
 Run `pingroom` (global install) or `npx --yes @pingroom/cli` (no install) with no
-arguments. It prints a QR code — scan it with the PingRoom app and pick both the
-account and the room the agent delivers to — or take the emailed-code fallback.
+arguments. It prints a QR code — scan it with the PingRoom app, pick the account,
+and grant the rooms this agent may reach — or take the emailed-code fallback.
 
 ```
 $ pingroom
@@ -61,43 +64,55 @@ $ pingroom
 
   [QR]
   Or open: https://pingroom.io/app/agents/pair?token=…
-  Waiting for approval… ✓ Connected as @agt_ab12cd34ef → #Project X
-  Sending a test question to PingRoom…
-  Answer “PingRoom connected. Can you answer this?” on your phone.
-✓ Test question answered (Yes). Agent Inbox is ready.
-```
-
-After QR approval, the CLI saves the active credential first, then sends one
-idempotent onboarding Question and observes it through the Handoff wait API.
-Short network and server failures are retried, and `Retry-After` is honored for
-rate limits within the two-minute overall deadline. An answer alone is not
-reported as success: the terminal response must also carry the server's exact
-`activation_completed: true` stamp. On supporting server and mobile builds,
-that stamp means the native phone returned the opaque proof carried in the push
-before the human answer, and this CLI then observed the result. An answered
-response whose stamp is false or missing is incomplete and is not retried as if
-history could be rewritten. If the Question is still pending when the local
-deadline elapses, or activation cannot start, the CLI prints the recovery
-command and exits with the connection still saved and usable. A terminal test
-without the stamp requires a current PingRoom app and a fresh numbered attempt;
-run `pingroom activate` again with the saved connection.
-
-Resume an open idempotent check with the saved QR credential:
+  Waiting for approval… ✓ Connected as @agt_ab12cd34ef → #Project X +2 more
+```
+
+Approving on the phone is the whole ceremony — connecting sends nothing else to
+your phone. The status line reflects the grant: `→ #Project X` for one room,
+`→ #Project X +2 more` for several, `→ all rooms` when you granted every room.
+
+## Proving the round-trip (optional)
 
 ```bash
 pingroom activate
 ```
 
-An incomplete explicit retry exits `1`; it never deletes or replaces the saved
-credential. The command does not fall back to `PINGROOM_TOKEN`, an email-only
-credential, or a credential without `pingroom:handoffs:create` and a
-QR-selected delivery room. Email-code and other non-interactive credential
-flows do not run the phone-response loop automatically.
+`activate` sends one idempotent onboarding Question and observes it through the
+Handoff wait API. Short network and server failures are retried, and
+`Retry-After` is honored for rate limits within the two-minute overall deadline.
+An answer alone is not reported as success: the terminal response must also
+carry the server's exact `activation_completed: true` stamp. On supporting
+server and mobile builds, that stamp means the native phone returned the opaque
+proof carried in the push before the human answer, and this CLI then observed
+the result. An answered response whose stamp is false or missing is incomplete
+and is not retried as if history could be rewritten.
+
+An incomplete run exits `1`; it never deletes or replaces the saved credential.
+The command does not fall back to `PINGROOM_TOKEN`, an email-only credential, or
+a credential without `pingroom:handoffs:create` and a delivery room. A grant of
+all rooms pins no delivery room — pick one under Connected Agents in the app
+first.
 
 There is deliberately no `login` command: being unconnected is a state the tool
 resolves, not one you have to discover. Once connected, bare `pingroom` prints
 that status line followed by the usual help.
 
+### What the approval grants
+
+Approving on the phone grants two separate things, and both are enforced:
+
+- **Permissions** — the scopes this CLI asks for: `rooms:read`,
+  `broadcast:send`, `attachments:write`, `notifications:read`, `questions:ask`,
+  `handoffs:create`, `live:write`. Nothing widens them later; a command needing
+  one you did not approve returns `403 insufficient_scope`.
+- **Rooms** — one room, several, or all of them. A room outside that grant
+  returns `403 room_not_granted` on any write, including pings, questions and
+  live streams. Widen it under Connected Agents in the app.
+
+Both refusals print the fix, not just the code. A credential paired by an older
+CLI carries the scope set that version asked for — reconnect to re-approve if a
+command starts reporting `insufficient_scope`.
+
 The credential lands in `~/.pingroom/credentials.json` (mode `0600`, inside a
 `0700` directory). `PINGROOM_HOME` moves that directory; `pingroom logout`
 clears it.
@@ -206,12 +221,41 @@ on the Lock Screen (iOS Live Activity / Dynamic Island, Android live update, and
 a full inline card in the app). `start` opens it with one alert, `update` moves
 it **silently**, `end` closes it with one completion alert.
 
+## Hearing replies
+
+Everything else here talks; `listen` is how an agent hears — replies to its own
+structured pings, a human's ping in a room it belongs to, anything landing while
+it works.
+
+```bash
+pingroom listen                      # block, printing each ping as it lands
+pingroom listen --once --json        # one batch as JSON, then exit
+pingroom listen --from "$LAST_ID"    # catch up from a known ping id
+```
+
+```
+      --timeout <sec>    Per long-poll hold (0-30, default 25)
+      --limit <n>        Max pings per batch (1-100, default 50)
+      --from <id>        Start after this ping id instead of "now"
+      --once             Print one batch and exit instead of blocking forever
+      --json             One JSON object per line instead of a readable line
+```
+
+The server holds each request open until something arrives, so this is a
+long-poll rather than a poll loop: an idle hour costs about 144 requests, not
+one per second. With no `--from` it starts from *now* — the first call takes the
+head cursor and returns nothing, so starting up never replays history. Transient
+failures (429, 5xx, network) back off geometrically and keep listening;
+`--once` is the form to use in a script.
+
 ```
 pingroom live <start|update|end|get> [options]
 
   -c, --correlation-id <id>  The stream key — reuse it for every ping (required)
       --template <name>      start only: status | steps | progress | metrics |
-                             countdown | question | matchup (fixed at creation)
+                             countdown | decision | matchup (fixed at creation;
+                             'decision' is the app's name for the wire id
+                             'question', which is still accepted)
       --steps <a,b,c>        start only: 2-8 comma-separated step labels
   -m, --message <text>       The card's live message line
       --progress <0..1>      Progress bar / Dynamic Island gauge
@@ -219,13 +263,14 @@ pingroom live <start|update|end|get> [options]
       --metric <label:value> Repeatable, up to 3 (metrics template)
       --deadline-at <epoch>  Countdown target (countdown template)
       --eta-at <epoch>       Live ETA (status/progress templates)
-      --prompt <text>        The ask (question template)
-      --option <value:label> Repeatable, up to 4 (question template)
+      --prompt <text>        The ask (decision template)
+      --option <value:label> Repeatable, up to 4 (decision template)
       --left <label:value>   Left side (matchup template)
       --right <label:value>  Right side (matchup template)
       --center <text>        Center score/clock, <= 40 (matchup template)
       --accent-override <#rrggbb>  Semantic accent for this frame
       --failed               end only: finish as failed instead of done
+  -d, --data <json>          Structured data object carried on this frame
   -t, --title <text>         Card title (<= 40 chars)
   -a, --action <1-4>         Quick-action slot supplying the icon and sound
       --require-ack          Add an Acknowledge button