realtime-avatar 0.25.0 → 0.26.0

package/dist/server.js

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

package/dist/tanstack-start.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-DNHHQ5GZ.js';
-import './chunk-GMYGHDY2.js';
+import { createProxyHandler } from './chunk-XJPGQMEW.js';
+import './chunk-HMESE54B.js';
 import './chunk-MCIXU6XP.js';
 
 // src/tanstack-start.ts

package/dist/tools.d.ts

@@ -93,6 +93,22 @@ interface RoomLike {
         identity: string;
     }>;
 }
+/**
+ * Registration did not arm the tools. `retryable` says whether trying again can help:
+ * - true: the agent was not there or had not armed registration by the deadline (a slow start,
+ *   or a session minted without `client_tools` — one attempt cannot tell them apart), or the RPC
+ *   transport failed.
+ * - false: the manifest is too large, the agent refused or answered something unreadable, or
+ *   LiveKit refused the request itself. The same request will fail the same way.
+ */
+declare class ToolRegistrationError extends Error {
+    readonly name = "ToolRegistrationError";
+    readonly retryable: boolean;
+    constructor(message: string, options: {
+        retryable: boolean;
+        cause?: unknown;
+    });
+}
 /**
  * Register your tools and start answering calls to them.
  *
@@ -131,4 +147,4 @@ declare function attachAvatarTools(room: RoomLike, tools: Record<string, Registe
     timeoutMs?: number;
 }): Promise<ToolRegistration>;
 
-export { type AvatarTool, MAX_MANIFEST_BYTES, MAX_RESULT_CHARS, MAX_TOOLS, type RegisteredTool, TOOL_DEADLINE_MS, type ToolContext, type ToolRegistration, attachAvatarTools, defineAvatarTool };
+export { type AvatarTool, MAX_MANIFEST_BYTES, MAX_RESULT_CHARS, MAX_TOOLS, type RegisteredTool, TOOL_DEADLINE_MS, type ToolContext, type ToolRegistration, ToolRegistrationError, attachAvatarTools, defineAvatarTool };

package/dist/tools.js

@@ -35,14 +35,26 @@ function candidateIdentities(room) {
   const agents = all.filter((id) => /^agent[-_]/i.test(id));
   return [...agents, ...all.filter((id) => !agents.includes(id))];
 }
+function rpcCode(error) {
+  return typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+}
 function methodMissing(error) {
-  const code = error?.code;
-  if (code === "UNSUPPORTED_METHOD" || code === "RECIPIENT_NOT_FOUND" || code === 1401 || code === 1402) {
+  const code = rpcCode(error);
+  if (code === "UNSUPPORTED_METHOD" || code === "RECIPIENT_NOT_FOUND" || code === 1400 || code === 1401) {
     return true;
   }
   const message = error instanceof Error ? error.message : String(error ?? "");
   return /not supported|unsupported_method|recipient_not_found|recipient not found/i.test(message);
 }
+var TRANSIENT_RPC_CODES = /* @__PURE__ */ new Set([1501, 1502, 1503, 1505]);
+var ToolRegistrationError = class extends Error {
+  name = "ToolRegistrationError";
+  retryable;
+  constructor(message, options) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.retryable = options.retryable;
+  }
+};
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function buildManifest(tools) {
   const descriptors = [];
@@ -72,8 +84,9 @@ async function attachAvatarTools(room, tools, options = {}) {
   const { descriptors, rejected } = buildManifest(tools);
   const payload = JSON.stringify({ tools: descriptors });
   if (payload.length > MAX_MANIFEST_BYTES) {
-    throw new Error(
-      `tool manifest is ${payload.length} bytes, over the ${MAX_MANIFEST_BYTES} limit \u2014 shorten descriptions or register fewer tools`
+    throw new ToolRegistrationError(
+      `tool manifest is ${payload.length} bytes, over the ${MAX_MANIFEST_BYTES} limit \u2014 shorten descriptions or register fewer tools`,
+      { retryable: false }
     );
   }
   options.signal?.throwIfAborted();
@@ -156,14 +169,21 @@ async function attachAvatarTools(room, tools, options = {}) {
         } catch (error) {
           activeCaller = void 0;
           lastError = error;
-          if (!methodMissing(error)) throw error;
+          if (!methodMissing(error)) {
+            if (options.signal?.aborted) throw error;
+            throw new ToolRegistrationError(
+              `tool registration failed: ${error instanceof Error ? error.message : String(error)}`,
+              { retryable: TRANSIENT_RPC_CODES.has(rpcCode(error)), cause: error }
+            );
+          }
         }
       }
       if (Date.now() >= deadline) break;
       await sleep(200);
     }
-    throw new Error(
-      sawCandidate ? `no participant accepted the tool manifest \u2014 either this session was not minted with the \`client_tools\` capability (a server-side grant), or the agent never armed registration within ${options.timeoutMs ?? 8e3}ms` + (lastError instanceof Error ? ` (last error: ${lastError.message})` : "") : "no remote participant joined the room before the timeout \u2014 nothing to register with"
+    throw new ToolRegistrationError(
+      sawCandidate ? `no participant accepted the tool manifest \u2014 either this session was not minted with the \`client_tools\` capability (a server-side grant), or the agent never armed registration within ${options.timeoutMs ?? 8e3}ms` + (lastError instanceof Error ? ` (last error: ${lastError.message})` : "") : "no remote participant joined the room before the timeout \u2014 nothing to register with",
+      { retryable: true, cause: lastError ?? void 0 }
     );
   } catch (error) {
     dispose();
@@ -171,4 +191,4 @@ async function attachAvatarTools(room, tools, options = {}) {
   }
 }
 
-export { MAX_MANIFEST_BYTES, MAX_RESULT_CHARS, MAX_TOOLS, TOOL_DEADLINE_MS, attachAvatarTools, defineAvatarTool };
+export { MAX_MANIFEST_BYTES, MAX_RESULT_CHARS, MAX_TOOLS, TOOL_DEADLINE_MS, ToolRegistrationError, attachAvatarTools, defineAvatarTool };

package/package.json

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

package/dist/playout-delay-DWOc8iCl.d.ts

@@ -1,65 +0,0 @@
-/**
- * Receiver-side playout delay (SECONDS) for the avatar media tracks.
- *
- * The avatar is published from a GPU datacenter and reaches viewers over the
- * public internet, where a few percent of packet loss is normal. A shallow
- * receiver buffer stalls (freezes) on every loss while it waits for a
- * retransmit; a deeper buffer recovers the lost packets BEFORE playout, so the
- * viewer sees smooth 25fps instead of freezing. Measured at ~5% loss this took
- * the stream from ~11fps with multi-second freezes to a steady 25fps with zero
- * freezes.
- *
- * 0.5s is applied via the native `RemoteTrack.setPlayoutDelay`, which sets the
- * receiver's `playoutDelayHint` — the same Chromium jitter-buffer knob the old
- * hand-rolled `jitterBufferTarget` reached into (the spec renamed
- * playoutDelayHint→jitterBufferTarget; both influence the same buffer depth),
- * but typed and SDK-owned so there is no cast or feature-probe. The hint is NOT
- * free at the open: the receiver holds the FIRST video frame toward the target
- * (~250-450ms of measured TTFF), a deliberate cost paid once for the freeze-free
- * steady state above. The open-small-then-ramp variant that tried to dodge that
- * cost was shipped, failed twice (the rVFC ramp trigger is throttled on the
- * opacity:0-mounted element, stranding the shallow buffer), and was deliberately
- * removed in 2262e4c7b — do not re-propose it. No-op on browsers that don't
- * support the hint (the SDK warns and moves on).
- *
- * This lives in the vanilla browser package, not the React one, because the
- * React surface applies it for you and a plain-DOM page has to be given it.
- * Until this file existed the helper was only reachable through
- * `realtime-avatar/react`, so every plain-DOM adopter — every one of this repo's
- * own demos included — ran with the browser's default shallow buffer and froze on
- * every lost packet. Nobody should have to know this knob exists: `prepareAvatarRoom`
- * (and `attachRemoteAudio`, which calls it) applies it to every track the room
- * subscribes, and `RealtimeAvatarLiveKitRoom` does the same for React. This file is
- * the one place the number and its reasoning live.
- * Structural like its siblings: no `livekit-client` import, no version pin.
- */
-declare const DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS = 0.5;
-/**
- * A track that can take a native playout-delay hint — livekit-client's subscribed
- * `RemoteTrack`. Duck-typed on the method rather than `instanceof`, so a
- * placeholder or local track is skipped and the helper is testable with a fake.
- */
-interface PlayoutDelayTarget {
-    setPlayoutDelay(delayInSeconds: number): void;
-}
-/**
- * Apply the receiver playout delay to ONE subscribed track.
- *
- * Call it for every track `RoomEvent.TrackSubscribed` hands you, audio and video
- * alike, before or after `attach()` — WebRTC syncs the pair to the LARGER hint,
- * so applying it to one stream and not the other lets the lips lag the voice.
- * Returns `true` when the hint was applied and `false` when the object cannot take
- * one (a local track, a placeholder, a not-yet-subscribed publication), so a
- * caller can log the miss without a try/catch. The delay is floored at 0 so a
- * negative input can never throw.
- */
-declare function applyPlayoutDelay(track: unknown, delaySeconds?: number): boolean;
-/**
- * Apply the SAME native playout delay to the avatar's audio + video tracks
- * (kept equal so the a/v sync stays lip-locked). Pure and exported so the clamp
- * and the both-tracks-equal invariant are unit-testable without a DOM; the React
- * hook `useAvatarPlayoutDelay` is a thin effect wrapper around this.
- */
-declare function applyAvatarPlayoutDelay(videoTrack: unknown, audioTrack: unknown, delaySeconds?: number): void;
-
-export { DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS as D, type PlayoutDelayTarget as P, applyAvatarPlayoutDelay as a, applyPlayoutDelay as b };