@burdenoff/fe-libs 2026.1013.13 → 2026.1014.1

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

@@ -0,0 +1,96 @@
+import { AvatarProblem } from '../useAvatarCopy';
+/** The gateway route; the base URL is the TTS endpoint's origin plus this. */
+export declare const AVATAR_API_PATH = "/api/avatar/v1";
+/**
+ * The avatar API's base URL from the hosted TTS endpoint the host configured, or null when it cannot be used (none configured, not a URL,
+ * credentials in it, or plain `http:` off a loopback host). A relative endpoint is resolved against `locationHref`.
+ */
+export declare function avatarApiBaseFromTtsEndpoint(ttsEndpoint: string | null | undefined, locationHref?: string): string | null;
+export interface AvatarAvailability {
+    readonly available: boolean;
+    /** Coarse on purpose (§3.3): no verified workspace reached the server, or the avatar is not enabled for this caller. */
+    readonly reason: 'workspace_context_required' | 'not_enabled' | null;
+    /** Approved and provider-ready ids; names and pictures are the client's. */
+    readonly avatars: readonly string[];
+    /** The disclosure version the client must show and echo back on create. */
+    readonly consentVersion: string;
+    /** The server's session cap, D. */
+    readonly maxSessionSeconds: number;
+}
+export interface AvatarSessionStart {
+    readonly sessionId: string;
+    readonly livekitUrl: string;
+    /** Joins one room, for connecting only: its expiry (`connectBy`) bounds the connect, not the session. */
+    readonly participantToken: string;
+    /** The avatar worker's identity in that room. */
+    readonly avatarIdentity: string;
+    /** Wall-clock milliseconds: the token cannot connect after this. */
+    readonly connectBy: number;
+    /** Wall-clock milliseconds: the server's hard end (create + D - 5 s). */
+    readonly endsAt: number;
+}
+export type AvatarSessionState = 'starting' | 'ready' | 'ending' | 'ended' | 'failed' | 'canceled';
+export interface AvatarSessionStatus {
+    readonly sessionId: string;
+    readonly state: AvatarSessionState;
+    /** Who or what ended it; never a claim that a reply was heard (P1c). */
+    readonly endedReason: string | null;
+}
+/** The reasons a client may give when it ends a session; analytics only (§3.3). */
+export type AvatarClientEndReason = 'user' | 'voice_end' | 'workspace_switch' | 'idle' | 'page_hide' | 'client_error';
+/** A non-2xx answer, a refused response shape, or no answer at all (`status` 0). */
+export declare class AvatarApiError extends Error {
+    readonly status: number;
+    /** The server's or the gateway's code, `invalid_response` for a body we refused, `network` for no answer. */
+    readonly code: string;
+    readonly retryAfterSeconds: number | null;
+    constructor(status: number, 
+    /** The server's or the gateway's code, `invalid_response` for a body we refused, `network` for no answer. */
+    code: string, retryAfterSeconds: number | null);
+}
+export interface AvatarSessionClientOptions {
+    /** `https://<gateway>/api/avatar/v1` (avatarApiBaseFromTtsEndpoint). */
+    readonly baseUrl: string;
+    /** The person's `Authorization` value (`Bearer …`), read at request time; null when signed out. */
+    readonly getAuthorization: () => string | null;
+    /**
+     * The workspace token as an `X-Workspace-Authorization` value (`Bearer …`), or null when none can be had. `fresh`: the gateway refused
+     * the last one, mint it again instead of reusing a stored one.
+     */
+    readonly getWorkspaceAuthorization: (options: {
+        readonly fresh: boolean;
+    }) => Promise<string | null>;
+    readonly fetchImpl?: typeof fetch;
+    /** Waits between the contract's retries; injectable for tests. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** How long 409 `start_in_progress` may be retried with the same key before giving up. */
+    readonly startInProgressBudgetMs?: number;
+}
+export interface AvatarSessionClient {
+    availability(signal?: AbortSignal): Promise<AvatarAvailability>;
+    create(input: {
+        readonly avatarId: string;
+        readonly consentVersion: string;
+        readonly idempotencyKey: string;
+    }, signal?: AbortSignal): Promise<AvatarSessionStart>;
+    status(sessionId: string, signal?: AbortSignal): Promise<AvatarSessionStatus>;
+    /** Ends one of the person's own sessions. `keepalive`: sent on page hide, best effort (it may not survive a CORS preflight). */
+    end(sessionId: string, options: {
+        readonly reason: AvatarClientEndReason;
+        readonly keepalive?: boolean;
+    }): Promise<AvatarSessionStatus>;
+}
+/** A UUID v4, from the platform when it has one. */
+export declare function avatarIdempotencyKey(random?: Crypto | undefined): string;
+export declare function createAvatarSessionClient(options: AvatarSessionClientOptions): AvatarSessionClient;
+/** What the avatar UI does with a refusal: what to tell the person, and whether to stop offering the toggle for this page. */
+export interface AvatarRefusal {
+    readonly problem: AvatarProblem;
+    /** The avatar is not offered here at all (404, 403 not allowed, no workspace): hide the toggle until the next page load. */
+    readonly hide: boolean;
+}
+/**
+ * The person's side of every failure (§3.4): the normal voice always continues; this says what to show. 404 means "not here" (the module
+ * or the route is off), 403 "not for you", 429/503 "not now".
+ */
+export declare function avatarRefusalFor(error: unknown): AvatarRefusal;

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

