@pouchy_ai/companion-sdk 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -12,6 +12,69 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.24.0] - 2026-07-11
+
+### Added
+
+- **`CompanionError.code` is now populated on EVERY helper, and the vocabulary
+  ships in the package.** `COMPANION_ERROR_CODES` (+ the `CompanionErrorCode`
+  type) is exported — the append-only HTTP `code` list the server emits
+  (`missing_scope`, `session_not_found`, `turn_pending`, …), drift-tested
+  against the server source. Previously only `postJson`-backed calls carried
+  `code`; the GET/stream helpers (`recall`, `history`, `setModalities`,
+  `ping`, `getAvatar`, `getWallet`, `pendingConfirms`, and `sendText`'s
+  streaming fallback) constructed `CompanionError` without it, so a
+  `missing_scope` 403 from `getWallet()` had `code === undefined`. All of them
+  now thread the server's `code` through — switch on it instead of matching
+  error prose.
+
+### Changed (server-side, shipped with the platform)
+
+- `GET …/history` now enforces the `chat` scope the API reference always
+  documented (a token without `chat` gets a 403 `missing_scope` instead of the
+  transcript).
+- The `control.error` stream code `call_mint_failed` (voice-credential mint
+  failure) is now documented everywhere the other stream codes are.
+
+### Docs
+
+- `/sdk` REST quickstart now shows the REAL session → input flow (the previous
+  snippet showed a `POST /api/companion/message` endpoint that never existed)
+  and the 0.23.0 `argsJson` tool-handler form.
+- OpenAPI: `history` response shape corrected to `{ ok, count, history }`;
+  `confirm` documents instance-token auth + the full
+  `{ status, outcome?, retryable? }` response; `end` summary reflects memory
+  consolidation.
+- `wallet.read` scope comment no longer claims there is no standalone REST
+  endpoint (`GET /api/companion/wallet` shipped in 0.20.0).
+
+## [0.23.0] - 2026-07-11
+
+### Added
+
+- **`onToolCall` hands you pre-parsed arguments.** The callback now receives a
+  `ToolCallEvent` — the `companion.tool_call` wire payload plus `argsJson`:
+  `args` pre-parsed as JSON (`undefined` when empty or malformed). Every tool
+  handler was re-implementing the same `try { JSON.parse(args) } catch {}`
+  boilerplate; now `const { item } = call.argsJson as {...}` just works, and the
+  raw `args` string is still there when you need the exact model output.
+  `ToolCallEvent` is exported. Backwards-compatible (the type extends
+  `ToolCallPayload`).
+
+### Docs
+
+- The `control.error` stream-plane code vocabulary (`agent_error`,
+  `stream_unauthorized`) is now documented in the protocol/API references, the
+  README event tables, and pouchy.ai/sdk — previously the codes were emitted
+  but listed nowhere.
+- The pouchy.ai/sdk CDN snippet now uses the canonical self-hosted bundle URL
+  (`https://pouchy.ai/sdk/companion-sdk.js`) and includes the
+  `@elevenlabs/client` import-map entry voice needs.
+- `openCompanionCall` / `VoiceToolBridge` (the advanced voice primitive
+  `connectCall`/`startCall` wrap) get a pointer in the package README.
+
+No wire-protocol change (`PROTOCOL_VERSION` stays `1`).
+
 ## [0.22.0] - 2026-07-11
 
 ### Added

package/README.md

@@ -67,7 +67,7 @@ Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers:
 | --- | --- | --- |
 | `onMessage(fn)` | `companion.message` | the assistant reply (fires exactly once per turn, streaming or not) |
 | `onDelta(fn)` | *(POST-response SSE)* | **token streaming** — registering makes `sendText` stream the reply as it is generated: `fn(chunk, {reset?})` fires per text chunk (`reset` = clear the partial — that text was tool-call deliberation); `onMessage` then fires once with the authoritative final text (replay-deduplicated). Force per call with `sendText(text, { stream: true \| false })` |
-| `onToolCall(fn)` | `companion.tool_call` | the companion asks your app to run a declared tool → `sendToolResult` |
+| `onToolCall(fn)` | `companion.tool_call` | the companion asks your app to run a declared tool → `sendToolResult`. The call carries `argsJson` — `args` pre-parsed as JSON (undefined on empty/malformed args) |
 | `onRender(fn)` | `companion.ui_action` | **Instant UI** — draw `payload.interface` (platform-neutral genui schema) with your own renderer (web / iOS / Android / CLI). Needs `ui.render` |
 | `onInterfaceUpdate(fn)` | `companion.ui_update` | live `{key,value}` update to an already-rendered panel (no rebuild) |
 | `onSocialMessage(fn)` | `companion.social_message` | inbound A2A friend message, delivered cross-app. Needs `social.message` |
