@agent-native/core 0.84.21 → 0.84.23

package/corpus/templates/chat/README.md

@@ -0,0 +1,32 @@
+# Chat
+
+The minimal agent-native starter app — a clean, ChatGPT-style shell with chat at
+the center, durable threads, standard app navigation, auth, live sync, and
+actions. Start here when you want a real browser app to build on without
+committing to a domain template.
+
+**Live app: [chat.agent-native.com](https://chat.agent-native.com)**
+
+Chat is the basic agent-native app starting point. It gives you the app-agent
+loop wired end to end and one example action, so you can add your own UI, data,
+and actions on top.
+
+## Features
+
+- ChatGPT-style shell with a threads list and durable chat history.
+- Auth, live sync, and application state wired out of the box.
+- The action surface the agent and UI share, plus one example action to copy.
+- A minimal, brandable base for any domain app.
+
+## Develop locally
+
+Scaffold your own copy and run it:
+
+```bash
+npx @agent-native/core@latest create my-app --standalone --template chat
+cd my-app
+pnpm install
+pnpm dev
+```
+
+Full docs: [agent-native.com/docs/template-chat](https://agent-native.com/docs/template-chat).

package/corpus/templates/clips/.agents/skills/frontend-design/SKILL.md

@@ -53,6 +53,8 @@ Default to Apple/Linear-level restraint: make the primary workflow obvious, then
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
 
+**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
+
 ## Agent-Native UI Rules
 
 - Agent-native apps use React, Vite, Tailwind CSS, shadcn/ui, and `@tabler/icons-react`.

package/corpus/templates/clips/.agents/skills/recording/SKILL.md

@@ -31,9 +31,38 @@ Some recordings are linked to a meeting — when `meeting_id` is non-null on the
 4. **Record.** Start a `MediaRecorder` with `mimeType: "video/webm;codecs=vp9,opus"` (fallback to vp8, then browser default). Use `timeslice: 2000` so chunks arrive every 2s.
 5. **Upload each chunk.** `ondataavailable` POSTs the chunk bytes to `/api/uploads/chunk` with headers `X-Recording-Id` and `X-Chunk-Index`. Don't retry inline — buffer failed chunks in `IndexedDB` and let a background worker re-send.
 6. **Live transcription.** Alongside the MediaRecorder, `useLiveTranscription` runs the Web Speech API to accumulate transcript text in real time. On stop, the client calls `save-browser-transcript` to persist the result immediately — no API key needed. Desktop recordings use local Whisper/macOS speech first when available, and fall back to Web Speech in the webview on non-mac before relying on upload transcription.
-7. **Finalize.** On stop, send the final chunk to `/api/uploads/:id/chunk?isFinal=1`. The route calls `finalize-recording`, which stitches chunks, uploads the finished media when storage is configured, transitions `status` to `ready`, then kicks off `request-transcript` for higher-quality output (see `ai-video-tools`).
+7. **Finalize.** On stop, send the final chunk to `/api/uploads/:id/chunk?isFinal=1`. The route calls `finalize-recording`, which stitches chunks, makes the media seekable (see below), uploads the finished media when storage is configured, transitions `status` to `ready`, then kicks off `request-transcript` for higher-quality output (see `ai-video-tools`).
 8. **Navigate.** Once the row is `ready` the UI navigates to `/r/:id`.
 
+## Seekable playback (don't ship raw MediaRecorder output)
+
+Raw `MediaRecorder` files are not friendly to progressive HTTP playback, which
+shows up as "clip takes minutes to load" and "re-buffers every time I seek"
+even though the file downloads fine:
+
+- **MP4** is written with the `moov` metadata atom *after* `mdat`, so a player
+  must fetch the whole file before it can start or seek.
+- **WebM** is a live stream with no Cues (seek index) and an unknown Segment
+  duration, so Chrome won't honor `currentTime = X` and has to scan/download.
+
+`finalize-recording` fixes this before upload: MP4 gets pure-TS faststart
+(`server/lib/faststart.ts`), WebM gets a lossless `ffmpeg -c copy` remux that
+writes a SeekHead + Cues + real duration (`server/lib/video-remux.ts`). Both are
+best-effort — on failure we upload the original, never block finalize. Recordings
+above `CLIPS_INLINE_REMUX_MAX_BYTES` (default 200 MB) skip the inline pass and
+are repaired in the background.
+
+The **streaming/resumable** upload path forwards raw bytes straight to the
+provider and cannot rewrite them inline, so `finalize-recording` schedules a
+background `ensureRecordingSeekable` pass for those.
+
+To repair clips uploaded before this existed (or via streaming), call the
+`reprocess-recording` action: `--id`, `--ids='[...]'`, or `--all --limit=N`. It
+re-fetches provider media, rewrites it, re-uploads, and repoints the row. It's
+idempotent (already-seekable clips are skipped unless `--force`) and only touches
+provider-hosted clips owned by the caller. This is the right tool when a user
+reports a specific slow/buffering clip.
+
 ## Loom import
 
 Use `import-loom-recording` for Loom share or embed URLs. The action validates

package/corpus/templates/clips/README.md

@@ -0,0 +1,37 @@
+# Clips
+
+An open-source, agent-native alternative to Loom, Granola, and Wispr Flow rolled
+into one app. Screen recording, calendar-synced meeting notes, and push-to-talk
+voice dictation — all transcribed, searchable, and yours to own.
+
+**Live app: [clips.agent-native.com](https://clips.agent-native.com)**
+
+The agent transcribes, titles, summarizes, and indexes everything you capture,
+then lets you ask "find the clip where we discussed the rollout plan" across every
+transcript. Shared clips are agent-readable: paste a share link into an agent and
+it can read the transcript and see timestamped frames without the raw video.
+
+## Features
+
+- Screen recording with webcam overlay, audio capture, and pause/trim.
+- Calendar-synced meeting recordings with AI summary, notes, and action items.
+- Push-to-talk (Fn-hold) dictation with searchable history and vocabulary biasing.
+- Auto-generated titles, summaries, and chapter markers for every recording.
+- Full-text search across recordings, meetings, and dictations in one library.
+- Sharing with per-clip permissions, agent-readable links, and Slack unfurls.
+- Chrome extension for capturing browser logs with a recording.
+
+## Develop locally
+
+Scaffold your own copy and run it:
+
+```bash
+npx @agent-native/core@latest create my-clips --standalone --template clips
+cd my-clips
+pnpm install
+pnpm dev
+```
+
+Clips needs a video storage backend (Builder.io or an S3-compatible bucket)
+before recordings can upload — see the docs for setup.
+Full docs: [agent-native.com/docs/template-clips](https://agent-native.com/docs/template-clips).

package/corpus/templates/clips/actions/finalize-recording.ts

@@ -40,12 +40,27 @@ import {
   getResumableSession,
 } from "../server/lib/resumable-session.js";
 import { isStreamingUploadDisabled } from "../server/lib/streaming-upload-mode.js";
+import { remuxWebmToSeekable } from "../server/lib/video-remux.js";
 import {
   requiresConfiguredVideoStorage,
   STORAGE_SETUP_REQUIRED_REASON,
 } from "../server/lib/video-storage.js";
+import {
+  ensureRecordingSeekable,
+  markRecordingSeekable,
+} from "./lib/ensure-seekable-video.js";
 import requestTranscript from "./request-transcript.js";
 
+// Recordings up to this size get their seekable rewrite applied inline during
+// finalize (we already hold the assembled bytes). Larger recordings are handed
+// off to the background/reprocess path so we don't stretch the finalize
+// request or exhaust serverless /tmp. Override with CLIPS_INLINE_REMUX_MAX_BYTES.
+function inlineRemuxMaxBytes(): number {
+  const raw = Number(process.env.CLIPS_INLINE_REMUX_MAX_BYTES ?? "");
+  if (Number.isFinite(raw) && raw > 0) return Math.floor(raw);
+  return 200 * 1024 * 1024;
+}
+
 /**
  * Decode a base64 string back into a Uint8Array.
  * We store chunks as base64 in application_state because the SQL JSON
@@ -118,6 +133,10 @@ async function markRecordingReady(params: {
   finalHasAudio: boolean;
   finalHasCamera: boolean;
   existingTitle: string;
+  // Whether a seekable rewrite (MP4 faststart / WebM Cues remux) was already
+  // applied to the uploaded bytes. When false, a best-effort background repair
+  // is triggered so streamed/raw uploads still become seekable.
+  seekableApplied: boolean;
 }) {
   const {
     id,
@@ -131,6 +150,7 @@ async function markRecordingReady(params: {
     finalHasAudio,
     finalHasCamera,
     existingTitle,
+    seekableApplied,
   } = params;
   const db = getDb();
   const now = new Date().toISOString();
@@ -181,6 +201,30 @@ async function markRecordingReady(params: {
   });
   await writeAppState("refresh-signal", { ts: Date.now() });
 
+  if (seekableApplied) {
+    // Uploaded bytes are already start-playable and seekable — remember it so
+    // later reprocess sweeps skip this clip.
+    await markRecordingSeekable(id, videoUrl).catch((err) => {
+      console.warn("[finalize] failed to write seekable marker", {
+        id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+  } else {
+    // Streaming/resumable (or oversized) uploads shipped raw MediaRecorder
+    // bytes with no seekable rewrite: an MP4 with a trailing moov or a WebM
+    // without a Cues index buffers on load and re-buffers on every seek. Fix
+    // it in the background so playback is smooth without blocking finalize.
+    void Promise.resolve(
+      ensureRecordingSeekable({ recordingId: id, ownerEmail }),
+    ).catch((err: unknown) => {
+      console.warn("[finalize] background seekable remux failed", {
+        id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+  }
+
   // Kick off transcription in the background — fire-and-forget so the chunk
   // endpoint gets a quick response. The request context (user email via
   // AsyncLocalStorage) carries through to async continuations.
@@ -375,6 +419,10 @@ export default defineAction({
             ...readyParams,
             videoUrl,
             videoSizeBytes: resumableSession.bytesUploaded,
+            // Streaming path forwards raw MediaRecorder bytes straight to the
+            // provider — no faststart/Cues rewrite happened. Repair in the
+            // background.
+            seekableApplied: false,
           });
           // Delete only after durable state is written — so a retry before
           // this point can still find the session and re-enter this path.
@@ -521,9 +569,14 @@ export default defineAction({
       // recordings.
       parts.length = 0;
 
-      // Apply faststart to MP4 files — moves the moov atom before mdat so
-      // browsers can begin playback immediately via HTTP range requests.
+      // Make the assembled recording seekable before upload — we already hold
+      // the full bytes, so a viewer never has to wait through a non-seekable
+      // first play. MP4: relocate moov ahead of mdat (pure TS). WebM: remux to
+      // add a Cues index + real duration (ffmpeg -c copy). When neither runs
+      // (unknown format, oversized, or ffmpeg unavailable) `seekableApplied`
+      // stays false and markRecordingReady schedules a background repair.
       let uploadData = assembled;
+      let seekableApplied = false;
       if (videoFormat === "mp4") {
         try {
           uploadData = applyFaststart(assembled);
@@ -561,6 +614,32 @@ export default defineAction({
           }
           throw err;
         }
+        // moov is present and validated — the MP4 is start-playable/seekable.
+        seekableApplied = true;
+      } else if (videoFormat === "webm") {
+        // MediaRecorder WebM has no Cues index and an unknown duration, so
+        // Chrome buffers on load and re-buffers on every seek. A lossless
+        // `ffmpeg -c copy` remux rewrites it with a SeekHead + Cues + real
+        // duration. Bounded by size so finalize stays fast; larger clips get a
+        // background pass. Best-effort: on any failure we upload the original.
+        if (assembled.byteLength <= inlineRemuxMaxBytes()) {
+          try {
+            const seekable = await remuxWebmToSeekable(uploadData);
+            if (seekable.changed) {
+              uploadData = seekable.bytes;
+              seekableApplied = true;
+              debugLog("[finalize] webm remux applied", {
+                id,
+                bytes: uploadData.byteLength,
+              });
+            }
+          } catch (err) {
+            console.warn("[finalize] webm remux failed, uploading as-is", {
+              id,
+              err: err instanceof Error ? err.message : String(err),
+            });
+          }
+        }
       }
 
       let upload: Awaited<ReturnType<typeof uploadFile>>;
@@ -721,12 +800,13 @@ export default defineAction({
       debugLog("[finalize] done", {
         id,
         videoUrl: upload.url,
-        bytes: assembled.byteLength,
+        bytes: uploadData.byteLength,
       });
       return markRecordingReady({
         ...readyParams,
         videoUrl: upload.url,
-        videoSizeBytes: assembled.byteLength,
+        videoSizeBytes: uploadData.byteLength,
+        seekableApplied,
       });
     } finally {
       // Unconditional chunk scratch-space cleanup. Runs on success AND on

package/corpus/templates/clips/actions/lib/ensure-seekable-video.ts

@@ -0,0 +1,256 @@
+/**
+ * Repair an already-stored recording so it plays back and seeks instantly.
+ *
+ * This is the fetch-based counterpart to the inline seekable pass in
+ * `finalize-recording`. It re-fetches a recording's stored provider media,
+ * runs the format-appropriate seekable rewrite (MP4 faststart / WebM Cues
+ * remux), and, when that changed the bytes, re-uploads the fixed file and
+ * repoints the recording at it.
+ *
+ * Used by:
+ *   - `reprocess-recording` — owner/agent triggered backfill of clips that were
+ *     uploaded before the seekable pass existed (or via the streaming path,
+ *     which never applied it).
+ *   - `finalize-recording` — a best-effort background pass for the resumable
+ *     streaming path, whose bytes live at the provider and were never buffered
+ *     server-side for an inline rewrite.
+ *
+ * Everything is best-effort and non-destructive: if we can't fetch, can't
+ * improve, or can't re-upload, the existing recording is left exactly as-is.
+ */
+
+import {
+  readAppState,
+  writeAppState,
+} from "@agent-native/core/application-state";
+import { uploadFile } from "@agent-native/core/file-upload";
+import { MAX_UPLOAD_BYTES } from "@shared/upload-limits.js";
+import { and, eq } from "drizzle-orm";
+
+import { getDb, schema } from "../../server/db/index.js";
+import { ownerEmailMatches } from "../../server/lib/recordings.js";
+import {
+  makeSeekable,
+  type VideoFormat,
+} from "../../server/lib/video-remux.js";
+import { isLoomRecordingSource } from "../../shared/loom.js";
+
+const PROVIDER_FETCH_TIMEOUT_MS = 60_000;
+
+export type EnsureSeekableStatus =
+  | "optimized"
+  | "already-optimized"
+  | "skipped-not-ready"
+  | "skipped-no-media"
+  | "skipped-local-media"
+  | "skipped-too-large"
+  | "skipped-fetch-failed"
+  | "skipped-upload-failed"
+  | "not-found";
+
+export interface EnsureSeekableResult {
+  recordingId: string;
+  status: EnsureSeekableStatus;
+  changed: boolean;
+  videoUrl?: string | null;
+  detail?: string;
+}
+
+/** application_state key marking a recording's media as already made seekable. */
+export function seekableMarkerKey(recordingId: string): string {
+  return `recording-seekable-${recordingId}`;
+}
+
+/**
+ * Record that `videoUrl` for `recordingId` has been made seekable, so later
+ * sweeps skip it. Scoped by URL so a re-upload that changes the URL is not
+ * mistaken for already-processed.
+ */
+export async function markRecordingSeekable(
+  recordingId: string,
+  videoUrl: string | null | undefined,
+): Promise<void> {
+  await writeAppState(seekableMarkerKey(recordingId), {
+    recordingId,
+    videoUrl: videoUrl ?? null,
+    at: new Date().toISOString(),
+  });
+}
+
+async function isAlreadyMarked(
+  recordingId: string,
+  videoUrl: string | null,
+): Promise<boolean> {
+  const marker = await readAppState(seekableMarkerKey(recordingId)).catch(
+    () => null,
+  );
+  return Boolean(
+    marker &&
+    typeof marker === "object" &&
+    (marker as { videoUrl?: unknown }).videoUrl === videoUrl,
+  );
+}
+
+function isRemoteProviderUrl(videoUrl: string | null | undefined): boolean {
+  return typeof videoUrl === "string" && /^https:\/\//i.test(videoUrl.trim());
+}
+
+async function fetchProviderBytes(
+  videoUrl: string,
+): Promise<
+  { ok: true; bytes: Uint8Array } | { ok: false; reason: EnsureSeekableStatus }
+> {
+  const controller = new AbortController();
+  const timeout = setTimeout(
+    () => controller.abort(),
+    PROVIDER_FETCH_TIMEOUT_MS,
+  );
+  try {
+    const res = await fetch(videoUrl, { signal: controller.signal });
+    if (!res.ok) return { ok: false, reason: "skipped-fetch-failed" };
+
+    const declaredLength = Number(res.headers.get("content-length") ?? "0");
+    if (Number.isFinite(declaredLength) && declaredLength > MAX_UPLOAD_BYTES) {
+      return { ok: false, reason: "skipped-too-large" };
+    }
+
+    const buf = new Uint8Array(await res.arrayBuffer());
+    if (buf.byteLength === 0)
+      return { ok: false, reason: "skipped-fetch-failed" };
+    if (buf.byteLength > MAX_UPLOAD_BYTES) {
+      return { ok: false, reason: "skipped-too-large" };
+    }
+    return { ok: true, bytes: buf };
+  } catch {
+    return { ok: false, reason: "skipped-fetch-failed" };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/**
+ * Ensure a single recording's stored media is seekable. Owner-scoped: pass the
+ * resolved owner email so the DB lookup can only touch that owner's rows.
+ */
+export async function ensureRecordingSeekable(params: {
+  recordingId: string;
+  ownerEmail: string;
+  force?: boolean;
+}): Promise<EnsureSeekableResult> {
+  const { recordingId, ownerEmail, force = false } = params;
+  const db = getDb();
+
+  const [rec] = await db
+    .select({
+      id: schema.recordings.id,
+      status: schema.recordings.status,
+      videoUrl: schema.recordings.videoUrl,
+      videoFormat: schema.recordings.videoFormat,
+      sourceAppName: schema.recordings.sourceAppName,
+    })
+    .from(schema.recordings)
+    .where(
+      and(
+        eq(schema.recordings.id, recordingId),
+        ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+      ),
+    );
+
+  if (!rec) {
+    return { recordingId, status: "not-found", changed: false };
+  }
+  if (rec.status !== "ready") {
+    return { recordingId, status: "skipped-not-ready", changed: false };
+  }
+  if (isLoomRecordingSource(rec)) {
+    return { recordingId, status: "skipped-local-media", changed: false };
+  }
+  if (!rec.videoUrl) {
+    return { recordingId, status: "skipped-no-media", changed: false };
+  }
+  // Only provider-hosted media can be re-fetched and re-uploaded. Local/dev
+  // blobs (served from application_state via /api/video) and other relative
+  // URLs are left untouched.
+  if (!isRemoteProviderUrl(rec.videoUrl)) {
+    return {
+      recordingId,
+      status: "skipped-local-media",
+      changed: false,
+      videoUrl: rec.videoUrl,
+    };
+  }
+
+  if (!force && (await isAlreadyMarked(recordingId, rec.videoUrl))) {
+    return {
+      recordingId,
+      status: "already-optimized",
+      changed: false,
+      videoUrl: rec.videoUrl,
+    };
+  }
+
+  const fetched = await fetchProviderBytes(rec.videoUrl);
+  if (!fetched.ok) {
+    return { recordingId, status: fetched.reason, changed: false };
+  }
+
+  const videoFormat: VideoFormat = rec.videoFormat === "mp4" ? "mp4" : "webm";
+  const seekable = await makeSeekable({
+    mediaBytes: fetched.bytes,
+    videoFormat,
+  });
+
+  if (!seekable.changed) {
+    // Already seekable (or unimprovable) — remember so we don't refetch it.
+    await markRecordingSeekable(recordingId, rec.videoUrl);
+    return {
+      recordingId,
+      status: "already-optimized",
+      changed: false,
+      videoUrl: rec.videoUrl,
+    };
+  }
+
+  const mimeType = videoFormat === "mp4" ? "video/mp4" : "video/webm";
+  const upload = await uploadFile({
+    data: seekable.bytes,
+    filename: `${recordingId}.${videoFormat}`,
+    mimeType,
+    ownerEmail,
+    skipCompressionWait: true,
+  });
+
+  if (!upload?.url) {
+    // Could not re-upload — do NOT touch the row; the original still plays.
+    return {
+      recordingId,
+      status: "skipped-upload-failed",
+      changed: false,
+      videoUrl: rec.videoUrl,
+    };
+  }
+
+  await db
+    .update(schema.recordings)
+    .set({
+      videoUrl: upload.url,
+      videoSizeBytes: seekable.bytes.byteLength,
+      updatedAt: new Date().toISOString(),
+    })
+    .where(
+      and(
+        eq(schema.recordings.id, recordingId),
+        ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+      ),
+    );
+
+  await markRecordingSeekable(recordingId, upload.url);
+  await writeAppState("refresh-signal", { ts: Date.now() });
+
+  return {
+    recordingId,
+    status: "optimized",
+    changed: true,
+    videoUrl: upload.url,
+  };
+}

package/corpus/templates/clips/actions/reprocess-recording.ts

@@ -0,0 +1,160 @@
+/**
+ * Repair the playback of already-stored recordings.
+ *
+ * Clips uploaded via the streaming path (or before the seekable rewrite
+ * existed) can ship raw MediaRecorder output: an MP4 with a trailing `moov`
+ * atom or a WebM with no Cues index. Those load slowly and re-buffer on every
+ * seek even though the file downloads fine. This action re-fetches the stored
+ * media, rewrites it to be start-playable and seekable (MP4 faststart / WebM
+ * Cues remux), re-uploads the fixed file, and repoints the recording at it.
+ *
+ * It's idempotent and non-destructive: clips that are already seekable are
+ * skipped, and any clip we can't improve or re-upload is left untouched.
+ *
+ * Usage:
+ *   pnpm action reprocess-recording --id=<recordingId>
+ *   pnpm action reprocess-recording --ids='["id1","id2"]'
+ *   pnpm action reprocess-recording --all --limit=20
+ *   pnpm action reprocess-recording --id=<recordingId> --force
+ */
+
+import { defineAction } from "@agent-native/core";
+import { and, desc, eq, isNotNull } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  getCurrentOwnerEmail,
+  ownerEmailMatches,
+} from "../server/lib/recordings.js";
+import {
+  ensureRecordingSeekable,
+  type EnsureSeekableResult,
+} from "./lib/ensure-seekable-video.js";
+
+const MAX_TARGETS_PER_CALL = 100;
+const DEFAULT_ALL_LIMIT = 20;
+
+function parseIds(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((v): v is string => typeof v === "string" && !!v);
+  }
+  if (typeof value === "string" && value.trim()) {
+    try {
+      const parsed = JSON.parse(value);
+      if (Array.isArray(parsed)) {
+        return parsed.filter((v): v is string => typeof v === "string" && !!v);
+      }
+    } catch {
+      // Fall back to a single comma-separated / plain id string.
+      return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    }
+  }
+  return [];
+}
+
+export default defineAction({
+  description:
+    "Repair slow-loading or buffering recordings by rewriting their stored video to be start-playable and seekable (MP4 faststart / WebM Cues remux) and re-uploading it. Use for clips that take a long time to load or re-buffer when scrubbing. Pass `id` for one clip, `ids` for several, or `all: true` to sweep the caller's ready clips (bounded by `limit`). Already-seekable clips are skipped unless `force` is true.",
+  schema: z.object({
+    id: z.string().optional().describe("A single recording id to repair."),
+    ids: z
+      .union([z.array(z.string()), z.string()])
+      .optional()
+      .describe(
+        "Multiple recording ids (array, or JSON/comma string for CLI).",
+      ),
+    all: z.coerce
+      .boolean()
+      .optional()
+      .describe(
+        "Repair the caller's own ready clips, most recent first, up to `limit`.",
+      ),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_TARGETS_PER_CALL)
+      .optional()
+      .describe(
+        `Max clips to process when using \`all\` (default ${DEFAULT_ALL_LIMIT}).`,
+      ),
+    force: z.coerce
+      .boolean()
+      .optional()
+      .describe("Re-run even on clips already marked seekable."),
+  }),
+  run: async (args) => {
+    const db = getDb();
+    const ownerEmail = getCurrentOwnerEmail();
+    const force = Boolean(args.force);
+
+    let targetIds: string[] = [];
+    if (args.id) targetIds.push(args.id);
+    targetIds.push(...parseIds(args.ids));
+
+    if (args.all) {
+      const limit = args.limit ?? DEFAULT_ALL_LIMIT;
+      const rows = await db
+        .select({ id: schema.recordings.id })
+        .from(schema.recordings)
+        .where(
+          and(
+            ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+            eq(schema.recordings.status, "ready"),
+            isNotNull(schema.recordings.videoUrl),
+          ),
+        )
+        .orderBy(desc(schema.recordings.createdAt))
+        .limit(limit);
+      targetIds.push(...rows.map((r) => r.id));
+    }
+
+    // De-dupe while preserving order, and bound the batch so a single call
+    // can't run unboundedly under the hosted foreground budget.
+    targetIds = Array.from(new Set(targetIds)).slice(0, MAX_TARGETS_PER_CALL);
+
+    if (targetIds.length === 0) {
+      return {
+        ok: true,
+        processed: 0,
+        changed: 0,
+        results: [] as EnsureSeekableResult[],
+        message:
+          "No recordings to reprocess. Pass id / ids, or all: true to sweep your clips.",
+      };
+    }
+
+    const results: EnsureSeekableResult[] = [];
+    for (const recordingId of targetIds) {
+      try {
+        results.push(
+          await ensureRecordingSeekable({ recordingId, ownerEmail, force }),
+        );
+      } catch (err) {
+        console.warn("[reprocess-recording] failed for", recordingId, err);
+        results.push({
+          recordingId,
+          status: "skipped-fetch-failed",
+          changed: false,
+          detail: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    const changed = results.filter((r) => r.changed).length;
+    console.log(
+      `Reprocessed ${results.length} recording(s); ${changed} rewritten for smoother playback.`,
+    );
+
+    return {
+      ok: true,
+      processed: results.length,
+      changed,
+      results,
+    };
+  },
+});