@pouchy_ai/companion-sdk

@pouchy_ai/companion-sdk

Embed the Pouchy companion — chat, voice, tools, memory, live world-state, Instant UI, and agent-to-agent messaging — in any app, game, or site.

All six companion capabilities are reachable over the SDK (memory · reasoning · skills · A2A/social · wallet · instant UI), and each rides a platform-neutral contract — so the same companion runs on web, native iOS/Android, or a CLI. See companion-capabilities.

Install

npm i @pouchy_ai/companion-sdk

No bundler? Pull it from a CDN via an import map instead — see companion-integration-faq.

The package ships ESM-only ("type": "module", no CJS build). Every modern bundler and Node ≥ 18 consumes it as-is; on Node ≥ 20.17 even require() of the ESM entry works natively. Changes per release are tracked in CHANGELOG.md; the pinnable CDN releases (immutable URL + SRI per version) are indexed at pouchy.ai/sdk/versions.

React? @pouchy_ai/react wraps this SDK in a <CompanionProvider> + useCompanion / useMessages / useTyping / useCall hooks so you don't wire the handshake, stream, or teardown yourself.

Svelte / Vue? This package ships thin adapters as subpath exports — @pouchy_ai/companion-sdk/svelte and @pouchy_ai/companion-sdk/vue (0.31.0).

Quickstart

Two steps. 1) Your backend exchanges the project Secret Key (create one in the dashboard → Keys) for a per-user session token — first-seen external_user_ids are provisioned automatically:

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):

import { createCompanion } from '@pouchy_ai/companion-sdk';

const companion = createCompanion({ baseUrl: 'https://pouchy.ai', token: sessionToken });
await companion.connect();
companion.onMessage((t) => console.log(t));
companion.start();
await companion.sendText('hey');
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: companion-quickstart
• Spec: companion-sdk-protocol
• API reference: companion-api-reference
• Capabilities map: companion-capabilities
• Instant UI renderer contract: companion-instant-ui

Framework adapters (Svelte / Vue)

Thin, logic-free bindings over one shared view controller (createCompanionView, also exported from the root for any other framework). The view tracks { streamState, transcript, draft, typing, pendingConfirms } as immutable snapshots, wraps sendText (optimistic user turn — rolled back if the send rejects, 0.32.1, except on queued_offline / reply_timeout / needs_event_stream, where the text did not get lost; a rejected send also clears its dead draft and typing, 0.63.1) and confirmAction (confirm-card bookkeeping; a confirm_resolved/confirm_not_found rejection drops the stale card, since a confirm can be resolved elsewhere — hosted page or an IM keyword reply), and can restore recent history with { restore: N }. You own the client lifecycle — create/connect/start it once, hand it to the adapter, close it when done. React hosts: use the standalone @pouchy_ai/react package instead (it owns the client lifecycle and adds a voice-call hook; this view owns the richer render-state).

<script>
  import { companionStore } from '@pouchy_ai/companion-sdk/svelte';
  const companion = companionStore(client, { restore: 20 });
