@pouchy_ai/companion-sdk 0.28.0 → 0.28.1

package/CHANGELOG.md

@@ -12,6 +12,42 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.28.1] - 2026-07-12
+
+### Fixed
+
+- **WebSocket reconnect storm on short-lived connections.** A gateway that
+  accepted the socket and immediately closed it cleanly (auth-expressed-as-
+  close, LB idle policy, misconfigured proxy) made `stream: 'websocket'`
+  reconnect in a zero-delay hot loop. A connection that lived under ~2s now
+  sits out the same 500ms→8s doubling backoff the SSE loop uses (a long-lived
+  connection still reconnects immediately).
+- **A throwing event handler no longer poisons the stream loop.** Handler
+  exceptions used to propagate into the SSE/WS loop's catch — read as a
+  CONNECTION failure (backoff + reconnect + cursor replay) — and, on the
+  `sendText` local-emit path, rejected a `sendText` whose turn had actually
+  succeeded. Handlers are now isolated per-call (logged, remaining handlers
+  still run).
+- **Custom voice-tool bridges may throw.** With `openCompanionCall` and a
+  bring-your-own bridge whose `invoke` rejected, the model never received a
+  `function_call_output` — the voice turn hung until the provider timeout,
+  plus an unhandled rejection. A rejecting bridge now answers the model with
+  `{ ok: false, error }`.
+- Timer hygiene: the 20s voice-tool timeout and the 10s microphone-acquire
+  timeout are now cleared on normal completion instead of lingering.
+
+### Changed
+
+- **`CompanionErrorCodeValue` is now DERIVED** from the drift-tested server
+  vocabulary plus the SDK-synthesized list, instead of hand-retyped — the old
+  copy had silently drifted 5 codes behind (`not_representative`,
+  `call_unsupported`, `call_connect_failed`, `call_dependency_missing` now
+  autocomplete). A new drift test pins every `new CompanionError(...)` call
+  site to a declared code. Types-only; no runtime behavior change.
+- `package.json` now declares `"engines": { "node": ">=18" }` and the README
+  documents that the package ships **ESM-only** (modern bundlers and Node ≥ 18
+  consume it as-is; there is no CJS build).
+
 ## [0.28.0] - 2026-07-12
 
 ### Added
