@pouchy_ai/companion-sdk 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -12,6 +12,37 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-07-08
+
+### Added
+
+- **Typing / activity indicator** — a new `companion.typing` event and a
+  `client.onTyping(({ active }) => …)` convenience. The server emits
+  `active:true` when a turn starts working and `active:false` when it emits
+  its reply or pauses for an app tool result, so it spans the whole turn —
+  including the tool-loop / thinking phase BEFORE the first text delta, which
+  `onDelta` can't observe. Drive a "typing…" affordance uniformly across
+  streaming and non-streaming replies. Additive and non-breaking (receivers
+  ignore unknown types); the terminal `companion.message` stays authoritative.
+  Wire protocol stays `PROTOCOL_VERSION 1` (an added outbound type is
+  backwards-compatible). New payload type: `TypingPayload { active: boolean }`.
+
+### Added
+
+- **Opt-in voice barge-in** — `connectCall({ bargeIn: true })` keeps the
+  microphone OPEN while the companion speaks, so the user can interrupt
+  mid-utterance and both providers' native VAD interruption takes over
+  (OpenAI Realtime server VAD; ElevenLabs Convai interruption handling).
+  Default remains half-duplex (mic muted during agent speech): on phone
+  speakers browser echo cancellation does not fully remove the companion's
+  own voice, and it would barge in on itself. Enable only where AEC holds —
+  headphones, desktop, or devices you have verified.
+- The OpenAI Realtime microphone request now asks for explicit
+  `echoCancellation` / `noiseSuppression` / `autoGainControl` processing
+  constraints (harmless in half-duplex; required for barge-in to be viable).
+
+No wire-protocol change (`PROTOCOL_VERSION` stays `1`).
+
 ## [0.13.0] - 2026-07-06
 
 ### Added

package/README.md

@@ -70,6 +70,7 @@ Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers:
 | `onConfirmRequest(fn)` | `companion.confirm_request` | a sensitive-op approval request. **Platform session tokens** (your end users): show your own confirm card and resolve it with `confirmAction` — this is how confirm-gated custom skills (POST / credentialed) run. First-party user tokens: observe-only — approval stays first-party (where the `stepUp:true` biometric gate lives) |
 | `onAudio(fn)` | `companion.audio` | TTS clip (non-call modality) |
 | `onExpression(fn)` | `companion.expression` | avatar viseme / expression / gesture |
