@burdenoff/fe-libs 2026.1013.12 → 2026.1013.14

package/dist/shared/assistant/avatar/live/avatarPcm16.js

@@ -0,0 +1,54 @@
+import { PcmFormatError as e } from "./avatarAudioErrors.js";
+//#region src/shared/assistant/avatar/live/avatarPcm16.ts
+var t = 16e3, n = 2;
+function r(e) {
+	let t = new Int16Array(e.length);
+	for (let n = 0; n < e.length; n += 1) {
+		let r = e[n] ?? 0;
+		Number.isNaN(r) ? t[n] = 0 : r >= 1 ? t[n] = 32767 : r <= -1 ? t[n] = -32768 : t[n] = Math.round(r < 0 ? r * 32768 : r * 32767);
+	}
+	return t;
+}
+function i(e) {
+	let t = new Uint8Array(e.length * 2), n = new DataView(t.buffer);
+	for (let t = 0; t < e.length; t += 1) n.setInt16(t * 2, e[t] ?? 0, !0);
+	return t;
+}
+function a(e) {
+	return i(r(e));
+}
+function o(e) {
+	s(e);
+	let t = new Int16Array(e.length / 2), n = new DataView(e.buffer, e.byteOffset, e.byteLength);
+	for (let e = 0; e < t.length; e += 1) t[e] = n.getInt16(e * 2, !0);
+	return t;
+}
+function s(t) {
+	if (t.byteLength % 2 != 0) throw new e(`PCM16 byte length must be even, got ${t.byteLength}`);
+}
+function c(n, r = t) {
+	let i = typeof n == "number" ? n : n.byteLength;
+	if (!Number.isFinite(i) || i < 0 || i % 2 != 0) throw new e(`PCM16 byte length must be a non-negative even number, got ${i}`);
+	if (!(r > 0)) throw new e(`sample rate must be positive, got ${r}`);
+	return i / 2 / r;
+}
+function l(n, r = t) {
+	if (!Number.isFinite(n) || n <= 0) throw new e(`chunk duration must be positive, got ${n}`);
+	return Math.max(1, Math.round(r * n / 1e3));
+}
+function u(e, n, r = t) {
+	s(e);
+	let i = l(n, r) * 2, a = [];
+	for (let t = 0; t < e.byteLength; t += i) a.push(e.subarray(t, Math.min(e.byteLength, t + i)));
+	return a;
+}
+function d(e) {
+	let t = e[0];
+	if (!t) return new Float32Array();
+	if (e.length === 1) return t.slice();
+	let n = new Float32Array(t.length), r = 1 / e.length;
+	for (let t of e) for (let e = 0; e < n.length; e += 1) n[e] = (n[e] ?? 0) + (t[e] ?? 0) * r;
+	return n;
+}
+//#endregion
+export { t as AVATAR_SAMPLE_RATE, n as PCM16_BYTES_PER_SAMPLE, o as bytesToInt16LE, u as chunkPcm16, d as downmixToMono, r as floatToInt16, a as floatToPcm16Bytes, i as int16ToBytesLE, c as pcm16DurationOf, l as pcm16SamplesPerChunk };

package/dist/shared/assistant/avatar/live/avatarPlaybackTracker.d.ts

