@pingroom/cli 0.7.5 → 0.7.6

package/README.md

@@ -243,6 +243,36 @@ 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.
 
+## Managing rooms, webhooks, and quick actions
+
+The management nouns cover the rest of the agent surface (agent token required;
+`--room` where noted):
+
+```bash
+pingroom rooms list                       # rooms this account belongs to
+pingroom rooms get GZNFB6BZGJIH
+pingroom rooms create -n "Deploys" --icon bell --color "#e33122"
+pingroom rooms create -n "Status" --icon globe --color "#0391fe" --public --handle status
+pingroom rooms join GZNFB6BZGJIH
+
+pingroom webhooks list --room GZNFB6BZGJIH
+pingroom webhooks create --room GZNFB6BZGJIH --name "CI" --action 2   # prints the secret URL once
+pingroom webhooks update <id> --room GZNFB6BZGJIH --enabled false
+pingroom webhooks delete <id> --room GZNFB6BZGJIH
+
+pingroom actions list --room GZNFB6BZGJIH
+pingroom actions set 3 --room GZNFB6BZGJIH --label "Deploy done" --icon 🚀
+pingroom actions trigger 3 --room GZNFB6BZGJIH
+
+pingroom approval -p "Ship v2 to production?" --wait   # exit 0 approved · 4 denied · 3 expired
+
+pingroom attachment get <id> --out report.md
+pingroom attachment delete <id>
+```
+
+Creating webhooks and uploading attachments require a Pro account; public-room
+creation runs under its own consent scope (`pingroom:rooms:publish`).
+
 ## Hearing replies
 
 Everything else here talks; `listen` is how an agent hears — replies to its own
@@ -506,6 +536,9 @@ Options are `value:label` pairs (repeat `-o` for 2–4). Omit them for the binar
 Approve/Deny default — two options is the lock-screen fast path. `--ttl` sets the
 expiry in seconds (default 1h; 30–86400). `--scope room` lets any eligible member
 answer (first tap wins); the default `direct` asks your bound user.
+`--idempotency-key <key>` sends a printable 1–255 character `Idempotency-Key`
+header. Retrying the same key with the same request returns the original
+Question; reusing it with a changed request returns `409 idempotency_conflict`.
 
 ## Handoffs (agent → human)
 
@@ -590,18 +623,20 @@ tune the approval-question expiry with `--ttl <seconds>` (default 900).
 
 ## MCP client setup
 
-Print the canonical remote endpoint, a copy-ready Claude Code command, Cursor
-JSON, and the Claude Desktop custom-connector steps:
+Print the canonical remote endpoint, copy-ready Codex and Claude Code commands,
+Cursor JSON, Claude custom-connector steps, and the public OpenAI directory:
 
 ```bash
 pingroom mcp
 # no global install: npx --yes @pingroom/cli mcp
 ```
 
