scoutline 0.10.0 → 0.10.2

package/dist/lib/research-state.js

@@ -0,0 +1,214 @@
+/**
+ * Research state file — resume mechanism for interrupted research
+ * (tech-plan §3, T07).
+ *
+ * Research costs 4-250 credits per request. A research task runs
+ * asynchronously server-side: POST /research creates it and returns a
+ * `request_id`, then GET /research/{id} polls until completion. If the
+ * CLI exits (Ctrl-C, crash) mid-poll, the task keeps running and
+ * consuming credits. Without a persistence mechanism, the next identical
+ * request would POST a SECOND task — a double charge.
+ *
+ * This module persists `{ requestId, identityHash, createdAt, status }`
+ * to `~/.scoutline/research/<state-hash>.json` so the next invocation of
+ * the same request detects the in-flight task and polls it instead of
+ * creating a new one. The state-hash is deterministic for a given
+ * `{provider, capability, credentialFingerprint, request}` tuple (see
+ * `computeResearchStateHash`).
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import cache-root resolution and normalized errors.
+ *   - Must NOT import transport, command presentation, or a Provider
+ *     Adapter.
+ *
+ * Resilience contract (tech-plan §3 / G1-G3):
+ *   - `write()` uses `{ flag: "wx" }` for atomic creation. A concurrent
+ *     invocation that finds the file already exists gets EEXIST and
+ *     polls the existing task instead of creating a new one.
+ *   - `read()` catches JSON parse errors, deletes the corrupt file, and
+ *     returns `null` (treated as absent → new task created).
+ *   - `remove()` deletes the file and ignores ENOENT (already gone).
+ */
+import crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { researchStateDir } from "./cache.js";
+/**
+ * Recursively sort object keys so `JSON.stringify` produces a stable
+ * representation regardless of insertion order. Mirrors the cache module's
+ * `sortKeysDeep` so the same request hashes identically here and in the
+ * response-cache key.
+ */
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map((element) => sortKeysDeep(element));
+    }
+    if (value && typeof value === "object") {
+        const input = value;
+        const out = {};
+        for (const key of Object.keys(input).sort()) {
+            out[key] = sortKeysDeep(input[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Compute the deterministic state-file identity hash for a research
+ * request (tech-plan §3 / CR3).
+ *
+ *   state-hash = SHA-256(recursively-key-sorted-JSON({
+ *     provider, capability, credentialFingerprint, request
+ *   }))
+ *
+ * Same canonical approach as `buildProviderCacheKey`'s request hashing,
+ * extended to include provider + capability + credential. Rotating the
+ * API key orphans old state files (correct — the old task belongs to the
+ * old key's billing). The hash never contains a raw credential.
+ */
+export function computeResearchStateHash(input) {
+    const payload = {
+        provider: input.provider,
+        capability: input.capability,
+        credentialFingerprint: input.credentialFingerprint,
+        request: sortKeysDeep(input.request),
+    };
+    return crypto.createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+// ---------------------------------------------------------------------------
+// Production state-file implementation
+// ---------------------------------------------------------------------------
+/**
+ * Build a production {@link ResearchStateFile} backed by files under
+ * `~/.scoutline/research/` (via {@link researchStateDir}). One JSON file
+ * per in-flight task, named `<state-hash>.json`.
+ *
+ * - `write()` atomically creates the file with `{ flag: "wx" }`. A
+ *   concurrent invocation that finds it exists throws EEXIST; the caller
+ *   catches that and polls the existing task.
+ * - `read()` catches JSON parse errors, deletes the corrupt file, and
+ *   returns `null`.
+ * - `remove()` deletes the file and ignores ENOENT.
+ */
+export function createProductionResearchStateFile() {
+    function filePath(identityHash) {
+        return path.join(researchStateDir(), `${identityHash}.json`);
+    }
+    return {
+        async read(identityHash) {
+            if (!identityHash)
+                return null;
+            const file = filePath(identityHash);
+            let raw;
+            try {
+                raw = await fs.readFile(file, "utf8");
+            }
+            catch {
+                return null;
+            }
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    await fs.unlink(file).catch(() => { });
+                    return null;
+                }
+                const obj = parsed;
+                const requestId = obj.requestId;
+                const storedHash = obj.identityHash;
+                const createdAt = obj.createdAt;
+                const status = obj.status;
+                if (typeof requestId !== "string" ||
+                    requestId.length === 0 ||
+                    typeof storedHash !== "string" ||
+                    typeof createdAt !== "string" ||
+                    (status !== "pending" && status !== "in_progress")) {
+                    await fs.unlink(file).catch(() => { });
+                    return null;
+                }
+                return { requestId, identityHash: storedHash, createdAt, status };
+            }
+            catch {
+                // Corrupt JSON — delete the file so the next run creates a fresh
+                // task instead of forever reading garbage.
+                await fs.unlink(file).catch(() => { });
+                return null;
+            }
+        },
+        async write(identityHash, state) {
+            const dir = researchStateDir();
+            await fs.mkdir(dir, { recursive: true });
+            const file = filePath(identityHash);
+            const payload = JSON.stringify(state);
+            // `{ flag: "wx" }` atomically creates the file only if it does not
+            // exist. A concurrent invocation that lost the race gets EEXIST;
+            // the caller catches it and polls the existing task instead of
+            // creating a second one.
+            await fs.writeFile(file, payload, { flag: "wx" });
+        },
+        async remove(identityHash) {
+            const file = filePath(identityHash);
+            await fs.unlink(file).catch((err) => {
+                // ENOENT is expected (already removed, or never written). Swallow
+                // it; any other error re-throws.
+                if (err && err.code === "ENOENT")
+                    return;
+                throw err;
+            });
+        },
+    };
+}
+/**
+ * Convenience helper exported for the Adapter and tests: builds an
+ * in-memory {@link ResearchStateFile} that throws EEXIST on a second
+ * write to the same hash, mirroring the production `{ flag: "wx" }`
+ * contract exactly. The adapter's lifecycle must not depend on whether
+ * the state file is disk-backed or memory-backed.
+ */
+export function createInMemoryResearchStateFile() {
+    const store = new Map();
+    return {
+        store,
+        async read(identityHash) {
+            const raw = store.get(identityHash);
+            if (raw === undefined)
+                return null;
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    store.delete(identityHash);
+                    return null;
+                }
+                const obj = parsed;
+                const requestId = obj.requestId;
+                const storedHash = obj.identityHash;
+                const createdAt = obj.createdAt;
+                const status = obj.status;
+                if (typeof requestId !== "string" ||
+                    requestId.length === 0 ||
+                    typeof storedHash !== "string" ||
+                    typeof createdAt !== "string" ||
+                    (status !== "pending" && status !== "in_progress")) {
+                    store.delete(identityHash);
+                    return null;
+                }
+                return { requestId, identityHash: storedHash, createdAt, status };
+            }
+            catch {
+                store.delete(identityHash);
+                return null;
+            }
+        },
+        async write(identityHash, state) {
+            if (store.has(identityHash)) {
+                const err = new Error(`EEXIST: file already exists, write '${identityHash}.json'`);
+                err.code = "EEXIST";
+                throw err;
+            }
+            store.set(identityHash, JSON.stringify(state));
+        },
+        async remove(identityHash) {
+            store.delete(identityHash);
+        },
+    };
+}
+//# sourceMappingURL=research-state.js.map

package/dist/lib/research-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-state.js","sourceRoot":"","sources":["../../src/lib/research-state.ts"],"names":[],"mappings":"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"}

package/dist/providers/minimax/sdk-client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MiniMax SDK client factory (DESIGN.md §12 — P2-04).
+ *
+ * This is the ONLY module that imports `mmx-cli/sdk`. The Adapter and
+ * registry consume {@link createMiniMaxSdk} plus the injectable
+ * {@link MiniMaxSdkConstructor} / {@link MiniMaxSdkPort} types declared
+ * in `providers/types.ts`, so the transitional SDK never leaks past
+ * this boundary.
+ *
+ * The characterized SDK reads its own config directory during
+ * construction (it calls `getConfigDir()`, which honours
+ * `MMX_CONFIG_DIR`). To prevent the SDK from touching the user's real
+ * `~/.mmx` state, the factory temporarily points `MMX_CONFIG_DIR` at a
+ * unique nonexistent path for the synchronous construction call only,
+ * then restores the prior value in `finally`. The temporary directory
+ * is NEVER created on disk.
+ */
+import type { MiniMaxSdkConstructor, MiniMaxSdkPort } from "../types.js";
+/**
+ * Construct a MiniMax SDK port. The optional `constructor` lets tests
+ * inject a fake; production omits it and uses the pinned `mmx-cli/sdk`
+ * implementation.
+ */
+export declare function createMiniMaxSdk(options: {
+    apiKey: string;
+    region: "global" | "cn";
+    baseUrl: string;
+}, constructor?: MiniMaxSdkConstructor): MiniMaxSdkPort;
+//# sourceMappingURL=sdk-client.d.ts.map

package/dist/providers/minimax/sdk-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-client.d.ts","sourceRoot":"","sources":["../../../src/providers/minimax/sdk-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIzE;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EACrE,WAAW,CAAC,EAAE,qBAAqB,GAClC,cAAc,CAoBhB"}

package/dist/providers/minimax/sdk-client.js

@@ -0,0 +1,50 @@
+/**
+ * MiniMax SDK client factory (DESIGN.md §12 — P2-04).
+ *
+ * This is the ONLY module that imports `mmx-cli/sdk`. The Adapter and
+ * registry consume {@link createMiniMaxSdk} plus the injectable
+ * {@link MiniMaxSdkConstructor} / {@link MiniMaxSdkPort} types declared
+ * in `providers/types.ts`, so the transitional SDK never leaks past
+ * this boundary.
+ *
+ * The characterized SDK reads its own config directory during
+ * construction (it calls `getConfigDir()`, which honours
+ * `MMX_CONFIG_DIR`). To prevent the SDK from touching the user's real
+ * `~/.mmx` state, the factory temporarily points `MMX_CONFIG_DIR` at a
+ * unique nonexistent path for the synchronous construction call only,
+ * then restores the prior value in `finally`. The temporary directory
+ * is NEVER created on disk.
+ */
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { MiniMaxSDK } from "mmx-cli/sdk";
+const MMX_CONFIG_DIR = "MMX_CONFIG_DIR";
+/**
+ * Construct a MiniMax SDK port. The optional `constructor` lets tests
+ * inject a fake; production omits it and uses the pinned `mmx-cli/sdk`
+ * implementation.
+ */
+export function createMiniMaxSdk(options, constructor) {
+    const Ctor = constructor ?? MiniMaxSDK;
+    const hadPrev = Object.prototype.hasOwnProperty.call(process.env, MMX_CONFIG_DIR);
+    const prev = process.env[MMX_CONFIG_DIR];
+    // A unique nonexistent path. It is deliberately never created.
+    const temporaryDir = path.join(tmpdir(), `scoutline-minimax-${randomUUID()}`);
+    process.env[MMX_CONFIG_DIR] = temporaryDir;
+    try {
+        // Construction is synchronous and reads MMX_CONFIG_DIR via the
+        // SDK's getConfigDir(). The async search/vision calls happen
+        // after this block, with the original env already restored.
+        return new Ctor(options);
+    }
+    finally {
+        if (hadPrev) {
+            process.env[MMX_CONFIG_DIR] = prev;
+        }
+        else {
+            delete process.env[MMX_CONFIG_DIR];
+        }
+    }
+}
+//# sourceMappingURL=sdk-client.js.map

package/dist/providers/minimax/sdk-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-client.js","sourceRoot":"","sources":["../../../src/providers/minimax/sdk-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAExC;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAqE,EACrE,WAAmC;IAEnC,MAAM,IAAI,GAAG,WAAW,IAAK,UAA+C,CAAC;IAE7E,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAClF,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACzC,+DAA+D;IAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,qBAAqB,UAAU,EAAE,EAAE,CAAC,CAAC;IAC9E,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,YAAY,CAAC;IAC3C,IAAI,CAAC;QACH,+DAA+D;QAC/D,6DAA6D;QAC7D,4DAA4D;QAC5D,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;YAAS,CAAC;QACT,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC;QACrC,CAAC;aAAM,CAAC;YACN,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/providers/zai/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/providers/zai/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,KAAK,EAIV,kBAAkB,EAElB,sBAAsB,EAGvB,MAAM,aAAa,CAAC;AAupBrB;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,CAAC,EAAE,sBAAsB,GAAG,kBAAkB,CAyG7F"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/providers/zai/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,KAAK,EAIV,kBAAkB,EAElB,sBAAsB,EAGvB,MAAM,aAAa,CAAC;AAw0BrB;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,CAAC,EAAE,sBAAsB,GAAG,kBAAkB,CAyG7F"}

package/dist/providers/zai/adapter.js

@@ -24,13 +24,14 @@
  * and location to the Provider. It NEVER sends count.
  */
 import crypto from "node:crypto";
+import { promises as fsPromises } from "node:fs";
 import { ApiError, AuthError, NetworkError, TimeoutError, UnsupportedOptionError, ValidationError, } from "../../lib/errors.js";
 import { getMcpToolName } from "../../lib/mcp-config.js";
 import { ZaiMcpClient, } from "../../lib/mcp-client.js";
 import { buildLegacyRepositoryCacheKey } from "../../lib/cache.js";
 import { applySearchTopic } from "../../lib/search-topic.js";
 import { isZaiConfigured, requireZaiApiKey } from "./credentials.js";
-import { resolveImageSource, resolveVideoSource } from "./media.js";
+import { resolveImageSource, resolveVideoSource, fetchImageSource, fetchVideoSource, } from "./media.js";
 import { createZaiQuotaCapability } from "./quota.js";
 import { createZaiRepositoryCapability } from "./repository.js";
 import { createZaiReaderCapability } from "./reader.js";
@@ -397,40 +398,191 @@ function createZaiVisionCapability(options) {
             // Unsupported operations never reach here: the descriptor-level
             // gate and `supports()` reject first (defence in depth).
             resolveApiKey();
-            const { toolName, args } = buildZaiVisionInvocation(request);
-            // Disable client-owned cache and retry so shared execution is the
-            // single policy owner. Vision enables the Z.AI vision MCP server.
-            const clientOptions = {
-                enableVision: true,
-                noCache: true,
-                disableRetry: true,
-            };
-            const client = clientFactory(clientOptions);
+            const tempPaths = [];
             try {
-                const raw = await invokeZaiVision(client, toolName, args);
-                return normalizeZaiVisionResult(raw);
+                // First attempt: HTTP(S) URLs pass straight through to the
+                // Provider's server-side fetcher.
+                const first = buildZaiVisionInvocation(request, resolveImageSource, resolveVideoSource);
+                try {
+                    return normalizeZaiVisionResult(await invokeZaiVisionOnce(clientFactory, first.toolName, first.args));
+                }
+                catch (error) {
+                    // Automatic URL -> local fallback (Issue E): Z.AI's vision MCP
+                    // refuses base64 data URIs and its server-side URL fetcher is
+                    // unreliable — it rejects some image URLs with code 1210,
+                    // returns empty, or hangs. The MCP surfaces these inconsistently
+                    // (a 1210 reaches the Adapter as a sanitized ApiError 500 with
+                    // the original detail discarded, so it cannot be detected by
+                    // status code or message). Retry by fetching each URL source
+                    // here to a temp file (validated against the same Z.AI media
+                    // limits) and passing that path.
+                    //
+                    // The fallback fires for ANY transport/processing failure on a
+                    // URL source except auth/quota (those are not source-related and
+                    // a local fetch cannot remedy them). Auth (401/403) and
+                    // exhausted-quota failures therefore propagate untouched.
+                    if (isUrlVisionSource(request) && isFallbackEligibleError(error)) {
+                        try {
+                            const fetched = await prefetchVisionUrlSources(request);
+                            for (const local of fetched.values())
+                                tempPaths.push(local);
+                            const resolveImage = makePrefetchResolver(fetched, resolveImageSource);
+                            const resolveVideo = makePrefetchResolver(fetched, resolveVideoSource);
+                            const fallback = buildZaiVisionInvocation(request, resolveImage, resolveVideo);
+                            return normalizeZaiVisionResult(await invokeZaiVisionOnce(clientFactory, fallback.toolName, fallback.args));
+                        }
+                        catch (fallbackError) {
+                            // The local fetch or the retried attempt failed. Surface a
+                            // TERMINAL error (422, not in the shared retry policy's
+                            // retryable set) so the policy does not re-run the whole
+                            // URL attempt and multiply latency without benefit. The
+                            // message names both the original Provider failure and the
+                            // fallback failure so the user knows the fallback was
+                            // attempted and why it could not recover.
+                            throw new ApiError(`Z.AI vision request failed for the URL source and the local-fetch fallback also failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`, 422);
+                        }
+                    }
+                    throw error;
+                }
             }
             finally {
-                await client.close().catch(() => { });
+                await cleanupTempPaths(tempPaths);
             }
         },
     };
     return capability;
 }