@@ -0,0 +1,181 @@
+import { AvatarScheduler } from './avatarPorts';
+export interface AvatarTrackerConfig {
+    /** After the provider says "started" (or none arrived), how long to wait for the meter to hear audio. */
+    readonly audibleGraceMs: number;
+    /** Time allowed between the first write and audible playback. */
+    readonly startLatencyAllowanceMs: number;
+    /** Fixed slack added to the expected duration before "no finish" is declared. */
+    readonly finishSlackMs: number;
+    /** Extra slack proportional to the expected duration. */
+    readonly finishSlackRatio: number;
+    /** How long to wait after the provider's finished before onEnd (jitter buffer and output latency). */
+    readonly tailMs: number;
+    /**
+     * While the meter still hears audio after finished, extend the tail by at most this much. Still heard then: the output is silenced
+     * before the reply is reported ended (the "completed" outcome's `mutedAtEnd`).
+     */
+    readonly maxTailExtraMs: number;
+    /** Provider position may undershoot the expected duration by this much (or 5 percent) before it is "early". */
+    readonly positionToleranceSec: number;
+    /** Meter quiet this long, after the expected end, without a provider finish: declare uncertain early. */
+    readonly quietGraceMs: number;
+    /** false when no meter can be built (then meter-based checks are skipped, never assumed). */
+    readonly meterSupported: boolean;
+}
+export declare const DEFAULT_AVATAR_TRACKER_CONFIG: AvatarTrackerConfig;
+export type AvatarFailureCause = 'not-allowed' | 'unsupported' | 'unknown';
+export type AvatarUncertainReason = 'no-finish' | 'no-finish-quiet' | 'early-finish' | 'provider-interrupted' | 'bad-payload' | 'avatar-left' | 'disconnected' | 'silent-playback' | 'stall' | 'synth-failed'
+/** The avatar reported playing part of a reply we were about to retry: something may have been heard, so it is not replayed. */
+ | 'played-before-retry';
+export type AvatarBeforeAudioReason = 
+/** The avatar still refuses our stream (its answer to our clear was "reject" or "method not supported"). */
+'not-accepted' | 'not-ready' | 'audio-blocked' | 'avatar-left' | 'disconnected' | 'stall' | 'synth-failed' | 'stream-error'
+/** We wrote audio, but neither the provider nor the meter showed any playback in time: the avatar is not responding. */
+ | 'no-start';
+export type AvatarReplyOutcome = 
+/**
+ * The provider reported the reply played out. `mutedAtEnd`: a meter that can hear still heard audio when the tail wait after that report
+ * ran out (tailMs plus maxTailExtraMs), so the output was silenced (stopOutput) BEFORE onEnd. The report claims only what the provider
+ * confirmed, that the reply played out; it does not claim that its audio ended by itself, since that end was cut, not heard.
+ */
+{
+    readonly kind: 'completed';
+    readonly mutedAtEnd?: true;
+} | {
+    readonly kind: 'cancelled';
+}
+/** Nothing was heard: safe to speak the same reply with the normal voice. */
+ | {
+    readonly kind: 'failed-before-audio';
+    readonly reason: AvatarBeforeAudioReason;
+    readonly cause: AvatarFailureCause;
+}
+/** Something may have been heard: never replay automatically; show an interrupted/unavailable state. */
+ | {
+    readonly kind: 'uncertain';
+    readonly reason: AvatarUncertainReason;
+    readonly heardAudio: boolean;
+    readonly cause: AvatarFailureCause;
+}
+/**
+ * Nothing of this reply was written: the avatar's EARLIER output could not be established as stopped (operator decision 7, 2026-10-09).
+ * While that output may still play, the reply must not start anywhere: no voice fallback, no retry. It ends as an error.
+ */
+ | {
+    readonly kind: 'output-not-cleared';
+};
+export interface AvatarTrackerCallbacks {
+    onStart(): void;
+    onChunkStart(index: number): void;
+    onEnd(): void;
+    /**
+     * Stop delivery, silence the output and request the provider clear. Called BEFORE any failure/uncertain outcome is reported, and before a
+     * completion whose audible end was cut (`mutedAtEnd`). `overdue`: the tracker stops because the provider's start or finish did not come
+     * in time (see isAvatarReportOverdue); a report of this reply that still arrives is presumed lost.
+     */
+    stopOutput(overdue: boolean): void;
+    onOutcome(outcome: AvatarReplyOutcome): void;
+}
+/**
+ * The verdicts that mean the provider's report of the reply did not come in time: no start (nothing heard or signalled within the start
+ * allowance and the audible grace), or no finish (by the finish deadline, or quiet long after the expected end). A report that still arrives
+ * after such a verdict is presumed lost (see AvatarClearOptions.finishOverdue in avatarTransport.ts).
+ */
+export declare function isAvatarReportOverdue(reason: AvatarUncertainReason | AvatarBeforeAudioReason): boolean;
+export declare class ReplyPlaybackTracker {
+    private readonly callbacks;
+    private readonly scheduler;
+    private readonly config;
+    private done;
+    /** The provider confirmed completion: only the tail wait remains; failures and safety nets no longer apply. */
+    private finishing;
+    private firstWriteAt;
+    /** A write completed: bytes really left for the avatar. */
+    private deliveredAt;
+    private startedAt;
+    private streamClosedAt;
+    private expectedTotalSec;
+    private readonly durations;
+    private lastChunkStart;
+    private meterAudible;
+    private meterEverAudible;
+    /**
+     * The meter still heard audio when this reply began writing: an earlier reply's tail, which it cannot tell apart from ours. From then
+     * on it is ignored for this reply, exactly as if there were none: it neither starts the reply nor proves it silent.
+     */
+    private meterIgnored;
+    /** When the meter first heard audio after our first write. */
+    private firstAudibleAt;
+    private lastAudibleAt;
+    private heardByRpc;
+    /** The bound on an unproven start (see firstWrite), until streamEnding arms the reply's own deadline. */
+    private cancelStartWait;
+    private readonly cancels;
+    constructor(callbacks: AvatarTrackerCallbacks, scheduler: AvatarScheduler, config?: AvatarTrackerConfig);
+    get isDone(): boolean;
+    get heard(): boolean;
+    /**
+     * Nothing of this reply can have been heard so far, by the same proof a failure uses (see provablySilent). Read-only, added for the
+     * avatar output (BOFF-8822 P8): when the person switches the avatar off mid-reply, a reply that provably played nothing hands every
+     * piece to the speakers, and one that may have been heard hands over only the pieces that cannot have begun.
+     */
+    get nothingHeard(): boolean;
+    /**
+     * The avatar's start latency as this reply measured it: from the first write until the meter first heard audio (the meter's attack and the
+     * audio's own leading silence included). Null until then, and for a reply whose meter is ignored (see meterIgnored).
+     */
+    get audibleAfterMs(): number | null;
+    /** The meter's evidence counts for this reply: there is one that can hear, and it was not still hearing earlier audio when we began. */
+    private get meterUsable();
+    firstWrite(): void;
+    /** A write completed (call after awaiting it). From now on silence must be PROVEN before a reply may go to the voice. */
+    delivered(): void;
+    chunkReady(index: number, durationSec: number): void;
+    /**
+     * Call BEFORE awaiting segment.close(): the provider can report finished before the close promise resolves,
+     * and a finished that arrives while the stream still looks open would be misread as an early finish.
+     */
+    streamEnding(totalDurationSec: number): void;
+    providerStarted(): void;
+    /** Provisional: a level meter on the avatar's received audio. Never used to report completion. */
+    meter(audible: boolean): void;
+    providerFinished(positionSec: number | null, interrupted: boolean | null): void;
+    avatarLeft(): void;
+    disconnected(): void;
+    audioBlocked(): void;
+    /** The next chunk did not arrive in time. */
+    stalled(): void;
+    /** Synthesis or the stream failed. */
+    failed(reason: 'synth-failed' | 'stream-error' | 'not-ready' | 'not-accepted', cause?: AvatarFailureCause): void;
+    /**
+     * Before this reply wrote anything: the avatar's earlier output could not be established as stopped, so the reply must not start (see
+     * the "output-not-cleared" outcome).
+     */
+    outputNotCleared(): void;
+    cancel(): void;
+    /**
+     * How long the provider gets to finish `durationSec` of audio once it was handed over: the start allowance, the audio itself, and the
+     * fixed and proportional finish slack. The one budget for streamEnding's deadline and for an unproven start (see firstWrite).
+     */
+    private noFinishBudgetMs;
+    /** The audio of every piece announced so far (chunkReady), in seconds: at the first write, the piece being written. */
+    private handedSec;
+    /**
+     * Nothing can have been heard: nothing reached the avatar, or a meter that can really hear stayed silent and the provider signalled nothing.
+     * Without that proof a failure is reported as uncertain, so the voice never repeats speech the user may have heard.
+     */
+    private provablySilent;
+    private failOrUncertain;
+    private markStarted;
+    private emitChunkStart;
+    private scheduleChunkStart;
+    private finishAfterTail;
+    /** After the expected end, a quiet meter and no finish from the provider means we cannot confirm completion. */
+    private pollQuiet;
+    private becomeUncertain;
+    private becomeFailedBeforeAudio;
+    /** Runs `fn` after `ms` unless the reply ends first; returns a function that cancels it sooner. */
+    private later;
+    private finish;
+    private clearTimers;
+}