-`pingroom mcp add claude-code` prints the exact `claude mcp add` command but does
-not execute it or modify client configuration. After adding the server, use the
-client's MCP controls to authenticate in the browser; no PingRoom API key is
-pasted into its config.
+`pingroom mcp add codex` and `pingroom mcp add claude-code` print the exact setup
+commands but do not execute them or modify client configuration. After adding
+the server, use the client's MCP controls to authenticate in the browser; no
+PingRoom API key is pasted into its config. Once PingRoom's public listing is
+approved, the same plugin will also be discoverable in the Plugins Directory
+shared by ChatGPT and Codex.
 
 For a fully typed client, use [`@pingroom/sdk`](https://www.npmjs.com/package/@pingroom/sdk).
 See <https://pingroom.io/connect-mcp.md> for the complete MCP and OAuth guide.

package/bin/pingroom.js

@@ -41,8 +41,9 @@ import { VERSION } from '../lib/version.js';
 import { HELP } from '../lib/help.js';
 import {
   parseArgs, parseConfigArgs, parseHandoffArgs, parseHandoffsArgs, parseHookArgs,
-  parseLiveArgs, parseLogoutArgs, parseQArgs,
+  parseLiveArgs, parseLogoutArgs, parseManageArgs, parseQArgs,
 } from '../lib/parser.js';
+import { actions, approval, attachment, rooms, webhooks } from '../lib/commands/manage.js';
 import { ping } from '../lib/commands/ping.js';
 import { ask, cancel, list, watch } from '../lib/commands/ask.js';
 import { handoff, listHandoffs } from '../lib/commands/handoff.js';
@@ -67,6 +68,11 @@ const COMMANDS = {
   mcp,
   activate: (rest) => activateStoredInbox(parseQArgs(rest)),
   live: (rest) => live(parseLiveArgs(rest)),
+  rooms: (rest) => rooms(parseManageArgs(rest)),
+  webhooks: (rest) => webhooks(parseManageArgs(rest)),
+  actions: (rest) => actions(parseManageArgs(rest)),
+  approval: (rest) => approval(parseManageArgs(rest)),
+  attachment: (rest) => attachment(parseManageArgs(rest)),
   config: (rest) => config(parseConfigArgs(rest)),
   logout: (rest) => logout(parseLogoutArgs(rest)),
 };

package/lib/commands/ask.js

@@ -76,11 +76,24 @@ export async function ask(args) {
   }
   if (args.data !== undefined) body.data = parseDataObject(args.data);
 
+  const headers = { Authorization: `Bearer ${token}` };
+  // Question creation is the durable human gate for workflows. A printable,
+  // bounded key lets a caller safely replay the exact same create request
+  // after an ambiguous transport failure; the server returns 409 if the key is
+  // ever reused for a different payload.
+  if (args.idempotency_key !== undefined) {
+    const key = String(args.idempotency_key);
+    if (!/^[\x21-\x7E]{1,255}$/.test(key)) {
+      fail('--idempotency-key must be 1–255 printable ASCII characters without spaces', EXIT.USAGE);
+    }
+    headers['Idempotency-Key'] = key;
+  }
+
   // Pre-flight: reject a bad --timeout before the question exists.
   if (args.wait) resolveWaitHold(args, { def: 25, cap: 30 });
 
   const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/questions`;
-  const { res, text, json } = await httpJson('POST', url, { body, headers: { Authorization: `Bearer ${token}` } });
+  const { res, text, json } = await httpJson('POST', url, { body, headers });
   if (!res.ok) {
     const detail = apiDetail(res, json);
     fail(`ask failed: ${detail}`);

package/lib/commands/manage.js

@@ -0,0 +1,260 @@
+// Room, webhook, quick-action, approval, and attachment management — the
+// agent REST surface that previously had no CLI verbs. One module, one
+// sub-command dispatch per noun, JSON-first output (--json prints the raw
+// response; the default prints a compact human line per record).
+
+import { EXIT } from '../constants.js';
+import { fail } from '../util.js';
+import { commandHelp } from '../help.js';
+import { apiDetail, httpJson } from '../http.js';
+import { agentContext } from '../config.js';
+
+function sub(args, allowed, noun) {
+  const name = args._[0];
+  if (!name || !allowed.includes(name)) {
+    fail(`usage: pingroom ${noun} <${allowed.join('|')}>\nRun "pingroom ${noun} --help".`, EXIT.USAGE);
+  }
+  return name;
+}
+
+function auth(token) {
+  return { Authorization: `Bearer ${token}` };
+}
+
+async function requireOk(promise, what) {
+  const { res, text, json } = await promise;
+  if (!res.ok) fail(`${what} failed: ${apiDetail(res, json)}`);
+  return { text, json };
+}
+
+function printJsonOr(args, text, lines) {
+  if (args.json) process.stdout.write(`${text}\n`);
+  else process.stdout.write(`${lines}\n`);
+}
+
+// ---------------------------------------------------------------- rooms
+
+export async function rooms(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('rooms')}\n`); return EXIT.OK; }
+  const action = sub(args, ['list', 'get', 'create', 'join'], 'rooms');
+  const { token, apiBase } = agentContext(args);
+
+  if (action === 'list') {
+    const { text, json } = await requireOk(
+      httpJson('GET', `${apiBase}/api/agent/rooms`, { headers: auth(token) }),
+      'rooms list',
+    );
+    const items = Array.isArray(json) ? json : (json.rooms ?? json.data ?? []);
+    printJsonOr(args, text, items.map((r) => `${r.invite_code}  ${r.name}${r.is_public ? '  (public)' : ''}`).join('\n') || '(no rooms)');
+    return EXIT.OK;
+  }
+
+  if (action === 'get') {
+    const code = args._[1];
+    if (!code) fail('usage: pingroom rooms get <invite-code>', EXIT.USAGE);
+    const { text } = await requireOk(
+      httpJson('GET', `${apiBase}/api/agent/rooms/${encodeURIComponent(code)}`, { headers: auth(token) }),
+      'rooms get',
+    );
+    process.stdout.write(`${text}\n`);
+    return EXIT.OK;
+  }
+
+  if (action === 'join') {
+    const code = args._[1];
+    if (!code) fail('usage: pingroom rooms join <invite-code>', EXIT.USAGE);
+    const { text, json } = await requireOk(
+      httpJson('POST', `${apiBase}/api/agent/rooms/join`, { headers: auth(token), body: { invite_code: code } }),
+      'rooms join',
+    );
+    printJsonOr(args, text, `joined ${json.room?.name ?? code}`);
+    return EXIT.OK;
+  }
+
+  // create — private by default; --public requires --handle and uses the
+  // dedicated consent scope on the server.
+  if (!args.name) fail('rooms create needs --name', EXIT.USAGE);
+  if (!args.icon || !args.color) fail('rooms create needs --icon and --color (see "pingroom rooms list-icons" via the app, e.g. --icon bell --color "#e33122")', EXIT.USAGE);
+
+  const body = { name: args.name, icon: args.icon, color: args.color };
+  if (args.description) body.description = args.description;
+
+  let url = `${apiBase}/api/agent/rooms`;
+  if (args.public) {
+    if (!args.handle) fail('a public room needs --handle', EXIT.USAGE);
+    body.handle = args.handle;
+    url = `${apiBase}/api/agent/rooms/public`;
+  }
+
+  const { text, json } = await requireOk(httpJson('POST', url, { headers: auth(token), body }), 'rooms create');
+  printJsonOr(args, text, `created ${json.room?.invite_code ?? json.invite_code ?? ''} ${args.name}`.trim());
+  return EXIT.OK;
+}
+
+// ------------------------------------------------------------- webhooks
+
+export async function webhooks(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('webhooks')}\n`); return EXIT.OK; }
+  const action = sub(args, ['list', 'create', 'update', 'delete'], 'webhooks');
+  const { token, apiBase, room } = agentContext(args, { needRoom: true });
+  const base = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/webhooks`;
+
+  if (action === 'list') {
+    const { text, json } = await requireOk(httpJson('GET', base, { headers: auth(token) }), 'webhooks list');
+    const items = Array.isArray(json) ? json : (json.webhooks ?? json.data ?? []);
+    printJsonOr(args, text, items.map((w) => `${w.id}  ${w.name}${w.enabled === false ? '  (disabled)' : ''}`).join('\n') || '(no webhooks)');
+    return EXIT.OK;
+  }
+
+  if (action === 'delete') {
+    const id = args._[1];
+    if (!id) fail('usage: pingroom webhooks delete <id> --room <code>', EXIT.USAGE);
+    await requireOk(httpJson('DELETE', `${base}/${encodeURIComponent(id)}`, { headers: auth(token) }), 'webhooks delete');
+    process.stdout.write('deleted\n');
+    return EXIT.OK;
+  }
+
+  const body = {};
+  for (const key of ['name', 'title', 'message', 'icon', 'color', 'sound']) {
+    if (args[key] !== undefined) body[key] = args[key];
+  }
+  if (args.action !== undefined) body.action_number = Number(args.action);
+  if (args.cooldown !== undefined) body.cooldown_seconds = Number(args.cooldown);
+  if (args.enabled !== undefined) body.enabled = args.enabled !== 'false';
+
+  if (action === 'create') {
+    if (!body.name) fail('webhooks create needs --name', EXIT.USAGE);
+    const { text, json } = await requireOk(httpJson('POST', base, { headers: auth(token), body }), 'webhooks create');
+    // The trigger URL carries the webhook secret — print it once, like the app.
+    printJsonOr(args, text, `created ${json.webhook?.id ?? ''}\n${json.webhook?.url ?? json.url ?? ''}`.trim());
+    return EXIT.OK;
+  }
+
+  const id = args._[1];
+  if (!id) fail('usage: pingroom webhooks update <id> --room <code> [fields]', EXIT.USAGE);
+  const { text } = await requireOk(
+    httpJson('PUT', `${base}/${encodeURIComponent(id)}`, { headers: auth(token), body }),
+    'webhooks update',
+  );
+  process.stdout.write(`${text}\n`);
+  return EXIT.OK;
+}
+
+// -------------------------------------------------------------- actions
+
+export async function actions(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('actions')}\n`); return EXIT.OK; }
+  const action = sub(args, ['list', 'set', 'trigger'], 'actions');
+  const { token, apiBase, room } = agentContext(args, { needRoom: true });
+  const base = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/actions`;
+
+  if (action === 'list') {
+    const { text, json } = await requireOk(httpJson('GET', base, { headers: auth(token) }), 'actions list');
+    const items = Array.isArray(json) ? json : (json.actions ?? json.quick_actions ?? json.data ?? []);
+    printJsonOr(args, text, items.map((a) => `${a.action_number}  ${a.icon ?? ''} ${a.label ?? '(unset)'}`).join('\n') || '(no actions)');
+    return EXIT.OK;
+  }
+
+  const slot = args._[1];
+  if (!/^[1-4]$/.test(String(slot))) fail(`usage: pingroom actions ${action} <1-4> --room <code>`, EXIT.USAGE);
+
+  if (action === 'trigger') {
+    const { text } = await requireOk(
+      httpJson('POST', `${base}/${slot}/trigger`, { headers: auth(token), body: {} }),
+      'actions trigger',
+    );
+    process.stdout.write(`${text}\n`);
+    return EXIT.OK;
+  }
+
+  if (!args.label || !args.icon) fail('actions set needs --label and --icon', EXIT.USAGE);
+  const body = { label: args.label, icon: args.icon };
+  if (args.sound !== undefined) body.sound = args.sound;
+  if (args.require_ack) body.requires_ack = true;
+
+  const { text } = await requireOk(
+    httpJson('PUT', `${base}/${slot}`, { headers: auth(token), body }),
+    'actions set',
+  );
+  process.stdout.write(`${text}\n`);
+  return EXIT.OK;
+}
+
+// ------------------------------------------------------------- approval
+
+const APPROVAL_EXIT = { approved: EXIT.OK, denied: EXIT.CANCELLED, expired: EXIT.EXPIRED };
+
+export async function approval(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('approval')}\n`); return EXIT.OK; }
+
+  if (!args.prompt) fail('an approval needs --prompt', EXIT.USAGE);
+  const { token, apiBase, room } = agentContext(args, { needRoom: true });
+
+  const body = { prompt: args.prompt };
+  if (args.context) body.context = args.context;
+  if (args.ttl !== undefined) {
+    if (!/^\d+$/.test(String(args.ttl))) fail('--ttl must be an integer number of seconds', EXIT.USAGE);
+    body.ttl = Number(args.ttl);
+  }
+
+  const { text, json } = await requireOk(
+    httpJson('POST', `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/approvals`, { headers: auth(token), body }),
+    'approval',
+  );
+
+  if (!args.wait) {
+    process.stdout.write(`${text}\n`);
+    return EXIT.OK;
+  }
+
+  for (;;) {
+    const { res, text: waitText, json: state } = await httpJson(
+      'GET',
+      `${apiBase}/api/agent/approvals/${encodeURIComponent(json.id)}/wait?timeout=25`,
+      { headers: auth(token) },
+    );
+    if (!res.ok) fail(`approval wait failed: ${apiDetail(res, state)}`);
+    if (state && state.state && state.state !== 'pending') {
+      process.stdout.write(`${args.json ? waitText : state.state}\n`);
+      return APPROVAL_EXIT[state.state] ?? EXIT.OK;
+    }
+  }
+}
+
+// ----------------------------------------------------------- attachment
+
+export async function attachment(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('attachment')}\n`); return EXIT.OK; }
+  const action = sub(args, ['get', 'delete'], 'attachment');
+  const id = args._[1];
+  if (!id) fail(`usage: pingroom attachment ${action} <id>`, EXIT.USAGE);
+  const { token, apiBase } = agentContext(args);
+
+  if (action === 'delete') {
+    await requireOk(
+      httpJson('DELETE', `${apiBase}/api/agent/attachments/${encodeURIComponent(id)}`, { headers: auth(token) }),
+      'attachment delete',
+    );
+    process.stdout.write('deleted\n');
+    return EXIT.OK;
+  }
+
+  // Binary download: raw fetch, not httpJson. Bytes go to --out or stdout.
+  const res = await fetch(`${apiBase}/api/agent/attachments/${encodeURIComponent(id)}/content`, {
+    headers: auth(token),
+  });
+  if (!res.ok) {
+    let json = null;
+    try { json = await res.json(); } catch { /* binary error bodies stay generic */ }
+    fail(`attachment get failed: ${apiDetail(res, json)}`);
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+  if (args.out) {
+    const { writeFileSync } = await import('node:fs');
+    writeFileSync(args.out, bytes);
+    process.stdout.write(`${args.out}  ${bytes.length} bytes\n`);
+  } else {
+    process.stdout.write(bytes);
+  }
+  return EXIT.OK;
+}