@@ -77,7 +77,7 @@ Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers:
 | `onVoiceInject(fn)` | `companion.voice_inject` | `fn({text, speak})` — a `voiceRelevant` world-state line to say aloud during a live call; route `text` to your voice session when `speak` |
 | `onTyping(fn)` | `companion.typing` | activity indicator — `fn({active})` fires `true` when a turn starts working and `false` when it finishes / pauses, spanning the tool-loop / thinking phase before the first text delta. Drive a "typing…" state |
 | `onUsage(fn)` | `control.usage` | per-token metering echo. _(reserved — not emitted yet)_ |
-| `onError(fn)` | `control.error` | agent / stream errors |
+| `onError(fn)` | `control.error` | agent / stream errors — `agent_error` (server-side turn failed after accept; safe to re-send), `call_mint_failed` (voice-credential mint failed — retry later or fall back to text) or the SDK-synthesized `stream_unauthorized` (stream 401 exhausted reconnects — refresh the token, `start()` again) |
 
 ### Instant UI
 
@@ -141,10 +141,19 @@ exported: `COMPANION_MODALITIES`, `REPRESENT_SCOPES`, `DEFAULT_MODALITIES`,
 the SDK's drift test.
 
 The wire-protocol runtime constants are exported too — `PROTOCOL_VERSION`,
-`INBOUND_TYPES`, and `OUTBOUND_TYPES` — so you can assert the version or
-enumerate/validate the event vocabulary without hard-coding strings. Every
+`INBOUND_TYPES`, `OUTBOUND_TYPES`, and `COMPANION_ERROR_CODES` (the append-only
+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
 outbound payload has a named type; `ToolCallPayload` (`{ id, name, args }`) types
-the `companion.tool_call` event and `onToolCall`'s callback.
+the `companion.tool_call` event, and `onToolCall`'s callback receives
+`ToolCallEvent` — the payload plus `argsJson` (pre-parsed args).
+
+For advanced voice hosts, the lower-level `openCompanionCall(client, options)`
+primitive that `connectCall`/`startCall` wrap is exported too (bring-your-own
+call lifecycle; see `docs/companion-integration-faq.md`).
 
 ## Representative mode (代聊)
 

package/dist/client.d.ts

@@ -75,6 +75,13 @@ export interface CompanionToolDecl {
     description?: string;
     parameters?: Record<string, unknown>;
 }
+/** What `onToolCall` hands your handler: the `companion.tool_call` wire payload
+ *  plus `argsJson` — `args` pre-parsed as JSON. `undefined` when `args` is
+ *  empty or not valid JSON; keep reading the raw `args` string when you need
+ *  the exact model output. */
+export interface ToolCallEvent extends ToolCallPayload {
+    argsJson?: unknown;
+}
 /** Voice-plane credentials, discriminated by provider (see startCall). */
 export type CallCredentials = {
     provider: 'elevenlabs-convai';
@@ -332,8 +339,11 @@ export declare class CompanionClient {
      *  string fed back to the voice model. Times out so a missing result can't
      *  hang the call. */
     private invokeVoiceTool;
-    /** Convenience: subscribe to tool-call requests from the companion. */
-    onToolCall(handler: (call: ToolCallPayload, envelope: CompanionEnvelope) => void): () => void;
+    /** Convenience: subscribe to tool-call requests from the companion. The call
+     *  carries the wire payload plus `argsJson` — `args` pre-parsed as JSON
+     *  (undefined when empty or malformed), so handlers don't each re-implement
+     *  the same try/catch around `JSON.parse(args)`. */
+    onToolCall(handler: (call: ToolCallEvent, envelope: CompanionEnvelope) => void): () => void;
     /** Convenience: subscribe to errors the companion surfaces — server-side agent
      *  errors and stream failures (e.g. a permanent `stream_unauthorized`) both
      *  arrive as `control.error`. Returns an unsubscribe fn. */

package/dist/client.js

@@ -15,6 +15,17 @@
 import { PROTOCOL_VERSION } from './protocol.js';
 import { parseSse } from './sse.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) {
+    if (!args.trim())
+        return undefined;
+    try {
+        return JSON.parse(args);
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Canonical URL of the official Pouchy brand icon at `size` px, derived from a
  *  deployment origin. Standalone (no client/token needed) so a surface can show
  *  the Pouchy mark before/without connecting. */
@@ -202,7 +213,7 @@ export class CompanionClient {
             // Old server / error before the stream opened — behave like postJson.
             const json = (await res.json().catch(() => null));
             if (!res.ok || !json || json.ok === false) {
-                throw new CompanionError(json?.error || `request failed (${res.status})`, res.status);
+                throw new CompanionError(json?.error || `request failed (${res.status})`, res.status, json?.code);
             }
             return { seq: json.seq ?? null };
         }
@@ -239,7 +250,7 @@ export class CompanionClient {
                         /* stream already finished */
                     }
                     if (d.ok === false) {
-                        throw new CompanionError(d.error || 'turn failed', d.status ?? 500);
+                        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.
@@ -501,12 +512,16 @@ export class CompanionClient {
             });
         });
     }
-    /** Convenience: subscribe to tool-call requests from the companion. */
+    /** Convenience: subscribe to tool-call requests from the companion. The call
+     *  carries the wire payload plus `argsJson` — `args` pre-parsed as JSON
+     *  (undefined when empty or malformed), so handlers don't each re-implement
+     *  the same try/catch around `JSON.parse(args)`. */
     onToolCall(handler) {
         return this.on('companion.tool_call', (env) => {
             const p = env.payload;
             if (typeof p?.id === 'string' && typeof p?.name === 'string') {
-                handler({ id: p.id, name: p.name, args: typeof p.args === 'string' ? p.args : '' }, env);
+                const args = typeof p.args === 'string' ? p.args : '';
+                handler({ id: p.id, name: p.name, args, argsJson: parseArgsJson(args) }, env);
             }
         });
     }
@@ -540,7 +555,7 @@ export class CompanionClient {
         });
         const json = (await res.json().catch(() => null));
         if (!res.ok || !json || json.ok === false) {
-            throw new CompanionError(json?.error || `recall failed (${res.status})`, res.status);
+            throw new CompanionError(json?.error || `recall failed (${res.status})`, res.status, json?.code);
         }
         return json.memories ?? [];
     }
