@pingroom/sdk 0.2.0 → 0.3.1

package/README.md

@@ -20,12 +20,32 @@ import { PingRoom } from '@pingroom/sdk';
 const pr = new PingRoom({ token: process.env.PINGROOM_TOKEN });
 
 // Broadcast to a room you own
-await pr.broadcast('ab12cd', { message: 'Deploy shipped ✅', data: { version: '1.4.0' } });
+await pr.broadcast('ab12cd', {
+  message: 'Deploy shipped ✅',
+  data: { version: '1.4.0' },
+  requires_ack: true,
+  ack_timeout_seconds: 300,
+});
 
 // Ping another agent by handle
 await pr.agents.ping('agt_reviewer', { message: 'PR #42 ready', correlation_id: 'pr-42' });
 ```
 
+### Link pings
+
+A ping becomes a tappable link button when its `data` carries the reserved
+keys `url` (absolute http(s), ≤ 2048 chars) and optional `button_label`
+(≤ 26 chars). The `linkPing()` helper builds and validates that fragment:
+
+```ts
+import { PingRoom, linkPing } from '@pingroom/sdk';
+
+await pr.broadcast('ab12cd', {
+  message: 'Build 512 ready',
+  data: { commit: 'abc123', ...linkPing({ url: 'https://ci.example.com/b/512', buttonLabel: 'Open build' }) },
+});
+```
+
 > Security note: an agent credential is a bearer token. Keep it server-side. Do not embed a long-lived token in a browser bundle or a public client.
 
 ## Authentication
@@ -57,7 +77,7 @@ Generic MCP clients (Cursor, Claude Desktop, Claude Code) should use the standar
 ```ts
 await pr.rooms.list();
 await pr.rooms.get('ab12cd');
-await pr.rooms.create({ name: 'Deploys', icon: 'rocket', color: '#e53d30' });
+await pr.rooms.create({ name: 'Deploys', icon: 'rocket', color: '#e33122' });
 await pr.rooms.join({ invite_code: 'ab12cd' });
 
 await pr.actions.update('ab12cd', 1, { label: 'Approve', icon: 'check' });
