@bedolla/enrivision 0.1.5 → 0.1.7

package/dist/tools/AnalyzeMediaTool.js

@@ -1,31 +1,27 @@
 /**
  * ANALYZE MEDIA TOOL
  *
- * Implements the `analyze_media` MCP tool:
- * - Validates local file paths or http(s) URLs
- * - Materializes URL inputs via bounded downloads (temporary, owned cleanup)
- * - Streams the bytes to EnriProxy via resumable uploads
- * - Triggers server-side analysis and returns text-only results
+ * Facade for the `analyze_media` MCP tool:
+ * - Validates local file paths or http(s) URLs (param parser)
+ * - Materializes URL inputs via bounded downloads (input resolver)
+ * - Uploads single files or multi-image tar sets through resumable
+ *   EnriProxy sessions (uploader + tar packager)
+ * - Triggers server-side analysis and returns sanitized text-only results
  *
  * @module tools/AnalyzeMediaTool
  */
-import { existsSync } from "node:fs";
-import { stat, open } from "node:fs/promises";
-import { basename, extname, isAbsolute } from "node:path";
 import { randomUUID } from "node:crypto";
 import { lookup as mimeLookup } from "mime-types";
-import { EnriProxyHttpError } from "../client/EnriProxyClient.js";
-import { assertHttpUrl, assertNonEmptyString, assertObject, optionalBoolean, optionalInt, optionalNumber, optionalString } from "../shared/validation.js";
+import { assertHttpUrl, assertNonEmptyString } from "../shared/validation.js";
 import { MediaUrlFetcher } from "../shared/mediaUrlFetcher.js";
-import { computeTarSizeBytes, TarStream } from "../shared/tar.js";
-/**
- * Content type for EnriVision media-set archives (tar, no compression).
- */
-const ENRIVISION_MEDIA_SET_TAR_CONTENT_TYPE = "application/vnd.enrivision.media-set+tar";
-/**
- * Fixed manifest entry name inside EnriVision media-set tar archives.
- */
-const ENRIVISION_MEDIA_SET_TAR_MANIFEST_NAME = "manifest.json";
+import { EnriProxyHttpError } from "../client/EnriProxyClient.js";
+import { AnalyzeMediaExtractionSanitizer } from "./AnalyzeMediaExtractionSanitizer.js";
+import { AnalyzeMediaInputResolver } from "./AnalyzeMediaInputResolver.js";
+import { AnalyzeMediaParamParser } from "./AnalyzeMediaParamParser.js";
+import { AnalyzeMediaResumableUploader } from "./AnalyzeMediaResumableUploader.js";
+import { isProgressQuiet, withResumableRetry } from "./AnalyzeMediaResumableUploader.js";
+import { AnalyzeMediaTarPackager } from "./AnalyzeMediaTarPackager.js";
+import { ANALYZE_MEDIA_LIMITS } from "./AnalyzeMediaContract.js";
 /**
  * MCP tool that uploads and analyzes local or http(s) URL media.
  */