@@ -555,7 +570,7 @@ export class CompanionClient {
         const res = await this.fetchAuthed(this.url(`/api/companion/session/${encodeURIComponent(id)}/history${qs}`), { headers: { Authorization: `Bearer ${this.opts.token}` } });
         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);
+            throw new CompanionError(json?.error || `history failed (${res.status})`, res.status, json?.code);
         }
         return json.history ?? [];
     }
@@ -575,7 +590,7 @@ export class CompanionClient {
         });
         const json = (await res.json().catch(() => null));
         if (!res.ok || !json || json.ok === false) {
-            throw new CompanionError(json?.error || `setModalities failed (${res.status})`, res.status);
+            throw new CompanionError(json?.error || `setModalities failed (${res.status})`, res.status, json?.code);
         }
         return { modalities: json.modalities ?? modalities };
     }
@@ -587,7 +602,7 @@ export class CompanionClient {
         const res = await this.fetchAuthed(this.url(`/api/companion/session/${encodeURIComponent(id)}/ping`), { method: 'POST', headers: { Authorization: `Bearer ${this.opts.token}` } });
         if (!res.ok) {
             const json = (await res.json().catch(() => null));
-            throw new CompanionError(json?.error || `ping failed (${res.status})`, res.status);
+            throw new CompanionError(json?.error || `ping failed (${res.status})`, res.status, json?.code);
         }
     }
     /** Remember a fact (into this app's namespace unless `namespace` is given and
@@ -634,7 +649,7 @@ export class CompanionClient {
         });
         const json = (await res.json().catch(() => null));
         if (!res.ok || !json || json.ok === false) {
-            throw new CompanionError(json?.error || `avatar fetch failed (${res.status})`, res.status);
+            throw new CompanionError(json?.error || `avatar fetch failed (${res.status})`, res.status, json?.code);
         }
         return {
             name: json.name ?? null,
@@ -655,7 +670,7 @@ export class CompanionClient {
         });
         const json = (await res.json().catch(() => null));
         if (!res.ok || !json || json.ok === false) {
-            throw new CompanionError(json?.error || `wallet fetch failed (${res.status})`, res.status);
+            throw new CompanionError(json?.error || `wallet fetch failed (${res.status})`, res.status, json?.code);
         }
         return {
             balances: json.balances ?? [],
@@ -769,7 +784,7 @@ export class CompanionClient {
         const res = await this.fetchAuthed(this.url(`/api/companion/session/${encodeURIComponent(sessionId)}/confirm`), { headers: { Authorization: `Bearer ${this.opts.token}` } });
         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);
+            throw new CompanionError(json?.error || `pending confirms failed (${res.status})`, res.status, json?.code);
         }
         return json.pending ?? [];
     }

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 { CompanionClientOptions, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, WorldStateInput, CompanionAvatar, CompanionWallet, WalletBalance, BrandIconSize, EndSessionResult } from './client.js';
+export type { CompanionClientOptions, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, ToolCallEvent, WorldStateInput, CompanionAvatar, CompanionWallet, WalletBalance, BrandIconSize, EndSessionResult } 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 { PROTOCOL_VERSION, INBOUND_TYPES, OUTBOUND_TYPES } 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. */
 export declare function createCompanion(opts: CompanionClientOptions): CompanionClient;

