@nodetool-ai/agents 0.8.1 → 0.8.3

package/dist/capabilities/media.js

@@ -22,7 +22,7 @@ import { Buffer } from "node:buffer";
 import { randomInt, randomUUID } from "node:crypto";
 import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { loadMediaRefBytes } from "@nodetool-ai/runtime";
+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";
@@ -31,7 +31,7 @@ import { assertFetchUrlAllowed, assertResolvedHostAllowed } from "../network-gua
 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 } from "../tools/asset-persist.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";
@@ -267,16 +267,6 @@ async function finishOutput(context, bytes, assets, opts) {
     }
     return result;
 }
-/**
- * The asset the seam saved for a generation, read off the registry's settled
- * outcome. The encoded-audio paths return the provider's result rather than
- * the seam's, so this is how a capability learns what was persisted.
- */
-async function seamAssetFor(id) {
-    const { generationRegistry } = await import("@nodetool-ai/runtime");
-    const outcome = generationRegistry.outcome(id);
-    return outcome?.asset_ids[0] ?? null;
-}
 /** What a `background: true` call answers with. */
 function backgroundReceipt(id, spec) {
     return {
@@ -375,6 +365,8 @@ const generateImage = {
                 negative_prompt: params["negative_prompt"],
                 width: params["width"],
                 height: params["height"],
+                aspect_ratio: aliased(params, "aspect_ratio", "aspectRatio", "aspect"),
+                resolution: aliased(params, "resolution"),
                 quality: params["quality"]
             }
         });
@@ -418,6 +410,9 @@ const editImage = {
                 negative_prompt: params["negative_prompt"],
                 target_width: params["target_width"],
                 target_height: params["target_height"],
+                aspect_ratio: aliased(params, "aspect_ratio", "aspectRatio", "aspect"),
+                resolution: aliased(params, "resolution"),
+                quality: params["quality"],
                 strength: params["strength"]
             }
         });
@@ -742,6 +737,9 @@ const videoFromReferences = {
         });
     }
 };
