@pouchy_ai/companion-sdk 0.10.0

package/dist/client.js

@@ -0,0 +1,716 @@
+// Companion SDK — the client a third-party surface (web / app / game / hardware)
+// uses to embed the Pouchy companion in a few lines. Wraps the REST/SSE plane:
+//   const c = createCompanion({ baseUrl, token });
+//   await c.connect();
+//   c.onMessage((text) => render(text));
+//   c.start();
+//   c.sendWorldState({ type: 'game.player.hp', data: { hp: 12 }, retained: true });
+//   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.
+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';
+/** Canonical URL of the official Pouchy brand icon at `size` px, derived from a
+ *  deployment origin. Standalone (no client/token needed) so a surface can show
+ *  the Pouchy mark before/without connecting. */
+export function pouchyBrandIconUrl(baseUrl, size = 512) {
+    return baseUrl.replace(/\/+$/, '') + `/brand-assets/icon/pouchy-icon-${size}.png`;
+}
+export class CompanionError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'CompanionError';
+        this.status = status;
+    }
+}
+const SEEN_CAP = 512;
+export class CompanionClient {
+    opts;
+    doFetch;
+    _session = null;
+    cursor = 0;
+    streaming = false;
+    abort = null;
+    handlers = new Map();
+    seen = new Set();
+    // Voice tool-calls awaiting the app's sendToolResult, keyed by a synthetic id.
+    pendingVoiceTools = new Map();
+    constructor(opts) {
+        if (!opts.baseUrl)
+            throw new Error('CompanionClient: baseUrl is required');
+        if (!opts.token)
+            throw new Error('CompanionClient: token is required');
+        this.opts = opts;
+        this.doFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** The active session id, or null before connect(). */
+    get sessionId() {
+        return this._session;
+    }
+    url(path) {
+        return this.opts.baseUrl.replace(/\/+$/, '') + path;
+    }
+    jsonHeaders() {
+        return { Authorization: `Bearer ${this.opts.token}`, 'Content-Type': 'application/json' };
+    }
+    requireSession() {
+        if (!this._session)
+            throw new Error('CompanionClient: call connect() first');
+        return this._session;
+    }
+    async postJson(path, body) {
+        const res = await this.doFetch(this.url(path), {
+            method: 'POST',
+            headers: this.jsonHeaders(),
+            body: JSON.stringify(body)
+        });
+        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 json;
+    }
+    /** Handshake: start or resume the session for this surface. */
+    async connect() {
+        const json = await this.postJson('/api/companion/session', {
+            surface: this.opts.surface ?? 'default',
+            modalities: this.opts.modalities,
+            handles: this.opts.handles,
+            contextKinds: this.opts.contextKinds,
+            tools: this.opts.tools,
+            appContext: this.opts.appContext,
+            ...(this.opts.visitor ? { visitor: this.opts.visitor } : {})
+        });
+        this._session = json.session;
+        this.cursor = json.resumeCursor ?? 0;
+        return {
+            ...json,
+            representative: json.representative ?? false,
+            visitorPaired: json.visitorPaired ?? false
+        };
+    }
+    /** Pair this representative session's VISITOR with the owner so their two
+     *  companions become friends — unlocking the A2A plane (messaging, gifts,
+     *  visiting) between them. Only valid in a representative session (the client
+     *  was created with a `visitor`).
+     *
+     *  Two-token consent: this client's PAT (the owner's) must hold `represent:pair`,
+     *  and you pass the VISITOR's own Pouchy PAT — which must hold `social.message`
+     *  — as proof + consent. The visitor must therefore also be a Pouchy user. */
+    async pairVisitor(visitorToken) {
+        if (!this.opts.visitor) {
+            throw new Error('pairVisitor() requires a representative session (createCompanion({ visitor }))');
+        }
+        if (!visitorToken)
+            throw new Error('pairVisitor: visitorToken is required');
+        const json = await this.postJson('/api/companion/pair', {
+            visitorToken,
+            visitorId: this.opts.visitor.id
+        });
+        return { pairId: json.pairId ?? null };
+    }
+    /** 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. */
+    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 };
+    }
+    /** Push live world-state — a single event or a batch. Retained events
+     *  (retained:true) coalesce per kind; transient ones carry a salience.
+     *
+     *  Ergonomic input: `specversion` / `id` / `source` are filled automatically
+     *  (id → a fresh handle, source → this surface), so callers only supply the
+     *  meaningful fields: `{ type, data, retained?, salience?, voiceRelevant? }`.
+     *  A full CloudEvents envelope is still accepted (its fields win). */
+    async sendWorldState(event) {
+        const id = this.requireSession();
+        const fill = (e) => ({
+            ...e,
+            specversion: '1.0',
+            id: e.id ?? this.randomId(),
+            source: e.source ?? this.opts.surface ?? 'companion-sdk'
+        });
+        const body = Array.isArray(event) ? { events: event.map(fill) } : fill(event);
+        const json = await this.postJson(`/api/companion/session/${id}/context`, body);
+        return { accepted: json.accepted ?? 0, dropped: json.dropped ?? 0 };
+    }
+    randomId() {
+        const c = globalThis.crypto;
+        return c?.randomUUID ? c.randomUUID() : `ws_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+    }
+    /** Open the voice plane. Returns realtime credentials to connect DIRECTLY to
+     *  the voice provider (the Pouchy server is out of the audio path). Provider
+     *  precedence is server-side: ElevenLabs Convai (primary) → OpenAI Realtime
+     *  (fallback). Requires the `call` scope.
+     *
+     *  - `elevenlabs-convai`: open the EL session with the returned `token` and
+     *    pass `instructions` as `overrides.agent.prompt.prompt` (the EL agent runs
+     *    EL's LLM, so the persona/memory snapshot rides in client-side).
+     *  - `openai-realtime`: open WebRTC with the short-lived `clientSecret`
+     *    (instructions are baked into the session server-side).
+     */
+    async startCall(opts) {
+        const id = this.requireSession();
+        return this.postJson(`/api/companion/session/${id}/call`, {
+            voice: opts?.voice,
+            locale: opts?.locale
+        });
+    }
+    /** Open a live voice call end-to-end: mints credentials (startCall) and opens a
+     *  WebRTC session directly to the provider — no first-party app code needed.
+     *  Browser-only. Returns a handle to hang up + inject live context. EL Convai
+     *  needs the optional '@elevenlabs/client' peer dependency; OpenAI Realtime has
+     *  no extra deps. */
+    async connectCall(opts) {
+        // Buffer the voice transcript so we can hand it to the server at call end —
+        // the audio is provider-direct, so this is the ONLY way a voice play-along
+        // reaches the companion's long-term memory. We still forward every line to
+        // the caller's own onTranscript.
+        const transcript = [];
+        const callerOnTranscript = opts?.onTranscript;
+        const wrappedOpts = {
+            ...opts,
+            onTranscript: (e) => {
+                if (e?.text?.trim())
+                    transcript.push({ role: e.role, text: e.text });
+                callerOnTranscript?.(e);
+            }
+        };
+        // Let the live voice call invoke tools — routed through the SAME
+        // onToolCall/sendToolResult the text path uses (one handler for voice +
+        // text). We offer the app's DECLARED tools PLUS the universal host-control
+        // verbs (pause/toggle/navigate/…) so the companion can act on any surface.
+        // Only when the app signalled it wants to act (declared tools or handles) —
+        // otherwise a pure-chat embed wouldn't get tools it can't service.
+        const declared = this.opts.tools ?? [];
+        const wantsTools = declared.length > 0 || (this.opts.handles?.length ?? 0) > 0;
+        const hostVerbs = wantsTools
+            ? HOST_CONTROL_TOOLS.filter((v) => !declared.some((d) => d.name === v.name))
+            : [];
+        // Avatar emote tools ride along ALWAYS — even a pure-chat / audio embed that
+        // declared no tools — so the embodied companion can express itself without
+        // each third party declaring play_gesture / play_expression, and so the EL
+        // Convai path (whose shared agent already knows these tools) has a handler to
+        // call. The SDK no-ops them unless the app opted in by declaring the same
+        // name (see invokeVoiceTool); declared ones use the app's own schema.
+        const avatarTools = AVATAR_VISUAL_TOOLS.filter((v) => !declared.some((d) => d.name === v.name));
+        const voiceTools = [...declared, ...hostVerbs, ...avatarTools];
+        const bridge = voiceTools.length
+            ? { tools: voiceTools, invoke: (name, argsJson) => this.invokeVoiceTool(name, argsJson) }
+            : undefined;
+        const creds = await this.startCall({ voice: opts?.voice, locale: opts?.locale });
+        const call = await openCompanionCall(creds, wrappedOpts, bridge);
+        // Bridge server-pushed voiceRelevant moments into the live call (item 2):
+        // the server emits companion.voice_inject while the call is active; inject
+        // each into the session so the companion reacts out loud. Needs start().
+        const unsub = this.on('companion.voice_inject', (env) => {
+            const p = env.payload;
+            if (typeof p?.text === 'string' && p.text)
+                call.injectEvent(p.text, p.speak !== false);
+        });
+        const close = call.close;
+        return {
+            ...call,
+            close: () => {
+                unsub();
+                close();
+                // Consolidate this call into durable memory (best-effort, keepalive).
+                void this.endSession({ transcript });
+            }
+        };
+    }
+    /** End the session: consolidate what happened into the companion's long-term
+     *  memory, so it remembers this experience in future first-party conversations.
+     *  Called automatically when a connectCall() handle is closed; call it directly
+     *  when a non-voice session ends. Best-effort + idempotent (safe to call twice;
+     *  uses keepalive so it survives a page unload). Pass the voice transcript when
+     *  you have it (connectCall does this for you). */
+    async endSession(opts) {
+        const id = this._session;
+        if (!id)
+            return;
+        // Cap the payload (fetch keepalive bodies are size-limited): last 60 lines.
+        const transcript = (opts?.transcript ?? [])
+            .filter((t) => t && typeof t.text === 'string' && t.text.trim())
+            .slice(-60)
+            .map((t) => ({ role: t.role, text: t.text.slice(0, 500) }));
+        try {
+            await this.doFetch(this.url(`/api/companion/session/${id}/end`), {
+                method: 'POST',
+                headers: this.jsonHeaders(),
+                body: JSON.stringify({ transcript }),
+                keepalive: true
+            });
+        }
+        catch {
+            /* best-effort — memory consolidation is not on the user's critical path */
+        }
+    }
+    /** Report the result of a companion.tool_call this surface performed. When all
+     *  of the turn's calls are reported, the companion resumes and the continuation
+     *  (a companion.message or more tool calls) arrives on the event stream. */
+    async sendToolResult(callId, result) {
+        // Voice tool-call: resolve it locally so the result flows back to the voice
+        // provider, not to a server text turn. (Same call shape as the text path.)
+        const pending = this.pendingVoiceTools.get(callId);
+        if (pending) {
+            pending(JSON.stringify({ ok: result.ok !== false, result: result.result ?? null }));
+            return { allDone: true };
+        }
+        const id = this.requireSession();
+        const json = await this.postJson(`/api/companion/session/${id}/tool-result`, { callId, ok: result.ok !== false, result: result.result });
+        return { allDone: json.allDone ?? false };
+    }
+    /** A tool the live voice call asked the app to run. Fires the SAME
+     *  companion.tool_call event the text flow uses (so the app's onToolCall +
+     *  sendToolResult handle voice identically), and resolves with the result
+     *  string fed back to the voice model. Times out so a missing result can't
+     *  hang the call. */
+    invokeVoiceTool(name, argsJson) {
+        const isHostVerb = HOST_CONTROL_TOOL_NAMES.includes(name);
+        const isAvatarTool = AVATAR_VISUAL_TOOL_NAMES.includes(name);
+        const isDeclared = this.opts.tools?.some((t) => t.name === name) ?? false;
+        if (!isHostVerb && !isAvatarTool && !isDeclared) {
+            return Promise.resolve(JSON.stringify({ ok: false, error: `unknown tool: ${name}` }));
+        }
+        // Avatar emote the app didn't opt into (didn't declare) → silent no-op
+        // success: a pure audio / 2D embed never renders a body, so the gesture /
+        // expression call resolves OK (the model's turn continues) but nothing
+        // happens. Declared avatar tools fall through to the app's handler below.
+        if (isAvatarTool && !isDeclared) {
+            return Promise.resolve(JSON.stringify({ ok: true }));
+        }
+        // Don't make the voice model wait ~20s if nothing can service the call.
+        if (!this.handlers.get('companion.tool_call')?.size) {
+            return Promise.resolve(JSON.stringify({ ok: false, error: 'no tool handler (register companion.onToolCall)' }));
+        }
+        // invoke_action carries the REAL action name in its params — unwrap it so it
+        // reaches onToolCall exactly like a declared tool. The other host verbs
+        // (set_feature/set_value/navigate/highlight) pass through by name.
+        let dispatchName = name;
+        let dispatchArgs = argsJson;
+        if (name === 'invoke_action') {
+            try {
+                const a = JSON.parse(argsJson || '{}');
+                if (typeof a.action !== 'string' || !a.action) {
+                    return Promise.resolve(JSON.stringify({ ok: false, error: 'invoke_action needs "action"' }));
+                }
+                dispatchName = a.action;
+                dispatchArgs = JSON.stringify(a.params ?? {});
+            }
+            catch {
+                return Promise.resolve(JSON.stringify({ ok: false, error: 'invoke_action args not JSON' }));
+            }
+        }
+        else if (name === 'set_feature') {
+            // The ElevenLabs path can only send string params, so `on` arrives as
+            // "true"/"false". Normalize to a real boolean so the app's handler is
+            // provider-agnostic (OpenAI already sends a boolean).
+            try {
+                const a = JSON.parse(argsJson || '{}');
+                const on = a.on === true || a.on === 'true';
+                dispatchArgs = JSON.stringify({ feature: a.feature, on });
+            }
+            catch {
+                /* leave args as-is */
+            }
+        }
+        const id = `vc_${this.randomId()}`;
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (out) => {
+                if (settled)
+                    return;
+                settled = true;
+                this.pendingVoiceTools.delete(id);
+                resolve(out);
+            };
+            this.pendingVoiceTools.set(id, finish);
+            setTimeout(() => finish(JSON.stringify({ ok: false, error: 'tool result timed out' })), 20_000);
+            this.emit({
+                v: PROTOCOL_VERSION,
+                id: `evt_${this.randomId()}`,
+                ts: Date.now(),
+                type: 'companion.tool_call',
+                payload: { id, name: dispatchName, args: dispatchArgs }
+            });
+        });
+    }
+    /** Convenience: subscribe to tool-call requests from the companion. */
+    onToolCall(handler) {
+        return this.on('companion.tool_call', (env) => {
+            const p = env.payload;
+            if (typeof p?.id === 'string' && typeof p?.name === 'string') {
+                handler({ id: p.id, name: p.name, args: typeof p.args === 'string' ? p.args : '' }, env);
+            }
+        });
+    }
+    /** 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. */
+    onError(handler) {
+        return this.on('control.error', (env) => {
+            const p = env.payload;
+            handler({
+                code: typeof p?.code === 'string' ? p.code : 'error',
+                message: typeof p?.message === 'string' ? p.message : 'unknown error'
+            }, env);
+        });
+    }
+    /** Recall the memory this token is authorized to see (ranked). */
+    async recall(opts) {
+        const qs = opts?.limit ? `?limit=${encodeURIComponent(opts.limit)}` : '';
+        const res = await this.doFetch(this.url(`/api/companion/memory${qs}`), {
+            headers: { Authorization: `Bearer ${this.opts.token}` }
+        });
+        const json = (await res.json().catch(() => null));
+        if (!res.ok || !json || json.ok === false) {
+            throw new CompanionError(json?.error || `recall failed (${res.status})`, res.status);
+        }
+        return json.memories ?? [];
+    }
+    /** Remember a fact (into this app's namespace unless `namespace` is given and
+     *  the token has the core scope). Intimate-tier writes are rejected server-side. */
+    async remember(fact) {
+        return this.postJson('/api/companion/memory', fact);
+    }
+    /** Ingest a DOCUMENT into the user's knowledge base. Unlike `remember` (one
+     *  short fact), this distils already-extracted text — a PDF body, a meeting
+     *  transcript, notes — into a headline summary PLUS full-text chunks, each
+     *  embedded and semantically recallable, and surfaces it in the user's "My
+     *  materials" list with source attribution, exactly like a first-party upload.
+     *  So the materials entry point can live in YOUR app, not just Pouchy's.
+     *
+     *  Extract the text yourself (your own parser, or Pouchy's /api/stt for audio)
+     *  and pass it here. Writes the user's SHARED knowledge, so the token must
+     *  hold `memory.write:core` (the user's consent) — otherwise 403. Embeddings
+     *  are computed on the user's next first-party open (eventually-consistent
+     *  semantic recall). `kind` is a free label for the source type (pdf / audio /
+     *  note / …) used only for display + the materials icon. */
+    async ingestKnowledge(doc) {
+        return this.postJson('/api/companion/knowledge', doc);
+    }
+    /** Convenience over `ingestKnowledge`: hand over a RAW file and Pouchy
+     *  understands it server-side before ingesting — no parser/transcriber/vision on
+     *  your side. Pass a `data:<mime>;base64,…` URL. Supported today: **PDF**
+     *  (server-side text extraction), **audio/video** (Whisper transcript), and
+     *  **image** (server-side vision caption — an objective description becomes the
+     *  material). For other types, extract the text yourself and call
+     *  `ingestKnowledge`. Same `memory.write:core` requirement and "My materials"
+     *  integration as `ingestKnowledge`. */
+    async ingestFile(file) {
+        return this.postJson('/api/companion/knowledge/file', file);
+    }
+    /** Fetch the user's CURRENT companion avatar so the embedding can render the
+     *  same virtual human Pouchy shows. The avatar is a VRM 3D model (`vrmUrl`,
+     *  load it with a VRM/glTF renderer e.g. three-vrm); `imageUrl` is a flat 2D
+     *  portrait when one exists (null today for built-in models). URLs are absolute
+     *  and the /models asset is CORS-enabled, so a cross-origin renderer can fetch
+     *  the VRM directly. Reflects the user's live choice (built-in or custom). */
+    async getAvatar() {
+        const res = await this.doFetch(this.url('/api/companion/avatar'), {
+            headers: { Authorization: `Bearer ${this.opts.token}` }
+        });
+        const json = (await res.json().catch(() => null));
+        if (!res.ok || !json || json.ok === false) {
+            throw new CompanionError(json?.error || `avatar fetch failed (${res.status})`, res.status);
+        }
+        return {
+            name: json.name ?? null,
+            archetype: json.archetype ?? 'girlfriend',
+            modelId: json.modelId ?? null,
+            vrmUrl: json.vrmUrl ?? null,
+            imageUrl: json.imageUrl ?? null
+        };
+    }
+    /** Canonical URL of the official Pouchy brand icon (square PNG, transparent
+     *  background) at the given size. Static + public — needs no token — so it's
+     *  safe to drop straight into an `<img src>` for "powered by Pouchy" badges,
+     *  the companion's app tile, etc. Sizes: 256 | 512 | 1024 (default 512). */
+    brandIconUrl(size = 512) {
+        return pouchyBrandIconUrl(this.opts.baseUrl, size);
+    }
+    /** Subscribe to outbound events of a given type, or "*" for all. Returns an
+     *  unsubscribe function. */
+    on(type, handler) {
+        let set = this.handlers.get(type);
+        if (!set) {
+            set = new Set();
+            this.handlers.set(type, set);
+        }
+        set.add(handler);
+        return () => set?.delete(handler);
+    }
+    /** Convenience: subscribe to assistant text replies. */
+    onMessage(handler) {
+        return this.on('companion.message', (env) => {
+            const text = env.payload?.text;
+            if (typeof text === 'string')
+                handler(text, env);
+        });
+    }
+    /** Convenience: subscribe to Instant UI render surfaces (companion.ui_action).
+     *  The host draws `payload.interface` with its OWN renderer — a web component, a
+     *  native iOS/Android view tree, a CLI/TUI — all consuming the same
+     *  platform-neutral genui schema. If the panel set `reportChanges`, feed the
+     *  user's edits back via `sendText`/`sendWorldState` to continue the turn. */
+    onRender(handler) {
+        return this.on('companion.ui_action', (env) => {
+            const p = env.payload;
+            if (p && typeof p === 'object' && Array.isArray(p.interface?.nodes))
+                handler(p, env);
+        });
+    }
+    /** Convenience: subscribe to TTS audio clips for the reply (companion.audio,
+     *  non-call modality) — play `url`, or resolve `ref` your way. */
+    onAudio(handler) {
+        return this.on('companion.audio', (env) => {
+            const p = env.payload;
+            if (p && typeof p === 'object' && (typeof p.url === 'string' || typeof p.ref === 'string')) {
+                handler(p, env);
+            }
+        });
+    }
+    /** Convenience: subscribe to avatar cues (companion.expression) — viseme /
+     *  expression / gesture for an embed rendering the companion's body. */
+    onExpression(handler) {
+        return this.on('companion.expression', (env) => handler(env.payload, env));
+    }
+    /** Convenience: subscribe to the per-token metering echo (control.usage) for a
+     *  usage / billing view. */
+    onUsage(handler) {
+        return this.on('control.usage', (env) => handler(env.payload, env));
+    }
+    /** Convenience: OBSERVE sensitive-op confirmation requests
+     *  (companion.confirm_request) — a payment, skill run, or friend message the
+     *  companion wants the user to approve. Use it to surface the pending approval
+     *  in your UI (e.g. "open Pouchy to approve"). NOTE: an embed cannot approve —
+     *  approval is authed as the first-party Pouchy user (their app / a hosted
+     *  confirm page), which is also where a biometric (Face ID / passkey) gate
+     *  lives. This handler is observe-only. */
+    onConfirmRequest(handler) {
+        return this.on('companion.confirm_request', (env) => {
+            const p = env.payload;
+            if (p && typeof p === 'object' && typeof p.confirmId === 'string')
+                handler(p, env);
+        });
+    }
+    /** Convenience: subscribe to live updates of an already-rendered Instant UI
+     *  panel (companion.ui_update). Apply each `{ key, value }` to the panel's state
+     *  bag and re-evaluate bound displays — no rebuild. */
+    onInterfaceUpdate(handler) {
+        return this.on('companion.ui_update', (env) => {
+            const p = env.payload;
+            if (p && typeof p === 'object' && Array.isArray(p.update?.updates))
+                handler(p, env);
+        });
+    }
+    /** Convenience: subscribe to inbound A2A messages from the user's paired
+     *  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) {
+        return this.on('companion.social_message', (env) => {
+            const p = env.payload;
+            if (p && typeof p === 'object' && typeof p.content === 'string')
+                handler(p, env);
+        });
+    }
+    /** Open the event stream (auto-reconnecting with the resume cursor). Uses the
+     *  WebSocket plane when opted in + available, else SSE. */
+    start() {
+        if (this.streaming)
+            return;
+        this.requireSession();
+        this.streaming = true;
+        const wsImpl = this.opts.webSocketImpl ?? globalThis.WebSocket;
+        if (this.opts.stream === 'websocket' && wsImpl) {
+            void this.wsLoop(wsImpl);
+        }
+        else {
+            void this.loop();
+        }
+    }
+    /** WebSocket receive loop. Resolves when the socket closes; on any failure
+     *  while still streaming it falls back to the SSE loop, so opting into WS can
+     *  only ever DEGRADE to SSE, never drop replies. Input is still sent over
+     *  REST (sendInput) — receiving is the latency-sensitive half. */
+    async wsLoop(WS) {
+        const id = this.requireSession();
+        const { deriveWsStreamUrl, decodeWsMessage } = await import('./ws-transport.js');
+        try {
+            await new Promise((resolve, reject) => {
+                const ws = new WS(deriveWsStreamUrl(this.opts.baseUrl, id, this.opts.token, this.cursor));
+                const done = (err) => (err ? reject(err) : resolve());
+                ws.onmessage = (ev) => {
+                    if (!this.streaming) {
+                        ws.close();
+                        return;
+                    }
+                    const raw = typeof ev.data === 'string' ? ev.data : '';
+                    const frame = raw ? decodeWsMessage(raw) : null;
+                    if (frame)
+                        this.handleFrame(frame.event, frame.data);
+                };
+                ws.onerror = () => done(new Error('companion ws error'));
+                ws.onclose = () => done();
+                // Stopping the stream closes the socket.
+                const poll = setInterval(() => {
+                    if (!this.streaming) {
+                        clearInterval(poll);
+                        try {
+                            ws.close();
+                        }
+                        catch {
+                            /* already closing */
+                        }
+                    }
+                }, 250);
+            });
+        }
+        catch {
+            // Socket unavailable / rejected — degrade to the robust SSE loop.
+            if (this.streaming)
+                await this.loop();
+        }
+    }
+    /** Stop the event stream. */
+    stop() {
+        this.streaming = false;
+        this.abort?.abort();
+        this.abort = null;
+    }
+    emit(envelope) {
+        // Dedup by envelope id — an ungraceful drop reconnects from the last KNOWN
+        // cursor (advanced only on the clean `reconnect` frame), which can replay a
+        // few events; the id set collapses those.
+        if (envelope.id) {
+            if (this.seen.has(envelope.id))
+                return;
+            this.seen.add(envelope.id);
+            if (this.seen.size > SEEN_CAP) {
+                const first = this.seen.values().next().value;
+                if (first !== undefined)
+                    this.seen.delete(first);
+            }
+        }
+        // Avatar emote tools the app didn't opt into resolve as a silent no-op, so a
+        // pure audio / 2D embed never has to register a handler for them. (Voice
+        // avatar calls are no-op'd earlier in invokeVoiceTool, before they reach
+        // here; this covers the text / event-stream path.) Declared = the app opted
+        // in → deliver to its onToolCall like any other tool.
+        if (envelope.type === 'companion.tool_call') {
+            const p = envelope.payload;
+            const name = typeof p?.name === 'string' ? p.name : '';
+            const callId = typeof p?.id === 'string' ? p.id : '';
+            const declared = this.opts.tools?.some((t) => t.name === name) ?? false;
+            if (name &&
+                AVATAR_VISUAL_TOOL_NAMES.includes(name) &&
+                !declared &&
+                !this.pendingVoiceTools.has(callId)) {
+                if (callId)
+                    void this.sendToolResult(callId, { ok: true }).catch(() => { });
+                return;
+            }
+        }
+        for (const h of this.handlers.get(envelope.type) ?? [])
+            h(envelope);
+        for (const h of this.handlers.get('*') ?? [])
+            h(envelope);
+    }
+    handleFrame(event, data) {
+        if (event === 'reconnect') {
+            try {
+                const d = JSON.parse(data);
+                if (typeof d.cursor === 'number')
+                    this.cursor = d.cursor;
+            }
+            catch {
+                /* ignore */
+            }
+            return;
+        }
+        let env = null;
+        try {
+            env = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (event === 'open') {
+            const rc = env?.payload?.resumeCursor;
+            if (typeof rc === 'number')
+                this.cursor = rc;
+            return;
+        }
+        if (env && typeof env.type === 'string')
+            this.emit(env);
+    }
+    async loop() {
+        const id = this.requireSession();
+        let backoff = 500;
+        while (this.streaming) {
+            this.abort = new AbortController();
+            try {
+                const res = await this.doFetch(this.url(`/api/companion/session/${id}/stream?cursor=${this.cursor}`), { headers: { Authorization: `Bearer ${this.opts.token}` }, signal: this.abort.signal });
+                if (res.status === 401 || res.status === 403) {
+                    // Permanent: the token can't subscribe (most often it lacks the
+                    // `events.subscribe` scope; also revoked / wrong user). Retrying is
+                    // futile and would silently swallow every reply — surface it as a
+                    // control.error and stop the loop.
+                    this.streaming = false;
+                    this.emit({
+                        v: PROTOCOL_VERSION,
+                        id: `stream_err_${Date.now()}`,
+                        session: this._session ?? undefined,
+                        ts: Date.now(),
+                        type: 'control.error',
+                        payload: {
+                            code: 'stream_unauthorized',
+                            message: `event stream rejected (${res.status}); the token likely lacks the "events.subscribe" scope`
+                        }
+                    });
+                    break;
+                }
+                if (!res.ok || !res.body) {
+                    if (!this.streaming)
+                        break;
+                    await this.sleep(backoff);
+                    backoff = Math.min(backoff * 2, 8000);
+                    continue;
+                }
+                backoff = 500; // healthy connection resets backoff
+                await this.consume(res.body);
+            }
+            catch {
+                if (!this.streaming)
+                    break;
+                await this.sleep(backoff);
+                backoff = Math.min(backoff * 2, 8000);
+            }
+        }
+    }
+    async consume(body) {
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buf = '';
+        while (this.streaming) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            const { events, rest } = parseSse(buf);
+            buf = rest;
+            for (const ev of events)
+                this.handleFrame(ev.event, ev.data);
+        }
+    }
+    sleep(ms) {
+        return new Promise((res) => setTimeout(res, ms));
+    }
+}