@mevdragon/vidfarm-devcli 0.9.0 → 0.10.0

package/dist/src/cli.js

@@ -144,10 +144,16 @@ Generate AI media and drop it on the timeline (for local coding agents):
                             original vs decomposed (caption-free),
                             non-billing (alias: ghostcut)
 
-Clip curation (the third library — mine long-form video into a reusable clip store):
-  clips scan <video-path>   Detect scenes → tag + transcribe (Gemini)    LOCAL: ffmpeg + BYOK Gemini
-                            → embed → persist to ~/.vidfarm/clips.db.     (cloud: POST /clips/scan)
-    --tier flash|flash-lite   Gemini tier (default flash-lite, cheapest)
+Clip hunting (the third library — mine long-form video into a reusable clip store):
+  clips scan <video-path>   Hunt short clips out of a long video.        LOCAL-FIRST: local ffmpeg +
+                            Detect → tag/transcribe → embed → persist    your local claude/codex CLI
+                            to ~/.vidfarm/clips.db.                      (keys are fallback)
+    --range "MM:SS-MM:SS"     Only hunt these source windows (repeatable; big cost saver)
+    --duration <sec>          Target clip length as a SOFT band (10→5-20s, 30→20-40s)
+    --aspect 9:16|16:9|4:3|1:1  Crop clips (also: vertical/horizontal/square) [--crop-focus <f>]
+    --no-text                 Prefer scenes WITHOUT captions/on-screen text (selection only)
+    --cloud [--url <url>]     BACKUP: run on the deployed pipeline       → POST /clips/scan (+ poll)
+                              (uploads to your temp folder — 30-day TTL — bills AWS compute only)
     --dry-run                 Show the estimated cost and stop (over $1 needs --yes/confirm)
   clips list                List the local clip library                  → GET  /clips
   clips search "<text>"     Hybrid structured + semantic search          → POST /clips/search

package/dist/src/config.js

