dsh-vision-router 2.2.7 → 2.3.0

package/lib/core-primitives.js

@@ -1,94 +1,51 @@
-import z from '@deepseek-ai/schemastery'
-import { mkdir, writeFile, readFile, unlink } from 'node:fs/promises'
+
+
 import path from 'node:path'
-import { tmpdir } from 'node:os'
-import { DeepSeekAdapter, resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek'
-import { getOrCreateAnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id'
+
 import { existsSync } from 'node:fs'
 import { execFile } from 'node:child_process'
 import { Worker } from 'node:worker_threads'
 import { createRequire } from 'node:module'
 import { pathToFileURL } from 'node:url'
 import { promisify } from 'node:util'
-import { appendPromptToImageOnlyMessage, fetchWithOpenAICompatibility } from './http-compat.js'
+import { fetchWithOpenAICompatibility } from './http-compat.js'
 import {
   directSessionAffinityHeaders,
-  isOfficialOpenCodeGoUrl,
-  openCodeSessionAffinityHeaderForUrl,
   rawSessionIdentity,
-  sessionIdentityOf,
 } from './session-affinity.js'
-import { runWithVisionSessionAffinity, streamWithVisionSessionAffinity } from './session-affinity-runtime.js'
+import { runWithVisionSessionAffinity } from './session-affinity-runtime.js'
 import {
-  routingCorrectionFor,
-  toAnthropicMessages,
   callAnthropicCompatible,
   anthropicMediaType,
 } from './catalog-corrections.js'
-import { createCachedUpdateChecker } from './update-check.js'
-import { probeLocalBackends } from './local-connection-probe.js'
-import { detectDshSelfUpdatePlan, runDshPluginUpdate } from './self-update.js'
+
 import {
-  classifyVisionFailure,
-  createDeadline,
   combineSignals,
-  createVisionCircuitBreaker,
-  createVisionTurnMemory,
-  buildVisionFailure,
-  ensureSentencePunctuation,
-  resultCodeForKinds,
   qwenKeyEndpointHint,
   kindForHttpStatus,
-  VISION_FAILURE_KINDS,
-  VISION_RESULT_CODES,
 } from './vision-resilience.js'
-import { currentVisionExecutionOrder } from './vision-execution-order.js'
-import { applyVisionExecutionOrder } from './vision-execution-order-apply.js'
-import { createHash, randomBytes } from 'node:crypto'
-import {
-  normalizeStructuredBootstrapResult,
-  structuredBootstrapMemory,
-  structuredBootstrapQuestion,
-} from './structured-bootstrap.js'
-import { planMixedBranches, renderMixedGuidance } from './mixed-router.js'
-import { renderDepthGuidance } from './depth-guidance.js'
-import { assertNoRepetitionLoop } from './repetition-guard.js'
-import { compareRgbaStreams } from './pixel-diff-stream.js'
+
+import { createHash } from 'node:crypto'
+
 import {
-  boundedOcrTiles,
   defaultImageResourceGovernor,
   estimateImageOperationBytes,
   scaleBox,
   scaledDimensions,
 } from './image-resource-governor.js'
-import { createSessionVisionIndex } from './session-vision-index.js'
-import { createSessionVisionStateStore } from './session-vision-state.js'
+
 import {
   ERROR_RESPONSE_MAX_BYTES,
-  METADATA_RESPONSE_MAX_BYTES,
   MODEL_RESPONSE_MAX_BYTES,
   readResponseJsonBounded,
   readResponseTextBounded,
 } from './http-body-limit.js'
-import { writeArtifactFile } from './artifact-boundary.js'
+
 import { stripTrailingSlashes } from './string-normalization.js'
 import { isOffloadedImageBlock, offloadedImagePlaceholder } from './image-offload-compat.js'
 import { proxyHostMatchesAny } from './proxy-routing.js'
-import { parseVersionComparator } from './version-range.js'
-import { captureWindowsDesktop } from './windows-desktop-capture.js'
-import {
-  sharpPromise,
-  sharpWarningHook,
-  registerSharpWarningHook,
-  warnSharp,
-  parseVersionParts,
-  compareVersionParts,
-  versionSatisfies,
-  sharpPeerRangeCache,
-  sharpPeerRange,
-  loadSharp,
-} from './sharp-runtime.js'
 
+import { loadSharp } from './sharp-runtime.js'
 export const IMAGE_EXTENSIONS = {
   png: 'image/png',
   jpg: 'image/jpeg',
@@ -109,7 +66,6 @@ export function mediaTypeOf(path) {
  */
 export { depthLimitFor } from './depth-guidance.js'
 
-
 /**
  * Detect the image format from magic bytes instead of the file extension.
  * Attachments are stored as content-addressed files WITHOUT an extension,
@@ -1268,29 +1224,52 @@ export function bitmapOfGray(raw, width, height, threshold = 128) {
   return out
 }
 
+function visionAbortReason(signal, fallback = 'vision operation aborted') {
+  if (signal?.reason instanceof Error) return signal.reason
+  const error = new Error(fallback)
+  error.name = 'AbortError'
+  error.code = 'ABORT_ERR'
+  return error
+}
+
+function throwIfVisionAborted(signal, fallback) {
+  if (signal?.aborted) throw visionAbortReason(signal, fallback)
+}
+
+function isVisionAbort(error, signal) {
+  return signal?.aborted === true || error?.name === 'AbortError' || error?.code === 'ABORT_ERR'
+}
+
 /** Vectorize an image buffer into an SVG string via potrace posterization. */
-export function posterizeSvg(bytes, steps = 4, fillStrategy = 'dominant', timeoutMs = 60000) {
+export function posterizeSvg(bytes, steps = 4, fillStrategy = 'dominant', timeoutMs = 60000, options = {}) {
   // potrace is CPU-bound and runs its computation in long synchronous
   // chunks: on the main thread it blocks the whole dsh process (other
   // sessions time out) and a setTimeout-based timeout can NEVER fire while
   // the loop is blocked. Run it in a worker thread instead — the main loop
   // stays responsive, and a timeout hard-terminates the worker.
+  const signal = options?.signal
   return new Promise((resolve, reject) => {
     let settled = false
     let worker
+    let timer
+    let abortListener
     const finish = (error, svg) => {
       if (settled) return
       settled = true
-      clearTimeout(timer)
+      if (timer !== undefined) clearTimeout(timer)
+      if (signal && abortListener) signal.removeEventListener?.('abort', abortListener)
       void worker?.terminate()
       if (error) reject(error)
       else resolve(svg)
     }
-    const timer = setTimeout(() => {
-      if (settled) return
-      settled = true
-      void worker?.terminate()
-      reject(
+    abortListener = () => finish(visionAbortReason(signal, 'potrace aborted'))
+    if (signal?.aborted) {
+      finish(visionAbortReason(signal, 'potrace aborted'))
+      return
+    }
+    signal?.addEventListener?.('abort', abortListener, { once: true })
+    timer = setTimeout(() => {
+      finish(
         new Error(
           'potrace timed out — the image is too large or too complex; crop it to the target region first',
         ),
@@ -1347,23 +1326,30 @@ export function posterizeSvg(bytes, steps = 4, fillStrategy = 'dominant', timeou
  * @param palette - [{ hex, count, share }] from quantizeColors, ordered by
  *   share descending.
  */
-export function posterizeSvgColor(data, info, palette, timeoutMs = 60000) {
+export function posterizeSvgColor(data, info, palette, timeoutMs = 60000, options = {}) {
+  const signal = options?.signal
   return new Promise((resolve, reject) => {
     let settled = false
     let worker
+    let timer
+    let abortListener
     const finish = (error, svg) => {
       if (settled) return
       settled = true
-      clearTimeout(timer)
+      if (timer !== undefined) clearTimeout(timer)
+      if (signal && abortListener) signal.removeEventListener?.('abort', abortListener)
       void worker?.terminate()
       if (error) reject(error)
       else resolve(svg)
     }
-    const timer = setTimeout(() => {
-      if (settled) return
-      settled = true
-      void worker?.terminate()
-      reject(
+    abortListener = () => finish(visionAbortReason(signal, 'color trace aborted'))
+    if (signal?.aborted) {
+      finish(visionAbortReason(signal, 'color trace aborted'))
+      return
+    }
+    signal?.addEventListener?.('abort', abortListener, { once: true })
+    timer = setTimeout(() => {
+      finish(
         new Error(
           'color trace timed out — the image is too large or too complex; crop it to the target region first',
         ),
@@ -1473,13 +1459,21 @@ export function resolveVisionOcrEngine(requestedEngine, configuredEngine = 'auto
 }
 
 /** OCR image bytes with a local tesseract binary (chi_sim+eng) when available. */
-export async function ocrWithTesseract(bytes, timeoutMs = 60000) {
-  const exec = promisify(execFile)
+export async function ocrWithTesseract(bytes, timeoutMs = 60000, options = {}) {
+  const exec = typeof options.exec === 'function' ? options.exec : promisify(execFile)
+  const signal = options.signal
+  throwIfVisionAborted(signal, 'tesseract OCR aborted')
   const { stdout } = await exec(
     'tesseract',
     ['stdin', 'stdout', '-l', 'chi_sim+eng', '--psm', '6'],
-    { timeout: Math.min(timeoutMs, 60000), maxBuffer: 32 * 1024 * 1024, input: bytes },
+    {
+      timeout: Math.min(timeoutMs, 60000),
+      maxBuffer: 32 * 1024 * 1024,
+      input: bytes,
+      ...(signal === undefined ? {} : { signal }),
+    },
   )
+  throwIfVisionAborted(signal, 'tesseract OCR aborted')
   return String(stdout ?? '')
 }
 
@@ -1543,6 +1537,7 @@ export function selectTesseractOcrCandidate(candidates) {
 
 export async function ocrWithTesseractAdaptive(bytes, timeoutMs = 12000, options = {}) {
   const exec = typeof options.exec === 'function' ? options.exec : promisify(execFile)
+  const signal = options.signal
   const requestedBudget = Number(timeoutMs)
   const budgetMs = Number.isFinite(requestedBudget) && requestedBudget > 0
     ? Math.min(60000, requestedBudget)
@@ -1551,20 +1546,25 @@ export async function ocrWithTesseractAdaptive(bytes, timeoutMs = 12000, options
   const attemptedPsms = []
   const remaining = () => Math.max(1, budgetMs - (Date.now() - started))
   const run = async (psm) => {
+    throwIfVisionAborted(signal, 'adaptive tesseract OCR aborted')
     attemptedPsms.push(psm)
     const common = ['stdin', 'stdout', '-l', 'chi_sim+eng', '--psm', String(psm)]
     const execOptions = () => ({
       timeout: remaining(),
       maxBuffer: 32 * 1024 * 1024,
       input: bytes,
+      ...(signal === undefined ? {} : { signal }),
     })
     const { stdout: plain } = await exec('tesseract', common, execOptions())
+    throwIfVisionAborted(signal, 'adaptive tesseract OCR aborted')
     const text = String(plain ?? '').trim()
     if (text === '') return assessTesseractOcr('', '', psm)
     try {
       const { stdout: tsv } = await exec('tesseract', [...common, 'tsv'], execOptions())
+      throwIfVisionAborted(signal, 'adaptive tesseract OCR aborted')
       return assessTesseractOcr(text, String(tsv ?? ''), psm)
-    } catch {
+    } catch (error) {
+      if (isVisionAbort(error, signal)) throw error
       return { psm, text, words: 0, quality: 0, riskyTokens: [], uncertain: true }
     }
   }
@@ -1577,7 +1577,8 @@ export async function ocrWithTesseractAdaptive(bytes, timeoutMs = 12000, options
     if (Date.now() - started >= budgetMs) break
     try {
       candidates.push(await run(psm))
-    } catch {
+    } catch (error) {
+      if (isVisionAbort(error, signal)) throw error
       // Keep the first successful local OCR result when an optional review pass fails.
     }
   }
@@ -2096,6 +2097,7 @@ export async function callLocalBackend(provider, messages, options = {}) {
         maxTokens,
         signal: options.signal,
         allowKeyless: true,
+        providerTransport: options.providerTransport,
         system: system.join('\n').trim(),
         ...(rawSessionIdentity(options.sessionId) === undefined
           ? {}
@@ -2109,6 +2111,7 @@ export async function callLocalBackend(provider, messages, options = {}) {
   }
   return callOpenAICompatible(provider, messages, {
     maxTokens,
+    providerTransport: options.providerTransport,
     signal: options.signal,
     ...(rawSessionIdentity(options.sessionId) === undefined
       ? {}
@@ -2291,7 +2294,7 @@ export async function callOpenAICompatible(provider, messages, options = {}) {
         body: JSON.stringify(body),
         ...(options.signal === undefined ? {} : { signal: options.signal }),
       },
-      { active: true, providerName: provider.name },
+      { active: true, providerName: provider.name, providerTransport: options.providerTransport },
     )
   const response = await request()
   if (!response.ok) {
@@ -2414,61 +2417,6 @@ async function visionAnswer(llm, options) {
   })
 }
 
-/** Environment shim for `resolveAdapterOptions`: `{ get: (name) => ({ value }) }`. */
-export function launchEnvironmentLike(env) {
-  const map = env ?? {}
-  return {
-    get(name) {
-      return Object.prototype.hasOwnProperty.call(map, name) ? { value: map[name] } : undefined
-    },
-  }
-}
-
-/**
- * Legacy-only DeepSeek reconstruction for Host contracts that do not own the
- * official provider lifecycle. Modern Hosts keep `deepseek-official` Host-owned
- * because request-local attachment/file/image-access seams cannot be cloned
- * safely here. Remove this helper when the legacy takeover window is retired.
- */
-export function createNativeDeepSeekAdapter(ctx) {
-  const env = launchEnvironmentLike(
-    typeof process !== 'undefined' && process.env ? process.env : {},
-  )
-  const options = () => {
-    let raw
-    try {
-      const settings = ctx.get('settings')
-      raw = settings && settings.get ? settings.get('llm-deepseek') : undefined
-    } catch {
-      raw = undefined
-    }
-    return resolveAdapterOptions(raw ?? {}, env)
-  }
-  const resolveApiKey = async (connection) => {
-    const ref = connection.apiKeyEnv
-    const credentials = ctx.get('credentials')
-    if (credentials !== undefined) {
-      try {
-        const hit = await credentials.resolve(ref)
-        if (hit && typeof hit.value === 'string' && hit.value.length > 0) return hit.value
-      } catch {
-        /* fall through to the environment */
-      }
-    }
-    const ambient = env.get(ref)
-    if (ambient !== undefined && typeof ambient.value === 'string' && ambient.value.length > 0) {
-      return ambient.value
-    }
-    throw new Error(`vision-router: no API key for the native DeepSeek route (${ref})`)
-  }
-  let userId
-  const resolveUserId = () => {
-    if (userId === undefined) userId = getOrCreateAnonymousUserId()
-    return userId
-  }
-  return new DeepSeekAdapter({ options, resolveApiKey, resolveUserId })
-}
-
 /**
  * dsh-vision 并入：本地识别提示模板。
  * `plain` = 平铺描述；`structured` = 结构化识别（【初步判断】/【细节】/
@@ -2595,7 +2543,11 @@ export async function buildInstantLocalMap(ctx, messages, provider, options = {}
                 const text = await callLocalBackend(
                   currentProvider,
                   [{ role: 'user', content }],
-                  { maxTokens: currentProvider.maxTokens ?? 2048, signal },
+                  {
+                    maxTokens: currentProvider.maxTokens ?? 2048,
+                    signal,
+                    providerTransport: options.providerTransport,
+                  },
                 )
                 return { id, ok: true, text, elapsedMs: Date.now() - startedAt }
               } catch (error) {
@@ -2673,7 +2625,7 @@ export async function buildInstantLocalMap(ctx, messages, provider, options = {}
  * 标记；provider/style/timeout 也可以是 getter，让设置页保存后下一次 stream
  * 立即读取新值，无需重启或重建 adapter。
  */
-export function createWrapperStreamBody(ctx, { imageMemory, delegateProvider, preserveImageInput, instantLocal, instantLocalStyle, instantLocalTimeoutMs, instantLocalMaxPixels }) {
+export function createWrapperStreamBody(ctx, { imageMemory, delegateProvider, preserveImageInput, instantLocal, instantLocalStyle, instantLocalTimeoutMs, instantLocalMaxPixels, providerTransport }) {
   // issue #103: the reasoning level is a per-session picker choice (the chat
   // page's bottom-right selector), but the host can drop reasoningEffort from
   // the later steps of a multi-step turn once the twin metadata lacks a
@@ -2709,6 +2661,7 @@ export function createWrapperStreamBody(ctx, { imageMemory, delegateProvider, pr
               memory: imageMemory,
               timeoutMs: liveValue(instantLocalTimeoutMs),
               downscaleMaxPixels: liveValue(instantLocalMaxPixels),
+              providerTransport,
             })
           : undefined
       // Rewrite image blocks ANYWHERE in the model input — including inside
@@ -2801,7 +2754,7 @@ export function createWrapperStreamBody(ctx, { imageMemory, delegateProvider, pr
  * route). Any other route name (e.g. the `deepseek-vision` alias) advertises
  * no models, so it stays functional but invisible in the picker.
  */
-export function createStealthAdapter(ctx, { native, imageMemory, pairs, chainRoute, delegateProvider, instantLocal, instantLocalStyle, instantLocalTimeoutMs, instantLocalMaxPixels }) {
+export function createStealthAdapter(ctx, { native, imageMemory, pairs, chainRoute, delegateProvider, instantLocal, instantLocalStyle, instantLocalTimeoutMs, instantLocalMaxPixels, providerTransport }) {
   return {
     providerInfo(provider) {
       return { id: provider, name: 'DeepSeek' }
@@ -2822,7 +2775,7 @@ export function createStealthAdapter(ctx, { native, imageMemory, pairs, chainRou
       const base = await native.resolveModel(provider, model, signal)
       return { ...base, provider, inputModalities: ['text', 'image'] }
     },
-    ...createWrapperStreamBody(ctx, { imageMemory, delegateProvider, instantLocal, instantLocalStyle, instantLocalTimeoutMs, instantLocalMaxPixels }),
+    ...createWrapperStreamBody(ctx, { imageMemory, delegateProvider, instantLocal, instantLocalStyle, instantLocalTimeoutMs, instantLocalMaxPixels, providerTransport }),
   }
 }
 

package/lib/desktop-screenshot-tool.js

@@ -0,0 +1,262 @@
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { readFile, unlink } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { promisify } from 'node:util'
+
+import {
+  callLocalBackend,
+  localDescribePrompt,
+  localProvidersOf,
+  toOpenAIContent,
+} from './core-primitives.js'
+import { loadSharp } from './sharp-runtime.js'
+import { captureWindowsDesktop } from './windows-desktop-capture.js'
+import { currentVisionTurnBudgetSignal } from './turn-budget-context.js'
+import { combineSignals } from './vision-resilience.js'
+
+function abortReason(signal, fallback = 'vision_screenshot aborted') {
+  if (signal?.reason instanceof Error) return signal.reason
+  const error = new Error(fallback)
+  error.name = 'AbortError'
+  error.code = 'ABORT_ERR'
+  return error
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortReason(signal)
+}
+
+function isAbortFailure(error) {
+  return error?.name === 'AbortError' || error?.code === 'ABORT_ERR'
+}
+
+export async function captureDesktopPng(target, timeoutMs, signal, options = {}) {
+  const platform = options.platform ?? process.platform
+  const run = options.execFileAsync ?? promisify(execFile)
+  const captureWindows = options.captureWindowsDesktop ?? captureWindowsDesktop
+  throwIfAborted(signal)
+  if (platform === 'win32') {
+    // Own DPI-aware capture at the implementation boundary rather than
+    // depending on a process-wide execFile argument rewrite.
+    await captureWindows(target, { timeoutMs, signal })
+    throwIfAborted(signal)
+    return platform
+  }
+  if (platform === 'darwin') {
+    // Without -m, screencapture writes one file per display while the tool owns
+    // exactly one artifact path, so request the main display explicitly.
+    await run('screencapture', ['-x', '-m', target], {
+      timeout: timeoutMs,
+      windowsHide: true,
+      ...(signal === undefined ? {} : { signal }),
+    })
+    throwIfAborted(signal)
+    return platform
+  }
+  try {
+    await run('import', ['-window', 'root', target], {
+      timeout: timeoutMs,
+      ...(signal === undefined ? {} : { signal }),
+    })
+  } catch (error) {
+    if (signal?.aborted || isAbortFailure(error)) throw error
+    await run('scrot', [target], {
+      timeout: timeoutMs,
+      ...(signal === undefined ? {} : { signal }),
+    })
+  }
+  throwIfAborted(signal)
+  return platform
+}
+
+async function downscaleForIdentification(data) {
+  try {
+    const sharp = await loadSharp()
+    if (!sharp) return data
+    const downscaled = await sharp(data, { failOn: 'none' })
+      .resize({ width: 1280, height: 1280, fit: 'inside', withoutEnlargement: true })
+      .png()
+      .toBuffer()
+    return downscaled.length > 0 && downscaled.length < data.length ? downscaled : data
+  } catch {
+    return data
+  }
+}
+
+async function identifyDesktopCapture(data, {
+  current,
+  timeoutMs,
+  instantLocalStyle,
+  providerTransport,
+  signal,
+} = {}) {
+  throwIfAborted(signal)
+  const locals = localProvidersOf(current())
+  if (locals.length === 0) {
+    return {
+      identifyError: 'no local vision backend enabled (localOllama / localLmStudio); enable one to use identify',
+    }
+  }
+
+  const startedAt = Date.now()
+  const identifyBytes = await downscaleForIdentification(data)
+  throwIfAborted(signal)
+  const result = {}
+  if (identifyBytes !== data) {
+    result.identifyDownscaled = {
+      originalBytes: data.length,
+      sentBytes: identifyBytes.length,
+    }
+  }
+
+  const content = toOpenAIContent(
+    [{ type: 'image', attachment: { mediaType: 'image/png', data: identifyBytes } }],
+    () => identifyBytes,
+  )
+  content.push({ type: 'text', text: localDescribePrompt(instantLocalStyle()) })
+
+  const deadlineAt = Date.now() + timeoutMs()
+  const errors = []
+  for (let index = 0; index < locals.length; index++) {
+    throwIfAborted(signal)
+    const local = locals[index]
+    const remainingMs = deadlineAt - Date.now()
+    if (remainingMs <= 0) break
+    // Reserve a fair share for later local backends. A connected but hung
+    // first backend must not consume the entire fallback budget.
+    const roundBudgetMs = Math.max(1, Math.floor(remainingMs / (locals.length - index)))
+    const controller = new AbortController()
+    const roundSignal = signal
+      ? AbortSignal.any([signal, controller.signal])
+      : controller.signal
+    const timer = setTimeout(() => controller.abort(), roundBudgetMs)
+    try {
+      const identified = await callLocalBackend(
+        local,
+        [{ role: 'user', content }],
+        {
+          maxTokens: local.maxTokens ?? 2048,
+          signal: roundSignal,
+          providerTransport,
+        },
+      )
+      if (typeof identified === 'string' && identified.trim() !== '') {
+        result.identified = identified.trim()
+        result.identifiedBy = local.name
+        result.elapsedSec = Math.max(1, Math.round((Date.now() - startedAt) / 1000))
+        return result
+      }
+      errors.push(`${local.name}: empty response`)
+    } catch (error) {
+      if (signal?.aborted) throw abortReason(signal)
+      errors.push(`${local.name}: ${error && error.message ? error.message : String(error)}`)
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  result.identifyError = errors.length > 0
+    ? errors.join('; ').slice(0, 1000)
+    : 'local vision identification timed out before a backend could respond'
+  return result
+}
+
+/**
+ * Build the privacy-sensitive desktop screenshot tool definition.
+ *
+ * Tool registration/exposure remains owned by Core + LocalVisionStabilizer;
+ * this module owns only the platform capture and optional local-recognition
+ * implementation behind that existing permission boundary.
+ */
+export function createDesktopScreenshotTool({
+  current,
+  timeoutMs,
+  saveArtifact,
+  stringOutput,
+  instantLocalStyle,
+  providerTransport,
+  captureDesktop = captureDesktopPng,
+} = {}) {
+  if (
+    typeof current !== 'function' ||
+    typeof timeoutMs !== 'function' ||
+    typeof saveArtifact !== 'function' ||
+    typeof captureDesktop !== 'function'
+  ) {
+    throw new TypeError('desktop screenshot tool requires live config, timeout, artifact and capture callbacks')
+  }
+  if (typeof instantLocalStyle !== 'function') {
+    throw new TypeError('desktop screenshot tool requires a live local describe style')
+  }
+
+  return {
+    name: 'vision_screenshot',
+    description:
+      'Capture the user\'s desktop screen as a PNG artifact (the virtual screen on Windows; the main display on macOS; the root display on Linux). ' +
+      'Windows: per-monitor-DPI-aware PowerShell capture; macOS: screencapture; Linux: ImageMagick import (falls back to scrot; either command must be installed). ' +
+      'This privacy-sensitive tool is disabled by default and works only after the user explicitly enables Desktop screenshot in Vision Router settings. ' +
+      'Use it when you need to see what is on the user\'s screen right now — e.g. their current GUI, an app, or a page outside this browser. ' +
+      'Optional identify=true also runs local recognition on the capture using the enabled local backends (Ollama, then LM Studio) and returns the description alongside the path.',
+    parameters: {
+      type: 'object',
+      properties: {
+        identify: {
+          type: 'boolean',
+          description:
+            'Also recognize the captured screen with enabled local vision backends (Ollama, then LM Studio) and return the description text with the path. Default false.',
+        },
+      },
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      if (current().desktopScreenshot !== true) {
+        throw new Error(
+          'vision_screenshot is disabled; enable Desktop screenshot explicitly in Vision Router settings before use',
+        )
+      }
+
+      const tmp = path.join(
+        tmpdir(),
+        `vision-screenshot-${Date.now()}-${Math.floor(Math.random() * 1e9)}.png`,
+      )
+      try {
+        const signal = combineSignals(currentVisionTurnBudgetSignal(), exec?.signal)
+        throwIfAborted(signal)
+        const platform = await captureDesktop(tmp, timeoutMs(), signal)
+        throwIfAborted(signal)
+        if (!existsSync(tmp)) {
+          throw new Error(
+            `vision_screenshot: no output produced on ${platform} (is a screen available?)`,
+          )
+        }
+        const data = await readFile(tmp, signal === undefined ? undefined : { signal })
+        throwIfAborted(signal)
+        let identification
+        if (args.identify === true) {
+          identification = await identifyDesktopCapture(data, {
+            current,
+            timeoutMs,
+            instantLocalStyle,
+            providerTransport,
+            signal,
+          })
+        }
+        // Artifact publication is the final commit point. If optional local
+        // identification is cancelled, no successful screenshot result should
+        // already have escaped into the managed artifact store.
+        throwIfAborted(signal)
+        const target = await saveArtifact(exec, `screenshot-${Date.now()}.png`, data)
+        return JSON.stringify({
+          path: target,
+          bytes: data.length,
+          ...(identification ?? {}),
+        })
+      } finally {
+        try { await unlink(tmp) } catch { /* best effort cleanup */ }
+      }
+    },
+  }
+}