@pouchy_ai/companion-sdk 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -12,6 +12,42 @@ 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
+
+- **Token streaming** — the reply can now render as it is generated instead
+  of arriving as one block. Register `onDelta((chunk, meta) => …)` and
+  `sendText` automatically streams: the POST response itself carries SSE
+  `delta` frames (raw text chunks), an optional `reset` (a hop that streamed
+  text turned out to be tool-call deliberation — clear the partial render),
+  and a final `done` frame. `onMessage` still fires exactly ONCE with the
+  authoritative final text (the done frame's envelope is emitted locally and
+  the event-stream replay of the same envelope id is deduplicated), so
+  existing render code keeps working unchanged — deltas are a pure add-on.
+  Pass `sendText(text, { stream: false })` to force the buffered path, or
+  `{ stream: true }` to stream without a subscriber. Requires a server with
+  streaming input support; on older servers the SDK transparently falls back
+  to the buffered response. No wire-protocol (envelope) change.
+
 ## [0.12.1] - 2026-07-05
 
 ### Added
@@ -127,7 +163,7 @@ self-hosted/CDN build; this entry captures the surface that ships publicly.
 - **Public distribution.** Installable from the public npm registry as
   `@pouchy_ai/companion-sdk`; also resolvable via `esm.sh` / `jsDelivr` for
   no-bundler / import-map consumers, and self-hosted at
