@mux/ai 0.28.1 → 0.30.0

package/dist/index.js

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // package.json
-var version = "0.28.1";
+var version = "0.30.0";
 
 // src/lib/language-codes.ts
 var ISO639_1_TO_3 = {
@@ -247,7 +247,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"),
@@ -566,7 +566,8 @@ var TOKEN_USAGE_FIELDS = [
   "outputTokens",
   "totalTokens",
   "reasoningTokens",
-  "cachedInputTokens"
+  "cachedInputTokens",
+  "cacheWriteTokens"
 ];
 function isDefinedTokenUsageValue(value) {
   return typeof value === "number";
@@ -608,6 +609,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) {
@@ -633,6 +640,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) {
@@ -650,7 +660,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);
@@ -1372,6 +1382,7 @@ __export(primitives_exports, {
   extractTextFromVTT: () => extractTextFromVTT,
   extractTimestampedTranscript: () => extractTimestampedTranscript,
   fetchTranscriptForAsset: () => fetchTranscriptForAsset,
+  filterVttByScope: () => filterVttByScope,
   findCaptionTrack: () => findCaptionTrack,
   getHeatmapForAsset: () => getHeatmapForAsset,
   getHeatmapForPlaybackId: () => getHeatmapForPlaybackId,
@@ -1400,7 +1411,8 @@ import { createAnthropic } from "@ai-sdk/anthropic";
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
 import { createOpenAI } from "@ai-sdk/openai";
 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"
 };
@@ -1409,11 +1421,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",
@@ -1474,7 +1495,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)) {
@@ -1908,13 +1929,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/primitives/text-chunking.ts
@@ -2155,30 +2185,97 @@ function chunkText(text, strategy) {
   }
 }
 
+// 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/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;
   }
