@pouchy_ai/companion-sdk 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -12,6 +12,79 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.30.0] - 2026-07-12
+
+No breaking changes despite the minor bump — everything here is additive
+surface (which this repo's house policy ships as `0.x.0`).
+
+### Added
+
+- **Typed `control.error` code vocabulary.** New runtime export
+  `CONTROL_ERROR_CODES` — the server-emitted stream-plane codes
+  (`agent_error`, `call_mint_failed`) — plus the types `ControlErrorCode`,
+  `ControlErrorPayload`, and the open union `ControlErrorCodeValue` (server
+  codes + the SDK-synthesized `stream_unauthorized` + a forward-compat string
+  arm, same doctrine as `CompanionErrorCodeValue`). `onError`'s handler now
+  sees `code: ControlErrorCodeValue` instead of a bare `string`, so a `switch`
+  on it autocompletes. Drift-tested two ways: the SDK list must equal the
+  server list, AND every `control.error` emit site's code literal (server and
+  SDK) must be declared — a new site inventing a code fails CI.
+- **`on()` narrows the envelope payload per event name.** New
+  `OutboundPayloadMap` + a generic overload:
+  `on('companion.typing', (env) => env.payload.active)` type-checks without a
+  cast; `on('*')` keeps the untyped envelope. Type-only — zero runtime change.
+  New wire-payload types exported along the way: `HelloAckPayload`,
+  `CallReadyPayload`, `ControlErrorPayload`.
+- **Stream-state observability.** `client.streamState` +
+  `onStreamStateChange((state, prev) => …)` with
+  `'idle' | 'connecting' | 'connected' | 'reconnecting' | 'degraded_sse' |
+  'stopped'` (`CompanionStreamState`) — including the previously invisible
+  WebSocket→SSE degrade (`degraded_sse`) and the permanent-401/403 stop. Hosts
+  no longer hand-roll a connection enum around `onMessage` traffic.
+
+### Fixed
+
+- **Reconnect backoff now carries jitter (additive, 0–25%)** in both the SSE
+  and WebSocket receive loops, so a fleet of embeds doesn't reconnect in
+  lockstep after a server deploy/restart (thundering herd).
+- **`Retry-After` HTTP-date form is parsed.** RFC 9110 allows a date form
+  (proxies/CDNs emit it); it used to read as `undefined`. Delta-seconds still
+  win; a date converts to a non-negative seconds delta.
+- **The streaming `sendText` leg keeps the 429 body `hint`.** The non-SSE
+  error fallback dropped the actionable hint (e.g. "provision a project …")
+  that the buffered path has surfaced since 0.27.0.
+
+## [0.29.1] - 2026-07-12
+
+### Fixed
+
+- **`CompanionError.retryAfter` no longer reports a spurious `0`.** A missing
+  `Retry-After` header was parsed as `Number(null) === 0`, so EVERY error
+  thrown from a POST without the header (a `400 invalid_request`, a
+  `404 session_not_found`, …) carried `retryAfter: 0` — telling backoff code
+  "retry immediately" on non-retryable errors. It is now `undefined` unless
+  the body's `retryAfterSec` or a real header names a value, as documented.
+- **`sendText({ awaitReply: true, stream: false })` now cancels its POST.**
+  The buffered leg never passed the operation's `AbortSignal` to the network
+  call, so the promise rejected on abort/deadline but the billed turn kept
+  running server-side. It now aborts with the same linked controller the
+  streaming leg uses.
+- **Abort-listener leak on a reused `AbortSignal` in `awaitReply`.** The
+  deadline's reject listener was never removed, so a host reusing one
+  long-lived signal across many `sendText({ awaitReply, signal })` calls
+  accumulated one orphan listener per call (memory growth + Node's
+  MaxListenersExceeded warning). Removed in the same `finally` as the rest.
+
+### Added
+
+- **`signal` on `sendToolResult` and `startCall`** — the two request-performing
+  methods 0.29.0's "AbortSignal on every network method" pass missed
+  (backwards-compatible addition, per this package's patch policy).
+- **`require()` of the package now works on Node ≥ 20.17** (require-ESM): the
+  `exports` map gained a `default` condition — previously `require()` failed
+  with `ERR_PACKAGE_PATH_NOT_EXPORTED` before the feature could apply, despite
+  the README documenting it.
+
 ## [0.29.0] - 2026-07-12
 
 ### Added
@@ -616,7 +689,9 @@ 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.29.0...HEAD
+[Unreleased]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.30.0...HEAD
+[0.30.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.29.1...companion-sdk-v0.30.0
+[0.29.1]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.29.0...companion-sdk-v0.29.1
 [0.29.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.28.1...companion-sdk-v0.29.0
 [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

package/README.md

@@ -63,9 +63,25 @@ Token as `token` instead — same API. See the docs' authentication section.)
 - **Capabilities map:** [`docs/companion-capabilities.md`](../../docs/companion-capabilities.md)
 - **Instant UI renderer contract:** [`docs/companion-instant-ui.md`](../../docs/companion-instant-ui.md)
 
+### Constructor options (beyond `baseUrl` + `token`)
+
+`createCompanion({ … })` also takes: `surface` (one resumable session per
+surface), `modalities` / `handles` / `contextKinds` / `tools` /
+`appContext` (the capability handshake), `visitor` (representative mode,
+below), `onAuthError` (401 → return a fresh token and the client retries
+transparently), `stream: 'sse' | 'websocket'` (receive transport —
+`'websocket'` opts into the lower-latency WS plane when the deployment serves
+one and **falls back to SSE automatically**, observable as
+`streamState === 'degraded_sse'`), and two injection points for Node/tests:
+`fetch` (custom fetch implementation) and `webSocketImpl` (WebSocket
+constructor when `globalThis.WebSocket` is absent).
+
 ## Events
 
-Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers:
+Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers.
+Since 0.30.0 `on()` narrows the envelope payload per event name
+(`OutboundPayloadMap`) — e.g. `on('companion.typing', (env) => env.payload.active)`
+type-checks without a cast; `'*'` keeps the untyped envelope:
 
 | Helper | Event | Use |
 | --- | --- | --- |
@@ -82,7 +98,7 @@ Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers:
 | `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) |
+| `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). Since 0.30.0 the vocabulary is EXPORTED TYPED: `CONTROL_ERROR_CODES` (runtime list, drift-tested against the server) + the `ControlErrorCodeValue` union `fn`'s `err.code` now carries — `switch` on it with autocomplete |
 
 ### Instant UI
 
@@ -112,7 +128,8 @@ local/device skills).
 | `endSession()` | Distill the session into durable memory now; returns `{ skipped?: 'no_session' \| 'no_content' \| 'throttled' }`. |
 | `close()` | One-call teardown: `stop()` + `endSession()` — the text-session mirror of the call handle's `close()`. |
 | `startCall(opts)` / `connectCall(opts)` | Voice plane: raw credentials / fully-wired call handle (`call.close()` ends + folds the transcript into memory). |
-| `getAvatar()` / `brandIconUrl(size?)` | The user's avatar (VRM/portrait) and the Pouchy brand icon for your UI. |
+| `streamState` / `onStreamStateChange(fn)` | Receive-stream lifecycle (0.30.0): `'idle' \| 'connecting' \| 'connected' \| 'reconnecting' \| 'degraded_sse' \| 'stopped'` (`CompanionStreamState`). `fn(state, prev)` fires on change only — drive a connection indicator; `degraded_sse` = the WS transport errored and delivery continues on the SSE fallback; `stopped` = `stop()`/`close()` or a permanent `stream_unauthorized` failure. |
+| `getAvatar()` / `brandIconUrl(size?)` | The user's avatar (VRM/portrait) and the Pouchy brand icon for your UI. Standalone (no client/token): `pouchyBrandIconUrl(baseUrl, size?)` derives the same URL before/without connecting. |
 | `getWallet()` | Read the instance's own wallet — `{ balances: [{ currency, amount }], totalUsd, currency }`. Read-only + receive-only; needs the `wallet.read` scope. |
 
 Tool calling beyond your own declared tools: `HOST_CONTROL_TOOLS` (universal
@@ -122,12 +139,14 @@ are offered automatically once you declare `tools`/`handles`, and
 embeds receive expression cues — declare them or they no-op silently. Full
 contract: `docs/companion-host-control.md`.
 
-**Cancellation (0.29.0):** every request-performing method accepts an optional
-`AbortSignal`. Methods with an options object take a `signal?` field
-(`sendText(text, { signal })`, `recall({ signal })`, …); the rest take a
-trailing `opts` (`getAvatar({ signal })`, `ping({ signal })`, …). Aborting
-rejects with `CompanionError` `code: 'aborted'`, and for `sendText({ awaitReply })`
-it also tears down the in-flight event stream.
+**Cancellation (0.29.0, completed in 0.29.1):** every request-performing method
+accepts an optional `AbortSignal` — including `sendToolResult(callId, result,
+{ signal })` and `startCall({ signal })` since 0.29.1. Methods with an options
+object take a `signal?` field (`sendText(text, { signal })`,
+`recall({ signal })`, …); the rest take a trailing `opts`
+(`getAvatar({ signal })`, `ping({ signal })`, …). Aborting rejects with
+`CompanionError` `code: 'aborted'`, and for `sendText({ awaitReply })` it also
+tears down the in-flight event stream.
 
 ```ts
 const ac = new AbortController();

package/dist/client.d.ts

@@ -1,7 +1,8 @@
-import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundType, PendingConfirm, RenderInterfacePayload, SocialMessagePayload, ToolCallPayload, TypingPayload, UsagePayload, VoiceInjectPayload, WorldStateEvent } from './protocol.js';
+import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundPayloadMap, OutboundType, PendingConfirm, RenderInterfacePayload, SocialMessagePayload, ToolCallPayload, TypingPayload, UsagePayload, VoiceInjectPayload, 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'>>;
+import { type ControlErrorCodeValue } from './errors.js';
 import { type CompanionCall, type CompanionCallOptions } from './call.js';
 export interface CompanionClientOptions {
     /** Origin of the Pouchy deployment, e.g. "https://pouchy.ai". */
@@ -198,6 +199,18 @@ type Handler = (envelope: CompanionEnvelope) => void;
 type DeltaHandler = (chunk: string, meta: {
     reset?: boolean;
 }) => void;
+/** Lifecycle of the receive event stream (0.30.0) — observable via
+ *  `client.streamState` + `onStreamStateChange`, so a host can render a
+ *  connection indicator without hand-rolling its own enum.
+ *  - `idle`        — before start()
+ *  - `connecting`  — start() called; first connection being established
+ *  - `connected`   — the event stream is live (WS or SSE as configured)
+ *  - `reconnecting`— connection lost / closed; backing off before the next try
+ *  - `degraded_sse`— the WebSocket transport errored and delivery continues on
+ *                    the SSE fallback (still live — replies keep arriving)
+ *  - `stopped`     — stop()/close() was called, or a permanent stream failure
+ *                    (the `stream_unauthorized` control.error) ended the loop */
+export type CompanionStreamState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'degraded_sse' | 'stopped';
 export declare class CompanionClient {
     private readonly opts;
     private readonly doFetch;
@@ -210,9 +223,22 @@ export declare class CompanionClient {
     private readonly seen;
     private readonly deltaHandlers;
     private readonly pendingVoiceTools;
+    private _streamState;
+    private readonly streamStateHandlers;
     constructor(opts: CompanionClientOptions);
     /** The active session id, or null before connect(). */
     get sessionId(): string | null;
+    /** Current lifecycle of the receive event stream (0.30.0) — `idle` before
+     *  start(), then `connecting` / `connected` / `reconnecting` /
+     *  `degraded_sse` (WS errored, SSE fallback carrying delivery) / `stopped`.
+     *  Subscribe to transitions with `onStreamStateChange`. */
+    get streamState(): CompanionStreamState;
+    /** Subscribe to receive-stream lifecycle transitions (0.30.0) — drive a
+     *  connection indicator: `client.onStreamStateChange((s) => setStatus(s))`.
+     *  Fires only on change, with the previous state as the second argument.
+     *  Returns an unsubscribe function. */
+    onStreamStateChange(handler: (state: CompanionStreamState, prev: CompanionStreamState) => void): () => void;
+    private setStreamState;
     /** Swap the bearer token used by every subsequent request and stream
      *  reconnect. Session tokens expire (default 1h) — call this when your
      *  backend re-mints one, or wire `onAuthError` to do it on demand. */
@@ -346,6 +372,7 @@ export declare class CompanionClient {
     startCall(opts?: {
         voice?: string;
         locale?: string;
+        signal?: AbortSignal;
     }): Promise<CallCredentials>;
     /** Open a live voice call end-to-end: mints credentials (startCall) and opens a
      *  WebRTC session directly to the provider — no first-party app code needed.
@@ -388,6 +415,8 @@ export declare class CompanionClient {
     sendToolResult(callId: string, result: {
         ok?: boolean;
         result?: unknown;
+    }, opts?: {
+        signal?: AbortSignal;
     }): Promise<{
         allDone: boolean;
     }>;
@@ -404,9 +433,12 @@ export declare class CompanionClient {
     onToolCall(handler: (call: ToolCallEvent, envelope: CompanionEnvelope) => void): () => void;
     /** Convenience: subscribe to errors the companion surfaces — server-side agent
      *  errors and stream failures (e.g. a permanent `stream_unauthorized`) both
-     *  arrive as `control.error`. Returns an unsubscribe fn. */
+     *  arrive as `control.error`. Since 0.30.0 `code` is typed as
+     *  `ControlErrorCodeValue` (the CONTROL_ERROR_CODES vocabulary + the
+     *  SDK-synthesized stream codes, open for newer servers) so a `switch` on it
+     *  autocompletes. Returns an unsubscribe fn. */
     onError(handler: (err: {
-        code: string;
+        code: ControlErrorCodeValue;
         message: string;
     }, envelope: CompanionEnvelope) => void): () => void;
     /** Recall the memory this token is authorized to see. Without `query` the
@@ -530,8 +562,12 @@ export declare class CompanionClient {
      *  the companion's app tile, etc. Sizes: 256 | 512 | 1024 (default 512). */
     brandIconUrl(size?: BrandIconSize): string;
     /** Subscribe to outbound events of a given type, or "*" for all. Returns an
-     *  unsubscribe function. */
-    on(type: OutboundType | '*', handler: Handler): () => void;
+     *  unsubscribe function. Since 0.30.0 the envelope payload is NARROWED per
+     *  event name (OutboundPayloadMap) — e.g. `on('companion.typing', (env) =>
+     *  env.payload.active)` type-checks without a cast; `'*'` keeps the untyped
+     *  envelope. Type-only: runtime behavior is unchanged. */
+    on<T extends OutboundType>(type: T, handler: (envelope: CompanionEnvelope<OutboundPayloadMap[T]>) => void): () => void;
+    on(type: '*', handler: Handler): () => void;
     /** Convenience: subscribe to assistant text replies. */
     onMessage(handler: (text: string, envelope: CompanionEnvelope) => void): () => void;
     /** Convenience: subscribe to Instant UI render surfaces (companion.ui_action).
@@ -624,7 +660,14 @@ export declare class CompanionClient {
     stop(): void;
     private emit;
     private handleFrame;
+    /** SSE receive loop. `degraded` marks that this loop is the WS transport's
+     *  fallback, so its healthy state reads `degraded_sse` (still live) instead
+     *  of `connected` — the host can tell "fine" from "fine, but on plan B". */
     private loop;
     private consume;
     private sleep;
+    /** Backoff sleep with additive jitter (0–25%, 0.30.0) so a fleet of embeds
+     *  doesn't reconnect in lockstep after a server deploy/restart (thundering
+     *  herd) — every reconnect path sleeps through here, never bare sleep(). */
+    private backoffSleep;
 }

package/dist/client.js

@@ -62,6 +62,9 @@ export class CompanionClient {
     deltaHandlers = new Set();
     // Voice tool-calls awaiting the app's sendToolResult, keyed by a synthetic id.
     pendingVoiceTools = new Map();
+    // Receive-stream lifecycle (0.30.0) — see CompanionStreamState.
+    _streamState = 'idle';
+    streamStateHandlers = new Set();
     constructor(opts) {
         if (!opts.baseUrl)
             throw new CompanionError('CompanionClient: baseUrl is required', 0, 'missing_option');
@@ -74,6 +77,37 @@ export class CompanionClient {
     get sessionId() {
         return this._session;
     }
+    /** Current lifecycle of the receive event stream (0.30.0) — `idle` before
+     *  start(), then `connecting` / `connected` / `reconnecting` /
+     *  `degraded_sse` (WS errored, SSE fallback carrying delivery) / `stopped`.
+     *  Subscribe to transitions with `onStreamStateChange`. */
+    get streamState() {
+        return this._streamState;
+    }
+    /** Subscribe to receive-stream lifecycle transitions (0.30.0) — drive a
+     *  connection indicator: `client.onStreamStateChange((s) => setStatus(s))`.
+     *  Fires only on change, with the previous state as the second argument.
+     *  Returns an unsubscribe function. */
+    onStreamStateChange(handler) {
+        this.streamStateHandlers.add(handler);
+        return () => this.streamStateHandlers.delete(handler);
+    }
+    setStreamState(next) {
+        if (next === this._streamState)
+            return;
+        const prev = this._streamState;
+        this._streamState = next;
+        // Same isolation doctrine as emit(): a throwing consumer handler must not
+        // skip the remaining handlers or bubble into the stream loop.
+        for (const h of this.streamStateHandlers) {
+            try {
+                h(next, prev);
+            }
+            catch (e) {
+                console.error('[companion-sdk] stream-state handler threw', e);
+            }
+        }
+    }
     /** Swap the bearer token used by every subsequent request and stream
      *  reconnect. Session tokens expire (default 1h) — call this when your
      *  backend re-mints one, or wire `onAuthError` to do it on demand. */
@@ -191,8 +225,21 @@ export class CompanionClient {
         const fromBody = json?.retryAfterSec;
         if (typeof fromBody === 'number' && Number.isFinite(fromBody) && fromBody >= 0)
             return fromBody;
-        const header = Number(res.headers.get('Retry-After'));
-        return Number.isFinite(header) && header >= 0 ? header : undefined;
+        // Missing/blank header must stay undefined — Number(null) is 0, which
+        // used to stamp retryAfter: 0 on EVERY error without the header (a 400,
+        // a 404 …), telling backoff code "retry immediately".
+        const raw = res.headers.get('Retry-After');
+        if (raw === null || raw.trim() === '')
+            return undefined;
+        const header = Number(raw);
+        if (Number.isFinite(header) && header >= 0)
+            return header;
+        // RFC 9110 also allows an HTTP-date (proxies/CDNs emit it) — convert to a
+        // non-negative seconds delta (0.30.0). Unparseable stays undefined.
+        const at = Date.parse(raw);
+        if (!Number.isNaN(at))
+            return Math.max(0, Math.ceil((at - Date.now()) / 1000));
+        return undefined;
     }
     async postJson(path, body, signal) {
         const res = await this.fetchAuthed(this.url(path), {
@@ -305,6 +352,9 @@ export class CompanionClient {
             opts.signal.addEventListener('abort', onCallerAbort, { once: true });
         }
         let timer;
+        // Held so the finally can REMOVE it — a host reusing one long-lived signal
+        // across many awaitReply calls accumulated one orphan listener per call.
+        let onCallerAbortReject;
         const deadline = new Promise((_, reject) => {
             timer = setTimeout(() => {
                 ac.abort();
@@ -313,7 +363,8 @@ export class CompanionClient {
             // The caller's signal also rejects the operation (the stream teardown
             // alone would otherwise leave the fallback wait hanging to the timer).
             if (opts?.signal) {
-                opts.signal.addEventListener('abort', () => reject(new CompanionError('request aborted', 0, 'aborted')), { once: true });
+                onCallerAbortReject = () => reject(new CompanionError('request aborted', 0, 'aborted'));
+                opts.signal.addEventListener('abort', onCallerAbortReject, { once: true });
             }
         });
         try {
@@ -322,7 +373,10 @@ export class CompanionClient {
             let pausedOnTools = false;
             if (opts?.stream === false) {
                 const json = await Promise.race([
-                    this.postJson(`/api/companion/session/${sessionId}/input`, body),
+                    // ac.signal, like the streaming leg: the deadline and the caller's
+                    // signal both abort it — without this the promise rejected but the
+                    // billed POST kept running beyond cancellation.
+                    this.postJson(`/api/companion/session/${sessionId}/input`, body, ac.signal),
                     deadline
                 ]);
                 seq = json.seq ?? null;
@@ -354,6 +408,8 @@ export class CompanionClient {
                 clearTimeout(timer);
             if (onCallerAbort)
                 opts?.signal?.removeEventListener('abort', onCallerAbort);
+            if (onCallerAbortReject)
+                opts?.signal?.removeEventListener('abort', onCallerAbortReject);
         }
     }
     /** The streaming leg of sendText: parse the POST response's SSE frames —
@@ -373,7 +429,11 @@ export class CompanionClient {
             // Old server / error before the stream opened — behave like postJson.
             const json = (await res.json().catch(() => null));
             if (!res.ok || !json || json.ok === false) {
-                throw new CompanionError(json?.error || `request failed (${res.status})`, res.status, json?.code, this.retryAfterFrom(res, json));
+                // Same as postJson: the 429 body's actionable `hint` (e.g. "provision
+                // a project …") must survive the streaming leg too (0.30.0).
+                const hint = json?.hint;
+                const detail = typeof hint === 'string' && hint ? ` — ${hint}` : '';
+                throw new CompanionError((json?.error || `request failed (${res.status})`) + detail, res.status, json?.code, this.retryAfterFrom(res, json));
             }
             return { seq: json.seq ?? null };
         }
@@ -512,10 +572,7 @@ export class CompanionClient {
      */
     async startCall(opts) {
         const id = this.requireSession();
-        return this.postJson(`/api/companion/session/${id}/call`, {
-            voice: opts?.voice,
-            locale: opts?.locale
-        });
+        return this.postJson(`/api/companion/session/${id}/call`, { voice: opts?.voice, locale: opts?.locale }, opts?.signal);
     }
     /** Open a live voice call end-to-end: mints credentials (startCall) and opens a
      *  WebRTC session directly to the provider — no first-party app code needed.
@@ -651,7 +708,7 @@ export class CompanionClient {
     /** Report the result of a companion.tool_call this surface performed. When all
      *  of the turn's calls are reported, the companion resumes and the continuation
      *  (a companion.message or more tool calls) arrives on the event stream. */
-    async sendToolResult(callId, result) {
+    async sendToolResult(callId, result, opts) {
         // Voice tool-call: resolve it locally so the result flows back to the voice
         // provider, not to a server text turn. (Same call shape as the text path.)
         const pending = this.pendingVoiceTools.get(callId);
@@ -660,7 +717,7 @@ export class CompanionClient {
             return { allDone: true };
         }
         const id = this.requireSession();
-        const json = await this.postJson(`/api/companion/session/${id}/tool-result`, { callId, ok: result.ok !== false, result: result.result });
+        const json = await this.postJson(`/api/companion/session/${id}/tool-result`, { callId, ok: result.ok !== false, result: result.result }, opts?.signal);
         return { allDone: json.allDone ?? false };
     }
     /** A tool the live voice call asked the app to run. Fires the SAME
@@ -758,7 +815,10 @@ export class CompanionClient {
     }
     /** Convenience: subscribe to errors the companion surfaces — server-side agent
      *  errors and stream failures (e.g. a permanent `stream_unauthorized`) both
-     *  arrive as `control.error`. Returns an unsubscribe fn. */
+     *  arrive as `control.error`. Since 0.30.0 `code` is typed as
+     *  `ControlErrorCodeValue` (the CONTROL_ERROR_CODES vocabulary + the
+     *  SDK-synthesized stream codes, open for newer servers) so a `switch` on it
+     *  autocompletes. Returns an unsubscribe fn. */
     onError(handler) {
         return this.on('control.error', (env) => {
             const p = env.payload;
@@ -928,8 +988,6 @@ export class CompanionClient {
     brandIconUrl(size = 512) {
         return pouchyBrandIconUrl(this.opts.baseUrl, size);
     }
-    /** Subscribe to outbound events of a given type, or "*" for all. Returns an
-     *  unsubscribe function. */
     on(type, handler) {
         let set = this.handlers.get(type);
         if (!set) {
@@ -1084,6 +1142,7 @@ export class CompanionClient {
             return;
         this.requireSession();
         this.streaming = true;
+        this.setStreamState('connecting');
         const gen = ++this.streamGen;
         const wsImpl = this.opts.webSocketImpl ?? globalThis.WebSocket;
         if (this.opts.stream === 'websocket' && wsImpl) {
@@ -1114,6 +1173,10 @@ export class CompanionClient {
                     const ws = new WS(deriveWsStreamUrl(this.opts.baseUrl, id, this.opts.token, this.cursor));
                     let poll;
                     let settled = false;
+                    ws.onopen = () => {
+                        if (this.streaming && gen === this.streamGen)
+                            this.setStreamState('connected');
+                    };
                     const settle = (err) => {
                         if (poll) {
                             clearInterval(poll);
@@ -1157,8 +1220,12 @@ export class CompanionClient {
             }
             if (errored) {
                 // Socket unavailable / rejected — degrade to the robust SSE loop (once).
-                if (this.streaming && gen === this.streamGen)
-                    await this.loop(gen);
+                // The SSE loop's healthy state then reads `degraded_sse`, so the host
+                // can observe the (previously invisible) WS→SSE degrade.
+                if (this.streaming && gen === this.streamGen) {
+                    this.setStreamState('reconnecting');
+                    await this.loop(gen, true);
+                }
                 return;
             }
             // Clean close: the while-guard reconnects if still streaming, else exits.
@@ -1166,8 +1233,10 @@ export class CompanionClient {
             // 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 (this.streaming && gen === this.streamGen)
+                this.setStreamState('reconnecting');
             if (Date.now() - connectedAt < 2000) {
-                await this.sleep(backoff);
+                await this.backoffSleep(backoff);
                 backoff = Math.min(backoff * 2, 8000);
             }
             else {
@@ -1181,6 +1250,7 @@ export class CompanionClient {
         this.streamGen++; // invalidate any loop still unwinding
         this.abort?.abort();
         this.abort = null;
+        this.setStreamState('stopped');
     }
     emit(envelope) {
         // Dedup by envelope id — an ungraceful drop reconnects from the last KNOWN
@@ -1265,7 +1335,10 @@ export class CompanionClient {
         if (env && typeof env.type === 'string')
             this.emit(env);
     }
-    async loop(gen) {
+    /** SSE receive loop. `degraded` marks that this loop is the WS transport's
+     *  fallback, so its healthy state reads `degraded_sse` (still live) instead
+     *  of `connected` — the host can tell "fine" from "fine, but on plan B". */
+    async loop(gen, degraded = false) {
         const id = this.requireSession();
         let backoff = 500;
         let authRefreshes = 0; // consecutive 401→refresh cycles without a healthy connect
@@ -1299,23 +1372,27 @@ export class CompanionClient {
                             message: `event stream rejected (${res.status}); the token likely lacks the "events.subscribe" scope`
                         }
                     });
+                    this.setStreamState('stopped');
                     break;
                 }
                 if (!res.ok || !res.body) {
                     if (!this.streaming || gen !== this.streamGen)
                         break;
-                    await this.sleep(backoff);
+                    this.setStreamState('reconnecting');
+                    await this.backoffSleep(backoff);
                     backoff = Math.min(backoff * 2, 8000);
                     continue;
                 }
                 backoff = 500; // healthy connection resets backoff
                 authRefreshes = 0;
+                this.setStreamState(degraded ? 'degraded_sse' : 'connected');
                 await this.consume(res.body, gen);
             }
             catch {
                 if (!this.streaming || gen !== this.streamGen)
                     break;
-                await this.sleep(backoff);
+                this.setStreamState('reconnecting');
+                await this.backoffSleep(backoff);
                 backoff = Math.min(backoff * 2, 8000);
             }
         }
@@ -1338,4 +1415,10 @@ export class CompanionClient {
     sleep(ms) {
         return new Promise((res) => setTimeout(res, ms));
     }
+    /** Backoff sleep with additive jitter (0–25%, 0.30.0) so a fleet of embeds
+     *  doesn't reconnect in lockstep after a server deploy/restart (thundering
+     *  herd) — every reconnect path sleeps through here, never bare sleep(). */
+    backoffSleep(ms) {
+        return this.sleep(ms + Math.floor(Math.random() * ms * 0.25));
+    }
 }

package/dist/errors.d.ts

@@ -1,9 +1,22 @@
-import type { CompanionErrorCode } from './protocol.js';
+import type { CompanionErrorCode, ControlErrorCode } 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", "aborted"];
 export type SdkSynthesizedErrorCode = (typeof SDK_SYNTHESIZED_ERROR_CODES)[number];
+/** `control.error` STREAM codes the SDK itself synthesizes (never sent by the
+ *  server) — the stream-plane sibling of SDK_SYNTHESIZED_ERROR_CODES above.
+ *  Runtime array so the drift test can assert every locally-emitted
+ *  `control.error` envelope uses a declared code; APPEND-ONLY. */
+export declare const SDK_STREAM_ERROR_CODES: readonly ["stream_unauthorized"];
+export type SdkStreamErrorCode = (typeof SDK_STREAM_ERROR_CODES)[number];
+/** `control.error` `code` values a consumer can switch on (0.30.0): the server
+ *  vocabulary (CONTROL_ERROR_CODES, drift-tested against the server list) plus
+ *  the SDK-synthesized stream codes — DERIVED from the runtime lists rather
+ *  than hand-retyped, same doctrine as CompanionErrorCodeValue below. The
+ *  `(string & {})` arm keeps the type open for codes newer than this SDK build
+ *  while preserving autocomplete. */
+export type ControlErrorCodeValue = ControlErrorCode | SdkStreamErrorCode | (string & {});
 /** 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

package/dist/errors.js

@@ -17,6 +17,13 @@ export const SDK_SYNTHESIZED_ERROR_CODES = [
     'call_dependency_missing', // optional voice dependency not installed
     'aborted' // a caller-supplied AbortSignal cancelled the request (0.29.0)
 ];
+/** `control.error` STREAM codes the SDK itself synthesizes (never sent by the
+ *  server) — the stream-plane sibling of SDK_SYNTHESIZED_ERROR_CODES above.
+ *  Runtime array so the drift test can assert every locally-emitted
+ *  `control.error` envelope uses a declared code; APPEND-ONLY. */
+export const SDK_STREAM_ERROR_CODES = [
+    'stream_unauthorized' // the event stream got a permanent 401/403 and reconnect gave up
+];
 export class CompanionError extends Error {
     status;
     code;

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 import { CompanionClient, type CompanionClientOptions } from './client.js';
 export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js';
-export type { CompanionErrorCodeValue } from './errors.js';
-export type { CompanionClientOptions, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, ToolCallEvent, WorldStateInput, CompanionAvatar, CompanionWallet, WalletBalance, BrandIconSize, EndSessionResult, SendTextReply } from './client.js';
+export type { CompanionErrorCodeValue, ControlErrorCodeValue } from './errors.js';
+export type { CompanionClientOptions, CompanionStreamState, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, ToolCallEvent, WorldStateInput, CompanionAvatar, CompanionWallet, WalletBalance, BrandIconSize, EndSessionResult, SendTextReply } 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 { COMPANION_SCOPES, COMPANION_MODALITIES, SENSITIVE_SCOPES, REPRESENT_SCOPES, DEFAULT_SCOPES, DEFAULT_MODALITIES, isSensitiveScope, isRepresentScope, hasScope } from './scopes.js';
 export type { CompanionScope, CompanionModality } from './scopes.js';
-export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, PendingConfirm, ToolCallPayload, AudioClipPayload, ExpressionPayload, TypingPayload, VoiceInjectPayload, UsagePayload, MessagePayload } from './protocol.js';
-export { PROTOCOL_VERSION, INBOUND_TYPES, OUTBOUND_TYPES, COMPANION_ERROR_CODES } from './protocol.js';
-export type { CompanionErrorCode } from './protocol.js';
+export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, PendingConfirm, ToolCallPayload, AudioClipPayload, ExpressionPayload, TypingPayload, VoiceInjectPayload, UsagePayload, MessagePayload, ControlErrorPayload, HelloAckPayload, CallReadyPayload, OutboundPayloadMap } from './protocol.js';
+export { PROTOCOL_VERSION, INBOUND_TYPES, OUTBOUND_TYPES, COMPANION_ERROR_CODES, CONTROL_ERROR_CODES } from './protocol.js';
+export type { CompanionErrorCode, ControlErrorCode } from './protocol.js';
 /** Create a companion client. */
 export declare function createCompanion(opts: CompanionClientOptions): CompanionClient;

package/dist/index.js

@@ -15,7 +15,9 @@ export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_
 export { COMPANION_SCOPES, COMPANION_MODALITIES, SENSITIVE_SCOPES, REPRESENT_SCOPES, DEFAULT_SCOPES, DEFAULT_MODALITIES, isSensitiveScope, isRepresentScope, hasScope } from './scopes.js';
 // Runtime protocol constants — so a host can assert PROTOCOL_VERSION or
 // enumerate/validate the event vocabulary without hard-coding the strings.
-export { PROTOCOL_VERSION, INBOUND_TYPES, OUTBOUND_TYPES, COMPANION_ERROR_CODES } from './protocol.js';
+// CONTROL_ERROR_CODES (0.30.0) is the stream-plane control.error vocabulary —
+// a separate, smaller list than the HTTP COMPANION_ERROR_CODES.
+export { PROTOCOL_VERSION, INBOUND_TYPES, OUTBOUND_TYPES, COMPANION_ERROR_CODES, CONTROL_ERROR_CODES } from './protocol.js';
 /** Create a companion client. */
 export function createCompanion(opts) {
     return new CompanionClient(opts);

package/dist/protocol.d.ts

@@ -12,6 +12,15 @@ export type InboundType = (typeof INBOUND_TYPES)[number];
 export declare const OUTBOUND_TYPES: readonly ["hello.ack", "companion.message", "companion.audio", "companion.tool_call", "companion.ui_action", "companion.ui_update", "companion.expression", "companion.voice_inject", "companion.confirm_request", "companion.social_message", "companion.typing", "control.call_ready", "control.error", "control.usage"];
 export type OutboundType = (typeof OUTBOUND_TYPES)[number];
 export type MessageType = InboundType | OutboundType;
+/** `control.error` STREAM-plane code vocabulary (0.30.0) — a separate, smaller
+ *  vocabulary from COMPANION_ERROR_CODES below (those tag HTTP `{ok:false}`
+ *  response bodies; these tag `control.error` envelopes on the event stream,
+ *  surfaced by `onError`). Self-contained mirror of the server list
+ *  (drift-tested); APPEND-ONLY. The SDK itself synthesizes one more,
+ *  `stream_unauthorized` (errors.ts) — the public union `ControlErrorCodeValue`
+ *  covers both plus a forward-compat string arm. */
+export declare const CONTROL_ERROR_CODES: readonly ["agent_error", "call_mint_failed"];
+export type ControlErrorCode = (typeof CONTROL_ERROR_CODES)[number];
 /** HTTP error `code` vocabulary — what `CompanionError.code` can hold. A
  *  self-contained mirror of the server's api-error.ts list (drift-tested);
  *  APPEND-ONLY: renaming or removing a code is a breaking SDK change.
@@ -187,3 +196,51 @@ export interface WorldStateEvent<D = unknown> {
     salience?: number;
     voiceRelevant?: boolean;
 }
+/** Payload of a `control.error` event — a typed error on the event stream
+ *  (surfaced by `onError`). `code` is one of CONTROL_ERROR_CODES, the
+ *  SDK-synthesized `stream_unauthorized`, or a code newer than this SDK build
+ *  (the open arm keeps forward compat without losing autocomplete). */
+export interface ControlErrorPayload {
+    code: ControlErrorCode | (string & {});
+    message: string;
+}
+/** Payload of a `hello.ack` — the handshake reply. On the REST plane this is
+ *  the `/session` response body (what `connect()` normalizes into `HelloAck`);
+ *  the event stream's greeting `open` frame carries a partial echo (just
+ *  `{ resumeCursor }`), so every field is optional at the wire level. */
+export interface HelloAckPayload {
+    session?: string;
+    grantedScopes?: string[];
+    modalities?: string[];
+    resumeCursor?: number;
+    representative?: boolean;
+    visitorPaired?: boolean;
+}
+/** Payload of a `control.call_ready` event — the stream echo of `start_call`'s
+ *  accept. Deliberately SECRET-FREE (`provider` plus non-secret metadata such
+ *  as `agentId` / `model` / `voice`); the actual WebRTC credentials only ride
+ *  the `startCall` HTTP response. */
+export interface CallReadyPayload {
+    provider: string;
+    [k: string]: unknown;
+}
+/** Per-event payload types, keyed by outbound event name — what `client.on()`
+ *  narrows envelopes with (0.30.0). Type-only; extending the base Record keeps
+ *  indexing valid for every OutboundType, so an event added to the vocabulary
+ *  before it gets a dedicated payload type simply reads as `unknown`. */
+export interface OutboundPayloadMap extends Record<OutboundType, unknown> {
+    'hello.ack': HelloAckPayload;
+    'companion.message': MessagePayload;
+    'companion.audio': AudioClipPayload;
+    'companion.tool_call': ToolCallPayload;
+    'companion.ui_action': RenderInterfacePayload;
+    'companion.ui_update': InterfaceUpdatePayload;
+    'companion.expression': ExpressionPayload;
+    'companion.voice_inject': VoiceInjectPayload;
+    'companion.confirm_request': ConfirmRequestPayload;
+    'companion.social_message': SocialMessagePayload;
+    'companion.typing': TypingPayload;
+    'control.call_ready': CallReadyPayload;
+    'control.error': ControlErrorPayload;
+    'control.usage': UsagePayload;
+}

package/dist/protocol.js

@@ -40,6 +40,17 @@ export const OUTBOUND_TYPES = [
     'control.error',
     'control.usage' // reserved — not emitted yet
 ];
+/** `control.error` STREAM-plane code vocabulary (0.30.0) — a separate, smaller
+ *  vocabulary from COMPANION_ERROR_CODES below (those tag HTTP `{ok:false}`
+ *  response bodies; these tag `control.error` envelopes on the event stream,
+ *  surfaced by `onError`). Self-contained mirror of the server list
+ *  (drift-tested); APPEND-ONLY. The SDK itself synthesizes one more,
+ *  `stream_unauthorized` (errors.ts) — the public union `ControlErrorCodeValue`
+ *  covers both plus a forward-compat string arm. */
+export const CONTROL_ERROR_CODES = [
+    'agent_error', // a server-side turn failed after the input was accepted — no reply was produced; safe to re-send
+    'call_mint_failed' // start_call couldn't mint the voice-provider credential — retry later or fall back to text
+];
 /** HTTP error `code` vocabulary — what `CompanionError.code` can hold. A
  *  self-contained mirror of the server's api-error.ts list (drift-tested);
  *  APPEND-ONLY: renaming or removing a code is a breaking SDK change.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.29.0",
-  "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.",
+  "version": "0.30.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",
   "homepage": "https://pouchy.ai",
@@ -16,7 +16,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "main": "./dist/index.js",