@mengruo/dsh-vision-toolkit 0.0.1 → 0.1.0

package/lib/runtime.js

@@ -149,6 +149,16 @@ export class Semaphore {
             next.resolve();
         }
     }
+    /** Non-blocking acquisition: claim a free slot immediately, else return false. */
+    tryAcquire(permits = 1) {
+        if (!Number.isInteger(permits) || permits < 1 || permits > this.limit)
+            return false;
+        if (this.waiters.length === 0 && this.active + permits <= this.limit) {
+            this.active += permits;
+            return true;
+        }
+        return false;
+    }
 }
 const REGION_PATTERN = /^\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*$/;
 const MAX_TIMEOUT_MS = 600_000;
@@ -301,6 +311,7 @@ export class VisionToolkitRuntime {
     config;
     semaphores = new Map();
     glanceCache = new WeakMap();
+    providerGates = new Map();
     adapter;
     constructor(ctx, config, adapter) {
         this.ctx = ctx;
@@ -317,20 +328,37 @@ export class VisionToolkitRuntime {
     }
     /** Capture the credential and provider identity used by one evidence conversion. */
     async captureEvidenceRuntime() {
-        const env = await this.resolveVisionEnv();
-        const evidenceFingerprint = evidenceRuntimeFingerprint(this.config, createHash('sha256').update(env.VISION_API_KEY).digest('hex'), env.VISION_SSL_VERIFY);
+        // The primary provider's key hash sharpens cache invalidation, but a
+        // missing primary credential must not block evidence conversion when a
+        // later provider in the failover pool is available.
+        let credentialSha256;
+        let sslVerify;
+        try {
+            const env = await this.resolveVisionEnv();
+            credentialSha256 = createHash('sha256').update(env.VISION_API_KEY).digest('hex');
+            sslVerify = env.VISION_SSL_VERIFY;
+        }
+        catch {
+            credentialSha256 = undefined;
+        }
+        const evidenceFingerprint = evidenceRuntimeFingerprint(this.config, credentialSha256, sslVerify);
         return Object.freeze({
             evidenceFingerprint,
-            glance: (request, options) => this.glanceWithEnv(request, options, env),
+            glance: (request, options) => this.glanceWithEnv(request, options),
         });
     }
     timeout(options) {
-        const value = options.timeoutMs ?? this.config.timeoutMs;
+        const value = options.timeoutMs ?? this.operationTimeoutMs();
         if (!Number.isInteger(value) || value < 1000 || value > MAX_TIMEOUT_MS) {
             throw new VisionToolkitError('input', `timeoutMs must be an integer between 1000 and ${MAX_TIMEOUT_MS}`);
         }
         return value;
     }
+    /** Overall operation budget: the slowest enabled provider's timeout, else the global default. */
+    operationTimeoutMs() {
+        const providers = this.config.providers.filter(provider => provider.enabled);
+        return providers.length === 0 ? this.config.timeoutMs : Math.max(...providers.map(provider => provider.timeoutMs));
+    }
     operationError(tool, error, deadline, phase = 'execution') {
         if (deadline.cancelled) {
             return new VisionToolkitError('cancelled', phase === 'queue' ? `${tool}: cancelled while waiting for a concurrency slot` : `${tool}: cancelled`);
@@ -408,29 +436,69 @@ export class VisionToolkitRuntime {
                 this.semaphores.delete(semaphore.key);
         }
     }
-    /** Resolve the configured credential at the remote-operation boundary. */
-    async resolveVisionEnv() {
-        const resolved = isBuiltInFreeVisionProvider(this.config.provider)
-            ? { value: BUILT_IN_FREE_VISION_KEY, source: 'built-in' }
-            : await this.ctx.credentials.resolve(this.config.provider.credential);
-        if (resolved === undefined) {
-            throw new VisionToolkitError('config', `credential ${this.config.provider.credential} is not configured; set it through DSH credentials`);
-        }
-        return this.visionEnv(resolved);
+    /** Highest-priority enabled provider, falling back to the first entry. */
+    get primaryProvider() {
+        return this.config.providers.find(provider => provider.enabled) ?? this.config.providers[0];
     }
-    visionEnv(resolved) {
+    /** Build the upstream environment for one resolved provider. */
+    providerEnv(provider, resolved) {
         const sslVerify = process.env.VISION_SSL_VERIFY?.trim();
         return {
             VISION_API_KEY: resolved.value,
-            VISION_BASE_URL: this.config.provider.baseUrl,
-            VISION_MODEL: this.config.provider.model,
-            VISION_API_PROTOCOL: this.config.provider.protocol === 'anthropic' ? 'anthropic' : 'chat_completions',
-            VISION_ANTHROPIC_THINKING: this.config.provider.anthropicThinking,
+            VISION_BASE_URL: provider.baseUrl,
+            VISION_MODEL: provider.model,
+            VISION_API_PROTOCOL: provider.protocol === 'anthropic' ? 'anthropic' : 'chat_completions',
+            VISION_ANTHROPIC_THINKING: provider.anthropicThinking,
             ...(sslVerify === undefined ? {} : { VISION_SSL_VERIFY: sslVerify }),
-            VISION_USER_AGENT: this.config.provider.userAgent,
+            VISION_USER_AGENT: provider.userAgent,
             LANG: this.config.language,
         };
     }
+    /** Resolve one provider's credential into its environment, or undefined when unavailable. */
+    async resolveProviderEnv(provider) {
+        let resolved;
+        try {
+            resolved = isBuiltInFreeVisionProvider({
+                baseUrl: provider.baseUrl,
+                credential: provider.credential,
+                model: provider.model,
+                protocol: provider.protocol,
+                anthropicThinking: provider.anthropicThinking,
+                userAgent: provider.userAgent,
+            })
+                ? { value: BUILT_IN_FREE_VISION_KEY, source: 'built-in' }
+                : await this.ctx.credentials.resolve(provider.credential);
+        }
+        catch {
+            resolved = undefined;
+        }
+        if (resolved === undefined)
+            return undefined;
+        return { provider, env: this.providerEnv(provider, resolved) };
+    }
+    /** Resolve every enabled provider in priority order, skipping unreadable credentials. */
+    async resolveProviderPool() {
+        const pool = [];
+        for (const provider of this.config.providers) {
+            if (!provider.enabled)
+                continue;
+            const entry = await this.resolveProviderEnv(provider);
+            if (entry === undefined) {
+                this.ctx.logger.warn('dsh-vision-toolkit provider=%s credential=%s unavailable; skipped from the failover pool', provider.name, String(provider.credential));
+                continue;
+            }
+            pool.push(entry);
+        }
+        return pool;
+    }
+    /** Resolve the primary provider's credential at the remote-operation boundary. */
+    async resolveVisionEnv() {
+        const entry = await this.resolveProviderEnv(this.primaryProvider);
+        if (entry === undefined) {
+            throw new VisionToolkitError('config', `credential ${String(this.primaryProvider.credential)} is not configured; set it through DSH credentials`);
+        }
+        return entry.env;
+    }
     pathPolicy(workspace) {
         return createPathPolicy(workspace, this.config.allowedDirs);
     }
@@ -503,7 +571,7 @@ export class VisionToolkitRuntime {
             || probed.width * probed.height > maxPixels) {
             return undefined;
         }
-        return { path: real, bytes: bytes.length, width: probed.width, height: probed.height, format: probed.format };
+        return { path: real, bytes: bytes.length, width: probed.width, height: probed.height, format: probed.format, hasAlpha: probed.hasAlpha };
     }
     cacheEntryOutDigest(entry, prefix) {
         const tail = entry.slice(prefix.length + 1);
@@ -560,7 +628,7 @@ export class VisionToolkitRuntime {
         }
         await Promise.all([...stalePartials, ...remove].map(name => rm(join(root, name), { force: true }).catch(() => { })));
     }
-    async autoCompressImage(image, policy, operation) {
+    async autoCompressImage(image, policy, operation, maxBytes, maxPixels) {
         let bytes;
         try {
             bytes = await readFile(image.path, { signal: operation.signal });
@@ -574,7 +642,7 @@ export class VisionToolkitRuntime {
         const digest = createHash('sha256').update(bytes).digest('hex').slice(0, COMPRESSED_IMAGE_CACHE_KEY_DIGEST_LENGTH);
         const root = await this.compressedImageRoot(policy);
         await this.pruneCompressedCache(root);
-        const prefix = `${COMPRESSED_IMAGE_CACHE_VERSION}-${digest}-b${this.config.maxImageBytes}-p${this.config.maxImagePixels}`;
+        const prefix = `${COMPRESSED_IMAGE_CACHE_VERSION}-${digest}-b${maxBytes}-p${maxPixels}`;
         for (const entry of await readdir(root)) {
             if (!entry.startsWith(`${prefix}-`) || entry.startsWith('.'))
                 continue;
@@ -583,7 +651,7 @@ export class VisionToolkitRuntime {
                 await rm(join(root, entry), { force: true }).catch(() => { });
                 continue;
             }
-            const cached = await this.readCacheCandidate(root, entry, outDigestPrefix, this.config.maxImageBytes, this.config.maxImagePixels, operation);
+            const cached = await this.readCacheCandidate(root, entry, outDigestPrefix, maxBytes, maxPixels, operation);
             if (cached !== undefined) {
                 return { ...cached, originalPath: image.path };
             }
@@ -592,7 +660,7 @@ export class VisionToolkitRuntime {
         const staged = join(root, `.${prefix}-${randomUUID()}.partial`);
         let compressed;
         try {
-            compressed = await this.adapter.compressImage(image.path, staged, this.config.maxImageBytes, this.config.maxImagePixels, { signal: operation.signal });
+            compressed = await this.adapter.compressImage(image.path, staged, maxBytes, maxPixels, { signal: operation.signal });
         }
         catch (error) {
             await rm(staged, { force: true }).catch(() => { });
@@ -603,7 +671,7 @@ export class VisionToolkitRuntime {
         const outDigest = createHash('sha256').update(stagedBytes).digest('hex').slice(0, COMPRESSED_IMAGE_CACHE_KEY_DIGEST_LENGTH);
         const finalName = `${prefix}-${outDigest}-${compressed.width}x${compressed.height}.${extension}`;
         const finalPath = join(root, finalName);
-        const existing = await this.readCacheCandidate(root, finalName, outDigest, this.config.maxImageBytes, this.config.maxImagePixels, operation);
+        const existing = await this.readCacheCandidate(root, finalName, outDigest, maxBytes, maxPixels, operation);
         if (existing !== undefined) {
             await rm(staged, { force: true }).catch(() => { });
             return { ...existing, originalPath: image.path };
@@ -623,9 +691,11 @@ export class VisionToolkitRuntime {
             width: compressed.width,
             height: compressed.height,
             format: compressed.format,
+            hasAlpha: compressed.hasAlpha,
             originalPath: image.path,
         };
     }
+    /** Validate one image against the configured global limits (used by local tools). */
     async validateImage(raw, policy, operation) {
         const image = await resolveInputFile(raw, policy);
         const decoded = await this.adapter.probeImageSize(image.path, { signal: operation.signal });
@@ -639,16 +709,106 @@ export class VisionToolkitRuntime {
             throw new VisionToolkitError('input', `image content is ${decoded.format}, but the filename uses ${extension}`);
         }
         if (image.bytes <= this.config.maxImageBytes && pixels <= this.config.maxImagePixels) {
-            return { ...image, width: decoded.width, height: decoded.height, format: decoded.format, originalPath: image.path };
+            return { ...image, width: decoded.width, height: decoded.height, format: decoded.format, hasAlpha: decoded.hasAlpha, originalPath: image.path };
         }
-        return this.autoCompressImage(image, policy, operation);
+        return this.autoCompressImage(image, policy, operation, this.config.maxImageBytes, this.config.maxImagePixels);
     }
     accountImage(image, operation) {
         operation.metrics.imageCount += 1;
         operation.metrics.imageBytes += image.bytes;
         operation.metrics.imagePixels += image.width * image.height;
     }
-    async glanceCacheKey(request, images, env, signal) {
+    /** Stable gate key for one provider's in-flight request cap. */
+    providerGate(provider) {
+        const key = `${provider.baseUrl}\u0000${provider.model}\u0000${String(provider.credential)}`;
+        let gate = this.providerGates.get(key);
+        if (gate === undefined) {
+            gate = new Semaphore(provider.concurrency);
+            this.providerGates.set(key, gate);
+        }
+        return gate;
+    }
+    /**
+     * Prepare one image for an online vision request against the enabled
+     * provider pool. The raw image is kept when at least one enabled provider
+     * accepts it; otherwise it is compressed once to the first (highest
+     * priority) provider's limits so the priority route can proceed.
+     */
+    async prepareVisionImage(raw, providers, policy, operation) {
+        const image = await resolveInputFile(raw, policy);
+        const decoded = await this.adapter.probeImageSize(image.path, { signal: operation.signal });
+        const pixels = decoded.width * decoded.height;
+        if (!Number.isSafeInteger(pixels) || pixels < 1) {
+            throw new VisionToolkitError('input', `image dimensions are invalid: ${decoded.width}x${decoded.height}`);
+        }
+        const extension = extname(image.path).toLowerCase();
+        const expected = FORMAT_BY_EXTENSION.get(extension);
+        if (expected !== decoded.format) {
+            throw new VisionToolkitError('input', `image content is ${decoded.format}, but the filename uses ${extension}`);
+        }
+        const fits = providers.some(provider => image.bytes <= provider.maxImageBytes && pixels <= provider.maxImagePixels);
+        if (fits) {
+            return { ...image, width: decoded.width, height: decoded.height, format: decoded.format, hasAlpha: decoded.hasAlpha, originalPath: image.path };
+        }
+        const first = providers[0];
+        if (first === undefined) {
+            throw new VisionToolkitError('config', 'no enabled vision provider is available for this image');
+        }
+        return this.autoCompressImage(image, policy, operation, first.maxImageBytes, first.maxImagePixels);
+    }
+    /**
+     * Run one online-vision upstream command across the enabled provider pool in
+     * priority order. A provider is skipped when its size limits or concurrency
+     * are exhausted, retried up to its attempt count, and the next provider
+     * takes over on failure. Throws once every provider has failed.
+     */
+    async runVisionWithFailover(tool, args, images, operation, pool) {
+        if (pool.length === 0) {
+            throw new VisionToolkitError('config', 'no enabled vision provider has a resolvable credential');
+        }
+        let lastError;
+        let attempted = false;
+        for (const { provider, env } of pool) {
+            const fits = images.every(image => image.bytes <= provider.maxImageBytes && image.width * image.height <= provider.maxImagePixels);
+            if (!fits)
+                continue;
+            const gate = this.providerGate(provider);
+            if (!gate.tryAcquire())
+                continue;
+            attempted = true;
+            try {
+                for (let attempt = 1; attempt <= provider.attempts; attempt++) {
+                    const attemptDeadline = createDeadline(operation.signal, provider.timeoutMs);
+                    try {
+                        return await this.runUpstream(tool, args, { signal: attemptDeadline.signal, metrics: operation.metrics }, env);
+                    }
+                    catch (error) {
+                        if (operation.signal.aborted)
+                            throw error;
+                        const classified = error instanceof VisionToolkitError
+                            ? error
+                            : new VisionToolkitError('service', `${tool}: request failed`, { cause: error });
+                        lastError = attemptDeadline.timedOut && classified.code === 'cancelled'
+                            ? new VisionToolkitError('timeout', `${tool}: ${provider.name} request timed out after ${provider.timeoutMs}ms`, { cause: classified })
+                            : classified;
+                    }
+                    finally {
+                        attemptDeadline.cleanup();
+                    }
+                }
+            }
+            finally {
+                gate.release();
+            }
+        }
+        if (!attempted) {
+            throw new VisionToolkitError('capacity', `${tool}: no enabled vision provider accepts the image size or has a free concurrency slot`);
+        }
+        if (lastError instanceof VisionToolkitError)
+            throw lastError;
+        throw new VisionToolkitError('service', `${tool}: all vision providers failed`, { cause: lastError });
+    }
+    async glanceCacheKey(request, images, pool, signal) {
         const imageFingerprints = await Promise.all(images.map(async (image) => {
             let bytes;
             try {
@@ -670,16 +830,20 @@ export class VisionToolkitRuntime {
             query: request.query ?? null,
             ocr: request.ocr === true,
             region: request.region ?? null,
-            provider: {
+            language: this.config.language,
+            providers: pool.map(({ provider, env }) => ({
+                name: provider.name,
                 baseUrl: env.VISION_BASE_URL,
                 model: env.VISION_MODEL,
                 protocol: env.VISION_API_PROTOCOL,
                 anthropicThinking: env.VISION_ANTHROPIC_THINKING,
                 sslVerify: env.VISION_SSL_VERIFY ?? null,
                 userAgent: env.VISION_USER_AGENT,
-                language: env.LANG,
                 credentialSha256: createHash('sha256').update(env.VISION_API_KEY).digest('hex'),
-            },
+                maxImageBytes: provider.maxImageBytes,
+                maxImagePixels: provider.maxImagePixels,
+                attempts: provider.attempts,
+            })),
         });
     }
     async runUpstream(tool, args, operation, env) {
@@ -746,7 +910,7 @@ export class VisionToolkitRuntime {
     async glance(request, options) {
         return this.glanceWithEnv(request, options);
     }
-    async glanceWithEnv(request, options, capturedEnv) {
+    async glanceWithEnv(request, options) {
         return this.runOperation('vision_glance', options, async (operation) => {
             if (request.images.length === 0)
                 throw new VisionToolkitError('input', 'glance requires at least one image');
@@ -759,10 +923,15 @@ export class VisionToolkitRuntime {
             if (request.region !== undefined)
                 parseRegion(request.region);
             const policy = await this.pathPolicy(options.workspace);
+            const pool = await this.resolveProviderPool();
+            if (pool.length === 0) {
+                throw new VisionToolkitError('config', 'no enabled vision provider has a resolvable credential');
+            }
+            const providers = pool.map(entry => entry.provider);
             const images = [];
             const seen = new Set();
             for (const raw of request.images) {
-                const image = await this.validateImage(raw, policy, operation);
+                const image = await this.prepareVisionImage(raw, providers, policy, operation);
                 if (seen.has(image.path)) {
                     operation.metrics.cacheHits += 1;
                     continue;
@@ -771,10 +940,9 @@ export class VisionToolkitRuntime {
                 this.accountImage(image, operation);
                 images.push(image);
             }
-            const env = capturedEnv ?? await this.resolveVisionEnv();
             const cacheKey = options.sessionScope === undefined
                 ? undefined
-                : await this.glanceCacheKey(request, images, env, operation.signal);
+                : await this.glanceCacheKey(request, images, pool, operation.signal);
             if (options.sessionScope !== undefined && cacheKey !== undefined) {
                 const cached = this.glanceCache.get(options.sessionScope);
                 if (cached?.key === cacheKey) {
@@ -782,12 +950,12 @@ export class VisionToolkitRuntime {
                     return cached.result;
                 }
             }
-            const result = await this.runUpstream('glance', [
+            const result = await this.runVisionWithFailover('glance', [
                 ...images.map(image => image.path),
                 ...(request.region !== undefined ? ['--region', request.region] : []),
                 ...(request.ocr === true ? ['--ocr'] : []),
                 ...(request.query !== undefined ? ['-q', request.query] : []),
-            ], operation, env);
+            ], images, operation, pool);
             const answer = result.stdout.trim();
             if (answer.length === 0)
                 throw new VisionToolkitError('output', 'glance: vision API returned an empty description');
@@ -823,14 +991,17 @@ export class VisionToolkitRuntime {
         if (request.region !== undefined)
             parseRegion(request.region);
         const policy = await this.pathPolicy(options.workspace);
-        const image = await this.validateImage(request.image, policy, operation);
+        const pool = await this.resolveProviderPool();
+        if (pool.length === 0) {
+            throw new VisionToolkitError('config', 'no enabled vision provider has a resolvable credential');
+        }
+        const image = await this.prepareVisionImage(request.image, pool.map(entry => entry.provider), policy, operation);
         this.accountImage(image, operation);
-        const env = await this.resolveVisionEnv();
-        const result = await this.runUpstream(tool, [
+        const result = await this.runVisionWithFailover(tool, [
             image.path,
             request.target,
             ...(request.region !== undefined ? ['--region', request.region] : []),
-        ], operation, env);
+        ], [image], operation, pool);
         const elements = parseLocationOutput(result.stdout);
         this.validateLocations(elements, image.width, image.height);
         return { image, elements };
@@ -1142,7 +1313,13 @@ export class VisionToolkitRuntime {
                 throw new VisionToolkitError('input', 'long_screenshot_ocr.prompt must not be empty when provided');
             }
             const policy = await this.pathPolicy(options.workspace);
-            const image = await this.validateImage(request.image, policy, operation);
+            const pool = splitOnly ? [] : await this.resolveProviderPool();
+            if (!splitOnly && pool.length === 0) {
+                throw new VisionToolkitError('config', 'no enabled vision provider has a resolvable credential');
+            }
+            const image = splitOnly
+                ? await this.validateImage(request.image, policy, operation)
+                : await this.prepareVisionImage(request.image, pool.map(entry => entry.provider), policy, operation);
             this.accountImage(image, operation);
             const stem = basename(image.originalPath, extname(image.originalPath));
             const finalDirectory = resolveOutputDirectory(request.runName, policy, `${stem}.long-ocr`);
@@ -1158,7 +1335,7 @@ export class VisionToolkitRuntime {
                 const finalOutput = join(finalDirectory, basename(stagedOutput));
                 const stagedChunks = join(stagedDirectory, 'chunks');
                 const stagedManifest = join(stagedChunks, 'manifest.json');
-                const result = await this.runUpstream('long_screenshot_ocr', [
+                const ocrArgs = [
                     image.path,
                     '--mode',
                     mode,
@@ -1177,7 +1354,10 @@ export class VisionToolkitRuntime {
                     String(chunkTimeoutSeconds),
                     ...(splitOnly ? ['--split-only'] : []),
                     ...(request.resume === true ? ['--resume'] : []),
-                ], operation, splitOnly ? undefined : await this.resolveVisionEnv());
+                ];
+                const result = splitOnly
+                    ? await this.runUpstream('long_screenshot_ocr', ocrArgs, operation)
+                    : await this.runVisionWithFailover('long_screenshot_ocr', ocrArgs, [image], operation, pool);
                 const reported = result.stdout.trim();
                 const expectedReported = splitOnly ? stagedManifest : stagedOutput;
                 if (reported !== expectedReported) {
@@ -1509,20 +1689,8 @@ export class VisionToolkitRuntime {
             }
         });
     }
-    async writableDirectoryCheck(path, label) {
-        const probe = join(path, `.vision-toolkit-health-${randomUUID()}`);
-        try {
-            await writeFile(probe, 'ok\n', { encoding: 'utf8', flag: 'wx' });
-            await rm(probe, { force: true });
-            return { status: 'ok', detail: `${label} is writable: ${path}` };
-        }
-        catch {
-            await rm(probe, { force: true }).catch(() => { });
-            return { status: 'error', detail: `${label} is not writable: ${path}` };
-        }
-    }
-    /** Health: inspect local readiness, optionally probe `/models`, and explicitly test one real multimodal request. */
-    async health(testConnection, options, testModel = false) {
+    /** Health: inspect local readiness, and optionally probe one provider's `/models` plus one real multimodal request. */
+    async health(testConnection, options, testModel = false, provider) {
         return this.runOperation('vision_toolkit_health', options, async (operation) => {
             const info = this.upstreamVersion;
             const python = { status: 'ok', detail: `${info.pythonVersion} via ${info.python}` };
@@ -1544,117 +1712,104 @@ export class VisionToolkitRuntime {
                     throw new VisionToolkitError('cancelled', 'vision_toolkit_health: cancelled');
                 chrome = { status: 'error', detail: 'Chrome availability probe failed' };
             }
-            let resolvedCredential;
-            let credential;
-            try {
-                resolvedCredential = isBuiltInFreeVisionProvider(this.config.provider)
-                    ? { value: BUILT_IN_FREE_VISION_KEY, source: 'built-in' }
-                    : await this.ctx.credentials.resolve(this.config.provider.credential);
-                credential = resolvedCredential === undefined
-                    ? { status: 'error', detail: `credential ${this.config.provider.credential} is not configured` }
-                    : { status: 'ok', detail: `credential ${this.config.provider.credential} is resolvable` };
-            }
-            catch {
-                credential = { status: 'error', detail: `credential ${this.config.provider.credential} could not be resolved` };
-            }
-            let artifactDirectory;
-            try {
-                // allowedDirs are session input roots; they do not affect output readiness.
-                const policy = await createPathPolicy(options.workspace, []);
-                artifactDirectory = await this.writableDirectoryCheck(policy.outputDir, 'Artifact directory');
-            }
-            catch {
-                artifactDirectory = { status: 'error', detail: 'Artifact directory could not be prepared' };
-            }
-            const tempDirectory = await this.writableDirectoryCheck(info.runtimeHome, 'Runtime temp directory');
             let service = {
                 status: 'not_tested',
-                detail: 'Connection was not tested; pass testConnection=true to query the configured /models endpoint',
+                detail: 'Connection was not tested; use the per-provider API test',
             };
             let model = {
                 status: 'not_tested',
-                detail: 'Vision model was not tested; run an explicit model test to send the bundled diagnostic image',
+                detail: 'Vision model was not tested; use the per-provider model test',
             };
-            if (testConnection) {
-                if (resolvedCredential === undefined) {
-                    service = { status: 'error', detail: 'Connection test skipped because the configured credential is unavailable' };
-                }
-                else {
-                    operation.metrics.usedVisionService = true;
-                    const endpoint = `${this.config.provider.baseUrl}/models`;
-                    try {
-                        const started = Date.now();
-                        const headers = {
-                            Accept: 'application/json',
-                            'User-Agent': this.config.provider.userAgent,
-                        };
-                        if (this.config.provider.protocol === 'anthropic') {
-                            headers['x-api-key'] = resolvedCredential.value;
-                            headers['anthropic-version'] = '2023-06-01';
-                        }
-                        else {
-                            headers.Authorization = `Bearer ${resolvedCredential.value}`;
-                        }
-                        const response = await fetch(endpoint, {
-                            method: 'GET',
-                            headers,
-                            signal: operation.signal,
-                        });
-                        operation.metrics.upstreamMs += Date.now() - started;
-                        await response.body?.cancel().catch(() => { });
-                        if (response.ok) {
-                            service = { status: 'ok', detail: `Service responded at ${endpoint} (HTTP ${response.status})` };
-                        }
-                        else if (response.status === 401) {
-                            service = { status: 'error', detail: `Service rejected the configured credential (HTTP ${response.status})` };
-                        }
-                        else if (response.status === 403) {
-                            // Some providers (e.g. Groq preview/account restrictions) block GET /models
-                            // while real multimodal requests still work. Treat 403 as a warning so the
-                            // explicit vision-model test, not the model list endpoint, decides access.
-                            service = { status: 'warning', detail: `Service is reachable but restricted GET /models (HTTP 403); the credential may still be valid for real vision requests` };
-                        }
-                        else if (response.status === 404 || response.status === 405) {
-                            service = { status: 'warning', detail: `Service is reachable but does not expose GET /models (HTTP ${response.status})` };
-                        }
-                        else if (response.status === 429) {
-                            service = { status: 'warning', detail: 'Service is reachable but rate-limited the connection test (HTTP 429)' };
-                        }
-                        else {
-                            service = { status: 'error', detail: `Service connection test failed with HTTP ${response.status}` };
-                        }
+            const target = provider ?? (testConnection || testModel ? this.primaryProvider : undefined);
+            if (target !== undefined && (testConnection || testModel)) {
+                const entry = await this.resolveProviderEnv(target);
+                if (entry === undefined) {
+                    if (testConnection) {
+                        service = { status: 'error', detail: `Connection test skipped because credential ${String(target.credential)} is unavailable` };
                     }
-                    catch {
-                        if (operation.signal.aborted)
-                            throw new VisionToolkitError('cancelled', 'vision_toolkit_health: connection test cancelled');
-                        service = { status: 'error', detail: `Service could not be reached at ${endpoint}` };
+                    if (testModel) {
+                        model = { status: 'error', detail: `Vision model test skipped because credential ${String(target.credential)} is unavailable` };
                     }
                 }
-            }
-            if (testModel) {
-                if (resolvedCredential === undefined) {
-                    model = { status: 'error', detail: 'Vision model test skipped because the configured credential is unavailable' };
-                }
                 else {
-                    try {
-                        const result = await this.runUpstream('glance', [VISION_MODEL_TEST_IMAGE, '-q', VISION_MODEL_TEST_PROMPT], operation, this.visionEnv(resolvedCredential));
-                        if (result.stdout.trim().length === 0) {
-                            throw new VisionToolkitError('output', 'glance: vision API returned an empty description');
+                    if (testConnection) {
+                        operation.metrics.usedVisionService = true;
+                        const endpoint = `${target.baseUrl}/models`;
+                        try {
+                            const started = Date.now();
+                            const headers = {
+                                Accept: 'application/json',
+                                'User-Agent': target.userAgent,
+                            };
+                            if (target.protocol === 'anthropic') {
+                                headers['x-api-key'] = entry.env.VISION_API_KEY;
+                                headers['anthropic-version'] = '2023-06-01';
+                            }
+                            else {
+                                headers.Authorization = `Bearer ${entry.env.VISION_API_KEY}`;
+                            }
+                            const response = await fetch(endpoint, {
+                                method: 'GET',
+                                headers,
+                                signal: operation.signal,
+                            });
+                            operation.metrics.upstreamMs += Date.now() - started;
+                            await response.body?.cancel().catch(() => { });
+                            if (response.ok) {
+                                service = { status: 'ok', detail: `Service responded at ${endpoint} (HTTP ${response.status})` };
+                            }
+                            else if (response.status === 401) {
+                                service = { status: 'error', detail: `Service rejected the configured credential (HTTP ${response.status})` };
+                            }
+                            else if (response.status === 403) {
+                                // Some providers (e.g. Groq preview/account restrictions) block GET /models
+                                // while real multimodal requests still work. Treat 403 as a warning so the
+                                // explicit vision-model test, not the model list endpoint, decides access.
+                                service = { status: 'warning', detail: `Service is reachable but restricted GET /models (HTTP 403); the credential may still be valid for real vision requests` };
+                            }
+                            else if (response.status === 404 || response.status === 405) {
+                                service = { status: 'warning', detail: `Service is reachable but does not expose GET /models (HTTP ${response.status})` };
+                            }
+                            else if (response.status === 429) {
+                                service = { status: 'warning', detail: 'Service is reachable but rate-limited the connection test (HTTP 429)' };
+                            }
+                            else {
+                                service = { status: 'error', detail: `Service connection test failed with HTTP ${response.status}` };
+                            }
+                        }
+                        catch {
+                            if (operation.signal.aborted)
+                                throw new VisionToolkitError('cancelled', 'vision_toolkit_health: connection test cancelled');
+                            service = { status: 'error', detail: `Service could not be reached at ${endpoint}` };
                         }
-                        model = {
-                            status: 'ok',
-                            detail: `Vision model ${this.config.provider.model} completed a multimodal request`,
-                        };
                     }
-                    catch (error) {
-                        if (operation.signal.aborted)
-                            throw error;
-                        const detail = error instanceof Error ? error.message : String(error);
-                        model = { status: 'error', detail: `Vision model test failed: ${detail.slice(0, 600)}` };
+                    if (testModel) {
+                        try {
+                            const attemptDeadline = createDeadline(operation.signal, target.timeoutMs);
+                            try {
+                                const result = await this.runUpstream('glance', [VISION_MODEL_TEST_IMAGE, '-q', VISION_MODEL_TEST_PROMPT], { signal: attemptDeadline.signal, metrics: operation.metrics }, entry.env);
+                                if (result.stdout.trim().length === 0) {
+                                    throw new VisionToolkitError('output', 'glance: vision API returned an empty description');
+                                }
+                                model = {
+                                    status: 'ok',
+                                    detail: `Vision model ${target.model} completed a multimodal request`,
+                                };
+                            }
+                            finally {
+                                attemptDeadline.cleanup();
+                            }
+                        }
+                        catch (error) {
+                            if (operation.signal.aborted)
+                                throw error;
+                            const detail = error instanceof Error ? error.message : String(error);
+                            model = { status: 'error', detail: `Vision model test failed: ${detail.slice(0, 600)}` };
+                        }
                     }
                 }
             }
-            const checks = { python, dependencies, chrome, credential, artifactDirectory, tempDirectory, service, model };
+            const checks = { python, dependencies, chrome, service, model };
             const healthy = Object.values(checks).every(check => check.status !== 'error');
             return {
                 pluginVersion: PLUGIN_VERSION,
@@ -1663,6 +1818,7 @@ export class VisionToolkitRuntime {
                 healthy,
                 connectionTested: testConnection,
                 modelTested: testModel,
+                ...(provider === undefined ? {} : { providerName: provider.name }),
             };
         });
     }