@mux/ai 0.28.1 → 0.30.0

package/dist/workflows/index.js

@@ -1,114 +1,11 @@
 // src/workflows/ask-questions.ts
 import { generateText, Output } from "ai";
 import dedent2 from "dedent";
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
-// src/lib/image-download.ts
-import pRetry, { AbortError } from "p-retry";
-var BASE64_CHUNK_SIZE = 32768;
-function bytesToBase64(bytes) {
-  if (bytes.length === 0) {
-    return "";
-  }
-  let binary = "";
-  for (let i = 0; i < bytes.length; i += BASE64_CHUNK_SIZE) {
-    const chunk = bytes.subarray(i, i + BASE64_CHUNK_SIZE);
-    binary += String.fromCharCode(...chunk);
-  }
-  if (typeof globalThis.btoa !== "function") {
-    throw new TypeError("Base64 encoder is not available in this environment.");
-  }
-  return globalThis.btoa(binary);
-}
-var DEFAULT_OPTIONS = {
-  timeout: 1e4,
-  retries: 3,
-  retryDelay: 1e3,
-  maxRetryDelay: 1e4,
-  exponentialBackoff: true
-};
-async function downloadImageAsBase64(url, options = {}) {
-  "use step";
-  const opts = { ...DEFAULT_OPTIONS, ...options };
-  let attemptCount = 0;
-  return pRetry(
-    async () => {
-      attemptCount++;
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), opts.timeout);
-      try {
-        const response = await fetch(url, {
-          signal: controller.signal,
-          headers: {
-            "User-Agent": "@mux/ai image downloader"
-          }
-        });
-        clearTimeout(timeoutId);
-        if (!response.ok) {
-          if (response.status >= 400 && response.status < 500 && response.status !== 429) {
-            throw new AbortError(`HTTP ${response.status}: ${response.statusText}`);
-          }
-          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-        }
-        const contentType = response.headers.get("content-type");
-        if (!contentType?.startsWith("image/")) {
-          throw new AbortError(`Invalid content type: ${contentType}. Expected image/*`);
-        }
-        const arrayBuffer = await response.arrayBuffer();
-        const buffer = new Uint8Array(arrayBuffer);
-        if (buffer.length === 0) {
-          throw new AbortError("Downloaded image is empty");
-        }
-        const base64Data = `data:${contentType};base64,${bytesToBase64(buffer)}`;
-        return {
-          base64Data,
-          buffer,
-          url,
-          contentType,
-          sizeBytes: buffer.length,
-          attempts: attemptCount
-        };
-      } catch (error) {
-        clearTimeout(timeoutId);
-        if (error instanceof AbortError) {
-          throw error;
-        }
-        if (error instanceof Error) {
-          if (error.name === "AbortError") {
-            throw new Error(`Request timeout after ${opts.timeout}ms`);
-          }
-          throw new Error(`Download failed: ${error.message}`);
-        }
-        throw new Error("Unknown download error");
-      }
-    },
-    {
-      retries: opts.retries,
-      minTimeout: opts.retryDelay,
-      maxTimeout: opts.maxRetryDelay,
-      factor: opts.exponentialBackoff ? 2 : 1,
-      randomize: true,
-      // Add jitter to prevent thundering herd
-      onFailedAttempt: (error) => {
-        console.warn(`Image download attempt ${error.attemptNumber} failed for ${url}`);
-        if (error.retriesLeft > 0) {
-          console.warn(`Retrying... (${error.retriesLeft} attempts left)`);
-        }
-      }
-    }
-  );
-}
-async function downloadImagesAsBase64(urls, options = {}, maxConcurrent = 5) {
-  "use step";
-  const results = [];
-  for (let i = 0; i < urls.length; i += maxConcurrent) {
-    const batch = urls.slice(i, i + maxConcurrent);
-    const batchPromises = batch.map((url) => downloadImageAsBase64(url, options));
-    const batchResults = await Promise.all(batchPromises);
-    results.push(...batchResults);
-  }
-  return results;
-}
+// src/lib/content-policy-error.ts
+import { APICallError, NoObjectGeneratedError, RetryError } from "ai";
+import { z as z2 } from "zod";
 
 // src/lib/prompt-fragments.ts
 import dedent from "dedent";