@@ -83,6 +103,26 @@ Or a single long-poll:
 const { notifications, cursor } = await pr.notifications.wait({ after: lastCursor, timeout: 20 });
 ```
 
+Read one ping and wait for its acknowledgement through the same namespace:
+
+```ts
+const ping = await pr.notifications.getNotification(notificationId);
+console.log(ping.action_state?.status); // open | acked | expired
+
+const result = await pr.notifications.waitForAcknowledgement(notificationId, { timeout: 30 });
+switch (result.action_state.status) {
+  case 'acked':
+    console.log(`Acknowledged by ${result.action_state.acked_by?.name ?? 'someone'}`);
+    break;
+  case 'expired':
+    console.log('Nobody acknowledged before the deadline');
+    break;
+  case 'open':
+    // This bounded hold timed out; call waitForAcknowledgement again to continue.
+    break;
+}
+```
+
 ## Human-in-the-loop approvals
 
 Ask the human you act for to decide, and block until they tap an answer on their phone.
@@ -141,6 +181,62 @@ await pr.questions.cancel(q.id);              // withdraw a pending one
 
 > `pr.approvals` is the ergonomic two-option shortcut and stays fully supported — it routes through the same machinery server-side. Use it for plain yes/no gates; use `pr.questions` for everything richer.
 
+## Handoffs (Agent → one human)
+
+A **handoff** is the direct, private version of the human-in-the-loop: it always targets **exactly one human** and is never readable by anyone else in the room. Reach for `pr.handoffs` when an agent needs to hand a task to *its* human (or one specific person) and block on the outcome — no room to pick, no room-scope answering. It's backed by the ack and question primitives, so a handoff is one of two `kind`s:
+
+- **`ack`** — "acknowledge this." Resolves the moment the human taps acknowledge. States: `open | acked | expired`.
+- **`question`** — "pick one." 2–4 tappable options. States: `pending | answered | expired | cancelled`.
+
+Requires the `pingroom:handoffs:create` scope.
+
+On first connect, activate the human's private Agent Inbox. This is idempotent:
+it creates at most one inbox and one onboarding test Question.
+
+```ts
+const onboarding = await pr.inbox.ensure();
+console.log(onboarding.room.invite_code, onboarding.question.state);
+```
+
+```ts
+// Ask for an acknowledgement. Pass idempotencyKey so a retried create is a no-op.
+const task = await pr.handoffs.requestAck({
+  prompt: 'Deploy 1.4.0 to prod is queued — ack to proceed.',
+  idempotencyKey: 'deploy-1.4.0',   // reuse verbatim on network retries
+});
+
+// Block until the human acks (or it expires). Terminal states never throw.
+const result = await pr.handoffs.waitForResult(task.id);
+if (result.state === 'acked') {
+  console.log(`Acked by ${result.acked_by?.display_name} at ${result.acked_at}`);
+}
+```
+
+```ts
+// Ask a multi-option question. Bare strings normalize to { value, label: value }.
+const q = await pr.handoffs.ask({
+  prompt: 'Ship or hold 1.4.0?',
+  options: ['deploy', 'hold'],
+  idempotencyKey: 'ship-1.4.0',
+});
+
+const answered = await pr.handoffs.waitForResult(q.id);
+if (answered.state === 'answered') {
+  // A negative choice ('hold') is a SUCCESSFUL answered result — not an error.
+  console.log(`Human chose ${answered.answer?.value}`);
+}
+```
+
+`waitForResult` loops the bounded long-poll until a terminal state lands, so `expired`/`cancelled` and a negative answer all come back as normal results — nothing is thrown for the outcome. Full options: `prompt`, `target` (`'me'` — the default — or a user UUID), `expiresIn` (120–86400s, default 900), `urgency` (`'active'` | `'passive'`), `correlationId`, `replyTo`, `data`, `idempotencyKey`.
+
+```ts
+await pr.handoffs.get(id);                // current state (polling / audit)
+await pr.handoffs.list({ state: 'open' }); // your open handoffs
+await pr.handoffs.list({ state: 'all' });  // recent history (up to 200 per kind)
+```
+
+Create/read map coded failures onto `PingRoomError` — branch on `error.code` (see [`HandoffErrorCode`](#errors)). The exported union includes target-policy, scope/quota, idempotency, feature, and capability failures; `capability_check_unavailable` is retryable. Authentication and schema-validation failures may have no code, so also inspect `error.status`.
+
 ## Incoming webhooks (no token needed)
 
 A room's incoming-webhook URL carries its own secret — ideal for CI/deploy hooks:
@@ -151,21 +247,138 @@ import { sendIncomingWebhook } from '@pingroom/sdk';
 await sendIncomingWebhook(process.env.PINGROOM_WEBHOOK_URL, {
   message: 'Build #42 passed',
   data: { commit: 'abc123' },
+  requires_ack: true,
+  ack_timeout_seconds: 300,
 }, { idempotencyKey: 'build-42' });
 ```
 