@@ -563,7 +599,24 @@ 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.12.1...HEAD
+[Unreleased]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.28.1...HEAD
+[0.28.1]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.28.0...companion-sdk-v0.28.1
+[0.28.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.27.0...companion-sdk-v0.28.0
+[0.27.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.26.1...companion-sdk-v0.27.0
+[0.26.1]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.26.0...companion-sdk-v0.26.1
+[0.26.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.25.0...companion-sdk-v0.26.0
+[0.25.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.24.0...companion-sdk-v0.25.0
+[0.24.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.23.0...companion-sdk-v0.24.0
+[0.23.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.22.0...companion-sdk-v0.23.0
+[0.22.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.21.0...companion-sdk-v0.22.0
+[0.21.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.20.0...companion-sdk-v0.21.0
+[0.20.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.19.1...companion-sdk-v0.20.0
+[0.19.1]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.19.0...companion-sdk-v0.19.1
+[0.19.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.18.1...companion-sdk-v0.19.0
+[0.18.1]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.18.0...companion-sdk-v0.18.1
+[0.18.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.17.0...companion-sdk-v0.18.0
+[0.17.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.13.0...companion-sdk-v0.17.0
+[0.13.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.12.1...companion-sdk-v0.13.0
 [0.12.1]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.12.0...companion-sdk-v0.12.1
 [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

package/README.md

@@ -16,6 +16,10 @@ npm i @pouchy_ai/companion-sdk
 
 No bundler? Pull it from a CDN via an import map instead — see
 [`docs/companion-integration-faq.md`](../../docs/companion-integration-faq.md).
+
+The package ships **ESM-only** (`"type": "module"`, no CJS build). Every modern
+bundler and Node ≥ 18 consumes it as-is; on Node ≥ 20.17 even `require()` of the
+ESM entry works natively.
 Changes per release are tracked in [`CHANGELOG.md`](./CHANGELOG.md).
 
 **React?** [`@pouchy_ai/react`](../react-sdk/README.md) wraps this SDK in a
@@ -76,6 +80,7 @@ Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers:
 | `onExpression(fn)` | `companion.expression` | avatar viseme / expression / gesture. _(reserved — not emitted yet)_ |
 | `onVoiceInject(fn)` | `companion.voice_inject` | `fn({text, speak})` — a `voiceRelevant` world-state line to say aloud during a live call; route `text` to your voice session when `speak` |
 | `onTyping(fn)` | `companion.typing` | activity indicator — `fn({active})` fires `true` when a turn starts working and `false` when it finishes / pauses, spanning the tool-loop / thinking phase before the first text delta. Drive a "typing…" state |
+| `on('control.call_ready', fn)` | `control.call_ready` | a voice call is ready — the stream echo of `startCall`'s accept. Deliberately **secret-free** (`{ provider, agentId/model, voice, … }` — the actual WebRTC credentials only ride the `startCall` HTTP response); useful for UI state on surfaces that didn't initiate the call |
 | `onUsage(fn)` | `control.usage` | per-token metering echo. _(reserved — not emitted yet)_ |
 | `onError(fn)` | `control.error` | agent / stream errors — `agent_error` (server-side turn failed after accept; safe to re-send), `call_mint_failed` (voice-credential mint failed — retry later or fall back to text) or the SDK-synthesized `stream_unauthorized` (stream 401 exhausted reconnects — refresh the token, `start()` again) |
 

package/dist/call.js

@@ -175,11 +175,18 @@ async function getMicWithTimeout() {
             m.getTracks().forEach((t) => t.stop());
     })
         .catch(() => { });
-    const timeout = new Promise((_, reject) => setTimeout(() => {
-        timedOut = true;
-        reject(new CompanionError('microphone request timed out', 0, 'call_connect_failed'));
-    }, GUM_TIMEOUT_MS));
-    return Promise.race([micPromise, timeout]);
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            timedOut = true;
+            reject(new CompanionError('microphone request timed out', 0, 'call_connect_failed'));
+        }, GUM_TIMEOUT_MS);
+    });
+    // Clear the timer when the mic wins the race — it held a live 10s closure.
+    return Promise.race([micPromise, timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
 }
 // ── OpenAI Realtime — self-contained WebRTC ─────────────────────────────────
 async function openOpenAICall(creds, opts, bridge) {
@@ -289,7 +296,14 @@ async function openOpenAICall(creds, opts, bridge) {
             callNames.delete(callId);
             if (name && bridge.tools.some((t) => t.name === name)) {
                 const argsText = typeof msg.arguments === 'string' ? msg.arguments : '{}';
-                void bridge.invoke(name, argsText).then((output) => {
+                // invokeVoiceTool never rejects, but openCompanionCall is a public
+                // export (bring-your-own bridge) — a throwing consumer bridge must
+                // still answer the model, or the voice turn hangs until provider
+                // timeout (plus an unhandled rejection).
+                void bridge
+                    .invoke(name, argsText)
+                    .catch((e) => JSON.stringify({ ok: false, error: e instanceof Error ? e.message : 'tool failed' }))
+                    .then((output) => {
                     try {
                         dc.send(JSON.stringify({
                             type: 'conversation.item.create',

package/dist/client.js

@@ -674,15 +674,20 @@ export class CompanionClient {
         const id = `vc_${this.randomId()}`;
         return new Promise((resolve) => {
             let settled = false;
+            let timer;
             const finish = (out) => {
                 if (settled)
                     return;
                 settled = true;
+                // Clear on normal completion too — a chatty tool-using call was
+                // accumulating a live 20s timer (+closure) per invocation.
+                if (timer)
+                    clearTimeout(timer);
                 this.pendingVoiceTools.delete(id);
                 resolve(out);
             };
             this.pendingVoiceTools.set(id, finish);
-            setTimeout(() => finish(JSON.stringify({ ok: false, error: 'tool result timed out' })), 20_000);
+            timer = setTimeout(() => finish(JSON.stringify({ ok: false, error: 'tool result timed out' })), 20_000);
             this.emit({
                 v: PROTOCOL_VERSION,
                 id: `evt_${this.randomId()}`,
@@ -1040,8 +1045,10 @@ export class CompanionClient {
         // 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.
+        let backoff = 500;
         while (this.streaming && gen === this.streamGen) {
             let errored = false;
+            const connectedAt = Date.now();
             try {
                 await new Promise((resolve, reject) => {
                     const ws = new WS(deriveWsStreamUrl(this.opts.baseUrl, id, this.opts.token, this.cursor));
@@ -1095,6 +1102,17 @@ export class CompanionClient {
                 return;
             }
             // Clean close: the while-guard reconnects if still streaming, else exits.
+            // A SHORT-LIVED connection (gateway that accepts then immediately
+            // closes — auth-as-close, LB idle policy, misconfigured proxy) must
+            // back off like the SSE loop, or this reconnects in a zero-delay hot
+            // loop. A connection that lived a while resets the backoff.
+            if (Date.now() - connectedAt < 2000) {
+                await this.sleep(backoff);
+                backoff = Math.min(backoff * 2, 8000);
+            }
+            else {
+                backoff = 500;
+            }
         }
     }
     /** Stop the event stream. */
@@ -1137,10 +1155,27 @@ export class CompanionClient {
                 return;
             }
         }
-        for (const h of this.handlers.get(envelope.type) ?? [])
-            h(envelope);
-        for (const h of this.handlers.get('*') ?? [])
-            h(envelope);
+        // Each handler is isolated: a THROWING consumer handler must not skip the
+        // remaining handlers, and — worse — it used to propagate up through the
+        // stream loop's catch, which read it as a CONNECTION failure (backoff +
+        // reconnect + cursor replay); on the sendText local-emit path it rejected
+        // a sendText whose turn had actually succeeded.
+        for (const h of this.handlers.get(envelope.type) ?? []) {
+            try {
+                h(envelope);
+            }
+            catch (e) {
+                console.error('[companion-sdk] event handler threw', e);
+            }
+        }
+        for (const h of this.handlers.get('*') ?? []) {
+            try {
+                h(envelope);
+            }
+            catch (e) {
+                console.error('[companion-sdk] event handler threw', e);
+            }
+        }
     }
     handleFrame(event, data) {
         if (event === 'reconnect') {

package/dist/errors.d.ts

@@ -1,13 +1,22 @@
+import type { CompanionErrorCode } from './protocol.js';
+/** Codes the SDK itself synthesizes (status 0 — never sent by the server).
+ *  Runtime array so the drift test can assert every `new CompanionError(...)`
+ *  call site uses a declared code; APPEND-ONLY like the server vocabulary. */
+export declare const SDK_SYNTHESIZED_ERROR_CODES: readonly ["reply_timeout", "needs_event_stream", "not_connected", "missing_option", "not_representative", "call_unsupported", "call_connect_failed", "call_dependency_missing"];
+export type SdkSynthesizedErrorCode = (typeof SDK_SYNTHESIZED_ERROR_CODES)[number];
 /** Thrown by every helper on an HTTP or client-side failure. `status` is the
  *  HTTP status (0 for client-synthesized failures — timeouts, unsupported
  *  environments, missing optional deps); `code` is machine-switchable when
  *  the server (or the SDK itself) names a cause. On a `rate_limited` (429)
  *  failure, `retryAfter` carries the server's Retry-After in SECONDS so a
  *  consumer can back off precisely instead of guessing. */
-/** `CompanionError.code` values: the server vocabulary (COMPANION_ERROR_CODES)
- *  plus the SDK-synthesized ones. The `(string & {})` arm keeps the type open
- *  for codes newer than this SDK build while preserving autocomplete. */
-export type CompanionErrorCodeValue = 'missing_token' | 'invalid_token' | 'missing_scope' | 'invalid_request' | 'session_not_found' | 'turn_pending' | 'no_pending_tools' | 'unknown_call' | 'payload_too_large' | 'rate_limited' | 'forbidden' | 'unavailable' | 'confirm_not_found' | 'confirm_resolved' | 'step_up_required' | 'step_up_failed' | 'reply_timeout' | 'needs_event_stream' | 'not_connected' | 'missing_option' | (string & {});
+/** `CompanionError.code` values: the server vocabulary (COMPANION_ERROR_CODES,
+ *  drift-tested against api-error.ts) plus the SDK-synthesized ones — DERIVED
+ *  from those runtime lists rather than hand-retyped, so a new code can never
+ *  silently miss this union again (the old copy had drifted 5 codes behind).
+ *  The `(string & {})` arm keeps the type open for codes newer than this SDK
+ *  build while preserving autocomplete. */
+export type CompanionErrorCodeValue = CompanionErrorCode | SdkSynthesizedErrorCode | (string & {});
 export declare class CompanionError extends Error {
     status: number;
     code?: CompanionErrorCodeValue;

package/dist/errors.js

@@ -3,6 +3,19 @@
 // Lives in its own module so call.ts can use it without a runtime cycle
 // through client.ts (client.ts re-exports it, keeping the public import path
 // `@pouchy_ai/companion-sdk` → `CompanionError` unchanged).
+/** Codes the SDK itself synthesizes (status 0 — never sent by the server).
+ *  Runtime array so the drift test can assert every `new CompanionError(...)`
+ *  call site uses a declared code; APPEND-ONLY like the server vocabulary. */
+export const SDK_SYNTHESIZED_ERROR_CODES = [
+    'reply_timeout', // awaitReply/replyTimeoutMs elapsed before the reply
+    'needs_event_stream', // turn paused on tools but start() was never called
+    'not_connected', // a call/stream helper was used before connect
+    'missing_option', // a required option was omitted (e.g. sessionId)
+    'not_representative', // pairVisitor on a non-representative token
+    'call_unsupported', // startCall on a server/provider without voice
+    'call_connect_failed', // WebRTC/provider handshake failed
+    'call_dependency_missing' // optional voice dependency not installed
+];
 export class CompanionError extends Error {
     status;
     code;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.28.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.",
+  "version": "0.28.1",
+  "description": "Embed the Pouchy companion \u2014 chat, voice, tools, memory, live world-state, instant UI, and agent-to-agent messaging \u2014 in any app, game, or site.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://pouchy.ai",
@@ -28,6 +28,9 @@
     "LICENSE"
   ],
   "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/fix-esm-extensions.mjs",
     "build:cdn": "esbuild ../../src/lib/companion-sdk/index.ts --bundle --format=esm --platform=browser --external:@elevenlabs/client --legal-comments=none --outfile=cdn/companion-sdk.js && node scripts/cdn-banner.mjs",