videobook 0.0.0-stage → 0.2.0

package/dist/chain-plan.js

@@ -0,0 +1,746 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { findAudioFile, findVideoFile, } from "videobook-engine";
+import { notebookGridAddress, parseNotebookGridAddress, } from "videobook-engine/notebook-grid";
+import { NOTEBOOK_GRID_ADDRESS_SOURCE, normalizeNotebookReference, } from "videobook-engine/notebook-mentions";
+import { resolveNotebookArtifactReference } from "./notebook-reference-resolver.js";
+import { toolSpendsMoney } from "./paid-tools.js";
+const CHAIN_VERSION = 1;
+const CHAIN_MIN_STEPS = 1;
+const CHAIN_MAX_STEPS = 16;
+const CHAIN_UNSUPPORTED_TOOLS = new Set(["chain", "chat"]);
+const GENERATION_OUTPUTS = {
+    asset_id: "artifact",
+    model: "string",
+    cell_id: "string",
+    address: "string",
+    job_id: "string",
+    status: "string",
+};
+export const CHAIN_TOOL_CATALOG = {
+    generate_image: {
+        outputs: GENERATION_OUTPUTS,
+        completion: "generation",
+        gridFields: ["refs.image"],
+        inputTypes: { model: "string", prompt: "string", image: "artifact", options: "json" },
+        placement: "generate_image",
+        artifactOutput: "asset_id",
+    },
+    generate_video: {
+        outputs: GENERATION_OUTPUTS,
+        completion: "generation",
+        gridFields: ["refs.first_frame", "refs.last_frame", "refs.image", "refs.video", "refs.audio", "replace_audio_with"],
+        inputTypes: {
+            model: "string",
+            prompt: "string",
+            first_frame: "artifact",
+            last_frame: "artifact",
+            image: "artifact",
+            video: "artifact",
+            audio: "artifact",
+            replace_audio_with: "artifact",
+            options: "json",
+        },
+        placement: "generate_video",
+        artifactOutput: "asset_id",
+    },
+    generate_audio: {
+        outputs: GENERATION_OUTPUTS,
+        completion: "generation",
+        gridFields: ["refs.video", "refs.audio"],
+        inputTypes: { model: "string", prompt: "string", video: "artifact", audio: "artifact", options: "json" },
+        placement: "generate_audio",
+        artifactOutput: "asset_id",
+    },
+    assemble_goal: {
+        outputs: { sequence_id: "string", status: "string" },
+        completion: "sync",
+        gridFields: ["artifact_ids"],
+        inputTypes: { goal_id: "string", artifact_ids: "artifact" },
+    },
+    extract_audio: {
+        outputs: {
+            audio_asset_id: "artifact",
+            source_video: "artifact",
+            job_id: "string",
+            status: "string",
+        },
+        completion: "extract_audio",
+        gridFields: ["asset_id"],
+        inputTypes: { asset_id: "artifact" },
+    },
+    replace_video_audio: {
+        outputs: {
+            asset_id: "artifact",
+            audio_asset_id: "artifact",
+            job_id: "string",
+            status: "string",
+        },
+        completion: "replace_video_audio",
+        gridFields: ["asset_id", "audio_asset_id"],
+        inputTypes: {
+            asset_id: "artifact",
+            audio_asset_id: "artifact",
+        },
+    },
+    audio_mix: {
+        outputs: {
+            target_asset_id: "artifact",
+            layer_asset_id: "artifact",
+            volume: "number",
+            job_id: "string",
+            status: "string",
+        },
+        completion: "audio_mix",
+        gridFields: ["target_asset_id", "layer_asset_id"],
+        inputTypes: { target_asset_id: "artifact", layer_asset_id: "artifact", volume: "number" },
+    },
+    apply_sfx: {
+        outputs: { asset_id: "artifact", job_id: "string", status: "string", applied: "number", dropped: "number" },
+        completion: "apply_sfx",
+        gridFields: ["asset_id"],
+        inputTypes: { asset_id: "artifact", sfx: "json" },
+    },
+    trim_video: {
+        outputs: {
+            asset_id: "artifact",
+            job_id: "string",
+            status: "string",
+        },
+        completion: "trim_video",
+        gridFields: ["asset_id"],
+        inputTypes: { asset_id: "artifact" },
+    },
+    extract_frame: {
+        outputs: {
+            image_asset_id: "artifact",
+            source_video: "artifact",
+            job_id: "string",
+            status: "string",
+        },
+        completion: "extract_frame",
+        gridFields: ["asset_id"],
+        inputTypes: { asset_id: "artifact", frame: "string", timestamp: "number" },
+    },
+    asset_manifest: {
+        outputs: {
+            artifactId: "artifact",
+            path: "string",
+            files: "json",
+        },
+        completion: "sync",
+        gridFields: ["asset_id"],
+        inputTypes: { asset_id: "artifact" },
+    },
+    read_asset_metadata: {
+        outputs: {
+            value: "json",
+        },
+        completion: "sync",
+        gridFields: ["asset_id"],
+        inputTypes: { asset_id: "artifact", name: "string" },
+    },
+};
+const GRID_TOKEN = NOTEBOOK_GRID_ADDRESS_SOURCE;
+const GRID_PATTERN = new RegExp(`^@?(${GRID_TOKEN})$`, "iu");
+const PLACEHOLDER_ARTIFACT = "01900000-0000-7000-8000-000000000001";
+const chainRefSchema = z.object({
+    $ref: z.object({
+        step_id: z.string().min(1),
+        output: z.string().min(1),
+    }),
+});
+export const chainStepSchema = z.object({
+    id: z.string().min(1).max(64).regex(/^[A-Za-z][A-Za-z0-9_-]*$/),
+    tool: z.string().min(1),
+    params: z.record(z.string(), z.unknown()),
+});
+const chainRunInputSchema = z.object({
+    action: z.literal("run"),
+    version: z.literal(CHAIN_VERSION),
+    book_id: z.string().uuid(),
+    notebook_id: z.string().uuid().optional(),
+    request_id: z.string().min(1).optional(),
+    steps: z.array(chainStepSchema).min(CHAIN_MIN_STEPS).max(CHAIN_MAX_STEPS),
+});
+export const chainStatusInputSchema = z.object({
+    action: z.literal("status"),
+    book_id: z.string().uuid(),
+    chain_id: z.string().uuid(),
+});
+export const chainCancelInputSchema = z.object({
+    action: z.literal("cancel"),
+    book_id: z.string().uuid(),
+    chain_id: z.string().uuid(),
+});
+export const chainApproveInputSchema = z.object({
+    action: z.literal("approve"),
+    book_id: z.string().uuid(),
+    chain_id: z.string().uuid(),
+    step_id: z.string().min(1).max(64),
+    actor: z.enum(["chat", "voice", "api"]).optional(),
+});
+export function readChainParam(params, path) {
+    let current = params;
+    for (const segment of path.split(".")) {
+        if (current === null || typeof current !== "object" || Array.isArray(current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+export function writeChainParam(params, path, value) {
+    const [head, ...rest] = path.split(".");
+    if (rest.length === 0)
+        return { ...params, [head]: value };
+    const child = params[head];
+    const nested = child !== null && typeof child === "object" && !Array.isArray(child)
+        ? child
+        : {};
+    return { ...params, [head]: writeChainParam(nested, rest.join("."), value) };
+}
+export function isChainRef(value) {
+    return chainRefSchema.safeParse(value).success;
+}
+export function supportedChainTool(name) {
+    if (CHAIN_UNSUPPORTED_TOOLS.has(name))
+        return null;
+    return CHAIN_TOOL_CATALOG[name] ?? null;
+}
+export function chainPlanFingerprint(input) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        version: input.version,
+        notebookId: input.notebookId ?? null,
+        steps: input.steps,
+    }))
+        .digest("hex");
+}
+function typesCompatible(output, input) {
+    if (output === input)
+        return true;
+    return output === "artifact" && input === "string";
+}
+function walkValues(value, visit, path = "") {
+    visit(value, path);
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => walkValues(entry, visit, `${path}[${index}]`));
+        return;
+    }
+    if (value && typeof value === "object" && !isChainRef(value)) {
+        for (const [key, child] of Object.entries(value)) {
+            walkValues(child, visit, path ? `${path}.${key}` : key);
+        }
+    }
+}
+const CHAIN_STEP_ID = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+function chainStepRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function chainStepId(value) {
+    return typeof value === "string" && CHAIN_STEP_ID.test(value) ? value : null;
+}
+function unusedChainStepId(preferred, used, index) {
+    for (const candidate of preferred) {
+        if (candidate && !used.has(candidate))
+            return candidate;
+    }
+    let number = index + 1;
+    while (used.has(`step${number}`))
+        number += 1;
+    return `step${number}`;
+}
+function chainStepIndexAlias(token, count) {
+    const numbered = /^(?:step[_-]?)?(\d+)$/iu.exec(token);
+    if (!numbered)
+        return null;
+    const number = Number(numbered[1]);
+    if (token === "0")
+        return count > 0 ? 0 : null;
+    if (number >= 1 && number <= count)
+        return number - 1;
+    return null;
+}
+export function ensureChainStepIds(steps) {
+    if (!Array.isArray(steps))
+        return steps;
+    const records = steps.map(chainStepRecord);
+    const explicit = records.map((record) => chainStepId(record?.id));
+    const used = new Set(explicit.filter((id) => id !== null));
+    const toolCounts = new Map();
+    for (const record of records) {
+        const tool = typeof record?.tool === "string" ? record.tool : "";
+        if (!tool)
+            continue;
+        toolCounts.set(tool, (toolCounts.get(tool) ?? 0) + 1);
+    }
+    const ids = records.map((record, index) => {
+        if (!record)
+            return null;
+        const current = explicit[index];
+        if (current)
+            return current;
+        const tool = typeof record.tool === "string" ? record.tool : "";
+        const toolId = toolCounts.get(tool) === 1 ? chainStepId(tool) : null;
+        const alias = chainStepId(record.step_id) ?? chainStepId(record.name);
+        const id = unusedChainStepId([alias, toolId], used, index);
+        used.add(id);
+        return id;
+    });
+    const idSet = new Set(ids.filter((id) => id !== null));
+    const toolIds = new Map();
+    records.forEach((record, index) => {
+        const tool = typeof record?.tool === "string" ? record.tool : "";
+        const id = ids[index];
+        if (!tool || !id || toolCounts.get(tool) !== 1)
+            return;
+        toolIds.set(tool, id);
+    });
+    const resolveRef = (token) => {
+        if (idSet.has(token))
+            return token;
+        const fromTool = toolIds.get(token);
+        if (fromTool)
+            return fromTool;
+        const index = chainStepIndexAlias(token, ids.length);
+        return index === null ? token : ids[index] ?? token;
+    };
+    let refsChanged = false;
+    const next = steps.map((entry, index) => {
+        const record = records[index];
+        const id = ids[index];
+        if (!record || !id)
+            return entry;
+        const params = chainStepRecord(record.params);
+        const nextParams = params
+            ? mapChainParams(params, (node) => {
+                if (!isChainRef(node))
+                    return node;
+                const stepId = resolveRef(node.$ref.step_id);
+                if (stepId === node.$ref.step_id)
+                    return node;
+                refsChanged = true;
+                return { $ref: { step_id: stepId, output: node.$ref.output } };
+            })
+            : record.params;
+        if (record.id === id && !refsChanged)
+            return entry;
+        return { ...record, id, params: nextParams };
+    });
+    const unchanged = !refsChanged && next.every((entry, index) => entry === steps[index]);
+    return unchanged ? steps : next;
+}
+function chainInputWithStepIds(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        return input;
+    const record = input;
+    if (!Object.hasOwn(record, "steps"))
+        return input;
+    const steps = ensureChainStepIds(record.steps);
+    return steps === record.steps ? input : { ...record, steps };
+}
+function mapChainParams(value, map, path = "") {
+    const mapped = map(value, path);
+    if (mapped !== value)
+        return mapped;
+    if (Array.isArray(value)) {
+        return value.map((entry, index) => mapChainParams(entry, map, `${path}[${index}]`));
+    }
+    if (value && typeof value === "object" && !isChainRef(value)) {
+        const next = {};
+        for (const [key, child] of Object.entries(value)) {
+            next[key] = mapChainParams(child, map, path ? `${path}.${key}` : key);
+        }
+        return next;
+    }
+    return value;
+}
+export function substituteChainRefs(params, outputs) {
+    return mapChainParams(params, (node) => {
+        if (!isChainRef(node))
+            return node;
+        const stepOutputs = outputs.get(node.$ref.step_id);
+        if (!stepOutputs || !(node.$ref.output in stepOutputs)) {
+            throw new Error(`Missing output ${node.$ref.output} from step ${node.$ref.step_id}`);
+        }
+        return stepOutputs[node.$ref.output];
+    });
+}
+function looksLikeGridAttempt(value) {
+    return value.startsWith("@") || GRID_PATTERN.test(value.trim());
+}
+function asGridAddress(value) {
+    const slot = parseNotebookGridAddress(normalizeNotebookReference(value));
+    return slot ? notebookGridAddress(slot) : null;
+}
+async function primaryObjectHash(engine, artifactId) {
+    const artifact = engine.artifacts.get(artifactId);
+    if (!artifact.ok)
+        return null;
+    const manifest = await engine.files.manifest(artifactId);
+    if (!manifest.ok)
+        return null;
+    const file = findVideoFile(manifest.value.files)
+        ?? findAudioFile(manifest.value.files, artifact.value.kind)
+        ?? manifest.value.files.find((entry) => entry.name.startsWith("original."))
+        ?? manifest.value.files[0];
+    return file?.objectHash ?? null;
+}
+async function resolvePinnedTarget(context, field, index, raw) {
+    const notebookId = context.notebookId;
+    let notebook = null;
+    if (notebookId) {
+        const read = context.engine.notebooks.read(notebookId);
+        if (!read.ok)
+            return read.error.message;
+        notebook = read.value;
+    }
+    const documents = notebook
+        ? [notebook]
+        : context.engine.notebooks.list();
+    const resolved = resolveNotebookArtifactReference({
+        engine: context.engine,
+        documents,
+        reference: raw,
+        requireMedia: false,
+    });
+    if ("code" in resolved) {
+        return resolved.message;
+    }
+    const objectHash = await primaryObjectHash(context.engine, resolved.artifactId);
+    return {
+        field,
+        index,
+        address: resolved.cellAddress ?? normalizeNotebookReference(raw),
+        cellId: resolved.cellId ?? null,
+        artifactId: resolved.artifactId,
+        objectHash,
+    };
+}
+/**
+ * Resolve one grid-addressable value to a pin, or report why it cannot be one.
+ * Anything that is neither an address attempt nor an id is left alone for the
+ * tool's own schema to judge.
+ */
+async function pinGridField(context, stepId, field, index, raw) {
+    if (looksLikeGridAttempt(raw) && !asGridAddress(raw) && !raw.includes("-")) {
+        return `Step ${stepId} field ${field} is not a valid @a1-@bl8 target`;
+    }
+    if (!looksLikeGridAttempt(raw) && !raw.includes("-"))
+        return null;
+    const pinned = await resolvePinnedTarget(context, field, index, raw);
+    return typeof pinned === "string" ? `Step ${stepId} ${pinned}` : pinned;
+}
+function collectRefs(params) {
+    const refs = [];
+    walkValues(params, (node, path) => {
+        if (!isChainRef(node))
+            return;
+        const field = path.split("[")[0].split(".").pop() ?? path;
+        refs.push({ path, ref: node, field });
+    });
+    return refs;
+}
+function withRefPlaceholders(params) {
+    return mapChainParams(params, (node) => {
+        if (!isChainRef(node))
+            return node;
+        return PLACEHOLDER_ARTIFACT;
+    });
+}
+export async function preflightChainPlan(input, context) {
+    if (typeof input === "object"
+        && input !== null
+        && "action" in input
+        && input.action !== undefined
+        && input.action !== "run") {
+        return { ok: false, error: "Chain preflight only accepts action=run" };
+    }
+    const parsed = chainRunInputSchema.safeParse(chainInputWithStepIds(input));
+    if (!parsed.success) {
+        return { ok: false, error: z.prettifyError(parsed.error) };
+    }
+    const data = parsed.data;
+    if (data.book_id !== context.bookId) {
+        return { ok: false, error: "Chain book_id does not match the active book" };
+    }
+    if (data.notebook_id && context.notebookId && data.notebook_id !== context.notebookId) {
+        return {
+            ok: false,
+            error: "Chain notebook_id does not match the active notebook",
+        };
+    }
+    const notebookId = data.notebook_id ?? context.notebookId ?? null;
+    const ids = data.steps.map((step) => step.id);
+    if (new Set(ids).size !== ids.length) {
+        return { ok: false, error: "Chain step ids must be unique" };
+    }
+    const declared = new Map();
+    const preflightSteps = [];
+    for (const [index, step] of data.steps.entries()) {
+        if (CHAIN_UNSUPPORTED_TOOLS.has(step.tool)) {
+            return {
+                ok: false,
+                error: `Unsupported chain tool: ${step.tool}`,
+            };
+        }
+        const spec = supportedChainTool(step.tool);
+        if (!spec) {
+            return {
+                ok: false,
+                error: `Unknown or unsupported chain tool: ${step.tool}`,
+            };
+        }
+        const schema = context.toolSchemas.get(step.tool);
+        if (!schema) {
+            return { ok: false, error: `Unknown or unsupported chain tool: ${step.tool}` };
+        }
+        if (typeof step.params.book_id === "string" && step.params.book_id !== context.bookId) {
+            return {
+                ok: false,
+                error: `Step ${step.id} overrides book_id and cannot dispatch cross-book`,
+            };
+        }
+        if (typeof step.params.notebook_id === "string"
+            && notebookId
+            && step.params.notebook_id !== notebookId) {
+            return {
+                ok: false,
+                error: `Step ${step.id} overrides notebook_id and cannot dispatch cross-notebook`,
+            };
+        }
+        const refs = collectRefs(step.params);
+        for (const { ref, field, path } of refs) {
+            if (ref.$ref.step_id === step.id) {
+                return {
+                    ok: false,
+                    error: `Step ${step.id} cannot reference its own output at ${path}`,
+                };
+            }
+            const earlier = declared.get(ref.$ref.step_id);
+            if (!earlier) {
+                const later = data.steps.some((candidate) => candidate.id === ref.$ref.step_id);
+                return {
+                    ok: false,
+                    error: later
+                        ? `Step ${step.id} has a forward reference to ${ref.$ref.step_id} at ${path}`
+                        : `Step ${step.id} references unknown step ${ref.$ref.step_id} at ${path}`,
+                };
+            }
+            if (earlier.index >= index) {
+                return {
+                    ok: false,
+                    error: `Step ${step.id} has a forward reference to ${ref.$ref.step_id} at ${path}`,
+                };
+            }
+            const outputType = earlier.spec.outputs[ref.$ref.output];
+            if (!outputType) {
+                return {
+                    ok: false,
+                    error: `Step ${step.id} references unavailable output ${ref.$ref.step_id}.${ref.$ref.output}`,
+                };
+            }
+            const inputType = spec.inputTypes[field] ?? "string";
+            if (!typesCompatible(outputType, inputType)) {
+                return {
+                    ok: false,
+                    error: `Step ${step.id} input ${field} is incompatible with ${ref.$ref.step_id}.${ref.$ref.output}`,
+                };
+            }
+        }
+        const pins = [];
+        for (const field of spec.gridFields) {
+            const raw = readChainParam(step.params, field);
+            if (isChainRef(raw) || raw === undefined)
+                continue;
+            const entries = Array.isArray(raw)
+                ? raw.map((value, position) => ({ index: position, value }))
+                : [{ index: null, value: raw }];
+            for (const entry of entries) {
+                if (isChainRef(entry.value))
+                    continue;
+                if (typeof entry.value !== "string") {
+                    return {
+                        ok: false,
+                        error: `Step ${step.id} field ${field} must be a string or {$ref}`,
+                    };
+                }
+                const pinned = await pinGridField(context, step.id, field, entry.index, entry.value);
+                if (typeof pinned === "string")
+                    return { ok: false, error: pinned };
+                if (pinned)
+                    pins.push(pinned);
+            }
+        }
+        const literalParams = withRefPlaceholders(step.params);
+        const validated = z.object(schema).safeParse({
+            ...literalParams,
+            book_id: context.bookId,
+            ...(notebookId && schema.notebook_id !== undefined
+                ? { notebook_id: notebookId }
+                : {}),
+        });
+        if (!validated.success) {
+            return {
+                ok: false,
+                error: `Invalid parameters for ${step.tool}: ${z.prettifyError(validated.error)}`,
+            };
+        }
+        declared.set(step.id, { index, spec });
+        const effect = context.effectForTool(step.tool);
+        const autoApplyStep = context.autoApplyTools.has(step.tool) || effect === "read";
+        preflightSteps.push({
+            id: step.id,
+            tool: step.tool,
+            params: step.params,
+            spec,
+            pins,
+            autoApply: autoApplyStep,
+            effect,
+            requiresApproval: !autoApplyStep && toolSpendsMoney(step.tool),
+        });
+    }
+    const effect = preflightSteps.some((step) => step.effect === "generation")
+        ? "generation"
+        : preflightSteps.some((step) => step.effect === "mutation")
+            ? "mutation"
+            : "read";
+    // A step that stops for its own review does not also need the combined sheet.
+    // A free in-place mutation still does, or it would run with no review at all.
+    const autoApply = preflightSteps.every((step) => step.autoApply || step.requiresApproval);
+    return {
+        ok: true,
+        plan: {
+            version: CHAIN_VERSION,
+            bookId: context.bookId,
+            notebookId,
+            requestId: data.request_id ?? null,
+            steps: preflightSteps,
+            fingerprint: chainPlanFingerprint({
+                version: CHAIN_VERSION,
+                notebookId,
+                steps: data.steps,
+            }),
+            autoApply,
+            effect,
+        },
+    };
+}
+export async function revalidatePinnedTargets(engine, notebookId, pins) {
+    for (const pin of pins) {
+        if (pin.cellId && notebookId) {
+            const notebook = engine.notebooks.read(notebookId);
+            if (!notebook.ok)
+                return notebook.error.message;
+            const cell = notebook.value.cells.find((candidate) => candidate.id === pin.cellId);
+            if (!cell)
+                return `Pinned cell for ${pin.address} is gone`;
+            if (cell.outputArtifactId !== pin.artifactId) {
+                return `Pinned target ${pin.address} no longer points at the same artifact`;
+            }
+        }
+        const artifact = engine.artifacts.get(pin.artifactId);
+        if (!artifact.ok)
+            return `Pinned artifact ${pin.artifactId} is gone`;
+        const hash = await primaryObjectHash(engine, pin.artifactId);
+        if (pin.objectHash && hash && hash !== pin.objectHash) {
+            return `Pinned target ${pin.address} changed since planning`;
+        }
+    }
+    return null;
+}
+function uniqueGridMentions(query) {
+    const matches = [
+        ...query.matchAll(new RegExp(`@(${GRID_TOKEN})(?![\\w-])`, "giu")),
+        ...query.matchAll(new RegExp(`\\b(${GRID_TOKEN})\\b`, "giu")),
+    ];
+    const seen = new Set();
+    const mentions = [];
+    for (const match of matches) {
+        const token = match[1]?.toLowerCase();
+        if (!token || !parseNotebookGridAddress(token) || seen.has(token))
+            continue;
+        seen.add(token);
+        mentions.push(token);
+    }
+    return mentions;
+}
+function gridAfter(query, pattern) {
+    const match = pattern.exec(query);
+    const token = match?.[1]?.toLowerCase();
+    return token && parseNotebookGridAddress(token) ? token : null;
+}
+function extractAudioReplacePlan(query) {
+    if (!/\bextract(?:\s+the)?\s+audio\b/i.test(query))
+        return null;
+    if (!/\breplace(?:\s+the)?\s+audio\b/i.test(query))
+        return null;
+    const source = gridAfter(query, new RegExp(`\\bfrom\\s+@?(${GRID_TOKEN})\\b`, "iu")) ?? uniqueGridMentions(query)[0] ?? null;
+    const target = gridAfter(query, new RegExp(`\\b(?:in|on)\\s+(?:the\\s+video\\s+(?:in|on)\\s+)?@?(${GRID_TOKEN})\\b`, "iu")) ?? uniqueGridMentions(query)[1] ?? null;
+    if (!source || !target || source === target)
+        return null;
+    return {
+        message: "Extracting audio and replacing the target soundtrack.",
+        steps: [
+            {
+                id: "extract",
+                tool: "extract_audio",
+                params: { asset_id: `@${source}` },
+            },
+            {
+                id: "replace",
+                tool: "replace_video_audio",
+                params: {
+                    asset_id: `@${target}`,
+                    audio_asset_id: {
+                        $ref: { step_id: "extract", output: "audio_asset_id" },
+                    },
+                },
+            },
+        ],
+    };
+}
+function trimThenExtractPlan(query) {
+    if (!/\btrim\b/i.test(query))
+        return null;
+    if (!/\bextract(?:\s+the)?\s+audio\b/i.test(query))
+        return null;
+    if (/\breplace(?:\s+the)?\s+audio\b/i.test(query))
+        return null;
+    const mentions = uniqueGridMentions(query);
+    const source = mentions[0];
+    if (!source)
+        return null;
+    const seconds = query.match(/\b(\d+(?:\.\d+)?)\s*(?:s|sec|seconds)?\b/i)?.[1];
+    const trimEnd = seconds ? Number(seconds) : 1;
+    if (!Number.isFinite(trimEnd) || trimEnd <= 0)
+        return null;
+    return {
+        message: "Trimming the clip then extracting audio.",
+        steps: [
+            {
+                id: "trim",
+                tool: "trim_video",
+                params: {
+                    asset_id: `@${source}`,
+                    trim_start: 0,
+                    trim_end: trimEnd,
+                },
+            },
+            {
+                id: "extract",
+                tool: "extract_audio",
+                params: {
+                    asset_id: {
+                        $ref: { step_id: "trim", output: "asset_id" },
+                    },
+                },
+            },
+        ],
+    };
+}
+export function planStackedChainFromQuery(query) {
+    return extractAudioReplacePlan(query) ?? trimThenExtractPlan(query);
+}