@pingroom/cli 0.7.2 → 0.7.4

package/lib/commands/handoff.js

@@ -0,0 +1,149 @@
+// `handoff` and `handoffs` — hand a decision to a specific human (ack or
+// question) and, with --wait, block until they answer.
+
+import { EXIT } from '../constants.js';
+import { fail, parseDataObject, requireMaxLength, resolveWaitHold, sleep } from '../util.js';
+import { commandHelp } from '../help.js';
+import { apiDetail, httpJson } from '../http.js';
+import { agentContext } from '../config.js';
+import { buildOptions, exitForHandoffState, HANDOFF_PENDING, printHandoff } from '../render.js';
+import { writeGitHubHandoffOutputs } from '../github-output.js';
+
+export async function listHandoffs(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('handoffs')}\n`); return EXIT.OK; }
+  const { token, apiBase } = agentContext(args);
+  const state = args.state || 'open';
+  if (state !== 'open' && state !== 'all') {
+    fail("--state must be 'open' or 'all' for handoffs", EXIT.USAGE);
+  }
+
+  const url = `${apiBase}/api/agent/handoffs?state=${encodeURIComponent(state)}`;
+  const { res, text, json } = await httpJson('GET', url, { headers: { Authorization: `Bearer ${token}` } });
+  if (!res.ok) {
+    const detail = apiDetail(res, json);
+    fail(`handoffs list failed: ${detail}`);
+  }
+  if (args.json) { process.stdout.write(`${text}\n`); return EXIT.OK; }
+
+  const handoffs = (json && json.handoffs) || [];
+  if (handoffs.length === 0) { process.stdout.write('no handoffs\n'); return EXIT.OK; }
+  for (const h of handoffs) {
+    const answer = h.answer && (h.answer.value ?? h.answer.text);
+    const outcome = answer !== undefined && answer !== null ? ` → ${answer}` : '';
+    process.stdout.write(
+      `${h.id}  ${String(h.kind || '').padEnd(8)}  ${String(h.state || '').padEnd(9)}  ${h.prompt || ''}${outcome}\n`,
+    );
+  }
+  return EXIT.OK;
+}
+
+// Long-poll GET /handoffs/{id}/wait until the handoff leaves open/pending, then
+// print it and return the state's exit code. Reuses the shared bounded hold.
+async function waitForHandoff(id, args, { token, apiBase }, initialDeliveryState) {
+  const hold = resolveWaitHold(args, { def: 20, cap: 25 });
+
+  for (;;) {
+    const started = Date.now();
+    const url = `${apiBase}/api/agent/handoffs/${encodeURIComponent(id)}/wait?timeout=${hold}`;
+    const { res, text, json } = await httpJson('GET', url, { headers: { Authorization: `Bearer ${token}` } });
+    if (!res.ok) {
+      const detail = apiDetail(res, json);
+      fail(`wait failed: ${detail}`);
+    }
+    if (json && json.state && !HANDOFF_PENDING.has(json.state)) {
+      // Read/wait responses intentionally carry delivery_state=null. Preserve
+      // the create response's durable delivery result so --wait callers and
+      // the GitHub Action do not lose it at the terminal read boundary.
+      const resolved = json.delivery_state == null && initialDeliveryState != null
+        ? { ...json, delivery_state: initialDeliveryState }
+        : json;
+      if (args.github_output !== undefined) writeGitHubHandoffOutputs(args.github_output, resolved);
+      if (args.json) process.stdout.write(`${text}\n`);
+      else printHandoff(resolved);
+      return exitForHandoffState(resolved.state);
+    }
+    // Still open/pending at the hold timeout — poll again, with the same
+    // hot-loop floor as waitForResolution.
+    const elapsed = Date.now() - started;
+    if (elapsed < 1000) await sleep(1000 - elapsed);
+  }
+}
+
+export async function handoff(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('handoff')}\n`); return EXIT.OK; }
+
+  const message = args.message;
+  if (!message) fail('a --message is required', EXIT.USAGE);
+  requireMaxLength(message, 500, '--message');
+
+  const { token, apiBase } = agentContext(args);
+
+  const options = buildOptions(args.option);
+  // Any --option (or an explicit --question) makes this a question handoff.
+  const isQuestion = Boolean(args.question) || Boolean(options);
+  if (isQuestion && (!options || options.length < 2)) {
+    fail('a question handoff needs at least 2 --option values', EXIT.USAGE);
+  }
+  if (isQuestion && options && options.length > 4) {
+    fail('a question handoff accepts at most 4 --option values', EXIT.USAGE);
+  }
+  if (!isQuestion && options) {
+    fail('--option requires --question', EXIT.USAGE);
+  }
+
+  const body = { kind: isQuestion ? 'question' : 'ack', prompt: message };
+
+  const target = args.target || 'me';
+  body.audience = { type: 'direct', user_id: target };
+
+  if (options) body.options = options;
+
+  if (args.expires_in !== undefined) {
+    if (!/^\d+$/.test(String(args.expires_in))) fail('--expires-in must be an integer number of seconds', EXIT.USAGE);
+    const secs = Number(args.expires_in);
+    if (secs < 120 || secs > 86_400) fail('--expires-in must be between 120 and 86400 seconds', EXIT.USAGE);
+    body.expires_in = secs;
+  }
+  if (args.urgency !== undefined) {
+    if (args.urgency !== 'active' && args.urgency !== 'passive') fail("--urgency must be 'active' or 'passive'", EXIT.USAGE);
+    body.urgency = args.urgency;
+  }
+  if (args.correlation_id !== undefined) body.correlation_id = args.correlation_id;
+  if (args.reply_to !== undefined) body.reply_to = args.reply_to;
+  if (args.data !== undefined) body.data = parseDataObject(args.data);
+
+  const headers = { Authorization: `Bearer ${token}` };
+  // A stable Idempotency-Key lets network retries collapse to one resource; the
+  // server returns the same handoff for a matching key+hash (409 on conflict).
+  if (args.idempotency_key !== undefined) {
+    if (!args.idempotency_key) fail('--idempotency-key must be non-empty', EXIT.USAGE);
+    headers['Idempotency-Key'] = args.idempotency_key;
+  }
+
+  // Pre-flight: reject a bad --timeout before the handoff exists.
+  if (args.wait) resolveWaitHold(args, { def: 20, cap: 25 });
+
+  const url = `${apiBase}/api/agent/handoffs`;
+  const { res, text, json } = await httpJson('POST', url, { body, headers });
+  if (!res.ok) {
+    const code = json && json.code;
+    const detail = apiDetail(res, json);
+    // A recipient who isn't reachable yet is a distinct, retriable outcome (4),
+    // not a generic error — CI may want to wait and retry rather than fail hard.
+    if (res.status === 409 && code === 'recipient_not_ready') {
+      if (args.json) process.stdout.write(`${text}\n`);
+      else process.stderr.write(`pingroom: recipient not ready\n`);
+      return EXIT.CANCELLED;
+    }
+    fail(`handoff failed: ${detail}`);
+  }
+
+  if (!args.wait) {
+    if (args.github_output !== undefined) writeGitHubHandoffOutputs(args.github_output, json);
+    if (args.json) process.stdout.write(`${text}\n`);
+    else printHandoff(json);
+    return EXIT.OK;
+  }
+
+  return waitForHandoff(json.id, args, { token, apiBase }, json.delivery_state);
+}

