@pouchy_ai/companion-sdk 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -12,6 +12,40 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-07-02
+
+### Added
+
+- **`AVATAR_VISUAL_TOOLS` / `AVATAR_VISUAL_TOOL_NAMES` are now exported from the
+  package entry point.** `docs/companion-host-control.md` has documented these
+  since the avatar-emote work, but the public `index.ts` never re-exported them —
+  hosts that wanted to filter or inspect the avatar visual tool set had to
+  reach into internal module paths. Additive; no behavior change.
+
+### Docs
+
+- The protocol document now reflects the shipped transport reality: REST + SSE
+  is the live control/data plane, `stream: 'websocket'` is a client-side option
+  that automatically falls back to SSE (the server WebSocket endpoint is not
+  yet available), and the server agent loop is live. The voice and poker
+  integration guides now install the SDK from npm instead of a local build /
+  bundled tarball.
+
+## [0.10.1] - 2026-06-29
+
+### Fixed
+
+- **Voice calls no longer drop on a transient network blip.** A WebRTC
+  `connectionState` of `disconnected` is transient per spec — a brief Wi-Fi
+  hiccup or cell handoff routinely hits it and recovers to `connected` on its
+  own. `connectCall()` previously tore the call down the instant `disconnected`
+  appeared, killing calls that would have healed. It now holds a short grace
+  window (6s) and only tears down if the connection is still `disconnected` when
+  it elapses; recovery to `connected` cancels the teardown. `failed` / `closed`
+  remain immediately fatal, and a genuine silent drop still tears down (so the
+  mic can't keep recording). No surface change — `connectCall` signature,
+  events, payloads, and scopes are unchanged.
+
 ## [0.10.0] - 2026-06-28
 
 Completes the SDK surface for all six companion capabilities, with Instant UI and
@@ -82,5 +116,8 @@ self-hosted/CDN build; this entry captures the surface that ships publicly.
 - **Versioned wire protocol.** `PROTOCOL_VERSION = 1`, kept in lockstep with the
   server by `protocol.drift.test.ts` (fails CI on divergence).
 
-[Unreleased]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.9.0...HEAD
+[Unreleased]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.11.0...HEAD
+[0.11.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.10.1...companion-sdk-v0.11.0
+[0.10.1]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.10.0...companion-sdk-v0.10.1
+[0.10.0]: https://github.com/oviswang/Pouchy/compare/companion-sdk-v0.9.0...companion-sdk-v0.10.0
 [0.9.0]: https://github.com/oviswang/Pouchy/releases/tag/companion-sdk-v0.9.0

package/dist/call.js

@@ -302,10 +302,26 @@ async function openOpenAICall(creds, opts, bridge) {
     }
     await pc.setRemoteDescription({ type: 'answer', sdp: await res.text() });
     let closed = false;
+    // `disconnected` is TRANSIENT per the WebRTC spec — a brief Wi-Fi hiccup or a
+    // cell handoff routinely drops to `disconnected` and recovers to `connected`
+    // on its own. Tearing down the instant it appears killed calls that would have
+    // healed (field report: SDK voice "动不动就掉线"). Give it a grace window to
+    // come back; only if it's STILL disconnected when the timer fires do we tear
+    // down — so the mic still can't record forever on a genuine silent drop (the
+    // original concern). `failed` / `closed` stay immediately fatal.
+    const DISCONNECT_GRACE_MS = 6000;
+    let disconnectTimer = null;
+    const clearDisconnectTimer = () => {
+        if (disconnectTimer) {
+            clearTimeout(disconnectTimer);
+            disconnectTimer = null;
+        }
+    };
     const teardown = () => {
         if (closed)
             return;
         closed = true;
+        clearDisconnectTimer();
         if (micUnmuteTimer) {
             clearTimeout(micUnmuteTimer);
             micUnmuteTimer = null;
@@ -320,13 +336,35 @@ async function openOpenAICall(creds, opts, bridge) {
         mic.getTracks().forEach((t) => t.stop());
     };
     pc.onconnectionstatechange = () => {
-        if (['failed', 'disconnected', 'closed'].includes(pc.connectionState)) {
-            // Tear down BEFORE surfacing the error. On a silent transport drop
-            // (Wi-Fi→cellular, ICE failure, server expiry) the embedder may never
-            // call close(), so without this the mic keeps recording indefinitely.
-            // Mirrors the first-party realtime/connection.ts fail() ordering.
+        const st = pc.connectionState;
+        if (st === 'connected') {
+            // (Re)connected — cancel any pending disconnect teardown.
+            clearDisconnectTimer();
+            return;
+        }
+        if (st === 'failed' || st === 'closed') {
+            // Genuinely dead — tear down immediately, BEFORE surfacing the error, so a
+            // silent transport drop can't leave the mic recording (mirrors the
+            // first-party realtime/connection.ts fail() ordering).
+            clearDisconnectTimer();
             teardown();
-            opts.onError?.(new Error(`call ${pc.connectionState}`));
+            opts.onError?.(new Error(`call ${st}`));
+            return;
+        }
+        if (st === 'disconnected') {
+            // Hold a grace window; a recovery to `connected` (handled above) cancels
+            // the timer. Still disconnected when it fires → tear down.
+            if (disconnectTimer || closed)
+                return;
+            disconnectTimer = setTimeout(() => {
+                disconnectTimer = null;
+                if (closed)
+                    return;
+                if (pc.connectionState === 'disconnected') {
+                    teardown();
+                    opts.onError?.(new Error('call disconnected'));
+                }
+            }, DISCONNECT_GRACE_MS);
         }
     };
     return {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { CompanionClient, type CompanionClientOptions } from './client.js';
 export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js';
 export type { CompanionClientOptions, HelloAck, RecalledMemory, CallCredentials, CompanionToolDecl, WorldStateInput, CompanionAvatar, BrandIconSize } from './client.js';
-export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES } from './call.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 type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, AudioClipPayload, ExpressionPayload, UsagePayload } from './protocol.js';
 /** Create a companion client. */

package/dist/index.js

@@ -10,7 +10,7 @@
 //   await c.sendText('what should I do?');
 import { CompanionClient } from './client.js';
 export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js';
-export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES } from './call.js';
+export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_VISUAL_TOOLS, AVATAR_VISUAL_TOOL_NAMES } from './call.js';
 /** Create a companion client. */
 export function createCompanion(opts) {
     return new CompanionClient(opts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.10.0",
+  "version": "0.11.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",
@@ -21,7 +21,12 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/fix-esm-extensions.mjs",
@@ -40,7 +45,13 @@
     "esbuild": "^0.24.0",
     "typescript": "^5.5.0"
   },
-  "keywords": ["pouchy", "ai-companion", "voice", "agent", "sdk"],
+  "keywords": [
+    "pouchy",
+    "ai-companion",
+    "voice",
+    "agent",
+    "sdk"
+  ],
   "publishConfig": {
     "access": "public"
   }