@agent-native/core 0.79.17 → 0.79.19

package/corpus/templates/clips/desktop/src/lib/recorder.ts

@@ -86,6 +86,7 @@ const NATIVE_FULLSCREEN_RECORDING_FLAG = "clips:native-fullscreen-recording";
 const DEV_SYNTHETIC_CAPTURE_FLAG = "clips:dev-synthetic-capture";
 const LEGACY_DEV_REAL_CAPTURE_FLAG = "clips:dev-real-capture";
 const LIVE_UPLOAD_CHUNK_MS = 1_000;
+const NATIVE_FULLSCREEN_SEGMENT_MS = 5 * 60_000;
 const CLOUD_CAPTURE_FRAME_RATE = 24;
 const CLOUD_CAPTURE_MAX_WIDTH = 1920;
 const CLOUD_CAPTURE_MAX_HEIGHT = 1080;
@@ -122,6 +123,13 @@ export function shouldUseNativeFullscreenRecording(
   return isMacPlatform();
 }
 
+function shouldSaveLocalTranscriptionStartupFailure(): boolean {
+  // Local Whisper/SFSpeech capture is macOS-only today. Non-mac desktop builds
+  // should wait for upload transcription instead of publishing a misleading
+  // native-transcription failure before `request-transcript` runs.
+  return isMacPlatform();
+}
+
 function shouldUseDevSyntheticCapture(): boolean {
   if (!import.meta.env.DEV) return false;
   if (typeof localStorage === "undefined") return false;
@@ -962,7 +970,7 @@ async function saveRecordingTranscript(
         recordingId,
         fullText: text,
         segments: transcript.segments,
-        source: "whisper",
+        source: transcript.source ?? "whisper",
       }),
     });
     if (!res.ok) {
@@ -1753,6 +1761,8 @@ async function startNativeFullscreenRecording(
   let cancelPromise: Promise<void> | null = null;
   let stateUnlistens: UnlistenFn[] = [];
   let tickHandle: ReturnType<typeof setInterval> | null = null;
+  let segmentRotateHandle: ReturnType<typeof setInterval> | null = null;
+  let segmentRotateInFlight = false;
   // Pause/resume tracking. The Rust side actually stops the SCStream on
   // pause and starts a new segment on resume; on stop it concatenates
   // segments via AVFoundation. We keep the JS-side timer in sync so the
@@ -1760,6 +1770,37 @@ async function startNativeFullscreenRecording(
   let pausedAt: number | null = null;
   let accumulatedPauseMs = 0;
 
+  function clearSegmentRotator() {
+    if (segmentRotateHandle) {
+      clearInterval(segmentRotateHandle);
+      segmentRotateHandle = null;
+    }
+  }
+
+  function startSegmentRotator() {
+    clearSegmentRotator();
+    segmentRotateHandle = setInterval(() => {
+      if (stopped || pausedAt != null || segmentRotateInFlight) return;
+      segmentRotateInFlight = true;
+      invoke("native_fullscreen_recording_rotate_segment")
+        .catch((err) => {
+          const message = err instanceof Error ? err.message : String(err);
+          console.warn("[clips-recorder] native segment rotation failed:", err);
+          if (
+            !stopped &&
+            pausedAt == null &&
+            message.includes("paused recording")
+          ) {
+            pausedAt = Date.now();
+            emitState();
+          }
+        })
+        .finally(() => {
+          segmentRotateInFlight = false;
+        });
+    }, NATIVE_FULLSCREEN_SEGMENT_MS);
+  }
+
   function emitState() {
     const now = Date.now();
     const pausedNowMs = pausedAt != null ? now - pausedAt : 0;
@@ -1781,6 +1822,7 @@ async function startNativeFullscreenRecording(
         stopped = true;
         console.log("[clips-recorder] native full-screen stop requested");
         if (!localOnly) showFinalizingFeedback();
+        clearSegmentRotator();
         if (tickHandle) {
           clearInterval(tickHandle);
           tickHandle = null;
@@ -1940,6 +1982,7 @@ async function startNativeFullscreenRecording(
       if (stopped) return;
       cancelPromise = (async () => {
         stopped = true;
+        clearSegmentRotator();
         if (tickHandle) {
           clearInterval(tickHandle);
           tickHandle = null;
@@ -2020,6 +2063,7 @@ async function startNativeFullscreenRecording(
   ]);
   stateUnlistens = toolbarUnlistens;
   tickHandle = setInterval(emitState, 500);
+  startSegmentRotator();
   emit("clips:toolbar-enabled", true).catch(() => {});
   emitState();
 
@@ -2041,7 +2085,11 @@ async function startNativeFullscreenRecording(
     if (stopped && transcriptionCapture) {
       void transcriptionCapture.cancel().catch(() => {});
       transcriptionCapture = null;
-    } else if (wantsAudio && !transcriptionCapture) {
+    } else if (
+      wantsAudio &&
+      !transcriptionCapture &&
+      shouldSaveLocalTranscriptionStartupFailure()
+    ) {
       void saveTranscriptFailure(
         "macOS Speech recognition could not start for this recording. Check Speech Recognition and Microphone permissions, then retry transcription.",
       );
@@ -2863,7 +2911,11 @@ async function startRecordingInner(
   if (stopped && transcriptionCapture) {
     void transcriptionCapture.cancel().catch(() => {});
     transcriptionCapture = null;
-  } else if (wantsAudio && !transcriptionCapture) {
+  } else if (
+    wantsAudio &&
+    !transcriptionCapture &&
+    shouldSaveLocalTranscriptionStartupFailure()
+  ) {
     void saveTranscriptFailure(
       "macOS Speech recognition could not start for this recording. Check Speech Recognition and Microphone permissions, then retry transcription.",
     );

package/corpus/templates/clips/desktop/src/lib/transcription-capture.ts

@@ -1,10 +1,10 @@
 /**
  * Live transcription for recordings.
  *
- * Thin wrapper over the shared transcription engine (`transcription-engine.ts`),
- * which runs a local whisper.cpp context over BOTH the microphone and system
- * audio in parallel. Whisper does not end per-utterance, so the workers run
- * continuously until stop, which flushes any trailing speech.
+ * Thin wrapper over the shared transcription engines. It tries local
+ * whisper.cpp/macOS speech first (mic + optional system audio), then falls
+ * back to Web Speech in the desktop webview when the local Rust engine is not
+ * available (notably non-mac builds).
  *
  * The handle exposes `stop()` (returns the full speaker-labelled transcript,
  * after a short grace for trailing finals) and `cancel()` (stops + discards).
@@ -23,6 +23,7 @@ import {
 
 /** Grace period after stop for whisper to emit any flushed trailing finals. */
 const WHISPER_STOP_SETTLE_MS = 1500;
+const WEB_SPEECH_STOP_SETTLE_MS = 1200;
 
 function wait(ms: number): Promise<void> {
   return new Promise((resolve) => window.setTimeout(resolve, ms));
@@ -33,6 +34,8 @@ export interface CapturedTranscript {
   text: string;
   /** Real whisper segments with verbatim timestamps. */
   segments: SourcedTranscriptSegment[];
+  /** Source stored with `save-browser-transcript`. */
+  source?: "web-speech" | "macos-native" | "whisper";
 }
 
 export interface TranscriptionCapture {
@@ -40,6 +43,213 @@ export interface TranscriptionCapture {
   cancel(): Promise<void>;
 }
 
+interface SpeechRecognitionResultLike {
+  isFinal: boolean;
+  0?: { transcript?: string };
+}
+
+interface SpeechRecognitionEventLike {
+  resultIndex: number;
+  results: ArrayLike<SpeechRecognitionResultLike>;
+}
+
+interface SpeechRecognitionErrorEventLike {
+  error: string;
+}
+
+interface SpeechRecognitionLike {
+  continuous: boolean;
+  interimResults: boolean;
+  lang: string;
+  maxAlternatives: number;
+  onresult: ((event: SpeechRecognitionEventLike) => void) | null;
+  onerror: ((event: SpeechRecognitionErrorEventLike) => void) | null;
+  onend: (() => void) | null;
+  start: () => void;
+  stop: () => void;
+  abort: () => void;
+}
+
+type SpeechRecognitionCtor = new () => SpeechRecognitionLike;
+
+function getSpeechRecognitionCtor(): SpeechRecognitionCtor | null {
+  if (typeof window === "undefined") return null;
+  const w = window as unknown as {
+    SpeechRecognition?: SpeechRecognitionCtor;
+    webkitSpeechRecognition?: SpeechRecognitionCtor;
+  };
+  return w.SpeechRecognition || w.webkitSpeechRecognition || null;
+}
+
+function browserLanguage(): string {
+  return navigator.language || "en-US";
+}
+
+function shouldUseBrowserTranscriptionFallback(): boolean {
+  if (typeof navigator === "undefined") return false;
+  const platform =
+    (navigator as { userAgentData?: { platform?: string } }).userAgentData
+      ?.platform ||
+    navigator.platform ||
+    navigator.userAgent;
+
+  // Keep macOS on the existing local Whisper -> SFSpeech path. Web Speech is
+  // only a bridge for non-mac desktop builds where the Rust engines are absent.
+  return !/mac/i.test(platform);
+}
+
+function appendTranscriptText(current: string, next: string): string {
+  const cleanCurrent = current.trim();
+  const cleanNext = next.trim();
+  if (!cleanNext) return cleanCurrent;
+  if (!cleanCurrent) return cleanNext;
+  return `${cleanCurrent} ${cleanNext}`;
+}
+
+function createWebSpeechTranscriptBuffer() {
+  let committedFinalText = "";
+  let sessionFinalText = "";
+  let interimText = "";
+
+  return {
+    update(event: SpeechRecognitionEventLike) {
+      let nextFinal = "";
+      let nextInterim = "";
+      for (let i = 0; i < event.results.length; i++) {
+        const result = event.results[i];
+        const text = result[0]?.transcript ?? "";
+        if (result.isFinal) {
+          nextFinal += text;
+        } else {
+          nextInterim += text;
+        }
+      }
+      sessionFinalText = nextFinal;
+      interimText = nextInterim;
+    },
+    commitSession(opts?: { preserveInterim?: boolean }) {
+      committedFinalText = appendTranscriptText(
+        committedFinalText,
+        sessionFinalText,
+      );
+      sessionFinalText = "";
+      if (!opts?.preserveInterim) {
+        interimText = "";
+      }
+    },
+    text() {
+      return [committedFinalText, sessionFinalText, interimText]
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .join(" ")
+        .trim();
+    },
+  };
+}
+
+async function startBrowserTranscriptionCapture(): Promise<TranscriptionCapture | null> {
+  const Ctor = getSpeechRecognitionCtor();
+  if (!Ctor) return null;
+
+  const recognition = new Ctor();
+  let disposed = false;
+  let stopped = false;
+  const transcriptBuffer = createWebSpeechTranscriptBuffer();
+  let stopResolver: ((value: CapturedTranscript) => void) | null = null;
+  let settleTimer: ReturnType<typeof window.setTimeout> | null = null;
+
+  const captured = (): CapturedTranscript => ({
+    text: transcriptBuffer.text(),
+    segments: [],
+    source: "web-speech",
+  });
+
+  const settleStop = () => {
+    if (!stopResolver) return;
+    if (settleTimer) {
+      window.clearTimeout(settleTimer);
+      settleTimer = null;
+    }
+    const resolve = stopResolver;
+    stopResolver = null;
+    disposed = true;
+    resolve(captured());
+  };
+
+  recognition.continuous = true;
+  recognition.interimResults = true;
+  recognition.lang = browserLanguage();
+  recognition.maxAlternatives = 1;
+
+  recognition.onresult = (event) => {
+    transcriptBuffer.update(event);
+  };
+
+  recognition.onerror = (event) => {
+    if (event.error === "no-speech" || event.error === "aborted") return;
+    console.warn(
+      "[clips-recorder] Web Speech transcription error:",
+      event.error,
+    );
+  };
+
+  recognition.onend = () => {
+    if (disposed) return;
+    transcriptBuffer.commitSession({ preserveInterim: stopped });
+    if (stopped) {
+      settleStop();
+      return;
+    }
+    try {
+      recognition.start();
+    } catch (err) {
+      console.warn(
+        "[clips-recorder] Web Speech transcription restart failed:",
+        err,
+      );
+    }
+  };
+
+  try {
+    recognition.start();
+    console.log("[clips-recorder] transcription started (web-speech mic)");
+  } catch (err) {
+    console.warn("[clips-recorder] Web Speech transcription unavailable:", err);
+    disposed = true;
+    return null;
+  }
+
+  return {
+    stop() {
+      stopped = true;
+      return new Promise<CapturedTranscript>((resolve) => {
+        stopResolver = resolve;
+        settleTimer = window.setTimeout(settleStop, WEB_SPEECH_STOP_SETTLE_MS);
+        try {
+          recognition.stop();
+        } catch {
+          settleStop();
+        }
+      });
+    },
+    async cancel() {
+      disposed = true;
+      stopped = true;
+      if (settleTimer) {
+        window.clearTimeout(settleTimer);
+        settleTimer = null;
+      }
+      try {
+        recognition.abort();
+      } catch {
+        // ignore
+      }
+    },
+  };
+}
+
+export const __test = { createWebSpeechTranscriptBuffer };
+
 export async function startTranscriptionCapture(
   mic?: {
     deviceId?: string | null;
@@ -84,7 +294,9 @@ export async function startTranscriptionCapture(
   } catch (err) {
     cleanup();
     console.warn("[clips-recorder] whisper transcript unavailable:", err);
-    return null;
+    return shouldUseBrowserTranscriptionFallback()
+      ? startBrowserTranscriptionCapture()
+      : null;
   }
 
   return {

package/corpus/templates/clips/desktop/src-tauri/src/lib.rs

@@ -113,6 +113,7 @@ pub fn run() {
             native_screen::native_fullscreen_recording_cancel,
             native_screen::native_fullscreen_recording_pause,
             native_screen::native_fullscreen_recording_resume,
+            native_screen::native_fullscreen_recording_rotate_segment,
             native_screen::native_fullscreen_pending_uploads,
             native_screen::native_fullscreen_recording_retry_upload,
             native_screen::native_fullscreen_recording_discard_upload,

package/corpus/templates/clips/desktop/src-tauri/src/native_screen.rs

@@ -129,6 +129,14 @@ struct NativeFullscreenSession {
     /// time when reporting `duration_ms`, so the upload metadata matches
     /// the actual recorded content rather than wall-clock time.
     paused_total: Duration,
+    /// Start time for the segment currently being captured. Used to subtract
+    /// unrecoverable segment time when ScreenCaptureKit fails finalization
+    /// but earlier segments are still playable.
+    current_segment_started_at: Instant,
+    /// Recorded time lost because a finalized segment was unusable and had to
+    /// be skipped during recovery.
+    lost_segment_duration: Duration,
+    lost_segment_count: u32,
     /// When the current pause began, if paused. Folded into `paused_total`
     /// on resume.
     paused_at: Option<Instant>,
@@ -723,7 +731,9 @@ pub async fn native_fullscreen_recording_begin(
         // Rebaseline the duration clock: the warm phase ran during the
         // countdown, so `started_at` (set at warm time) is several seconds
         // early. The clip's first written frame is now, so measure from now.
-        session.started_at = Instant::now();
+        let now = Instant::now();
+        session.started_at = now;
+        session.current_segment_started_at = now;
         session.pending_recording_output = false;
 
         Ok(NativeFullscreenStartInfo {
@@ -1057,6 +1067,7 @@ pub async fn native_fullscreen_recording_resume(
     session.backend = Some(backend);
     session.segments.push(segment_path);
     session.restart.segment_counter = next_counter;
+    session.current_segment_started_at = Instant::now();
     session.paused_total = session
         .paused_total
         .checked_add(paused_at.elapsed())
@@ -1065,6 +1076,106 @@ pub async fn native_fullscreen_recording_resume(
     Ok(())
 }
 
+/// Best-effort checkpoint for long ScreenCaptureKit recordings. It finalizes
+/// the current segment and immediately starts a sibling segment, so a later
+/// ReplayKit finalization failure can only lose the active segment instead of
+/// the entire recording.
+#[tauri::command]
+pub async fn native_fullscreen_recording_rotate_segment(
+    app: AppHandle,
+    state: State<'_, NativeFullscreenRecordingState>,
+) -> Result<(), String> {
+    #[cfg(not(target_os = "macos"))]
+    {
+        let _ = (app, state);
+        Ok(())
+    }
+
+    #[cfg(target_os = "macos")]
+    {
+        let mut guard = state.inner.lock().map_err(|e| e.to_string())?;
+        let Some(session) = guard.as_mut() else {
+            return Ok(());
+        };
+        if session.pending_recording_output || session.paused_at.is_some() {
+            return Ok(());
+        }
+        if !matches!(
+            session.backend.as_ref(),
+            Some(NativeFullscreenBackend::ScreenCaptureKit { .. })
+        ) {
+            return Ok(());
+        }
+
+        rotate_screencapturekit_segment(&app, session)
+    }
+}
+
+#[cfg(target_os = "macos")]
+fn rotate_screencapturekit_segment(
+    app: &AppHandle,
+    session: &mut NativeFullscreenSession,
+) -> Result<(), String> {
+    let restart = session.restart.clone();
+    let next_counter = restart.segment_counter.saturating_add(1);
+    let extension = native_extension_for_mime_type(session.mime_type);
+    let segment_path = segment_path_for(app, &restart.safe_id, extension, next_counter)?;
+    let _ = std::fs::remove_file(&segment_path);
+
+    if let Some(free) = free_disk_bytes(segment_path.parent().unwrap_or(&segment_path)) {
+        if free < DISK_SPACE_BLOCK_BYTES {
+            eprintln!(
+                "[clips-tray] skipping segment rotation because disk space is low: {} free",
+                format_mb(free)
+            );
+            return Ok(());
+        }
+    }
+
+    eprintln!(
+        "[clips-tray] rotating ScreenCaptureKit recording segment -> {}",
+        segment_path.display()
+    );
+    let rotation_started = Instant::now();
+    let stop_outcome = finalize_active_backend(session, true);
+    if let Err(err) = &stop_outcome {
+        eprintln!("[clips-tray] segment rotation finalize reported an error: {err}");
+    }
+    recover_from_unusable_current_segment(session, "segment rotation", true);
+
+    let start_result = start_screencapturekit_backend_at(
+        &segment_path,
+        restart.include_audio,
+        restart.capture_system_audio,
+        restart.mic_device_id.as_deref(),
+        restart.mic_device_label.as_deref(),
+        restart.target_display_id,
+        restart.capture_region,
+        false,
+    );
+
+    let (backend, _, _) = match start_result {
+        Ok(result) => result,
+        Err(err) => {
+            session.paused_at = Some(rotation_started);
+            return Err(format!(
+                "ScreenCaptureKit segment rotation paused recording after a finalized checkpoint, but the next segment could not start: {err}"
+            ));
+        }
+    };
+
+    session.paused_total = session
+        .paused_total
+        .checked_add(rotation_started.elapsed())
+        .unwrap_or(session.paused_total);
+    session.backend = Some(backend);
+    session.segments.push(segment_path);
+    session.restart.segment_counter = next_counter;
+    session.current_segment_started_at = Instant::now();
+    session.paused_at = None;
+    Ok(())
+}
+
 /// Outcome of taking the active session out of state and finalizing
 /// every backend / segment it owns. Both the upload and the save-locally
 /// stop commands need exactly this prelude, so it lives in one place.
@@ -1076,9 +1187,10 @@ struct StoppedSession {
     stop_outcome: Result<(), String>,
     /// Result of merging segment files into `session.path`.
     consolidate_outcome: Result<(), String>,
-    /// True when more than one segment was captured (i.e. the user
-    /// paused at least once). Used to decide whether a consolidation
-    /// failure is fatal — single-segment consolidation is just a rename.
+    /// True when more than one segment was captured (manual pause/resume or
+    /// automatic long-recording checkpoints). Used to decide whether a
+    /// consolidation failure is fatal — single-segment consolidation is just a
+    /// rename.
     multi_segment: bool,
 }
 
@@ -1105,6 +1217,7 @@ fn take_and_finalize_active_session(
     // playable. The caller persists recovery metadata so a finalize
     // failure doesn't orphan the file.
     let stop_outcome = finalize_active_backend(&mut session, true);
+    recover_from_unusable_current_segment(&mut session, "final stop", false);
     println!(
         "[clips-tray] finalize backend done (ok={}); {}",
         stop_outcome.is_ok(),
@@ -1124,10 +1237,18 @@ fn take_and_finalize_active_session(
         session.segments.len(),
         describe_recording_path(&session.path)
     );
+    if session.lost_segment_count > 0 {
+        eprintln!(
+            "[clips-tray] recovered recording by dropping {} unusable segment(s), approx {}s lost",
+            session.lost_segment_count,
+            session.lost_segment_duration.as_secs()
+        );
+    }
     let duration_ms = session
         .started_at
         .elapsed()
         .saturating_sub(session.paused_total)
+        .saturating_sub(session.lost_segment_duration)
         .as_millis();
     Ok(StoppedSession {
         session,
@@ -1150,6 +1271,52 @@ fn finalize_active_backend(
     stop_native_recording(&mut backend, wait_for_finalize)
 }
 
+fn playable_recording_file(path: &Path, mime_type: &str) -> bool {
+    match std::fs::metadata(path) {
+        Ok(metadata) if metadata.len() > 0 => {}
+        _ => return false,
+    }
+    if mime_type == MP4_RECORDING_MIME_TYPE || mime_type == QUICKTIME_RECORDING_MIME_TYPE {
+        return mp4_has_moov(path) != Some(false);
+    }
+    true
+}
+
+fn recover_from_unusable_current_segment(
+    session: &mut NativeFullscreenSession,
+    reason: &str,
+    allow_empty: bool,
+) -> bool {
+    let Some(current) = session.segments.last().cloned() else {
+        return false;
+    };
+    if playable_recording_file(&current, session.mime_type) {
+        return false;
+    }
+    if !allow_empty && session.segments.len() <= 1 {
+        eprintln!(
+            "[clips-tray] current recording segment is unusable after {reason}, but no earlier segment exists to recover"
+        );
+        return false;
+    }
+
+    let dropped = session.segments.pop();
+    if dropped.as_ref() == Some(&current) {
+        let _ = std::fs::remove_file(&current);
+        session.lost_segment_count = session.lost_segment_count.saturating_add(1);
+        session.lost_segment_duration = session
+            .lost_segment_duration
+            .checked_add(session.current_segment_started_at.elapsed())
+            .unwrap_or(session.lost_segment_duration);
+        eprintln!(
+            "[clips-tray] dropped unusable recording segment after {reason}; recovered {} earlier segment(s)",
+            session.segments.len()
+        );
+        return true;
+    }
+    false
+}
+
 /// Best-effort cleanup of a session being discarded (cancel, or a stale
 /// session displaced by a new start). Finalizes any active backend and
 /// deletes every on-disk artifact — segment files and the final path.
@@ -2243,15 +2410,19 @@ fn new_fullscreen_session(
     height: Option<u32>,
     restart: RestartInfo,
 ) -> NativeFullscreenSession {
+    let now = Instant::now();
     NativeFullscreenSession {
         backend: Some(backend),
         path: path.clone(),
         mime_type,
-        started_at: Instant::now(),
+        started_at: now,
         width,
         height,
         segments: vec![path],
         paused_total: Duration::ZERO,
+        current_segment_started_at: now,
+        lost_segment_duration: Duration::ZERO,
+        lost_segment_count: 0,
         paused_at: None,
         restart,
         pending_recording_output: false,

package/corpus/templates/clips/server/lib/public-agent-context.ts

@@ -455,6 +455,34 @@ function compactBugReport(report: PublicAgentBugReport) {
   };
 }
 
+export function transcriptStatusInstructions(
+  transcript: PublicAgentTranscript,
+) {
+  const status = transcript?.status ?? "missing";
+  const failureReason = transcript?.failureReason ?? "";
+  const lowerReason = failureReason.toLowerCase();
+
+  if (status === "pending") {
+    return [
+      "The transcript is still pending. For long recordings this can take several minutes; wait 15-30 seconds and fetch apis.context.url or apis.transcript.url again a few times before falling back to frames or telling the user no transcript exists.",
+    ];
+  }
+
+  if (status === "failed" && lowerReason.includes("credits exhausted")) {
+    return [
+      "Transcription failed because Builder transcription credits are exhausted. Tell the user to upgrade or connect Builder.io credits, or configure a Groq key for backup speech-to-text. Generic OpenAI or Anthropic chat keys do not transcribe Clips recordings.",
+    ];
+  }
+
+  if (status === "failed" && failureReason) {
+    return [
+      `Transcription failed with reason: ${failureReason}. Explain this to the user and suggest retrying transcription or configuring the supported Builder.io/Groq transcription fallback.`,
+    ];
+  }
+
+  return [];
+}
+
 export function buildPublicAgentContext({
   event,
   access,
@@ -496,6 +524,7 @@ export function buildPublicAgentContext({
       }));
   const instructions = [
     "Use transcript.segments for timestamped spoken context.",
+    ...transcriptStatusInstructions(transcript),
     ...(bugReport
       ? [
           "Use bugReport for the submitted product context: source URL, page title, app version, environment, severity, and redacted host metadata.",
@@ -559,6 +588,8 @@ export function buildPublicAgentContext({
     transcript: {
       status: transcript?.status ?? "missing",
       language: transcript?.language ?? null,
+      failureReason: transcript?.failureReason ?? null,
+      retryAfterSeconds: transcript?.status === "pending" ? 15 : null,
       fullText: transcript?.fullText ?? "",
       segments: agentSegments,
       segmentCount: agentSegments.length,