package/dist/index.js

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

package/dist/protocol.d.ts

@@ -12,6 +12,12 @@ export type InboundType = (typeof INBOUND_TYPES)[number];
 export declare const OUTBOUND_TYPES: readonly ["hello.ack", "companion.message", "companion.audio", "companion.tool_call", "companion.ui_action", "companion.ui_update", "companion.expression", "companion.voice_inject", "companion.confirm_request", "companion.social_message", "companion.typing", "control.call_ready", "control.error", "control.usage"];
 export type OutboundType = (typeof OUTBOUND_TYPES)[number];
 export type MessageType = InboundType | OutboundType;
+/** HTTP error `code` vocabulary — what `CompanionError.code` can hold. A
+ *  self-contained mirror of the server's api-error.ts list (drift-tested);
+ *  APPEND-ONLY: renaming or removing a code is a breaking SDK change.
+ *  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 type CompanionErrorCode = (typeof COMPANION_ERROR_CODES)[number];
 /** The single envelope every control/data-plane message shares. */
 export interface CompanionEnvelope<T = unknown> {
     v: typeof PROTOCOL_VERSION;

package/dist/protocol.js

@@ -40,3 +40,20 @@ export const OUTBOUND_TYPES = [
     'control.error',
     'control.usage' // reserved — not emitted yet
 ];
+/** HTTP error `code` vocabulary — what `CompanionError.code` can hold. A
+ *  self-contained mirror of the server's api-error.ts list (drift-tested);
+ *  APPEND-ONLY: renaming or removing a code is a breaking SDK change.
+ *  Consumers can switch on these instead of string-matching error prose. */
+export const COMPANION_ERROR_CODES = [
+    'missing_token', // 401 — no Authorization: Bearer header
+    'invalid_token', // 401 — token unknown, revoked, or expired
+    'missing_scope', // 403 — token lacks a required grant
+    'invalid_request', // 400 — malformed JSON / missing or invalid fields
+    'session_not_found', // 404 — sessionId expired or never started
+    'turn_pending', // 409 — a turn is paused awaiting tool results
+    '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
+    'forbidden', // 403 — authorization denial other than a missing scope
+    'unavailable' // 503 — backing store/provider not configured or down
+];

package/dist/scopes.js

@@ -21,7 +21,7 @@ export const COMPANION_SCOPES = [
     'memory.read:core', // read the shared global brain (SENSITIVE)
     'memory.write:core', // write into the shared global brain (SENSITIVE)
     'skills.execute', // run the user's installed skills (SENSITIVE)
-    'wallet.read', // READ-ONLY wallet: balance + own deposit address (receive-only; not sensitive). Surfaced via the companion's wallet tools (ask it) — no standalone REST endpoint.
+    'wallet.read', // READ-ONLY wallet: balance + own deposit address (receive-only; not sensitive). GET /api/companion/wallet (SDK: getWallet(), 0.20.0+) or ask the companion's wallet tools.
     'wallet.spend', // spend from the Care Wallet (SENSITIVE)
     'social.message', // message friends via A2A (SENSITIVE)
     // ── Representative ("on-behalf-of") plane ─────────────────────────────

package/package.json

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