@mengruo/dsh-vision-toolkit 0.1.3 → 0.1.4

package/src/runtime.ts

@@ -475,6 +475,9 @@ export interface VisionToolkitHealthResult {
     python: HealthCheck
     dependencies: HealthCheck
     chrome: HealthCheck
+    credential: HealthCheck
+    artifactDirectory: HealthCheck
+    tempDirectory: HealthCheck
     service: HealthCheck
     model: HealthCheck
   }
@@ -537,8 +540,15 @@ 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'])
+/**
+ * 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 +781,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 +796,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())
@@ -1010,13 +1026,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 +1043,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
   }
@@ -1383,6 +1399,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 +1447,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 +1486,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 +1501,7 @@ export class VisionToolkitRuntime {
           }
           task.status = 'failed'
           task.error = classified
+          this.advanceAfterFailure(task, operation, launchNext)
           return
         } finally {
           reqDeadline.cleanup()
@@ -2453,6 +2488,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 +2521,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 +2632,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,

package/src/storage-history.ts

@@ -0,0 +1,172 @@
+/** Durable configured-storage history used to authorize persisted image paths after Profile restarts. */
+
+import type { Context, Fiber } from '@deepseek-ai/cordis'
+import { defineDomain } from '@deepseek-ai/dsh-storage-domain'
+import type { DomainGlobal } from '@deepseek-ai/dsh-storage-domain'
+import { z } from 'zod'
+import { resolveConfig, type VisionToolkitConfig } from './config.ts'
+
+const storageHistoryStateSchema = z.object({
+  roots: z.array(z.string().min(1)),
+})
+
+type StorageHistoryState = z.infer<typeof storageHistoryStateSchema>
+
+/** Plugin-owned storage roots that survive Settings-provider and Profile restarts. */
+export const storageHistoryDomainSpec = defineDomain({
+  name: 'vision_toolkit_storage',
+  version: 0,
+  global: {
+    schema: storageHistoryStateSchema,
+    initial: { roots: [] },
+  },
+  tables: {},
+})
+
+interface StorageBinding {
+  accepting: boolean
+  global: DomainGlobal<StorageHistoryState>
+}
+
+function sameRoots(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((root, index) => root === right[index])
+}
+
+/**
+ * Return every configured root that must remain readable, including the active root.
+ * @param config - Settings generation to summarize.
+ * @returns normalized configured roots in retention order.
+ */
+export function configuredStorageRoots(config: VisionToolkitConfig): string[] {
+  const resolved = resolveConfig(config)
+  return [...new Set([
+    ...resolved.storageHistory,
+    ...(resolved.storageDir === undefined ? [] : [resolved.storageDir]),
+  ])]
+}
+
+/**
+ * Merge plugin-owned roots into a Settings generation without retaining its active root as history.
+ * @param config - Settings generation being restored.
+ * @param durableRoots - roots loaded from the plugin-owned sidecar.
+ * @returns the original generation when unchanged, otherwise a generation with restored history.
+ */
+export function restoreDurableStorageHistory(
+  config: VisionToolkitConfig,
+  durableRoots: readonly string[],
+): VisionToolkitConfig {
+  const resolved = resolveConfig(config)
+  const storageHistory = [...new Set([...resolved.storageHistory, ...durableRoots])]
+    .filter(root => root !== resolved.storageDir)
+  if (sameRoots(storageHistory, resolved.storageHistory)) return config
+  return { ...config, storageHistory }
+}
+
+/** Optional storage-domain sidecar for storage roots that Settings cannot persist itself. */
+export class StorageHistoryStore {
+  private storage: StorageBinding | undefined
+  private storageFiber: (Fiber & PromiseLike<Fiber>) | undefined
+  private storageReady: Promise<void> | undefined
+  private mutationTail: Promise<void> = Promise.resolve()
+  private desiredRoots: readonly string[] | undefined
+  private persistenceTicket = 0
+  private warned = false
+
+  constructor(private readonly ctx: Context) {
+    if (typeof ctx.inject !== 'function') return
+    this.storageFiber = ctx.inject(['storageDomain'], async (storageCtx: Context) => {
+      const domain = await storageCtx.storageDomain.open(storageHistoryDomainSpec)
+      const binding: StorageBinding = { accepting: true, global: domain.global }
+      this.storage = binding
+      try {
+        if (this.desiredRoots !== undefined) {
+          await this.write(binding, this.desiredRoots, this.persistenceTicket)
+        }
+      } catch (error) {
+        this.storage = undefined
+        await domain.close()
+        throw error
+      }
+      return async () => {
+        binding.accepting = false
+        if (this.storage === binding) this.storage = undefined
+        await this.mutationTail
+        await domain.close()
+      }
+    })
+    this.storageReady = Promise.resolve(this.storageFiber).then(
+      () => undefined,
+      (error: unknown) => { this.warnOnce(error) },
+    )
+  }
+
+  /**
+   * Restore durable roots into one Settings generation before runtime preparation.
+   * @param config - Settings generation to restore.
+   * @returns the generation with available durable roots merged into its history.
+   */
+  async restore(config: VisionToolkitConfig): Promise<VisionToolkitConfig> {
+    const binding = await this.prepareStorage()
+    return restoreDurableStorageHistory(config, binding?.global.get().roots ?? [])
+  }
+
+  /**
+   * Persist the active and historical configured roots.
+   * @param config - validated generation whose roots must survive restart.
+   * @returns false when no storage-domain is available; true after persistence or when there are no roots.
+   */
+  async persist(config: VisionToolkitConfig): Promise<boolean> {
+    const roots = configuredStorageRoots(config)
+    const ticket = ++this.persistenceTicket
+    this.desiredRoots = roots
+    if (roots.length === 0) return true
+    const binding = await this.prepareStorage()
+    if (binding === undefined) return false
+    await this.write(binding, roots, ticket)
+    return true
+  }
+
+  /** Release the optional storage-domain binding with the plugin lifecycle. */
+  dispose(): void {
+    const fiber = this.storageFiber
+    this.storageFiber = undefined
+    this.storageReady = undefined
+    if (fiber !== undefined) void fiber.dispose().catch(error => { this.warnOnce(error) })
+  }
+
+  private async prepareStorage(): Promise<StorageBinding | undefined> {
+    const current = this.activeStorage()
+    if (current !== undefined) return current
+    if (this.ctx.get('storageDomain') === undefined) return undefined
+    await this.storageReady
+    return this.activeStorage()
+  }
+
+  private activeStorage(): StorageBinding | undefined {
+    return this.storage?.accepting === true ? this.storage : undefined
+  }
+
+  private write(binding: StorageBinding, roots: readonly string[], ticket: number): Promise<void> {
+    return this.enqueueMutation(async () => {
+      if (!binding.accepting) throw new Error('the storage-domain provider changed while storage history was pending')
+      if (ticket !== this.persistenceTicket) return
+      if (sameRoots(binding.global.get().roots, roots)) return
+      await binding.global.set({ roots: [...roots] })
+    })
+  }
+
+  private enqueueMutation(operation: () => Promise<void>): Promise<void> {
+    const result = this.mutationTail.then(operation)
+    this.mutationTail = result.then(() => undefined, () => undefined)
+    return result
+  }
+
+  private warnOnce(error: unknown): void {
+    if (this.warned) return
+    this.warned = true
+    this.ctx.logger?.warn(
+      'dsh-vision-toolkit: configured storage history sidecar is unavailable. %s',
+      (error instanceof Error ? error.message : String(error)).slice(0, 500),
+    )
+  }
+}