package/dist/shared/assistant/avatar/live/avatarPlaybackTracker.js

@@ -0,0 +1,221 @@
+//#region src/shared/assistant/avatar/live/avatarPlaybackTracker.ts
+var e = {
+	audibleGraceMs: 3e3,
+	startLatencyAllowanceMs: 3e3,
+	finishSlackMs: 3e3,
+	finishSlackRatio: .25,
+	tailMs: 350,
+	maxTailExtraMs: 1e3,
+	positionToleranceSec: .5,
+	quietGraceMs: 2e3,
+	meterSupported: !0
+};
+function t(e) {
+	return e === "no-start" || e === "no-finish" || e === "no-finish-quiet";
+}
+var n = class {
+	callbacks;
+	scheduler;
+	config;
+	done = !1;
+	finishing = !1;
+	firstWriteAt = null;
+	deliveredAt = null;
+	startedAt = null;
+	streamClosedAt = null;
+	expectedTotalSec = null;
+	durations = [];
+	lastChunkStart = -1;
+	meterAudible = !1;
+	meterEverAudible = !1;
+	meterIgnored = !1;
+	firstAudibleAt = null;
+	lastAudibleAt = null;
+	heardByRpc = !1;
+	cancelStartWait = null;
+	cancels = /* @__PURE__ */ new Set();
+	constructor(t, n, r = e) {
+		this.callbacks = t, this.scheduler = n, this.config = r;
+	}
+	get isDone() {
+		return this.done;
+	}
+	get heard() {
+		return this.startedAt !== null;
+	}
+	get nothingHeard() {
+		return this.provablySilent();
+	}
+	get audibleAfterMs() {
+		return this.firstAudibleAt === null || this.firstWriteAt === null ? null : this.firstAudibleAt - this.firstWriteAt;
+	}
+	get meterUsable() {
+		return this.config.meterSupported && !this.meterIgnored;
+	}
+	firstWrite() {
+		if (!(this.done || this.firstWriteAt !== null)) {
+			if (this.firstWriteAt = this.scheduler.now(), this.meterAudible &&= (this.meterIgnored = !0, !1), this.meterUsable) {
+				this.later(this.config.startLatencyAllowanceMs + this.config.audibleGraceMs, () => {
+					this.startedAt === null && this.becomeFailedBeforeAudio("no-start", "unknown");
+				});
+				return;
+			}
+			this.cancelStartWait = this.later(this.noFinishBudgetMs(this.handedSec()), () => {
+				this.startedAt === null && this.becomeUncertain("no-finish");
+			});
+		}
+	}
+	delivered() {
+		this.done || this.deliveredAt !== null || (this.deliveredAt = this.scheduler.now());
+	}
+	chunkReady(e, t) {
+		this.done || (this.durations[e] = t, this.startedAt !== null && this.scheduleChunkStart(e));
+	}
+	streamEnding(e) {
+		this.done || this.streamClosedAt !== null || (this.streamClosedAt = this.scheduler.now(), this.expectedTotalSec = e, this.cancelStartWait?.(), this.cancelStartWait = null, this.later(this.noFinishBudgetMs(e), () => {
+			this.meterUsable && this.startedAt === null && !this.meterEverAudible ? this.becomeFailedBeforeAudio("no-start", "unknown") : this.becomeUncertain("no-finish");
+		}), this.pollQuiet());
+	}
+	providerStarted() {
+		this.done || this.firstWriteAt === null || (this.heardByRpc = !0, this.markStarted("rpc"));
+	}
+	meter(e) {
+		this.done || this.meterIgnored || (this.meterAudible = e, e && this.firstWriteAt !== null && (this.meterEverAudible = !0, this.lastAudibleAt = this.scheduler.now(), this.firstAudibleAt ??= this.lastAudibleAt, this.markStarted("meter")));
+	}
+	providerFinished(e, t) {
+		if (!this.done) {
+			if (e === null || t === null) return this.becomeUncertain("bad-payload");
+			if (t) return this.becomeUncertain("provider-interrupted");
+			if (this.streamClosedAt === null || this.expectedTotalSec === null || e + Math.max(this.config.positionToleranceSec, .05 * this.expectedTotalSec) < this.expectedTotalSec) return this.becomeUncertain("early-finish");
+			this.markStarted("finish"), this.finishing = !0, this.clearTimers(), this.finishAfterTail();
+		}
+	}
+	avatarLeft() {
+		this.failOrUncertain("avatar-left");
+	}
+	disconnected() {
+		this.failOrUncertain("disconnected");
+	}
+	audioBlocked() {
+		if (!this.done) {
+			if (this.startedAt === null) return this.becomeFailedBeforeAudio("audio-blocked", "unknown");
+			this.becomeUncertain("silent-playback");
+		}
+	}
+	stalled() {
+		this.failOrUncertain("stall");
+	}
+	failed(e, t = "unknown") {
+		if (!this.done) {
+			if (this.provablySilent()) return this.becomeFailedBeforeAudio(e, t);
+			this.becomeUncertain(e === "synth-failed" ? "synth-failed" : "stall", t);
+		}
+	}
+	outputNotCleared() {
+		this.done || (this.finish(), this.callbacks.stopOutput(!1), this.callbacks.onOutcome({ kind: "output-not-cleared" }));
+	}
+	cancel() {
+		this.done || (this.finish(), this.callbacks.stopOutput(!1), this.callbacks.onOutcome({ kind: "cancelled" }));
+	}
+	noFinishBudgetMs(e) {
+		let t = this.config.finishSlackMs + this.config.finishSlackRatio * e * 1e3;
+		return this.config.startLatencyAllowanceMs + e * 1e3 + t;
+	}
+	handedSec() {
+		return this.durations.reduce((e, t) => e + t, 0);
+	}
+	provablySilent() {
+		return this.startedAt !== null || this.heardByRpc || this.meterEverAudible ? !1 : this.deliveredAt === null ? !0 : this.meterUsable;
+	}
+	failOrUncertain(e) {
+		if (!(this.done || this.finishing)) {
+			if (this.provablySilent()) return this.becomeFailedBeforeAudio(e, "unknown");
+			this.becomeUncertain(e);
+		}
+	}
+	markStarted(e) {
+		if (!(this.done || this.startedAt !== null)) {
+			this.startedAt = this.scheduler.now(), this.emitChunkStart(0), this.callbacks.onStart();
+			for (let e = 1; e < this.durations.length; e += 1) this.scheduleChunkStart(e);
+			e === "rpc" && this.meterUsable && !this.meterEverAudible && this.later(this.config.audibleGraceMs, () => {
+				this.meterEverAudible || this.becomeUncertain("silent-playback");
+			});
+		}
+	}
+	emitChunkStart(e) {
+		this.done || e <= this.lastChunkStart || (this.lastChunkStart = e, this.callbacks.onChunkStart(e));
+	}
+	scheduleChunkStart(e) {
+		if (this.startedAt === null || e === 0 || this.durations[e] === void 0) return;
+		let t = 0;
+		for (let n = 0; n < e; n += 1) t += this.durations[n] ?? 0;
+		let n = this.startedAt + t * 1e3 - this.scheduler.now();
+		this.later(Math.max(0, n), () => this.emitChunkStart(e));
+	}
+	finishAfterTail() {
+		let e = this.scheduler.now(), t = () => {
+			if (this.done) return;
+			let n = this.scheduler.now() - e;
+			if (!(this.meterUsable && this.meterAudible)) {
+				this.finish(), this.callbacks.onEnd(), this.callbacks.onOutcome({ kind: "completed" });
+				return;
+			}
+			if (n >= this.config.tailMs + this.config.maxTailExtraMs) {
+				this.finish(), this.callbacks.stopOutput(!1), this.callbacks.onEnd(), this.callbacks.onOutcome({
+					kind: "completed",
+					mutedAtEnd: !0
+				});
+				return;
+			}
+			this.later(100, t);
+		};
+		this.later(this.config.tailMs, t);
+	}
+	pollQuiet() {
+		if (this.done || !this.meterUsable) return;
+		let e = () => {
+			if (this.done) return;
+			let t = this.scheduler.now(), n = (this.startedAt ?? (this.firstWriteAt ?? t) + this.config.startLatencyAllowanceMs) + (this.expectedTotalSec ?? 0) * 1e3, r = this.meterAudible ? 0 : t - (this.lastAudibleAt ?? this.firstWriteAt ?? t);
+			if (this.startedAt !== null && t >= n && r >= this.config.quietGraceMs) {
+				this.becomeUncertain("no-finish-quiet");
+				return;
+			}
+			this.later(250, e);
+		};
+		this.later(250, e);
+	}
+	becomeUncertain(e, n = "unknown") {
+		if (this.done || this.finishing) return;
+		let r = this.startedAt !== null || this.heardByRpc || this.meterEverAudible;
+		this.finish(), this.callbacks.stopOutput(t(e)), this.callbacks.onOutcome({
+			kind: "uncertain",
+			reason: e,
+			heardAudio: r,
+			cause: n
+		});
+	}
+	becomeFailedBeforeAudio(e, n) {
+		this.done || this.finishing || (this.finish(), this.callbacks.stopOutput(t(e)), this.callbacks.onOutcome({
+			kind: "failed-before-audio",
+			reason: e,
+			cause: n
+		}));
+	}
+	later(e, t) {
+		let n = this.scheduler.setTimeout(() => {
+			this.cancels.delete(n), t();
+		}, e);
+		return this.cancels.add(n), () => {
+			this.cancels.delete(n), n();
+		};
+	}
+	finish() {
+		this.done = !0, this.clearTimers();
+	}
+	clearTimers() {
+		for (let e of [...this.cancels]) e();
+		this.cancels.clear();
+	}
+};
+//#endregion
+export { e as DEFAULT_AVATAR_TRACKER_CONFIG, n as ReplyPlaybackTracker, t as isAvatarReportOverdue };

