@pouchy_ai/companion-sdk 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -12,6 +12,24 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [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

@@ -140,6 +140,12 @@ 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.
+
 ## 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'>>;
@@ -333,11 +333,7 @@ export declare class CompanionClient {
      *  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;
+    onToolCall(handler: (call: ToolCallPayload, 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,8 +8,10 @@
 //   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';

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_
 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,6 +1,6 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.21.0",
+  "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.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",