+/**
+ * Perform one vision transport attempt. A fresh client is constructed per
+ * attempt (the Adapter never retries internally; shared execution owns the
+ * retry policy) and closed exactly once in `finally`. Close failure never
+ * replaces a successful result nor masks the primary failure.
+ */
+async function invokeZaiVisionOnce(clientFactory, toolName, args) {
+    const clientOptions = {
+        enableVision: true,
+        noCache: true,
+        disableRetry: true,
+    };
+    const client = clientFactory(clientOptions);
+    try {
+        return await invokeZaiVision(client, toolName, args);
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+/**
+ * Whether a `VisionRequest` carries at least one HTTP(S) source. The
+ * URL->local fallback only applies when a Provider-attempted URL is the
+ * likely cause of a client error; local-file sources already resolved
+ * before transport and are not re-attempted with a fetch.
+ */
+function isUrlVisionSource(request) {
+    return visionSourceUrls(request).length > 0;
+}
+/**
+ * Collect the HTTP(S) source strings carried by a `VisionRequest`.
+ * `diff` carries two image sources; `video` carries one video source;
+ * every other operation carries one image source.
+ */
+function visionSourceUrls(request) {
+    const out = [];
+    const pushIfUrl = (s) => {
+        if (typeof s === "string" && (s.startsWith("http://") || s.startsWith("https://"))) {
+            out.push(s);
+        }
+    };
+    switch (request.operation) {
+        case "diff":
+            pushIfUrl(request.expectedSource);
+            pushIfUrl(request.actualSource);
+            break;
+        case "video":
+            pushIfUrl(request.source);
+            break;
+        default:
+            pushIfUrl(request.source);
+    }
+    return out;
+}
+/**
+ * Whether a normalized vision error is eligible for the URL -> local
+ * fallback. The fallback fires for any transport or processing failure
+ * that a local fetch could plausibly remedy: client errors (400/422, e.g.
+ * a 1210 image-format rejection), server errors (5xx), timeouts, and
+ * network errors. Auth failures (401/403) and exhausted-quota failures are
+ * NOT eligible — a local fetch cannot fix a missing credential or a spent
+ * quota, so those propagate to the user unchanged.
+ *
+ * Note: the vision MCP surfaces a code 1210 image-format rejection as a
+ * sanitized `ApiError` 500 with the original detail discarded, so this
+ * check is deliberately type-and-status-based rather than message-based.
+ */
+function isFallbackEligibleError(error) {
+    if (error instanceof ApiError) {
+        return error.statusCode !== 401 && error.statusCode !== 403;
+    }
+    return error instanceof TimeoutError || error instanceof NetworkError;
+}
+/**
+ * Prefetch each HTTP(S) source URL on the request to a validated temp
+ * file path, returning a Map from the original URL to its local path.
+ * Video sources use the video media limits; every other source uses the
+ * image limits. A fetch failure throws the normalized media error and
+ * aborts the fallback (the original client error is then surfaced).
+ */
+async function prefetchVisionUrlSources(request) {
+    const isVideo = request.operation === "video";
+    const fetched = new Map();
+    for (const url of visionSourceUrls(request)) {
+        const local = isVideo ? await fetchVideoSource(url) : await fetchImageSource(url);
+        fetched.set(url, local);
+    }
+    return fetched;
+}
+/**
+ * Build a sync media resolver for the fallback attempt. A source present
+ * in the prefetched `urlToPath` map is substituted with its local temp
+ * path; every other source falls through to the normal passthrough
+ * resolver (`resolveImageSource`/`resolveVideoSource`).
+ */
+function makePrefetchResolver(urlToPath, passthrough) {
+    return (source) => urlToPath.get(source) ?? passthrough(source);
+}
+/**
+ * Unlink every prefetched temp file. Each unlink is best-effort: a
+ * missing file or permission failure never replaces a successful result
+ * nor masks a primary failure.
+ */
+async function cleanupTempPaths(tempPaths) {
+    for (const p of tempPaths) {
+        try {
+            await fsPromises.unlink(p);
+        }
+        catch {
+            // Best-effort cleanup; ignore.
+        }
+    }
+}
 /**
  * Map a discriminated `VisionRequest` to its dedicated Z.AI MCP tool name
- * and arguments, resolving media through the Z.AI media Module. Field
+ * and arguments, resolving media through the supplied resolvers. Field
  * names mirror the characterized transport schema (see `mcp-client.ts`
  * and the live discovery fixtures). Optional fields are omitted when
  * absent so the Provider receives the same request shape Phase 1 sent.
+ *
+ * The image/video resolvers are injected so the first attempt can pass
+ * HTTP(S) URLs straight through (`resolveImageSource`) while a fallback
+ * attempt can substitute a fetched temp-file path (`fetchImageSource`).
  */
-function buildZaiVisionInvocation(request) {
+function buildZaiVisionInvocation(request, resolveImage, resolveVideo) {
     switch (request.operation) {
         case "interpret-image":
             return {
                 toolName: VISION_ANALYZE_TOOL_PUBLIC_NAME,
                 args: {
-                    image_source: resolveImageSource(request.source),
+                    image_source: resolveImage(request.source),
                     prompt: request.instruction,
                 },
             };
@@ -438,14 +590,14 @@ function buildZaiVisionInvocation(request) {
             return {
                 toolName: VISION_UI_TO_ARTIFACT_TOOL_PUBLIC_NAME,
                 args: {
-                    image_source: resolveImageSource(request.source),
+                    image_source: resolveImage(request.source),
                     output_type: request.outputType,
                     prompt: request.instruction,
                 },
             };
         case "extract-text": {
             const args = {
-                image_source: resolveImageSource(request.source),
+                image_source: resolveImage(request.source),
                 prompt: request.instruction,
             };
             if (request.programmingLanguage) {
@@ -455,7 +607,7 @@ function buildZaiVisionInvocation(request) {
         }
         case "diagnose-error": {
             const args = {
-                image_source: resolveImageSource(request.source),
+                image_source: resolveImage(request.source),
                 prompt: request.instruction,
             };
             if (request.context) {
@@ -465,7 +617,7 @@ function buildZaiVisionInvocation(request) {
         }
         case "diagram": {
             const args = {
-                image_source: resolveImageSource(request.source),
+                image_source: resolveImage(request.source),
                 prompt: request.instruction,
             };
             if (request.diagramType) {
@@ -475,7 +627,7 @@ function buildZaiVisionInvocation(request) {
         }
         case "chart": {
             const args = {
-                image_source: resolveImageSource(request.source),
+                image_source: resolveImage(request.source),
                 prompt: request.instruction,
             };
             if (request.focus) {
@@ -487,8 +639,8 @@ function buildZaiVisionInvocation(request) {
             return {
                 toolName: VISION_DIFF_TOOL_PUBLIC_NAME,
                 args: {
-                    expected_image_source: resolveImageSource(request.expectedSource),
-                    actual_image_source: resolveImageSource(request.actualSource),
+                    expected_image_source: resolveImage(request.expectedSource),
+                    actual_image_source: resolveImage(request.actualSource),
                     prompt: request.instruction,
                 },
             };
@@ -496,7 +648,7 @@ function buildZaiVisionInvocation(request) {
             return {
                 toolName: VISION_VIDEO_TOOL_PUBLIC_NAME,
                 args: {
-                    video_source: resolveVideoSource(request.source),
+                    video_source: resolveVideo(request.source),
                     prompt: request.instruction,
                 },
             };