@pouchy_ai/companion-sdk 0.13.0 → 0.14.0

package/CHANGELOG.md

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

@@ -123,6 +123,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/package.json

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