@pingroom/cli 0.7.3 → 0.7.4

package/README.md

@@ -153,7 +153,7 @@ URL (it embeds its own secret — treat it like a password and store it as a CI
 ```
 pingroom ping [options]
 
-  -m, --message <text>   Ping body text (required)
+  -m, --message <text>   Ping body (required; <= 120 private / <= 160 public)
   -t, --title <text>     Ping title (<= 40 chars)
   -a, --action <1-4>     Quick-action slot to attribute the ping to
   -d, --data <json>      Extra JSON data, e.g. '{"commit":"abc123"}'
@@ -169,6 +169,11 @@ pingroom ping [options]
       --json             Print the raw JSON response
 ```
 
+Ping titles are limited to 40 characters. Bodies are limited to 120 characters
+in private rooms and 160 in public rooms. A room code or webhook URL does not
+reveal room visibility, so the CLI rejects only bodies over 160 locally; the
+server applies the tighter 120-character private-room limit.
+
 To make the ping actionable, add `--require-ack`. The first eligible recipient to
 acknowledge it wins; `--ack-timeout` optionally expires it if nobody responds:
 
@@ -392,6 +397,13 @@ Full protocol: <https://pingroom.io/liveactivities.md>
 including `@v0` before it is moved to v0.7.3 — GitHub treats them as unexpected
 inputs, warns, and drops them; the step then falls through to the plain `ping`
 path, `outputs.answer` is never set, and any job gated on it silently proceeds.
+
+`urgent` was added in **v0.7.4** and has the same failure mode on an older pin:
+GitHub drops the unknown input and the Ping goes out at normal priority, which
+looks like it worked. `require-ack` is not a substitute — as of the same release
+it opens the acknowledgement lifecycle without raising the interruption level,
+so a workflow that used it to break through Focus needs `urgent: true`.
+
 Everything else on this page (ping, `require-ack`, and the whole `handoff`
 family) works on `@v0`.
 

package/lib/commands/hook.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 
-import { EXIT } from '../constants.js';
+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';
@@ -62,7 +62,7 @@ function summarizeTranscript(path) {
     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, 500);
+    if (text) return truncate(text, PUBLIC_PING_MESSAGE_MAX_LENGTH);
   }
   return '';
 }