</script>
{#each $companion.transcript as turn}<p>{turn.role}: {turn.text}</p>{/each}
{#if $companion.typing}<p>…</p>{/if}
<button onclick={() => companion.sendText('hey')}>send</button>

// Vue 3
import { useCompanion } from '@pouchy_ai/companion-sdk/vue';
const { snapshot, sendText } = useCompanion(client, { restore: 20 });
// snapshot.value.transcript / .draft / .streamState — auto-disposes with scope

Constructor options (beyond baseUrl + token)

createCompanion({ … }) also takes: surface (one resumable session per surface), modalities / handles / contextKinds / tools / appContext (the capability handshake — since 0.77.0 connect()'s ack carries droppedTools: [{ index, reason }] for any tools entry it refused: missing_name / duplicate_name / over_cap), visitor (representative mode, below), onAuthError (401 → return a fresh token and the client retries transparently), stream: 'sse' | 'websocket' (receive transport — 'websocket' opts into the lower-latency WS plane when the deployment serves one — pouchy.ai does not (serverless); an optional self-hosted WebSocket gateway worker does, for a host that can hold sockets — and falls back to SSE automatically — when the socket cannot open, and since 0.73.1 when the gateway refuses it with a 4xxx close (4401 unauthorized, 4502 upstream failure) — observable as streamState === 'degraded_sse'), streamBaseUrl (0.59.0 — the origin the WS plane is served from, i.e. your self-hosted gateway; only the reply socket goes there, every REST call and the SSE fallback keep using baseUrl; unset derives the socket URL from baseUrl), debug (0.32.0 — true logs structured instrumentation events via console.debug; a function receives every CompanionDebugEvent: HTTP request/response with method/path/status/ms, each delivered envelope post-dedup, stream-state transitions, synthesized errors — never the token, headers, or bodies), queueOffline (0.34.0 — opt-in offline send queue, below) with outboxStore (custom persistence for it; default localStorage), requestTimeoutMs (0.35.0 — deadline for any request to produce response HEADERS, default 30 000 ms, 0 disables; expiry rejects code: 'request_timeout'; never bounds reading a streaming body; since 0.40.0/0.40.1 the long-work POSTs — whose headers only arrive when the server work completes — default to that work's own ceiling instead of 30 s: buffered /input sends, sendToolResult and the two knowledge ingests get 310 s, confirmAction 65 s, so a long-running turn/ingest/action is no longer declared dead while it succeeds server-side; an explicit requestTimeoutMs still bounds every request at your value), replayPendingToolCalls (0.37.0, default true — when connect() resumes a session paused on YOUR tools, re-emit each outstanding call to onToolCall with replayed: true; see "Resuming a paused turn" below), and two injection points for Node/tests: fetch (custom fetch implementation) and webSocketImpl (WebSocket constructor when globalThis.WebSocket is absent).

Events

Subscribe with on(type, fn) (or '*'), or these typed convenience helpers. Since 0.30.0 on() narrows the envelope payload per event name (OutboundPayloadMap) — e.g. on('companion.typing', (env) => env.payload.active) type-checks without a cast; '*' keeps the untyped envelope:

Instant UI

import { renderInterface } from './instant-ui'; // your renderer (web example in examples/web-instant-ui)
let panel: ReturnType<typeof renderInterface> | null = null;
companion.onRender(({ interface: ui }) => { panel = renderInterface(ui, mountEl); });
companion.onInterfaceUpdate(({ update }) => panel?.applyUpdate(update));

Reference renderers ship in the repo under examples/: web-instant-ui (vanilla), native-instant-ui (SwiftUI + Jetpack Compose), and cli-skills (terminal + local/device skills).

Already have an A2UI-catalog renderer? (0.42.0) toA2UI(payload.interface) projects any panel losslessly to Google's A2UI v0.9 flat wire format (standard component/field names; Pouchy-only concepts ride a _pouchy extension A2UI renderers ignore), and fromA2UI ingests a surface back. INSTANT_UI_NODE_TYPES lists the atom catalog as data for capability checks. Embedded Button / table-row actions are opaque EmbeddedAction { type } values — hand them back to the companion, never interpret them.

import { toA2UI } from '@pouchy_ai/companion-sdk';
companion.onRender(({ interface: ui }) => myA2uiRenderer.render(toA2UI(ui)));

Client methods (beyond the quickstart)

Tool calling beyond your own declared tools — voice calls only: on connectCall() sessions the SDK automatically offers HOST_CONTROL_TOOLS (universal verbs — invoke_action, set_feature, set_value, navigate, highlight) once you declare tools/handles, and AVATAR_VISUAL_TOOLS (play_gesture / play_expression) let avatar-rendering embeds receive expression cues — declare them or they no-op silently. Text turns expose exactly the tools[] you declared (nothing is auto-added), so declare the verbs there yourself if you want them outside calls. Full contract: companion-host-control.

Cancellation (0.29.0, completed in 0.29.1): every request-performing method accepts an optional AbortSignal — including sendToolResult(callId, result, { signal }) and startCall({ signal }) since 0.29.1. Methods with an options object take a signal? field (sendText(text, { signal }), recall({ signal }), …); the rest take a trailing opts (getAvatar({ signal }), ping({ signal }), …). Aborting rejects with CompanionError code: 'aborted', and for sendText({ awaitReply }) it also tears down the in-flight event stream.

const ac = new AbortController();
const p = companion.sendText('summarize this', { awaitReply: true, signal: ac.signal });
// …user navigated away
ac.abort(); // p rejects with code: 'aborted'

Offline send queue (0.34.0, opt-in): queueOffline: true turns a network-level send failure (fetch rejected / navigator.onLine === false) into a queued send instead of a lost one — replayed FIFO on reconnect with its original turnId (server-deduped, so a retry can never double-run a turn; see the methods table above for the full per-item semantics). Since 0.39.0 the replay is double-run-safe even after a long offline gap: a send known to have never reached the server (navigator.onLine was false) replays at any age, while an AMBIGUOUS one (the turn may have run server-side) is replayed only while younger than OUTBOX_AMBIGUOUS_MAX_AGE_MS (30 min) and dropped past that rather than risk a duplicate; a transient 409 mid-flush keeps the item instead of discarding it:

const companion = createCompanion({ baseUrl, token, queueOffline: true });
await companion.connect();
companion.onOutboxChange((items) => render(items.length)); // "N pending" badge
const r = await companion.sendText('hey');
if (r.queued) render('queued — sends on reconnect', r.turnId);

Resuming a paused turn (0.37.0): a turn that pauses on YOUR declared tools used to be unrecoverable if the embed lost its state (tab reload / crash mid-pause) — the only unblock was abandoning it via endSession() (/end). Now connect() on a session resumed mid-pause returns the outstanding calls as HelloAck.pendingToolCalls (PendingToolCall[] — { id, name, args, turnId?, pausedAt? }; always present, empty when none), and — unless you pass replayPendingToolCalls: false — re-emits each to your onToolCall handler with replayed: true (one tick after connect() resolves, at most once per client instance), so your existing tool loop completes the turn instead of losing it. Register onToolCall before connect()/start(). Because the app may have already PERFORMED a replayed call and died before posting the result, side-effecting tools should treat id as an idempotency key when replayed is set (the server's result apply is idempotent per id too — a double sendToolResult for the same id is safe); use pausedAt to judge staleness before re-running something expensive:

declare function runTool(name: string, args: unknown): Promise<string>; // yours

const performed = new Set<string>(); // your durable "already ran" ledger
companion.onToolCall(async ({ id, name, argsJson, replayed }) => {
  if (replayed && performed.has(id)) {
    await companion.sendToolResult(id, { ok: true, result: 'already applied' });
    return;
  }
  performed.add(id);
  const result = await runTool(name, argsJson);
  await companion.sendToolResult(id, { ok: true, result });
});
const ack = await companion.connect(); // resumed mid-pause → ack.pendingToolCalls
companion.start();

Scopes (typed)

The full capability-scope vocabulary ships as typed constants — no more copying scope strings from prose:

import {
  COMPANION_SCOPES, SENSITIVE_SCOPES, DEFAULT_SCOPES,
  hasScope, grantsScope, isSensitiveScope, type CompanionScope
} from '@pouchy_ai/companion-sdk';

const ack = await c.connect();
if (!hasScope(ack.grantedScopes, 'skills.execute')) {
  // hide the "run a skill" affordance instead of eating a 403
}
// Gate a READ-ONLY affordance with grantsScope, not hasScope: a key granted
// only `wallet.spend` can still read the balance, so hasScope(g,'wallet.read')
// would wrongly hide it. grantsScope honours that subsumption.
if (grantsScope(ack.grantedScopes, 'wallet.read')) {
  // safe to show the wallet balance (getWallet() will succeed)
}

COMPANION_SCOPES lists every scope a key can carry; SENSITIVE_SCOPES are the ones that are never on by default (money / skills / social / core memory / the representative plane); DEFAULT_SCOPES is what a fresh key gets. hasScope(granted, required) is an exact-grant check; grantsScope(granted, required) additionally honours scope subsumption (wallet.spend ⊇ wallet.read) — use it to gate whether an API call will succeed. Also exported: COMPANION_MODALITIES, REPRESENT_SCOPES, DEFAULT_MODALITIES, isRepresentScope(). The list mirrors the server vocabulary and is guarded by the SDK's drift test.

The wire-protocol runtime constants are exported too — PROTOCOL_VERSION, INBOUND_TYPES, OUTBOUND_TYPES, and COMPANION_ERROR_CODES (the append-only HTTP code vocabulary behind CompanionError.code, e.g. missing_scope / session_not_found / turn_pending) — so you can assert the version, validate the event vocabulary, or switch on error codes without hard-coding strings. Every helper populates CompanionError.code when the server names a cause (0.24.0 — previously only the POST-backed calls did). 0.27.0 adds rate_limited for the runtime's 429 cost gates (turn burst ceiling, demo daily budget); on those failures CompanionError.retryAfter carries the server's Retry-After in seconds, so back off with if (e.code === 'rate_limited') await sleep((e.retryAfter ?? 1) * 1000) (retryAfter is undefined when the server names no window). The SDK also synthesizes a few client-side codes outside that HTTP vocabulary: reply_timeout (awaitReply fallback gave up), stream_unauthorized (event-stream 401/403 — a 401 exhausted the token-refresh retries; a 403 is immediately terminal, commonly a missing events.subscribe scope), and — 0.26.0 — the voice connect-step codes call_unsupported (no WebRTC/mic in this environment), call_connect_failed (mic timeout / SDP exchange failed) and call_dependency_missing (@elevenlabs/client not installed). 0.28.0 adds the confirm/step-up codes (confirm_not_found, confirm_resolved, step_up_required, step_up_failed), the client-side needs_event_stream, and types CompanionError.code as the CompanionErrorCodeValue union (autocomplete in your switch; still open for newer servers). 0.34.0 adds queued_offline (a send parked in the offline outbox for replay) and 0.35.0 adds request_timeout (the requestTimeoutMs headers deadline fired). 0.72.0 adds invalid_option (an option the SDK refused before sending, e.g. a turnId outside 1–256 chars) and 0.73.0 reply_unavailable (an awaitReply retry of a completed turnId whose reply the server no longer holds). 0.45.0 adds the server code quota_exhausted (402 — the account's monthly allowance is spent, credits or realtime voice minutes, e.g. startCall past the plan's voice ceiling): not retryable, unlike rate_limited — upgrade the plan or wait for the 1st (UTC) reset. The authoritative reference is the exported CompanionErrorCodeValue union on CompanionError.code (the internal SDK_SYNTHESIZED_ERROR_CODES list is drift-tested but deliberately not part of the public index surface). (stream_unauthorized above is a control.error/onError code, not a thrown CompanionError.code.) Every outbound payload has a named type; ToolCallPayload ({ id, name, args, replayed? }) types the companion.tool_call event, MessagePayload ({ text, replyTo?, attachments? }) types companion.message (attachments: MessageAttachment[] — files the turn produced, 0.54.0), PendingToolCall (0.37.0) types the HelloAck.pendingToolCalls entries, and onToolCall's callback receives ToolCallEvent — the payload plus argsJson (pre-parsed args). On a persisted server fault (a real 5xx) CompanionError.errorId (0.56.0) carries the server's err_… reference — quote it to support; it is the id the server's own error row is keyed by. Absent on 4xx and transport failures.

For advanced voice hosts, the lower-level openCompanionCall(creds, options?, bridge?) primitive is exported too — it consumes the CallCredentials that startCall() mints (bring-your-own call lifecycle; see companion-integration-faq).

In-call memory recall (voiceToolToken, 0.46.0)

On the ElevenLabs path the agent carries a server-side webhook tool that reads the session's memory mid-call. It authenticates with the call-scoped creds.voiceToolToken, which you hand to EL as a dynamic variable at session start:

import { VOICE_TOOL_VARIABLE, VOICE_TOOL_VARIABLE_PLAIN } from '@pouchy_ai/companion-sdk';

const creds = await companion.startCall();
if (creds.provider === 'elevenlabs-convai') {
  // Conversation.startSession({
  //   conversationToken: creds.token, connectionType: 'webrtc',
  //   dynamicVariables: {
  //     [VOICE_TOOL_VARIABLE]: creds.voiceToolToken,
  //     [VOICE_TOOL_VARIABLE_PLAIN]: creds.voiceToolToken   // 0.47.0 — the one EL actually substitutes
  //   }
  // })
}

EL substitutes it into that tool's Authorization header and never sends the secret__ class of variable to the LLM, so the credential rides a live conversation without entering a prompt.

connectCall() handles this automatically. If you plumb the call yourself, this is the one omission that surfaces no error: EL substitutes the agent's empty default, the tool call 401s, and the companion simply says it doesn't recall anything — a call that sounds entirely normal with memory switched off. The field is absent (not empty) when the session holds no memory grant; pass it through as-is and omit the key when it is missing.

Representative mode (代聊)

Pass a visitor and the session flips from owner-facing to representative: the companion answers that visitor on the owner's behalf (代聊 / customer-service) using only screened owner context — never the owner's private memory, system prompt, or PII. Works over text and voice.

const c = createCompanion({
  baseUrl: 'https://pouchy.ai',
  token: OWNER_PAT,                 // must hold the `represent` scope
  surface: 'support-widget',
  appContext: { name: 'AcmeShop', description: 'Order support' },
  visitor: { id: stableVisitorId, displayName: 'Sam' }  // stable per end-user
});
const ack = await c.connect();      // → { representative: true, visitorPaired, … }
await c.sendText('do you ship to Canada?');
const call = await c.connectCall(); // same, over voice

Scopes (granted by the owner's "Let it represent you to visitors" key toggle):

Without represent, supplying a visitor is rejected (403). First-party tools (wallet / skills / social) are withheld; your own declared tools still work. Full walkthrough: API reference §3.3–3.4.

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).

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({ audioTags: true }) (0.64.0) lets the companion perform short voice cues on an ElevenLabs call: it laughs, sighs, whispers and speaks softly instead of only saying words (Eleven v4). Opt-in, because the provider's transcript then contains the cues ([laughs] 你也太可爱了吧) — connectCall strips them before onTranscript and before the transcript reaches memory. The server may decline (OpenAI Realtime fallback, or the operator switched it off); startCall credentials carry audioTags: true only when granted. Plumbing the ElevenLabs session yourself? Run every agent transcript line through stripAudioTags(text) before you show or store it.

To see what was performed (0.70.0): on a granted call every companion onTranscript line carries audioTags: string[] (['sighs', 'laughs'], or []); the field is absent on user lines and on calls without the grant. Self-plumbed: extractAudioTags(line) gives the same list.

onEnd(end) (0.71.0) says why a call ended, once per call, on every path: end.reason is 'user' (your close()), 'agent' (the companion hung up with ElevenLabs' end_call tool), 'remote' (the provider closed it cleanly without saying why) or 'error' (end.error; onError got it first). Passing onEnd moves a clean far-side end out of onError, which then means failure only; without it nothing changes. 'agent' needs the ElevenLabs agent to send its tool responses to the client (otherwise it reads 'remote'), and openai-realtime has no clean remote end. connectCall sends the call to /end on every end, the companion's hang-up included.

connectCall({ record: true }) (0.65.0) records the whole call — both voices, kept by the voice provider, so a host that cannot capture audio on the device (React Native's native WebRTC has no WebAudio / MediaRecorder) gets the same recording as a browser. Turn it on per agent in the dashboard (the agent's recording switch, which grants call.record); it runs on ElevenLabs only, and you own telling readers their calls are recorded. The handle says what happened before the call connects: call.recording is true, or false with call.recordingUnavailable ('not_enabled' | 'not_configured' | 'no_conversation_id' | 'store_failed') — tell the reader the truth either way. After the call, getCallRecording(call.callGen) answers { state: 'ready', audio, contentType } (an MP3 Blob), { state: 'pending', retryAfterSec } while the provider is still processing, or { state: 'none' | 'expired' | 'deleted' }. Recordings are kept for 7 days: copy the file to your own storage. deleteCallRecording(callGen) removes the provider's copy (audio and transcript) — use it when a reader deletes their account. Self-plumbed: startCall({ record: true }) returns the same recording / recordingUnavailable / callGen on the credentials.

connectCall({ avatar: { faceId } }) (0.75.0) puts a talking-face video avatar on the call. Pouchy runs it on Simli and holds the Simli key: the handle carries call.video — { provider: 'simli', faceId, sessionToken, iceServers, maxSessionLength, model } — which you open with simli-client and feed the companion's remote audio track; the voice is unchanged, the face lip-syncs to it. You build the faces yourself, with your project's admin key: admin-sdk createVideoFace(image) (or POST /v1/admin/video-faces) builds one from an image of your character, and listVideoFaces() reports it ready once the build finishes (minutes to hours; billed per face built). faceId must be one of your project's ready faces, and the session needs the call.video scope, which it gets once the project has one — withhold it per reader with withhold_scopes to keep the voice and drop the face. A call that asked and got no face still connects, with call.videoUnavailable ('not_enabled' | 'not_configured' | 'face_not_allowed' | 'face_not_ready' | 'mint_failed'; face_not_ready since 0.75.1: the face is yours but still building). Billed per minute on top of the voice. Self-plumbed: startCall({ avatar }) returns the same fields on the credentials.

avatar.model (0.76.0) picks Simli's animation model: 'fasttalk' (Simli's default, used when you omit it) or 'artalk'. call.video.model says which one the session was minted with. Same per-minute rate either way — try both on your own face; how expressive it reads depends on the face image too.

connectCall({ brief }) (0.67.0) tells the companion what this call is about: your application's note ("she just got the acceptance letter", "you are calling from the station"). It opens on it and keeps to it, and never reads it out. Up to 1,000 characters. It needs the chat.instructions scope (the agent's per-turn instructions switch), because it joins the prompt as your words and is not moderated as user speech; send it from a token your backend minted.

A call made with a Pouchy World role's session token carries where the story is: the scene, the story clock, flags, the facts already revealed, and the role's own last beats. PUBLIC state only — never the role's secrets, notes, goals or unrevealed facts — because a call's instructions reach the reader's device (the ElevenLabs web SDK takes its prompt as a client-side override); keep anything the reader must not see out of the persona and brief too. call.worldBrief (and creds.worldBrief) says 'included', 'no_story' or 'unavailable' (the call went ahead without it). call.privateStory (0.68.0) says whether the role can reach its private layer on this call: 'tool' (the in-call recall_private_story tool, served ElevenLabs ↔ Pouchy, never through your page) or 'none' (the role keeps it vague). call.trimmed (0.68.0) reports the characters the server cut to keep the instructions within the realtime cap ({ story?, context? }; your brief is never cut) and is absent when nothing was. Nothing said on the call changes the story: after the call, fold it back in as a beat on the world turn door with trigger.context: "this was a phone call", the gist as text, and any proposedPatches the call should leave behind.

Mute and typing (0.69.0). call.setMuted(true) mutes the reader's microphone until setMuted(false); it holds across the companion's lines (the half-duplex re-open never undoes it), and connectCall({ muted: true }) opens the call muted. Show a mute control only when call.canMute is true. call.sendText(text) sends a line the reader TYPED as their turn: the companion answers it as something they said, it reaches onTranscript as role: 'user', and it is in the memory consolidated at hang-up. It cuts an utterance in progress, like speaking would. Nothing is sent before you call it, so run any check of your own first. injectEvent is different: a context line, never reported as the reader's words.

call.interrupt() (0.36.0) is the silent cut: stop the utterance currently being spoken WITHOUT generating new speech — for real-time commentary going stale at a beat boundary (next hand starts while last hand's remark is still playing). Idempotent; check call.provider for the tier: openai-realtime is guaranteed (response.cancel + output-buffer clear — playback stops within ~an audio frame, the session continues); elevenlabs-convai is best-effort (the EL client exposes no public stop-playback API — we signal user_activity and attempt the client's internal buffer cut; worst case a no-op). For guaranteed preemption on EL, injectEvent(text, true) — which does speak new content — remains the reliable lever.

connectCall() for the ElevenLabs Convai provider needs the optional peer dependency:

npm i @elevenlabs/client

OpenAI Realtime needs no extra dependency (self-contained WebRTC).

Build & publish

The source lives in the app repo at src/lib/companion-sdk and is decoupled from any $lib import, so this package builds with plain tsc:

cd packages/companion-sdk
npm run build      # tsc → dist/ (ESM + .d.ts + source/declaration maps) + src/ (shipped sources)
npm run build:cdn  # cdn/companion-sdk{,.min}.js + versions/<v>/ + integrity.json (SRI)
npm publish        # public scope (publishConfig.access: "public"); runs build via prepublishOnly

The CDN artifacts are committed and served from pouchy.ai: /sdk/companion-sdk{,.min}.js (floating, 1h cache) and /sdk/v<version>/companion-sdk{,.min}.js (pinned, immutable) — pin the versioned URL together with the sha384 hash from cdn/integrity.json (also published at pouchy.ai/sdk) to opt out of silent upgrades.

The wire contract (protocol.ts) is a self-contained mirror of the server's; protocol.drift.test.ts (run by the app's vitest) fails CI if they diverge.

Full release steps (version bump, CHANGELOG.md, drift test, tag) live in PUBLISHING.md.

License

Proprietary — © 2026 Pouchy.ai. The published package may be installed and used to build integrations with Pouchy's official services; all other rights are reserved. See LICENSE.