@mevdragon/vidfarm-devcli 0.6.0 → 0.7.0

package/dist/src/cli.js

@@ -43,6 +43,11 @@ Local editor loop:
   serve [template_id] [opts]  Boot the FULL editor locally (single origin, disk-backed).
                               Records + storage run on disk; render runs in-process on
                               this box for FREE (no cloud, no wallet charge).
+                              /discover and /library still list the CLOUD catalog —
+                              opening a cloud template seeds it onto local disk, and
+                              the editor's Render button can hand off to the cloud
+                              renderer (needs the cloud --api-key). Only the editor
+                              and its data are local.
                               With a template_id or --fork, pulls that composition
                               (or the template's default/shared decomposition) from
                               the cloud host onto local disk to edit offline.
@@ -51,8 +56,9 @@ Local editor loop:
     --key <api-key>           Bootstrap/browser key (default: VIDFARM_API_KEY or a dev key)
     --fork <id>               Pull + open a specific cloud fork
     --host <url>              Cloud host to pull from (default: ${DEFAULT_HOST})
-    --api-key <key>           Cloud key for the pull (default: VIDFARM_API_KEY)
+    --api-key <key>           Cloud key for pulls/library/cloud render (default: VIDFARM_API_KEY)
     --refetch                 Overwrite local composition with the cloud copy
+    --no-cloud                Fully local: no cloud catalog, seeding, or cloud render
     --no-open                 Don't auto-open the browser
   <template_id> [opts]      Alias for 'serve <template_id>' (boot the local editor)
   publish [template_id]     Push local composition.html/json to your fork  → PUT/PATCH composition + POST versions
@@ -104,8 +110,9 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --track <n>             Timeline layer index (auto if omitted)
     --x --y --width --height   Geometry as % (default full canvas 0/0/100/100)
     --object-fit <fit>      cover|contain|fill|none|scale-down (default cover)
-  ghostcut <forkId>         Read the two video sources: original vs      → GET  .../compositions/:forkId/ghostcut
-                            decomposed (caption-free), non-billing
+  remove-video-captions <forkId>   Read the two video sources:        → GET  .../compositions/:forkId/remove-video-captions
+                            original vs decomposed (caption-free),
+                            non-billing (alias: ghostcut)
   versions <forkId>         List immutable version snapshots             → GET  .../compositions/:forkId/versions
   snapshot <forkId>         Save the working state as a new version      → POST .../compositions/:forkId/versions
   render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/render
@@ -244,8 +251,9 @@ async function main() {
         case "decompose":
             await runDecomposeCommand(rest);
             return;
+        case "remove-video-captions":
         case "ghostcut":
-            await runGhostcutCommand(rest);
+            await runRemoveVideoCaptionsCommand(rest);
             return;
         case "versions":
             await runVersionsCommand(rest);
@@ -454,7 +462,10 @@ async function runServeCommand(argv) {
             share: { type: "string" },
             refetch: { type: "boolean", default: false },
             open: { type: "boolean", default: true },
-            "no-open": { type: "boolean", default: false }
+            "no-open": { type: "boolean", default: false },
+            // Disable the cloud passthrough entirely: /discover and /library list
+            // only local data and the editor offers no "Render in Cloud".
+            "no-cloud": { type: "boolean", default: false }
         }
     });
     const port = Number(parsed.values.port);