@@ -35,193 +31,180 @@ export class AnalyzeMediaTool {
      */
     deps;
     /**
-     * Bounded http(s) media fetcher used when `path`/`paths` carry URLs.
+     * Raw argument validator.
+     */
+    paramParser;
+    /**
+     * Local/URL input materializer.
+     */
+    inputResolver;
+    /**
+     * Resumable chunk uploader.
      */
-    urlFetcher;
+    uploader;
+    /**
+     * Multi-image tar set packager.
+     */
+    tarPackager;
+    /**
+     * Extraction output sanitizer.
+     */
+    sanitizer;
+    /**
+     * Cached vision-capability verdicts keyed by endpoint + model.
+     *
+     * @remarks
+     * `execute` builds a fresh client per call, so instance-keyed caching
+     * would never hit: the key is `serverUrl + model` (one account per
+     * endpoint). Entries live for `ANALYZE_MEDIA_LIMITS.visionProbeCacheTtlMs`
+     * (mirrors EnriCode `PROBE_CACHE_TTL_MS` and its per-client scoping).
+     */
+    visionProbeCache = new Map();
     /**
      * Creates a new {@link AnalyzeMediaTool}.
      *
-     * @param deps - Tool dependencies
-     * @param urlFetcher - Optional URL fetcher override for tests
+     * @param deps - Tool dependencies.
+     * @param urlFetcher - Optional URL fetcher override for tests.
      */
     constructor(deps, urlFetcher = new MediaUrlFetcher()) {
         this.deps = deps;
-        this.urlFetcher = urlFetcher;
+        this.paramParser = new AnalyzeMediaParamParser();
+        this.inputResolver = new AnalyzeMediaInputResolver(urlFetcher);
+        this.uploader = new AnalyzeMediaResumableUploader();
+        this.tarPackager = new AnalyzeMediaTarPackager(this.uploader);
+        this.sanitizer = new AnalyzeMediaExtractionSanitizer();
     }
     /**
      * Validates raw MCP tool arguments.
      *
-     * @param raw - Raw tool arguments
-     * @returns Validated parameters
+     * @param raw - Raw tool arguments.
+     * @returns Validated parameters.
+     * @throws Error with an Spanish-first bilingual message when arguments are missing or out of range.
      */
     parseParams(raw) {
-        const obj = assertObject(raw, "arguments");
-        const pathRaw = typeof obj["path"] === "string" ? obj["path"].trim() : "";
-        const path = pathRaw ? pathRaw : undefined;
-        if (path && !isAbsolute(path) && !MediaUrlFetcher.isHttpUrl(path)) {
-            throw new Error("path debe ser una ruta de archivo absoluta o una URL http(s).");
-        }
-        const pathsRaw = obj["paths"];
-        let paths;
-        if (typeof pathsRaw !== "undefined") {
-            if (!Array.isArray(pathsRaw)) {
-                throw new Error("paths debe ser un arreglo de rutas de archivo absolutas.");
-            }
-            const out = [];
-            for (const item of pathsRaw) {
-                if (typeof item !== "string" || !item.trim()) {
-                    continue;
-                }
-                const p = item.trim();
-                if (!isAbsolute(p) && !MediaUrlFetcher.isHttpUrl(p)) {
-                    throw new Error("paths debe contener sólo rutas de archivo absolutas o URLs http(s).");
-                }
-                out.push(p);
-            }
-            if (out.length > 0) {
-                paths = out;
-            }
-        }
-        if (!path && (!paths || paths.length === 0)) {
-            throw new Error("Proporcione 'path' o 'paths'.");
-        }
-        const context = optionalString(obj["context"]);
-        const question = optionalString(obj["question"]);
-        const language = optionalString(obj["language"]);
-        const maxFrames = optionalInt(obj["max_frames"]);
-        const transcribe = optionalBoolean(obj["transcribe"]);
-        const transcriptionLanguage = optionalString(obj["transcription_language"]);
-        const analysisModeRaw = optionalString(obj["analysis_mode"]);
-        const analysisMode = analysisModeRaw === "auto" || analysisModeRaw === "single" || analysisModeRaw === "multipass"
-            ? analysisModeRaw
-            : analysisModeRaw
-                ? (() => {
-                    throw new Error("analysis_mode debe ser uno de: auto|single|multipass.");
-                })()
-                : undefined;
-        const videoRaw = obj["video"];
-        let video;
-        if (typeof videoRaw !== "undefined") {
-            const v = assertObject(videoRaw, "video");
-            video = {
-                clipStartSeconds: optionalNumber(v["clip_start_seconds"]),
-                clipDurationSeconds: optionalNumber(v["clip_duration_seconds"]),
-                segmentSeconds: optionalNumber(v["segment_seconds"]),
-                maxSegments: optionalInt(v["max_segments"]),
-                maxFramesPerSegment: optionalInt(v["max_frames_per_segment"])
-            };
-        }
-        const documentRaw = obj["document"];
-        let document;
-        if (typeof documentRaw !== "undefined") {
-            const d = assertObject(documentRaw, "document");
-            document = {
-                maxPagesTotal: optionalInt(d["max_pages_total"]),
-                pagesPerBatch: optionalInt(d["pages_per_batch"]),
-                maxImagesPerBatch: optionalInt(d["max_images_per_batch"]),
-                scannedTextThresholdChars: optionalInt(d["scanned_text_threshold_chars"])
-            };
-        }
-        const audioRaw = obj["audio"];
-        let audio;
-        if (typeof audioRaw !== "undefined") {
-            const a = assertObject(audioRaw, "audio");
-            audio = {
-                timestamps: optionalBoolean(a["timestamps"]),
-                segmentSeconds: optionalNumber(a["segment_seconds"]),
-                maxSegments: optionalInt(a["max_segments"])
-            };
-        }
-        const imagesRaw = obj["images"];
-        let images;
-        if (typeof imagesRaw !== "undefined") {
-            const img = assertObject(imagesRaw, "images");
-            images = {
-                maxImagesTotal: optionalInt(img["max_images_total"]),
-                imagesPerBatch: optionalInt(img["images_per_batch"]),
-                maxDimension: optionalInt(img["max_dimension"])
-            };
-        }
-        return {
-            path,
-            paths,
-            context,
-            question,
-            language,
-            maxFrames,
-            transcribe,
-            transcriptionLanguage,
-            analysisMode,
-            region: this.parseRegion(obj["region"]),
-            video,
-            document,
-            audio,
-            images
-        };
+        return this.paramParser.parseParams(raw);
     }
     /**
      * Executes the tool.
      *
-     * @param params - Validated parameters
-     * @returns Tool result
+     * @param params - Validated parameters.
+     * @param options - Optional execution options (cancellation signal).
+     * @returns Tool result.
+     * @throws Error with an Spanish-first bilingual message when configuration, upload, or analysis fails.
      */
-    async execute(params) {
+    async execute(params, options) {
+        const signal = options?.signal;
+        if (signal?.aborted) {
+            throw new Error("La solicitud fue cancelada por el cliente. / Request cancelled by the client.");
+        }
         const serverUrl = assertHttpUrl(this.deps.defaultServerUrl, "ENRIPROXY_URL");
         const apiKey = assertNonEmptyString(this.deps.defaultApiKey, "ENRIPROXY_API_KEY");
         const timeoutMs = this.deps.defaultTimeoutMs;
         const clientTraceId = `enrivision_${randomUUID()}`;
         const client = this.deps.createClient(serverUrl, apiKey, timeoutMs);
-        const requestedPaths = Array.isArray(params.paths) && params.paths.length > 0
-            ? [...params.paths]
-            : typeof params.path === "string" && params.path.trim()
-                ? [params.path.trim()]
-                : [];
-        if (requestedPaths.length === 0) {
-            throw new Error("Proporcione 'path' o 'paths'.");
-        }
-        const materialized = [];
+        // Continuation mode: no upload, no analysis, no filesystem touch — only
+        // the next window of a previously truncated list.
+        if (typeof params.cursor === "string") {
+            return await this.executeContinuation(client, params.cursor, params.offset, params.continuationLimit, signal);
+        }
+        const resolved = await this.inputResolver.resolve(params, signal);
+        let uploadId = null;
         try {
-            const inputs = [];
-            for (const requested of requestedPaths) {
-                if (!MediaUrlFetcher.isHttpUrl(requested)) {
-                    inputs.push({ localPath: requested });
-                    continue;
-                }
-                const fetched = await this.urlFetcher.fetch(requested);
-                materialized.push(fetched);
-                inputs.push({ localPath: fetched.localPath, urlContentType: fetched.contentType });
+            // Inside the try so the finally below always releases materialized
+            // URL downloads, even when the region check throws (A1).
+            this.rejectRegionForNonImage(params.region, resolved.inputs);
+            this.rejectMismatchedTuning(params, resolved.inputs);
+            // Fail-open vision probe (mirrors EnriCode `assertRemoteVisionCapable`):
+            // with an explicit visionless model, fail before any session or byte
+            // instead of uploading up to 4 GiB first. Only `vision === false`
+            // rejects; unknown models and probe failures proceed (fail-open).
+            await this.assertVisionCapable(client, this.resolveRequestedModel(params), signal);
+            // Advisory mismatch warnings for the remote (`source_url`) branch: the
+            // local gates above no-op on the empty input list by design (the server,
+            // which sees the served type, decides applicability), but when the URL
+            // extension guesses a known media type, likely-ignored tuning is
+            // declared as warnings instead of failing.
+            const remoteUrl = resolved.remoteUrl;
+            const remoteAdvisoryWarnings = remoteUrl !== undefined ? this.advisoryRemoteTuningWarnings(params, remoteUrl) : [];
+            const transcribeWarning = this.transcribeInapplicableWarning(params, resolved.inputs);
+            // Oversized lone URLs skip upload entirely: the server ingests
+            // `source_url` directly (SSRF guards already passed client-side).
+            if (remoteUrl === undefined && resolved.inputs.length > 1) {
+                uploadId = await this.tarPackager.uploadImageSetAsMediaSetTar(client, resolved.inputs, timeoutMs, clientTraceId, signal);
             }
-            let uploadId;
-            if (inputs.length > 1) {
-                uploadId = await this.uploadImageSetAsMediaSetTar(client, inputs, timeoutMs, clientTraceId);
-            }
-            else {
-                const single = inputs[0];
-                const fileSize = await this.assertReadableFile(single.localPath);
-                const filename = basename(single.localPath);
-                const contentType = this.resolveEffectiveContentType(single.localPath, single.urlContentType);
-                const session = await client.createUploadSession({
-                    filename,
-                    sizeBytes: fileSize,
-                    contentType,
-                    clientTraceId
-                });
-                const finalOffset = await this.uploadFileResumable(client, single.localPath, fileSize, session, timeoutMs);
-                if (finalOffset !== fileSize) {
-                    throw new Error(`Subida incompleta: se enviaron ${finalOffset} de ${fileSize} bytes.`);
+            else if (remoteUrl === undefined) {
+                const single = resolved.inputs[0];
+                const session = await withResumableRetry(() => client.createUploadSession({
+                    filename: single.filename,
+                    sizeBytes: single.sizeBytes,
+                    contentType: single.contentType,
+                    clientTraceId,
+                    signal,
+                }), signal);
+                const serverMaxBytes = typeof session.max_file_size_bytes === "number"
+                    && Number.isFinite(session.max_file_size_bytes)
+                    && session.max_file_size_bytes > 0
+                    ? Math.floor(session.max_file_size_bytes)
+                    : null;
+                if (serverMaxBytes !== null && single.sizeBytes > serverMaxBytes) {
+                    try {
+                        await client.deleteUploadSession(session.upload_id, AbortSignal.timeout(15_000));
+                    }
+                    catch {
+                        // Best-effort: the size error always wins.
+                    }
+                    throw new Error(`El archivo excede el tamaño máximo del servidor (${String(serverMaxBytes)} bytes); use un archivo más pequeño. / File exceeds the server maximum size (${String(serverMaxBytes)} bytes); use a smaller file.`);
+                }
+                const finalOffset = await this.uploader.uploadFileResumable(client, single.localPath, single.sizeBytes, session, timeoutMs, signal, single.stagedIdentity);
+                if (finalOffset !== single.sizeBytes) {
+                    throw new Error(`Subida incompleta: se enviaron ${finalOffset} de ${single.sizeBytes} bytes. / Incomplete upload: sent ${finalOffset} of ${single.sizeBytes} bytes.`);
                 }
                 uploadId = session.upload_id;
             }
             const defaultLanguageRaw = typeof process.env["ENRIVISION_DEFAULT_LANGUAGE"] === "string"
                 ? process.env["ENRIVISION_DEFAULT_LANGUAGE"].trim()
                 : "";
-            const language = typeof params.language === "string" && params.language.trim()
-                ? params.language.trim()
-                : defaultLanguageRaw
+            const defaultLanguageValid = defaultLanguageRaw.length > 0
+                && defaultLanguageRaw.length <= 32
+                && /^[A-Za-z]{2,8}([-_][A-Za-z0-9]{1,8}){0,2}$/.test(defaultLanguageRaw);
+            if (defaultLanguageRaw && !defaultLanguageValid && !isProgressQuiet()) {
+                console.error(`enrivision: invalid ENRIVISION_DEFAULT_LANGUAGE ('${defaultLanguageRaw}'); ignoring it and using the server default. Use a code like 'es', 'en' or 'auto'.`);
+            }
+            const explicitLanguage = typeof params.language === "string" ? params.language.trim() : "";
+            // Precedence: explicit `language` > ENRIVISION_DEFAULT_LANGUAGE > server default.
+            const language = explicitLanguage
+                ? explicitLanguage
+                : defaultLanguageValid
                     ? defaultLanguageRaw
                     : undefined;
+            if (!explicitLanguage && defaultLanguageRaw && defaultLanguageValid && !isProgressQuiet()) {
+                console.error(`enrivision: effective response language '${defaultLanguageRaw}' (ENRIVISION_DEFAULT_LANGUAGE; the explicit 'language' parameter wins).`);
+            }
+            const envModelRaw = typeof process.env["ENRIVISION_MODEL"] === "string"
+                ? process.env["ENRIVISION_MODEL"].trim()
+                : "";
+            const envModelValid = envModelRaw.length > 0 && envModelRaw.length <= 128;
+            if (envModelRaw && !envModelValid && !isProgressQuiet()) {
+                console.error(`enrivision: invalid ENRIVISION_MODEL (128 characters max); ignoring it and using auto-dispatch.`);
+            }
+            const requestedModel = typeof params.model === "string" && params.model.trim()
+                ? params.model.trim()
+                : envModelValid
+                    ? envModelRaw
+                    : undefined;
+            // Scale the unary analyze timeout by mode (mirrors EnriCode single 10 min
+            // / multipass+auto 20 min, matching the server wall-clock budgets): a
+            // single image must not retain a 30 min umbrella, while `auto` shares
+            // the multipass budget because the server may escalate to multipass and
+            // the client cannot know upfront. Explicit operator timeouts cap via
+            // Math.min.
+            const analyzeTimeoutMs = params.analysisMode === "single"
+                ? Math.min(timeoutMs, ANALYZE_MEDIA_LIMITS.singleAnalyzeTimeoutMs)
+                : Math.min(timeoutMs, ANALYZE_MEDIA_LIMITS.multipassAnalyzeTimeoutMs);
             const analysis = await client.analyze({
-                uploadId,
+                ...(uploadId !== null ? { uploadId } : { sourceUrl: remoteUrl }),
+                ...(requestedModel ? { model: requestedModel } : {}),
+                timeoutMs: analyzeTimeoutMs,
                 context: params.context,
                 question: params.question,
                 language,
@@ -233,367 +216,538 @@ export class AnalyzeMediaTool {
                 video: params.video,
                 document: params.document,
                 audio: params.audio,
-                images: params.images
+                images: params.images,
+                signal,
             });
             const extraction = this.stripInternalExtractionFields(analysis.extraction);
-            return {
+            // Surface the effective model + correlation id from the server: the
+            // model id tells the caller which dispatch branch actually answered
+            // (useful with auto-dispatch and affinity hints).
+            if (typeof analysis.model === "string" && analysis.model.length > 0) {
+                extraction["model_used"] = analysis.model;
+            }
+            if (typeof analysis.request_id === "string" && analysis.request_id.length > 0) {
+                extraction["request_id"] = analysis.request_id;
+            }
+            const result = {
                 analysis: analysis.analysis,
                 ...(Array.isArray(analysis.elements) && analysis.elements.length > 0
-                    ? { elements: Object.freeze(analysis.elements.map((element) => Object.freeze({ ...element }))) }
+                    ? {
+                        elements: Object.freeze(analysis.elements.map((element) => Object.freeze({ ...element, box: Object.freeze({ ...element.box }) }))),
+                    }
                     : {}),
                 media_type: analysis.media_type,
-                extraction
+                ...((params.warnings && params.warnings.length > 0) || transcribeWarning || remoteAdvisoryWarnings.length > 0 || (analysis.warnings && analysis.warnings.length > 0)
+                    ? {
+                        warnings: [
+                            ...(params.warnings ?? []),
+                            ...(transcribeWarning ? [transcribeWarning] : []),
+                            ...remoteAdvisoryWarnings,
+                            ...(analysis.warnings ?? []),
+                        ],
+                    }
+                    : {}),
+                extraction,
             };
+            // Release server bytes on success too: upload sessions live ~3 h and
+            // count against the per-key quota, so a successful analysis must not
+            // leak its session (mirrors EnriCode bestEffortDeleteUploadSession).
+            await this.deleteUploadedBytesBestEffort(client, uploadId);
+            return result;
+        }
+        catch (error) {
+            await this.deleteUploadedBytesBestEffort(client, uploadId);
+            throw error;
         }
         finally {
-            for (const fetched of materialized) {
-                await fetched.cleanup();
+            for (const fetched of resolved.materialized) {
+                try {
+                    await fetched.cleanup();
+                }
+                catch (cleanupError) {
+                    if (!isProgressQuiet()) {
+                        console.error(`enrivision: temp cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
+                    }
+                }
             }
         }
     }
     /**
-     * Resolves the upload content type for one media input.
+     * Rejects a `region` zoom against non-image inputs before any upload.
      *
      * @remarks
-     * URL downloads keep their extension-derived type when the extension is
-     * recognized; otherwise the server-reported content type wins over the
-     * generic `application/octet-stream` fallback.
+     * `region` zooms one image at native resolution: sending it with video,
+     * audio, PDF, or a tar set wastes an upload plus a server rejection (or
+     * a silent ignore). Fail locally in Spanish using the resolved effective
+     * content type (server-reported type wins, mirroring the resolver).
      *
-     * @param localPath - Local file path (already materialized for URLs)
-     * @param urlContentType - Server-reported content type for downloaded URLs
-     * @returns Effective MIME type
+     * @param region - Validated region, or undefined when absent.
+     * @param inputs - Resolved upload-ready inputs.
+     * @throws Error with an Spanish-first bilingual message when `region` targets non-image media.
      */
-    resolveEffectiveContentType(localPath, urlContentType) {
-        const detected = this.detectMimeType(localPath);
-        if (detected !== "application/octet-stream") {
-            return detected;
+    rejectRegionForNonImage(region, inputs) {
+        if (!region || inputs.length !== 1) {
+            return;
         }
-        if (urlContentType && urlContentType.trim() && urlContentType !== "application/octet-stream") {
-            return urlContentType.trim();
+        const single = inputs[0];
+        if (!single.contentType.toLowerCase().startsWith("image/")) {
+            throw new Error(`region sólo aplica a imágenes; el archivo es ${single.contentType} (${single.localPath}). Omita 'region' para video, audio o documentos. / region only applies to images; the file is ${single.contentType} (${single.localPath}). Omit 'region' for video, audio, or documents.`);
         }
-        return detected;
     }
     /**
-     * Removes internal identifiers (upload ids, routing-only values, etc.) from the
-     * extraction payload before returning it to the model.
+     * Rejects tuning knobs that the resolved content type would silently ignore.
      *
-     * @param extraction - Raw extraction object returned by EnriProxy
-     * @returns Sanitized extraction object
-     */
-    stripInternalExtractionFields(extraction) {
-        const stripped = this.stripInternalFields(extraction);
-        return this.asPlainObject(stripped);
-    }
-    /**
-     * Recursively strips internal fields from an unknown value.
+     * @remarks
+     * Pre-upload gate mirroring EnriCode `VisionAnalyzeMediaRequestRecords`:
+     * `video.*` tuning only applies to video, `images.*` only to images
+     * and documents (PDF page-image sets on the remote route), `document.*`
+     * only to PDF/Office/TXT/CSV, clip/`maxFramesPerSegment` never to audio,
+     * `video.segment_seconds`/`max_segments` never to audio without an audio
+     * section, and `audio.segment_seconds`/`max_segments` never to video
+     * without a video section (shared flats fan out to both sections by
+     * design and are exempt). Multi-image sets only accept `images.*`. The top-level
+     * `maxFrames` knob is media-agnostic by design (EnriCode declares
+     * `max_frames` "sin efecto en imágenes fijas o audio"): it never
+     * triggers a mismatch gate and is forwarded for the server to apply or
+     * ignore. Unknown content types (`application/octet-stream` included)
+     * skip every gate by design so the server (not this gate) decides
+     * applicability, mirroring EnriCode `VisionAnalyzeMediaRequestRecords`.
+     * Failing here saves the
+     * full upload plus a late server rejection.
      *
-     * @param value - Unknown value to sanitize
-     * @returns Sanitized value
+     * @param params - Validated tool parameters.
+     * @param inputs - Resolved upload-ready inputs.
+     * @throws Error with an Spanish-first bilingual message when tuning mismatches the content type.
      */
-    stripInternalFields(value) {
-        if (Array.isArray(value)) {
-            return value.map((item) => this.stripInternalFields(item));
-        }
-        if (!value || typeof value !== "object") {
-            return value;
-        }
-        const record = value;
-        const next = {};
-        for (const [key, child] of Object.entries(record)) {
-            if (key === "upload_id" || key === "uploadId") {
-                continue;
-            }
-            if (key === "detected_media_type") {
-                continue;
+    rejectMismatchedTuning(params, inputs) {
+        // Top-level `maxFrames` is media-agnostic (EnriCode `max_frames` is
+        // "sin efecto en imágenes fijas o audio"): only the `video` section
+        // participates in the video-only gate.
+        const hasVideoTuning = typeof params.video !== "undefined";
+        const hasDocumentTuning = typeof params.document !== "undefined";
+        const hasImagesTuning = typeof params.images !== "undefined";
+        const hasAudioTuning = typeof params.audio !== "undefined";
+        if (!hasVideoTuning && !hasDocumentTuning && !hasImagesTuning && !hasAudioTuning) {
+            return;
+        }
+        if (inputs.length > 1) {
+            if (hasVideoTuning || hasDocumentTuning || hasAudioTuning) {
+                throw new Error("El afinado video/document/audio solo aplica a archivos individuales y se habría ignorado en el conjunto de imágenes: quite esos parámetros o use images.* para conjuntos. / video/document/audio tuning only applies to single files and would have been ignored on the image set: drop those params or use images.* for sets.");
             }
-            if (key === "analysis_mode_requested" || key === "analysis_mode_used") {
-                continue;
+            return;
+        }
+        const single = inputs[0];
+        if (!single) {
+            return;
+        }
+        const normalized = single.contentType.trim().toLowerCase();
+        const isImage = normalized.startsWith("image/");
+        const isVideo = normalized.startsWith("video/");
+        const isAudio = normalized.startsWith("audio/");
+        const isDocument = isDocumentContentType(normalized);
+        // Unknown content types (empty, `application/octet-stream`, or any
+        // non-media guess) skip every mismatch gate by design: the server (not
+        // this gate) decides applicability. Mirrors EnriCode
+        // `VisionAnalyzeMediaRequestRecords` ("Unknown content types ...
+        // forward guarded knobs untouched ... so the server decides").
+        if (normalized === "" || (!isImage && !isVideo && !isAudio && !isDocument)) {
+            return;
+        }
+        if (hasDocumentTuning && !isDocument) {
+            throw new Error(`El afinado 'document.*' solo aplica a PDF y documentos de Office/TXT/CSV y se habría ignorado en silencio: quite esos parámetros o use un documento (el archivo es ${single.contentType}). / 'document.*' tuning only applies to PDF and Office/TXT/CSV documents and would have been silently ignored: drop those params or use a document (the file is ${single.contentType}).`);
+        }
+        if (hasImagesTuning && (isVideo || isAudio)) {
+            throw new Error(`El afinado 'images.*' solo aplica a imágenes y documentos y se habría ignorado en silencio: quite esos parámetros o use un archivo de imagen o documento (el archivo es ${single.contentType}). / 'images.*' tuning only applies to images and documents and would have been silently ignored: drop those params or use an image or document file (the file is ${single.contentType}).`);
+        }
+        if (hasVideoTuning && (isImage || isDocument)) {
+            throw new Error(`El afinado de video (clip, segmentSeconds, maxSegments, maxFramesPerSegment) solo aplica a video y se habría ignorado en silencio: quite esos parámetros o use un archivo de video (el archivo es ${single.contentType}). / Video tuning (clip, segmentSeconds, maxSegments, maxFramesPerSegment) only applies to video and would have been silently ignored: drop those params or use a video file (the file is ${single.contentType}).`);
+        }
+        // Wrong-section scalar knobs are only rejected when the matching section
+        // is absent: shared top-level flats fan out to BOTH sections by design
+        // (the server applies the media-matching one), so a video+audio pair
+        // with equal segment values is the flat fan-out, never a silent drop.
+        if (isAudio && typeof params.video !== "undefined") {
+            const video = params.video;
+            const audioSegmentActive = typeof params.audio?.segmentSeconds !== "undefined"
+                || typeof params.audio?.maxSegments !== "undefined";
+            if (typeof video.clipStartSeconds !== "undefined"
+                || typeof video.clipDurationSeconds !== "undefined"
+                || typeof video.maxFramesPerSegment !== "undefined") {
+                throw new Error(`El afinado de video (clip o maxFramesPerSegment) no aplica a audio y se habría ignorado en silencio: quite clip/maxFramesPerSegment o use un archivo de video (el archivo es ${single.contentType}). / Video tuning (clip or maxFramesPerSegment) does not apply to audio and would have been silently ignored: drop clip/maxFramesPerSegment or use a video file (the file is ${single.contentType}).`);
             }
-            if (key === "multipass") {
-                continue;
+            if (!audioSegmentActive
+                && (typeof video.segmentSeconds !== "undefined" || typeof video.maxSegments !== "undefined")) {
+                throw new Error(`El afinado video.segment_seconds/max_segments no aplica a audio y se habría ignorado en silencio: use audio.segment_seconds/max_segments o los planos segmentSeconds/maxSegments (el archivo es ${single.contentType}). / video.segment_seconds/max_segments tuning does not apply to audio and would have been silently ignored: use audio.segment_seconds/max_segments or the flat segmentSeconds/maxSegments (the file is ${single.contentType}).`);
             }
-            if (key === "model") {
-                continue;
+        }
+        if (isVideo && typeof params.audio !== "undefined") {
+            const audio = params.audio;
+            const videoSegmentActive = typeof params.video?.segmentSeconds !== "undefined"
+                || typeof params.video?.maxSegments !== "undefined";
+            if (!videoSegmentActive
+                && (typeof audio.segmentSeconds !== "undefined" || typeof audio.maxSegments !== "undefined")) {
+                throw new Error(`El afinado audio.segment_seconds/max_segments no aplica a video y se habría ignorado en silencio: use video.segment_seconds/max_segments o los planos segmentSeconds/maxSegments (el archivo es ${single.contentType}). / audio.segment_seconds/max_segments tuning does not apply to video and would have been silently ignored: use video.segment_seconds/max_segments or the flat segmentSeconds/maxSegments (the file is ${single.contentType}).`);
             }
-            next[key] = this.stripInternalFields(child);
         }
-        return next;
     }
     /**
-     * Ensures the sanitized extraction value is a plain JSON object.
+     * Resolves the requested server-side model id for dispatch affinity.
+     *
+     * @remarks
+     * Pure read of `params.model` plus the validated `ENRIVISION_MODEL` env
+     * fallback (no operator logging): used by the pre-upload vision probe,
+     * which runs before the main model-resolution block in `execute`.
      *
-     * @param value - Sanitized value
-     * @returns Plain object
+     * @param params - Validated tool parameters.
+     * @returns Trimmed model id, or undefined for auto-dispatch.
      */
-    asPlainObject(value) {
-        if (value && typeof value === "object" && !Array.isArray(value)) {
-            return value;
+    resolveRequestedModel(params) {
+        if (typeof params.model === "string" && params.model.trim()) {
+            return params.model.trim();
+        }
+        const envModelRaw = typeof process.env["ENRIVISION_MODEL"] === "string"
+            ? process.env["ENRIVISION_MODEL"].trim()
+            : "";
+        if (envModelRaw.length > 0 && envModelRaw.length <= 128) {
+            return envModelRaw;
         }
-        return {};
+        return undefined;
     }
     /**
-     * Validates that a path exists and is a readable file.
+     * Fails fast when the requested model explicitly lacks vision, before any byte.
      *
-     * @param filePath - Local filesystem path
-    /**
-     * Parses and validates the optional relative image region.
+     * @remarks
+     * Mirrors EnriCode `assertRemoteVisionCapable`: probes `GET
+     * `/v1/account/models` (15 s budget inside the client) and matches the
+     * requested model by `id`, `requestModelId`, or canonical ids. Only an
+     * explicit `vision === false` rejects; unknown models, missing flags, and
+     * probe failures stay fail-open so a stale discovery snapshot never blocks
+     * a valid upload. Verdicts are cached per client for 5 min; 401/404 probe
+     * failures invalidate the entry so revoked keys never ride a stale verdict.
+     * Clients without `getAccountModels` (older stubs) skip the probe entirely.
      *
-     * @param raw - Raw `region` argument.
-     * @returns Validated region, or undefined when absent.
+     * @param client - EnriProxy client used for the upload.
+     * @param requestedModel - Trimmed model id, or undefined for auto-dispatch.
+     * @param signal - Optional cancellation signal.
+     * @throws Error with an Spanish-first bilingual message when the model explicitly lacks vision.
      */
-    parseRegion(raw) {
-        if (raw === undefined || raw === null) {
-            return undefined;
+    async assertVisionCapable(client, requestedModel, signal) {
+        const modelId = typeof requestedModel === "string" ? requestedModel.trim() : "";
+        if (!modelId || signal?.aborted) {
+            return;
+        }
+        const probe = client;
+        if (typeof probe.getAccountModels !== "function") {
+            return;
+        }
+        const now = Date.now();
+        const cacheKey = `${this.deps.defaultServerUrl}::${modelId}`;
+        const cached = this.visionProbeCache.get(cacheKey);
+        if (cached !== undefined && cached.expiresAt > now) {
+            if (!cached.verdict) {
+                throw AnalyzeMediaTool.buildVisionlessModelError(modelId);
+            }
+            return;
         }
-        if (typeof raw !== "object" || Array.isArray(raw)) {
-            throw new Error("region debe ser un objeto {x, y, width, height} con coordenadas relativas entre 0 y 1. Nunca invente coordenadas: use las cajas devueltas en 'elements' de un análisis previo de la misma imagen.");
+        if (cached !== undefined) {
+            this.visionProbeCache.delete(cacheKey);
         }
-        const record = raw;
-        const readFraction = (fieldName) => {
-            const value = record[fieldName];
-            const parsed = typeof value === "number" ? value : Number(value);
-            if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
-                throw new Error(`region.${fieldName} debe ser un número entre 0 y 1 (coordenadas relativas a la imagen original). Use las cajas de 'elements' de un análisis previo.`);
+        let payload;
+        try {
+            payload = await probe.getAccountModels.call(client, signal);
+        }
+        catch (error) {
+            if (error instanceof EnriProxyHttpError && (error.status === 401 || error.status === 404)) {
+                this.visionProbeCache.delete(cacheKey);
             }
-            return parsed;
-        };
-        const region = {
-            x: readFraction("x"),
-            y: readFraction("y"),
-            width: readFraction("width"),
-            height: readFraction("height")
-        };
-        if (region.width <= 0 || region.height <= 0) {
-            throw new Error("region.width y region.height deben ser mayores que 0.");
+            return;
+        }
+        const entry = findAccountModelEntry(payload, modelId);
+        if (entry === null) {
+            return;
         }
-        return region;
+        if (entry.vision === false) {
+            this.rememberVisionProbe(cacheKey, false, now);
+            throw AnalyzeMediaTool.buildVisionlessModelError(modelId);
+        }
+        this.rememberVisionProbe(cacheKey, true, now);
     }
     /**
-     * Validates that a path exists and is a readable file.
+     * Maximum vision-probe cache entries (model ids are caller-controlled).
+     */
+    static MAX_VISION_PROBE_ENTRIES = 100;
+    /**
+     * Remembers one vision-probe verdict, purging expired entries and
+     * evicting oldest-first past the cap so long-lived tool instances
+     * cannot leak one entry per distinct model id.
      *
-     * @param filePath - Local filesystem path
-     * @returns File size in bytes
+     * @param cacheKey - Server plus model cache key.
+     * @param verdict - Whether the model has vision.
+     * @param now - Current epoch milliseconds.
+     * @returns Nothing.
      */
-    async assertReadableFile(filePath) {
-        if (!existsSync(filePath)) {
-            throw new Error(`Archivo no encontrado: ${filePath}`);
-        }
-        const st = await stat(filePath);
-        if (!st.isFile()) {
-            throw new Error(`No es un archivo: ${filePath}`);
-        }
-        // Ensure the file is readable.
-        const handle = await open(filePath, "r");
-        try {
-            return st.size;
+    rememberVisionProbe(cacheKey, verdict, now) {
+        for (const [key, entry] of this.visionProbeCache) {
+            if (entry.expiresAt <= now) {
+                this.visionProbeCache.delete(key);
+            }
         }
-        finally {
-            await handle.close();
+        while (this.visionProbeCache.size >= AnalyzeMediaTool.MAX_VISION_PROBE_ENTRIES) {
+            const oldest = this.visionProbeCache.keys().next().value;
+            if (oldest === undefined) {
+                break;
+            }
+            this.visionProbeCache.delete(oldest);
         }
+        this.visionProbeCache.set(cacheKey, { verdict, expiresAt: now + ANALYZE_MEDIA_LIMITS.visionProbeCacheTtlMs });
     }
     /**
-     * Detects MIME type using file extension.
+     * Builds the visionless-model rejection error.
      *
-     * @param filePath - File path
-     * @returns MIME type string
+     * @param modelId - Requested model id.
+     * @returns Spanish-first bilingual error (no byte was uploaded).
      */
-    detectMimeType(filePath) {
-        const detected = mimeLookup(filePath);
-        if (typeof detected === "string" && detected.trim()) {
-            return detected.trim();
-        }
-        return "application/octet-stream";
+    static buildVisionlessModelError(modelId) {
+        return new Error(`El modelo ${modelId} no tiene capacidad de visión (vision=false en /v1/account/models). Elige un modelo con visión o usa la ruta local; no se subió ningún byte. / Model ${modelId} has no vision capability (vision=false in /v1/account/models). Pick a vision-capable model or use the local route; no bytes were uploaded.`);
     }
     /**
-     * Uploads multiple local images as a single EnriVision media-set tar archive.
+     * Executes one truncated-list continuation read (no upload, no analysis).
+     *
+     * @param client - EnriProxy client.
+     * @param cursor - Opaque cursor from a truncated response.
+     * @param offset - Start index, or undefined for the stored next offset.
+     * @param limit - Window length (1-100), or undefined for the server default.
+     * @param signal - Optional cancellation signal.
+     * @returns Tool result carrying the page plus chaining state.
+     */
+    async executeContinuation(client, cursor, offset, limit, signal) {
+        const page = await client.fetchSegmentPage({
+            cursor,
+            ...(typeof offset === "number" ? { offset } : {}),
+            ...(typeof limit === "number" ? { limit } : {}),
+            ...(typeof signal !== "undefined" ? { signal } : {}),
+        });
+        const lines = page.entries.map((entry) => {
+            if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+                return `- ${String(entry ?? "")}`;
+            }
+            const record = entry;
+            const text = record["summary"] ?? record["text"];
+            const start = record["start_seconds"] ?? record["start"];
+            const end = record["end_seconds"] ?? record["end"];
+            const span = typeof start === "number" && typeof end === "number"
+                ? ` [${start.toFixed(2)}-${end.toFixed(2)}s]`
+                : "";
+            return `- ${String(text ?? JSON.stringify(entry) ?? "")}${span}`;
+        });
+        const end = page.nextOffset;
+        const start = Math.max(0, end - lines.length);
+        const header = `Continuación: entradas ${start}-${end} de ${page.total} / Continuation: entries ${start}-${end} of ${page.total}.`;
+        const tail = page.hasMore
+            ? `Quedan ${page.total - end} entradas: pide más con cursor "${page.cursor}" y offset ${end}. / ${page.total - end} entries remain: ask for more with cursor "${page.cursor}" and offset ${end}.`
+            : `No quedan más entradas. / No more entries.`;
+        return {
+            analysis: `${header}\n${lines.join("\n")}\n${tail}`,
+            media_type: "continuation",
+            warnings: [],
+            extraction: {
+                continuation: true,
+                total: page.total,
+                has_more: page.hasMore,
+                next_offset: page.nextOffset,
+                cursor: page.cursor,
+            },
+        };
+    }
+    /**
+     * Warns when `transcribe` is set for media it cannot affect.
      *
      * @remarks
-     * This avoids creating many concurrent resumable upload sessions (which are
-     * capped per API key) and enables server-side batching + reduce for large
-     * screenshot sets.
+     * Mirrors EnriCode `LocalMediaAnalysisService` (transcribe is inapplicable
+     * for images and documents): instead of failing, the knob is forwarded
+     * and declared as a bilingual honesty warning so the model never assumes
+     * audio was transcribed. Videos and audio files never warn.
      *
-     * @param client - EnriProxy client
-     * @param inputs - Resolved media inputs (local paths, URLs already materialized)
-     * @param timeoutMs - Request timeout per HTTP request
-     * @param clientTraceId - Client trace id for correlation
-     * @returns Upload id for the created tar session
+     * @param params - Validated tool parameters.
+     * @param inputs - Resolved upload-ready inputs.
+     * @returns Bilingual warning, or undefined when `transcribe` may apply.
      */
-    async uploadImageSetAsMediaSetTar(client, inputs, timeoutMs, clientTraceId) {
-        if (inputs.length < 2) {
-            throw new Error("uploadImageSetAsMediaSetTar requires at least 2 file paths.");
-        }
-        const files = [];
-        for (let i = 0; i < inputs.length; i += 1) {
-            const input = inputs[i];
-            const sizeBytes = await this.assertReadableFile(input.localPath);
-            const filename = basename(input.localPath);
-            const contentType = this.resolveEffectiveContentType(input.localPath, input.urlContentType);
-            if (!contentType.toLowerCase().startsWith("image/")) {
-                throw new Error(`paths debe contener sólo archivos de imagen. No es imagen: ${input.localPath} (${contentType})`);
-            }
-            const extRaw = extname(filename).toLowerCase();
-            const ext = extRaw && /^[a-z0-9.]+$/.test(extRaw) ? extRaw : ".img";
-            const entryName = `${String(i + 1).padStart(6, "0")}${ext}`;
-            files.push({
-                index: i + 1,
-                path: input.localPath,
-                filename,
-                sizeBytes,
-                contentType,
-                entryName
-            });
+    transcribeInapplicableWarning(params, inputs) {
+        if (typeof params.transcribe === "undefined") {
+            return undefined;
         }
-        const manifest = {
-            type: "enrivision_media_set",
-            version: 1,
-            media_type: "image_set",
-            items: files.map((f) => ({
-                index: f.index,
-                name: f.entryName,
-                filename: f.filename,
-                content_type: f.contentType,
-                size_bytes: f.sizeBytes
-            }))
-        };
-        const manifestBuffer = Buffer.from(JSON.stringify(manifest), "utf8");
-        const nowSeconds = Math.floor(Date.now() / 1000);
-        const entries = [
-            {
-                name: ENRIVISION_MEDIA_SET_TAR_MANIFEST_NAME,
-                source: { type: "buffer", buffer: manifestBuffer },
-                mtimeSeconds: nowSeconds
-            },
-            ...files.map((f) => ({
-                name: f.entryName,
-                source: { type: "file", path: f.path, sizeBytes: f.sizeBytes },
-                mtimeSeconds: nowSeconds
-            }))
-        ];
-        const tarSizeBytes = computeTarSizeBytes(entries);
-        const tar = new TarStream(entries);
-        if (tar.getSizeBytes() !== tarSizeBytes) {
-            throw new Error("Internal error: tar size mismatch.");
-        }
-        const session = await client.createUploadSession({
-            filename: "enrivision-image-set.tar",
-            sizeBytes: tarSizeBytes,
-            contentType: ENRIVISION_MEDIA_SET_TAR_CONTENT_TYPE,
-            clientTraceId
-        });
-        const chunkSize = Math.max(1, Math.floor(session.chunk_size_bytes));
-        let offset = await client.getUploadOffset(session.upload_id);
-        if (offset < 0 || offset > tarSizeBytes) {
-            throw new Error(`Invalid server offset for tar upload: ${offset}`);
-        }
-        while (offset < tarSizeBytes) {
-            let madeProgress = false;
-            for await (const chunk of tar.iterateChunks(offset, chunkSize)) {
-                if (chunk.length === 0) {
-                    continue;
-                }
-                const expectedOffset = offset;
-                const nextOffset = await this.uploadChunkWithRetry(client, session.upload_id, expectedOffset, chunk, timeoutMs);
-                offset = nextOffset;
-                madeProgress = true;
-                const progress = Math.floor((offset / tarSizeBytes) * 100);
-                console.error(`enrivision: upload ${progress}% (${offset}/${tarSizeBytes} bytes)`);
-                // Offset resync: restart generation from the server-provided offset.
-                if (offset !== expectedOffset + chunk.length) {
-                    break;
-                }
-                if (offset >= tarSizeBytes) {
-                    break;
-                }
-            }
-            if (!madeProgress) {
-                throw new Error("Subida estancada: no hubo progreso al enviar los fragmentos del tar.");
-            }
+        if (inputs.length > 1) {
+            return ("transcribe no tiene efecto en conjuntos de varias imágenes y se ignora. / " +
+                "transcribe has no effect on multi-image sets and is ignored.");
         }
-        if (offset !== tarSizeBytes) {
-            throw new Error(`Subida incompleta: se enviaron ${offset} de ${tarSizeBytes} bytes.`);
+        const single = inputs[0];
+        if (!single) {
+            return undefined;
+        }
+        const normalized = single.contentType.trim().toLowerCase();
+        if (normalized.startsWith("image/")) {
+            return ("transcribe no tiene efecto en imágenes y se ignora. / " +
+                "transcribe has no effect on images and is ignored.");
         }
-        return session.upload_id;
+        if (isDocumentContentType(normalized)) {
+            return ("transcribe no tiene efecto en documentos y se ignora. / " +
+                "transcribe has no effect on documents and is ignored.");
+        }
+        return undefined;
     }
     /**
-     * Uploads a file to EnriProxy in resumable chunks.
+     * Runs the mismatch gates on the remote (`source_url`) branch as advisories.
+     *
+     * @remarks
+     * The local gates no-op on the empty remote input list by design (the
+     * server, which sees the served type, decides applicability). When the URL
+     * extension guesses a known media type, the same gates run against the
+     * guess and likely-ignored tuning is declared as bilingual warnings
+     * instead of errors; URLs with no usable extension stay server-decides
+     * with no warnings.
      *
-     * @param client - EnriProxy client
-     * @param filePath - Local file path
-     * @param fileSize - Total file size in bytes
-     * @param session - Server-created session
-     * @param timeoutMs - Request timeout in milliseconds
-     * @returns Final offset
+     * @param params - Validated tool parameters.
+     * @param remoteUrl - Remote http(s) URL the server will ingest.
+     * @returns Advisory warnings (empty when nothing looks mismatched).
      */
-    async uploadFileResumable(client, filePath, fileSize, session, timeoutMs) {
-        const chunkSize = Math.max(1, Math.floor(session.chunk_size_bytes));
-        const handle = await open(filePath, "r");
+    advisoryRemoteTuningWarnings(params, remoteUrl) {
+        const guessed = mimeLookup(remoteUrl.split(/[?#]/)[0] ?? remoteUrl);
+        if (typeof guessed !== "string") {
+            return [];
+        }
+        const contentType = guessed.trim().toLowerCase();
+        if (!MediaUrlFetcher.isAllowedMediaContentType(contentType)) {
+            return [];
+        }
+        const advisories = [];
+        const wrapAdvisory = (detail) => `La URL remota parece ${contentType} por extensión, así que el servidor podría ignorar este afinado (solo aviso; el servidor decide): ${detail} / ` +
+            `Remote URL looks like ${contentType} by extension, so this tuning may be ignored by the server (advisory only; the server decides): ${detail}`;
         try {
-            let offset = await client.getUploadOffset(session.upload_id);
-            while (offset < fileSize) {
-                const remaining = fileSize - offset;
-                const nextSize = Math.min(chunkSize, remaining);
-                const buffer = Buffer.allocUnsafe(nextSize);
-                const read = await handle.read(buffer, 0, nextSize, offset);
-                if (read.bytesRead <= 0) {
-                    break;
-                }
-                const chunk = read.bytesRead === buffer.length ? buffer : buffer.subarray(0, read.bytesRead);
-                offset = await this.uploadChunkWithRetry(client, session.upload_id, offset, chunk, timeoutMs);
-                const progress = Math.floor((offset / fileSize) * 100);
-                console.error(`enrivision: upload ${progress}% (${offset}/${fileSize} bytes)`);
-            }
-            return offset;
+            this.rejectMismatchedTuning(params, [{ localPath: remoteUrl, contentType }]);
         }
-        finally {
-            await handle.close();
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            advisories.push(wrapAdvisory(detail));
+        }
+        try {
+            this.rejectRegionForNonImage(params.region, [{ localPath: remoteUrl, contentType }]);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            advisories.push(wrapAdvisory(detail));
+        }
+        const transcribeWarning = this.transcribeInapplicableWarning(params, [{ localPath: remoteUrl, contentType }]);
+        if (typeof transcribeWarning !== "undefined") {
+            advisories.push(wrapAdvisory(transcribeWarning));
         }
+        return advisories;
     }
     /**
-     * Uploads a single chunk with retry and offset resync.
+     * Releases uploaded bytes when the analysis fails or is cancelled.
+     *
+     * @remarks
+     * Best-effort by design: it runs on an independent 15 s signal (the
+     * caller signal may already be cancelled) and never throws, so the
+     * original upload/analysis error always reaches the model unchanged.
      *
-     * @param client - EnriProxy client
-     * @param uploadId - Upload id
-     * @param offset - Expected offset
-     * @param chunk - Chunk bytes
-     * @param timeoutMs - Timeout in ms
-     * @returns New offset
+     * @param client - EnriProxy client used for the upload.
+     * @param uploadId - Upload id to release, or null when nothing was uploaded.
      */
-    async uploadChunkWithRetry(client, uploadId, offset, chunk, timeoutMs) {
-        const maxAttempts = 5;
-        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-            try {
-                return await client.appendUploadChunk({ uploadId, offset, chunk, timeoutMs });
+    async deleteUploadedBytesBestEffort(client, uploadId) {
+        if (!uploadId || typeof client.deleteUploadSession !== "function") {
+            return;
+        }
+        try {
+            await client.deleteUploadSession(uploadId, AbortSignal.timeout(15_000));
+        }
+        catch (cleanupError) {
+            // A second delete after an already-handled deadline/identity branch
+            // 404s: that is the expected terminal state, not noise.
+            const status = cleanupError?.status;
+            const message = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+            if (status === 404 || /HTTP 404/u.test(message)) {
+                return;
             }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                if (error instanceof EnriProxyHttpError) {
-                    // Offset mismatch: resync and let the caller re-read at the correct offset.
-                    if (error.status === 409) {
-                        const actual = await client.getUploadOffset(uploadId);
-                        if (actual !== offset) {
-                            console.error(`enrivision: offset resync (${offset} -> ${actual})`);
-                            return actual;
-                        }
-                    }
-                    // Do not retry on client errors (except 409 which is handled above).
-                    if (error.status === 400 ||
-                        error.status === 401 ||
-                        error.status === 403 ||
-                        error.status === 404 ||
-                        error.status === 410 ||
-                        error.status === 413) {
-                        throw error;
-                    }
-                }
-                if (attempt === maxAttempts) {
-                    throw error;
-                }
-                const backoffMs = Math.min(1000 * Math.pow(2, attempt - 1), 10000);
-                console.error(`enrivision: retry ${attempt}/${maxAttempts} after ${backoffMs}ms (${message})`);
-                await new Promise((resolve) => setTimeout(resolve, backoffMs));
+            if (!isProgressQuiet()) {
+                console.error(`enrivision: could not release upload ${uploadId}: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
             }
         }
-        throw new Error("La subida falló tras los reintentos.");
     }
+    /**
+     * Removes internal identifiers from the extraction payload.
+     *
+     * @param extraction - Raw extraction object returned by EnriProxy.
+     * @returns Sanitized extraction object.
+     */
+    stripInternalExtractionFields(extraction) {
+        return this.sanitizer.sanitize(extraction);
+    }
+}
+/**
+ * Reports whether one normalized content type is a document type.
+ *
+ * @remarks
+ * Shared by the mismatch gate and the `transcribe` inapplicability warning
+ * so both agree on what counts as a document (PDF, Office, TXT/CSV, RTF).
+ *
+ * @param normalizedContentType - Lowercased content type.
+ * @returns True for document types.
+ */
+function isDocumentContentType(normalizedContentType) {
+    return (normalizedContentType === "application/pdf"
+        || normalizedContentType.includes("wordprocessing")
+        || normalizedContentType.includes("msword")
+        || normalizedContentType.includes("spreadsheet")
+        || normalizedContentType.includes("excel")
+        || normalizedContentType.includes("presentation")
+        || normalizedContentType.includes("powerpoint")
+        || normalizedContentType.includes("oasis.opendocument")
+        || normalizedContentType === "text/plain"
+        || normalizedContentType === "text/csv"
+        || normalizedContentType.includes("rtf"));
+}
+/**
+ * Finds one account-model entry matching a requested model id.
+ *
+ * @remarks
+ * Mirrors EnriCode `assertRemoteVisionCapable` matching: the entry matches
+ * on `id`, `requestModelId`/`request_model_id`, or any canonical id
+ * (`canonicalIds`/`canonical_ids`). Non-object payloads, missing `data`,
+ * and non-array `data` yield null (fail-open: the caller proceeds).
+ *
+ * @param payload - Parsed `/v1/account/models` body.
+ * @param modelId - Trimmed requested model id.
+ * @returns Matched entry, or null when no entry matches.
+ */
+function findAccountModelEntry(payload, modelId) {
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+        return null;
+    }
+    const data = payload["data"];
+    if (!Array.isArray(data)) {
+        return null;
+    }
+    for (const candidate of data) {
+        if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) {
+            continue;
+        }
+        const record = candidate;
+        const ids = [
+            record["id"],
+            record["requestModelId"],
+            record["request_model_id"],
+        ];
+        const canonical = record["canonicalIds"] ?? record["canonical_ids"];
+        if (Array.isArray(canonical)) {
+            ids.push(...canonical);
+        }
+        const matches = ids.some((id) => typeof id === "string" && id.trim() === modelId);
+        if (!matches) {
+            continue;
+        }
+        const vision = record["vision"];
+        return { vision: typeof vision === "boolean" ? vision : undefined };
+    }
+    return null;
 }
 //# sourceMappingURL=AnalyzeMediaTool.js.map