realtime-avatar 0.4.1 → 0.5.1

package/README.md

@@ -70,20 +70,34 @@ all), and the `video` policy types are deliberately not one-to-one with the wire
 ```ts
 // calls
 rta.startCall({ avatarId, mode?, instructions?, context?, maxSeconds?, video?, transcript?, metadata? })
-rta.endCall(sessionId, { reason? })    // free an abandoned call's slot now; idempotent, never throws
+rta.endCall(sessionId, { reason? })     // free an abandoned call's slot; idempotent, never throws
 
 // avatars
-rta.createAvatarFromVideo({ displayName, videoUrl, voice? })
+rta.createAvatarFromImage({ displayName, imageUrl, motionPrompt?, voice? })  // the only lane
+rta.createAvatarFromVideo({ displayName, videoUrl, voice? })                 // DEPRECATED — closed, 422
 rta.listAvatars()
 rta.getAvatar(avatarId)
-rta.syncClips(avatarId, clipUrls)      // after ANY clip change
+rta.updateAvatar(avatarId, patch)       // re-point displayName / defaultVoiceId
+rta.swapSource(avatarId, { sourceAssetId, anchorTimeMs? })  // re-shoot her: new loop, library re-renders
+rta.retimeAnchor(avatarId, anchorTimeMs)                    // same loop, different rest frame
+rta.deleteAvatar(avatarId)
+
+// clip library — declared as JSON, never as URLs
+rta.setClipLibrary(avatarId, { clips, expectedRevision? })  // declare the FULL set; CAS via expectedRevision
+rta.setLoop(avatarId, { motionPrompt })     // re-direct the RESTING LOOP; clips untouched
+rta.waitForLoop(avatarId)               // block until it settles; THROWS if it failed
+rta.waitForClips(avatarId)              // block until nothing is still rendering
+rta.listClips(avatarId)                 // rows + revision, anchor, eligibility
+rta.syncClips(avatarId, clipUrls)       // DEPRECATED — external-URL tier; use setClipLibrary
 
 // assets
 rta.createRemoteAsset({ kind, remoteUrl })
 rta.uploadAsset(file, { kind })
 
 // billing
-rta.creditBalance()
+rta.creditBalance()                                 // balance + reserved
+rta.listSessions({ from, to, endUserId })           // per-session: when, how long, what it cost
+rta.iterateSessions({ from, to })                   // the same, paging handled
 
 // webhooks
 verifyTranscript(rawBytes, headers, secret)

package/dist/express.d.ts

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

package/dist/express.js

@@ -43,7 +43,7 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.4.1";
+var SDK_VERSION = "0.5.1";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -157,10 +157,15 @@ var RealtimeAvatar = class {
   /**
    * Register a character from a looping clip you host.
    *
-   * Use a VIDEO source for anything that will be called live. An avatar built from a still
-   * image reaches `ready`, mints calls, and publishes a BLACK track — the status and the
-   * track dimensions both look fine, only the pixels are wrong. Image sources are for
-   * offline lipsync renders.
+   * @deprecated CLOSED to new callers — this answers `422` unless your tenant was already
+   * creating from video, in which case it keeps working and your existing avatars are
+   * untouched. Use {@link createAvatarFromImage}: one still, and the platform renders the
+   * resting loop and the motion library from it.
+   *
+   * The reason it closed is not arbitrary. Every clip has to start and end on ONE rest pose
+   * or a state switch reads as a jump, and the platform can only guarantee that when it
+   * rendered the loop and the clips from the same portrait. A supplied video cannot honour
+   * it, so the lane could never be made to look right.
    */
   async createAvatarFromVideo(input) {
     const asset = await this.createRemoteAsset({ kind: "video", remoteUrl: input.videoUrl });
@@ -173,12 +178,41 @@ var RealtimeAvatar = class {
       metadata: input.metadata
     });
   }
+  /**
+   * Register a character from ONE still image. The platform generates everything moving:
+   * the resting loop she idles in, then a starter motion library rendered against her rest
+   * pose. No footage, no clip URLs, nothing to shoot.
+   *
+   * `motionPrompt` directs the RESTING LOOP — the video she plays when nothing else is
+   * happening — and it is the only chance to direct it, because there is no API today that
+   * re-generates a loop after creation (see {@link updateAvatar} for the one thing that can
+   * be re-pointed). Describe a small closed arc that returns to where it started: "settles
+   * into frame, breathes gently, a slow blink". Omit it and the house default is used.
+   *
+   * Creation returns while the avatar is still `preprocessing`; poll {@link getAvatar} until
+   * it leaves that state. The loop is load-bearing, so a failure there settles `failed` with
+   * a readable error — the motion library is not, and a library failure degrades to
+   * loop-only rather than demoting the character.
+   */
+  async createAvatarFromImage(input) {
+    const asset = await this.createRemoteAsset({ kind: "image", remoteUrl: input.imageUrl });
+    return this.createAvatar({
+      displayName: input.displayName,
+      sourceKind: "image",
+      sourceAssetId: asset.id,
+      motionPrompt: input.motionPrompt,
+      voice: input.voice,
+      settings: input.settings,
+      metadata: input.metadata
+    });
+  }
   async createAvatar(input) {
     const body = {
       displayName: input.displayName,
       sourceKind: input.sourceKind,
       sourceAssetId: input.sourceAssetId
     };
+    if (input.motionPrompt !== void 0) body.motionPrompt = input.motionPrompt;
     if (input.voice !== void 0) body.voice = input.voice;
     if (input.settings !== void 0) body.settings = input.settings;
     if (input.metadata !== void 0) body.metadata = input.metadata;
@@ -191,15 +225,192 @@ var RealtimeAvatar = class {
   async getAvatar(avatarId) {
     return toAvatar(await this.#json(await this.#request("GET", `/avatars/${avatarId}`)));
   }
-  /** Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice. */
+  /**
+   * Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice.
+   *
+   * Cheap metadata only. The three things that cost a render have their own methods, because
+   * putting them in a patch alongside a rename would hide minutes of GPU work behind a field:
+   * {@link retimeAnchor} moves the rest frame, {@link swapSource} replaces the footage, and
+   * the resting loop is re-directed by description at `PUT /v1/avatars/{id}/loop`.
+   */
   async updateAvatar(avatarId, patch) {
     return toAvatar(
       await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
     );
   }
+  /**
+   * Re-shoot the character — swap in new footage as her resting loop.
+   *
+   * ASYNCHRONOUS, and that is the whole design. This returns as soon as the swap is
+   * accepted; the avatar keeps serving its CURRENT loop, cache and clips the entire time,
+   * and cuts over to the new generation in one step once the replacement is prepared.
+   * A call minted a second after this returns is a normal call on the old footage.
+   *
+   * Two consequences worth designing for:
+   *
+   * - **The clip library empties and refills.** Old takes are footage of the old source and
+   *   cannot splice against the new loop, so they are dropped and re-rendered. Between the
+   *   cutover and the last re-render she rests on the new loop with less variety — never
+   *   broken, just plainer. Do not gate your UI on the library being full.
+   * - **A failed swap does not fail the avatar.** She keeps serving, `status` stays `ready`,
+   *   and the reason lands on `error`. So poll `getAvatar` and read `error` — a non-null
+   *   `error` on a `ready` avatar is the swap that did not take, not an unhealthy character.
+   *
+   * The frame this rests on comes from the new footage: pass `anchorTimeMs` when frame 0 of
+   * the take is mid-blink. Video-sourced avatars only — a portrait-anchored one is a 422.
+   */
+  async swapSource(avatarId, input) {
+    const json2 = { sourceAssetId: input.sourceAssetId };
+    if (input.anchorTimeMs !== void 0) json2.anchorTimeMs = input.anchorTimeMs;
+    return toAvatar(await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: json2 })));
+  }
+  /**
+   * Re-point the anchor at a different frame of the loop she ALREADY has — same footage,
+   * different rest pose. `swapSource` replaces the footage; this only moves the frame.
+   *
+   * Re-renders the clip library the same way, with the same degradation window, and is
+   * clamped server-side to the loop's last extractable frame (read the avatar back to see
+   * what was actually cut). Video-sourced avatars only.
+   */
+  async retimeAnchor(avatarId, anchorTimeMs) {
+    return toAvatar(
+      await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: { anchorTimeMs } }))
+    );
+  }
   async deleteAvatar(avatarId) {
     await this.#json(await this.#request("DELETE", `/avatars/${avatarId}`));
   }
+  // A clip envelope missing `revision` would silently drop `expectedRevision` from the
+  // next declare — CAS degrades to unconditional with zero signal — so it throws instead.
+  #clipEnvelope(out) {
+    if (typeof out.revision !== "number" || !Array.isArray(out.data)) {
+      throw new RealtimeAvatarError("clip library response did not match the contract");
+    }
+    return out;
+  }
+  /**
+   * Declare the avatar's full desired clip library — a declaration, not a delta. The
+   * platform reconciles it against what exists: unchanged clips are `kept` (still
+   * serving), new or changed ones are `queued` to render, and clips you dropped are
+   * `retired`. The 202 is acceptance, not readiness — poll `listClips` until no row is
+   * `queued` or `generating`. A rejected upload settles `failed`, which is terminal, so
+   * waiting for all-`ready` waits forever. While a re-render is in flight the previous
+   * take keeps serving, so a declaration never blanks a live avatar.
+   *
+   * `expectedRevision` is compare-and-set: pass the `revision` you last read and a
+   * concurrent writer surfaces as a 409 instead of a lost update. Omit it to declare
+   * unconditionally.
+   *
+   * At most 12 clips: one `idle`, up to two `listen`, the rest `gesture`. An uploaded
+   * clip (`source: { assetId }`) must start AND end on the avatar's rest pose — pose
+   * validation rejects it otherwise (`status: "failed"`, the verdict in `poseCheck`),
+   * and the rest of the library is untouched.
+   */
+  async setClipLibrary(avatarId, library) {
+    const body = { clips: library.clips };
+    if (library.expectedRevision !== void 0) body.expectedRevision = library.expectedRevision;
+    return this.#clipEnvelope(
+      await this.#json(
+        await this.#request("PUT", `/avatars/${avatarId}/clips`, { json: body })
+      )
+    );
+  }
+  /**
+   * Re-direct the RESTING LOOP — the video she plays when nothing else is happening — from
+   * a new one-sentence description.
+   *
+   * Not a clip, and this is the distinction integrations get wrong: a clip with
+   * `role: "idle"` is a variant spliced OVER the loop, and declaring one never changes what
+   * she rests in. This is the only thing that does.
+   *
+   * `202`, because the render takes minutes. Three properties, all measured against a real
+   * render rather than asserted:
+   *
+   * - **She never goes dark.** She stays `ready` and keeps serving her previous loop for the
+   *   entire render — returned as `servingUrl` — then the swap publishes in one step.
+   * - **Your clip library is untouched.** Clips render against the portrait, not against the
+   *   loop, so a re-direct re-queues nothing and does not move `revision`.
+   * - **It bills once**, at the rendering model's rate, per re-direct.
+   *
+   * Refusals worth telling apart: `409 loop_pending` (one is already in flight — wait) and
+   * `422 loop_not_generatable` (a grandfathered video-sourced avatar has no portrait to
+   * re-animate — terminal, do not retry).
+   */
+  async setLoop(avatarId, loop) {
+    return await this.#json(
+      await this.#request("PUT", `/avatars/${avatarId}/loop`, { json: { motionPrompt: loop.motionPrompt } })
+    );
+  }
+  /**
+   * Block until a loop re-direct settles, and throw if it did not take.
+   *
+   * `setLoop` returns on ACCEPTANCE; the render runs for minutes afterwards. Every caller
+   * therefore writes the same polling loop, and the obvious version of it never terminates
+   * on failure — a failed re-direct leaves her `ready` (she is still serving the old loop)
+   * and writes nothing to `error`. `idleVideoStatus` is the only field that moves, which is
+   * why this exists rather than a doc line telling you to poll.
+   *
+   * Race-free without a baseline: the platform commits `queued` before `setLoop` returns, so
+   * by the time you can call this the status has already left `ready`.
+   *
+   * Resolves with the settled avatar — `sourceAssetId` is now the new loop. Throws on a
+   * failed render and on timeout; a timeout is not a failure, so re-poll or call again.
+   */
+  async waitForLoop(avatarId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20 * 6e4;
+    const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const avatar = await this.getAvatar(avatarId);
+      if (avatar.idleVideoStatus === "failed") {
+        throw new RealtimeAvatarError(
+          `Loop re-direct failed for ${avatarId}. She is still serving her previous loop \u2014 nothing was lost, and you can send another description.`
+        );
+      }
+      if (avatar.idleVideoStatus === "ready" || avatar.idleVideoStatus === "none") return avatar;
+      if (Date.now() >= deadline) {
+        throw new RealtimeAvatarError(
+          `Loop re-direct for ${avatarId} was still ${avatar.idleVideoStatus} after ${Math.round(timeoutMs / 1e3)}s. This is a timeout, not a failure \u2014 the render may still land.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
+  /**
+   * Block until every clip in the library has stopped moving.
+   *
+   * Settled means no row is `queued` or `generating` — NOT that every row is `ready`.
+   * Waiting for all-`ready` is the intuitive version and it hangs forever: a clip rejected
+   * by pose validation settles `failed`, which is terminal. So this returns the library
+   * with the failures in it and lets you decide; a partial library is a legitimate outcome
+   * and the rest of it is already serving.
+   *
+   * Throws only on timeout.
+   */
+  async waitForClips(avatarId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20 * 6e4;
+    const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const library = await this.listClips(avatarId);
+      const moving = library.data.filter((c) => c.status === "queued" || c.status === "generating");
+      if (moving.length === 0) return library;
+      if (Date.now() >= deadline) {
+        throw new RealtimeAvatarError(
+          `${moving.length} clip(s) on ${avatarId} were still rendering after ${Math.round(timeoutMs / 1e3)}s: ${moving.map((c) => c.clipId).join(", ")}. This is a timeout, not a failure.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
+  /** The avatar's clip library: every non-retired clip, plus revision, anchor and eligibility. */
+  async listClips(avatarId) {
+    return this.#clipEnvelope(
+      await this.#json(
+        await this.#request("GET", `/avatars/${avatarId}/clips`)
+      )
+    );
+  }
   /**
    * Reconcile an avatar's clip set after it changes.
    *
@@ -210,6 +421,10 @@ var RealtimeAvatar = class {
    * **At most 32 URLs per call.** This is the whole set for the avatar, not a delta, and the
    * endpoint rejects an oversize list rather than truncating it — so a library that outgrows
    * 32 needs the set trimmed, not split across two calls.
+   *
+   * @deprecated The externally-hosted clip tier this serves is sunsetting. Declare the
+   * library with {@link setClipLibrary} instead — the platform renders and hosts the
+   * clips, and pose-validates uploads against the avatar's rest pose.
    */
   async syncClips(avatarId, clipUrls) {
     const out = await this.#json(
@@ -385,7 +600,17 @@ function toAvatar(raw) {
     displayName: String(a.displayName ?? ""),
     sourceKind: a.sourceKind === "video" ? "video" : "image",
     status: a.status ?? "draft",
-    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null
+    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null,
+    sourceAssetId: a.sourceAssetId ? String(a.sourceAssetId) : null,
+    // Carried because it is the ONLY channel a failed source swap has: she stays `ready`
+    // and serving, and this says why the re-shoot did not take.
+    error: a.error ? String(a.error) : null,
+    // The loop lane's terminal signal, and the reason it is here: a re-direct that fails
+    // leaves `status` on `ready` (she is still serving the old loop, which is the whole
+    // design) and writes nothing to `error`. Without this field a caller polling after
+    // `setLoop` has NO way to distinguish "still rendering" from "gave up", and waits
+    // forever. queued → generating → ready | failed.
+    idleVideoStatus: a.idleVideoStatus ?? "none"
   };
 }
 function toAsset(raw) {

package/dist/hono.d.ts

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

package/dist/hono.js

@@ -43,7 +43,7 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.4.1";
+var SDK_VERSION = "0.5.1";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -157,10 +157,15 @@ var RealtimeAvatar = class {
   /**
    * Register a character from a looping clip you host.
    *
-   * Use a VIDEO source for anything that will be called live. An avatar built from a still
-   * image reaches `ready`, mints calls, and publishes a BLACK track — the status and the
-   * track dimensions both look fine, only the pixels are wrong. Image sources are for
-   * offline lipsync renders.
+   * @deprecated CLOSED to new callers — this answers `422` unless your tenant was already
+   * creating from video, in which case it keeps working and your existing avatars are
+   * untouched. Use {@link createAvatarFromImage}: one still, and the platform renders the
+   * resting loop and the motion library from it.
+   *
+   * The reason it closed is not arbitrary. Every clip has to start and end on ONE rest pose
+   * or a state switch reads as a jump, and the platform can only guarantee that when it
+   * rendered the loop and the clips from the same portrait. A supplied video cannot honour
+   * it, so the lane could never be made to look right.
    */
   async createAvatarFromVideo(input) {
     const asset = await this.createRemoteAsset({ kind: "video", remoteUrl: input.videoUrl });
@@ -173,12 +178,41 @@ var RealtimeAvatar = class {
       metadata: input.metadata
     });
   }
+  /**
+   * Register a character from ONE still image. The platform generates everything moving:
+   * the resting loop she idles in, then a starter motion library rendered against her rest
+   * pose. No footage, no clip URLs, nothing to shoot.
+   *
+   * `motionPrompt` directs the RESTING LOOP — the video she plays when nothing else is
+   * happening — and it is the only chance to direct it, because there is no API today that
+   * re-generates a loop after creation (see {@link updateAvatar} for the one thing that can
+   * be re-pointed). Describe a small closed arc that returns to where it started: "settles
+   * into frame, breathes gently, a slow blink". Omit it and the house default is used.
+   *
+   * Creation returns while the avatar is still `preprocessing`; poll {@link getAvatar} until
+   * it leaves that state. The loop is load-bearing, so a failure there settles `failed` with
+   * a readable error — the motion library is not, and a library failure degrades to
+   * loop-only rather than demoting the character.
+   */
+  async createAvatarFromImage(input) {
+    const asset = await this.createRemoteAsset({ kind: "image", remoteUrl: input.imageUrl });
+    return this.createAvatar({
+      displayName: input.displayName,
+      sourceKind: "image",
+      sourceAssetId: asset.id,
+      motionPrompt: input.motionPrompt,
+      voice: input.voice,
+      settings: input.settings,
+      metadata: input.metadata
+    });
+  }
   async createAvatar(input) {
     const body = {
       displayName: input.displayName,
       sourceKind: input.sourceKind,
       sourceAssetId: input.sourceAssetId
     };
+    if (input.motionPrompt !== void 0) body.motionPrompt = input.motionPrompt;
     if (input.voice !== void 0) body.voice = input.voice;
     if (input.settings !== void 0) body.settings = input.settings;
     if (input.metadata !== void 0) body.metadata = input.metadata;
@@ -191,15 +225,192 @@ var RealtimeAvatar = class {
   async getAvatar(avatarId) {
     return toAvatar(await this.#json(await this.#request("GET", `/avatars/${avatarId}`)));
   }
-  /** Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice. */
+  /**
+   * Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice.
+   *
+   * Cheap metadata only. The three things that cost a render have their own methods, because
+   * putting them in a patch alongside a rename would hide minutes of GPU work behind a field:
+   * {@link retimeAnchor} moves the rest frame, {@link swapSource} replaces the footage, and
+   * the resting loop is re-directed by description at `PUT /v1/avatars/{id}/loop`.
+   */
   async updateAvatar(avatarId, patch) {
     return toAvatar(
       await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
     );
   }
+  /**
+   * Re-shoot the character — swap in new footage as her resting loop.
+   *
+   * ASYNCHRONOUS, and that is the whole design. This returns as soon as the swap is
+   * accepted; the avatar keeps serving its CURRENT loop, cache and clips the entire time,
+   * and cuts over to the new generation in one step once the replacement is prepared.
+   * A call minted a second after this returns is a normal call on the old footage.
+   *
+   * Two consequences worth designing for:
+   *
+   * - **The clip library empties and refills.** Old takes are footage of the old source and
+   *   cannot splice against the new loop, so they are dropped and re-rendered. Between the
+   *   cutover and the last re-render she rests on the new loop with less variety — never
+   *   broken, just plainer. Do not gate your UI on the library being full.
+   * - **A failed swap does not fail the avatar.** She keeps serving, `status` stays `ready`,
+   *   and the reason lands on `error`. So poll `getAvatar` and read `error` — a non-null
+   *   `error` on a `ready` avatar is the swap that did not take, not an unhealthy character.
+   *
+   * The frame this rests on comes from the new footage: pass `anchorTimeMs` when frame 0 of
+   * the take is mid-blink. Video-sourced avatars only — a portrait-anchored one is a 422.
+   */
+  async swapSource(avatarId, input) {
+    const json2 = { sourceAssetId: input.sourceAssetId };
+    if (input.anchorTimeMs !== void 0) json2.anchorTimeMs = input.anchorTimeMs;
+    return toAvatar(await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: json2 })));
+  }
+  /**
+   * Re-point the anchor at a different frame of the loop she ALREADY has — same footage,
+   * different rest pose. `swapSource` replaces the footage; this only moves the frame.
+   *
+   * Re-renders the clip library the same way, with the same degradation window, and is
+   * clamped server-side to the loop's last extractable frame (read the avatar back to see
+   * what was actually cut). Video-sourced avatars only.
+   */
+  async retimeAnchor(avatarId, anchorTimeMs) {
+    return toAvatar(
+      await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: { anchorTimeMs } }))
+    );
+  }
   async deleteAvatar(avatarId) {
     await this.#json(await this.#request("DELETE", `/avatars/${avatarId}`));
   }
+  // A clip envelope missing `revision` would silently drop `expectedRevision` from the
+  // next declare — CAS degrades to unconditional with zero signal — so it throws instead.
+  #clipEnvelope(out) {
+    if (typeof out.revision !== "number" || !Array.isArray(out.data)) {
+      throw new RealtimeAvatarError("clip library response did not match the contract");
+    }
+    return out;
+  }
+  /**
+   * Declare the avatar's full desired clip library — a declaration, not a delta. The
+   * platform reconciles it against what exists: unchanged clips are `kept` (still
+   * serving), new or changed ones are `queued` to render, and clips you dropped are
+   * `retired`. The 202 is acceptance, not readiness — poll `listClips` until no row is
+   * `queued` or `generating`. A rejected upload settles `failed`, which is terminal, so
+   * waiting for all-`ready` waits forever. While a re-render is in flight the previous
+   * take keeps serving, so a declaration never blanks a live avatar.
+   *
+   * `expectedRevision` is compare-and-set: pass the `revision` you last read and a
+   * concurrent writer surfaces as a 409 instead of a lost update. Omit it to declare
+   * unconditionally.
+   *
+   * At most 12 clips: one `idle`, up to two `listen`, the rest `gesture`. An uploaded
+   * clip (`source: { assetId }`) must start AND end on the avatar's rest pose — pose
+   * validation rejects it otherwise (`status: "failed"`, the verdict in `poseCheck`),
+   * and the rest of the library is untouched.
+   */
+  async setClipLibrary(avatarId, library) {
+    const body = { clips: library.clips };
+    if (library.expectedRevision !== void 0) body.expectedRevision = library.expectedRevision;
+    return this.#clipEnvelope(
+      await this.#json(
+        await this.#request("PUT", `/avatars/${avatarId}/clips`, { json: body })
+      )
+    );
+  }
+  /**
+   * Re-direct the RESTING LOOP — the video she plays when nothing else is happening — from
+   * a new one-sentence description.
+   *
+   * Not a clip, and this is the distinction integrations get wrong: a clip with
+   * `role: "idle"` is a variant spliced OVER the loop, and declaring one never changes what
+   * she rests in. This is the only thing that does.
+   *
+   * `202`, because the render takes minutes. Three properties, all measured against a real
+   * render rather than asserted:
+   *
+   * - **She never goes dark.** She stays `ready` and keeps serving her previous loop for the
+   *   entire render — returned as `servingUrl` — then the swap publishes in one step.
+   * - **Your clip library is untouched.** Clips render against the portrait, not against the
+   *   loop, so a re-direct re-queues nothing and does not move `revision`.
+   * - **It bills once**, at the rendering model's rate, per re-direct.
+   *
+   * Refusals worth telling apart: `409 loop_pending` (one is already in flight — wait) and
+   * `422 loop_not_generatable` (a grandfathered video-sourced avatar has no portrait to
+   * re-animate — terminal, do not retry).
+   */
+  async setLoop(avatarId, loop) {
+    return await this.#json(
+      await this.#request("PUT", `/avatars/${avatarId}/loop`, { json: { motionPrompt: loop.motionPrompt } })
+    );
+  }
+  /**
+   * Block until a loop re-direct settles, and throw if it did not take.
+   *
+   * `setLoop` returns on ACCEPTANCE; the render runs for minutes afterwards. Every caller
+   * therefore writes the same polling loop, and the obvious version of it never terminates
+   * on failure — a failed re-direct leaves her `ready` (she is still serving the old loop)
+   * and writes nothing to `error`. `idleVideoStatus` is the only field that moves, which is
+   * why this exists rather than a doc line telling you to poll.
+   *
+   * Race-free without a baseline: the platform commits `queued` before `setLoop` returns, so
+   * by the time you can call this the status has already left `ready`.
+   *
+   * Resolves with the settled avatar — `sourceAssetId` is now the new loop. Throws on a
+   * failed render and on timeout; a timeout is not a failure, so re-poll or call again.
+   */
+  async waitForLoop(avatarId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20 * 6e4;
+    const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const avatar = await this.getAvatar(avatarId);
+      if (avatar.idleVideoStatus === "failed") {
+        throw new RealtimeAvatarError(
+          `Loop re-direct failed for ${avatarId}. She is still serving her previous loop \u2014 nothing was lost, and you can send another description.`
+        );
+      }
+      if (avatar.idleVideoStatus === "ready" || avatar.idleVideoStatus === "none") return avatar;
+      if (Date.now() >= deadline) {
+        throw new RealtimeAvatarError(
+          `Loop re-direct for ${avatarId} was still ${avatar.idleVideoStatus} after ${Math.round(timeoutMs / 1e3)}s. This is a timeout, not a failure \u2014 the render may still land.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
+  /**
+   * Block until every clip in the library has stopped moving.
+   *
+   * Settled means no row is `queued` or `generating` — NOT that every row is `ready`.
+   * Waiting for all-`ready` is the intuitive version and it hangs forever: a clip rejected
+   * by pose validation settles `failed`, which is terminal. So this returns the library
+   * with the failures in it and lets you decide; a partial library is a legitimate outcome
+   * and the rest of it is already serving.
+   *
+   * Throws only on timeout.
+   */
+  async waitForClips(avatarId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20 * 6e4;
+    const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const library = await this.listClips(avatarId);
+      const moving = library.data.filter((c) => c.status === "queued" || c.status === "generating");
+      if (moving.length === 0) return library;
+      if (Date.now() >= deadline) {
+        throw new RealtimeAvatarError(
+          `${moving.length} clip(s) on ${avatarId} were still rendering after ${Math.round(timeoutMs / 1e3)}s: ${moving.map((c) => c.clipId).join(", ")}. This is a timeout, not a failure.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
+  /** The avatar's clip library: every non-retired clip, plus revision, anchor and eligibility. */
+  async listClips(avatarId) {
+    return this.#clipEnvelope(
+      await this.#json(
+        await this.#request("GET", `/avatars/${avatarId}/clips`)
+      )
+    );
+  }
   /**
    * Reconcile an avatar's clip set after it changes.
    *
@@ -210,6 +421,10 @@ var RealtimeAvatar = class {
    * **At most 32 URLs per call.** This is the whole set for the avatar, not a delta, and the
    * endpoint rejects an oversize list rather than truncating it — so a library that outgrows
    * 32 needs the set trimmed, not split across two calls.
+   *
+   * @deprecated The externally-hosted clip tier this serves is sunsetting. Declare the
+   * library with {@link setClipLibrary} instead — the platform renders and hosts the
+   * clips, and pose-validates uploads against the avatar's rest pose.
    */
   async syncClips(avatarId, clipUrls) {
     const out = await this.#json(
@@ -385,7 +600,17 @@ function toAvatar(raw) {
     displayName: String(a.displayName ?? ""),
     sourceKind: a.sourceKind === "video" ? "video" : "image",
     status: a.status ?? "draft",
-    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null
+    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null,
+    sourceAssetId: a.sourceAssetId ? String(a.sourceAssetId) : null,
+    // Carried because it is the ONLY channel a failed source swap has: she stays `ready`
+    // and serving, and this says why the re-shoot did not take.
+    error: a.error ? String(a.error) : null,
+    // The loop lane's terminal signal, and the reason it is here: a re-direct that fails
+    // leaves `status` on `ready` (she is still serving the old loop, which is the whole
+    // design) and writes nothing to `error`. Without this field a caller polling after
+    // `setLoop` has NO way to distinguish "still rendering" from "gave up", and waits
+    // forever. queued → generating → ready | failed.
+    idleVideoStatus: a.idleVideoStatus ?? "none"
   };
 }
 function toAsset(raw) {