@@ -0,0 +1,261 @@
+//#region src/shared/assistant/avatar/live/avatarSessionClient.ts
+var e = "/api/avatar/v1", t = new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+]), n = /^avs_[0-9a-f]{32}$/, r = /^av_[a-z0-9_]{1,64}$/i, i = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function a(n, r) {
+	if (typeof n != "string" || n.trim() === "") return null;
+	let i;
+	try {
+		i = new URL(n.trim(), r);
+	} catch {
+		return null;
+	}
+	return i.username !== "" || i.password !== "" || i.protocol === "http:" && !t.has(i.hostname.toLowerCase()) || i.protocol !== "https:" && i.protocol !== "http:" ? null : `${i.protocol}//${i.host}${e}`;
+}
+var o = class extends Error {
+	status;
+	code;
+	retryAfterSeconds;
+	constructor(e, t, n) {
+		super(`avatar api ${e} ${t}`), this.status = e, this.code = t, this.retryAfterSeconds = n, this.name = "AvatarApiError";
+	}
+};
+function s(e = globalThis.crypto) {
+	if (e && typeof e.randomUUID == "function") return e.randomUUID();
+	let t = new Uint8Array(16);
+	if (e && typeof e.getRandomValues == "function") e.getRandomValues(t);
+	else throw Error("no secure random source for an Idempotency-Key");
+	t[6] = (t[6] ?? 0) & 15 | 64, t[8] = (t[8] ?? 0) & 63 | 128;
+	let n = [...t].map((e) => e.toString(16).padStart(2, "0")).join("");
+	return `${n.slice(0, 8)}-${n.slice(8, 12)}-${n.slice(12, 16)}-${n.slice(16, 20)}-${n.slice(20)}`;
+}
+function c(e) {
+	return typeof e == "object" && !!e && !Array.isArray(e);
+}
+function l(e, t) {
+	let n = e.headers.get("retry-after"), r = n === null || n.trim() === "" ? NaN : Number(n);
+	if (Number.isFinite(r) && r >= 0) return r;
+	let i = c(t) && c(t.error) ? Number(t.error.retryAfterSeconds) : NaN;
+	return Number.isFinite(i) && i >= 0 ? i : null;
+}
+async function u(e) {
+	try {
+		return await e.json();
+	} catch {
+		return null;
+	}
+}
+async function d(e) {
+	let t = await u(e), n = c(t) && c(t.error) && typeof t.error.code == "string" ? t.error.code : "http_error";
+	return new o(e.status, n, l(e, t));
+}
+function f(e) {
+	if (!c(e) || typeof e.available != "boolean") throw new o(200, "invalid_response", null);
+	let t = Array.isArray(e.avatars) ? e.avatars.flatMap((e) => c(e) && typeof e.id == "string" && r.test(e.id) ? [e.id] : []) : [], n = e.reason === "workspace_context_required" || e.reason === "not_enabled" ? e.reason : null, i = typeof e.consentVersion == "string" ? e.consentVersion : "", a = typeof e.maxSessionSeconds == "number" && Number.isFinite(e.maxSessionSeconds) ? e.maxSessionSeconds : 0, s = e.available && t.length > 0 && i !== "" && a > 0;
+	return {
+		available: s,
+		reason: s ? null : n ?? "not_enabled",
+		avatars: t,
+		consentVersion: i,
+		maxSessionSeconds: a
+	};
+}
+function p(e) {
+	try {
+		let n = new URL(e);
+		return n.protocol === "wss:" ? !0 : n.protocol === "ws:" && t.has(n.hostname.toLowerCase());
+	} catch {
+		return !1;
+	}
+}
+function m(e) {
+	if (!c(e)) throw new o(201, "invalid_response", null);
+	let { sessionId: t, livekitUrl: r, participantToken: i, avatarIdentity: a, connectBy: s, endsAt: l } = e, u = typeof s == "string" ? Date.parse(s) : NaN, d = typeof l == "string" ? Date.parse(l) : NaN;
+	if (typeof t != "string" || !n.test(t) || typeof r != "string" || !p(r) || typeof i != "string" || i === "" || typeof a != "string" || a === "" || !Number.isFinite(u) || !Number.isFinite(d)) throw new o(201, "invalid_response", null);
+	return {
+		sessionId: t,
+		livekitUrl: r,
+		participantToken: i,
+		avatarIdentity: a,
+		connectBy: u,
+		endsAt: d
+	};
+}
+var h = [
+	"starting",
+	"ready",
+	"ending",
+	"ended",
+	"failed",
+	"canceled"
+];
+function g(e, t) {
+	if (!c(e) || !h.includes(e.state)) throw new o(200, "invalid_response", null);
+	return {
+		sessionId: t,
+		state: e.state,
+		endedReason: typeof e.endedReason == "string" ? e.endedReason : null
+	};
+}
+var _ = (e) => new Promise((t) => {
+	setTimeout(t, e);
+});
+function v(e) {
+	let t = e.fetchImpl ?? ((e, t) => fetch(e, t)), a = e.sleep ?? _, s = e.startInProgressBudgetMs ?? 15e3, c = e.baseUrl.replace(/\/+$/, "");
+	async function l(t, n) {
+		let r = e.getAuthorization();
+		if (!r) throw new o(401, "unauthenticated", null);
+		let i = { authorization: r };
+		if (t) {
+			let t = await e.getWorkspaceAuthorization({ fresh: n });
+			t && (i["x-workspace-authorization"] = t);
+		}
+		return i;
+	}
+	async function p(e, n) {
+		try {
+			return await t(e, {
+				...n,
+				credentials: "omit",
+				cache: "no-store"
+			});
+		} catch (e) {
+			throw n.signal?.aborted ? e : new o(0, "network", null);
+		}
+	}
+	return {
+		async availability(e) {
+			for (let t = 1;; t += 1) {
+				let n = await l(!0, t > 1), r = await p(`${c}/availability`, {
+					method: "GET",
+					headers: n,
+					signal: e
+				});
+				if (r.ok) return f(await u(r));
+				if (!(r.status === 401 && t === 1)) throw await d(r);
+			}
+		},
+		async create(e, t) {
+			if (!r.test(e.avatarId) || !i.test(e.idempotencyKey)) throw new o(400, "invalid_request", null);
+			let n = JSON.stringify({
+				avatarId: e.avatarId,
+				consentVersion: e.consentVersion
+			}), f = Date.now(), h = !1, g = !1;
+			for (;;) {
+				let r = await l(!0, h);
+				if (r["x-workspace-authorization"] === void 0) throw new o(403, "workspace_context_required", null);
+				let i = await p(`${c}/sessions`, {
+					method: "POST",
+					headers: {
+						...r,
+						"content-type": "application/json",
+						"idempotency-key": e.idempotencyKey
+					},
+					body: n,
+					signal: t
+				});
+				if (i.status === 201) return m(await u(i));
+				let _ = await d(i);
+				if (i.status === 401 && !h) {
+					h = !0;
+					continue;
+				}
+				if (i.status === 409 && _.code === "start_in_progress" && Date.now() - f < s) {
+					if (await a(Math.max(250, (_.retryAfterSeconds ?? 1) * 1e3)), t?.aborted) throw _;
+					continue;
+				}
+				if (i.status === 502 && !g) {
+					g = !0;
+					continue;
+				}
+				throw _;
+			}
+		},
+		async status(e, t) {
+			if (!n.test(e)) throw new o(400, "invalid_request", null);
+			let r = await l(!1, !1), i = await p(`${c}/sessions/${e}`, {
+				method: "GET",
+				headers: r,
+				signal: t
+			});
+			if (!i.ok) throw await d(i);
+			return g(await u(i), e);
+		},
+		async end(e, { reason: t, keepalive: r = !1 }) {
+			if (!n.test(e)) throw new o(400, "invalid_request", null);
+			let i = await l(!1, !1), a = await p(`${c}/sessions/${e}/end`, {
+				method: "POST",
+				headers: {
+					...i,
+					"content-type": "application/json"
+				},
+				body: JSON.stringify({ reason: t }),
+				keepalive: r
+			});
+			if (!a.ok) throw await d(a);
+			return g(await u(a), e);
+		}
+	};
+}
+function y(e) {
+	if (!(e instanceof o) || e.status === 0) return {
+		problem: "connection",
+		hide: !1
+	};
+	if (e.status === 404) return {
+		problem: "unavailable",
+		hide: !0
+	};
+	switch (e.code) {
+		case "avatar_not_allowed":
+		case "workspace_context_required": return {
+			problem: "unavailable",
+			hide: !0
+		};
+		case "avatar_not_approved":
+		case "avatar_not_ready": return {
+			problem: "not-ready",
+			hide: !1
+		};
+		case "actor_already_active": return {
+			problem: "already-running",
+			hide: !1
+		};
+		case "workspace_busy":
+		case "env_busy":
+		case "provider_concurrency_limited":
+		case "provider_no_capacity":
+		case "counters_unavailable":
+		case "avatar_busy": return {
+			problem: "capacity",
+			hide: !1
+		};
+		case "start_rate_limited":
+		case "provider_rate_limited": return {
+			problem: "rate-limited",
+			hide: !1
+		};
+		case "avatar_paused":
+		case "budget_exhausted": return {
+			problem: "paused",
+			hide: !1
+		};
+		case "avatar_unavailable": return {
+			problem: "unavailable",
+			hide: !1
+		};
+		case "provider_unavailable":
+		case "provider_out_of_credits": return {
+			problem: "provider",
+			hide: !1
+		};
+		default: return {
+			problem: e.status === 401 ? "unavailable" : "provider",
+			hide: !1
+		};
+	}
+}
+//#endregion
+export { e as AVATAR_API_PATH, o as AvatarApiError, a as avatarApiBaseFromTtsEndpoint, s as avatarIdempotencyKey, y as avatarRefusalFor, v as createAvatarSessionClient };

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