+### Live Activities from a webhook
+
+See [Live Activities](#live-activities) below for the full picture. From a webhook, put `live_status` at the **top level** of the payload:
+
+```ts
+await sendIncomingWebhook(process.env.PINGROOM_WEBHOOK_URL, {
+  message: 'Deploying v1.4.0',
+  correlation_id: 'deploy-42',
+  live_status: { state: 'running', template: 'progress', progress: 0.4 },
+});
+```
+
+> **Not inside `data`.** The server routes on a top-level `live_status` and *strips* the key from `data` so a legacy caller cannot spoof completion alerts. A nested `data.live_status` silently sends an ordinary ping and still answers `success: true`. (SDK versions before 0.3.1 dropped `live_status` from the request body entirely — upgrade.)
+
+## Live Activities
+
+A **live-status stream** is one thing being tracked, keyed by your `correlation_id`. The first ping starts a self-updating card on every room member's Lock Screen (iOS Live Activity / Dynamic Island, Android ongoing live update, and a full inline card in the app). Later `running` pings move it **silently** — no new notification. The first `done`/`failed` sends one completion alert and ends it.
+
+Protocol: <https://pingroom.io/liveactivities.md> (v1.2).
+
+### Two ways to send one
+
+```ts
+import { PingRoom, liveStatus, sendIncomingWebhook } from '@pingroom/sdk';
+
+// A. Agent credential — needs the `pingroom:live:write` scope.
+const pr = new PingRoom({ token: process.env.PINGROOM_TOKEN });
+await pr.live.push('AB12CD', liveStatus.progress('deploy-42', {
+  state: 'running',
+  message: 'Building image',
+  progress: 0.4,
+}));
+
+// B. A room's incoming webhook (Pro) — no token. The builder returns
+// { correlation_id, live_status }, which is exactly the webhook body.
+await sendIncomingWebhook(
+  process.env.PINGROOM_WEBHOOK_URL,
+  liveStatus.progress('deploy-42', {
+    state: 'running',
+    message: 'Building image',
+    progress: 0.4,
+  }),
+);
+```
+
+There is a third producer — a person driving a stream from the app composer over `POST /api/rooms/{code}/live` with their own JWT — but that is a Human JWT route and is not part of this agent SDK.
+
+### Templates
+
+`template` is fixed at stream creation; a later ping cannot re-template a running card. Content set at creation is **sticky**, so a sparse update carrying just `progress` keeps rendering the full template — and so does the terminal leg, so a bare `{ state: 'done' }` ends the activity on the finished card rather than an empty one.
+
+| Builder | Renders |
+|---|---|
+| `liveStatus.status` | Title, message, optional progress |
+| `liveStatus.steps` | Segmented tracker; `steps` (2–8 labels) required on the first ping and immutable after |
+| `liveStatus.progress` | Determinate bar with optional `eta_at` |
+| `liveStatus.metrics` | Up to 3 `{label, value}` counters |
+| `liveStatus.countdown` | Large live timer to `deadline_at` |
+| `liveStatus.question` | `prompt` + up to 4 `{value, label}` options on the lock screen |
+| `liveStatus.matchup` | `left` / `center` / `right` — a score or A-vs-B |
+
+```ts
+await pr.live.push('AB12CD', liveStatus.steps('release-7', {
+  state: 'running',
+  steps: ['Build', 'Test', 'Deploy', 'Verify'],
+  current_step: 2,
+  message: 'Deploying to prod',
+}));
+
+await pr.live.push('AB12CD', liveStatus.matchup('game-3', {
+  state: 'running',
+  left: { label: 'ARS', value: '2' },
+  right: { label: 'CHE', value: '1' },
+  center: "68'",
+}));
+```
+
+### Ending and reading back
+
+```ts
+// Always end a stream. `done`/`failed` is never rate-limited or quota-blocked,
+// so a card can't be metered into hanging open on a lock screen.
+await pr.live.push('AB12CD', liveStatus.done('deploy-42', 'Shipped v1.4.0'));
+// ...or liveStatus.failed('deploy-42', 'Rollback triggered')
+
+// Reconcile after a restart instead of opening a duplicate.
+// Returns null (not a throw) when there is no such stream in the last 24 hours.
+const snap = await pr.live.get('AB12CD', 'deploy-42');
+if (snap) console.log(snap.template, snap.current_step, snap.updated_at);
+```
+
+`get()` returns **every** stored field (`state`, `progress`, `message`, `category`, `template`, `agent_id`, `accent_override`, `eta_at`, `deadline_at`, `metrics`, `prompt`, `options`, `left`, `right`, `center`, `steps`, `current_step`) plus `action_state` and `updated_at`. Fields you never set come back as `null`, not omitted.
+
+### Ownership and limits
+
+A stream belongs to the credential that started it. An agent can never advance a webhook's stream or another registration's, even under the same `correlation_id`. Updates are throttled to ~6/min per correlation and 10 new streams/min per producer; free agent accounts get 5 new streams/day (`402 free_limit_reached`). Creation is the only charged leg.
+
+### `liveActivity.*` is not this
+
+The exported `liveActivity.*` builders produce the frozen **native** `{ attributes, content_state }` push-layer shape for tests and tooling. No endpoint accepts them as input, and a `live_activity` block inside a `broadcast()` `data` object is carried as opaque structured data — it starts nothing. Use `liveStatus.*` to drive a real activity.
+
 ## Verifying outgoing webhooks
 
-When PingRoom POSTs an event to *your* server, verify it before trusting it. The signature is `HMAC-SHA256(signing_secret, rawBody)`, sent as `X-PingRoom-Signature: sha256=<hex>`. **Verify over the exact raw request body — re-serializing the parsed JSON will not match.**
+When PingRoom POSTs an event to *your* server, verify it before trusting it. New deliveries carry two lower-case hex HMAC-SHA256 headers:
+
+- `X-PingRoom-Signature-V2` signs `` `v2\n${timestamp}\n${deliveryId}\n${rawBody}` `` and binds `X-PingRoom-Delivery` as well as the timestamp and body.
+- `X-PingRoom-Signature` keeps the legacy `` `${timestamp}.${rawBody}` `` contract so existing receivers continue to work.
+
+`timestamp` is the Unix-seconds value in `X-PingRoom-Timestamp`, and `deliveryId` is the exact `X-PingRoom-Delivery` value. **Verify over the exact raw request body; re-serializing parsed JSON can change the bytes and invalidate the signature.** If v2 is present, receivers MUST verify it and reject the request on failure. The helper accepts legacy v1 only when v2 is absent. It rejects timestamps outside a five-minute replay window by default; set `maxAgeSeconds` to customize that window.
 
 ```ts
-import { verifyWebhookSignature, WEBHOOK_SIGNATURE_HEADER } from '@pingroom/sdk';
+import {
+  verifyWebhookSignature,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_SIGNATURE_V2_HEADER,
+  WEBHOOK_TIMESTAMP_HEADER,
+  WEBHOOK_DELIVERY_HEADER,
+} from '@pingroom/sdk';
 
 // Express example — capture the raw body (e.g. express.raw())
 app.post('/pingroom', async (req, res) => {
   const ok = await verifyWebhookSignature({
     payload: req.body,                          // a Buffer/string of the RAW body
     signature: req.get(WEBHOOK_SIGNATURE_HEADER),
+    signatureV2: req.get(WEBHOOK_SIGNATURE_V2_HEADER),
+    timestamp: req.get(WEBHOOK_TIMESTAMP_HEADER),
+    deliveryId: req.get(WEBHOOK_DELIVERY_HEADER),
     secret: process.env.PINGROOM_SIGNING_SECRET,
   });
   if (!ok) return res.status(401).end();

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { HttpClient } from './http.js';
+import type { LiveStatusPing, LiveStatusResult, LiveStatusSnapshot } from './liveStatus.js';
 import { McpClient } from './mcp.js';
-import type { AgentNotification, Approval, ApprovalInput, CreatePublicRoomInput, CreateRoomInput, Credential, ClaimCompleteParams, ClaimStartParams, DirectoryEntry, DirectoryListInput, DirectoryProfile, DirectPingResult, JoinRoomInput, ListNotificationsInput, ListenInput, ListQuestionsInput, Paginated, PingInput, PingResult, PingRoomOptions, Question, QuestionInput, QuickAction, RegisterParams, Room, RotateHandleResult, TriggerInput, UpdateQuickActionInput, WaitApprovalInput, WaitInput, WaitQuestionInput, WaitResult } from './types.js';
+import type { AcknowledgementWaitResult, AgentInboxEnsureResult, AgentNotification, Approval, ApprovalInput, CreatePublicRoomInput, CreateRoomInput, Credential, ClaimCompleteParams, ClaimStartParams, AskInput, DirectoryEntry, DirectoryListInput, DirectoryProfile, DirectPingResult, Handoff, ListHandoffsInput, JoinRoomInput, ListNotificationsInput, ListenInput, ListQuestionsInput, NotificationDetail, Paginated, PingInput, PingResult, PingRoomOptions, Question, QuestionInput, QuickAction, RegisterParams, Room, RequestAckInput, RotateHandleResult, TriggerInput, UpdateQuickActionInput, WaitApprovalInput, WaitHandoffInput, WaitForAcknowledgementInput, WaitInput, WaitQuestionInput, WaitResult } from './types.js';
 /** Agent credential lifecycle (auth.md flow). */
 declare class AuthApi {
     private readonly http;
@@ -40,6 +41,13 @@ declare class NotificationsApi {
     constructor(http: HttpClient);
     /** Paginated list (polling fallback). Prefer wait()/listen() for real-time. */
     list(input?: ListNotificationsInput): Promise<Paginated<AgentNotification>>;
+    /** Fetch one visible notification, including its current acknowledgement state. */
+    getNotification(notificationId: string): Promise<NotificationDetail>;
+    /**
+     * One bounded long-poll for an ack-required ping. The returned state may
+     * still be `open` when the hold timeout elapses; call again to keep waiting.
+     */
+    waitForAcknowledgement(notificationId: string, input?: WaitForAcknowledgementInput): Promise<AcknowledgementWaitResult>;
     /** One long-poll: resolves as soon as new pings land, or with an empty list at timeout. */
     wait(input?: WaitInput): Promise<WaitResult>;
     /**
@@ -53,7 +61,11 @@ declare class NotificationsApi {
 declare class AgentsApi {
     private readonly http;
     constructor(http: HttpClient);
-    /** Direct agent-to-agent ping, addressed by the target's handle. */
+    /**
+     * @deprecated Retired server-side — always fails with 410
+     * `cross_account_ping_retired`. An agent can only reach the account that
+     * connected it; to reach anyone else, post into a room you both belong to.
+     */
     ping(handle: string, ping: PingInput): Promise<DirectPingResult>;
 }
 declare class ApprovalsApi {
@@ -97,6 +109,49 @@ declare class QuestionsApi {
     /** Withdraw a still-pending Question (409 if it already resolved). */
     cancel(questionId: string): Promise<Question>;
 }
+/**
+ * The Handoff façade: the Agent → one-human loop. Always DIRECT (exactly one
+ * human) and PRIVATE (no other room member can read it). Backed by the ack and
+ * question primitives, so its {@link Handoff.state | state} space is their union
+ * — kept DISTINCT per {@link Handoff.kind | kind}. A negative answer to a
+ * question handoff (e.g. `hold`) is a SUCCESSFUL `answered` result, not an error.
+ *
+ *   const task = await pr.handoffs.requestAck({ prompt, idempotencyKey });
+ *   const result = await pr.handoffs.waitForResult(task.id);
+ *
+ *   const q = await pr.handoffs.ask({ prompt, options: ['deploy', 'hold'], idempotencyKey });
+ */
+declare class HandoffsApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Ask a human to acknowledge (an `ack` handoff). Resolves on the first acknowledgement. */
+    requestAck(input: RequestAckInput): Promise<Handoff>;
+    /**
+     * Ask a human a multi-option question (a `question` handoff). Resolves on the
+     * first tapped answer. Bare-string options normalize to `{ value, label }`.
+     */
+    ask(input: AskInput): Promise<Handoff>;
+    /** Fetch a handoff's current state. */
+    get(id: string): Promise<Handoff>;
+    /**
+     * Block until the handoff resolves (or expires/cancels), looping the bounded
+     * long-poll under the hood. `expired`/`cancelled` and a negative answer (e.g.
+     * `hold`) all surface as normal terminal results — nothing is thrown for them.
+     */
+    waitForResult(id: string, input?: WaitHandoffInput): Promise<Handoff>;
+    /** List the agent's open handoffs or bounded recent history. */
+    list(input?: ListHandoffsInput): Promise<Handoff[]>;
+    /** One bounded long-poll; returns the (possibly still-open) handoff. */
+    private wait;
+    private create;
+}
+/** One-call activation of the bound human's private Agent Inbox. */
+declare class InboxApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Idempotently create/resolve the inbox and deliver its one-time test Question. */
+    ensure(): Promise<AgentInboxEnsureResult>;
+}
 declare class ProfileApi {
     private readonly http;
     constructor(http: HttpClient);
@@ -105,6 +160,28 @@ declare class ProfileApi {
     /** Rotate the agent's handle — the kill-switch for a leaked handle. */
     rotateHandle(): Promise<RotateHandleResult>;
 }
+/**
+ * Live-status streams — a self-updating card on the room members' lock screen.
+ *
+ * Requires the `pingroom:live:write` scope. Free accounts get a small daily
+ * budget of NEW streams; updates and the terminal ping are never charged, so a
+ * card can never be quota-blocked into hanging open.
+ */
+declare class LiveApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Send one stream ping — start, update, or end, chosen by `live_status.state`
+     * and whether the correlation already exists.
+     */
+    push(inviteCode: string, ping: LiveStatusPing): Promise<LiveStatusResult>;
+    /**
+     * Read back a stream this credential started, so a restarted producer can
+     * reconcile instead of opening a duplicate. Returns null when there is no
+     * such stream in the last 24 hours.
+     */
+    get(inviteCode: string, correlationId: string): Promise<LiveStatusSnapshot | null>;
+}
 /** Public, unauthenticated agent directory. */
 declare class DirectoryApi {
     private readonly http;
@@ -120,6 +197,9 @@ export declare class PingRoom {
     readonly agents: AgentsApi;
     readonly approvals: ApprovalsApi;
     readonly questions: QuestionsApi;
+    readonly handoffs: HandoffsApi;
+    readonly inbox: InboxApi;
+    readonly live: LiveApi;
     readonly profile: ProfileApi;
     readonly directory: DirectoryApi;
     readonly mcp: McpClient;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -1,3 +1,4 @@
+import { PingRoomError } from './errors.js';
 import { HttpClient } from './http.js';
 import { sleep } from './internal/async.js';
 import { assertActionNumber, assertStructuredData, requireNonEmpty } from './internal/guards.js';
@@ -119,6 +120,23 @@ class NotificationsApi {
     list(input = {}) {
         return this.http.request('GET', '/api/agent/notifications', { query: dropUndefined({ ...input }) });
     }
+    /** Fetch one visible notification, including its current acknowledgement state. */
+    getNotification(notificationId) {
+        requireNonEmpty(notificationId, 'notificationId');
+        return this.http.request('GET', `/api/agent/notifications/${enc(notificationId)}`);
+    }
+    /**
+     * One bounded long-poll for an ack-required ping. The returned state may
+     * still be `open` when the hold timeout elapses; call again to keep waiting.
+     */
+    waitForAcknowledgement(notificationId, input = {}) {
+        requireNonEmpty(notificationId, 'notificationId');
+        return this.http.request('GET', `/api/agent/notifications/${enc(notificationId)}/ack/wait`, {
+            query: dropUndefined({ timeout: input.timeout }),
+            timeoutMs: waitTimeoutMs(input.timeout),
+            ...(input.signal ? { signal: input.signal } : {}),
+        });
+    }
     /** One long-poll: resolves as soon as new pings land, or with an empty list at timeout. */
     wait(input = {}) {
         return this.http.request('GET', '/api/agent/notifications/wait', {
@@ -176,7 +194,11 @@ class AgentsApi {
     constructor(http) {
         this.http = http;
     }
-    /** Direct agent-to-agent ping, addressed by the target's handle. */
+    /**
+     * @deprecated Retired server-side — always fails with 410
+     * `cross_account_ping_retired`. An agent can only reach the account that
+     * connected it; to reach anyone else, post into a room you both belong to.
+     */
     ping(handle, ping) {
         requireNonEmpty(handle, 'handle');
         assertPing(ping);
@@ -279,6 +301,118 @@ class QuestionsApi {
         return this.http.request('POST', `/api/agent/questions/${enc(questionId)}/cancel`, { body: {} });
     }
 }
+/** A bare string option is shorthand for `{ value, label: value }`. */
+function normalizeHandoffOptions(options) {
+    return options.map((o) => (typeof o === 'string' ? { value: o, label: o } : o));
+}
+/** Terminal states never change again — the wait loop can stop as soon as one lands. */
+function isHandoffTerminal(handoff) {
+    const s = handoff.state;
+    return s === 'acked' || s === 'answered' || s === 'expired' || s === 'cancelled';
+}
+/**
+ * The Handoff façade: the Agent → one-human loop. Always DIRECT (exactly one
+ * human) and PRIVATE (no other room member can read it). Backed by the ack and
+ * question primitives, so its {@link Handoff.state | state} space is their union
+ * — kept DISTINCT per {@link Handoff.kind | kind}. A negative answer to a
+ * question handoff (e.g. `hold`) is a SUCCESSFUL `answered` result, not an error.
+ *
+ *   const task = await pr.handoffs.requestAck({ prompt, idempotencyKey });
+ *   const result = await pr.handoffs.waitForResult(task.id);
+ *
+ *   const q = await pr.handoffs.ask({ prompt, options: ['deploy', 'hold'], idempotencyKey });
+ */
+class HandoffsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Ask a human to acknowledge (an `ack` handoff). Resolves on the first acknowledgement. */
+    requestAck(input) {
+        requireNonEmpty(input.prompt, 'prompt');
+        assertStructuredData(input.data);
+        return this.create('ack', input);
+    }
+    /**
+     * Ask a human a multi-option question (a `question` handoff). Resolves on the
+     * first tapped answer. Bare-string options normalize to `{ value, label }`.
+     */
+    ask(input) {
+        requireNonEmpty(input.prompt, 'prompt');
+        assertStructuredData(input.data);
+        if (!Array.isArray(input.options) || input.options.length < 2 || input.options.length > 4) {
+            throw new PingRoomError('`options` must contain between 2 and 4 entries for a question handoff.', {
+                code: 'invalid_request',
+            });
+        }
+        return this.create('question', input, normalizeHandoffOptions(input.options));
+    }
+    /** Fetch a handoff's current state. */
+    get(id) {
+        requireNonEmpty(id, 'id');
+        return this.http.request('GET', `/api/agent/handoffs/${enc(id)}`);
+    }
+    /**
+     * Block until the handoff resolves (or expires/cancels), looping the bounded
+     * long-poll under the hood. `expired`/`cancelled` and a negative answer (e.g.
+     * `hold`) all surface as normal terminal results — nothing is thrown for them.
+     */
+    async waitForResult(id, input = {}) {
+        requireNonEmpty(id, 'id');
+        for (;;) {
+            if (input.signal?.aborted) {
+                throw input.signal.reason ?? new Error('aborted');
+            }
+            const handoff = await this.wait(id, input);
+            if (isHandoffTerminal(handoff)) {
+                return handoff;
+            }
+        }
+    }
+    /** List the agent's open handoffs or bounded recent history. */
+    async list(input = {}) {
+        const res = await this.http.request('GET', '/api/agent/handoffs', {
+            query: dropUndefined({ state: input.state }),
+        });
+        return res.handoffs ?? [];
+    }
+    /** One bounded long-poll; returns the (possibly still-open) handoff. */
+    wait(id, input) {
+        return this.http.request('GET', `/api/agent/handoffs/${enc(id)}/wait`, {
+            query: dropUndefined({ timeout: input.timeout }),
+            timeoutMs: waitTimeoutMs(input.timeout),
+            ...(input.signal ? { signal: input.signal } : {}),
+        });
+    }
+    create(kind, input, options) {
+        const body = dropUndefined({
+            kind,
+            prompt: input.prompt,
+            audience: { type: 'direct', user_id: input.target ?? 'me' },
+            expires_in: input.expiresIn,
+            urgency: input.urgency,
+            options,
+            correlation_id: input.correlationId,
+            reply_to: input.replyTo,
+            data: input.data,
+        });
+        return this.http.request('POST', '/api/agent/handoffs', {
+            body,
+            ...(input.idempotencyKey ? { headers: { 'Idempotency-Key': input.idempotencyKey } } : {}),
+        });
+    }
+}
+/** One-call activation of the bound human's private Agent Inbox. */
+class InboxApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Idempotently create/resolve the inbox and deliver its one-time test Question. */
+    ensure() {
+        return this.http.request('POST', '/api/agent/inbox/ensure', { body: {} });
+    }
+}
 class ProfileApi {
     http;
     constructor(http) {
@@ -294,6 +428,46 @@ class ProfileApi {
         return this.http.request('POST', '/api/agent/profile/handle/rotate', { body: {} });
     }
 }
+/**
+ * Live-status streams — a self-updating card on the room members' lock screen.
+ *
+ * Requires the `pingroom:live:write` scope. Free accounts get a small daily
+ * budget of NEW streams; updates and the terminal ping are never charged, so a
+ * card can never be quota-blocked into hanging open.
+ */
+class LiveApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Send one stream ping — start, update, or end, chosen by `live_status.state`
+     * and whether the correlation already exists.
+     */
+    push(inviteCode, ping) {
+        requireNonEmpty(inviteCode, 'inviteCode');
+        requireNonEmpty(ping.correlation_id, 'correlation_id');
+        assertStructuredData(ping.data);
+        return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/live`, { body: ping });
+    }
+    /**
+     * Read back a stream this credential started, so a restarted producer can
+     * reconcile instead of opening a duplicate. Returns null when there is no
+     * such stream in the last 24 hours.
+     */
+    async get(inviteCode, correlationId) {
+        requireNonEmpty(inviteCode, 'inviteCode');
+        requireNonEmpty(correlationId, 'correlationId');
+        try {
+            return await this.http.request('GET', `/api/agent/rooms/${enc(inviteCode)}/live/${enc(correlationId)}`);
+        }
+        catch (error) {
+            if (error instanceof PingRoomError && error.status === 404)
+                return null;
+            throw error;
+        }
+    }
+}
 /** Public, unauthenticated agent directory. */
 class DirectoryApi {
     http;
@@ -319,6 +493,9 @@ export class PingRoom {
     agents;
     approvals;
     questions;
+    handoffs;
+    inbox;
+    live;
     profile;
     directory;
     mcp;
@@ -340,6 +517,9 @@ export class PingRoom {
         this.agents = new AgentsApi(this.http);
         this.approvals = new ApprovalsApi(this.http);
         this.questions = new QuestionsApi(this.http);
+        this.handoffs = new HandoffsApi(this.http);
+        this.inbox = new InboxApi(this.http);
+        this.live = new LiveApi(this.http);
         this.profile = new ProfileApi(this.http);
         this.directory = new DirectoryApi(this.http);
         this.mcp = new McpClient(this.http);