@minicor/mcp-server 4.1.0 → 4.2.0

package/README.md

@@ -270,7 +270,7 @@ After all steps pass individually:
 
 Then close the loop at the job level:
 
-- Point the job's workflow step at the finished `workflowId` (`update_job variant=draft`). If the workflow was edited in Dev Mode, `dev_mode_publish` first - jobs execute published workflows, not Dev Mode branches.
+- Point the job's workflow step at the finished `workflowId` (`update_job variant=draft`). If the workflow was edited in Dev Mode, `dev_mode_publish` first - jobs execute published workflows, not drafts.
 - `run_tests variant=draft` - the test cases from Phase 3 are the pass/fail verdict for the build
 - On a red case, `resolve_job_state` / `inspect_job_execution` locate the failing step; replay just that slice with `run_job` (`fromStepId` + `seedExecutionId`) or drop back into the workflow, fix, re-run
 - When the suite is green, `publish_job` puts it live at `/m/:slug/:path`
@@ -345,7 +345,7 @@ You work **backwards from the job's test cases**. The job's test suite is the ma
                       seedExecutionId=<failed execution>  (seeds ctx so mid-graph starts
                       resolve earlier steps' values).
    5b. Workflow-level (microscope) - the failing step's workflowId -> dev_mode_load,
-                      fix/run the branch's flow steps with dev_mode_run,
+                      fix/run the draft's flow steps (dev_mode_run needs vmId),
                       dev_mode_publish - jobs execute PUBLISHED workflows.
 6. PUBLISH          - when run_tests variant=draft is green, publish_job promotes the draft;
                       runtime traffic at /m/:slug serves it immediately.
@@ -686,6 +686,12 @@ Jobs/middleware base resolution (precedence: **proxy > direct > default**):
 | `MIDDLEWARE_SERVICE_URL_US`       | Direct middleware-service base for US (overrides the generic one)   | unset                  |
 | `MIDDLEWARE_SERVICE_URL_CA`       | Direct middleware-service base for CA (overrides the generic one)   | unset                  |
 | `EXPERIMENTAL_USE_CODE_MODE`      | Expose the experimental single `codemode` tool surface              | unset (standard tools) |
+| `SEEER_SERVICE_PROXY_BASE`        | Frontend origin fronting the video-tool proxy (auth = user bearer, like the agents/stitchy proxies) | unset                  |
+| `SEEER_SERVICE_PROXY_PREFIX`      | video-tool proxy path prefix                                         | `/api/video-tool`      |
+| `SEEER_SERVICE_URL`               | Direct video-tool service URL (enables `analyze_recording` / `annotate_recording` / `get_recording_event`; frame tools route through it) | unset (local ffmpeg)   |
+| `SEEER_SERVICE_TOKEN`             | App token for direct mode (sent as X-API-Key)                        | unset                  |
+| `SEEER_SERVICE_ID_TOKEN`          | Static Google identity token for IAM-gated Cloud Run (local testing) | unset                  |
+| `SEEER_SERVICE_USE_GCP_IDENTITY`  | Set to 1 to mint identity tokens from the GCP metadata server        | unset                  |
 
 When none are set, Jobs calls the region's public middleware-service Cloud Run directly. To route through the frontend (once it deploys an `/api/middleware/[...path]` proxy), set `MIDDLEWARE_SERVICE_PROXY_BASE` (or the per-region variants).
 

package/dist/__tests__/recording-frames.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { computeSampleTimestamps, buildScaleFilter, runCommand, } from "../recording-frames.js";
+import { computeSampleTimestamps, computeRangeTimestamps, buildScaleFilter, buildCropFilter, cacheKeyForUrl, runCommand, } from "../recording-frames.js";
 describe("computeSampleTimestamps", () => {
     it("returns evenly-spaced, centered timestamps within the duration", () => {
         expect(computeSampleTimestamps(10, 4)).toEqual([1.25, 3.75, 6.25, 8.75]);
@@ -22,6 +22,47 @@ describe("computeSampleTimestamps", () => {
         expect(computeSampleTimestamps(Number.NaN, 4)).toEqual([]);
     });
 });
+describe("computeRangeTimestamps", () => {
+    it("samples the window at the requested fps, inclusive of both ends", () => {
+        expect(computeRangeTimestamps(10, 14, 1, 16)).toEqual([10, 11, 12, 13, 14]);
+    });
+    it("falls back to even spacing when fps would exceed maxFrames", () => {
+        const ts = computeRangeTimestamps(0, 30, 2, 4);
+        expect(ts).toHaveLength(4);
+        expect(ts[0]).toBe(0);
+        expect(ts[3]).toBe(30);
+    });
+    it("returns a single frame for a zero-ish span with n=1", () => {
+        expect(computeRangeTimestamps(5, 5.4, 1, 16)).toEqual([5]);
+    });
+    it("returns empty for invalid input", () => {
+        expect(computeRangeTimestamps(10, 5, 1, 16)).toEqual([]);
+        expect(computeRangeTimestamps(0, 10, 0, 16)).toEqual([]);
+        expect(computeRangeTimestamps(0, 10, 1, 0)).toEqual([]);
+        expect(computeRangeTimestamps(Number.NaN, 10, 1, 16)).toEqual([]);
+    });
+});
+describe("buildCropFilter", () => {
+    it("builds a crop for the region with padding", () => {
+        expect(buildCropFilter({ x: 100, y: 50, width: 200, height: 100, pad: 10 })).toBe("crop=220:120:90:40");
+    });
+    it("clamps to video bounds", () => {
+        expect(buildCropFilter({ x: -20, y: -20, width: 3000, height: 2000 }, 2560, 1440)).toBe("crop=2560:1440:0:0");
+    });
+    it("returns null when the region is entirely outside the video", () => {
+        expect(buildCropFilter({ x: 5000, y: 5000, width: 100, height: 100 }, 2560, 1440)).toBeNull();
+    });
+});
+describe("cacheKeyForUrl", () => {
+    it("ignores the SAS query so re-minted URLs share a cache entry", () => {
+        const a = cacheKeyForUrl("https://acct.blob.core.windows.net/replay/rpa_1_2.mp4?sig=abc&se=2026");
+        const b = cacheKeyForUrl("https://acct.blob.core.windows.net/replay/rpa_1_2.mp4?sig=zzz&se=2027");
+        expect(a).toBe(b);
+    });
+    it("differs for different blobs", () => {
+        expect(cacheKeyForUrl("https://acct.blob.core.windows.net/replay/rpa_1_2.mp4")).not.toBe(cacheKeyForUrl("https://acct.blob.core.windows.net/replay/rpa_1_3.mp4"));
+    });
+});
 describe("runCommand", () => {
     it("resolves on a zero exit code", async () => {
         const result = await runCommand(process.execPath, ["-e", "process.stdout.write('hi')"], 10_000);

package/dist/__tests__/recording-frames.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"recording-frames.test.js","sourceRoot":"","sources":["../../src/__tests__/recording-frames.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"recording-frames.test.js","sourceRoot":"","sources":["../../src/__tests__/recording-frames.test.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -153,7 +153,7 @@ async function unsetStoredApiBase(region) {
 }
 const codeModeEnabled = shouldUseCodeMode();
 const instructions = buildInstructions(true);
-const server = new McpServer({ name: SERVER_NAME, version: "4.0.0" }, {
+const server = new McpServer({ name: SERVER_NAME, version: "4.2.0" }, {
     instructions: codeModeEnabled
         ? buildCodeModeInstructions(instructions, { sessionLifecycle: true })
         : instructions,

package/dist/lib.js

@@ -60,7 +60,7 @@ export async function createMinicorServer(transport, opts = {}) {
     const localTools = opts.localTools ?? true;
     const codeModeEnabled = opts.codeMode ?? shouldUseCodeMode();
     const instructions = buildInstructions(localTools);
-    const server = new McpServer({ name: SERVER_NAME, version: "4.0.0" }, {
+    const server = new McpServer({ name: SERVER_NAME, version: "4.2.0" }, {
         instructions: codeModeEnabled
             ? buildCodeModeInstructions(instructions, {
                 sessionLifecycle: localTools,

package/dist/recording-frames.d.ts

@@ -1,12 +1,22 @@
 /**
- * Extracts sampled still frames from a recording (MP4) so that a vision-capable
- * model can visually verify or debug an execution.
+ * Extracts still frames from a recording (MP4) so that a vision-capable model
+ * can visually verify or debug an execution.
  *
  * The recording endpoints return a signed URL to an MP4. A model cannot "watch"
- * a video URL, so this module downloads the video and uses ffmpeg to sample a
- * handful of frames, returned as base64 JPEGs. ffmpeg (and ideally ffprobe) must
- * be available on the MCP host; when they are missing we throw a clear error so
- * the caller can fall back to handing the raw URL to a human.
+ * a video URL, so this module downloads the video and uses ffmpeg to extract
+ * frames, returned as base64 JPEGs. Supports:
+ *   - evenly-spaced sampling across the whole video (default)
+ *   - exact timestamps ("show me t=41.5s")
+ *   - dense sampling of a time range ("what happened between t=30s and t=45s")
+ *   - region cropping at the recording's native resolution ("zoom in here")
+ *
+ * Downloads are cached under ~/.minicor/cache/recordings keyed on the blob
+ * identity (URL minus the SAS query), so successive calls against the same
+ * recording skip the download entirely.
+ *
+ * ffmpeg (and ideally ffprobe) must be available on the MCP host; when they are
+ * missing we throw a clear error so the caller can fall back to handing the raw
+ * URL to a human.
  */
 export interface ExtractedFrame {
     /** Human-readable label, e.g. "t=12.3s" or "frame 2". */
@@ -16,15 +26,49 @@ export interface ExtractedFrame {
     /** Base64-encoded JPEG (no data: prefix). */
     base64: string;
 }
+export interface FrameRegion {
+    /** Left edge in native video pixels. */
+    x: number;
+    /** Top edge in native video pixels. */
+    y: number;
+    width: number;
+    height: number;
+    /** Extra context padding around the region, in pixels. Default 0. */
+    pad?: number;
+}
+export interface FrameRange {
+    /** Window start in seconds. */
+    start: number;
+    /** Window end in seconds. */
+    end: number;
+    /** Sampling rate within the window. Default 1 fps. */
+    fps?: number;
+}
 export interface ExtractFramesOptions {
-    /** Number of evenly-spaced frames to sample. Default 4. */
+    /**
+     * Number of evenly-spaced frames to sample. Default 4. Ignored when
+     * `timestamps` or `range` is provided.
+     */
     count?: number;
+    /** Exact timestamps (seconds) to extract. Takes precedence over `range`/`count`. */
+    timestamps?: number[];
+    /** Dense sampling of a time window. Takes precedence over `count`. */
+    range?: FrameRange;
+    /** Safety cap on total frames for timestamps/range modes. Default 16. */
+    maxFrames?: number;
+    /**
+     * Crop to this region at the recording's NATIVE resolution before any
+     * scaling — the way to keep small on-screen text readable.
+     */
+    region?: FrameRegion;
     /**
      * Optional max output width in px. When omitted (the default) frames keep the
      * recording's ORIGINAL resolution — important for reading fine on-screen detail.
      * Only set this if you explicitly want to trade resolution for smaller frames.
      */
     maxWidth?: number;
+    /** Use the on-disk download cache. Default true. */
+    cache?: boolean;
     /** Max bytes to download before aborting. Default 200 MB. */
     maxBytes?: number;
     /** Overall download timeout in ms. Default 60s. */
@@ -39,11 +83,22 @@ export interface ExtractFramesOptions {
  * avoid black/blank frames at the very start and end.
  */
 export declare function computeSampleTimestamps(durationSeconds: number, count: number): number[];
+/**
+ * Computes timestamps for dense sampling of a [start, end] window at `fps`,
+ * capped at `maxFrames` (falling back to even spacing across the window when
+ * the requested rate would exceed the cap).
+ */
+export declare function computeRangeTimestamps(start: number, end: number, fps: number, maxFrames: number): number[];
 /**
  * Builds an ffmpeg scale filter that caps width while preserving aspect ratio.
  * Returns null when no cap is requested, so frames keep their original resolution.
  */
 export declare function buildScaleFilter(maxWidth?: number): string | null;
+/**
+ * Builds an ffmpeg crop filter for a region (with optional padding), clamped to
+ * the video bounds when they are known. Returns null for degenerate regions.
+ */
+export declare function buildCropFilter(region: FrameRegion, videoWidth?: number | null, videoHeight?: number | null): string | null;
 export interface CommandResult {
     code: number | null;
     stdout: string;
@@ -51,8 +106,26 @@ export interface CommandResult {
 }
 export declare function runCommand(command: string, args: string[], timeoutMs: number): Promise<CommandResult>;
 /**
- * Downloads the recording at `url` and returns sampled JPEG frames.
- * Throws with a clear message when ffmpeg is unavailable.
+ * Stable cache key for a recording URL: the blob identity without the SAS
+ * query, so re-minted signed URLs for the same blob hit the same cache entry.
+ */
+export declare function cacheKeyForUrl(url: string): string;
+/**
+ * Returns a local path to the recording, downloading it if not already cached.
+ * The returned file must NOT be deleted by the caller (it is shared).
+ */
+export declare function getCachedRecording(url: string, opts: {
+    maxBytes: number;
+    downloadTimeoutMs: number;
+}): Promise<string>;
+export interface VideoInfo {
+    durationSeconds: number | null;
+    width: number | null;
+    height: number | null;
+}
+/**
+ * Downloads the recording at `url` (via the shared cache) and returns extracted
+ * JPEG frames. Throws with a clear message when ffmpeg is unavailable.
  */
 export declare function extractFramesFromUrl(url: string, options?: ExtractFramesOptions): Promise<ExtractedFrame[]>;
 //# sourceMappingURL=recording-frames.d.ts.map

package/dist/recording-frames.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recording-frames.d.ts","sourceRoot":"","sources":["../src/recording-frames.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAWD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CASxF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKjE;AAID,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,CAAC,CA4CxB;AAqHD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,cAAc,EAAE,CAAC,CAuF3B"}
+{"version":3,"file":"recording-frames.d.ts","sourceRoot":"","sources":["../src/recording-frames.ts"],"names":[],"mappings":"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"}

package/dist/recording-frames.js

@@ -1,25 +1,40 @@
 /**
- * Extracts sampled still frames from a recording (MP4) so that a vision-capable
- * model can visually verify or debug an execution.
+ * Extracts still frames from a recording (MP4) so that a vision-capable model
+ * can visually verify or debug an execution.
  *
  * The recording endpoints return a signed URL to an MP4. A model cannot "watch"
- * a video URL, so this module downloads the video and uses ffmpeg to sample a
- * handful of frames, returned as base64 JPEGs. ffmpeg (and ideally ffprobe) must
- * be available on the MCP host; when they are missing we throw a clear error so
- * the caller can fall back to handing the raw URL to a human.
+ * a video URL, so this module downloads the video and uses ffmpeg to extract
+ * frames, returned as base64 JPEGs. Supports:
+ *   - evenly-spaced sampling across the whole video (default)
+ *   - exact timestamps ("show me t=41.5s")
+ *   - dense sampling of a time range ("what happened between t=30s and t=45s")
+ *   - region cropping at the recording's native resolution ("zoom in here")
+ *
+ * Downloads are cached under ~/.minicor/cache/recordings keyed on the blob
+ * identity (URL minus the SAS query), so successive calls against the same
+ * recording skip the download entirely.
+ *
+ * ffmpeg (and ideally ffprobe) must be available on the MCP host; when they are
+ * missing we throw a clear error so the caller can fall back to handing the raw
+ * URL to a human.
  */
 import { spawn } from "node:child_process";
-import { mkdtemp, open, readFile, readdir, rm } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { mkdtemp, mkdir, open, readFile, readdir, rename, rm, stat, utimes, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { MINICOR_DIR } from "./paths.js";
 const DEFAULTS = {
     count: 4,
+    maxFrames: 16,
+    cache: true,
     maxBytes: 200 * 1024 * 1024,
     downloadTimeoutMs: 60_000,
     commandTimeoutMs: 30_000,
     ffmpegPath: "ffmpeg",
     ffprobePath: "ffprobe",
 };
+// ── Sampling math ────────────────────────────────────────────
 /**
  * Computes evenly-spaced sample timestamps centered within the duration, so we
  * avoid black/blank frames at the very start and end.
@@ -34,6 +49,29 @@ export function computeSampleTimestamps(durationSeconds, count) {
         return Number((durationSeconds * fraction).toFixed(3));
     });
 }
+/**
+ * Computes timestamps for dense sampling of a [start, end] window at `fps`,
+ * capped at `maxFrames` (falling back to even spacing across the window when
+ * the requested rate would exceed the cap).
+ */
+export function computeRangeTimestamps(start, end, fps, maxFrames) {
+    if (!Number.isFinite(start) ||
+        !Number.isFinite(end) ||
+        end <= start ||
+        !Number.isFinite(fps) ||
+        fps <= 0 ||
+        maxFrames <= 0) {
+        return [];
+    }
+    const span = end - start;
+    const requested = Math.floor(span * fps) + 1;
+    const n = Math.min(requested, maxFrames);
+    if (n === 1)
+        return [Number(start.toFixed(3))];
+    const step = span / (n - 1);
+    return Array.from({ length: n }, (_, i) => Number((start + i * step).toFixed(3)));
+}
+// ── ffmpeg filters ───────────────────────────────────────────
 /**
  * Builds an ffmpeg scale filter that caps width while preserving aspect ratio.
  * Returns null when no cap is requested, so frames keep their original resolution.
@@ -44,6 +82,43 @@ export function buildScaleFilter(maxWidth) {
     }
     return `scale='min(${maxWidth},iw)':-2`;
 }
+/**
+ * Builds an ffmpeg crop filter for a region (with optional padding), clamped to
+ * the video bounds when they are known. Returns null for degenerate regions.
+ */
+export function buildCropFilter(region, videoWidth, videoHeight) {
+    const pad = region.pad ?? 0;
+    let x0 = Math.floor(region.x - pad);
+    let y0 = Math.floor(region.y - pad);
+    let x1 = Math.ceil(region.x + region.width + pad);
+    let y1 = Math.ceil(region.y + region.height + pad);
+    x0 = Math.max(x0, 0);
+    y0 = Math.max(y0, 0);
+    if (videoWidth != null && Number.isFinite(videoWidth))
+        x1 = Math.min(x1, videoWidth);
+    if (videoHeight != null && Number.isFinite(videoHeight))
+        y1 = Math.min(y1, videoHeight);
+    const w = x1 - x0;
+    const h = y1 - y0;
+    if (w <= 0 || h <= 0)
+        return null;
+    return `crop=${w}:${h}:${x0}:${y0}`;
+}
+function buildVideoFilter(region, maxWidth, videoWidth, videoHeight) {
+    const parts = [];
+    if (region) {
+        const crop = buildCropFilter(region, videoWidth, videoHeight);
+        if (!crop) {
+            throw new Error("the requested region falls entirely outside the video bounds");
+        }
+        parts.push(crop);
+    }
+    const scale = buildScaleFilter(maxWidth);
+    if (scale)
+        parts.push(scale);
+    return parts.length > 0 ? parts.join(",") : null;
+}
+// ── Command execution ────────────────────────────────────────
 class CommandNotFoundError extends Error {
 }
 export function runCommand(command, args, timeoutMs) {
@@ -87,6 +162,98 @@ export function runCommand(command, args, timeoutMs) {
         });
     });
 }
+// ── Download cache ───────────────────────────────────────────
+const CACHE_DIR = path.join(MINICOR_DIR, "cache", "recordings");
+const CACHE_TTL_MS = 30 * 60 * 1000; // 30 min — SAS URLs are short-lived anyway
+const CACHE_MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2 GB
+/**
+ * Stable cache key for a recording URL: the blob identity without the SAS
+ * query, so re-minted signed URLs for the same blob hit the same cache entry.
+ */
+export function cacheKeyForUrl(url) {
+    let identity = url;
+    try {
+        const parsed = new URL(url);
+        identity = `${parsed.origin}${parsed.pathname}`;
+    }
+    catch {
+        // Not a parseable URL — hash the raw string.
+    }
+    return createHash("sha1").update(identity).digest("hex");
+}
+async function evictCache() {
+    let entries = [];
+    try {
+        const files = await readdir(CACHE_DIR);
+        for (const f of files) {
+            if (!f.endsWith(".mp4"))
+                continue;
+            const full = path.join(CACHE_DIR, f);
+            try {
+                const s = await stat(full);
+                entries.push({ file: full, mtimeMs: s.mtimeMs, size: s.size });
+            }
+            catch {
+                /* raced with another eviction */
+            }
+        }
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    const fresh = [];
+    for (const e of entries) {
+        if (now - e.mtimeMs > CACHE_TTL_MS) {
+            await rm(e.file, { force: true }).catch(() => { });
+        }
+        else {
+            fresh.push(e);
+        }
+    }
+    let total = fresh.reduce((sum, e) => sum + e.size, 0);
+    if (total <= CACHE_MAX_BYTES)
+        return;
+    fresh.sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
+    for (const e of fresh) {
+        if (total <= CACHE_MAX_BYTES)
+            break;
+        await rm(e.file, { force: true }).catch(() => { });
+        total -= e.size;
+    }
+}
+/**
+ * Returns a local path to the recording, downloading it if not already cached.
+ * The returned file must NOT be deleted by the caller (it is shared).
+ */
+export async function getCachedRecording(url, opts) {
+    // Private permissions: recordings can contain sensitive screen content.
+    await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
+    const dest = path.join(CACHE_DIR, `${cacheKeyForUrl(url)}.mp4`);
+    try {
+        const s = await stat(dest);
+        if (s.size > 0 && Date.now() - s.mtimeMs <= CACHE_TTL_MS) {
+            // Touch for LRU so hot recordings survive eviction.
+            const now = new Date();
+            await utimes(dest, now, now).catch(() => { });
+            return dest;
+        }
+    }
+    catch {
+        /* not cached yet */
+    }
+    const partial = `${dest}.${process.pid}.${Date.now()}.part`;
+    try {
+        await downloadToFile(url, partial, opts.maxBytes, opts.downloadTimeoutMs);
+        await rename(partial, dest);
+    }
+    finally {
+        // A failed/aborted download must not leave partial bytes accumulating.
+        await rm(partial, { force: true }).catch(() => { });
+    }
+    await evictCache();
+    return dest;
+}
 async function downloadToFile(url, dest, maxBytes, timeoutMs) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -102,7 +269,7 @@ async function downloadToFile(url, dest, maxBytes, timeoutMs) {
         if (!res.body) {
             throw new Error("recording download returned an empty body");
         }
-        const handle = await open(dest, "w");
+        const handle = await open(dest, "w", 0o600);
         try {
             let total = 0;
             for await (const chunk of res.body) {
@@ -121,30 +288,46 @@ async function downloadToFile(url, dest, maxBytes, timeoutMs) {
         clearTimeout(timer);
     }
 }
-async function probeDurationSeconds(file, ffprobePath, timeoutMs) {
+async function probeVideo(file, ffprobePath, timeoutMs) {
     try {
-        const { stdout } = await runCommand(ffprobePath, ["-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", file], timeoutMs);
-        const duration = parseFloat(stdout.trim());
-        return Number.isFinite(duration) && duration > 0 ? duration : null;
+        const { stdout } = await runCommand(ffprobePath, [
+            "-v",
+            "error",
+            "-select_streams",
+            "v:0",
+            "-show_entries",
+            "stream=width,height:format=duration",
+            "-of",
+            "json",
+            file,
+        ], timeoutMs);
+        const parsed = JSON.parse(stdout);
+        const duration = parseFloat(parsed?.format?.duration);
+        const width = Number(parsed?.streams?.[0]?.width);
+        const height = Number(parsed?.streams?.[0]?.height);
+        return {
+            durationSeconds: Number.isFinite(duration) && duration > 0 ? duration : null,
+            width: Number.isFinite(width) && width > 0 ? width : null,
+            height: Number.isFinite(height) && height > 0 ? height : null,
+        };
     }
-    catch (e) {
-        if (e instanceof CommandNotFoundError) {
-            return null; // ffprobe missing; caller falls back to thumbnail sampling
-        }
-        return null;
+    catch {
+        // ffprobe missing or unparseable; caller falls back to thumbnail sampling.
+        return { durationSeconds: null, width: null, height: null };
     }
 }
-async function extractFrameAt(file, timestampSeconds, outPath, scaleFilter, ffmpegPath, timeoutMs) {
+// ── Frame extraction ─────────────────────────────────────────
+async function extractFrameAt(file, timestampSeconds, outPath, videoFilter, ffmpegPath, timeoutMs) {
     const args = ["-ss", String(timestampSeconds), "-i", file, "-frames:v", "1"];
-    if (scaleFilter) {
-        args.push("-vf", scaleFilter);
+    if (videoFilter) {
+        args.push("-vf", videoFilter);
     }
     // -q:v 2 = highest-quality JPEG, so the original resolution is preserved with minimal artifacts.
     args.push("-q:v", "2", "-y", outPath);
     await runCommand(ffmpegPath, args, timeoutMs);
 }
-async function extractThumbnails(file, count, outPattern, scaleFilter, ffmpegPath, timeoutMs) {
-    const vf = scaleFilter ? `thumbnail,${scaleFilter}` : "thumbnail";
+async function extractThumbnails(file, count, outPattern, videoFilter, ffmpegPath, timeoutMs) {
+    const vf = videoFilter ? `thumbnail,${videoFilter}` : "thumbnail";
     await runCommand(ffmpegPath, [
         "-i",
         file,
@@ -169,27 +352,66 @@ async function readJpegBase64(file) {
         return null;
     }
 }
+function resolveTimestamps(opts, durationSeconds) {
+    if (opts.timestamps && opts.timestamps.length > 0) {
+        // Sorted copy: callers are promised chronological frames.
+        const valid = [...opts.timestamps]
+            .filter((t) => Number.isFinite(t) && t >= 0)
+            .sort((a, b) => a - b)
+            .slice(0, opts.maxFrames);
+        return valid.map((t) => {
+            // Clamp seeks slightly inside the end so they land on a frame.
+            if (durationSeconds != null && t >= durationSeconds) {
+                return Number(Math.max(durationSeconds - 0.05, 0).toFixed(3));
+            }
+            return Number(t.toFixed(3));
+        });
+    }
+    if (opts.range) {
+        const end = durationSeconds != null
+            ? Math.min(opts.range.end, durationSeconds - 0.01)
+            : opts.range.end;
+        return computeRangeTimestamps(opts.range.start, end, opts.range.fps ?? 1, opts.maxFrames);
+    }
+    if (durationSeconds != null) {
+        return computeSampleTimestamps(durationSeconds, opts.count);
+    }
+    return null; // no duration and no explicit targets: thumbnail fallback
+}
 /**
- * Downloads the recording at `url` and returns sampled JPEG frames.
- * Throws with a clear message when ffmpeg is unavailable.
+ * Downloads the recording at `url` (via the shared cache) and returns extracted
+ * JPEG frames. Throws with a clear message when ffmpeg is unavailable.
  */
 export async function extractFramesFromUrl(url, options = {}) {
     const opts = { ...DEFAULTS, ...options };
-    const scaleFilter = buildScaleFilter(opts.maxWidth);
     const workDir = await mkdtemp(path.join(tmpdir(), "laminar-frames-"));
-    const videoPath = path.join(workDir, "recording.mp4");
+    let videoPath;
     try {
-        await downloadToFile(url, videoPath, opts.maxBytes, opts.downloadTimeoutMs);
-        const duration = await probeDurationSeconds(videoPath, opts.ffprobePath, opts.commandTimeoutMs);
+        if (opts.cache) {
+            try {
+                videoPath = await getCachedRecording(url, opts);
+            }
+            catch {
+                // Cache dir unusable (permissions, disk) — fall back to a temp download.
+                videoPath = path.join(workDir, "recording.mp4");
+                await downloadToFile(url, videoPath, opts.maxBytes, opts.downloadTimeoutMs);
+            }
+        }
+        else {
+            videoPath = path.join(workDir, "recording.mp4");
+            await downloadToFile(url, videoPath, opts.maxBytes, opts.downloadTimeoutMs);
+        }
+        const info = await probeVideo(videoPath, opts.ffprobePath, opts.commandTimeoutMs);
+        const videoFilter = buildVideoFilter(opts.region, opts.maxWidth, info.width, info.height);
+        const timestamps = resolveTimestamps(opts, info.durationSeconds);
         const frames = [];
         try {
-            if (duration != null) {
-                const timestamps = computeSampleTimestamps(duration, opts.count);
+            if (timestamps != null) {
                 let lastError = null;
                 for (let i = 0; i < timestamps.length; i++) {
                     const outPath = path.join(workDir, `frame-${i}.jpg`);
                     try {
-                        await extractFrameAt(videoPath, timestamps[i], outPath, scaleFilter, opts.ffmpegPath, opts.commandTimeoutMs);
+                        await extractFrameAt(videoPath, timestamps[i], outPath, videoFilter, opts.ffmpegPath, opts.commandTimeoutMs);
                     }
                     catch (e) {
                         // ffmpeg missing is fatal; a single bad frame (e.g. a seek that lands
@@ -216,7 +438,7 @@ export async function extractFramesFromUrl(url, options = {}) {
             else {
                 // No duration (ffprobe missing) — fall back to thumbnail sampling.
                 const outPattern = path.join(workDir, "thumb-%03d.jpg");
-                await extractThumbnails(videoPath, opts.count, outPattern, scaleFilter, opts.ffmpegPath, opts.commandTimeoutMs);
+                await extractThumbnails(videoPath, opts.count, outPattern, videoFilter, opts.ffmpegPath, opts.commandTimeoutMs);
                 const files = (await readdir(workDir))
                     .filter((f) => f.startsWith("thumb-") && f.endsWith(".jpg"))
                     .sort();