@pouchy_ai/companion-sdk 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -12,6 +12,51 @@ 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
+
+- **Runtime protocol constants are now exported.** `PROTOCOL_VERSION`,
+  `INBOUND_TYPES`, and `OUTBOUND_TYPES` are re-exported from the package entry —
+  previously only their *types* were reachable. A host can now assert the
+  protocol version or enumerate/validate the event vocabulary at runtime without
+  hard-coding the strings.
+- **`ToolCallPayload` type.** The `companion.tool_call` payload
+  (`{ id, name, args }`) now has a named, exported interface, so a consumer using
+  the generic `on('companion.tool_call', …)` gets a typed payload — parity with
+  `RenderInterfacePayload`, `ConfirmRequestPayload`, and the other payload types.
+  `onToolCall`'s callback is typed against it.
+
+No wire-protocol change (`PROTOCOL_VERSION` stays `1`); this is a purely additive
+type/export surface, hence the minor bump.
+
 ## [0.21.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
 
@@ -140,6 +140,17 @@ exported: `COMPANION_MODALITIES`, `REPRESENT_SCOPES`, `DEFAULT_MODALITIES`,
 `isRepresentScope()`. The list mirrors the server vocabulary and is guarded by
 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
+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).
+
+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 (代聊)
 
 Pass a `visitor` and the session flips from **owner-facing** to **representative**:

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundType, PendingConfirm, RenderInterfacePayload, SocialMessagePayload, TypingPayload, UsagePayload, VoiceInjectPayload, WorldStateEvent } from './protocol.js';
+import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundType, PendingConfirm, RenderInterfacePayload, SocialMessagePayload, ToolCallPayload, TypingPayload, UsagePayload, VoiceInjectPayload, WorldStateEvent } from './protocol.js';
 /** Ergonomic world-state input: a WorldStateEvent with the CloudEvents plumbing
  *  (specversion / id / source) optional — sendWorldState fills them. */
 export type WorldStateInput<D = unknown> = Omit<WorldStateEvent<D>, 'specversion' | 'id' | 'source'> & Partial<Pick<WorldStateEvent<D>, 'specversion' | 'id' | 'source'>>;
@@ -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,12 +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: {
-        id: string;
-        name: string;
-        args: string;
-    }, 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

@@ -8,11 +8,24 @@
 //   await c.sendText('how am I doing?');
 //
 // Pure, dependency-free, isomorphic (browser + Node 18+ fetch). The transport is
-// an internal detail — when the WebSocket plane lands it slots in behind this
-// same API. Protocol types are shared with the server via companion-protocol.
+// an internal detail: the default REST/SSE plane, or an opt-in WebSocket plane
+// (ws-transport.ts) that degrades back to SSE on failure — both sit behind this
+// same API. Protocol types are a self-contained copy of the server's contract,
+// kept in lockstep by protocol.drift.test.ts.
 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. */
@@ -499,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,10 +1,11 @@
 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, 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 } from './protocol.js';
+export { PROTOCOL_VERSION, INBOUND_TYPES, OUTBOUND_TYPES } from './protocol.js';
 /** Create a companion client. */
 export declare function createCompanion(opts: CompanionClientOptions): CompanionClient;

package/dist/index.js

@@ -1,5 +1,6 @@
 // Companion SDK — public entry. Embed the Pouchy companion in a third-party
-// surface (web / app / game / hardware) over the REST/SSE plane.
+// surface (web / app / game / hardware) over the REST/SSE plane (with an
+// optional WebSocket transport that degrades to SSE).
 //
 //   import { createCompanion } from '$lib/companion-sdk';
 //   const c = createCompanion({ baseUrl: 'https://pouchy.ai', token: PAT });
@@ -12,6 +13,9 @@ import { CompanionClient } from './client.js';
 export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js';
 export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_VISUAL_TOOLS, AVATAR_VISUAL_TOOL_NAMES } from './call.js';
 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';
 /** Create a companion client. */
 export function createCompanion(opts) {
     return new CompanionClient(opts);

package/dist/protocol.d.ts

@@ -76,6 +76,18 @@ export interface PendingConfirm {
     /** Epoch ms when the companion asked. */
     createdAt: number;
 }
+/** Payload of a `companion.tool_call` event — the companion is asking the host
+ *  to run one of the app-declared tools it was given at `hello`. `args` is the
+ *  raw JSON string the model produced (parse it yourself); reply by posting the
+ *  result back with `client.sendToolResult(id, …)`. */
+export interface ToolCallPayload {
+    /** Correlation id — echo it back on the tool result. */
+    id: string;
+    /** The declared tool name the model chose. */
+    name: string;
+    /** The model's arguments as a raw JSON string. */
+    args: string;
+}
 /** Payload of a `companion.ui_update` event — a live change to an
  *  already-rendered Instant UI panel: write each `{ key, value }` into the
  *  panel's state bag (re-evaluating templates / progress / `when`), without

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.21.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",