@@ -185,7 +185,7 @@ async function hookNotify(event, name, { token, room, apiBase, args }) {
     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.', 500);
+    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;

package/lib/commands/live.js

@@ -51,7 +51,8 @@ export async function live(args) {
     state: sub === 'end' ? (args.failed ? 'failed' : 'done') : 'running',
   };
 
-  // 256, not the 500 a ping body gets: this is the card's one live line.
+  // This live-status payload field has its own 256-character contract; ordinary
+  // Ping bodies are 120 in private rooms and 160 in public rooms.
   requireMaxLength(args.message, 256, '--message');
   requireMaxLength(args.title, 40, '--title');
   requireMaxLength(args.prompt, 256, '--prompt');

package/lib/commands/ping.js

@@ -1,4 +1,4 @@
-import { EXIT } from '../constants.js';
+import { EXIT, PING_TITLE_MAX_LENGTH, PUBLIC_PING_MESSAGE_MAX_LENGTH } from '../constants.js';
 import { fail, parseDataObject, requireMaxLength } from '../util.js';
 import { commandHelp } from '../help.js';
 import { apiDetail, httpJson, requireSafeUrl, uploadAttachments } from '../http.js';
@@ -9,8 +9,10 @@ export async function ping(args) {
 
   const message = args.message;
   if (!message) fail('a --message is required', EXIT.USAGE);
-  requireMaxLength(message, 500, '--message');
-  requireMaxLength(args.title, 40, '--title');
+  // Room visibility is not encoded in a room code or webhook URL. Validate the
+  // public ceiling here; the API applies 120 for private rooms and 160 for public.
+  requireMaxLength(message, PUBLIC_PING_MESSAGE_MAX_LENGTH, '--message');
+  requireMaxLength(args.title, PING_TITLE_MAX_LENGTH, '--title');
 
   if (args.action !== undefined && !/^[1-4]$/.test(String(args.action))) {
     fail('--action must be an integer 1–4', EXIT.USAGE);
@@ -81,6 +83,7 @@ export async function ping(args) {
     if (args.action !== undefined) body.action = Number(args.action);
     if (data) body.data = data;
     if (args.require_ack) body.requires_ack = true;
+    if (args.urgent) body.is_urgent = true;
     if (ackTimeout !== undefined) body.ack_timeout_seconds = ackTimeout;
     result = await httpJson('POST', webhook, { body });
   } else if (token) {
@@ -96,6 +99,7 @@ export async function ping(args) {
     if (args.action !== undefined) body.action_number = Number(args.action);
     if (data) body.data = data;
     if (args.require_ack) body.requires_ack = true;
+    if (args.urgent) body.is_urgent = true;
     if (ackTimeout !== undefined) body.ack_timeout_seconds = ackTimeout;
     if (attachPaths.length) {
       body.attachment_ids = await uploadAttachments(attachPaths, apiBase, token);

package/lib/constants.js

@@ -5,3 +5,10 @@ export const MCP_ENDPOINT = `${BUILTIN_API}/api/agent/mcp`;
 export const DEFAULT_API = process.env.PINGROOM_API_URL || BUILTIN_API;
 
 export const EXIT = { OK: 0, ERROR: 1, USAGE: 2, EXPIRED: 3, CANCELLED: 4 };
+
+// A caller holding only a room code or webhook URL cannot know the room's
+// visibility without another request. Keep the CLI's local ceiling at the
+// public-room limit; Laravel applies the tighter private-room limit.
+export const PING_TITLE_MAX_LENGTH = 40;
+export const PRIVATE_PING_MESSAGE_MAX_LENGTH = 120;
+export const PUBLIC_PING_MESSAGE_MAX_LENGTH = 160;

package/lib/help.js

@@ -35,13 +35,17 @@ Commands:
   logout   Forget the stored credential`;
 
 export const HELP_PING = `ping options:
-  -m, --message <text>   Ping body text (required)
+  -m, --message <text>   Ping body (required; <= 120 private / <= 160 public)
   -t, --title <text>     Ping title (<= 40 chars)
   -a, --action <1-4>     Quick-action slot to attribute the ping to
   -d, --data <json>      Extra JSON data object, e.g. '{"commit":"abc123"}'
       --url <https-url>  Make the ping a tappable link (absolute http(s) URL)
       --button-label <t> Link button text (<= 26 chars; requires --url)
-      --require-ack      Keep the ping open until an eligible recipient acknowledges it
+      --urgent           Deliver time-sensitive so it breaks through Focus / Do Not
+                         Disturb. Delivery only - asks nothing of the recipient
+      --require-ack      Keep the ping open until an eligible recipient acknowledges it,
+                         showing a lock-screen card with an Acknowledge button. Does
+                         not raise the interruption level; combine with --urgent
       --ack-timeout <s>  Ack deadline in seconds (requires --require-ack)
       --attach <path>    Attach a file (md/pdf/html/txt/jpg/jpeg/png/zip, <= 5 MiB);
                          repeat for up to 4. Requires --token and a Pro account
@@ -105,7 +109,7 @@ export const HELP_LIVE = `live <start|update|end|get> options (agent token, or a
                              'question', which is still accepted)
       --category <name>      start only: status | steps | alert. Legacy, but
                              'alert' has no template equivalent and is the only
-                             way to start time-sensitive without --require-ack
+                             way to start a stream time-sensitive
       --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
@@ -124,7 +128,8 @@ export const HELP_LIVE = `live <start|update|end|get> options (agent token, or a
   -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
+      --require-ack          Add an Acknowledge button (does not raise the
+                             interruption level; see --category alert)
       --ack-timeout <s>      Ack deadline in seconds
       --room <code>          Room invite code (used with --token)
   -w, --webhook <url>        Room webhook URL instead of a token`;

package/lib/parser.js

@@ -62,6 +62,7 @@ export const parseArgs = makeParser({
     '--url': 'url',
     '--button-label': 'button_label',
     '--require-ack': 'require_ack',
+    '--urgent': 'urgent',
     '--ack-timeout': 'ack_timeout',
     '--attach': 'attach',
     '--token': 'token',
@@ -70,7 +71,7 @@ export const parseArgs = makeParser({
     '--json': 'json',
     '-h': 'help', '--help': 'help',
   },
-  booleans: ['require_ack', 'json', 'help'],
+  booleans: ['require_ack', 'urgent', 'json', 'help'],
   repeatable: ['attach'],
 });
 
@@ -159,6 +160,9 @@ export const parseLiveArgs = makeParser({
     '-a': 'action', '--action': 'action',
     '-d': 'data', '--data': 'data',
     '--require-ack': 'require_ack',
+    // No --urgent here on purpose. A STREAM starts time-sensitive via
+    // `--category alert` (fixed at creation); the live-status endpoint does not
+    // accept `is_urgent`, so the flag would parse and then be silently dropped.
     '--ack-timeout': 'ack_timeout',
     '-w': 'webhook', '--webhook': 'webhook',
     '--token': 'token',

package/lib/util.js

@@ -39,7 +39,8 @@ export function stripControlChars(value) {
 
 export function truncate(value, max) {
   const str = String(value ?? '');
-  return str.length <= max ? str : `${str.slice(0, max - 1)}…`;
+  const characters = Array.from(str);
+  return characters.length <= max ? str : `${characters.slice(0, max - 1).join('')}…`;
 }
 
 /**
@@ -51,8 +52,11 @@ export function truncate(value, max) {
  * it is, with the limit and the actual length named.
  */
 export function requireMaxLength(value, max, flag) {
-  if (typeof value === 'string' && value.length > max) {
-    fail(`${flag} must be at most ${max} characters (got ${value.length})`, EXIT.USAGE);
+  if (typeof value === 'string') {
+    const length = Array.from(value).length;
+    if (length > max) {
+      fail(`${flag} must be at most ${max} characters (got ${length})`, EXIT.USAGE);
+    }
   }
 }
 

package/package.json

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