package/dist/shared/assistant/avatar/live/avatarPorts.d.ts

@@ -0,0 +1,66 @@
+export type AvatarUnsubscribe = () => void;
+export interface AvatarScheduler {
+    /** Milliseconds, monotonic. */
+    now(): number;
+    /** Returns a cancel function. */
+    setTimeout(fn: () => void, ms: number): () => void;
+}
+export declare const realAvatarScheduler: AvatarScheduler;
+/**
+ * @internal A fake clock for tests: timers only fire when advance() is called. Exported for the avatar suites (the assistant barrel
+ * star-exports this module); production code uses `realAvatarScheduler`.
+ */
+export declare class FakeAvatarScheduler implements AvatarScheduler {
+    private current;
+    private nextId;
+    private readonly timers;
+    now(): number;
+    setTimeout(fn: () => void, ms: number): () => void;
+    /** Advance time, firing due timers in order (timers scheduled while advancing are honoured). */
+    advance(ms: number): void;
+    pendingTimers(): number;
+}
+export interface AvatarByteWriter {
+    write(chunk: Uint8Array): Promise<void>;
+    close(): Promise<void>;
+}
+export interface AvatarRemoteTrack {
+    readonly identity: string;
+    readonly kind: 'audio' | 'video';
+    attach(element: HTMLMediaElement): void;
+    detach(): void;
+    /** The raw track for WebAudio metering; null when the platform does not expose it. */
+    readonly mediaStreamTrack: MediaStreamTrack | null;
+}
+export declare class AvatarRpcRejectedError extends Error {
+    constructor(message: string);
+}
+/** Everything the transport needs from a LiveKit room. */
+export interface AvatarRoom {
+    connect(url: string, token: string): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    hasParticipant(identity: string): boolean;
+    hasVideoTrack(identity: string): boolean;
+    onParticipantConnected(handler: (identity: string) => void): AvatarUnsubscribe;
+    onParticipantDisconnected(handler: (identity: string) => void): AvatarUnsubscribe;
+    onTrackSubscribed(handler: (track: AvatarRemoteTrack) => void): AvatarUnsubscribe;
+    onDisconnected(handler: () => void): AvatarUnsubscribe;
+    onReconnecting(handler: () => void): AvatarUnsubscribe;
+    onReconnected(handler: () => void): AvatarUnsubscribe;
+    onAudioPlaybackChanged(handler: (canPlay: boolean) => void): AvatarUnsubscribe;
+    /** The handler may throw AvatarRpcRejectedError to reject the call. Returns the response payload. */
+    registerRpc(method: string, handler: (callerIdentity: string, payload: string) => string): void;
+    unregisterRpc(method: string): void;
+    performRpc(destinationIdentity: string, method: string, payload: string, timeoutMs: number): Promise<string>;
+    openByteStream(options: {
+        topic: string;
+        name: string;
+        destinationIdentity: string;
+        attributes: Record<string, string>;
+    }): Promise<AvatarByteWriter>;
+    /** Resume audio playback after a user gesture. */
+    startAudio(): Promise<void>;
+    /** Whether the browser currently lets remote audio play (false until a user gesture while autoplay is blocked). */
+    canPlaybackAudio(): boolean;
+}

