@pouchy_ai/companion-sdk 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -12,6 +12,27 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-07-05
+
+### Added
+
+- **`confirmAction(confirmId, approve)`** — resolve a pending sensitive-op
+  confirmation from the embed. Platform **session tokens** only (end-user
+  instances minted via `/v1/sessions`): the embedding app's end user is that
+  account's only human, so the session may approve. First-party user tokens
+  remain observe-only (401) — approval of a real Pouchy user's ops stays on
+  their first-party surface with its biometric step-up. On approve the
+  recorded action runs server-side and its outcome arrives as a normal
+  `companion.message`. This is the run path for the platform's new
+  **confirm-gated custom skills** (POST / credentialed tools, keys served
+  from the project credential vault).
+- **`pendingConfirms()`** — the session's still-pending confirmations
+  (display-safe: `confirmId`, `scope`, `summary`, `createdAt`), for rebuilding
+  a confirm card after a reload. Same session-token-only auth.
+- **`PendingConfirm`** type export; `ConfirmRequestPayload` /
+  `onConfirmRequest` docs updated for the two-token model. No wire-protocol
+  change (`PROTOCOL_VERSION` stays `1`); additive surface.
+
 ## [0.11.0] - 2026-07-02
 
 ### Added
@@ -116,7 +137,8 @@ self-hosted/CDN build; this entry captures the surface that ships publicly.
 - **Versioned wire protocol.** `PROTOCOL_VERSION = 1`, kept in lockstep with the
   server by `protocol.drift.test.ts` (fails CI on divergence).
 