@@ -2512,6 +2609,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) {
@@ -2616,6 +2730,7 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
   const {
     languageCode,
     cleanTranscript = true,
+    scope,
     shouldSign,
     credentials,
     required = false
@@ -2647,9 +2762,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) {
@@ -2664,6 +2785,9 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
 // src/workflows/index.ts
 var workflows_exports = {};
 __export(workflows_exports, {
+  ASK_QUESTIONS_DEFAULT_MAX_ANSWER_OPTION_LENGTH: () => ASK_QUESTIONS_DEFAULT_MAX_ANSWER_OPTION_LENGTH,
+  ASK_QUESTIONS_DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH: () => ASK_QUESTIONS_DEFAULT_MAX_FREE_FORM_ANSWER_LENGTH,
+  ASK_QUESTIONS_MAX_QUESTION_LENGTH: () => ASK_QUESTIONS_MAX_QUESTION_LENGTH,
   DEFAULT_DESCRIPTION_LENGTH: () => DEFAULT_DESCRIPTION_LENGTH,
   DEFAULT_SUMMARY_KEYWORD_LIMIT: () => DEFAULT_SUMMARY_KEYWORD_LIMIT,
   DEFAULT_TITLE_LENGTH: () => DEFAULT_TITLE_LENGTH,
@@ -2704,7 +2828,156 @@ __export(workflows_exports, {
 // src/workflows/ask-questions.ts
 import { generateText, Output } from "ai";
 import dedent2 from "dedent";
+import { z as z3 } from "zod";
+
+// src/lib/content-policy-error.ts
+import { APICallError, NoObjectGeneratedError, RetryError } from "ai";
 import { z as z2 } from "zod";
+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";
@@ -2918,33 +3191,37 @@ 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/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
       })
@@ -3294,12 +3571,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,
@@ -3317,7 +3594,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 },
@@ -3334,11 +3611,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
@@ -3360,7 +3638,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
@@ -3379,7 +3658,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(
@@ -3387,15 +3665,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}).`,
@@ -3414,8 +3691,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}).`,
@@ -3431,7 +3707,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");
@@ -3443,6 +3720,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).",
@@ -3461,7 +3747,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({
@@ -3490,7 +3777,8 @@ async function askQuestionsInternal(assetId, questions, options, collectedUsage)
         playbackId,
         storyboardWidth,
         policy === "signed",
-        credentials
+        credentials,
+        storyboardScope
       );
       imageUrl = storyboardUrl;
       if (imageSubmissionMode === "base64") {
@@ -3605,11 +3893,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>
@@ -3719,7 +4007,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 },
@@ -3736,22 +4024,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
   };
@@ -3773,6 +4063,7 @@ async function hasBurnedInCaptionsInternal(assetId, options, collectedUsage) {
     imageDownloadOptions,
     promptOverrides,
     credentials,
+    scope,
     ...config
   } = options;
   const userPrompt = buildUserPrompt2(promptOverrides);
@@ -3783,7 +4074,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);
@@ -3837,13 +4139,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,
@@ -3855,21 +4157,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
@@ -3885,13 +4190,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
@@ -3982,7 +4288,8 @@ function buildUserPrompt3({
   promptOverrides,
   minChaptersPerHour = 3,
   maxChaptersPerHour = 8,
-  languageName
+  languageName,
+  scope
 }) {
   const contextSections = [
     {
@@ -3997,6 +4304,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 = {
@@ -4023,7 +4332,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     minChaptersPerHour,
     maxChaptersPerHour,
     credentials,
-    outputLanguageCode
+    outputLanguageCode,
+    scope
   } = options;
   const modelConfig = resolveLanguageModelConfig({
     ...options,
@@ -4032,6 +4342,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) {
@@ -4046,7 +4358,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(", ");
@@ -4067,7 +4380,8 @@ async function generateChaptersInternal(assetId, options, collectedUsage) {
     promptOverrides,
     minChaptersPerHour,
     maxChaptersPerHour,
-    languageName
+    languageName,
+    scope: resolvedScope
   });
   let chaptersData = null;
   try {
@@ -4089,7 +4403,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}.`);
   }
@@ -4115,8 +4431,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,
@@ -4136,7 +4453,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) {
@@ -4207,8 +4524,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)."
   )
 });
@@ -4385,7 +4702,7 @@ async function identifyProfanityWithAI({
     tag: "transcript",
     content: plainText
   });
-  const response = await generateText4({
+  const response = await withContentPolicyErrorHandling(() => generateText4({
     model,
     output: Output4.object({ schema: profanityDetectionSchema }),
     messages: [
@@ -4400,19 +4717,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
   };
@@ -4695,11 +5014,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(
@@ -4712,7 +5036,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(
@@ -4809,21 +5134,21 @@ 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";
-var aiMomentInsightSchema = z6.object({
-  hotspotIndex: z6.number(),
-  startMs: z6.number(),
-  endMs: z6.number(),
-  timestamp: z6.string(),
-  engagementScore: z6.number(),
-  insight: z6.string().max(1e3)
+import { z as z7 } from "zod";
+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`
@@ -5085,26 +5410,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(
@@ -5127,13 +5455,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,
@@ -5843,12 +6172,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 };
   });
@@ -5867,7 +6208,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);
@@ -5878,7 +6220,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(
@@ -5895,7 +6246,8 @@ async function getModerationScores(assetId, options = {}) {
       cleanTranscript: true,
       shouldSign: policy === "signed",
       credentials,
-      required: true
+      required: true,
+      scope: effectiveScope
     });
     if (provider === "openai") {
       thumbnailScores = await requestOpenAITranscriptModeration(
@@ -5913,17 +6265,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",
@@ -5933,7 +6289,8 @@ async function getModerationScores(assetId, options = {}) {
       interval: thumbnailInterval,
       width: thumbnailWidth,
       shouldSign: policy === "signed",
-      credentials
+      credentials,
+      scope: renderableScope
     });
     thumbnailCount = thumbnailUrls.length;
     if (provider === "openai") {
@@ -6019,7 +6376,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;
@@ -6032,17 +6389,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"];
@@ -6318,7 +6675,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",
@@ -6338,11 +6695,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
@@ -6354,7 +6712,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
   };
@@ -6363,7 +6722,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",
@@ -6380,11 +6739,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
@@ -6396,7 +6756,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
   };
@@ -6448,7 +6809,8 @@ async function getSummaryAndTagsInternal(assetId, options, collectedUsage) {
     titleLength,
     descriptionLength,
     tagCount,
-    outputLanguageCode
+    outputLanguageCode,
+    scope
   } = options ?? {};
   if (!VALID_TONES.includes(tone)) {
     throw new MuxAiError(
@@ -6465,6 +6827,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).",
@@ -6483,7 +6854,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]);
@@ -6514,7 +6886,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);
@@ -6950,16 +7328,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.
@@ -7026,10 +7404,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) {
@@ -7041,7 +7419,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(
@@ -7202,7 +7580,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: [
@@ -7217,8 +7595,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) {
@@ -7243,7 +7622,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
     }
   };
 }
@@ -7257,8 +7637,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,
@@ -7266,7 +7646,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: [
@@ -7282,7 +7662,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
@@ -7293,13 +7674,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
   };