realtime-avatar 0.11.5 → 0.13.0

package/dist/{chunk-SML2NB3Q.js → chunk-NOHMMTFR.js}

@@ -1,4 +1,4 @@
-import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-FAEFGA2G.js';
+import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-UVNDDNU2.js';
 
 // ../proxy/src/config.ts
 var json = (body, status = 200) => new Response(JSON.stringify(body), {
@@ -61,6 +61,21 @@ function createProxyHandler(config) {
       minted.set(call.sessionId, now);
       return json(call.raw);
     } catch (error) {
+      if (error instanceof RealtimeAvatarHttpError && error.status === 429) {
+        const concurrency = error.code === "concurrency_limit_reached";
+        const counts = error.concurrency;
+        const message = concurrency ? counts?.maxConcurrentSessions !== void 0 && counts.activeSessions !== void 0 && counts.connectingSessions !== void 0 && counts.pendingSessions !== void 0 ? `Session limit reached (${counts.maxConcurrentSessions} allowed): ${counts.activeSessions} active, ${counts.connectingSessions} connecting, ${counts.pendingSessions} starting. End a session or wait for pending starts to clear, then retry.` : "The concurrent session limit is reached. Active and starting sessions count. End a session or wait for pending starts to clear, then retry." : "Too many requests. Wait before retrying.";
+        const response = json({
+          error: message,
+          code: concurrency ? "concurrency_limit_reached" : "rate_limited",
+          status: 429,
+          retryable: true,
+          ...concurrency ? counts : {},
+          ...error.requestId ? { requestId: error.requestId } : {}
+        }, 429);
+        if (error.requestId) response.headers.set("X-Request-ID", error.requestId);
+        return response;
+      }
       if (error instanceof RealtimeAvatarHttpError && error.isBilling) {
         return json({ code: error.code ?? "insufficient_credits" }, 402);
       }

package/dist/{chunk-FAEFGA2G.js → chunk-UVNDDNU2.js}

@@ -11,12 +11,32 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
   status;
   code;
   body;
-  constructor(status, code, body) {
-    super(`Realtime Avatar API ${status}${code ? ` (${code})` : ""}: ${body || "no body"}`);
+  requestId;
+  concurrency;
+  constructor(status, code, body, requestId) {
+    const bounded = body.slice(0, 400);
+    super(`Realtime Avatar API ${status}${code ? ` (${code})` : ""}: ${bounded || "no body"}`);
     this.name = "RealtimeAvatarHttpError";
     this.status = status;
     this.code = code;
-    this.body = body;
+    this.body = bounded;
+    let parsed = {};
+    try {
+      const value = JSON.parse(body);
+      if (value && typeof value === "object" && !Array.isArray(value)) parsed = value;
+    } catch {
+    }
+    const validId = (value) => typeof value === "string" && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value);
+    this.requestId = validId(parsed.requestId) ? parsed.requestId : validId(requestId) ? requestId : void 0;
+    if (status === 429 && code === "concurrency_limit_reached") {
+      this.concurrency = {};
+      for (const key of ["maxConcurrentSessions", "liveSessions", "activeSessions", "connectingSessions", "pendingSessions"]) {
+        const value = parsed[key];
+        if (typeof value === "number" && Number.isSafeInteger(value) && value >= (key === "maxConcurrentSessions" ? 1 : 0)) {
+          this.concurrency[key] = value;
+        }
+      }
+    }
   }
   /** Out of credits, or over this key's spend limit. Surface a paywall, not an error. */
   get isBilling() {
@@ -26,12 +46,12 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 var motionIdSchema = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/).refine((value) => !["__proto__", "constructor", "prototype"].includes(value), "Reserved identifier");
 function motionRecord(valueSchema) {
   const record = z.record(motionIdSchema, valueSchema);
-  return z.transform((value, ctx) => {
+  return z.preprocess((value, ctx) => {
     if (value !== null && typeof value === "object" && Object.hasOwn(value, "__proto__")) {
       ctx.addIssue({ code: "custom", path: ["__proto__"], message: "Reserved identifier" });
     }
     return value;
-  }).pipe(record);
+  }, record);
 }
 var clipSourceSchema = z.union([
   z.strictObject({ assetId: z.string().trim().min(1).max(160) }),
@@ -134,9 +154,7 @@ var schema13 = z.strictObject({
   "verdict": schema11,
   "issues": schema12,
   "firstFrameUrl": schema4,
-  "lastFrameUrl": schema4,
-  "trimStartMs": schema8,
-  "trimEndMs": schema8
+  "lastFrameUrl": schema4
 });
 var schema14 = z.union([schema13, schema3]);
 var schema15 = z.strictObject({
@@ -218,7 +236,7 @@ function isTransient(cause) {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.11.5";
+var SDK_VERSION = "0.13.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -270,14 +288,16 @@ var RealtimeAvatar = class {
     if (options.video !== void 0) Object.assign(body, videoToWire(options.video));
     const response = await this.#request("POST", "/realtime/livekit/session", { json: body });
     if (response.status === 429) {
-      const busy = await response.json();
-      return {
-        queued: true,
-        position: typeof busy.queue_position === "number" ? busy.queue_position : null,
-        size: typeof busy.queue_size === "number" ? busy.queue_size : 0,
-        retryAfterMs: typeof busy.recommended_retry_ms === "number" ? busy.recommended_retry_ms : 3e3,
-        queueTicketId: typeof busy.queue_ticket_id === "string" ? busy.queue_ticket_id : null
-      };
+      const busy = await response.clone().json().catch(() => null);
+      if (isRecord(busy) && !("code" in busy) && typeof busy.queue_size === "number" && Number.isFinite(busy.queue_size) && busy.queue_size >= 0 && typeof busy.recommended_retry_ms === "number" && Number.isFinite(busy.recommended_retry_ms) && busy.recommended_retry_ms >= 0) {
+        return {
+          queued: true,
+          position: typeof busy.queue_position === "number" ? busy.queue_position : null,
+          size: busy.queue_size,
+          retryAfterMs: busy.recommended_retry_ms,
+          queueTicketId: typeof busy.queue_ticket_id === "string" ? busy.queue_ticket_id : null
+        };
+      }
     }
     const grant = await this.#json(response);
     return {
@@ -657,7 +677,7 @@ var RealtimeAvatar = class {
       code = JSON.parse(text).code;
     } catch {
     }
-    throw new RealtimeAvatarHttpError(response.status, code, text.slice(0, 400));
+    throw new RealtimeAvatarHttpError(response.status, code, text, response.headers.get("x-request-id") ?? void 0);
   }
 };
 function toUsageSessionPage(raw) {

package/dist/express.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-9a0bRdXl.js';
-import './types-nxdohaiH.js';
+import { P as ProxyConfig } from './types-CJcTowDB.js';
+import './types-B9GTrpx0.js';
 
 type Expressish = {
     method: string;

package/dist/express.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-SML2NB3Q.js';
-import './chunk-FAEFGA2G.js';
+import { createProxyHandler } from './chunk-NOHMMTFR.js';
+import './chunk-UVNDDNU2.js';
 
 // ../proxy/src/express.ts
 function realtimeAvatarExpress(config) {

package/dist/hono.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-9a0bRdXl.js';
-import './types-nxdohaiH.js';
+import { P as ProxyConfig } from './types-CJcTowDB.js';
+import './types-B9GTrpx0.js';
 
 /**
  * Hono (and anything else built on Fetch handlers — Workers, Bun, Deno).

package/dist/hono.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-SML2NB3Q.js';
-import './chunk-FAEFGA2G.js';
+import { createProxyHandler } from './chunk-NOHMMTFR.js';
+import './chunk-UVNDDNU2.js';
 
 // ../proxy/src/hono.ts
 function realtimeAvatarHono(config) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipLibraryDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as AssetKind, h as Asset, i as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as CreditBalance, T as TranscriptPayload } from './types-nxdohaiH.js';
-export { l as AvatarClip, m as CallConnection, n as CallQueued, o as ClipDeclaration, p as ClipLibraryPlan, q as ClipSource, r as ContextMessage, s as EndCallReason, V as VideoPolicy, t as isQueued } from './types-nxdohaiH.js';
+import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipLibraryDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as AssetKind, h as Asset, i as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as CreditBalance, T as TranscriptPayload } from './types-B9GTrpx0.js';
+export { l as AvatarClip, m as CallConnection, n as CallQueued, o as ClipDeclaration, p as ClipLibraryPlan, q as ClipSource, r as ContextMessage, s as EndCallReason, V as VideoPolicy, t as isQueued } from './types-B9GTrpx0.js';
 import { z } from 'zod';
 
 interface RealtimeAvatarOptions {
@@ -294,6 +294,7 @@ declare class RealtimeAvatarError extends Error {
  * | `loop_pending` · `anchor_pending` | 409 | one is already in flight — wait, then retry |
  * | `revision_conflict` | 409 | someone declared first. Re-read `listClips`, re-decide, re-declare |
  * | `clip_render_limit` | 429 | a true rate limit; nothing was applied. Retry later |
+ * | `concurrency_limit_reached` | 429 | active and starting sessions occupy the limit; release one or wait for pending starts before retrying |
  * | `clip_screen_unavailable` | 503 | the prose screen could not run. Retry |
  *
  * Pose validation does NOT appear here: a rejected upload is not an error response at all.
@@ -308,7 +309,9 @@ declare class RealtimeAvatarHttpError extends RealtimeAvatarError {
     readonly status: number;
     readonly code: string | undefined;
     readonly body: string;
-    constructor(status: number, code: string | undefined, body: string);
+    readonly requestId?: string;
+    readonly concurrency?: Partial<Record<"maxConcurrentSessions" | "liveSessions" | "activeSessions" | "connectingSessions" | "pendingSessions", number>>;
+    constructor(status: number, code: string | undefined, body: string, requestId?: string);
     /** Out of credits, or over this key's spend limit. Surface a paywall, not an error. */
     get isBilling(): boolean;
 }
@@ -338,32 +341,12 @@ declare const clipLibraryDeclarationSchema: z.ZodObject<{
             clips: z.ZodArray<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
-    actions: z.ZodOptional<z.ZodPipe<z.ZodTransform<Record<string, {
-        description: string;
-        clips: string[];
-    }>, Record<string, {
-        description: string;
-        clips: string[];
-    }>>, z.ZodRecord<z.ZodString, z.ZodObject<{
+    actions: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
         description: z.ZodString;
         clips: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>>>;
     expectedRevision: z.ZodInt;
-    clips: z.ZodNonOptional<z.ZodPipe<z.ZodTransform<Record<string, {
-        source: {
-            assetId: string;
-        } | {
-            motionPrompt: string;
-            durationSeconds?: number | undefined;
-        };
-    }>, Record<string, {
-        source: {
-            assetId: string;
-        } | {
-            motionPrompt: string;
-            durationSeconds?: number | undefined;
-        };
-    }>>, z.ZodRecord<z.ZodString, z.ZodObject<{
+    clips: z.ZodNonOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
         source: z.ZodUnion<readonly [z.ZodObject<{
             assetId: z.ZodString;
         }, z.core.$strict>, z.ZodObject<{

package/dist/index.js

@@ -1 +1 @@
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, verifyTranscript } from './chunk-FAEFGA2G.js';
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, verifyTranscript } from './chunk-UVNDDNU2.js';

package/dist/nextjs.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-9a0bRdXl.js';
-import './types-nxdohaiH.js';
+import { P as ProxyConfig } from './types-CJcTowDB.js';
+import './types-B9GTrpx0.js';
 
 /**
  * App Router. Mount at `app/api/realtime-avatar/[...path]/route.ts`:

package/dist/nextjs.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-SML2NB3Q.js';
-import './chunk-FAEFGA2G.js';
+import { createProxyHandler } from './chunk-NOHMMTFR.js';
+import './chunk-UVNDDNU2.js';
 
 // ../proxy/src/nextjs.ts
 function createRealtimeAvatarRoute(config) {

package/dist/{proxy-client-8cQOLLE_.d.ts → proxy-client-BoUJWSkf.d.ts}

@@ -403,6 +403,22 @@ interface Governor {
     healthySinceMs: number | null;
 }
 
+declare const NETWORK_QUALITY_POLICY: {
+    readonly startupGraceMs: 3000;
+    readonly maxSampleGapMs: 1500;
+    readonly minimumPackets: 20;
+    readonly lossWindowSamples: 3;
+    readonly lossRatio: 0.05;
+    readonly jitterSeconds: 0.1;
+    readonly impairedFps: 12;
+    readonly downgradeMs: 2000;
+    readonly floorMs: 2000;
+    readonly notifyAfterDowngradeMs: 5000;
+    readonly recoverMs: 5000;
+    readonly clearNoticeMs: 10000;
+};
+type NetworkQualityStatus = "unknown" | "healthy" | "poor";
+
 /** How the media is fit into the surface box. Mirrors CSS `object-fit`. */
 type AvatarVideoFit = "contain" | "cover";
 type AvatarVideoSurfaceProps = {
@@ -439,8 +455,13 @@ type AvatarVideoSurfaceProps = {
      * Enable the subscriber-side fast-down/sticky-up quality governor. It starts on
      * the lower simulcast rung, reacts immediately to an SFU pause or decoded-frame
      * freeze, and only probes the full layer after a clean dwell. Default true.
+     * False releases the manual cap to HIGH on each subscription without running
+     * the governor. SFU bandwidth adaptation and live/idle fallback remain active.
      */
-    adaptiveQuality?: boolean;
+    adaptiveQuality?: boolean | "network-only";
+    /** Opt-in "network-only" keeps HIGH unless sustained receiver/network impairment is
+     * observed. Status is unknown until enough fresh data exists; poor after 5s. */
+    onNetworkStatusChange?: (status: NetworkQualityStatus) => void;
     /**
      * Opening bet for the governor when `adaptiveQuality` is on. `"high"` opens on the
      * FULL simulcast layer under probation — sharp from frame 1, no LOW→HIGH layer-walk —
@@ -1539,9 +1560,11 @@ type FreezeReadingFn = () => {
     inhibited: boolean;
 };
 interface UseAvatarQualityGovernorInput {
-    /** Master switch (product policy — the player's feature flag). Off ⇒ inert, no tick,
-     *  no subscriptions, the cap is never touched (byte-identical to today). */
-    enabled: boolean;
+    /** Master switch (product policy). Off releases the manual cap to HIGH on each
+     * subscription, with no governor tick or congestion listeners. SFU adaptation stays on. */
+    enabled: boolean | "network-only";
+    /** Sustained, receiver-evidenced impairment. Never inferred from rendering jitter alone. */
+    onNetworkStatusChange?: (status: NetworkQualityStatus) => void;
     /** The player's rVFC freeze reading getter (see FreezeReadingFn). Optional: without
      *  it the governor still reacts to Paused + getStats freezes, just without the
      *  cross-browser rVFC signal. */
@@ -1624,4 +1647,4 @@ interface ProxyClientOptions {
 }
 declare function createProxyClient(options: ProxyClientOptions): AvatarSessionClient;
 
-export { RECONNECT_BACKOFF_MS as $, type AvatarVideoFit as A, type BehaviorSnapshot as B, type CallTranscript as C, DEFAULT_APPROACHING_END_LEAD_SECONDS as D, type EndReason as E, type FishTtsModel as F, type Governor as G, type GraceWindowClosedEvent as H, type GraceWindowOpenEvent as I, type GraceWindowState as J, type IdleWarningEvent as K, type LiveKitSessionGrant as L, type InboundRtpCursor as M, type InboundRtpReading as N, type KnownBehaviorState as O, type LLMProvider as P, type LLMSelection as Q, type LiveKitAvatarGrantState as R, type LiveKitAvatarGrantStatus as S, type LiveKitCapacityState as T, type LiveKitConnectionStatus as U, type LiveKitSessionRequest as V, type LiveKitSessionStartResult as W, MAX_RECONNECT_ATTEMPTS as X, MAX_SESSION_INSTRUCTIONS_CHARS as Y, type ProxyClientOptions as Z, type QualityCap as _, AdaptivePlayoutController as a, type RealtimeAvatarRequestOptions as a0, type RealtimeSessionApi as a1, type RealtimeSessionMedia as a2, type RealtimeSessionRoomSinks as a3, type ReconnectPolicy as a4, type ReconnectingEvent as a5, type RecoveryState as a6, type RetryStep as a7, type SessionBehavior as a8, type SessionClip as a9, useAvatarAdaptivePlayoutDelay as aA, useAvatarPlayoutDelay as aB, useAvatarQualityGovernor as aC, useCallTranscript as aD, useLiveKitAvatarGrant as aE, useLiveTrackProducing as aF, useMicLease as aG, useRealtimeSession as aH, useReleaseMicLeaseOnTrackEnded as aI, useSessionLifecycle as aJ, AvatarVideoSurface as aK, type AvatarVideoSurfaceProps as aL, type LivePlaybackKeeper as aM, MIC_LEASE_ENDED_TIMEOUT_MS as aN, type MicLease as aO, type PlayableVideoElement as aP, RealtimeAvatarCapacityError as aQ, RealtimeAvatarLiveKitRoom as aR, type RealtimeAvatarLiveKitRoomProps as aS, shouldReplayPendingTurn as aT, type SessionClocks as aa, type SessionEndReason as ab, type SessionLifecycleApi as ac, type SessionLifecyclePhase as ad, type SessionLifecyclePhaseKind as ae, SessionLifecycleRoomBridge as af, type SessionLifecycleRoomBridgeProps as ag, type SurfaceLayers as ah, type TurnState as ai, type TurnTimeoutEvent as aj, type UseAvatarQualityGovernorInput as ak, type UseLiveKitAvatarGrantInput as al, type UseRealtimeSessionInput as am, type UseSessionLifecycleInput as an, type VoiceSpec as ao, type VoiceSpecInput as ap, capacityErrorFromBusy as aq, capacityStateFromGrant as ar, createProxyClient as as, isNativeLiveTrackSubscribed as at, knownBehaviorStates as au, mapTurnState as av, readInboundRtp as aw, sessionBehaviorSchema as ax, sessionClipSchema as ay, splitCallTranscript as az, type AdaptivePlayoutDecision as b, type AdaptivePlayoutOptions as c, type AdaptivePlayoutSample as d, type ApproachingEndEvent as e, type ApproachingEndReason as f, type AvatarSessionClient as g, type CallTranscriptSegment as h, type CartesiaTtsModel as i, type ClipResult as j, type ClosingTurnResult as k, type CreditsLowEvent as l, DEFAULT_CREDITS_LOW_LEAD_SECONDS as m, DEFAULT_GOVERNOR_CONFIG as n, DEFAULT_GRACE_CEILING_SECONDS as o, DEFAULT_GRACE_WINDOW_LEAD_SECONDS as p, DEFAULT_IDLE_SECONDS as q, DEFAULT_IDLE_WARN_LEAD_SECONDS as r, DEFAULT_TURN_TIMEOUT_SECONDS as s, type EndedEvent as t, type ExtendResult as u, type FreezeReadingFn as v, type GovernorAction as w, type GovernorConfig as x, type GovernorSignal as y, type GovernorState as z };
+export { RECONNECT_BACKOFF_MS as $, type AvatarVideoFit as A, type BehaviorSnapshot as B, type CallTranscript as C, DEFAULT_APPROACHING_END_LEAD_SECONDS as D, type EndReason as E, type FishTtsModel as F, type Governor as G, type GraceWindowClosedEvent as H, type GraceWindowOpenEvent as I, type GraceWindowState as J, type IdleWarningEvent as K, type LiveKitSessionGrant as L, type InboundRtpCursor as M, type InboundRtpReading as N, type KnownBehaviorState as O, type LLMProvider as P, type LLMSelection as Q, type LiveKitAvatarGrantState as R, type LiveKitAvatarGrantStatus as S, type LiveKitCapacityState as T, type LiveKitConnectionStatus as U, type LiveKitSessionRequest as V, type LiveKitSessionStartResult as W, MAX_RECONNECT_ATTEMPTS as X, MAX_SESSION_INSTRUCTIONS_CHARS as Y, type ProxyClientOptions as Z, type QualityCap as _, AdaptivePlayoutController as a, type RealtimeAvatarRequestOptions as a0, type RealtimeSessionApi as a1, type RealtimeSessionMedia as a2, type RealtimeSessionRoomSinks as a3, type ReconnectPolicy as a4, type ReconnectingEvent as a5, type RecoveryState as a6, type RetryStep as a7, type SessionBehavior as a8, type SessionClip as a9, useAvatarAdaptivePlayoutDelay as aA, useAvatarPlayoutDelay as aB, useAvatarQualityGovernor as aC, useCallTranscript as aD, useLiveKitAvatarGrant as aE, useLiveTrackProducing as aF, useMicLease as aG, useRealtimeSession as aH, useReleaseMicLeaseOnTrackEnded as aI, useSessionLifecycle as aJ, AvatarVideoSurface as aK, type AvatarVideoSurfaceProps as aL, type LivePlaybackKeeper as aM, MIC_LEASE_ENDED_TIMEOUT_MS as aN, type MicLease as aO, NETWORK_QUALITY_POLICY as aP, type NetworkQualityStatus as aQ, type PlayableVideoElement as aR, RealtimeAvatarCapacityError as aS, RealtimeAvatarLiveKitRoom as aT, type RealtimeAvatarLiveKitRoomProps as aU, shouldReplayPendingTurn as aV, type SessionClocks as aa, type SessionEndReason as ab, type SessionLifecycleApi as ac, type SessionLifecyclePhase as ad, type SessionLifecyclePhaseKind as ae, SessionLifecycleRoomBridge as af, type SessionLifecycleRoomBridgeProps as ag, type SurfaceLayers as ah, type TurnState as ai, type TurnTimeoutEvent as aj, type UseAvatarQualityGovernorInput as ak, type UseLiveKitAvatarGrantInput as al, type UseRealtimeSessionInput as am, type UseSessionLifecycleInput as an, type VoiceSpec as ao, type VoiceSpecInput as ap, capacityErrorFromBusy as aq, capacityStateFromGrant as ar, createProxyClient as as, isNativeLiveTrackSubscribed as at, knownBehaviorStates as au, mapTurnState as av, readInboundRtp as aw, sessionBehaviorSchema as ax, sessionClipSchema as ay, splitCallTranscript as az, type AdaptivePlayoutDecision as b, type AdaptivePlayoutOptions as c, type AdaptivePlayoutSample as d, type ApproachingEndEvent as e, type ApproachingEndReason as f, type AvatarSessionClient as g, type CallTranscriptSegment as h, type CartesiaTtsModel as i, type ClipResult as j, type ClosingTurnResult as k, type CreditsLowEvent as l, DEFAULT_CREDITS_LOW_LEAD_SECONDS as m, DEFAULT_GOVERNOR_CONFIG as n, DEFAULT_GRACE_CEILING_SECONDS as o, DEFAULT_GRACE_WINDOW_LEAD_SECONDS as p, DEFAULT_IDLE_SECONDS as q, DEFAULT_IDLE_WARN_LEAD_SECONDS as r, DEFAULT_TURN_TIMEOUT_SECONDS as s, type EndedEvent as t, type ExtendResult as u, type FreezeReadingFn as v, type GovernorAction as w, type GovernorConfig as x, type GovernorSignal as y, type GovernorState as z };

package/dist/react-native.d.ts

@@ -1,8 +1,8 @@
 import { LiveKitRoomProps } from '@livekit/react-native';
 export { AudioSession, VideoTrack, VideoTrackProps, registerGlobals } from '@livekit/react-native';
 import { ReactNode, ReactElement } from 'react';
-import { L as LiveKitSessionGrant, A as AvatarVideoFit } from './proxy-client-8cQOLLE_.js';
-export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, g as AvatarSessionClient, B as BehaviorSnapshot, C as CallTranscript, h as CallTranscriptSegment, i as CartesiaTtsModel, j as ClipResult, k as ClosingTurnResult, l as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, m as DEFAULT_CREDITS_LOW_LEAD_SECONDS, n as DEFAULT_GOVERNOR_CONFIG, o as DEFAULT_GRACE_CEILING_SECONDS, p as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, q as DEFAULT_IDLE_SECONDS, r as DEFAULT_IDLE_WARN_LEAD_SECONDS, s as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, t as EndedEvent, u as ExtendResult, F as FishTtsModel, v as FreezeReadingFn, G as Governor, w as GovernorAction, x as GovernorConfig, y as GovernorSignal, z as GovernorState, H as GraceWindowClosedEvent, I as GraceWindowOpenEvent, J as GraceWindowState, K as IdleWarningEvent, M as InboundRtpCursor, N as InboundRtpReading, O as KnownBehaviorState, P as LLMProvider, Q as LLMSelection, R as LiveKitAvatarGrantState, S as LiveKitAvatarGrantStatus, T as LiveKitCapacityState, U as LiveKitConnectionStatus, V as LiveKitSessionRequest, W as LiveKitSessionStartResult, X as MAX_RECONNECT_ATTEMPTS, Y as MAX_SESSION_INSTRUCTIONS_CHARS, Z as ProxyClientOptions, _ as QualityCap, $ as RECONNECT_BACKOFF_MS, a0 as RealtimeAvatarRequestOptions, a1 as RealtimeSessionApi, a2 as RealtimeSessionMedia, a3 as RealtimeSessionRoomSinks, a4 as ReconnectPolicy, a5 as ReconnectingEvent, a6 as RecoveryState, a7 as RetryStep, a8 as SessionBehavior, a9 as SessionClip, aa as SessionClocks, ab as SessionEndReason, ac as SessionLifecycleApi, ad as SessionLifecyclePhase, ae as SessionLifecyclePhaseKind, af as SessionLifecycleRoomBridge, ag as SessionLifecycleRoomBridgeProps, ah as SurfaceLayers, ai as TurnState, aj as TurnTimeoutEvent, ak as UseAvatarQualityGovernorInput, al as UseLiveKitAvatarGrantInput, am as UseRealtimeSessionInput, an as UseSessionLifecycleInput, ao as VoiceSpec, ap as VoiceSpecInput, aq as capacityErrorFromBusy, ar as capacityStateFromGrant, as as createProxyClient, at as isNativeLiveTrackSubscribed, au as knownBehaviorStates, av as mapTurnState, aw as readInboundRtp, ax as sessionBehaviorSchema, ay as sessionClipSchema, az as splitCallTranscript, aA as useAvatarAdaptivePlayoutDelay, aB as useAvatarPlayoutDelay, aC as useAvatarQualityGovernor, aD as useCallTranscript, aE as useLiveKitAvatarGrant, aF as useLiveTrackProducing, aG as useMicLease, aH as useRealtimeSession, aI as useReleaseMicLeaseOnTrackEnded, aJ as useSessionLifecycle } from './proxy-client-8cQOLLE_.js';
+import { L as LiveKitSessionGrant, A as AvatarVideoFit } from './proxy-client-BoUJWSkf.js';
+export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, g as AvatarSessionClient, B as BehaviorSnapshot, C as CallTranscript, h as CallTranscriptSegment, i as CartesiaTtsModel, j as ClipResult, k as ClosingTurnResult, l as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, m as DEFAULT_CREDITS_LOW_LEAD_SECONDS, n as DEFAULT_GOVERNOR_CONFIG, o as DEFAULT_GRACE_CEILING_SECONDS, p as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, q as DEFAULT_IDLE_SECONDS, r as DEFAULT_IDLE_WARN_LEAD_SECONDS, s as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, t as EndedEvent, u as ExtendResult, F as FishTtsModel, v as FreezeReadingFn, G as Governor, w as GovernorAction, x as GovernorConfig, y as GovernorSignal, z as GovernorState, H as GraceWindowClosedEvent, I as GraceWindowOpenEvent, J as GraceWindowState, K as IdleWarningEvent, M as InboundRtpCursor, N as InboundRtpReading, O as KnownBehaviorState, P as LLMProvider, Q as LLMSelection, R as LiveKitAvatarGrantState, S as LiveKitAvatarGrantStatus, T as LiveKitCapacityState, U as LiveKitConnectionStatus, V as LiveKitSessionRequest, W as LiveKitSessionStartResult, X as MAX_RECONNECT_ATTEMPTS, Y as MAX_SESSION_INSTRUCTIONS_CHARS, Z as ProxyClientOptions, _ as QualityCap, $ as RECONNECT_BACKOFF_MS, a0 as RealtimeAvatarRequestOptions, a1 as RealtimeSessionApi, a2 as RealtimeSessionMedia, a3 as RealtimeSessionRoomSinks, a4 as ReconnectPolicy, a5 as ReconnectingEvent, a6 as RecoveryState, a7 as RetryStep, a8 as SessionBehavior, a9 as SessionClip, aa as SessionClocks, ab as SessionEndReason, ac as SessionLifecycleApi, ad as SessionLifecyclePhase, ae as SessionLifecyclePhaseKind, af as SessionLifecycleRoomBridge, ag as SessionLifecycleRoomBridgeProps, ah as SurfaceLayers, ai as TurnState, aj as TurnTimeoutEvent, ak as UseAvatarQualityGovernorInput, al as UseLiveKitAvatarGrantInput, am as UseRealtimeSessionInput, an as UseSessionLifecycleInput, ao as VoiceSpec, ap as VoiceSpecInput, aq as capacityErrorFromBusy, ar as capacityStateFromGrant, as as createProxyClient, at as isNativeLiveTrackSubscribed, au as knownBehaviorStates, av as mapTurnState, aw as readInboundRtp, ax as sessionBehaviorSchema, ay as sessionClipSchema, az as splitCallTranscript, aA as useAvatarAdaptivePlayoutDelay, aB as useAvatarPlayoutDelay, aC as useAvatarQualityGovernor, aD as useCallTranscript, aE as useLiveKitAvatarGrant, aF as useLiveTrackProducing, aG as useMicLease, aH as useRealtimeSession, aI as useReleaseMicLeaseOnTrackEnded, aJ as useSessionLifecycle } from './proxy-client-BoUJWSkf.js';
 import { StyleProp, ViewStyle } from 'react-native';
 export { useChat, useConnectionState, useLocalParticipant, useRoomContext, useTrackToggle, useTranscriptions, useVoiceAssistant } from '@livekit/components-react';
 export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS } from './playout-delay-DWOc8iCl.js';

package/dist/react-native.js

@@ -3,7 +3,7 @@ export { AudioSession, VideoTrack, registerGlobals } from '@livekit/react-native
 import { useEffect, createElement, useRef, useState, useCallback, useMemo } from 'react';
 import { useTranscriptions, useLocalParticipant, useMaybeRoomContext, useVoiceAssistant, useConnectionState, isTrackReference, useRoomContext, useChat } from '@livekit/components-react';
 export { useChat, useConnectionState, useLocalParticipant, useRoomContext, useTrackToggle, useTranscriptions, useVoiceAssistant } from '@livekit/components-react';
-import { ConnectionQuality, RoomEvent, TrackEvent, ConnectionState, Track, VideoQuality, ConnectionError, ConnectionErrorReason, DisconnectReason, Room } from 'livekit-client';
+import { VideoQuality, ConnectionQuality, RoomEvent, TrackEvent, ConnectionState, Track, ConnectionError, ConnectionErrorReason, DisconnectReason, Room } from 'livekit-client';
 export { DisconnectReason, Room, RoomEvent, Track } from 'livekit-client';
 import { Platform, StyleSheet, Animated, Image, View, Text } from 'react-native';
 import { z } from 'zod';
@@ -241,6 +241,13 @@ function normalizeRealtimeAvatarError(input) {
   if (status === 409) {
     return { code: "conflict", message: "That request is already in progress. Try again in a moment.", retryable: true };
   }
+  if (status === 429 && rawCode === "concurrency_limit_reached") {
+    return {
+      code: rawCode,
+      message: userSafeMessage(rawMessage) ?? "The concurrent session limit is reached. Active and starting sessions count. End a session or wait for pending starts to clear, then retry.",
+      retryable: true
+    };
+  }
   if (status === 429) {
     return { code: "rate_limited", message: "Too many realtime requests. Please slow down and retry.", retryable: true };
   }
@@ -870,6 +877,144 @@ var resolveLowCapQuality = (declaredLayerQualities, lowUnhealthy = 0) => {
   return lowUnhealthy >= LOW_CAP_STEP_AFTER_UNHEALTHY ? sorted[0] : sorted[sorted.length - 2];
 };
 
+// ../client/src/react/network-quality.ts
+var NETWORK_QUALITY_POLICY = {
+  startupGraceMs: 3e3,
+  maxSampleGapMs: 1500,
+  minimumPackets: 20,
+  lossRatio: 0.05,
+  jitterSeconds: 0.1,
+  impairedFps: 12,
+  downgradeMs: 2e3,
+  floorMs: 2e3,
+  notifyAfterDowngradeMs: 5e3,
+  recoverMs: 5e3,
+  clearNoticeMs: 1e4
+};
+function readNetworkVideoSample(report) {
+  const samples = [];
+  report?.forEach((row) => {
+    if (row.type !== "inbound-rtp" || (row.kind ?? row.mediaType) !== "video") return;
+    const { timestamp, framesDecoded, packetsReceived, packetsLost, jitter } = row;
+    if (typeof row.id !== "string" || ![timestamp, framesDecoded, packetsReceived, packetsLost, jitter].every(
+      (n) => typeof n === "number" && Number.isFinite(n)
+    ) || timestamp < 0 || framesDecoded < 0 || packetsReceived < 0 || jitter < 0) return;
+    samples.push({
+      id: `${row.id}:${row.ssrc ?? ""}`,
+      timestamp,
+      framesDecoded,
+      packetsReceived,
+      packetsLost,
+      jitter
+    });
+  });
+  return samples.length === 1 ? samples[0] : null;
+}
+function initNetworkQuality(nowMs) {
+  return {
+    cap: "high",
+    status: "unknown",
+    sample: null,
+    lastPollMs: null,
+    openedMs: nowMs,
+    badMs: 0,
+    postDowngradeBadMs: 0,
+    reducedBadMs: 0,
+    cleanMs: 0,
+    packetWindow: []
+  };
+}
+function stepNetworkQuality(previous, sample, nowMs, options) {
+  const p = NETWORK_QUALITY_POLICY;
+  const s = { ...previous, sample, lastPollMs: nowMs };
+  const before = previous.sample;
+  const pollMs = previous.lastPollMs === null ? 0 : nowMs - previous.lastPollMs;
+  const elapsedMs = sample && before ? sample.timestamp - before.timestamp : 0;
+  const interrupted = options.inhibited || pollMs <= 0 || pollMs > p.maxSampleGapMs;
+  const valid = !interrupted && sample !== null && before !== null && sample.id === before.id && elapsedMs > 0 && elapsedMs <= p.maxSampleGapMs && sample.framesDecoded >= before.framesDecoded && sample.packetsReceived >= before.packetsReceived;
+  if (!valid || nowMs - s.openedMs < p.startupGraceMs) {
+    s.badMs = s.postDowngradeBadMs = s.reducedBadMs = s.cleanMs = 0;
+    s.packetWindow = [];
+    if (options.inhibited) s.sample = null;
+    return s;
+  }
+  const received = sample.packetsReceived - before.packetsReceived;
+  const lost = Math.max(0, sample.packetsLost - before.packetsLost);
+  s.packetWindow = [...previous.packetWindow, { received, lost }].slice(-3);
+  const totals = s.packetWindow.reduce((sum, interval) => ({
+    received: sum.received + interval.received,
+    lost: sum.lost + interval.lost
+  }), { received: 0, lost: 0 });
+  const packets = totals.received + totals.lost;
+  const fps = (sample.framesDecoded - before.framesDecoded) * 1e3 / elapsedMs;
+  const loss = packets >= p.minimumPackets ? totals.lost / packets : null;
+  const impaired = options.paused || fps < p.impairedFps;
+  const bad = options.paused || impaired && (loss !== null && loss >= p.lossRatio || received >= p.minimumPackets && sample.jitter >= p.jitterSeconds);
+  const clean = received > 0 && !options.paused && loss !== null && loss < p.lossRatio && sample.jitter < p.jitterSeconds && fps >= p.impairedFps;
+  const duration = Math.min(pollMs, elapsedMs);
+  s.badMs = bad ? previous.badMs + duration : 0;
+  s.postDowngradeBadMs = bad && previous.cap !== "high" ? previous.postDowngradeBadMs + duration : 0;
+  s.cleanMs = clean ? previous.cleanMs + duration : 0;
+  s.reducedBadMs = bad && fps === 0 && previous.cap !== "high" ? previous.reducedBadMs + duration : 0;
+  if (s.badMs >= p.downgradeMs && s.cap === "high") s.cap = "reduced";
+  else if (s.reducedBadMs >= p.floorMs && fps === 0 && s.cap === "reduced") s.cap = "floor";
+  if (s.postDowngradeBadMs >= p.notifyAfterDowngradeMs) s.status = "poor";
+  if (s.cleanMs >= p.recoverMs) s.cap = "high";
+  if (s.cleanMs >= p.clearNoticeMs) s.status = "healthy";
+  return s;
+}
+
+// ../client/src/react/network-quality-binding.ts
+function bindNetworkQuality(publication, inhibited, notify, tickMs) {
+  let disposed = false;
+  let running = false;
+  let state = initNetworkQuality(performance.now());
+  const apply = () => {
+    const qualities = (publication.trackInfo?.layers ?? []).map((l) => l.quality);
+    const cap = state.cap === "high" ? VideoQuality.HIGH : resolveLowCapQuality(qualities, state.cap === "floor" ? 2 : 0);
+    try {
+      publication.setVideoQuality(cap);
+    } catch {
+    }
+  };
+  const emit = (status) => {
+    try {
+      notify(status);
+    } catch {
+    }
+  };
+  apply();
+  emit("unknown");
+  const tick = async () => {
+    if (disposed || running) return;
+    running = true;
+    try {
+      const track = publication.track;
+      const stats = await track?.getRTCStatsReport?.();
+      if (disposed || publication.track !== track) return;
+      const prior = state;
+      state = stepNetworkQuality(state, readNetworkVideoSample(stats), performance.now(), {
+        paused: track?.streamState === Track.StreamState.Paused,
+        inhibited: document.hidden || publication.isMuted || inhibited()
+      });
+      if (state.cap !== prior.cap) apply();
+      if (state.status !== prior.status) emit(state.status);
+    } catch {
+      if (!disposed) state = { ...state, sample: null, packetWindow: [], badMs: 0, postDowngradeBadMs: 0, cleanMs: 0, reducedBadMs: 0 };
+    } finally {
+      running = false;
+    }
+  };
+  const timer = setInterval(() => {
+    void tick();
+  }, tickMs);
+  return () => {
+    disposed = true;
+    clearInterval(timer);
+    emit("unknown");
+  };
+}
+
 // ../client/src/react/use-quality-governor.ts
 var qualityToSignal = (q) => {
   switch (q) {
@@ -886,7 +1031,7 @@ var qualityToSignal = (q) => {
   }
 };
 function useAvatarQualityGovernor(input) {
-  const { enabled, freezeReading, config: policy = DEFAULT_GOVERNOR_CONFIG, tickMs = 1e3 } = input;
+  const { enabled, freezeReading, onNetworkStatusChange, config: policy = DEFAULT_GOVERNOR_CONFIG, tickMs = 1e3 } = input;
   const room = useMaybeRoomContext();
   const { videoTrack } = useVoiceAssistant();
   const {
@@ -923,11 +1068,28 @@ function useAvatarQualityGovernor(input) {
   ]);
   const freezeReadingRef = useRef(freezeReading);
   freezeReadingRef.current = freezeReading;
+  const networkCallback = useRef(onNetworkStatusChange);
+  networkCallback.current = onNetworkStatusChange;
   const targetPublication = videoTrack?.publication;
   const targetParticipant = videoTrack?.participant;
   const targetTrack = targetPublication?.track;
   useEffect(() => {
-    if (!enabled || !room || !targetPublication || !targetParticipant) return;
+    if (!room || !targetPublication || !targetParticipant) return;
+    if (enabled === "network-only") {
+      return bindNetworkQuality(
+        targetPublication,
+        () => freezeReadingRef.current?.().inhibited ?? false,
+        (status) => networkCallback.current?.(status),
+        tickMs
+      );
+    }
+    if (!enabled) {
+      try {
+        targetPublication.setVideoQuality(VideoQuality.HIGH);
+      } catch {
+      }
+      return;
+    }
     let pausedSinceTick = false;
     let lastFreezeStat = null;
     let jitterTrend = null;
@@ -2595,8 +2757,13 @@ function createProxyClient(options) {
         requestOptions
       );
       if (response.status === 429) {
-        const busy = await response.json().catch(() => ({}));
-        return { status: "busy", busy };
+        const value = await response.clone().json().catch(() => null);
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          const busy = value;
+          const valid = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+          const queue2 = busy.queued === true && valid(busy.size) && valid(busy.retryAfterMs) || valid(busy.queue_size) && valid(busy.recommended_retry_ms);
+          if (!("code" in busy) && queue2) return { status: "busy", busy };
+        }
       }
       if (!response.ok) {
         throw await RealtimeAvatarApiError.fromResponse(response);

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import { RegisteredTool, ToolRegistration } from './tools.js';
 import { ReactNode } from 'react';
-import { g as AvatarSessionClient, A as AvatarVideoFit } from './proxy-client-8cQOLLE_.js';
-export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, aK as AvatarVideoSurface, aL as AvatarVideoSurfaceProps, B as BehaviorSnapshot, C as CallTranscript, h as CallTranscriptSegment, i as CartesiaTtsModel, j as ClipResult, k as ClosingTurnResult, l as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, m as DEFAULT_CREDITS_LOW_LEAD_SECONDS, n as DEFAULT_GOVERNOR_CONFIG, o as DEFAULT_GRACE_CEILING_SECONDS, p as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, q as DEFAULT_IDLE_SECONDS, r as DEFAULT_IDLE_WARN_LEAD_SECONDS, s as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, t as EndedEvent, u as ExtendResult, F as FishTtsModel, v as FreezeReadingFn, G as Governor, w as GovernorAction, x as GovernorConfig, y as GovernorSignal, z as GovernorState, H as GraceWindowClosedEvent, I as GraceWindowOpenEvent, J as GraceWindowState, K as IdleWarningEvent, M as InboundRtpCursor, N as InboundRtpReading, O as KnownBehaviorState, P as LLMProvider, Q as LLMSelection, R as LiveKitAvatarGrantState, S as LiveKitAvatarGrantStatus, T as LiveKitCapacityState, U as LiveKitConnectionStatus, V as LiveKitSessionRequest, W as LiveKitSessionStartResult, aM as LivePlaybackKeeper, X as MAX_RECONNECT_ATTEMPTS, Y as MAX_SESSION_INSTRUCTIONS_CHARS, aN as MIC_LEASE_ENDED_TIMEOUT_MS, aO as MicLease, aP as PlayableVideoElement, Z as ProxyClientOptions, _ as QualityCap, $ as RECONNECT_BACKOFF_MS, aQ as RealtimeAvatarCapacityError, aR as RealtimeAvatarLiveKitRoom, aS as RealtimeAvatarLiveKitRoomProps, a0 as RealtimeAvatarRequestOptions, a1 as RealtimeSessionApi, a2 as RealtimeSessionMedia, a3 as RealtimeSessionRoomSinks, a4 as ReconnectPolicy, a5 as ReconnectingEvent, a6 as RecoveryState, a7 as RetryStep, a8 as SessionBehavior, a9 as SessionClip, aa as SessionClocks, ab as SessionEndReason, ac as SessionLifecycleApi, ad as SessionLifecyclePhase, ae as SessionLifecyclePhaseKind, af as SessionLifecycleRoomBridge, ag as SessionLifecycleRoomBridgeProps, ah as SurfaceLayers, ai as TurnState, aj as TurnTimeoutEvent, ak as UseAvatarQualityGovernorInput, al as UseLiveKitAvatarGrantInput, am as UseRealtimeSessionInput, an as UseSessionLifecycleInput, ao as VoiceSpec, ap as VoiceSpecInput, aq as capacityErrorFromBusy, ar as capacityStateFromGrant, as as createProxyClient, au as knownBehaviorStates, av as mapTurnState, aw as readInboundRtp, ax as sessionBehaviorSchema, ay as sessionClipSchema, aT as shouldReplayPendingTurn, az as splitCallTranscript, aA as useAvatarAdaptivePlayoutDelay, aB as useAvatarPlayoutDelay, aC as useAvatarQualityGovernor, aD as useCallTranscript, aE as useLiveKitAvatarGrant, aG as useMicLease, aH as useRealtimeSession, aI as useReleaseMicLeaseOnTrackEnded, aJ as useSessionLifecycle } from './proxy-client-8cQOLLE_.js';
+import { g as AvatarSessionClient, A as AvatarVideoFit } from './proxy-client-BoUJWSkf.js';
+export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, aK as AvatarVideoSurface, aL as AvatarVideoSurfaceProps, B as BehaviorSnapshot, C as CallTranscript, h as CallTranscriptSegment, i as CartesiaTtsModel, j as ClipResult, k as ClosingTurnResult, l as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, m as DEFAULT_CREDITS_LOW_LEAD_SECONDS, n as DEFAULT_GOVERNOR_CONFIG, o as DEFAULT_GRACE_CEILING_SECONDS, p as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, q as DEFAULT_IDLE_SECONDS, r as DEFAULT_IDLE_WARN_LEAD_SECONDS, s as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, t as EndedEvent, u as ExtendResult, F as FishTtsModel, v as FreezeReadingFn, G as Governor, w as GovernorAction, x as GovernorConfig, y as GovernorSignal, z as GovernorState, H as GraceWindowClosedEvent, I as GraceWindowOpenEvent, J as GraceWindowState, K as IdleWarningEvent, M as InboundRtpCursor, N as InboundRtpReading, O as KnownBehaviorState, P as LLMProvider, Q as LLMSelection, R as LiveKitAvatarGrantState, S as LiveKitAvatarGrantStatus, T as LiveKitCapacityState, U as LiveKitConnectionStatus, V as LiveKitSessionRequest, W as LiveKitSessionStartResult, aM as LivePlaybackKeeper, X as MAX_RECONNECT_ATTEMPTS, Y as MAX_SESSION_INSTRUCTIONS_CHARS, aN as MIC_LEASE_ENDED_TIMEOUT_MS, aO as MicLease, aP as NETWORK_QUALITY_POLICY, aQ as NetworkQualityStatus, aR as PlayableVideoElement, Z as ProxyClientOptions, _ as QualityCap, $ as RECONNECT_BACKOFF_MS, aS as RealtimeAvatarCapacityError, aT as RealtimeAvatarLiveKitRoom, aU as RealtimeAvatarLiveKitRoomProps, a0 as RealtimeAvatarRequestOptions, a1 as RealtimeSessionApi, a2 as RealtimeSessionMedia, a3 as RealtimeSessionRoomSinks, a4 as ReconnectPolicy, a5 as ReconnectingEvent, a6 as RecoveryState, a7 as RetryStep, a8 as SessionBehavior, a9 as SessionClip, aa as SessionClocks, ab as SessionEndReason, ac as SessionLifecycleApi, ad as SessionLifecyclePhase, ae as SessionLifecyclePhaseKind, af as SessionLifecycleRoomBridge, ag as SessionLifecycleRoomBridgeProps, ah as SurfaceLayers, ai as TurnState, aj as TurnTimeoutEvent, ak as UseAvatarQualityGovernorInput, al as UseLiveKitAvatarGrantInput, am as UseRealtimeSessionInput, an as UseSessionLifecycleInput, ao as VoiceSpec, ap as VoiceSpecInput, aq as capacityErrorFromBusy, ar as capacityStateFromGrant, as as createProxyClient, au as knownBehaviorStates, av as mapTurnState, aw as readInboundRtp, ax as sessionBehaviorSchema, ay as sessionClipSchema, aV as shouldReplayPendingTurn, az as splitCallTranscript, aA as useAvatarAdaptivePlayoutDelay, aB as useAvatarPlayoutDelay, aC as useAvatarQualityGovernor, aD as useCallTranscript, aE as useLiveKitAvatarGrant, aG as useMicLease, aH as useRealtimeSession, aI as useReleaseMicLeaseOnTrackEnded, aJ as useSessionLifecycle } from './proxy-client-BoUJWSkf.js';
 export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS } from './playout-delay-DWOc8iCl.js';
 import 'zod';
 import '@livekit/components-react';

package/dist/react.js

@@ -1,7 +1,7 @@
 "use client";
 import { useRef, useState, useEffect, useCallback, useMemo, createElement, Fragment } from 'react';
 import { useRoomContext, useConnectionState, useTranscriptions, useLocalParticipant, RoomAudioRenderer, LiveKitRoom, useMaybeRoomContext, useVoiceAssistant, VideoTrack, useChat } from '@livekit/components-react';
-import { ConnectionState, ConnectionQuality, RoomEvent, TrackEvent, Track, VideoQuality, ConnectionError, ConnectionErrorReason, DisconnectReason, Room } from 'livekit-client';
+import { ConnectionState, VideoQuality, ConnectionQuality, RoomEvent, TrackEvent, Track, ConnectionError, ConnectionErrorReason, DisconnectReason, Room } from 'livekit-client';
 import { z } from 'zod';
 
 // ../client/src/react/use-character-tools.ts
@@ -394,6 +394,13 @@ function normalizeRealtimeAvatarError(input) {
   if (status === 409) {
     return { code: "conflict", message: "That request is already in progress. Try again in a moment.", retryable: true };
   }
+  if (status === 429 && rawCode === "concurrency_limit_reached") {
+    return {
+      code: rawCode,
+      message: userSafeMessage(rawMessage) ?? "The concurrent session limit is reached. Active and starting sessions count. End a session or wait for pending starts to clear, then retry.",
+      retryable: true
+    };
+  }
   if (status === 429) {
     return { code: "rate_limited", message: "Too many realtime requests. Please slow down and retry.", retryable: true };
   }
@@ -1071,6 +1078,145 @@ var resolveLowCapQuality = (declaredLayerQualities, lowUnhealthy = 0) => {
   return lowUnhealthy >= LOW_CAP_STEP_AFTER_UNHEALTHY ? sorted[0] : sorted[sorted.length - 2];
 };
 
+// ../client/src/react/network-quality.ts
+var NETWORK_QUALITY_POLICY = {
+  startupGraceMs: 3e3,
+  maxSampleGapMs: 1500,
+  minimumPackets: 20,
+  lossWindowSamples: 3,
+  lossRatio: 0.05,
+  jitterSeconds: 0.1,
+  impairedFps: 12,
+  downgradeMs: 2e3,
+  floorMs: 2e3,
+  notifyAfterDowngradeMs: 5e3,
+  recoverMs: 5e3,
+  clearNoticeMs: 1e4
+};
+function readNetworkVideoSample(report) {
+  const samples = [];
+  report?.forEach((row) => {
+    if (row.type !== "inbound-rtp" || (row.kind ?? row.mediaType) !== "video") return;
+    const { timestamp, framesDecoded, packetsReceived, packetsLost, jitter } = row;
+    if (typeof row.id !== "string" || ![timestamp, framesDecoded, packetsReceived, packetsLost, jitter].every(
+      (n) => typeof n === "number" && Number.isFinite(n)
+    ) || timestamp < 0 || framesDecoded < 0 || packetsReceived < 0 || jitter < 0) return;
+    samples.push({
+      id: `${row.id}:${row.ssrc ?? ""}`,
+      timestamp,
+      framesDecoded,
+      packetsReceived,
+      packetsLost,
+      jitter
+    });
+  });
+  return samples.length === 1 ? samples[0] : null;
+}
+function initNetworkQuality(nowMs) {
+  return {
+    cap: "high",
+    status: "unknown",
+    sample: null,
+    lastPollMs: null,
+    openedMs: nowMs,
+    badMs: 0,
+    postDowngradeBadMs: 0,
+    reducedBadMs: 0,
+    cleanMs: 0,
+    packetWindow: []
+  };
+}
+function stepNetworkQuality(previous, sample, nowMs, options) {
+  const p = NETWORK_QUALITY_POLICY;
+  const s = { ...previous, sample, lastPollMs: nowMs };
+  const before = previous.sample;
+  const pollMs = previous.lastPollMs === null ? 0 : nowMs - previous.lastPollMs;
+  const elapsedMs = sample && before ? sample.timestamp - before.timestamp : 0;
+  const interrupted = options.inhibited || pollMs <= 0 || pollMs > p.maxSampleGapMs;
+  const valid = !interrupted && sample !== null && before !== null && sample.id === before.id && elapsedMs > 0 && elapsedMs <= p.maxSampleGapMs && sample.framesDecoded >= before.framesDecoded && sample.packetsReceived >= before.packetsReceived;
+  if (!valid || nowMs - s.openedMs < p.startupGraceMs) {
+    s.badMs = s.postDowngradeBadMs = s.reducedBadMs = s.cleanMs = 0;
+    s.packetWindow = [];
+    if (options.inhibited) s.sample = null;
+    return s;
+  }
+  const received = sample.packetsReceived - before.packetsReceived;
+  const lost = Math.max(0, sample.packetsLost - before.packetsLost);
+  s.packetWindow = [...previous.packetWindow, { received, lost }].slice(-p.lossWindowSamples);
+  const totals = s.packetWindow.reduce((sum, interval) => ({
+    received: sum.received + interval.received,
+    lost: sum.lost + interval.lost
+  }), { received: 0, lost: 0 });
+  const packets = totals.received + totals.lost;
+  const fps = (sample.framesDecoded - before.framesDecoded) * 1e3 / elapsedMs;
+  const loss = packets >= p.minimumPackets ? totals.lost / packets : null;
+  const impaired = options.paused || fps < p.impairedFps;
+  const bad = options.paused || impaired && (loss !== null && loss >= p.lossRatio || received >= p.minimumPackets && sample.jitter >= p.jitterSeconds);
+  const clean = received > 0 && !options.paused && loss !== null && loss < p.lossRatio && sample.jitter < p.jitterSeconds && fps >= p.impairedFps;
+  const duration = Math.min(pollMs, elapsedMs);
+  s.badMs = bad ? previous.badMs + duration : 0;
+  s.postDowngradeBadMs = bad && previous.cap !== "high" ? previous.postDowngradeBadMs + duration : 0;
+  s.cleanMs = clean ? previous.cleanMs + duration : 0;
+  s.reducedBadMs = bad && fps === 0 && previous.cap !== "high" ? previous.reducedBadMs + duration : 0;
+  if (s.badMs >= p.downgradeMs && s.cap === "high") s.cap = "reduced";
+  else if (s.reducedBadMs >= p.floorMs && fps === 0 && s.cap === "reduced") s.cap = "floor";
+  if (s.postDowngradeBadMs >= p.notifyAfterDowngradeMs) s.status = "poor";
+  if (s.cleanMs >= p.recoverMs) s.cap = "high";
+  if (s.cleanMs >= p.clearNoticeMs) s.status = "healthy";
+  return s;
+}
+
+// ../client/src/react/network-quality-binding.ts
+function bindNetworkQuality(publication, inhibited, notify, tickMs) {
+  let disposed = false;
+  let running = false;
+  let state = initNetworkQuality(performance.now());
+  const apply = () => {
+    const qualities = (publication.trackInfo?.layers ?? []).map((l) => l.quality);
+    const cap = state.cap === "high" ? VideoQuality.HIGH : resolveLowCapQuality(qualities, state.cap === "floor" ? 2 : 0);
+    try {
+      publication.setVideoQuality(cap);
+    } catch {
+    }
+  };
+  const emit = (status) => {
+    try {
+      notify(status);
+    } catch {
+    }
+  };
+  apply();
+  emit("unknown");
+  const tick = async () => {
+    if (disposed || running) return;
+    running = true;
+    try {
+      const track = publication.track;
+      const stats = await track?.getRTCStatsReport?.();
+      if (disposed || publication.track !== track) return;
+      const prior = state;
+      state = stepNetworkQuality(state, readNetworkVideoSample(stats), performance.now(), {
+        paused: track?.streamState === Track.StreamState.Paused,
+        inhibited: document.hidden || publication.isMuted || inhibited()
+      });
+      if (state.cap !== prior.cap) apply();
+      if (state.status !== prior.status) emit(state.status);
+    } catch {
+      if (!disposed) state = { ...state, sample: null, packetWindow: [], badMs: 0, postDowngradeBadMs: 0, cleanMs: 0, reducedBadMs: 0 };
+    } finally {
+      running = false;
+    }
+  };
+  const timer = setInterval(() => {
+    void tick();
+  }, tickMs);
+  return () => {
+    disposed = true;
+    clearInterval(timer);
+    emit("unknown");
+  };
+}
+
 // ../client/src/react/use-quality-governor.ts
 var qualityToSignal = (q) => {
   switch (q) {
@@ -1087,7 +1233,7 @@ var qualityToSignal = (q) => {
   }
 };
 function useAvatarQualityGovernor(input) {
-  const { enabled, freezeReading, config: policy = DEFAULT_GOVERNOR_CONFIG, tickMs = 1e3 } = input;
+  const { enabled, freezeReading, onNetworkStatusChange, config: policy = DEFAULT_GOVERNOR_CONFIG, tickMs = 1e3 } = input;
   const room = useMaybeRoomContext();
   const { videoTrack } = useVoiceAssistant();
   const {
@@ -1124,11 +1270,28 @@ function useAvatarQualityGovernor(input) {
   ]);
   const freezeReadingRef = useRef(freezeReading);
   freezeReadingRef.current = freezeReading;
+  const networkCallback = useRef(onNetworkStatusChange);
+  networkCallback.current = onNetworkStatusChange;
   const targetPublication = videoTrack?.publication;
   const targetParticipant = videoTrack?.participant;
   const targetTrack = targetPublication?.track;
   useEffect(() => {
-    if (!enabled || !room || !targetPublication || !targetParticipant) return;
+    if (!room || !targetPublication || !targetParticipant) return;
+    if (enabled === "network-only") {
+      return bindNetworkQuality(
+        targetPublication,
+        () => freezeReadingRef.current?.().inhibited ?? false,
+        (status) => networkCallback.current?.(status),
+        tickMs
+      );
+    }
+    if (!enabled) {
+      try {
+        targetPublication.setVideoQuality(VideoQuality.HIGH);
+      } catch {
+      }
+      return;
+    }
     let pausedSinceTick = false;
     let lastFreezeStat = null;
     let jitterTrend = null;
@@ -1360,6 +1523,7 @@ function AvatarVideoSurface(props) {
     // Keep the governor alive across presentation-intent changes; resetting it on
     // every turn would re-apply LOW and a normal short turn could never earn HIGH.
     enabled: adaptiveQuality,
+    onNetworkStatusChange: props.onNetworkStatusChange,
     freezeReading: frameFlow.freezeReading,
     config: governorConfig
   });
@@ -3214,8 +3378,13 @@ function createProxyClient(options) {
         requestOptions
       );
       if (response.status === 429) {
-        const busy = await response.json().catch(() => ({}));
-        return { status: "busy", busy };
+        const value = await response.clone().json().catch(() => null);
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          const busy = value;
+          const valid = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+          const queue2 = busy.queued === true && valid(busy.size) && valid(busy.retryAfterMs) || valid(busy.queue_size) && valid(busy.recommended_retry_ms);
+          if (!("code" in busy) && queue2) return { status: "busy", busy };
+        }
       }
       if (!response.ok) {
         throw await RealtimeAvatarApiError.fromResponse(response);
@@ -3251,4 +3420,4 @@ function createProxyClient(options) {
   };
 }
 
-export { AdaptivePlayoutController, AvatarCall, AvatarVideoSurface, DEFAULT_APPROACHING_END_LEAD_SECONDS, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, DEFAULT_AVATAR_UNSTABLE_STALL_MS, DEFAULT_CREDITS_LOW_LEAD_SECONDS, DEFAULT_GOVERNOR_CONFIG, DEFAULT_GRACE_CEILING_SECONDS, DEFAULT_GRACE_WINDOW_LEAD_SECONDS, DEFAULT_IDLE_SECONDS, DEFAULT_IDLE_WARN_LEAD_SECONDS, DEFAULT_TURN_TIMEOUT_SECONDS, MAX_RECONNECT_ATTEMPTS, MAX_SESSION_INSTRUCTIONS_CHARS, MIC_LEASE_ENDED_TIMEOUT_MS, RECONNECT_BACKOFF_MS, RealtimeAvatarCapacityError, RealtimeAvatarLiveKitRoom, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, knownBehaviorStates, mapTurnState, readInboundRtp, sessionBehaviorSchema, sessionClipSchema, shouldReplayPendingTurn, splitCallTranscript, useAvatarAdaptivePlayoutDelay, useAvatarCall, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useCharacterTools, useLiveKitAvatarGrant, useMicLease, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };
+export { AdaptivePlayoutController, AvatarCall, AvatarVideoSurface, DEFAULT_APPROACHING_END_LEAD_SECONDS, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, DEFAULT_AVATAR_UNSTABLE_STALL_MS, DEFAULT_CREDITS_LOW_LEAD_SECONDS, DEFAULT_GOVERNOR_CONFIG, DEFAULT_GRACE_CEILING_SECONDS, DEFAULT_GRACE_WINDOW_LEAD_SECONDS, DEFAULT_IDLE_SECONDS, DEFAULT_IDLE_WARN_LEAD_SECONDS, DEFAULT_TURN_TIMEOUT_SECONDS, MAX_RECONNECT_ATTEMPTS, MAX_SESSION_INSTRUCTIONS_CHARS, MIC_LEASE_ENDED_TIMEOUT_MS, NETWORK_QUALITY_POLICY, RECONNECT_BACKOFF_MS, RealtimeAvatarCapacityError, RealtimeAvatarLiveKitRoom, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, knownBehaviorStates, mapTurnState, readInboundRtp, sessionBehaviorSchema, sessionClipSchema, shouldReplayPendingTurn, splitCallTranscript, useAvatarAdaptivePlayoutDelay, useAvatarCall, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useCharacterTools, useLiveKitAvatarGrant, useMicLease, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };

package/dist/server.d.ts

@@ -1,3 +1,3 @@
 export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, RealtimeAvatarOptions, StartCallOptions, clipLibraryDeclarationSchema, verifyTranscript } from './index.js';
-export { h as Asset, g as AssetKind, A as Avatar, l as AvatarClip, c as AvatarSourceSwap, b as AvatarUpdate, m as CallConnection, C as CallMode, a as CallPolicy, n as CallQueued, o as ClipDeclaration, f as ClipLibrary, d as ClipLibraryDeclaration, p as ClipLibraryPlan, e as ClipLibraryUpdate, q as ClipSource, r as ContextMessage, k as CreditBalance, E as EndCallOptions, s as EndCallReason, i as ListSessionsOptions, L as LoopRedirect, S as StartCallResult, T as TranscriptPayload, j as UsageSession, U as UsageSessionPage, V as VideoPolicy, t as isQueued } from './types-nxdohaiH.js';
+export { h as Asset, g as AssetKind, A as Avatar, l as AvatarClip, c as AvatarSourceSwap, b as AvatarUpdate, m as CallConnection, C as CallMode, a as CallPolicy, n as CallQueued, o as ClipDeclaration, f as ClipLibrary, d as ClipLibraryDeclaration, p as ClipLibraryPlan, e as ClipLibraryUpdate, q as ClipSource, r as ContextMessage, k as CreditBalance, E as EndCallOptions, s as EndCallReason, i as ListSessionsOptions, L as LoopRedirect, S as StartCallResult, T as TranscriptPayload, j as UsageSession, U as UsageSessionPage, V as VideoPolicy, t as isQueued } from './types-B9GTrpx0.js';
 import 'zod';

package/dist/server.js

@@ -1 +1 @@
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, verifyTranscript } from './chunk-FAEFGA2G.js';
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, verifyTranscript } from './chunk-UVNDDNU2.js';

package/dist/tanstack-start.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-9a0bRdXl.js';
-import './types-nxdohaiH.js';
+import { P as ProxyConfig } from './types-CJcTowDB.js';
+import './types-B9GTrpx0.js';
 
 /**
  * TanStack Start. Mount at `routes/api/realtime-avatar/$.ts` — the trailing `$` is Start's

package/dist/tanstack-start.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-SML2NB3Q.js';
-import './chunk-FAEFGA2G.js';
+import { createProxyHandler } from './chunk-NOHMMTFR.js';
+import './chunk-UVNDDNU2.js';
 
 // src/tanstack-start.ts
 function realtimeAvatarServerRoute(config) {

package/dist/{types-nxdohaiH.d.ts → types-B9GTrpx0.d.ts}

@@ -343,10 +343,10 @@ interface components {
         CreateApiKeyRequest: {
             name: string;
             /**
-             * @default test
+             * @description Deprecated. Accepted for older clients but ignored; all new keys use the same tic_ format.
              * @enum {string}
              */
-            environment: "live" | "test";
+            environment?: "live" | "test";
             /**
              * @default [
              *       "realtime:write",
@@ -363,15 +363,16 @@ interface components {
             keyId: string;
             tenantId: string;
             name: string;
-            /** @enum {string} */
-            environment: "live" | "test";
             redactedKey: string;
+            /** @default false */
+            canReveal: boolean;
             scopes: ("*" | "api_keys:write" | "credits:read" | "avatars:read" | "avatars:write" | "realtime:write" | "usage:read" | "usage:write")[];
             /** @enum {string} */
             status: "active" | "revoked" | "expired";
             spendLimitCreditMicros: number | null;
             createdAt: string;
             expiresAt: string | null;
+            /** Format: starts_with */
             apiKey: string;
         };
         Asset: {
@@ -482,8 +483,6 @@ interface components {
                     issues: string[];
                     firstFrameUrl: string | null;
                     lastFrameUrl: string | null;
-                    trimStartMs: number | null;
-                    trimEndMs: number | null;
                 } | null;
                 error: {
                     code: string;
@@ -522,6 +521,13 @@ interface components {
                 };
             };
         };
+        ReviewAvatarClipRequest: {
+            clipId: string;
+            uploadAssetId: string;
+            expectedRevision: number;
+            expectedAnchorVersion: number;
+            reason: string;
+        };
         PutAvatarClipsRequest: {
             expectedRevision: number;
             clips: {
@@ -573,8 +579,6 @@ interface components {
                     issues: string[];
                     firstFrameUrl: string | null;
                     lastFrameUrl: string | null;
-                    trimStartMs: number | null;
-                    trimEndMs: number | null;
                 } | null;
                 error: {
                     code: string;
@@ -659,6 +663,16 @@ interface components {
             grantedScopes?: ("*" | "api_keys:write" | "credits:read" | "avatars:read" | "avatars:write" | "realtime:write" | "usage:read" | "usage:write")[];
             /** @description Present on 402 — where to send the user to top up. */
             billingUrl?: string;
+            /** @description On concurrency_limit_reached: the workspace's concurrent session limit. */
+            maxConcurrentSessions?: number;
+            /** @description Legacy concurrency count: occupied reservations, including active, connecting and starting sessions. Not the number of active conversations. */
+            liveSessions?: number;
+            /** @description On concurrency_limit_reached: counted reservations with started media, observed at refusal. */
+            activeSessions?: number;
+            /** @description On concurrency_limit_reached: counted reservations with an attached session that has not started media. */
+            connectingSessions?: number;
+            /** @description On concurrency_limit_reached: counted in-flight starts with no attached session yet. */
+            pendingSessions?: number;
         } & {
             [key: string]: unknown;
         };

package/dist/{types-9a0bRdXl.d.ts → types-CJcTowDB.d.ts}

@@ -1,4 +1,4 @@
-import { C as CallMode, a as CallPolicy } from './types-nxdohaiH.js';
+import { C as CallMode, a as CallPolicy } from './types-B9GTrpx0.js';
 
 /** The three things a caller can ask the proxy to do. Gate on these, not on URLs. */
 type ProxyOperation = "connect" | "end" | "avatars" | "credits";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-avatar",
-  "version": "0.11.5",
+  "version": "0.13.0",
   "description": "Realtime Avatar SDK. `realtime-avatar` and the route adapters hold your API key and are server-only; `realtime-avatar/react`, `/browser` and `/tools` never can — importing a server entry into a browser build throws at bundle time.",
   "license": "MIT",
   "author": "The Influence Company",