realtime-avatar 0.6.0 → 0.7.0

package/README.md

@@ -25,6 +25,19 @@ return call.raw;   // relay to the browser byte-for-byte
 
 That is the whole server half. The client joins with the payload and renders her.
 
+New here? The [quickstart](https://realtimeavatar.ai/docs/quickstart) goes from an API key to a
+working call, and a [sandbox key](https://realtimeavatar.ai/signup) is free with no card. Mount
+the server half on your framework:
+[Next.js](https://realtimeavatar.ai/docs/nextjs) ·
+[Express](https://realtimeavatar.ai/docs/express) ·
+[Hono, Workers, Bun, Deno](https://realtimeavatar.ai/docs/hono) ·
+[TanStack Start](https://realtimeavatar.ai/docs/tanstack-start), and render it with
+[React or React Native](https://realtimeavatar.ai/docs/react).
+
+Using a coding agent? Point it at [`AGENTS.md`](../../AGENTS.md) and give it the
+[MCP server](https://realtimeavatar.ai/docs/mcp) so it can read your real avatar ids instead of
+inventing them.
+
 ---
 
 ## What you get
@@ -184,6 +197,14 @@ for building your own queue UI, and the zod schemas `sessionBehaviorSchema` / `s
 ## Docs and support
 
 - Full documentation: <https://realtimeavatar.ai/docs>
+- [Quickstart](https://realtimeavatar.ai/docs/quickstart) — key to a live call
+- [Authentication](https://realtimeavatar.ai/docs/authentication) — what belongs on your server, and why
+- [Calls](https://realtimeavatar.ai/docs/sessions) — what your server decides and what the client reports
+- [Creating an avatar](https://realtimeavatar.ai/docs/video) — one photo in, a moving character out
+- [Tool calling](https://realtimeavatar.ai/docs/tool-calling) — your handlers, your server, no hosted executor
+- [MCP server](https://realtimeavatar.ai/docs/mcp) — give a coding agent the account itself
+- [API reference](https://realtimeavatar.ai/docs/api-reference) · [OpenAPI 3.1](https://realtimeavatar.ai/openapi.json)
+- [Pricing](https://realtimeavatar.ai/pricing) — one meter, seconds on air
 - Issues and feature requests: this repo
 - The API is versioned at `/api/v1`; breaking changes get a new version, not a silent edit.
 

package/dist/{chunk-GKV42PSY.js → chunk-OP32WHW7.js}

@@ -43,7 +43,7 @@ function isTransient(cause) {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.7.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -542,6 +542,10 @@ function toUsageSessionPage(raw) {
     sessions: rows.filter(isRecord).map((row) => ({
       sessionId: String(row.sessionId ?? ""),
       avatarId: typeof row.avatarId === "string" ? row.avatarId : null,
+      // Added to the contract alongside avatarId so a usage row is readable without a
+      // second lookup. Defensive like its siblings: an older server that omits it
+      // yields null rather than the string "undefined".
+      avatarName: typeof row.avatarName === "string" ? row.avatarName : null,
       status: usageStatus(row.status),
       startedAt: typeof row.startedAt === "string" ? row.startedAt : null,
       endedAt: typeof row.endedAt === "string" ? row.endedAt : null,

package/dist/{chunk-JLQWZF6B.js → chunk-YRY3QUTC.js}

@@ -1,4 +1,4 @@
-import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-GKV42PSY.js';
+import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-OP32WHW7.js';
 
 // ../proxy/src/config.ts
 var json = (body, status = 200) => new Response(JSON.stringify(body), {

package/dist/express.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-CHrhuhYb.js';
-import './types-BeGuvyra.js';
+import { P as ProxyConfig } from './types-NKCoqM8E.js';
+import './types-ZfY6oxQY.js';
 
 type Expressish = {
     method: string;

package/dist/express.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-JLQWZF6B.js';
-import './chunk-GKV42PSY.js';
+import { createProxyHandler } from './chunk-YRY3QUTC.js';
+import './chunk-OP32WHW7.js';
 
 // ../proxy/src/express.ts
 function realtimeAvatarExpress(config) {

package/dist/hono.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-CHrhuhYb.js';
-import './types-BeGuvyra.js';
+import { P as ProxyConfig } from './types-NKCoqM8E.js';
+import './types-ZfY6oxQY.js';
 
 /**
  * Hono (and anything else built on Fetch handlers — Workers, Bun, Deno).

package/dist/hono.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-JLQWZF6B.js';
-import './chunk-GKV42PSY.js';
+import { createProxyHandler } from './chunk-YRY3QUTC.js';
+import './chunk-OP32WHW7.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 ClipDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as ClipSyncResult, h as AssetKind, i as Asset, j as ListSessionsOptions, U as UsageSessionPage, k as UsageSession, l as CreditBalance, T as TranscriptPayload } from './types-BeGuvyra.js';
-export { m as AvatarClip, n as CallConnection, o as CallQueued, p as ClipLibraryPlan, q as ClipSource, r as ContextMessage, s as EndCallReason, V as VideoPolicy, t as VideoState, u as isQueued } from './types-BeGuvyra.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 ClipDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as ClipSyncResult, h as AssetKind, i as Asset, j as ListSessionsOptions, U as UsageSessionPage, k as UsageSession, l as CreditBalance, T as TranscriptPayload } from './types-ZfY6oxQY.js';
+export { m as AvatarClip, n as CallConnection, o as CallQueued, p as ClipLibraryPlan, q as ClipSource, r as ContextMessage, s as EndCallReason, V as VideoPolicy, t as VideoState, u as isQueued } from './types-ZfY6oxQY.js';
 
 interface RealtimeAvatarOptions {
     /** `tic_live_…` or `tic_test_…`. Server-side only — never ship this to a browser. */

package/dist/index.js

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

package/dist/nextjs.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-CHrhuhYb.js';
-import './types-BeGuvyra.js';
+import { P as ProxyConfig } from './types-NKCoqM8E.js';
+import './types-ZfY6oxQY.js';
 
 /**
  * App Router. Mount at `app/api/realtime-avatar/[...path]/route.ts`:

package/dist/nextjs.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-JLQWZF6B.js';
-import './chunk-GKV42PSY.js';
+import { createProxyHandler } from './chunk-YRY3QUTC.js';
+import './chunk-OP32WHW7.js';
 
 // ../proxy/src/nextjs.ts
 function createRealtimeAvatarRoute(config) {

package/dist/{proxy-client-DylBmlgX.d.ts → proxy-client-BzblQMvg.d.ts}

@@ -112,7 +112,7 @@ type SessionBehavior = z.infer<typeof sessionBehaviorSchema>;
  * The cap the mint enforces on `instructions`. Exported so an app can budget its prompt
  * assembly against the real number instead of probing for it with a binary search.
  */
-declare const MAX_SESSION_INSTRUCTIONS_CHARS = 4000;
+declare const MAX_SESSION_INSTRUCTIONS_CHARS = 8000;
 declare const liveKitSessionRequestSchema: z.ZodObject<{
     avatarId: z.ZodString;
     backgroundId: z.ZodDefault<z.ZodString>;
@@ -1167,6 +1167,20 @@ type UseSessionLifecycleInput<T extends LLMProvider = LLMProvider> = {
     reconnectBackoffMs?: number[];
     /** 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}.
+     *
+     * 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
+     * a room that was never joined. Without this the slot is held until the PLATFORM's
+     * join timeout (75s at time of writing) — and on a plan whose ceiling is 1, that is
+     * 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).
+     */
+    connectWatchdogSeconds?: number;
     /** Forwarded to {@link useLiveKitAvatarGrant}. Defaults true (queue auto-retry). */
     autoRetryBusy?: boolean;
     requestOptions?: UseLiveKitAvatarGrantInput<T>["requestOptions"];

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-DylBmlgX.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_AVATAR_PLAYOUT_DELAY_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, E as EndReason, u as EndedEvent, v as ExtendResult, F as FishTtsModel, w as FreezeReadingFn, G as Governor, x as GovernorAction, y as GovernorConfig, z as GovernorSignal, H as GovernorState, I as GraceWindowClosedEvent, J as GraceWindowOpenEvent, K as GraceWindowState, M as IdleWarningEvent, N as InboundRtpCursor, O as InboundRtpReading, P as KnownBehaviorState, Q as LLMProvider, R as LLMSelection, S as LiveKitAvatarGrantState, T as LiveKitAvatarGrantStatus, U as LiveKitCapacityState, V as LiveKitConnectionStatus, W as LiveKitSessionRequest, X as LiveKitSessionStartResult, Y as MAX_RECONNECT_ATTEMPTS, Z as MAX_SESSION_INSTRUCTIONS_CHARS, _ as ProxyClientOptions, $ as QualityCap, a0 as RECONNECT_BACKOFF_MS, a1 as RealtimeAvatarRequestOptions, a2 as RealtimeSessionApi, a3 as RealtimeSessionMedia, a4 as RealtimeSessionRoomSinks, a5 as ReconnectPolicy, a6 as ReconnectingEvent, a7 as RecoveryState, a8 as RetryStep, a9 as SessionBehavior, aa as SessionClip, ab as SessionClocks, ac as SessionEndReason, ad as SessionLifecycleApi, ae as SessionLifecyclePhase, af as SessionLifecyclePhaseKind, ag as SessionLifecycleRoomBridge, ah as SessionLifecycleRoomBridgeProps, ai as SurfaceLayers, aj as TurnState, ak as TurnTimeoutEvent, al as UseAvatarQualityGovernorInput, am as UseLiveKitAvatarGrantInput, an as UseRealtimeSessionInput, ao as UseSessionLifecycleInput, ap as VoiceSpec, aq as VoiceSpecInput, ar as capacityErrorFromBusy, as as capacityStateFromGrant, at as createProxyClient, au as isNativeLiveTrackSubscribed, av as knownBehaviorStates, aw as mapTurnState, ax as readInboundRtp, ay as sessionBehaviorSchema, az as sessionClipSchema, aA as splitCallTranscript, aB as useAvatarAdaptivePlayoutDelay, aC as useAvatarPlayoutDelay, aD as useAvatarQualityGovernor, aE as useCallTranscript, aF as useLiveKitAvatarGrant, aG as useLiveTrackProducing, aH as useMicLease, aI as useRealtimeSession, aJ as useReleaseMicLeaseOnTrackEnded, aK as useSessionLifecycle } from './proxy-client-DylBmlgX.js';
+import { L as LiveKitSessionGrant, A as AvatarVideoFit } from './proxy-client-BzblQMvg.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_AVATAR_PLAYOUT_DELAY_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, E as EndReason, u as EndedEvent, v as ExtendResult, F as FishTtsModel, w as FreezeReadingFn, G as Governor, x as GovernorAction, y as GovernorConfig, z as GovernorSignal, H as GovernorState, I as GraceWindowClosedEvent, J as GraceWindowOpenEvent, K as GraceWindowState, M as IdleWarningEvent, N as InboundRtpCursor, O as InboundRtpReading, P as KnownBehaviorState, Q as LLMProvider, R as LLMSelection, S as LiveKitAvatarGrantState, T as LiveKitAvatarGrantStatus, U as LiveKitCapacityState, V as LiveKitConnectionStatus, W as LiveKitSessionRequest, X as LiveKitSessionStartResult, Y as MAX_RECONNECT_ATTEMPTS, Z as MAX_SESSION_INSTRUCTIONS_CHARS, _ as ProxyClientOptions, $ as QualityCap, a0 as RECONNECT_BACKOFF_MS, a1 as RealtimeAvatarRequestOptions, a2 as RealtimeSessionApi, a3 as RealtimeSessionMedia, a4 as RealtimeSessionRoomSinks, a5 as ReconnectPolicy, a6 as ReconnectingEvent, a7 as RecoveryState, a8 as RetryStep, a9 as SessionBehavior, aa as SessionClip, ab as SessionClocks, ac as SessionEndReason, ad as SessionLifecycleApi, ae as SessionLifecyclePhase, af as SessionLifecyclePhaseKind, ag as SessionLifecycleRoomBridge, ah as SessionLifecycleRoomBridgeProps, ai as SurfaceLayers, aj as TurnState, ak as TurnTimeoutEvent, al as UseAvatarQualityGovernorInput, am as UseLiveKitAvatarGrantInput, an as UseRealtimeSessionInput, ao as UseSessionLifecycleInput, ap as VoiceSpec, aq as VoiceSpecInput, ar as capacityErrorFromBusy, as as capacityStateFromGrant, at as createProxyClient, au as isNativeLiveTrackSubscribed, av as knownBehaviorStates, aw as mapTurnState, ax as readInboundRtp, ay as sessionBehaviorSchema, az as sessionClipSchema, aA as splitCallTranscript, aB as useAvatarAdaptivePlayoutDelay, aC as useAvatarPlayoutDelay, aD as useAvatarQualityGovernor, aE as useCallTranscript, aF as useLiveKitAvatarGrant, aG as useLiveTrackProducing, aH as useMicLease, aI as useRealtimeSession, aJ as useReleaseMicLeaseOnTrackEnded, aK as useSessionLifecycle } from './proxy-client-BzblQMvg.js';
 import { StyleProp, ViewStyle } from 'react-native';
 export { useChat, useConnectionState, useLocalParticipant, useRoomContext, useTrackToggle, useTranscriptions, useVoiceAssistant } from '@livekit/components-react';
 export { DisconnectReason, RemoteAudioTrack, RemoteTrack, RemoteVideoTrack, Room, RoomEvent, SendTextOptions, Track } from 'livekit-client';

package/dist/react-native.js

@@ -358,7 +358,12 @@ function useLiveKitAvatarGrant(input) {
       setState({ status: "requesting", grant: null, busy: null, error: null });
     }
     void client.createLiveKitSessionOrBusy(request, requestOptions).then((result) => {
-      if (cancelled) return;
+      if (cancelled) {
+        if (result.status !== "busy") {
+          void client.releaseLiveKitSession(result.grant.session_id, "superseded");
+        }
+        return;
+      }
       if (result.status === "busy") {
         queueTicketRef.current = result.busy.queue_ticket_id ?? queueTicketRef.current;
         setState({ status: "busy", grant: null, busy: result.busy, error: null });
@@ -1156,7 +1161,7 @@ var transcriptWebhookSchema = z.object({
 var clientMetadataSchema = z.record(z.string().min(1).max(64), z.string().max(200)).refine((value) => Object.keys(value).length <= 16, {
   message: "client_metadata carries at most 16 entries"
 });
-var MAX_SESSION_INSTRUCTIONS_CHARS = 4e3;
+var MAX_SESSION_INSTRUCTIONS_CHARS = 8e3;
 z.object({
   avatar_id: z.string().min(1).max(160).default(DEFAULT_AVATAR_ID),
   background_id: z.string().min(1).max(160).default(DEFAULT_BACKGROUND_ID),
@@ -1494,6 +1499,7 @@ function resolveIdleTimeoutMs(args) {
   if (grantIdleSeconds > 0) return grantIdleSeconds * 1e3;
   return DEFAULT_IDLE_SECONDS * 1e3;
 }
+var DEFAULT_CONNECT_WATCHDOG_SECONDS = 12;
 function resolveWarnBeforeMs(idleTimeoutMs, override, idleWarnLeadSeconds) {
   if (idleTimeoutMs <= 0) return 0;
   const maxLeadMs = Math.max(0, idleTimeoutMs - 1e3);
@@ -1518,6 +1524,7 @@ function useSessionLifecycle(input) {
     reconnectBackoffMs,
     maxReconnectAttempts,
     autoRetryBusy = true,
+    connectWatchdogSeconds,
     requestOptions,
     onBehaviorChange
   } = input;
@@ -1527,6 +1534,7 @@ 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 grantState = useLiveKitAvatarGrant({
     client,
     session,
@@ -1685,6 +1693,16 @@ function useSessionLifecycle(input) {
     },
     [active, onConnected]
   );
+  useEffect(() => {
+    if (!active || connected || connectWatchdogMs <= 0) return;
+    if (grantState.status !== "ready" || !grantState.grant) return;
+    if (recovery.kind === "failed" || recovery.kind === "ended") return;
+    const timer = window.setTimeout(() => {
+      releaseRef.current("disconnected");
+      setRecovery({ kind: "reconnecting", attempt: attemptRef.current });
+    }, connectWatchdogMs);
+    return () => window.clearTimeout(timer);
+  }, [active, connected, connectWatchdogMs, grantState.status, grantState.grant, recovery.kind]);
   useEffect(() => {
     if (!active || !needsFreshGrant(recovery)) return;
     const step2 = retryStep(attemptRef.current, reconnectPolicyRef.current);
@@ -1700,6 +1718,7 @@ function useSessionLifecycle(input) {
       attemptRef.current = step2.attempt;
       setAttempt(step2.attempt);
       refreshBaselineCapacityRef.current = capacityRef.current;
+      releaseRef.current("superseded");
       setRecovery({ kind: "refreshing", attempt: step2.attempt });
       refreshRef.current();
     }, step2.delayMs);
@@ -1712,6 +1731,7 @@ function useSessionLifecycle(input) {
     attemptRef.current = 0;
     setAttempt(0);
     refreshBaselineCapacityRef.current = capacityRef.current;
+    releaseRef.current("superseded");
     setRecovery({ kind: "refreshing", attempt: 0 });
     refreshRef.current();
   }, [active, clearTimer, recovery.kind]);

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode } from 'react';
-import { g as AvatarSessionClient, A as AvatarVideoFit } from './proxy-client-DylBmlgX.js';
-export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, aL as AvatarVideoSurface, aM 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_AVATAR_PLAYOUT_DELAY_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, E as EndReason, u as EndedEvent, v as ExtendResult, F as FishTtsModel, w as FreezeReadingFn, G as Governor, x as GovernorAction, y as GovernorConfig, z as GovernorSignal, H as GovernorState, I as GraceWindowClosedEvent, J as GraceWindowOpenEvent, K as GraceWindowState, M as IdleWarningEvent, N as InboundRtpCursor, O as InboundRtpReading, P as KnownBehaviorState, Q as LLMProvider, R as LLMSelection, S as LiveKitAvatarGrantState, T as LiveKitAvatarGrantStatus, U as LiveKitCapacityState, V as LiveKitConnectionStatus, W as LiveKitSessionRequest, X as LiveKitSessionStartResult, aN as LivePlaybackKeeper, Y as MAX_RECONNECT_ATTEMPTS, Z as MAX_SESSION_INSTRUCTIONS_CHARS, aO as MIC_LEASE_ENDED_TIMEOUT_MS, aP as MicLease, aQ as PlayableVideoElement, _ as ProxyClientOptions, $ as QualityCap, a0 as RECONNECT_BACKOFF_MS, aR as RealtimeAvatarCapacityError, aS as RealtimeAvatarLiveKitRoom, aT as RealtimeAvatarLiveKitRoomProps, a1 as RealtimeAvatarRequestOptions, a2 as RealtimeSessionApi, a3 as RealtimeSessionMedia, a4 as RealtimeSessionRoomSinks, a5 as ReconnectPolicy, a6 as ReconnectingEvent, a7 as RecoveryState, a8 as RetryStep, a9 as SessionBehavior, aa as SessionClip, ab as SessionClocks, ac as SessionEndReason, ad as SessionLifecycleApi, ae as SessionLifecyclePhase, af as SessionLifecyclePhaseKind, ag as SessionLifecycleRoomBridge, ah as SessionLifecycleRoomBridgeProps, ai as SurfaceLayers, aj as TurnState, ak as TurnTimeoutEvent, al as UseAvatarQualityGovernorInput, am as UseLiveKitAvatarGrantInput, an as UseRealtimeSessionInput, ao as UseSessionLifecycleInput, ap as VoiceSpec, aq as VoiceSpecInput, ar as capacityErrorFromBusy, as as capacityStateFromGrant, at as createProxyClient, av as knownBehaviorStates, aw as mapTurnState, ax as readInboundRtp, ay as sessionBehaviorSchema, az as sessionClipSchema, aU as shouldReplayPendingTurn, aA as splitCallTranscript, aB as useAvatarAdaptivePlayoutDelay, aC as useAvatarPlayoutDelay, aD as useAvatarQualityGovernor, aE as useCallTranscript, aF as useLiveKitAvatarGrant, aH as useMicLease, aI as useRealtimeSession, aJ as useReleaseMicLeaseOnTrackEnded, aK as useSessionLifecycle } from './proxy-client-DylBmlgX.js';
+import { g as AvatarSessionClient, A as AvatarVideoFit } from './proxy-client-BzblQMvg.js';
+export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, aL as AvatarVideoSurface, aM 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_AVATAR_PLAYOUT_DELAY_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, E as EndReason, u as EndedEvent, v as ExtendResult, F as FishTtsModel, w as FreezeReadingFn, G as Governor, x as GovernorAction, y as GovernorConfig, z as GovernorSignal, H as GovernorState, I as GraceWindowClosedEvent, J as GraceWindowOpenEvent, K as GraceWindowState, M as IdleWarningEvent, N as InboundRtpCursor, O as InboundRtpReading, P as KnownBehaviorState, Q as LLMProvider, R as LLMSelection, S as LiveKitAvatarGrantState, T as LiveKitAvatarGrantStatus, U as LiveKitCapacityState, V as LiveKitConnectionStatus, W as LiveKitSessionRequest, X as LiveKitSessionStartResult, aN as LivePlaybackKeeper, Y as MAX_RECONNECT_ATTEMPTS, Z as MAX_SESSION_INSTRUCTIONS_CHARS, aO as MIC_LEASE_ENDED_TIMEOUT_MS, aP as MicLease, aQ as PlayableVideoElement, _ as ProxyClientOptions, $ as QualityCap, a0 as RECONNECT_BACKOFF_MS, aR as RealtimeAvatarCapacityError, aS as RealtimeAvatarLiveKitRoom, aT as RealtimeAvatarLiveKitRoomProps, a1 as RealtimeAvatarRequestOptions, a2 as RealtimeSessionApi, a3 as RealtimeSessionMedia, a4 as RealtimeSessionRoomSinks, a5 as ReconnectPolicy, a6 as ReconnectingEvent, a7 as RecoveryState, a8 as RetryStep, a9 as SessionBehavior, aa as SessionClip, ab as SessionClocks, ac as SessionEndReason, ad as SessionLifecycleApi, ae as SessionLifecyclePhase, af as SessionLifecyclePhaseKind, ag as SessionLifecycleRoomBridge, ah as SessionLifecycleRoomBridgeProps, ai as SurfaceLayers, aj as TurnState, ak as TurnTimeoutEvent, al as UseAvatarQualityGovernorInput, am as UseLiveKitAvatarGrantInput, an as UseRealtimeSessionInput, ao as UseSessionLifecycleInput, ap as VoiceSpec, aq as VoiceSpecInput, ar as capacityErrorFromBusy, as as capacityStateFromGrant, at as createProxyClient, av as knownBehaviorStates, aw as mapTurnState, ax as readInboundRtp, ay as sessionBehaviorSchema, az as sessionClipSchema, aU as shouldReplayPendingTurn, aA as splitCallTranscript, aB as useAvatarAdaptivePlayoutDelay, aC as useAvatarPlayoutDelay, aD as useAvatarQualityGovernor, aE as useCallTranscript, aF as useLiveKitAvatarGrant, aH as useMicLease, aI as useRealtimeSession, aJ as useReleaseMicLeaseOnTrackEnded, aK as useSessionLifecycle } from './proxy-client-BzblQMvg.js';
 import '@livekit/components-react';
 import 'livekit-client';
 import 'zod';

package/dist/react.js

@@ -317,7 +317,12 @@ function useLiveKitAvatarGrant(input) {
       setState({ status: "requesting", grant: null, busy: null, error: null });
     }
     void client.createLiveKitSessionOrBusy(request, requestOptions).then((result) => {
-      if (cancelled) return;
+      if (cancelled) {
+        if (result.status !== "busy") {
+          void client.releaseLiveKitSession(result.grant.session_id, "superseded");
+        }
+        return;
+      }
       if (result.status === "busy") {
         queueTicketRef.current = result.busy.queue_ticket_id ?? queueTicketRef.current;
         setState({ status: "busy", grant: null, busy: result.busy, error: null });
@@ -1374,7 +1379,7 @@ var transcriptWebhookSchema = z.object({
 var clientMetadataSchema = z.record(z.string().min(1).max(64), z.string().max(200)).refine((value) => Object.keys(value).length <= 16, {
   message: "client_metadata carries at most 16 entries"
 });
-var MAX_SESSION_INSTRUCTIONS_CHARS = 4e3;
+var MAX_SESSION_INSTRUCTIONS_CHARS = 8e3;
 z.object({
   avatar_id: z.string().min(1).max(160).default(DEFAULT_AVATAR_ID),
   background_id: z.string().min(1).max(160).default(DEFAULT_BACKGROUND_ID),
@@ -1717,6 +1722,7 @@ function resolveIdleTimeoutMs(args) {
   if (grantIdleSeconds > 0) return grantIdleSeconds * 1e3;
   return DEFAULT_IDLE_SECONDS * 1e3;
 }
+var DEFAULT_CONNECT_WATCHDOG_SECONDS = 12;
 function resolveWarnBeforeMs(idleTimeoutMs, override, idleWarnLeadSeconds) {
   if (idleTimeoutMs <= 0) return 0;
   const maxLeadMs = Math.max(0, idleTimeoutMs - 1e3);
@@ -1741,6 +1747,7 @@ function useSessionLifecycle(input) {
     reconnectBackoffMs,
     maxReconnectAttempts,
     autoRetryBusy = true,
+    connectWatchdogSeconds,
     requestOptions,
     onBehaviorChange
   } = input;
@@ -1750,6 +1757,7 @@ 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 grantState = useLiveKitAvatarGrant({
     client,
     session,
@@ -1908,6 +1916,16 @@ function useSessionLifecycle(input) {
     },
     [active, onConnected]
   );
+  useEffect(() => {
+    if (!active || connected || connectWatchdogMs <= 0) return;
+    if (grantState.status !== "ready" || !grantState.grant) return;
+    if (recovery.kind === "failed" || recovery.kind === "ended") return;
+    const timer = window.setTimeout(() => {
+      releaseRef.current("disconnected");
+      setRecovery({ kind: "reconnecting", attempt: attemptRef.current });
+    }, connectWatchdogMs);
+    return () => window.clearTimeout(timer);
+  }, [active, connected, connectWatchdogMs, grantState.status, grantState.grant, recovery.kind]);
   useEffect(() => {
     if (!active || !needsFreshGrant(recovery)) return;
     const step2 = retryStep(attemptRef.current, reconnectPolicyRef.current);
@@ -1923,6 +1941,7 @@ function useSessionLifecycle(input) {
       attemptRef.current = step2.attempt;
       setAttempt(step2.attempt);
       refreshBaselineCapacityRef.current = capacityRef.current;
+      releaseRef.current("superseded");
       setRecovery({ kind: "refreshing", attempt: step2.attempt });
       refreshRef.current();
     }, step2.delayMs);
@@ -1935,6 +1954,7 @@ function useSessionLifecycle(input) {
     attemptRef.current = 0;
     setAttempt(0);
     refreshBaselineCapacityRef.current = capacityRef.current;
+    releaseRef.current("superseded");
     setRecovery({ kind: "refreshing", attempt: 0 });
     refreshRef.current();
   }, [active, clearTimer, recovery.kind]);

package/dist/server.d.ts

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

package/dist/server.js

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

package/dist/tanstack-start.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-CHrhuhYb.js';
-import './types-BeGuvyra.js';
+import { P as ProxyConfig } from './types-NKCoqM8E.js';
+import './types-ZfY6oxQY.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-JLQWZF6B.js';
-import './chunk-GKV42PSY.js';
+import { createProxyHandler } from './chunk-YRY3QUTC.js';
+import './chunk-OP32WHW7.js';
 
 // src/tanstack-start.ts
 function realtimeAvatarServerRoute(config) {

package/dist/{types-CHrhuhYb.d.ts → types-NKCoqM8E.d.ts}

@@ -1,4 +1,4 @@
-import { C as CallMode, a as CallPolicy } from './types-BeGuvyra.js';
+import { C as CallMode, a as CallPolicy } from './types-ZfY6oxQY.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/dist/{types-BeGuvyra.d.ts → types-ZfY6oxQY.d.ts}

@@ -1,7 +1,6 @@
 interface components {
     schemas: {
         LiveKitSessionRequest: {
-            /** @default maria */
             avatar_id: string;
             /** @default plain_white */
             background_id: string;
@@ -144,7 +143,9 @@ interface components {
             client_metadata?: {
                 [key: string]: string;
             };
+            /** @description DEPRECATED, no-op. Accepted and ignored. The faster hesitation ceiling this requested is now the default for every session, so sending it changes nothing. Safe to stop sending; the field is retained only so existing callers do not break. */
             fast_endpointing?: boolean;
+            require_ready_clip_library?: boolean;
         };
         LiveKitSessionGrant: {
             /**
@@ -248,11 +249,15 @@ interface components {
         CreateAvatarRequest: {
             displayName: string;
             /**
+             * @description `image` is how avatars are created: upload a portrait, and the platform generates the looping source video and the motion library from it. `video` is CLOSED — it survives in this enum for a handful of grandfathered tenants, and `createAvatar` answers everyone else `422` ("Creating from a supplied video is closed"). The gate is a per-tenant flag that fails closed, so treat `video` as unavailable unless you already know yours is on.
              * @default image
              * @enum {string}
              */
             sourceKind: "image" | "video";
-            /** @enum {string} */
+            /**
+             * @description Omit it. This is not a choice between renderers — the model is DERIVED from `sourceKind` (`image` → `realtime-avatar-live-v1`, `video` → `realtime-avatar-video-v1`), and sending one that disagrees with your `sourceKind` is `422 Avatar model is not compatible with its source kind`. So an explicit value can only ever restate what the source already decided, or fail. It follows that `realtime-avatar-video-v1` is unreachable on the `image` lane everyone uses: it needs `sourceKind: "video"`, which is closed.
+             * @enum {string}
+             */
             modelId?: "realtime-avatar-live-v1" | "realtime-avatar-video-v1";
             sourceAssetId?: string;
             motionPrompt?: string;
@@ -268,7 +273,7 @@ interface components {
                     emotion?: string | null;
                     language?: string | null;
                 };
-            };
+            } | unknown | unknown;
             llm?: {
                 /** @enum {string} */
                 provider: "local" | "gemini" | "openai";
@@ -312,7 +317,10 @@ interface components {
             artDirection?: string;
             /** @enum {string} */
             stylePreset?: "cinematic-founder" | "editorial-companion" | "warm-anime" | "luxury-realism" | "soft-3d" | "noir-avatar";
-            /** Format: uri */
+            /**
+             * Format: uri
+             * @description Dashboard-only. `updateAvatar` needs a request/env context to pull the image into tenant storage, and the public route does not supply one, so sending this here is always `400 Portrait updates are not available on this route`. To change the portrait over this API, register the image with `POST /v1/assets` or `POST /v1/assets/remote` and PATCH the returned id as `sourceAssetId`, which is the swap lane and does work.
+             */
             portraitUrl?: string;
             sourceAssetId?: string;
             anchorTimeMs?: number;
@@ -392,6 +400,7 @@ interface components {
             data: {
                 sessionId: string;
                 avatarId: string | null;
+                avatarName: string | null;
                 /** @enum {string} */
                 status: "reserved" | "started" | "released" | "failed";
                 startedAt: string | null;
@@ -410,6 +419,31 @@ interface components {
             /** Format: date-time */
             to: string;
         };
+        ListAvatarsResponse: {
+            data: {
+                id: string;
+                tenantId: string;
+                displayName: string;
+                /** @enum {string} */
+                sourceKind: "image" | "video";
+                /** @enum {string} */
+                modelId: "realtime-avatar-live-v1" | "realtime-avatar-video-v1";
+                sourceAssetId: string | null;
+                /** @enum {string} */
+                status: "draft" | "preprocessing" | "ready" | "failed" | "disabled" | "deleted";
+                error: string | null;
+                /** @enum {string} */
+                idleVideoStatus: "none" | "queued" | "generating" | "ready" | "failed";
+                defaultVoiceId: string | null;
+                llm: {
+                    /** @enum {string} */
+                    provider: "local" | "gemini" | "openai";
+                    model?: string | null;
+                } | null;
+                createdAt: string;
+                updatedAt: string;
+            }[];
+        };
         ListAvatarClipsResponse: {
             data: {
                 clipId: string;
@@ -421,6 +455,7 @@ interface components {
                 whenHint: string | null;
                 /** @enum {string} */
                 source: "generated" | "uploaded";
+                uploadAssetId: string | null;
                 motionPrompt: string | null;
                 durationSeconds: number | null;
                 anchorVersion: number;
@@ -484,6 +519,7 @@ interface components {
                 whenHint: string | null;
                 /** @enum {string} */
                 source: "generated" | "uploaded";
+                uploadAssetId: string | null;
                 motionPrompt: string | null;
                 durationSeconds: number | null;
                 anchorVersion: number;
@@ -546,6 +582,20 @@ interface components {
         OkResponse: {
             ok: boolean;
         };
+        Error: {
+            /** @description Human-readable message. Not a stable contract — switch on `code` or `status`. */
+            error: string;
+            /** @description Repeats the HTTP status in the body. Absent on unhandled 500s. */
+            status?: number;
+            /** @description Machine-readable discriminator, present where the failure has one — billing, clip-library and loop refusals all carry it. Switch on this rather than on `error`, whose wording is not a contract. The set is open and grows with the API; the codes a given endpoint can return are documented with that endpoint at https://realtimeavatar.ai/docs/api-reference. */
+            code?: string;
+            /** @description Set when the failure is worth retrying as-is. */
+            retryable?: boolean;
+            /** @description Present on 402 — where to send the user to top up. */
+            billingUrl?: string;
+        } & {
+            [key: string]: unknown;
+        };
     };
     responses: never;
     parameters: never;
@@ -721,7 +771,7 @@ type VideoPolicy = {
 };
 /** What YOUR SERVER decides about a call. Never accept any of this from a browser. */
 interface CallPolicy {
-    /** Her behavior contract — who she is and how she speaks. Max 4000 chars. */
+    /** Her behavior contract — who she is and how she speaks. Max 8000 chars. */
     instructions?: string;
     /** Up to 32 prior messages, replayed as memory. */
     context?: readonly ContextMessage[];

package/package.json

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