package/lib/commands/mcp.js

@@ -6,6 +6,8 @@ import { fail } from '../util.js';
 
 export function mcp(rest) {
   const claudeCommand = `claude mcp add --transport http pingroom ${MCP_ENDPOINT}`;
+  const codexAddCommand = `codex mcp add pingroom --url ${MCP_ENDPOINT}`;
+  const codexLoginCommand = 'codex mcp login pingroom';
 
   if (rest.length === 0 || (rest.length === 1 && (rest[0] === '-h' || rest[0] === '--help'))) {
     const config = {
@@ -20,6 +22,13 @@ export function mcp(rest) {
 Claude Code:
   ${claudeCommand}
 
+Codex CLI:
+  ${codexAddCommand}
+  ${codexLoginCommand}
+
+OpenAI Plugins Directory (ChatGPT and Codex):
+  Search for PingRoom after its public listing is approved.
+
 Cursor JSON (~/.cursor/mcp.json):
 ${JSON.stringify(config, null, 2)}
 
@@ -43,5 +52,14 @@ This command only prints setup instructions and does not modify client config.
     return EXIT.OK;
   }
 
-  fail('usage: pingroom mcp [add claude-code]', EXIT.USAGE);
+  if (rest.length === 2 && rest[0] === 'add' && rest[1] === 'codex') {
+    process.stdout.write(
+`No client configuration was changed. Copy and run:
+  ${codexAddCommand}
+  ${codexLoginCommand}
+`);
+    return EXIT.OK;
+  }
+
+  fail('usage: pingroom mcp [add claude-code|codex]', EXIT.USAGE);
 }

package/lib/config.js

@@ -1,7 +1,7 @@
 // Local state (~/.pingroom) and the layered resolution every command shares:
 // explicit flag > env var > config file > the paired credential > built-in.
 
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import {
   chmodSync, closeSync, fchmodSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync,
   writeFileSync,
@@ -12,6 +12,7 @@ import { join } from 'node:path';
 import { BUILTIN_API, EXIT } from './constants.js';
 import { fail } from './util.js';
 import { requireSafeUrl } from './http.js';
+import { parseJsonStrict } from './strict-json.js';
 
 // --- local state (~/.pingroom) ---------------------------------------------
 //
@@ -36,9 +37,9 @@ export function configPath() { return join(pingroomHome(), 'config.json'); }
 // never be able to crash a ping: a hand-edited file degrades to "not set".
 export function readJsonFile(path) {
   let raw;
-  try { raw = readFileSync(path, 'utf8'); } catch { return null; }
+  try { raw = new TextDecoder('utf-8', { fatal: true }).decode(readFileSync(path)); } catch { return null; }
   let value;
-  try { value = JSON.parse(raw); } catch { return null; }
+  try { value = parseJsonStrict(raw, path); } catch { return null; }
   if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
   return value;
 }
@@ -183,6 +184,13 @@ export function agentContext(args, { needRoom = false } = {}) {
   if (needRoom && !room) {
     fail('--room is required (or set one with "pingroom config set default_room <code>")', EXIT.USAGE);
   }
+  if (args.expected_room_sha256 !== undefined) {
+    const expected = String(args.expected_room_sha256);
+    if (!/^[a-f0-9]{64}$/.test(expected)) fail('--expected-room-sha256 must be 64 lowercase hexadecimal characters', EXIT.USAGE);
+    if (!room) fail('--expected-room-sha256 requires a resolved room', EXIT.USAGE);
+    const actual = createHash('sha256').update(String(room), 'utf8').digest('hex');
+    if (actual !== expected) fail('resolved room does not match --expected-room-sha256', EXIT.USAGE);
+  }
   return { token, apiBase, room };
 }
 

package/lib/help.js

@@ -31,6 +31,11 @@ Commands:
   mcp      Print the remote MCP endpoint and setup for Claude Code, Cursor, and
            Claude Desktop
   activate Retry Agent Inbox activation with the saved QR-paired credential
+  rooms    List, inspect, create, or join rooms (rooms list|get|create|join)
+  webhooks Manage a room's incoming webhooks (webhooks list|create|update|delete)
+  actions  List, configure, or trigger a room's quick actions (actions list|set|trigger)
+  approval Send an approve/deny request; with --wait, block on the decision
+  attachment Download or delete an attachment by id (attachment get|delete)
   config   Read/write local settings (config list | get <key> | set <key> <val>)
   logout   Forget the stored credential`;
 
@@ -65,6 +70,7 @@ export const HELP_ASK = `ask options (agent token required):
       --scope <s>        Who answers: 'direct' (default) or 'room'
       --target <uuid>    For --scope direct: a specific room member
       --ttl <seconds>    Expiry; omit for the server default (1h; 30..86400)
+      --idempotency-key <key>  Dedupe this exact create request across retries
       --text-input <ph>  Invite a short typed answer; <ph> is the placeholder
       --text-max <n>     Max typed-answer length (1..60)
       --wait             Block until answered/expired/cancelled
@@ -73,6 +79,8 @@ export const HELP_ASK = `ask options (agent token required):
       --correlation-id <id>  Opaque id echoed on every read of this question
       --reply-to <id>    Id of the ping this question replies to
       --room <code>      Room invite code (required for ask)
+      --expected-room-sha256 <hex>
+                         Fail unless the resolved room matches this SHA-256
       --github-output <path>  Safely append question outputs for GitHub Actions`;
 
 export const HELP_LIST = `list options:
@@ -292,6 +300,37 @@ export const COMMAND_HELP_SECTIONS = {
   live: HELP_LIVE,
   hook: HELP_HOOK,
   activate: HELP_ACTIVATE,
+  rooms: `rooms (agent token required):
+  pingroom rooms list               List the rooms this account belongs to
+  pingroom rooms get <code>         Show one room
+  pingroom rooms create -n <name> --icon <id> --color <hex>
+                                    Create a private room (add --description);
+                                    --public --handle <handle> creates a public
+                                    room under its own consent scope
+  pingroom rooms join <code>        Join a room by invite code`,
+  webhooks: `webhooks (agent token + --room required):
+  pingroom webhooks list --room <code>
+  pingroom webhooks create --room <code> --name <n>
+                                    Optional: --title --message --icon --color
+                                    --sound --action <1-4> --cooldown <sec>
+                                    Prints the secret trigger URL once
+  pingroom webhooks update <id> --room <code> [same fields, plus --enabled true|false]
+  pingroom webhooks delete <id> --room <code>`,
+  actions: `actions (agent token + --room required):
+  pingroom actions list --room <code>
+  pingroom actions set <1-4> --room <code> --label <text> --icon <emoji>
+                                    Optional: --sound, --require-ack
+  pingroom actions trigger <1-4> --room <code>`,
+  approval: `approval (agent token + --room required):
+  pingroom approval -p <prompt>     Send an approve/deny request
+      -c, --context <text>   Secondary line (<= 40 chars)
+      --ttl <seconds>        Expiry; omit for the server default
+      --wait                 Block until approved/denied/expired
+                             (exit 0 approved · 4 denied · 3 expired)`,
+  attachment: `attachment (agent token required):
+  pingroom attachment get <id> [--out <path>]
+                                    Download; bytes go to --out or stdout
+  pingroom attachment delete <id>   Delete an unclaimed upload`,
   config: HELP_CONFIG,
   logout: `logout:
   pingroom logout                   Forget the stored credential (PINGROOM_TOKEN

package/lib/http.js

@@ -3,6 +3,7 @@
 
 import { EXIT } from './constants.js';
 import { fail, stripControlChars } from './util.js';
+import { readStrictJsonResponse } from './strict-json.js';
 
 /**
  * The fixes that live on THIS side of the wire. The server's message always
@@ -85,15 +86,13 @@ export async function httpJson(method, url, { body, headers = {}, soft = false,
   }
 
   let text;
+  let json;
   try {
-    text = await res.text();
+    ({ text, json } = await readStrictJsonResponse(res, 'PingRoom API response'));
   } catch (err) {
-    // A connection dropped mid-body throws here, not at fetch().
     if (soft) return { res: null, text: '', json: null, error: err };
-    fail(`network error: ${err.message}`);
+    fail(`untrusted JSON response: ${err.message}`);
   }
-  let json = null;
-  try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON response */ }
 
   return { res, text, json };
 }
@@ -165,9 +164,10 @@ export async function uploadAttachments(paths, apiBase, token) {
       fail(`network error uploading ${name}: ${err.message}`);
     }
 
-    const text = await res.text().catch(() => '');
     let json = null;
-    try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON response */ }
+    try { ({ json } = await readStrictJsonResponse(res, 'attachment API response')); } catch (error) {
+      fail(`untrusted JSON response uploading ${name}: ${error.message}`);
+    }
 
     if (res.status === 402) {
       fail(`--attach ${name}: ping attachments are a Pro feature`, EXIT.USAGE);
@@ -196,9 +196,7 @@ export async function hookFetch(method, url, { body, token } = {}) {
     },
     ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
   });
