@pouchy_ai/companion-sdk 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -12,6 +12,59 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.29.0] - 2026-07-12
+
+### Added
+
+- **`AbortSignal` on every network method.** All request-performing public
+  methods now accept an optional `signal` — cancel an in-flight `sendText`
+  (including its `awaitReply` deadline + event-stream teardown), `recall`,
+  `history`, `sendWorldState`, `ingestKnowledge`, `ingestFile`, `remember`,
+  `getAvatar`, `getWallet`, `confirmAction`, `pendingConfirms`,
+  `setModalities`, `ping`, `pairVisitor`, or `connect`. Methods with an
+  existing options object gained a `signal?` field; the rest gained a trailing
+  `opts?: { signal?: AbortSignal }`. Fully additive — no existing call
+  changes. A fired signal rejects with `CompanionError` `code: 'aborted'`
+  (new synthesized code), converted at the single fetch choke point so the
+  "every helper rejects with CompanionError" contract holds; the signal also
+  rides the 401-refresh retry automatically.
+
+## [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 +616,25 @@ 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.29.0...HEAD
+[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
+[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) |
 
@@ -117,6 +122,20 @@ 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.
+
+```ts
+const ac = new AbortController();
+const p = companion.sendText('summarize this', { awaitReply: true, signal: ac.signal });
+// …user navigated away
+ac.abort(); // p rejects with code: 'aborted'
+```
+
 ## Scopes (typed)
 
 The full capability-scope vocabulary ships as typed constants — no more

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.d.ts

@@ -230,6 +230,11 @@ export declare class CompanionClient {
      *  the strict awaitReply correlation is only safe to enforce there. */
     private serverEchoesReplyTo;
     private fetchAuthed;
+    /** Normalize a thrown fetch error to a CompanionError. An AbortError (the
+     *  caller's signal fired) becomes a switchable `code: 'aborted'`; anything
+     *  else that is already a CompanionError passes through; the rest wrap as a
+     *  status-0 network failure. */
+    private asCompanionError;
     /** Peek the error `code` of a failure response without consuming its body. */
     private errorCodeOf;
     private url;
@@ -241,7 +246,9 @@ export declare class CompanionClient {
     private retryAfterFrom;
     private postJson;
     /** Handshake: start or resume the session for this surface. */
-    connect(): Promise<HelloAck>;
+    connect(opts?: {
+        signal?: AbortSignal;
+    }): Promise<HelloAck>;
     /** Pair this representative session's VISITOR with the owner so their two
      *  companions become friends — unlocking the A2A plane (messaging, gifts,
      *  visiting) between them. Only valid in a representative session (the client
@@ -250,7 +257,9 @@ export declare class CompanionClient {
      *  Two-token consent: this client's PAT (the owner's) must hold `represent:pair`,
      *  and you pass the VISITOR's own Pouchy PAT — which must hold `social.message`
      *  — as proof + consent. The visitor must therefore also be a Pouchy user. */
-    pairVisitor(visitorToken: string): Promise<{
+    pairVisitor(visitorToken: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
         pairId: string | null;
     }>;
     /** Send a user text turn, optionally with images (data URLs) for a multimodal
@@ -279,12 +288,14 @@ export declare class CompanionClient {
         images?: string[];
         stream?: boolean;
         replyTimeoutMs?: number;
+        signal?: AbortSignal;
     }): Promise<SendTextReply>;
     sendText(text: string, opts?: {
         images?: string[];
         stream?: boolean;
         awaitReply?: boolean;
         replyTimeoutMs?: number;
+        signal?: AbortSignal;
     }): Promise<{
         seq: number | null;
     }>;
@@ -312,7 +323,9 @@ export declare class CompanionClient {
      *  (id → a fresh handle, source → this surface), so callers only supply the
      *  meaningful fields: `{ type, data, retained?, salience?, voiceRelevant? }`.
      *  A full CloudEvents envelope is still accepted (its fields win). */
-    sendWorldState(event: WorldStateInput | WorldStateInput[]): Promise<{
+    sendWorldState(event: WorldStateInput | WorldStateInput[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
         accepted: number;
         dropped: number;
         injected: number;
@@ -404,6 +417,7 @@ export declare class CompanionClient {
     recall(opts?: {
         limit?: number;
         query?: string;
+        signal?: AbortSignal;
     }): Promise<RecalledMemory[]>;
     /** Fetch this session's recent conversation turns (oldest→newest) so a
      *  reconnecting embed can restore its transcript. Distinct from `recall`
@@ -412,18 +426,23 @@ export declare class CompanionClient {
      *  first). `limit` defaults to 20, capped at 50. */
     history(opts?: {
         limit?: number;
+        signal?: AbortSignal;
     }): Promise<CompanionTurn[]>;
     /** Change this session's I/O modalities mid-session (e.g. enable/disable
      *  `voice`). The request is intersected with the token's granted modalities
      *  server-side — a session can't widen past its key — and the EFFECTIVE set is
      *  returned. Requires a live session. */
-    setModalities(modalities: string[]): Promise<{
+    setModalities(modalities: string[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
         modalities: string[];
     }>;
     /** Keepalive: bump this session's last-seen time so a long-idle embed stays
      *  "live" within the session TTL (cross-app A2A friend messages keep reaching
      *  it). Cheap; call it on a timer for a background tab. Requires a live session. */
-    ping(): Promise<void>;
+    ping(opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
     /** Remember a fact (into this app's namespace unless `namespace` is given and
      *  the token has the core scope). Intimate-tier writes are rejected server-side. */
     remember(fact: {
@@ -436,6 +455,8 @@ export declare class CompanionClient {
         kind?: string;
         namespace?: string;
         sensitivity?: 'public' | 'personal';
+    }, opts?: {
+        signal?: AbortSignal;
     }): Promise<{
         cloudId: string;
         namespace: string;
@@ -459,6 +480,8 @@ export declare class CompanionClient {
         name: string;
         kind?: string;
         locale?: string;
+    }, opts?: {
+        signal?: AbortSignal;
     }): Promise<{
         ok: boolean;
         summary: string;
@@ -477,6 +500,8 @@ export declare class CompanionClient {
         name: string;
         kind?: string;
         locale?: string;
+    }, opts?: {
+        signal?: AbortSignal;
     }): Promise<{
         ok: boolean;
         summary: string;
@@ -488,13 +513,17 @@ export declare class CompanionClient {
      *  portrait when one exists (null today for built-in models). URLs are absolute
      *  and the /models asset is CORS-enabled, so a cross-origin renderer can fetch
      *  the VRM directly. Reflects the user's live choice (built-in or custom). */
-    getAvatar(): Promise<CompanionAvatar>;
+    getAvatar(opts?: {
+        signal?: AbortSignal;
+    }): Promise<CompanionAvatar>;
     /** Read the companion instance's OWN wallet — nonzero stablecoin balances +
      *  total USD. Read-only and receive-only (spends go through the confirm-gated
      *  pay tools, never here). Requires the `wallet.read` scope (or `wallet.spend`,
      *  which subsumes it). Same data the companion gives when asked "what's my
      *  balance?". */
-    getWallet(): Promise<CompanionWallet>;
+    getWallet(opts?: {
+        signal?: AbortSignal;
+    }): Promise<CompanionWallet>;
     /** Canonical URL of the official Pouchy brand icon (square PNG, transparent
      *  background) at the given size. Static + public — needs no token — so it's
      *  safe to drop straight into an `<img src>` for "powered by Pouchy" badges,
@@ -549,7 +578,9 @@ export declare class CompanionClient {
      *  MAY call `confirmAction(sameConfirmId, true)` again to re-run it (the server
      *  dedupes a partial first attempt). A non-idempotent action (a message / skill)
      *  stays terminal and is never retryable. */
-    confirmAction(confirmId: string, approve: boolean): Promise<{
+    confirmAction(confirmId: string, approve: boolean, opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
         ok: boolean;
         status: 'approved' | 'denied' | 'exec_failed';
         outcome?: string;
@@ -559,7 +590,9 @@ export declare class CompanionClient {
      *  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[]>;
+    pendingConfirms(opts?: {
+        signal?: AbortSignal;
+    }): 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

@@ -120,7 +120,16 @@ export class CompanionClient {
         return major > 1 || (major === 1 && minor >= 1);
     }
     async fetchAuthed(url, init) {
-        const res = await this.doFetch(url, init);
+        let res;
+        try {
+            res = await this.doFetch(url, init);
+        }
+        catch (e) {
+            // A caller-supplied AbortSignal makes fetch throw a native AbortError —
+            // convert it at this single choke point so cancellation honors the
+            // "every helper rejects with CompanionError" contract (code 'aborted').
+            throw this.asCompanionError(e);
+        }
         const apiVersion = res.headers.get('x-pouchy-api-version');
         if (apiVersion)
             this.serverApiVersion = apiVersion;
@@ -135,7 +144,24 @@ export class CompanionClient {
         if (!(await this.tryRefreshToken()))
             return res;
         init.headers.Authorization = `Bearer ${this.opts.token}`;
-        return this.doFetch(url, init);
+        try {
+            return await this.doFetch(url, init);
+        }
+        catch (e) {
+            throw this.asCompanionError(e);
+        }
+    }
+    /** Normalize a thrown fetch error to a CompanionError. An AbortError (the
+     *  caller's signal fired) becomes a switchable `code: 'aborted'`; anything
+     *  else that is already a CompanionError passes through; the rest wrap as a
+     *  status-0 network failure. */
+    asCompanionError(e) {
+        if (e instanceof CompanionError)
+            return e;
+        const name = e?.name;
+        if (name === 'AbortError')
+            return new CompanionError('request aborted', 0, 'aborted');
+        return new CompanionError(e instanceof Error ? e.message : 'network request failed', 0);
     }
     /** Peek the error `code` of a failure response without consuming its body. */
     async errorCodeOf(res) {
@@ -168,11 +194,14 @@ export class CompanionClient {
         const header = Number(res.headers.get('Retry-After'));
         return Number.isFinite(header) && header >= 0 ? header : undefined;
     }
-    async postJson(path, body) {
+    async postJson(path, body, signal) {
         const res = await this.fetchAuthed(this.url(path), {
             method: 'POST',
             headers: this.jsonHeaders(),
-            body: JSON.stringify(body)
+            body: JSON.stringify(body),
+            // The signal rides `init`, so the 401-refresh retry in fetchAuthed
+            // reuses it automatically (init is passed to both doFetch calls).
+            ...(signal ? { signal } : {})
         });
         const json = (await res.json().catch(() => null));
         if (!res.ok || !json || json.ok === false) {
@@ -185,7 +214,7 @@ export class CompanionClient {
         return json;
     }
     /** Handshake: start or resume the session for this surface. */
-    async connect() {
+    async connect(opts) {
         const json = await this.postJson('/api/companion/session', {
             surface: this.opts.surface ?? 'default',
             modalities: this.opts.modalities,
@@ -194,7 +223,7 @@ export class CompanionClient {
             tools: this.opts.tools,
             appContext: this.opts.appContext,
             ...(this.opts.visitor ? { visitor: this.opts.visitor } : {})
-        });
+        }, opts?.signal);
         this._session = json.session;
         this.cursor = json.resumeCursor ?? 0;
         return {
@@ -211,7 +240,7 @@ export class CompanionClient {
      *  Two-token consent: this client's PAT (the owner's) must hold `represent:pair`,
      *  and you pass the VISITOR's own Pouchy PAT — which must hold `social.message`
      *  — as proof + consent. The visitor must therefore also be a Pouchy user. */
-    async pairVisitor(visitorToken) {
+    async pairVisitor(visitorToken, opts) {
         if (!this.opts.visitor) {
             throw new CompanionError('pairVisitor() requires a representative session (createCompanion({ visitor }))', 0, 'not_representative');
         }
@@ -220,7 +249,7 @@ export class CompanionClient {
         const json = await this.postJson('/api/companion/pair', {
             visitorToken,
             visitorId: this.opts.visitor.id
-        });
+        }, opts?.signal);
         return { pairId: json.pairId ?? null };
     }
     async sendText(text, opts) {
@@ -235,10 +264,10 @@ export class CompanionClient {
             return this.sendTextAwaitingReply(id, body, opts, turnId);
         const wantStream = opts?.stream ?? this.deltaHandlers.size > 0;
         if (!wantStream) {
-            const json = await this.postJson(`/api/companion/session/${id}/input`, body);
+            const json = await this.postJson(`/api/companion/session/${id}/input`, body, opts?.signal);
             return { seq: json.seq ?? null };
         }
-        return this.sendTextStreaming(id, body);
+        return this.sendTextStreaming(id, body, opts?.signal);
     }
     /** The awaitReply leg of sendText. Prefers the in-request answer (the
      *  streaming `done` frame's envelope); falls back to the next
@@ -265,12 +294,27 @@ export class CompanionClient {
         // promise past replyTimeoutMs (previously only the fallback wait was
         // bounded). The abort tears the in-flight stream down with it.
         const ac = new AbortController();
+        // Link the caller's signal: aborting it tears down the in-flight stream
+        // (via ac) AND rejects the whole operation with `aborted`, exactly like
+        // the deadline does. If it is already aborted, fail fast.
+        let onCallerAbort;
+        if (opts?.signal) {
+            if (opts.signal.aborted)
+                throw new CompanionError('request aborted', 0, 'aborted');
+            onCallerAbort = () => ac.abort();
+            opts.signal.addEventListener('abort', onCallerAbort, { once: true });
+        }
         let timer;
         const deadline = new Promise((_, reject) => {
             timer = setTimeout(() => {
                 ac.abort();
                 reject(new CompanionError(`timed out after ${timeoutMs}ms waiting for the reply — buffered mode needs start() polling the event stream`, 0, 'reply_timeout'));
             }, timeoutMs);
+            // 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 });
+            }
         });
         try {
             let seq = null;
@@ -308,6 +352,8 @@ export class CompanionClient {
             off();
             if (timer !== undefined)
                 clearTimeout(timer);
+            if (onCallerAbort)
+                opts?.signal?.removeEventListener('abort', onCallerAbort);
         }
     }
     /** The streaming leg of sendText: parse the POST response's SSE frames —
@@ -430,7 +476,7 @@ export class CompanionClient {
      *  (id → a fresh handle, source → this surface), so callers only supply the
      *  meaningful fields: `{ type, data, retained?, salience?, voiceRelevant? }`.
      *  A full CloudEvents envelope is still accepted (its fields win). */
-    async sendWorldState(event) {
+    async sendWorldState(event, opts) {
         const id = this.requireSession();
         const fill = (e) => ({
             ...e,
@@ -439,7 +485,7 @@ export class CompanionClient {
             source: e.source ?? this.opts.surface ?? 'companion-sdk'
         });
         const body = Array.isArray(event) ? { events: event.map(fill) } : fill(event);
-        const json = await this.postJson(`/api/companion/session/${id}/context`, body);
+        const json = await this.postJson(`/api/companion/session/${id}/context`, body, opts?.signal);
         // injected/reacted tell the host a live-call inject or a proactive text
         // reaction was triggered by this batch (0.28.0 — previously discarded).
         return {
@@ -674,15 +720,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()}`,
@@ -731,7 +782,8 @@ export class CompanionClient {
         const query = params.toString();
         const qs = query ? `?${query}` : '';
         const res = await this.fetchAuthed(this.url(`/api/companion/memory${qs}`), {
-            headers: { Authorization: `Bearer ${this.opts.token}` }
+            headers: { Authorization: `Bearer ${this.opts.token}` },
+            ...(opts?.signal ? { signal: opts.signal } : {})
         });
         const json = (await res.json().catch(() => null));
         if (!res.ok || !json || json.ok === false) {
@@ -747,7 +799,10 @@ export class CompanionClient {
     async history(opts) {
         const id = this.requireSession();
         const qs = opts?.limit ? `?limit=${encodeURIComponent(opts.limit)}` : '';
-        const res = await this.fetchAuthed(this.url(`/api/companion/session/${encodeURIComponent(id)}/history${qs}`), { headers: { Authorization: `Bearer ${this.opts.token}` } });
+        const res = await this.fetchAuthed(this.url(`/api/companion/session/${encodeURIComponent(id)}/history${qs}`), {
+            headers: { Authorization: `Bearer ${this.opts.token}` },
+            ...(opts?.signal ? { signal: opts.signal } : {})
+        });
         const json = (await res.json().catch(() => null));
         if (!res.ok || !json || json.ok === false) {
             throw new CompanionError(json?.error || `history failed (${res.status})`, res.status, json?.code);
@@ -758,7 +813,7 @@ export class CompanionClient {
      *  `voice`). The request is intersected with the token's granted modalities
      *  server-side — a session can't widen past its key — and the EFFECTIVE set is
      *  returned. Requires a live session. */
-    async setModalities(modalities) {
+    async setModalities(modalities, opts) {
         const id = this.requireSession();
         const res = await this.fetchAuthed(this.url(`/api/companion/session/${encodeURIComponent(id)}/modalities`), {
             method: 'POST',
@@ -766,7 +821,8 @@ export class CompanionClient {
                 Authorization: `Bearer ${this.opts.token}`,
                 'Content-Type': 'application/json'
             },
-            body: JSON.stringify({ modalities })
+            body: JSON.stringify({ modalities }),
+            ...(opts?.signal ? { signal: opts.signal } : {})
         });
         const json = (await res.json().catch(() => null));
         if (!res.ok || !json || json.ok === false) {
@@ -777,9 +833,13 @@ export class CompanionClient {
     /** Keepalive: bump this session's last-seen time so a long-idle embed stays
      *  "live" within the session TTL (cross-app A2A friend messages keep reaching
      *  it). Cheap; call it on a timer for a background tab. Requires a live session. */
-    async ping() {
+    async ping(opts) {
         const id = this.requireSession();
-        const res = await this.fetchAuthed(this.url(`/api/companion/session/${encodeURIComponent(id)}/ping`), { method: 'POST', headers: { Authorization: `Bearer ${this.opts.token}` } });
+        const res = await this.fetchAuthed(this.url(`/api/companion/session/${encodeURIComponent(id)}/ping`), {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${this.opts.token}` },
+            ...(opts?.signal ? { signal: opts.signal } : {})
+        });
         if (!res.ok) {
             const json = (await res.json().catch(() => null));
             throw new CompanionError(json?.error || `ping failed (${res.status})`, res.status, json?.code);
@@ -787,8 +847,8 @@ export class CompanionClient {
     }
     /** Remember a fact (into this app's namespace unless `namespace` is given and
      *  the token has the core scope). Intimate-tier writes are rejected server-side. */
-    async remember(fact) {
-        return this.postJson('/api/companion/memory', fact);
+    async remember(fact, opts) {
+        return this.postJson('/api/companion/memory', fact, opts?.signal);
     }
     /** Ingest a DOCUMENT into the user's knowledge base. Unlike `remember` (one
      *  short fact), this distils already-extracted text — a PDF body, a meeting
@@ -804,8 +864,8 @@ export class CompanionClient {
      *  are computed on the user's next first-party open (eventually-consistent
      *  semantic recall). `kind` is a free label for the source type (pdf / audio /
      *  note / …) used only for display + the materials icon. */
-    async ingestKnowledge(doc) {
-        return this.postJson('/api/companion/knowledge', doc);
+    async ingestKnowledge(doc, opts) {
+        return this.postJson('/api/companion/knowledge', doc, opts?.signal);
     }
     /** Convenience over `ingestKnowledge`: hand over a RAW file and Pouchy
      *  understands it server-side before ingesting — no parser/transcriber/vision on
@@ -815,8 +875,8 @@ export class CompanionClient {
      *  material). For other types, extract the text yourself and call
      *  `ingestKnowledge`. Same `memory.write:core` requirement and "My materials"
      *  integration as `ingestKnowledge`. */
-    async ingestFile(file) {
-        return this.postJson('/api/companion/knowledge/file', file);
+    async ingestFile(file, opts) {
+        return this.postJson('/api/companion/knowledge/file', file, opts?.signal);
     }
     /** Fetch the user's CURRENT companion avatar so the embedding can render the
      *  same virtual human Pouchy shows. The avatar is a VRM 3D model (`vrmUrl`,
@@ -824,9 +884,10 @@ export class CompanionClient {
      *  portrait when one exists (null today for built-in models). URLs are absolute
      *  and the /models asset is CORS-enabled, so a cross-origin renderer can fetch
      *  the VRM directly. Reflects the user's live choice (built-in or custom). */
-    async getAvatar() {
+    async getAvatar(opts) {
         const res = await this.fetchAuthed(this.url('/api/companion/avatar'), {
-            headers: { Authorization: `Bearer ${this.opts.token}` }
+            headers: { Authorization: `Bearer ${this.opts.token}` },
+            ...(opts?.signal ? { signal: opts.signal } : {})
         });
         const json = (await res.json().catch(() => null));
         if (!res.ok || !json || json.ok === false) {
@@ -845,9 +906,10 @@ export class CompanionClient {
      *  pay tools, never here). Requires the `wallet.read` scope (or `wallet.spend`,
      *  which subsumes it). Same data the companion gives when asked "what's my
      *  balance?". */
-    async getWallet() {
+    async getWallet(opts) {
         const res = await this.fetchAuthed(this.url('/api/companion/wallet'), {
-            headers: { Authorization: `Bearer ${this.opts.token}` }
+            headers: { Authorization: `Bearer ${this.opts.token}` },
+            ...(opts?.signal ? { signal: opts.signal } : {})
         });
         const json = (await res.json().catch(() => null));
         if (!res.ok || !json || json.ok === false) {
@@ -952,17 +1014,20 @@ export class CompanionClient {
      *  MAY call `confirmAction(sameConfirmId, true)` again to re-run it (the server
      *  dedupes a partial first attempt). A non-idempotent action (a message / skill)
      *  stays terminal and is never retryable. */
-    async confirmAction(confirmId, approve) {
+    async confirmAction(confirmId, approve, opts) {
         const sessionId = this.requireSession();
-        return this.postJson(`/api/companion/session/${encodeURIComponent(sessionId)}/confirm`, { confirmId, approve });
+        return this.postJson(`/api/companion/session/${encodeURIComponent(sessionId)}/confirm`, { confirmId, approve }, opts?.signal);
     }
     /** 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() {
+    async pendingConfirms(opts) {
         const sessionId = this.requireSession();
-        const res = await this.fetchAuthed(this.url(`/api/companion/session/${encodeURIComponent(sessionId)}/confirm`), { headers: { Authorization: `Bearer ${this.opts.token}` } });
+        const res = await this.fetchAuthed(this.url(`/api/companion/session/${encodeURIComponent(sessionId)}/confirm`), {
+            headers: { Authorization: `Bearer ${this.opts.token}` },
+            ...(opts?.signal ? { signal: opts.signal } : {})
+        });
         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, json?.code);
@@ -1040,8 +1105,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 +1162,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 +1215,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", "aborted"];
+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,20 @@
 // 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
+    'aborted' // a caller-supplied AbortSignal cancelled the request (0.29.0)
+];
 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.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.",
   "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",