-[Unreleased]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.11.0...HEAD
+[Unreleased]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.12.0...HEAD
+[0.12.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.11.0...companion-sdk-v0.12.0
 [0.11.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.10.1...companion-sdk-v0.11.0
 [0.10.1]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.10.0...companion-sdk-v0.10.1
 [0.10.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.9.0...companion-sdk-v0.10.0

package/README.md

@@ -47,7 +47,7 @@ Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers:
 | `onRender(fn)` | `companion.ui_action` | **Instant UI** — draw `payload.interface` (platform-neutral genui schema) with your own renderer (web / iOS / Android / CLI). Needs `ui.render` |
 | `onInterfaceUpdate(fn)` | `companion.ui_update` | live `{key,value}` update to an already-rendered panel (no rebuild) |
 | `onSocialMessage(fn)` | `companion.social_message` | inbound A2A friend message, delivered cross-app. Needs `social.message` |
-| `onConfirmRequest(fn)` | `companion.confirm_request` | observe a sensitive-op approval (`stepUp:true` ⇒ the first-party surface should gate it with a biometric). Observe-only — approval is first-party |
+| `onConfirmRequest(fn)` | `companion.confirm_request` | a sensitive-op approval request. **Platform session tokens** (your end users): show your own confirm card and resolve it with `confirmAction` — this is how confirm-gated custom skills (POST / credentialed) run. First-party user tokens: observe-only — approval stays first-party (where the `stepUp:true` biometric gate lives) |
 | `onAudio(fn)` | `companion.audio` | TTS clip (non-call modality) |
 | `onExpression(fn)` | `companion.expression` | avatar viseme / expression / gesture |
 | `onUsage(fn)` | `control.usage` | per-token metering echo |

package/dist/call.js

@@ -153,8 +153,35 @@ export async function openCompanionCall(creds, opts = {}, bridge) {
         ? openOpenAICall(creds, opts, bridge)
         : openConvaiCall(creds, opts, bridge);
 }
+// Connect-step timeouts (mirror the first-party realtime path). Without them a
+// stuck mic (Android WebView holding the device) or a hung SDP exchange hangs
+// the connect promise forever — and if gUM already resolved, with a hot mic.
+const GUM_TIMEOUT_MS = 10_000;
+const SDP_TIMEOUT_MS = 8_000;
+/** getUserMedia with a timeout. If the timeout wins, a late-resolving mic is
+ *  stopped so a slow permission grant can't leave the device recording after
+ *  we've already given up on the call. */
+async function getMicWithTimeout() {
+    let timedOut = false;
+    const micPromise = navigator.mediaDevices.getUserMedia({ audio: true });
+    micPromise
+        .then((m) => {
+        if (timedOut)
+            m.getTracks().forEach((t) => t.stop());
+    })
+        .catch(() => { });
+    const timeout = new Promise((_, reject) => setTimeout(() => {
+        timedOut = true;
+        reject(new Error('microphone request timed out'));
+    }, GUM_TIMEOUT_MS));
+    return Promise.race([micPromise, timeout]);
+}
 // ── OpenAI Realtime — self-contained WebRTC ─────────────────────────────────
 async function openOpenAICall(creds, opts, bridge) {
+    // Acquire the mic FIRST (with a timeout): if gUM fails/times out there is no
+    // RTCPeerConnection yet to leak. Creating pc before gUM (the old order) leaked
+    // a peer connection on every permission denial.
+    const mic = await getMicWithTimeout();
     const pc = new RTCPeerConnection();
     const audioEl = opts.audioElement ?? new Audio();
     audioEl.autoplay = true;
@@ -162,7 +189,6 @@ async function openOpenAICall(creds, opts, bridge) {
         audioEl.srcObject = e.streams[0];
         void audioEl.play().catch(() => { });
     };
-    const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
     for (const track of mic.getAudioTracks())
         pc.addTrack(track, mic);
     // Half-duplex mic (mirrors the first-party realtime path, #1524): on a phone
@@ -290,14 +316,33 @@ async function openOpenAICall(creds, opts, bridge) {
     };
     const offer = await pc.createOffer();
     await pc.setLocalDescription(offer);
-    const res = await fetch(OPENAI_REALTIME_CALLS, {
-        method: 'POST',
-        headers: { Authorization: `Bearer ${creds.clientSecret}`, 'Content-Type': 'application/sdp' },
-        body: offer.sdp
-    });
-    if (!res.ok) {
+    // Bound the SDP exchange so a hung network can't leave the pc + hot mic open
+    // forever. On any failure, close both before throwing.
+    const sdpAbort = new AbortController();
+    const sdpTimer = setTimeout(() => sdpAbort.abort(), SDP_TIMEOUT_MS);
+    const cleanupPartial = () => {
         pc.close();
         mic.getTracks().forEach((t) => t.stop());
+    };
+    let res;
+    try {
+        res = await fetch(OPENAI_REALTIME_CALLS, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${creds.clientSecret}`, 'Content-Type': 'application/sdp' },
+            body: offer.sdp,
+            signal: sdpAbort.signal
+        });
+    }
+    catch {
+        clearTimeout(sdpTimer);
+        cleanupPartial();
+        throw new Error(sdpAbort.signal.aborted
+            ? 'OpenAI Realtime SDP exchange timed out'
+            : 'OpenAI Realtime SDP exchange failed');
+    }
+    clearTimeout(sdpTimer);
+    if (!res.ok) {
+        cleanupPartial();
         throw new Error(`OpenAI Realtime SDP exchange failed (${res.status})`);
     }
     await pc.setRemoteDescription({ type: 'answer', sdp: await res.text() });
@@ -367,6 +412,23 @@ async function openOpenAICall(creds, opts, bridge) {
             }, DISCONNECT_GRACE_MS);
         }
     };
+    // Data-channel liveness (mirrors the first-party dataChannel.onclose/onerror).
+    // A dc-only death — the channel closes/errors while pc.connectionState still
+    // reads 'connected' — otherwise goes undetected and the mic stays hot.
+    // teardown flips `closed` before it calls dc.close(), so a normal teardown's
+    // own channel close is guarded out here (no double-fire / spurious error).
+    dc.onclose = () => {
+        if (closed)
+            return;
+        teardown();
+        opts.onError?.(new Error('call data channel closed'));
+    };
+    dc.onerror = () => {
+        if (closed)
+            return;
+        teardown();
+        opts.onError?.(new Error('call data channel error'));
+    };
     return {
         provider: 'openai-realtime',
         close: teardown,
@@ -485,6 +547,21 @@ async function openConvaiCall(creds, opts, bridge) {
                 /* session not yet established */
             }
             opts.onError?.(new Error('call disconnected'));
+        },
+        // Liveness backstop (first-party F3): a transport wedge can flip status to
+        // 'disconnected' WITHOUT firing onDisconnect, leaving "connected" with a hot
+        // mic forever. Treat a disconnected status the same as onDisconnect.
+        onStatusChange: ({ status }) => {
+            if (closed || status !== 'disconnected')
+                return;
+            closed = true;
+            try {
+                void conv.endSession().catch(() => { });
+            }
+            catch {
+                /* session not yet established */
+            }
+            opts.onError?.(new Error('call disconnected'));
         }
     });
     return {

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundType, RenderInterfacePayload, SocialMessagePayload, UsagePayload, WorldStateEvent } from './protocol.js';
+import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundType, PendingConfirm, RenderInterfacePayload, SocialMessagePayload, UsagePayload, WorldStateEvent } from './protocol.js';
 /** Ergonomic world-state input: a WorldStateEvent with the CloudEvents plumbing
  *  (specversion / id / source) optional — sendWorldState fills them. */
 export type WorldStateInput<D = unknown> = Omit<WorldStateEvent<D>, 'specversion' | 'id' | 'source'> & Partial<Pick<WorldStateEvent<D>, 'specversion' | 'id' | 'source'>>;
@@ -331,14 +331,36 @@ export declare class CompanionClient {
     /** Convenience: subscribe to the per-token metering echo (control.usage) for a
      *  usage / billing view. */
     onUsage(handler: (payload: UsagePayload, envelope: CompanionEnvelope) => void): () => void;
-    /** Convenience: OBSERVE sensitive-op confirmation requests
+    /** Convenience: subscribe to sensitive-op confirmation requests
      *  (companion.confirm_request) — a payment, skill run, or friend message the
-     *  companion wants the user to approve. Use it to surface the pending approval
-     *  in your UI (e.g. "open Pouchy to approve"). NOTE: an embed cannot approve —
-     *  approval is authed as the first-party Pouchy user (their app / a hosted
-     *  confirm page), which is also where a biometric (Face ID / passkey) gate
-     *  lives. This handler is observe-only. */
+     *  companion wants the user to approve. Use it to surface the pending
+     *  approval in your UI.
+     *
+     *  Whether YOU can resolve it depends on the token:
+     *  - **Platform session tokens** (minted via /v1/sessions for your end
+     *    users): show your own confirm card and call `confirmAction` — your end
+     *    user is the account's human, so the session may approve. This is how
+     *    confirm-gated custom skills (POST / credentialed) run.
+     *  - **First-party user tokens** (Login-with-Pouchy PATs): observe-only —
+     *    approval is authed as the Pouchy user (their app / a hosted confirm
+     *    page), which is also where the biometric (Face ID / passkey) gate
+     *    lives. `confirmAction` returns 401 on these tokens. */
     onConfirmRequest(handler: (payload: ConfirmRequestPayload, envelope: CompanionEnvelope) => void): () => void;
+    /** Resolve a pending confirmation (platform session tokens only — see
+     *  `onConfirmRequest`). Show the user what they're approving (the event's
+     *  `summary`), collect an explicit tap, then pass their decision here. On
+     *  approval the recorded action runs server-side and its outcome arrives as
+     *  a normal companion.message; a denial emits a brief decline. One-time:
+     *  re-resolving a settled confirmId fails with 409. */
+    confirmAction(confirmId: string, approve: boolean): Promise<{
+        ok: boolean;
+        status: 'approved' | 'denied';
+    }>;
+    /** The session's still-pending confirmations (display-safe: id, summary,
+     *  scope, timestamps — never raw args). Use it to rebuild your confirm card
+     *  after a reload, since confirm_request events are not replayed. Platform
+     *  session tokens only, like `confirmAction`. */
+    pendingConfirms(): Promise<PendingConfirm[]>;
     /** Convenience: subscribe to live updates of an already-rendered Instant UI
      *  panel (companion.ui_update). Apply each `{ key, value }` to the panel's state
      *  bag and re-evaluate bound displays — no rebuild. */

package/dist/client.js

@@ -487,13 +487,20 @@ export class CompanionClient {
     onUsage(handler) {
         return this.on('control.usage', (env) => handler(env.payload, env));
     }
-    /** Convenience: OBSERVE sensitive-op confirmation requests
+    /** Convenience: subscribe to sensitive-op confirmation requests
      *  (companion.confirm_request) — a payment, skill run, or friend message the
-     *  companion wants the user to approve. Use it to surface the pending approval
-     *  in your UI (e.g. "open Pouchy to approve"). NOTE: an embed cannot approve —
-     *  approval is authed as the first-party Pouchy user (their app / a hosted
-     *  confirm page), which is also where a biometric (Face ID / passkey) gate
-     *  lives. This handler is observe-only. */
+     *  companion wants the user to approve. Use it to surface the pending
+     *  approval in your UI.
+     *
+     *  Whether YOU can resolve it depends on the token:
+     *  - **Platform session tokens** (minted via /v1/sessions for your end
+     *    users): show your own confirm card and call `confirmAction` — your end
+     *    user is the account's human, so the session may approve. This is how
+     *    confirm-gated custom skills (POST / credentialed) run.
+     *  - **First-party user tokens** (Login-with-Pouchy PATs): observe-only —
+     *    approval is authed as the Pouchy user (their app / a hosted confirm
+     *    page), which is also where the biometric (Face ID / passkey) gate
+     *    lives. `confirmAction` returns 401 on these tokens. */
     onConfirmRequest(handler) {
         return this.on('companion.confirm_request', (env) => {
             const p = env.payload;
@@ -501,6 +508,29 @@ export class CompanionClient {
                 handler(p, env);
         });
     }
+    /** Resolve a pending confirmation (platform session tokens only — see
+     *  `onConfirmRequest`). Show the user what they're approving (the event's
+     *  `summary`), collect an explicit tap, then pass their decision here. On
+     *  approval the recorded action runs server-side and its outcome arrives as
+     *  a normal companion.message; a denial emits a brief decline. One-time:
+     *  re-resolving a settled confirmId fails with 409. */
+    async confirmAction(confirmId, approve) {
+        const sessionId = this.requireSession();
+        return this.postJson(`/api/companion/session/${encodeURIComponent(sessionId)}/confirm`, { confirmId, approve });
+    }
+    /** The session's still-pending confirmations (display-safe: id, summary,
+     *  scope, timestamps — never raw args). Use it to rebuild your confirm card
+     *  after a reload, since confirm_request events are not replayed. Platform
+     *  session tokens only, like `confirmAction`. */
+    async pendingConfirms() {
+        const sessionId = this.requireSession();
+        const res = await this.doFetch(this.url(`/api/companion/session/${encodeURIComponent(sessionId)}/confirm`), { headers: { Authorization: `Bearer ${this.opts.token}` } });
+        const json = (await res.json().catch(() => null));
+        if (!res.ok || !json || json.ok === false) {
+            throw new CompanionError(json?.error || `pending confirms failed (${res.status})`, res.status);
+        }
+        return json.pending ?? [];
+    }
     /** Convenience: subscribe to live updates of an already-rendered Instant UI
      *  panel (companion.ui_update). Apply each `{ key, value }` to the panel's state
      *  bag and re-evaluate bound displays — no rebuild. */
@@ -543,40 +573,66 @@ export class CompanionClient {
     async wsLoop(WS) {
         const id = this.requireSession();
         const { deriveWsStreamUrl, decodeWsMessage } = await import('./ws-transport.js');
-        try {
-            await new Promise((resolve, reject) => {
-                const ws = new WS(deriveWsStreamUrl(this.opts.baseUrl, id, this.opts.token, this.cursor));
-                const done = (err) => (err ? reject(err) : resolve());
-                ws.onmessage = (ev) => {
-                    if (!this.streaming) {
-                        ws.close();
-                        return;
-                    }
-                    const raw = typeof ev.data === 'string' ? ev.data : '';
-                    const frame = raw ? decodeWsMessage(raw) : null;
-                    if (frame)
-                        this.handleFrame(frame.event, frame.data);
-                };
-                ws.onerror = () => done(new Error('companion ws error'));
-                ws.onclose = () => done();
-                // Stopping the stream closes the socket.
-                const poll = setInterval(() => {
-                    if (!this.streaming) {
-                        clearInterval(poll);
+        // Reconnect across CLEAN closes (a WS gateway with a bounded lifetime, like
+        // the SSE endpoint's window) just as the SSE loop does — a graceful close
+        // must not silently end reply delivery. Only a connection ERROR degrades to
+        // SSE, and only once. Each connection's poll timer + socket are released in
+        // the settle() finally so neither leaks after fallback/reconnect.
+        while (this.streaming) {
+            let errored = false;
+            try {
+                await new Promise((resolve, reject) => {
+                    const ws = new WS(deriveWsStreamUrl(this.opts.baseUrl, id, this.opts.token, this.cursor));
+                    let poll;
+                    let settled = false;
+                    const settle = (err) => {
+                        if (poll) {
+                            clearInterval(poll);
+                            poll = undefined;
+                        }
                         try {
                             ws.close();
                         }
                         catch {
                             /* already closing */
                         }
-                    }
-                }, 250);
-            });
-        }
-        catch {
-            // Socket unavailable / rejected — degrade to the robust SSE loop.
-            if (this.streaming)
-                await this.loop();
+                        if (settled)
+                            return;
+                        settled = true;
+                        if (err)
+                            reject(err);
+                        else
+                            resolve();
+                    };
+                    ws.onmessage = (ev) => {
+                        if (!this.streaming) {
+                            settle();
+                            return;
+                        }
+                        const raw = typeof ev.data === 'string' ? ev.data : '';
+                        const frame = raw ? decodeWsMessage(raw) : null;
+                        if (frame)
+                            this.handleFrame(frame.event, frame.data);
+                    };
+                    ws.onerror = () => settle(new Error('companion ws error'));
+                    ws.onclose = () => settle();
+                    // Stopping the stream closes the socket + clears this timer.
+                    poll = setInterval(() => {
+                        if (!this.streaming)
+                            settle();
+                    }, 250);
+                });
+            }
+            catch {
+                errored = true;
+            }
+            if (errored) {
+                // Socket unavailable / rejected — degrade to the robust SSE loop (once).
+                if (this.streaming)
+                    await this.loop();
+                return;
+            }
+            // Clean close: the while-guard reconnects if still streaming, else exits.
         }
     }
     /** Stop the event stream. */

package/dist/index.d.ts

@@ -3,6 +3,6 @@ export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js
 export type { CompanionClientOptions, HelloAck, RecalledMemory, CallCredentials, CompanionToolDecl, WorldStateInput, CompanionAvatar, BrandIconSize } from './client.js';
 export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_VISUAL_TOOLS, AVATAR_VISUAL_TOOL_NAMES } from './call.js';
 export type { CompanionCall, CompanionCallOptions, VoiceToolBridge } from './call.js';
-export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, AudioClipPayload, ExpressionPayload, UsagePayload } from './protocol.js';
+export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, PendingConfirm, AudioClipPayload, ExpressionPayload, UsagePayload } from './protocol.js';
 /** Create a companion client. */
 export declare function createCompanion(opts: CompanionClientOptions): CompanionClient;

package/dist/protocol.d.ts

@@ -38,11 +38,14 @@ export interface RenderInterfacePayload {
 }
 /** Payload of a `companion.confirm_request` event — the companion is asking the
  *  user to approve a sensitive op (a payment, a skill run, a friend message).
- *  An embed may OBSERVE this to surface the pending approval in its own UI, but
- *  it CANNOT approve: approval is authed as the first-party Pouchy user (their
- *  app / a hosted confirm page), so a third-party DOM can never confirm a spend.
- *  A first-party native host can gate that approval behind a biometric (Face ID
- *  / passkey) — see docs/companion-wallet-noncustodial.md. */
+ *  Who may approve depends on the token: a PLATFORM SESSION TOKEN (an end-user
+ *  instance minted via /v1/sessions) resolves it directly with
+ *  `client.confirmAction` — the embedding app's end user is that account's
+ *  human. A first-party user's token can only OBSERVE: approval of a real
+ *  Pouchy user's ops is authed as that user (their app / a hosted confirm
+ *  page), so a third-party DOM can never confirm a spend, and the first-party
+ *  host can gate approval behind a biometric (Face ID / passkey) — see
+ *  docs/companion-wallet-noncustodial.md. */
 export interface ConfirmRequestPayload {
     /** Opaque id the first-party surface passes to the confirm endpoint. */
     confirmId: string;
@@ -56,6 +59,17 @@ export interface ConfirmRequestPayload {
      *  Cryptographic enforcement is server-side follow-up; this is the host's cue. */
     stepUp?: boolean;
 }
+/** One still-pending confirmation, as returned by `client.pendingConfirms()` —
+ *  display-safe (never the recorded tool call or its raw args). */
+export interface PendingConfirm {
+    confirmId: string;
+    /** The scope of the op needing approval (e.g. `skills.execute`). */
+    scope: string;
+    /** A human, user-facing summary of what approving will do. */
+    summary: string;
+    /** Epoch ms when the companion asked. */
+    createdAt: number;
+}
 /** Payload of a `companion.ui_update` event — a live change to an
  *  already-rendered Instant UI panel: write each `{ key, value }` into the
  *  panel's state bag (re-evaluating templates / progress / `when`), without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Embed the Pouchy companion — chat, voice, tools, memory, live world-state, instant UI, and agent-to-agent messaging — in any app, game, or site.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",