@mengruo/dsh-vision-toolkit 0.1.3 → 0.1.5

package/src/runtime-manager.ts

@@ -7,6 +7,7 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import { resolveConfig, type ResolvedVisionToolkitConfig, type VisionToolkitConfig } from './config.ts'
+import { preflightSharedStorageBase } from './paths.ts'
 import { VisionToolkitRuntime } from './runtime.ts'
 import { UpstreamAdapter, type UpstreamVersionInfo } from './upstream.ts'
 
@@ -26,16 +27,30 @@ export interface RuntimeManagerStatus {
   lastError?: string
 }
 
+/** Storage selection paired to the active or validated startup generation. */
+export interface RuntimeStorageGeneration {
+  generation: number
+  storageDir?: string
+}
+
 /** Test seam for preparing one generation. */
 export type RuntimeGenerationFactory = (
   ctx: Context,
   config: ResolvedVisionToolkitConfig,
+  readableStorageDirs: readonly string[],
 ) => Promise<VisionToolkitRuntime>
 
-async function defaultFactory(ctx: Context, config: ResolvedVisionToolkitConfig): Promise<VisionToolkitRuntime> {
+/** Async commit prerequisite run after preparation and before a generation becomes active. */
+export type RuntimeGenerationBeforePublish = (candidate: PreparedRuntimeGeneration) => Promise<void>
+
+async function defaultFactory(
+  ctx: Context,
+  config: ResolvedVisionToolkitConfig,
+  readableStorageDirs: readonly string[],
+): Promise<VisionToolkitRuntime> {
   const adapter = new UpstreamAdapter(ctx, config)
   await adapter.prepare()
-  return new VisionToolkitRuntime(ctx, config, adapter)
+  return new VisionToolkitRuntime(ctx, config, adapter, readableStorageDirs)
 }
 
 function fingerprint(config: ResolvedVisionToolkitConfig): string {
@@ -57,6 +72,8 @@ export class VisionToolkitRuntimeManager {
   private generation = 0
   private reconfigureTicket = 0
   private lastError: string | undefined
+  private validatedStartupStorageDir: string | null | undefined
+  private readonly readableStorageDirs = new Set<string>()
 
   constructor(
     private readonly ctx: Context,
@@ -69,22 +86,69 @@ export class VisionToolkitRuntimeManager {
     return this.active.runtime
   }
 
+  /** Configuration belonging to the currently serving runtime generation. */
+  currentConfig(): ResolvedVisionToolkitConfig {
+    if (this.active === undefined) throw new Error('dsh-vision-toolkit runtime is not ready')
+    return this.active.config
+  }
+
   /** Whether at least one generation is available. */
   get ready(): boolean {
     return this.active !== undefined
   }
 
-  /** Resolve and fully prepare a candidate without changing the active runtime. */
-  async prepareCandidate(raw: VisionToolkitConfig): Promise<PreparedRuntimeGeneration> {
-    const config = resolveConfig(raw)
+  /** Storage config safe for paste writes even when initial runtime preparation failed. */
+  storageGeneration(): RuntimeStorageGeneration {
+    if (this.active !== undefined) {
+      return {
+        generation: this.generation,
+        ...(this.active.config.storageDir === undefined ? {} : { storageDir: this.active.config.storageDir }),
+      }
+    }
+    if (this.validatedStartupStorageDir === undefined) {
+      throw new Error('dsh-vision-toolkit storage configuration is not ready')
+    }
+    return {
+      generation: this.generation,
+      ...(this.validatedStartupStorageDir === null ? {} : { storageDir: this.validatedStartupStorageDir }),
+    }
+  }
+
+  /** Validated storage for best-effort consumers; undefined when startup preflight failed. */
+  validatedStorageDirectory(): string | undefined {
+    if (this.active !== undefined) return this.active.config.storageDir
+    return this.validatedStartupStorageDir ?? undefined
+  }
+
+  private async prepareResolvedCandidate(config: ResolvedVisionToolkitConfig): Promise<PreparedRuntimeGeneration> {
     const resolvedFingerprint = fingerprint(config)
     if (this.active?.fingerprint === resolvedFingerprint) {
       return { ...this.active, config }
     }
-    const runtime = await this.factory(this.ctx, config)
+    const runtime = await this.factory(
+      this.ctx,
+      config,
+      [...new Set([...this.readableStorageDirs, ...config.storageHistory])]
+        .filter(storageDir => storageDir !== config.storageDir),
+    )
     return { config, fingerprint: resolvedFingerprint, runtime }
   }
 
+  private rememberStorageDirectory(storageDir: string | undefined): void {
+    if (storageDir !== undefined) this.readableStorageDirs.add(storageDir)
+  }
+
+  private rememberStorageDirectories(storageDirs: readonly string[]): void {
+    for (const storageDir of storageDirs) this.rememberStorageDirectory(storageDir)
+  }
+
+  /** Resolve and fully prepare a candidate without changing the active runtime. */
+  async prepareCandidate(raw: VisionToolkitConfig): Promise<PreparedRuntimeGeneration> {
+    const config = resolveConfig(raw)
+    if (config.storageDir !== undefined) await preflightSharedStorageBase(config.storageDir)
+    return this.prepareResolvedCandidate(config)
+  }
+
   /**
    * Publish one already-prepared generation atomically.
    * @param candidate - generation returned by {@link prepareCandidate}.
@@ -97,6 +161,8 @@ export class VisionToolkitRuntimeManager {
     }
     this.reconfigureTicket += 1
     this.active = candidate
+    this.rememberStorageDirectories(candidate.config.storageHistory)
+    this.rememberStorageDirectory(candidate.config.storageDir)
     this.generation += 1
     this.lastError = undefined
     this.ctx.logger.info(
@@ -108,10 +174,21 @@ export class VisionToolkitRuntimeManager {
     )
   }
 
-  /** Prepare and publish the initial or explicitly validated generation. */
-  async initialize(raw: VisionToolkitConfig): Promise<void> {
+  /**
+   * Prepare and publish the initial or explicitly validated generation.
+   * @param raw - untrusted Settings generation to resolve and prepare.
+   * @param beforePublish - optional durable prerequisite run after preparation.
+   */
+  async initialize(raw: VisionToolkitConfig, beforePublish?: RuntimeGenerationBeforePublish): Promise<void> {
     try {
-      this.activateCandidate(await this.prepareCandidate(raw))
+      const config = resolveConfig(raw)
+      if (config.storageDir !== undefined) await preflightSharedStorageBase(config.storageDir)
+      this.validatedStartupStorageDir = config.storageDir ?? null
+      this.rememberStorageDirectories(config.storageHistory)
+      this.rememberStorageDirectory(config.storageDir)
+      const candidate = await this.prepareResolvedCandidate(config)
+      await beforePublish?.(candidate)
+      this.activateCandidate(candidate)
     } catch (error) {
       this.lastError = messageOf(error)
       throw error
@@ -121,13 +198,17 @@ export class VisionToolkitRuntimeManager {
   /**
    * Apply an externally committed Settings generation. Concurrent edits are
    * last-write-wins; a slower obsolete prepare can never overwrite a newer one.
+   * @param raw - externally committed Settings generation.
+   * @param beforePublish - optional durable prerequisite run after preparation.
    * @returns whether this call published a new active generation.
    */
-  async reconfigure(raw: VisionToolkitConfig): Promise<boolean> {
+  async reconfigure(raw: VisionToolkitConfig, beforePublish?: RuntimeGenerationBeforePublish): Promise<boolean> {
     const ticket = ++this.reconfigureTicket
     let candidate: PreparedRuntimeGeneration
     try {
       candidate = await this.prepareCandidate(raw)
+      if (ticket !== this.reconfigureTicket) return false
+      await beforePublish?.(candidate)
     } catch (error) {
       if (ticket === this.reconfigureTicket) this.lastError = messageOf(error)
       throw error
@@ -135,6 +216,8 @@ export class VisionToolkitRuntimeManager {
     if (ticket !== this.reconfigureTicket) return false
     const changed = this.active?.fingerprint !== candidate.fingerprint
     this.active = candidate
+    this.rememberStorageDirectories(candidate.config.storageHistory)
+    this.rememberStorageDirectory(candidate.config.storageDir)
     if (changed) {
       this.generation += 1
       this.ctx.logger.info(

package/src/runtime.ts

@@ -18,6 +18,7 @@ import { isBuiltInFreeVisionProvider, type ResolvedProvider, type ResolvedVision
 import { BUILT_IN_FREE_VISION_KEY } from './defaults.ts'
 import { evidenceRuntimeFingerprint } from './evidence-cache.ts'
 import { VisionToolkitError, type VisionToolkitErrorCode } from './errors.ts'
+import { ObjectStorageClient, splitObjectStorageCredential, type ObjectStorageSettings } from './object-storage.ts'
 import {
   assertDistinctOutput,
   commitStagedDirectory,
@@ -475,6 +476,9 @@ export interface VisionToolkitHealthResult {
     python: HealthCheck
     dependencies: HealthCheck
     chrome: HealthCheck
+    credential: HealthCheck
+    artifactDirectory: HealthCheck
+    tempDirectory: HealthCheck
     service: HealthCheck
     model: HealthCheck
   }
@@ -537,8 +541,26 @@ const FORMAT_BY_EXTENSION = new Map([
 ])
 const HEX_COLOR_PATTERN = /^#[0-9A-F]{6}$/
 
-/** Error codes a provider retries within its attempt budget (429 is handled separately). */
-const RETRYABLE_CODES: ReadonlySet<VisionToolkitErrorCode> = new Set(['service', 'timeout'])
+/** MIME type for one analyzed image format, used when uploading to object storage. */
+function imageMimeType(format: string): string {
+  switch (format) {
+    case 'png': return 'image/png'
+    case 'jpeg': return 'image/jpeg'
+    case 'gif': return 'image/gif'
+    case 'webp': return 'image/webp'
+    default: return 'application/octet-stream'
+  }
+}
+
+/**
+ * Error codes a provider retries against the SAME provider within its
+ * `attempts` budget. Only transient failures are worth re-requesting: a
+ * timeout may clear on the next attempt and a 5xx / network drop is usually
+ * ephemeral. Deterministic failures (auth, quota, rate_limit, invalid_request,
+ * region, tos) must fail over to the next provider immediately instead of
+ * re-requesting a backend that cannot succeed with the same input.
+ */
+const RETRYABLE_CODES: ReadonlySet<VisionToolkitErrorCode> = new Set(['timeout', 'server', 'network'])
 
 /** Resolve as soon as `signal` aborts (or immediately when already aborted). */
 function untilAbort(signal: AbortSignal): Promise<void> {
@@ -771,6 +793,7 @@ export class VisionToolkitRuntime {
     private readonly ctx: Context,
     private readonly config: ResolvedVisionToolkitConfig,
     adapter?: UpstreamAdapter,
+    private readonly readableStorageDirs: readonly string[] = [],
   ) {
     this.adapter = adapter ?? new UpstreamAdapter(ctx, config)
   }
@@ -785,6 +808,11 @@ export class VisionToolkitRuntime {
     return this.config.sessionMaxConcurrency
   }
 
+  /** Shared storage root belonging to this immutable runtime generation. */
+  get storageDirectory(): string | undefined {
+    return this.config.storageDir
+  }
+
   /** Stable identity for persisted image descriptions produced by this runtime. */
   get evidenceFingerprint(): string {
     return evidenceRuntimeFingerprint(this.config, undefined, process.env.VISION_SSL_VERIFY?.trim())
@@ -952,6 +980,7 @@ export class VisionToolkitRuntime {
       VISION_API_PROTOCOL: provider.protocol === 'anthropic' ? 'anthropic' : 'chat_completions',
       VISION_ANTHROPIC_THINKING: provider.anthropicThinking,
       ...(sslVerify === undefined ? {} : { VISION_SSL_VERIFY: sslVerify }),
+      ...(provider.stream ? { VISION_STREAM: '1' } : {}),
       VISION_USER_AGENT: provider.userAgent,
       LANG: this.config.language,
     }
@@ -968,6 +997,8 @@ export class VisionToolkitRuntime {
         protocol: provider.protocol,
         anthropicThinking: provider.anthropicThinking,
         userAgent: provider.userAgent,
+        stream: provider.stream,
+        uploadViaUrl: provider.uploadViaUrl,
       })
         ? { value: BUILT_IN_FREE_VISION_KEY, source: 'built-in' }
         : await this.ctx.credentials.resolve(provider.credential)
@@ -1010,13 +1041,13 @@ export class VisionToolkitRuntime {
   }
 
   private pathPolicy(workspace: string): Promise<PathPolicy> {
-    return createPathPolicy(workspace, this.config.allowedDirs)
+    return createPathPolicy(workspace, this.config.allowedDirs, this.config.storageDir, this.readableStorageDirs)
   }
 
   private async compressedImageRoot(policy: PathPolicy): Promise<string> {
-    const root = join(policy.workspace, '.dsh-vision-toolkit', 'tmp', 'compressed-images')
-    let current = policy.workspace
-    for (const segment of ['.dsh-vision-toolkit', 'tmp', 'compressed-images']) {
+    const root = join(policy.storageRoot, 'tmp', 'compressed-images')
+    let current = policy.storageRoot
+    for (const segment of ['tmp', 'compressed-images']) {
       current = join(current, segment)
       try {
         await mkdir(current, { mode: 0o700 })
@@ -1027,13 +1058,13 @@ export class VisionToolkitRuntime {
       if (info.isSymbolicLink() || !info.isDirectory()) {
         throw new VisionToolkitError('path', `compressed-image cache path is not a real directory: ${current}`)
       }
-      if (!isWithin(policy.workspace, current)) {
-        throw new VisionToolkitError('path', `compressed-image cache path escaped the workspace: ${current}`)
+      if (!isWithin(policy.storageRoot, current)) {
+        throw new VisionToolkitError('path', `compressed-image cache path escaped plugin storage: ${current}`)
       }
     }
     const canonical = await realpath(root)
-    if (!isWithin(policy.workspace, canonical)) {
-      throw new VisionToolkitError('path', 'compressed-image cache resolved outside the workspace')
+    if (!isWithin(policy.storageRoot, canonical)) {
+      throw new VisionToolkitError('path', 'compressed-image cache resolved outside plugin storage')
     }
     return canonical
   }
@@ -1237,6 +1268,84 @@ export class VisionToolkitRuntime {
     operation.metrics.imagePixels += image.width * image.height
   }
 
+  /** Resolve the configured object storage into a usable client, or undefined. */
+  private async resolveObjectStorageClient(): Promise<ObjectStorageClient | undefined> {
+    const objectStorage = this.config.objectStorage
+    if (objectStorage.credential === undefined || objectStorage.endpoint.length === 0 || objectStorage.bucket.length === 0) {
+      return undefined
+    }
+    let resolved: ResolvedCredential | undefined
+    try {
+      resolved = await this.ctx.credentials.resolve(objectStorage.credential)
+    } catch {
+      resolved = undefined
+    }
+    if (resolved === undefined) return undefined
+    let accessKeyId: string
+    let secretAccessKey: string
+    try {
+      const split = splitObjectStorageCredential(resolved.value)
+      accessKeyId = split.accessKeyId
+      secretAccessKey = split.secretAccessKey
+    } catch (error) {
+      throw new VisionToolkitError('config', 'object storage credential is malformed', { cause: error })
+    }
+    const settings: ObjectStorageSettings = {
+      endpoint: objectStorage.endpoint,
+      bucket: objectStorage.bucket,
+      accessKeyId,
+      secretAccessKey,
+      ...(objectStorage.publicBase === undefined ? {} : { publicBase: objectStorage.publicBase }),
+    }
+    return new ObjectStorageClient(settings)
+  }
+
+  /**
+   * Upload the prepared images to object storage and return their URLs plus a
+   * cleanup callback, when the primary provider opts into URL transfer and
+   * object storage is configured. Returns undefined otherwise (base64 path).
+   */
+  private async maybeTransferImages(
+    pool: readonly ResolvedProviderEnv[],
+    images: readonly ImageInfo[],
+    operation: OperationContext,
+  ): Promise<{ urls: string[]; cleanup: () => Promise<void> } | undefined> {
+    const primary = pool[0]
+    if (primary === undefined || primary.provider.uploadViaUrl !== true) return undefined
+    const client = await this.resolveObjectStorageClient()
+    if (client === undefined) {
+      throw new VisionToolkitError('config', 'uploadViaUrl is enabled but object storage is not configured')
+    }
+    const keys: string[] = []
+    const urls: string[] = []
+    try {
+      for (const image of images) {
+        if (operation.signal.aborted) throw new VisionToolkitError('cancelled', 'vision image upload cancelled')
+        const uploaded = await client.uploadImage(image.path, imageMimeType(image.format))
+        keys.push(uploaded.key)
+        urls.push(uploaded.url)
+      }
+    } catch (error) {
+      await Promise.allSettled(keys.map(key => client.deleteObject(key)))
+      throw error
+    }
+    return {
+      urls,
+      cleanup: async () => {
+        await Promise.allSettled(keys.map(key => client.deleteObject(key)))
+      },
+    }
+  }
+
+  /** Settings "test storage" probe: upload → head → delete a tiny marker object. */
+  async testObjectStorage(): Promise<{ detail: string }> {
+    const client = await this.resolveObjectStorageClient()
+    if (client === undefined) {
+      throw new VisionToolkitError('config', 'object storage is not configured (endpoint, bucket, and credential are required)')
+    }
+    return client.test()
+  }
+
   /** Stable gate key for one provider's in-flight request cap. */
   private providerGate(provider: ResolvedProvider): Semaphore {
     const key = `${provider.baseUrl}\u0000${provider.model}\u0000${String(provider.credential)}`
@@ -1383,6 +1492,22 @@ export class VisionToolkitRuntime {
     return Math.max(0, Math.min(t2Remaining, globalRemaining))
   }
 
+  /**
+   * Advance to the next provider after one provider reached a terminal
+   * failure. This is what makes failover work for FAST failures too: the
+   * hedge timer only launches the next provider when the current one is SLOW
+   * (crosses t1), so a quick auth/5xx/network failure must explicitly launch
+   * the successor. Never advances when a higher-priority provider superseded
+   * this task, when the whole operation was cancelled, or when the global
+   * deadline has too little room left for another request. `launch` is
+   * idempotent, so an earlier hedge timer cannot cause a double launch.
+   */
+  private advanceAfterFailure(task: ProviderTask, operation: OperationContext, launchNext: () => void): void {
+    if (task.abort.signal.aborted || operation.signal.aborted) return
+    if (operation.deadlineAt - Date.now() < this.config.minAvailableSeconds * 1000) return
+    launchNext()
+  }
+
   /**
    * Run one provider to a terminal state: retryable errors retry within
    * `attempts`, a single request crossing t1 hedges the next provider, and the
@@ -1415,6 +1540,7 @@ export class VisionToolkitRuntime {
         if (budget < minAvailableMs) {
           task.status = 'failed'
           task.error = new VisionToolkitError('timeout', `${tool}: ${provider.name} has insufficient remaining time`)
+          this.advanceAfterFailure(task, operation, launchNext)
           return
         }
         const reqDeadline = createDeadline(AbortSignal.any([operation.signal, task.abort.signal]), budget)
@@ -1453,6 +1579,7 @@ export class VisionToolkitRuntime {
           if (reqDeadline.timedOut) {
             task.status = 'failed'
             task.error = new VisionToolkitError('timeout', `${tool}: ${provider.name} exhausted its t2 budget`)
+            this.advanceAfterFailure(task, operation, launchNext)
             return
           }
           if (classified.code === 'rate_limit') {
@@ -1467,6 +1594,7 @@ export class VisionToolkitRuntime {
           }
           task.status = 'failed'
           task.error = classified
+          this.advanceAfterFailure(task, operation, launchNext)
           return
         } finally {
           reqDeadline.cleanup()
@@ -1568,6 +1696,8 @@ export class VisionToolkitRuntime {
         protocol: env.VISION_API_PROTOCOL,
         anthropicThinking: env.VISION_ANTHROPIC_THINKING,
         sslVerify: env.VISION_SSL_VERIFY ?? null,
+        stream: env.VISION_STREAM === '1',
+        uploadViaUrl: provider.uploadViaUrl,
         userAgent: env.VISION_USER_AGENT,
         credentialSha256: createHash('sha256').update(env.VISION_API_KEY).digest('hex'),
         maxImageBytes: provider.maxImageBytes,
@@ -1698,24 +1828,31 @@ export class VisionToolkitRuntime {
           return cached.result
         }
       }
-      const result = await this.runVisionHedge('glance', [
-        ...images.map(image => image.path),
-        ...(request.region !== undefined ? ['--region', request.region] : []),
-        ...(request.ocr === true ? ['--ocr'] : []),
-        ...(request.query !== undefined ? ['-q', request.query] : []),
-      ], images, operation, pool)
-      const answer = result.stdout.trim()
-      if (answer.length === 0) throw new VisionToolkitError('output', 'glance: vision API returned an empty description')
-      const value: GlanceResult = {
-        images,
-        mode: request.ocr === true ? 'ocr' : request.query !== undefined ? 'qa' : 'describe',
-        answer,
-        truncated: false,
-      }
-      if (options.sessionScope !== undefined && cacheKey !== undefined && !operation.signal.aborted) {
-        this.glanceCache.set(options.sessionScope, { key: cacheKey, result: value })
+      const transfer = request.region === undefined
+        ? await this.maybeTransferImages(pool, images, operation)
+        : undefined
+      try {
+        const result = await this.runVisionHedge('glance', [
+          ...(transfer !== undefined ? transfer.urls : images.map(image => image.path)),
+          ...(transfer === undefined && request.region !== undefined ? ['--region', request.region] : []),
+          ...(request.ocr === true ? ['--ocr'] : []),
+          ...(request.query !== undefined ? ['-q', request.query] : []),
+        ], images, operation, pool)
+        const answer = result.stdout.trim()
+        if (answer.length === 0) throw new VisionToolkitError('output', 'glance: vision API returned an empty description')
+        const value: GlanceResult = {
+          images,
+          mode: request.ocr === true ? 'ocr' : request.query !== undefined ? 'qa' : 'describe',
+          answer,
+          truncated: false,
+        }
+        if (options.sessionScope !== undefined && cacheKey !== undefined && !operation.signal.aborted) {
+          this.glanceCache.set(options.sessionScope, { key: cacheKey, result: value })
+        }
+        return value
+      } finally {
+        if (transfer !== undefined) await transfer.cleanup()
       }
-      return value
     })
   }
 
@@ -1751,14 +1888,23 @@ export class VisionToolkitRuntime {
     }
     const image = await this.prepareVisionImage(request.image, pool.map(entry => entry.provider), policy, operation)
     this.accountImage(image, operation)
-    const result = await this.runVisionHedge(tool, [
-      image.path,
-      request.target,
-      ...(request.region !== undefined ? ['--region', request.region] : []),
-    ], [image], operation, pool)
-    const elements = parseLocationOutput(result.stdout)
-    this.validateLocations(elements, image.width, image.height)
-    return { image, elements }
+    const transfer = request.region === undefined
+      ? await this.maybeTransferImages(pool, [image], operation)
+      : undefined
+    try {
+      const result = await this.runVisionHedge(tool, transfer !== undefined
+        ? [transfer.urls[0]!, request.target, '--size', `${image.width}x${image.height}`]
+        : [
+          image.path,
+          request.target,
+          ...(request.region !== undefined ? ['--region', request.region] : []),
+        ], [image], operation, pool)
+      const elements = parseLocationOutput(result.stdout)
+      this.validateLocations(elements, image.width, image.height)
+      return { image, elements }
+    } finally {
+      if (transfer !== undefined) await transfer.cleanup()
+    }
   }
 
   /** ground: locate one named target and return pixel boxes. */
@@ -2453,6 +2599,18 @@ export class VisionToolkitRuntime {
     })
   }
 
+  private async writableDirectoryCheck(path: string, label: string): Promise<HealthCheck> {
+    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, and optionally probe one provider's `/models` plus one real multimodal request. */
   async health(testConnection: boolean, options: ToolCallOptions, testModel = false, provider?: ResolvedProvider): Promise<VisionToolkitHealthResult> {
     return this.runOperation('vision_toolkit_health', options, async (operation) => {
@@ -2474,6 +2632,27 @@ export class VisionToolkitRuntime {
         if (operation.signal.aborted) throw new VisionToolkitError('cancelled', 'vision_toolkit_health: cancelled')
         chrome = { status: 'error', detail: 'Chrome availability probe failed' }
       }
+      let resolvedCredential: ResolvedCredential | undefined
+      let credential: HealthCheck
+      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: HealthCheck
+      try {
+        // allowedDirs are session input roots; they do not affect output readiness.
+        const policy = await createPathPolicy(options.workspace, [], this.config.storageDir)
+        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: HealthCheck = {
         status: 'not_tested',
         detail: 'Connection was not tested; use the per-provider API test',
@@ -2564,7 +2743,7 @@ export class VisionToolkitRuntime {
           }
         }
       }
-      const checks = { python, dependencies, chrome, service, model }
+      const checks = { python, dependencies, chrome, credential, artifactDirectory, tempDirectory, service, model }
       const healthy = Object.values(checks).every(check => check.status !== 'error')
       return {
         pluginVersion: PLUGIN_VERSION,