@mux/ai 0.54.0 → 0.55.0

package/dist/{index-cbaPe-aE.d.ts → index-B-rLy1do.d.ts}

@@ -1,4 +1,4 @@
-import { l as WorkflowCredentialsInput, n as WorkflowScope, T as TextChunk, b as ChunkingStrategy, q as VTTCue, r as CompletedShotsResult, D as DeletedShotsResult, s as ErroredShotsResult, H as Hotspot, t as HotspotOptions, u as HotspotResponse, L as LOW_CONFIDENCE_THRESHOLD, v as MAX_CUE_TEXT_CHARS, w as ParseVTTCuesOptions, x as PendingShotsResult, y as Shot, z as ShotRequestOptions, B as ShotsResult, F as SkippedShotsResult, G as TranscriptEmptyReason, J as TranscriptFetchOptions, K as TranscriptFetchStepResult, N as TranscriptResult, O as WaitForShotsOptions, Q as buildTranscriptUrl, R as buildVttFromCueBlocks, X as buildVttFromTranslatedCueBlocks, Y as concatenateVttSegments, Z as extractTextFromVTT, _ as extractTimestampedTranscript, $ as fetchTranscriptDataForUrl, a0 as fetchTranscriptForAsset, a1 as filterVttByScope, a2 as findCaptionTrack, a3 as getHotspotsForAsset, a4 as getHotspotsForPlaybackId, a5 as getHotspotsForVideo, a6 as getReadyTextTracks, a7 as getReliableLanguageCode, a8 as getShotsForAsset, a9 as parseVTTCues, aa as replaceCueText, ab as requestShotsForAsset, ac as sanitizeUntrustedText, ad as secondsToTimestamp, ae as splitVttPreambleAndCueBlocks, af as stripVttMetadataBlocks, ag as vttTimestampToSeconds, ah as waitForShotsForAsset } from './transcripts-BCtzC8hZ.js';
+import { l as WorkflowCredentialsInput, n as WorkflowScope, h as TextChunk, b as ChunkingStrategy, q as VTTCue, r as CompletedShotsResult, D as DeletedShotsResult, s as ErroredShotsResult, H as Hotspot, t as HotspotOptions, u as HotspotResponse, L as LOW_CONFIDENCE_THRESHOLD, v as MAX_CUE_TEXT_CHARS, w as ParseVTTCuesOptions, x as PendingShotsResult, y as Shot, z as ShotRequestOptions, B as ShotsResult, F as SkippedShotsResult, G as TranscriptEmptyReason, J as TranscriptFetchOptions, K as TranscriptFetchStepResult, N as TranscriptResult, O as WaitForShotsOptions, Q as buildTranscriptUrl, R as buildVttFromCueBlocks, X as buildVttFromTranslatedCueBlocks, Y as concatenateVttSegments, Z as extractTextFromVTT, _ as extractTimestampedTranscript, $ as fetchTranscriptDataForUrl, a0 as fetchTranscriptForAsset, a1 as filterVttByScope, a2 as findCaptionTrack, a3 as getHotspotsForAsset, a4 as getHotspotsForPlaybackId, a5 as getHotspotsForVideo, a6 as getReadyTextTracks, a7 as getReliableLanguageCode, a8 as getShotsForAsset, a9 as parseVTTCues, aa as replaceCueText, ab as requestShotsForAsset, ac as sanitizeUntrustedText, ad as secondsToTimestamp, ae as splitVttPreambleAndCueBlocks, af as stripVttMetadataBlocks, ag as vttTimestampToSeconds, ah as waitForShotsForAsset } from './transcripts-DxSHvTk9.js';
 
 interface HeatmapOptions {
     /** Time window for results, e.g., '7:days' (default: '7:days') */

package/dist/{index-CmTC1w4V.d.ts → index-BBk0AcY1.d.ts}

@@ -1,5 +1,5 @@
 import { LanguageModel, generateText as generateText$1 } from 'ai';
-import { l as WorkflowCredentialsInput, M as MuxAsset, A as AssetTextTrack, i as TokenUsage, f as ScopedMuxAIOptions, I as ImageSubmissionMode, d as MuxAIOptions, b as ChunkingStrategy, k as VideoEmbeddingsResult, H as Hotspot, y as Shot, q as VTTCue, j as ToneType, g as StorageAdapter } from './transcripts-BCtzC8hZ.js';
+import { l as WorkflowCredentialsInput, M as MuxAsset, A as AssetTextTrack, T as TokenUsage, f as ScopedMuxAIOptions, I as ImageSubmissionMode, d as MuxAIOptions, b as ChunkingStrategy, k as VideoEmbeddingsResult, H as Hotspot, y as Shot, q as VTTCue, j as ToneType, g as StorageAdapter } from './transcripts-DxSHvTk9.js';
 import { z } from 'zod';
 import { S as SafetyReport, e as PromptOverrides, h as SceneContextItemV1, D as DEFAULT_DESCRIPTION_LENGTH, a as DEFAULT_SUMMARY_KEYWORD_LIMIT, b as DEFAULT_TITLE_LENGTH } from './summarization-BFmhXeAu.js';
 import { createAnthropic } from '@ai-sdk/anthropic';

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { I as ISO639_1, a as ISO639_3, L as LanguageCodePair, M as MUX_TRACK_PASSTHROUGH_MAX_CHARS, R as ReplaceAndCreateTextTrackInput, b as ReplaceAndCreateTextTrackResult, c as ReplaceAndCreateTrackInput, d as ReplaceExistingTracksPolicy, e as ReplaceSourceTrackInput, f as ReplaceableTrackType, S as SourceTrackReplacementPolicy, g as SupportedISO639_1, h as SupportedISO639_3, T as TextTrackReplacementPlan, i as TextTrackSummary, j as TextTrackTarget, k as TrackSummary, l as TrackTarget, m as buildMuxAiTrackPassthrough, n as findNameCollisionTextTracks, o as findSameLanguageTextTracks, p as getLanguageCodePair, q as getLanguageName, r as isDuplicateTrackNameError, s as isMuxGeneratedTextTrack, t as isUndeterminedLanguageCode, u as isValidISO639_1, v as isValidISO639_3, w as normalizeTrackLanguageCode, x as normalizeTrackName, y as planSourceTrackReplacement, z as planTextTrackReplacement, A as replaceAndCreateTextTrack, B as replaceAndCreateTrack, C as replaceSourceTrack, D as summarizeTextTrack, E as toISO639_1, F as toISO639_3, G as validateTrackPassthrough, H as workflows } from './index-CmTC1w4V.js';
-import { M as MuxAsset, W as WorkflowCredentials, S as StoragePutObjectInput, a as StoragePresignGetObjectInput } from './transcripts-BCtzC8hZ.js';
-export { A as AssetTextTrack, C as ChunkEmbedding, b as ChunkingStrategy, E as Encrypted, c as EncryptedPayload, I as ImageSubmissionMode, d as MuxAIOptions, P as PlaybackAsset, e as PlaybackPolicy, f as ScopedMuxAIOptions, g as StorageAdapter, T as TextChunk, h as TokenChunkingConfig, i as TokenUsage, j as ToneType, U as UsageMetadata, V as VTTChunkingConfig, k as VideoEmbeddingsResult, l as WorkflowCredentialsInput, m as WorkflowMuxClient, n as WorkflowScope, o as decryptFromWorkflow, p as encryptForWorkflow } from './transcripts-BCtzC8hZ.js';
+export { I as ISO639_1, a as ISO639_3, L as LanguageCodePair, M as MUX_TRACK_PASSTHROUGH_MAX_CHARS, R as ReplaceAndCreateTextTrackInput, b as ReplaceAndCreateTextTrackResult, c as ReplaceAndCreateTrackInput, d as ReplaceExistingTracksPolicy, e as ReplaceSourceTrackInput, f as ReplaceableTrackType, S as SourceTrackReplacementPolicy, g as SupportedISO639_1, h as SupportedISO639_3, T as TextTrackReplacementPlan, i as TextTrackSummary, j as TextTrackTarget, k as TrackSummary, l as TrackTarget, m as buildMuxAiTrackPassthrough, n as findNameCollisionTextTracks, o as findSameLanguageTextTracks, p as getLanguageCodePair, q as getLanguageName, r as isDuplicateTrackNameError, s as isMuxGeneratedTextTrack, t as isUndeterminedLanguageCode, u as isValidISO639_1, v as isValidISO639_3, w as normalizeTrackLanguageCode, x as normalizeTrackName, y as planSourceTrackReplacement, z as planTextTrackReplacement, A as replaceAndCreateTextTrack, B as replaceAndCreateTrack, C as replaceSourceTrack, D as summarizeTextTrack, E as toISO639_1, F as toISO639_3, G as validateTrackPassthrough, H as workflows } from './index-BBk0AcY1.js';
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
-export { i as primitives } from './index-cbaPe-aE.js';
+import { T as TokenUsage, M as MuxAsset, W as WorkflowCredentials, S as StoragePutObjectInput, a as StoragePresignGetObjectInput } from './transcripts-DxSHvTk9.js';
+export { A as AssetTextTrack, C as ChunkEmbedding, b as ChunkingStrategy, E as Encrypted, c as EncryptedPayload, I as ImageSubmissionMode, d as MuxAIOptions, P as PlaybackAsset, e as PlaybackPolicy, f as ScopedMuxAIOptions, g as StorageAdapter, h as TextChunk, i as TokenChunkingConfig, j as ToneType, U as UsageMetadata, V as VTTChunkingConfig, k as VideoEmbeddingsResult, l as WorkflowCredentialsInput, m as WorkflowMuxClient, n as WorkflowScope, o as decryptFromWorkflow, p as encryptForWorkflow } from './transcripts-DxSHvTk9.js';
+export { i as primitives } from './index-B-rLy1do.js';
 import 'ai';
 import 'zod';
 import './summarization-BFmhXeAu.js';
@@ -11,9 +11,25 @@ import '@ai-sdk/google';
 import '@ai-sdk/openai';
 import '@mux/ts';
 
-var version = "0.54.0";
+var version = "0.55.0";
 
 type MuxAiErrorType = "validation_error" | "processing_error" | "timeout_error" | "content_policy_error";
+interface ModelCallDiagnostics {
+    phase: "brief" | "draft" | "format_repair" | "length_repair";
+    provider: string;
+    modelId: string;
+    maxOutputTokens?: number;
+}
+interface SerializedMuxAiError {
+    message: string;
+    publicType: MuxAiErrorType;
+    retryable: boolean;
+    stack?: string;
+    usage?: TokenUsage;
+    finishReason?: string;
+    rawFinishReason?: string;
+    diagnostics?: ModelCallDiagnostics;
+}
 /**
  * An error whose message is safe to surface verbatim to the customer.
  *
@@ -23,9 +39,8 @@ type MuxAiErrorType = "validation_error" | "processing_error" | "timeout_error"
  * this brand (unexpected SDK failures, upstream provider errors, etc.)
  * should be treated as internal and obfuscated.
  *
- * Own properties (`publicMessage`, `publicType`, `retryable`) survive
- * JSON serialization across workflow step boundaries, unlike inherited
- * `Error.message`.
+ * Custom Workflow serializers preserve safe metadata across step boundaries.
+ * The runtime's built-in Error serializer drops arbitrary own properties.
  */
 declare class MuxAiError extends Error {
     /** Structural brand for duck-type identification. */
@@ -36,6 +51,8 @@ declare class MuxAiError extends Error {
     readonly publicMessage: string;
     /** Whether the customer should retry the job. */
     readonly retryable: boolean;
+    usage?: TokenUsage;
+    diagnostics?: ModelCallDiagnostics;
     /** Internal diagnostic failure; non-enumerable and excluded from JSON. */
     readonly cause?: unknown;
     constructor(message: string, opts?: {
@@ -44,6 +61,8 @@ declare class MuxAiError extends Error {
         cause?: unknown;
     });
     static is(value: unknown): value is MuxAiError;
+    static [WORKFLOW_SERIALIZE](instance: MuxAiError): SerializedMuxAiError;
+    static [WORKFLOW_DESERIALIZE](value: SerializedMuxAiError): MuxAiError;
 }
 declare function wrapError(error: unknown, message: string): never;
 
@@ -131,4 +150,4 @@ declare class WorkflowStorageClient {
 }
 declare function createWorkflowStorageClient(options?: WorkflowStorageClientOptions): WorkflowStorageClient;
 
-export { type LegacyMp4SupportRendition, MuxAiError, type MuxAiErrorType, MuxAsset, type MuxPlaybackService, STATIC_RENDITIONS_GUIDE_URL, StoragePresignGetObjectInput, StoragePutObjectInput, WorkflowCredentials, type WorkflowCredentialsProvider, WorkflowStorageClient, createWorkflowStorageClient, getLegacyMp4SupportRenditionSizeError, getMuxPlaybackOrigin, resolveLegacyMp4SupportRendition, setWorkflowCredentialsProvider, usesLegacyMp4Support, version, wrapError };
+export { type LegacyMp4SupportRendition, MuxAiError, type MuxAiErrorType, MuxAsset, type MuxPlaybackService, STATIC_RENDITIONS_GUIDE_URL, StoragePresignGetObjectInput, StoragePutObjectInput, TokenUsage, WorkflowCredentials, type WorkflowCredentialsProvider, WorkflowStorageClient, createWorkflowStorageClient, getLegacyMp4SupportRenditionSizeError, getMuxPlaybackOrigin, resolveLegacyMp4SupportRendition, setWorkflowCredentialsProvider, usesLegacyMp4Support, version, wrapError };

package/dist/index.js

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // package.json
-var version = "0.54.0";
+var version = "0.55.0";
 
 // src/lib/language-codes.ts
 var ISO639_1_TO_3 = {
@@ -178,6 +178,10 @@ function getLanguageName(code) {
   }
 }
 
+// node_modules/@workflow/serde/dist/index.js
+var WORKFLOW_SERIALIZE = /* @__PURE__ */ Symbol.for("workflow-serialize");
+var WORKFLOW_DESERIALIZE = /* @__PURE__ */ Symbol.for("workflow-deserialize");
+
 // src/lib/prompt-fragments.ts
 import dedent from "dedent";
 
@@ -699,7 +703,7 @@ function rethrowWithTokenUsage(error, collectedUsage) {
 }
 
 // src/lib/mux-ai-error.ts
-var MuxAiError = class extends Error {
+var MuxAiError = class _MuxAiError extends Error {
   constructor(message, opts) {
     super(message);
     /** Structural brand for duck-type identification. */
@@ -715,6 +719,32 @@ var MuxAiError = class extends Error {
   static is(value) {
     return typeof value === "object" && value !== null && "__robots_error" in value && value.__robots_error === true;
   }
+  static [WORKFLOW_SERIALIZE](instance) {
+    const incomplete = instance;
+    return {
+      message: instance.publicMessage,
+      publicType: instance.publicType,
+      retryable: instance.retryable,
+      stack: instance.stack,
+      usage: getErrorTokenUsage(instance),
+      finishReason: incomplete.finishReason,
+      rawFinishReason: incomplete.rawFinishReason,
+      diagnostics: instance.diagnostics
+    };
+  }
+  static [WORKFLOW_DESERIALIZE](value) {
+    const error = new _MuxAiError(value.message, { type: value.publicType, retryable: value.retryable });
+    Object.assign(error, {
+      usage: value.usage,
+      diagnostics: value.diagnostics,
+      ...value.finishReason !== void 0 && { finishReason: value.finishReason },
+      ...value.rawFinishReason !== void 0 && { rawFinishReason: value.rawFinishReason }
+    });
+    if (value.stack !== void 0) {
+      error.stack = value.stack;
+    }
+    return error;
+  }
 };
 function extractErrorDetail(error) {
   if (error instanceof Error && error.message) {
@@ -1528,10 +1558,6 @@ async function getMuxThumbnailBaseUrl(playbackId, credentials) {
   return getMuxImageBaseUrl(playbackId, "thumbnail", credentials);
 }
 
-// node_modules/@workflow/serde/dist/index.js
-var WORKFLOW_SERIALIZE = /* @__PURE__ */ Symbol.for("workflow-serialize");
-var WORKFLOW_DESERIALIZE = /* @__PURE__ */ Symbol.for("workflow-deserialize");
-
 // src/lib/s3-sigv4.ts
 var AWS4_ALGORITHM = "AWS4-HMAC-SHA256";
 var AWS4_REQUEST_TERMINATOR = "aws4_request";
@@ -3487,7 +3513,8 @@ async function withRetry(fn, {
   maxRetries = DEFAULT_RETRY_OPTIONS.maxRetries,
   baseDelay = DEFAULT_RETRY_OPTIONS.baseDelay,
   maxDelay = DEFAULT_RETRY_OPTIONS.maxDelay,
-  shouldRetry = defaultShouldRetry
+  shouldRetry = defaultShouldRetry,
+  onRetry
 } = {}) {
   let lastError;
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
@@ -3500,6 +3527,7 @@ async function withRetry(fn, {
       if (isLastAttempt || !shouldRetry(retryError, attempt + 1)) {
         throw error;
       }
+      onRetry?.(error, attempt + 1);
       const delay = calculateDelay(attempt + 1, baseDelay, maxDelay);
       console.warn(
         `Attempt ${attempt + 1} failed: ${retryError.message}. Retrying in ${Math.round(delay)}ms...`
@@ -3593,10 +3621,54 @@ async function withContentPolicyErrorHandling(operation) {
   }
 }
 async function withContentPolicyAwareRetry(operation, retryOptions) {
-  return withRetry(
-    () => withContentPolicyErrorHandling(operation),
-    retryOptions
-  );
+  const retriedUsage = [];
+  try {
+    const response = await withRetry(
+      () => withContentPolicyErrorHandling(operation),
+      {
+        ...retryOptions,
+        onRetry: (error, attempt) => {
+          const usage = getErrorTokenUsage(error);
+          if (usage) {
+            retriedUsage.push(usage);
+          }
+          retryOptions?.onRetry?.(error, attempt);
+        }
+      }
+    );
+    return includeRetriedUsage(response, retriedUsage);
+  } catch (error) {
+    rethrowWithTokenUsage(error, retriedUsage);
+  }
+}
+function includeRetriedUsage(response, retriedUsage) {
+  if (!retriedUsage.length || typeof response !== "object" || response === null) {
+    return response;
+  }
+  const result = response;
+  const merge = (usage) => {
+    const combined = aggregateTokenUsage([...retriedUsage, getErrorTokenUsage({ usage }) ?? {}]);
+    return {
+      ...usage,
+      ...combined,
+      ...combined.cachedInputTokens !== void 0 || combined.cacheWriteTokens !== void 0 ? {
+        inputTokenDetails: {
+          ...usage?.inputTokenDetails,
+          ...combined.cachedInputTokens !== void 0 && { cacheReadTokens: combined.cachedInputTokens },
+          ...combined.cacheWriteTokens !== void 0 && { cacheWriteTokens: combined.cacheWriteTokens }
+        }
+      } : {},
+      ...combined.reasoningTokens !== void 0 ? {
+        outputTokenDetails: { ...usage?.outputTokenDetails, reasoningTokens: combined.reasoningTokens }
+      } : {}
+    };
+  };
+  const descriptors = Object.getOwnPropertyDescriptors(response);
+  descriptors.usage = { value: merge(result.usage), enumerable: true, configurable: true };
+  if ("totalUsage" in result) {
+    descriptors.totalUsage = { value: merge(result.totalUsage), enumerable: true, configurable: true };
+  }
+  return Object.create(Object.getPrototypeOf(response), descriptors);
 }
 function rethrowContentPolicyError(error) {
   const block = extractContentPolicyBlock(error);
@@ -3732,6 +3804,35 @@ function findBlockedCategory(ratings) {
   return ratings?.find((rating) => rating.blocked === true)?.category ?? void 0;
 }
 
+// src/lib/model-call-diagnostics.ts
+import { APICallError as APICallError3 } from "ai";
+function recordModelCallFailure(error, diagnostics, observedUsage = getErrorTokenUsage(error)) {
+  if (typeof error !== "object" || error === null) {
+    return;
+  }
+  const failure = error;
+  if (failure.diagnostics) {
+    return;
+  }
+  failure.diagnostics = { ...diagnostics };
+  console.warn("[@mux/ai] Model call failed.", {
+    ...diagnostics,
+    finishReason: failure.finishReason,
+    statusCode: failure.statusCode,
+    errorName: error instanceof Error ? error.name : void 0,
+    requestId: APICallError3.isInstance(error) ? error.responseHeaders?.["x-request-id"] ?? error.responseHeaders?.["request-id"] : void 0,
+    usage: observedUsage
+  });
+}
+async function withModelCallDiagnostics(diagnostics, operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    recordModelCallFailure(error, diagnostics);
+    throw error;
+  }
+}
+
 // src/lib/text-repair-capabilities.ts
 var OPENAI_REPAIR_CAPABILITIES = {
   "gpt-5.1": { supportsReasoningNone: true },
@@ -3893,13 +3994,14 @@ function createTextRepairGenerator(options) {
   return async (plan) => {
     let usage;
     const started = Date.now();
+    const maxOutputTokens = options.maxOutputTokens ?? Math.min(32768, Math.max(1024, plan.spans.reduce((total, span) => total + Math.min(...span.budgets.map((limit) => limit.value * (limit.unit === "words" ? 4 : 2))), 0) + 128));
     try {
       const response = await withContentPolicyErrorHandling(() => generateText({
         model: options.model,
         providerOptions: options.providerOptions ?? getTextRepairProviderOptions(options.model),
         maxRetries: 0,
         abortSignal: AbortSignal.timeout(options.timeoutMs ?? 3e4),
-        maxOutputTokens: options.maxOutputTokens ?? Math.min(32768, Math.max(1024, plan.spans.reduce((total, span) => total + Math.min(...span.budgets.map((limit) => limit.value * (limit.unit === "words" ? 4 : 2))), 0) + 128)),
+        maxOutputTokens,
         output: Output.object({ schema: jsonSchema(repairJsonSchema(plan)), name: "paragraph_replacements" }),
         system: promptDedent`
           ${NON_DISCLOSURE_CONSTRAINT}
@@ -3927,6 +4029,12 @@ function createTextRepairGenerator(options) {
       return { replacements: output, usage, elapsedMs: Date.now() - started };
     } catch (error) {
       const cause = NoObjectGeneratedError2.isInstance(error) && error.finishReason && error.finishReason !== "stop" ? new IncompleteGenerationError(error.finishReason, void 0, getErrorTokenUsage(error)) : error;
+      recordModelCallFailure(cause, {
+        phase: "length_repair",
+        provider: typeof options.model === "object" ? options.model.provider : "gateway",
+        modelId: typeof options.model === "object" ? options.model.modelId : options.model,
+        maxOutputTokens
+      }, usage ?? getErrorTokenUsage(cause));
       return { usage: usage ?? getErrorTokenUsage(cause), elapsedMs: Date.now() - started, error: cause instanceof Error ? cause.message : String(cause), errorCause: cause };
     }
   };
@@ -6789,7 +6897,7 @@ async function generateEngagementInsightsInternal(assetId, options, collectedUsa
 }
 
 // src/workflows/generate-text.ts
-import { APICallError as APICallError3, generateText as generateTextWithModel, Output as Output7 } from "ai";
+import { APICallError as APICallError4, generateText as generateTextWithModel, Output as Output7 } from "ai";
 import { z as z8 } from "zod";
 var GENERATE_TEXT_MAX_VARIANTS = 5;
 var GENERATE_TEXT_MAX_ARTIFACTS = 5;
@@ -6912,7 +7020,7 @@ function resolveGenerateTextOptions(options) {
   }
   return { ...options, variants };
 }
-var LENGTH_TARGET_RATIO = 0.9;
+var LENGTH_TARGET_RATIO = 0.85;
 function resolveLengthTarget(limit) {
   return Math.max(1, Math.floor(limit.value * LENGTH_TARGET_RATIO));
 }
@@ -7201,122 +7309,124 @@ function readUsage(response) {
 }
 async function extractBriefWithModel(args) {
   "use step";
-  const model = await createLanguageModelFromConfig(args.provider, args.modelId, args.credentials);
-  const response = await withContentPolicyAwareRetry(() => generateTextWithModel({
-    model,
-    maxRetries: 0,
-    output: Output7.object({
-      name: "editorial_brief",
-      description: "Source-grounded editorial brief used to write every requested artifact.",
-      schema: briefSchema
-    }),
-    system: args.systemPrompt,
-    messages: [
-      {
-        role: "user",
-        content: [
-          { type: "text", text: args.userPrompt },
-          ...args.imageUrls.map((url) => ({ type: "image", image: url }))
-        ]
-      }
-    ]
-  }));
-  const output = getGeneratedOutputWithContentPolicyHandling(response);
-  if (!output) {
-    throw new Error("Editorial brief output missing");
-  }
-  return {
-    brief: clampBriefArrays(briefSchema.parse(output)),
-    usage: readUsage(response),
-    unexpectedKeys: detectUnexpectedKeysFromRawText(response.text, briefSchema.keyof().options)
-  };
-}
-var artifactSchema = z8.object({ content: z8.string() });
-async function generateArtifactWithModel(args) {
-  "use step";
-  const model = await createLanguageModelFromConfig(args.provider, args.modelId, args.credentials);
-  const attempt = async (messages) => {
+  return withModelCallDiagnostics({ phase: "brief", provider: args.provider, modelId: args.modelId }, async () => {
+    const model = await createLanguageModelFromConfig(args.provider, args.modelId, args.credentials);
     const response = await withContentPolicyAwareRetry(() => generateTextWithModel({
       model,
       maxRetries: 0,
       output: Output7.object({
-        name: "generated_text",
-        description: "One finished artifact written from the editorial brief.",
-        schema: artifactSchema
+        name: "editorial_brief",
+        description: "Source-grounded editorial brief used to write every requested artifact.",
+        schema: briefSchema
       }),
       system: args.systemPrompt,
-      messages
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: args.userPrompt },
+            ...args.imageUrls.map((url) => ({ type: "image", image: url }))
+          ]
+        }
+      ]
     }));
     const output = getGeneratedOutputWithContentPolicyHandling(response);
     if (!output) {
-      throw new Error("Generated text output missing");
+      throw new Error("Editorial brief output missing");
     }
     return {
-      content: artifactSchema.parse(output).content.trim(),
+      brief: clampBriefArrays(briefSchema.parse(output)),
       usage: readUsage(response),
-      unexpectedKeys: detectUnexpectedKeysFromRawText(response.text, artifactSchema.keyof().options)
+      unexpectedKeys: detectUnexpectedKeysFromRawText(response.text, briefSchema.keyof().options)
     };
-  };
-  const judge = (content) => content ? findGenerateTextLengthViolation(content, args.limits) : "empty";
-  const initialMessages = [{ role: "user", content: args.userPrompt }];
-  const first = await attempt(initialMessages);
-  const firstViolation = judge(first.content);
-  const firstEscaped = hasEscapedLineBreaks(first.content);
-  if (!firstViolation && !firstEscaped) {
-    return { content: first.content, usages: [first.usage], unexpectedKeys: first.unexpectedKeys };
-  }
-  let candidate = first;
-  const usages = [first.usage];
-  const unexpectedKeys = [...first.unexpectedKeys];
-  if (firstViolation === "empty" || firstEscaped) {
-    const feedback = [
-      firstViolation && firstViolation !== "empty" ? describeLengthRevision(firstViolation) : void 0,
-      firstEscaped ? ESCAPED_TEXT_REVISION : void 0
-    ].filter((line) => Boolean(line)).join("\n");
-    const revisionMessages = firstViolation === "empty" ? [{ role: "user", content: `${args.userPrompt}
+  });
+}
+var artifactSchema = z8.object({ content: z8.string() });
+async function generateArtifactWithModel(args) {
+  "use step";
+  const diagnostics = { phase: "draft", provider: args.provider, modelId: args.modelId };
+  return withModelCallDiagnostics(diagnostics, async () => {
+    const model = await createLanguageModelFromConfig(args.provider, args.modelId, args.credentials);
+    const attempt = async (messages) => {
+      const response = await withContentPolicyAwareRetry(() => generateTextWithModel({
+        model,
+        maxRetries: 0,
+        output: Output7.object({
+          name: "generated_text",
+          description: "One finished artifact written from the editorial brief.",
+          schema: artifactSchema
+        }),
+        system: args.systemPrompt,
+        messages
+      }));
+      const output = getGeneratedOutputWithContentPolicyHandling(response);
+      if (!output) {
+        throw new Error("Generated text output missing");
+      }
+      return {
+        content: artifactSchema.parse(output).content.trim(),
+        usage: readUsage(response),
+        unexpectedKeys: detectUnexpectedKeysFromRawText(response.text, artifactSchema.keyof().options)
+      };
+    };
+    const judge = (content) => content ? findGenerateTextLengthViolation(content, args.limits) : "empty";
+    const initialMessages = [{ role: "user", content: args.userPrompt }];
+    const first = await attempt(initialMessages);
+    const firstViolation = judge(first.content);
+    const firstEscaped = hasEscapedLineBreaks(first.content);
+    if (!firstViolation && !firstEscaped) {
+      return { content: first.content, usages: [first.usage], unexpectedKeys: first.unexpectedKeys };
+    }
+    let candidate = first;
+    const usages = [first.usage];
+    const unexpectedKeys = [...first.unexpectedKeys];
+    if (firstViolation === "empty" || firstEscaped) {
+      const feedback = [
+        firstViolation && firstViolation !== "empty" ? describeLengthRevision(firstViolation) : void 0,
+        firstEscaped ? ESCAPED_TEXT_REVISION : void 0
+      ].filter((line) => Boolean(line)).join("\n");
+      const revisionMessages = firstViolation === "empty" ? [{ role: "user", content: `${args.userPrompt}
 
 ${renderSection({ tag: "revision_request", content: "The previous draft was empty. Write the complete artifact." })}` }] : [...initialMessages, { role: "assistant", content: JSON.stringify({ content: first.content }) }, { role: "user", content: renderSection({ tag: "revision_request", content: feedback }) }];
-    candidate = await attempt(revisionMessages).catch((error) => rethrowWithTokenUsage(error, usages));
-    usages.push(candidate.usage);
-    unexpectedKeys.push(...candidate.unexpectedKeys);
-  }
-  const violation = judge(candidate.content);
-  if (!violation || violation === "empty") {
-    return { content: candidate.content, usages, unexpectedKeys, violation };
-  }
-  const repaired = await repairText({
-    content: candidate.content,
-    limits: args.limits,
-    protectedTerms: args.protectedTerms,
-    model
-  });
-  usages.push(...repaired.attempts.flatMap((item) => item.call.usage ? [item.call.usage] : []));
-  if (repaired.status !== "valid") {
-    const cause = repaired.attempts.at(-1)?.call.errorCause;
-    let failure;
-    if (isIncompleteGenerationError(cause)) {
-      failure = new IncompleteGenerationError(cause.finishReason, cause.rawFinishReason);
-    } else if (MuxAiError.is(cause)) {
-      failure = new MuxAiError(cause.publicMessage, { type: cause.publicType, retryable: cause.retryable });
-    } else {
-      const apiError = APICallError3.isInstance(cause) ? cause : void 0;
-      console.warn("[@mux/ai] Bounded text repair failed.", {
-        provider: args.provider,
-        modelId: args.modelId,
-        reason: repaired.reason,
-        errorName: cause instanceof Error ? cause.name : void 0,
-        statusCode: apiError?.statusCode,
-        requestId: apiError?.responseHeaders?.["x-request-id"] ?? apiError?.responseHeaders?.["request-id"]
-      });
-      failure = new MuxAiError("Unable to complete text generation.", {
-        type: "processing_error",
-        retryable: apiError?.isRetryable ?? true,
-        cause
-      });
+      diagnostics.phase = "format_repair";
+      candidate = await attempt(revisionMessages).catch((error) => rethrowWithTokenUsage(error, usages));
+      usages.push(candidate.usage);
+      unexpectedKeys.push(...candidate.unexpectedKeys);
+    }
+    const violation = judge(candidate.content);
+    if (!violation || violation === "empty") {
+      return { content: candidate.content, usages, unexpectedKeys, violation };
+    }
+    diagnostics.phase = "length_repair";
+    const repaired = await repairText({
+      content: candidate.content,
+      limits: args.limits,
+      protectedTerms: args.protectedTerms,
+      model
+    });
+    usages.push(...repaired.attempts.flatMap((item) => item.call.usage ? [item.call.usage] : []));
+    if (repaired.status !== "valid") {
+      const cause = repaired.attempts.at(-1)?.call.errorCause;
+      let failure;
+      if (isIncompleteGenerationError(cause)) {
+        failure = new IncompleteGenerationError(cause.finishReason, cause.rawFinishReason);
+      } else if (MuxAiError.is(cause)) {
+        failure = new MuxAiError(cause.publicMessage, { type: cause.publicType, retryable: cause.retryable });
+      } else {
+        const apiError = APICallError4.isInstance(cause) ? cause : void 0;
+        failure = new MuxAiError("Unable to complete text generation.", {
+          type: "processing_error",
+          retryable: apiError?.isRetryable ?? true,
+          cause
+        });
+      }
+      if (typeof cause === "object" && cause !== null && "diagnostics" in cause) {
+        failure.diagnostics = cause.diagnostics;
+      }
+      rethrowWithTokenUsage(failure, usages);
     }
-    rethrowWithTokenUsage(failure, usages);
-  }
-  return { content: repaired.content, usages, unexpectedKeys };
+    return { content: repaired.content, usages, unexpectedKeys };
+  });
 }
 async function generateText7(assetId, options) {
   "use workflow";
@@ -9702,7 +9812,7 @@ async function translateAudio(assetId, toLanguageCode, options = {}) {
 
 // src/workflows/translate-captions.ts
 import {
-  APICallError as APICallError4,
+  APICallError as APICallError5,
   generateText as generateText9,
   NoObjectGeneratedError as NoObjectGeneratedError3,
   NoOutputGeneratedError as NoOutputGeneratedError2,
@@ -9857,7 +9967,7 @@ function isProviderServiceError(error) {
   if (RetryError2.isInstance(error)) {
     return isProviderServiceError(error.lastError);
   }
-  if (APICallError4.isInstance(error)) {
+  if (APICallError5.isInstance(error)) {
     return true;
   }
   if (error instanceof Error && "cause" in error) {