-  `https://www.pouchy.ai/sdk/companion-sdk.js`.
+  `https://pouchy.ai/sdk/companion-sdk.js`.
 - **Chat.** Text and multimodal (text + images) messaging.
 - **Voice.** Live WebRTC call (`connectCall`), provider-agnostic across OpenAI
   Realtime (zero extra deps) and ElevenLabs Convai (optional

package/README.md

@@ -18,10 +18,26 @@ No bundler? Pull it from a CDN via an import map instead — see
 [`docs/companion-integration-faq.md`](../../docs/companion-integration-faq.md).
 Changes per release are tracked in [`CHANGELOG.md`](./CHANGELOG.md).
 
+## Quickstart
+
+Two steps. **1)** Your backend exchanges the project **Secret Key** (create one
+in the [dashboard](https://pouchy.ai/dashboard) → Keys) for a per-user
+session token — first-seen `external_user_id`s are provisioned automatically:
+
+```http
+POST https://pouchy.ai/v1/sessions
+Authorization: Bearer pchy_sk_…
+{ "agent": "<agentId>", "external_user_id": "user_4211" }
+
+→ { "session_token": "pchy_…", "expires_in": 3600, "instance": { … } }
+```
+
+**2)** The client connects with the session token (never ship the Secret Key):
+
 ```ts
 import { createCompanion } from '@pouchy_ai/companion-sdk';
 
-const companion = createCompanion({ baseUrl: 'https://www.pouchy.ai', token: PAT });
+const companion = createCompanion({ baseUrl: 'https://pouchy.ai', token: sessionToken });
 await companion.connect();
 companion.onMessage((t) => console.log(t));
 companion.start();
@@ -30,6 +46,9 @@ await companion.connectCall();              // live voice (browser)
 companion.sendWorldState({ type: 'game.player.hp', data: { hp: 12 }, retained: true });
 ```
 
+(Personal/single-user integrations can pass a server-minted Personal Access
+Token as `token` instead — same API. See the docs' authentication section.)
+
 - **Guide:** [`docs/companion-quickstart.md`](../../docs/companion-quickstart.md)
 - **Spec:** [`docs/companion-sdk-protocol.md`](../../docs/companion-sdk-protocol.md)
 - **API reference:** [`docs/companion-api-reference.md`](../../docs/companion-api-reference.md)
@@ -42,7 +61,8 @@ Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers:
 
 | Helper | Event | Use |
 | --- | --- | --- |
-| `onMessage(fn)` | `companion.message` | streamed assistant text |
+| `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` |
 | `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) |
@@ -75,7 +95,7 @@ memory, system prompt, or PII. Works over text and voice.
 
 ```ts
 const c = createCompanion({
-  baseUrl: 'https://www.pouchy.ai',
+  baseUrl: 'https://pouchy.ai',
   token: OWNER_PAT,                 // must hold the `represent` scope
   surface: 'support-widget',
   appContext: { name: 'AcmeShop', description: 'Order support' },
@@ -103,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/dist/client.d.ts

@@ -4,7 +4,7 @@ import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, Expres
 export type WorldStateInput<D = unknown> = Omit<WorldStateEvent<D>, 'specversion' | 'id' | 'source'> & Partial<Pick<WorldStateEvent<D>, 'specversion' | 'id' | 'source'>>;
 import { type CompanionCall, type CompanionCallOptions } from './call.js';
 export interface CompanionClientOptions {
-    /** Origin of the Pouchy deployment, e.g. "https://www.pouchy.ai". */
+    /** Origin of the Pouchy deployment, e.g. "https://pouchy.ai". */
     baseUrl: string;
     /** A Pouchy access token (PAT). */
     token: string;
@@ -126,6 +126,15 @@ export declare class CompanionError extends Error {
     constructor(message: string, status: number);
 }
 type Handler = (envelope: CompanionEnvelope) => void;
+/** Token-streaming subscriber (P1-2). `chunk` is a raw text delta of the reply
+ *  being generated; `meta.reset` (with an empty chunk) tells the renderer to
+ *  CLEAR the partial text (a hop that streamed text turned out to be tool-call
+ *  deliberation, not the reply). Deltas are advisory — the final
+ *  companion.message (fired through onMessage as usual) is authoritative and
+ *  should replace whatever the deltas rendered. */
+type DeltaHandler = (chunk: string, meta: {
+    reset?: boolean;
+}) => void;
 export declare class CompanionClient {
     private readonly opts;
     private readonly doFetch;
@@ -135,6 +144,7 @@ export declare class CompanionClient {
     private abort;
     private readonly handlers;
     private readonly seen;
+    private readonly deltaHandlers;
     private readonly pendingVoiceTools;
     constructor(opts: CompanionClientOptions);
     /** The active session id, or null before connect(). */
@@ -158,12 +168,31 @@ export declare class CompanionClient {
     }>;
     /** Send a user text turn, optionally with images (data URLs) for a multimodal
      *  turn — images need the `files` scope. The reply arrives on the event stream
-     *  as a `companion.message` — subscribe via onMessage()/start() to receive it. */
+     *  as a `companion.message` — subscribe via onMessage()/start() to receive it.
+     *
+     *  TOKEN STREAMING (P1-2): when any onDelta() subscriber is registered (or
+     *  `opts.stream` is true), the reply streams token-by-token on this very
+     *  request — delta subscribers fire as chunks arrive, and onMessage still
+     *  fires exactly ONCE with the authoritative final text (the streamed copy
+     *  is emitted locally; the event-stream replay of the same envelope is
+     *  deduplicated by id). Pass `stream: false` to force the buffered path. */
     sendText(text: string, opts?: {
         images?: string[];
+        stream?: boolean;
     }): Promise<{
         seq: number | null;
     }>;
+    /** The streaming leg of sendText: parse the POST response's SSE frames —
+     *  `delta` / `reset` → delta subscribers, `done` → resolve (emitting the
+     *  final envelope locally so onMessage fires immediately and the log replay
+     *  dedups by id). Falls back to buffered semantics if the server ever
+     *  responds with plain JSON (e.g. an old deployment). */
+    private sendTextStreaming;
+    /** Subscribe to token-streaming deltas of the reply (P1-2). Registering a
+     *  subscriber makes sendText stream automatically. Returns an unsubscribe
+     *  function. Render chunks as they arrive; on `meta.reset` clear the partial;
+     *  when onMessage fires, replace the partial with the final text. */
+    onDelta(handler: DeltaHandler): () => void;
     /** Push live world-state — a single event or a batch. Retained events
      *  (retained:true) coalesce per kind; transient ones carry a salience.
      *

package/dist/client.js

@@ -37,6 +37,9 @@ export class CompanionClient {
     abort = null;
     handlers = new Map();
     seen = new Set();
+    // Token-streaming delta subscribers (P1-2). When any are registered,
+    // sendText automatically streams the reply.
+    deltaHandlers = new Set();
     // Voice tool-calls awaiting the app's sendToolResult, keyed by a synthetic id.
     pendingVoiceTools = new Map();
     constructor(opts) {
@@ -115,11 +118,98 @@ export class CompanionClient {
     }
     /** Send a user text turn, optionally with images (data URLs) for a multimodal
      *  turn — images need the `files` scope. The reply arrives on the event stream
-     *  as a `companion.message` — subscribe via onMessage()/start() to receive it. */
+     *  as a `companion.message` — subscribe via onMessage()/start() to receive it.
+     *
+     *  TOKEN STREAMING (P1-2): when any onDelta() subscriber is registered (or
+     *  `opts.stream` is true), the reply streams token-by-token on this very
+     *  request — delta subscribers fire as chunks arrive, and onMessage still
+     *  fires exactly ONCE with the authoritative final text (the streamed copy
+     *  is emitted locally; the event-stream replay of the same envelope is
+     *  deduplicated by id). Pass `stream: false` to force the buffered path. */
     async sendText(text, opts) {
         const id = this.requireSession();
-        const json = await this.postJson(`/api/companion/session/${id}/input`, { text, ...(opts?.images?.length ? { images: opts.images } : {}) });
-        return { seq: json.seq ?? null };
+        const wantStream = opts?.stream ?? this.deltaHandlers.size > 0;
+        const body = { text, ...(opts?.images?.length ? { images: opts.images } : {}) };
+        if (!wantStream) {
+            const json = await this.postJson(`/api/companion/session/${id}/input`, body);
+            return { seq: json.seq ?? null };
+        }
+        return this.sendTextStreaming(id, body);
+    }
+    /** The streaming leg of sendText: parse the POST response's SSE frames —
+     *  `delta` / `reset` → delta subscribers, `done` → resolve (emitting the
+     *  final envelope locally so onMessage fires immediately and the log replay
+     *  dedups by id). Falls back to buffered semantics if the server ever
+     *  responds with plain JSON (e.g. an old deployment). */
+    async sendTextStreaming(sessionId, body) {
+        const res = await this.doFetch(this.url(`/api/companion/session/${sessionId}/input`), {
+            method: 'POST',
+            headers: this.jsonHeaders(),
+            body: JSON.stringify({ ...body, stream: true })
+        });
+        const ctype = res.headers.get('content-type') ?? '';
+        if (!ctype.includes('text/event-stream')) {
+            // Old server / error before the stream opened — behave like postJson.
+            const json = (await res.json().catch(() => null));
+            if (!res.ok || !json || json.ok === false) {
+                throw new CompanionError(json?.error || `request failed (${res.status})`, res.status);
+            }
+            return { seq: json.seq ?? null };
+        }
+        if (!res.body)
+            throw new CompanionError('streaming response has no body', 502);
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = '';
+        const fireDelta = (chunk, meta) => {
+            for (const h of this.deltaHandlers)
+                h(chunk, meta);
+        };
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (value)
+                buf += decoder.decode(value, { stream: true });
+            const { events, rest } = parseSse(buf);
+            buf = rest;
+            for (const ev of events) {
+                if (ev.event === 'delta') {
+                    const d = JSON.parse(ev.data);
+                    if (typeof d.text === 'string' && d.text)
+                        fireDelta(d.text, {});
+                }
+                else if (ev.event === 'reset') {
+                    fireDelta('', { reset: true });
+                }
+                else if (ev.event === 'done') {
+                    const d = JSON.parse(ev.data);
+                    try {
+                        await reader.cancel();
+                    }
+                    catch {
+                        /* stream already finished */
+                    }
+                    if (d.ok === false) {
+                        throw new CompanionError(d.error || 'turn failed', d.status ?? 500);
+                    }
+                    // Emit the final envelope NOW so onMessage fires with zero poll
+                    // latency; the event-stream replay of the same id is deduped.
+                    if (d.envelope && typeof d.envelope === 'object')
+                        this.emit(d.envelope);
+                    return { seq: d.seq ?? null };
+                }
+            }
+            if (done)
+                break;
+        }
+        throw new CompanionError('stream ended without a done frame', 502);
+    }
+    /** Subscribe to token-streaming deltas of the reply (P1-2). Registering a
+     *  subscriber makes sendText stream automatically. Returns an unsubscribe
+     *  function. Render chunks as they arrive; on `meta.reset` clear the partial;
+     *  when onMessage fires, replace the partial with the final text. */
+    onDelta(handler) {
+        this.deltaHandlers.add(handler);
+        return () => this.deltaHandlers.delete(handler);
     }
     /** Push live world-state — a single event or a batch. Retained events
      *  (retained:true) coalesce per kind; transient ones carry a salience.

package/dist/index.js

@@ -2,7 +2,7 @@
 // surface (web / app / game / hardware) over the REST/SSE plane.
 //
 //   import { createCompanion } from '$lib/companion-sdk';
-//   const c = createCompanion({ baseUrl: 'https://www.pouchy.ai', token: PAT });
+//   const c = createCompanion({ baseUrl: 'https://pouchy.ai', token: PAT });
 //   await c.connect();
 //   c.onMessage((text) => console.log(text));
 //   c.start();

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.12.1",
+  "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",
-  "homepage": "https://www.pouchy.ai",
+  "homepage": "https://pouchy.ai",
   "repository": {
     "type": "git",
     "url": "https://github.com/oviswang/Pouchy.git",