@pouchy_ai/companion-sdk 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -12,6 +12,33 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [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) or the SDK-synthesized `stream_unauthorized` (stream 401 exhausted reconnects — refresh the token, `start()` again) |
 
 ### Instant UI
 
@@ -144,7 +144,12 @@ 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
 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. */
@@ -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);
             }
         });
     }

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, 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';

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.23.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",