@@ -0,0 +1,270 @@
+import { AvatarRoom, AvatarByteWriter, AvatarRemoteTrack, AvatarScheduler, AvatarUnsubscribe } from './avatarPorts';
+export declare class AvatarNotReadyError extends Error {
+    readonly missing: 'participant' | 'video' | 'connection';
+    constructor(missing: 'participant' | 'video' | 'connection');
+}
+export declare class AvatarSegmentBusyError extends Error {
+    constructor();
+}
+/** The segment was ended by the provider, a clear, a disconnect or disposal: stop writing. */
+export declare class AvatarSegmentEndedError extends Error {
+    constructor();
+}
+export declare class AvatarTransportClosedError extends Error {
+    constructor();
+}
+export type AvatarTransportEvent = {
+    readonly type: 'ready';
+} | {
+    readonly type: 'playbackStarted';
+}
+/** positionSec / interrupted are null when the provider payload was not the documented shape. */
+ | {
+    readonly type: 'playbackFinished';
+    readonly positionSec: number | null;
+    readonly interrupted: boolean | null;
+    readonly synthetic: boolean;
+} | {
+    readonly type: 'unmatchedFinished';
+}
+/**
+ * A lk.playback_finished taken as the late report owed by a segment that a clear of ours ended without the avatar's confirmation (see
+ * owedFinishes): it is about that segment, never a later one. positionSec / interrupted as reported (null when not the documented shape).
+ */
+ | {
+    readonly type: 'owedFinished';
+    readonly positionSec: number | null;
+    readonly interrupted: boolean | null;
+}
+/** A lk.playback_started while no segment of ours was open or waiting (a stray start for audio we already cleared). */
+ | {
+    readonly type: 'unmatchedStarted';
+} | {
+    readonly type: 'avatarLeft';
+} | {
+    readonly type: 'disconnected';
+} | {
+    readonly type: 'reconnecting';
+} | {
+    readonly type: 'reconnected';
+} | {
+    readonly type: 'audioPlayback';
+    readonly canPlay: boolean;
+}
+/** Result of the readiness probe at connect (see AvatarReadinessProbeOptions). */
+ | {
+    readonly type: 'readiness';
+    readonly status: AvatarReadinessStatus;
+    readonly attempts: number;
+    readonly ms: number;
+    /** Why the last unsuccessful attempt failed: "rejected", "unsupported", "timeout", "recipient-disconnected", "error". */
+    readonly lastReason: string | null;
+} | {
+    readonly type: 'error';
+    readonly message: string;
+};
+/**
+ * confirmed: the avatar answered our probe as the sender it will play (its stream handler is registered for us).
+ * unconfirmed: it never did within the time limit. The transport is still usable: the engine's first-reply retry and voice fallback
+ * remain as the safety net. skipped: the probe is disabled.
+ */
+export type AvatarReadinessStatus = 'confirmed' | 'unconfirmed' | 'skipped';
+/** What one lk.clear_buffer achieved. The engine uses it before it ever writes the same reply again. */
+export interface AvatarClearOutcome {
+    /** The playback position the avatar reported for what it dropped; null when it did not say. */
+    readonly positionSec: number | null;
+    /** True when no lk.playback_finished answered (timeout, failed call, nothing to clear): positionSec is then our own estimate or null. */
+    readonly synthetic: boolean;
+    /** How the call itself was answered: "ok", "rejected", "unsupported", "timeout", "recipient-disconnected", "error", or "none" if not sent. */
+    readonly rpc: string;
+}
+/** What the caller of a clear knows about the segment it ends (see LiveKitAvatarTransport.clearBuffer). */
+export interface AvatarClearOptions {
+    /**
+     * The avatar's report of that segment is already overdue: its own tracker stopped waiting for it (no start, or no finish, within its
+     * deadline). When the avatar does not confirm the clear, such a segment then owes no lk.playback_finished (see owedFinishes): a report that
+     * late is presumed lost, as the tracker presumes, and waiting for it would take a later segment's own report for it. Default false.
+     */
+    readonly finishOverdue?: boolean;
+}
+/**
+ * The first byte stream of a connection can reach the worker before the worker has seen us join (signalling and the data channel are
+ * different paths) and be dropped silently: LiveKit's reference receiver registers its stream handler, and its lk.clear_buffer handler,
+ * only after it has seen its sender. So before the first reply, the transport calls lk.clear_buffer (a no-op on an idle avatar) until the
+ * avatar answers it with anything but "reject": the reference answers "reject" to a caller it does not know and fails with
+ * "method not supported" before it has registered. Bounded: never more than timeoutMs, never a fixed sleep.
+ */
+export interface AvatarReadinessProbeOptions {
+    /** Give up after this long (default 6000 ms); the connection is then "unconfirmed" but usable. */
+    readonly timeoutMs?: number;
+    /** Response timeout of one probe call (default 1500 ms). */
+    readonly rpcTimeoutMs?: number;
+    /** Wait before the second attempt (default 150 ms); doubles up to maxBackoffMs (default 1000 ms). */
+    readonly initialBackoffMs?: number;
+    readonly maxBackoffMs?: number;
+}
+export type AvatarTransportState = 'idle' | 'connecting' | 'ready' | 'closed';
+export interface AvatarSegmentWriter {
+    readonly id: number;
+    readonly state: 'open' | 'closed' | 'ended';
+    /** Seconds of audio handed to the stream, a write still in flight included (its bytes may already be on their way to the avatar). */
+    readonly pushedSec: number;
+    write(pcm: Uint8Array): Promise<void>;
+    /** End of segment (flush): the avatar plays what it has and then reports lk.playback_finished. */
+    close(): Promise<void>;
+    /** Abandon the segment without expecting a lk.playback_finished for it (best-effort trailer). Idempotent. */
+    discard(): void;
+}
+export interface AvatarTransportOptions {
+    readonly room: AvatarRoom;
+    readonly avatarIdentity: string;
+    readonly scheduler: AvatarScheduler;
+    readonly readyTimeoutMs?: number;
+    readonly clearTimeoutMs?: number;
+    /** The first-stream readiness probe. Default: enabled with the defaults above. `false` disables it (tests, comparisons). */
+    readonly readinessProbe?: AvatarReadinessProbeOptions | false;
+}
+export interface AvatarConnectParams {
+    readonly url: string;
+    readonly token: string;
+    readonly videoElement?: HTMLVideoElement | null;
+    readonly audioElement?: HTMLAudioElement | null;
+    /** Called when the avatar's audio track arrives, e.g. to start a level meter on its MediaStreamTrack. */
+    readonly onAvatarAudio?: (track: AvatarRemoteTrack) => void;
+    /**
+     * Called when the avatar's video track arrives (BOFF-8822 P8, additive): the stage attaches it to a video element it owns and may
+     * remount, so the element is not fixed at connect time. Readiness still counts the track whether or not anyone takes it.
+     */
+    readonly onAvatarVideo?: (track: AvatarRemoteTrack) => void;
+}
+declare class Segment implements AvatarSegmentWriter {
+    readonly id: number;
+    private readonly writer;
+    private readonly owner;
+    state: 'open' | 'closed' | 'ended';
+    private pushedBytes;
+    constructor(id: number, writer: AvatarByteWriter, owner: LiveKitAvatarTransport);
+    get pushedSec(): number;
+    write(pcm: Uint8Array): Promise<void>;
+    close(): Promise<void>;
+    discard(): void;
+    /** Called by the transport when the segment can no longer be written to. Best-effort trailer. */
+    end(): void;
+}
+export declare class LiveKitAvatarTransport {
+    private readonly options;
+    private static nextInstanceId;
+    /** Distinguishes connections: each transport instance is one connection to one avatar session. */
+    readonly instanceId: number;
+    private state;
+    private readonly listeners;
+    private readonly unsubscribes;
+    private nextSegmentId;
+    private current;
+    private readonly awaiting;
+    private clearInFlight;
+    private clearSettle;
+    private avatarPresent;
+    private videoPresent;
+    private degraded;
+    private audioElement;
+    private disposed;
+    private rejectReady;
+    private mediaReady;
+    private resolveMediaReady;
+    private readinessStatus;
+    private wakeProbe;
+    /**
+     * A clear of ours that no longer waits (a probe call, a clear answered "ok" whose lk.playback_finished did not come in time, or one for a
+     * segment whose report was already overdue) may still be answered with lk.playback_finished(interrupted), even when nothing was playing
+     * (the reference does not do that, a provider may). Such an answer must never end the segment we write next. At most ONE answer is absorbed
+     * per such clear, and only within the clear timeout: anything beyond is a real interruption. Trade-off: if the old clear is never answered,
+     * a real interruption inside the window is taken for its answer; the reply then ends through the tracker's quiet/no-finish nets
+     * (uncertain, never replayed) instead of at once. A clear the avatar confirmed nothing of is handled by owedFinishes instead.
+     */
+    private strayFinishDeadline;
+    private strayAnswers;
+    /**
+     * lk.playback_finished reports still owed by segments that a clear of ours ended while the avatar confirmed nothing (no finished answered
+     * the clear, and the call itself got no "ok": it timed out or failed). The avatar may have ignored that clear and play the segment on, and
+     * report its end at any later time. It plays streams in the order they were opened, so such a report comes before any later segment's:
+     * every lk.playback_finished goes to these first, oldest first and whatever it says, before a waiting clear, the stray-answer window and any
+     * later segment. So a stopped segment's late end can never complete or end a LATER reply, nor confirm a later clear (BOFF-8822 G1: after a
+     * time-based release that came too early, the stopped segment's natural end was taken for the next reply's). Counted on this connection
+     * (one transport is one connection), and only for the avatar the clear was sent to: forgotten when it leaves, and not counted for a clear
+     * it left during or was absent for (see avatarDepartures), since a worker that comes back knows nothing of those segments.
+     * The cost when such a report never comes (the avatar cleared the segment after all, or dropped it): the next lk.playback_finished is taken
+     * for it, so that reply is never completed by its own report; it ends through the tracker's no-finish or quiet nets as uncertain, bounded by
+     * its own deadline and never claimed. A reply left to reach that deadline ends the cost: its tracker's clear is for an overdue report,
+     * which owes nothing (AvatarClearOptions.finishOverdue), so the reply after it completes on its own report. A Stop or a new question that ends
+     * such a reply before its deadline does not: that clear is for a report not yet overdue, so when the avatar confirms nothing of it either,
+     * that reply owes its report in turn and the reply after it is taken the same way. The cost repeats, one reply at a time, for as long as
+     * each such reply is interrupted before its deadline by a clear the avatar does not confirm, and stops at the first reply left to its
+     * deadline, a clear the avatar confirms, or the avatar leaving; no reply it reaches is ever claimed. Counting that interrupted reply's report
+     * as already paid would stop the repetition, but whenever the report taken was the stopped segment's after all, that reply's own late end
+     * could then complete the reply after it: the false completion this rule exists to prevent (kept for safety, review AD-R1 of 2026-10-11).
+     * Starts are not counted the same way: a segment stopped before it started, that the avatar then plays on, may send its lk.playback_started
+     * while a later segment of ours is open or waiting, and that starts the later reply (its captions) early. It never completes it.
+     */
+    private owedFinishes;
+    /**
+     * How often the avatar left on this connection. A clear notes it when it is sent to an avatar that is present: if the avatar leaves before
+     * the clear resolves (the LiveKit client SDK reports the participant gone first, and only then rejects the calls pending to it, as
+     * RECIPIENT_DISCONNECTED), or was absent when it was sent, the clear leaves nothing to expect, neither an owed report nor a late answer:
+     * the worker that left reports nothing more, and one that comes back knows nothing of that clear (review AD-R2 of 2026-10-11).
+     */
+    private avatarDepartures;
+    constructor(options: AvatarTransportOptions);
+    get transportState(): AvatarTransportState;
+    /** The readiness probe's result once connect() has resolved; null before. */
+    get readiness(): AvatarReadinessStatus | null;
+    /** True while the browser blocks the avatar's audio (autoplay policy): resumeAudio() from a user gesture is needed. */
+    get audioBlocked(): boolean;
+    subscribe(handler: (event: AvatarTransportEvent) => void): AvatarUnsubscribe;
+    private emit;
+    /**
+     * Resume audio playback. Call it synchronously from the user's click on the Avatar toggle (a user gesture is required by
+     * the browser's autoplay policy), and again from a "tap to enable sound" control when audioPlayback reports canPlay=false.
+     */
+    resumeAudio(): Promise<void>;
+    /** Mute or unmute the avatar's audio element instantly (used to silence output on cancel before the provider confirms). */
+    setOutputMuted(muted: boolean): void;
+    connect(params: AvatarConnectParams): Promise<void>;
+    /** Expect at most one more late answer to a clear of ours that no longer waits (see strayFinishDeadline). */
+    private armStrayWindow;
+    /**
+     * Once a clear's outcome is known: what the avatar may still report of the segment it ended. Nothing when a real lk.playback_finished
+     * answered the clear, or when the avatar refused it (it plays nothing of ours and reports nothing). A brief window for one late
+     * interrupted answer when the call was answered "ok", or when that segment's report was already overdue (see strayFinishDeadline).
+     * Otherwise the avatar confirmed nothing: it may have ignored the clear and play the segment on, so that segment owes its report, however
+     * late (see owedFinishes). Called only while the avatar the clear was sent to is still there (see avatarDepartures).
+     */
+    private expectLateAnswer;
+    private checkReady;
+    private waitMediaReady;
+    /**
+     * Bounded readiness probe (see AvatarReadinessProbeOptions). Resolves with the readiness event to emit; rejects when the transport was closed, the
+     * connection dropped, or the avatar left meanwhile. Every call is capped by the remaining budget, so the whole probe never exceeds timeoutMs.
+     */
+    private probeReadiness;
+    private assertReady;
+    openSegment(): Promise<AvatarSegmentWriter>;
+    /** Called by Segment.close(). */
+    segmentClosed(segment: Segment): void;
+    /** Called by Segment.discard(): forget it so the next reply is not blocked waiting for a finished that will not be reported. */
+    segmentDiscarded(segment: Segment): void;
+    private endAllSegments;
+    private handleStarted;
+    private handleFinished;
+    /**
+     * Interrupt: stop writing at once, ask the avatar to drop its buffer, and wait up to the timeout for its
+     * lk.playback_finished(interrupted). Like the reference sender, a missing answer is treated as interrupted.
+     * Resolves when settled; callers must not open a new segment before it resolves. When the avatar confirms nothing of it, the segment it
+     * ended still owes its lk.playback_finished, unless `options` says that report is already overdue (see owedFinishes), or the avatar left
+     * before the clear resolved or was absent when it was sent (see avatarDepartures).
+     */
+    clearBuffer(options?: AvatarClearOptions): Promise<AvatarClearOutcome>;
+    dispose(): Promise<void>;
+    private teardown;
+}
+export {};