realtime-avatar 0.27.0 → 0.27.1

package/README.md

@@ -353,6 +353,28 @@ a last line first.
 On the lower-level hooks, `reconnect()` redials (a double tap mints once), and so does setting
 `active` to false and back. `reset()` does not undo an end.
 
+### Waiting for the character
+
+Joining the room is not enough to start a conversation: the character's agent must also
+arrive. The shared React and React Native lifecycle allows at most 30 seconds from the first
+held grant to that readiness, including automatic retries and signaling reconnects. The
+existing connect watchdog (12 seconds by default) also recovers a connected room whose agent
+never arrives. A transport connection alone does not reset the retry count or buy more time.
+
+When the budget or retry count runs out, the SDK releases the session, leaves the room and
+ends with `phase.reason: "error"` / `onEnded({ reason: "failed" })`. The optional `phase.code`
+distinguishes `agent_timeout` from `connection_timeout`; these are client observations, not
+HTTP status codes. `agent_timeout` means at least one room connected but the call never became
+ready; retries may also have transport delays. `connection_timeout` means no room connected.
+While connecting, `phase.waitingFor` distinguishes `agent` from `transport`.
+No automatic mint follows that failure; `reconnect()` starts a fresh budget. A call that
+already reached live keeps LiveKit's normal recovery of its existing room.
+
+On `useRealtimeSession` or `useSessionLifecycle`, `readyTimeoutSeconds` changes the total
+budget (positive, default 30). `connectWatchdogSeconds` changes the per-attempt wait; disabling
+that watchdog with zero still leaves the total budget in force. Neither setting fabricates
+media readiness or changes the application's first-video-frame gate.
+
 ### Optional connection details
 
 `AvatarCall` provides call status, actions and end reasons for your default UI. To show

package/dist/{chunk-NMJQEGYW.js → chunk-4IEGR75H.js}

@@ -665,7 +665,7 @@ var liveKitSessionReleaseReasonSchema = z.enum([
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.27.0";
+var SDK_VERSION = "0.27.1";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;

package/dist/{chunk-SUKZ77GL.js → chunk-DOHZ365B.js}

@@ -1,4 +1,4 @@
-import { sessionModeSchema, liveKitSessionReleaseReasonSchema, RealtimeAvatar, ROUTE_TIMEOUT_MS, isQueued, RealtimeAvatarHttpError, RealtimeAvatarError } from './chunk-NMJQEGYW.js';
+import { sessionModeSchema, liveKitSessionReleaseReasonSchema, RealtimeAvatar, ROUTE_TIMEOUT_MS, isQueued, RealtimeAvatarHttpError, RealtimeAvatarError } from './chunk-4IEGR75H.js';
 import { z } from 'zod';
 
 // ../http-client/src/generated/error-semantics.ts

package/dist/express.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-SUKZ77GL.js';
-import './chunk-NMJQEGYW.js';
+import { createProxyHandler } from './chunk-DOHZ365B.js';
+import './chunk-4IEGR75H.js';
 import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/express.ts

package/dist/hono.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-SUKZ77GL.js';
-import './chunk-NMJQEGYW.js';
+import { createProxyHandler } from './chunk-DOHZ365B.js';
+import './chunk-4IEGR75H.js';
 import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/hono.ts

package/dist/index.js

@@ -1,2 +1,2 @@
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript } from './chunk-NMJQEGYW.js';
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript } from './chunk-4IEGR75H.js';
 import './chunk-MCIXU6XP.js';

package/dist/nextjs.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-SUKZ77GL.js';
-import './chunk-NMJQEGYW.js';
+import { createProxyHandler } from './chunk-DOHZ365B.js';
+import './chunk-4IEGR75H.js';
 import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/nextjs.ts

package/dist/{proxy-client-D75TLU5X.d.ts → proxy-client-Cs2azqD1.d.ts}

