@anionex/dsh-vision-toolkit 0.1.27 → 0.1.29

package/src/exposure.ts

@@ -19,7 +19,7 @@ export const VISION_TOOLKIT_ACTIVATE = 'vision_toolkit_activate'
 
 interface AgentExposure {
   active: boolean
-  hideActivation?: () => void
+  liftRestriction?: () => void
   toolDisposers: Array<() => void>
   toolNames: string[]
 }
@@ -150,6 +150,9 @@ export class VisionToolExposure {
     const listeners = [
       this.ctx.on('agent/created', ({ agent }) => { this.attach(agent) }),
       this.ctx.on('agent/disposed', ({ agent }) => { this.detach(agent) }),
+      this.ctx.on('session/event', (session, event) => {
+        if (event.type === 'step/end') this.applyHideActivationForSession(session)
+      }),
       this.ctx.on('tools/result', (exec, result) => {
         if (result.isError === false
           && exec.name === 'skill'
@@ -192,23 +195,42 @@ export class VisionToolExposure {
 
     const definitions = this.createTools()
     const toolDisposers: Array<() => void> = []
-    let hideActivation: (() => void) | undefined
     try {
       for (const definition of definitions) toolDisposers.push(agent.ctx.tools.register(definition))
-      hideActivation = agent.ctx.tools.restrict({ deny: [VISION_TOOLKIT_ACTIVATE] })
+      // A Skill call and the bootstrap can be issued in the same model step.
+      // Restricting immediately would turn the still-in-flight bootstrap call
+      // into an UNKNOWN_TOOL error, so live sessions hide at step/end.
+      if (!this.isLiveSession(agent.session)) this.applyHideActivation(agent)
     } catch (error) {
-      hideActivation?.()
       for (const dispose of toolDisposers.reverse()) dispose()
       throw error
     }
 
     state.active = true
-    state.hideActivation = hideActivation
     state.toolDisposers = toolDisposers
     state.toolNames = definitions.map(definition => definition.name)
     return { activated: true, tools: [...state.toolNames] }
   }
 
+  /** Whether the session is attached to the live SessionStore (production). */
+  private isLiveSession(session: Session): boolean {
+    return this.ctx.sessions.get(session.id) === session
+  }
+
+  private applyHideActivationForSession(session: Session): void {
+    for (const agent of this.ctx.agents.list()) {
+      if (agent.session === session && this.states.get(agent)?.active === true) {
+        this.applyHideActivation(agent)
+      }
+    }
+  }
+
+  private applyHideActivation(agent: Agent): void {
+    const state = this.states.get(agent)
+    if (state === undefined || state.liftRestriction !== undefined) return
+    state.liftRestriction = agent.ctx.tools.restrict({ deny: [VISION_TOOLKIT_ACTIVATE] })
+  }
+
   private detach(agent: Agent): void {
     const state = this.states.get(agent)
     if (state === undefined) return
@@ -222,7 +244,7 @@ export class VisionToolExposure {
   }
 
   private disposeState(state: AgentExposure): void {
-    state.hideActivation?.()
+    state.liftRestriction?.()
     for (const dispose of state.toolDisposers.reverse()) dispose()
   }
 }

package/src/runtime-install.ts

@@ -8,6 +8,8 @@
 
 import { createHash, randomUUID } from 'node:crypto'
 import {
+  access,
+  chmod,
   lstat,
   mkdir,
   mkdtemp,
@@ -20,10 +22,16 @@ import {
   utimes,
   writeFile,
 } from 'node:fs/promises'
+import { createWriteStream } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
+import { Transform } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
 import { fileURLToPath } from 'node:url'
 import type { Context } from '@deepseek-ai/cordis'
+import { x as extractTar } from 'tar'
+import { EnvHttpProxyAgent } from 'undici'
+import { request as undiciRequest } from 'undici'
 import type { ResolvedVisionToolkitConfig } from './config.ts'
 import { VisionToolkitError } from './errors.ts'
 import { UPSTREAM_COMMIT, UPSTREAM_REPOSITORY, UPSTREAM_VERSION } from './version.ts'
@@ -252,10 +260,317 @@ async function pythonMetadata(
   }
 }
 
-async function resolveBootstrapPython(
+interface PythonBootstrapArtifact {
+  url: string
+  sha256: string
+  size: number
+}
+
+interface PythonBootstrapManifest {
+  schemaVersion: 1
+  pythonVersion: string
+  buildTag: string
+  artifacts: Record<string, PythonBootstrapArtifact>
+}
+
+const PYTHON_BOOTSTRAP_MANIFEST_PATH = join(PACKAGE_ROOT, 'assets', 'python-bootstrap.json')
+const PYTHON_DOWNLOAD_TIMEOUT_MS = 10 * 60 * 1000
+const PYTHON_DOWNLOAD_ATTEMPTS = 3
+
+async function readPythonBootstrapManifest(): Promise<PythonBootstrapManifest> {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(await readFile(PYTHON_BOOTSTRAP_MANIFEST_PATH, 'utf8'))
+  } catch (error) {
+    throw new VisionToolkitError('runtime', `python bootstrap manifest is unreadable: ${PYTHON_BOOTSTRAP_MANIFEST_PATH}`, { cause: error })
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    throw new VisionToolkitError('runtime', 'python bootstrap manifest is not an object')
+  }
+  const manifest = parsed as Partial<PythonBootstrapManifest>
+  if (
+    manifest.schemaVersion !== 1
+    || typeof manifest.pythonVersion !== 'string'
+    || !/^3\.\d+\.\d+$/u.test(manifest.pythonVersion)
+    || typeof manifest.buildTag !== 'string'
+    || !/^\d{8}$/u.test(manifest.buildTag)
+    || typeof manifest.artifacts !== 'object'
+    || manifest.artifacts === null
+  ) {
+    throw new VisionToolkitError('runtime', 'python bootstrap manifest is invalid')
+  }
+  for (const [target, artifact] of Object.entries(manifest.artifacts)) {
+    if (
+      typeof artifact !== 'object'
+      || artifact === null
+      || typeof artifact.url !== 'string'
+      || !artifact.url.startsWith('https://github.com/astral-sh/python-build-standalone/releases/download/')
+      || typeof artifact.sha256 !== 'string'
+      || !/^[a-f0-9]{64}$/u.test(artifact.sha256)
+      || !Number.isInteger(artifact.size)
+      || artifact.size <= 0
+    ) {
+      throw new VisionToolkitError('runtime', `python bootstrap manifest has an invalid artifact: ${target}`)
+    }
+  }
+  return manifest as PythonBootstrapManifest
+}
+
+/** Map Node platform/arch to the pinned artifact name, including musl Linux. */
+export function pythonBootstrapTarget(platform: string, arch: string, musl: boolean): string {
+  return platform === 'linux' && musl ? `${platform}-${arch}-musl` : `${platform}-${arch}`
+}
+
+async function runningMusl(): Promise<boolean> {
+  if (process.platform !== 'linux') return false
+  try {
+    await access(join('/', 'etc', 'alpine-release'))
+    return true
+  } catch {
+    // Fall through to the loader-name probe.
+  }
+  const loader = process.arch === 'arm64' ? 'aarch64' : 'x86_64'
+  try {
+    await access(join('/', 'lib', `ld-musl-${loader}.so.1`))
+    return true
+  } catch {
+    return false
+  }
+}
+
+interface DownloadResponse {
+  statusCode: number
+  headers: Record<string, string | string[] | undefined>
+  body: NodeJS.ReadableStream
+  close: () => Promise<void>
+}
+
+type DownloadRequest = (url: string, signal: AbortSignal) => Promise<DownloadResponse>
+
+const DOWNLOAD_HOSTS = new Set([
+  'github.com',
+  'objects.githubusercontent.com',
+  'release-assets.githubusercontent.com',
+])
+
+async function defaultDownloadRequest(url: string, signal: AbortSignal): Promise<DownloadResponse> {
+  const dispatcher = new EnvHttpProxyAgent()
+  let current = url
+  try {
+    for (let redirects = 0; ; redirects++) {
+      const host = new URL(current).hostname
+      if (!DOWNLOAD_HOSTS.has(host)) throw new Error(`download redirected outside GitHub: ${host}`)
+      const response = await undiciRequest(current, {
+        dispatcher,
+        signal,
+        headers: { 'user-agent': 'dsh-vision-toolkit' },
+      })
+      if (response.statusCode >= 300 && response.statusCode < 400) {
+        const location = response.headers.location
+        await response.body.dump().catch(() => {})
+        if (typeof location !== 'string' || location.length === 0 || redirects >= 5) {
+          throw new Error('download redirected too many times or without a Location header')
+        }
+        current = new URL(location, current).toString()
+        continue
+      }
+      return {
+        statusCode: response.statusCode,
+        headers: response.headers,
+        body: response.body,
+        close: () => dispatcher.close().catch(() => {}),
+      }
+    }
+  } catch (error) {
+    await dispatcher.close().catch(() => {})
+    throw error
+  }
+}
+
+async function downloadBundledPythonOnce(
+  artifact: PythonBootstrapArtifact,
+  destination: string,
+  requestImpl: DownloadRequest = defaultDownloadRequest,
+): Promise<void> {
+  const signal = AbortSignal.timeout(PYTHON_DOWNLOAD_TIMEOUT_MS)
+  let response: DownloadResponse
+  try {
+    response = await requestImpl(artifact.url, signal)
+  } catch (error) {
+    throw new Error(`download request failed: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  try {
+    if (response.statusCode !== 200) throw new Error(`download returned HTTP ${response.statusCode}`)
+    const hash = createHash('sha256')
+    let bytes = 0
+    const hasher = new Transform({
+      transform(chunk, _encoding, callback) {
+        hash.update(chunk as Buffer)
+        bytes += (chunk as Buffer).length
+        callback(null, chunk)
+      },
+    })
+    await pipeline(response.body, hasher, createWriteStream(destination))
+    if (bytes !== artifact.size) throw new Error(`size mismatch: expected ${artifact.size}, received ${bytes}`)
+    if (hash.digest('hex') !== artifact.sha256) throw new Error('sha256 mismatch')
+  } finally {
+    await response.close()
+  }
+}
+
+async function downloadBundledPython(
+  artifact: PythonBootstrapArtifact,
+  destination: string,
+  requestImpl: DownloadRequest,
+): Promise<void> {
+  let lastError: unknown
+  for (let attempt = 0; attempt < PYTHON_DOWNLOAD_ATTEMPTS; attempt++) {
+    try {
+      await downloadBundledPythonOnce(artifact, destination, requestImpl)
+      return
+    } catch (error) {
+      lastError = error
+      if (attempt + 1 < PYTHON_DOWNLOAD_ATTEMPTS) {
+        await new Promise(resolveWait => setTimeout(resolveWait, 500 * 2 ** attempt))
+      }
+    }
+  }
+  throw lastError
+}
+
+/**
+ * Cross-process directory lock with a stale-lock timeout and heartbeat,
+ * matching the managed-runtime lock semantics.
+ */
+async function withDirectoryLock<T>(lockPath: string, fn: () => Promise<T>): Promise<T> {
+  const owner = randomUUID()
+  let acquired = false
+  await mkdir(dirname(lockPath), { recursive: true })
+  try {
+    await mkdir(lockPath, { recursive: false })
+    acquired = true
+    await writeFile(join(lockPath, 'owner'), `${owner}\n`, { flag: 'wx' })
+  } catch (error) {
+    if (acquired) {
+      await rm(lockPath, { recursive: true, force: true }).catch(() => {})
+      throw error
+    }
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+    const started = Date.now()
+    while (Date.now() - started < PREPARE_TIMEOUT_MS) {
+      try {
+        const info = await stat(lockPath)
+        if (Date.now() - info.mtimeMs > LOCK_STALE_MS) {
+          await rm(lockPath, { recursive: true, force: true })
+          return withDirectoryLock(lockPath, fn)
+        }
+      } catch {
+        return withDirectoryLock(lockPath, fn)
+      }
+      await new Promise(resolveWait => setTimeout(resolveWait, 250))
+    }
+    throw new VisionToolkitError('runtime', 'timed out waiting for another process to prepare the bundled Python')
+  }
+  const heartbeat = setInterval(() => {
+    const now = new Date()
+    void utimes(lockPath, now, now).catch(() => {})
+  }, LOCK_HEARTBEAT_MS)
+  heartbeat.unref()
+  try {
+    return await fn()
+  } finally {
+    clearInterval(heartbeat)
+    try {
+      if ((await readFile(join(lockPath, 'owner'), 'utf8')).trim() === owner) {
+        await rm(lockPath, { recursive: true, force: true })
+      }
+    } catch {
+      // The lock was already removed or replaced.
+    }
+  }
+}
+
+export async function acquireBundledPython(
+  ctx: Context,
+  stateRoot: string,
+  cwd: string,
+  manifestOverride?: PythonBootstrapManifest,
+  requestImpl?: DownloadRequest,
+): Promise<{ command: RuntimeCommand; version: string }> {
+  const manifest = manifestOverride ?? await readPythonBootstrapManifest()
+  const target = pythonBootstrapTarget(process.platform, process.arch, await runningMusl())
+  const artifact = manifest.artifacts[target]
+  if (artifact === undefined) {
+    throw new VisionToolkitError(
+      'runtime',
+      `no bundled Python ${manifest.pythonVersion} artifact for ${target}; install Python 3.11+ or configure runtime.python`,
+    )
+  }
+  const root = join(stateRoot, 'python-bootstrap', `${manifest.pythonVersion}-${target}`)
+  const interpreter = process.platform === 'win32' ? join(root, 'python.exe') : join(root, 'bin', 'python3')
+  const command: RuntimeCommand = { program: interpreter, prefix: [], display: interpreter }
+  const cached = await pythonMetadata(ctx, command, cwd)
+  if (cached !== undefined) return { command, version: cached.version }
+  await withDirectoryLock(`${root}.lock`, async () => {
+    const ready = await pythonMetadata(ctx, command, cwd)
+    if (ready !== undefined) return
+    const parent = dirname(root)
+    await mkdir(parent, { recursive: true })
+    await rm(root, { recursive: true, force: true })
+    const work = await mkdtemp(join(parent, '.python-bootstrap-'))
+    try {
+      const archive = join(work, 'python.tar.gz')
+      const extractDir = join(work, 'extract')
+      await mkdir(extractDir, { recursive: true })
+      try {
+        await downloadBundledPython(artifact, archive, requestImpl ?? defaultDownloadRequest)
+      } catch (error) {
+        throw new VisionToolkitError(
+          'runtime',
+          `bundled Python ${manifest.pythonVersion} could not be downloaded for ${target} (${error instanceof Error ? error.message : String(error)}); install Python 3.11+ or configure runtime.python`,
+          { cause: error },
+        )
+      }
+      try {
+        await extractTar({ file: archive, cwd: extractDir, strip: 1 })
+      } catch (error) {
+        throw new VisionToolkitError(
+          'runtime',
+          `bundled Python ${manifest.pythonVersion} could not be extracted for ${target}`,
+          { cause: error },
+        )
+      }
+      const extractedInterpreter = process.platform === 'win32'
+        ? join(extractDir, 'python.exe')
+        : join(extractDir, 'bin', 'python3')
+      try {
+        await access(extractedInterpreter)
+      } catch (error) {
+        throw new VisionToolkitError(
+          'runtime',
+          `bundled Python ${manifest.pythonVersion} for ${target} is missing its interpreter`,
+          { cause: error },
+        )
+      }
+      if (process.platform !== 'win32') await chmod(extractedInterpreter, 0o755)
+      await rename(extractDir, root)
+    } finally {
+      await rm(work, { recursive: true, force: true })
+    }
+  })
+  const metadata = await pythonMetadata(ctx, command, cwd)
+  if (metadata === undefined) {
+    throw new VisionToolkitError('runtime', 'bundled Python did not start after extraction')
+  }
+  return { command, version: metadata.version }
+}
+
+export async function resolveBootstrapPython(
   ctx: Context,
   configured: string | undefined,
   cwd: string,
+  manifestOverride?: PythonBootstrapManifest,
+  requestImpl?: DownloadRequest,
 ): Promise<{ command: RuntimeCommand; version: string; major: number; minor: number }> {
   const candidates: RuntimeCommand[] = configured === undefined
     ? process.platform === 'win32'
@@ -275,12 +590,27 @@ async function resolveBootstrapPython(
       return { command, ...metadata }
     }
   }
-  throw new VisionToolkitError(
-    'runtime',
-    configured === undefined
-      ? 'vision-toolkit requires Python 3.11 or newer; tried python3, python, and the Windows py launcher'
-      : `vision-toolkit requires Python 3.11 or newer: ${configured}`,
-  )
+  if (configured !== undefined) {
+    throw new VisionToolkitError('runtime', `vision-toolkit requires Python 3.11 or newer: ${configured}`)
+  }
+  try {
+    const stateRoot = visionToolkitStateRoot()
+    await mkdir(stateRoot, { recursive: true })
+    const bundled = await acquireBundledPython(ctx, stateRoot, cwd, manifestOverride, requestImpl)
+    return {
+      command: bundled.command,
+      version: bundled.version,
+      major: Number.parseInt(bundled.version.split('.')[0] ?? '', 10),
+      minor: Number.parseInt(bundled.version.split('.')[1] ?? '', 10),
+    }
+  } catch (error) {
+    if (error instanceof VisionToolkitError) throw error
+    throw new VisionToolkitError(
+      'runtime',
+      'vision-toolkit requires Python 3.11 or newer; tried python3, python, and the Windows py launcher, and automatic bundled-Python preparation failed',
+      { cause: error },
+    )
+  }
 }
 
 /** Persistent per-DSH-home cache root shared by runtime and Web support files. */

package/src/runtime.ts

@@ -2082,8 +2082,13 @@ export class VisionToolkitRuntime {
             await response.body?.cancel().catch(() => {})
             if (response.ok) {
               service = { status: 'ok', detail: `Service responded at ${endpoint} (HTTP ${response.status})` }
-            } else if (response.status === 401 || response.status === 403) {
+            } 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) {

package/src/skill.ts

@@ -24,8 +24,8 @@ export const VISION_TOOLS_SKILL_CONTENT = readFileSync(
 /** Runtime skill registration mounted only after every native tool is ready. */
 export const VISION_TOOLS_SKILL: SkillRegistration = {
   name: VISION_TOOLS_SKILL_NAME,
-  description: 'Native DSH visual engineering tools adapted from agent-vision-toolkit: vision_glance, vision_ground, vision_detect, vision_trace, vision_crop, vision_pixel_diff, vision_long_screenshot_ocr, vision_extract_foreground, vision_dominant_colors, vision_html_screenshot, and upstream playbooks.',
-  whenToUse: 'Use whenever a task depends on image text/content, pixel coordinates, screenshot-to-UI reconstruction, visual regression, reusable image/SVG assets, diagram reconstruction, GUI operation from screenshots, or tall screenshot OCR.',
+  description: '把截图或设计图还原为 UI（网页、应用界面或组件），生成 HTML/CSS 或项目现有前端代码；也支持图片问答、长截图/聊天记录 OCR、元素定位与盘点、裁剪、前景提取、像素对比、取色、SVG 描摹和 HTML 转截图。当任务涉及图片理解、UI 还原/重建（rebuild or restore a UI from a screenshot）、视觉回归、像素坐标、基于截图的 GUI 操作、可复用图片/SVG 素材、图表还原或长截图 OCR 时使用。',
+  whenToUse: '任务依赖图片文字/内容、像素坐标、截图转 UI 重建、视觉回归、可复用图片/SVG 素材、图表还原、基于截图的 GUI 操作或长截图 OCR 时使用。',
   source: 'runtime',
   resourceBase: {
     kind: 'directory',