@pouchy_ai/companion-sdk 0.30.0 → 0.32.0

package/src/client.ts

@@ -0,0 +1,1959 @@
+// 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: the default REST/SSE plane, or an opt-in WebSocket plane
+// (ws-transport.ts) that degrades back to SSE on failure — both sit behind this
+// same API. Protocol types are a self-contained copy of the server's contract,
+// kept in lockstep by protocol.drift.test.ts.
+
+import type {
+	AudioClipPayload,
+	CompanionEnvelope,
+	ConfirmRequestPayload,
+	ExpressionPayload,
+	InterfaceUpdatePayload,
+	OutboundPayloadMap,
+	OutboundType,
+	PendingConfirm,
+	RenderInterfacePayload,
+	SocialMessagePayload,
+	ToolCallPayload,
+	TypingPayload,
+	UsagePayload,
+	VoiceInjectPayload,
+	WorldStateEvent
+} from './protocol';
+import { PROTOCOL_VERSION } from './protocol';
+
+/** 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'>>;
+import { parseSse } from './sse';
+import { CompanionError, type ControlErrorCodeValue } from './errors';
+import {
+	openCompanionCall,
+	type CompanionCall,
+	type CompanionCallOptions,
+	type VoiceToolBridge,
+	HOST_CONTROL_TOOLS,
+	HOST_CONTROL_TOOL_NAMES,
+	AVATAR_VISUAL_TOOLS,
+	AVATAR_VISUAL_TOOL_NAMES
+} from './call';
+
+export interface CompanionClientOptions {
+	/** Origin of the Pouchy deployment, e.g. "https://pouchy.ai". */
+	baseUrl: string;
+	/** A Pouchy access token (PAT). */
+	token: string;
+	/** Logical surface (one resumable session per surface), default "default". */
+	surface?: string;
+	/** Requested I/O modalities (intersected with the token's grant server-side). */
+	modalities?: string[];
+	/** Action types this surface can perform (declared at handshake). */
+	handles?: string[];
+	/** World-state kinds this surface emits (declared at handshake). */
+	contextKinds?: string[];
+	/** Tools the companion may ask this surface to perform (companion.tool_call). */
+	tools?: CompanionToolDecl[];
+	/** Static description of THIS app/game so the companion is grounded in where it
+	 *  is (drives reasoning + the call opener). Live state still flows via
+	 *  sendWorldState. */
+	appContext?: { name?: string; description?: string };
+	/** Open a REPRESENTATIVE ("on-behalf-of" / 代聊) session: the companion fields
+	 *  this VISITOR's messages on the owner's behalf — customer-service style —
+	 *  drawing only on screened owner context (persona + share-screened facts, plus
+	 *  the knowledge base when the owner's token grants `expose:knowledge`). Each
+	 *  visitor (stable opaque `id`, 8-64 url-safe chars that YOU keep stable per
+	 *  end-user) gets their own continuous thread. Requires the token's `represent`
+	 *  scope — without it the handshake is rejected (never silently downgraded to an
+	 *  owner-facing session). */
+	visitor?: { id: string; displayName?: string };
+	/** Injectable fetch (for Node < 18 / tests). Defaults to global fetch. */
+	fetch?: typeof fetch;
+	/** Instrumentation (0.32.0). `true` logs structured events via
+	 *  console.debug('[pouchy-sdk]', …); a function receives every
+	 *  `CompanionDebugEvent` (HTTP request/response, delivered envelope,
+	 *  stream-state transition, synthesized error) for your own logger /
+	 *  devtools / test recorder. Events never carry the token or any header —
+	 *  method, path, status, timing, envelope type/id only. Zero cost when
+	 *  unset. */
+	debug?: boolean | ((event: CompanionDebugEvent) => void);
+	/** Receive transport for the reply stream. 'sse' (default) works on every
+	 *  deploy; 'websocket' opts into the lower-latency WS plane when the host
+	 *  supports it (adapter-node / a WS gateway) and falls back to SSE if the
+	 *  socket can't open — so enabling it can never stop reply delivery. */
+	stream?: 'sse' | 'websocket';
+	/** Injectable WebSocket constructor (Node without a global WebSocket, or
+	 *  tests). Defaults to globalThis.WebSocket when present. */
+	webSocketImpl?: typeof WebSocket;
+	/** Called when a request or the event stream is rejected with 401 (expired /
+	 *  revoked token — session tokens live 1h by default). Return a fresh token
+	 *  (e.g. re-minted by your backend via POST /v1/sessions) and the client
+	 *  retries transparently; return null to give up, surfacing the failure
+	 *  exactly as without this hook. Scope denials (403 `missing_scope`) are
+	 *  configuration errors and never trigger it. Alternative: call `setToken()`
+	 *  proactively on your own refresh schedule. */
+	onAuthError?: () => string | null | Promise<string | null>;
+}
+
+export interface HelloAck {
+	session: string;
+	grantedScopes: string[];
+	modalities: string[];
+	resumeCursor: number;
+	/** True when this is a representative (visitor-facing) session — i.e. a
+	 *  `visitor` was supplied and the token holds `represent`. */
+	representative: boolean;
+	/** Representative sessions only: whether this visitor is already paired with
+	 *  the owner (their two companions are friends). Lets you skip offering a
+	 *  "pair" affordance to an already-connected visitor. */
+	visitorPaired: boolean;
+}
+
+/** A tool the embedding declares the companion may ask it to perform. */
+export interface CompanionToolDecl {
+	name: string;
+	description?: string;
+	parameters?: Record<string, unknown>;
+}
+
+/** What `onToolCall` hands your handler: the `companion.tool_call` wire payload
+ *  plus `argsJson` — `args` pre-parsed as JSON. `undefined` when `args` is
+ *  empty or not valid JSON; keep reading the raw `args` string when you need
+ *  the exact model output. */
+export interface ToolCallEvent extends ToolCallPayload {
+	argsJson?: unknown;
+}
+
+/** Model tool arguments are model output — tolerate junk without throwing. */
+function parseArgsJson(args: string): unknown {
+	if (!args.trim()) return undefined;
+	try {
+		return JSON.parse(args) as unknown;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Voice-plane credentials, discriminated by provider (see startCall). */
+export type CallCredentials =
+	| {
+			provider: 'elevenlabs-convai';
+			/** EL conversation token (open WebRTC with @elevenlabs/client). */
+			token: string;
+			agentId: string;
+			/** Pass as overrides.agent.prompt.prompt when starting the EL session. */
+			instructions: string;
+			/** Server-resolved EL voice id (the user's cloned/localized voice). Pass
+			 *  as overrides.tts.voiceId so the call isn't a stock default voice. */
+			voice?: string;
+			/** Server-resolved agent language (ISO 639-1, e.g. 'zh'). Pass as
+			 *  overrides.agent.language so the call opens in the user's language. */
+			language?: string;
+			/** First-message override ('' = suppress the canned greeting so the call
+			 *  opens in-character / context-aware). Pass as overrides.agent.firstMessage. */
+			firstMessage?: string;
+	  }
+	| {
+			provider: 'openai-realtime';
+			/** Ephemeral client secret (ek_…); open WebRTC directly to OpenAI. */
+			clientSecret: string;
+			model: string;
+			voice: string;
+			expiresAt: number | null;
+	  };
+
+export interface RecalledMemory {
+	content: string;
+	category?: string;
+	kind?: string;
+	importance: number;
+	namespace: string;
+	createdAt?: string;
+}
+
+/** One exchange from a session's conversation log (see `history`). `user` is the
+ *  end-user's message, `assistant` the companion's reply; either may be `''` for
+ *  a paused / assistant-only row. `ts` is epoch ms. */
+export interface CompanionTurn {
+	user: string;
+	assistant: string;
+	ts: number;
+}
+
+/** The user's current companion avatar (see getAvatar). */
+export interface CompanionAvatar {
+	/** Companion display name (the user's chosen name), or null. */
+	name: string | null;
+	/** Persona archetype driving the default look/voice. */
+	archetype: 'girlfriend' | 'boyfriend' | 'pet';
+	/** The active model id (e.g. "default-gf-luna", or a custom id), or null. */
+	modelId: string | null;
+	/** Absolute URL to the VRM 3D model — the avatar itself. CORS-enabled so a
+	 *  cross-origin renderer can fetch it. Null only if resolution failed. */
+	vrmUrl: string | null;
+	/** Absolute URL to a flat 2D portrait when available; null for VRM-only
+	 *  built-ins today (reserved for custom previews / server-rendered thumbs). */
+	imageUrl: string | null;
+}
+
+/** One nonzero stablecoin balance line. */
+export interface WalletBalance {
+	/** Stablecoin code (USDT / USDC / DAI / USD1). */
+	currency: string;
+	/** Decimal amount as a string (not atomic units), e.g. "5.83". */
+	amount: string;
+}
+/** Read-only snapshot of the companion instance's OWN wallet (receive-only —
+ *  there is no way to move funds via the SDK). Requires the `wallet.read` scope. */
+export interface CompanionWallet {
+	/** Nonzero per-currency balances (empty when the wallet is empty). */
+	balances: WalletBalance[];
+	/** Total across the balances; the allowed stablecoins are USD-pegged 1:1. */
+	totalUsd: number;
+	/** Denomination of `totalUsd` (always "USD" today). */
+	currency: string;
+}
+
+/** Available sizes for the Pouchy brand icon (px). */
+export type BrandIconSize = 256 | 512 | 1024;
+
+/** 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: string, size: BrandIconSize = 512): string {
+	return baseUrl.replace(/\/+$/, '') + `/brand-assets/icon/pouchy-icon-${size}.png`;
+}
+
+/** The single error type the SDK throws — for HTTP failures (`status` is the
+ *  response code) AND for local precondition mistakes (`status: 0`, e.g. calling
+ *  a method before `connect()`). `code` is a stable machine-readable tag you can
+ *  switch on, shared with the `control.error` stream event vocabulary:
+ *  `'not_connected'`, `'missing_option'`, `'not_representative'`, or the server's
+ *  own error code for an HTTP failure (when it sends one). Defined in errors.ts
+ *  (so call.ts shares it cycle-free); re-exported here so the public import
+ *  path is unchanged. */
+export { CompanionError } from './errors';
+
+/** The server's memory-consolidation diagnostic from `endSession()` / `close()`.
+ *  `ok` is whether consolidation ran; `facts` is how many memories it wrote;
+ *  `skipped` (when present) says why nothing was written
+ *  (`'no_session'` | `'no_content'` | `'throttled'`). */
+export interface EndSessionResult {
+	ok: boolean;
+	facts?: number;
+	skipped?: string;
+}
+
+/** What `sendText(text, { awaitReply: true })` resolves with: the completed
+ *  turn's reply. `text` is the authoritative final assistant text (same value
+ *  onMessage receives); `envelope` is the full `companion.message` envelope
+ *  for hosts that want the id/ts. */
+export interface SendTextReply {
+	seq: number | null;
+	text: string;
+	envelope: CompanionEnvelope;
+}
+
+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;
+const SEEN_CAP = 512;
+
+/** Structured instrumentation event (0.32.0) — see `debug` in
+ *  CompanionClientOptions. `at` is Date.now(). Deliberately free of secrets:
+ *  no token, no headers, no bodies — safe to pipe to any logger. */
+export type CompanionDebugEvent =
+	| { kind: 'request'; at: number; method: string; path: string }
+	| {
+			kind: 'response';
+			at: number;
+			method: string;
+			path: string;
+			status: number;
+			/** Wall-clock ms from request start to headers. */
+			ms: number;
+	  }
+	| { kind: 'envelope'; at: number; type: string; id: string }
+	| { kind: 'stream'; at: number; state: CompanionStreamState; prev: CompanionStreamState }
+	| { kind: 'error'; at: number; message: string; code?: string; status?: number };
+
+/** Lifecycle of the receive event stream (0.30.0) — observable via
+ *  `client.streamState` + `onStreamStateChange`, so a host can render a
+ *  connection indicator without hand-rolling its own enum.
+ *  - `idle`        — before start()
+ *  - `connecting`  — start() called; first connection being established
+ *  - `connected`   — the event stream is live (WS or SSE as configured)
+ *  - `reconnecting`— connection lost / closed; backing off before the next try
+ *  - `degraded_sse`— the WebSocket transport errored and delivery continues on
+ *                    the SSE fallback (still live — replies keep arriving)
+ *  - `stopped`     — stop()/close() was called, or a permanent stream failure
+ *                    (the `stream_unauthorized` control.error) ended the loop */
+export type CompanionStreamState =
+	| 'idle'
+	| 'connecting'
+	| 'connected'
+	| 'reconnecting'
+	| 'degraded_sse'
+	| 'stopped';
+
+export class CompanionClient {
+	private readonly opts: CompanionClientOptions;
+	private readonly doFetch: typeof fetch;
+	private _session: string | null = null;
+	private cursor = 0;
+	private streaming = false;
+	private abort: AbortController | null = null;
+	// Bumped on every start()/stop(): a loop whose generation is stale exits
+	// instead of resurrecting — stop() immediately followed by start() used to
+	// leave TWO concurrent receive loops polling forever (the old one saw
+	// `streaming === true` again after its backoff sleep).
+	private streamGen = 0;
+	private readonly handlers = new Map<string, Set<Handler>>();
+	private readonly seen = new Set<string>();
+	// Token-streaming delta subscribers (P1-2). When any are registered,
+	// sendText automatically streams the reply.
+	private readonly deltaHandlers = new Set<DeltaHandler>();
+	// Voice tool-calls awaiting the app's sendToolResult, keyed by a synthetic id.
+	private readonly pendingVoiceTools = new Map<string, (out: string) => void>();
+	// Receive-stream lifecycle (0.30.0) — see CompanionStreamState.
+	private _streamState: CompanionStreamState = 'idle';
+	private readonly streamStateHandlers = new Set<
+		(state: CompanionStreamState, prev: CompanionStreamState) => void
+	>();
+
+	// Instrumentation sink (0.32.0) — null when `debug` is unset, so the hot
+	// paths pay one falsy check.
+	private readonly debugSink: ((event: CompanionDebugEvent) => void) | null;
+
+	constructor(opts: CompanionClientOptions) {
+		if (!opts.baseUrl)
+			throw new CompanionError('CompanionClient: baseUrl is required', 0, 'missing_option');
+		if (!opts.token)
+			throw new CompanionError('CompanionClient: token is required', 0, 'missing_option');
+		this.opts = opts;
+		this.doFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+		this.debugSink =
+			opts.debug === true
+				? (e) => console.debug('[pouchy-sdk]', e.kind, e)
+				: typeof opts.debug === 'function'
+					? opts.debug
+					: null;
+	}
+
+	/** Fire an instrumentation event. A throwing sink must never break the
+	 *  request/stream path it observes. */
+	private dbg(event: CompanionDebugEvent): void {
+		if (!this.debugSink) return;
+		try {
+			this.debugSink(event);
+		} catch {
+			/* observer errors are the observer's problem */
+		}
+	}
+
+	/** The active session id, or null before connect(). */
+	get sessionId(): string | null {
+		return this._session;
+	}
+
+	/** Current lifecycle of the receive event stream (0.30.0) — `idle` before
+	 *  start(), then `connecting` / `connected` / `reconnecting` /
+	 *  `degraded_sse` (WS errored, SSE fallback carrying delivery) / `stopped`.
+	 *  Subscribe to transitions with `onStreamStateChange`. */
+	get streamState(): CompanionStreamState {
+		return this._streamState;
+	}
+
+	/** Subscribe to receive-stream lifecycle transitions (0.30.0) — drive a
+	 *  connection indicator: `client.onStreamStateChange((s) => setStatus(s))`.
+	 *  Fires only on change, with the previous state as the second argument.
+	 *  Returns an unsubscribe function. */
+	onStreamStateChange(
+		handler: (state: CompanionStreamState, prev: CompanionStreamState) => void
+	): () => void {
+		this.streamStateHandlers.add(handler);
+		return () => this.streamStateHandlers.delete(handler);
+	}
+
+	private setStreamState(next: CompanionStreamState): void {
+		if (next === this._streamState) return;
+		const prev = this._streamState;
+		this._streamState = next;
+		this.dbg({ kind: 'stream', at: Date.now(), state: next, prev });
+		// Same isolation doctrine as emit(): a throwing consumer handler must not
+		// skip the remaining handlers or bubble into the stream loop.
+		for (const h of this.streamStateHandlers) {
+			try {
+				h(next, prev);
+			} catch (e) {
+				console.error('[companion-sdk] stream-state handler threw', e);
+			}
+		}
+	}
+
+	/** Swap the bearer token used by every subsequent request and stream
+	 *  reconnect. Session tokens expire (default 1h) — call this when your
+	 *  backend re-mints one, or wire `onAuthError` to do it on demand. */
+	setToken(token: string): void {
+		if (!token) throw new CompanionError('setToken: token is required', 0, 'missing_option');
+		this.opts.token = token;
+	}
+
+	// In-flight onAuthError call, shared so concurrent 401s trigger ONE refresh.
+	private refreshing: Promise<string | null> | null = null;
+
+	/** Run opts.onAuthError (deduped), apply the fresh token, and report whether
+	 *  the caller should retry. Never throws — a failed refresh means "surface
+	 *  the original 401". */
+	private async tryRefreshToken(): Promise<boolean> {
+		const refresh = this.opts.onAuthError;
+		if (!refresh) return false;
+		this.refreshing ??= Promise.resolve()
+			.then(refresh)
+			.catch(() => null)
+			.finally(() => {
+				this.refreshing = null;
+			});
+		const token = await this.refreshing;
+		if (!token) return false;
+		this.opts.token = token;
+		return true;
+	}
+
+	/** doFetch with one transparent retry after a 401-triggered token refresh.
+	 *  Everything except the stream loop (which has its own auth handling) goes
+	 *  through here. */
+	// The running server's X-Pouchy-Api-Version (captured off every authed
+	// response) — capability detection for additive protocol features.
+	private serverApiVersion: string | null = null;
+
+	/** True when the server echoes `replyTo` on companion.message (API ≥ 1.1) —
+	 *  the strict awaitReply correlation is only safe to enforce there. */
+	private serverEchoesReplyTo(): boolean {
+		const m = /^(\d+)\.(\d+)/.exec(this.serverApiVersion ?? '');
+		if (!m) return false;
+		const major = Number(m[1]);
+		const minor = Number(m[2]);
+		return major > 1 || (major === 1 && minor >= 1);
+	}
+
+	private async fetchAuthed(
+		url: string,
+		init: RequestInit & { headers: Record<string, string> }
+	): Promise<Response> {
+		const method = init.method ?? 'GET';
+		const path = url.startsWith(this.opts.baseUrl) ? url.slice(this.opts.baseUrl.length) : url;
+		const startedAt = Date.now();
+		this.dbg({ kind: 'request', at: startedAt, method, path });
+		let res: Response;
+		try {
+			res = await this.doFetch(url, init);
+		} catch (e) {
+			// A caller-supplied AbortSignal makes fetch throw a native AbortError —
+			// convert it at this single choke point so cancellation honors the
+			// "every helper rejects with CompanionError" contract (code 'aborted').
+			const err = this.asCompanionError(e);
+			this.dbg({ kind: 'error', at: Date.now(), message: err.message, code: err.code, status: 0 });
+			throw err;
+		}
+		this.dbg({
+			kind: 'response',
+			at: Date.now(),
+			method,
+			path,
+			status: res.status,
+			ms: Date.now() - startedAt
+		});
+		const apiVersion = res.headers.get('x-pouchy-api-version');
+		if (apiVersion) this.serverApiVersion = apiVersion;
+		if (res.status !== 401) return res;
+		// A step-up 401 (biometric confirm) is NOT a token problem — refreshing
+		// and retrying would burn a backend re-mint on a doomed request. Only
+		// token-shaped 401s go through onAuthError.
+		const code = await this.errorCodeOf(res);
+		if (code === 'step_up_required' || code === 'step_up_failed') return res;
+		if (!(await this.tryRefreshToken())) return res;
+		init.headers.Authorization = `Bearer ${this.opts.token}`;
+		const retryAt = Date.now();
+		this.dbg({ kind: 'request', at: retryAt, method, path });
+		try {
+			const retryRes = await this.doFetch(url, init);
+			this.dbg({
+				kind: 'response',
+				at: Date.now(),
+				method,
+				path,
+				status: retryRes.status,
+				ms: Date.now() - retryAt
+			});
+			return retryRes;
+		} catch (e) {
+			const err = this.asCompanionError(e);
+			this.dbg({ kind: 'error', at: Date.now(), message: err.message, code: err.code, status: 0 });
+			throw err;
+		}
+	}
+
+	/** Normalize a thrown fetch error to a CompanionError. An AbortError (the
+	 *  caller's signal fired) becomes a switchable `code: 'aborted'`; anything
+	 *  else that is already a CompanionError passes through; the rest wrap as a
+	 *  status-0 network failure. */
+	private asCompanionError(e: unknown): CompanionError {
+		if (e instanceof CompanionError) return e;
+		const name = (e as { name?: unknown })?.name;
+		if (name === 'AbortError') return new CompanionError('request aborted', 0, 'aborted');
+		return new CompanionError(e instanceof Error ? e.message : 'network request failed', 0);
+	}
+
+	/** Peek the error `code` of a failure response without consuming its body. */
+	private async errorCodeOf(res: Response): Promise<string | undefined> {
+		try {
+			const json = (await res.clone().json()) as { code?: unknown } | null;
+			return typeof json?.code === 'string' ? json.code : undefined;
+		} catch {
+			return undefined;
+		}
+	}
+
+	private url(path: string): string {
+		return this.opts.baseUrl.replace(/\/+$/, '') + path;
+	}
+
+	private jsonHeaders(): Record<string, string> {
+		return { Authorization: `Bearer ${this.opts.token}`, 'Content-Type': 'application/json' };
+	}
+
+	private requireSession(): string {
+		if (!this._session)
+			throw new CompanionError('CompanionClient: call connect() first', 0, 'not_connected');
+		return this._session;
+	}
+
+	/** Retry-After in seconds for a throttled response: the JSON body's
+	 *  `retryAfterSec` (companion rate-limit shape) wins, else the standard
+	 *  Retry-After header. Undefined when the server named neither. */
+	private retryAfterFrom(res: Response, json: { retryAfterSec?: unknown } | null): number | undefined {
+		const fromBody = json?.retryAfterSec;
+		if (typeof fromBody === 'number' && Number.isFinite(fromBody) && fromBody >= 0) return fromBody;
+		// Missing/blank header must stay undefined — Number(null) is 0, which
+		// used to stamp retryAfter: 0 on EVERY error without the header (a 400,
+		// a 404 …), telling backoff code "retry immediately".
+		const raw = res.headers.get('Retry-After');
+		if (raw === null || raw.trim() === '') return undefined;
+		const header = Number(raw);
+		if (Number.isFinite(header) && header >= 0) return header;
+		// RFC 9110 also allows an HTTP-date (proxies/CDNs emit it) — convert to a
+		// non-negative seconds delta (0.30.0). Unparseable stays undefined.
+		const at = Date.parse(raw);
+		if (!Number.isNaN(at)) return Math.max(0, Math.ceil((at - Date.now()) / 1000));
+		return undefined;
+	}
+
+	private async postJson<T>(path: string, body: unknown, signal?: AbortSignal): Promise<T> {
+		const res = await this.fetchAuthed(this.url(path), {
+			method: 'POST',
+			headers: this.jsonHeaders(),
+			body: JSON.stringify(body),
+			// The signal rides `init`, so the 401-refresh retry in fetchAuthed
+			// reuses it automatically (init is passed to both doFetch calls).
+			...(signal ? { signal } : {})
+		});
+		const json = (await res.json().catch(() => null)) as
+			| ({ ok?: boolean; error?: string; code?: string; retryAfterSec?: number } & T)
+			| null;
+		if (!res.ok || !json || json.ok === false) {
+			// The 429 body carries an actionable `hint` (e.g. "provision a project
+			// …") — surface it instead of discarding it.
+			const hint = (json as { hint?: unknown } | null)?.hint;
+			const detail = typeof hint === 'string' && hint ? ` — ${hint}` : '';
+			throw new CompanionError(
+				(json?.error || `request failed (${res.status})`) + detail,
+				res.status,
+				json?.code,
+				this.retryAfterFrom(res, json)
+			);
+		}
+		return json;
+	}
+
+	/** Handshake: start or resume the session for this surface. */
+	async connect(opts?: { signal?: AbortSignal }): Promise<HelloAck> {
+		const json = await this.postJson<{
+			session: string;
+			grantedScopes: string[];
+			modalities: string[];
+			resumeCursor: number;
+			representative?: boolean;
+			visitorPaired?: boolean;
+		}>('/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 } : {})
+		}, opts?.signal);
+		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: string, opts?: { signal?: AbortSignal }): Promise<{ pairId: string | null }> {
+		if (!this.opts.visitor) {
+			throw new CompanionError(
+				'pairVisitor() requires a representative session (createCompanion({ visitor }))',
+				0,
+				'not_representative'
+			);
+		}
+		if (!visitorToken)
+			throw new CompanionError('pairVisitor: visitorToken is required', 0, 'missing_option');
+		const json = await this.postJson<{ pairId?: string }>('/api/companion/pair', {
+			visitorToken,
+			visitorId: this.opts.visitor.id
+		}, opts?.signal);
+		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.
+	 *
+	 *  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.
+	 *
+	 *  AWAIT THE REPLY (request/response hosts — a REPL, an HTTP handler, a
+	 *  test): pass `awaitReply: true` and the promise resolves with the final
+	 *  reply `{ seq, text, envelope }` — no onMessage wiring, no hand-rolled
+	 *  turn gate. It rides the same streaming request (the terminal `done`
+	 *  frame carries the authoritative envelope), so it works without start();
+	 *  onMessage/onDelta subscribers still fire as usual. Only when the reply
+	 *  can't ride the request (`stream: false`, or an old server) does it fall
+	 *  back to the event stream — which then DOES need start() — resolving with
+	 *  the next `companion.message`, or rejecting with code `reply_timeout`
+	 *  after `replyTimeoutMs` (default 60s). */
+	async sendText(
+		text: string,
+		opts: { awaitReply: true; images?: string[]; stream?: boolean; replyTimeoutMs?: number; signal?: AbortSignal }
+	): Promise<SendTextReply>;
+	async sendText(
+		text: string,
+		opts?: { images?: string[]; stream?: boolean; awaitReply?: boolean; replyTimeoutMs?: number; signal?: AbortSignal }
+	): Promise<{ seq: number | null }>;
+	async sendText(
+		text: string,
+		opts?: { images?: string[]; stream?: boolean; awaitReply?: boolean; replyTimeoutMs?: number; signal?: AbortSignal }
+	): Promise<{ seq: number | null } | SendTextReply> {
+		const id = this.requireSession();
+		// Client-minted correlation id (0.28.0): the server echoes it back as
+		// `replyTo` on this turn's companion.message — even across an app-tool
+		// pause — so awaitReply's fallback matches THE reply, not the first
+		// message that happens by (world-state reactions, confirm outcomes).
+		const turnId = `turn_${this.randomId()}`;
+		const body = { text, turnId, ...(opts?.images?.length ? { images: opts.images } : {}) };
+		if (opts?.awaitReply) return this.sendTextAwaitingReply(id, body, opts, turnId);
+		const wantStream = opts?.stream ?? this.deltaHandlers.size > 0;
+		if (!wantStream) {
+			const json = await this.postJson<{ seq: number | null }>(
+				`/api/companion/session/${id}/input`,
+				body,
+				opts?.signal
+			);
+			return { seq: json.seq ?? null };
+		}
+		return this.sendTextStreaming(id, body, opts?.signal);
+	}
+
+	/** The awaitReply leg of sendText. Prefers the in-request answer (the
+	 *  streaming `done` frame's envelope); falls back to the next
+	 *  `companion.message` off the event stream, bounded by a timeout. The
+	 *  fallback subscription opens BEFORE the POST so a fast event-stream reply
+	 *  can't slip through the gap. */
+	private async sendTextAwaitingReply(
+		sessionId: string,
+		body: Record<string, unknown>,
+		opts?: { stream?: boolean; replyTimeoutMs?: number; signal?: AbortSignal },
+		turnId?: string
+	): Promise<SendTextReply> {
+		const timeoutMs = opts?.replyTimeoutMs ?? 60_000;
+		let resolveFallback!: (env: CompanionEnvelope) => void;
+		const fallback = new Promise<CompanionEnvelope>((res) => (resolveFallback = res));
+		// Correlate: resolve only on THIS turn's reply (`replyTo === turnId`).
+		// Servers on API ≥ 1.1 always echo it, so there an un-tagged message is
+		// PROACTIVE traffic (world-state reaction, confirm outcome) — skip it.
+		// Older servers never echo — keep the legacy resolve-on-first there.
+		const off = this.on('companion.message', (env) => {
+			const replyTo = (env.payload as { replyTo?: unknown } | null)?.replyTo;
+			if (replyTo === turnId) return resolveFallback(env);
+			if (replyTo === undefined && !this.serverEchoesReplyTo()) resolveFallback(env);
+		});
+		// One deadline bounds the WHOLE operation (0.28.0): the timer starts
+		// before the POST, so a stalled streaming response can no longer hang the
+		// promise past replyTimeoutMs (previously only the fallback wait was
+		// bounded). The abort tears the in-flight stream down with it.
+		const ac = new AbortController();
+		// Link the caller's signal: aborting it tears down the in-flight stream
+		// (via ac) AND rejects the whole operation with `aborted`, exactly like
+		// the deadline does. If it is already aborted, fail fast.
+		let onCallerAbort: (() => void) | undefined;
+		if (opts?.signal) {
+			if (opts.signal.aborted) throw new CompanionError('request aborted', 0, 'aborted');
+			onCallerAbort = () => ac.abort();
+			opts.signal.addEventListener('abort', onCallerAbort, { once: true });
+		}
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		// Held so the finally can REMOVE it — a host reusing one long-lived signal
+		// across many awaitReply calls accumulated one orphan listener per call.
+		let onCallerAbortReject: (() => void) | undefined;
+		const deadline = new Promise<never>((_, reject) => {
+			timer = setTimeout(() => {
+				ac.abort();
+				reject(
+					new CompanionError(
+						`timed out after ${timeoutMs}ms waiting for the reply — buffered mode needs start() polling the event stream`,
+						0,
+						'reply_timeout'
+					)
+				);
+			}, timeoutMs);
+			// The caller's signal also rejects the operation (the stream teardown
+			// alone would otherwise leave the fallback wait hanging to the timer).
+			if (opts?.signal) {
+				onCallerAbortReject = () => reject(new CompanionError('request aborted', 0, 'aborted'));
+				opts.signal.addEventListener('abort', onCallerAbortReject, { once: true });
+			}
+		});
+		try {
+			let seq: number | null = null;
+			let envelope: CompanionEnvelope | undefined;
+			let pausedOnTools = false;
+			if (opts?.stream === false) {
+				const json = await Promise.race([
+					// ac.signal, like the streaming leg: the deadline and the caller's
+					// signal both abort it — without this the promise rejected but the
+					// billed POST kept running beyond cancellation.
+					this.postJson<{ seq: number | null }>(
+						`/api/companion/session/${sessionId}/input`,
+						body,
+						ac.signal
+					),
+					deadline
+				]);
+				seq = json.seq ?? null;
+			} else {
+				const r = await Promise.race([
+					this.sendTextStreaming(sessionId, body, ac.signal),
+					deadline
+				]);
+				seq = r.seq;
+				envelope = r.envelope;
+				pausedOnTools = r.kind === 'tool_calls';
+			}
+			if (!envelope) {
+				// A turn paused on app tool calls resolves via the event stream once
+				// the app posts results — without start() those events never arrive,
+				// so waiting out the timer is a guaranteed hang. Fail fast + say why.
+				if (pausedOnTools && !this.streaming) {
+					throw new CompanionError(
+						'the turn paused on app tool calls — awaitReply needs start() (the event stream) to receive the post-resume reply',
+						0,
+						'needs_event_stream'
+					);
+				}
+				envelope = await Promise.race([fallback, deadline]);
+			}
+			const replyText = (envelope.payload as { text?: unknown })?.text;
+			return { seq, text: typeof replyText === 'string' ? replyText : '', envelope };
+		} finally {
+			off();
+			if (timer !== undefined) clearTimeout(timer);
+			if (onCallerAbort) opts?.signal?.removeEventListener('abort', onCallerAbort);
+			if (onCallerAbortReject) opts?.signal?.removeEventListener('abort', onCallerAbortReject);
+		}
+	}
+
+	/** 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 async sendTextStreaming(
+		sessionId: string,
+		body: Record<string, unknown>,
+		signal?: AbortSignal
+	): Promise<{ seq: number | null; envelope?: CompanionEnvelope; kind?: string }> {
+		const res = await this.fetchAuthed(this.url(`/api/companion/session/${sessionId}/input`), {
+			method: 'POST',
+			headers: this.jsonHeaders(),
+			body: JSON.stringify({ ...body, stream: true }),
+			...(signal ? { signal } : {})
+		});
+		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)) as
+				| ({ ok?: boolean; error?: string; code?: string; retryAfterSec?: number; seq?: number | null } & Record<
+						string,
+						unknown
+					>)
+				| null;
+			if (!res.ok || !json || json.ok === false) {
+				// Same as postJson: the 429 body's actionable `hint` (e.g. "provision
+				// a project …") must survive the streaming leg too (0.30.0).
+				const hint = (json as { hint?: unknown } | null)?.hint;
+				const detail = typeof hint === 'string' && hint ? ` — ${hint}` : '';
+				throw new CompanionError(
+					(json?.error || `request failed (${res.status})`) + detail,
+					res.status,
+					json?.code,
+					this.retryAfterFrom(res, json)
+				);
+			}
+			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: string, meta: { reset?: boolean }) => {
+			for (const h of this.deltaHandlers) h(chunk, meta);
+		};
+		try {
+		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') {
+					// A malformed delta frame is dropped, not fatal — losing one text
+					// chunk beats throwing away the whole turn (the final message
+					// arrives intact in the done frame / event stream regardless).
+					let d: { text?: string };
+					try {
+						d = JSON.parse(ev.data) as { text?: string };
+					} catch {
+						continue;
+					}
+					if (typeof d.text === 'string' && d.text) fireDelta(d.text, {});
+				} else if (ev.event === 'reset') {
+					fireDelta('', { reset: true });
+				} else if (ev.event === 'done') {
+					// The done frame carries the turn's resolution — unparseable means
+					// the turn's outcome is unknowable, so fail it explicitly instead
+					// of letting a raw SyntaxError escape the SDK.
+					let d: {
+						ok?: boolean;
+						error?: string;
+						code?: string;
+						status?: number;
+						kind?: string;
+						seq?: number | null;
+						envelope?: CompanionEnvelope | null;
+					};
+					try {
+						d = JSON.parse(ev.data) as typeof d;
+					} catch {
+						try {
+							await reader.cancel();
+						} catch {
+							/* stream already finished */
+						}
+						throw new CompanionError('malformed done frame', 502);
+					}
+					try {
+						await reader.cancel();
+					} catch {
+						/* stream already finished */
+					}
+					if (d.ok === false) {
+						throw new CompanionError(d.error || 'turn failed', d.status ?? 500, d.code);
+					}
+					// 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, envelope: d.envelope ?? undefined, kind: d.kind };
+				}
+			}
+			if (done) break;
+		}
+		throw new CompanionError('stream ended without a done frame', 502);
+		} catch (e) {
+			// A throwing user onDelta handler (or an abort) must not leak the
+			// reader — cancel so the connection is released, then rethrow.
+			try {
+				await reader.cancel();
+			} catch {
+				/* stream already finished */
+			}
+			throw e;
+		}
+	}
+
+	/** 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 {
+		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.
+	 *
+	 *  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: WorldStateInput | WorldStateInput[],
+		opts?: { signal?: AbortSignal }
+	): Promise<{ accepted: number; dropped: number; injected: number; reacted: boolean }> {
+		const id = this.requireSession();
+		const fill = (e: WorldStateInput): WorldStateEvent => ({
+			...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<{
+			accepted: number;
+			dropped: number;
+			injected?: number;
+			reacted?: boolean;
+		}>(`/api/companion/session/${id}/context`, body, opts?.signal);
+		// injected/reacted tell the host a live-call inject or a proactive text
+		// reaction was triggered by this batch (0.28.0 — previously discarded).
+		return {
+			accepted: json.accepted ?? 0,
+			dropped: json.dropped ?? 0,
+			injected: json.injected ?? 0,
+			reacted: json.reacted === true
+		};
+	}
+
+	private randomId(): string {
+		const c = (globalThis as { crypto?: { randomUUID?: () => string } }).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?: { voice?: string; locale?: string; signal?: AbortSignal }
+	): Promise<CallCredentials> {
+		const id = this.requireSession();
+		return this.postJson<CallCredentials>(
+			`/api/companion/session/${id}/call`,
+			{ voice: opts?.voice, locale: opts?.locale },
+			opts?.signal
+		);
+	}
+
+	/** 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?: CompanionCallOptions & { voice?: string; locale?: string }
+	): Promise<CompanionCall> {
+		// 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: { role: 'user' | 'assistant'; text: string }[] = [];
+		const callerOnTranscript = opts?.onTranscript;
+		const callerOnError = opts?.onError;
+		// Cleanup must run whichever side ends the call — the app calling close()
+		// OR a provider-initiated teardown (pc failure / EL disconnect), which
+		// surfaces as onError with no close() following. Idempotent. `unsub` is
+		// assigned after the call opens; a connect-phase onError finds the no-op.
+		let unsub: () => void = () => {};
+		let cleaned = false;
+		const cleanup = () => {
+			if (cleaned) return;
+			cleaned = true;
+			unsub();
+			// Consolidate this call into durable memory (best-effort, keepalive).
+			void this.endSession({ transcript });
+		};
+		const wrappedOpts: CompanionCallOptions = {
+			...opts,
+			onTranscript: (e) => {
+				// Cap the buffer (endSession consolidates the tail anyway) so an
+				// hours-long call can't grow this array unbounded.
+				if (e?.text?.trim()) {
+					transcript.push({ role: e.role, text: e.text });
+					if (transcript.length > 200) transcript.splice(0, transcript.length - 200);
+				}
+				callerOnTranscript?.(e);
+			},
+			onError: (err) => {
+				cleanup();
+				callerOnError?.(err);
+			}
+		};
+
+		// 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: VoiceToolBridge | undefined = 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().
+		unsub = this.on('companion.voice_inject', (env) => {
+			const p = env.payload as { text?: unknown; speak?: unknown };
+			if (typeof p?.text === 'string' && p.text) call.injectEvent(p.text, p.speak !== false);
+		});
+		const close = call.close;
+		return {
+			...call,
+			close: () => {
+				close();
+				cleanup();
+			}
+		};
+	}
+
+	/** 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).
+	 *
+	 *  Returns the server's consolidation diagnostic — `{ ok, facts?, skipped? }`
+	 *  — or `null` if there was no session or the (swallowed) keepalive request
+	 *  failed. `skipped` tells you WHY nothing was written: `'no_session'` (you
+	 *  passed the instance id, not the session id), `'no_content'` (empty turn log
+	 *  / a voice transcript that never arrived), `'throttled'` (a duplicate end
+	 *  beacon — harmless). `facts` is how many memories were consolidated. */
+	async endSession(opts?: {
+		transcript?: { role: string; text: string }[];
+	}): Promise<EndSessionResult | null> {
+		const id = this._session;
+		if (!id) return null;
+		// 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 {
+			const res = await this.fetchAuthed(this.url(`/api/companion/session/${id}/end`), {
+				method: 'POST',
+				headers: this.jsonHeaders(),
+				body: JSON.stringify({ transcript }),
+				keepalive: true
+			});
+			return (await res.json().catch(() => null)) as EndSessionResult | null;
+		} catch {
+			/* best-effort — memory consolidation is not on the user's critical path */
+			return null;
+		}
+	}
+
+	/** Tear the session down in one call: stop the event stream and consolidate
+	 *  memory (endSession) exactly once. The single teardown entry point for a
+	 *  NON-voice (text) session — mirror of what a connectCall() handle's close()
+	 *  does for voice. Idempotent. Returns endSession's diagnostic (or null).
+	 *  NOTE: if you drive `ping()` on your own timer for a background tab, clear
+	 *  that timer yourself — the client doesn't own it. */
+	async close(): Promise<EndSessionResult | null> {
+		this.stop();
+		return this.endSession();
+	}
+
+	/** 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: string,
+		result: { ok?: boolean; result?: unknown },
+		opts?: { signal?: AbortSignal }
+	): Promise<{ allDone: boolean }> {
+		// 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<{ allDone: boolean }>(
+			`/api/companion/session/${id}/tool-result`,
+			{ callId, ok: result.ok !== false, result: result.result },
+			opts?.signal
+		);
+		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. */
+	private invokeVoiceTool(name: string, argsJson: string): Promise<string> {
+		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 || '{}') as { action?: unknown; params?: unknown };
+				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 || '{}') as { feature?: unknown; on?: unknown };
+				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<string>((resolve) => {
+			let settled = false;
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const finish = (out: string) => {
+				if (settled) return;
+				settled = true;
+				// Clear on normal completion too — a chatty tool-using call was
+				// accumulating a live 20s timer (+closure) per invocation.
+				if (timer) clearTimeout(timer);
+				this.pendingVoiceTools.delete(id);
+				resolve(out);
+			};
+			this.pendingVoiceTools.set(id, finish);
+			timer = 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 }
+			} as CompanionEnvelope);
+		});
+	}
+
+	/** Convenience: subscribe to tool-call requests from the companion. The call
+	 *  carries the wire payload plus `argsJson` — `args` pre-parsed as JSON
+	 *  (undefined when empty or malformed), so handlers don't each re-implement
+	 *  the same try/catch around `JSON.parse(args)`. */
+	onToolCall(
+		handler: (call: ToolCallEvent, envelope: CompanionEnvelope) => void
+	): () => void {
+		return this.on('companion.tool_call', (env) => {
+			const p = env.payload as { id?: unknown; name?: unknown; args?: unknown };
+			if (typeof p?.id === 'string' && typeof p?.name === 'string') {
+				const args = typeof p.args === 'string' ? p.args : '';
+				handler({ id: p.id, name: p.name, args, argsJson: parseArgsJson(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`. Since 0.30.0 `code` is typed as
+	 *  `ControlErrorCodeValue` (the CONTROL_ERROR_CODES vocabulary + the
+	 *  SDK-synthesized stream codes, open for newer servers) so a `switch` on it
+	 *  autocompletes. Returns an unsubscribe fn. */
+	onError(
+		handler: (
+			err: { code: ControlErrorCodeValue; message: string },
+			envelope: CompanionEnvelope
+		) => void
+	): () => void {
+		return this.on('control.error', (env) => {
+			const p = env.payload as { code?: unknown; message?: unknown };
+			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. Without `query` the
+	 *  facts come back ranked by importance/recency; with `query` the server
+	 *  runs semantic search over them (embedding-based, falls back to ranked
+	 *  when embeddings are unavailable) — e.g.
+	 *  `recall({ query: 'food preferences', limit: 10 })`. */
+	async recall(opts?: { limit?: number; query?: string; signal?: AbortSignal }): Promise<RecalledMemory[]> {
+		const params = new URLSearchParams();
+		if (opts?.limit) params.set('limit', String(opts.limit));
+		if (opts?.query?.trim()) params.set('q', opts.query.trim());
+		const query = params.toString();
+		const qs = query ? `?${query}` : '';
+		const res = await this.fetchAuthed(this.url(`/api/companion/memory${qs}`), {
+			headers: { Authorization: `Bearer ${this.opts.token}` },
+			...(opts?.signal ? { signal: opts.signal } : {})
+		});
+		const json = (await res.json().catch(() => null)) as
+			| { ok?: boolean; error?: string; code?: string; memories?: RecalledMemory[] }
+			| null;
+		if (!res.ok || !json || json.ok === false) {
+			throw new CompanionError(json?.error || `recall failed (${res.status})`, res.status, json?.code);
+		}
+		return json.memories ?? [];
+	}
+
+	/** Fetch this session's recent conversation turns (oldest→newest) so a
+	 *  reconnecting embed can restore its transcript. Distinct from `recall`
+	 *  (durable memory / facts) — this is the raw exchange log. Returns the
+	 *  token's OWN session turns only; requires a live session (call `connect`
+	 *  first). `limit` defaults to 20, capped at 50. */
+	async history(opts?: { limit?: number; signal?: AbortSignal }): Promise<CompanionTurn[]> {
+		const id = this.requireSession();
+		const qs = opts?.limit ? `?limit=${encodeURIComponent(opts.limit)}` : '';
+		const res = await this.fetchAuthed(
+			this.url(`/api/companion/session/${encodeURIComponent(id)}/history${qs}`),
+			{
+				headers: { Authorization: `Bearer ${this.opts.token}` },
+				...(opts?.signal ? { signal: opts.signal } : {})
+			}
+		);
+		const json = (await res.json().catch(() => null)) as
+			| { ok?: boolean; error?: string; code?: string; history?: CompanionTurn[] }
+			| null;
+		if (!res.ok || !json || json.ok === false) {
+			throw new CompanionError(json?.error || `history failed (${res.status})`, res.status, json?.code);
+		}
+		return json.history ?? [];
+	}
+
+	/** Change this session's I/O modalities mid-session (e.g. enable/disable
+	 *  `voice`). The request is intersected with the token's granted modalities
+	 *  server-side — a session can't widen past its key — and the EFFECTIVE set is
+	 *  returned. Requires a live session. */
+	async setModalities(modalities: string[], opts?: { signal?: AbortSignal }): Promise<{ modalities: string[] }> {
+		const id = this.requireSession();
+		const res = await this.fetchAuthed(
+			this.url(`/api/companion/session/${encodeURIComponent(id)}/modalities`),
+			{
+				method: 'POST',
+				headers: {
+					Authorization: `Bearer ${this.opts.token}`,
+					'Content-Type': 'application/json'
+				},
+				body: JSON.stringify({ modalities }),
+				...(opts?.signal ? { signal: opts.signal } : {})
+			}
+		);
+		const json = (await res.json().catch(() => null)) as
+			| { ok?: boolean; error?: string; code?: string; modalities?: string[] }
+			| null;
+		if (!res.ok || !json || json.ok === false) {
+			throw new CompanionError(json?.error || `setModalities failed (${res.status})`, res.status, json?.code);
+		}
+		return { modalities: json.modalities ?? modalities };
+	}
+
+	/** Keepalive: bump this session's last-seen time so a long-idle embed stays
+	 *  "live" within the session TTL (cross-app A2A friend messages keep reaching
+	 *  it). Cheap; call it on a timer for a background tab. Requires a live session. */
+	async ping(opts?: { signal?: AbortSignal }): Promise<void> {
+		const id = this.requireSession();
+		const res = await this.fetchAuthed(
+			this.url(`/api/companion/session/${encodeURIComponent(id)}/ping`),
+			{
+				method: 'POST',
+				headers: { Authorization: `Bearer ${this.opts.token}` },
+				...(opts?.signal ? { signal: opts.signal } : {})
+			}
+		);
+		if (!res.ok) {
+			const json = (await res.json().catch(() => null)) as { error?: string; code?: string } | null;
+			throw new CompanionError(json?.error || `ping failed (${res.status})`, res.status, json?.code);
+		}
+	}
+
+	/** 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: {
+		content: string;
+		importance?: number;
+		confidence?: number;
+		/** Only these two are kept server-side — anything else is discarded, so
+		 *  the type refuses it at compile time instead of dropping it silently. */
+		category?: 'relationship' | 'shared_experience';
+		kind?: string;
+		namespace?: string;
+		sensitivity?: 'public' | 'personal';
+	}, opts?: { signal?: AbortSignal }): Promise<{ cloudId: string; namespace: string }> {
+		return this.postJson<{ cloudId: string; namespace: string }>('/api/companion/memory', fact, opts?.signal);
+	}
+
+	/** 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 —
+	 *  send your pchy_ token as the bearer; the relay is auth-gated and metered)
+	 *  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: {
+		text: string;
+		name: string;
+		kind?: string;
+		locale?: string;
+	}, opts?: { signal?: AbortSignal }): Promise<{ ok: boolean; summary: string; chunks: number }> {
+		return this.postJson<{ ok: boolean; summary: string; chunks: number }>(
+			'/api/companion/knowledge',
+			doc,
+			opts?.signal
+		);
+	}
+
+	/** 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: {
+		dataUrl: string;
+		name: string;
+		kind?: string;
+		locale?: string;
+	}, opts?: { signal?: AbortSignal }): Promise<{ ok: boolean; summary: string; chunks: number }> {
+		return this.postJson<{ ok: boolean; summary: string; chunks: number }>(
+			'/api/companion/knowledge/file',
+			file,
+			opts?.signal
+		);
+	}
+
+	/** 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(opts?: { signal?: AbortSignal }): Promise<CompanionAvatar> {
+		const res = await this.fetchAuthed(this.url('/api/companion/avatar'), {
+			headers: { Authorization: `Bearer ${this.opts.token}` },
+			...(opts?.signal ? { signal: opts.signal } : {})
+		});
+		const json = (await res.json().catch(() => null)) as
+			| ({ ok?: boolean; error?: string; code?: string } & Partial<CompanionAvatar>)
+			| null;
+		if (!res.ok || !json || json.ok === false) {
+			throw new CompanionError(json?.error || `avatar fetch failed (${res.status})`, res.status, json?.code);
+		}
+		return {
+			name: json.name ?? null,
+			archetype: json.archetype ?? 'girlfriend',
+			modelId: json.modelId ?? null,
+			vrmUrl: json.vrmUrl ?? null,
+			imageUrl: json.imageUrl ?? null
+		};
+	}
+
+	/** Read the companion instance's OWN wallet — nonzero stablecoin balances +
+	 *  total USD. Read-only and receive-only (spends go through the confirm-gated
+	 *  pay tools, never here). Requires the `wallet.read` scope (or `wallet.spend`,
+	 *  which subsumes it). Same data the companion gives when asked "what's my
+	 *  balance?". */
+	async getWallet(opts?: { signal?: AbortSignal }): Promise<CompanionWallet> {
+		const res = await this.fetchAuthed(this.url('/api/companion/wallet'), {
+			headers: { Authorization: `Bearer ${this.opts.token}` },
+			...(opts?.signal ? { signal: opts.signal } : {})
+		});
+		const json = (await res.json().catch(() => null)) as
+			| ({ ok?: boolean; error?: string; code?: string } & Partial<CompanionWallet>)
+			| null;
+		if (!res.ok || !json || json.ok === false) {
+			throw new CompanionError(json?.error || `wallet fetch failed (${res.status})`, res.status, json?.code);
+		}
+		return {
+			balances: json.balances ?? [],
+			totalUsd: json.totalUsd ?? 0,
+			currency: json.currency ?? 'USD'
+		};
+	}
+
+	/** 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: BrandIconSize = 512): string {
+		return pouchyBrandIconUrl(this.opts.baseUrl, size);
+	}
+
+	/** Subscribe to outbound events of a given type, or "*" for all. Returns an
+	 *  unsubscribe function. Since 0.30.0 the envelope payload is NARROWED per
+	 *  event name (OutboundPayloadMap) — e.g. `on('companion.typing', (env) =>
+	 *  env.payload.active)` type-checks without a cast; `'*'` keeps the untyped
+	 *  envelope. Type-only: runtime behavior is unchanged. */
+	on<T extends OutboundType>(
+		type: T,
+		handler: (envelope: CompanionEnvelope<OutboundPayloadMap[T]>) => void
+	): () => void;
+	on(type: '*', handler: Handler): () => void;
+	on(type: OutboundType | '*', handler: Handler): () => void {
+		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: (text: string, envelope: CompanionEnvelope) => void): () => void {
+		return this.on('companion.message', (env) => {
+			const text = (env.payload as { text?: unknown })?.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: (payload: RenderInterfacePayload, envelope: CompanionEnvelope) => void
+	): () => void {
+		return this.on('companion.ui_action', (env) => {
+			const p = env.payload as RenderInterfacePayload;
+			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: (payload: AudioClipPayload, envelope: CompanionEnvelope) => void): () => void {
+		return this.on('companion.audio', (env) => {
+			const p = env.payload as AudioClipPayload;
+			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: (payload: ExpressionPayload, envelope: CompanionEnvelope) => void): () => void {
+		return this.on('companion.expression', (env) => handler(env.payload as ExpressionPayload, env));
+	}
+
+	/** Convenience: subscribe to the per-token metering echo (control.usage) for a
+	 *  usage / billing view. */
+	onUsage(handler: (payload: UsagePayload, envelope: CompanionEnvelope) => void): () => void {
+		return this.on('control.usage', (env) => handler(env.payload as UsagePayload, env));
+	}
+
+	/** Convenience: subscribe to 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.
+	 *
+	 *  Whether YOU can resolve it depends on the token:
+	 *  - **Platform session tokens** (minted via /v1/sessions for your end
+	 *    users): show your own confirm card and call `confirmAction` — your end
+	 *    user is the account's human, so the session may approve. This is how
+	 *    confirm-gated custom skills (POST / credentialed) run.
+	 *  - **First-party user tokens** (Login-with-Pouchy PATs): observe-only —
+	 *    approval is authed as the Pouchy user (their app / a hosted confirm
+	 *    page), which is also where the biometric (Face ID / passkey) gate
+	 *    lives. `confirmAction` returns 401 on these tokens. */
+	onConfirmRequest(
+		handler: (payload: ConfirmRequestPayload, envelope: CompanionEnvelope) => void
+	): () => void {
+		return this.on('companion.confirm_request', (env) => {
+			const p = env.payload as ConfirmRequestPayload;
+			if (p && typeof p === 'object' && typeof p.confirmId === 'string') handler(p, env);
+		});
+	}
+
+	/** Resolve a pending confirmation (platform session tokens only — see
+	 *  `onConfirmRequest`). Show the user what they're approving (the event's
+	 *  `summary`), collect an explicit tap, then pass their decision here. On
+	 *  approval the recorded action runs server-side; its result comes back as
+	 *  `outcome` in this response (render it where the user tapped) AND as a
+	 *  normal companion.message on the stream (so the conversation shows it).
+	 *  A denial returns/emits a brief decline the same way. Single-use:
+	 *  re-resolving a settled confirmId fails with 409.
+	 *
+	 *  RETRY: if an approved IDEMPOTENT action (a wallet payment) flakes on a
+	 *  transient error, `status` is `'exec_failed'` and `retryable` is true — you
+	 *  MAY call `confirmAction(sameConfirmId, true)` again to re-run it (the server
+	 *  dedupes a partial first attempt). A non-idempotent action (a message / skill)
+	 *  stays terminal and is never retryable. */
+	async confirmAction(
+		confirmId: string,
+		approve: boolean,
+		opts?: { signal?: AbortSignal }
+	): Promise<{
+		ok: boolean;
+		status: 'approved' | 'denied' | 'exec_failed';
+		outcome?: string;
+		retryable?: boolean;
+	}> {
+		const sessionId = this.requireSession();
+		return this.postJson<{
+			ok: boolean;
+			status: 'approved' | 'denied' | 'exec_failed';
+			outcome?: string;
+			retryable?: boolean;
+		}>(`/api/companion/session/${encodeURIComponent(sessionId)}/confirm`, { confirmId, approve }, opts?.signal);
+	}
+
+	/** The session's still-pending confirmations (display-safe: id, summary,
+	 *  scope, timestamps — never raw args). Use it to rebuild your confirm card
+	 *  after a reload, since confirm_request events are not replayed. Platform
+	 *  session tokens only, like `confirmAction`. */
+	async pendingConfirms(opts?: { signal?: AbortSignal }): Promise<PendingConfirm[]> {
+		const sessionId = this.requireSession();
+		const res = await this.fetchAuthed(
+			this.url(`/api/companion/session/${encodeURIComponent(sessionId)}/confirm`),
+			{
+				headers: { Authorization: `Bearer ${this.opts.token}` },
+				...(opts?.signal ? { signal: opts.signal } : {})
+			}
+		);
+		const json = (await res.json().catch(() => null)) as
+			| { ok?: boolean; error?: string; code?: string; pending?: PendingConfirm[] }
+			| null;
+		if (!res.ok || !json || json.ok === false) {
+			throw new CompanionError(json?.error || `pending confirms failed (${res.status})`, res.status, json?.code);
+		}
+		return json.pending ?? [];
+	}
+
+	/** 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: (payload: InterfaceUpdatePayload, envelope: CompanionEnvelope) => void
+	): () => void {
+		return this.on('companion.ui_update', (env) => {
+			const p = env.payload as InterfaceUpdatePayload;
+			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: (payload: SocialMessagePayload, envelope: CompanionEnvelope) => void
+	): () => void {
+		return this.on('companion.social_message', (env) => {
+			const p = env.payload as SocialMessagePayload;
+			if (p && typeof p === 'object' && typeof p.content === 'string') 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: (payload: TypingPayload, envelope: CompanionEnvelope) => void): () => void {
+		return this.on('companion.typing', (env) => {
+			const p = env.payload as TypingPayload;
+			if (p && typeof p === 'object' && typeof p.active === 'boolean') handler(p, env);
+		});
+	}
+
+	/** Convenience: subscribe to voice-inject cues (companion.voice_inject) — a
+	 *  `voiceRelevant` world-state line the companion should say aloud during a
+	 *  live call. Route `payload.text` to your active voice session when
+	 *  `payload.speak`. A text-only host can ignore it. */
+	onVoiceInject(
+		handler: (payload: VoiceInjectPayload, envelope: CompanionEnvelope) => void
+	): () => void {
+		return this.on('companion.voice_inject', (env) => {
+			const p = env.payload as VoiceInjectPayload;
+			if (p && typeof p === 'object' && typeof p.text === '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(): void {
+		if (this.streaming) return;
+		this.requireSession();
+		this.streaming = true;
+		this.setStreamState('connecting');
+		const gen = ++this.streamGen;
+		const wsImpl = this.opts.webSocketImpl ?? (globalThis as { WebSocket?: typeof WebSocket }).WebSocket;
+		if (this.opts.stream === 'websocket' && wsImpl) {
+			void this.wsLoop(wsImpl, gen);
+		} else {
+			void this.loop(gen);
+		}
+	}
+
+	/** 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. */
+	private async wsLoop(WS: typeof WebSocket, gen: number): Promise<void> {
+		const id = this.requireSession();
+		const { deriveWsStreamUrl, decodeWsMessage } = await import('./ws-transport');
+		// Reconnect across CLEAN closes (a WS gateway with a bounded lifetime, like
+		// the SSE endpoint's window) just as the SSE loop does — a graceful close
+		// must not silently end reply delivery. Only a connection ERROR degrades to
+		// SSE, and only once. Each connection's poll timer + socket are released in
+		// the settle() finally so neither leaks after fallback/reconnect.
+		let backoff = 500;
+		while (this.streaming && gen === this.streamGen) {
+			let errored = false;
+			const connectedAt = Date.now();
+			try {
+				await new Promise<void>((resolve, reject) => {
+					const ws = new WS(deriveWsStreamUrl(this.opts.baseUrl, id, this.opts.token, this.cursor));
+					let poll: ReturnType<typeof setInterval> | undefined;
+					let settled = false;
+					ws.onopen = () => {
+						if (this.streaming && gen === this.streamGen) this.setStreamState('connected');
+					};
+					const settle = (err?: unknown) => {
+						if (poll) {
+							clearInterval(poll);
+							poll = undefined;
+						}
+						try {
+							ws.close();
+						} catch {
+							/* already closing */
+						}
+						if (settled) return;
+						settled = true;
+						if (err) reject(err);
+						else resolve();
+					};
+					ws.onmessage = (ev: MessageEvent) => {
+						if (!this.streaming || gen !== this.streamGen) {
+							settle();
+							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 = () => settle(new Error('companion ws error'));
+					ws.onclose = () => settle();
+					// Stopping the stream closes the socket + clears this timer.
+					poll = setInterval(() => {
+						if (!this.streaming || gen !== this.streamGen) settle();
+					}, 250);
+				});
+			} catch {
+				errored = true;
+			}
+			if (errored) {
+				// Socket unavailable / rejected — degrade to the robust SSE loop (once).
+				// The SSE loop's healthy state then reads `degraded_sse`, so the host
+				// can observe the (previously invisible) WS→SSE degrade.
+				if (this.streaming && gen === this.streamGen) {
+					this.setStreamState('reconnecting');
+					await this.loop(gen, true);
+				}
+				return;
+			}
+			// Clean close: the while-guard reconnects if still streaming, else exits.
+			// A SHORT-LIVED connection (gateway that accepts then immediately
+			// closes — auth-as-close, LB idle policy, misconfigured proxy) must
+			// back off like the SSE loop, or this reconnects in a zero-delay hot
+			// loop. A connection that lived a while resets the backoff.
+			if (this.streaming && gen === this.streamGen) this.setStreamState('reconnecting');
+			if (Date.now() - connectedAt < 2000) {
+				await this.backoffSleep(backoff);
+				backoff = Math.min(backoff * 2, 8000);
+			} else {
+				backoff = 500;
+			}
+		}
+	}
+
+	/** Stop the event stream. */
+	stop(): void {
+		this.streaming = false;
+		this.streamGen++; // invalidate any loop still unwinding
+		this.abort?.abort();
+		this.abort = null;
+		this.setStreamState('stopped');
+	}
+
+	private emit(envelope: CompanionEnvelope): void {
+		// 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);
+			}
+		}
+		// Post-dedup: the debug channel sees each envelope exactly once, in
+		// delivery order — replays collapsed above never reach it.
+		this.dbg({ kind: 'envelope', at: Date.now(), type: envelope.type, id: envelope.id ?? '' });
+		// 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 as { id?: unknown; name?: unknown };
+			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;
+			}
+		}
+		// Each handler is isolated: a THROWING consumer handler must not skip the
+		// remaining handlers, and — worse — it used to propagate up through the
+		// stream loop's catch, which read it as a CONNECTION failure (backoff +
+		// reconnect + cursor replay); on the sendText local-emit path it rejected
+		// a sendText whose turn had actually succeeded.
+		for (const h of this.handlers.get(envelope.type) ?? []) {
+			try {
+				h(envelope);
+			} catch (e) {
+				console.error('[companion-sdk] event handler threw', e);
+			}
+		}
+		for (const h of this.handlers.get('*') ?? []) {
+			try {
+				h(envelope);
+			} catch (e) {
+				console.error('[companion-sdk] event handler threw', e);
+			}
+		}
+	}
+
+	private handleFrame(event: string, data: string): void {
+		if (event === 'reconnect') {
+			try {
+				const d = JSON.parse(data) as { cursor?: number };
+				if (typeof d.cursor === 'number') this.cursor = d.cursor;
+			} catch {
+				/* ignore */
+			}
+			return;
+		}
+		let env: CompanionEnvelope | null = null;
+		try {
+			env = JSON.parse(data) as CompanionEnvelope;
+		} catch {
+			return;
+		}
+		if (event === 'open') {
+			const rc = (env?.payload as { resumeCursor?: number })?.resumeCursor;
+			if (typeof rc === 'number') this.cursor = rc;
+			return;
+		}
+		if (env && typeof env.type === 'string') this.emit(env);
+	}
+
+	/** SSE receive loop. `degraded` marks that this loop is the WS transport's
+	 *  fallback, so its healthy state reads `degraded_sse` (still live) instead
+	 *  of `connected` — the host can tell "fine" from "fine, but on plan B". */
+	private async loop(gen: number, degraded = false): Promise<void> {
+		const id = this.requireSession();
+		let backoff = 500;
+		let authRefreshes = 0; // consecutive 401→refresh cycles without a healthy connect
+		while (this.streaming && gen === this.streamGen) {
+			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) {
+					// 401 = the token itself is bad — usually an EXPIRED session token
+					// (they live ~1h). With an onAuthError hook this is recoverable:
+					// refresh and reconnect instead of going permanently silent. The
+					// counter stops a hot loop when the hook keeps returning a token
+					// the server keeps rejecting.
+					if (res.status === 401 && authRefreshes < 3 && (await this.tryRefreshToken())) {
+						authRefreshes += 1;
+						continue;
+					}
+					// 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`
+						}
+					});
+					this.setStreamState('stopped');
+					break;
+				}
+				if (!res.ok || !res.body) {
+					if (!this.streaming || gen !== this.streamGen) break;
+					this.setStreamState('reconnecting');
+					await this.backoffSleep(backoff);
+					backoff = Math.min(backoff * 2, 8000);
+					continue;
+				}
+				backoff = 500; // healthy connection resets backoff
+				authRefreshes = 0;
+				this.setStreamState(degraded ? 'degraded_sse' : 'connected');
+				await this.consume(res.body, gen);
+			} catch {
+				if (!this.streaming || gen !== this.streamGen) break;
+				this.setStreamState('reconnecting');
+				await this.backoffSleep(backoff);
+				backoff = Math.min(backoff * 2, 8000);
+			}
+		}
+	}
+
+	private async consume(body: ReadableStream<Uint8Array>, gen: number): Promise<void> {
+		const reader = body.getReader();
+		const decoder = new TextDecoder();
+		let buf = '';
+		while (this.streaming && gen === this.streamGen) {
+			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);
+		}
+	}
+
+	private sleep(ms: number): Promise<void> {
+		return new Promise((res) => setTimeout(res, ms));
+	}
+
+	/** Backoff sleep with additive jitter (0–25%, 0.30.0) so a fleet of embeds
+	 *  doesn't reconnect in lockstep after a server deploy/restart (thundering
+	 *  herd) — every reconnect path sleeps through here, never bare sleep(). */
+	private backoffSleep(ms: number): Promise<void> {
+		return this.sleep(ms + Math.floor(Math.random() * ms * 0.25));
+	}
+}