package/lib/commands/hook.js

@@ -0,0 +1,301 @@
+import { readFileSync } from 'node:fs';
+
+import { EXIT, PUBLIC_PING_MESSAGE_MAX_LENGTH } from '../constants.js';
+import { truncate } from '../util.js';
+import { commandHelp } from '../help.js';
+import { hookFetch, isSafeUrl } from '../http.js';
+import { resolveApiBase, resolveRoom, resolveToken, storedCredentialOriginError } from '../config.js';
+import { VERSION } from '../version.js';
+
+// --- hook (Claude Code integration) ----------------------------------------
+//
+// A single command wired into several Claude Code hook events. It reads the
+// hook's JSON payload on stdin and switches on `hook_event_name`:
+//   Stop / SubagentStop / SessionEnd  -> ping the room ("Claude finished")
+//   Notification                      -> ping the room (idle / needs-input)
+//   PreToolUse                        -> ask a PingRoom question and gate the
+//                                        tool call on the phone's Approve/Deny.
+//
+// Safety: the hook FAILS OPEN. It never blocks the agent and never
+// auto-approves. Any missing config / network error / non-answer defers to the
+// normal local prompt (PreToolUse -> permissionDecision "ask") and exits 0. It
+// must not call fail() (a non-zero exit — 2 especially — would break the run).
+
+// Read all of stdin as a string. Resolves '' when nothing is piped (TTY), so a
+// stray `pingroom hook` in a terminal is a silent no-op rather than a hang.
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) { resolve(''); return; }
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(data));
+  });
+}
+
+// Pull the readable text out of a Claude transcript message's content, which is
+// either a plain string or an array of typed blocks.
+function extractAssistantText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+      .map((b) => b.text)
+      .join(' ');
+  }
+  return '';
+}
+
+// Tail a Claude Code transcript (JSONL) and return the last assistant message as
+// a single truncated line. Best-effort: any read/parse failure yields ''.
+function summarizeTranscript(path) {
+  if (!path || typeof path !== 'string') return '';
+  let content;
+  try { content = readFileSync(path, 'utf8'); } catch { return ''; }
+  const lines = content.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    const msg = entry && entry.message;
+    if (!msg || msg.role !== 'assistant') continue;
+    const text = extractAssistantText(msg.content).replace(/\s+/g, ' ').trim();
+    if (text) return truncate(text, PUBLIC_PING_MESSAGE_MAX_LENGTH);
+  }
+  return '';
+}
+
+// A short, single-line description of the tool call for the question prompt.
+// Never emits more than a truncated line, and strips whitespace/newlines so an
+// untrusted command can't reshape the message.
+function summarizeToolInput(input) {
+  if (!input || typeof input !== 'object') return '';
+  let raw = '';
+  if (typeof input.command === 'string') raw = input.command;          // Bash
+  else if (typeof input.file_path === 'string') raw = input.file_path; // Read/Write/Edit
+  else if (typeof input.path === 'string') raw = input.path;
+  else if (typeof input.url === 'string') raw = input.url;             // WebFetch
+  else if (typeof input.pattern === 'string') raw = input.pattern;     // Grep/Glob
+  else { try { raw = JSON.stringify(input); } catch { raw = ''; } }
+  return truncate(String(raw).replace(/\s+/g, ' ').trim(), 160);
+}
+
+function emitPreToolUseDecision(decision, reason) {
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: decision,
+      permissionDecisionReason: reason,
+    },
+  })}\n`);
+}
+
+// Long-poll the wait endpoint until the question leaves `pending`. The server
+// expires it at its ttl, so this always terminates; a mid-poll throw propagates
+// to the caller's fail-open handler.
+async function hookWaitForAnswer(id, { token, apiBase }) {
+  for (;;) {
+    const url = `${apiBase}/api/agent/questions/${encodeURIComponent(id)}/wait?timeout=25`;
+    const json = await hookFetch('GET', url, { token });
+    if (json && json.state && json.state !== 'pending') return json;
+  }
+}
+
+async function hookPreToolUse(event, { token, room, apiBase, args }) {
+  if (!token || !room) {
+    emitPreToolUseDecision('ask', 'PingRoom not configured (pair by QR, or configure both a token and room)');
+    return EXIT.OK;
+  }
+
+  const toolName = event.tool_name || 'a tool';
+  const summary = summarizeToolInput(event.tool_input);
+  const prompt = truncate(`Run ${toolName}${summary ? `: ${summary}` : ''}?`, 500);
+
+  let ttl = 900;
+  if (args.ttl !== undefined && /^\d+$/.test(String(args.ttl))) ttl = Number(args.ttl);
+
+  let questionId;
+  let cancelled = false;
+  const cancelQuestion = async () => {
+    if (!questionId || cancelled) return;
+    cancelled = true;
+    try {
+      await hookFetch('POST', `${apiBase}/api/agent/questions/${encodeURIComponent(questionId)}/cancel`, { body: {}, token });
+    } catch { /* best-effort — a leftover question expires on its own ttl */ }
+  };
+  // If the agent aborts the tool call, withdraw the question so it doesn't linger
+  // on the phone. Exit 0 so the abort itself isn't reported as a hook failure.
+  const onSignal = () => { cancelQuestion().finally(() => process.exit(EXIT.OK)); };
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+
+  try {
+    const data = { tool_name: String(toolName) };
+    if (event.cwd) data.cwd = String(event.cwd);
+    const created = await hookFetch('POST', `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/questions`, {
+      token,
+      body: {
+        prompt,
+        context: 'Claude Code',
+        options: [
+          { value: 'allow', label: 'Approve', style: 'primary' },
+          { value: 'deny', label: 'Deny', style: 'danger' },
+        ],
+        ttl,
+        data,
+        ...(event.session_id ? { correlation_id: String(event.session_id) } : {}),
+      },
+    });
+    questionId = created && created.id;
+    if (!questionId) {
+      emitPreToolUseDecision('ask', 'PingRoom did not return a question — deferring to local prompt');
+      return EXIT.OK;
+    }
+
+    const resolved = await hookWaitForAnswer(questionId, { token, apiBase });
+    if (resolved.state === 'answered') {
+      const value = resolved.answer && (resolved.answer.value || resolved.answer.text);
+      if (value === 'allow') { emitPreToolUseDecision('allow', 'Approved via PingRoom'); return EXIT.OK; }
+      if (value === 'deny') { emitPreToolUseDecision('deny', 'Denied via PingRoom'); return EXIT.OK; }
+      emitPreToolUseDecision('ask', `PingRoom answer "${value}" — deferring to local prompt`);
+      return EXIT.OK;
+    }
+    emitPreToolUseDecision('ask', `PingRoom question ${resolved.state} — deferring to local prompt`);
+    return EXIT.OK;
+  } catch (err) {
+    emitPreToolUseDecision('ask', `PingRoom unavailable (${err.message}) — deferring to local prompt`);
+    return EXIT.OK;
+  } finally {
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+  }
+}
+
+async function hookNotify(event, name, { token, room, apiBase, args }) {
+  if (!token || !room) {
+    if (!args.quiet) process.stderr.write('pingroom: hook skipped (pair by QR, or configure both a token and room)\n');
+    return EXIT.OK;
+  }
+
+  let title;
+  let message;
+  if (name === 'Stop' || name === 'SubagentStop') {
+    title = 'Claude finished';
+    message = summarizeTranscript(event.transcript_path) || 'Session finished — waiting for you.';
+  } else if (name === 'Notification') {
+    message = truncate(event.message || 'Claude is waiting for your input.', PUBLIC_PING_MESSAGE_MAX_LENGTH);
+    // A PreToolUse hook already turns permission prompts into a question; skip
+    // the duplicate "needs your permission" Notification so you aren't paged twice.
+    if (/permission/i.test(message)) return EXIT.OK;
+    title = 'Claude needs you';
+  } else if (name === 'SessionEnd') {
+    if (event.reason === 'clear') return EXIT.OK; // /clear isn't worth a ping
+    title = 'Session ended';
+    message = `Claude Code session ended (${event.reason || 'unknown'}).`;
+  } else {
+    return EXIT.OK; // unknown event — stay silent rather than send noise
+  }
+
+  const data = { event: name };
+  if (event.session_id) data.session_id = String(event.session_id);
+  if (event.cwd) data.cwd = String(event.cwd);
+
+  try {
+    await hookFetch('POST', `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/notifications`, {
+      token,
+      body: {
+        message,
+        title,
+        data,
+        ...(event.session_id ? { correlation_id: String(event.session_id) } : {}),
+      },
+    });
+    if (!args.quiet) process.stderr.write('pingroom: pinged ✅\n');
+  } catch (err) {
+    // A broken ping must never break the agent — report to stderr and exit 0.
+    if (!args.quiet) process.stderr.write(`pingroom: hook ping failed (${err.message})\n`);
+  }
+  return EXIT.OK;
+}
+
+function printHookConfig() {
+  const command = `npx --yes @pingroom/cli@${VERSION} hook`;
+  const config = {
+    hooks: {
+      Stop: [{ hooks: [{ type: 'command', command }] }],
+      Notification: [{ hooks: [{ type: 'command', command }] }],
+      PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command, timeout: 960 }] }],
+    },
+  };
+  process.stdout.write(
+`# PingRoom × Claude Code — merge this into ~/.claude/settings.json
+#
+# 1. Connect once and choose a delivery room when you scan the QR:
+#      npm install --global @pingroom/cli && pingroom
+#    Or, without a global install:
+#      npx --yes @pingroom/cli@${VERSION}
+#    The hook reads that stored credential and paired room automatically; you do
+#    not need to export PINGROOM_TOKEN or PINGROOM_ROOM for a local setup.
+#
+# 2. Merge the "hooks" block below into ~/.claude/settings.json.
+#      Stop / Notification  -> ping your phone.
+#      PreToolUse (Bash)     -> ask a question you Approve/Deny from the lock
+#                               screen before the command runs. Add or change the
+#                               matcher to gate other tools.
+#
+# If PingRoom is unreachable the hook defers to the normal local prompt — it
+# never auto-approves and never blocks the agent.
+# PINGROOM_TOKEN / PINGROOM_ROOM remain supported for CI and headless shells.
+
+${JSON.stringify(config, null, 2)}
+`);
+}
+
+export async function hook(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('hook')}\n`); return EXIT.OK; }
+  if (args.print_config) { printHookConfig(); return EXIT.OK; }
+
+  let event = {};
+  const raw = await readStdin();
+  if (raw) { try { event = JSON.parse(raw); } catch { event = {}; } }
+  const name = event.hook_event_name || '';
+
+  // The hook fails open, so it reads the same layered config as everything else
+  // but never complains about a missing piece — it just defers.
+  const token = resolveToken(args);
+  const room = resolveRoom(args);
+  const apiBase = resolveApiBase(args);
+
+  const originError = storedCredentialOriginError(args, apiBase);
+  if (originError) {
+    if (name === 'PreToolUse') {
+      emitPreToolUseDecision('ask', `${originError}; deferring to local prompt`);
+    } else if (!args.quiet) {
+      process.stderr.write(`pingroom: hook skipped (${originError})\n`);
+    }
+    return EXIT.OK;
+  }
+
+  // Every other command that attaches a bearer gates its base through
+  // requireSafeUrl first; the hook was the one that didn't, so a config or env
+  // pointing at plain http shipped `Authorization: Bearer …` in the clear with
+  // nothing on screen. Same rule here — but enforced by deferring, not by
+  // exiting: the hook's whole contract is that it never blocks the agent, so a
+  // hard failure would trade a credential leak for a broken session.
+  if (!isSafeUrl(apiBase)) {
+    const why = `${apiBase} is not https — refusing to send credentials over cleartext`;
+    if (name === 'PreToolUse') {
+      emitPreToolUseDecision('ask', `PingRoom API base ${why}; deferring to local prompt`);
+    } else if (!args.quiet) {
+      process.stderr.write(`pingroom: hook skipped (API base ${why})\n`);
+    }
+    return EXIT.OK;
+  }
+
+  if (name === 'PreToolUse') {
+    return hookPreToolUse(event, { token, room, apiBase, args });
+  }
+  return hookNotify(event, name, { token, room, apiBase, args });
+}

