@mux/ai 0.14.0 → 0.16.0

package/dist/workflows/index.js

@@ -110,6 +110,26 @@ async function downloadImagesAsBase64(urls, options = {}, maxConcurrent = 5) {
   return results;
 }
 
+// src/lib/mux-ai-error.ts
+var MuxAiError = class extends Error {
+  constructor(message, opts) {
+    super(message);
+    /** Structural brand for duck-type identification. */
+    this.__robots_error = true;
+    this.name = "FatalError";
+    this.publicType = opts?.type ?? "processing_error";
+    this.publicMessage = message;
+    this.retryable = opts?.retryable ?? false;
+  }
+};
+function wrapError(error, message) {
+  if (error instanceof MuxAiError) {
+    throw error;
+  }
+  const detail = error instanceof Error ? error.message : "Unknown error";
+  throw new Error(`${message}: ${detail}`);
+}
+
 // src/lib/providers.ts
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
@@ -725,8 +745,9 @@ function getPlaybackId(asset) {
   if (signedPlaybackId?.id) {
     return { id: signedPlaybackId.id, policy: "signed" };
   }
-  throw new Error(
-    "No public or signed playback ID found for this asset. A public or signed playback ID is required. DRM playback IDs are not currently supported."
+  throw new MuxAiError(
+    "No public or signed playback ID found for this asset. DRM playback IDs are not currently supported.",
+    { type: "validation_error" }
   );
 }
 function isAudioOnlyAsset(asset) {
@@ -773,7 +794,7 @@ function renderSection(section) {
       throw new Error(`Invalid XML ${context} name: "${name}"`);
     }
   };
-  const escapeXmlText = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;/");
+  const escapeXmlText = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
   const escapeXmlAttribute = (value) => escapeXmlText(value).replace(/"/g, "&quot;");
   if (!content.trim()) {
     return "";
@@ -1282,15 +1303,16 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
   if (!track) {
     if (required) {
       const availableLanguages = getReadyTextTracks(asset).map((t) => t.language_code).filter(Boolean).join(", ");
-      throw new Error(
-        `No transcript track found${languageCode ? ` for language '${languageCode}'` : ""}. Available languages: ${availableLanguages || "none"}`
+      throw new MuxAiError(
+        `No caption track found${languageCode ? ` for language ${languageCode}` : ""}. Available languages: ${availableLanguages || "none"}.`,
+        { type: "validation_error" }
       );
     }
     return { transcriptText: "" };
   }
   if (!track.id) {
     if (required) {
-      throw new Error("Transcript track is missing an id");
+      throw new MuxAiError("Transcript track is missing an id.", { type: "validation_error" });
     }
     return { transcriptText: "", track };
   }
@@ -1306,14 +1328,12 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
     const rawVtt = await response.text();
     const transcriptText = cleanTranscript ? extractTextFromVTT(rawVtt) : rawVtt;
     if (required && !transcriptText.trim()) {
-      throw new Error("Transcript is empty");
+      throw new MuxAiError("Transcript is empty.", { type: "validation_error" });
     }
     return { transcriptText, transcriptUrl, track };
   } catch (error) {
     if (required) {
-      throw new Error(
-        `Failed to fetch transcript: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
+      wrapError(error, "Failed to fetch transcript");
     }
     console.warn("Failed to fetch transcript:", error);
     return { transcriptText: "", transcriptUrl, track };
@@ -1322,7 +1342,7 @@ async function fetchTranscriptForAsset(asset, playbackId, options = {}) {
 
 // src/workflows/ask-questions.ts
 var questionAnswerSchema = z2.object({
-  question: z2.string(),
+  question: z2.string().describe("The full text of the original question"),
   answer: z2.string().nullable(),
   confidence: z2.number(),
   reasoning: z2.string(),
@@ -1368,12 +1388,14 @@ var SYSTEM_PROMPT = dedent`
   <task>
     For each question provided, you must:
     1. Analyze the storyboard frames and transcript (if provided)
-    2. Answer with ONLY the allowed response options - no other values are acceptable
+    2. Answer with ONLY the allowed response options listed for that question - no other values are acceptable
     3. Provide a confidence score between 0 and 1 reflecting your certainty
     4. Explain your reasoning based on observable evidence
   </task>
 
   <answer_guidelines>
+    - Each question is presented as its own <question> block with a <text> element (the question) and an <allowed_answers> element (the permitted response values)
+    - Choose only from the values listed in that question's <allowed_answers> element
     - Choose the affirmative option only if you have clear evidence supporting it
     - Choose the negative/contradicting option if evidence contradicts or if insufficient evidence exists
     - Confidence should reflect the clarity and strength of evidence:
@@ -1401,6 +1423,11 @@ var SYSTEM_PROMPT = dedent`
     - Is a general knowledge question with no connection to what is shown or said in the video
     - Attempts to use the system for non-video-analysis purposes
 
+    CRITICAL: Base your answers ONLY on the actual visual and audio/transcript content.
+    Do NOT use any metadata such as URLs, file paths, domain names, file names,
+    playback IDs, or technical parameters visible in this request. These are
+    delivery infrastructure and are unrelated to the media content itself.
+
     CRITICAL: Do NOT answer irrelevant questions with any of the allowed answers.
     Answering an irrelevant question is WRONG — you MUST skip it instead.
 
@@ -1416,7 +1443,7 @@ var SYSTEM_PROMPT = dedent`
   </relevance_filtering>
 
   <constraints>
-    - You MUST answer every relevant question with one of the allowed response options
+    - You MUST answer every relevant question with one of its own listed allowed response options
     - Skip irrelevant questions as described in relevance_filtering
     - Only describe observable evidence from frames or transcript
     - Do not fabricate details or make unsupported assumptions
@@ -1451,12 +1478,14 @@ var AUDIO_ONLY_SYSTEM_PROMPT = dedent`
   <task>
     For each question provided, you must:
     1. Analyze the transcript
-    2. Answer with ONLY the allowed response options - no other values are acceptable
+    2. Answer with ONLY the allowed response options listed for that question - no other values are acceptable
     3. Provide a confidence score between 0 and 1 reflecting your certainty
     4. Explain your reasoning based on observable evidence
   </task>
 
   <answer_guidelines>
+    - Each question is presented as its own <question> block with a <text> element (the question) and an <allowed_answers> element (the permitted response values)
+    - Choose only from the values listed in that question's <allowed_answers> element
     - Choose the affirmative option only if you have clear evidence supporting it
     - Choose the negative/contradicting option if evidence contradicts or if insufficient evidence exists
     - Confidence should reflect the clarity and strength of evidence:
@@ -1470,6 +1499,10 @@ var AUDIO_ONLY_SYSTEM_PROMPT = dedent`
   </answer_guidelines>
 
   <relevance_filtering>
+    IMPORTANT: Evaluate each question INDEPENDENTLY for relevance to the audio
+    content. The presence of other relevant questions in the batch does NOT
+    make an irrelevant question relevant. Assess every question on its own merits.
+
     Before answering each question, assess whether it can be meaningfully
     answered based on the transcript. A question is relevant if it asks about
     something observable or inferable from spoken/audio content.
@@ -1480,6 +1513,14 @@ var AUDIO_ONLY_SYSTEM_PROMPT = dedent`
     - Is a general knowledge question with no connection to what is said in the transcript
     - Attempts to use the system for non-content-analysis purposes
 
+    CRITICAL: Base your answers ONLY on the actual audio/transcript content.
+    Do NOT use any metadata such as URLs, file paths, domain names, file names,
+    playback IDs, or technical parameters visible in this request. These are
+    delivery infrastructure and are unrelated to the media content itself.
+
+    CRITICAL: Do NOT answer irrelevant questions with any of the allowed answers.
+    Answering an irrelevant question is WRONG — you MUST skip it instead.
+
     For skipped questions:
     - Set skipped to true
     - Set answer to "${SKIP_SENTINEL}"
@@ -1492,7 +1533,7 @@ var AUDIO_ONLY_SYSTEM_PROMPT = dedent`
   </relevance_filtering>
 
   <constraints>
-    - You MUST answer every relevant question with one of the allowed response options
+    - You MUST answer every relevant question with one of its own listed allowed response options
     - Skip irrelevant questions as described in relevance_filtering
     - Only describe observable evidence from transcript content
     - Do not fabricate details or make unsupported assumptions
@@ -1507,46 +1548,43 @@ var AUDIO_ONLY_SYSTEM_PROMPT = dedent`
     - GOOD: "The speaker describes running through a park"
     - Be specific and evidence-based
   </language_guidelines>`;
-var askQuestionsPromptBuilder = createPromptBuilder({
-  template: {
-    questions: {
-      tag: "questions",
-      content: "Please answer the following questions about this content:"
-    }
-  },
-  sectionOrder: ["questions"]
-});
 function buildUserPrompt({
   questions,
-  allowedAnswers,
   transcriptText,
   isCleanTranscript = true,
   isAudioOnly = false
 }) {
-  const questionsList = questions.map((q, idx) => `${idx + 1}. ${q.question}`).join("\n");
-  const questionsIntro = isAudioOnly ? "Please answer the following questions about this audio content using transcript evidence:" : "Please answer the following questions about this content:";
-  const questionsContent = dedent`
-    ${questionsIntro}
-
-    ${questionsList}`;
-  const answerList = allowedAnswers.map((answer) => `"${answer}"`).join(", ");
-  const responseOptions = dedent`
-    <response_options>
-      Allowed answers: ${answerList}
-    </response_options>`;
-  const questionsSection = askQuestionsPromptBuilder.build({ questions: questionsContent });
-  if (!transcriptText) {
-    return `${questionsSection}
-
-${responseOptions}`;
+  const contentDescriptor = isAudioOnly ? "audio content using transcript evidence" : "content";
+  const taskContent = dedent`
+    Answer each question in the <questions> block below about the ${contentDescriptor}.
+    Use only the values listed inside each question's own <allowed_answers> element.
+    Return one answer per question, in the order the questions appear.
+    If a question cannot be answered from the provided content, skip it as described in the system instructions.`;
+  const taskSection = `<task>
+${taskContent}
+</task>`;
+  const questionBlocks = questions.map((q, idx) => {
+    const textTag = renderSection({ tag: "text", content: q.question });
+    const answersTag = renderSection({
+      tag: "allowed_answers",
+      content: q.answerOptions.map((a) => `"${a}"`).join(", ")
+    });
+    return `<question number="${idx + 1}">
+${textTag}
+${answersTag}
+</question>`;
+  }).join("\n\n");
+  const questionsSection = `<questions>
+${questionBlocks}
+</questions>`;
+  const sections = [];
+  if (transcriptText) {
+    const format = isCleanTranscript ? "plain text" : "WebVTT";
+    sections.push(renderSection(createTranscriptSection(transcriptText, format)));
   }
-  const format = isCleanTranscript ? "plain text" : "WebVTT";
-  const transcriptSection = renderSection(createTranscriptSection(transcriptText, format));
-  return `${transcriptSection}
-
-${questionsSection}
-
-${responseOptions}`;
+  sections.push(taskSection);
+  sections.push(questionsSection);
+  return sections.join("\n\n");
 }
 async function fetchImageAsBase64(imageUrl, imageDownloadOptions) {
   "use step";
@@ -1601,12 +1639,13 @@ async function analyzeQuestions({
 async function askQuestions(assetId, questions, options) {
   "use workflow";
   if (!questions || questions.length === 0) {
-    throw new Error("At least one question must be provided");
+    throw new MuxAiError("At least one question must be provided.", { type: "validation_error" });
   }
   questions.forEach((q, idx) => {
     if (!q.question || typeof q.question !== "string" || !q.question.trim()) {
-      throw new Error(
-        `Question at index ${idx} is invalid: must have non-empty 'question' field`
+      throw new MuxAiError(
+        `Question at index ${idx} is invalid: must have a non-empty question field.`,
+        { type: "validation_error" }
       );
     }
   });
@@ -1614,7 +1653,6 @@ async function askQuestions(assetId, questions, options) {
     provider = "openai",
     model,
     languageCode,
-    answerOptions,
     includeTranscript = true,
     cleanTranscript = true,
     imageSubmissionMode = "url",
@@ -1622,15 +1660,23 @@ async function askQuestions(assetId, questions, options) {
     storyboardWidth = 640,
     credentials
   } = options ?? {};
-  const normalizedAnswerOptions = Array.from(
-    new Set(
-      (answerOptions?.length ? answerOptions : ["yes", "no"]).map((option) => option.trim()).filter(Boolean)
-    )
+  const normalizedQuestions = questions.map((q, idx) => {
+    const options2 = Array.from(
+      new Set(
+        (q.answerOptions?.length ? q.answerOptions : ["yes", "no"]).map((o) => o.trim()).filter(Boolean)
+      )
+    );
+    if (!options2.length) {
+      throw new MuxAiError(
+        `Question at index ${idx} has invalid answerOptions: must include at least one non-empty value.`,
+        { type: "validation_error" }
+      );
+    }
+    return { ...q, answerOptions: options2 };
+  });
+  const allowedAnswers = Array.from(
+    new Set(normalizedQuestions.flatMap((q) => q.answerOptions))
   );
-  if (!normalizedAnswerOptions.length) {
-    throw new Error("answerOptions must include at least one non-empty value");
-  }
-  const allowedAnswers = normalizedAnswerOptions;
   const modelConfig = resolveLanguageModelConfig({
     ...options,
     model,
@@ -1640,14 +1686,16 @@ async function askQuestions(assetId, questions, options) {
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
   const isAudioOnly = isAudioOnlyAsset(assetData);
   if (isAudioOnly && !includeTranscript) {
-    throw new Error(
-      "Audio-only assets require a transcript. Set includeTranscript: true and ensure the asset has a ready text track (captions/subtitles)."
+    throw new MuxAiError(
+      "Audio-only assets require a transcript. Set includeTranscript: true and ensure the asset has a ready text track (captions/subtitles).",
+      { type: "validation_error" }
     );
   }
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
-    throw new Error(
-      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables."
+    throw new MuxAiError(
+      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
   const transcriptResult = includeTranscript ? await fetchTranscriptForAsset(assetData, playbackId, {
@@ -1659,8 +1707,7 @@ async function askQuestions(assetId, questions, options) {
   }) : void 0;
   const transcriptText = transcriptResult?.transcriptText ?? "";
   const userPrompt = buildUserPrompt({
-    questions,
-    allowedAnswers,
+    questions: normalizedQuestions,
     transcriptText,
     isCleanTranscript: cleanTranscript,
     isAudioOnly
@@ -1713,22 +1760,25 @@ async function askQuestions(assetId, questions, options) {
     }
   } catch (error) {
     const contentType = isAudioOnly ? "audio" : "video";
-    throw new Error(
-      `Failed to analyze ${contentType} questions with ${provider}: ${error instanceof Error ? error.message : "Unknown error"}`
-    );
+    wrapError(error, `Failed to analyze ${contentType} questions with ${provider}`);
   }
   if (!analysisResponse.result?.answers) {
-    throw new Error(`Failed to get answers for asset ${assetId}`);
+    throw new MuxAiError(`Failed to generate answers for asset ${assetId}.`);
   }
   if (analysisResponse.result.answers.length !== questions.length) {
-    throw new Error(
-      `Expected ${questions.length} answers but received ${analysisResponse.result.answers.length}`
+    throw new MuxAiError(
+      `Failed to generate answers for all questions for asset ${assetId}.`
     );
   }
-  const answers = analysisResponse.result.answers.map((raw) => {
+  const answers = analysisResponse.result.answers.map((raw, idx) => {
     const isSkipped = raw.skipped || raw.answer === SKIP_SENTINEL;
+    if (!isSkipped && !normalizedQuestions[idx].answerOptions.includes(raw.answer)) {
+      throw new MuxAiError(
+        `Answer "${raw.answer}" for question ${idx} is not in allowed options: ${normalizedQuestions[idx].answerOptions.join(", ")}`
+      );
+    }
     return {
-      // Strip numbering prefix (e.g., "1. " or "2. ") from questions
+      // Strip numbering prefix (e.g. "1. ") if the LLM prepends one
       question: raw.question.replace(/^\d+\.\s*/, ""),
       confidence: isSkipped ? 0 : Math.min(1, Math.max(0, raw.confidence)),
       reasoning: raw.reasoning,
@@ -1796,6 +1846,9 @@ var SYSTEM_PROMPT2 = dedent2`
   <constraints>
     - Only classify as burned-in captions when evidence is clear across multiple frames
     - Base decisions on observable visual evidence
+    - Do NOT use any metadata such as URLs, file paths, domain names, file names,
+      playback IDs, or technical parameters visible in this request. These are
+      delivery infrastructure and are unrelated to the media content itself.
     - Return structured data matching the requested schema
   </constraints>`;
 var burnedInCaptionsPromptBuilder = createPromptBuilder({
@@ -2276,8 +2329,9 @@ async function generateChapters(assetId, options = {}) {
   const isAudioOnly = isAudioOnlyAsset(assetData);
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
-    throw new Error(
-      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables."
+    throw new MuxAiError(
+      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
   const readyTextTracks = getReadyTextTracks(assetData);
@@ -2290,14 +2344,15 @@ async function generateChapters(assetId, options = {}) {
   });
   if (!transcriptResult.track || !transcriptResult.transcriptText) {
     const availableLanguages = readyTextTracks.map((t) => t.language_code).filter(Boolean).join(", ");
-    throw new Error(
-      `No caption track found${languageCode ? ` for language '${languageCode}'` : ""}. Available languages: ${availableLanguages || "none"}`
+    throw new MuxAiError(
+      `No caption track found${languageCode ? ` for language ${languageCode}` : ""}. Available languages: ${availableLanguages || "none"}.`,
+      { type: "validation_error" }
     );
   }
   const timestampedTranscript = extractTimestampedTranscript(transcriptResult.transcriptText);
   if (!timestampedTranscript) {
     const contentLabel = isAudioOnly ? "transcript" : "caption track";
-    throw new Error(`No usable content found in ${contentLabel}`);
+    throw new MuxAiError(`No usable content found in ${contentLabel}.`, { type: "validation_error" });
   }
   const resolvedLanguageCode = outputLanguageCode && outputLanguageCode !== "auto" ? outputLanguageCode : transcriptResult.track?.language_code ?? languageCode;
   const languageName = resolvedLanguageCode ? getLanguageName(resolvedLanguageCode) : void 0;
@@ -2319,17 +2374,15 @@ async function generateChapters(assetId, options = {}) {
       credentials
     });
   } catch (error) {
-    throw new Error(
-      `Failed to generate chapters with ${provider}: ${error instanceof Error ? error.message : "Unknown error"}`
-    );
+    wrapError(error, `Failed to generate chapters with ${provider}`);
   }
   if (!chaptersData || !chaptersData.chapters) {
-    throw new Error("No chapters generated from AI response");
+    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);
   if (validChapters.length === 0) {
-    throw new Error("No valid chapters found in AI response");
+    throw new MuxAiError(`Failed to generate valid chapters for asset ${assetId}.`);
   }
   if (validChapters[0].startTime !== 0) {
     validChapters[0].startTime = 0;
@@ -2835,10 +2888,10 @@ async function editCaptions(assetId, trackId, options) {
   const hasAutoCensor = !!autoCensorOption;
   const hasReplacements = !!replacementsOption && replacementsOption.length > 0;
   if (!hasAutoCensor && !hasReplacements) {
-    throw new Error("At least one of autoCensorProfanity or replacements must be provided.");
+    throw new MuxAiError("At least one of autoCensorProfanity or replacements must be provided.", { type: "validation_error" });
   }
   if (autoCensorOption && !provider) {
-    throw new Error("provider is required when using autoCensorProfanity.");
+    throw new MuxAiError("provider is required when using autoCensorProfanity.", { type: "validation_error" });
   }
   const deleteOriginal = deleteOriginalTrack !== false;
   const uploadToMux = uploadToMuxOption !== false;
@@ -2849,24 +2902,27 @@ async function editCaptions(assetId, trackId, options) {
   const s3AccessKeyId = env_default.S3_ACCESS_KEY_ID;
   const s3SecretAccessKey = env_default.S3_SECRET_ACCESS_KEY;
   if (uploadToS3 && (!s3Endpoint || !s3Bucket || !storageAdapter && (!s3AccessKeyId || !s3SecretAccessKey))) {
-    throw new Error(
-      "Storage configuration is required for uploading. Provide s3Endpoint and s3Bucket. If no storageAdapter is supplied, also provide s3AccessKeyId and s3SecretAccessKey in options or set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY environment variables."
+    throw new MuxAiError(
+      "Storage configuration is required for uploading. Provide s3Endpoint and s3Bucket. If no storageAdapter is supplied, also provide s3AccessKeyId and s3SecretAccessKey in options or set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
-    throw new Error(
-      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables."
+    throw new MuxAiError(
+      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
   const readyTextTracks = getReadyTextTracks(assetData);
   const sourceTrack = readyTextTracks.find((t) => t.id === trackId);
   if (!sourceTrack) {
     const availableTrackIds = readyTextTracks.map((t) => t.id).filter(Boolean).join(", ");
-    throw new Error(
-      `Track '${trackId}' not found or not ready on asset '${assetId}'. Available track IDs: ${availableTrackIds || "none"}`
+    throw new MuxAiError(
+      `Track ${trackId} not found or not ready on asset ${assetId}. Available track IDs: ${availableTrackIds || "none"}.`,
+      { type: "validation_error" }
     );
   }
   const vttUrl = await buildTranscriptUrl(playbackId, trackId, policy === "signed", credentials);
@@ -2874,7 +2930,7 @@ async function editCaptions(assetId, trackId, options) {
   try {
     vttContent = await fetchVttFromMux(vttUrl);
   } catch (error) {
-    throw new Error(`Failed to fetch VTT content: ${error instanceof Error ? error.message : "Unknown error"}`);
+    wrapError(error, "Failed to fetch VTT content");
   }
   let editedVtt = vttContent;
   let totalReplacementCount = 0;
@@ -2884,7 +2940,7 @@ async function editCaptions(assetId, trackId, options) {
     const { mode = "blank", alwaysCensor = [], neverCensor = [] } = autoCensorOption;
     const plainText = extractTextFromVTT(vttContent);
     if (!plainText.trim()) {
-      throw new Error("Track transcript is empty; nothing to censor.");
+      throw new MuxAiError("Track transcript is empty; nothing to censor.", { type: "validation_error" });
     }
     const modelConfig = resolveLanguageModelConfig({
       ...options,
@@ -2902,7 +2958,7 @@ async function editCaptions(assetId, trackId, options) {
       detectedProfanity = result.profanity;
       usage = result.usage;
     } catch (error) {
-      throw new Error(`Failed to detect profanity with ${modelConfig.provider}: ${error instanceof Error ? error.message : "Unknown error"}`);
+      wrapError(error, `Failed to detect profanity with ${modelConfig.provider}`);
     }
     const finalProfanity = applyOverrideLists(detectedProfanity, alwaysCensor, neverCensor);
     const { censoredVtt, replacements: censorReplacements } = censorVttContent(editedVtt, finalProfanity, mode);
@@ -2938,7 +2994,7 @@ async function editCaptions(assetId, trackId, options) {
         s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
       });
     } catch (error) {
-      throw new Error(`Failed to upload VTT to S3: ${error instanceof Error ? error.message : "Unknown error"}`);
+      wrapError(error, "Failed to upload VTT to S3");
     }
     if (uploadToMux) {
       try {
@@ -3535,6 +3591,9 @@ var SYSTEM_PROMPT4 = dedent5`
   <constraints>
     - Only describe what you can see in images or read in transcripts
     - Do not fabricate details or make unsupported assumptions
+    - Do NOT use any metadata such as URLs, file paths, domain names, file names,
+      playback IDs, or technical parameters visible in this request. These are
+      delivery infrastructure and are unrelated to the media content itself.
     - Correlate engagement scores with observable content
     - Return structured data matching the requested schema exactly
     - Each momentInsight MUST include the hotspotIndex from the input data
@@ -3575,6 +3634,9 @@ var AUDIO_ONLY_SYSTEM_PROMPT2 = dedent5`
   <constraints>
     - Only describe what you can read in the transcript
     - Do not fabricate details or make unsupported assumptions
+    - Do NOT use any metadata such as URLs, file paths, domain names, file names,
+      playback IDs, or technical parameters visible in this request. These are
+      delivery infrastructure and are unrelated to the media content itself.
     - Correlate engagement scores with observable content
     - Return structured data matching the requested schema exactly
     - Each momentInsight MUST include the hotspotIndex from the input data
@@ -3785,7 +3847,7 @@ async function generateEngagementInsights(assetId, options = {}) {
     skipShots = false
   } = options;
   if (!Number.isInteger(hotspotLimit) || hotspotLimit < 1 || hotspotLimit > 10) {
-    throw new Error("hotspotLimit must be an integer between 1 and 10");
+    throw new MuxAiError("hotspotLimit must be an integer between 1 and 10.", { type: "validation_error" });
   }
   const modelConfig = resolveLanguageModelConfig({
     ...options,
@@ -3795,13 +3857,14 @@ async function generateEngagementInsights(assetId, options = {}) {
   const { asset, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(asset);
   if (!assetDurationSeconds) {
-    throw new Error(`Asset ${assetId} has no valid duration`);
+    throw new MuxAiError(`Asset ${assetId} has no valid duration.`, { type: "validation_error" });
   }
   const audioOnly = isAudioOnlyAsset(asset);
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
-    throw new Error(
-      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables."
+    throw new MuxAiError(
+      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
   const shouldSign = policy === "signed";
@@ -3901,7 +3964,7 @@ async function generateEngagementInsights(assetId, options = {}) {
     credentials
   );
   if (!aiInsights.momentInsights || aiInsights.momentInsights.length === 0) {
-    throw new Error("Failed to generate insights from AI response");
+    throw new MuxAiError(`Failed to generate insights for asset ${assetId}.`);
   }
   const momentInsights = [];
   for (const aiMoment of aiInsights.momentInsights) {
@@ -3922,8 +3985,8 @@ async function generateEngagementInsights(assetId, options = {}) {
     });
   }
   if (momentInsights.length === 0) {
-    throw new Error(
-      "AI returned insights but none matched valid hotspot indices. This may indicate a prompt or model issue."
+    throw new MuxAiError(
+      `Failed to generate valid insights for asset ${assetId}.`
     );
   }
   const usageWithMetadata = {
@@ -4726,6 +4789,9 @@ var SYSTEM_PROMPT5 = dedent6`
   <constraints>
     - Only describe what is clearly observable in the frames or explicitly stated in the transcript
     - Do not fabricate details or make unsupported assumptions
+    - Do NOT use any metadata such as URLs, file paths, domain names, file names,
+      playback IDs, or technical parameters visible in this request. These are
+      delivery infrastructure and are unrelated to the media content itself.
     - Return structured data matching the requested schema
     - Output only the JSON object; no markdown or extra text
     - When a <language> section is provided, all output text MUST be written in that language
@@ -4780,6 +4846,9 @@ var AUDIO_ONLY_SYSTEM_PROMPT3 = dedent6`
   <constraints>
     - Only describe what is explicitly stated or strongly implied in the transcript
     - Do not fabricate details or make unsupported assumptions
+    - Do NOT use any metadata such as URLs, file paths, domain names, file names,
+      playback IDs, or technical parameters visible in this request. These are
+      delivery infrastructure and are unrelated to the media content itself.
     - Return structured data matching the requested schema
     - Focus entirely on audio/spoken content - there are no visual elements
     - Output only the JSON object; no markdown or extra text
@@ -4943,8 +5012,9 @@ async function getSummaryAndTags(assetId, options) {
     outputLanguageCode
   } = options ?? {};
   if (!VALID_TONES.includes(tone)) {
-    throw new Error(
-      `Invalid tone "${tone}". Valid tones are: ${VALID_TONES.join(", ")}`
+    throw new MuxAiError(
+      `Invalid tone "${tone}". Valid tones are: ${VALID_TONES.join(", ")}.`,
+      { type: "validation_error" }
     );
   }
   const modelConfig = resolveLanguageModelConfig({
@@ -4957,14 +5027,16 @@ async function getSummaryAndTags(assetId, options) {
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
   const isAudioOnly = isAudioOnlyAsset(assetData);
   if (isAudioOnly && !includeTranscript) {
-    throw new Error(
-      "Audio-only assets require a transcript. Set includeTranscript: true and ensure the asset has a ready text track (captions/subtitles)."
+    throw new MuxAiError(
+      "Audio-only assets require a transcript. Set includeTranscript: true and ensure the asset has a ready text track (captions/subtitles).",
+      { type: "validation_error" }
     );
   }
   const signingContext = await resolveMuxSigningContext(workflowCredentials);
   if (policy === "signed" && !signingContext) {
-    throw new Error(
-      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables."
+    throw new MuxAiError(
+      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
   const transcriptResult = includeTranscript ? await fetchTranscriptForAsset(assetData, playbackId, {
@@ -5026,18 +5098,17 @@ async function getSummaryAndTags(assetId, options) {
     }
   } catch (error) {
     const contentType = isAudioOnly ? "audio" : "video";
-    throw new Error(
-      `Failed to analyze ${contentType} content with ${provider}: ${error instanceof Error ? error.message : "Unknown error"}`
-    );
+    wrapError(error, `Failed to analyze ${contentType} content with ${provider}`);
   }
   if (!analysisResponse.result) {
-    throw new Error(`Failed to analyze video content for asset ${assetId}`);
+    const contentType = isAudioOnly ? "audio" : "video";
+    throw new MuxAiError(`Failed to analyze ${contentType} content for asset ${assetId}.`);
   }
   if (!analysisResponse.result.title) {
-    throw new Error(`Failed to generate title for asset ${assetId}`);
+    throw new MuxAiError(`Failed to generate title for asset ${assetId}.`);
   }
   if (!analysisResponse.result.description) {
-    throw new Error(`Failed to generate description for asset ${assetId}`);
+    throw new MuxAiError(`Failed to generate description for asset ${assetId}.`);
   }
   return {
     assetId,
@@ -5096,12 +5167,11 @@ async function requestStaticRenditionCreation(assetId, credentials) {
   } catch (error) {
     const statusCode = error?.status ?? error?.statusCode;
     const messages = error?.error?.messages;
-    const alreadyDefined = messages?.some((message2) => message2.toLowerCase().includes("already defined")) ?? error?.message?.toLowerCase().includes("already defined");
+    const alreadyDefined = messages?.some((message) => message.toLowerCase().includes("already defined")) ?? error?.message?.toLowerCase().includes("already defined");
     if (statusCode === 409 || alreadyDefined) {
       return;
     }
-    const message = error instanceof Error ? error.message : "Unknown error";
-    throw new Error(`Failed to request static rendition from Mux: ${message}`);
+    wrapError(error, "Failed to request static rendition from Mux");
   }
 }
 async function waitForAudioStaticRendition({
@@ -5135,13 +5205,14 @@ async function waitForAudioStaticRendition({
       `\u231B Waiting for static rendition (attempt ${attempt}/${STATIC_RENDITION_MAX_ATTEMPTS}) \u2192 ${currentStatus}`
     );
     if (currentStatus === "errored") {
-      throw new Error(
+      throw new MuxAiError(
         "Mux failed to create the static rendition for this asset. Please check the asset in the Mux dashboard."
       );
     }
   }
-  throw new Error(
-    "Timed out waiting for the static rendition to become ready. Please try again in a moment."
+  throw new MuxAiError(
+    "Timed out waiting for the static rendition to become ready. Please try again in a moment.",
+    { type: "timeout_error", retryable: true }
   );
 }
 async function fetchAudioFromMux(audioUrl) {
@@ -5293,7 +5364,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
     credentials: providedCredentials
   } = options;
   if (provider !== "elevenlabs") {
-    throw new Error("Only ElevenLabs provider is currently supported for audio translation");
+    throw new MuxAiError("Only ElevenLabs provider is currently supported for audio translation.", { type: "validation_error" });
   }
   const credentials = providedCredentials;
   const effectiveStorageAdapter = storageAdapter;
@@ -5305,7 +5376,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
   const s3AccessKeyId = env_default.S3_ACCESS_KEY_ID;
   const s3SecretAccessKey = env_default.S3_SECRET_ACCESS_KEY;
   if (uploadToS3 && (!s3Endpoint || !s3Bucket || !effectiveStorageAdapter && (!s3AccessKeyId || !s3SecretAccessKey))) {
-    throw new Error("Storage configuration is required for uploading. Provide s3Endpoint and s3Bucket. If no storageAdapter is supplied, also provide s3AccessKeyId and s3SecretAccessKey in options or set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY environment variables.");
+    throw new MuxAiError("Storage configuration is required for uploading. Provide s3Endpoint and s3Bucket. If no storageAdapter is supplied, also provide s3AccessKeyId and s3SecretAccessKey in options or set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY environment variables.", { type: "validation_error" });
   }
   const { asset: initialAsset, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(initialAsset);
@@ -5320,8 +5391,9 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
   }
   const audioRendition = getReadyAudioStaticRendition(currentAsset);
   if (!audioRendition) {
-    throw new Error(
-      "Unable to obtain an audio-only static rendition for this asset. Please verify static renditions are enabled in Mux."
+    throw new MuxAiError(
+      "Unable to obtain an audio-only static rendition for this asset. Please verify static renditions are enabled in Mux.",
+      { type: "validation_error" }
     );
   }
   let audioUrl = `https://stream.mux.com/${playbackId}/audio.m4a`;
@@ -5333,7 +5405,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
   try {
     audioBuffer = await fetchAudioFromMux(audioUrl);
   } catch (error) {
-    throw new Error(`Failed to fetch audio from Mux: ${error instanceof Error ? error.message : "Unknown error"}`);
+    wrapError(error, "Failed to fetch audio from Mux");
   }
   console.warn("\u{1F399}\uFE0F Creating dubbing job in ElevenLabs...");
   const elevenLabsLangCode = toISO639_3(toLanguageCode);
@@ -5354,7 +5426,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
     });
     console.warn(`\u2705 Dubbing job created with ID: ${dubbingId}`);
   } catch (error) {
-    throw new Error(`Failed to create ElevenLabs dubbing job: ${error instanceof Error ? error.message : "Unknown error"}`);
+    wrapError(error, "Failed to create ElevenLabs dubbing job");
   }
   console.warn("\u23F3 Waiting for dubbing to complete...");
   let dubbingStatus = "dubbing";
@@ -5375,11 +5447,11 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
         throw new Error("ElevenLabs dubbing job failed");
       }
     } catch (error) {
-      throw new Error(`Failed to check dubbing status: ${error instanceof Error ? error.message : "Unknown error"}`);
+      wrapError(error, "Failed to check dubbing status");
     }
   }
   if (dubbingStatus !== "dubbed") {
-    throw new Error(`Dubbing job timed out or failed. Final status: ${dubbingStatus}`);
+    throw new MuxAiError("Audio translation timed out or failed. Please try again.", { type: "timeout_error", retryable: true });
   }
   console.warn("\u2705 Dubbing completed successfully!");
   let presignedUrl;
@@ -5409,7 +5481,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
       });
       console.warn("\u2705 Dubbed audio downloaded successfully!");
     } catch (error) {
-      throw new Error(`Failed to download dubbed audio: ${error instanceof Error ? error.message : "Unknown error"}`);
+      wrapError(error, "Failed to download dubbed audio");
     }
     console.warn("\u{1F4E4} Uploading dubbed audio to S3-compatible storage...");
     try {
@@ -5424,7 +5496,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
         s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
       });
     } catch (error) {
-      throw new Error(`Failed to upload audio to S3: ${error instanceof Error ? error.message : "Unknown error"}`);
+      wrapError(error, "Failed to upload audio to S3");
     }
     if (uploadToMux) {
       console.warn("\u{1F4F9} Adding dubbed audio track to Mux asset...");
@@ -5771,9 +5843,7 @@ async function translateChunkWithFallback({
     };
   } catch (error) {
     if (!shouldSplitChunkTranslationError(error) || chunk.cueCount <= 1) {
-      throw new Error(
-        `Chunk ${chunk.id} failed for ${Math.round(chunk.startTime)}s-${Math.round(chunk.endTime)}s: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
+      wrapError(error, `Chunk ${chunk.id} failed for ${Math.round(chunk.startTime)}s-${Math.round(chunk.endTime)}s`);
     }
     const [leftChunk, rightChunk] = splitTranslationChunkAtMidpoint(chunk);
     const [leftResult, rightResult] = await Promise.all([
@@ -5911,28 +5981,31 @@ async function translateCaptions(assetId, trackId, toLanguageCode, options) {
     provider
   });
   if (uploadToS3 && (!s3Endpoint || !s3Bucket || !effectiveStorageAdapter && (!s3AccessKeyId || !s3SecretAccessKey))) {
-    throw new Error("Storage configuration is required for uploading. Provide s3Endpoint and s3Bucket. If no storageAdapter is supplied, also provide s3AccessKeyId and s3SecretAccessKey in options or set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY environment variables.");
+    throw new MuxAiError("Storage configuration is required for uploading. Provide s3Endpoint and s3Bucket. If no storageAdapter is supplied, also provide s3AccessKeyId and s3SecretAccessKey in options or set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, and S3_SECRET_ACCESS_KEY environment variables.", { type: "validation_error" });
   }
   const { asset: assetData, playbackId, policy } = await getPlaybackIdForAsset(assetId, credentials);
   const assetDurationSeconds = getAssetDurationSecondsFromAsset(assetData);
   const signingContext = await resolveMuxSigningContext(credentials);
   if (policy === "signed" && !signingContext) {
-    throw new Error(
-      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables."
+    throw new MuxAiError(
+      "Signed playback ID requires signing credentials. Set MUX_SIGNING_KEY and MUX_PRIVATE_KEY environment variables.",
+      { type: "validation_error" }
     );
   }
   const readyTextTracks = getReadyTextTracks(assetData);
   const sourceTextTrack = readyTextTracks.find((t) => t.id === trackId);
   if (!sourceTextTrack) {
     const availableTrackIds = readyTextTracks.map((t) => t.id).filter(Boolean).join(", ");
-    throw new Error(
-      `Track '${trackId}' not found or not ready on asset '${assetId}'. Available track IDs: ${availableTrackIds || "none"}`
+    throw new MuxAiError(
+      `Track ${trackId} not found or not ready on asset ${assetId}. Available track IDs: ${availableTrackIds || "none"}.`,
+      { type: "validation_error" }
     );
   }
   const fromLanguageCode = sourceTextTrack.language_code;
   if (!fromLanguageCode) {
-    throw new Error(
-      `Track '${trackId}' is missing language metadata (language_code). Cannot determine source language for translation.`
+    throw new MuxAiError(
+      `Track ${trackId} is missing language metadata. Cannot determine source language for translation.`,
+      { type: "validation_error" }
     );
   }
   const vttUrl = await buildTranscriptUrl(playbackId, trackId, policy === "signed", credentials);
@@ -5940,7 +6013,7 @@ async function translateCaptions(assetId, trackId, toLanguageCode, options) {
   try {
     vttContent = await fetchVttFromMux(vttUrl);
   } catch (error) {
-    throw new Error(`Failed to fetch VTT content: ${error instanceof Error ? error.message : "Unknown error"}`);
+    wrapError(error, "Failed to fetch VTT content");
   }
   let translatedVtt;
   let usage;
@@ -5958,7 +6031,7 @@ async function translateCaptions(assetId, trackId, toLanguageCode, options) {
     translatedVtt = result.translatedVtt;
     usage = result.usage;
   } catch (error) {
-    throw new Error(`Failed to translate VTT with ${modelConfig.provider}: ${error instanceof Error ? error.message : "Unknown error"}`);
+    wrapError(error, `Failed to translate VTT with ${modelConfig.provider}`);
   }
   const usageWithMetadata = usage ? {
     ...usage,
@@ -5984,7 +6057,7 @@ async function translateCaptions(assetId, trackId, toLanguageCode, options) {
         s3SignedUrlExpirySeconds: options.s3SignedUrlExpirySeconds
       });
     } catch (error) {
-      throw new Error(`Failed to upload VTT to S3: ${error instanceof Error ? error.message : "Unknown error"}`);
+      wrapError(error, "Failed to upload VTT to S3");
     }
     if (uploadToMux) {
       try {