package/dist/shared/assistant/avatar/live/avatarPorts.js

@@ -0,0 +1,44 @@
+//#region src/shared/assistant/avatar/live/avatarPorts.ts
+var e = {
+	now: () => performance.now(),
+	setTimeout: (e, t) => {
+		let n = setTimeout(e, t);
+		return () => clearTimeout(n);
+	}
+}, t = class {
+	current = 0;
+	nextId = 1;
+	timers = /* @__PURE__ */ new Map();
+	now() {
+		return this.current;
+	}
+	setTimeout(e, t) {
+		let n = this.nextId++;
+		return this.timers.set(n, {
+			at: this.current + Math.max(0, t),
+			fn: e
+		}), () => {
+			this.timers.delete(n);
+		};
+	}
+	advance(e) {
+		let t = this.current + e;
+		for (;;) {
+			let e = null, n = Infinity;
+			for (let [r, i] of this.timers) i.at <= t && i.at < n && (n = i.at, e = r);
+			if (e === null) break;
+			let r = this.timers.get(e);
+			this.timers.delete(e), r && (this.current = Math.max(this.current, r.at), r.fn());
+		}
+		this.current = t;
+	}
+	pendingTimers() {
+		return this.timers.size;
+	}
+}, n = class extends Error {
+	constructor(e) {
+		super(e), this.name = "AvatarRpcRejectedError";
+	}
+};
+//#endregion
+export { n as AvatarRpcRejectedError, t as FakeAvatarScheduler, e as realAvatarScheduler };

