pidge-cli 0.10.0 → 0.11.0

package/README.md

@@ -33,6 +33,12 @@ then gets the answer as JSON — no webhook, no polling loop to write.
 > stdout now carries only the `operating_contract`, so the key never lands in an agent's
 > transcript/logs.
 >
+> **v0.11.0** (Pidge manifest v30): the **first-contact WOW** (#217). New **`pidge hello`** —
+> your channel's debut handshake, narrated LIVE on the lock screen by a server-driven 3-stage
+> Live Activity (Conectando → toque para confirmar → Concluído ✓) so your human *sees* the
+> agent→human→agent loop close. Send + wait in one; run it as your first contact on a fresh
+> channel. (It's a thin `ask --template onboarding` wrapper — that path already works on v0.10.0.)
+>
 > **v0.10.0** (Pidge manifest v29): the onboarding-close batch. **`pidge selftest`** proves
 > your listener works by ROUND-TRIP (#205) — fire a nonce, run the listener, confirm it
 > picks it up + acks in time (PASS exit 0 / FAIL exit 2 with the likely cause). `listen_mode`
@@ -121,6 +127,7 @@ npx pidge-cli notify --title "Relatório" --file ./relatorio.xlsx
 
 | Command | What it does |
 |---|---|
+| `hello` | **v0.11.0 (#217):** your channel's **first-contact WOW** — send the onboarding handshake **and block** until the human confirms. The server narrates a 3-stage Live Activity on the lock screen (Conectando → toque para confirmar → Concluído ✓) so they *see* the agent→human→agent loop close. Run it as your **first** contact on a fresh channel. A thin `ask --template onboarding` wrapper with friendly default copy. |
 | `ask` | Send a notification **and block** until the human answers; prints the chosen action JSON. The default for agents. |
 | `notify` | Send only. Prints the raw 201 JSON; the `correlation_id` + warnings go to stderr. |
 | `wait <correlation_id>` | Block on an already-sent notification until it's answered. |

package/bin/pidge.js

@@ -157,6 +157,10 @@ USAGE
   pidge doctor                            validate the setup WITHOUT exposing secrets:
                                           env source, server, key, "canal X · N devices"
   pidge whoami                            which channel does this key speak for (JSON)
+  pidge hello  [options]                  FIRST-CONTACT WOW (#217): your channel's debut handshake,
+                                          narrated LIVE on the lock screen by a 3-stage Live Activity
+                                          (Conectando → toque para confirmar → Concluído ✓). send + wait
+                                          in one — run it as your FIRST contact on a fresh channel.
   pidge ask    [options]                  send AND wait for the answer (prints chosen_action JSON)
   pidge notify [options]                  send only (prints the 201 JSON)
   pidge wait   <correlation_id> [options] block on an already-sent notification
@@ -298,7 +302,7 @@ function fetchT(url, opts = {}, timeoutMs = 30000) {
 // The server advertises its manifest version on every response. When it's newer
 // than what this CLI shipped knowing, nudge ONCE on stderr — the agent re-reads
 // the manifest (whats_new) and learns the new capabilities without polling.
-const KNOWN_MANIFEST_VERSION = 28;
+const KNOWN_MANIFEST_VERSION = 30;
 let newsWarned = false;
 function checkManifestNews(res) {
   const v = parseInt(res.headers.get('x-pidge-manifest-version') || '0', 10);
@@ -1273,6 +1277,31 @@ ${notes.map((n) => `- ${n}`).join('\n')}
       process.exit(ok ? 0 : 2);
       break;
     }
+    case 'hello': {
+      // #217 — the first-contact WOW: fire the onboarding handshake and block on
+      // your human's confirmation. The SERVER narrates a 3-stage Live Activity on
+      // the lock screen (Conectando → toque para confirmar → Concluído ✓) so your
+      // human SEES the agent→human→agent loop close. One command: send + wait.
+      // Run it as your FIRST contact on a fresh channel. A thin wrapper over `ask`:
+      // it just pins template=onboarding and friendly default copy.
+      if (v.profile === 'tracking')
+        die('pidge: `hello --profile tracking` makes no sense — the handshake waits for a confirmation, which tracking (Live-Activity-only) never produces', 1);
+      v.template = 'onboarding';
+      if (v.title === undefined) v.title = 'Seu agente está pronto 🐦';
+      if (v.body === undefined) v.body = 'Toque em Feito ✓ para confirmar que me recebeu — você vai ver o teste fechar na tela.';
+      const cid = v['correlation-id'] || crypto.randomUUID();
+      v['correlation-id'] = cid;
+      console.error(`pidge: correlation_id=${cid}`);
+      const { ok, info } = await doNotify();
+      if (!ok) process.exit(2);
+      console.error(`pidge: WOW sent (${info.registered_devices} device(s)) — watch the lock screen narrate the handshake; waiting for your human to confirm on ${cid}`);
+      // No --timeout ⇒ obey the template's suggestion from the 201 echo (onboarding
+      // = 3600 s); explicit --timeout always wins.
+      let timeout = num(v.timeout, NaN);
+      if (!Number.isFinite(timeout)) timeout = info.suggested_ask_timeout || 3600;
+      await waitForAnswer(cid, { timeout, interval: num(v.interval, 30) });
+      break;
+    }
     case 'ask': {
       // Send, then block on the answer in one shot. stdout = ONLY chosen_action JSON.
       // tracking is Live-Activity-only: it NEVER produces a chosen_action, so an ask

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pidge-cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Send rich, actionable iPhone notifications to a human and block until they answer. Built for AI agents.",
   "keywords": [
     "pidge",