@@ -68,6 +68,11 @@ const schema = z.object({
     GHOSTCUT_KEY: z.string().optional(),
     GHOSTCUT_SECRET: z.string().optional(),
     GHOSTCUT_USD_PER_30S: z.coerce.number().min(0).default(0.10),
+    // GhostCut caption removal is for SHORT clips, never long-form sources —
+    // clip hunting must select text-free scenes instead of laundering a whole
+    // long video through GhostCut. 15 min default ceiling (per-30s pricing makes
+    // long-form runs absurd anyway).
+    GHOSTCUT_MAX_DURATION_SEC: z.coerce.number().min(0).default(900),
     // Cloud passthrough for `vidfarm serve`: the local box keeps editing/render
     // fully local but lists the upstream (prod) catalog in /discover and
     // /library, seeds forks on demand, and can hand a render off to the cloud.

package/dist/src/devcli/clips.js

@@ -1,35 +1,55 @@
-// devcli `vidfarm clips …` — the local clip-curation surface. Uses local
-// ffmpeg (near-zero compute) + BYOK Gemini, persisting to a SQLite clip library
-// (~/.vidfarm). Every scan shows an estimated cost first; scans over $1 require
-// --yes or an interactive confirm. Mirrors the cloud REST surface 1:1.
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+// devcli `vidfarm clips …` — the local clip-curation surface. LOCAL-FIRST:
+// local ffmpeg for compute and, by default, the user's local agent CLI
+// subscription (claude/codex) for scene evaluation — no API key needed. BYOK
+// provider keys are the first fallback, and `--cloud` is the explicit backup
+// that runs the hunt on the deployed pipeline instead (never the default).
+// Persists to a SQLite clip library (~/.vidfarm). Every keyed scan shows an
+// estimated cost first; scans over $1 require --yes or an interactive confirm.
+// Mirrors the cloud REST surface 1:1.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { homedir } from "node:os";
 import { parseArgs } from "node:util";
 import { createInterface } from "node:readline/promises";
 import { createIdV7 } from "../lib/ids.js";
-import { ClipModelClient, estimateScanCostFromScenes, formatCostEstimate, detectScenes, hasFfmpeg, probeVideo, scanVideo, searchClips } from "../services/clip-curation/index.js";
+import { buildEffectiveGuidance, ClipModelClient, detectLocalAgent, detectScenes, estimateScanCostFromScenes, fitScenesToDurationBand, formatCostEstimate, hasFfmpeg, LocalAgentClipClient, normalizeAspect, normalizeCropFocus, normalizeWindows, parseClipHuntPrompt, parseTimeRanges, probeVideo, resolveDurationBand, scanVideo, searchClips } from "../services/clip-curation/index.js";
 import { ClipStore } from "./clip-store.js";
-export const CLIPS_HELP = `vidfarm clips — build & search a local clip library (local ffmpeg + BYOK Gemini)
+export const CLIPS_HELP = `vidfarm clips — build & search a local clip library (local ffmpeg + local agent by default)
 
   clips scan <video-path>          Mine a long-form video into tagged, searchable clips
-    --provider <p>                 gemini | openai | openrouter (default: gemini)
-                                   gemini→gemini-2.5-flash-lite, openai→gpt-5.4-nano,
-                                   openrouter→google/gemini-2.5-flash
-    --tier flash|flash-lite        Gemini tier (default: flash-lite; ignored for openai/openrouter)
+    --provider <p>                 agent | gemini | openai | openrouter
+                                   Default: agent when a local claude/codex CLI is installed
+                                   (your subscription, no API key), else gemini.
+    --agent claude|codex           Which local agent CLI to use for --provider agent (default: auto)
+    --tier flash|flash-lite        Gemini tier (default: flash-lite; ignored for openai/openrouter/agent)
     --prompt "<guidance>"          Reshape clipping toward your goal: an LLM pass
-                                   keeps/drops/merges scenes, and tags are biased to it
+                                   keeps/drops/merges scenes, and tags are biased to it.
+                                   Inline hints are honored too: "between 12:30 and 15:45",
+                                   "30 sec clips", "vertical", "no captions".
+    --range "MM:SS-MM:SS"          Only hunt inside this source range (repeatable / comma-separated)
+    --duration <sec>               Target clip length as a SOFT band (10→5-20s, 30→20-40s, …)
+    --aspect <a>                   Crop clips to 9:16 | 16:9 | 4:3 | 1:1 (or vertical/horizontal/square)
+    --crop-focus <f>               center | top | bottom | left | right (default: center)
+    --no-text                      Prefer scenes WITHOUT burned-in captions/on-screen text
+                                   (scene selection — NEVER GhostCut on the long-form source)
     --no-refine                    Keep prompt tag-bias but skip the keep/drop/merge pass
+    --cloud                        BACKUP: run the hunt on the deployed pipeline instead of this
+                                   machine (uploads to your temp folder — auto-deletes in 30 days —
+                                   or pass --url; needs VIDFARM_API_KEY; bills AWS compute only)
+    --url <video-url>              With --cloud: hunt a YouTube/TikTok/IG/X URL without uploading
+    --tracer <id>                  With --cloud: tag the hunt's billing/observability rollup
+    --api-url <base>               With --cloud: deployment base URL (or VIDFARM_API_URL)
+    --api-key <key>                With --cloud: API key (or VIDFARM_API_KEY)
     --dry-run                      Print the estimated cost and exit
     --yes                          Skip the >$1 confirmation prompt
     --frames <n>                   Keyframes per scene for tagging (1-3, default 2)
     --no-audio                     Skip per-scene audio (Gemini only; no transcripts; cheaper)
-    --concurrency <n>              Parallel scenes (default 3; respect rate limits)
+    --concurrency <n>              Parallel scenes (default 3; agent default 2)
     --threshold <0..1>             Scene-cut sensitivity (default 0.3; lower = more cuts)
     --min-scene <sec>              Merge scenes shorter than this (default 0.6)
-    --max-scene <sec>              Split scenes longer than this (default 8)
+    --max-scene <sec>              Split scenes longer than this (default 8; --duration overrides)
     --gemini-key / --openai-key / --openrouter-key <key>   Provider key (or *_API_KEY env)
-    --embed-provider gemini|openai --embed-key <key>       Embeddings when using openrouter
+    --embed-provider gemini|openai --embed-key <key>       Embeddings for agent/openrouter scans
     --home <dir>                   Library dir (default: ~/.vidfarm or VIDFARM_HOME)
 
   clips list                       List clips in the library
@@ -97,9 +117,20 @@ async function runScan(argv) {
         allowPositionals: true,
         options: {
             provider: { type: "string" },
+            agent: { type: "string" },
             tier: { type: "string" },
             prompt: { type: "string" },
+            range: { type: "string", multiple: true },
+            duration: { type: "string" },
+            aspect: { type: "string" },
+            "crop-focus": { type: "string" },
+            "no-text": { type: "boolean" },
             "no-refine": { type: "boolean" },
+            cloud: { type: "boolean" },
+            url: { type: "string" },
+            tracer: { type: "string" },
+            "api-url": { type: "string" },
+            "api-key": { type: "string" },
             "dry-run": { type: "boolean" },
             yes: { type: "boolean" },
             frames: { type: "string" },
@@ -116,67 +147,146 @@ async function runScan(argv) {
             home: { type: "string" }
         }
     });
+    // ── Hunt spec: explicit flags win; inline prompt hints fill the gaps ──────
+    const guidancePromptRaw = values.prompt?.trim() || undefined;
+    const parsedPrompt = parseClipHuntPrompt(guidancePromptRaw);
+    const rawWindows = values.range?.length
+        ? parseTimeRanges(values.range)
+        : parsedPrompt.windows;
+    const durationBand = values.duration
+        ? resolveDurationBand(Number(values.duration))
+        : parsedPrompt.target_duration_sec != null
+            ? resolveDurationBand(parsedPrompt.target_duration_sec)
+            : null;
+    const aspect = values.aspect
+        ? (normalizeAspect(values.aspect) ?? (() => { throw new Error(`--aspect must be 9:16 | 16:9 | 4:3 | 1:1 (or vertical/horizontal/square), got "${values.aspect}"`); })())
+        : parsedPrompt.aspect;
+    const cropFocus = normalizeCropFocus(values["crop-focus"]);
+    const avoidText = Boolean(values["no-text"]) || parsedPrompt.avoid_text;
+    const guidance = buildEffectiveGuidance({ contentPrompt: guidancePromptRaw, avoidText }) || undefined;
+    // ── BACKUP path: run the hunt on the deployed pipeline (--cloud) ──────────
+    if (values.cloud) {
+        return runScanCloud({
+            videoArg: positionals[0],
+            sourceUrl: values.url?.trim() || undefined,
+            apiUrl: values["api-url"],
+            apiKey: values["api-key"],
+            tracer: values.tracer,
+            prompt: guidancePromptRaw,
+            windows: rawWindows,
+            durationBand,
+            aspect,
+            cropFocus,
+            avoidText
+        });
+    }
     const videoArg = positionals[0];
     if (!videoArg)
-        throw new Error("Usage: vidfarm clips scan <video-path> [--tier flash|flash-lite] [--dry-run]");
+        throw new Error("Usage: vidfarm clips scan <video-path> [--range MM:SS-MM:SS] [--duration 30] [--aspect 9:16] [--dry-run]");
     const videoPath = path.resolve(process.cwd(), videoArg);
     if (!existsSync(videoPath))
         throw new Error(`No such video: ${videoPath}`);
     if (!(await hasFfmpeg())) {
         throw new Error("ffmpeg is required for `clips scan` but was not found (bundled ffmpeg-static missing and none on PATH).");
     }
-    const provider = normalizeProvider(values.provider);
+    // ── Model resolution: LOCAL-FIRST ─────────────────────────────────────────
+    // 1. --provider agent (or no --provider + a local claude/codex CLI installed)
+    //    → the user's local agent subscription evaluates scenes; no API key.
+    // 2. --provider gemini|openai|openrouter (or a key in env/config) → BYOK API.
+    // 3. --cloud (handled above) → the deployed pipeline, as an explicit backup.
+    const provider = resolveScanProvider(values);
     const tier = normalizeTier(values.tier);
     const framesPerScene = clampInt(values.frames, 2, 1, 3);
-    // Audio is Gemini-only (chat models on openai/openrouter don't take the clip).
+    // Audio is Gemini-only (chat models on openai/openrouter — and CLI agents — don't take the clip).
     const includeAudio = !values["no-audio"] && provider === "gemini";
-    const guidancePrompt = values.prompt?.trim() || undefined;
-    const concurrency = clampInt(values.concurrency, 3, 1, 12);
+    // Local agents run one process per call — keep parallelism modest by default.
+    const concurrency = clampInt(values.concurrency, provider === "agent" ? 2 : 3, 1, 12);
     const sceneOptions = {
         threshold: values.threshold ? Number(values.threshold) : undefined,
         minSceneSec: values["min-scene"] ? Number(values["min-scene"]) : undefined,
-        maxSceneSec: values["max-scene"] ? Number(values["max-scene"]) : undefined
+        // A duration band lifts the split ceiling; an explicit --max-scene still wins.
+        maxSceneSec: values["max-scene"] ? Number(values["max-scene"]) : durationBand?.max_sec
     };
     // Resolve the tagging key + optional embedding config. Optional here so
-    // --dry-run can show the cost without a key; the key is required below to scan.
-    const apiKey = resolveProviderKey(provider, values, { optional: true });
-    const embedding = apiKey ? resolveEmbeddingConfig(provider, apiKey, values) : null;
+    // --dry-run can show the cost without a key; required below to scan (API providers).
+    const apiKey = provider === "agent" ? "" : resolveProviderKey(provider, values, { optional: true });
+    const embedding = provider === "agent"
+        ? resolveAgentEmbeddingConfig(values)
+        : apiKey ? resolveEmbeddingConfig(provider, apiKey, values) : null;
     console.log(`[clips] probing ${path.basename(videoPath)} …`);
     const probe = await probeVideo(videoPath);
     console.log(`[clips] ${fmtDuration(probe.duration_sec)} · ${probe.width ?? "?"}x${probe.height ?? "?"} · ${probe.codec ?? "?"}`);
+    const windows = normalizeWindows(rawWindows, probe.duration_sec);
+    if (rawWindows.length && !windows.length) {
+        throw new Error("--range produced no usable window inside the video's duration.");
+    }
+    if (windows.length) {
+        console.log(`[clips] hunting only ${windows.map((w) => `${fmtClock(w.start_sec)}–${fmtClock(w.end_sec)}`).join(", ")} (${fmtDuration(windows.reduce((a, w) => a + w.end_sec - w.start_sec, 0))} of ${fmtDuration(probe.duration_sec)}).`);
+    }
+    if (durationBand) {
+        console.log(`[clips] target clip length ~${durationBand.target_sec}s (soft range ${durationBand.min_sec}–${durationBand.max_sec}s).`);
+    }
+    if (aspect && aspect !== "original")
+        console.log(`[clips] cropping clips to ${aspect} (${cropFocus}).`);
+    if (avoidText)
+        console.log(`[clips] preferring scenes without on-screen text/captions (selection only — GhostCut is never run on the source).`);
     console.log(`[clips] detecting scenes …`);
-    const scenes = await detectScenes(videoPath, { durationSec: probe.duration_sec, ...sceneOptions });
+    const detected = await detectScenes(videoPath, { durationSec: probe.duration_sec, windows, ...sceneOptions });
+    const scenes = fitScenesToDurationBand(detected, durationBand);
     if (scenes.length === 0)
         throw new Error("No scenes detected (is the video readable / non-empty?).");
     const store = new ClipStore(values.home);
-    const client = apiKey ? new ClipModelClient({ provider, apiKey, tier, embedding }) : null;
+    let client = null;
+    if (provider === "agent") {
+        client = new LocalAgentClipClient({
+            agent: values.agent === "claude" || values.agent === "codex" ? values.agent : "auto",
+            embedding,
+            tier
+        });
+        console.log(`[clips] evaluating scenes with your local ${client.tagModelId} subscription (no API cost).`);
+    }
+    else if (apiKey) {
+        client = new ClipModelClient({ provider, apiKey, tier, embedding });
+    }
     if (client && !client.canEmbed) {
         console.warn(`[clips] no embedding provider for "${provider}" — clips will be structured-searchable only.`);
         console.warn(`        Add --embed-provider gemini|openai --embed-key <key> for semantic search.`);
     }
-    const estimate = estimateScanCostFromScenes(scenes, {
-        tier,
-        provider,
-        tagModelId: client?.tagModelId,
-        embedModelId: client ? client.embeddingModelId : defaultEmbedModelForEstimate(provider),
-        framesPerScene,
-        includeAudio
-    });
-    console.log(`\n  Cost estimate: ${formatCostEstimate(estimate)}`);
-    console.log(`  Target: $0.05–0.10 per source hour (${withinTarget(estimate.usd_per_source_hour) ? "on target" : "note"}).`);
-    if (guidancePrompt)
-        console.log(`  Guidance: "${guidancePrompt}"`);
+    // Cost estimate: local-agent scans ride the user's subscription, so only the
+    // optional embedding spend applies; API scans estimate the full BYOK cost.
+    const estimate = provider === "agent"
+        ? null
+        : estimateScanCostFromScenes(scenes, {
+            tier,
+            provider,
+            tagModelId: client?.tagModelId,
+            embedModelId: client ? client.embeddingModelId : defaultEmbedModelForEstimate(provider),
+            framesPerScene,
+            includeAudio
+        });
+    if (estimate) {
+        console.log(`\n  Cost estimate: ${formatCostEstimate(estimate)}`);
+        console.log(`  Target: $0.05–0.10 per source hour (${withinTarget(estimate.usd_per_source_hour) ? "on target" : "note"}).`);
+    }
+    else {
+        console.log(`\n  Cost: local agent subscription (${scenes.length} scenes; embeddings ${embedding ? `via ${embedding.provider}` : "off"}).`);
+    }
+    if (guidance)
+        console.log(`  Guidance: "${guidance.replace(/\n/g, " · ")}"`);
     console.log("");
     if (values["dry-run"]) {
         console.log("[clips] --dry-run: not scanning. Re-run without --dry-run to build the library.");
         return;
     }
-    // Actually scanning now — a key is required.
-    if (!client)
-        resolveProviderKey(provider, values); // throws the "No <provider> API key" error
+    // Actually scanning now — an evaluator is required.
+    if (!client) {
+        if (provider !== "agent")
+            resolveProviderKey(provider, values); // throws the "No <provider> API key" error
+        throw new Error("No scene evaluator available. Install Claude Code (`claude`) or Codex (`codex`), pass a provider key, or run with --cloud.");
+    }
     const activeClient = client;
-    // $1 confirmation gate (handoff Target 1).
-    if (estimate.usd > 1 && !values.yes) {
+    // $1 confirmation gate (handoff Target 1) — keyed scans only.
+    if (estimate && estimate.usd > 1 && !values.yes) {
         const ok = await confirm(`This scan is estimated at $${estimate.usd.toFixed(2)}. Proceed? [y/N] `);
         if (!ok) {
             console.log("[clips] aborted.");
@@ -200,9 +310,10 @@ async function runScan(argv) {
         thumbsDir: store.paths.thumbsDir,
         framesPerScene,
         includeAudio,
-        guidancePrompt,
+        guidancePrompt: guidance,
         refineSegmentation: !values["no-refine"],
-        reencodeClips: true
+        reencodeClips: true,
+        crop: aspect && aspect !== "original" ? { aspect, focus: cropFocus } : undefined
     };
     console.log(`[clips] scanning ${scenes.length} scenes (${provider}/${activeClient.tagModelId}, ${concurrency}x) …`);
     let errors = 0;
@@ -212,6 +323,8 @@ async function runScan(argv) {
         videoPath,
         scenes,
         probe,
+        windows,
+        durationBand,
         sourceFilename: path.basename(videoPath),
         concurrency,
         onRefine: (r) => {
@@ -253,6 +366,139 @@ async function runScan(argv) {
     console.log(`  db    → ${store.paths.db}`);
     console.log(`  try:  vidfarm clips search "…"  |  vidfarm clips preset run "funny reaction gifs"`);
 }
+// ── clips scan --cloud (explicit backup: the deployed pipeline) ─────────────
+// Uploads the local file into the user's temp folder (30-day TTL, auto-removed)
+// — or passes --url straight through — then starts POST /clips/scan and polls.
+// The hunt bills AWS compute only; AI runs on the account's saved BYOK keys.
+async function runScanCloud(input) {
+    const baseUrl = (input.apiUrl || process.env.VIDFARM_API_URL || process.env.VIDFARM_UPSTREAM_HOST || "https://vidfarm.cc").replace(/\/$/, "");
+    const apiKey = input.apiKey || process.env.VIDFARM_API_KEY || "";
+    if (!apiKey)
+        throw new Error("--cloud needs an API key: pass --api-key or set VIDFARM_API_KEY.");
+    const headers = { "vidfarm-api-key": apiKey, "content-type": "application/json", accept: "application/json" };
+    let tempFileId;
+    let fileName;
+    if (!input.sourceUrl) {
+        if (!input.videoArg)
+            throw new Error("Usage: vidfarm clips scan --cloud <video-path> | --cloud --url <video-url>");
+        const videoPath = path.resolve(process.cwd(), input.videoArg);
+        if (!existsSync(videoPath))
+            throw new Error(`No such video: ${videoPath}`);
+        fileName = path.basename(videoPath);
+        const sizeBytes = statSync(videoPath).size;
+        console.log(`[clips] uploading ${fileName} (${(sizeBytes / (1024 * 1024)).toFixed(1)} MB) to your temp folder (auto-deletes in 30 days) …`);
+        const presignRes = await fetch(`${baseUrl}/api/v1/user/me/temporary-files/presign`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ file_name: fileName, content_type: "video/mp4", size_bytes: sizeBytes, folder_path: "clip-sources" })
+        });
+        const presign = await presignRes.json();
+        if (!presignRes.ok || !presign.upload || !presign.file_id) {
+            throw new Error(`Temp upload presign failed (${presignRes.status}): ${presign.error ?? "unexpected response"}`);
+        }
+        if (presign.transport !== "presigned") {
+            throw new Error("The deployment does not support presigned uploads — upload via the web UI, then re-run with --url or temp_file_id.");
+        }
+        const putRes = await fetch(presign.upload.url, {
+            method: presign.upload.method,
+            headers: presign.upload.headers,
+            body: readFileSync(path.resolve(process.cwd(), input.videoArg))
+        });
+        if (!putRes.ok)
+            throw new Error(`Upload failed (${putRes.status}).`);
+        const finalizeRes = await fetch(`${baseUrl}/api/v1/user/me/temporary-files`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                file_id: presign.file_id,
+                file_name: fileName,
+                content_type: "video/mp4",
+                size_bytes: sizeBytes,
+                storage_key: presign.storage_key,
+                folder_path: "clip-sources"
+            })
+        });
+        if (!finalizeRes.ok) {
+            const body = await finalizeRes.text().catch(() => "");
+            throw new Error(`Temp upload finalize failed (${finalizeRes.status}): ${body.slice(0, 300)}`);
+        }
+        tempFileId = presign.file_id;
+    }
+    console.log(`[clips] starting cloud hunt …`);
+    const scanRes = await fetch(`${baseUrl}/clips/scan`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            ...(input.sourceUrl ? { source_url: input.sourceUrl } : { temp_file_id: tempFileId, filename: fileName }),
+            prompt: input.prompt ?? "",
+            ...(input.tracer ? { tracer: input.tracer } : {}),
+            hunt_spec: {
+                ...(input.windows.length ? { windows: input.windows } : {}),
+                ...(input.durationBand ? { duration_band: input.durationBand } : {}),
+                ...(input.aspect ? { aspect: input.aspect } : {}),
+                crop_focus: input.cropFocus,
+                ...(input.avoidText ? { avoid_text: true } : {})
+            }
+        })
+    });
+    const scan = await scanRes.json();
+    if (!scanRes.ok || !scan.scan_id) {
+        throw new Error(`Cloud scan failed to start (${scanRes.status}): ${scan.error ?? "unexpected response"}`);
+    }
+    console.log(`[clips] scan ${scan.scan_id} ${scan.status ?? "queued"}${scan.tracer ? ` (tracer ${scan.tracer})` : ""}.`);
+    if (scan.compute_estimate?.estimated_charge_usd != null) {
+        console.log(`[clips] estimated AWS compute charge ~$${scan.compute_estimate.estimated_charge_usd.toFixed(4)} (AI runs on your saved provider keys).`);
+    }
+    // Async by design — poll until the pipeline finishes.
+    const started = timestamp();
+    for (;;) {
+        await new Promise((r) => setTimeout(r, 5000));
+        const pollRes = await fetch(`${baseUrl}/clips/scan/${encodeURIComponent(scan.scan_id)}`, { headers });
+        if (!pollRes.ok)
+            continue;
+        const poll = await pollRes.json();
+        const status = poll.source?.status ?? poll.scan?.status ?? "running";
+        if (status === "complete") {
+            console.log(`\n[clips] cloud hunt done in ${elapsed(started)}: ${poll.source?.clip_count ?? 0} clips.`);
+            console.log(`  browse → ${baseUrl}/clips`);
+            return;
+        }
+        if (status === "failed") {
+            throw new Error(`Cloud hunt failed: ${poll.scan?.error ?? "unknown error"}`);
+        }
+        process.stdout.write(`\r[clips] ${status} … ${elapsed(started)} `);
+    }
+}
+/**
+ * LOCAL-FIRST provider pick: an explicit --provider always wins; otherwise use
+ * the local agent CLI when one is installed (subscription-powered, keyless),
+ * else fall back to gemini BYOK. The cloud pipeline is never a silent default
+ * — it's the explicit `--cloud` backup.
+ */
+function resolveScanProvider(values) {
+    if (values.provider === "agent" || values.provider === "local" || values.provider === "local-agent")
+        return "agent";
+    if (values.provider)
+        return normalizeProvider(values.provider);
+    if (values.agent)
+        return "agent";
+    if (detectLocalAgent())
+        return "agent";
+    return "gemini";
+}
+/** Embeddings for a local-agent scan: any gemini/openai key found makes the library semantically searchable. */
+function resolveAgentEmbeddingConfig(flags) {
+    const explicit = flags["embed-provider"]?.trim();
+    const tryProvider = (p) => {
+        const key = flags["embed-key"]?.trim() || resolveProviderKey(p, flags, { optional: true });
+        return key ? { provider: p, apiKey: key } : null;
+    };
+    if (explicit === "gemini")
+        return tryProvider("gemini");
+    if (explicit === "openai")
+        return tryProvider("openai");
+    return tryProvider("gemini") ?? tryProvider("openai");
+}
 // ── clips list ──────────────────────────────────────────────────────────────
 async function runList(argv) {
     const { values } = parseArgs({
@@ -320,8 +566,15 @@ async function runSearch(argv) {
             queryEmbedding = await client.embedQuery(criteria.semantic_text ?? query);
         }
     }
+    else if (detectLocalAgent()) {
+        // Local-first: no key, but a local agent CLI can still turn the natural-
+        // language query into a structured filter (vector re-rank needs a key).
+        const agent = new LocalAgentClipClient({});
+        console.log(`[clips] structuring query with your local ${agent.tagModelId} …`);
+        criteria = await agent.naturalLanguageToCriteria(query);
+    }
     else {
-        console.warn(`[clips] no ${provider} key — structured/keyword search only (set the provider key for semantic search).`);
+        console.warn(`[clips] no ${provider} key or local agent CLI — structured/keyword search only.`);
     }
     const t0 = timestamp();
     const hits = store.search({ criteria, queryEmbedding, limit });
@@ -550,10 +803,20 @@ async function runPresetSave(argv) {
         criteria = asJson;
     }
     else {
-        // Treat as natural language → structured (needs a provider key).
+        // Natural language → structured: provider key when present, else the
+        // local agent CLI (local-first), else the usual missing-key error.
         const provider = normalizeProvider(values.provider);
-        const apiKey = resolveProviderKey(provider, values);
-        criteria = await new ClipModelClient({ provider, apiKey }).naturalLanguageToCriteria(fromQuery);
+        const apiKey = resolveProviderKey(provider, values, { optional: true });
+        if (apiKey) {
+            criteria = await new ClipModelClient({ provider, apiKey }).naturalLanguageToCriteria(fromQuery);
+        }
+        else if (detectLocalAgent()) {
+            criteria = await new LocalAgentClipClient({}).naturalLanguageToCriteria(fromQuery);
+        }
+        else {
+            resolveProviderKey(provider, values); // throws the "No <provider> API key" error
+            throw new Error("unreachable");
+        }
     }
     const store = new ClipStore(values.home);
     const preset = store.savePreset({ name, criteria, description: values.description });

package/dist/src/editor-chat.js

@@ -41,7 +41,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "Use POST /api/v1/primitives/images/edit only when the user wants to revise the attached/source image itself; its body is { tracer, payload: { source_image_url, instruction, reference_attachments? } }. Use POST /api/v1/primitives/images/generate when they want a new image inspired by or similar to the attachment.",
         "If the user asks to modify an attached image and the message includes an attachment URL, call POST /api/v1/primitives/images/edit with source_image_url inside payload set to that exact URL and instruction inside payload set to the requested edit.",
         "If the user asks to generate a new AI video from text or reference images, call POST /api/v1/primitives/videos/generate with body { tracer, payload: { prompt, input_references?, duration? } }. AI video duration is seconds; use duration: 4 for a 4-second video and never use duration_ms on /videos/generate. input_references must be direct image asset URLs, not webpage or social post URLs. Use frame_images for exact first/last-frame image-to-video.",
-        "If the user asks to render HTML/design into an image, call POST /api/v1/primitives/images/render-html. If the user asks to turn existing media URLs into a slideshow/video, call POST /api/v1/primitives/videos/render-slides. If the user asks to dedupe, camouflage, or apply small zoom/tilt/rotate/filter/tint transforms to an image or video for reuse, call POST /api/v1/primitives/media/dedupe with body { tracer, payload: { source_media_url, media_type?, effects?: { zoom?, tilt?, rotate?, saturation?, speed?, horizontal_flip?, contrast?, brightness?, hue_rotate?, blur? }, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Primitive media utility routes are also allowed directly here, including /videos/trim, /videos/remove-captions, /videos/extract-audio, /videos/probe, /videos/extract-frame, /videos/mute, /videos/replace-audio, /videos/concat, /audio/trim, /audio/probe, /audio/concat, and /audio/normalize. If the user asks to remove burned-in captions, subtitles, or on-screen text from a video, call POST /api/v1/primitives/videos/remove-captions with body { tracer, payload: { source_video_url } } — an async job that returns a durable caption-free MP4 and bills about $0.10 per 30 seconds of source video.",
+        "If the user asks to render HTML/design into an image, call POST /api/v1/primitives/images/render-html. If the user asks to turn existing media URLs into a slideshow/video, call POST /api/v1/primitives/videos/render-slides. If the user asks to dedupe, camouflage, or apply small zoom/tilt/rotate/filter/tint transforms to an image or video for reuse, call POST /api/v1/primitives/media/dedupe with body { tracer, payload: { source_media_url, media_type?, effects?: { zoom?, tilt?, rotate?, saturation?, speed?, horizontal_flip?, contrast?, brightness?, hue_rotate?, blur? }, tint_color?, tint_opacity?, width?, height?, duration_ms?, object_fit?, background_color?, output_format? }, webhook_url? }. Primitive media utility routes are also allowed directly here, including /videos/trim, /videos/remove-captions, /videos/extract-audio, /videos/probe, /videos/extract-frame, /videos/mute, /videos/replace-audio, /videos/concat, /audio/trim, /audio/probe, /audio/concat, and /audio/normalize. If the user asks to remove burned-in captions, subtitles, or on-screen text from a video, call POST /api/v1/primitives/videos/remove-captions with body { tracer, payload: { source_video_url } } — an async job that returns a durable caption-free MP4 and bills about $0.10 per 30 seconds of source video. Caption removal is capped at ~15 minutes of source and must NEVER be used on long-form video: when the user wants short clips out of a long video (a podcast, stream VOD, webinar, or a YouTube/TikTok/IG/X URL), call POST /clips/scan instead with body { source_url | temp_file_id | s3_key, prompt, ranges?: [\"MM:SS-MM:SS\"], target_duration_sec?, aspect?: \"9:16\"|\"16:9\"|\"4:3\"|\"1:1\", avoid_text?, tracer? } — target_duration_sec is a SOFT range (30 → 20-40s), ranges restrict the hunt to those source windows (big cost saver), aspect crops every clip, and avoid_text prefers text-free scenes via scene SELECTION (never caption removal on the source). The hunt is async (202 + scan_id): poll GET /clips/scan/:scanId, then browse GET /clips/feed?source=<source_video_id> or POST /clips/search. Hunts bill AWS compute only — the AI tagging runs on the user's own saved provider keys. To erase captions from a finished HUNTED clip, pass that short mp4 to /videos/remove-captions afterwards.",
         "Brainstorm primitives are also available directly here. If the user explicitly asks for hooks, angles, awareness-stage advice, a cold-start strategy questionnaire, or product-placement opportunities in a video, call the matching brainstorm primitive immediately instead of brainstorming in chat from memory. Use POST /api/v1/primitives/brainstorm/coldstart with body { tracer, payload: { user_message }, webhook_url? } when the user is clueless and needs foundational strategy questions. Use /brainstorm/awareness_stages with body { tracer, payload: { offer_description }, webhook_url? } when they are unsure what type of ads to make. Use /brainstorm/angles with body { tracer, payload: { offer_description, problem_awareness, solution_awareness }, webhook_url? } when they want persuasive ad angles; problem_awareness must be problem_unaware or problem_aware, and solution_awareness must be solution_unaware or solution_aware. Use /brainstorm/hooks with body { tracer, payload: { offer_description }, webhook_url? } when they are stuck on openings and want many hooks.",
         "Product placement is a first-class brainstorm primitive, just like angles and hooks. When the user asks to identify product-placement opportunities in a video, or to repurpose a video into a native ad for their product, prefer POST /api/v1/primitives/brainstorm/product_placement with body { tracer, payload: { source_video_url, offer_description }, webhook_url? }. source_video_url is the exact video to analyze — for the current composition, first call GET /api/v1/compositions/:forkId/remove-video-captions to pick the correct source (the ORIGINAL uploaded video vs the DECOMPOSED, caption-free video), then pass that URL. offer_description is the user's product/offer. This primitive watches the video and returns timestamped, native placement opportunities. It prefers a Gemini key for video understanding.",
         "BEFORE calling /brainstorm/product_placement for the CURRENT composition, first call the product_placement_context tool (or GET /api/v1/compositions/:forkId/product-placement.json). Decompose already scouted product-AGNOSTIC placement surfaces for this fork — real, grounded moments (timestamp, surface_type, surface_note, best_for, why_it_works). Use those surfaces to ground your answer and to seed the primitive: fold the strongest surfaces into offer_description (for example append 'Known native placement surfaces: 0:04 empty desk prop; 0:12 phone screen swap') so the product-specific pass builds on grounded moments instead of re-watching blind. If the user just wants a quick conversational take on where their product could go, the surfaces from product_placement_context are often enough to answer directly without the billable primitive.",

package/dist/src/frontend/homepage-view.js

@@ -11,9 +11,6 @@ function LibraryIcon() {
 function CalendarIcon() {
     return _jsxs("svg", { viewBox: "0 0 20 20", fill: "none", stroke: "currentColor", strokeWidth: "1.7", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("circle", { cx: "10", cy: "10", r: "7.2" }), _jsx("path", { d: "M10 6.3v4.1l2.8 1.7" })] });
 }
-function ClipsIcon() {
-    return _jsxs("svg", { viewBox: "0 0 20 20", fill: "none", stroke: "currentColor", strokeWidth: "1.7", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("rect", { x: "3", y: "4.5", width: "14", height: "11", rx: "1.5" }), _jsx("path", { d: "M3 8h14" }), _jsx("path", { d: "M6.2 4.7 4.6 8" }), _jsx("path", { d: "M9.6 4.7 8 8" }), _jsx("path", { d: "M13 4.7 11.4 8" })] });
-}
 function ChatIcon() {
     return _jsxs("svg", { viewBox: "0 0 20 20", fill: "none", stroke: "currentColor", strokeWidth: "1.7", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("path", { d: "M4.2 5.2a2 2 0 0 1 2-2h7.6a2 2 0 0 1 2 2v5.6a2 2 0 0 1-2 2H9.2l-4.1 3.1v-3.1a2 2 0 0 1-.9-1.7Z" }), _jsx("path", { d: "M7.3 7.1h5.4" }), _jsx("path", { d: "M7.3 9.6h3.7" })] });
 }
