@anionex/dsh-vision-toolkit 0.1.37 → 0.1.39

package/src/runtime-install.ts

@@ -88,6 +88,8 @@ const PYPI_MIRROR_BASE_URL = 'https://mirrors.cloud.tencent.com/pypi/simple'
 const PROBE_TIMEOUT_MS = 30_000
 const LOCK_STALE_MS = 15 * 60 * 1000
 const LOCK_HEARTBEAT_MS = 5_000
+const WINDOWS_FILE_RETRY_ATTEMPTS = 5
+const WINDOWS_FILE_RETRY_DELAY_MS = 250
 
 /** Absolute root of the packaged upstream snapshot. */
 export function bundledUpstreamRoot(): string {
@@ -103,6 +105,47 @@ function sha256(bytes: string | Buffer): string {
   return createHash('sha256').update(bytes).digest('hex')
 }
 
+/**
+ * Windows Defender/antivirus real-time scanning briefly locks freshly written
+ * Python DLLs, so recursive removal and directory replacement can fail with
+ * EBUSY/EPERM immediately after installation. Retry those transient Windows
+ * errors before surfacing them; non-Windows platforms pass through unchanged.
+ */
+export async function withWindowsTransientRetry<T>(operation: () => Promise<T>): Promise<T> {
+  let lastError: unknown
+  for (let attempt = 1; attempt <= WINDOWS_FILE_RETRY_ATTEMPTS; attempt += 1) {
+    try {
+      return await operation()
+    } catch (error) {
+      lastError = error
+      const code = error instanceof Error ? (error as NodeJS.ErrnoException).code : undefined
+      const transient = process.platform === 'win32' && (code === 'EBUSY' || code === 'EPERM' || code === 'EACCES')
+      if (!transient) break
+      if (attempt < WINDOWS_FILE_RETRY_ATTEMPTS) {
+        await new Promise(resolveWait => setTimeout(resolveWait, WINDOWS_FILE_RETRY_DELAY_MS * attempt))
+      }
+    }
+  }
+  throw lastError
+}
+
+/**
+ * Best-effort removal used after the primary runtime path has already
+ * succeeded or failed. Transient Windows locks must not turn a usable runtime
+ * into an error, but leaving the directory behind should still be audible.
+ */
+export async function ignoreCleanupFailure(ctx: Context, label: string, path: string): Promise<void> {
+  try {
+    await withWindowsTransientRetry(() => rm(path, { recursive: true, force: true }))
+  } catch (error) {
+    ctx.logger.warn(
+      'dsh-vision-toolkit: %s cleanup failed: %s',
+      label,
+      error instanceof Error ? error.message : String(error),
+    )
+  }
+}
+
 export function isolatedPythonEnvironment(home: string): NodeJS.ProcessEnv {
   return {
     HOME: home,
@@ -488,7 +531,7 @@ async function withDirectoryLock<T>(lockPath: string, fn: () => Promise<T>): Pro
     await writeFile(join(lockPath, 'owner'), `${owner}\n`, { flag: 'wx' })
   } catch (error) {
     if (acquired) {
-      await rm(lockPath, { recursive: true, force: true }).catch(() => {})
+      await withWindowsTransientRetry(() => rm(lockPath, { recursive: true, force: true })).catch(() => {})
       throw error
     }
     if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
@@ -497,7 +540,7 @@ async function withDirectoryLock<T>(lockPath: string, fn: () => Promise<T>): Pro
       try {
         const info = await stat(lockPath)
         if (Date.now() - info.mtimeMs > LOCK_STALE_MS) {
-          await rm(lockPath, { recursive: true, force: true })
+          await withWindowsTransientRetry(() => rm(lockPath, { recursive: true, force: true }))
           return withDirectoryLock(lockPath, fn)
         }
       } catch {
@@ -518,7 +561,7 @@ async function withDirectoryLock<T>(lockPath: string, fn: () => Promise<T>): Pro
     clearInterval(heartbeat)
     try {
       if ((await readFile(join(lockPath, 'owner'), 'utf8')).trim() === owner) {
-        await rm(lockPath, { recursive: true, force: true })
+        await withWindowsTransientRetry(() => rm(lockPath, { recursive: true, force: true }))
       }
     } catch {
       // The lock was already removed or replaced.
@@ -552,7 +595,7 @@ export async function acquireBundledPython(
     if (ready !== undefined) return
     const parent = dirname(root)
     await mkdir(parent, { recursive: true })
-    await rm(root, { recursive: true, force: true })
+    await withWindowsTransientRetry(() => rm(root, { recursive: true, force: true }))
     const work = await mkdtemp(join(parent, '.python-bootstrap-'))
     try {
       const archive = join(work, 'python.tar.gz')
@@ -589,9 +632,9 @@ export async function acquireBundledPython(
         )
       }
       if (process.platform !== 'win32') await chmod(extractedInterpreter, 0o755)
-      await rename(extractDir, root)
+      await withWindowsTransientRetry(() => rename(extractDir, root))
     } finally {
-      await rm(work, { recursive: true, force: true })
+      await ignoreCleanupFailure(ctx, 'bundled Python staging', work)
     }
   })
   const metadata = await pythonMetadata(ctx, command, cwd)
@@ -827,7 +870,7 @@ async function waitForManagedRuntime(
     try {
       const info = await stat(lockPath)
       if (Date.now() - info.mtimeMs > LOCK_STALE_MS) {
-        await rm(lockPath, { recursive: true, force: true })
+        await withWindowsTransientRetry(() => rm(lockPath, { recursive: true, force: true }))
         return undefined
       }
     } catch {
@@ -844,7 +887,7 @@ async function releaseManagedLock(lockPath: string, owner: string): Promise<void
   } catch {
     return
   }
-  await rm(lockPath, { recursive: true, force: true })
+  await withWindowsTransientRetry(() => rm(lockPath, { recursive: true, force: true }))
 }
 
 async function prepareManaged(
@@ -899,7 +942,7 @@ async function prepareManaged(
     await writeFile(join(lockPath, 'owner'), `${lockOwner}\n`, { flag: 'wx' })
   } catch (error) {
     if (lockAcquired) {
-      await rm(lockPath, { recursive: true, force: true })
+      await withWindowsTransientRetry(() => rm(lockPath, { recursive: true, force: true })).catch(() => {})
       throw error
     }
     if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
@@ -1016,17 +1059,17 @@ async function prepareManaged(
     const quarantine = `${finalRoot}.replaced-${randomUUID()}`
     let quarantined = false
     try {
-      await rename(finalRoot, quarantine)
+      await withWindowsTransientRetry(() => rename(finalRoot, quarantine))
       quarantined = true
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
     }
     try {
-      await rename(staging, finalRoot)
+      await withWindowsTransientRetry(() => rename(staging, finalRoot))
     } catch (error) {
       if (quarantined) {
         try {
-          await rename(quarantine, finalRoot)
+          await withWindowsTransientRetry(() => rename(quarantine, finalRoot))
         } catch (restoreError) {
           throw new VisionToolkitError(
             'runtime',
@@ -1037,13 +1080,18 @@ async function prepareManaged(
       }
       throw error
     }
-    await rm(quarantine, { recursive: true, force: true })
+    await ignoreCleanupFailure(ctx, 'managed runtime quarantine', quarantine)
     const python: RuntimeCommand = { program: interpreter, prefix: [], display: interpreter }
     return { source: 'managed', root: BUNDLED_ROOT, python, cleanHome, pythonVersion: metadata.version, dependencies }
   } finally {
     clearInterval(heartbeat)
-    await rm(staging, { recursive: true, force: true })
-    await releaseManagedLock(lockPath, lockOwner)
+    await ignoreCleanupFailure(ctx, 'managed runtime staging', staging)
+    await releaseManagedLock(lockPath, lockOwner).catch(error => {
+      ctx.logger.warn(
+        'dsh-vision-toolkit: managed runtime lock cleanup failed: %s',
+        error instanceof Error ? error.message : String(error),
+      )
+    })
   }
 }
 

package/src/runtime.ts

@@ -16,6 +16,7 @@ import { SaxesParser } from 'saxes'
 import { describeArtifact, type ArtifactDescriptor } from './artifacts.ts'
 import { isBuiltInFreeVisionProvider, type ResolvedVisionToolkitConfig } from './config.ts'
 import { BUILT_IN_FREE_VISION_KEY } from './defaults.ts'
+import { evidenceRuntimeFingerprint } from './evidence-cache.ts'
 import { VisionToolkitError } from './errors.ts'
 import {
   assertDistinctOutput,
@@ -480,6 +481,12 @@ export interface ToolCallOptions {
   sessionScope?: object
 }
 
+/** One immutable vision-service snapshot used to generate cache-keyed evidence. */
+export interface CapturedEvidenceRuntime {
+  readonly evidenceFingerprint: string
+  glance(request: GlanceRequest, options: ToolCallOptions): Promise<GlanceResult>
+}
+
 interface GlanceCacheEntry {
   key: string
   result: GlanceResult
@@ -698,6 +705,25 @@ export class VisionToolkitRuntime {
     return this.adapter.versionInfo
   }
 
+  /** Stable identity for persisted image descriptions produced by this runtime. */
+  get evidenceFingerprint(): string {
+    return evidenceRuntimeFingerprint(this.config, undefined, process.env.VISION_SSL_VERIFY?.trim())
+  }
+
+  /** Capture the credential and provider identity used by one evidence conversion. */
+  async captureEvidenceRuntime(): Promise<CapturedEvidenceRuntime> {
+    const env = await this.resolveVisionEnv()
+    const evidenceFingerprint = evidenceRuntimeFingerprint(
+      this.config,
+      createHash('sha256').update(env.VISION_API_KEY).digest('hex'),
+      env.VISION_SSL_VERIFY,
+    )
+    return Object.freeze({
+      evidenceFingerprint,
+      glance: (request: GlanceRequest, options: ToolCallOptions) => this.glanceWithEnv(request, options, env),
+    })
+  }
+
   private timeout(options: ToolCallOptions): number {
     const value = options.timeoutMs ?? this.config.timeoutMs
     if (!Number.isInteger(value) || value < 1000 || value > MAX_TIMEOUT_MS) {
@@ -1213,6 +1239,14 @@ export class VisionToolkitRuntime {
 
   /** glance: describe, targeted QA, OCR, or multi-image comparison. */
   async glance(request: GlanceRequest, options: ToolCallOptions): Promise<GlanceResult> {
+    return this.glanceWithEnv(request, options)
+  }
+
+  private async glanceWithEnv(
+    request: GlanceRequest,
+    options: ToolCallOptions,
+    capturedEnv?: UpstreamEnvironment,
+  ): Promise<GlanceResult> {
     return this.runOperation('vision_glance', options, async (operation) => {
       if (request.images.length === 0) throw new VisionToolkitError('input', 'glance requires at least one image')
       if (request.query !== undefined && request.ocr === true) {
@@ -1235,7 +1269,7 @@ export class VisionToolkitRuntime {
         this.accountImage(image, operation)
         images.push(image)
       }
-      const env = await this.resolveVisionEnv()
+      const env = capturedEnv ?? await this.resolveVisionEnv()
       const cacheKey = options.sessionScope === undefined
         ? undefined
         : await this.glanceCacheKey(request, images, env, operation.signal)

package/src/upstream.ts

@@ -541,9 +541,19 @@ const VISION_MODEL_GUARD = [
   '        requested=prompt or vision_client.DEFAULT_PROMPT',
   '        return original_describe(image_url,f"{policy}\\n\\n{requested}",*args,**kwargs)',
   '    vision_client.describe_image=guarded_describe',
+  '    ground_module=None',
+  '    original_parse_matches=None',
+  '    if Path(script).name in {"ground","detect"} and importlib.util.find_spec("ground") is not None:',
+  '        import ground as ground_module',
+  '        original_parse_matches=ground_module.parse_matches',
+  '        def normalized_parse_matches(*args,**kwargs):',
+  '            matches=original_parse_matches(*args,**kwargs)',
+  '            return [ground_module.Match(" ".join(str(match.label).split()),match.bbox) for match in matches]',
+  '        ground_module.parse_matches=normalized_parse_matches',
   '    try:',
   '        runpy.run_path(script,run_name="__main__")',
   '    finally:',
+  '        if ground_module is not None: ground_module.parse_matches=original_parse_matches',
   '        vision_client.describe_image=original_describe',
 ].join('\n')