@pouchy_ai/companion-sdk 0.26.1 → 0.28.0

package/CHANGELOG.md

@@ -12,6 +12,91 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.28.0] - 2026-07-12
+
+### Added
+
+- **Turn correlation (`turnId` → `replyTo`).** Every `sendText` now mints a
+  `turnId` and sends it with the turn; servers on API ≥ 1.1 echo it back as
+  `replyTo` on the reply's `companion.message` — including a reply that lands
+  after an app-tool pause. `awaitReply`'s buffered fallback now resolves ONLY
+  on the correlated reply on those servers, so a proactive world-state
+  reaction or a confirm outcome can no longer steal the resolution (the known
+  0.25–0.27 caveat). Against older servers the legacy resolve-on-first
+  behavior is kept automatically (capability-detected via
+  `X-Pouchy-Api-Version`). New `MessagePayload` type (`{ text, replyTo? }`).
+- **`needs_event_stream` error.** With `awaitReply` and no `start()`, a turn
+  that pauses on app tool calls used to wait out the full `replyTimeoutMs`
+  and then time out — the post-resume reply can only arrive on the event
+  stream. It now rejects immediately with `code: "needs_event_stream"`.
+- **Typed confirm errors.** The confirm/step-up endpoints now carry codes:
+  `confirm_not_found`, `confirm_resolved`, `step_up_required`,
+  `step_up_failed` (vocabulary is append-only). The client no longer burns an
+  `onAuthError` token refresh on a step-up 401.
+- **`sendWorldState` returns `injected` and `reacted`** — whether the batch
+  triggered a live-call inject or a proactive text reaction (previously
+  discarded).
+- **429 `hint` surfaced.** The demo-budget hint ("provision a project…") is
+  appended to the thrown `CompanionError` message instead of being dropped.
+- **`CompanionErrorCodeValue`** — `CompanionError.code` is now typed as the
+  known vocabulary union (plus open `string`), so `switch` statements get
+  autocomplete and exhaustiveness help.
+
+### Fixed
+
+- **`replyTimeoutMs` now bounds the WHOLE awaitReply operation.** Previously
+  only the buffered-fallback wait was bounded — a stalled streaming response
+  could hang the promise indefinitely. The deadline now starts before the
+  POST and aborts the in-flight stream on expiry.
+- **`stop()` immediately followed by `start()` no longer leaves two live
+  receive loops.** Loops carry a generation token; a stale loop exits instead
+  of resurrecting alongside the new one (it double-polled the stream forever).
+- **`connectCall` cleans up on provider-initiated teardown.** A dropped call
+  (pc failure / provider disconnect) now runs the same unsubscribe +
+  `endSession({ transcript })` consolidation that `close()` runs — previously
+  the voice_inject listener leaked and the call was never consolidated into
+  memory. The buffered transcript is also capped (drop-oldest 200).
+- **A throwing `onDelta` handler no longer leaks the streaming reader** — the
+  stream is cancelled before the error propagates.
+- **`remember`'s `category` is now typed `'relationship' |
+  'shared_experience'`** — the only two values the server keeps; anything
+  else was silently discarded.
+- **`/input` image constraints now error instead of silently dropping.** A
+  non-`data:` URL or a 5th image is a 400 `invalid_request` — previously the
+  image was filtered out and the model just never saw it.
+- **OpenAPI drift**: `/input` documents `stream` + `turnId` + image rules;
+  confirm 200 documents `exec_failed`/`outcome`/`retryable`; hello.ack lists
+  `modalities`/`representative`/`visitorPaired`; `/pair` documents its body.
+
+## [0.27.0] - 2026-07-12
+
+### Added
+
+- **`rate_limited` error code + `CompanionError.retryAfter`.** The runtime's
+  two cost gates (per-user turn burst ceiling, demo daily budget) answer 429;
+  those responses now carry `code: "rate_limited"`, so the typed-error contract
+  finally covers the most common failure a busy integration hits. On any 429
+  the thrown `CompanionError` also exposes `retryAfter` (seconds, from the
+  body's `retryAfterSec` or the standard `Retry-After` header) so consumers can
+  back off precisely:
+  `if (e.code === 'rate_limited') await sleep(e.retryAfter * 1000)`.
+- **OpenAPI now documents the 429s** (shared `RateLimited` response on every
+  model-running path) and the `input` text cap below.
+
+### Changed
+
+- **`input` text is capped at 32,000 chars** (parity with `tool-result`); an
+  over-limit turn returns 413 `payload_too_large` instead of riding a multi-MB
+  string into the model context.
+- Malformed streaming frames no longer throw raw `SyntaxError` out of
+  `sendText`: a bad `delta` frame is skipped (the durable reply still lands),
+  and a bad `done` frame fails the turn with a clean `CompanionError` (502).
+
+### Fixed
+
+- OpenAPI: `/api/companion/pair` no longer claims to deliver paired-friend
+  messages (pairing only; sends happen inside companion turns).
+
 ## [0.26.1] - 2026-07-12
 
 ### Changed

package/README.md

@@ -96,7 +96,7 @@ local/device skills).
 
 | Method | What it does |
 |---|---|
-| `sendText(text, { awaitReply: true, replyTimeoutMs? })` | Request/response mode: the promise resolves with the completed turn's reply `{ seq, text, envelope }` (`SendTextReply`) — no `onMessage` wiring or hand-rolled turn gate. Works without `start()` (the reply rides the same streaming request); only the `stream: false` / old-server fallback needs the event stream, and it rejects with `code: 'reply_timeout'` after `replyTimeoutMs` (default 60s). |
+| `sendText(text, { awaitReply: true, replyTimeoutMs? })` | Request/response mode: the promise resolves with the completed turn's reply `{ seq, text, envelope }` (`SendTextReply`) — no `onMessage` wiring or hand-rolled turn gate. Works without `start()` when the turn completes in text (the reply rides the same streaming request). A turn that pauses on YOUR declared tools resolves via the event stream, so it DOES need `start()` — without it the promise rejects immediately with `code: 'needs_event_stream'`. `replyTimeoutMs` (default 60s) bounds the whole operation (0.28.0); on expiry it aborts the in-flight stream and rejects with `code: 'reply_timeout'`. Each turn carries a minted `turnId` the server echoes as `replyTo` on the reply (API ≥ 1.1), so the fallback resolves on THE reply — proactive messages can't steal it. |
 | `recall({ query?, limit? })` / `remember({ content, … })` | Read / write the token-scoped memory namespace. `query` runs SEMANTIC search over the facts server-side (embedding-based, ranked fallback); omit it for the plain importance/recency ranking. |
 | `ingestKnowledge({ text, name, … })` / `ingestFile(file)` | Push documents into the user's knowledge base ("My materials"); needs `memory.write:core`. |
 | `history({ limit? })` | Fetch the session transcript — restore chat on reload. |
@@ -147,15 +147,24 @@ HTTP `code` vocabulary behind `CompanionError.code`, e.g. `missing_scope` /
 `session_not_found` / `turn_pending`) — so you can assert the version, validate
 the event vocabulary, or switch on error codes without hard-coding strings.
 Every helper populates `CompanionError.code` when the server names a cause
-(0.24.0 — previously only the POST-backed calls did). The SDK also synthesizes
+(0.24.0 — previously only the POST-backed calls did). 0.27.0 adds
+`rate_limited` for the runtime's 429 cost gates (turn burst ceiling, demo
+daily budget); on those failures `CompanionError.retryAfter` carries the
+server's Retry-After in seconds, so back off with
+`if (e.code === 'rate_limited') await sleep(e.retryAfter * 1000)`. The SDK also synthesizes
 a few client-side codes outside that HTTP vocabulary: `reply_timeout`
 (awaitReply fallback gave up), `stream_unauthorized` (event-stream 401
 exhausted reconnects), and — 0.26.0 — the voice connect-step codes
 `call_unsupported` (no WebRTC/mic in this environment), `call_connect_failed`
 (mic timeout / SDP exchange failed) and `call_dependency_missing`
-(`@elevenlabs/client` not installed). Every
+(`@elevenlabs/client` not installed). 0.28.0 adds the confirm/step-up codes
+(`confirm_not_found`, `confirm_resolved`, `step_up_required`, `step_up_failed`),
+the client-side `needs_event_stream`, and types `CompanionError.code` as the
+`CompanionErrorCodeValue` union (autocomplete in your `switch`; still open for
+newer servers). Every
 outbound payload has a named type; `ToolCallPayload` (`{ id, name, args }`) types
-the `companion.tool_call` event, and `onToolCall`'s callback receives
+the `companion.tool_call` event, `MessagePayload` (`{ text, replyTo? }`) types
+`companion.message`, and `onToolCall`'s callback receives
 `ToolCallEvent` — the payload plus `argsJson` (pre-parsed args).
 
 For advanced voice hosts, the lower-level `openCompanionCall(client, options)`

package/dist/call.js

@@ -234,7 +234,17 @@ async function openOpenAICall(creds, opts, bridge) {
     const dc = pc.createDataChannel('oai-events');
     // `response.function_call_arguments.done` carries the call_id + args but often
     // not the name — the name arrives earlier on `response.output_item.added`; track it.
+    // Cancelled tool calls never reach `arguments.done`, so their entries were
+    // never deleted — cap the map (drop-oldest) so a long call can't grow it.
     const callNames = new Map();
+    const rememberCallName = (id, name) => {
+        callNames.set(id, name);
+        if (callNames.size > 64) {
+            const first = callNames.keys().next().value;
+            if (first !== undefined)
+                callNames.delete(first);
+        }
+    };
     if (bridge?.tools.length) {
         dc.addEventListener('open', () => {
             try {
@@ -271,7 +281,7 @@ async function openOpenAICall(creds, opts, bridge) {
             msg.item?.type === 'function_call' &&
             msg.item.call_id &&
             msg.item.name) {
-            callNames.set(msg.item.call_id, msg.item.name);
+            rememberCallName(msg.item.call_id, msg.item.name);
         }
         if (bridge && msg.type === 'response.function_call_arguments.done' && msg.call_id) {
             const callId = msg.call_id;

package/dist/client.d.ts

@@ -205,6 +205,7 @@ export declare class CompanionClient {
     private cursor;
     private streaming;
     private abort;
+    private streamGen;
     private readonly handlers;
     private readonly seen;
     private readonly deltaHandlers;
@@ -224,10 +225,20 @@ export declare class CompanionClient {
     /** doFetch with one transparent retry after a 401-triggered token refresh.
      *  Everything except the stream loop (which has its own auth handling) goes
      *  through here. */
+    private serverApiVersion;
+    /** True when the server echoes `replyTo` on companion.message (API ≥ 1.1) —
+     *  the strict awaitReply correlation is only safe to enforce there. */
+    private serverEchoesReplyTo;
     private fetchAuthed;
+    /** Peek the error `code` of a failure response without consuming its body. */
+    private errorCodeOf;
     private url;
     private jsonHeaders;
     private requireSession;
+    /** Retry-After in seconds for a throttled response: the JSON body's
+     *  `retryAfterSec` (companion rate-limit shape) wins, else the standard
+     *  Retry-After header. Undefined when the server named neither. */
+    private retryAfterFrom;
     private postJson;
     /** Handshake: start or resume the session for this surface. */
     connect(): Promise<HelloAck>;
@@ -304,6 +315,8 @@ export declare class CompanionClient {
     sendWorldState(event: WorldStateInput | WorldStateInput[]): Promise<{
         accepted: number;
         dropped: number;
+        injected: number;
+        reacted: boolean;
     }>;
     private randomId;
     /** Open the voice plane. Returns realtime credentials to connect DIRECTLY to
@@ -417,7 +430,9 @@ export declare class CompanionClient {
         content: string;
         importance?: number;
         confidence?: number;
-        category?: string;
+        /** Only these two are kept server-side — anything else is discarded, so
+         *  the type refuses it at compile time instead of dropping it silently. */
+        category?: 'relationship' | 'shared_experience';
         kind?: string;
         namespace?: string;
         sensitivity?: 'public' | 'personal';

package/dist/client.js

@@ -50,6 +50,11 @@ export class CompanionClient {
     cursor = 0;
     streaming = false;
     abort = null;
+    // Bumped on every start()/stop(): a loop whose generation is stale exits
+    // instead of resurrecting — stop() immediately followed by start() used to
+    // leave TWO concurrent receive loops polling forever (the old one saw
+    // `streaming === true` again after its backoff sleep).
+    streamGen = 0;
     handlers = new Map();
     seen = new Set();
     // Token-streaming delta subscribers (P1-2). When any are registered,
@@ -101,13 +106,47 @@ export class CompanionClient {
     /** doFetch with one transparent retry after a 401-triggered token refresh.
      *  Everything except the stream loop (which has its own auth handling) goes
      *  through here. */
+    // The running server's X-Pouchy-Api-Version (captured off every authed
+    // response) — capability detection for additive protocol features.
+    serverApiVersion = null;
+    /** True when the server echoes `replyTo` on companion.message (API ≥ 1.1) —
+     *  the strict awaitReply correlation is only safe to enforce there. */
+    serverEchoesReplyTo() {
+        const m = /^(\d+)\.(\d+)/.exec(this.serverApiVersion ?? '');
+        if (!m)
+            return false;
+        const major = Number(m[1]);
+        const minor = Number(m[2]);
+        return major > 1 || (major === 1 && minor >= 1);
+    }
     async fetchAuthed(url, init) {
         const res = await this.doFetch(url, init);
-        if (res.status !== 401 || !(await this.tryRefreshToken()))
+        const apiVersion = res.headers.get('x-pouchy-api-version');
+        if (apiVersion)
+            this.serverApiVersion = apiVersion;
+        if (res.status !== 401)
+            return res;
+        // A step-up 401 (biometric confirm) is NOT a token problem — refreshing
+        // and retrying would burn a backend re-mint on a doomed request. Only
+        // token-shaped 401s go through onAuthError.
+        const code = await this.errorCodeOf(res);
+        if (code === 'step_up_required' || code === 'step_up_failed')
+            return res;
+        if (!(await this.tryRefreshToken()))
             return res;
         init.headers.Authorization = `Bearer ${this.opts.token}`;
         return this.doFetch(url, init);
     }
+    /** Peek the error `code` of a failure response without consuming its body. */
+    async errorCodeOf(res) {
+        try {
+            const json = (await res.clone().json());
+            return typeof json?.code === 'string' ? json.code : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     url(path) {
         return this.opts.baseUrl.replace(/\/+$/, '') + path;
     }
@@ -119,6 +158,16 @@ export class CompanionClient {
             throw new CompanionError('CompanionClient: call connect() first', 0, 'not_connected');
         return this._session;
     }
+    /** Retry-After in seconds for a throttled response: the JSON body's
+     *  `retryAfterSec` (companion rate-limit shape) wins, else the standard
+     *  Retry-After header. Undefined when the server named neither. */
+    retryAfterFrom(res, json) {
+        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;
+    }
     async postJson(path, body) {
         const res = await this.fetchAuthed(this.url(path), {
             method: 'POST',
@@ -127,7 +176,11 @@ export class CompanionClient {
         });
         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);
+            // The 429 body carries an actionable `hint` (e.g. "provision a project
+            // …") — surface it instead of discarding it.
+            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 json;
     }
@@ -172,9 +225,14 @@ export class CompanionClient {
     }
     async sendText(text, opts) {
         const id = this.requireSession();
-        const body = { text, ...(opts?.images?.length ? { images: opts.images } : {}) };
+        // Client-minted correlation id (0.28.0): the server echoes it back as
+        // `replyTo` on this turn's companion.message — even across an app-tool
+        // pause — so awaitReply's fallback matches THE reply, not the first
+        // message that happens by (world-state reactions, confirm outcomes).
+        const turnId = `turn_${this.randomId()}`;
+        const body = { text, turnId, ...(opts?.images?.length ? { images: opts.images } : {}) };
         if (opts?.awaitReply)
-            return this.sendTextAwaitingReply(id, body, opts);
+            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);
@@ -187,31 +245,61 @@ export class CompanionClient {
      *  `companion.message` off the event stream, bounded by a timeout. The
      *  fallback subscription opens BEFORE the POST so a fast event-stream reply
      *  can't slip through the gap. */
-    async sendTextAwaitingReply(sessionId, body, opts) {
+    async sendTextAwaitingReply(sessionId, body, opts, turnId) {
         const timeoutMs = opts?.replyTimeoutMs ?? 60_000;
         let resolveFallback;
         const fallback = new Promise((res) => (resolveFallback = res));
-        const off = this.on('companion.message', (env) => resolveFallback(env));
+        // Correlate: resolve only on THIS turn's reply (`replyTo === turnId`).
+        // Servers on API ≥ 1.1 always echo it, so there an un-tagged message is
+        // PROACTIVE traffic (world-state reaction, confirm outcome) — skip it.
+        // Older servers never echo — keep the legacy resolve-on-first there.
+        const off = this.on('companion.message', (env) => {
+            const replyTo = env.payload?.replyTo;
+            if (replyTo === turnId)
+                return resolveFallback(env);
+            if (replyTo === undefined && !this.serverEchoesReplyTo())
+                resolveFallback(env);
+        });
+        // One deadline bounds the WHOLE operation (0.28.0): the timer starts
+        // before the POST, so a stalled streaming response can no longer hang the
+        // promise past replyTimeoutMs (previously only the fallback wait was
+        // bounded). The abort tears the in-flight stream down with it.
+        const ac = new AbortController();
         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);
+        });
         try {
             let seq = null;
             let envelope;
+            let pausedOnTools = false;
             if (opts?.stream === false) {
-                const json = await this.postJson(`/api/companion/session/${sessionId}/input`, body);
+                const json = await Promise.race([
+                    this.postJson(`/api/companion/session/${sessionId}/input`, body),
+                    deadline
+                ]);
                 seq = json.seq ?? null;
             }
             else {
-                const r = await this.sendTextStreaming(sessionId, body);
+                const r = await Promise.race([
+                    this.sendTextStreaming(sessionId, body, ac.signal),
+                    deadline
+                ]);
                 seq = r.seq;
                 envelope = r.envelope;
+                pausedOnTools = r.kind === 'tool_calls';
             }
             if (!envelope) {
-                envelope = await Promise.race([
-                    fallback,
-                    new Promise((_, reject) => {
-                        timer = setTimeout(() => reject(new CompanionError(`timed out after ${timeoutMs}ms waiting for the reply — buffered mode needs start() polling the event stream`, 0, 'reply_timeout')), timeoutMs);
-                    })
-                ]);
+                // A turn paused on app tool calls resolves via the event stream once
+                // the app posts results — without start() those events never arrive,
+                // so waiting out the timer is a guaranteed hang. Fail fast + say why.
+                if (pausedOnTools && !this.streaming) {
+                    throw new CompanionError('the turn paused on app tool calls — awaitReply needs start() (the event stream) to receive the post-resume reply', 0, 'needs_event_stream');
+                }
+                envelope = await Promise.race([fallback, deadline]);
             }
             const replyText = envelope.payload?.text;
             return { seq, text: typeof replyText === 'string' ? replyText : '', envelope };
@@ -227,18 +315,19 @@ export class CompanionClient {
      *  final envelope locally so onMessage fires immediately and the log replay
      *  dedups by id). Falls back to buffered semantics if the server ever
      *  responds with plain JSON (e.g. an old deployment). */
-    async sendTextStreaming(sessionId, body) {
+    async sendTextStreaming(sessionId, body, signal) {
         const res = await this.fetchAuthed(this.url(`/api/companion/session/${sessionId}/input`), {
             method: 'POST',
             headers: this.jsonHeaders(),
-            body: JSON.stringify({ ...body, stream: true })
+            body: JSON.stringify({ ...body, stream: true }),
+            ...(signal ? { signal } : {})
         });
         const ctype = res.headers.get('content-type') ?? '';
         if (!ctype.includes('text/event-stream')) {
             // 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);
+                throw new CompanionError(json?.error || `request failed (${res.status})`, res.status, json?.code, this.retryAfterFrom(res, json));
             }
             return { seq: json.seq ?? null };
         }
@@ -251,43 +340,80 @@ export class CompanionClient {
             for (const h of this.deltaHandlers)
                 h(chunk, meta);
         };
-        for (;;) {
-            const { done, value } = await reader.read();
-            if (value)
-                buf += decoder.decode(value, { stream: true });
-            const { events, rest } = parseSse(buf);
-            buf = rest;
-            for (const ev of events) {
-                if (ev.event === 'delta') {
-                    const d = JSON.parse(ev.data);
-                    if (typeof d.text === 'string' && d.text)
-                        fireDelta(d.text, {});
-                }
-                else if (ev.event === 'reset') {
-                    fireDelta('', { reset: true });
-                }
-                else if (ev.event === 'done') {
-                    const d = JSON.parse(ev.data);
-                    try {
-                        await reader.cancel();
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (value)
+                    buf += decoder.decode(value, { stream: true });
+                const { events, rest } = parseSse(buf);
+                buf = rest;
+                for (const ev of events) {
+                    if (ev.event === 'delta') {
+                        // A malformed delta frame is dropped, not fatal — losing one text
+                        // chunk beats throwing away the whole turn (the final message
+                        // arrives intact in the done frame / event stream regardless).
+                        let d;
+                        try {
+                            d = JSON.parse(ev.data);
+                        }
+                        catch {
+                            continue;
+                        }
+                        if (typeof d.text === 'string' && d.text)
+                            fireDelta(d.text, {});
                     }
-                    catch {
-                        /* stream already finished */
+                    else if (ev.event === 'reset') {
+                        fireDelta('', { reset: true });
                     }
-                    if (d.ok === false) {
-                        throw new CompanionError(d.error || 'turn failed', d.status ?? 500, d.code);
+                    else if (ev.event === 'done') {
+                        // The done frame carries the turn's resolution — unparseable means
+                        // the turn's outcome is unknowable, so fail it explicitly instead
+                        // of letting a raw SyntaxError escape the SDK.
+                        let d;
+                        try {
+                            d = JSON.parse(ev.data);
+                        }
+                        catch {
+                            try {
+                                await reader.cancel();
+                            }
+                            catch {
+                                /* stream already finished */
+                            }
+                            throw new CompanionError('malformed done frame', 502);
+                        }
+                        try {
+                            await reader.cancel();
+                        }
+                        catch {
+                            /* stream already finished */
+                        }
+                        if (d.ok === false) {
+                            throw new CompanionError(d.error || 'turn failed', d.status ?? 500, d.code);
+                        }
+                        // Emit the final envelope NOW so onMessage fires with zero poll
+                        // latency; the event-stream replay of the same id is deduped.
+                        if (d.envelope && typeof d.envelope === 'object')
+                            this.emit(d.envelope);
+                        return { seq: d.seq ?? null, envelope: d.envelope ?? undefined, kind: d.kind };
                     }
-                    // Emit the final envelope NOW so onMessage fires with zero poll
-                    // latency; the event-stream replay of the same id is deduped.
-                    if (d.envelope && typeof d.envelope === 'object')
-                        this.emit(d.envelope);
-                    return { seq: d.seq ?? null, envelope: d.envelope ?? undefined };
                 }
+                if (done)
+                    break;
             }
-            if (done)
-                break;
+            throw new CompanionError('stream ended without a done frame', 502);
+        }
+        catch (e) {
+            // A throwing user onDelta handler (or an abort) must not leak the
+            // reader — cancel so the connection is released, then rethrow.
+            try {
+                await reader.cancel();
+            }
+            catch {
+                /* stream already finished */
+            }
+            throw e;
         }
-        throw new CompanionError('stream ended without a done frame', 502);
     }
     /** Subscribe to token-streaming deltas of the reply (P1-2). Registering a
      *  subscriber makes sendText stream automatically. Returns an unsubscribe
@@ -314,7 +440,14 @@ export class CompanionClient {
         });
         const body = Array.isArray(event) ? { events: event.map(fill) } : fill(event);
         const json = await this.postJson(`/api/companion/session/${id}/context`, body);
-        return { accepted: json.accepted ?? 0, dropped: json.dropped ?? 0 };
+        // 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 {
+            accepted: json.accepted ?? 0,
+            dropped: json.dropped ?? 0,
+            injected: json.injected ?? 0,
+            reacted: json.reacted === true
+        };
     }
     randomId() {
         const c = globalThis.crypto;
@@ -350,12 +483,36 @@ export class CompanionClient {
         // the caller's own onTranscript.
         const transcript = [];
         const callerOnTranscript = opts?.onTranscript;
+        const callerOnError = opts?.onError;
+        // Cleanup must run whichever side ends the call — the app calling close()
+        // OR a provider-initiated teardown (pc failure / EL disconnect), which
+        // surfaces as onError with no close() following. Idempotent. `unsub` is
+        // assigned after the call opens; a connect-phase onError finds the no-op.
+        let unsub = () => { };
+        let cleaned = false;
+        const cleanup = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            unsub();
+            // Consolidate this call into durable memory (best-effort, keepalive).
+            void this.endSession({ transcript });
+        };
         const wrappedOpts = {
             ...opts,
             onTranscript: (e) => {
-                if (e?.text?.trim())
+                // Cap the buffer (endSession consolidates the tail anyway) so an
+                // hours-long call can't grow this array unbounded.
+                if (e?.text?.trim()) {
                     transcript.push({ role: e.role, text: e.text });
+                    if (transcript.length > 200)
+                        transcript.splice(0, transcript.length - 200);
+                }
                 callerOnTranscript?.(e);
+            },
+            onError: (err) => {
+                cleanup();
+                callerOnError?.(err);
             }
         };
         // Let the live voice call invoke tools — routed through the SAME
@@ -385,7 +542,7 @@ export class CompanionClient {
         // Bridge server-pushed voiceRelevant moments into the live call (item 2):
         // the server emits companion.voice_inject while the call is active; inject
         // each into the session so the companion reacts out loud. Needs start().
-        const unsub = this.on('companion.voice_inject', (env) => {
+        unsub = this.on('companion.voice_inject', (env) => {
             const p = env.payload;
             if (typeof p?.text === 'string' && p.text)
                 call.injectEvent(p.text, p.speak !== false);
@@ -394,10 +551,8 @@ export class CompanionClient {
         return {
             ...call,
             close: () => {
-                unsub();
                 close();
-                // Consolidate this call into durable memory (best-effort, keepalive).
-                void this.endSession({ transcript });
+                cleanup();
             }
         };
     }
@@ -864,19 +1019,20 @@ export class CompanionClient {
             return;
         this.requireSession();
         this.streaming = true;
+        const gen = ++this.streamGen;
         const wsImpl = this.opts.webSocketImpl ?? globalThis.WebSocket;
         if (this.opts.stream === 'websocket' && wsImpl) {
-            void this.wsLoop(wsImpl);
+            void this.wsLoop(wsImpl, gen);
         }
         else {
-            void this.loop();
+            void this.loop(gen);
         }
     }
     /** WebSocket receive loop. Resolves when the socket closes; on any failure
      *  while still streaming it falls back to the SSE loop, so opting into WS can
      *  only ever DEGRADE to SSE, never drop replies. Input is still sent over
      *  REST (sendInput) — receiving is the latency-sensitive half. */
-    async wsLoop(WS) {
+    async wsLoop(WS, gen) {
         const id = this.requireSession();
         const { deriveWsStreamUrl, decodeWsMessage } = await import('./ws-transport.js');
         // Reconnect across CLEAN closes (a WS gateway with a bounded lifetime, like
@@ -884,7 +1040,7 @@ 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.
-        while (this.streaming) {
+        while (this.streaming && gen === this.streamGen) {
             let errored = false;
             try {
                 await new Promise((resolve, reject) => {
@@ -911,7 +1067,7 @@ export class CompanionClient {
                             resolve();
                     };
                     ws.onmessage = (ev) => {
-                        if (!this.streaming) {
+                        if (!this.streaming || gen !== this.streamGen) {
                             settle();
                             return;
                         }
@@ -924,7 +1080,7 @@ export class CompanionClient {
                     ws.onclose = () => settle();
                     // Stopping the stream closes the socket + clears this timer.
                     poll = setInterval(() => {
-                        if (!this.streaming)
+                        if (!this.streaming || gen !== this.streamGen)
                             settle();
                     }, 250);
                 });
@@ -934,8 +1090,8 @@ export class CompanionClient {
             }
             if (errored) {
                 // Socket unavailable / rejected — degrade to the robust SSE loop (once).
-                if (this.streaming)
-                    await this.loop();
+                if (this.streaming && gen === this.streamGen)
+                    await this.loop(gen);
                 return;
             }
             // Clean close: the while-guard reconnects if still streaming, else exits.
@@ -944,6 +1100,7 @@ export class CompanionClient {
     /** Stop the event stream. */
     stop() {
         this.streaming = false;
+        this.streamGen++; // invalidate any loop still unwinding
         this.abort?.abort();
         this.abort = null;
     }
@@ -1013,11 +1170,11 @@ export class CompanionClient {
         if (env && typeof env.type === 'string')
             this.emit(env);
     }
-    async loop() {
+    async loop(gen) {
         const id = this.requireSession();
         let backoff = 500;
         let authRefreshes = 0; // consecutive 401→refresh cycles without a healthy connect
-        while (this.streaming) {
+        while (this.streaming && gen === this.streamGen) {
             this.abort = new AbortController();
             try {
                 const res = await this.doFetch(this.url(`/api/companion/session/${id}/stream?cursor=${this.cursor}`), { headers: { Authorization: `Bearer ${this.opts.token}` }, signal: this.abort.signal });
@@ -1050,7 +1207,7 @@ export class CompanionClient {
                     break;
                 }
                 if (!res.ok || !res.body) {
-                    if (!this.streaming)
+                    if (!this.streaming || gen !== this.streamGen)
                         break;
                     await this.sleep(backoff);
                     backoff = Math.min(backoff * 2, 8000);
@@ -1058,21 +1215,21 @@ export class CompanionClient {
                 }
                 backoff = 500; // healthy connection resets backoff
                 authRefreshes = 0;
-                await this.consume(res.body);
+                await this.consume(res.body, gen);
             }
             catch {
-                if (!this.streaming)
+                if (!this.streaming || gen !== this.streamGen)
                     break;
                 await this.sleep(backoff);
                 backoff = Math.min(backoff * 2, 8000);
             }
         }
     }
-    async consume(body) {
+    async consume(body, gen) {
         const reader = body.getReader();
         const decoder = new TextDecoder();
         let buf = '';
-        while (this.streaming) {
+        while (this.streaming && gen === this.streamGen) {
             const { done, value } = await reader.read();
             if (done)
                 break;

package/dist/errors.d.ts

@@ -1,9 +1,16 @@
 /** 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. */
+ *  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 & {});
 export declare class CompanionError extends Error {
     status: number;
-    code?: string;
-    constructor(message: string, status: number, code?: string);
+    code?: CompanionErrorCodeValue;
+    retryAfter?: number;
+    constructor(message: string, status: number, code?: string, retryAfter?: number);
 }

package/dist/errors.js

@@ -3,18 +3,17 @@
 // 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).
-/** 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. */
 export class CompanionError extends Error {
     status;
     code;
-    constructor(message, status, code) {
+    retryAfter;
+    constructor(message, status, code, retryAfter) {
         super(message);
         this.name = 'CompanionError';
         this.status = status;
         if (code)
             this.code = code;
+        if (typeof retryAfter === 'number' && Number.isFinite(retryAfter))
+            this.retryAfter = retryAfter;
     }
 }

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 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 { 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 } from './protocol.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';
 /** Create a companion client. */

package/dist/protocol.d.ts

@@ -16,7 +16,7 @@ export type MessageType = InboundType | OutboundType;
  *  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.
  *  Consumers can switch on these instead of string-matching error prose. */
-export declare const COMPANION_ERROR_CODES: readonly ["missing_token", "invalid_token", "missing_scope", "invalid_request", "session_not_found", "turn_pending", "no_pending_tools", "unknown_call", "payload_too_large", "forbidden", "unavailable"];
+export declare const COMPANION_ERROR_CODES: readonly ["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"];
 export type CompanionErrorCode = (typeof COMPANION_ERROR_CODES)[number];
 /** The single envelope every control/data-plane message shares. */
 export interface CompanionEnvelope<T = unknown> {
@@ -163,6 +163,14 @@ export interface VoiceInjectPayload {
 export interface TypingPayload {
     active: boolean;
 }
+/** Payload of a `companion.message` event — the companion's text reply. When
+ *  the turn was started by this client with sendText, `replyTo` echoes the
+ *  request's turnId (0.28.0) so a reply can be correlated to its turn;
+ *  proactive messages (world-state reactions, confirm outcomes) carry none. */
+export interface MessagePayload {
+    text: string;
+    replyTo?: string;
+}
 /** A live world-state event the app streams in. `retained:true` = latest-value
  *  state (coalesced); `retained:false` = a transient moment carrying `salience`
  *  and optional `voiceRelevant`. */

package/dist/protocol.js

@@ -54,6 +54,11 @@ export const COMPANION_ERROR_CODES = [
     'no_pending_tools', // 409 — tool result posted but nothing is pending
     'unknown_call', // 404 — tool result for a callId the turn didn't issue
     'payload_too_large', // 413 — body/image over the documented cap
+    'rate_limited', // 429 — turn burst / demo daily budget spent; Retry-After + retryAfterSec say when
     'forbidden', // 403 — authorization denial other than a missing scope
-    'unavailable' // 503 — backing store/provider not configured or down
+    'unavailable', // 503 — backing store/provider not configured or down
+    'confirm_not_found', // 404 — confirmId unknown or not on this session
+    'confirm_resolved', // 409 — confirm already approved/denied/expired (single-use)
+    'step_up_required', // 401 — approval needs a passkey assertion (fetch confirm/stepup)
+    'step_up_failed' // 401 — the passkey assertion didn't verify; retry the step-up
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.26.1",
+  "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.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",