videoclaw 3.0.0-alpha.1

package/dist/video/execution-runtime.js

@@ -0,0 +1,750 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { artifactPathFor } from './artifact-store.js';
+import { readSceneCandidatesArtifact } from './scene-candidate-store.js';
+import { readSceneSelectionArtifact } from './scene-selection-store.js';
+import { readSeedanceAssets } from './seedance-asset-library.js';
+import { readFlowCharacters } from './flow-character-library.js';
+import { assertReferenceBudget } from './native-seedance.js';
+import { assertRouteRequestValid, isOmniFirstFrameEnabled } from './provider-platform/route-capabilities.js';
+import { resolveProjectWorkspace } from './workspace.js';
+import { augmentPromptWithContinuity } from './gemini-continuity.js';
+import { repasteContinuityDescriptors, resolveAssetTags } from './prompt-rules.js';
+import { extractFlowMarkers, injectFlowCharacterMarkers, planFlowCharacterSlots, stripFlowMarkers, } from './flow-markers.js';
+import { buildAssetTagLookup } from './asset-tag-lookup.js';
+import { listCharacterProfiles } from './characters.js';
+import { readEnvironmentAssets } from './environment-assets.js';
+import { readVoiceClones } from './voice-clone.js';
+import { hostChainSeedAsImage, defaultChainSeedHostDeps, } from './seedance-chain-host.js';
+function adapterEnvVarForRoute(routeId) {
+    switch (routeId) {
+        case 'veo-useapi':
+            return 'VCLAW_VEO_USEAPI_ADAPTER';
+        case 'seedance-direct':
+            return 'VCLAW_SEEDANCE_DIRECT_ADAPTER';
+        case 'runway-useapi':
+            return 'VCLAW_RUNWAY_USEAPI_ADAPTER';
+        case 'dreamina-useapi':
+            return 'VCLAW_DREAMINA_USEAPI_ADAPTER';
+    }
+}
+function builtinAdapterCommandForRoute(routeId) {
+    if (!(routeId === 'seedance-direct' || routeId === 'veo-useapi' || routeId === 'runway-useapi' || routeId === 'dreamina-useapi')) {
+        return null;
+    }
+    const scriptPath = fileURLToPath(new URL('../cli/provider-adapter.js', import.meta.url));
+    return `${JSON.stringify(process.execPath)} ${JSON.stringify(scriptPath)} --route ${routeId}`;
+}
+function resolveAdapterCommand(routeId, env) {
+    const override = env[adapterEnvVarForRoute(routeId)];
+    if (override && override.trim()) {
+        return override;
+    }
+    const builtin = builtinAdapterCommandForRoute(routeId);
+    if (builtin) {
+        return builtin;
+    }
+    throw new Error(`Live execution for ${routeId} requires ${adapterEnvVarForRoute(routeId)} to point at an adapter command.`);
+}
+function unique(values) {
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+/**
+ * Assemble a scene's reference set, merging continuity + identity instead of
+ * choosing one. A chain-from-prev keyframe video (when present) leads so
+ * downstream adapters treat it as the primary seed; character Asset:// identity
+ * refs follow. Only the "assets + chain" case differs from legacy behavior —
+ * the other three branches are byte-identical to the prior either/or.
+ *
+ * Routing note: on seedance-direct, classifyReferencePaths sends Asset:// to
+ * reference_images and the .mp4 keyframe to reference_videos, so the merged
+ * array lands in the correct provider slots within the ≤9 img / ≤3 vid budget.
+ */
+export function resolveSceneReferencePaths(input) {
+    const { resolvedAssetUris, chainSeedPath, packetOrBaseReferencePaths, additionalReferencePaths = [] } = input;
+    // The image-identity "winner" set (Asset:// URIs / @tag image refs) replaces the
+    // base/packet refs as before; voice clips are appended on top of whichever wins.
+    const base = resolvedAssetUris.length > 0
+        ? (chainSeedPath ? [chainSeedPath, ...resolvedAssetUris] : resolvedAssetUris)
+        : (chainSeedPath ? [chainSeedPath, ...packetOrBaseReferencePaths] : packetOrBaseReferencePaths);
+    return unique([...base, ...additionalReferencePaths]);
+}
+const REFERENCE_VIDEO_EXTS = new Set(['.mp4', '.mov', '.webm', '.avi', '.mkv']);
+const REFERENCE_AUDIO_EXTS = new Set(['.mp3', '.wav', '.m4a', '.aac', '.flac', '.ogg']);
+// Routes that consume a blank-video-with-audio voice clone as a video reference to
+// lock a cloned voice (the black-frame video carries the voice; a raw MP3 does NOT
+// lock it as reliably — that is the whole point of the trick):
+//   • seedance-direct — the .mp4 rides into `reference_videos`
+//   • runway-useapi   — Seedance-2 via the UseAPI gateway → `videoAssetId` + audio:true
+//   • dreamina-useapi — Seedance-2 via Dreamina Omni Reference → `omni_N_videoRef`
+//     (the omni video ref is EXPECTED to drive the voice on its own; unverified
+//     live — if a render is mute, VCLAW_DREAMINA_AUDIO=1 forces `audio:true`)
+// Other routes leave voice clones un-injected (byte-identical).
+const VOICE_REF_ROUTES = new Set(['seedance-direct', 'runway-useapi', 'dreamina-useapi']);
+/**
+ * Classifies a scene's reference paths into image/video/audio counts using the
+ * same extension buckets the native transports use. Anything that is not a
+ * recognized video/audio file (including `Asset://` URIs, which the Seedance
+ * transport routes into `reference_images`) is counted as an image reference.
+ */
+function countReferencesByKind(referencePaths) {
+    let images = 0;
+    let videos = 0;
+    let audios = 0;
+    for (const path of referencePaths) {
+        if (!path)
+            continue;
+        const ext = (path.split('?')[0]?.match(/\.[^.\\/]+$/)?.[0] ?? '').toLowerCase();
+        if (REFERENCE_VIDEO_EXTS.has(ext))
+            videos += 1;
+        else if (REFERENCE_AUDIO_EXTS.has(ext))
+            audios += 1;
+        else
+            images += 1;
+    }
+    return { images, videos, audios };
+}
+/**
+ * Error thrown when `resolveChainSeeds` is enabled and the upstream scene has
+ * no selected candidate (or no usable video output).
+ */
+export class ChainFromPrevSourceMissingError extends Error {
+    code = 'chain-from-prev-source-missing';
+    sceneIndex;
+    sourceSceneIndex;
+    constructor(sceneIndex, sourceSceneIndex, reason) {
+        super(`chain-from-prev-source-missing: scene ${sceneIndex} requested chain from scene ${sourceSceneIndex} but ${reason}`);
+        this.sceneIndex = sceneIndex;
+        this.sourceSceneIndex = sourceSceneIndex;
+        this.name = 'ChainFromPrevSourceMissingError';
+    }
+}
+export async function buildExecutionPayload(projectSlug, plan, root = process.cwd(), options = {}) {
+    if (!plan.recommendedRouteId) {
+        throw new Error(`Cannot build execution payload for ${projectSlug}: recommendedRouteId missing.`);
+    }
+    const workspace = resolveProjectWorkspace(projectSlug, root);
+    const storyboard = JSON.parse(await readFile(artifactPathFor(workspace, 'storyboard'), 'utf-8'));
+    const assetManifest = existsSync(artifactPathFor(workspace, 'asset-manifest'))
+        ? JSON.parse(await readFile(artifactPathFor(workspace, 'asset-manifest'), 'utf-8'))
+        : { assets: [] };
+    const filmmakingPrompts = existsSync(artifactPathFor(workspace, 'filmmaking-prompts'))
+        ? JSON.parse(await readFile(artifactPathFor(workspace, 'filmmaking-prompts'), 'utf-8'))
+        : null;
+    const readyPromptPacketsByScene = new Map();
+    for (const packet of filmmakingPrompts?.seedancePackets ?? []) {
+        if (isExecutionReadyPromptPacket(packet)) {
+            readyPromptPacketsByScene.set(packet.sceneIndex, packet);
+        }
+    }
+    const assetsByScene = new Map();
+    for (const asset of assetManifest.assets ?? []) {
+        if (!Number.isInteger(asset.sceneIndex))
+            continue;
+        const sceneAssets = assetsByScene.get(asset.sceneIndex) ?? [];
+        sceneAssets.push(asset);
+        assetsByScene.set(asset.sceneIndex, sceneAssets);
+    }
+    // Chain-from-prev resolution is only considered when the caller opts in.
+    // Reads both selection + candidates so we can locate the upstream scene's
+    // selected candidate's video output.
+    const chainSeedsByScene = new Map();
+    if (options.resolveChainSeeds) {
+        const selection = await readSceneSelectionArtifact(root, projectSlug);
+        const candidates = await readSceneCandidatesArtifact(root, projectSlug);
+        const sceneList = (storyboard.scenes ?? []).map((s) => s.sceneIndex ?? 0);
+        const sceneIndexFilter = options.sceneIndices
+            ? new Set(options.sceneIndices)
+            : new Set(sceneList);
+        for (const sel of selection.scenes) {
+            if (!sel.chainFromPrev)
+                continue;
+            if (!sceneIndexFilter.has(sel.sceneIndex))
+                continue;
+            // Explicit chain source (auto-chain fallback ladder) wins; absent → the
+            // immediately previous scene (legacy behavior).
+            const sourceSceneIndex = sel.chainFromSceneIndex ?? sel.sceneIndex - 1;
+            const upstreamSelection = selection.scenes.find((s) => s.sceneIndex === sourceSceneIndex);
+            if (!upstreamSelection || !upstreamSelection.selectedCandidateId) {
+                throw new ChainFromPrevSourceMissingError(sel.sceneIndex, sourceSceneIndex, upstreamSelection ? 'upstream scene has no selected candidate' : 'upstream scene has no selection entry');
+            }
+            const upstreamEntry = candidates.scenes.find((s) => s.sceneIndex === sourceSceneIndex);
+            const upstreamCandidate = upstreamEntry?.candidates.find((c) => c.id === upstreamSelection.selectedCandidateId);
+            if (!upstreamCandidate) {
+                throw new ChainFromPrevSourceMissingError(sel.sceneIndex, sourceSceneIndex, `candidate ${upstreamSelection.selectedCandidateId} missing from candidates artifact`);
+            }
+            const firstVideo = upstreamCandidate.outputs.find((o) => o.kind === 'video');
+            if (!firstVideo) {
+                throw new ChainFromPrevSourceMissingError(sel.sceneIndex, sourceSceneIndex, `candidate ${upstreamSelection.selectedCandidateId} has no video output to chain from`);
+            }
+            chainSeedsByScene.set(sel.sceneIndex, {
+                path: firstVideo.path,
+                sourceCandidateId: upstreamCandidate.id,
+            });
+        }
+        // seedance-direct rejects local file references (a chain seed is the prior
+        // scene's downloaded `.mp4`), so host it: extract the last frame and upload
+        // it as an image, replacing the seed path with a hosted URL that seedance
+        // routes into `reference_images` (the keyframe). runway/dreamina upload
+        // local refs themselves, so this is gated to seedance-direct; non-local
+        // seeds (already a URL / Asset://) pass through `hostChainSeedAsImage`
+        // untouched. Off-route the map is byte-identical to today.
+        if (plan.recommendedRouteId === 'seedance-direct') {
+            const env = options.env ?? process.env;
+            const chainSeedHost = options.chainSeedHost ?? defaultChainSeedHostDeps(env);
+            const chainSeedWorkDir = join(workspace.projectDir, 'artifacts', 'chain-seeds');
+            for (const [sceneIndex, seed] of chainSeedsByScene) {
+                const hosted = await hostChainSeedAsImage(seed.path, chainSeedWorkDir, chainSeedHost);
+                if (hosted !== seed.path) {
+                    chainSeedsByScene.set(sceneIndex, { ...seed, path: hosted });
+                }
+            }
+        }
+    }
+    const sceneFilter = options.sceneIndices ? new Set(options.sceneIndices) : null;
+    // Seedance character/product identity is locked via managed Asset Library
+    // avatars (Asset:// URIs). When the project has registered them, each scene's
+    // cast names resolve to Asset:// URIs that become that scene's reference set.
+    // Absent artifact -> empty map -> behavior identical to today (no injection).
+    // Gated to the Seedance route so Veo/Runway payloads are untouched.
+    const assetUriByName = plan.recommendedRouteId === 'seedance-direct'
+        ? (await readSeedanceAssets(workspace.root, projectSlug)).assetUriByName
+        : new Map();
+    // Google Flow saved-character refs (flow-characters.json) → scene characters
+    // become `character_1..7` on the veo-useapi route. Absent artifact -> empty map
+    // -> no `--character` flags emitted (byte-identical to today). Gated to the
+    // veo-useapi route so Seedance/Runway/Dreamina payloads are untouched.
+    const characterRefByName = plan.recommendedRouteId === 'veo-useapi'
+        ? (await readFlowCharacters(workspace.root, projectSlug)).characterRefByName
+        : new Map();
+    // Voice clones (the blank-video-with-audio trick). The .mp4 voice clip becomes a
+    // video reference the transport routes into the provider's voice slot to lock the
+    // cloned voice — see VOICE_REF_ROUTES for the routes + their slots (seedance-direct
+    // reference_videos, runway-useapi videoAssetId, dreamina-useapi omni_N_videoRef).
+    // Other routes -> null -> byte-identical no-op; absent artifact -> empty -> no-op.
+    //   • `@VoiceName` tags  -> voiceEntryByName (explicit, resolved via assetTagLookup)
+    //   • a character bound with `voice-clone --character <name>` -> voiceByCharacter,
+    //     auto-injected into every scene that features that character (no tag needed).
+    const voiceClones = VOICE_REF_ROUTES.has(plan.recommendedRouteId)
+        ? await readVoiceClones(workspace.root, projectSlug)
+        : null;
+    const voicesByName = voiceClones?.voiceEntryByName ?? new Map();
+    // @Name tagging lookup: characters (+ seedance Asset:// URIs) + locked
+    // environment plates (so @location tags resolve) + voice clones (so @VoiceName
+    // tags resolve). Built once per payload; empty -> resolveAssetTags is a no-op
+    // (byte-identical to today).
+    const assetTagLookup = buildAssetTagLookup({
+        characters: await listCharacterProfiles(workspace),
+        assetUriByName,
+        // On seedance-direct a raw character portrait both fails submit (needs a
+        // hosted URL / Asset:// URI) and trips the real-person filter, so an @Name
+        // tag only injects a reference when the character is registered in the Asset
+        // Library — its descriptor text still substitutes. Off-route: unchanged.
+        assetUriOnly: plan.recommendedRouteId === 'seedance-direct',
+        environmentsByName: (await readEnvironmentAssets(workspace.root, projectSlug)).environmentEntryByName,
+        voicesByName,
+    });
+    // omni-flash First-Frame is gated: when the operator has not opted in, a
+    // stored scene.firstFrame is dropped (warned) so behavior is byte-identical.
+    const omniFirstFrameEnabled = isOmniFirstFrameEnabled(options.env ?? process.env);
+    const droppedFirstFrameScenes = [];
+    const tasks = (storyboard.scenes ?? [])
+        .filter((scene) => {
+        if (!sceneFilter)
+            return true;
+        const sceneIndex = scene.sceneIndex ?? 0;
+        return sceneFilter.has(sceneIndex);
+    })
+        .map((scene) => {
+        if (scene.firstFrame && !omniFirstFrameEnabled) {
+            droppedFirstFrameScenes.push(scene.sceneIndex ?? 0);
+        }
+        const sceneIndex = scene.sceneIndex ?? 0;
+        const sceneAssets = assetsByScene.get(sceneIndex) ?? [];
+        const chainSeed = chainSeedsByScene.get(sceneIndex);
+        const promptPacket = readyPromptPacketsByScene.get(sceneIndex);
+        const promptPacketReferencePaths = promptPacket
+            ? promptPacket.references.map((reference) => reference.path ?? '')
+            : [];
+        // A chain seed is normally the prior scene's video, but on seedance-direct
+        // it was hosted as a last-frame IMAGE above — so classify by its actual
+        // extension rather than assuming a chain seed is always a video.
+        const chainSeedIsVideo = chainSeed
+            ? REFERENCE_VIDEO_EXTS.has((chainSeed.path.split('?')[0]?.match(/\.[^.\\/]+$/)?.[0] ?? '').toLowerCase())
+            : false;
+        const hasVideo = chainSeedIsVideo || sceneAssets.some((asset) => asset.kind === 'video');
+        // A non-video chain seed (the seedance hosted last-frame image) counts as
+        // an image input so `inputKind` resolves to 'image', not 'text'.
+        const chainSeedIsImage = !!chainSeed && !chainSeedIsVideo;
+        const hasImage = chainSeedIsImage
+            || sceneAssets.some((asset) => asset.kind === 'image')
+            || promptPacketReferencePaths.length > 0;
+        // When we chain from the previous scene's output, the seed video path
+        // must lead `referencePaths` so downstream adapters pick it as the
+        // primary input. We also force `inputKind: 'video'`.
+        const baseReferencePaths = unique(sceneAssets
+            .filter((asset) => asset.kind === 'image' || asset.kind === 'video' || asset.kind === 'audio')
+            .map((asset) => asset.path ?? ''));
+        // A ready prompt packet supplies the IMAGE references, but the scene's
+        // own audio/video reference assets must still survive — otherwise
+        // reference_audios (and any non-packet video reference) silently
+        // disappears from the provider payload for packet-driven scenes.
+        const baseNonImageReferencePaths = unique(sceneAssets
+            .filter((asset) => asset.kind === 'video' || asset.kind === 'audio')
+            .map((asset) => asset.path ?? ''));
+        const packetOrBaseReferencePaths = promptPacketReferencePaths.length > 0
+            ? unique([...promptPacketReferencePaths, ...baseNonImageReferencePaths])
+            : baseReferencePaths;
+        // When the project has registered Seedance Asset Library avatars, this
+        // scene's resolved cast/product Asset:// URIs become its reference set
+        // (the proven identity-lock mechanism). Names that don't resolve are
+        // dropped. Empty map (no artifact) -> falls through to today's behavior.
+        // Resolve @Name tags in the scene prompt: substitute descriptors and
+        // collect tagged references. No '@' tokens -> unchanged text, no refs.
+        const rawPrompt = promptPacket?.promptText.trim() || scene.scenePrompt?.animationPrompt?.trim() || scene.description || '';
+        // veo-useapi auto-inject (useapi blog 260609): plan the character_1..7
+        // body slots FIRST (cast order, then tag-only registered names), then
+        // rewrite each registered @Name tag into its canonical @character_N
+        // marker BEFORE resolveAssetTags — the reserved marker grammar there
+        // preserves the injected tokens verbatim. INTENDED behavior change: a
+        // replaced @Name is no longer seen by resolveAssetTags, so its loose
+        // portrait referencePath is NOT collected — the saved Flow character
+        // already bundles its identity images, and the loose portrait would
+        // waste the shared image-reference budget. Characters WITHOUT a Flow ref
+        // keep today's descriptor-substitution path (incl. referencePath
+        // collection). Tagless prompts: the planned refs equal today's list and
+        // the text is unchanged → byte-identical payload. Off-route (empty map)
+        // this block is skipped entirely.
+        let flowSlotPlan = null;
+        let taggedPrompt = rawPrompt;
+        if (plan.recommendedRouteId === 'veo-useapi' && characterRefByName.size > 0) {
+            flowSlotPlan = planFlowCharacterSlots(rawPrompt, scene.characters ?? [], characterRefByName);
+            if (flowSlotPlan.overflow.length > 0) {
+                // Operator-visible, never fatal (stdout stays clean JSON) — same
+                // channel as the unresolved-tag and marker-strip warnings.
+                console.warn(`Flow character slots are capped at 7; scene ${sceneIndex} drops: ${flowSlotPlan.overflow.join(', ')}.`);
+            }
+            taggedPrompt = injectFlowCharacterMarkers(rawPrompt, flowSlotPlan.slotByLowerName).text;
+        }
+        const tagResult = resolveAssetTags(taggedPrompt, assetTagLookup);
+        let promptText = tagResult.text;
+        for (const name of tagResult.unresolved) {
+            // Operator-visible, never fatal (stdout stays clean JSON).
+            console.warn(`@Name tag "@${name}" in scene ${sceneIndex} did not resolve to a known character/asset; left as plain text.`);
+        }
+        // Google Flow inline @-markers (useapi blog 260609) are a veo-useapi-only
+        // grammar; on every other route the literal tokens would leak into the
+        // provider prompt, so strip them and warn (same operator-visible channel
+        // as unresolved tags, never fatal). On veo-useapi they pass through
+        // untouched. Marker-free prompts are byte-identical either way.
+        if (plan.recommendedRouteId !== 'veo-useapi' && extractFlowMarkers(promptText).length > 0) {
+            const strippedMarkers = stripFlowMarkers(promptText);
+            promptText = strippedMarkers.text;
+            console.warn(`Flow @-markers are veo-useapi only; removed for ${plan.recommendedRouteId} in scene ${sceneIndex}: ${strippedMarkers.stripped.join(', ')}.`);
+        }
+        // A character bound to a voice clone (`voice-clone --character`) auto-injects
+        // its black-frame voice clip into every scene it appears in — the cartoon-show
+        // voice-lock, no @tag required. The .mp4 routes into Seedance `reference_videos`
+        // and is counted against the video budget below. No bound voice -> no-op.
+        const sceneVoiceClips = unique(scene.characters ?? [])
+            .map((name) => {
+            const v = voiceClones?.voiceByCharacter.get(name.toLowerCase());
+            // Prefer the durable hosted URL — the remote seedance-direct API can't
+            // read a local path. Fall back to the local clip when unhosted.
+            return v?.hostedUrl ?? v?.clipPath;
+        })
+            .filter((path) => Boolean(path));
+        // Image identity refs (Asset:// URIs + @tag image paths) are the "winner" set
+        // that replaces the base/packet refs. Voice clips are NOT folded in here —
+        // they are additive (see resolveSceneReferencePaths) so the identity image is
+        // never dropped to make room for the voice (the runway talking-head case).
+        const resolvedAssetUris = unique([
+            ...unique(scene.characters ?? [])
+                .map((name) => assetUriByName.get(name))
+                .filter((uri) => Boolean(uri)),
+            ...tagResult.referencedPaths,
+        ]);
+        const referencePaths = resolveSceneReferencePaths({
+            resolvedAssetUris,
+            chainSeedPath: chainSeed ? chainSeed.path : null,
+            packetOrBaseReferencePaths,
+            additionalReferencePaths: sceneVoiceClips,
+        });
+        // Fail fast if the injected reference set exceeds the per-generation limits
+        // (reuses the canonical budget; does not duplicate the limits). Runs whenever
+        // this feature populated references — identity URIs OR a voice clip — so
+        // non-asset payloads stay byte-identical to today.
+        if (resolvedAssetUris.length > 0 || sceneVoiceClips.length > 0) {
+            assertReferenceBudget(referencePaths);
+        }
+        const backendHints = unique([
+            ...sceneAssets.map((asset) => asset.backend ?? ''),
+            ...(promptPacket ? ['filmmaking-prompts', `prompt-variant:${promptPacket.variant}`] : []),
+        ]);
+        const durationSeconds = promptPacket?.durationSeconds ?? scene.durationSeconds;
+        // OUTPUT-DEPENDENT render resolution, threaded from the prompt packet.
+        // Absent on legacy packets -> field omitted (no change to existing tasks).
+        const resolution = promptPacket?.resolution;
+        // Tag how these references should be DELIVERED so the transport never
+        // turns a lone character sheet into the video's first frame (which made
+        // solo clips open on the character grid). Asset-Library avatars and
+        // filmmaking-prompts packet images are identity references ('character');
+        // a chain-from-prev seed is a continuity keyframe ('keyframe'); plain
+        // ambiguous scene assets stay unset → today's first-frame behavior.
+        const referenceRole = resolvedAssetUris.length > 0
+            ? 'character'
+            : chainSeed
+                ? 'keyframe'
+                : promptPacketReferencePaths.length > 0
+                    ? 'character'
+                    : undefined;
+        return {
+            sceneIndex,
+            prompt: promptText,
+            inputKind: hasVideo ? 'video' : hasImage ? 'image' : 'text',
+            referencePaths,
+            ...(referenceRole ? { referenceRole } : {}),
+            ...(promptPacket ? {
+                referenceSlots: promptPacket.references.map((reference) => ({
+                    slot: reference.slot,
+                    role: reference.role,
+                    label: reference.label,
+                    ...(reference.path ? { path: reference.path } : {}),
+                })),
+                promptPacketVariant: promptPacket.variant,
+            } : {}),
+            // Asset ids only — packet reference slot names are surfaced separately
+            // via `referenceSlots` and must not pollute the asset-id provenance
+            // contract (telemetry/reports join these back to the asset manifest).
+            sourceAssetIds: unique(sceneAssets.map((asset) => asset.id ?? '')),
+            backendHints,
+            characters: unique(scene.characters ?? []),
+            // veo-useapi only: scene characters registered in flow-characters.json
+            // resolve to their Flow character refs (character_1..7). The slot plan
+            // built above is the single source of truth — its ordering contract is
+            // "cast order first, then tag-only characters", so a tagless scene
+            // yields exactly the legacy cast-derived list. Empty/absent -> no
+            // characterRefs field (byte-identical legacy on every other route).
+            ...(flowSlotPlan && flowSlotPlan.orderedRefs.length > 0
+                ? { characterRefs: flowSlotPlan.orderedRefs }
+                : {}),
+            ...(Number.isFinite(durationSeconds) ? { durationSeconds } : {}),
+            ...(resolution ? { resolution } : {}),
+            ...(scene.voicePreset ? { voicePreset: scene.voicePreset } : {}),
+            ...(scene.referenceVideoMediaId ? { referenceVideoMediaId: scene.referenceVideoMediaId } : {}),
+            // omni-flash First-Frame carrier — only stamped when the operator has
+            // opted in via VCLAW_OMNI_FIRST_FRAME. Gate off → a stored scene.firstFrame
+            // is silently dropped here (warned below), so behavior is byte-identical.
+            ...(scene.firstFrame && omniFirstFrameEnabled ? { firstFrame: true } : {}),
+            ...(chainSeed ? { chainedFromCandidateId: chainSeed.sourceCandidateId } : {}),
+        };
+    });
+    // PHASE-3 opt-in continuity loop. Only mutates prompts for tasks that carry a
+    // chain-from-prev seed, and only when the caller opts in. Default-off path is
+    // byte-identical to today (no Gemini call, no prompt change).
+    if (options.continuityFeedback && chainSeedsByScene.size > 0) {
+        // Deterministic continuity source + Gemini fallback: the project's
+        // story-bible cast/setting/prop descriptors (graceful when absent).
+        let storyBible = null;
+        const storyBiblePath = artifactPathFor(workspace, 'story-bible');
+        if (existsSync(storyBiblePath)) {
+            try {
+                storyBible = JSON.parse(await readFile(storyBiblePath, 'utf-8'));
+            }
+            catch {
+                storyBible = null;
+            }
+        }
+        const castDescriptors = (storyBible?.characters ?? [])
+            .map((character) => (character.description ? `${character.name}: ${character.description}` : character.name))
+            .filter(Boolean);
+        const settingDescriptors = (storyBible?.settings ?? [])
+            .map((setting) => `${setting.name}: ${setting.description}`)
+            .filter(Boolean);
+        const propDescriptors = (storyBible?.props ?? [])
+            .map((prop) => `${prop.name}: ${prop.description}`)
+            .filter(Boolean);
+        const priorDescriptors = [...castDescriptors, ...settingDescriptors, ...propDescriptors];
+        for (const task of tasks) {
+            const chainSeed = chainSeedsByScene.get(task.sceneIndex);
+            if (!chainSeed)
+                continue;
+            // Defense-in-depth: augmentPromptWithContinuity is documented to never
+            // throw (it catches all Gemini/network/parse/readFile errors and falls
+            // back to the deterministic path), but an unexpected escape (e.g. an OOM
+            // or a V8-internal error from a very large base64 image conversion) must
+            // NOT abort the whole payload build. Wrap per-task so one task degrading
+            // leaves its prompt unchanged and the remaining tasks still process.
+            try {
+                const augmented = await augmentPromptWithContinuity({
+                    nextPrompt: task.prompt,
+                    priorReferenceImagePath: chainSeed.path,
+                    priorDescriptors,
+                    ...(options.continuityFetcher ? { fetcher: options.continuityFetcher } : {}),
+                    env: options.env ?? process.env,
+                });
+                // StoryCraft anti-drift: re-state the full descriptor block verbatim
+                // (idempotent — won't double-inject if already present).
+                task.prompt = repasteContinuityDescriptors(augmented.prompt, {
+                    cast: castDescriptors,
+                    settings: settingDescriptors,
+                    props: propDescriptors,
+                });
+            }
+            catch (error) {
+                // Preserve the documented degradation contract unconditionally: keep
+                // the original prompt for this task and continue with the rest.
+                // eslint-disable-next-line no-console
+                console.warn(`[continuity] scene ${task.sceneIndex} continuity augmentation failed; using original prompt: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    const outputDir = join(workspace.projectDir, 'outputs');
+    await mkdir(outputDir, { recursive: true });
+    // Pre-submission route-capability check. Validates only the profile-level
+    // resolution (always 720p|1080p, both in every live route's matrix) and the
+    // worst-case per-task reference-budget counts against the target route's
+    // declared limits. Refs are already capped downstream by the transports at
+    // the same numbers, so a valid payload is never newly rejected here; this
+    // only fails fast on a genuinely out-of-matrix combo (and downgrades to
+    // warnings when VCLAW_ALLOW_UNSAFE_MODELS is set). Durations are intentionally
+    // not validated here because the transports clamp per-task durations.
+    const maxImageRefs = tasks.reduce((max, task) => Math.max(max, countReferencesByKind(task.referencePaths).images), 0);
+    const maxVideoRefs = tasks.reduce((max, task) => Math.max(max, countReferencesByKind(task.referencePaths).videos), 0);
+    // Audio refs are intentionally NOT validated here: some transports (e.g.
+    // runway-useapi) silently ignore audio reference assets today rather than
+    // erroring, so failing on them would change existing behavior. Image/video
+    // ref budgets are the proven, transport-enforced limits.
+    // Advisory: a stored storyboard requested omni-flash First-Frame but the gate
+    // is off, so those scenes fall back to legacy R2V. Emit to stderr (JSON stdout
+    // stays clean) so the operator knows why nothing changed.
+    if (droppedFirstFrameScenes.length > 0) {
+        console.warn(`[vclaw] omni-flash First-Frame requested for scene(s) [${droppedFirstFrameScenes.join(', ')}] but VCLAW_OMNI_FIRST_FRAME is not set — ignoring (legacy R2V). Set VCLAW_OMNI_FIRST_FRAME=1 to enable (build-ahead; unverified-live until useapi.net ships omni-flash frames mode).`);
+    }
+    // veo-useapi model gate: voice narration is omni-flash-only. We resolve the
+    // model the transport will actually pass (veoModel ?? quality) and flag any
+    // scene voice preset. hasVideoRef (dedicated V2V edit, not the scene-chaining
+    // seed) is wired once referenceVideoMediaId exists. Both are no-ops for legacy
+    // payloads (no voicePreset / non-veo route) so nothing is newly rejected.
+    assertRouteRequestValid(plan.recommendedRouteId, {
+        resolution: plan.executionProfile.resolution,
+        imageRefs: maxImageRefs,
+        videoRefs: maxVideoRefs,
+        veoModel: plan.executionProfile.veoModel ?? plan.executionProfile.quality,
+        hasVoice: tasks.some((task) => !!task.voicePreset),
+        hasVideoRef: tasks.some((task) => !!task.referenceVideoMediaId),
+        // First-Frame is already gated when stamping task.firstFrame above, so any
+        // present firstFrame means the operator opted in — it satisfies the
+        // omni-flash voice-needs-a-visual-anchor precondition.
+        hasStartImage: tasks.some((task) => !!task.firstFrame),
+    }, { env: options.env ?? process.env });
+    return {
+        workspaceRoot: workspace.root,
+        projectSlug,
+        productionMode: plan.productionMode,
+        routeId: plan.recommendedRouteId,
+        operationKind: plan.operationKind,
+        executionProfile: plan.executionProfile,
+        generatedAt: new Date().toISOString(),
+        outputDir,
+        tasks,
+        promptGuidance: plan.promptGuidance,
+    };
+}
+function isExecutionReadyPromptPacket(packet) {
+    if (!packet.promptText.trim())
+        return false;
+    if (packet.references.some((reference) => reference.status !== 'ready'))
+        return false;
+    if (packet.references.some((reference) => !reference.path?.trim()))
+        return false;
+    return true;
+}
+export async function submitExecutionPayload(payload, options = {}) {
+    const env = options.env ?? process.env;
+    const adapterCommand = resolveAdapterCommand(payload.routeId, env);
+    const result = await new Promise((resolve, reject) => {
+        const child = spawn('sh', ['-lc', adapterCommand], {
+            env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            resolve({ stdout, stderr, code });
+        });
+        child.stdin.write(JSON.stringify(payload));
+        child.stdin.end();
+    });
+    if (result.code !== 0) {
+        throw new Error(`Adapter command failed for ${payload.routeId}: ${result.stderr.trim() || `exit ${result.code}`}`);
+    }
+    const trimmed = result.stdout.trim();
+    let rawResult = trimmed;
+    if (trimmed) {
+        try {
+            rawResult = JSON.parse(trimmed);
+        }
+        catch {
+            rawResult = trimmed;
+        }
+    }
+    const externalJobId = rawResult && typeof rawResult === 'object' && 'externalJobId' in rawResult
+        ? String(rawResult.externalJobId ?? '') || null
+        : null;
+    // Adapter submit contract (CLAUDE.md "Provider routes and adapters"): submit
+    // MUST print JSON with an externalJobId. Silently accepting a malformed
+    // response used to leave the scene permanently "submitted" with nothing to
+    // poll — fail loudly instead.
+    if (!externalJobId) {
+        throw new Error(`Adapter submit for ${payload.routeId} returned no externalJobId ` +
+            `(stdout: ${trimmed ? trimmed.slice(0, 200) : '<empty>'}). ` +
+            'Adapters must print JSON {"externalJobId":"..."} on submit.');
+    }
+    return {
+        adapterCommand,
+        externalJobId,
+        rawResult,
+    };
+}
+export async function pollExecutionPayload(input, options = {}) {
+    const env = options.env ?? process.env;
+    const adapterCommand = resolveAdapterCommand(input.routeId, env);
+    const result = await new Promise((resolve, reject) => {
+        const child = spawn('sh', ['-lc', adapterCommand], {
+            env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            resolve({ stdout, stderr, code });
+        });
+        child.stdin.write(JSON.stringify({
+            action: 'poll',
+            ...input,
+        }));
+        child.stdin.end();
+    });
+    if (result.code !== 0) {
+        throw new Error(`Adapter poll failed for ${input.routeId}: ${result.stderr.trim() || `exit ${result.code}`}`);
+    }
+    const trimmed = result.stdout.trim();
+    let rawResult = trimmed;
+    if (trimmed) {
+        try {
+            rawResult = JSON.parse(trimmed);
+        }
+        catch {
+            rawResult = trimmed;
+        }
+    }
+    const status = rawResult && typeof rawResult === 'object' && 'status' in rawResult
+        ? String(rawResult.status ?? '')
+        : '';
+    if (!(status === 'pending' || status === 'completed' || status === 'failed')) {
+        throw new Error(`Adapter poll for ${input.routeId} returned invalid status: ${status || 'missing'}`);
+    }
+    const outputs = rawResult && typeof rawResult === 'object' && 'outputs' in rawResult && Array.isArray(rawResult.outputs)
+        ? (rawResult.outputs
+            .filter((asset) => typeof asset.id === 'string' && typeof asset.kind === 'string' && typeof asset.path === 'string')
+            .map((asset) => ({
+            id: String(asset.id),
+            kind: ['image', 'video', 'audio', 'subtitle', 'other'].includes(String(asset.kind))
+                ? String(asset.kind)
+                : 'other',
+            path: String(asset.path),
+            ...(Number.isInteger(asset.sceneIndex) ? { sceneIndex: asset.sceneIndex } : {}),
+            ...(typeof asset.backend === 'string' && asset.backend.trim() ? { backend: asset.backend } : {}),
+        })))
+        : [];
+    const issues = rawResult && typeof rawResult === 'object' && 'issues' in rawResult && Array.isArray(rawResult.issues)
+        ? rawResult.issues.map((value) => String(value))
+        : [];
+    const externalJobId = rawResult && typeof rawResult === 'object' && 'externalJobId' in rawResult
+        ? String(rawResult.externalJobId ?? '') || input.externalJobId
+        : input.externalJobId;
+    return {
+        status,
+        externalJobId,
+        outputs,
+        issues,
+        rawResult,
+    };
+}
+export async function cancelExecutionPayload(input, options = {}) {
+    const env = options.env ?? process.env;
+    const adapterCommand = resolveAdapterCommand(input.routeId, env);
+    const result = await new Promise((resolve, reject) => {
+        const child = spawn('sh', ['-lc', adapterCommand], {
+            env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            resolve({ stdout, stderr, code });
+        });
+        child.stdin.write(JSON.stringify({
+            action: 'cancel',
+            ...input,
+        }));
+        child.stdin.end();
+    });
+    if (result.code !== 0) {
+        throw new Error(`Adapter cancel failed for ${input.routeId}: ${result.stderr.trim() || `exit ${result.code}`}`);
+    }
+    const trimmed = result.stdout.trim();
+    let rawResult = trimmed;
+    if (trimmed) {
+        try {
+            rawResult = JSON.parse(trimmed);
+        }
+        catch {
+            rawResult = trimmed;
+        }
+    }
+    const status = rawResult && typeof rawResult === 'object' && 'status' in rawResult
+        ? String(rawResult.status ?? '')
+        : '';
+    if (!(status === 'cancelled' || status === 'unsupported')) {
+        throw new Error(`Adapter cancel for ${input.routeId} returned invalid status: ${status || 'missing'}`);
+    }
+    const issues = rawResult && typeof rawResult === 'object' && 'issues' in rawResult && Array.isArray(rawResult.issues)
+        ? rawResult.issues.map((value) => String(value))
+        : [];
+    const externalJobId = rawResult && typeof rawResult === 'object' && 'externalJobId' in rawResult
+        ? String(rawResult.externalJobId ?? '') || input.externalJobId
+        : input.externalJobId;
+    return {
+        status: status,
+        externalJobId,
+        issues,
+        rawResult,
+    };
+}
+//# sourceMappingURL=execution-runtime.js.map