package/src/upstream.ts

@@ -1059,22 +1059,47 @@ export class UpstreamAdapter {
       return new VisionToolkitError('output', `${tool}: upstream output exceeded the capture limit`)
     }
     const message = upstreamFailureMessage(tool, result.stderr, options.secrets ?? [])
-    if (/HTTP 401|\b401\b|Unauthorized|authentication/i.test(result.stderr)) {
-      return new VisionToolkitError('service', `${message}; verify the configured credential`)
+    const stderr = result.stderr
+
+    // Remote provider failures, classified into a machine-routable taxonomy so
+    // the failover loop retries transient errors and fails over immediately on
+    // deterministic ones. Order matters: auth/quota/rate-limit/region/tos are
+    // checked before the broader server/network/request-shape patterns.
+    if (/HTTP 401|\b401\b|HTTP 403|\b403\b|Unauthorized|Forbidden|authentication|Invalid API-key|invalid api key|check the api key/i.test(stderr)) {
+      return new VisionToolkitError('auth', `${message}; verify the configured credential`)
+    }
+    if (/HTTP 402|\b402\b|Payment Required|insufficient balance|insufficient quota|insufficient credits|billing|out of credits|out of quota/i.test(stderr)) {
+      return new VisionToolkitError('quota', `${message}; the provider account is out of quota or unpaid`)
     }
-    if (/HTTP 429|\b429\b|rate limit|quota/i.test(result.stderr)) {
+    if (/HTTP 429|\b429\b|rate ?limit|too many requests/i.test(stderr)) {
       return new VisionToolkitError('rate_limit', `${message}; retry later or reduce concurrency`)
     }
-    if (/Missing config VISION_/i.test(result.stderr)) {
+    if (/not available in your region|prohibited region|unsupported region|region is not supported/i.test(stderr)) {
+      return new VisionToolkitError('region', `${message}; the provider is not available in this region`)
+    }
+    if (/terms of service|\btos\b|content policy|safety system/i.test(stderr)) {
+      return new VisionToolkitError('tos', `${message}; the request was rejected by the provider content policy`)
+    }
+    if (/HTTP 5\d\d|\b500\b|\b502\b|\b503\b|\b504\b|bad gateway|service unavailable|internal server error/i.test(stderr)) {
+      return new VisionToolkitError('server', `${message}; the provider returned a server error`)
+    }
+    if (/connection refused|connection reset|ECONN|ENOTFOUND|EAI_AGAIN|getaddrinfo|fetch failed|name resolution|network error|network is unreachable/i.test(stderr)) {
+      return new VisionToolkitError('network', `${message}; network failure reaching the provider`)
+    }
+    if (/HTTP 400|\b400\b|HTTP 404|\b404\b|HTTP 422|\b422\b|invalid request|invalid model|no such model|model not exist|unknown model/i.test(stderr)) {
+      return new VisionToolkitError('invalid_request', `${message}; the request or model is not supported by this provider`)
+    }
+
+    if (/Missing config VISION_/i.test(stderr)) {
       return new VisionToolkitError('config', message)
     }
-    if (/maxImagePixels|exceed(?:s|ing).*pixels/i.test(result.stderr)) {
+    if (/maxImagePixels|exceed(?:s|ing).*pixels/i.test(stderr)) {
       return new VisionToolkitError('capacity', message)
     }
-    if (/not found|only PNG|unsupported|cannot open|empty region|must be|expects|invalid colour|needs at least/i.test(result.stderr)) {
+    if (/not found|only PNG|unsupported|cannot open|empty region|must be|expects|invalid colour|needs at least/i.test(stderr)) {
       return new VisionToolkitError('input', message)
     }
-    if (/requires Pillow|requires numpy|requires vtracer|no Chrome|capture failed/i.test(result.stderr)) {
+    if (/requires Pillow|requires numpy|requires vtracer|no Chrome|capture failed/i.test(stderr)) {
       return new VisionToolkitError('runtime', message)
     }
     return new VisionToolkitError(

package/src/web.ts

@@ -22,6 +22,7 @@ import {
 } from './paste-images.ts'
 import {
   resolveConfig,
+  retainedStorageHistory,
   isBuiltInFreeVisionProvider,
   VISION_TOOLKIT_SETTINGS_NAMESPACE,
   type ResolvedProvider,
@@ -346,16 +347,22 @@ export class VisionToolkitWebBackend {
 
   private async save(request: SaveRequest): Promise<VisionToolkitSettingsSnapshot> {
     if (!this.ctx.settings.writable) throw new Error('settings provider is read-only')
+    const current = resolveConfig(descriptorOf(this.ctx).value as VisionToolkitConfig)
+    const storageHistory = retainedStorageHistory(request.value, current)
+    const value: VisionToolkitConfig = {
+      ...request.value,
+      ...(storageHistory.length === 0 ? {} : { storageHistory }),
+    }
     let candidate: PreparedRuntimeGeneration
     try {
-      candidate = await this.manager.prepareCandidate(request.value)
+      candidate = await this.manager.prepareCandidate(value)
     } catch (error) {
       this.manager.recordFailure(error)
       throw error
     }
     await this.ctx.settings.replace(
       VISION_TOOLKIT_SETTINGS_NAMESPACE,
-      request.value as object,
+      value as object,
       request.expectedRevision,
     )
     this.manager.activateCandidate(candidate)