videobook 0.0.0-stage → 0.2.0

package/dist/tools/chat.js

@@ -0,0 +1,848 @@
+import { v7 as uuidv7 } from "uuid";
+import { z } from "zod";
+import { applyBackgroundAudioRoute, planBackgroundAudioFromQuery, applyBytedanceNamedModelRoute, applyStackedChainRoute, applyVideoJoinRoute, AUTO_APPLY_TOOL_NAMES, buildChatRoutingPrompt, buildChatRoutingUserMessage, buildRoutableTools, effectForTool, getRoutableTool, NESTED_TIMESTAMP_PARAMS, TIMESTAMP_PARAMS, } from "../chat-router.js";
+import { ensureChainStepIds, planStackedChainFromQuery, preflightChainPlan, } from "../chain-plan.js";
+import { withoutUnrequestedSettings } from "../chat-generation-settings.js";
+import { resolveChatViewAction } from "../chat-view-actions.js";
+import { rewriteChatGenerationPrompt } from "../chat-prompt-rewrite.js";
+import { parseTime } from "../time-parse.js";
+import { withLogging } from "./log-wrapper.js";
+import { applyGenerationRoutingDefaults } from "../chat-generation-routing.js";
+import { getApiKey } from "../api-key.js";
+import { SCRIPT_FILENAME } from "../jobs/describe-image.js";
+import { timelineSlotArtifactIds } from "../timeline-helpers.js";
+import { expandSlotRefs, parseArtifactIdTags, resolveArtifactRefs, } from "../artifact-refs.js";
+import { buildIntelligenceResponses, firstResponseText, intelligenceRequest, } from "../openai-intelligence.js";
+import { chatIntelligenceRequestOptions, chatModelSchema, } from "../chat-models.js";
+import { notebookGridAddress, } from "videobook-engine/notebook-grid";
+import { NOTEBOOK_GRID_ADDRESS_SOURCE, replaceNotebookMentions, } from "videobook-engine/notebook-mentions";
+import { notebookMediaAddresses, resolveNotebookPromptReferences, tagNotebookGridAddresses, } from "../notebook-reference-resolver.js";
+const chatActionPlanSchema = z.object({
+    kind: z.literal("chat-action-plan"),
+    planId: z.string().uuid(),
+    bookId: z.string().uuid(),
+    prompt: z.string().min(1),
+    routedTool: z.string().min(1),
+    tool: z.string().min(1),
+    params: z.record(z.string(), z.unknown()),
+    message: z.string(),
+    summary: z.string().min(1),
+    effect: z.enum(["mutation", "generation", "view"]),
+    confirmation: z.object({
+        required: z.boolean(),
+        reason: z.string().min(1),
+    }),
+});
+const CHAT_ROUTING_MAX_OUTPUT_TOKENS = 2048;
+const CHAT_ROUTING_TIMEOUT_MS = 45_000;
+const NOTEBOOK_DESTINATION_SOURCE = NOTEBOOK_GRID_ADDRESS_SOURCE;
+function duplicateDestinationReference(prompt) {
+    if (!/\b(?:copy|duplicate)\b/iu.test(prompt))
+        return null;
+    const explicit = new RegExp(`\\b(?:at|in|into|to)\\s+@(${NOTEBOOK_DESTINATION_SOURCE})(?![\\w-])`, "iu").exec(prompt);
+    if (explicit?.[1])
+        return explicit[1].toLowerCase();
+    const mentions = [...prompt.matchAll(new RegExp(`@(${NOTEBOOK_DESTINATION_SOURCE})(?![\\w-])`, "giu"))];
+    return mentions.length > 1
+        ? mentions.at(-1)?.[1]?.toLowerCase() ?? null
+        : null;
+}
+function buildChatNotebookContext(engine, notebook) {
+    if (!notebook)
+        return null;
+    return {
+        id: notebook.id,
+        name: notebook.name,
+        cells: notebook.cells.map((cell) => {
+            const artifact = cell.outputArtifactId
+                ? engine.artifacts.get(cell.outputArtifactId)
+                : null;
+            return {
+                address: `@${notebookGridAddress(cell.slot)}`,
+                cellId: cell.id,
+                ...(cell.label === undefined ? {} : { label: cell.label }),
+                type: cell.type,
+                outputAsset: artifact?.ok ? `@${artifact.value.artifactId}` : null,
+            };
+        }),
+    };
+}
+function attachNotebookReferences(assetContext, notebookContext) {
+    if (!notebookContext)
+        return assetContext;
+    return assetContext.map((asset) => {
+        const assetId = typeof asset.asset_id === "string" ? asset.asset_id : "";
+        const references = notebookContext.cells
+            .filter((cell) => cell.outputAsset === `@${assetId}`)
+            .map((cell) => cell.address);
+        return references.length > 0
+            ? { ...asset, notebook_references: references }
+            : asset;
+    });
+}
+function formatHistoryForPrompt(lines) {
+    if (lines.length === 0)
+        return "";
+    const formatted = lines.map((line) => line.role === "user"
+        ? `User: ${line.text ?? ""}`
+        : `Assistant: ${line.tool ? `[${line.tool}] ` : ""}${line.message ?? ""}`);
+    return `Recent conversation:\n${formatted.join("\n")}`;
+}
+function isMediaContextObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stripAssetToken(value) {
+    return value.replace(/^@/u, "").trim();
+}
+function stringAssetIds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => typeof entry === "string" && entry.trim()
+        ? [stripAssetToken(entry)]
+        : []);
+}
+function overlapNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+        return value;
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed) && parsed >= 0)
+            return parsed;
+    }
+    return undefined;
+}
+export function normalizeChatRoutedParams(tool, source) {
+    const params = { ...source };
+    if (tool === "plan_chat_command") {
+        const context = params.media_context;
+        if (Array.isArray(context)) {
+            if (context.length === 1 && isMediaContextObject(context[0])) {
+                params.media_context = context[0];
+            }
+            else {
+                delete params.media_context;
+            }
+        }
+        return params;
+    }
+    if (tool === "chain") {
+        if ("steps" in params)
+            params.steps = ensureChainStepIds(params.steps);
+        return params;
+    }
+    if (tool !== "splice_video")
+        return params;
+    const assetIds = stringAssetIds(params.asset_ids);
+    if (typeof params.first_asset_id !== "string"
+        && assetIds.length >= 2) {
+        params.first_asset_id = assetIds[0];
+        params.second_asset_id = assetIds[1];
+        if (assetIds.length > 2)
+            params.additional_asset_ids = assetIds.slice(2);
+    }
+    if (typeof params.first_asset_id === "string") {
+        params.first_asset_id = stripAssetToken(params.first_asset_id);
+    }
+    if (typeof params.second_asset_id === "string") {
+        params.second_asset_id = stripAssetToken(params.second_asset_id);
+    }
+    const additional = stringAssetIds(params.additional_asset_ids);
+    if (additional.length > 0)
+        params.additional_asset_ids = additional;
+    const overlap = overlapNumber(params.overlap);
+    if (overlap !== undefined)
+        params.overlap = overlap;
+    else if (params.overlap === undefined)
+        params.overlap = 0;
+    delete params.asset_ids;
+    delete params.media_context;
+    return params;
+}
+export function normalizeChatTimestampParams(tool, source) {
+    const params = { ...source };
+    const timestampParams = TIMESTAMP_PARAMS[tool];
+    if (timestampParams) {
+        for (const paramName of timestampParams) {
+            if (!(paramName in params))
+                continue;
+            try {
+                params[paramName] = parseTime(params[paramName]);
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    const nestedTimestampParams = NESTED_TIMESTAMP_PARAMS[tool];
+    if (!nestedTimestampParams)
+        return params;
+    for (const [collectionName, fieldNames] of Object.entries(nestedTimestampParams)) {
+        const collection = params[collectionName];
+        if (!Array.isArray(collection))
+            continue;
+        params[collectionName] = collection.map((item) => {
+            if (typeof item !== "object" || item === null || Array.isArray(item))
+                return item;
+            const normalized = { ...item };
+            for (const fieldName of fieldNames) {
+                if (!(fieldName in normalized))
+                    continue;
+                try {
+                    normalized[fieldName] = parseTime(normalized[fieldName]);
+                }
+                catch {
+                    continue;
+                }
+            }
+            return normalized;
+        });
+    }
+    return params;
+}
+/** Close open strings / braces / brackets so truncated Gemini JSON can parse. */
+function closeTruncatedJson(text) {
+    let inString = false;
+    let escape = false;
+    const stack = [];
+    for (const ch of text) {
+        if (inString) {
+            if (escape) {
+                escape = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escape = true;
+                continue;
+            }
+            if (ch === "\"")
+                inString = false;
+            continue;
+        }
+        if (ch === "\"") {
+            inString = true;
+            continue;
+        }
+        if (ch === "{")
+            stack.push("}");
+        else if (ch === "[")
+            stack.push("]");
+        else if (ch === "}" || ch === "]") {
+            if (stack.length > 0 && stack[stack.length - 1] === ch)
+                stack.pop();
+        }
+    }
+    let out = text;
+    if (inString)
+        out += "\"";
+    // Drop a trailing incomplete property fragment: , "key or , "key": value-less
+    out = out.replace(/,\s*"[^"]*"\s*:\s*$/u, "");
+    out = out.replace(/,\s*"[^"]*$/u, "");
+    out = out.replace(/,\s*$/u, "");
+    // Re-scan stack after stripping incomplete tails
+    inString = false;
+    escape = false;
+    stack.length = 0;
+    for (const ch of out) {
+        if (inString) {
+            if (escape) {
+                escape = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escape = true;
+                continue;
+            }
+            if (ch === "\"")
+                inString = false;
+            continue;
+        }
+        if (ch === "\"") {
+            inString = true;
+            continue;
+        }
+        if (ch === "{")
+            stack.push("}");
+        else if (ch === "[")
+            stack.push("]");
+        else if (ch === "}" || ch === "]") {
+            if (stack.length > 0 && stack[stack.length - 1] === ch)
+                stack.pop();
+        }
+    }
+    if (inString)
+        out += "\"";
+    while (stack.length > 0)
+        out += stack.pop();
+    return out;
+}
+/** Best-effort repairs for common Gemini JSON glitches before JSON.parse. */
+export function repairChatRoutingJson(text) {
+    let out = text.trim();
+    // Strip trailing commas before } or ]
+    out = out.replace(/,(\s*[}\]])/g, "$1");
+    // Quote bare http(s) URLs used as property values
+    out = out.replace(/(:\s*)(https?:\/\/[^\s,"}\]]+)/g, (_m, prefix, url) => `${prefix}${JSON.stringify(url)}`);
+    // Quote bare @slug tokens used as property values
+    out = out.replace(/(:\s*)(@[\w-]+)/g, (_m, prefix, slug) => `${prefix}${JSON.stringify(slug)}`);
+    // Close truncated objects (missing final } / message field) — the live
+    // failure mode for create_watermark_card routing under Kie load.
+    out = closeTruncatedJson(out);
+    return out;
+}
+export function parseChatDecision(outputText) {
+    const attempts = [outputText, repairChatRoutingJson(outputText)];
+    let lastError;
+    for (const candidate of attempts) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (parsed && typeof parsed === "object" && typeof parsed.tool === "string") {
+                return {
+                    tool: parsed.tool,
+                    params: (parsed.params && typeof parsed.params === "object"
+                        ? parsed.params
+                        : {}),
+                    message: typeof parsed.message === "string" ? parsed.message : "",
+                };
+            }
+            lastError = new Error("Routing decision missing tool field");
+        }
+        catch (e) {
+            lastError = e;
+        }
+    }
+    const msg = lastError instanceof Error ? lastError.message : String(lastError);
+    const snippet = outputText.length > 200 ? `${outputText.slice(0, 200)}…` : outputText;
+    throw new Error(`${msg} (raw: ${JSON.stringify(snippet)})`);
+}
+export async function enrichAssetContext(engine, resolvedAssets) {
+    const rows = [];
+    for (const a of resolvedAssets) {
+        const row = {
+            tag: a.tag,
+            type: a.artifactType,
+            asset_id: a.artifactId,
+            has_file: a.filePath !== null,
+        };
+        const metaResult = await engine.metadata.artifacts.read(a.artifactId, "original");
+        if (metaResult.ok) {
+            const sourceUrl = typeof metaResult.value.source_url === "string"
+                ? metaResult.value.source_url
+                : typeof metaResult.value.webpage_url === "string"
+                    ? metaResult.value.webpage_url
+                    : null;
+            if (sourceUrl)
+                row.source_url = sourceUrl;
+        }
+        rows.push(row);
+    }
+    return rows;
+}
+export async function loadScriptContentsForChat(engine, resolvedAssets) {
+    const scriptContents = [];
+    for (const asset of resolvedAssets) {
+        if (asset.artifactType !== "script" || !asset.filePath)
+            continue;
+        const readResult = await engine.files.read(asset.artifactId, SCRIPT_FILENAME);
+        if (!readResult.ok)
+            continue;
+        const content = typeof readResult.value === "string"
+            ? readResult.value
+            : new TextDecoder().decode(readResult.value);
+        scriptContents.push({ tag: asset.tag, content });
+    }
+    return scriptContents;
+}
+function appendChatHistory(engine, input) {
+    void engine.logs
+        .append("chat", { role: "user", text: input.prompt, ts: Date.now() })
+        .catch(() => { });
+    void engine.logs
+        .append("chat", {
+        role: "assistant",
+        tool: input.tool,
+        params: input.params,
+        message: input.message,
+        error: input.failed,
+        ts: Date.now(),
+    })
+        .catch(() => { });
+}
+function autoApplyReason(tool, chainPausesPerStep = false) {
+    return tool === "duplicate_asset"
+        ? "Duplication is reversible and only adds a copied asset and cell"
+        : tool === "extract_audio"
+            ? "Audio extraction is free, local, and only adds derived media"
+            : tool === "chain"
+                ? chainPausesPerStep
+                    ? "Every step that spends money stops for its own review before it runs"
+                    : "This chain only reads or auto-applies existing local actions"
+                : "Frame extraction is free and only adds a new image cell";
+}
+async function applyChatActionPlan(engine, bookId, plan) {
+    if (plan.bookId !== bookId) {
+        return error("The chat action belongs to a different book");
+    }
+    if (plan.tool === "chat")
+        return error("Chat cannot route to itself");
+    if (plan.effect === "view")
+        return error("View actions open in the app and have nothing to apply");
+    const { getAllToolDefs } = await import("./index.js");
+    const targetDef = getAllToolDefs(engine).find((definition) => definition.name === plan.tool);
+    if (!targetDef)
+        return error(`Tool handler not found: ${plan.tool}`);
+    const params = { ...plan.params, book_id: bookId };
+    if (plan.tool === "chain" && "steps" in params) {
+        params.steps = ensureChainStepIds(params.steps);
+    }
+    const validated = z.object(targetDef.schema).safeParse(params);
+    if (!validated.success) {
+        return error(`Invalid parameters for ${plan.routedTool}: ${z.prettifyError(validated.error)}`);
+    }
+    const wrappedDef = withLogging(targetDef, engine);
+    let result;
+    try {
+        result = await wrappedDef.handler(validated.data);
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        result = error(`${plan.routedTool} failed: ${message}`);
+    }
+    appendChatHistory(engine, {
+        prompt: plan.prompt,
+        tool: plan.routedTool,
+        params: plan.params,
+        message: plan.message,
+        failed: Boolean(result.isError),
+    });
+    return result;
+}
+export { chatActionPlanSchema, duplicateDestinationReference };
+export function chatDef(engine) {
+    return {
+        name: "chat",
+        description: "Route one composer request through the app's chat model: runs reads and returns reviewable plans for edits and generation. Agents should call the specific tools directly instead.",
+        schema: {
+            prompt: z.string().min(1).optional().describe("Natural language query with optional @asset tags"),
+            book_id: z.string().uuid().describe("Book UUID"),
+            notebook_id: z.string().uuid().optional().describe("Open notebook UUID for resolving grid addresses"),
+            model: chatModelSchema.optional().describe("Chat routing model"),
+            action_plan: chatActionPlanSchema.optional().describe("Previously previewed action to apply"),
+        },
+        handler: (args) => handleChatRequest(engine, args),
+    };
+}
+export function prepareVoiceChatAction(engine, input, decision) {
+    return handleChatRequest(engine, input, decision);
+}
+async function handleChatRequest(engine, args, proposedDecision) {
+    const { prompt, book_id: bookId, notebook_id: notebookId, model, action_plan: actionPlan } = args;
+    if (actionPlan)
+        return await applyChatActionPlan(engine, bookId, actionPlan);
+    if (!prompt)
+        return error("A chat prompt is required");
+    const chatRequest = chatIntelligenceRequestOptions(model);
+    const book = engine.book.get();
+    let notebookDocument = null;
+    try {
+        if (notebookId) {
+            const notebook = engine.notebooks.read(notebookId);
+            if (!notebook.ok)
+                throw new Error(notebook.error.message);
+            notebookDocument = notebook.value;
+        }
+    }
+    catch (cause) {
+        return error(cause instanceof Error ? cause.message : String(cause));
+    }
+    const notebookContext = buildChatNotebookContext(engine, notebookDocument);
+    const notebookAddresses = notebookDocument
+        ? notebookMediaAddresses(notebookDocument)
+        : new Set();
+    // 0. Tag bare grid addresses ("the image at A1") so the steps below see the
+    // reference the speaker meant instead of prose.
+    const taggedPrompt = tagNotebookGridAddresses(prompt, notebookAddresses);
+    // 1. Expand @s01 slot refs → the artifact ids they occupy
+    const expandedPrompt = expandSlotRefs(taggedPrompt, timelineSlotArtifactIds(engine));
+    const stackedPlan = planStackedChainFromQuery(expandedPrompt);
+    if (stackedPlan) {
+        const { getAllToolDefs } = await import("./index.js");
+        const allDefs = getAllToolDefs(engine);
+        const targetDef = allDefs.find((definition) => definition.name === "chain");
+        if (!targetDef)
+            return error("Tool handler not found: chain");
+        const preflight = await preflightChainPlan({
+            action: "run",
+            version: 1,
+            book_id: bookId,
+            ...(notebookId ? { notebook_id: notebookId } : {}),
+            steps: stackedPlan.steps,
+        }, {
+            engine,
+            bookId,
+            notebookId,
+            toolSchemas: new Map(allDefs.map((definition) => [definition.name, definition.schema])),
+            autoApplyTools: AUTO_APPLY_TOOL_NAMES,
+            effectForTool: (name) => effectForTool(name, /^(?:generate|extend|upscale)_/u.test(name) ? "generation" : "action"),
+        });
+        if (!preflight.ok)
+            return error(preflight.error);
+        const params = {
+            action: "run",
+            version: 1,
+            book_id: bookId,
+            ...(notebookId ? { notebook_id: notebookId } : {}),
+            steps: stackedPlan.steps,
+        };
+        const validated = z.object(targetDef.schema).safeParse(params);
+        if (!validated.success) {
+            return error(`Invalid parameters for chain: ${z.prettifyError(validated.error)}`);
+        }
+        const effect = preflight.plan.effect === "generation"
+            ? "generation"
+            : "mutation";
+        const autoApply = preflight.plan.autoApply;
+        return json({
+            kind: "chat-action-plan",
+            planId: uuidv7(),
+            bookId,
+            prompt: taggedPrompt,
+            routedTool: "chain",
+            tool: "chain",
+            params: validated.data,
+            message: stackedPlan.message,
+            summary: stackedPlan.message,
+            effect,
+            confirmation: {
+                required: !autoApply,
+                reason: autoApply
+                    ? "This chain only reads or auto-applies existing local actions"
+                    : "This request changes the current book",
+            },
+        });
+    }
+    const notebookResolution = notebookDocument
+        ? resolveNotebookPromptReferences({
+            engine: engine,
+            document: notebookDocument,
+            prompt: expandedPrompt,
+            requireMedia: false,
+        })
+        : null;
+    const duplicateDestination = duplicateDestinationReference(expandedPrompt);
+    const resolutionPrompt = notebookResolution && duplicateDestination
+        ? replaceNotebookMentions(expandedPrompt, notebookResolution.resolved
+            .filter((item) => item.reference !== duplicateDestination)
+            .map((item) => ({
+            reference: item.reference,
+            replacement: `@${item.artifactId}`,
+        })))
+        : notebookResolution?.prompt ?? expandedPrompt;
+    const unresolvedNotebookReferences = notebookResolution?.unresolved
+        .filter((issue) => issue.reference !== duplicateDestination)
+        ?? [];
+    if (unresolvedNotebookReferences.length > 0) {
+        return error(`Asset not found: ${unresolvedNotebookReferences
+            .map((issue) => `${issue.mention} (${issue.code})`)
+            .join(", ")}`);
+    }
+    // 2. Resolve @<artifact-id> tags
+    const { resolved: resolvedAssets, unresolved } = await resolveArtifactRefs(engine, parseArtifactIdTags(resolutionPrompt));
+    if (unresolved.length > 0) {
+        return error(`Asset not found: ${unresolved.join(", ")}`);
+    }
+    // 3. Build asset context for the LLM (include source_url when known)
+    const assetContext = attachNotebookReferences(await enrichAssetContext(engine, resolvedAssets), notebookContext);
+    const imageFiles = resolvedAssets
+        .filter((asset) => asset.artifactType === "image")
+        .map((asset) => asset.filePath)
+        .filter((path) => path !== null);
+    const videoFiles = resolvedAssets
+        .filter((asset) => asset.artifactType === "video")
+        .map((asset) => asset.filePath)
+        .filter((path) => path !== null);
+    const scriptContents = await loadScriptContentsForChat(engine, resolvedAssets);
+    // 4. Read recent history for context
+    const historyLines = engine.logs.read("chat", {
+        limit: 10,
+    });
+    const historyContext = formatHistoryForPrompt(historyLines);
+    const initialDecision = proposedDecision ?? planBackgroundAudioFromQuery({
+        query: expandedPrompt, assetContext, notebookContext,
+    });
+    const apiKey = getApiKey("OPENAI_API_KEY");
+    if (!apiKey && !initialDecision) {
+        return error("OPENAI_API_KEY environment variable is not set");
+    }
+    const { getAllToolDefs } = await import("./index.js");
+    const allDefs = getAllToolDefs(engine);
+    const routableTools = buildRoutableTools(allDefs);
+    const systemPrompt = buildChatRoutingPrompt(book.name, routableTools, historyContext || undefined);
+    const userMessage = buildChatRoutingUserMessage({
+        query: expandedPrompt,
+        assetContext,
+        imageFiles,
+        videoFiles,
+        scriptContents,
+        notebookContext,
+    });
+    let decision;
+    if (initialDecision) {
+        decision = initialDecision;
+    }
+    else
+        try {
+            const responses = buildIntelligenceResponses(apiKey ?? undefined, {
+                timeout: CHAT_ROUTING_TIMEOUT_MS,
+                model: chatRequest.model,
+                reasoningEffort: chatRequest.reasoningEffort,
+            });
+            let lastError;
+            decision = { tool: "", params: {}, message: "" };
+            for (let attempt = 0; attempt < 2; attempt++) {
+                try {
+                    const response = await responses(intelligenceRequest({
+                        instructions: systemPrompt,
+                        input: userMessage,
+                        text: { format: { type: "json_object" } },
+                        max_output_tokens: CHAT_ROUTING_MAX_OUTPUT_TOKENS,
+                    }, chatRequest), AbortSignal.timeout(CHAT_ROUTING_TIMEOUT_MS));
+                    const outputText = firstResponseText(response);
+                    decision = parseChatDecision(outputText);
+                    lastError = null;
+                    break;
+                }
+                catch (e) {
+                    lastError = e;
+                }
+            }
+            if (lastError) {
+                const msg = lastError instanceof Error ? lastError.message : String(lastError);
+                return error(`Routing failed: ${msg}`);
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return error(`Routing failed: ${msg}`);
+        }
+    if (!decision.tool) {
+        return error("Could not determine which tool to use. Please rephrase.");
+    }
+    const bytedanceRoute = applyBytedanceNamedModelRoute({
+        query: expandedPrompt,
+        tool: decision.tool,
+        params: decision.params ?? {},
+        message: decision.message,
+        assetContext,
+    });
+    const joinRoute = bytedanceRoute.substituted
+        ? bytedanceRoute
+        : applyVideoJoinRoute({
+            query: expandedPrompt,
+            tool: bytedanceRoute.tool,
+            params: bytedanceRoute.params,
+            message: bytedanceRoute.message,
+            assetContext,
+            notebookContext,
+        });
+    const stackedRoute = joinRoute.substituted
+        ? joinRoute
+        : applyStackedChainRoute({
+            query: expandedPrompt,
+            tool: joinRoute.tool,
+            params: joinRoute.params,
+            message: joinRoute.message,
+            assetContext,
+            notebookContext,
+        });
+    const audioRoute = stackedRoute.substituted
+        ? stackedRoute
+        : applyBackgroundAudioRoute({
+            query: expandedPrompt,
+            tool: stackedRoute.tool,
+            params: stackedRoute.params,
+            message: stackedRoute.message,
+            assetContext,
+            notebookContext,
+        });
+    decision = {
+        tool: audioRoute.tool,
+        params: audioRoute.params,
+        // The voice path routes the spoken sentence here, so the sheet's title
+        // reads in the same vocabulary as the prompt beneath it.
+        message: tagNotebookGridAddresses(audioRoute.message, notebookAddresses),
+    };
+    // 6. Validate tool exists in routable registry
+    const routableTool = getRoutableTool(routableTools, decision.tool);
+    if (!routableTool) {
+        return error(`Unknown tool: ${decision.tool}. Please rephrase.`);
+    }
+    // A view opens in the app, so the plan carries the resolved target back
+    // instead of running a handler here.
+    if (routableTool.effect === "view") {
+        const view = resolveChatViewAction(engine, notebookDocument, routableTool.actualTool, decision.params ?? {});
+        if (!view.ok)
+            return error(view.message);
+        if (!proposedDecision)
+            appendChatHistory(engine, {
+                prompt: taggedPrompt,
+                tool: decision.tool,
+                params: view.params,
+                message: decision.message,
+                failed: false,
+            });
+        return json({
+            kind: "chat-action-plan",
+            planId: uuidv7(),
+            bookId,
+            prompt: taggedPrompt,
+            routedTool: decision.tool,
+            tool: routableTool.actualTool,
+            params: view.params,
+            message: decision.message,
+            summary: decision.message.trim() || "Show media fullscreen",
+            effect: "view",
+            confirmation: {
+                required: false,
+                reason: "Opening a view changes nothing in the book",
+            },
+        });
+    }
+    // 7. Apply fixups (spread to avoid mutating decision.params for logging)
+    const routedParams = normalizeChatRoutedParams(decision.tool, normalizeChatTimestampParams(decision.tool, decision.params ?? {}));
+    // The routing prompt asks the model to omit optional parameters so each tool
+    // can apply its defaults; enforce that for generation rather than trusting
+    // it, since an invented duration or a muted soundtrack costs a real
+    // generation. Reads the query, not the routed prompt, so only what the
+    // person actually said counts as asking.
+    const params = routableTool.category === "generation"
+        ? withoutUnrequestedSettings({
+            query: expandedPrompt,
+            params: routedParams,
+            requiredParams: routableTool.requiredParams,
+        }).params
+        : routedParams;
+    // Inject book_id
+    params.book_id = bookId;
+    if (notebookId
+        && routableTool.params.includes("notebook_id")
+        && params.notebook_id === undefined) {
+        params.notebook_id = notebookId;
+    }
+    // create_watermark_card needs a URL; if the model omitted it, take source_url
+    // from a referenced asset (e.g. "QR from the url in @vid-og").
+    if (decision.tool === "create_watermark_card" && (params.url === undefined || params.url === "")) {
+        const fromAsset = assetContext.find((a) => typeof a.source_url === "string");
+        if (fromAsset)
+            params.url = fromAsset.source_url;
+    }
+    // Inject script content as prompt for generation tools
+    const scriptIsPrompt = scriptContents.length > 0
+        && routableTool.category === "generation";
+    if (scriptIsPrompt) {
+        const combinedScript = scriptContents.map((s) => s.content).join("\n\n");
+        params.prompt = combinedScript;
+    }
+    // Generation routes: default the model, fold flat ref fields into refs, and
+    // default the ElevenLabs voice. Runs after the script injection above so
+    // script content reaches the prompt.
+    Object.assign(params, await applyGenerationRoutingDefaults(decision.tool, params));
+    // The voice model writes its own params, so a bare address can survive there
+    // even when the query carried none.
+    if (typeof params.prompt === "string") {
+        params.prompt = tagNotebookGridAddresses(params.prompt, notebookAddresses);
+    }
+    // Rewrite the routed prompt against the target model's guide, so the sheet
+    // reviews the prompt the provider will see rather than the sentence that
+    // picked the tool. A script the speaker attached is their own wording and
+    // stands as written. Runs last: the rewrite has to see resolved mentions to
+    // hand them back intact.
+    if (routableTool.category === "generation"
+        && !scriptIsPrompt
+        && typeof params.prompt === "string") {
+        params.prompt = await rewriteChatGenerationPrompt(engine, {
+            bookId,
+            model: typeof params.model === "string" ? params.model : "",
+            prompt: params.prompt,
+        });
+    }
+    // 8. Look up handler from tool defs
+    const targetDef = allDefs.find((d) => d.name === routableTool.actualTool);
+    if (!targetDef) {
+        return error(`Tool handler not found: ${routableTool.actualTool}`);
+    }
+    const validated = z.object(targetDef.schema).safeParse(params);
+    if (!validated.success) {
+        return error(`Invalid parameters for ${decision.tool}: ${z.prettifyError(validated.error)}`);
+    }
+    if (routableTool.effect !== "read") {
+        const effect = routableTool.effect;
+        const summary = decision.message.trim()
+            || `${effect === "generation" ? "Generate" : "Apply"} with ${decision.tool}`;
+        let autoApply = routableTool.autoApply;
+        let chainPausesPerStep = false;
+        if (targetDef.name === "chain") {
+            const preflight = await preflightChainPlan({
+                action: "run",
+                version: 1,
+                ...params,
+                book_id: bookId,
+            }, {
+                engine,
+                bookId,
+                notebookId,
+                toolSchemas: new Map(allDefs.map((definition) => [definition.name, definition.schema])),
+                autoApplyTools: AUTO_APPLY_TOOL_NAMES,
+                effectForTool: (name) => effectForTool(name, /^(?:generate|extend|upscale)_/u.test(name) ? "generation" : "action"),
+            });
+            if (!preflight.ok)
+                return error(preflight.error);
+            autoApply = preflight.plan.autoApply;
+            chainPausesPerStep = preflight.plan.steps.some((step) => step.requiresApproval);
+        }
+        return json({
+            kind: "chat-action-plan",
+            planId: uuidv7(),
+            bookId,
+            prompt: taggedPrompt,
+            routedTool: decision.tool,
+            tool: targetDef.name,
+            params: validated.data,
+            message: decision.message,
+            summary,
+            effect,
+            confirmation: {
+                required: !autoApply,
+                reason: autoApply
+                    ? autoApplyReason(targetDef.name, chainPausesPerStep)
+                    : effect === "generation"
+                        ? "This request creates generated media and may incur provider spend"
+                        : "This request changes the current book",
+            },
+        });
+    }
+    // 9. Execute (wrapped so the routed tool writes its own action log entry)
+    const wrappedDef = withLogging(targetDef, engine);
+    let handlerResult;
+    try {
+        handlerResult = await wrappedDef.handler(validated.data);
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        return error(`${decision.tool} failed: ${message}`);
+    }
+    if (!proposedDecision)
+        appendChatHistory(engine, {
+            prompt: taggedPrompt,
+            tool: decision.tool,
+            params: decision.params,
+            message: decision.message,
+            failed: Boolean(handlerResult.isError),
+        });
+    return handlerResult;
+}
+function error(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+function json(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}