@@ -58,13 +55,11 @@ function PrimaryNav({ account }) {
         ? [
             { id: "discover", href: withAccountQuery("/discover", account.userId), label: "Discover", icon: _jsx(DiscoverIcon, {}) },
             { id: "library", href: withAccountQuery("/library", account.userId), label: "Library", icon: _jsx(LibraryIcon, {}) },
-            { id: "clips", href: "/clips", label: "Clips", icon: _jsx(ClipsIcon, {}) },
             { id: "calendar", href: withAccountQuery("/calendar", account.userId), label: "Calendar", icon: _jsx(CalendarIcon, {}) },
             { id: "settings", href: withAccountQuery("/settings", account.userId), label: "Settings", icon: _jsx(SettingsIcon, {}) }
         ]
         : [
             { id: "discover", href: "/discover", label: "Discover", icon: _jsx(DiscoverIcon, {}) },
-            { id: "clips", href: "/clips", label: "Clips", icon: _jsx(ClipsIcon, {}) },
             { id: "login", href: "/login", label: "Login", icon: _jsx(SettingsIcon, {}) }
         ];
     const menuItems = account.isLoggedIn

package/dist/src/page-shell.js

@@ -756,6 +756,53 @@ export function renderPageShell(input) {
         color: var(--muted);
       }
 
+      .view-toggle {
+        display: inline-flex;
+        flex: 0 0 auto;
+        gap: 4px;
+        padding: 3px;
+        border: 1px solid rgba(191, 164, 109, 0.28);
+        border-radius: 999px;
+        background: linear-gradient(180deg, rgba(247, 241, 230, 0.94), rgba(244, 236, 223, 0.96));
+        box-shadow:
+          inset 0 1px 0 rgba(255, 255, 255, 0.88),
+          0 8px 18px rgba(138, 102, 32, 0.08);
+      }
+
+      .view-toggle-tab {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-height: 38px;
+        padding: 0 18px;
+        border: 1px solid transparent;
+        border-radius: 999px;
+        background: transparent;
+        color: #6f6451;
+        text-decoration: none;
+        font-size: 0.9rem;
+        font-weight: 700;
+        font-family: inherit;
+        white-space: nowrap;
+        cursor: pointer;
+        box-shadow: none;
+        transition: background 160ms ease, color 160ms ease, border-color 160ms ease, box-shadow 160ms ease;
+      }
+
+      @media (hover: hover) {
+        .view-toggle-tab:hover {
+          transform: none;
+          color: var(--ink);
+        }
+      }
+
+      .view-toggle-tab.is-active {
+        border-color: rgba(232, 223, 204, 0.9);
+        background: rgba(255, 252, 247, 0.96);
+        color: var(--ink);
+        box-shadow: 0 8px 20px rgba(101, 73, 18, 0.08);
+      }
+
       .button,
       button,
       .link-button,

package/dist/src/primitive-registry.js

@@ -1403,6 +1403,13 @@ const videoRemoveCaptionsPrimitive = definePrimitive({
             }
             const probedDurationSeconds = Number(probeMetadata.durationSeconds ?? 0);
             const durationSeconds = Number.isFinite(probedDurationSeconds) && probedDurationSeconds > 0 ? probedDurationSeconds : 30;
+            // GhostCut is a per-FINISHED-CLIP tool, never a long-form pass. Clip
+            // hunting handles "no captions" as a scene-selection filter (avoid_text);
+            // after the hunt, apply caption removal to individual finished clips.
+            if (config.GHOSTCUT_MAX_DURATION_SEC > 0 && durationSeconds > config.GHOSTCUT_MAX_DURATION_SEC) {
+                throw new Error(`Caption removal is limited to videos up to ${Math.round(config.GHOSTCUT_MAX_DURATION_SEC / 60)} minutes (this source is ${Math.round(durationSeconds / 60)} min). ` +
+                    `For long-form video, hunt clips first (POST /clips/scan with avoid_text/no-captions guidance selects text-free scenes), then remove captions from the finished clips you keep.`);
+            }
             const cost = estimateGhostcutCostUsd(durationSeconds);
             ctx.logger.progress(0.12, "Submitting caption-removal task", {
                 durationSeconds: Number(durationSeconds.toFixed(3)),

package/dist/src/services/billing.js

@@ -167,6 +167,9 @@ function resolveCostCenterSlug(input) {
             || explicitSlug === "primitive_media_lambda"
             || explicitSlug === "job_runner_lambda"
             || explicitSlug === "step_functions_standard"
+            // Clip hunting (long-form → short-form): AWS compute only — the AI
+            // tagging/embedding spend is BYOK and deliberately NOT wallet-billed.
+            || explicitSlug === "clip_scan_lambda"
             ? explicitSlug
             : null;
     }