@pouchy_ai/companion-sdk 0.28.1 → 0.29.1

package/CHANGELOG.md

@@ -12,6 +12,54 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [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
+
+- **`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
@@ -599,7 +647,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.28.1...HEAD
+[Unreleased]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.29.1...HEAD
+[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
 [0.27.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.26.1...companion-sdk-v0.27.0

package/README.md

@@ -122,6 +122,22 @@ 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, 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();
+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/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;
@@ -333,6 +346,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.
@@ -375,6 +389,8 @@ export declare class CompanionClient {
     sendToolResult(callId: string, result: {
         ok?: boolean;
         result?: unknown;
+    }, opts?: {
+        signal?: AbortSignal;
     }): Promise<{
         allDone: boolean;
     }>;
@@ -404,6 +420,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 +429,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 +458,8 @@ export declare class CompanionClient {
         kind?: string;
         namespace?: string;
         sensitivity?: 'public' | 'personal';
+    }, opts?: {
+        signal?: AbortSignal;
     }): Promise<{
         cloudId: string;
         namespace: string;
@@ -459,6 +483,8 @@ export declare class CompanionClient {
         name: string;
         kind?: string;
         locale?: string;
+    }, opts?: {
+        signal?: AbortSignal;
     }): Promise<{
         ok: boolean;
         summary: string;
@@ -477,6 +503,8 @@ export declare class CompanionClient {
         name: string;
         kind?: string;
         locale?: string;
+    }, opts?: {
+        signal?: AbortSignal;
     }): Promise<{
         ok: boolean;
         summary: string;
@@ -488,13 +516,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 +581,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 +593,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) {
@@ -165,14 +191,23 @@ 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'));
+        // 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);
         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 +220,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 +229,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 +246,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 +255,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 +270,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 +300,31 @@ 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;
+        // 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();
                 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) {
+                onCallerAbortReject = () => reject(new CompanionError('request aborted', 0, 'aborted'));
+                opts.signal.addEventListener('abort', onCallerAbortReject, { once: true });
+            }
         });
         try {
             let seq = null;
@@ -278,7 +332,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;
@@ -308,6 +365,10 @@ export class CompanionClient {
             off();
             if (timer !== undefined)
                 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 —
@@ -430,7 +491,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 +500,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 {
@@ -466,10 +527,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.
@@ -605,7 +663,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);
@@ -614,7 +672,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
@@ -736,7 +794,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) {
@@ -752,7 +811,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);
@@ -763,7 +825,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',
@@ -771,7 +833,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) {
@@ -782,9 +845,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);
@@ -792,8 +859,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
@@ -809,8 +876,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
@@ -820,8 +887,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`,
@@ -829,9 +896,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) {
@@ -850,9 +918,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) {
@@ -957,17 +1026,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);

package/dist/errors.d.ts

@@ -2,7 +2,7 @@ import type { CompanionErrorCode } from './protocol.js';
 /** Codes the SDK itself synthesizes (status 0 — never sent by the server).
  *  Runtime array so the drift test can assert every `new CompanionError(...)`
  *  call site uses a declared code; APPEND-ONLY like the server vocabulary. */
-export declare const SDK_SYNTHESIZED_ERROR_CODES: readonly ["reply_timeout", "needs_event_stream", "not_connected", "missing_option", "not_representative", "call_unsupported", "call_connect_failed", "call_dependency_missing"];
+export 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

package/dist/errors.js

@@ -14,7 +14,8 @@ export const SDK_SYNTHESIZED_ERROR_CODES = [
     '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
+    '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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.28.1",
-  "description": "Embed the Pouchy companion \u2014 chat, voice, tools, memory, live world-state, instant UI, and agent-to-agent messaging \u2014 in any app, game, or site.",
+  "version": "0.29.1",
+  "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",