@pouchy_ai/companion-sdk 0.34.0 → 0.36.0

package/src/call.ts

@@ -187,6 +187,24 @@ export interface CompanionCall {
 	/** Inject an out-of-band context line. `speak: true` makes the companion react
 	 *  now; false stages it for the next turn. */
 	injectEvent: (text: string, speak?: boolean) => void;
+	/** SILENT CUT (0.36.0): stop the utterance currently being spoken WITHOUT
+	 *  generating any new speech — the "stale commentary at a beat boundary"
+	 *  case (field request: fast-paced game, last hand's commentary still
+	 *  playing when the next hand starts). Idempotent: a no-op when nothing is
+	 *  playing, after close(), and mid-connect.
+	 *
+	 *  Provider tiers (check `provider`):
+	 *  - `openai-realtime` — GUARANTEED: cancels the active response and clears
+	 *    the WebRTC output buffer (`response.cancel` + `output_audio_buffer.clear`);
+	 *    playback stops within ~an audio frame. The session continues normally.
+	 *  - `elevenlabs-convai` — BEST-EFFORT: the EL client exposes no public
+	 *    "stop playback" API; we signal `user_activity` (halts the agent's
+	 *    stream when the agent's interruption handling allows) and attempt the
+	 *    client's internal output-buffer cut when the installed build exposes
+	 *    it. Verify on your rig; worst case it degrades to a no-op — for a
+	 *    guaranteed preemption on EL, `injectEvent(text, true)` (which DOES
+	 *    speak new content) remains the reliable lever. */
+	interrupt: () => void;
 	provider: CallCredentials['provider'];
 }
 
@@ -296,6 +314,12 @@ async function openOpenAICall(
 		}, MIC_UNMUTE_TAIL_MS);
 	};
 
+	// Whether the model is audibly speaking right now (driven by the
+	// output_audio_buffer events below). Gates interrupt(): cancelling with no
+	// active response makes the server emit a benign-but-noisy error event, so
+	// an idle interrupt() must be a true no-op.
+	let oaiSpeaking = false;
+
 	const dc = pc.createDataChannel('oai-events');
 	// `response.function_call_arguments.done` carries the call_id + args but often
 	// not the name — the name arrives earlier on `response.output_item.added`; track it.
@@ -396,6 +420,7 @@ async function openOpenAICall(
 		) {
 			opts.onTranscript?.({ role: 'user', text: msg.transcript });
 		} else if (msg.type === 'output_audio_buffer.started') {
+			oaiSpeaking = true;
 			opts.onSpeakingChange?.(true);
 			// Model started speaking → mute the mic so its own audio can't
 			// echo-transcribe into a self-barge-in. bargeIn opts out (B wave):
@@ -411,6 +436,7 @@ async function openOpenAICall(
 			// and re-open the mic after a short tail so the last bit of the model's
 			// audio doesn't get captured the instant we unmute. Several event names
 			// can end a turn; any of them re-arms the mic.
+			oaiSpeaking = false;
 			opts.onSpeakingChange?.(false);
 			if (opts.bargeIn !== true) scheduleMicUnmute();
 		}
@@ -548,6 +574,21 @@ async function openOpenAICall(
 				})
 			);
 			if (speak) dc.send(JSON.stringify({ type: 'response.create' }));
+		},
+		interrupt: () => {
+			// Silent cut: stop generating (response.cancel) AND flush what's
+			// already buffered for playback (output_audio_buffer.clear — the
+			// WebRTC-mode control for exactly this). Order matters: cancel first
+			// so no new audio lands behind the clear. The `.cleared` event echoes
+			// back through the handler above, which resets the speaking state and
+			// re-arms the mic like any natural end of turn.
+			if (closed || !oaiSpeaking || dc.readyState !== 'open') return;
+			try {
+				dc.send(JSON.stringify({ type: 'response.cancel' }));
+				dc.send(JSON.stringify({ type: 'output_audio_buffer.clear' }));
+			} catch {
+				/* channel gone — the call is tearing down anyway */
+			}
 		}
 	};
 }
@@ -583,6 +624,9 @@ async function openConvaiCall(
 	}
 
 	let closed = false;