package/dist/shared/assistant/avatar/live/avatarProtocol.d.ts

@@ -0,0 +1,22 @@
+export declare const AVATAR_AUDIO_STREAM_TOPIC = "lk.audio_stream";
+export declare const AVATAR_RPC_CLEAR_BUFFER = "lk.clear_buffer";
+export declare const AVATAR_RPC_PLAYBACK_FINISHED = "lk.playback_finished";
+export declare const AVATAR_RPC_PLAYBACK_STARTED = "lk.playback_started";
+export declare const AVATAR_PCM_SAMPLE_RATE = 16000;
+export declare const AVATAR_PCM_CHANNELS = 1;
+/** PCM16 mono at 16 kHz. */
+export declare const AVATAR_PCM_BYTES_PER_SECOND: number;
+/** The reference sender waits this long for playback_finished(interrupted) after clear_buffer. */
+export declare const AVATAR_CLEAR_BUFFER_TIMEOUT_MS = 2000;
+export declare function avatarPcmDurationSec(byteLength: number): number;
+/** Attributes the receiver REQUIRES on every audio byte stream (strings). */
+export declare function avatarSegmentAttributes(): Record<string, string>;
+export interface AvatarPlaybackFinishedPayload {
+    readonly positionSec: number;
+    readonly interrupted: boolean;
+}
+/**
+ * Parse the lk.playback_finished RPC payload. Returns null when it is not the
+ * documented shape: callers must treat that as "completion unknown", never as success.
+ */
+export declare function parseAvatarPlaybackFinished(payload: string): AvatarPlaybackFinishedPayload | null;