package/lib/commands/listen.js

@@ -0,0 +1,83 @@
+import { EXIT } from '../constants.js';
+import { fail, numberOption, sleep } from '../util.js';
+import { commandHelp } from '../help.js';
+import { apiDetail, httpJson, retryAfterMs } from '../http.js';
+import { agentContext } from '../config.js';
+import { formatIncoming } from '../render.js';
+
+// --- listen ----------------------------------------------------------------
+//
+// The inbound half. Everything else here talks; this 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.
+//
+// The server holds each request open until something arrives or the timeout
+// elapses, so this is a long-poll, not a poll loop: an idle hour costs ~144
+// requests, not one per second.
+
+/** Cursor bookkeeping is the whole protocol: `after` in, `cursor` back. */
+export async function listen(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('listen')}\n`); return EXIT.OK; }
+
+  const { token, apiBase } = agentContext(args);
+  const headers = { Authorization: `Bearer ${token}` };
+
+  const timeout = numberOption(args.timeout, '--timeout', { min: 0, max: 30, integer: true }) ?? 25;
+  const limit = numberOption(args.limit, '--limit', { min: 1, max: 100, integer: true }) ?? 50;
+
+  // No cursor means "from now": the server answers an empty `after` with the
+  // head id and no rows, so starting up never replays history the agent has
+  // already seen. `--from` opts into catching up from a known id instead.
+  let cursor = args.from;
+  if (!cursor) {
+    const { res, json } = await httpJson('GET', `${apiBase}/api/agent/notifications/wait`, {
+      headers,
+      soft: true,
+    });
+    if (!res?.ok) fail(`listen failed: ${apiDetail(res, json)}`);
+    cursor = json && json.cursor;
+    if (!cursor) {
+      // A brand-new account with no pings at all has no head id. Nothing is
+      // wrong; there is simply nothing to be after yet.
+      cursor = '';
+    }
+  }
+
+  let transientRun = 0;
+
+  for (;;) {
+    const query = new URLSearchParams({ timeout: String(timeout), limit: String(limit) });
+    if (cursor) query.set('after', cursor);
+
+    const { res, json, error } = await httpJson(
+      'GET',
+      `${apiBase}/api/agent/notifications/wait?${query}`,
+      // The hold plus headroom: aborting at exactly the server's deadline would
+      // race it and turn every quiet window into a client-side error.
+      { headers, soft: true, signal: AbortSignal.timeout((timeout + 10) * 1000) },
+    );
+
+    if (error || res.status === 429 || res.status >= 500) {
+      transientRun += 1;
+      const retryAfter = res?.status === 429 ? retryAfterMs(res) : null;
+      // Geometric backoff so a real outage is not also a thundering herd. The
+      // loop is unbounded by design — `listen` is a daemon, not a request.
+      const backoff = Math.min(1000 * 2 ** Math.max(0, transientRun - 1), 30_000);
+      await sleep(Math.max(0, retryAfter ?? backoff));
+      continue;
+    }
+
+    if (!res.ok) fail(`listen failed: ${apiDetail(res, json)}`);
+    transientRun = 0;
+
+    const batch = Array.isArray(json?.notifications) ? json.notifications : [];
+    for (const item of batch) {
+      process.stdout.write(args.json ? `${JSON.stringify(item)}\n` : `${formatIncoming(item)}\n`);
+    }
+    // Advance only on a cursor the server actually returned, or a batch could be
+    // replayed forever against a stale `after`.
+    if (json && typeof json.cursor === 'string' && json.cursor) cursor = json.cursor;
+
+    if (args.once) return EXIT.OK;
+  }
+}