+	// Whether the agent is audibly speaking (onModeChange) — gates interrupt()
+	// so an idle call stays a true no-op.
+	let elSpeaking = false;
 	// Half-duplex mic (mirrors the first-party path, #1524): mute while the agent
 	// speaks so its own voice can't echo-transcribe into a self-barge-in (the SDK
 	// voice "说一句就断了" report), re-open after a short tail. Convai exposes
@@ -612,6 +656,7 @@ async function openConvaiCall(
 		onModeChange: ({ mode }: { mode: string }) => {
 			if (closed) return;
 			const speaking = mode === 'speaking';
+			elSpeaking = speaking;
 			opts.onSpeakingChange?.(speaking);
 			// bargeIn opts out of half-duplex (B wave): the mic stays open and
 			// ElevenLabs' native interruption handling takes over.
@@ -694,6 +739,31 @@ async function openConvaiCall(
 			} catch {
 				/* channel not ready */
 			}
+		},
+		interrupt: () => {
+			// BEST-EFFORT silent cut — the EL client has no public "stop playback"
+			// API (interruption is normally server-driven: a server `interruption`
+			// event → the client's internal OutputController.interrupt()). Two
+			// guarded levers, both no-ops when unavailable:
+			// 1. user_activity: tells the agent the user is acting; with the
+			//    agent's interruption handling enabled the server halts the
+			//    current utterance WITHOUT generating a reply (unlike
+			//    sendUserMessage, which speaks new content).
+			// 2. The internal output cut, when the installed client build exposes
+			//    it — same guarded-internal doctrine as setMicMuted above.
+			if (closed || !elSpeaking) return;
+			try {
+				(conv as unknown as { sendUserActivity?: () => void }).sendUserActivity?.();
+			} catch {
+				/* not supported on this client build */
+			}
+			try {
+				(
+					conv as unknown as { output?: { interrupt?: (resetDurationMs?: number) => void } }
+				).output?.interrupt?.();
+			} catch {
+				/* internal shape changed — the user_activity lever above still applies */
+			}
 		}
 	};
 }

package/src/client.ts

@@ -122,6 +122,16 @@ export interface CompanionClientOptions {
 	 *  silently), else an in-memory page-lifetime store. The key is
 	 *  `pouchy-outbox:${surface}`, so each surface keeps its own queue. */
 	outboxStore?: OutboxStore;
