@pouchy_ai/companion-sdk 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -12,6 +12,57 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-07-11
+
+### Fixed
+
+- **Voice-call connect failures now honor the typed-error contract.** The
+  call helpers (`connectCall` / `startCall` / `openCompanionCall`) used to
+  reject with plain `Error`s for the connect-step failures, so they carried
+  no `.code` and couldn't be `switch`ed like every other SDK rejection.
+  They now reject with `CompanionError` and three new client-synthesized
+  codes: `call_unsupported` (non-browser environment — no WebRTC/mic),
+  `call_connect_failed` (mic-permission timeout, SDP exchange failed or
+  timed out; `status` carries the HTTP status when the exchange answered
+  non-2xx), and `call_dependency_missing` (the optional
+  `@elevenlabs/client` peer dependency isn't installed). Like
+  `reply_timeout`/`stream_unauthorized` these are SDK-synthesized and
+  deliberately NOT part of the server-mirrored `COMPANION_ERROR_CODES`
+  HTTP vocabulary. Browser-native `getUserMedia` rejections (e.g.
+  `NotAllowedError` on permission denial) still propagate untouched.
+  `CompanionError` itself is unchanged and keeps its import path.
+
+## [0.25.0] - 2026-07-11
+
+### Added
+
+- **`sendText(text, { awaitReply: true })` — await the reply as the return
+  value.** Resolves with `{ seq, text, envelope }` (a new exported
+  `SendTextReply` type) once the turn completes: `text` is the authoritative
+  final assistant text (the same value `onMessage` receives), `envelope` the
+  full `companion.message` envelope. Request/response hosts — a CLI REPL, an
+  HTTP handler, a test — no longer hand-roll the resolve-on-message +
+  timeout gate every integration was writing. It rides the same streaming
+  request (the terminal `done` frame carries the envelope), so it works
+  without `start()`; `onMessage`/`onDelta` subscribers still fire as usual.
+  With `stream: false` (or an old server that answers plain JSON) it falls
+  back to the event stream — which then does need `start()` — resolving with
+  the next `companion.message` or rejecting with a client-side
+  `CompanionError` `code: 'reply_timeout'` after `replyTimeoutMs`
+  (default 60 000 ms).
+
+### Docs
+
+- OpenAPI spec corrections (served at `/api/companion/openapi.json`): the
+  memory-write body field is `content` (was wrongly documented as `text`),
+  knowledge ingest takes `name`/`kind`/`locale` (was `title`), the
+  modalities enum is `text|voice|call|files` (`avatar` never existed),
+  `GET …/confirm` (pending confirmations) is now documented, the session
+  handshake body documents `handles`/`contextKinds`/`visitor`, and memory
+  scopes use the real namespaced strings (`memory.read:app` …).
+- The `/sdk` reference described the call handle as having `.end()` — the
+  method is `close()`.
+
 ## [0.24.0] - 2026-07-11
 
 ### Added

package/README.md

@@ -96,6 +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). |
 | `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. |
@@ -146,7 +147,13 @@ 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). Every
+(0.24.0 — previously only the POST-backed calls did). 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
 outbound payload has a named type; `ToolCallPayload` (`{ id, name, args }`) types
 the `companion.tool_call` event, and `onToolCall`'s callback receives
 `ToolCallEvent` — the payload plus `argsJson` (pre-parsed args).

package/dist/call.js

@@ -10,6 +10,7 @@
 //
 // Browser-only (needs WebRTC + getUserMedia). Returns a handle to hang up and to
 // inject live context mid-call (the bridge the server uses for voiceRelevant).
+import { CompanionError } from './errors.js';
 /** Universal "host control" verbs the companion can call on ANY surface (web /
  *  game / app / hardware), regardless of provider. They're generic on purpose —
  *  the SPECIFIC intent rides in the string params, which YOUR surface interprets
@@ -147,7 +148,7 @@ const OPENAI_REALTIME_CALLS = 'https://api.openai.com/v1/realtime/calls';
 /** Open a live call from pre-minted credentials. */
 export async function openCompanionCall(creds, opts = {}, bridge) {
     if (typeof navigator === 'undefined' || !navigator.mediaDevices) {
-        throw new Error('connectCall is browser-only (needs WebRTC + microphone access)');
+        throw new CompanionError('connectCall is browser-only (needs WebRTC + microphone access)', 0, 'call_unsupported');
     }
     return creds.provider === 'openai-realtime'
         ? openOpenAICall(creds, opts, bridge)
@@ -176,7 +177,7 @@ async function getMicWithTimeout() {
         .catch(() => { });
     const timeout = new Promise((_, reject) => setTimeout(() => {
         timedOut = true;
-        reject(new Error('microphone request timed out'));
+        reject(new CompanionError('microphone request timed out', 0, 'call_connect_failed'));
     }, GUM_TIMEOUT_MS));
     return Promise.race([micPromise, timeout]);
 }
@@ -343,14 +344,14 @@ async function openOpenAICall(creds, opts, bridge) {
     catch {
         clearTimeout(sdpTimer);
         cleanupPartial();
-        throw new Error(sdpAbort.signal.aborted
+        throw new CompanionError(sdpAbort.signal.aborted
             ? 'OpenAI Realtime SDP exchange timed out'
-            : 'OpenAI Realtime SDP exchange failed');
+            : 'OpenAI Realtime SDP exchange failed', 0, 'call_connect_failed');
     }
     clearTimeout(sdpTimer);
     if (!res.ok) {
         cleanupPartial();
-        throw new Error(`OpenAI Realtime SDP exchange failed (${res.status})`);
+        throw new CompanionError(`OpenAI Realtime SDP exchange failed (${res.status})`, res.status, 'call_connect_failed');
     }
     await pc.setRemoteDescription({ type: 'answer', sdp: await res.text() });
     let closed = false;
@@ -458,7 +459,7 @@ async function openConvaiCall(creds, opts, bridge) {
         mod = await import('@elevenlabs/client');
     }
     catch {
-        throw new Error("elevenlabs-convai call needs the optional peer dependency '@elevenlabs/client' — install it (npm i @elevenlabs/client)");
+        throw new CompanionError("elevenlabs-convai call needs the optional peer dependency '@elevenlabs/client' — install it (npm i @elevenlabs/client)", 0, 'call_dependency_missing');
     }
     // App tools → EL client tools. NOTE: ElevenLabs only CALLS a client tool the
     // agent already knows (declared on the agent config); a shared Convai agent

package/dist/client.d.ts

@@ -166,12 +166,10 @@ export declare function pouchyBrandIconUrl(baseUrl: string, size?: BrandIconSize
  *  a method before `connect()`). `code` is a stable machine-readable tag you can
  *  switch on, shared with the `control.error` stream event vocabulary:
  *  `'not_connected'`, `'missing_option'`, `'not_representative'`, or the server's
- *  own error code for an HTTP failure (when it sends one). */
-export declare class CompanionError extends Error {
-    status: number;
-    code?: string;
-    constructor(message: string, status: number, code?: string);
-}
+ *  own error code for an HTTP failure (when it sends one). Defined in errors.ts
+ *  (so call.ts shares it cycle-free); re-exported here so the public import
+ *  path is unchanged. */
+export { CompanionError } from './errors.js';
 /** The server's memory-consolidation diagnostic from `endSession()` / `close()`.
  *  `ok` is whether consolidation ran; `facts` is how many memories it wrote;
  *  `skipped` (when present) says why nothing was written
@@ -181,6 +179,15 @@ export interface EndSessionResult {
     facts?: number;
     skipped?: string;
 }
+/** What `sendText(text, { awaitReply: true })` resolves with: the completed
+ *  turn's reply. `text` is the authoritative final assistant text (same value
+ *  onMessage receives); `envelope` is the full `companion.message` envelope
+ *  for hosts that want the id/ts. */
+export interface SendTextReply {
+    seq: number | null;
+    text: string;
+    envelope: CompanionEnvelope;
+}
 type Handler = (envelope: CompanionEnvelope) => void;
 /** Token-streaming subscriber (P1-2). `chunk` is a raw text delta of the reply
  *  being generated; `meta.reset` (with an empty chunk) tells the renderer to
@@ -244,13 +251,38 @@ export declare class CompanionClient {
      *  request — delta subscribers fire as chunks arrive, and onMessage still
      *  fires exactly ONCE with the authoritative final text (the streamed copy
      *  is emitted locally; the event-stream replay of the same envelope is
-     *  deduplicated by id). Pass `stream: false` to force the buffered path. */
+     *  deduplicated by id). Pass `stream: false` to force the buffered path.
+     *
+     *  AWAIT THE REPLY (request/response hosts — a REPL, an HTTP handler, a
+     *  test): pass `awaitReply: true` and the promise resolves with the final
+     *  reply `{ seq, text, envelope }` — no onMessage wiring, no hand-rolled
+     *  turn gate. It rides the same streaming request (the terminal `done`
+     *  frame carries the authoritative envelope), so it works without start();
+     *  onMessage/onDelta subscribers still fire as usual. Only when the reply
+     *  can't ride the request (`stream: false`, or an old server) does it fall
+     *  back to the event stream — which then DOES need start() — resolving with
+     *  the next `companion.message`, or rejecting with code `reply_timeout`
+     *  after `replyTimeoutMs` (default 60s). */
+    sendText(text: string, opts: {
+        awaitReply: true;
+        images?: string[];
+        stream?: boolean;
+        replyTimeoutMs?: number;
+    }): Promise<SendTextReply>;
     sendText(text: string, opts?: {
         images?: string[];
         stream?: boolean;
+        awaitReply?: boolean;
+        replyTimeoutMs?: number;
     }): Promise<{
         seq: number | null;
     }>;
+    /** The awaitReply leg of sendText. Prefers the in-request answer (the
+     *  streaming `done` frame's envelope); falls back to the next
+     *  `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. */
+    private sendTextAwaitingReply;
     /** The streaming leg of sendText: parse the POST response's SSE frames —
      *  `delta` / `reset` → delta subscribers, `done` → resolve (emitting the
      *  final envelope locally so onMessage fires immediately and the log replay
@@ -547,4 +579,3 @@ export declare class CompanionClient {
     private consume;
     private sleep;
 }
-export {};

package/dist/client.js

@@ -14,6 +14,7 @@
 // kept in lockstep by protocol.drift.test.ts.
 import { PROTOCOL_VERSION } from './protocol.js';
 import { parseSse } from './sse.js';
+import { CompanionError } from './errors.js';
 import { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_VISUAL_TOOLS, AVATAR_VISUAL_TOOL_NAMES } from './call.js';
 /** Model tool arguments are model output — tolerate junk without throwing. */
 function parseArgsJson(args) {
@@ -37,18 +38,10 @@ export function pouchyBrandIconUrl(baseUrl, size = 512) {
  *  a method before `connect()`). `code` is a stable machine-readable tag you can
  *  switch on, shared with the `control.error` stream event vocabulary:
  *  `'not_connected'`, `'missing_option'`, `'not_representative'`, or the server's
- *  own error code for an HTTP failure (when it sends one). */
-export class CompanionError extends Error {
-    status;
-    code;
-    constructor(message, status, code) {
-        super(message);
-        this.name = 'CompanionError';
-        this.status = status;
-        if (code)
-            this.code = code;
-    }
-}
+ *  own error code for an HTTP failure (when it sends one). Defined in errors.ts
+ *  (so call.ts shares it cycle-free); re-exported here so the public import
+ *  path is unchanged. */
+export { CompanionError } from './errors.js';
 const SEEN_CAP = 512;
 export class CompanionClient {
     opts;
@@ -177,26 +170,58 @@ export class CompanionClient {
         });
         return { pairId: json.pairId ?? null };
     }
