@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/capabilities/media.js

@@ -0,0 +1,2258 @@
+/**
+ * The `media` capability module — provider-backed generation, plus the vision
+ * judges that grade what it produced.
+ *
+ * These capabilities replace the generation tools in `../tools/media-tools.ts`
+ * and the judging tools in `../tools/creative-critique-tools.ts`. Wire names,
+ * descriptions and schemas are unchanged; `getAllMcpTools` builds them through
+ * `toolFromCapability`.
+ *
+ * Every generation capability is a thin wrapper around
+ * `ProcessingContext.runProviderPrediction` (or `streamProviderPrediction`
+ * where the capability requires it), so it dispatches to whichever
+ * `BaseProvider` the id names and needs nothing on the run beyond its context.
+ *
+ * Outputs are saved as assets when the context exposes a `createAsset` model
+ * interface, and fall back to the caller-supplied `output_file` under the
+ * workspace when it does not.
+ *
+ * Design: docs/tool-class-retirement-design.md § Migration.
+ */
+import { Buffer } from "node:buffer";
+import { randomInt, randomUUID } from "node:crypto";
+import { mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { currentGenerationReceipt, loadMediaRefBytes } from "@nodetool-ai/runtime";
+import { getMaxLocalUploadBytes } from "@nodetool-ai/storage";
+import { backgroundGenerationLimitError, startBackgroundGeneration } from "./background-generation.js";
+import { HostBinaryMissingError, clampTimeoutSeconds, mimeFromFilename, runHostBinary } from "../host-binaries.js";
+import { MAX_DOWNLOAD_BYTES, buildYtDlpArgv, confineArgvToWorkspace, hardenFfmpegArgv, refuseFlagLikeValue } from "../host-binary-guard.js";
+import { assertFetchUrlAllowed, assertResolvedHostAllowed } from "../network-guard.js";
+import { encodeBase64 as encodeMediaBase64 } from "../sandbox-bytes.js";
+import { imagePixelSize, sniffImageFormat } from "../sandbox-media.js";
+import { DEFAULT_MIME, MAX_MEDIA_REF_BYTES, filesystemPathForUri, mimeForRef } from "../sandbox-media-ref.js";
+import { MIME_TO_EXT, inferImageMime, persistOutput, timestampedName } from "../tools/asset-persist.js";
+import { persistBinaryOutput } from "../tools/binary-output.js";
+import { extractJSON, extractJSONAllowingTruncation } from "../utils/json-parser.js";
+import { isYtDlpEnabled } from "../yt-dlp-gate.js";
+import { isFunction, isNonBlankString, isNonEmptyString, isObjectLike, isRecord, isString } from "../utils/type-guards.js";
+import { generateTextSpec, generateImageSpec, editImageSpec, segmentImageSpec, generateVideoSpec, animateImageSpec, videoFromReferencesSpec, generateSpeechSpec, generateMusicSpec, transcribeAudioSpec, embedTextSpec, readMediaBytesSpec, critiqueImageSpec, compareImagesSpec, scoreImageAdherenceSpec, understandVideoSpec, ffmpegSpec, ffprobeSpec, ytDlpSpec, DEFAULT_UNDERSTAND_VIDEO_TOKENS, DEFAULT_VIDEO_PROMPT, MAX_COMPARE_IMAGES, MAX_UNDERSTAND_VIDEO_TOKENS } from "./media.specs.js";
+const MAX_INLINE_TEXT_PREVIEW = 500;
+const MAX_ADHERENCE_QUESTIONS = 12;
+const JUDGE_MAX_TOKENS = 1500;
+const generateText = {
+    spec: generateTextSpec,
+    impl: async (run, params) => {
+        const m = parseModelArgs(params);
+        if ("error" in m)
+            return m;
+        const prompt = params["prompt"];
+        if (!isNonEmptyString(prompt))
+            return { error: "prompt is required" };
+        const imageValues = params["images"];
+        if (imageValues !== undefined && !Array.isArray(imageValues)) {
+            return { error: "images must be an array of strings" };
+        }
+        const images = (imageValues ?? []).filter(isNonEmptyString);
+        if (images.length !== (imageValues ?? []).length) {
+            return { error: "images must contain only non-empty strings" };
+        }
+        const content = [
+            ...images.map(imagePart),
+            textPart(prompt)
+        ];
+        const messages = [];
+        const system = params["system"];
+        if (isNonEmptyString(system)) {
+            messages.push({ role: "system", content: system });
+        }
+        messages.push({ role: "user", content });
+        const maxTokens = Math.max(1, Math.min(16384, Number(params["max_tokens"]) || 2048));
+        try {
+            const result = (await run.context.runProviderPrediction({
+                provider: m.provider,
+                capability: "generate_message",
+                model: m.model,
+                params: {
+                    messages,
+                    max_tokens: maxTokens,
+                    temperature: typeof params["temperature"] === "number"
+                        ? params["temperature"]
+                        : 0
+                }
+            }));
+            return {
+                type: "text",
+                provider: m.provider,
+                model: m.model,
+                text: messageText(result)
+            };
+        }
+        catch (error) {
+            return predictionError("generate_message", m, error);
+        }
+    }
+};
+function readModelId(value) {
+    return isNonEmptyString(value) ? value : undefined;
+}
+/**
+ * Read a provider+model from the shapes find_model actually returns: a hit
+ * (`provider` + `model_id` + `ref`), its `.ref` (`provider` + `id`), or the
+ * documented `{provider, model}` pair. Nested `model` objects win over the
+ * top-level pair so `generate_video({prompt, model: hit.ref})` works.
+ */
+function modelFromRecord(value) {
+    if (!isRecord(value))
+        return null;
+    if (isRecord(value.ref)) {
+        const fromRef = modelFromRecord(value.ref);
+        if (fromRef !== null)
+            return fromRef;
+    }
+    const provider = readModelId(value.provider);
+    const id = readModelId(value.model_id) ??
+        (isNonEmptyString(value.model) ? value.model : undefined) ??
+        readModelId(value.id);
+    if (provider !== undefined && id !== undefined) {
+        return { provider, model: id };
+    }
+    return null;
+}
+/**
+ * A provider rejection, with the model that was called in it.
+ *
+ * "text_to_video failed: Unprocessable Entity" told a live session nothing:
+ * the model it had picked was an image-to-video endpoint, and the message
+ * named neither the model nor the way out. `find_model` now filters by
+ * direction, and when a provider still refuses, the error says which model to
+ * re-pick.
+ */
+function predictionError(capability, m, e) {
+    const detail = e instanceof Error ? e.message : String(e);
+    return {
+        error: `${capability} failed for ${m.provider}:${m.model} — ${detail}. ` +
+            `If the model does not do ${capability}, pick another with ` +
+            `find_model({capability: "${capability}"}).`
+    };
+}
+function parseModelArgs(params) {
+    const fromModel = modelFromRecord(params.model);
+    if (fromModel !== null)
+        return fromModel;
+    if (isRecord(params.model) && isNonEmptyString(params.provider)) {
+        const nested = params.model;
+        const id = readModelId(nested.model_id) ??
+            readModelId(nested.id) ??
+            (isNonEmptyString(nested.model) ? nested.model : undefined);
+        if (id !== undefined) {
+            return { provider: params.provider, model: id };
+        }
+    }
+    const fromParams = modelFromRecord(params);
+    if (fromParams !== null)
+        return fromParams;
+    if (isNonEmptyString(params.model) && params.model.includes("/")) {
+        const slash = params.model.indexOf("/");
+        return {
+            provider: params.model.slice(0, slash),
+            model: params.model.slice(slash + 1)
+        };
+    }
+    if (!isNonEmptyString(params.provider)) {
+        return { error: "provider must be a non-empty string (use find_model)" };
+    }
+    if (!isNonEmptyString(params.model)) {
+        return { error: "model must be a non-empty string (use find_model)" };
+    }
+    return { provider: params.provider, model: params.model };
+}
+async function readWorkspaceOrAssetFile(context, inputFile) {
+    // asset:// URIs are the primary handle the generate_* capabilities return (an
+    // asset is created with no workspace copy), and the docs advertise asset://
+    // sources. Route them through the asset resolver — the workspace treats them
+    // as literal keys (asset://id.png → key "asset:/id.png") and fails.
+    if (inputFile.startsWith("asset://")) {
+        const { bytes } = await context.resolveAssetBytes(inputFile);
+        if (!bytes) {
+            throw new Error(`Asset not found: ${inputFile}`);
+        }
+        return bytes;
+    }
+    // Read through the workspace so a cloud deployment behaves like a local one.
+    if (!context.workspace) {
+        throw new Error("No workspace configured — cannot read input file.");
+    }
+    const bytes = await context.workspace.read(inputFile);
+    if (!bytes) {
+        throw new Error(`Input file not found in workspace: ${inputFile}`);
+    }
+    return bytes;
+}
+/**
+ * A generation that produced no handle is a failure, not a success.
+ *
+ * A run whose bytes never became an asset (no asset interface, `createAsset`
+ * threw, no workspace to fall back to) used to return `{type, provider, model,
+ * bytes, mime_type}` — success-shaped, with `asset_uri` undefined, which an
+ * agent printed as "OK undefined" and carried on from. Report what was missing
+ * instead.
+ */
+function outputError(capability, m, missing) {
+    return {
+        error: `${capability} for ${m.provider}:${m.model} returned no usable output — ${missing}.`
+    };
+}
+/** The provider's bytes, or null when it produced none. */
+function generatedBytes(result) {
+    return result instanceof Uint8Array && result.length > 0 ? result : null;
+}
+/** Whether a persisted output carries a handle the caller can read back. */
+function hasOutputHandle(persisted) {
+    return (isNonEmptyString(persisted.asset_uri) || isNonEmptyString(persisted.path));
+}
+// ---------------------------------------------------------------------------
+// The generation seam, as the capabilities use it
+// ---------------------------------------------------------------------------
+function toolCallIdOf(params) {
+    const id = params["_tool_call_id"];
+    return isNonEmptyString(id) ? id : null;
+}
+function outputFileOf(params) {
+    return isString(params["output_file"]) ? params["output_file"] : undefined;
+}
+/** The request every media capability hands `runGeneration`. */
+function generationRequest(id, params, spec) {
+    const outputFile = outputFileOf(params);
+    const persist = {};
+    if (outputFile)
+        persist.name = path.basename(outputFile);
+    if (spec.mime)
+        persist.mime = spec.mime;
+    return {
+        id,
+        provider: spec.m.provider,
+        capability: spec.capability,
+        model: spec.m.model,
+        params: spec.params,
+        origin: { surface: "capability", tool_call_id: toolCallIdOf(params) },
+        persist
+    };
+}
+/**
+ * Write the bytes where the caller can read them back: the asset the seam
+ * saved when it could, plus a workspace copy when `output_file` was named or
+ * no asset exists. `persistOutput` handles the no-asset case as before.
+ */
+async function finishOutput(context, bytes, assets, opts) {
+    const first = assets[0];
+    if (!first || !isNonEmptyString(first.asset_id)) {
+        return persistOutput(context, bytes, opts);
+    }
+    const result = {
+        bytes: bytes.length,
+        mime_type: opts.mime,
+        asset_id: first.asset_id,
+        asset_uri: first.uri,
+        url: first.uri
+    };
+    if (opts.outputFile && context.workspace) {
+        try {
+            await context.workspace.write(opts.outputFile, bytes, opts.mime);
+            result.path = opts.outputFile;
+        }
+        catch {
+            // Non-fatal — the asset is the handle.
+        }
+    }
+    return result;
+}
+/** What a `background: true` call answers with. */
+function backgroundReceipt(id, spec) {
+    return {
+        type: spec.type,
+        generation_id: id,
+        status: "running",
+        background: true,
+        provider: spec.m.provider,
+        model: spec.m.model,
+        capability: spec.capability,
+        next: "Call await_generation with this generation_id to collect the asset, or get_generation to check on it."
+    };
+}
+/**
+ * Start a generation without waiting for it. The seam records the row and
+ * saves the asset whether or not anyone awaits; the count is bounded so a
+ * loop cannot open an unbounded number of paid calls.
+ */
+function startMediaBackgroundGeneration(context, req, spec, params) {
+    const outputFile = outputFileOf(params);
+    const started = startBackgroundGeneration(context, async () => {
+        const result = await context.runGeneration(req);
+        const bytes = generatedBytes(result.output);
+        if (bytes && outputFile && context.workspace) {
+            await context.workspace.write(outputFile, bytes, spec.mime ?? inferImageMime(bytes));
+        }
+    });
+    if (!started) {
+        return backgroundGenerationLimitError();
+    }
+    return backgroundReceipt(req.id ?? "", spec);
+}
+/**
+ * Run one media generation through the seam and answer with the handle:
+ * the asset (and workspace path) plus the `generation_id` the `generations`
+ * capabilities take.
+ */
+async function runMediaGeneration(run, params, spec) {
+    const context = run.context;
+    const id = randomUUID();
+    const req = generationRequest(id, params, spec);
+    if (params["background"] === true) {
+        return startMediaBackgroundGeneration(context, req, spec, params);
+    }
+    try {
+        const result = await context.runGeneration(req);
+        const bytes = generatedBytes(result.output);
+        if (!bytes) {
+            return {
+                ...outputError(spec.capability, spec.m, `the provider returned no ${spec.type} data`),
+                generation_id: id
+            };
+        }
+        const persisted = await finishOutput(context, bytes, result.assets, {
+            namePrefix: spec.namePrefix,
+            mime: spec.mime ?? inferImageMime(bytes),
+            outputFile: outputFileOf(params)
+        });
+        if (!hasOutputHandle(persisted)) {
+            return {
+                ...outputError(spec.capability, spec.m, `the ${persisted.bytes}-byte result could not be stored (no asset was created and no workspace file was written)`),
+                generation_id: id
+            };
+        }
+        return {
+            type: spec.type,
+            provider: spec.m.provider,
+            model: spec.m.model,
+            generation_id: id,
+            ...persisted
+        };
+    }
+    catch (e) {
+        return {
+            ...predictionError(spec.capability, spec.m, e),
+            generation_id: id
+        };
+    }
+}
+const generateImage = {
+    spec: generateImageSpec,
+    impl: async (run, params) => {
+        const m = parseModelArgs(params);
+        if ("error" in m)
+            return m;
+        const prompt = params["prompt"];
+        if (!isNonEmptyString(prompt))
+            return { error: "prompt is required" };
+        return runMediaGeneration(run, params, {
+            capability: "text_to_image",
+            m,
+            type: "image",
+            namePrefix: "generated-image",
+            params: {
+                prompt,
+                negative_prompt: params["negative_prompt"],
+                width: params["width"],
+                height: params["height"],
+                quality: params["quality"]
+            }
+        });
+    }
+};
+const editImage = {
+    spec: editImageSpec,
+    impl: async (run, params) => {
+        const context = run.context;
+        const m = parseModelArgs(params);
+        if ("error" in m)
+            return m;
+        const inputFile = params["input_file"];
+        const prompt = params["prompt"];
+        if (!isNonEmptyString(inputFile))
+            return { error: "input_file is required" };
+        if (!isNonEmptyString(prompt))
+            return { error: "prompt is required" };
+        const referenceFiles = params["reference_files"];
+        if (referenceFiles !== undefined && !Array.isArray(referenceFiles))
+            return { error: "reference_files must be an array of strings" };
+        const references = (referenceFiles ?? []).filter(isNonEmptyString);
+        let images;
+        try {
+            images = await Promise.all([inputFile, ...references].map((file) => readWorkspaceOrAssetFile(context, file)));
+        }
+        catch (e) {
+            return predictionError("image_to_image", m, e);
+        }
+        return runMediaGeneration(run, params, {
+            capability: "image_to_image",
+            m,
+            type: "image",
+            namePrefix: "edited-image",
+            params: {
+                // `coerceImageList` reads the list; the source image stays first so a
+                // provider that treats one input as the canvas and the rest as style
+                // references gets them in that order.
+                images,
+                prompt,
+                negative_prompt: params["negative_prompt"],
+                target_width: params["target_width"],
+                target_height: params["target_height"],
+                strength: params["strength"]
+            }
+        });
+    }
+};
+/** Coerce one `points` entry from the model's arguments. */
+function parseSegmentPoint(value) {
+    if (!isRecord(value))
+        return null;
+    const x = value["x"];
+    const y = value["y"];
+    if (typeof x !== "number" || typeof y !== "number")
+        return null;
+    return { x, y, include: value["include"] !== false };
+}
+function parseSegmentBox(value) {
+    if (!isRecord(value))
+        return null;
+    const { x, y, width, height } = value;
+    if (typeof x !== "number" ||
+        typeof y !== "number" ||
+        typeof width !== "number" ||
+        typeof height !== "number") {
+        return null;
+    }
+    return { x, y, width, height };
+}
+const segmentImage = {
+    spec: segmentImageSpec,
+    impl: async (run, params) => {
+        const context = run.context;
+        const m = parseModelArgs(params);
+        if ("error" in m)
+            return m;
+        const inputFile = params["input_file"];
+        if (!isNonEmptyString(inputFile))
+            return { error: "input_file is required" };
+        const rawPoints = params["points"];
+        const points = Array.isArray(rawPoints)
+            ? rawPoints
+                .map(parseSegmentPoint)
+                .filter((p) => p !== null)
+            : [];
+        try {
+            const image = await readWorkspaceOrAssetFile(context, inputFile);
+            const masks = (await context.runProviderPrediction({
+                provider: m.provider,
+                capability: "segment_image",
+                model: m.model,
+                params: {
+                    image,
+                    prompt: params["prompt"],
+                    points: points.length > 0 ? points : undefined,
+                    box: parseSegmentBox(params["box"]) ?? undefined,
+                    max_masks: params["max_masks"],
+                    min_confidence: params["min_confidence"]
+                }
+            }));
+            const saved = [];
+            for (const [index, found] of masks.entries()) {
+                const persisted = await persistOutput(context, found.mask, {
+                    namePrefix: `segment-mask-${index + 1}`,
+                    mime: found.mimeType || inferImageMime(found.mask)
+                });
+                saved.push({
+                    label: found.label ?? null,
+                    confidence: found.confidence ?? null,
+                    box: found.box ?? null,
+                    width: found.width ?? null,
+                    height: found.height ?? null,
+                    ...persisted
+                });
+            }
+            return {
+                type: "segmentation",
+                provider: m.provider,
+                model: m.model,
+                // An empty list is the model's answer, not a failure — say so, because
+                // a bare `[]` reads as a broken call.
+                found: saved.length,
+                masks: saved
+            };
+        }
+        catch (e) {
+            return predictionError("segment_image", m, e);
+        }
+    }
+};
+/**
+ * Read a generation parameter under any of the spellings a caller reaches for.
+ *
+ * The schemas are snake_case, the JS guest API takes an options bag, and the
+ * `TextToVideo` node's own property is `duration` — so a build asked for a
+ * 15-second clip with `{duration: 15}`, was billed for the model's 5-second
+ * default, and had nothing in the result saying the argument had been dropped.
+ * A silently ignored parameter on a call that spends money is the expensive
+ * kind of typo, and every one of these spellings means one thing.
+ */
+function aliased(params, canonical, ...aliases) {
+    for (const key of [canonical, ...aliases]) {
+        const value = params[key];
+        if (value !== undefined && value !== null)
+            return value;
+    }
+    return undefined;
+}
+/** The generation parameters every video capability forwards, de-aliased. */
+function videoShapeParams(params) {
+    return {
+        num_frames: aliased(params, "num_frames", "numFrames", "frames"),
+        duration_seconds: aliased(params, "duration_seconds", "durationSeconds", "duration"),
+        aspect_ratio: aliased(params, "aspect_ratio", "aspectRatio", "aspect"),
+        resolution: aliased(params, "resolution")
+    };
+}
+/** The aspect ratios the video providers name, as width/height. */
+const ASPECT_RATIOS = [
+    ["21:9", 21 / 9],
+    ["16:9", 16 / 9],
+    ["4:3", 4 / 3],
+    ["1:1", 1],
+    ["3:4", 3 / 4],
+    ["9:16", 9 / 16]
+];
+/** The listed ratio closest to `width/height`, or null for a bad size. */
+export function nearestAspectRatio(width, height) {
+    if (!Number.isFinite(width) || !Number.isFinite(height))
+        return null;
+    if (width <= 0 || height <= 0)
+        return null;
+    const target = width / height;
+    let best = ASPECT_RATIOS[0];
+    for (const candidate of ASPECT_RATIOS) {
+        if (Math.abs(candidate[1] - target) < Math.abs(best[1] - target)) {
+            best = candidate;
+        }
+    }
+    return best[0];
+}
+const generateVideo = {
+    spec: generateVideoSpec,
+    impl: async (run, params) => {
+        const m = parseModelArgs(params);
+        if ("error" in m)
+            return m;
+        const prompt = params["prompt"];
+        if (!isNonEmptyString(prompt))
+            return { error: "prompt is required" };
+        return runMediaGeneration(run, params, {
+            capability: "text_to_video",
+            m,
+            type: "video",
+            namePrefix: "generated-video",
+            mime: "video/mp4",
+            params: {
+                prompt,
+                negative_prompt: aliased(params, "negative_prompt", "negativePrompt"),
+                ...videoShapeParams(params)
+            }
+        });
+    }
+};
+const animateImage = {
+    spec: animateImageSpec,
+    impl: async (run, params) => {
+        const context = run.context;
+        const m = parseModelArgs(params);
+        if ("error" in m)
+            return m;
+        const inputFile = params["input_file"];
+        if (!isNonEmptyString(inputFile))
+            return { error: "input_file is required" };
+        let image;
+        try {
+            image = await readWorkspaceOrAssetFile(context, inputFile);
+        }
+        catch (e) {
+            return predictionError("image_to_video", m, e);
+        }
+        const shape = videoShapeParams(params);
+        // A vertical still animated at the provider's default aspect comes back
+        // 16:9, cropped or padded, and the caller finds out when the ad is cut:
+        // three 1280x720 beds under a 1080x1920 sequence. The source image is the
+        // best statement of intent available, so it sets the ratio when the call
+        // does not.
+        if (shape.aspect_ratio === undefined) {
+            const size = imagePixelSize(image);
+            const derived = size ? nearestAspectRatio(size.width, size.height) : null;
+            if (derived)
+                shape.aspect_ratio = derived;
+        }
+        return runMediaGeneration(run, params, {
+            capability: "image_to_video",
+            m,
+            type: "video",
+            namePrefix: "animated-video",
+            mime: "video/mp4",
+            params: { image, prompt: params["prompt"], ...shape }
+        });
+    }
+};
+/** Extensions that state a reference's kind without reading its bytes. */
+const IMAGE_EXTENSIONS = new Set([
+    "png",
+    "jpg",
+    "jpeg",
+    "gif",
+    "bmp",
+    "webp",
+    "avif",
+    "heic",
+    "heif",
+    "tif",
+    "tiff"
+]);
+const VIDEO_EXTENSIONS = new Set([
+    "mp4",
+    "m4v",
+    "mov",
+    "webm",
+    "mkv",
+    "avi",
+    "mpeg",
+    "mpg",
+    "wmv"
+]);
+/**
+ * Whether a reference is an image or a video. The provider takes the two in
+ * separate lists — a video handed over as an image is rejected with an opaque
+ * provider error — so the kind has to be settled here.
+ *
+ * The extension decides when it says anything, because it is what the caller
+ * stated. Otherwise the bytes do: the image sniffer first (it owns the
+ * `ftyp`-based AVIF/HEIC cases), then the three video containers. A reference
+ * neither names nor looks like either is null, and the call refuses it rather
+ * than guessing.
+ */
+export function classifyReferenceMedia(file, bytes) {
+    const dot = file.lastIndexOf(".");
+    const ext = dot > -1 ? file.slice(dot + 1).toLowerCase() : "";
+    if (IMAGE_EXTENSIONS.has(ext))
+        return "image";
+    if (VIDEO_EXTENSIONS.has(ext))
+        return "video";
+    if (sniffImageFormat(bytes) !== "unknown")
+        return "image";
+    const at = (i) => bytes[i] ?? -1;
+    const tag = (offset, text) => [...text].every((ch, i) => at(offset + i) === ch.charCodeAt(0));
+    if (tag(4, "ftyp"))
+        return "video";
+    // Matroska / WebM EBML header.
+    if (at(0) === 0x1a && at(1) === 0x45 && at(2) === 0xdf && at(3) === 0xa3) {
+        return "video";
+    }
+    if (tag(0, "RIFF") && tag(8, "AVI "))
+        return "video";
+    return null;
+}
+const videoFromReferences = {
+    spec: videoFromReferencesSpec,
+    impl: async (run, params) => {
+        const context = run.context;
+        const m = parseModelArgs(params);
+        if ("error" in m)
+            return m;
+        const referenceFiles = params["reference_files"];
+        if (!Array.isArray(referenceFiles)) {
+            return { error: "reference_files must be an array of strings" };
+        }
+        const files = referenceFiles.filter(isNonEmptyString);
+        if (files.length === 0) {
+            return { error: "reference_files must name at least one reference" };
+        }
+        const images = [];
+        const videos = [];
+        for (const file of files) {
+            let bytes;
+            try {
+                bytes = await readWorkspaceOrAssetFile(context, file);
+            }
+            catch (e) {
+                return predictionError("reference_to_video", m, e);
+            }
+            const kind = classifyReferenceMedia(file, bytes);
+            if (kind === null) {
+                return {
+                    error: `${file} is neither an image nor a video — reference_to_video takes only those`
+                };
+            }
+            (kind === "image" ? images : videos).push(bytes);
+        }
+        const useReferenceVideoAudio = aliased(params, "use_reference_video_audio", "useReferenceVideoAudio");
+        if (useReferenceVideoAudio === true && videos.length === 0) {
+            return {
+                error: "use_reference_video_audio needs a reference video to take the audio from"
+            };
+        }
+        const shape = videoShapeParams(params);
+        // Same reasoning as animate_image: a vertical reference rendered at the
+        // provider's default lands 16:9 and the crop is found at the cut. The
+        // first image reference states the intended shape when the call does not.
+        if (shape.aspect_ratio === undefined && images.length > 0) {
+            const size = imagePixelSize(images[0]);
+            const derived = size ? nearestAspectRatio(size.width, size.height) : null;
+            if (derived)
+                shape.aspect_ratio = derived;
+        }
+        return runMediaGeneration(run, params, {
+            capability: "reference_to_video",
+            m,
+            type: "video",
+            namePrefix: "reference-video",
+            mime: "video/mp4",
+            params: {
+                reference_images: images,
+                reference_videos: videos,
+                prompt: params["prompt"],
+                negative_prompt: aliased(params, "negative_prompt", "negativePrompt"),
+                use_reference_video_audio: useReferenceVideoAudio,
+                ...shape
+            }
+        });
+    }
+};
+// ---------------------------------------------------------------------------
+// generate_speech
+// ---------------------------------------------------------------------------
+function int16ToUint8(samples) {
+    const bytes = new Uint8Array(samples.byteLength);
+    const view = new DataView(bytes.buffer);
+    for (let i = 0; i < samples.length; i++) {
+        view.setInt16(i * 2, samples[i], true);
+    }
+    return bytes;
+}
+/**
+ * Wrap raw little-endian int16 PCM bytes in a minimal RIFF/WAVE container so
+ * the file is playable. Defaults match OpenAI's TTS PCM stream (24 kHz mono).
+ */
+function wrapPcmAsWav(pcm, sampleRate = 24000, channels = 1) {
+    const bitsPerSample = 16;
+    const byteRate = (sampleRate * channels * bitsPerSample) / 8;
+    const blockAlign = (channels * bitsPerSample) / 8;
+    const header = new Uint8Array(44);
+    const v = new DataView(header.buffer);
+    const w = (s, off) => {
+        for (let i = 0; i < s.length; i++)
+            v.setUint8(off + i, s.charCodeAt(i));
+    };
+    w("RIFF", 0);
+    v.setUint32(4, 36 + pcm.length, true);
+    w("WAVE", 8);
+    w("fmt ", 12);
+    v.setUint32(16, 16, true); // PCM chunk size
+    v.setUint16(20, 1, true); // PCM format
+    v.setUint16(22, channels, true);
+    v.setUint32(24, sampleRate, true);
+    v.setUint32(28, byteRate, true);
+    v.setUint16(32, blockAlign, true);
+    v.setUint16(34, bitsPerSample, true);
+    w("data", 36);
+    v.setUint32(40, pcm.length, true);
+    const out = new Uint8Array(header.length + pcm.length);
+    out.set(header, 0);
+    out.set(pcm, header.length);
+    return out;
+}
+const AUDIO_EXT_TO_FORMAT = {
+    mp3: "mp3",
+    wav: "wav",
+    flac: "flac",
+    opus: "opus",
+    ogg: "opus",
+    aac: "aac",
+    m4a: "aac"
+};
+function audioFormatFromOutputFile(outputFile) {
+    if (!outputFile)
+        return null;
+    const ext = path.extname(outputFile).slice(1).toLowerCase();
+    return AUDIO_EXT_TO_FORMAT[ext] ?? null;
+}
+function concatUint8(parts) {
+    let total = 0;
+    for (const p of parts)
+        total += p.length;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const p of parts) {
+        out.set(p, offset);
+        offset += p.length;
+    }
+    return out;
+}
+/**
+ * Ask for fully-encoded speech through whichever seam this context has.
+ *
+ * `context.textToSpeechEncoded` is the one `nodetool.audio.TextToSpeech` uses,
+ * and the one that emits the prediction events a run is billed and traced by,
+ * so it is tried first. Reaching past it to `getProvider` was the only path
+ * before, and it cost every FAL and KIE voice on a context that carries the
+ * prediction seams but not `getProvider`: the TypeError landed in the caller's
+ * catch, and the streaming fallback then reported "fal_ai does not support
+ * textToSpeech" — of a provider whose entire TTS catalog is encoded.
+ */
+async function encodedSpeech(context, m, params, generation) {
+    if (isFunction(context.textToSpeechEncoded)) {
+        return await context.textToSpeechEncoded({
+            ...generation,
+            provider: m.provider,
+            capability: "text_to_speech",
+            model: m.model,
+            params: {
+                text: params.text,
+                voice: params.voice,
+                speed: params.speed,
+                audioFormat: params.audioFormat
+            }
+        });
+    }
+    if (isFunction(context.getProvider)) {
+        const provider = await context.getProvider(m.provider);
+        return await provider.textToSpeechEncoded({
+            text: params.text,
+            model: m.model,
+            voice: isString(params.voice) ? params.voice : undefined,
+            speed: typeof params.speed === "number" ? params.speed : undefined,
+            audioFormat: params.audioFormat
+        });
+    }
+    throw new Error("this runtime's context has no encoded text_to_speech path");
+}
+async function speechAudio(context, provider, m, params, signal, outputFile) {
+    signal.throwIfAborted();
+    const providerParams = {
+        text: params.text,
+        model: m.model,
+        voice: isString(params.voice) ? params.voice : undefined,
+        speed: typeof params.speed === "number" ? params.speed : undefined,
+        audioFormat: params.audioFormat,
+        signal
+    };
+    let encodedError;
+    try {
+        const encoded = provider
+            ? await provider.textToSpeechEncoded(providerParams)
+            : await encodedSpeech(context, m, params);
+        signal.throwIfAborted();
+        if (encoded?.data && encoded.data.length > 0) {
+            return {
+                data: encoded.data,
+                mimeType: encoded.mimeType ?? "audio/mpeg",
+                outputFile
+            };
+        }
+    }
+    catch (error) {
+        if (signal.aborted || currentGenerationReceipt()?.provider_request_id) {
+            throw error;
+        }
+        encodedError = error;
+    }
+    if (currentGenerationReceipt()?.provider_request_id) {
+        throw new Error("The accepted speech request returned no audio; recover that request before submitting another.");
+    }
+    const parts = [];
+    let pcmOnly = true;
+    let mimeType;
+    let sampleRate;
+    try {
+        const stream = provider
+            ? provider.textToSpeech(providerParams)
+            : context.streamProviderPrediction({
+                provider: m.provider,
+                capability: "text_to_speech",
+                model: m.model,
+                params: { ...providerParams, signal }
+            });
+        for await (const item of stream) {
+            signal.throwIfAborted();
+            if (!isRecord(item)) {
+                continue;
+            }
+            const chunk = item;
+            if (chunk.data instanceof Uint8Array || isString(chunk.data)) {
+                const data = chunk.data instanceof Uint8Array
+                    ? chunk.data
+                    : Buffer.from(chunk.data, "base64");
+                if (data.length > 0) {
+                    parts.push(data);
+                }
+                if (isString(chunk.mimeType)) {
+                    mimeType = chunk.mimeType;
+                }
+                pcmOnly = false;
+            }
+            else {
+                if (chunk.sampleRate !== undefined) {
+                    if (typeof chunk.sampleRate !== "number" ||
+                        !Number.isInteger(chunk.sampleRate) ||
+                        chunk.sampleRate <= 0 ||
+                        chunk.sampleRate > 0xffffffff / 2) {
+                        throw new Error("TTS returned an invalid PCM sample rate");
+                    }
+                    if (sampleRate !== undefined && sampleRate !== chunk.sampleRate) {
+                        throw new Error("TTS changed PCM sample rate during the stream");
+                    }
+                    sampleRate = chunk.sampleRate;
+                }
+                if (chunk.samples instanceof Int16Array && chunk.samples.length > 0) {
+                    parts.push(int16ToUint8(chunk.samples));
+                }
+            }
+        }
+    }
+    catch (error) {
+        if (encodedError) {
+            throw new Error(`${encodedError instanceof Error ? encodedError.message : String(encodedError)} (the streaming fallback then failed too: ${error instanceof Error ? error.message : String(error)})`);
+        }
+        throw error;
+    }
+    signal.throwIfAborted();
+    const merged = concatUint8(parts);
+    if (merged.length === 0) {
+        throw new Error("Provider returned no audio data");
+    }
+    if (pcmOnly && !mimeType) {
+        if (merged.length < 2 || merged.length % 2 !== 0) {
+            throw new Error("TTS produced no complete audio samples");
+        }
+        const finalPath = outputFile
+            ? path.join(path.dirname(outputFile), `${path.basename(outputFile, path.extname(outputFile))}.wav`)
+            : undefined;
+        return {
+            data: wrapPcmAsWav(merged, sampleRate ?? 24000),
+            mimeType: "audio/wav",
+            outputFile: finalPath
+        };
+    }
+    return { data: merged, mimeType: mimeType ?? "audio/mpeg", outputFile };
+}
+function runAudioGeneration(context, req, spec, params, call) {
+    const work = async () => {
+        let saved;
+        const result = await context.runGenerationWith(req, async (provider, signal) => {
+            const audio = await call(provider, signal);
+            if (audio.outputFile && req.persist) {
+                req.persist.name = path.basename(audio.outputFile);
+            }
+            return audio;
+        }, {
+            finalizeOutput: async (output, assets) => {
+                if (!isRecord(output) ||
+                    !(output.data instanceof Uint8Array) ||
+                    !isString(output.mimeType)) {
+                    throw new Error("Provider returned invalid audio output");
+                }
+                const mime = output.mimeType;
+                const first = assets[0];
+                saved = { bytes: output.data.length, mime_type: mime };
+                if (first?.asset_id) {
+                    saved.asset_id = first.asset_id;
+                    saved.asset_uri = first.uri;
+                    saved.url = first.uri;
+                }
+                const outputFile = isString(output.outputFile)
+                    ? output.outputFile
+                    : undefined;
+                if (outputFile || !saved.asset_id) {
+                    const destination = outputFile ??
+                        timestampedName(spec.namePrefix, MIME_TO_EXT[mime] ?? "bin");
+                    if (!context.workspace) {
+                        return {
+                            status: "failed",
+                            path: destination,
+                            error: `Could not deliver audio to "${destination}": no workspace is available.`
+                        };
+                    }
+                    try {
+                        await context.workspace.write(destination, output.data, mime);
+                    }
+                    catch (error) {
+                        return {
+                            status: "failed",
+                            path: destination,
+                            error: error instanceof Error ? error.message : String(error)
+                        };
+                    }
+                    saved.path = destination;
+                    return { status: "completed", path: destination };
+                }
+                return { status: "completed" };
+            }
+        });
+        const response = {
+            type: "audio",
+            provider: spec.m.provider,
+            model: spec.m.model,
+            generation_id: result.id,
+            ...saved
+        };
+        if (result.delivery) {
+            response.delivery = result.delivery;
+        }
+        return response;
+    };
+    if (params.background === true) {
+        if (!startBackgroundGeneration(context, work)) {
+            return backgroundGenerationLimitError();
+        }
+        return backgroundReceipt(req.id ?? "", spec);
+    }
+    return work().catch((error) => ({
+        ...predictionError(spec.capability, spec.m, error),
+        generation_id: req.id
+    }));
+}
+const generateSpeech = {
+    spec: generateSpeechSpec,
+    impl: async (run, params) => {
+        const m = parseModelArgs(params);
+        if ("error" in m) {
+            return m;
+        }
+        const text = params.text;
+        if (!isNonEmptyString(text)) {
+            return { error: "text is required" };
+        }
+        const outputFile = outputFileOf(params);
+        const speechParams = {
+            text,
+            voice: params.voice,
+            speed: params.speed,
+            audioFormat: audioFormatFromOutputFile(outputFile) ?? "mp3"
+        };
+        const spec = {
+            capability: "text_to_speech",
+            m,
+            type: "audio",
+            namePrefix: "generated-speech",
+            params: { ...speechParams }
+        };
+        const req = generationRequest(randomUUID(), params, spec);
+        return runAudioGeneration(run.context, req, spec, params, (provider, signal) => speechAudio(run.context, provider, m, speechParams, signal, outputFile));
+    }
+};
+const generateMusic = {
+    spec: generateMusicSpec,
+    impl: async (run, params) => {
+        const m = parseModelArgs(params);
+        if ("error" in m) {
+            return m;
+        }
+        const prompt = params.prompt;
+        if (!isNonEmptyString(prompt)) {
+            return { error: "prompt is required" };
+        }
+        const outputFile = outputFileOf(params);
+        const musicParams = {
+            prompt,
+            lyrics: params.lyrics,
+            duration_seconds: aliased(params, "duration_seconds", "durationSeconds", "duration"),
+            audioFormat: audioFormatFromOutputFile(outputFile) ?? "mp3"
+        };
+        const spec = {
+            capability: "text_to_music",
+            m,
+            type: "audio",
+            namePrefix: "generated-music",
+            params: musicParams
+        };
+        const req = generationRequest(randomUUID(), params, spec);
+        return runAudioGeneration(run.context, req, spec, params, async (provider, signal) => {
+            signal.throwIfAborted();
+            const encoded = provider
+                ? await provider.textToMusic({
+                    prompt,
+                    model: { id: m.model, name: m.model, provider: m.provider },
+                    lyrics: isString(params.lyrics) ? params.lyrics : undefined,
+                    durationSeconds: typeof musicParams.duration_seconds === "number"
+                        ? musicParams.duration_seconds
+                        : undefined,
+                    audioFormat: musicParams.audioFormat,
+                    signal
+                })
+                : await run.context.textToMusic(req);
+            signal.throwIfAborted();
+            if (!encoded?.data || encoded.data.length === 0) {
+                throw new Error("Provider returned no audio data");
+            }
+            return {
+                data: encoded.data,
+                mimeType: encoded.mimeType ?? "audio/mpeg",
+                outputFile
+            };
+        });
+    }
+};
+const transcribeAudio = {
+    spec: transcribeAudioSpec,
+    impl: async (run, params) => {
+        const context = run.context;
+        const m = parseModelArgs(params);
+        if ("error" in m)
+            return m;
+        const inputFile = params["input_file"];
+        if (!isNonEmptyString(inputFile))
+            return { error: "input_file is required" };
+        try {
+            const audio = await readWorkspaceOrAssetFile(context, inputFile);
+            const result = (await context.runProviderPrediction({
+                provider: m.provider,
+                capability: "automatic_speech_recognition",
+                model: m.model,
+                params: {
+                    audio,
+                    language: params["language"],
+                    prompt: params["prompt"]
+                }
+            }));
+            const text = String(result.text ?? "");
+            return {
+                type: "transcription",
+                provider: m.provider,
+                model: m.model,
+                text: text.length > MAX_INLINE_TEXT_PREVIEW
+                    ? text.slice(0, MAX_INLINE_TEXT_PREVIEW) +
+                        `… [${text.length - MAX_INLINE_TEXT_PREVIEW} chars truncated]`
+                    : text,
+                full_length: text.length,
+                chunks: Array.isArray(result.chunks) ? result.chunks.length : 0
+            };
+        }
+        catch (e) {
+            return {
+                error: `transcribe failed: ${e instanceof Error ? e.message : String(e)}`
+            };
+        }
+    }
+};
+const embedText = {
+    spec: embedTextSpec,
+    impl: async (run, params) => {
+        const context = run.context;
+        const m = parseModelArgs(params);
+        if ("error" in m)
+            return m;
+        const text = params["text"];
+        if (!isString(text) && !Array.isArray(text))
+            return { error: "text must be a string or array of strings" };
+        try {
+            const result = (await context.runProviderPrediction({
+                provider: m.provider,
+                capability: "generate_embedding",
+                model: m.model,
+                params: {
+                    text,
+                    dimensions: params["dimensions"]
+                }
+            }));
+            return {
+                type: "embedding",
+                provider: m.provider,
+                model: m.model,
+                count: result.length,
+                dimensions: result[0]?.length ?? 0,
+                embeddings: result
+            };
+        }
+        catch (e) {
+            return {
+                error: `generate_embedding failed: ${e instanceof Error ? e.message : String(e)}`
+            };
+        }
+    }
+};
+function parseJudgeModelArgs(params) {
+    const provider = params["provider"];
+    const model = params["model"];
+    if (!isNonEmptyString(provider)) {
+        return {
+            error: "provider must be a non-empty string (use find_model with a vision-capable chat model)"
+        };
+    }
+    if (!isNonEmptyString(model)) {
+        return {
+            error: "model must be a non-empty string (use find_model with a vision-capable chat model)"
+        };
+    }
+    return { provider, model };
+}
+/** Normalize a media source so the context media resolver can inline it. */
+function normalizeMediaSource(source) {
+    const trimmed = source.trim();
+    if (trimmed.startsWith("data:") ||
+        trimmed.startsWith("asset://") ||
+        /^https?:\/\//i.test(trimmed)) {
+        return trimmed;
+    }
+    // Bare asset ids (what list_images and generate_image return) become
+    // asset:// URIs, which resolveMessageMediaUris inlines as data URIs.
+    return `asset://${trimmed}`;
+}
+function imagePart(source) {
+    return {
+        type: "image_url",
+        image: { type: "image", uri: normalizeMediaSource(source) }
+    };
+}
+function videoPart(source) {
+    return {
+        type: "video",
+        video: { type: "video", uri: normalizeMediaSource(source) }
+    };
+}
+function textPart(text) {
+    return { type: "text", text };
+}
+/** Pull the text out of a provider response message. */
+function messageText(message) {
+    const content = message.content;
+    if (isString(content))
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => (part.type === "text" ? part.text : ""))
+            .filter(Boolean)
+            .join("\n");
+    }
+    return "";
+}
+async function judgeCall(context, m, content, maxTokens = JUDGE_MAX_TOKENS, requiredImages) {
+    const result = (await context.runProviderPrediction({
+        provider: m.provider,
+        capability: "generate_message",
+        model: m.model,
+        params: {
+            messages: [{ role: "user", content }],
+            max_tokens: maxTokens,
+            temperature: 0,
+            strict_image_evidence: content.some((part) => part.type === "image_url") ||
+                Boolean(requiredImages?.length),
+            required_images: requiredImages?.map(normalizeMediaSource)
+        }
+    }));
+    return messageText(result);
+}
+/**
+ * Whether a model reply reads as cut off rather than merely wrong.
+ *
+ * A judge on a reasoning model spends its ceiling thinking and returns half a
+ * sentence; the caller then sees "did not return parseable JSON" and re-runs
+ * the same call at the same budget. Naming the cause in the error is the
+ * difference between one retry and three.
+ */
+export function looksTruncated(text) {
+    const trimmed = text.trimEnd();
+    if (trimmed.length === 0)
+        return false;
+    if (/[.!?\]}"]$/.test(trimmed))
+        return false;
+    return true;
+}
+function tasteBlock(params) {
+    const profile = params["taste_profile"];
+    if (!isNonBlankString(profile))
+        return "";
+    return `\n\nThe user's known aesthetic preferences (weigh these alongside the brief):\n${profile.trim()}`;
+}
+/**
+ * A critique out of a judge reply, whole or cut short.
+ *
+ * The reply is a report, not an instruction: a `verdict` plus two lists whose
+ * entries stand alone. A judge that hits its token ceiling mid-list has still
+ * said everything before the cut, so a truncated reply is salvaged rather than
+ * thrown away — before this, a run lost a usable verdict and every defect the
+ * judge had already named.
+ */
+function parseCritique(text) {
+    const parsed = extractJSONAllowingTruncation(text);
+    if (!isRecord(parsed)) {
+        return null;
+    }
+    const obj = parsed;
+    const verdict = obj["verdict"] === "pass" ? "pass" : "revise";
+    const defects = Array.isArray(obj["defects"])
+        ? obj["defects"]
+            .filter(isObjectLike)
+            .map((d) => ({
+            defect: String(d["defect"] ?? ""),
+            location: String(d["location"] ?? ""),
+            fix: String(d["fix"] ?? "")
+        }))
+            .filter((d) => d.defect)
+        : [];
+    const strengths = Array.isArray(obj["strengths"])
+        ? obj["strengths"].map(String).filter(Boolean)
+        : [];
+    return { verdict, defects, strengths };
+}
+const critiqueImage = {
+    spec: critiqueImageSpec,
+    impl: async (run, params) => {
+        const context = run.context;
+        const m = parseJudgeModelArgs(params);
+        if ("error" in m)
+            return m;
+        const image = params["image"];
+        const brief = params["brief"];
+        if (!isNonEmptyString(image))
+            return { error: "image is required" };
+        if (!isNonEmptyString(brief))
+            return { error: "brief is required" };
+        const prompt = `You are a demanding art director reviewing one image against a brief.` +
+            `\n\nBrief:\n${brief}${tasteBlock(params)}` +
+            `\n\nExamine the image and report only defects you can point at: things that are` +
+            ` wrong, missing relative to the brief, or technically broken (anatomy, geometry,` +
+            ` illegible text, composition, lighting inconsistencies). For each defect say` +
+            ` exactly where it is and the concrete change that fixes it.` +
+            `\n\nRules:` +
+            `\n- Never suggest adding embellishment or "more detail" — only fixes to named problems.` +
+            `\n- If the composition itself is wrong for the brief, say so explicitly; that means` +
+            ` regenerating, not patching.` +
+            `\n- Verdict "pass" only if the image fulfills the brief with no defect a client would notice.` +
+            `\n\nRespond with JSON only:` +
+            `\n{"verdict": "pass" | "revise", "defects": [{"defect": "...", "location": "...",` +
+            ` "fix": "..."}], "strengths": ["..."]}`;
+        try {
+            const text = await judgeCall(context, m, [
+                textPart(prompt),
+                imagePart(image)
+            ]);
+            const critique = parseCritique(text);
+            if (!critique) {
+                return {
+                    error: `Judge did not return parseable JSON` +
+                        `${looksTruncated(text) ? " (the reply stops mid-sentence — it hit the token ceiling; raise max_tokens or pick a model that does not spend the budget on reasoning)" : ""}` +
+                        `: ${text.slice(0, 300)}`
+                };
+            }
+            return {
+                type: "critique",
+                provider: m.provider,
+                model: m.model,
+                ...critique
+            };
+        }
+        catch (e) {
+            return {
+                error: `critique_image failed: ${e instanceof Error ? e.message : String(e)}`
+            };
+        }
+    }
+};
+function parsePairVerdict(text) {
+    const parsed = extractJSONAllowingTruncation(text);
+    if (!isRecord(parsed))
+        return null;
+    const obj = parsed;
+    const winner = Number(obj["winner"]);
+    if (winner !== 1 && winner !== 2)
+        return null;
+    return { winner, reason: String(obj["reason"] ?? "") };
+}
+const compareImages = {
+    spec: compareImagesSpec,
+    impl: async (run, params) => {
+        const context = run.context;
+        const m = parseJudgeModelArgs(params);
+        if ("error" in m)
+            return m;
+        const images = params["images"];
+        const brief = params["brief"];
+        if (!Array.isArray(images) ||
+            images.length < 2 ||
+            images.some((i) => !isNonEmptyString(i))) {
+            return { error: "images must be an array of 2-8 non-empty strings" };
+        }
+        if (images.length > MAX_COMPARE_IMAGES) {
+            return {
+                error: `images must contain at most ${MAX_COMPARE_IMAGES} candidates`
+            };
+        }
+        if (!isNonEmptyString(brief))
+            return { error: "brief is required" };
+        const prompt = `You are judging which of two images better fulfills a creative brief.` +
+            `\n\nBrief:\n${brief}${tasteBlock(params)}` +
+            `\n\nImage 1 is shown first, image 2 second. Judge fulfillment of the brief and` +
+            ` craft (composition, coherence, technical execution) — not which image is busier` +
+            ` or more embellished. You must pick exactly one winner.` +
+            `\n\nRespond with JSON only: {"winner": 1 | 2, "reason": "one sentence"}`;
+        const judgePair = async (a, b) => {
+            const call = async (first, second) => {
+                const text = await judgeCall(context, m, [textPart(prompt), imagePart(first), imagePart(second)], JUDGE_MAX_TOKENS, images.map(String));
+                const verdict = parsePairVerdict(text);
+                if (!verdict) {
+                    throw new Error(`Judge did not return parseable JSON: ${text.slice(0, 200)}`);
+                }
+                return {
+                    winner: verdict.winner === 1 ? first : second,
+                    reason: verdict.reason
+                };
+            };
+            try {
+                // Same pair, both presentation orders: an order-dependent preference
+                // cancels out; only a stable preference wins outright.
+                const [forward, reversed] = [await call(a, b), await call(b, a)];
+                if (forward.winner === reversed.winner) {
+                    return { winner: forward.winner, reason: forward.reason };
+                }
+                // crypto randomInt over Math.random: not security-sensitive (it only
+                // picks the tiebreak presentation order), but it keeps CodeQL's
+                // insecure-randomness rule quiet without an exception.
+                const tiebreak = randomInt(2) === 0 ? await call(a, b) : await call(b, a);
+                return {
+                    winner: tiebreak.winner,
+                    reason: `(order-sensitive verdict, tiebreak) ${tiebreak.reason}`
+                };
+            }
+            catch (e) {
+                return { error: e instanceof Error ? e.message : String(e) };
+            }
+        };
+        const matches = [];
+        let round = images.map(String);
+        try {
+            while (round.length > 1) {
+                const next = [];
+                for (let i = 0; i + 1 < round.length; i += 2) {
+                    const result = await judgePair(round[i], round[i + 1]);
+                    if ("error" in result)
+                        return { error: `compare_images failed: ${result.error}` };
+                    matches.push({
+                        a: round[i],
+                        b: round[i + 1],
+                        winner: result.winner,
+                        agreed: !result.reason.startsWith("(order-sensitive"),
+                        reason: result.reason
+                    });
+                    next.push(result.winner);
+                }
+                if (round.length % 2 === 1)
+                    next.push(round[round.length - 1]);
+                round = next;
+            }
+        }
+        catch (e) {
+            return {
+                error: `compare_images failed: ${e instanceof Error ? e.message : String(e)}`
+            };
+        }
+        return {
+            type: "comparison",
+            provider: m.provider,
+            model: m.model,
+            winner: round[0],
+            matches,
+            note: "Winner of a pairwise knockout. Other candidates were not deleted — " +
+                "surface them to the user if the pick looks wrong."
+        };
+    }
+};
+const scoreImageAdherence = {
+    spec: scoreImageAdherenceSpec,
+    impl: async (run, params) => {
+        const context = run.context;
+        const m = parseJudgeModelArgs(params);
+        if ("error" in m)
+            return m;
+        const image = params["image"];
+        const brief = params["brief"];
+        if (!isNonEmptyString(image))
+            return { error: "image is required" };
+        if (!isNonEmptyString(brief))
+            return { error: "brief is required" };
+        try {
+            let questions = Array.isArray(params["questions"])
+                ? params["questions"].map(String).filter(Boolean)
+                : [];
+            if (questions.length === 0) {
+                const decomposeText = await judgeCall(context, m, [
+                    textPart(`Decompose this creative brief into at most ${MAX_ADHERENCE_QUESTIONS} atomic` +
+                        ` yes/no questions, each verifiable by looking at a single image. Cover every` +
+                        ` explicit requirement (subjects, counts, colors, text, style, composition,` +
+                        ` mood). Phrase each so "yes" means the requirement is met. Skip anything not` +
+                        ` visually checkable.` +
+                        `\n\nBrief:\n${brief}` +
+                        `\n\nRespond with JSON only: {"questions": ["..."]}`)
+                ], JUDGE_MAX_TOKENS, [image]);
+                const parsed = extractJSON(decomposeText);
+                const list = isRecord(parsed) ? parsed["questions"] : parsed;
+                questions = Array.isArray(list) ? list.map(String).filter(Boolean) : [];
+                if (questions.length === 0) {
+                    return {
+                        error: `Could not decompose the brief into checks: ${decomposeText.slice(0, 300)}`
+                    };
+                }
+            }
+            questions = questions.slice(0, MAX_ADHERENCE_QUESTIONS);
+            const checks = questions.map((question, i) => ({
+                id: `q${i + 1}`,
+                question
+            }));
+            const answerText = await judgeCall(context, m, [
+                textPart(`Answer each question about the image with a strict yes or no. "yes" only if` +
+                    ` the image clearly satisfies it; when unsure, answer "no" and say why in the note.` +
+                    `\n\nQuestions:\n${checks.map((q) => `${q.id}: ${q.question}`).join("\n")}` +
+                    `\n\nRespond with JSON only:` +
+                    `\n{"answers": [{"id": "q1", "question": "...", "answer": "yes" | "no", "note": "..."}]}`),
+                imagePart(image)
+            ]);
+            const parsed = extractJSON(answerText);
+            const rawAnswers = isRecord(parsed) ? parsed["answers"] : null;
+            if (!Array.isArray(rawAnswers) || rawAnswers.length === 0) {
+                return {
+                    error: `Judge did not return parseable answers: ${answerText.slice(0, 300)}`,
+                    evidence_status: "invalid",
+                    total: checks.length,
+                    missing_ids: checks.map((check) => check.id)
+                };
+            }
+            const byId = new Map();
+            const invalid = [];
+            for (const raw of rawAnswers) {
+                if (!isRecord(raw)) {
+                    invalid.push("answer must be an object");
+                    continue;
+                }
+                const id = String(raw["id"] ?? "");
+                const check = checks.find((c) => c.id === id);
+                if (!check || raw["question"] !== check.question) {
+                    invalid.push(`unrequested or substituted check: ${id}`);
+                    continue;
+                }
+                if (byId.has(id)) {
+                    invalid.push(`duplicate check: ${id}`);
+                    continue;
+                }
+                if (raw["answer"] !== "yes" && raw["answer"] !== "no") {
+                    invalid.push(`invalid answer: ${id}`);
+                    continue;
+                }
+                byId.set(id, {
+                    id,
+                    question: check.question,
+                    answer: raw["answer"],
+                    note: String(raw["note"] ?? "")
+                });
+            }
+            const missingIds = checks.filter((c) => !byId.has(c.id)).map((c) => c.id);
+            if (invalid.length || missingIds.length) {
+                return {
+                    error: "Judge returned invalid or incomplete adherence evidence",
+                    evidence_status: "invalid",
+                    total: checks.length,
+                    missing_ids: missingIds,
+                    invalid
+                };
+            }
+            const answers = [];
+            for (const check of checks) {
+                const answer = byId.get(check.id);
+                if (answer) {
+                    answers.push(answer);
+                }
+            }
+            const passed = answers.filter((a) => a.answer === "yes").length;
+            return {
+                type: "adherence",
+                evidence_status: "complete",
+                provider: m.provider,
+                model: m.model,
+                score: passed / checks.length,
+                passed,
+                total: checks.length,
+                failed: answers.filter((a) => a.answer === "no"),
+                answers
+            };
+        }
+        catch (e) {
+            return {
+                error: `score_image_adherence failed: ${e instanceof Error ? e.message : String(e)}`
+            };
+        }
+    }
+};
+// ---------------------------------------------------------------------------
+// understand_video
+// ---------------------------------------------------------------------------
+/**
+ * Read a video with a multimodal chat model.
+ *
+ * The video rides as a `video` content part next to the instruction; the
+ * context's media resolver inlines an `asset://` URI and the provider decides
+ * whether the bytes go inline or through its files API.
+ *
+ * A provider with no video content part is not refused here any more: the
+ * runtime samples the clip into stills with ffmpeg and sends those. The reply
+ * carries `read_as` so the caller knows which of the two it got — a frame read
+ * has no audio and nothing between the samples, and an answer that depends on
+ * either should be treated as a guess.
+ */
+const understandVideo = {
+    spec: understandVideoSpec,
+    impl: async (run, params) => {
+        const m = parseJudgeModelArgs(params);
+        if ("error" in m)
+            return m;
+        const video = params["video"];
+        if (!isNonEmptyString(video)) {
+            return { error: "video is required" };
+        }
+        const promptParam = params["prompt"];
+        const prompt = isNonBlankString(promptParam)
+            ? promptParam
+            : DEFAULT_VIDEO_PROMPT;
+        const requested = Number(params["max_tokens"]);
+        const maxTokens = Number.isFinite(requested) && requested > 0
+            ? Math.min(Math.floor(requested), MAX_UNDERSTAND_VIDEO_TOKENS)
+            : DEFAULT_UNDERSTAND_VIDEO_TOKENS;
+        try {
+            const native = await run.context.providerSupportsVideoInput(m.provider);
+            const text = await judgeCall(run.context, m, [textPart(prompt), videoPart(video)], maxTokens);
+            return {
+                text,
+                provider: m.provider,
+                model: m.model,
+                read_as: native ? "video" : "sampled_frames",
+                // A reasoning model spends `max_tokens` on thinking and returns a
+                // fragment. Without this the caller reads half an answer as the whole
+                // answer — one run acted on "the clip shows a man attempting to" and
+                // never learned the sentence had been cut.
+                truncated: looksTruncated(text),
+                max_tokens: maxTokens
+            };
+        }
+        catch (e) {
+            return {
+                error: `understand_video failed: ${e instanceof Error ? e.message : String(e)}`
+            };
+        }
+    }
+};
+/**
+ * The gated read behind a media reference.
+ *
+ * The sandbox's own `media.bytes` needs a `ProcessingContext`, which a chat
+ * action deliberately runs without (#4780) — so a chat user could generate an
+ * image and never read it back. This is the same resolution past the
+ * permission gate, with the context the run already carries.
+ *
+ * A filesystem path is refused rather than contained here: `read_file` is the
+ * gated way to a workspace file, and a second containment rule beside
+ * `resolveGuestPath` is the thing worth not having.
+ */
+const readMediaBytes = {
+    spec: readMediaBytesSpec,
+    impl: async (run, params) => {
+        const uri = params.uri;
+        if (!isNonBlankString(uri)) {
+            return { error: "uri is required and must be a non-empty string" };
+        }
+        const trimmed = uri.trim();
+        if (filesystemPathForUri(trimmed) !== null) {
+            return {
+                error: `read_media_bytes does not read filesystem paths (${trimmed}). Use read_file for a workspace file, or pass an asset:// URI.`
+            };
+        }
+        // A bare id is what an agent reaches for after reading `asset_id` off a
+        // generation result; accept it rather than making that a failed round trip.
+        const ref = trimmed.includes("://")
+            ? { uri: trimmed }
+            : { uri: trimmed, asset_id: trimmed };
+        try {
+            const bytes = await loadMediaRefBytes(ref, run.context);
+            if (!bytes) {
+                return {
+                    error: `Could not read ${trimmed}. Pass the asset:// URI a generation returned (its asset_uri), or list_assets to find one.`
+                };
+            }
+            if (bytes.length > MAX_MEDIA_REF_BYTES) {
+                return {
+                    error: `${trimmed} is ${bytes.length} bytes, over the ${MAX_MEDIA_REF_BYTES} byte limit`
+                };
+            }
+            return {
+                uri: trimmed,
+                size: bytes.length,
+                mime_type: mimeForRef(ref, DEFAULT_MIME.document),
+                content_base64: encodeMediaBase64(bytes)
+            };
+        }
+        catch (e) {
+            return {
+                error: `read_media_bytes failed: ${e instanceof Error ? e.message : String(e)}`
+            };
+        }
+    }
+};
+/**
+ * A real directory a host media binary can run in, plus the workspace it
+ * belongs to.
+ *
+ * A local workspace *is* that directory, so the binary reads and writes the
+ * user's files in place. A cloud workspace has no directory, so the run gets a
+ * scratch one: inputs named in argv are staged into it beforehand
+ * ({@link stageHostBinaryInputs}) and the output is read back out of it
+ * afterwards ({@link persistWorkspaceFile}). Either way the binary sees plain
+ * paths and needs no knowledge of where the workspace actually lives.
+ */
+async function hostBinaryRoot(context) {
+    const workspace = context.workspace;
+    if (!workspace) {
+        return { error: "a workspace is required to run a host media binary" };
+    }
+    try {
+        return { workspace, cwd: await workspace.scratchDir() };
+    }
+    catch (e) {
+        return {
+            error: `could not prepare a working directory: ${e instanceof Error ? e.message : String(e)}`
+        };
+    }
+}
+/**
+ * Copy every argv path that names an existing workspace file into the scratch
+ * directory, so the binary finds its inputs where it expects them.
+ *
+ * A no-op on a local workspace, where the scratch directory is the workspace.
+ * Only whole arguments are staged: an input reaches ffmpeg as its own argv
+ * entry (`-i clip.mp4`), and a path buried inside a filter token names an
+ * output far more often than an input.
+ */
+async function stageHostBinaryInputs(workspace, argv) {
+    if (workspace.localDir)
+        return;
+    for (const arg of argv) {
+        if (!arg || arg.startsWith("-"))
+            continue;
+        try {
+            if (await workspace.exists(arg))
+                await workspace.materialize(arg);
+        }
+        catch {
+            // Not a workspace path, or not readable — the binary reports it.
+        }
+    }
+}
+function stringArgs(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return { error: "args must be a non-empty array of strings" };
+    }
+    const args = [];
+    for (const item of raw) {
+        if (!isString(item)) {
+            return { error: "args must be a non-empty array of strings" };
+        }
+        args.push(item);
+    }
+    return args;
+}
+/**
+ * Take what the binary produced and put it in the workspace.
+ *
+ * The file is on disk either way — in the workspace folder on a local run, in
+ * the scratch directory on a cloud one — so it is read from there and written
+ * through `persistBinaryOutput`, which stores it in the workspace and (when
+ * asked) as an asset.
+ */
+async function persistWorkspaceFile(context, workspace, relPath) {
+    let abs;
+    try {
+        const root = workspace.localDir ?? (await workspace.scratchDir());
+        abs = path.join(root, workspace.key(relPath));
+    }
+    catch (e) {
+        return { persist_error: e instanceof Error ? e.message : String(e) };
+    }
+    try {
+        const bytes = await readFile(abs);
+        const persisted = await persistBinaryOutput(context, bytes, {
+            outputFile: relPath,
+            contentType: mimeFromFilename(relPath),
+            uiPrefix: "media"
+        });
+        return { ...persisted };
+    }
+    catch (e) {
+        return { persist_error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * What a refused `://` in ffmpeg argv should do instead. The guard's default
+ * says "stage it first" without saying how; here there is a parameter for it.
+ */
+const FFMPEG_REMEDY = 'Pass the ref in `inputs` instead — {"clip.mp4": "asset://<id>.mp4"} ' +
+    "copies it into the workspace, then name `clip.mp4` in args.";
+/** The same remedy for `ffprobe`, whose one path argument replaces argv. */
+const FFPROBE_REMEDY = 'Pass the ref in `inputs` instead — {"clip.mp4": "asset://<id>.mp4"} ' +
+    'copies it into the workspace, then set path to "clip.mp4".';
+/** Per-file limit for inline, temporary, and non-local staged inputs. */
+const MAX_STAGED_INPUT_BYTES = 100 * 1024 * 1024;
+/** Files one `inputs` bag may stage. */
+const MAX_STAGED_INPUTS = 8;
+/** Bytes one `inputs` bag may stage in total. */
+const MAX_STAGED_TOTAL_BYTES = 256 * 1024 * 1024;
+/**
+ * Copy the refs in `inputs` into the workspace under the names the caller
+ * gave them, so argv can name plain local files.
+ *
+ * ffmpeg opens local files only — a URL or an `asset://` URI in argv is
+ * refused, and rightly so. But chat code has no workspace API of its own, so
+ * before this there was no way to put an asset where ffmpeg could see it: the
+ * capability was on the belt and unusable, and the refusal told the caller to
+ * "download first" with nothing to download with. Staging is that missing
+ * half, and it changes no boundary — the bytes are resolved host-side by the
+ * same resolver `save_asset` uses, and every name still goes through
+ * {@link confineArgvToWorkspace}.
+ */
+async function stageInputs(context, workspace, cwd, raw) {
+    if (raw === undefined || raw === null)
+        return { staged: {} };
+    if (!isRecord(raw)) {
+        return {
+            error: 'inputs must be an object of {"<workspace-relative name>": "<asset:// URI, /api/storage/ key, or data: URI>"}'
+        };
+    }
+    const entries = Object.entries(raw);
+    if (entries.length > MAX_STAGED_INPUTS) {
+        return {
+            error: `inputs stages at most ${MAX_STAGED_INPUTS} files; ${entries.length} were given.`
+        };
+    }
+    const names = entries.map(([name]) => name);
+    const refusal = await confineArgvToWorkspace(names, cwd);
+    if (refusal)
+        return refusal;
+    const staged = {};
+    let total = 0;
+    const localAssetLimit = workspace.localDir
+        ? getMaxLocalUploadBytes()
+        : undefined;
+    const hasLocalAsset = localAssetLimit !== undefined &&
+        entries.some(([, ref]) => isNonBlankString(ref) && ref.trim().startsWith("asset://"));
+    const totalLimit = hasLocalAsset
+        ? Math.max(MAX_STAGED_TOTAL_BYTES, localAssetLimit ?? 0)
+        : MAX_STAGED_TOTAL_BYTES;
+    for (const [name, ref] of entries) {
+        if (!isNonBlankString(name)) {
+            return { error: "inputs keys must be non-empty workspace paths." };
+        }
+        if (!isNonBlankString(ref)) {
+            return {
+                error: `inputs["${name}"] must be a string ref (asset:// URI, /api/storage/ key, or data: URI).`
+            };
+        }
+        let bytes = null;
+        let readError;
+        try {
+            bytes = await loadMediaRefBytes({ uri: ref.trim() }, context);
+        }
+        catch (e) {
+            // Keep why. Naming only the accepted forms is useless to a caller who
+            // already passed one — an unreachable bucket, a revoked credential and a
+            // typo all arrive here, and only the first two are worth retrying. Told
+            // just "pass an asset:// URI", a model re-sends the ref it has and then
+            // starts guessing at URL shapes.
+            readError = e instanceof Error ? e.message : String(e);
+        }
+        // Zero bytes is a failed read wearing a buffer, the same way it is in
+        // `save_asset` — staging it would hand ffmpeg an empty file and the
+        // failure would surface as an unhelpable decode error.
+        if (!bytes || bytes.byteLength === 0) {
+            return {
+                error: `inputs["${name}"]: could not read ${ref}. ` +
+                    (readError
+                        ? `Reading it failed: ${readError}. `
+                        : "It resolved to no bytes. ") +
+                    `Accepted: an asset:// URI, the /api/storage/ key a tool returned, ` +
+                    `or a data: URI.`
+            };
+        }
+        const inputLimit = localAssetLimit !== undefined && ref.trim().startsWith("asset://")
+            ? localAssetLimit
+            : MAX_STAGED_INPUT_BYTES;
+        if (bytes.byteLength > inputLimit) {
+            return {
+                error: `inputs["${name}"] is ${bytes.byteLength} bytes, over the ${inputLimit}-byte limit.`
+            };
+        }
+        total += bytes.byteLength;
+        if (total > totalLimit) {
+            return {
+                error: `inputs stages ${total} bytes, over the ${totalLimit}-byte total limit.`
+            };
+        }
+        // Through the workspace, so the staged input is durable and a cloud run
+        // stages at all; then onto disk in `cwd`, because the binary opens a real
+        // path. On a local workspace `materialize` hands back the file just
+        // written, so this is one write, not two.
+        try {
+            await workspace.write(name, bytes);
+            await workspace.materialize(name);
+        }
+        catch (e) {
+            return {
+                error: `inputs["${name}"] could not be staged: ${e instanceof Error ? e.message : String(e)}`
+            };
+        }
+        staged[name] = bytes.byteLength;
+    }
+    return { staged };
+}
+const ffmpeg = {
+    spec: ffmpegSpec,
+    impl: async (run, params) => {
+        const root = await hostBinaryRoot(run.context);
+        if ("error" in root)
+            return root;
+        const { workspace, cwd } = root;
+        const args = stringArgs(params["args"]);
+        if ("error" in args)
+            return args;
+        const stagedResult = await stageInputs(run.context, workspace, cwd, params["inputs"]);
+        if ("error" in stagedResult)
+            return stagedResult;
+        const outputFile = isNonBlankString(params["output_file"])
+            ? params["output_file"].trim()
+            : "";
+        const argv = [...args];
+        if (outputFile && !argv.includes(outputFile)) {
+            argv.push(outputFile);
+        }
+        const refusal = await confineArgvToWorkspace(argv, cwd, FFMPEG_REMEDY);
+        if (refusal)
+            return refusal;
+        const hardened = hardenFfmpegArgv(argv);
+        if ("error" in hardened)
+            return hardened;
+        const persistTarget = outputFile ||
+            [...argv].reverse().find((item) => item && !item.startsWith("-")) ||
+            "";
+        const timeoutMs = clampTimeoutSeconds(params["timeout_seconds"], 180, 600) * 1000;
+        const runOptions = { cwd, timeoutMs };
+        // Only a known output path can be watched for size; without one the
+        // wall clock and the capture cap are the run's bounds.
+        if (persistTarget) {
+            runOptions.artifactPath = persistTarget;
+        }
+        try {
+            await stageHostBinaryInputs(workspace, hardened.argv);
+            const result = await runHostBinary("ffmpeg", hardened.argv, runOptions);
+            const persisted = result.exitCode === 0 && persistTarget
+                ? await persistWorkspaceFile(run.context, workspace, persistTarget)
+                : undefined;
+            const report = {
+                success: result.exitCode === 0,
+                stdout: result.stdout,
+                stderr: result.stderr,
+                exit_code: result.exitCode,
+                ...(persisted ?? {})
+            };
+            if (Object.keys(stagedResult.staged).length > 0) {
+                report["staged"] = stagedResult.staged;
+            }
+            return report;
+        }
+        catch (e) {
+            if (e instanceof HostBinaryMissingError) {
+                return { error: e.message };
+            }
+            return {
+                error: `ffmpeg failed: ${e instanceof Error ? e.message : String(e)}`
+            };
+        }
+    }
+};
+/**
+ * What ffprobe reports as numbers, as numbers.
+ *
+ * ffprobe's JSON is all strings — `"duration": "8.000000"` — so arithmetic on
+ * it silently produces `"8.000000".toFixed is not a function`, or worse, a
+ * concatenation. The raw payload stays exactly as ffprobe wrote it; this is a
+ * second, typed view of the four fields a caller actually plans a cut with.
+ */
+export function ffprobeSummary(parsed) {
+    const format = isObjectLike(parsed["format"]) ? parsed["format"] : {};
+    const streams = Array.isArray(parsed["streams"]) ? parsed["streams"] : [];
+    const numeric = (value) => {
+        const n = typeof value === "number" ? value : Number(value);
+        return Number.isFinite(n) ? n : null;
+    };
+    const ofKind = (kind) => streams.find((s) => isObjectLike(s) && s["codec_type"] === kind);
+    const video = ofKind("video");
+    const audio = ofKind("audio");
+    const summary = {
+        duration_seconds: numeric(format["duration"]) ?? numeric(video?.["duration"]),
+        has_video: video !== undefined,
+        has_audio: audio !== undefined
+    };
+    if (video) {
+        summary["width"] = numeric(video["width"]);
+        summary["height"] = numeric(video["height"]);
+    }
+    return summary;
+}
+/**
+ * Refs `ffprobe` stages for itself, rather than refusing.
+ *
+ * These are the forms NodeTool's own tools hand back, so a caller probing a
+ * clip it just generated is passing the string it was given. An http(s) URL is
+ * not here: fetching one is egress, and egress belongs to the surfaces that
+ * declare it.
+ */
+function isStageableProbeRef(value) {
+    return (value.startsWith("asset://") ||
+        value.startsWith("/api/storage/") ||
+        value.startsWith("data:"));
+}
+/** A workspace file name for a staged probe target, from the ref itself. */
+function probeStagingName(ref) {
+    if (ref.startsWith("data:"))
+        return "ffprobe-input/input";
+    const tail = ref.split("/").pop() ?? "input";
+    const safe = tail.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 64);
+    return `ffprobe-input/${safe || "input"}`;
+}
+/**
+ * ffprobe with an argv NodeTool writes, not the caller.
+ *
+ * Everything a caller can say is one workspace path, so the whole boundary is
+ * the confinement check — there is no flag surface to guard, and no way to ask
+ * ffprobe to open a socket. `inputs` stages assets under workspace names the
+ * same way `ffmpeg`'s does: without it the two halves of one loop disagreed,
+ * and a caller who had just staged a clip for ffmpeg could not ask ffprobe how
+ * long it was without staging it a second time through a no-op ffmpeg copy.
+ */
+const ffprobe = {
+    spec: ffprobeSpec,
+    impl: async (run, params) => {
+        const root = await hostBinaryRoot(run.context);
+        if ("error" in root)
+            return root;
+        const { workspace, cwd } = root;
+        const target = params["path"];
+        if (!isNonBlankString(target)) {
+            return { error: "path is required" };
+        }
+        const requested = target.trim();
+        // ffprobe's whole argv is this one path, so an `asset://` here can only
+        // mean "probe that": there is no flag to smuggle and nothing else to
+        // confine. Refusing it made the two halves of one loop disagree — the
+        // guest's own `video.info(asset://…)` reads a ref happily — and a caller
+        // who just wanted a duration had to stage the file by hand first.
+        const autoStaged = isStageableProbeRef(requested);
+        const probePath = autoStaged ? probeStagingName(requested) : requested;
+        let toStage = params["inputs"];
+        if (autoStaged) {
+            const extra = isRecord(toStage) ? toStage : {};
+            toStage = { ...extra, [probePath]: requested };
+        }
+        const stagedResult = await stageInputs(run.context, workspace, cwd, toStage);
+        if ("error" in stagedResult)
+            return stagedResult;
+        const refusal = await confineArgvToWorkspace([probePath], cwd, FFPROBE_REMEDY);
+        if (refusal)
+            return refusal;
+        await stageHostBinaryInputs(workspace, [probePath]);
+        const timeoutMs = clampTimeoutSeconds(params["timeout_seconds"], 30, 120) * 1000;
+        try {
+            const result = await runHostBinary("ffprobe", [
+                "-v",
+                "error",
+                "-print_format",
+                "json",
+                "-show_format",
+                "-show_streams",
+                probePath
+            ], { cwd, timeoutMs });
+            if (result.exitCode !== 0) {
+                return {
+                    error: `ffprobe failed: ${result.stderr.trim() || `exit ${result.exitCode}`}`
+                };
+            }
+            const parsed = JSON.parse(result.stdout);
+            if (!isObjectLike(parsed)) {
+                return { error: "ffprobe returned no readable JSON" };
+            }
+            const report = {
+                path: requested,
+                ...parsed,
+                summary: ffprobeSummary(parsed)
+            };
+            if (Object.keys(stagedResult.staged).length > 0) {
+                report["staged"] = stagedResult.staged;
+            }
+            return report;
+        }
+        catch (e) {
+            if (e instanceof HostBinaryMissingError) {
+                return { error: e.message };
+            }
+            return {
+                error: `ffprobe failed: ${e instanceof Error ? e.message : String(e)}`
+            };
+        }
+    }
+};
+const DEFAULT_YT_DLP_OUTPUT = "downloads/yt-dlp/%(id)s.%(ext)s";
+const ytDlp = {
+    spec: ytDlpSpec,
+    impl: async (run, params) => {
+        // The cloud profile leaves this off every belt, so a model never sees it.
+        // A host that resolves the capability by name still lands here.
+        if (!isYtDlpEnabled()) {
+            return { error: "yt_dlp is not available on this deployment" };
+        }
+        const root = await hostBinaryRoot(run.context);
+        if ("error" in root)
+            return root;
+        const { workspace, cwd } = root;
+        const url = params["url"];
+        if (!isNonBlankString(url)) {
+            return { error: "url is required" };
+        }
+        // The downloader opens its own sockets from inside the server, so an
+        // http(s) check alone leaves the metadata service and every internal
+        // host reachable. Same guard the sandbox fetch bridge uses, plus the
+        // resolution step a hostname needs.
+        try {
+            assertFetchUrlAllowed(url);
+            await assertResolvedHostAllowed(url, "yt_dlp");
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return { error: message.replace(/^fetch: /, "yt_dlp: ") };
+        }
+        const outputFile = isNonBlankString(params["output_file"])
+            ? params["output_file"].trim()
+            : DEFAULT_YT_DLP_OUTPUT;
+        const format = isNonBlankString(params["format"])
+            ? params["format"].trim()
+            : "";
+        const timeoutMs = clampTimeoutSeconds(params["timeout_seconds"], 300, 900) * 1000;
+        // The template is the caller's, so it escapes the workspace as easily as
+        // an ffmpeg path does. `format` reaches yt-dlp as a selector, never a path.
+        const refusal = await confineArgvToWorkspace([outputFile], cwd);
+        if (refusal)
+            return refusal;
+        const flagLike = refuseFlagLikeValue(outputFile, "output_file") ??
+            (format ? refuseFlagLikeValue(format, "format") : undefined);
+        if (flagLike)
+            return flagLike;
+        const outDir = path.dirname(outputFile);
+        if (outDir && outDir !== ".") {
+            try {
+                await mkdir(path.join(cwd, outDir), { recursive: true });
+            }
+            catch (e) {
+                return {
+                    error: `could not create output directory: ${e instanceof Error ? e.message : String(e)}`
+                };
+            }
+        }
+        const download = { url, outputFile };
+        if (format) {
+            download.format = format;
+        }
+        const argv = buildYtDlpArgv(download);
+        try {
+            const result = await runHostBinary("yt-dlp", argv, {
+                cwd,
+                timeoutMs
+            });
+            const printed = result.stdout.trim().split("\n").filter(Boolean).at(-1);
+            // `--print after_move:filepath` names the finished file. Nothing printed
+            // on a clean exit means nothing was written — which is what an aborted
+            // over-cap download looks like, since `--print` silences the reason.
+            if (result.exitCode === 0 && !printed) {
+                return {
+                    success: false,
+                    url,
+                    error: `yt-dlp wrote no file. The download may have passed the ` +
+                        `${MAX_DOWNLOAD_BYTES}-byte limit, or the URL carried nothing to ` +
+                        `download.`,
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                    exit_code: result.exitCode
+                };
+            }
+            const produced = printed && !printed.startsWith("http")
+                ? path.isAbsolute(printed)
+                    ? path.relative(cwd, printed)
+                    : printed
+                : outputFile.includes("%(")
+                    ? ""
+                    : outputFile;
+            const persisted = result.exitCode === 0 && produced
+                ? await persistWorkspaceFile(run.context, workspace, produced)
+                : undefined;
+            return {
+                success: result.exitCode === 0,
+                url,
+                output_file: produced || outputFile,
+                stdout: result.stdout,
+                stderr: result.stderr,
+                exit_code: result.exitCode,
+                ...(persisted ?? {})
+            };
+        }
+        catch (e) {
+            if (e instanceof HostBinaryMissingError) {
+                return { error: e.message };
+            }
+            return {
+                error: `yt-dlp failed: ${e instanceof Error ? e.message : String(e)}`
+            };
+        }
+    }
+};
+/** Every media capability, in the order `getAllMcpTools` offered them. */
+export const MEDIA_CAPABILITIES = [
+    generateText,
+    generateImage,
+    editImage,
+    segmentImage,
+    generateVideo,
+    animateImage,
+    videoFromReferences,
+    generateSpeech,
+    generateMusic,
+    transcribeAudio,
+    embedText,
+    readMediaBytes,
+    critiqueImage,
+    compareImages,
+    scoreImageAdherence,
+    understandVideo,
+    ffmpeg,
+    ffprobe,
+    ytDlp
+];
+export const module = {
+    module: "media",
+    exports: MEDIA_CAPABILITIES
+};
+export { generateText, generateImage, editImage, segmentImage, generateVideo, animateImage, videoFromReferences, generateSpeech, generateMusic, transcribeAudio, embedText, readMediaBytes, critiqueImage, compareImages, scoreImageAdherence, understandVideo, ffmpeg, ffprobe, ytDlp };
+//# sourceMappingURL=media.js.map