+	/** Deadline for a request to produce RESPONSE HEADERS, in ms (0.35.0).
+	 *  Bounds every HTTP call the client makes (connect, sendText, recall, …) so
+	 *  a server that accepts the TCP connection but never answers can't hang a
+	 *  helper forever — previously only `sendText({ awaitReply })` had any
+	 *  deadline. Reading a response BODY (the SSE event stream, a streaming
+	 *  sendText reply) is never bounded by this — the timer is cleared the
+	 *  moment headers arrive. Composes with any per-call AbortSignal (whichever
+	 *  fires first wins); the timeout rejects as a status-0 CompanionError with
+	 *  code 'request_timeout'. Default 30_000; 0 disables. */
+	requestTimeoutMs?: number;
 }
 
 export interface HelloAck {
@@ -414,6 +424,10 @@ export class CompanionClient {
 	private readonly outboxHandlers = new Set<(items: readonly QueuedSend[]) => void>();
 	// In-flight flush, shared so concurrent triggers run ONE flush at a time.
 	private outboxFlush: Promise<{ sent: number; remaining: number }> | null = null;
+	/** Epoch-ms before which flush attempts are skipped — set from a 429's
+	 *  Retry-After during replay so the auto-flush on every reconnect doesn't
+	 *  re-hammer a server that just told us to back off (0.35.0). */
+	private outboxBlockedUntil = 0;
 
 	constructor(opts: CompanionClientOptions) {
 		if (!opts.baseUrl)
@@ -530,6 +544,48 @@ export class CompanionClient {
 		return major > 1 || (major === 1 && minor >= 1);
 	}
 
+	/** doFetch raced against the `requestTimeoutMs` HEADERS deadline (0.35.0).
+	 *  The deadline only bounds time-to-response-headers: it does NOT swap the
+	 *  request's AbortSignal, so a streaming response body stays tied to the
+	 *  caller's own signal, and the timer is cleared the moment the race
+	 *  settles. On timeout the helper rejects `request_timeout` (status 0) —
+	 *  code-bearing, so the offline queue's network-failure predicate correctly
+	 *  ignores it (the server may have received the request). The abandoned
+	 *  fetch keeps its rejection silenced so a late network error can't surface
+	 *  as an unhandled rejection. */
+	private async doFetchBounded(
+		url: string,
+		init: RequestInit & { headers: Record<string, string> }
+	): Promise<Response> {
+		const budget = this.opts.requestTimeoutMs ?? 30_000;
+		if (!budget) return this.doFetch(url, init);
+		const req = this.doFetch(url, init);
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		try {
+			return await Promise.race([
+				req,
+				new Promise<never>((_, reject) => {
+					timer = setTimeout(
+						() =>
+							reject(
+								new CompanionError(
+									`request timed out after ${budget}ms waiting for response headers`,
+									0,
+									'request_timeout'
+								)
+							),
+						budget
+					);
+				})
+			]);
+		} catch (e) {
+			req.catch(() => {});
+			throw e;
+		} finally {
+			if (timer !== undefined) clearTimeout(timer);
+		}
+	}
+
 	private async fetchAuthed(
 		url: string,
 		init: RequestInit & { headers: Record<string, string> }
@@ -540,7 +596,7 @@ export class CompanionClient {
 		this.dbg({ kind: 'request', at: startedAt, method, path });
 		let res: Response;
 		try {
-			res = await this.doFetch(url, init);
+			res = await this.doFetchBounded(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
@@ -570,7 +626,7 @@ export class CompanionClient {
 		const retryAt = Date.now();
 		this.dbg({ kind: 'request', at: retryAt, method, path });
 		try {
-			const retryRes = await this.doFetch(url, init);
+			const retryRes = await this.doFetchBounded(url, init);
 			this.dbg({
 				kind: 'response',
 				at: Date.now(),
@@ -856,6 +912,12 @@ export class CompanionClient {
 		turnId?: string
 	): Promise<SendTextReply> {
 		const timeoutMs = opts?.replyTimeoutMs ?? 60_000;
+		// Already-aborted fast-fail comes FIRST (0.35.0): it used to sit after the
+		// companion.message subscription below, whose cleanup lives in the finally
+		// of the try we never entered — every call with a spent signal leaked one
+		// permanent handler (a host reusing one AbortController across turns
+		// accumulated them without bound).
+		if (opts?.signal?.aborted) throw new CompanionError('request aborted', 0, 'aborted');
 		let resolveFallback!: (env: CompanionEnvelope) => void;
 		const fallback = new Promise<CompanionEnvelope>((res) => (resolveFallback = res));
 		// Correlate: resolve only on THIS turn's reply (`replyTo === turnId`).
@@ -874,10 +936,9 @@ export class CompanionClient {
 		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.
+		// the deadline does.
 		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 });
 		}
@@ -1066,7 +1127,14 @@ export class CompanionClient {
 			} catch {
 				/* stream already finished */
 			}
-			throw e;
+			// Normalize (0.35.0): a mid-stream network drop rejects reader.read()
+			// with a NATIVE TypeError. Rethrowing it raw broke the "every helper
+			// rejects with CompanionError" contract AND slipped past the offline
+			// queue's isNetworkSendFailure (which requires a code-less status-0
+			// CompanionError) — the exact loss queueOffline exists to prevent.
+			// Queueing the replay is safe: it reuses the ORIGINAL turnId and the
+			// server dedupes completed turns, so a turn that did run isn't re-run.
+			throw this.asCompanionError(e);
 		}
 	}
 
@@ -1152,6 +1220,10 @@ export class CompanionClient {
 	private async runOutboxFlush(): Promise<{ sent: number; remaining: number }> {
 		const id = this.requireSession();
 		const items = this.loadOutbox();
+		// Respect the last replay 429's Retry-After (0.35.0): the flush re-arms
+		// on EVERY stream reconnect, so without this gate a rate-limited server
+		// got re-hammered on each reconnect despite naming its own window.
+		if (Date.now() < this.outboxBlockedUntil) return { sent: 0, remaining: items.length };
 		let sent = 0;
 		while (items.length) {
 			const item = items[0];
@@ -1173,6 +1245,10 @@ export class CompanionClient {
 					this.commitOutbox();
 					continue;
 				}
+				// A throttle names its own retry window — honor it across flushes.
+				if (status === 429 && e instanceof CompanionError && typeof e.retryAfter === 'number') {
+					this.outboxBlockedUntil = Date.now() + e.retryAfter * 1000;
+				}
 				// Unreachable again (or throttled / a server-side failure): keep
 				// this item and everything behind it for the next flush.
 				break;
@@ -1513,7 +1589,10 @@ export class CompanionClient {
 	 *  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. */
+	 *  autocompletes. A malformed frame with no string `code` is delivered with
+	 *  the literal fallback `'error'` (not part of the exported vocabulary) —
+	 *  give your `switch` a `default:` arm rather than enumerating every code.
+	 *  Returns an unsubscribe fn. */
 	onError(
 		handler: (
 			err: { code: ControlErrorCodeValue; message: string },
@@ -1970,13 +2049,19 @@ export class CompanionClient {
 		let backoff = 500;
 		while (this.streaming && gen === this.streamGen) {
 			let errored = false;
-			const connectedAt = Date.now();
+			// Stamped in onopen (0.35.0) — measuring from before the constructor
+			// counted DNS/TCP/handshake time as "connection lifetime", so a gateway
+			// that took ~2s to accept and then instantly closed read as long-lived
+			// and RESET the backoff (a near-hot reconnect loop). 0 = never opened,
+			// which always backs off.
+			let openedAt = 0;
 			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 = () => {
+						openedAt = Date.now();
 						if (this.streaming && gen === this.streamGen) this.setStreamState('connected');
 					};
 					const settle = (err?: unknown) => {
@@ -2029,7 +2114,7 @@ export class CompanionClient {
 			// 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) {
+			if (openedAt === 0 || Date.now() - openedAt < 2000) {
 				await this.backoffSleep(backoff);
 				backoff = Math.min(backoff * 2, 8000);
 			} else {
@@ -2194,13 +2279,33 @@ export class CompanionClient {
 		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);
+		// Liveness watchdog (0.35.0). The server writes a `: ping` comment every
+		// ~1.5s and closes each stream window at 45s — a healthy connection is
+		// NEVER byte-silent for long. On a silent half-open TCP drop (NAT/LB
+		// idle-kill, laptop sleep) no FIN ever arrives: reader.read() blocks for
+		// minutes while streamState still reads 'connected' and every reply is
+		// silently lost. 10× the ping interval without a single byte can only be
+		// a dead connection — cancel the reader so read() returns and the loop
+		// reconnects through its normal backoff + cursor resume (replays dedupe
+		// by envelope id). Only the SSE plane gets this: the WS plane has no
+		// heartbeat contract, so an idle-but-healthy socket can't be told apart.
+		const SSE_STALL_MS = 15_000;
+		let lastByteAt = Date.now();
+		const watchdog = setInterval(() => {
+			if (Date.now() - lastByteAt > SSE_STALL_MS) void reader.cancel().catch(() => {});
+		}, 5_000);
+		try {
+			while (this.streaming && gen === this.streamGen) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				lastByteAt = Date.now();
+				buf += decoder.decode(value, { stream: true });
+				const { events, rest } = parseSse(buf);
+				buf = rest;
+				for (const ev of events) this.handleFrame(ev.event, ev.data);
+			}
+		} finally {
+			clearInterval(watchdog);
 		}
 	}
 

package/src/errors.ts

@@ -21,7 +21,8 @@ export const SDK_SYNTHESIZED_ERROR_CODES = [
 	'call_connect_failed', // WebRTC/provider handshake failed
 	'call_dependency_missing', // optional voice dependency not installed
 	'aborted', // a caller-supplied AbortSignal cancelled the request (0.29.0)
-	'queued_offline' // queueOffline: the text was queued while offline and will send on reconnect (0.34.0)
+	'queued_offline', // queueOffline: the text was queued while offline and will send on reconnect (0.34.0)
+	'request_timeout' // requestTimeoutMs elapsed before response headers arrived (0.35.0)
 ] as const;
 export type SdkSynthesizedErrorCode = (typeof SDK_SYNTHESIZED_ERROR_CODES)[number];