-    /** Send a user text turn, optionally with images (data URLs) for a multimodal
-     *  turn — images need the `files` scope. The reply arrives on the event stream
-     *  as a `companion.message` — subscribe via onMessage()/start() to receive it.
-     *
-     *  TOKEN STREAMING (P1-2): when any onDelta() subscriber is registered (or
-     *  `opts.stream` is true), the reply streams token-by-token on this very
-     *  request — delta subscribers fire as chunks arrive, and onMessage still
-     *  fires exactly ONCE with the authoritative final text (the streamed copy
-     *  is emitted locally; the event-stream replay of the same envelope is
-     *  deduplicated by id). Pass `stream: false` to force the buffered path. */
     async sendText(text, opts) {
         const id = this.requireSession();
-        const wantStream = opts?.stream ?? this.deltaHandlers.size > 0;
         const body = { text, ...(opts?.images?.length ? { images: opts.images } : {}) };
+        if (opts?.awaitReply)
+            return this.sendTextAwaitingReply(id, body, opts);
+        const wantStream = opts?.stream ?? this.deltaHandlers.size > 0;
         if (!wantStream) {
             const json = await this.postJson(`/api/companion/session/${id}/input`, body);
             return { seq: json.seq ?? null };
         }
         return this.sendTextStreaming(id, body);
     }