package/dist/shared/assistant/avatar/live/avatarProtocol.js

@@ -0,0 +1,27 @@
+//#region src/shared/assistant/avatar/live/avatarProtocol.ts
+var e = "lk.audio_stream", t = "lk.clear_buffer", n = "lk.playback_finished", r = "lk.playback_started", i = 16e3, a = 1, o = i * 1 * 2, s = 2e3;
+function c(e) {
+	return e / o;
+}
+function l() {
+	return {
+		sample_rate: String(i),
+		num_channels: "1"
+	};
+}
+function u(e) {
+	let t;
+	try {
+		t = JSON.parse(e);
+	} catch {
+		return null;
+	}
+	if (typeof t != "object" || !t) return null;
+	let n = t, r = n.playback_position, i = n.interrupted;
+	return typeof r != "number" || !Number.isFinite(r) || r < 0 || typeof i != "boolean" ? null : {
+		positionSec: r,
+		interrupted: i
+	};
+}
+//#endregion
+export { e as AVATAR_AUDIO_STREAM_TOPIC, s as AVATAR_CLEAR_BUFFER_TIMEOUT_MS, o as AVATAR_PCM_BYTES_PER_SECOND, a as AVATAR_PCM_CHANNELS, i as AVATAR_PCM_SAMPLE_RATE, t as AVATAR_RPC_CLEAR_BUFFER, n as AVATAR_RPC_PLAYBACK_FINISHED, r as AVATAR_RPC_PLAYBACK_STARTED, c as avatarPcmDurationSec, l as avatarSegmentAttributes, u as parseAvatarPlaybackFinished };