pidge-cli 0.10.0 → 0.11.1

package/README.md

@@ -33,6 +33,19 @@ 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.1** (Pidge manifest v31): **`pidge doctor` now probes the realtime path** (#171) —
+> after the HTTP checks it opens a quick `/cable` subscription and reports `realtime: ok` or
+> `realtime: INDISPONÍVEL` (the #119 failure class an HTTP-only doctor couldn't see: an edge
+> killing held responses, a proxy refusing the WebSocket). Exit stays `0` — an unavailable WS
+> just degrades `listen` to polling — but you learn it BEFORE the first deaf listen. The doctor
+> hint now leads with `pidge hello`, and the version nudge knows v31 (#229).
+>
+> **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 +134,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. |
@@ -131,7 +145,7 @@ npx pidge-cli notify --title "Relatório" --file ./relatorio.xlsx
 | `contract set <k>=<v>` / `contract show` | **v0.9.0:** DECLARE how you operate (`keep_connection_alive`, `mirror_in_origin_session`, `listen_mode=turn_based\|persistent\|external_daemon`, `quiet_when_idle`). **Advisory, never policy** — you declare, the human registers their expectation and *sees* if you honor it; Pidge enforces nothing. An unknown key/bad value is rejected locally (exit 1). |
 | `selftest [--window N]` | **v0.10.0 (#205):** prove your listener works by ROUND-TRIP — fire a nonce, run the listener, confirm it picks it up + acks in time. PASS exit `0` / FAIL exit `2` with the likely cause (timeout / orphan / transport). Run it as the last onboarding step + whenever sends seem to go unheard. |
 | `setup --claim <code>` | One-shot onboarding (v0.7.0): exchange the single-use code for the key, store it in `~/.config/pidge/env` (600), run doctor. **v0.9.0** also claims channel ownership so `doctor` can warn on a silent key swap. **v0.9.1+** declares your `operating_contract` (default `listen_mode=turn_based`; `--listen-mode persistent\|external_daemon` for a supervisor/daemon). |
-| `doctor` | Validate the setup **without exposing secrets**: env source, server reachable, key valid, **honest device reach**, channel ownership. Exit 0/2. |
+| `doctor` | Validate the setup **without exposing secrets**: env source, server reachable, key valid, **honest device reach**, channel ownership, and (**v0.11.1, #171**) a **realtime probe** (`realtime: ok / INDISPONÍVEL` — exit stays 0; an unavailable WS just degrades `listen` to polling). Exit 0/2. |
 | `whoami` | Which channel does this key speak for (JSON). |
 | `skill install` | Write `.claude/skills/pidge/SKILL.md` generated from the live manifest — persistent Pidge knowledge for Claude Code agents; re-run to update. |
 | `--version` | Print the CLI version. |

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 = 31;
 let newsWarned = false;
 function checkManifestNews(res) {
   const v = parseInt(res.headers.get('x-pidge-manifest-version') || '0', 10);
@@ -377,10 +381,10 @@ function wantRealtime() {
 // The server pings every ~3 s — that heartbeat is the liveness check (silence
 // >15 s ⇒ the socket is dead even if TCP hasn't noticed; close → caller
 // reconnects). Returns {close()} or null if the constructor itself failed.
-function cableSubscribe({ channel, onUp, onFrame, onDown }) {
+function cableSubscribe({ channel, onUp, onFrame, onDown, base = BASE, token = TOKEN }) {
   let ws;
   try {
-    ws = new WebSocket(BASE.replace(/^http/, 'ws') + '/cable', ['actioncable-v1-json', TOKEN]);
+    ws = new WebSocket(base.replace(/^http/, 'ws') + '/cable', ['actioncable-v1-json', token]);
   } catch (e) { onDown(e.message); return null; }
   const identifier = JSON.stringify({ channel });
   let lastBeat = Date.now();
@@ -448,6 +452,41 @@ async function cableSession({ channel, deadline, onUp, onFrame }) {
   return 'deadline';
 }
 
+// #171: doctor's realtime probe — the failure class an HTTP-only doctor can't
+// see (#119: an edge killing held responses, a proxy refusing the upgrade). A
+// green HTTP doctor can coexist with a `listen` that's deaf over the socket.
+// Open ONE ConversationChannel subscription on /cable (reusing cableSubscribe —
+// the same client `listen` holds), wait for confirm_subscription, close — all
+// within ≤5 s. Degrade is the CONTRACT, not a failure: an unavailable WS just
+// means `listen` polls (works, less instant), so this NEVER changes the exit
+// code — it only lets the agent KNOW before the first deaf listen. Resolves
+// {ok, ms} | {ok:false, reason} | {skipped:true} (Node <22 has no native
+// WebSocket — same gate as wantRealtime, :373).
+function probeRealtime(base, token) {
+  if (typeof WebSocket !== 'function') return Promise.resolve({ skipped: true });
+  return new Promise((resolve) => {
+    const started = Date.now();
+    let settled = false;
+    let sub = null;
+    const done = (result) => {
+      if (settled) return; settled = true;
+      clearTimeout(guard);
+      if (sub) sub.close();
+      resolve(result);
+    };
+    const guard = setTimeout(() => done({ ok: false, reason: 'no confirm_subscription within 5s' }), 5000);
+    sub = cableSubscribe({
+      channel: 'ConversationChannel',
+      base,
+      token,
+      onUp: () => done({ ok: true, ms: Date.now() - started }),
+      onFrame: () => { /* a stray frame during the probe is irrelevant */ },
+      onDown: (why) => done({ ok: false, reason: why }),
+    });
+    if (!sub) done({ ok: false, reason: 'WebSocket constructor failed' });
+  });
+}
+
 // Map CLI flags → the /notify JSON body, including only what was provided.
 function buildBody() {
   if (!v.title) die('pidge: --title is required', 1);
@@ -1089,8 +1128,25 @@ async function runDoctor(base = BASE, token = TOKEN, sourceLabel = null) {
     console.error('pidge doctor: BROKEN (exit 2) — devices exist but 0 are reachable (all disabled or on the wrong APNs environment): a send reaches nobody.');
     process.exit(2);
   }
-  console.error('pidge doctor: all good — try: pidge ask --template decision --title "Pidge funcionando?"');
-  console.log(JSON.stringify({ ok: true, base_url: base, channel: data.channel, devices, manifest_version: data.manifest_version }));
+  // #171: probe the realtime path (the #119 failure class an HTTP-only doctor
+  // misses). Exit stays 0 either way — an unavailable WS degrades to polling.
+  const rt = await probeRealtime(base, token);
+  let realtime;
+  if (rt.skipped) {
+    realtime = 'skipped';
+    console.error('pidge doctor: realtime: skipped — this Node lacks a native WebSocket (need Node ≥22); `listen` will poll. Upgrade Node for instant delivery.');
+  } else if (rt.ok) {
+    realtime = 'ok';
+    console.error(`pidge doctor: realtime: ok (ws connect + subscribe em ${rt.ms}ms)`);
+  } else {
+    realtime = 'unavailable';
+    console.error(`pidge doctor: realtime: INDISPONÍVEL — ${rt.reason}. O \`listen\` degrada pra polling (funciona, menos instantâneo); use --no-realtime pra fixar o piso.`);
+  }
+  // #229: lead with `pidge hello` — the first-contact WOW (send + wait in one),
+  // the same debut the /agent-setup guide leads with. It's a thin wrapper over
+  // `ask --template onboarding` (the underlying mechanism, if you need it raw).
+  console.error('pidge doctor: all good — try: pidge hello   (first-contact WOW — send + wait in one; equivalent: pidge ask --template onboarding)');
+  console.log(JSON.stringify({ ok: true, base_url: base, channel: data.channel, devices, manifest_version: data.manifest_version, realtime }));
   process.exit(0);
 }
 
@@ -1273,6 +1329,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.1",
   "description": "Send rich, actionable iPhone notifications to a human and block until they answer. Built for AI agents.",
   "keywords": [
     "pidge",