-  const text = await res.text();
-  let json = null;
-  try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON response */ }
+  const { json } = await readStrictJsonResponse(res, 'hook response');
   if (!res.ok) {
     throw new Error(apiDetail(res, json));
   }

package/lib/parser.js

@@ -70,6 +70,7 @@ export const parseArgs = makeParser({
     '--attach': 'attach',
     '--token': 'token',
     '--room': 'room',
+    '--expected-room-sha256': 'expected_room_sha256',
     '--api': 'api',
     '--json': 'json',
     '-h': 'help', '--help': 'help',
@@ -88,6 +89,7 @@ export const parseQArgs = makeParser({
     '--scope': 'scope',
     '--target': 'target',
     '--ttl': 'ttl',
+    '--idempotency-key': 'idempotency_key',
     '-d': 'data', '--data': 'data',
     '--correlation-id': 'correlation_id',
     '--reply-to': 'reply_to',
@@ -101,6 +103,7 @@ export const parseQArgs = makeParser({
     '--github-output': 'github_output',
     '--token': 'token',
     '--room': 'room',
+    '--expected-room-sha256': 'expected_room_sha256',
     '--api': 'api',
     '--wait': 'wait',
     '--json': 'json',
@@ -208,6 +211,40 @@ export const parseLogoutArgs = makeParser({
   bareDashIsPositional: true,
 });
 
+// Parser for the management nouns (rooms / webhooks / actions / approval /
+// attachment). One shared vocabulary: each sub-command reads the flags it
+// needs and the rest are usage errors at the command layer, same as everywhere.
+export const parseManageArgs = makeParser({
+  aliases: {
+    '-n': 'name', '--name': 'name',
+    '--description': 'description',
+    '--icon': 'icon',
+    '--color': 'color',
+    '--sound': 'sound',
+    '--label': 'label',
+    '-t': 'title', '--title': 'title',
+    '-m': 'message', '--message': 'message',
+    '-p': 'prompt', '--prompt': 'prompt',
+    '-c': 'context', '--context': 'context',
+    '--ttl': 'ttl',
+    '--public': 'public',
+    '--handle': 'handle',
+    '-a': 'action', '--action': 'action',
+    '--cooldown': 'cooldown',
+    '--enabled': 'enabled',
+    '--require-ack': 'require_ack',
+    '--out': 'out',
+    '--wait': 'wait',
+    '--token': 'token',
+    '--room': 'room',
+    '--expected-room-sha256': 'expected_room_sha256',
+    '--api': 'api',
+    '--json': 'json',
+    '-h': 'help', '--help': 'help',
+  },
+  booleans: ['public', 'require_ack', 'wait', 'json', 'help'],
+});
+
 export const parseHandoffsArgs = makeParser({
   aliases: {
     '--state': 'state',

package/lib/strict-json.js

@@ -0,0 +1,93 @@
+const MAX_JSON_BYTES = 1024 * 1024;
+
+export function parseJsonStrict(raw, label = 'JSON') {
+  if (typeof raw !== 'string') throw new Error(`${label} must be UTF-8 JSON`);
+  rejectDuplicateKeys(raw, label);
+  return JSON.parse(raw);
+}
+
+export async function readStrictJsonResponse(response, label = 'response') {
+  const chunks = [];
+  let size = 0;
+  if (response.body) {
+    const reader = response.body.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > MAX_JSON_BYTES) {
+        await reader.cancel().catch(() => {});
+        throw new Error(`${label} exceeded ${MAX_JSON_BYTES} bytes`);
+      }
+      chunks.push(Buffer.from(value));
+    }
+  }
+  const bytes = Buffer.concat(chunks);
+  let text;
+  try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error(`${label} was not valid UTF-8`); }
+  return { text, json: text ? parseJsonStrict(text, label) : null };
+}
+
+function rejectDuplicateKeys(raw, label) {
+  let index = 0;
+  const invalid = () => { throw new Error(`${label} is not valid JSON`); };
+  const whitespace = () => { while (/\s/u.test(raw[index] ?? '')) index += 1; };
+  const string = () => {
+    if (raw[index] !== '"') invalid();
+    const start = index++;
+    while (index < raw.length) {
+      if (raw[index] === '\\') { index += 2; continue; }
+      if (raw[index] === '"') {
+        index += 1;
+        try { return JSON.parse(raw.slice(start, index)); } catch { invalid(); }
+      }
+      index += 1;
+    }
+    invalid();
+  };
+  const value = () => {
+    whitespace();
+    if (raw[index] === '{') return object();
+    if (raw[index] === '[') return array();
+    if (raw[index] === '"') { string(); return; }
+    const start = index;
+    while (index < raw.length && !/[\s,\]}]/u.test(raw[index])) index += 1;
+    if (index === start) invalid();
+  };
+  const object = () => {
+    index += 1;
+    whitespace();
+    const keys = new Set();
+    if (raw[index] === '}') { index += 1; return; }
+    for (;;) {
+      whitespace();
+      const key = string();
+      if (keys.has(key)) throw new Error(`${label} contains a duplicate object key`);
+      keys.add(key);
+      whitespace();
+      if (raw[index] !== ':') invalid();
+      index += 1;
+      value();
+      whitespace();
+      if (raw[index] === '}') { index += 1; return; }
+      if (raw[index] !== ',') invalid();
+      index += 1;
+    }
+  };
+  const array = () => {
+    index += 1;
+    whitespace();
+    if (raw[index] === ']') { index += 1; return; }
+    for (;;) {
+      value();
+      whitespace();
+      if (raw[index] === ']') { index += 1; return; }
+      if (raw[index] !== ',') invalid();
+      index += 1;
+    }
+  };
+  whitespace();
+  value();
+  whitespace();
+  if (index !== raw.length) invalid();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingroom/cli",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "Send PingRoom Pings and wait for human decisions from CI, scripts, and agents.",
   "type": "module",
   "bin": {