@@ -476,16 +487,27 @@ async function runServeCommand(argv) {
     const templateId = parsed.positionals[0];
     const forkFlag = parsed.values.fork;
     // Env MUST be set before importing runtime — config.ts reads it at module
-    // load. Force the fully-local drivers; keep any cloud creds already present
-    // in the environment so render passthrough still works.
+    // load. Force the fully-local drivers.
     process.env.RECORDS_DRIVER = "local";
     process.env.STORAGE_DRIVER = "local";
     process.env.AWS_S3_BUCKET = "";
+    // A dev-shell .env can carry the staging Step Functions ARN, which would
+    // silently route this box's renders to the cloud state machine. serve is
+    // local-render by definition — cloud rendering is the EXPLICIT
+    // render_target="cloud" upstream handoff (the editor's "Render in Cloud").
+    process.env.VIDFARM_JOB_STATE_MACHINE_ARN = "";
     process.env.VIDFARM_DATA_DIR = dataDir;
     process.env.VIDFARM_API_KEY = apiKey;
     process.env.PORT = String(port);
     if (!process.env.NODE_ENV)
         process.env.NODE_ENV = "development";
+    // Cloud passthrough: only the editor is local — /discover and /library keep
+    // listing the upstream (cloud) catalog, templates seed onto disk on demand,
+    // and the editor's Render button can hand off to the cloud renderer. The
+    // upstream key is the AMBIENT cloud key (never the local bootstrap key).
+    const cloudEnabled = !parsed.values["no-cloud"];
+    process.env.VIDFARM_UPSTREAM_HOST = cloudEnabled ? host : "";
+    process.env.VIDFARM_UPSTREAM_API_KEY = cloudEnabled ? (cloudApiKey ?? "") : "";
     const { startRuntime } = await import("./runtime.js");
     await startRuntime();
     // If a template/fork was requested, pull its composition from the cloud host
@@ -493,13 +515,14 @@ async function runServeCommand(argv) {
     // resolves it. Best-effort: a failure just drops us to /discover.
     let openTemplateId = templateId;
     let openForkId = forkFlag;
-    if (templateId || forkFlag) {
+    if ((templateId || forkFlag) && !cloudEnabled) {
+        console.warn("[vidfarm] serve: --no-cloud set — skipping cloud seed of the requested template/fork.");
+    }
+    else if (templateId || forkFlag) {
         try {
             const seeded = await seedForkFromCloud({
-                host,
                 templateId,
                 forkId: forkFlag,
-                cloudApiKey,
                 shareToken: parsed.values.share,
                 bootstrapKey: apiKey,
                 refetch: parsed.values.refetch
@@ -518,105 +541,45 @@ async function runServeCommand(argv) {
         ? `/editor/${encodeURIComponent(openTemplateId)}${openForkId ? `?fork=${encodeURIComponent(openForkId)}` : ""}`
         : "/discover";
     const openUrl = `${base}/auto-login?api_key=${encodeURIComponent(apiKey)}&redirect=${encodeURIComponent(editorPath)}`;
-    printServeBanner({ base, dataDir, openUrl, editorPath });
+    printServeBanner({ base, dataDir, openUrl, editorPath, cloud: cloudEnabled ? { host, hasKey: Boolean(cloudApiKey) } : null });
     const shouldOpen = parsed.values.open && !parsed.values["no-open"];
     if (shouldOpen)
         openInBrowser(openUrl);
     // startRuntime() keeps the process alive via its HTTP server; nothing else to do.
 }
 // Pull a cloud fork's composition onto local disk and create the local
-// template + fork records so the editor resolves it. The fork is either an
-// explicit --fork or the template's default fork (which may be another user's
-// public decomposition). Media stays on cloud URLs — only the composition +
-// records are localized. Runs in-process after startRuntime(), so it shares the
-// server's disk-backed records/storage singletons.
+// template + fork records so the editor resolves it. Thin wrapper over
+// services/upstream.ts seedFromUpstream (which reads VIDFARM_UPSTREAM_HOST/
+// _API_KEY — set above from --host/--api-key). Runs in-process after
+// startRuntime(), so it shares the server's disk-backed records/storage.
 async function seedForkFromCloud(input) {
-    const { serverlessRecords } = await import("./services/serverless-records.js");
-    const { StorageService } = await import("./services/storage.js");
     const { ServerlessAuthService } = await import("./services/serverless-auth.js");
-    const storage = new StorageService();
-    const auth = new ServerlessAuthService();
+    const { seedFromUpstream } = await import("./services/upstream.js");
     // Ensure the local bootstrap customer exists and grab its id to own the seed.
-    const customer = await auth.authenticate(input.bootstrapKey);
-    const authHeaders = buildAuthHeaders({ apiKey: input.cloudApiKey, shareToken: input.shareToken });
-    // 1. Resolve the source fork: explicit --fork wins, else the template's
-    //    default fork (grabs the shared decomposition even if another user owns it).
-    let cloudForkId = input.forkId ?? null;
-    if (!cloudForkId && input.templateId) {
-        cloudForkId = await resolveForkId({ host: input.host, templateId: input.templateId, apiKey: input.cloudApiKey, shareToken: input.shareToken });
-    }
-    if (!cloudForkId) {
-        console.warn("[vidfarm] serve: no --fork and no default fork resolvable from cloud; starting empty.");
-        return null;
-    }
-    // 2. Read the serialized fork for its template id + title.
-    const forkMetaRes = await fetch(`${input.host}/api/v1/compositions/${encodeURIComponent(cloudForkId)}`, { headers: authHeaders });
-    const forkMeta = forkMetaRes.ok ? (await forkMetaRes.json().catch(() => null)) : null;
-    const templateId = input.templateId ?? (typeof forkMeta?.template_id === "string" ? forkMeta.template_id : null);
-    if (!templateId || !templateId.startsWith("template_")) {
-        console.warn(`[vidfarm] serve: could not determine a template id for fork ${cloudForkId}; starting empty.`);
-        return null;
-    }
-    const title = (typeof forkMeta?.title === "string" && forkMeta.title) || `Local · ${templateId}`;
-    // 3. Materialize the local template record (the editor 404s without it).
-    const existingTemplate = await serverlessRecords.getTemplate(templateId);
-    if (!existingTemplate) {
-        await serverlessRecords.createTemplate({
-            id: templateId,
-            inspirationId: `local:${templateId}`,
-            customerId: customer.id,
-            originalUrl: typeof forkMeta?.original_url === "string" ? forkMeta.original_url : "",
-            sourceHost: "local",
-            title,
-            visibility: "public"
-        });
-    }
-    // 4. Materialize the local fork (reuse the cloud id for stable URLs).
-    const localForkId = cloudForkId;
-    const existingFork = await serverlessRecords.getCompositionFork(localForkId);
-    if (!existingFork) {
-        await serverlessRecords.createCompositionFork({
-            id: localForkId,
-            customerId: customer.id,
-            templateId,
-            title,
-            visibility: "private"
-        });
-    }
-    // 5. Pull composition.html/json onto disk (skip if present unless --refetch,
-    //    so local edits aren't clobbered on re-serve).
-    const htmlKey = storage.compositionForkWorkingKey(localForkId, "composition.html");
-    const jsonKey = storage.compositionForkWorkingKey(localForkId, "composition.json");
-    const hasLocalHtml = Boolean(await storage.readText(htmlKey));
-    if (!hasLocalHtml || input.refetch) {
-        const htmlRes = await fetch(`${input.host}/api/v1/compositions/${encodeURIComponent(cloudForkId)}/composition.html`, { headers: authHeaders });
-        if (!htmlRes.ok) {
-            console.warn(`[vidfarm] serve: could not fetch composition.html for ${cloudForkId} (${htmlRes.status}); starting empty.`);
-            return null;
-        }
-        await storage.putText(htmlKey, await htmlRes.text(), "text/html; charset=utf-8");
-        const jsonRes = await fetch(`${input.host}/api/v1/compositions/${encodeURIComponent(cloudForkId)}/composition.json`, { headers: authHeaders });
-        if (jsonRes.ok)
-            await storage.putBuffer(jsonKey, Buffer.from(await jsonRes.text(), "utf8"), "application/json");
-        console.log(`[vidfarm] seeded fork ${localForkId} from ${input.host}`);
-    }
-    else {
-        console.log(`[vidfarm] fork ${localForkId} already local (use --refetch to overwrite)`);
-    }
-    // 6. Point the template's default fork at the local copy so a bare
-    //    /editor/:templateId resolves it too.
-    await serverlessRecords.stampDefaultForkIfUnset({ templateId, forkId: localForkId });
-    return { templateId, forkId: localForkId };
+    const customer = await new ServerlessAuthService().authenticate(input.bootstrapKey);
+    return seedFromUpstream({
+        customerId: customer.id,
+        templateId: input.templateId,
+        forkId: input.forkId,
+        shareToken: input.shareToken,
+        refetch: input.refetch
+    });
 }
 function printServeBanner(input) {
     const line = `${DIM}${"─".repeat(74)}${RESET}`;
     console.log("");
     console.log(line);
-    console.log(`${BOLD}${GREEN}  Vidfarm local server${RESET}  ${DIM}(fully local — records + storage on disk)${RESET}`);
+    console.log(`${BOLD}${GREEN}  Vidfarm local server${RESET}  ${DIM}(local editor — records + storage on disk)${RESET}`);
     console.log(line);
     console.log(`  server      ${input.base}`);
     console.log(`  data dir    ${input.dataDir}`);
     console.log(`  render      ${DIM}local (in-process HyperFrames render — free, no cloud charge)${RESET}`);
+    if (input.cloud) {
+        console.log(`  cloud       ${input.cloud.host} ${DIM}(/discover + /library list the cloud catalog; templates seed locally on open${input.cloud.hasKey ? "; Render can hand off to the cloud renderer" : "; set VIDFARM_API_KEY for /library + cloud render"})${RESET}`);
+    }
+    else {
+        console.log(`  cloud       ${DIM}off (--no-cloud) — local data only${RESET}`);
+    }
     console.log("");
     console.log(`  ${DIM}Agents: edit composition files under ${input.dataDir}/storage — the`);
     console.log(`  browser live-reloads on save. Multiple forks can be edited at once.${RESET}`);
@@ -1249,18 +1212,18 @@ async function runDecomposeCommand(argv) {
     });
     assertApiOk(result, "decompose");
     if (!ctx.json && result.json?.ghostcut_pending) {
-        console.log(`${DIM}GhostCut subtitle-removal is running in the background — poll \`vidfarm api POST /api/v1/compositions/${forkId}/ghostcut-poll\` or GET .../ghostcut until done.${RESET}`);
+        console.log(`${DIM}Subtitle removal (GhostCut) is running in the background — poll \`vidfarm api POST /api/v1/compositions/${forkId}/remove-video-captions-poll\` or GET .../remove-video-captions until done.${RESET}`);
     }
     emitResult(result, ctx.json);
 }
-async function runGhostcutCommand(argv) {
+async function runRemoveVideoCaptionsCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
     const forkId = parsed.positionals[0];
     if (!forkId)
-        throw new Error("ghostcut requires a fork id.");
+        throw new Error("remove-video-captions requires a fork id.");
     const ctx = commonContext(parsed.values);
-    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/ghostcut`, auth: ctx.auth });
-    assertApiOk(result, "ghostcut");
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/remove-video-captions`, auth: ctx.auth });
+    assertApiOk(result, "remove-video-captions");
     emitResult(result, ctx.json);
 }
 async function runVersionsCommand(argv) {

package/dist/src/config.js

@@ -68,6 +68,13 @@ 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),
+    // 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.
+    // Set by the serve command from --host + the ambient cloud VIDFARM_API_KEY;
+    // never set on deployed environments.
+    VIDFARM_UPSTREAM_HOST: z.string().optional(),
+    VIDFARM_UPSTREAM_API_KEY: z.string().optional(),
     RAPIDAPI_KEY: z.string().optional(),
     RAPIDAPI_VIDEO_DOWNLOAD_URL: z.string().url().default("https://snap-video3.p.rapidapi.com/download"),
     RAPIDAPI_VIDEO_DOWNLOAD_HOST: z.string().default("snap-video3.p.rapidapi.com"),

package/dist/src/editor-chat.js

@@ -41,9 +41,9 @@ 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/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 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.",
         "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/ghostcut 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.",
+        "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.",
         "You can ALSO satisfy a product-placement or video-analysis request WITHOUT the dedicated primitive: if the user attaches or references a video and you want to reason about it directly, you may analyze the attached video yourself and describe placement opportunities in chat. Support both paths — use the /brainstorm/product_placement primitive for a durable, structured, billable artifact the user can save, and direct multimodal reasoning for quick, conversational answers. When the user wants a saved/structured result or many opportunities, prefer the primitive.",
         "When brainstorm jobs finish and the response includes a JSON artifact, tell the user to open and review that JSON in the chat UI because it contains the structured brainstorm output.",
@@ -74,7 +74,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "AI generations in flight are listed in editor_context.pending_generations (each has layer_key, media_type, status, job_id, start, duration, prompt, and error). Use it to see what is still rendering, to avoid re-generating something already queued, and to report progress. A status of 'error' with an error message means that generation failed — offer to retry (a fresh generate_layer) or explain the failure; a resolved generation drops out of the list once its media is swapped in.",
         "Only use the http_request→add_layer flow (call the primitive route, then editor_action add_layer with src=<returned URL>) for media that ALREADY has a URL — e.g. /videos/render-slides slideshows, /images/edit revisions, /videos/download results, or a My Files asset. For net-new AI /videos/generate or /images/generate media destined for the timeline, prefer generate_layer so the async poll+placement is handled for you. Never invent media URLs or describe media that was not returned by a tool result.",
         "CAST / CHARACTER CONSISTENCY: the COMPOSITION BRIEF (stable template context in the system prompt) may include a `cast` array — the recurring people/characters identified from the source video by the decompose 2nd pass. Each entry has: slug, name, description (detailed appearance for consistent regeneration), appears_in (scene slugs), is_primary (the single most central subject), reference_url (that person isolated on a transparent background — the preferred reference), and still_url (the raw frame they were pulled from). When the user refers to an on-screen person by pronoun or description ('the same girl', 'her', 'that guy', 'the narrator', 'keep the character'), resolve them against the brief's cast: match by description/name/scene, or default to the is_primary member when the reference is ambiguous. Then, to generate a NEW clip of that same person AND place it on the timeline, call editor_action action_type=generate_layer with media_type='video', prompt describing the requested action/scene while restating their key appearance from the cast description so the model holds identity, and input_references=[reference_url] (fallback: [still_url]); for a NEW image use media_type='image' with prompt_attachments=[reference_url]. (If you only need the media as a reusable URL and are NOT placing it on this timeline, you may instead call POST /api/v1/primitives/videos/generate or /images/generate directly with the same reference in payload.input_references / payload.prompt_attachments.) Never pass a webpage/social URL as a reference — only the cast reference_url/still_url or another direct image asset URL.",
-        "If the composition brief's cast is absent or empty, or the referenced person is not in it, fall back to extracting a still yourself: call GET /api/v1/compositions/:forkId/ghostcut to pick the correct source video, then POST /api/v1/primitives/videos/extract-frame with source_video_url set to that URL and at_ms at a moment the person is clearly on screen (use video_context scene timings), then feed the returned image URL as generate_layer input_references (video) or prompt_attachments (image) exactly as above. Prefer the cast reference_url when present because it is already isolated from other people and reusable.",
+        "If the composition brief's cast is absent or empty, or the referenced person is not in it, fall back to extracting a still yourself: call GET /api/v1/compositions/:forkId/remove-video-captions to pick the correct source video, then POST /api/v1/primitives/videos/extract-frame with source_video_url set to that URL and at_ms at a moment the person is clearly on screen (use video_context scene timings), then feed the returned image URL as generate_layer input_references (video) or prompt_attachments (image) exactly as above. Prefer the cast reference_url when present because it is already isolated from other people and reusable.",
         "When placing generated character media on the timeline, prefer generate_layer (it applies the placement rules for you): to drop the character into a blank moment use intent='fill_gap' with start/duration on a timeline_gaps span; to swap them into an existing scene use intent='replace_layer' with replace_layer_key (its timing and full-canvas geometry are copied automatically). Always set aspect_ratio to the canvas (e.g. 9:16 for vertical) so the clip fills the frame. Only when you already have a finished media URL should you fall back to add_layer with explicit collision-free start/duration and full-canvas geometry (x=0, y=0, width=100, height=100) for a timeline-proxy/full-canvas replacement.",
         "Use set_layer_visual for geometry (x, y, width, height in %, plus font_size and border_radius in px). Use set_layer_style for text/color styling (color, background, background_style plain|outline|highlight-solid|highlight-translucent, font_family, font_weight, italic, underline, text_align, border_radius, font_size). Use set_layer_media to swap src, volume, muted, playback_start, or object_fit on media layers. Use set_layer_timing for start, duration, track index, playback_start.",
         "Use duplicate_layer to clone an existing layer; supply layer_key for the source, and optionally start/duration/track/label on the duplicate. Use split_layer with layer_key and split_time to cut at a moment in the timeline. Use group_layers with layer_keys (>=2) and optional group_label; ungroup_layers with layer_keys of any grouped members.",
@@ -83,7 +83,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "When you REPLACE an existing layer with a different kind (e.g., remove a video and add an image in its place), first read the removed layer's `track`, `start`, `duration`, `x`, `y`, `width`, `height`, and (for media) `playback_start` from editor_context, then pass ALL of them to add_layer. If the removed layer has `is_full_canvas: true` OR `is_timeline_proxy: true`, the replacement MUST be full canvas — set x=0, y=0, width=100, height=100. Timeline-proxy videos always render full canvas (100%×100%) at publish time even though editor_context may show them as tiny placeholders — trust the `is_timeline_proxy` / `is_full_canvas` flags. Skipping the geometry leaves you with a small floating overlay while the rest of the frame is black.",
         "Rule of thumb for replacements: (1) copy the removed layer's track (higher = drawn on top; keep the same so overlays stay in order), (2) copy start/duration exactly, (3) copy x/y/width/height exactly (or use 0/0/100/100 for full-canvas), (4) for video→image conversions, drop playback_start (images have no timeline). Never use the AI default geometry (12/18/54/32) for a replacement.",
         "When you simply want to change a layer's media without moving it, prefer set_layer_media (kind must match: video↔video, image↔image, audio↔audio) — it keeps the same node, id, track, and geometry.",
-        "CONTEXT AVAILABLE FOR USE — this composition can expose TWO video sources plus a text/scene context: (1) the ORIGINAL video — the raw uploaded source, with any baked-in subtitles/captions; (2) the DECOMPOSED video — a processed, caption-free copy Vidfarm produces asynchronously (subtitles removed) that the composition timeline renders from; and (3) the decomposed video context (transcript + per-scene visual descriptions + viral DNA) available via the video_context tool. The original and the decomposed video are NOT the same URL, and you should not carry both URLs in default context. When the user asks to reuse, re-render, or feed the composition's video into a primitive route (image extract, ai video edit, media/dedupe, video trim, video probe, etc.), call GET /api/v1/compositions/:forkId/ghostcut FIRST to read { status, original_source_url, mirrored_url } and pick correctly — here original_source_url is the ORIGINAL video and mirrored_url is the DECOMPOSED video: prefer the DECOMPOSED video (mirrored_url) when status=\"done\" and the downstream call should be caption-free (thumbnails, style references, re-cut hooks); prefer the ORIGINAL video (original_source_url) when the user explicitly wants the raw upload (branded intros, provenance, when captions are the subject matter). If status is \"pending\" and the user is not blocked on subtitle removal, use the ORIGINAL video and mention that the decomposed (caption-free) video is still processing. If status is \"none\" or \"failed\", there is no decomposed video yet — use the ORIGINAL video only. Do not call POST /ghostcut-poll unless the user explicitly asks to advance the subtitle-removal job.",
+        "CONTEXT AVAILABLE FOR USE — this composition can expose TWO video sources plus a text/scene context: (1) the ORIGINAL video — the raw uploaded source, with any baked-in subtitles/captions; (2) the DECOMPOSED video — a processed, caption-free copy Vidfarm produces asynchronously (subtitles removed) that the composition timeline renders from; and (3) the decomposed video context (transcript + per-scene visual descriptions + viral DNA) available via the video_context tool. The original and the decomposed video are NOT the same URL, and you should not carry both URLs in default context. When the user asks to reuse, re-render, or feed the composition's video into a primitive route (image extract, ai video edit, media/dedupe, video trim, video probe, etc.), call GET /api/v1/compositions/:forkId/remove-video-captions FIRST to read { status, original_source_url, mirrored_url } and pick correctly — here original_source_url is the ORIGINAL video and mirrored_url is the DECOMPOSED video: prefer the DECOMPOSED video (mirrored_url) when status=\"done\" and the downstream call should be caption-free (thumbnails, style references, re-cut hooks); prefer the ORIGINAL video (original_source_url) when the user explicitly wants the raw upload (branded intros, provenance, when captions are the subject matter). If status is \"pending\" and the user is not blocked on subtitle removal, use the ORIGINAL video and mention that the decomposed (caption-free) video is still processing. If status is \"none\" or \"failed\", there is no decomposed video yet — use the ORIGINAL video only. Do not call POST /remove-video-captions-poll unless the user explicitly asks to advance the subtitle-removal job. To strip burned-in captions from any OTHER video URL (not this fork's decompose flow), use the POST /api/v1/primitives/videos/remove-captions primitive instead.",
         "The OPTIONAL video_context tool returns this fork's decomposed video context: the source video's verbatim audio transcript (full text plus timestamped segments), a literal visual description of every scene, per-scene transcript excerpts, and viral DNA. Call it with the fork id from editor_context whenever the user asks what the source video says or shows, when writing/translating captions, hooks, or dubs that must match the spoken audio, or when you need scene-by-scene grounding before planning timeline edits. It is read-only and non-billing, so prefer it over guessing from frames or memory. If it returns status=\"none\", the fork was never smart-decomposed — offer to run POST /api/v1/compositions/:forkId/auto-decompose first. The same data is available via GET /api/v1/compositions/:forkId/video-context.json through http_request (useful for other forks).",
         "TEMPLATE FORMAT — MATCH IT WHEN WRITING TEXT: the COMPOSITION BRIEF (stable template context in the system prompt) carries composition_context — WHAT THIS TEMPLATE IS: its format/genre and narrative arc (trend_tagline, hook, retention, payoff, preserve, avoid). ALWAYS read it before writing or adjusting ANY captions, text layers, or on-screen copy, and make your copy fit the template's format and voice — do NOT default to generic product/app ad copy. The format dictates the caption style: a text-message / DM / iMessage conversation template's captions must read like short back-and-forth chat messages between people (in-character, conversational), a 'story time' / talking-head template reads like first-person spoken narration, a listicle reads like punchy numbered items, a fake-news / headline template reads like a news chyron, etc. `preserve` usually names format cues that must stay (e.g. the messaging-bubble layout); `avoid` names what to keep out. When the template's format is a conversation, skit, or roleplay, keep the captions in that voice and only weave the product in the way that format allows (subtly, in-dialogue) rather than replacing the messages with feature bullets. If the brief's composition_context is thin or you are unsure what the video actually shows, call video_context (scene visual descriptions + transcript) to ground the format BEFORE writing captions.",
         "MY FILES: the user has a personal file library ('My Files') of uploaded assets — videos (mp4/mov/webm), images (png/jpg/jpeg/gif/webp/svg), audio (mp3/wav/m4a/aac), and documents (pdf/md/txt/csv) — organized into virtual folders. Use the browse_files tool to explore AND write it: call action=list (optionally with folder_path) to see what files and folders exist, action=read with a file_id (copied from a prior list) to fetch one file, and action=write with file_name + content (+ optional folder_path) to SAVE a text file. When the user references their own footage, brand assets, logos, music, a brief, or a script ('use my product photo', 'the video I uploaded', 'my brand logo', 'the script in my files'), browse_files list first to find it rather than asking them to re-upload or paste a URL. For text files (md/txt/csv/srt/vtt/json), read returns the full text_content inline so you can read a brief or script directly. For images/video/audio/pdf, read returns only a durable view_url — use that URL as media: drop it into the timeline via editor_action add_layer/set_layer_media, or pass it into primitive routes (images/edit source_image_url, videos/generate input_references, videos/download). Never invent file ids or view URLs — always list to discover the real ones first.",

package/dist/src/primitive-registry.js

@@ -6,6 +6,7 @@ import { z } from "zod";
 import { config } from "./config.js";
 import { definePrimitive } from "./primitive-sdk.js";
 import { PrimitiveMediaLambdaService } from "./services/primitive-media-lambda.js";
+import { estimateGhostcutCostUsd, isGhostcutConfigured, pollStatus as pollGhostcutStatus, submitSubtitleRemoval } from "./services/ghostcut.js";
 import { buildHtmlImageCompositionHtml, buildMediaDedupeCompositionHtml, DEDUPE_DEFAULT_EFFECTS } from "./primitives/hyperframes-media.js";
 const imageProviderSchema = z.enum(["openai", "gemini", "openrouter"]);
 const videoProviderSchema = z.enum(["openai", "gemini", "openrouter"]);
@@ -360,6 +361,9 @@ const trimAudioPayloadSchema = z.object({
 const probeVideoPayloadSchema = z.object({
     source_video_url: mediaSourceUrlSchema
 });
+const removeVideoCaptionsPayloadSchema = z.object({
+    source_video_url: mediaSourceUrlSchema
+});
 const probeAudioPayloadSchema = z.object({
     source_audio_url: mediaSourceUrlSchema
 });
@@ -477,6 +481,7 @@ const PRIMITIVE_VIDEO_RENDER_SLIDES_ID = "primitive:video_render_slides";
 const PRIMITIVE_VIDEO_NORMALIZE_ID = "primitive:video_normalize";
 const PRIMITIVE_VIDEO_DOWNLOAD_ID = "primitive:video_download";
 const PRIMITIVE_VIDEO_TRIM_ID = "primitive:video_trim";
+const PRIMITIVE_VIDEO_REMOVE_CAPTIONS_ID = "primitive:video_remove_captions";
 const PRIMITIVE_VIDEO_EXTRACT_AUDIO_ID = "primitive:video_extract_audio";
 const PRIMITIVE_AUDIO_TRIM_ID = "primitive:audio_trim";
 const PRIMITIVE_VIDEO_PROBE_ID = "primitive:video_probe";
@@ -1222,6 +1227,125 @@ const videoTrimPrimitive = definePrimitive({
         }
     }
 });
+// GhostCut task polling budget. The job runner lambda has a 15-minute
+// timeout; probe + submit + mirror take up the rest. GhostCut usually clears
+// a sub-3-minute clip in a few minutes.
+const REMOVE_CAPTIONS_POLL_TIMEOUT_MS = 12 * 60 * 1000;
+const REMOVE_CAPTIONS_POLL_INTERVAL_MS = 5000;
+// Removes burned-in captions/subtitles/on-screen text from a source video via
+// the GhostCut inpainting service — the same plumbing auto-decompose uses
+// through src/services/ghostcut.ts. Unlike the fork-scoped
+// /remove-video-captions(-poll) composition routes, where the CLIENT drives
+// completion to keep per-request lambda time bounded, this primitive runs
+// inside the job runner and polls GhostCut to completion itself.
+const videoRemoveCaptionsPrimitive = definePrimitive({
+    id: PRIMITIVE_VIDEO_REMOVE_CAPTIONS_ID,
+    kind: "video_remove_captions",
+    operations: {
+        run: {
+            description: "Remove burned-in captions/subtitles/on-screen text from a source video into a reusable caption-free platform MP4.",
+            inputSchema: removeVideoCaptionsPayloadSchema,
+            workflow: "run"
+        }
+    },
+    jobs: {
+        async run(ctx, input) {
+            const payload = removeVideoCaptionsPayloadSchema.parse(input);
+            if (!isGhostcutConfigured()) {
+                throw new Error("Caption removal is unavailable: GHOSTCUT_KEY/GHOSTCUT_SECRET are not configured on this deployment.");
+            }
+            // Probe first: confirms the source actually has a video stream and
+            // captures the duration that prices the GhostCut task (per-30s chunks).
+            ctx.logger.progress(0.05, "Probing source video");
+            const probed = await executePrimitiveMediaOperation(ctx, {
+                operation: "video_probe",
+                payload: { source_video_url: payload.source_video_url },
+                outputKey: "probe.json"
+            });
+            const probeMetadata = (probed.metadata ?? {});
+            if (probeMetadata.hasVideo === false) {
+                throw new Error("source_video_url has no video stream — caption removal only works on videos.");
+            }
+            const probedDurationSeconds = Number(probeMetadata.durationSeconds ?? 0);
+            const durationSeconds = Number.isFinite(probedDurationSeconds) && probedDurationSeconds > 0 ? probedDurationSeconds : 30;
+            const cost = estimateGhostcutCostUsd(durationSeconds);
+            ctx.logger.progress(0.12, "Submitting caption-removal task", {
+                durationSeconds: Number(durationSeconds.toFixed(3)),
+                estimatedChunks: cost.chunks,
+                estimatedUsd: cost.usd
+            });
+            const submission = await submitSubtitleRemoval(payload.source_video_url);
+            const startedAtMs = Date.now();
+            let cleanedVideoUrl = null;
+            while (cleanedVideoUrl === null) {
+                if (Date.now() - startedAtMs > REMOVE_CAPTIONS_POLL_TIMEOUT_MS) {
+                    throw new Error(`GhostCut task ${submission.taskId} did not finish within ${Math.round(REMOVE_CAPTIONS_POLL_TIMEOUT_MS / 60000)} minutes.`);
+                }
+                const status = await pollGhostcutStatus(submission.taskId);
+                if (status.state === "failed") {
+                    throw new Error(`GhostCut task ${submission.taskId} failed: ${status.reason}`);
+                }
+                if (status.state === "done") {
+                    cleanedVideoUrl = status.videoUrl;
+                    break;
+                }
+                const upstreamProgress = Math.max(0, Math.min(100, status.progress));
+                ctx.logger.progress(0.15 + (upstreamProgress / 100) * 0.65, "Removing burned-in captions", {
+                    taskId: submission.taskId,
+                    upstreamProgress
+                });
+                await new Promise((resolve) => setTimeout(resolve, REMOVE_CAPTIONS_POLL_INTERVAL_MS));
+            }
+            // GhostCut hosts results on a short-lived third-party CDN — mirror the
+            // cleaned MP4 into platform storage so the output URL is durable.
+            ctx.logger.progress(0.85, "Mirroring caption-free video to platform storage");
+            const remoteVideo = await fetchRemoteBinary(cleanedVideoUrl, "video/mp4");
+            const stored = await storePrimitiveVideo(ctx, {
+                key: "captions-removed.mp4",
+                bytes: remoteVideo.bytes,
+                contentType: "video/mp4",
+                metadata: {
+                    primitive: "video_remove_captions",
+                    operation: "remove-video-captions",
+                    source_video_url: payload.source_video_url,
+                    ghostcut_task_id: submission.taskId
+                }
+            });
+            await ctx.billing.record({
+                type: "cpu_estimate",
+                costUsd: cost.usd,
+                costCenterSlug: "ghostcut_subtitle_removal",
+                idempotencyKey: `ghostcut_subtitle_removal:${submission.taskId}`,
+                occurredAtMs: Date.now(),
+                metadata: {
+                    operation: "remove-video-captions",
+                    source_video_url: payload.source_video_url,
+                    duration_seconds: Number(durationSeconds.toFixed(3)),
+                    chunk_count: cost.chunks,
+                    usd_per_chunk: cost.usdPerChunk,
+                    chunk_seconds: 30,
+                    task_id: submission.taskId
+                }
+            });
+            ctx.logger.progress(1, "Caption removal complete", { videoUrl: stored.url });
+            return {
+                progress: 1,
+                output: {
+                    files: compactUrls([payload.source_video_url, stored.url]),
+                    sourceVideoUrl: payload.source_video_url,
+                    captionsRemovedVideoUrl: stored.url,
+                    primary_file_url: stored.url,
+                    video: {
+                        file_url: stored.url,
+                        content_type: stored.contentType,
+                        duration_seconds: Number(durationSeconds.toFixed(3)),
+                        ghostcut_task_id: submission.taskId
+                    }
+                }
+            };
+        }
+    }
+});
 const videoExtractAudioPrimitive = definePrimitive({
     id: PRIMITIVE_VIDEO_EXTRACT_AUDIO_ID,
     kind: "video_extract_audio",
@@ -1864,6 +1988,7 @@ class PrimitiveRegistry {
         [videoNormalizePrimitive.id, videoNormalizePrimitive],
         [videoDownloadPrimitive.id, videoDownloadPrimitive],
         [videoTrimPrimitive.id, videoTrimPrimitive],
+        [videoRemoveCaptionsPrimitive.id, videoRemoveCaptionsPrimitive],
         [videoExtractAudioPrimitive.id, videoExtractAudioPrimitive],
         [audioTrimPrimitive.id, audioTrimPrimitive],
         [videoProbePrimitive.id, videoProbePrimitive],