@@ -179,7 +76,7 @@ var EnvSchema = z.object({
   MUX_TEST_ASSET_ID_VIOLENT_AUDIO_ONLY: optionalString("Mux test asset ID for audio-only assets with violent content.", "Mux test asset id for audio-only assets with violent content for testing"),
   // Eval config
   MUX_AI_EVAL_MODEL_SET: optionalString("Eval model selection mode.", "Choose between 'default' (provider defaults only) or 'all' (all configured models)"),
-  MUX_AI_EVAL_MODELS: optionalString("Comma-separated eval model pairs.", "Comma-separated provider:model pairs (e.g. 'openai:gpt-5.1,anthropic:claude-sonnet-4-5,google:gemini-3-flash-preview')"),
+  MUX_AI_EVAL_MODELS: optionalString("Comma-separated eval model pairs.", "Comma-separated provider:model pairs (e.g. 'openai:gpt-5.6-luna,anthropic:claude-sonnet-4-5,google:gemini-3-flash-preview')"),
   // AI Providers
   OPENAI_API_KEY: optionalString("OpenAI API key for OpenAI-backed workflows.", "OpenAI API key"),
   ANTHROPIC_API_KEY: optionalString("Anthropic API key for Claude-backed workflows.", "Anthropic API key"),
@@ -498,7 +395,8 @@ var TOKEN_USAGE_FIELDS = [
   "outputTokens",
   "totalTokens",
   "reasoningTokens",
-  "cachedInputTokens"
+  "cachedInputTokens",
+  "cacheWriteTokens"
 ];
 function isDefinedTokenUsageValue(value) {
   return typeof value === "number";
@@ -540,6 +438,12 @@ function getErrorTokenUsage(error) {
       extracted.cachedInputTokens = cacheReadTokens;
     }
   }
+  if (extracted.cacheWriteTokens === void 0) {
+    const cacheWriteTokens = source.inputTokenDetails?.cacheWriteTokens;
+    if (typeof cacheWriteTokens === "number") {
+      extracted.cacheWriteTokens = cacheWriteTokens;
+    }
+  }
   return Object.keys(extracted).length > 0 ? extracted : void 0;
 }
 function rethrowWithTokenUsage(error, collectedUsage) {
@@ -565,6 +469,9 @@ var MuxAiError = class extends Error {
     this.publicMessage = message;
     this.retryable = opts?.retryable ?? false;
   }
+  static is(value) {
+    return typeof value === "object" && value !== null && "__robots_error" in value && value.__robots_error === true;
+  }
 };
 function extractErrorDetail(error) {
   if (error instanceof Error && error.message) {
@@ -582,7 +489,7 @@ function extractErrorDetail(error) {
   return "Unknown error";
 }
 function wrapError(error, message) {
-  if (error instanceof MuxAiError) {
+  if (MuxAiError.is(error)) {
     throw error;
   }
   const rawDetail = extractErrorDetail(error);
@@ -600,6 +507,260 @@ function wrapError(error, message) {
   throw wrapped;
 }
 
+// src/lib/content-policy-error.ts
+var PolicyTokenSchema = z2.string().trim().min(1).max(64).regex(/^[A-Z0-9_]+$/);
+var SafetyRatingSchema = z2.object({
+  category: PolicyTokenSchema.nullish(),
+  blocked: z2.boolean().nullish()
+});
+var ContentPolicyResponseSchema = z2.object({
+  promptFeedback: z2.object({
+    blockReason: PolicyTokenSchema.nullish(),
+    safetyRatings: z2.array(SafetyRatingSchema).max(32).nullish()
+  }).nullish(),
+  candidates: z2.array(z2.object({
+    finishReason: PolicyTokenSchema.nullish(),
+    safetyRatings: z2.array(SafetyRatingSchema).max(32).nullish()
+  })).max(8).nullish()
+});
+var ContentPolicyUsageResponseSchema = z2.object({
+  usageMetadata: z2.object({
+    promptTokenCount: z2.number().finite().nonnegative().nullish(),
+    candidatesTokenCount: z2.number().finite().nonnegative().nullish(),
+    totalTokenCount: z2.number().finite().nonnegative().nullish(),
+    cachedContentTokenCount: z2.number().finite().nonnegative().nullish(),
+    thoughtsTokenCount: z2.number().finite().nonnegative().nullish()
+  }).nullish()
+});
+var CONTENT_POLICY_REASONS = /* @__PURE__ */ new Set([
+  "BLOCKLIST",
+  "ESCALATION",
+  "IMAGE_PROHIBITED_CONTENT",
+  "IMAGE_RECITATION",
+  "IMAGE_SAFETY",
+  "JAILBREAK",
+  "MODEL_ARMOR",
+  "PROHIBITED_CONTENT",
+  "RECITATION",
+  "SAFETY",
+  "SPII"
+]);
+async function withContentPolicyErrorHandling(operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    rethrowContentPolicyError(error);
+  }
+}
+function rethrowContentPolicyError(error) {
+  const block = extractContentPolicyBlock(error);
+  if (!block) {
+    throw error;
+  }
+  throwContentPolicyError(block, getContentPolicyTokenUsage(error));
+}
+function getGeneratedOutputWithContentPolicyHandling(response) {
+  if (response.finishReason === "content-filter") {
+    const rawReason = PolicyTokenSchema.safeParse(response.rawFinishReason);
+    const reason = rawReason.success && isContentPolicyReason(rawReason.data) ? rawReason.data : "CONTENT_FILTER";
+    throwContentPolicyError({ reason }, getErrorTokenUsage(response));
+  }
+  return response.output;
+}
+function throwContentPolicyError(block, usage) {
+  const category = block.category ? `; category: ${block.category}` : "";
+  const contentPolicyError = new MuxAiError(
+    `The supplied content was blocked by a content policy (reason: ${block.reason}${category}).`,
+    {
+      type: "content_policy_error",
+      retryable: false
+    }
+  );
+  if (usage) {
+    contentPolicyError.usage = usage;
+  }
+  throw contentPolicyError;
+}
+function extractContentPolicyBlock(error) {
+  if (RetryError.isInstance(error)) {
+    return extractContentPolicyBlock(error.lastError);
+  }
+  if (NoObjectGeneratedError.isInstance(error) && error.finishReason === "content-filter") {
+    return { reason: "CONTENT_FILTER" };
+  }
+  if (!APICallError.isInstance(error) || !error.responseBody) {
+    return void 0;
+  }
+  try {
+    const parsed = ContentPolicyResponseSchema.safeParse(JSON.parse(error.responseBody));
+    if (!parsed.success) {
+      return void 0;
+    }
+    const promptReason = parsed.data.promptFeedback?.blockReason;
+    if (isContentPolicyReason(promptReason)) {
+      return {
+        reason: promptReason,
+        category: findBlockedCategory(parsed.data.promptFeedback?.safetyRatings)
+      };
+    }
+    for (const candidate of parsed.data.candidates ?? []) {
+      if (isContentPolicyReason(candidate.finishReason)) {
+        return {
+          reason: candidate.finishReason,
+          category: findBlockedCategory(candidate.safetyRatings)
+        };
+      }
+    }
+  } catch {
+    return void 0;
+  }
+  return void 0;
+}
+function isContentPolicyReason(reason) {
+  return Boolean(reason && CONTENT_POLICY_REASONS.has(reason));
+}
+function getContentPolicyTokenUsage(error) {
+  const errorUsage = getErrorTokenUsage(error);
+  if (errorUsage) {
+    return errorUsage;
+  }
+  if (RetryError.isInstance(error)) {
+    return getContentPolicyTokenUsage(error.lastError);
+  }
+  if (!APICallError.isInstance(error) || !error.responseBody) {
+    return void 0;
+  }
+  try {
+    const parsed = ContentPolicyUsageResponseSchema.safeParse(JSON.parse(error.responseBody));
+    const usage = parsed.success ? parsed.data.usageMetadata : void 0;
+    if (!usage) {
+      return void 0;
+    }
+    const inputTokens = usage.promptTokenCount ?? 0;
+    const reasoningTokens = usage.thoughtsTokenCount ?? 0;
+    const outputTokens = (usage.candidatesTokenCount ?? 0) + reasoningTokens;
+    return {
+      inputTokens,
+      outputTokens,
+      totalTokens: usage.totalTokenCount ?? inputTokens + outputTokens,
+      reasoningTokens,
+      cachedInputTokens: usage.cachedContentTokenCount ?? 0
+    };
+  } catch {
+    return void 0;
+  }
+}
+function findBlockedCategory(ratings) {
+  return ratings?.find((rating) => rating.blocked === true)?.category ?? void 0;
+}
+
+// src/lib/image-download.ts
+import pRetry, { AbortError } from "p-retry";
+var BASE64_CHUNK_SIZE = 32768;
+function bytesToBase64(bytes) {
+  if (bytes.length === 0) {
+    return "";
+  }
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += BASE64_CHUNK_SIZE) {
+    const chunk = bytes.subarray(i, i + BASE64_CHUNK_SIZE);
+    binary += String.fromCharCode(...chunk);
+  }
+  if (typeof globalThis.btoa !== "function") {
+    throw new TypeError("Base64 encoder is not available in this environment.");
+  }
+  return globalThis.btoa(binary);
+}
+var DEFAULT_OPTIONS = {
+  timeout: 1e4,
+  retries: 3,
+  retryDelay: 1e3,
+  maxRetryDelay: 1e4,
+  exponentialBackoff: true
+};
+async function downloadImageAsBase64(url, options = {}) {
+  "use step";
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let attemptCount = 0;
+  return pRetry(
+    async () => {
+      attemptCount++;
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), opts.timeout);
+      try {
+        const response = await fetch(url, {
+          signal: controller.signal,
+          headers: {
+            "User-Agent": "@mux/ai image downloader"
+          }
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+          if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+            throw new AbortError(`HTTP ${response.status}: ${response.statusText}`);
+          }
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        const contentType = response.headers.get("content-type");
+        if (!contentType?.startsWith("image/")) {
+          throw new AbortError(`Invalid content type: ${contentType}. Expected image/*`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        const buffer = new Uint8Array(arrayBuffer);
+        if (buffer.length === 0) {
+          throw new AbortError("Downloaded image is empty");
+        }
+        const base64Data = `data:${contentType};base64,${bytesToBase64(buffer)}`;
+        return {
+          base64Data,
+          buffer,
+          url,
+          contentType,
+          sizeBytes: buffer.length,
+          attempts: attemptCount
+        };
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof AbortError) {
+          throw error;
+        }
+        if (error instanceof Error) {
+          if (error.name === "AbortError") {
+            throw new Error(`Request timeout after ${opts.timeout}ms`);
+          }
+          throw new Error(`Download failed: ${error.message}`);
+        }
+        throw new Error("Unknown download error");
+      }
+    },
+    {
+      retries: opts.retries,
+      minTimeout: opts.retryDelay,
+      maxTimeout: opts.maxRetryDelay,
+      factor: opts.exponentialBackoff ? 2 : 1,
+      randomize: true,
+      // Add jitter to prevent thundering herd
+      onFailedAttempt: (error) => {
+        console.warn(`Image download attempt ${error.attemptNumber} failed for ${url}`);
+        if (error.retriesLeft > 0) {
+          console.warn(`Retrying... (${error.retriesLeft} attempts left)`);
+        }
+      }
+    }
+  );
+}
+async function downloadImagesAsBase64(urls, options = {}, maxConcurrent = 5) {
+  "use step";
+  const results = [];
+  for (let i = 0; i < urls.length; i += maxConcurrent) {
+    const batch = urls.slice(i, i + maxConcurrent);
+    const batchPromises = batch.map((url) => downloadImageAsBase64(url, options));
+    const batchResults = await Promise.all(batchPromises);
+    results.push(...batchResults);
+  }
+  return results;
+}
+
 // src/lib/providers.ts
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
@@ -936,7 +1097,8 @@ async function resolveMuxSigningContext(credentials) {
 
 // src/lib/providers.ts
 var DEFAULT_LANGUAGE_MODELS = {
-  openai: "gpt-5.1",
+  // GPT-5.6 models default to medium reasoning when no effort is specified.
+  openai: "gpt-5.6-luna",
   anthropic: "claude-sonnet-4-5",
   google: "gemini-3-flash-preview"
 };
@@ -945,11 +1107,20 @@ var DEFAULT_EMBEDDING_MODELS = {
   google: "gemini-embedding-001"
 };
 var LANGUAGE_MODELS = {
-  openai: ["gpt-5.1", "gpt-5-mini"],
+  openai: ["gpt-5.6-luna", "gpt-5.1", "gpt-5-mini"],
   anthropic: ["claude-sonnet-4-5"],
   google: ["gemini-3-flash-preview", "gemini-3.1-flash-lite", "gemini-2.5-flash"]
 };
 var LANGUAGE_MODEL_DEPRECATIONS = [
+  {
+    provider: "openai",
+    modelId: "gpt-5.1",
+    replacementModelId: "gpt-5.6-luna",
+    phase: "warn",
+    deprecatedOn: "2026-08-01",
+    sunsetOn: "2026-10-01",
+    reason: "GPT-5.6 Luna with its default medium reasoning effort is the new OpenAI default."
+  },
   {
     provider: "google",
     modelId: "gemini-2.5-flash",
@@ -1010,7 +1181,7 @@ function parseEvalModelPair(value) {
   const modelId = modelIdRaw?.trim();
   if (!provider || !modelId) {
     throw new Error(
-      `Invalid eval model pair "${value}". Use "provider:model" (example: "openai:gpt-5.1").`
+      `Invalid eval model pair "${value}". Use "provider:model" (example: "openai:gpt-5.6-luna").`
     );
   }
   if (!isSupportedProvider(provider)) {
@@ -1283,19 +1454,82 @@ async function withRetry(fn, {
     try {
       return await fn();
     } catch (error) {
-      lastError = error instanceof Error ? error : new Error(String(error));
+      lastError = error;
+      const retryError = error instanceof Error ? error : new Error(String(error));
       const isLastAttempt = attempt === maxRetries;
-      if (isLastAttempt || !shouldRetry(lastError, attempt + 1)) {
-        throw lastError;
+      if (isLastAttempt || !shouldRetry(retryError, attempt + 1)) {
+        throw error;
       }
       const delay = calculateDelay(attempt + 1, baseDelay, maxDelay);
       console.warn(
-        `Attempt ${attempt + 1} failed: ${lastError.message}. Retrying in ${Math.round(delay)}ms...`
+        `Attempt ${attempt + 1} failed: ${retryError.message}. Retrying in ${Math.round(delay)}ms...`
       );
       await new Promise((resolve) => setTimeout(resolve, delay));
     }
   }
-  throw lastError || new Error("Retry failed with unknown error");
+  throw lastError ?? new Error("Retry failed with unknown error");
+}
+
+// src/lib/workflow-scope.ts
+function hasWorkflowScopeBoundaries(scope) {
+  return scope?.startTime !== void 0 || scope?.endTime !== void 0;
+}
+function resolveWorkflowScope(scope, assetDurationSeconds) {
+  if (assetDurationSeconds === void 0 || !Number.isFinite(assetDurationSeconds) || assetDurationSeconds <= 0) {
+    throw new MuxAiError("Asset has no valid duration.", { type: "validation_error" });
+  }
+  const startTime = scope?.startTime ?? 0;
+  const endTime = scope?.endTime ?? assetDurationSeconds;
+  if (!Number.isFinite(startTime) || startTime < 0) {
+    throw new MuxAiError(
+      `scope.startTime must be a finite, non-negative number (received ${startTime}).`,
+      { type: "validation_error" }
+    );
+  }
+  if (!Number.isFinite(endTime) || endTime < 0) {
+    throw new MuxAiError(
+      `scope.endTime must be a finite, non-negative number (received ${endTime}).`,
+      { type: "validation_error" }
+    );
+  }
+  if (endTime > assetDurationSeconds) {
+    throw new MuxAiError(
+      `scope.endTime (${endTime}) cannot exceed the asset duration (${assetDurationSeconds}).`,
+      { type: "validation_error" }
+    );
+  }
+  if (startTime >= endTime) {
+    throw new MuxAiError(
+      `scope.startTime (${startTime}) must be less than scope.endTime (${endTime}).`,
+      { type: "validation_error" }
+    );
+  }
+  return { startTime, endTime };
+}
+function resolveRenderableVideoScope(scope, assetDurationSeconds, videoTrackDurationSeconds) {
+  if (!hasWorkflowScopeBoundaries(scope)) {
+    return void 0;
+  }
+  const resolvedScope = resolveWorkflowScope(scope, assetDurationSeconds);
+  let renderableEndTime = resolvedScope.endTime;
+  if (videoTrackDurationSeconds !== void 0 && Number.isFinite(videoTrackDurationSeconds) && videoTrackDurationSeconds >= 0) {
+    renderableEndTime = Math.min(videoTrackDurationSeconds, resolvedScope.endTime);
+  }
+  const renderableScope = {
+    startTime: Math.min(resolvedScope.startTime, renderableEndTime),
+    endTime: renderableEndTime
+  };
+  if (renderableScope.startTime >= renderableScope.endTime) {
+    throw new MuxAiError("The requested scope does not include any renderable video.", {
+      type: "validation_error"
+    });
+  }
+  return renderableScope;
+}
+function timeRangesOverlap(firstStart, firstEnd, second) {
+  const secondStart = second.startTime ?? 0;
+  const secondEnd = second.endTime ?? Number.POSITIVE_INFINITY;
+  return firstStart < secondEnd && firstEnd > secondStart;
 }
 
 // src/lib/mux-url.ts
@@ -1384,13 +1618,22 @@ async function signUrl(url, playbackId, type = "video", params, credentials) {
 
 // src/primitives/storyboards.ts
 var DEFAULT_STORYBOARD_WIDTH = 640;
-async function getStoryboardUrl(playbackId, width = DEFAULT_STORYBOARD_WIDTH, shouldSign = false, credentials) {
+async function getStoryboardUrl(playbackId, width = DEFAULT_STORYBOARD_WIDTH, shouldSign = false, credentials, scope) {
   "use step";
   const baseUrl = getMuxStoryboardBaseUrl(playbackId);
+  const params = { width };
+  if (scope?.startTime !== void 0) {
+    params.asset_start_time = scope.startTime;
+  }
+  if (scope?.endTime !== void 0) {
+    params.asset_end_time = scope.endTime;
+  }
   if (shouldSign) {
-    return signUrl(baseUrl, playbackId, "storyboard", { width }, credentials);
+    return signUrl(baseUrl, playbackId, "storyboard", params, credentials);
   }
-  return `${baseUrl}?width=${width}`;
+  return `${baseUrl}?${new URLSearchParams(
+    Object.entries(params).map(([key, value]) => [key, String(value)])
+  ).toString()}`;
 }
 
 // src/lib/language-codes.ts
@@ -1829,6 +2072,23 @@ function parseVTTCues(vttContent) {
   }
   return cues;
 }
+function filterVttByScope(vttContent, scope) {
+  if (!scope || scope.startTime === void 0 && scope.endTime === void 0) {
+    return vttContent;
+  }
+  const { preamble, cueBlocks } = splitVttPreambleAndCueBlocks(vttContent);
+  const scopedCueBlocks = cueBlocks.filter((cueBlock) => {
+    const cue = parseVTTCues(cueBlock)[0];
+    return cue ? timeRangesOverlap(cue.startTime, cue.endTime, scope) : false;
+  }).map((cueBlock, index) => {
+    const lines = cueBlock.split("\n");
+    if (/^\d+$/.test(lines[0]?.trim()) && lines[1]?.includes("-->")) {
+      lines[0] = String(index + 1);
+    }
+    return lines.join("\n");
+  });
+  return buildVttFromCueBlocks(scopedCueBlocks, preamble);
+}
 function splitVttPreambleAndCueBlocks(vttContent) {
   const normalizedContent = normalizeLineEndings(vttContent).trim();
   if (!normalizedContent) {
@@ -1933,6 +2193,7 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
   const {
     languageCode,
     cleanTranscript = true,
+    scope,
     shouldSign,
     credentials,
     required = false
@@ -1964,9 +2225,15 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
       return { transcriptText: "", transcriptUrl, track };
     }
     const rawVtt = await response.text();
-    const transcriptText = cleanTranscript ? extractTextFromVTT(rawVtt) : rawVtt;
-    if (required && !transcriptText.trim()) {
-      throw new MuxAiError("Transcript is empty.", { type: "validation_error" });
+    const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+    const scopedVtt = filterVttByScope(rawVtt, effectiveScope);
+    const transcriptText = cleanTranscript ? extractTextFromVTT(scopedVtt) : scopedVtt;
+    const hasScopedCues = !effectiveScope || parseVTTCues(scopedVtt).length > 0;
+    if (required && (!transcriptText.trim() || !hasScopedCues)) {
+      throw new MuxAiError(
+        effectiveScope ? "Transcript has no cues in the requested scope." : "Transcript is empty.",
+        { type: "validation_error" }
+      );
     }
     return { transcriptText, transcriptUrl, track };
   } catch (error) {
@@ -1979,17 +2246,20 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
 }
 
 // src/workflows/ask-questions.ts
-var questionAnswerSchema = z2.object({
-  question: z2.string().describe("The full text of the original question"),
-  answer: z2.string().nullable(),
-  confidence: z2.number(),
-  reasoning: z2.string().max(1e3),
-  skipped: z2.boolean()
+var ASK_QUESTIONS_MAX_QUESTION_LENGTH = 600;
+var ASK_QUESTIONS_DEFAULT_MAX_ANSWER_OPTION_LENGTH = 150;
+var ASK_QUESTIONS_DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH = 500;
+var questionAnswerSchema = z3.object({
+  question: z3.string().describe("The full text of the original question"),
+  answer: z3.string().nullable(),
+  confidence: z3.number(),
+  reasoning: z3.string().max(1e3),
+  skipped: z3.boolean()
 });
 var SKIP_SENTINEL = "__SKIPPED__";
 function createAskQuestionsSchema(answerSchema) {
-  return z2.object({
-    answers: z2.array(
+  return z3.object({
+    answers: z3.array(
       questionAnswerSchema.extend({
         answer: answerSchema
       })
@@ -2339,12 +2609,12 @@ function buildResponseSchemaForQuestions(normalizedQuestions, maxFreeFormAnswerL
       SKIP_SENTINEL.length,
       longestConstrained
     );
-    return createAskQuestionsSchema(z2.string().min(1).max(schemaMax));
+    return createAskQuestionsSchema(z3.string().min(1).max(schemaMax));
   }
   const allowed = Array.from(
     new Set(normalizedQuestions.flatMap(allowedAnswersForQuestion))
   );
-  return createAskQuestionsSchema(z2.enum([...allowed, SKIP_SENTINEL]));
+  return createAskQuestionsSchema(z3.enum([...allowed, SKIP_SENTINEL]));
 }
 async function analyzeQuestions({
   provider,
@@ -2362,7 +2632,7 @@ async function analyzeQuestions({
     normalizedQuestions,
     maxFreeFormAnswerLength
   );
-  const response = await generateText({
+  const response = await withContentPolicyErrorHandling(() => generateText({
     model,
     output: Output.object({ schema: responseSchema }),
     experimental_telemetry: { isEnabled: true },
@@ -2379,11 +2649,12 @@ async function analyzeQuestions({
         ] : userPrompt
       }
     ]
-  });
-  if (!response.output) {
+  }));
+  const output = getGeneratedOutputWithContentPolicyHandling(response);
+  if (!output) {
     throw new Error("Ask-questions output missing");
   }
-  const parsed = responseSchema.parse(response.output);
+  const parsed = responseSchema.parse(output);
   const unexpectedRootKeys = detectUnexpectedKeysFromRawText(
     response.text,
     responseSchema.keyof().options
@@ -2405,7 +2676,8 @@ async function analyzeQuestions({
       outputTokens: response.usage.outputTokens,
       totalTokens: response.usage.totalTokens,
       reasoningTokens: response.usage.reasoningTokens,
-      cachedInputTokens: response.usage.cachedInputTokens
+      cachedInputTokens: response.usage.cachedInputTokens,
+      cacheWriteTokens: response.usage.inputTokenDetails?.cacheWriteTokens
     },
     unexpectedRootKeys,
     unexpectedAnswerKeys
@@ -2424,7 +2696,6 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
   if (!questions || questions.length === 0) {
     throw new MuxAiError("At least one question must be provided.", { type: "validation_error" });
   }
-  const MAX_QUESTION_LENGTH = 500;
   questions.forEach((q, idx) => {
     if (!q.question || typeof q.question !== "string" || !q.question.trim()) {
       throw new MuxAiError(
@@ -2432,15 +2703,14 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
         { type: "validation_error" }
       );
     }
-    if (q.question.length > MAX_QUESTION_LENGTH) {
+    if (q.question.length > ASK_QUESTIONS_MAX_QUESTION_LENGTH) {
       throw new MuxAiError(
-        `Question at index ${idx} exceeds the ${MAX_QUESTION_LENGTH}-character limit (received ${q.question.length}).`,
+        `Question at index ${idx} exceeds the ${ASK_QUESTIONS_MAX_QUESTION_LENGTH}-character limit (received ${q.question.length}).`,
         { type: "validation_error" }
       );
     }
   });
-  const DEFAULT_MAX_ANSWER_OPTION_LENGTH = 150;
-  const maxAnswerOptionLength = options?.maxAnswerOptionLength ?? DEFAULT_MAX_ANSWER_OPTION_LENGTH;
+  const maxAnswerOptionLength = options?.maxAnswerOptionLength ?? ASK_QUESTIONS_DEFAULT_MAX_ANSWER_OPTION_LENGTH;
   if (!Number.isFinite(maxAnswerOptionLength) || maxAnswerOptionLength <= 0) {
     throw new MuxAiError(
       `maxAnswerOptionLength must be a positive number (received ${maxAnswerOptionLength}).`,
@@ -2459,8 +2729,7 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
       }
     }
   });
-  const DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH = 500;
-  const maxFreeFormAnswerLength = options?.maxFreeFormAnswerLength ?? DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH;
+  const maxFreeFormAnswerLength = options?.maxFreeFormAnswerLength ?? ASK_QUESTIONS_DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH;
   if (!Number.isFinite(maxFreeFormAnswerLength) || maxFreeFormAnswerLength <= 0) {
     throw new MuxAiError(
       `maxFreeFormAnswerLength must be a positive number (received ${maxFreeFormAnswerLength}).`,
@@ -2476,7 +2745,8 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
     imageSubmissionMode = "url",
     imageDownloadOptions,
     storyboardWidth = 640,
-    credentials
+    credentials,
+    scope
   } = options ?? {};
   const normalizedQuestions = questions.map((q, idx) => normalizeQuestion(q, idx));
   const hasFreeForm = normalizedQuestions.some((q) => q.mode.kind === "freeForm");
@@ -2488,6 +2758,15 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
   const isAudioOnly = isAudioOnlyAsset(assetData);
+  const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+  const storyboardScope = isAudioOnly ? void 0 : resolveRenderableVideoScope(
+    effectiveScope,
+    assetDurationSeconds,
+    getVideoTrackDurationSecondsFromAsset(assetData)
+  );
+  if (isAudioOnly && effectiveScope) {
+    resolveWorkflowScope(effectiveScope, assetDurationSeconds);
+  }
   if (isAudioOnly && !includeTranscript) {
     throw new MuxAiError(
       "Audio-only assets require a transcript. Set includeTranscript: true and ensure the asset has a ready text track (captions/subtitles).",
@@ -2506,7 +2785,8 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
     cleanTranscript,
     shouldSign: policy === "signed",
     credentials,
-    required: isAudioOnly
+    required: isAudioOnly,
+    scope: effectiveScope
   }) : void 0;
   const transcriptText = transcriptResult?.transcriptText ?? "";
   const userPrompt = buildUserPrompt({
@@ -2535,7 +2815,8 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
         playbackId,
         storyboardWidth,
         policy === "signed",
-        credentials
+        credentials,
+        storyboardScope
       );
       imageUrl = storyboardUrl;
       if (imageSubmissionMode === "base64") {
@@ -2650,11 +2931,11 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
 // src/workflows/burned-in-captions.ts
 import { generateText as generateText2, Output as Output2 } from "ai";
 import dedent3 from "dedent";
-import { z as z3 } from "zod";
-var burnedInCaptionsSchema = z3.object({
-  hasBurnedInCaptions: z3.boolean(),
-  confidence: z3.number(),
-  detectedLanguage: z3.string().max(100).nullable()
+import { z as z4 } from "zod";
+var burnedInCaptionsSchema = z4.object({
+  hasBurnedInCaptions: z4.boolean(),
+  confidence: z4.number(),
+  detectedLanguage: z4.string().max(100).nullable()
 });
 var SYSTEM_PROMPT2 = promptDedent`
   <role>
@@ -2764,7 +3045,7 @@ async function analyzeStoryboard({
 }) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
-  const response = await generateText2({
+  const response = await withContentPolicyErrorHandling(() => generateText2({
     model,
     output: Output2.object({ schema: burnedInCaptionsSchema }),
     experimental_telemetry: { isEnabled: true },
@@ -2781,22 +3062,24 @@ async function analyzeStoryboard({
         ]
       }
     ]
-  });
+  }));
+  const output = getGeneratedOutputWithContentPolicyHandling(response);
   const unexpectedKeys = detectUnexpectedKeysFromRawText(
     response.text,
     burnedInCaptionsSchema.keyof().options
   );
   return {
     result: {
-      ...response.output,
-      confidence: Math.min(1, Math.max(0, response.output.confidence))
+      ...output,
+      confidence: Math.min(1, Math.max(0, output.confidence))
     },
     usage: {
       inputTokens: response.usage.inputTokens,
       outputTokens: response.usage.outputTokens,
       totalTokens: response.usage.totalTokens,
       reasoningTokens: response.usage.reasoningTokens,
-      cachedInputTokens: response.usage.cachedInputTokens
+      cachedInputTokens: response.usage.cachedInputTokens,
+      cacheWriteTokens: response.usage.inputTokenDetails?.cacheWriteTokens
     },
     unexpectedKeys
   };
@@ -2818,6 +3101,7 @@ async function hasBurnedInCaptionsInternal(assetId, options, collectedUsage) {
     imageDownloadOptions,
     promptOverrides,
     credentials,
+    scope,
     ...config
   } = options;
   const userPrompt = buildUserPrompt2(promptOverrides);
@@ -2828,7 +3112,18 @@ async function hasBurnedInCaptionsInternal(assetId, options, collectedUsage) {
   });
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
-  const imageUrl = await getStoryboardUrl(playbackId, 640, policy === "signed", credentials);
+  const storyboardScope = resolveRenderableVideoScope(
+    scope,
+    assetDurationSeconds,
+    getVideoTrackDurationSecondsFromAsset(assetData)
+  );
+  const imageUrl = await getStoryboardUrl(
+    playbackId,
+    640,
+    policy === "signed",
+    credentials,
+    storyboardScope
+  );
   let analysisResponse;
   if (imageSubmissionMode === "base64") {
     const base64Data = await fetchImageAsBase642(imageUrl, imageDownloadOptions);
@@ -2882,13 +3177,13 @@ async function hasBurnedInCaptionsInternal(assetId, options, collectedUsage) {
 // src/workflows/chapters.ts
 import { generateText as generateText3, Output as Output3 } from "ai";
 import dedent4 from "dedent";
-import { z as z4 } from "zod";
-var chapterSchema = z4.object({
-  startTime: z4.number(),
-  title: z4.string().max(300)
+import { z as z5 } from "zod";
+var chapterSchema = z5.object({
+  startTime: z5.number(),
+  title: z5.string().max(300)
 });
-var chaptersSchema = z4.object({
-  chapters: z4.array(chapterSchema)
+var chaptersSchema = z5.object({
+  chapters: z5.array(chapterSchema)
 });
 async function generateChaptersWithAI({
   provider,
@@ -2900,21 +3195,24 @@ async function generateChaptersWithAI({
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
   const response = await withRetry(
-    () => generateText3({
-      model,
-      output: Output3.object({ schema: chaptersSchema }),
-      messages: [
-        {
-          role: "system",
-          content: systemPrompt
-        },
-        {
-          role: "user",
-          content: userPrompt
-        }
-      ]
-    })
+    () => withContentPolicyErrorHandling(
+      () => generateText3({
+        model,
+        output: Output3.object({ schema: chaptersSchema }),
+        messages: [
+          {
+            role: "system",
+            content: systemPrompt
+          },
+          {
+            role: "user",
+            content: userPrompt
+          }
+        ]
+      })
+    )
   );
+  const output = getGeneratedOutputWithContentPolicyHandling(response);
   const unexpectedRootKeys = detectUnexpectedKeysFromRawText(
     response.text,
     chaptersSchema.keyof().options
@@ -2930,13 +3228,14 @@ async function generateChaptersWithAI({
   } catch {
   }
   return {
-    chapters: response.output,
+    chapters: output,
     usage: {
       inputTokens: response.usage.inputTokens,
       outputTokens: response.usage.outputTokens,
       totalTokens: response.usage.totalTokens,
       reasoningTokens: response.usage.reasoningTokens,
-      cachedInputTokens: response.usage.cachedInputTokens
+      cachedInputTokens: response.usage.cachedInputTokens,
+      cacheWriteTokens: response.usage.inputTokenDetails?.cacheWriteTokens
     },
     unexpectedRootKeys,
     unexpectedChapterKeys
@@ -3027,7 +3326,8 @@ function buildUserPrompt3({
   promptOverrides,
   minChaptersPerHour = 3,
   maxChaptersPerHour = 8,
-  languageName
+  languageName,
+  scope
 }) {
   const contextSections = [
     {
@@ -3042,6 +3342,8 @@ function buildUserPrompt3({
   const dynamicChapterGuidelines = dedent4`
     - Create at least ${minChaptersPerHour} and at most ${maxChaptersPerHour} chapters per hour of content
     - Use start times in seconds (not HH:MM:SS)
+    ${scope ? `- Analyze only the range from ${scope.startTime}s (inclusive) to ${scope.endTime}s (exclusive)
+- The first chapter must start at ${scope.startTime}s` : ""}
     - Chapter start times should be non-decreasing
     - Do not include text before or after the JSON`;
   const mergedOverrides = {
@@ -3068,7 +3370,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     minChaptersPerHour,
     maxChaptersPerHour,
     credentials,
-    outputLanguageCode
+    outputLanguageCode,
+    scope
   } = options;
   const modelConfig = resolveLanguageModelConfig({
     ...options,
@@ -3077,6 +3380,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
   });
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
+  const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+  const resolvedScope = effectiveScope ? resolveWorkflowScope(effectiveScope, assetDurationSeconds) : void 0;
   const isAudioOnly = isAudioOnlyAsset(assetData);
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
@@ -3091,7 +3396,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     cleanTranscript: false,
     // keep timestamps for chapter segmentation
     shouldSign: policy === "signed",
-    credentials
+    credentials,
+    scope: effectiveScope
   });
   if (!transcriptResult.track || !transcriptResult.transcriptText) {
     const availableLanguages = readyTextTracks.map((t) => t.language_code).filter(Boolean).join(", ");
@@ -3112,7 +3418,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     promptOverrides,
     minChaptersPerHour,
     maxChaptersPerHour,
-    languageName
+    languageName,
+    scope: resolvedScope
   });
   let chaptersData = null;
   try {
@@ -3134,7 +3441,9 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     throw new MuxAiError(`Failed to generate chapters for asset ${assetId}.`);
   }
   const { chapters: chaptersPayload, usage } = chaptersData;
-  const validChapters = chaptersPayload.chapters.filter((chapter) => typeof chapter.startTime === "number" && typeof chapter.title === "string").sort((a, b) => a.startTime - b.startTime);
+  const validChapters = chaptersPayload.chapters.filter((chapter) => typeof chapter.startTime === "number" && typeof chapter.title === "string").filter(
+    (chapter) => resolvedScope ? chapter.startTime >= resolvedScope.startTime && chapter.startTime < resolvedScope.endTime : true
+  ).sort((a, b) => a.startTime - b.startTime);
   if (validChapters.length === 0) {
     throw new MuxAiError(`Failed to generate valid chapters for asset ${assetId}.`);
   }
@@ -3160,8 +3469,9 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
   if (scrubbedChapters.length === 0) {
     throw new MuxAiError(`Failed to generate valid chapters for asset ${assetId}.`);
   }
-  if (scrubbedChapters[0].startTime !== 0) {
-    scrubbedChapters[0].startTime = 0;
+  const firstChapterStartTime = resolvedScope?.startTime ?? 0;
+  if (scrubbedChapters[0].startTime !== firstChapterStartTime) {
+    scrubbedChapters[0].startTime = firstChapterStartTime;
   }
   const usageWithMetadata = {
     ...usage,
@@ -3181,7 +3491,7 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
 
 // src/workflows/edit-captions.ts
 import { generateText as generateText4, Output as Output4 } from "ai";
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 
 // src/lib/mux-tracks.ts
 async function fetchVttFromMux(vttUrl) {
@@ -3464,8 +3774,8 @@ async function createPresignedGetUrlWithStorageAdapter(input, adapter) {
 }
 
 // src/workflows/edit-captions.ts
-var profanityDetectionSchema = z5.object({
-  profanity: z5.array(z5.string().max(100)).describe(
+var profanityDetectionSchema = z6.object({
+  profanity: z6.array(z6.string().max(100)).describe(
     "Unique profane words or short phrases exactly as they appear in the transcript text. Include each distinct form only once (e.g., if 'fuck' and 'fucking' both appear, list both)."
   )
 });
@@ -3642,7 +3952,7 @@ async function identifyProfanityWithAI({
     tag: "transcript",
     content: plainText
   });
-  const response = await generateText4({
+  const response = await withContentPolicyErrorHandling(() => generateText4({
     model,
     output: Output4.object({ schema: profanityDetectionSchema }),
     messages: [
@@ -3657,19 +3967,21 @@ async function identifyProfanityWithAI({
 ${transcriptSection}`
       }
     ]
-  });
+  }));
+  const output = getGeneratedOutputWithContentPolicyHandling(response);
   const unexpectedKeys = detectUnexpectedKeysFromRawText(
     response.text,
     profanityDetectionSchema.keyof().options
   );
   return {
-    profanity: response.output.profanity,
+    profanity: output.profanity,
     usage: {
       inputTokens: response.usage.inputTokens,
       outputTokens: response.usage.outputTokens,
       totalTokens: response.usage.totalTokens,
       reasoningTokens: response.usage.reasoningTokens,
-      cachedInputTokens: response.usage.cachedInputTokens
+      cachedInputTokens: response.usage.cachedInputTokens,
+      cacheWriteTokens: response.usage.inputTokenDetails?.cacheWriteTokens
     },
     unexpectedKeys
   };
@@ -4192,11 +4504,16 @@ async function generateEmbeddingsInternal(assetId, options, collectedUsage) {
     languageCode,
     chunkingStrategy = { type: "token", maxTokens: 500, overlap: 100 },
     batchSize = 5,
-    credentials
+    credentials,
+    scope
   } = options;
   const embeddingModel = resolveEmbeddingModelConfig({ ...options, provider, model });
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
+  const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+  if (effectiveScope) {
+    resolveWorkflowScope(effectiveScope, assetDurationSeconds);
+  }
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
     throw new Error(
@@ -4209,7 +4526,8 @@ async function generateEmbeddingsInternal(assetId, options, collectedUsage) {
     cleanTranscript: !useVttChunking,
     shouldSign: policy === "signed",
     credentials,
-    required: true
+    required: true,
+    scope: effectiveScope
   });
   const transcriptText = transcriptResult.transcriptText;
   const chunks = useVttChunking ? chunkVTTCues(
@@ -4306,7 +4624,7 @@ async function generateVideoEmbeddings(assetId, options = {}) {
 // src/workflows/engagement-insights.ts
 import { generateText as generateText5, Output as Output5 } from "ai";
 import dedent5 from "dedent";
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 
 // src/primitives/heatmap.ts
 async function getHeatmapForAsset(assetId, options = {}) {
@@ -4453,20 +4771,20 @@ async function getShotsForAsset(assetId, options = {}) {
 }
 
 // src/workflows/engagement-insights.ts
-var aiMomentInsightSchema = z6.object({
-  hotspotIndex: z6.number(),
-  startMs: z6.number(),
-  endMs: z6.number(),
-  timestamp: z6.string(),
-  engagementScore: z6.number(),
-  insight: z6.string().max(1e3)
+var aiMomentInsightSchema = z7.object({
+  hotspotIndex: z7.number(),
+  startMs: z7.number(),
+  endMs: z7.number(),
+  timestamp: z7.string(),
+  engagementScore: z7.number(),
+  insight: z7.string().max(1e3)
 });
-var aiOverallInsightSchema = z6.object({
-  summary: z6.string().max(2e3),
-  trends: z6.array(z6.string().max(500))
+var aiOverallInsightSchema = z7.object({
+  summary: z7.string().max(2e3),
+  trends: z7.array(z7.string().max(500))
 });
-var engagementInsightsSchema = z6.object({
-  momentInsights: z6.array(aiMomentInsightSchema),
+var engagementInsightsSchema = z7.object({
+  momentInsights: z7.array(aiMomentInsightSchema),
   overallInsight: aiOverallInsightSchema
 });
 var SYSTEM_PROMPT4 = promptDedent`
@@ -4728,26 +5046,29 @@ async function generateInsightsWithAI(provider, modelId, systemPrompt, userPromp
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
   const response = await withRetry(
-    () => generateText5({
-      model,
-      output: Output5.object({ schema: engagementInsightsSchema }),
-      experimental_telemetry: { isEnabled: true },
-      messages: [
-        {
-          role: "system",
-          content: systemPrompt
-        },
-        {
-          role: "user",
-          content: [
-            { type: "text", text: userPrompt },
-            ...imageUrls.map((url) => ({ type: "image", image: url }))
-          ]
-        }
-      ]
-    })
+    () => withContentPolicyErrorHandling(
+      () => generateText5({
+        model,
+        output: Output5.object({ schema: engagementInsightsSchema }),
+        experimental_telemetry: { isEnabled: true },
+        messages: [
+          {
+            role: "system",
+            content: systemPrompt
+          },
+          {
+            role: "user",
+            content: [
+              { type: "text", text: userPrompt },
+              ...imageUrls.map((url) => ({ type: "image", image: url }))
+            ]
+          }
+        ]
+      })
+    )
   );
-  if (!response.output) {
+  const output = getGeneratedOutputWithContentPolicyHandling(response);
+  if (!output) {
     throw new Error("AI returned empty or unparseable response");
   }
   const unexpectedRootKeys = detectUnexpectedKeysFromRawText(
@@ -4770,13 +5091,14 @@ async function generateInsightsWithAI(provider, modelId, systemPrompt, userPromp
   } catch {
   }
   return {
-    result: response.output,
+    result: output,
     usage: {
       inputTokens: response.usage.inputTokens,
       outputTokens: response.usage.outputTokens,
       totalTokens: response.usage.totalTokens,
       reasoningTokens: response.usage.reasoningTokens,
-      cachedInputTokens: response.usage.cachedInputTokens
+      cachedInputTokens: response.usage.cachedInputTokens,
+      cacheWriteTokens: response.usage.inputTokenDetails?.cacheWriteTokens
     },
     unexpectedRootKeys,
     unexpectedMomentKeys,
@@ -5048,27 +5370,32 @@ function planSamplingTimestamps(options) {
 // src/primitives/thumbnails.ts
 async function getThumbnailUrls(playbackId, duration, options = {}) {
   "use step";
-  const { interval = 10, width = 640, shouldSign = false, maxSamples, credentials } = options;
+  const { interval = 10, width = 640, shouldSign = false, maxSamples, credentials, scope } = options;
+  const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+  const resolvedScope = effectiveScope ? resolveWorkflowScope(effectiveScope, duration) : { startTime: 0, endTime: duration };
+  const rangeDuration = resolvedScope.endTime - resolvedScope.startTime;
   let timestamps = [];
-  if (duration <= 50) {
-    const spacing = duration / 6;
+  if (rangeDuration <= 50) {
+    const spacing = rangeDuration / 6;
     for (let i = 1; i <= 5; i++) {
-      timestamps.push(Math.round(i * spacing));
+      const time = resolvedScope.startTime + i * spacing;
+      timestamps.push(effectiveScope ? Number(time.toFixed(3)) : Math.round(time));
     }
   } else {
-    for (let time = 0; time < duration; time += interval) {
+    for (let time = resolvedScope.startTime; time < resolvedScope.endTime; time += interval) {
       timestamps.push(time);
     }
   }
   if (maxSamples !== void 0 && timestamps.length > maxSamples) {
     const newTimestamps = [];
-    newTimestamps.push(0);
+    newTimestamps.push(resolvedScope.startTime);
     if (maxSamples >= 2) {
-      const spacing = duration / (maxSamples - 1);
+      const lastTime = effectiveScope ? Math.max(resolvedScope.startTime, resolvedScope.endTime - 1e-3) : resolvedScope.endTime;
+      const spacing = (lastTime - resolvedScope.startTime) / (maxSamples - 1);
       for (let i = 1; i < maxSamples - 1; i++) {
-        newTimestamps.push(spacing * i);
+        newTimestamps.push(resolvedScope.startTime + spacing * i);
       }
-      newTimestamps.push(duration);
+      newTimestamps.push(lastTime);
     }
     timestamps = newTimestamps;
   }
@@ -5521,12 +5848,24 @@ async function requestGoogleVisionModeration(images, maxConcurrent = 5, submissi
   }));
   return processConcurrently(targets, moderateImageWithGoogleVision, maxConcurrent);
 }
+function toThumbnailTimeSeconds(timestampMs) {
+  return Number((timestampMs / 1e3).toFixed(2));
+}
+function filterTimestampsWithinExclusiveScope(timestampsMs, scope) {
+  if (!scope) {
+    return timestampsMs;
+  }
+  return timestampsMs.filter((timestampMs) => {
+    const time = toThumbnailTimeSeconds(timestampMs);
+    return time >= scope.startTime && time < scope.endTime;
+  });
+}
 async function getThumbnailUrlsFromTimestamps(playbackId, timestampsMs, options) {
   "use step";
   const { width, shouldSign, credentials } = options;
   const baseUrl = getMuxThumbnailBaseUrl(playbackId);
   const urlPromises = timestampsMs.map(async (tsMs) => {
-    const time = Number((tsMs / 1e3).toFixed(2));
+    const time = toThumbnailTimeSeconds(tsMs);
     const url = shouldSign ? await signUrl(baseUrl, playbackId, "thumbnail", { time, width }, credentials) : `${baseUrl}?time=${time}&width=${width}`;
     return { url, time };
   });
@@ -5545,7 +5884,8 @@ async function getModerationScores(assetId, options = {}) {
     maxConcurrent = 5,
     imageSubmissionMode = "url",
     imageDownloadOptions,
-    credentials: providedCredentials
+    credentials: providedCredentials,
+    scope
   } = options;
   const credentials = providedCredentials;
   const { asset, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
@@ -5556,7 +5896,16 @@ async function getModerationScores(assetId, options = {}) {
     (d) => d != null
   );
   const duration = candidateDurations.length > 0 ? Math.min(...candidateDurations) : 0;
+  const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+  const resolvedScope = effectiveScope ? resolveWorkflowScope(effectiveScope, assetDurationSeconds) : void 0;
   const isAudioOnly = isAudioOnlyAsset(asset);
+  const renderableScope = resolvedScope ? {
+    startTime: Math.min(resolvedScope.startTime, duration),
+    endTime: Math.min(resolvedScope.endTime, duration)
+  } : void 0;
+  if (!isAudioOnly && renderableScope && renderableScope.startTime >= renderableScope.endTime) {
+    throw new Error("The requested scope does not include any renderable video.");
+  }
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
     throw new Error(
@@ -5573,7 +5922,8 @@ async function getModerationScores(assetId, options = {}) {
       cleanTranscript: true,
       shouldSign: policy === "signed",
       credentials,
-      required: true
+      required: true,
+      scope: effectiveScope
     });
     if (provider === "openai") {
       thumbnailScores = await requestOpenAITranscriptModeration(
@@ -5591,17 +5941,21 @@ async function getModerationScores(assetId, options = {}) {
       throw new Error(`Unsupported moderation provider: ${exhaustiveCheck}`);
     }
   } else {
-    const estimatedIntervalCount = duration <= 50 ? 5 : Math.ceil(duration / thumbnailInterval);
+    const scopedDuration = renderableScope ? renderableScope.endTime - renderableScope.startTime : duration;
+    const estimatedIntervalCount = scopedDuration <= 50 ? 5 : Math.ceil(scopedDuration / thumbnailInterval);
     const thumbnailUrls = maxSamples !== void 0 && estimatedIntervalCount > maxSamples ? await getThumbnailUrlsFromTimestamps(
       playbackId,
-      planSamplingTimestamps({
-        duration_sec: duration,
-        max_candidates: maxSamples,
-        trim_start_sec: duration > 2 ? Math.min(5, Math.max(1, duration / 6)) : 0,
-        trim_end_sec: duration > 2 ? Math.min(5, Math.max(1, duration / 6)) : 0,
-        fps: videoTrackFps,
-        base_cadence_hz: thumbnailInterval > 0 ? 1 / thumbnailInterval : void 0
-      }),
+      filterTimestampsWithinExclusiveScope(
+        planSamplingTimestamps({
+          duration_sec: duration,
+          max_candidates: maxSamples,
+          trim_start_sec: renderableScope?.startTime ?? (duration > 2 ? Math.min(5, Math.max(1, duration / 6)) : 0),
+          trim_end_sec: renderableScope ? duration - renderableScope.endTime : duration > 2 ? Math.min(5, Math.max(1, duration / 6)) : 0,
+          fps: videoTrackFps,
+          base_cadence_hz: thumbnailInterval > 0 ? 1 / thumbnailInterval : void 0
+        }),
+        renderableScope
+      ),
       {
         width: thumbnailWidth,
         shouldSign: policy === "signed",
@@ -5611,7 +5965,8 @@ async function getModerationScores(assetId, options = {}) {
       interval: thumbnailInterval,
       width: thumbnailWidth,
       shouldSign: policy === "signed",
-      credentials
+      credentials,
+      scope: renderableScope
     });
     thumbnailCount = thumbnailUrls.length;
     if (provider === "openai") {
@@ -5697,7 +6052,7 @@ async function getModerationScores(assetId, options = {}) {
 // src/workflows/summarization.ts
 import { generateText as generateText6, Output as Output6 } from "ai";
 import dedent6 from "dedent";
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 
 // src/lib/markdown-normalization.ts
 var ESCAPED_LINE_BREAK_REGEX = /\\r\\n|\\n|\\r/g;
@@ -5710,17 +6065,17 @@ function normalizeMarkdownDescription(description) {
 var DEFAULT_SUMMARY_KEYWORD_LIMIT = 10;
 var DEFAULT_TITLE_LENGTH = 10;
 var DEFAULT_DESCRIPTION_LENGTH = 50;
-var summarySchema = z7.object({
-  keywords: z7.array(z7.string().max(200)),
-  title: z7.string().max(500),
-  description: z7.string().max(1e4)
+var summarySchema = z8.object({
+  keywords: z8.array(z8.string().max(200)),
+  title: z8.string().max(500),
+  description: z8.string().max(1e4)
 });
 function buildSummarySchema(descriptionLength) {
   const descriptionMaxChars = Math.max(2e3, descriptionLength * 15);
-  return z7.object({
-    keywords: z7.array(z7.string().max(200)),
-    title: z7.string().max(500),
-    description: z7.string().max(descriptionMaxChars)
+  return z8.object({
+    keywords: z8.array(z8.string().max(200)),
+    title: z8.string().max(500),
+    description: z8.string().max(descriptionMaxChars)
   });
 }
 var VALID_TONES = ["neutral", "playful", "professional"];
@@ -5996,7 +6351,7 @@ async function analyzeStoryboard2(imageDataUrl, provider, modelId, userPrompt, s
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
   const schema = buildSummarySchema(descriptionLength);
-  const response = await generateText6({
+  const response = await withContentPolicyErrorHandling(() => generateText6({
     model,
     output: Output6.object({
       name: "summary_metadata",
@@ -6016,11 +6371,12 @@ async function analyzeStoryboard2(imageDataUrl, provider, modelId, userPrompt, s
         ]
       }
     ]
-  });
-  if (!response.output) {
+  }));
+  const output = getGeneratedOutputWithContentPolicyHandling(response);
+  if (!output) {
     throw new Error("Summarization output missing");
   }
-  const parsed = schema.parse(response.output);
+  const parsed = schema.parse(output);
   const unexpectedKeys = detectUnexpectedKeysFromRawText(
     response.text,
     schema.keyof().options
@@ -6032,7 +6388,8 @@ async function analyzeStoryboard2(imageDataUrl, provider, modelId, userPrompt, s
       outputTokens: response.usage.outputTokens,
       totalTokens: response.usage.totalTokens,
       reasoningTokens: response.usage.reasoningTokens,
-      cachedInputTokens: response.usage.cachedInputTokens
+      cachedInputTokens: response.usage.cachedInputTokens,
+      cacheWriteTokens: response.usage.inputTokenDetails?.cacheWriteTokens
     },
     unexpectedKeys
   };
@@ -6041,7 +6398,7 @@ async function analyzeAudioOnly(provider, modelId, userPrompt, systemPrompt, des
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
   const schema = buildSummarySchema(descriptionLength);
-  const response = await generateText6({
+  const response = await withContentPolicyErrorHandling(() => generateText6({
     model,
     output: Output6.object({
       name: "summary_metadata",
@@ -6058,11 +6415,12 @@ async function analyzeAudioOnly(provider, modelId, userPrompt, systemPrompt, des
         content: userPrompt
       }
     ]
-  });
-  if (!response.output) {
+  }));
+  const output = getGeneratedOutputWithContentPolicyHandling(response);
+  if (!output) {
     throw new Error("Summarization output missing");
   }
-  const parsed = schema.parse(response.output);
+  const parsed = schema.parse(output);
   const unexpectedKeys = detectUnexpectedKeysFromRawText(
     response.text,
     schema.keyof().options
@@ -6074,7 +6432,8 @@ async function analyzeAudioOnly(provider, modelId, userPrompt, systemPrompt, des
       outputTokens: response.usage.outputTokens,
       totalTokens: response.usage.totalTokens,
       reasoningTokens: response.usage.reasoningTokens,
-      cachedInputTokens: response.usage.cachedInputTokens
+      cachedInputTokens: response.usage.cachedInputTokens,
+      cacheWriteTokens: response.usage.inputTokenDetails?.cacheWriteTokens
     },
     unexpectedKeys
   };
@@ -6126,7 +6485,8 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
     titleLength,
     descriptionLength,
     tagCount,
-    outputLanguageCode
+    outputLanguageCode,
+    scope
   } = options ?? {};
   if (!VALID_TONES.includes(tone)) {
     throw new MuxAiError(
@@ -6143,6 +6503,15 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, workflowCredentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
   const isAudioOnly = isAudioOnlyAsset(assetData);
+  const effectiveScope = hasWorkflowScopeBoundaries(scope) ? scope : void 0;
+  const storyboardScope = isAudioOnly ? void 0 : resolveRenderableVideoScope(
+    effectiveScope,
+    assetDurationSeconds,
+    getVideoTrackDurationSecondsFromAsset(assetData)
+  );
+  if (isAudioOnly && effectiveScope) {
+    resolveWorkflowScope(effectiveScope, assetDurationSeconds);
+  }
   if (isAudioOnly && !includeTranscript) {
     throw new MuxAiError(
       "Audio-only assets require a transcript. Set includeTranscript: true and ensure the asset has a ready text track (captions/subtitles).",
@@ -6161,7 +6530,8 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
     cleanTranscript,
     shouldSign: policy === "signed",
     credentials: workflowCredentials,
-    required: isAudioOnly
+    required: isAudioOnly,
+    scope: effectiveScope
   }) : void 0;
   const transcriptText = transcriptResult?.transcriptText ?? "";
   const resolvedLanguageCode = outputLanguageCode && outputLanguageCode !== "auto" ? outputLanguageCode : getReliableLanguageCode(transcriptResult?.track) ?? getReliableLanguageCode(getReadyTextTracks(assetData)[0]);
@@ -6192,7 +6562,13 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
         workflowCredentials
       );
     } else {
-      const storyboardUrl = await getStoryboardUrl(playbackId, 640, policy === "signed", workflowCredentials);
+      const storyboardUrl = await getStoryboardUrl(
+        playbackId,
+        640,
+        policy === "signed",
+        workflowCredentials,
+        storyboardScope
+      );
       imageUrl = storyboardUrl;
       if (imageSubmissionMode === "base64") {
         const downloadResult = await downloadImageAsBase64(storyboardUrl, imageDownloadOptions);
@@ -6628,16 +7004,16 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
 
 // src/workflows/translate-captions.ts
 import {
-  APICallError,
+  APICallError as APICallError2,
   generateText as generateText7,
-  NoObjectGeneratedError,
+  NoObjectGeneratedError as NoObjectGeneratedError2,
   Output as Output7,
-  RetryError,
+  RetryError as RetryError2,
   TypeValidationError
 } from "ai";
-import { z as z8 } from "zod";
-var translationSchema = z8.object({
-  translation: z8.string()
+import { z as z9 } from "zod";
+var translationSchema = z9.object({
+  translation: z9.string()
 });
 var SYSTEM_PROMPT6 = promptDedent`
   You are a subtitle translation expert. Translate VTT subtitle files to the target language specified by the user.
@@ -6704,10 +7080,10 @@ function isProviderServiceError(error) {
   if (!error) {
     return false;
   }
-  if (RetryError.isInstance(error)) {
+  if (RetryError2.isInstance(error)) {
     return isProviderServiceError(error.lastError);
   }
-  if (APICallError.isInstance(error)) {
+  if (APICallError2.isInstance(error)) {
     return true;
   }
   if (error instanceof Error && "cause" in error) {
@@ -6719,7 +7095,7 @@ function shouldSplitChunkTranslationError(error) {
   if (isProviderServiceError(error)) {
     return false;
   }
-  return NoObjectGeneratedError.isInstance(error) || TypeValidationError.isInstance(error) || isTranslationChunkValidationError(error);
+  return NoObjectGeneratedError2.isInstance(error) || TypeValidationError.isInstance(error) || isTranslationChunkValidationError(error);
 }
 function resolveTranslationChunkingOptions(options) {
   const targetChunkDurationSeconds = Math.max(
@@ -6880,7 +7256,7 @@ async function translateVttWithAI({
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
   const sanitisedVttContent = stripVttMetadataBlocks(vttContent);
-  const response = await generateText7({
+  const response = await withContentPolicyErrorHandling(() => generateText7({
     model,
     output: Output7.object({ schema: translationSchema }),
     messages: [
@@ -6895,8 +7271,9 @@ async function translateVttWithAI({
 ${sanitisedVttContent}`
       }
     ]
-  });
-  const translated = normalizeTranslatedVtt(response.output.translation);
+  }));
+  const output = getGeneratedOutputWithContentPolicyHandling(response);
+  const translated = normalizeTranslatedVtt(output.translation);
   const leakReason = detectLeakReason(translated);
   const safeTranslated = leakReason !== null ? vttContent : translated;
   if (leakReason !== null) {
@@ -6921,7 +7298,8 @@ ${sanitisedVttContent}`
       outputTokens: response.usage.outputTokens,
       totalTokens: response.usage.totalTokens,
       reasoningTokens: response.usage.reasoningTokens,
-      cachedInputTokens: response.usage.cachedInputTokens
+      cachedInputTokens: response.usage.cachedInputTokens,
+      cacheWriteTokens: response.usage.inputTokenDetails?.cacheWriteTokens
     }
   };
 }
@@ -6935,8 +7313,8 @@ async function translateCueChunkWithAI({
 }) {
   "use step";
   const model = await createLanguageModelFromConfig(provider, modelId, credentials);
-  const schema = z8.object({
-    translations: z8.array(z8.string().min(1).max(2e3)).length(cues.length)
+  const schema = z9.object({
+    translations: z9.array(z9.string().min(1).max(2e3)).length(cues.length)
   });
   const cuePayload = cues.map((cue, index) => ({
     index,
@@ -6944,7 +7322,7 @@ async function translateCueChunkWithAI({
     endTime: cue.endTime,
     text: cue.text
   }));
-  const response = await generateText7({
+  const response = await withContentPolicyErrorHandling(() => generateText7({
     model,
     output: Output7.object({ schema }),
     messages: [
@@ -6960,7 +7338,8 @@ Return exactly ${cues.length} translated cues in the same order as the input.
 ${JSON.stringify(cuePayload, null, 2)}`
       }
     ]
-  });
+  }));
+  const output = getGeneratedOutputWithContentPolicyHandling(response);
   const unexpectedKeys = detectUnexpectedKeysFromRawText(
     response.text,
     schema.keyof().options
@@ -6971,13 +7350,14 @@ ${JSON.stringify(cuePayload, null, 2)}`
     );
   }
   return {
-    translations: response.output.translations,
+    translations: output.translations,
     usage: {
       inputTokens: response.usage.inputTokens,
       outputTokens: response.usage.outputTokens,
       totalTokens: response.usage.totalTokens,
       reasoningTokens: response.usage.reasoningTokens,
-      cachedInputTokens: response.usage.cachedInputTokens
+      cachedInputTokens: response.usage.cachedInputTokens,
+      cacheWriteTokens: response.usage.inputTokenDetails?.cacheWriteTokens
     },
     unexpectedKeyCount: unexpectedKeys.length
   };
@@ -7340,6 +7720,9 @@ async function translateCaptionsInternal(assetId, trackId, toLanguageCode, optio
   };
 }
 export {
+  ASK_QUESTIONS_DEFAULT_MAX_ANSWER_OPTION_LENGTH,
+  ASK_QUESTIONS_DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH,
+  ASK_QUESTIONS_MAX_QUESTION_LENGTH,
   DEFAULT_DESCRIPTION_LENGTH,
   DEFAULT_SUMMARY_KEYWORD_LIMIT,
   DEFAULT_TITLE_LENGTH,