+| `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 |
 | `onError(fn)` | `control.error` | agent / stream errors |
 
@@ -123,6 +124,18 @@ the [source README](../../src/lib/companion-sdk/README.md#representative-mode-
 
 ## Voice (optional dependency)
 
+**Zero-code alternative:** if you just want a chat box, skip the SDK entirely —
+`<iframe src="https://pouchy.ai/embed?token=…&theme=dark&accent=%23ff6b81">` is a
+hosted drop-in widget with a postMessage control plane (docs:
+`docs/companion-widget.md` in the repo / pouchy.ai/sdk → Drop-in widget).
+
+`connectCall({ bargeIn: true })` opts into **full-duplex** voice: the mic stays
+open while the companion speaks so the user can interrupt mid-utterance (the
+providers' native interruption takes over). The default is half-duplex — on
+phone speakers echo cancellation can't fully remove the companion's own voice
+and it would interrupt itself. Enable it only where AEC holds (headphones,
+desktop, or devices you've verified).
+
 `connectCall()` for the **ElevenLabs Convai** provider needs the optional peer
 dependency:
 

package/dist/call.d.ts

@@ -46,6 +46,14 @@ export interface CompanionCallOptions {
     }) => void;
     onSpeakingChange?: (speaking: boolean) => void;
     onError?: (err: Error) => void;
+    /** OPT-IN full duplex: keep the mic OPEN while the companion speaks so the
+     *  user can interrupt mid-utterance (both providers' native VAD interruption
+     *  then works). Default false = half-duplex — the mic is muted during agent
+     *  speech, because on phone SPEAKERS browser echo cancellation does not fully
+     *  remove the companion's own voice and it barges in on itself (the SDK-voice
+     *  "说一句就断了" field report). Enable only where AEC actually holds:
+     *  headphones, desktop, or devices you have verified. */
+    bargeIn?: boolean;
 }
 export interface CompanionCall {
     /** Hang up. Idempotent. */

package/dist/call.js

@@ -163,7 +163,11 @@ const SDP_TIMEOUT_MS = 8_000;
  *  we've already given up on the call. */
 async function getMicWithTimeout() {
     let timedOut = false;
-    const micPromise = navigator.mediaDevices.getUserMedia({ audio: true });
+    const micPromise = navigator.mediaDevices.getUserMedia({
+        // Explicit processing constraints: echoCancellation is what makes the
+        // opt-in barge-in mode viable at all, and it is harmless in half-duplex.
+        audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true }
+    });
     micPromise
         .then((m) => {
         if (timedOut)
@@ -299,8 +303,10 @@ async function openOpenAICall(creds, opts, bridge) {
         else if (msg.type === 'output_audio_buffer.started') {
             opts.onSpeakingChange?.(true);
             // Model started speaking → mute the mic so its own audio can't
-            // echo-transcribe into a self-barge-in.
-            muteMicForSpeech();
+            // echo-transcribe into a self-barge-in. bargeIn opts out (B wave):
+            // the mic stays open and OpenAI's server VAD handles interruption.
+            if (opts.bargeIn !== true)
+                muteMicForSpeech();
         }
         else if (msg.type === 'output_audio_buffer.stopped' ||
             msg.type === 'output_audio_buffer.cleared' ||
@@ -311,7 +317,8 @@ async function openOpenAICall(creds, opts, bridge) {
             // audio doesn't get captured the instant we unmute. Several event names
             // can end a turn; any of them re-arms the mic.
             opts.onSpeakingChange?.(false);
-            scheduleMicUnmute();
+            if (opts.bargeIn !== true)
+                scheduleMicUnmute();
         }
     };
     const offer = await pc.createOffer();
@@ -497,6 +504,10 @@ async function openConvaiCall(creds, opts, bridge) {
                 return;
             const speaking = mode === 'speaking';
             opts.onSpeakingChange?.(speaking);
+            // bargeIn opts out of half-duplex (B wave): the mic stays open and
+            // ElevenLabs' native interruption handling takes over.
+            if (opts.bargeIn === true)
+                return;
             if (speaking) {
                 if (micUnmuteTimer) {
                     clearTimeout(micUnmuteTimer);

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundType, PendingConfirm, RenderInterfacePayload, SocialMessagePayload, UsagePayload, WorldStateEvent } from './protocol.js';
+import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundType, PendingConfirm, RenderInterfacePayload, SocialMessagePayload, TypingPayload, UsagePayload, 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'>>;
@@ -401,6 +401,12 @@ export declare class CompanionClient {
      *  friends (companion.social_message), delivered cross-app to any embed whose
      *  token holds `social.message`. Surface them in your own UI / notify the user. */
     onSocialMessage(handler: (payload: SocialMessagePayload, envelope: CompanionEnvelope) => void): () => void;
+    /** Convenience: subscribe to the companion's activity indicator
+     *  (companion.typing). Fires `active:true` when a turn starts working and
+     *  `active:false` when it finishes or pauses for a tool result — spanning the
+     *  tool-loop / thinking phase before the first text delta. Drive a "typing…"
+     *  affordance from it: `client.onTyping(({ active }) => setTyping(active))`. */
+    onTyping(handler: (payload: TypingPayload, envelope: CompanionEnvelope) => void): () => void;
     /** Open the event stream (auto-reconnecting with the resume cursor). Uses the
      *  WebSocket plane when opted in + available, else SSE. */
     start(): void;

package/dist/client.js

@@ -643,6 +643,18 @@ export class CompanionClient {
                 handler(p, env);
         });
     }
+    /** Convenience: subscribe to the companion's activity indicator
+     *  (companion.typing). Fires `active:true` when a turn starts working and
+     *  `active:false` when it finishes or pauses for a tool result — spanning the
+     *  tool-loop / thinking phase before the first text delta. Drive a "typing…"
+     *  affordance from it: `client.onTyping(({ active }) => setTyping(active))`. */
+    onTyping(handler) {
+        return this.on('companion.typing', (env) => {
+            const p = env.payload;
+            if (p && typeof p === 'object' && typeof p.active === 'boolean')
+                handler(p, env);
+        });
+    }
     /** Open the event stream (auto-reconnecting with the resume cursor). Uses the
      *  WebSocket plane when opted in + available, else SSE. */
     start() {

package/dist/index.d.ts

@@ -3,6 +3,6 @@ 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, 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, PendingConfirm, AudioClipPayload, ExpressionPayload, UsagePayload } from './protocol.js';
+export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, PendingConfirm, AudioClipPayload, ExpressionPayload, TypingPayload, UsagePayload } from './protocol.js';
 /** Create a companion client. */
 export declare function createCompanion(opts: CompanionClientOptions): CompanionClient;

package/dist/protocol.d.ts

@@ -3,7 +3,7 @@ export declare const PROTOCOL_VERSION: 1;
 export declare const INBOUND_TYPES: readonly ["hello", "input.text", "context.event", "context.snapshot", "tool.result", "control.start_call", "control.end_call", "control.set_modalities", "control.ping"];
 export type InboundType = (typeof INBOUND_TYPES)[number];
 /** Pouchy → app (control/data plane). */
-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", "control.call_ready", "control.error", "control.usage"];
+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;
 /** The single envelope every control/data-plane message shares. */
@@ -120,6 +120,16 @@ export interface SocialMessagePayload {
     /** ISO timestamp of delivery. */
     createdAt: string;
 }
+/** Payload of a `companion.typing` event — an activity indicator bracketing the
+ *  model work of a turn: `active:true` when the companion starts working,
+ *  `active:false` when it emits its reply or pauses for an app tool result. It
+ *  spans the whole turn — the tool-loop / thinking phase BEFORE the first text
+ *  delta, which `onDelta` can't observe — so a host can show a "typing…" state
+ *  uniformly across streaming and non-streaming replies. Advisory: a lost event
+ *  never affects the turn; the terminal `companion.message` is authoritative. */
+export interface TypingPayload {
+    active: boolean;
+}
 /** A live world-state event the app streams in. `retained:true` = latest-value
  *  state (coalesced); `retained:false` = a transient moment carrying `salience`
  *  and optional `voiceRelevant`. */

package/dist/protocol.js

@@ -29,6 +29,7 @@ export const OUTBOUND_TYPES = [
     'companion.voice_inject',
     'companion.confirm_request',
     'companion.social_message',
+    'companion.typing',
     'control.call_ready',
     'control.error',
     'control.usage'

package/package.json

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