@@ -1370,6 +1370,9 @@ type ReconnectPolicy = {
  *   {@link SessionLifecycleApi.reconnect}.
  */
 type SessionEndReason = "idle" | "disconnected" | "error" | "user";
+/** Client-observed readiness failure, not an HTTP/provider error code. `agent_timeout` means
+ * at least one room connected without reaching agent readiness; retries may also have transport delays. */
+type SessionReadinessFailure = "agent_timeout" | "connection_timeout";
 type SessionLifecyclePhase = {
     kind: "idle";
 } | {
@@ -1380,6 +1383,7 @@ type SessionLifecyclePhase = {
 } | {
     kind: "connecting";
     grant: LiveKitSessionGrant;
+    waitingFor?: "transport" | "agent";
 } | {
     kind: "live";
 } | {
@@ -1392,9 +1396,11 @@ type SessionLifecyclePhase = {
     attempt: number;
     /** Native LiveKit recovery keeps the same grant; fresh-grant recovery re-mints. */
     strategy: "in-place" | "fresh-grant";
+    reason?: SessionReadinessFailure;
 } | {
     kind: "ended";
     reason?: SessionEndReason;
+    code?: SessionReadinessFailure;
 };
 type SessionLifecyclePhaseKind = SessionLifecyclePhase["kind"];
 /**
@@ -1409,14 +1415,18 @@ type RecoveryState = {
 } | {
     kind: "refreshing";
     attempt: number;
+    reason?: SessionReadinessFailure;
 } | {
     kind: "reconnecting";
     attempt: number;
+    reason?: SessionReadinessFailure;
 } | {
     kind: "failed";
+    reason?: SessionReadinessFailure;
 } | {
     kind: "ended";
     reason?: SessionEndReason;
+    code?: SessionReadinessFailure;
 };
 /**
  * The CLIENT-OWNED idle budget (seconds): how long "quiet" before the client-
@@ -1466,8 +1476,8 @@ type UseSessionLifecycleInput<T extends LLMProvider = LLMProvider> = {
     /** Auto-reconnect give-up bound. Default {@link MAX_RECONNECT_ATTEMPTS}. */
     maxReconnectAttempts?: number;
     /**
-     * How long a held grant may sit UNCONNECTED before we give the slot back
-     * (seconds). Default {@link DEFAULT_CONNECT_WATCHDOG_SECONDS}.
+     * Per-attempt wait for the room connection, then for its first agent, before giving the
+     * slot back (seconds). Default {@link DEFAULT_CONNECT_WATCHDOG_SECONDS}.
      *
      * A grant that never reaches a live room is invisible to every other timer here:
      * the idle clock only runs once connected, and LiveKit reports no disconnect for
@@ -1476,9 +1486,16 @@ type UseSessionLifecycleInput<T extends LLMProvider = LLMProvider> = {
      * the caller's only slot, so their retry is refused by a call they never saw.
      * Measured in prod: 8 of 12 never-connected sessions held for 76-81s.
      *
-     * Set 0 to disable (the platform timeout remains the backstop).
+     * Set 0 to disable per-attempt recovery; the total readiness budget still applies.
      */
     connectWatchdogSeconds?: number;
+    /**
+     * Total pre-live readiness budget from the first held grant, including automatic retries.
+     * A transport connection alone never resets it. Default {@link DEFAULT_READY_TIMEOUT_SECONDS}.
+     * Non-positive/non-finite overrides use the default. Explicit reconnect starts a new budget.
+     * The existing connect watchdog also bounds each connected room's wait for its first agent.
+     */
+    readyTimeoutSeconds?: number;
     /** Forwarded to {@link useLiveKitAvatarGrant}. Defaults true (queue auto-retry). */
     autoRetryBusy?: boolean;
     requestOptions?: UseLiveKitAvatarGrantInput<T>["requestOptions"];
@@ -1499,7 +1516,7 @@ type SessionLifecycleApi = {
     grant: LiveKitSessionGrant | null;
     /** The underlying capacity signal (queue position/size, error) — unchanged. */
     capacity: LiveKitCapacityState;
-    /** The DOM recovery contract: auto-reconnect attempts since the last connect. */
+    /** The DOM recovery contract: auto-reconnect attempts since the last room + agent readiness. */
     attempt: number;
     /**
      * ms until the CLIENT-ENFORCED idle end, or null when not connected/live. Drives
@@ -1558,6 +1575,8 @@ type SessionLifecycleApi = {
     /** Reset to idle (mode/avatar change). Does not undo {@link end}: an ended call stays ended. */
     reset: () => void;
 };
+/** Maximum automatic startup wait across grants; successful room + agent readiness ends it. */
+declare const DEFAULT_READY_TIMEOUT_SECONDS = 30;
 declare function useSessionLifecycle<T extends LLMProvider = LLMProvider>(input: UseSessionLifecycleInput<T>): SessionLifecycleApi;
 /**
  * The optional realtime-session sinks the bridge ALSO fills when given the richer
@@ -2026,4 +2045,4 @@ interface ProxyClientOptions {
 }
 declare function createProxyClient(options: ProxyClientOptions): AvatarSessionClient;
 
-export { type ProxyClientOptions 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 GovernorSignal as H, type GovernorState as I, type GraceWindowClosedEvent as J, type GraceWindowOpenEvent as K, type LiveKitSessionGrant as L, type GraceWindowState as M, type IdleWarningEvent as N, type InboundRtpCursor as O, type InboundRtpReading as P, type KnownBehaviorState as Q, type LLMProvider as R, type LLMSelection as S, type LiveKitAvatarGrantState as T, type LiveKitAvatarGrantStatus as U, type LiveKitCapacityState as V, type LiveKitConnectionStatus as W, type LiveKitSessionRequest as X, type LiveKitSessionStartResult as Y, MAX_RECONNECT_ATTEMPTS as Z, MAX_SESSION_INSTRUCTIONS_CHARS as _, AdaptivePlayoutController as a, RealtimeAvatarCapacityError as a$, type QualityCap as a0, RECONNECT_BACKOFF_MS as a1, type RealtimeAvatarRequestOptions as a2, type RealtimeSessionApi as a3, type RealtimeSessionMedia as a4, type RealtimeSessionRoomSinks as a5, type ReconnectPolicy as a6, type ReconnectingEvent as a7, type RecoveryState as a8, type RetryStep as a9, mapTurnState as aA, readInboundRtp as aB, sessionBehaviorSchema as aC, sessionClipSchema as aD, splitCallTranscript as aE, useAvatarAdaptivePlayoutDelay as aF, useAvatarCamera as aG, useAvatarPlayoutDelay as aH, useAvatarQualityGovernor as aI, useCallTranscript as aJ, useLiveKitAvatarGrant as aK, useLiveTrackProducing as aL, useMicLease as aM, useRealtimeSession as aN, useReleaseMicLeaseOnTrackEnded as aO, useSessionLifecycle as aP, type CallMicrophone as aQ, type CallAudioPlayback as aR, type CallMicrophoneProblem as aS, AvatarVideoSurface as aT, type AvatarVideoSurfaceProps as aU, type LivePlaybackKeeper as aV, MIC_LEASE_ENDED_TIMEOUT_MS as aW, type MicLease as aX, NETWORK_QUALITY_POLICY as aY, type NetworkQualityStatus as aZ, type PlayableVideoElement as a_, type SendTurnOptions as aa, type SessionBehavior as ab, type SessionClip as ac, type SessionClocks as ad, type SessionEndReason as ae, type SessionLifecycleApi as af, type SessionLifecyclePhase as ag, type SessionLifecyclePhaseKind as ah, SessionLifecycleRoomBridge as ai, type SessionLifecycleRoomBridgeProps as aj, type SurfaceLayers as ak, type TranscriptSender as al, type TranscriptSenderOptions as am, type TurnState as an, type TurnTimeoutEvent as ao, type UseAvatarQualityGovernorInput as ap, type UseLiveKitAvatarGrantInput as aq, type UseRealtimeSessionInput as ar, type UseSessionLifecycleInput as as, type VoiceSpec as at, type VoiceSpecInput as au, capacityErrorFromBusy as av, capacityStateFromGrant as aw, createProxyClient as ax, isNativeLiveTrackSubscribed as ay, knownBehaviorStates as az, type AdaptivePlayoutDecision as b, RealtimeAvatarLiveKitRoom as b0, type RealtimeAvatarLiveKitRoomProps as b1, shouldReplayPendingTurn as b2, type AdaptivePlayoutOptions as c, type AdaptivePlayoutSample as d, type ApproachingEndEvent as e, type ApproachingEndReason as f, type AvatarConnectionDetails as g, type AvatarSessionClient as h, type CallTranscriptSegment as i, type CartesiaTtsModel as j, type ClipResult as k, type ClosingTurnResult as l, type CreditsLowEvent as m, DEFAULT_CREDITS_LOW_LEAD_SECONDS as n, DEFAULT_GOVERNOR_CONFIG as o, DEFAULT_GRACE_CEILING_SECONDS as p, DEFAULT_GRACE_WINDOW_LEAD_SECONDS as q, DEFAULT_IDLE_SECONDS as r, DEFAULT_IDLE_WARN_LEAD_SECONDS as s, DEFAULT_TURN_TIMEOUT_SECONDS as t, type DeclaredInputSource as u, type EndedEvent as v, type ExtendResult as w, type FreezeReadingFn as x, type GovernorAction as y, type GovernorConfig as z };
+export { MAX_SESSION_INSTRUCTIONS_CHARS 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 GovernorConfig as H, type GovernorSignal as I, type GovernorState as J, type GraceWindowClosedEvent as K, type LiveKitSessionGrant as L, type GraceWindowOpenEvent as M, type GraceWindowState as N, type IdleWarningEvent as O, type InboundRtpCursor as P, type InboundRtpReading as Q, type KnownBehaviorState as R, type LLMProvider as S, type LLMSelection as T, type LiveKitAvatarGrantState as U, type LiveKitAvatarGrantStatus as V, type LiveKitCapacityState as W, type LiveKitConnectionStatus as X, type LiveKitSessionRequest as Y, type LiveKitSessionStartResult as Z, MAX_RECONNECT_ATTEMPTS as _, AdaptivePlayoutController as a, type NetworkQualityStatus as a$, type ProxyClientOptions as a0, type QualityCap as a1, RECONNECT_BACKOFF_MS as a2, type RealtimeAvatarRequestOptions as a3, type RealtimeSessionApi as a4, type RealtimeSessionMedia as a5, type RealtimeSessionRoomSinks as a6, type ReconnectPolicy as a7, type ReconnectingEvent as a8, type RecoveryState as a9, isNativeLiveTrackSubscribed as aA, knownBehaviorStates as aB, mapTurnState as aC, readInboundRtp as aD, sessionBehaviorSchema as aE, sessionClipSchema as aF, splitCallTranscript as aG, useAvatarAdaptivePlayoutDelay as aH, useAvatarCamera as aI, useAvatarPlayoutDelay as aJ, useAvatarQualityGovernor as aK, useCallTranscript as aL, useLiveKitAvatarGrant as aM, useLiveTrackProducing as aN, useMicLease as aO, useRealtimeSession as aP, useReleaseMicLeaseOnTrackEnded as aQ, useSessionLifecycle as aR, type CallMicrophone as aS, type CallAudioPlayback as aT, type CallMicrophoneProblem as aU, AvatarVideoSurface as aV, type AvatarVideoSurfaceProps as aW, type LivePlaybackKeeper as aX, MIC_LEASE_ENDED_TIMEOUT_MS as aY, type MicLease as aZ, NETWORK_QUALITY_POLICY as a_, type RetryStep as aa, type SendTurnOptions as ab, type SessionBehavior as ac, type SessionClip as ad, type SessionClocks as ae, type SessionEndReason as af, type SessionLifecycleApi as ag, type SessionLifecyclePhase as ah, type SessionLifecyclePhaseKind as ai, SessionLifecycleRoomBridge as aj, type SessionLifecycleRoomBridgeProps as ak, type SessionReadinessFailure as al, type SurfaceLayers as am, type TranscriptSender as an, type TranscriptSenderOptions as ao, type TurnState as ap, type TurnTimeoutEvent as aq, type UseAvatarQualityGovernorInput as ar, type UseLiveKitAvatarGrantInput as as, type UseRealtimeSessionInput as at, type UseSessionLifecycleInput as au, type VoiceSpec as av, type VoiceSpecInput as aw, capacityErrorFromBusy as ax, capacityStateFromGrant as ay, createProxyClient as az, type AdaptivePlayoutDecision as b, type PlayableVideoElement as b0, RealtimeAvatarCapacityError as b1, RealtimeAvatarLiveKitRoom as b2, type RealtimeAvatarLiveKitRoomProps as b3, shouldReplayPendingTurn as b4, type AdaptivePlayoutOptions as c, type AdaptivePlayoutSample as d, type ApproachingEndEvent as e, type ApproachingEndReason as f, type AvatarConnectionDetails as g, type AvatarSessionClient as h, type CallTranscriptSegment as i, type CartesiaTtsModel as j, type ClipResult as k, type ClosingTurnResult as l, type CreditsLowEvent as m, DEFAULT_CREDITS_LOW_LEAD_SECONDS as n, DEFAULT_GOVERNOR_CONFIG as o, DEFAULT_GRACE_CEILING_SECONDS as p, DEFAULT_GRACE_WINDOW_LEAD_SECONDS as q, DEFAULT_IDLE_SECONDS as r, DEFAULT_IDLE_WARN_LEAD_SECONDS as s, DEFAULT_READY_TIMEOUT_SECONDS as t, DEFAULT_TURN_TIMEOUT_SECONDS as u, type DeclaredInputSource as v, type EndedEvent as w, type ExtendResult as x, type FreezeReadingFn as y, type GovernorAction as z };

package/dist/react-native.d.ts

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

package/dist/react-native.js

@@ -177,6 +177,8 @@ function RealtimeAvatarLiveKitRoom(props) {
     LiveKitRoom,
     {
       ...roomProps,
+      // Keep the room and its in-room observers scoped to the grant, as on web.
+      key: grant?.session_id ?? "no-session",
       serverUrl: grant?.livekit_url,
       token: grant?.participant_token,
       connect: shouldConnect,
@@ -2395,7 +2397,8 @@ function lifecyclePhaseFrom(args) {
       kind: "reconnectable",
       reconnecting: true,
       attempt: recovery.attempt,
-      strategy: "fresh-grant"
+      strategy: "fresh-grant",
+      ...recovery.reason ? { reason: recovery.reason } : {}
     };
   }
   if (recovery.kind === "failed") {
@@ -2403,11 +2406,16 @@ function lifecyclePhaseFrom(args) {
       kind: "reconnectable",
       reconnecting: false,
       attempt: MAX_RECONNECT_ATTEMPTS,
-      strategy: "fresh-grant"
+      strategy: "fresh-grant",
+      ...recovery.reason ? { reason: recovery.reason } : {}
     };
   }
   if (recovery.kind === "ended") {
-    return recovery.reason ? { kind: "ended", reason: recovery.reason } : { kind: "ended" };
+    return {
+      kind: "ended",
+      ...recovery.reason ? { reason: recovery.reason } : {},
+      ...recovery.code ? { code: recovery.code } : {}
+    };
   }
   switch (capacity.kind) {
     case "idle":
@@ -2420,7 +2428,7 @@ function lifecyclePhaseFrom(args) {
       return { kind: "ended", reason: "error" };
     case "active": {
       if (!connected || !agentPresent) {
-        return { kind: "connecting", grant: capacity.grant };
+        return { kind: "connecting", grant: capacity.grant, waitingFor: connected ? "agent" : "transport" };
       }
       if (idle.kind === "idle-warning") {
         return { kind: "idle-warning", secondsRemaining: idle.secondsRemaining, deadlineAt: idle.deadlineAt };
@@ -2448,6 +2456,7 @@ function resolveIdleTimeoutMs(args) {
   return DEFAULT_IDLE_SECONDS * 1e3;
 }
 var DEFAULT_CONNECT_WATCHDOG_SECONDS = 12;
+var DEFAULT_READY_TIMEOUT_SECONDS = 30;
 function resolveWarnBeforeMs(idleTimeoutMs, override, idleWarnLeadSeconds) {
   if (idleTimeoutMs <= 0) return 0;
   const maxLeadMs = Math.max(0, idleTimeoutMs - 1e3);
@@ -2473,6 +2482,7 @@ function useSessionLifecycle(input) {
     maxReconnectAttempts,
     autoRetryBusy = true,
     connectWatchdogSeconds,
+    readyTimeoutSeconds,
     requestOptions,
     onBehaviorChange
   } = input;
@@ -2483,17 +2493,27 @@ function useSessionLifecycle(input) {
   const reconnectPolicyRef = useRef(reconnectPolicy);
   reconnectPolicyRef.current = reconnectPolicy;
   const connectWatchdogMs = typeof connectWatchdogSeconds === "number" && Number.isFinite(connectWatchdogSeconds) ? Math.max(0, Math.floor(connectWatchdogSeconds)) * 1e3 : DEFAULT_CONNECT_WATCHDOG_SECONDS * 1e3;
+  const readyTimeoutMs = typeof readyTimeoutSeconds === "number" && Number.isFinite(readyTimeoutSeconds) && readyTimeoutSeconds > 0 ? Math.max(1, Math.floor(readyTimeoutSeconds)) * 1e3 : DEFAULT_READY_TIMEOUT_SECONDS * 1e3;
   const [userEnded, setUserEnded] = useState(false);
   const userEndedRef = useRef(false);
+  const [readinessFailed, setReadinessFailed] = useState(false);
+  const readinessFailureRef = useRef(null);
+  const readinessRef = useRef(null);
+  const readyGrantRef = useRef(null);
+  const agentWaitRef = useRef(null);
   const phaseRef = useRef({ kind: "idle" });
   const grantState = useLiveKitAvatarGrant({
     client,
     session,
-    active: active && !userEnded,
+    active: active && !userEnded && !readinessFailed,
     autoRetryBusy,
     requestOptions
   });
   const capacity = grantState.capacity;
+  const grantId = grantState.grant?.session_id ?? null;
+  const grantIdRef = useRef(null);
+  grantIdRef.current = grantId;
+  const retiredGrantRef = useRef(null);
   const [recovery, setRecovery] = useState({ kind: "connected" });
   const recoveryRef = useRef(recovery);
   recoveryRef.current = recovery;
@@ -2516,8 +2536,19 @@ function useSessionLifecycle(input) {
     grantIdleSeconds: grantState.grant?.idle_timeout_seconds ?? 0
   });
   const warnAtMs = resolveWarnBeforeMs(idleTimeoutMs, warnBeforeMs, idleWarnLeadSeconds);
-  const [agentPresent, setAgentPresentState] = useState(false);
-  const [connected, setConnected] = useState(false);
+  const [agentObservation, setAgentObservation] = useState({ grantId: null, present: false });
+  const [connectionObservation, setConnectionObservation] = useState({ grantId: null, connected: false });
+  const agentPresent = agentObservation.grantId === grantId && agentObservation.present;
+  const connected = connectionObservation.grantId === grantId && connectionObservation.connected;
+  connectedRef.current = connected;
+  const setAgentPresentState = useCallback((present) => {
+    const owner = grantIdRef.current;
+    setAgentObservation((prev) => prev.grantId === owner && prev.present === present ? prev : { grantId: owner, present });
+  }, []);
+  const setConnected = useCallback((value) => {
+    const owner = grantIdRef.current;
+    setConnectionObservation((prev) => prev.grantId === owner && prev.connected === value ? prev : { grantId: owner, connected: value });
+  }, []);
   const lastActivityRef = useRef(Date.now());
   const leaveRoomRef = useRef(null);
   const [, setClockTick] = useState(0);
@@ -2534,7 +2565,11 @@ function useSessionLifecycle(input) {
     refreshBaselineCapacityRef.current = null;
     attemptRef.current = 0;
     setAttempt(0);
-    setRecovery(userEndedRef.current ? { kind: "ended", reason: "user" } : { kind: "connected" });
+    readinessRef.current = null;
+    readyGrantRef.current = null;
+    agentWaitRef.current = null;
+    retiredGrantRef.current = null;
+    setRecovery(userEndedRef.current ? { kind: "ended", reason: "user" } : readinessFailureRef.current ? { kind: "ended", reason: "error", code: readinessFailureRef.current } : { kind: "connected" });
     setConnected(false);
     setAgentPresentState(false);
     lastActivityRef.current = Date.now();
@@ -2543,26 +2578,33 @@ function useSessionLifecycle(input) {
     if (active) return;
     userEndedRef.current = false;
     setUserEnded(false);
+    readinessFailureRef.current = null;
+    setReadinessFailed(false);
     reset();
   }, [active, reset]);
   const markActivity = useCallback(() => {
+    if (grantId === null || grantIdRef.current !== grantId) return;
     lastActivityRef.current = Date.now();
     setClockTick((value) => value + 1);
-  }, []);
+  }, [grantId]);
   const stayConnected = useCallback(() => {
+    if (grantId === null || grantIdRef.current !== grantId) return;
     if (!connectedRef.current) return;
     lastActivityRef.current = Date.now();
     setClockTick((value) => value + 1);
-  }, []);
+  }, [grantId]);
   const setAgentPresent = useCallback((present) => {
-    setAgentPresentState((prev) => {
-      if (present && !prev) lastActivityRef.current = Date.now();
-      return present;
+    if (grantId === null || grantIdRef.current !== grantId) return;
+    if (userEndedRef.current || readinessFailureRef.current || retiredGrantRef.current !== null && retiredGrantRef.current === grantIdRef.current) return;
+    setAgentObservation((prev) => {
+      if (present && (prev.grantId !== grantId || !prev.present)) lastActivityRef.current = Date.now();
+      return prev.grantId === grantId && prev.present === present ? prev : { grantId, present };
     });
-  }, []);
+  }, [grantId]);
   const registerLeaveRoom = useCallback((leave) => {
+    if (grantId === null || grantIdRef.current !== grantId) return;
     leaveRoomRef.current = leave;
-  }, []);
+  }, [grantId]);
   const endIdle = useCallback(() => {
     if (!connectedRef.current) return;
     clearTimer();
@@ -2574,24 +2616,25 @@ function useSessionLifecycle(input) {
     leaveRoomRef.current?.();
   }, [clearTimer]);
   const onConnected = useCallback(() => {
-    if (userEndedRef.current) return;
+    if (grantId === null || grantIdRef.current !== grantId) return;
+    if (userEndedRef.current || readinessFailureRef.current || retiredGrantRef.current !== null && retiredGrantRef.current === grantIdRef.current) return;
     clearTimer();
     connectedRef.current = true;
     manualReconnectPendingRef.current = false;
     refreshBaselineCapacityRef.current = null;
     setConnected(true);
-    attemptRef.current = 0;
-    setAttempt(0);
+    if (readinessRef.current) readinessRef.current.sawTransport = true;
     setRecovery({ kind: "connected" });
     lastActivityRef.current = Date.now();
-  }, [clearTimer]);
+  }, [clearTimer, grantId]);
   const onDisconnected = useCallback(
     (reason) => {
-      if (!active || userEndedRef.current) return;
+      if (grantId === null || grantIdRef.current !== grantId) return;
+      if (!active || userEndedRef.current || readinessFailureRef.current) return;
       const action = disconnectAction(reason, connectedRef.current);
       if (action === "noop") return;
       if (action === "reset") {
-        if (recoveryRef.current.kind === "refreshing") return;
+        if (recoveryRef.current.kind === "refreshing" || recoveryRef.current.kind === "reconnecting") return;
         reset();
         return;
       }
@@ -2608,11 +2651,12 @@ function useSessionLifecycle(input) {
       refreshBaselineCapacityRef.current = null;
       setRecovery({ kind: "reconnecting", attempt: attemptRef.current });
     },
-    [active, reset]
+    [active, reset, grantId]
   );
   const onConnectionError = useCallback(
     (error) => {
-      if (!active || userEndedRef.current || !isRecoverableConnectionError(error)) return;
+      if (grantId === null || grantIdRef.current !== grantId) return;
+      if (!active || userEndedRef.current || readinessFailureRef.current || !isRecoverableConnectionError(error)) return;
       connectedRef.current = false;
       setConnected(false);
       setAgentPresentState(false);
@@ -2623,7 +2667,7 @@ function useSessionLifecycle(input) {
         return { kind: "reconnecting", attempt: attemptRef.current };
       });
     },
-    [active]
+    [active, grantId]
   );
   useEffect(() => {
     if (capacity.kind === "error" && recovery.kind === "connected") manualReconnectPendingRef.current = false;
@@ -2633,11 +2677,12 @@ function useSessionLifecycle(input) {
     const baseline = refreshBaselineCapacityRef.current;
     if (baseline?.kind === "error" && baseline.error === capacity.error) return;
     refreshBaselineCapacityRef.current = null;
-    setRecovery({ kind: "reconnecting", attempt: recovery.attempt });
+    setRecovery({ kind: "reconnecting", attempt: recovery.attempt, ...recovery.reason ? { reason: recovery.reason } : {} });
   }, [capacity, recovery]);
   const onConnectionStateChange = useCallback(
     (state) => {
-      if (!active || userEndedRef.current) return;
+      if (grantId === null || grantIdRef.current !== grantId) return;
+      if (!active || userEndedRef.current || readinessFailureRef.current) return;
       if (state === "connected") {
         onConnected();
         return;
@@ -2651,14 +2696,78 @@ function useSessionLifecycle(input) {
         }
       }
     },
-    [active, onConnected]
+    [active, onConnected, grantId]
   );
+  useEffect(() => {
+    if (!active || userEnded || readinessFailed || !connected || !agentPresent || !grantState.grant) return;
+    readyGrantRef.current = grantState.grant.session_id;
+    readinessRef.current = null;
+    agentWaitRef.current = null;
+    attemptRef.current = 0;
+    setAttempt(0);
+  }, [active, userEnded, readinessFailed, connected, agentPresent, grantState.grant]);
+  const failReadiness = useCallback((code) => {
+    if (userEndedRef.current || readinessFailureRef.current) return;
+    readinessFailureRef.current = code;
+    clearTimer();
+    connectedRef.current = false;
+    manualReconnectPendingRef.current = false;
+    refreshBaselineCapacityRef.current = null;
+    const ended = { kind: "ended", reason: "error", code };
+    recoveryRef.current = ended;
+    setRecovery(ended);
+    setConnected(false);
+    setAgentPresentState(false);
+    releaseRef.current("disconnected");
+    setReadinessFailed(true);
+    leaveRoomRef.current?.();
+  }, [clearTimer]);
+  useEffect(() => {
+    if (!active || userEnded || readinessFailed) return;
+    if (recovery.kind === "ended" || recovery.kind === "failed") return;
+    if (grantState.grant && readyGrantRef.current === grantState.grant.session_id) return;
+    if (!readinessRef.current && grantState.grant) {
+      readinessRef.current = { startedAt: Date.now(), sawTransport: connected };
+    }
+    const budget = readinessRef.current;
+    if (!budget) return;
+    const timer = window.setTimeout(() => {
+      if (readinessRef.current !== budget) return;
+      failReadiness(budget.sawTransport ? "agent_timeout" : "connection_timeout");
+    }, Math.max(0, budget.startedAt + readyTimeoutMs - Date.now()));
+    return () => window.clearTimeout(timer);
+  }, [active, userEnded, readinessFailed, connected, agentPresent, grantState.grant, recovery.kind, readyTimeoutMs, failReadiness]);
+  useEffect(() => {
+    const sessionId = grantState.grant?.session_id;
+    if (!active || userEnded || readinessFailed || !sessionId || readyGrantRef.current === sessionId || agentPresent) return;
+    if (recovery.kind === "reconnecting" || recovery.kind === "failed" || recovery.kind === "ended") return;
+    if (agentWaitRef.current?.sessionId !== sessionId) {
+      if (!connected) return;
+      agentWaitRef.current = { sessionId, startedAt: Date.now() };
+    }
+    const wait = agentWaitRef.current;
+    if (connectWatchdogMs <= 0) return;
+    const timer = window.setTimeout(() => {
+      if (agentWaitRef.current !== wait || readinessFailureRef.current || userEndedRef.current) return;
+      retiredGrantRef.current = sessionId;
+      connectedRef.current = false;
+      setConnected(false);
+      setAgentPresentState(false);
+      const next = { kind: "reconnecting", attempt: attemptRef.current, reason: "agent_timeout" };
+      recoveryRef.current = next;
+      setRecovery(next);
+      releaseRef.current("disconnected");
+      leaveRoomRef.current?.();
+    }, Math.max(0, wait.startedAt + connectWatchdogMs - Date.now()));
+    return () => window.clearTimeout(timer);
+  }, [active, userEnded, readinessFailed, connected, agentPresent, grantState.grant, recovery.kind, connectWatchdogMs]);
   useEffect(() => {
     if (!active || connected || connectWatchdogMs <= 0) return;
     if (grantState.status !== "ready" || !grantState.grant) return;
     if (recovery.kind === "failed" || recovery.kind === "ended") return;
     if (recovery.kind === "in-place-reconnecting") return;
     const timer = window.setTimeout(() => {
+      if (readinessFailureRef.current || userEndedRef.current) return;
       releaseRef.current("disconnected");
       setRecovery({ kind: "reconnecting", attempt: attemptRef.current });
     }, connectWatchdogMs);
@@ -2668,6 +2777,10 @@ function useSessionLifecycle(input) {
     if (!active || !needsFreshGrant(recovery)) return;
     const step2 = retryStep(attemptRef.current, reconnectPolicyRef.current);
     if (step2.kind === "give-up") {
+      if (readinessRef.current) {
+        failReadiness(readinessRef.current.sawTransport ? "agent_timeout" : "connection_timeout");
+        return;
+      }
       manualReconnectPendingRef.current = false;
       refreshBaselineCapacityRef.current = null;
       releaseRef.current("disconnected");
@@ -2676,15 +2789,16 @@ function useSessionLifecycle(input) {
     }
     timerRef.current = window.setTimeout(() => {
       timerRef.current = null;
+      if (readinessFailureRef.current || userEndedRef.current) return;
       attemptRef.current = step2.attempt;
       setAttempt(step2.attempt);
       refreshBaselineCapacityRef.current = capacityRef.current;
       releaseRef.current("superseded");
-      setRecovery({ kind: "refreshing", attempt: step2.attempt });
+      setRecovery({ kind: "refreshing", attempt: step2.attempt, ...recovery.reason ? { reason: recovery.reason } : {} });
       refreshRef.current();
     }, step2.delayMs);
     return clearTimer;
-  }, [recovery.kind, active, attempt, clearTimer]);
+  }, [recovery.kind, active, attempt, clearTimer, failReadiness]);
   const end = useCallback(() => {
     if (!active || userEndedRef.current || phaseRef.current.kind === "ended") return;
     userEndedRef.current = true;
@@ -2701,6 +2815,13 @@ function useSessionLifecycle(input) {
   }, [active, clearTimer]);
   const reconnect = useCallback(() => {
     if (!active) return;
+    if (readinessFailureRef.current) {
+      readinessFailureRef.current = null;
+      setReadinessFailed(false);
+      reset();
+      manualReconnectPendingRef.current = true;
+      return;
+    }
     if (userEndedRef.current) {
       userEndedRef.current = false;
       setUserEnded(false);
@@ -2711,6 +2832,12 @@ function useSessionLifecycle(input) {
     if (manualReconnectPendingRef.current || recovery.kind === "in-place-reconnecting") return;
     manualReconnectPendingRef.current = true;
     clearTimer();
+    readinessRef.current = null;
+    agentWaitRef.current = null;
+    readyGrantRef.current = null;
+    connectedRef.current = false;
+    setConnected(false);
+    setAgentPresentState(false);
     attemptRef.current = 0;
     setAttempt(0);
     refreshBaselineCapacityRef.current = capacityRef.current;
@@ -2830,6 +2957,7 @@ function SessionLifecycleRoomBridge({
   const assistant = useVoiceAssistant();
   const transcriptions = useTranscriptions();
   const room = useRoomContext();
+  const roomMatchesGrant = lifecycle.grant === void 0 || lifecycle.grant !== null && room.name === lifecycle.grant.room_name;
   useCallMedia(room, {
     setMicrophoneFacts,
     setAudioPlayback,
@@ -2983,11 +3111,11 @@ function SessionLifecycleRoomBridge({
     detailsEnabled ? video?.publication : void 0
   ]);
   useEffect(() => {
-    onConnectionStateChange(connectionState);
-  }, [connectionState, onConnectionStateChange]);
+    if (roomMatchesGrant) onConnectionStateChange(connectionState);
+  }, [connectionState, onConnectionStateChange, roomMatchesGrant]);
   useEffect(() => {
-    setAgentPresent(agentPresent);
-  }, [agentPresent, setAgentPresent]);
+    if (roomMatchesGrant) setAgentPresent(agentPresent);
+  }, [agentPresent, setAgentPresent, roomMatchesGrant]);
   useEffect(() => {
     const active = isCallActivity({
       assistantState,
@@ -3695,4 +3823,4 @@ function createProxyClient(options) {
   };
 }
 
-export { AdaptivePlayoutController, AvatarVideoSurface, DEFAULT_APPROACHING_END_LEAD_SECONDS, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, 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, RECONNECT_BACKOFF_MS, RealtimeAvatarLiveKitRoom, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, isNativeLiveTrackSubscribed, knownBehaviorStates, mapTurnState, readInboundRtp, sessionBehaviorSchema, sessionClipSchema, splitCallTranscript, useAvatarAdaptivePlayoutDelay, useAvatarCamera, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useLiveKitAvatarGrant, useLiveTrackProducing, useMicLease, useRealtimeAvatarAudioSession, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };
+export { AdaptivePlayoutController, AvatarVideoSurface, DEFAULT_APPROACHING_END_LEAD_SECONDS, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, 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_READY_TIMEOUT_SECONDS, DEFAULT_TURN_TIMEOUT_SECONDS, MAX_RECONNECT_ATTEMPTS, MAX_SESSION_INSTRUCTIONS_CHARS, RECONNECT_BACKOFF_MS, RealtimeAvatarLiveKitRoom, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, isNativeLiveTrackSubscribed, knownBehaviorStates, mapTurnState, readInboundRtp, sessionBehaviorSchema, sessionClipSchema, splitCallTranscript, useAvatarAdaptivePlayoutDelay, useAvatarCamera, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useLiveKitAvatarGrant, useLiveTrackProducing, useMicLease, useRealtimeAvatarAudioSession, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };

package/dist/react.d.ts

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

package/dist/react.js

@@ -1074,6 +1074,8 @@ function RealtimeAvatarLiveKitRoom(props) {
     LiveKitRoom,
     {
       ...roomProps,
+      // A new grant owns a new room and bridge; an old room must not report its agent into it.
+      key: grant?.session_id ?? "no-session",
       serverUrl: grant?.livekit_url,
       token: grant?.participant_token,
       connect: shouldConnect,
@@ -3019,7 +3021,8 @@ function lifecyclePhaseFrom(args) {
       kind: "reconnectable",
       reconnecting: true,
       attempt: recovery.attempt,
-      strategy: "fresh-grant"
+      strategy: "fresh-grant",
+      ...recovery.reason ? { reason: recovery.reason } : {}
     };
   }
   if (recovery.kind === "failed") {
@@ -3027,11 +3030,16 @@ function lifecyclePhaseFrom(args) {
       kind: "reconnectable",
       reconnecting: false,
       attempt: MAX_RECONNECT_ATTEMPTS,
-      strategy: "fresh-grant"
+      strategy: "fresh-grant",
+      ...recovery.reason ? { reason: recovery.reason } : {}
     };
   }
   if (recovery.kind === "ended") {
-    return recovery.reason ? { kind: "ended", reason: recovery.reason } : { kind: "ended" };
+    return {
+      kind: "ended",
+      ...recovery.reason ? { reason: recovery.reason } : {},
+      ...recovery.code ? { code: recovery.code } : {}
+    };
   }
   switch (capacity.kind) {
     case "idle":
@@ -3044,7 +3052,7 @@ function lifecyclePhaseFrom(args) {
       return { kind: "ended", reason: "error" };
     case "active": {
       if (!connected || !agentPresent) {
-        return { kind: "connecting", grant: capacity.grant };
+        return { kind: "connecting", grant: capacity.grant, waitingFor: connected ? "agent" : "transport" };
       }
       if (idle.kind === "idle-warning") {
         return { kind: "idle-warning", secondsRemaining: idle.secondsRemaining, deadlineAt: idle.deadlineAt };
@@ -3072,6 +3080,7 @@ function resolveIdleTimeoutMs(args) {
   return DEFAULT_IDLE_SECONDS * 1e3;
 }
 var DEFAULT_CONNECT_WATCHDOG_SECONDS = 12;
+var DEFAULT_READY_TIMEOUT_SECONDS = 30;
 function resolveWarnBeforeMs(idleTimeoutMs, override, idleWarnLeadSeconds) {
   if (idleTimeoutMs <= 0) return 0;
   const maxLeadMs = Math.max(0, idleTimeoutMs - 1e3);
@@ -3097,6 +3106,7 @@ function useSessionLifecycle(input) {
     maxReconnectAttempts,
     autoRetryBusy = true,
     connectWatchdogSeconds,
+    readyTimeoutSeconds,
     requestOptions,
     onBehaviorChange
   } = input;
@@ -3107,17 +3117,27 @@ function useSessionLifecycle(input) {
   const reconnectPolicyRef = useRef(reconnectPolicy);
   reconnectPolicyRef.current = reconnectPolicy;
   const connectWatchdogMs = typeof connectWatchdogSeconds === "number" && Number.isFinite(connectWatchdogSeconds) ? Math.max(0, Math.floor(connectWatchdogSeconds)) * 1e3 : DEFAULT_CONNECT_WATCHDOG_SECONDS * 1e3;
+  const readyTimeoutMs = typeof readyTimeoutSeconds === "number" && Number.isFinite(readyTimeoutSeconds) && readyTimeoutSeconds > 0 ? Math.max(1, Math.floor(readyTimeoutSeconds)) * 1e3 : DEFAULT_READY_TIMEOUT_SECONDS * 1e3;
   const [userEnded, setUserEnded] = useState(false);
   const userEndedRef = useRef(false);
+  const [readinessFailed, setReadinessFailed] = useState(false);
+  const readinessFailureRef = useRef(null);
+  const readinessRef = useRef(null);
+  const readyGrantRef = useRef(null);
+  const agentWaitRef = useRef(null);
   const phaseRef = useRef({ kind: "idle" });
   const grantState = useLiveKitAvatarGrant({
     client,
     session,
-    active: active && !userEnded,
+    active: active && !userEnded && !readinessFailed,
     autoRetryBusy,
     requestOptions
   });
   const capacity = grantState.capacity;
+  const grantId = grantState.grant?.session_id ?? null;
+  const grantIdRef = useRef(null);
+  grantIdRef.current = grantId;
+  const retiredGrantRef = useRef(null);
   const [recovery, setRecovery] = useState({ kind: "connected" });
   const recoveryRef = useRef(recovery);
   recoveryRef.current = recovery;
@@ -3140,8 +3160,19 @@ function useSessionLifecycle(input) {
     grantIdleSeconds: grantState.grant?.idle_timeout_seconds ?? 0
   });
   const warnAtMs = resolveWarnBeforeMs(idleTimeoutMs, warnBeforeMs, idleWarnLeadSeconds);
-  const [agentPresent, setAgentPresentState] = useState(false);
-  const [connected, setConnected] = useState(false);
+  const [agentObservation, setAgentObservation] = useState({ grantId: null, present: false });
+  const [connectionObservation, setConnectionObservation] = useState({ grantId: null, connected: false });
+  const agentPresent = agentObservation.grantId === grantId && agentObservation.present;
+  const connected = connectionObservation.grantId === grantId && connectionObservation.connected;
+  connectedRef.current = connected;
+  const setAgentPresentState = useCallback((present) => {
+    const owner = grantIdRef.current;
+    setAgentObservation((prev) => prev.grantId === owner && prev.present === present ? prev : { grantId: owner, present });
+  }, []);
+  const setConnected = useCallback((value) => {
+    const owner = grantIdRef.current;
+    setConnectionObservation((prev) => prev.grantId === owner && prev.connected === value ? prev : { grantId: owner, connected: value });
+  }, []);
   const lastActivityRef = useRef(Date.now());
   const leaveRoomRef = useRef(null);
   const [, setClockTick] = useState(0);
@@ -3158,7 +3189,11 @@ function useSessionLifecycle(input) {
     refreshBaselineCapacityRef.current = null;
     attemptRef.current = 0;
     setAttempt(0);
-    setRecovery(userEndedRef.current ? { kind: "ended", reason: "user" } : { kind: "connected" });
+    readinessRef.current = null;
+    readyGrantRef.current = null;
+    agentWaitRef.current = null;
+    retiredGrantRef.current = null;
+    setRecovery(userEndedRef.current ? { kind: "ended", reason: "user" } : readinessFailureRef.current ? { kind: "ended", reason: "error", code: readinessFailureRef.current } : { kind: "connected" });
     setConnected(false);
     setAgentPresentState(false);
     lastActivityRef.current = Date.now();
@@ -3167,26 +3202,33 @@ function useSessionLifecycle(input) {
     if (active) return;
     userEndedRef.current = false;
     setUserEnded(false);
+    readinessFailureRef.current = null;
+    setReadinessFailed(false);
     reset();
   }, [active, reset]);
   const markActivity = useCallback(() => {
+    if (grantId === null || grantIdRef.current !== grantId) return;
     lastActivityRef.current = Date.now();
     setClockTick((value) => value + 1);
-  }, []);
+  }, [grantId]);
   const stayConnected = useCallback(() => {
+    if (grantId === null || grantIdRef.current !== grantId) return;
     if (!connectedRef.current) return;
     lastActivityRef.current = Date.now();
     setClockTick((value) => value + 1);
-  }, []);
+  }, [grantId]);
   const setAgentPresent = useCallback((present) => {
-    setAgentPresentState((prev) => {
-      if (present && !prev) lastActivityRef.current = Date.now();
-      return present;
+    if (grantId === null || grantIdRef.current !== grantId) return;
+    if (userEndedRef.current || readinessFailureRef.current || retiredGrantRef.current !== null && retiredGrantRef.current === grantIdRef.current) return;
+    setAgentObservation((prev) => {
+      if (present && (prev.grantId !== grantId || !prev.present)) lastActivityRef.current = Date.now();
+      return prev.grantId === grantId && prev.present === present ? prev : { grantId, present };
     });
-  }, []);
+  }, [grantId]);
   const registerLeaveRoom = useCallback((leave) => {
+    if (grantId === null || grantIdRef.current !== grantId) return;
     leaveRoomRef.current = leave;
-  }, []);
+  }, [grantId]);
   const endIdle = useCallback(() => {
     if (!connectedRef.current) return;
     clearTimer();
@@ -3198,24 +3240,25 @@ function useSessionLifecycle(input) {
     leaveRoomRef.current?.();
   }, [clearTimer]);
   const onConnected = useCallback(() => {
-    if (userEndedRef.current) return;
+    if (grantId === null || grantIdRef.current !== grantId) return;
+    if (userEndedRef.current || readinessFailureRef.current || retiredGrantRef.current !== null && retiredGrantRef.current === grantIdRef.current) return;
     clearTimer();
     connectedRef.current = true;
     manualReconnectPendingRef.current = false;
     refreshBaselineCapacityRef.current = null;
     setConnected(true);
-    attemptRef.current = 0;
-    setAttempt(0);
+    if (readinessRef.current) readinessRef.current.sawTransport = true;
     setRecovery({ kind: "connected" });
     lastActivityRef.current = Date.now();
-  }, [clearTimer]);
+  }, [clearTimer, grantId]);
   const onDisconnected = useCallback(
     (reason) => {
-      if (!active || userEndedRef.current) return;
+      if (grantId === null || grantIdRef.current !== grantId) return;
+      if (!active || userEndedRef.current || readinessFailureRef.current) return;
       const action = disconnectAction(reason, connectedRef.current);
       if (action === "noop") return;
       if (action === "reset") {
-        if (recoveryRef.current.kind === "refreshing") return;
+        if (recoveryRef.current.kind === "refreshing" || recoveryRef.current.kind === "reconnecting") return;
         reset();
         return;
       }
@@ -3232,11 +3275,12 @@ function useSessionLifecycle(input) {
       refreshBaselineCapacityRef.current = null;
       setRecovery({ kind: "reconnecting", attempt: attemptRef.current });
     },
-    [active, reset]
+    [active, reset, grantId]
   );
   const onConnectionError = useCallback(
     (error) => {
-      if (!active || userEndedRef.current || !isRecoverableConnectionError(error)) return;
+      if (grantId === null || grantIdRef.current !== grantId) return;
+      if (!active || userEndedRef.current || readinessFailureRef.current || !isRecoverableConnectionError(error)) return;
       connectedRef.current = false;
       setConnected(false);
       setAgentPresentState(false);
@@ -3247,7 +3291,7 @@ function useSessionLifecycle(input) {
         return { kind: "reconnecting", attempt: attemptRef.current };
       });
     },
-    [active]
+    [active, grantId]
   );
   useEffect(() => {
     if (capacity.kind === "error" && recovery.kind === "connected") manualReconnectPendingRef.current = false;
@@ -3257,11 +3301,12 @@ function useSessionLifecycle(input) {
     const baseline = refreshBaselineCapacityRef.current;
     if (baseline?.kind === "error" && baseline.error === capacity.error) return;
     refreshBaselineCapacityRef.current = null;
-    setRecovery({ kind: "reconnecting", attempt: recovery.attempt });
+    setRecovery({ kind: "reconnecting", attempt: recovery.attempt, ...recovery.reason ? { reason: recovery.reason } : {} });
   }, [capacity, recovery]);
   const onConnectionStateChange = useCallback(
     (state) => {
-      if (!active || userEndedRef.current) return;
+      if (grantId === null || grantIdRef.current !== grantId) return;
+      if (!active || userEndedRef.current || readinessFailureRef.current) return;
       if (state === "connected") {
         onConnected();
         return;
@@ -3275,14 +3320,78 @@ function useSessionLifecycle(input) {
         }
       }
     },
-    [active, onConnected]
+    [active, onConnected, grantId]
   );
+  useEffect(() => {
+    if (!active || userEnded || readinessFailed || !connected || !agentPresent || !grantState.grant) return;
+    readyGrantRef.current = grantState.grant.session_id;
+    readinessRef.current = null;
+    agentWaitRef.current = null;
+    attemptRef.current = 0;
+    setAttempt(0);
+  }, [active, userEnded, readinessFailed, connected, agentPresent, grantState.grant]);
+  const failReadiness = useCallback((code) => {
+    if (userEndedRef.current || readinessFailureRef.current) return;
+    readinessFailureRef.current = code;
+    clearTimer();
+    connectedRef.current = false;
+    manualReconnectPendingRef.current = false;
+    refreshBaselineCapacityRef.current = null;
+    const ended = { kind: "ended", reason: "error", code };
+    recoveryRef.current = ended;
+    setRecovery(ended);
+    setConnected(false);
+    setAgentPresentState(false);
+    releaseRef.current("disconnected");
+    setReadinessFailed(true);
+    leaveRoomRef.current?.();
+  }, [clearTimer]);
+  useEffect(() => {
+    if (!active || userEnded || readinessFailed) return;
+    if (recovery.kind === "ended" || recovery.kind === "failed") return;
+    if (grantState.grant && readyGrantRef.current === grantState.grant.session_id) return;
+    if (!readinessRef.current && grantState.grant) {
+      readinessRef.current = { startedAt: Date.now(), sawTransport: connected };
+    }
+    const budget = readinessRef.current;
+    if (!budget) return;
+    const timer = window.setTimeout(() => {
+      if (readinessRef.current !== budget) return;
+      failReadiness(budget.sawTransport ? "agent_timeout" : "connection_timeout");
+    }, Math.max(0, budget.startedAt + readyTimeoutMs - Date.now()));
+    return () => window.clearTimeout(timer);
+  }, [active, userEnded, readinessFailed, connected, agentPresent, grantState.grant, recovery.kind, readyTimeoutMs, failReadiness]);
+  useEffect(() => {
+    const sessionId = grantState.grant?.session_id;
+    if (!active || userEnded || readinessFailed || !sessionId || readyGrantRef.current === sessionId || agentPresent) return;
+    if (recovery.kind === "reconnecting" || recovery.kind === "failed" || recovery.kind === "ended") return;
+    if (agentWaitRef.current?.sessionId !== sessionId) {
+      if (!connected) return;
+      agentWaitRef.current = { sessionId, startedAt: Date.now() };
+    }
+    const wait = agentWaitRef.current;
+    if (connectWatchdogMs <= 0) return;
+    const timer = window.setTimeout(() => {
+      if (agentWaitRef.current !== wait || readinessFailureRef.current || userEndedRef.current) return;
+      retiredGrantRef.current = sessionId;
+      connectedRef.current = false;
+      setConnected(false);
+      setAgentPresentState(false);
+      const next = { kind: "reconnecting", attempt: attemptRef.current, reason: "agent_timeout" };
+      recoveryRef.current = next;
+      setRecovery(next);
+      releaseRef.current("disconnected");
+      leaveRoomRef.current?.();
+    }, Math.max(0, wait.startedAt + connectWatchdogMs - Date.now()));
+    return () => window.clearTimeout(timer);
+  }, [active, userEnded, readinessFailed, connected, agentPresent, grantState.grant, recovery.kind, connectWatchdogMs]);
   useEffect(() => {
     if (!active || connected || connectWatchdogMs <= 0) return;
     if (grantState.status !== "ready" || !grantState.grant) return;
     if (recovery.kind === "failed" || recovery.kind === "ended") return;
     if (recovery.kind === "in-place-reconnecting") return;
     const timer = window.setTimeout(() => {
+      if (readinessFailureRef.current || userEndedRef.current) return;
       releaseRef.current("disconnected");
       setRecovery({ kind: "reconnecting", attempt: attemptRef.current });
     }, connectWatchdogMs);
@@ -3292,6 +3401,10 @@ function useSessionLifecycle(input) {
     if (!active || !needsFreshGrant(recovery)) return;
     const step2 = retryStep(attemptRef.current, reconnectPolicyRef.current);
     if (step2.kind === "give-up") {
+      if (readinessRef.current) {
+        failReadiness(readinessRef.current.sawTransport ? "agent_timeout" : "connection_timeout");
+        return;
+      }
       manualReconnectPendingRef.current = false;
       refreshBaselineCapacityRef.current = null;
       releaseRef.current("disconnected");
@@ -3300,15 +3413,16 @@ function useSessionLifecycle(input) {
     }
     timerRef.current = window.setTimeout(() => {
       timerRef.current = null;
+      if (readinessFailureRef.current || userEndedRef.current) return;
       attemptRef.current = step2.attempt;
       setAttempt(step2.attempt);
       refreshBaselineCapacityRef.current = capacityRef.current;
       releaseRef.current("superseded");
-      setRecovery({ kind: "refreshing", attempt: step2.attempt });
+      setRecovery({ kind: "refreshing", attempt: step2.attempt, ...recovery.reason ? { reason: recovery.reason } : {} });
       refreshRef.current();
     }, step2.delayMs);
     return clearTimer;
-  }, [recovery.kind, active, attempt, clearTimer]);
+  }, [recovery.kind, active, attempt, clearTimer, failReadiness]);
   const end = useCallback(() => {
     if (!active || userEndedRef.current || phaseRef.current.kind === "ended") return;
     userEndedRef.current = true;
@@ -3325,6 +3439,13 @@ function useSessionLifecycle(input) {
   }, [active, clearTimer]);
   const reconnect = useCallback(() => {
     if (!active) return;
+    if (readinessFailureRef.current) {
+      readinessFailureRef.current = null;
+      setReadinessFailed(false);
+      reset();
+      manualReconnectPendingRef.current = true;
+      return;
+    }
     if (userEndedRef.current) {
       userEndedRef.current = false;
       setUserEnded(false);
@@ -3335,6 +3456,12 @@ function useSessionLifecycle(input) {
     if (manualReconnectPendingRef.current || recovery.kind === "in-place-reconnecting") return;
     manualReconnectPendingRef.current = true;
     clearTimer();
+    readinessRef.current = null;
+    agentWaitRef.current = null;
+    readyGrantRef.current = null;
+    connectedRef.current = false;
+    setConnected(false);
+    setAgentPresentState(false);
     attemptRef.current = 0;
     setAttempt(0);
     refreshBaselineCapacityRef.current = capacityRef.current;
@@ -3454,6 +3581,7 @@ function SessionLifecycleRoomBridge({
   const assistant = useVoiceAssistant();
   const transcriptions = useTranscriptions();
   const room = useRoomContext();
+  const roomMatchesGrant = lifecycle.grant === void 0 || lifecycle.grant !== null && room.name === lifecycle.grant.room_name;
   useCallMedia(room, {
     setMicrophoneFacts,
     setAudioPlayback,
@@ -3607,11 +3735,11 @@ function SessionLifecycleRoomBridge({
     detailsEnabled ? video?.publication : void 0
   ]);
   useEffect(() => {
-    onConnectionStateChange(connectionState);
-  }, [connectionState, onConnectionStateChange]);
+    if (roomMatchesGrant) onConnectionStateChange(connectionState);
+  }, [connectionState, onConnectionStateChange, roomMatchesGrant]);
   useEffect(() => {
-    setAgentPresent(agentPresent);
-  }, [agentPresent, setAgentPresent]);
+    if (roomMatchesGrant) setAgentPresent(agentPresent);
+  }, [agentPresent, setAgentPresent, roomMatchesGrant]);
   useEffect(() => {
     const active = isCallActivity({
       assistantState,
@@ -4675,4 +4803,4 @@ function RecordingPlayer({ assets, className }) {
   ] });
 }
 
-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, RecordingPlayer, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, knownBehaviorStates, mapTurnState, readInboundRtp, sessionBehaviorSchema, sessionClipSchema, shouldReplayPendingTurn, splitCallTranscript, useAvatarAdaptivePlayoutDelay, useAvatarCall, useAvatarCamera, 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_READY_TIMEOUT_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, RecordingPlayer, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, knownBehaviorStates, mapTurnState, readInboundRtp, sessionBehaviorSchema, sessionClipSchema, shouldReplayPendingTurn, splitCallTranscript, useAvatarAdaptivePlayoutDelay, useAvatarCall, useAvatarCamera, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useCharacterTools, useLiveKitAvatarGrant, useMicLease, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };

package/dist/server.js

@@ -1,2 +1,2 @@
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript } from './chunk-NMJQEGYW.js';
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript } from './chunk-4IEGR75H.js';
 import './chunk-MCIXU6XP.js';

package/dist/tanstack-start.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-SUKZ77GL.js';
-import './chunk-NMJQEGYW.js';
+import { createProxyHandler } from './chunk-DOHZ365B.js';
+import './chunk-4IEGR75H.js';
 import './chunk-MCIXU6XP.js';
 
 // src/tanstack-start.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-avatar",
-  "version": "0.27.0",
+  "version": "0.27.1",
   "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",