+    /** The awaitReply leg of sendText. Prefers the in-request answer (the
+     *  streaming `done` frame's envelope); falls back to the next
+     *  `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) {
+        const timeoutMs = opts?.replyTimeoutMs ?? 60_000;
+        let resolveFallback;
+        const fallback = new Promise((res) => (resolveFallback = res));
+        const off = this.on('companion.message', (env) => resolveFallback(env));
+        let timer;
+        try {
+            let seq = null;
+            let envelope;
+            if (opts?.stream === false) {
+                const json = await this.postJson(`/api/companion/session/${sessionId}/input`, body);
+                seq = json.seq ?? null;
+            }
+            else {
+                const r = await this.sendTextStreaming(sessionId, body);
+                seq = r.seq;
+                envelope = r.envelope;
+            }
+            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);
+                    })
+                ]);
+            }
+            const replyText = envelope.payload?.text;
+            return { seq, text: typeof replyText === 'string' ? replyText : '', envelope };
+        }
+        finally {
+            off();
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
     /** The streaming leg of sendText: parse the POST response's SSE frames —
      *  `delta` / `reset` → delta subscribers, `done` → resolve (emitting the
      *  final envelope locally so onMessage fires immediately and the log replay
@@ -256,7 +281,7 @@ export class CompanionClient {
                     // 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 };
+                    return { seq: d.seq ?? null, envelope: d.envelope ?? undefined };
                 }
             }
             if (done)

package/dist/errors.d.ts

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

package/dist/errors.js

@@ -0,0 +1,20 @@
+// CompanionError — the one error type every SDK helper rejects with (README
+// contract: consumers `switch` on `.code` instead of string-matching prose).
+// 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) {
+        super(message);
+        this.name = 'CompanionError';
+        this.status = status;
+        if (code)
+            this.code = code;
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { CompanionClient, type CompanionClientOptions } from './client.js';
 export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js';
-export type { CompanionClientOptions, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, ToolCallEvent, WorldStateInput, CompanionAvatar, CompanionWallet, WalletBalance, BrandIconSize, EndSessionResult } from './client.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';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.24.0",
-  "description": "Embed the Pouchy companion \u2014 chat, voice, tools, memory, live world-state, instant UI, and agent-to-agent messaging \u2014 in any app, game, or site.",
+  "version": "0.26.0",
+  "description": "Embed the Pouchy companion — chat, voice, tools, memory, live world-state, instant UI, and agent-to-agent messaging — in any app, game, or site.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://pouchy.ai",