+// ---------------------------------------------------------------------------
+// generate_speech
+// ---------------------------------------------------------------------------
 function int16ToUint8(samples) {
     const bytes = new Uint8Array(samples.byteLength);
     const view = new DataView(bytes.buffer);
@@ -840,228 +838,244 @@ async function encodedSpeech(context, m, params, generation) {
         return await provider.textToSpeechEncoded({
             text: params.text,
             model: m.model,
-            voice: params.voice,
-            speed: params.speed,
+            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");
 }
-const generateSpeech = {
-    spec: generateSpeechSpec,
-    impl: async (run, params) => {
-        const context = run.context;
-        const m = parseModelArgs(params);
-        if ("error" in m)
-            return m;
-        const text = params["text"];
-        if (!isNonEmptyString(text))
-            return { error: "text is required" };
-        const outputFile = isString(params["output_file"])
-            ? params["output_file"]
-            : undefined;
-        const desiredFormat = audioFormatFromOutputFile(outputFile) ?? "mp3";
-        const generationId = randomUUID();
-        const generation = {
-            id: generationId,
-            origin: { surface: "capability", tool_call_id: toolCallIdOf(params) },
-            persist: outputFile ? { name: path.basename(outputFile) } : {}
-        };
-        const speechParams = {
-            text,
-            voice: params["voice"],
-            speed: params["speed"],
-            audioFormat: desiredFormat
-        };
-        if (params["background"] === true) {
-            const spec = {
-                capability: "text_to_speech",
-                m,
-                type: "audio",
-                namePrefix: "generated-speech",
-                params: speechParams
+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
             };
-            const started = startBackgroundGeneration(context, () => encodedSpeech(context, m, speechParams, generation));
-            if (!started) {
-                return backgroundGenerationLimitError();
-            }
-            return backgroundReceipt(generationId, spec);
         }
-        try {
-            // Preferred path: ask the provider for fully-encoded audio in the
-            // desired container (mp3/wav/flac/...). Returns null when the provider
-            // doesn't support encoded TTS — we then fall through to streaming PCM.
-            let audio = null;
-            let mimeType;
-            let outputFileFinal = outputFile;
-            // The asset the seam saved on the encoded path, when it could.
-            let seamAssetId = null;
-            // Why the encoded path gave up, kept for the failure message. A provider
-            // that only does encoded TTS (FAL, KIE) leaves the streaming method as
-            // the base class's, which throws "<provider> does not support
-            // textToSpeech" — so discarding this error reported the one thing that
-            // was not wrong, and a session spent three rounds hunting for a TTS
-            // model when the real answer was in the sentence thrown here.
-            let encodedError;
-            try {
-                const encoded = await encodedSpeech(context, m, speechParams, generation);
-                if (encoded && encoded.data) {
-                    audio = encoded.data;
-                    mimeType = encoded.mimeType;
-                    seamAssetId = await seamAssetFor(generationId);
-                }
+    }
+    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;
             }
-            catch (e) {
-                encodedError = e instanceof Error ? e.message : String(e);
+            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;
             }
-            if (!audio) {
-                // Streaming path — provider returns either pre-encoded chunks
-                // (carrying mimeType) or raw int16 PCM samples that we must wrap in
-                // a WAV container before writing to disk so the file is playable.
-                const parts = [];
-                let pcmOnly = true;
-                // Capture the PCM sample rate from the stream — providers emit non-24k
-                // PCM (MiniMax 32000, Together varies). Hardcoding 24000 in the WAV
-                // header makes those play back at the wrong speed/pitch.
-                let pcmSampleRate;
-                try {
-                    for await (const item of context.streamProviderPrediction({
-                        id: generationId,
-                        origin: generation.origin,
-                        provider: m.provider,
-                        capability: "text_to_speech",
-                        model: m.model,
-                        params: {
-                            text,
-                            voice: params["voice"],
-                            speed: params["speed"]
-                        }
-                    })) {
-                        const chunk = item;
-                        if (chunk.data instanceof Uint8Array) {
-                            parts.push(chunk.data);
-                            if (chunk.mimeType)
-                                mimeType = chunk.mimeType;
-                            pcmOnly = false;
-                        }
-                        else if (isString(chunk.data)) {
-                            parts.push(Buffer.from(chunk.data, "base64"));
-                            if (chunk.mimeType)
-                                mimeType = chunk.mimeType;
-                            pcmOnly = false;
-                        }
-                        else if (chunk.samples) {
-                            pcmSampleRate ??= chunk.sampleRate;
-                            parts.push(int16ToUint8(chunk.samples));
-                        }
+            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");
                     }
-                }
-                catch (e) {
-                    // Both paths failed. Report the encoded one first: on a provider
-                    // that only does encoded TTS the streaming error is the base class's
-                    // "does not support textToSpeech", which is true of the method and
-                    // false of the provider.
-                    if (encodedError) {
-                        throw new Error(`${encodedError} (the streaming fallback then failed too: ${e instanceof Error ? e.message : String(e)})`);
+                    if (sampleRate !== undefined && sampleRate !== chunk.sampleRate) {
+                        throw new Error("TTS changed PCM sample rate during the stream");
                     }
-                    throw e;
+                    sampleRate = chunk.sampleRate;
                 }
-                if (parts.length === 0) {
-                    return {
-                        error: encodedError
-                            ? `Provider returned no audio data: ${encodedError}`
-                            : "Provider returned no audio data"
-                    };
+                if (chunk.samples instanceof Int16Array && chunk.samples.length > 0) {
+                    parts.push(int16ToUint8(chunk.samples));
                 }
-                const merged = concatUint8(parts);
-                if (pcmOnly && !mimeType) {
-                    // Wrap raw PCM in WAV so the bytes are playable. Rename .mp3 →
-                    // .wav since the actual data is now WAV, not MP3. Honor the provider's
-                    // actual sample rate (defaulting to 24k only when unknown).
-                    audio = wrapPcmAsWav(merged, pcmSampleRate ?? 24000);
-                    mimeType = "audio/wav";
-                    if (outputFileFinal) {
-                        const dir = path.dirname(outputFileFinal);
-                        const base = path.basename(outputFileFinal, path.extname(outputFileFinal));
-                        outputFileFinal = path.join(dir === "." ? "" : dir, `${base}.wav`);
-                    }
+            }
+        }
+    }
+    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");
                 }
-                else {
-                    audio = merged;
+                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 mime = mimeType ?? "audio/mpeg";
-            const persisted = await finishOutput(context, audio, seamAssetId
-                ? [
-                    {
-                        asset_id: seamAssetId,
-                        uri: `asset://${seamAssetId}.${MIME_TO_EXT[mime] ?? "bin"}`
+                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.`
+                        };
                     }
-                ]
-                : [], {
-                namePrefix: "generated-speech",
-                mime,
-                outputFile: outputFileFinal
-            });
-            return {
-                type: "audio",
-                provider: m.provider,
-                model: m.model,
-                generation_id: generationId,
-                ...persisted
-            };
+                    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;
         }
-        catch (e) {
-            return {
-                ...predictionError("text_to_speech", m, e),
-                generation_id: generationId
-            };
+        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));
     }
 };
-/**
- * Music from a prompt — the counterpart to {@link generateSpeech}, and the
- * hole every other generation capability made conspicuous.
- *
- * Without it, scoring a cut meant running `nodetool.audio.TextToMusic` through
- * `run_node`: a one-node graph, and therefore the graph validator, a typed
- * `music_model` property and a model ref to satisfy before a single second of
- * audio existed. A live session spent five rounds there and shipped silent.
- */
 const generateMusic = {
     spec: generateMusicSpec,
     impl: async (run, params) => {
-        const context = run.context;
         const m = parseModelArgs(params);
-        if ("error" in m)
+        if ("error" in m) {
             return m;
-        const prompt = params["prompt"];
-        if (!isNonEmptyString(prompt))
+        }
+        const prompt = params.prompt;
+        if (!isNonEmptyString(prompt)) {
             return { error: "prompt is required" };
-        if (!isFunction(context.textToMusic)) {
-            return {
-                error: "this runtime's context has no text_to_music path"
-            };
         }
-        const outputFile = isString(params["output_file"])
-            ? params["output_file"]
-            : undefined;
-        const desiredFormat = audioFormatFromOutputFile(outputFile) ?? "mp3";
-        const generationId = randomUUID();
+        const outputFile = outputFileOf(params);
         const musicParams = {
             prompt,
-            lyrics: params["lyrics"],
+            lyrics: params.lyrics,
             duration_seconds: aliased(params, "duration_seconds", "durationSeconds", "duration"),
-            audioFormat: desiredFormat
-        };
-        const req = {
-            id: generationId,
-            provider: m.provider,
-            capability: "text_to_music",
-            model: m.model,
-            params: musicParams,
-            origin: { surface: "capability", tool_call_id: toolCallIdOf(params) },
-            persist: outputFile ? { name: path.basename(outputFile) } : {}
+            audioFormat: audioFormatFromOutputFile(outputFile) ?? "mp3"
         };
         const spec = {
             capability: "text_to_music",
@@ -1070,45 +1084,31 @@ const generateMusic = {
             namePrefix: "generated-music",
             params: musicParams
         };
-        if (params["background"] === true) {
-            const started = startBackgroundGeneration(context, () => context.textToMusic(req));
-            if (!started) {
-                return backgroundGenerationLimitError();
-            }
-            return backgroundReceipt(generationId, spec);
-        }
-        try {
-            const encoded = await context.textToMusic(req);
+        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) {
-                return {
-                    error: "Provider returned no audio data",
-                    generation_id: generationId
-                };
+                throw new Error("Provider returned no audio data");
             }
-            const mime = encoded.mimeType ?? "audio/mpeg";
-            const seamAssetId = await seamAssetFor(generationId);
-            const persisted = await finishOutput(context, encoded.data, seamAssetId
-                ? [
-                    {
-                        asset_id: seamAssetId,
-                        uri: `asset://${seamAssetId}.${MIME_TO_EXT[mime] ?? "bin"}`
-                    }
-                ]
-                : [], { namePrefix: "generated-music", mime, outputFile });
             return {
-                type: "audio",
-                provider: m.provider,
-                model: m.model,
-                generation_id: generationId,
-                ...persisted
+                data: encoded.data,
+                mimeType: encoded.mimeType ?? "audio/mpeg",
+                outputFile
             };
-        }
-        catch (e) {
-            return {
-                ...predictionError("text_to_music", m, e),
-                generation_id: generationId
-            };
-        }
+        });
     }
 };
 const transcribeAudio = {
@@ -1244,7 +1244,7 @@ function messageText(message) {
     }
     return "";
 }
-async function judgeCall(context, m, content, maxTokens = JUDGE_MAX_TOKENS) {
+async function judgeCall(context, m, content, maxTokens = JUDGE_MAX_TOKENS, requiredImages) {
     const result = (await context.runProviderPrediction({
         provider: m.provider,
         capability: "generate_message",
@@ -1252,7 +1252,10 @@ async function judgeCall(context, m, content, maxTokens = JUDGE_MAX_TOKENS) {
         params: {
             messages: [{ role: "user", content }],
             max_tokens: maxTokens,
-            temperature: 0
+            temperature: 0,
+            strict_image_evidence: content.some((part) => part.type === "image_url") ||
+                Boolean(requiredImages?.length),
+            required_images: requiredImages?.map(normalizeMediaSource)
         }
     }));
     return messageText(result);
@@ -1403,11 +1406,7 @@ const compareImages = {
             `\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)
-                ]);
+                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)}`);
@@ -1502,7 +1501,7 @@ const scoreImageAdherence = {
                         ` 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) : [];
@@ -1513,36 +1512,82 @@ const scoreImageAdherence = {
                 }
             }
             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${questions.map((q, i) => `${i + 1}. ${q}`).join("\n")}` +
+                    `\n\nQuestions:\n${checks.map((q) => `${q.id}: ${q.question}`).join("\n")}` +
                     `\n\nRespond with JSON only:` +
-                    `\n{"answers": [{"question": "...", "answer": "yes" | "no", "note": "..."}]}`),
+                    `\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)}`
+                    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 answers = rawAnswers
-                .filter(isObjectLike)
-                .map((a) => ({
-                question: String(a["question"] ?? ""),
-                answer: a["answer"] === "yes" ? "yes" : "no",
-                note: String(a["note"] ?? "")
-            }));
+            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: answers.length ? passed / answers.length : 0,
+                score: passed / checks.length,
                 passed,
-                total: answers.length,
+                total: checks.length,
                 failed: answers.filter((a) => a.answer === "no"),
                 answers
             };
@@ -1810,7 +1855,8 @@ async function stageInputs(context, workspace, cwd, raw) {
     const localAssetLimit = workspace.localDir
         ? getMaxLocalUploadBytes()
         : undefined;
-    const hasLocalAsset = localAssetLimit !== undefined && entries.some(([, ref]) => isNonBlankString(ref) && ref.trim().startsWith("asset://"));
+    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;
@@ -1826,7 +1872,14 @@ async function stageInputs(context, workspace, cwd, raw) {
         let bytes = null;
         let readError;
         try {
-            bytes = await loadMediaRefBytes({ uri: ref.trim() }, context);
+            // `loadMediaRefBytes` reads `file://` URIs and absolute paths straight
+            // off the host disk. A filesystem-shaped ref resolves through the
+            // storage adapter alone, which keeps it inside the storage root.
+            const uri = ref.trim();
+            bytes =
+                filesystemPathForUri(uri) !== null
+                    ? ((await context.storage?.retrieve(uri)) ?? null)
+                    : await loadMediaRefBytes({ uri }, context);
         }
         catch (e) {
             // Keep why. Naming only the accepted forms is useless to a caller who