dsh-tool-vision 0.9.3 → 0.9.4

package/lib/vision-tools.js

@@ -1,2485 +1,2485 @@
-// dsh-tool-vision — pixel-level vision tools (ported from dsh-vision-router).
-//
-// The 14 vision_* tools share ONE configured OpenAI-compatible endpoint
-// (the plugin's own baseURL/apiKey/model settings — the same GLM endpoint
-// inspect_image uses). No provider chain, no local models, no fallbacks:
-// the router's tool *semantics* (prompts, parameter contracts, pixel
-// post-processing) are kept; its routing/resilience machinery is not.
-//
-// Everything here is unit-testable without a harness: the only injected
-// dependencies are `ctx` (attachments/fs services), `getConfig` (live
-// settings) and `exec` (tool execution context).
-
-import { createHash } from 'node:crypto'
-import { join, dirname, isAbsolute, relative as relativePath, sep, win32 as winPath } from 'node:path'
-import { existsSync } from 'node:fs'
-import { mkdir as mkdirP, writeFile as writeFileP, readFile as readFileP, rm as rmP, stat as statP } from 'node:fs/promises'
-import { Worker } from 'node:worker_threads'
-import { execFile } from 'node:child_process'
-import { promisify } from 'node:util'
-import { pathToFileURL } from 'node:url'
-import { createRequire } from 'node:module'
-import { sessionHeaders } from './session-header.js'
-
-// ── image formats ──────────────────────────────────────────────────────────
-
-export const IMAGE_EXTENSIONS = {
-  png: 'image/png',
-  jpg: 'image/jpeg',
-  jpeg: 'image/jpeg',
-  webp: 'image/webp',
-  gif: 'image/gif',
-  bmp: 'image/bmp',
-  avif: 'image/avif',
-  svg: 'image/svg+xml',
-  ico: 'image/x-icon',
-}
-
-const EXT_BY_MEDIA = {
-  'image/png': '.png',
-  'image/jpeg': '.jpg',
-  'image/webp': '.webp',
-  'image/gif': '.gif',
-  'image/bmp': '.bmp',
-  'image/avif': '.avif',
-  'image/svg+xml': '.svg',
-  'image/x-icon': '.ico',
-}
-
-export function mediaTypeOf(path) {
-  const match = String(path).toLowerCase().match(/\.([a-z0-9]+)$/)
-  return match ? IMAGE_EXTENSIONS[match[1]] : undefined
-}
-
-/**
- * Detect the image format from magic bytes instead of the file extension.
- * Attachments are stored as content-addressed files WITHOUT an extension,
- * so extension-based detection rejects them; the pixel tools must sniff.
- */
-export function sniffMediaType(bytes) {
-  if (!bytes || bytes.length < 12) return undefined
-  const head = (offset, count) => {
-    const parts = []
-    for (let i = offset; i < offset + count; i++) parts.push(bytes[i].toString(16).padStart(2, '0'))
-    return parts.join('')
-  }
-  if (head(0, 8) === '89504e470d0a1a0a') return 'image/png'
-  if (head(0, 3) === 'ffd8ff') return 'image/jpeg'
-  const riff = head(0, 4)
-  const webp = head(8, 4)
-  if (riff === '52494646' && webp === '57454250') return 'image/webp'
-  if (riff === '47494638') return 'image/gif' // GIF87a / GIF89a
-  return undefined
-}
-
-// ── input resolution ───────────────────────────────────────────────────────
-
-export function basenameOf(path) {
-  const parts = String(path).split('/')
-  return parts[parts.length - 1] || undefined
-}
-
-/**
- * True when the string is a durable attachment id such as "sha256:<hex>" —
- * the form the harness uses for uploaded images.
- */
-export function isAttachmentIdInput(input) {
-  return typeof input === 'string' && /^[a-z0-9]+:[0-9a-f]{32,}$/i.test(input.trim())
-}
-
-/** Cross-platform absolute-path test (posix drive-relative forms included). */
-export function isAbsolutePath(input) {
-  const value = String(input ?? '')
-  return isAbsolute(value) || winPath.isAbsolute(value)
-}
-
-/** Largest local image accepted by the pixel tools, in bytes. */
-export const MAX_IMAGE_BYTES = 20 * 1024 * 1024
-
-/** Resolve one tool argument (local path or attachment id) to image bytes. */
-export async function readImageBytes(ctx, exec, imagePath) {
-  const input = String(imagePath ?? '')
-  let bytes
-  let storedMediaType
-  if (isAttachmentIdInput(input)) {
-    const attachments = ctx.get('attachments')
-    if (attachments === undefined) {
-      throw new Error('tool-vision: the attachment service is not available in this deployment')
-    }
-    const session = exec && exec.agent && exec.agent.session
-    const ref = lookupAttachment(session, input.trim())
-    if (ref === undefined) {
-      throw new Error(
-        `tool-vision: unknown attachment id "${input}" (it must come from an image uploaded in this conversation)`,
-      )
-    }
-    let stored
-    try {
-      stored = await attachments.readImage(ref)
-    } catch (error) {
-      throw new Error(
-        `tool-vision: failed to read attachment ${input} (${error && error.message ? error.message : String(error)})`,
-      )
-    }
-    bytes = stored.data
-    if (bytes && bytes.length > MAX_IMAGE_BYTES) {
-      throw new Error(
-        `tool-vision: image too large: ${input} (${bytes.length} bytes, limit ${MAX_IMAGE_BYTES})`,
-      )
-    }
-    if (stored.ref && typeof stored.ref.mediaType === 'string') {
-      storedMediaType = stored.ref.mediaType
-    }
-  } else {
-    const fsService = ctx.get('fs')
-    if (fsService === undefined) throw new Error('tool-vision: the fs service is not available')
-    const resolved = await fsService.resolve(input)
-    const target = toRealPath(fsService, resolved)
-    // Second line of defense beyond the fs sandbox: a relative input must
-    // resolve inside the session workspace (refuse ../ escapes).
-    if (!isAbsolutePath(input)) {
-      const root = workspaceOf(exec)
-      const relative = relativePath(root, target)
-      if (relative === '..' || relative.startsWith('..' + sep) || isAbsolutePath(relative)) {
-        throw new Error(`tool-vision: path escapes the workspace: ${input}`)
-      }
-    }
-    // Pre-check size BEFORE reading: a huge file must not be buffered whole
-    // (readFileP has no limit and would OOM the process).
-    const info = await statP(target).catch(() => null)
-    if (info !== null && info.size > MAX_IMAGE_BYTES) {
-      throw new Error(
-        `tool-vision: image too large: ${input} (${info.size} bytes, limit ${MAX_IMAGE_BYTES})`,
-      )
-    }
-    bytes = await readFileP(target)
-    if (bytes.length > MAX_IMAGE_BYTES) {
-      throw new Error(`tool-vision: image too large: ${input} (${bytes.length} bytes, limit ${MAX_IMAGE_BYTES})`)
-    }
-  }
-  const mediaType = sniffMediaType(bytes) ?? storedMediaType ?? mediaTypeOf(input)
-  if (mediaType === undefined) {
-    throw new Error(`unsupported image format ${input} (png/jpeg/webp/gif only)`)
-  }
-  return { bytes, mediaType }
-}
-
-/** Find an uploaded attachment ref in the session's recorded upload index. */
-export function lookupAttachment(session, attachmentId) {
-  if (!session) return undefined
-  const recorded = session.recordedUploads
-  if (recorded) {
-    const ref = recorded.get ? recorded.get(attachmentId) : undefined
-    if (ref) return ref
-  }
-  const events = session.events ?? []
-  for (const event of events) {
-    const data = event && event.data
-    if (!data) continue
-    for (const block of Array.isArray(data.content) ? data.content : []) {
-      if (block && block.type === 'image' && block.attachment && block.attachment.attachmentId === attachmentId) {
-        return block.attachment
-      }
-    }
-    const message = data.message
-    if (message && Array.isArray(message.content)) {
-      for (const block of message.content) {
-        if (block && block.type === 'image' && block.attachment && block.attachment.attachmentId === attachmentId) {
-          return block.attachment
-        }
-      }
-    }
-  }
-  return undefined
-}
-
-/** Normalize an fs.resolve() result (string or { targetKey, displayPath }) to a real path. */
-export function toRealPath(fsService, resolved) {
-  if (typeof resolved === 'string') return resolved
-  if (typeof fsService?.processPath === 'function') {
-    const p = fsService.processPath(resolved)
-    if (typeof p === 'string' && p !== '') return p
-  }
-  const key = resolved?.targetKey
-  return typeof key === 'string' && key !== '' ? key : String(resolved ?? '')
-}
-
-// ── sharp (lazy) ───────────────────────────────────────────────────────────
-
-let sharpPromise = null
-
-/** Lazily load sharp; resolves null when the host cannot provide it. */
-export function loadSharp() {
-  if (!sharpPromise) {
-    sharpPromise = import('sharp')
-      .then((mod) => mod.default ?? mod)
-      .catch(() => null)
-  }
-  return sharpPromise
-}
-
-/**
- * Downscale an image so its pixel count stays within maxPixels (router
- * default 4MP). Returns the original buffer when the image is already small
- * enough or when sharp is unavailable — pixel tools degrade gracefully
- * instead of failing.
- */
-export async function downscaleImage(bytes, maxPixels) {
-  if (!bytes || bytes.length === 0) return bytes
-  const sharp = await loadSharp()
-  if (!sharp) return bytes
-  try {
-    const image = sharp(bytes, { failOn: 'none' })
-    const meta = await image.metadata()
-    const width = Number(meta.width) || 0
-    const height = Number(meta.height) || 0
-    if (width <= 0 || height <= 0 || width * height <= maxPixels) return bytes
-    const scale = Math.sqrt(maxPixels / (width * height))
-    const resized = await image
-      .resize({
-        width: Math.max(1, Math.floor(width * scale)),
-        height: Math.max(1, Math.floor(height * scale)),
-        fit: 'inside',
-      })
-      .toBuffer()
-    return resized && resized.length > 0 ? resized : bytes
-  } catch {
-    return bytes
-  }
-}
-
-/** Image dimensions via sharp (0/0 when unavailable). */
-export async function imageDims(bytes) {
-  const sharp = await loadSharp()
-  if (!sharp) return { width: 0, height: 0 }
-  try {
-    const meta = await sharp(bytes, { failOn: 'none' }).metadata()
-    return { width: meta.width ?? 0, height: meta.height ?? 0 }
-  } catch {
-    return { width: 0, height: 0 }
-  }
-}
-
-// ── content-hash cache ─────────────────────────────────────────────────────
-
-export function sha256Of(bytes) {
-  return createHash('sha256').update(bytes).digest('hex')
-}
-
-/** Small LRU+TTL cache for repeated image+question calls (router semantics). */
-export function createCache(maxEntries, ttlMs) {
-  const map = new Map()
-  return {
-    get(key) {
-      const entry = map.get(key)
-      if (!entry) return undefined
-      if (entry.expires <= Date.now()) {
-        map.delete(key)
-        return undefined
-      }
-      map.delete(key)
-      map.set(key, entry)
-      return entry.value
-    },
-    set(key, value) {
-      if (map.size >= maxEntries) {
-        const oldest = map.keys().next().value
-        if (oldest !== undefined) map.delete(oldest)
-      }
-      map.set(key, { value, expires: Date.now() + ttlMs })
-    },
-    size() {
-      return map.size
-    },
-    clear() {
-      map.clear()
-    },
-  }
-}
-
-// ── artifacts (tool outputs land in the session workspace) ─────────────────
-
-export function workspaceOf(exec) {
-  const session = exec && exec.agent && exec.agent.session
-  const cwd = session && session.header && session.header.cwd
-  return typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd()
-}
-
-/** Write a tool artifact under <workspace>/.dsh-tool-vision/ and return its path.
- *  Recursive: long-OCR writes stem/chunk-*.png subdirectories. */
-export async function writeArtifact(exec, relPath, data) {
-  const root = workspaceOf(exec)
-  const target = join(root, '.dsh-tool-vision', relPath)
-  await mkdirP(dirname(target), { recursive: true })
-  await writeFileP(target, data)
-  return target
-}
-
-/** Build an artifact filename stem from an input image reference. */
-export function artifactStemOf(imagePath, suffix) {
-  const base = String(basenameOf(imagePath) ?? 'image')
-    .replace(/\.(png|jpe?g|webp|gif)$/i, '')
-    .replace(/[^a-zA-Z0-9._-]/g, '-')
-    .slice(0, 32)
-  const fingerprint = createHash('sha256').update(String(imagePath)).digest('hex').slice(0, 8)
-  return `${base || 'image'}-${fingerprint}-${suffix}`
-}
-
-// ── JSON & prompt helpers ──────────────────────────────────────────────────
-
-const MAX_EXTRACT_JSON_CHARS = 200_000
-
-/** Extract the first balanced JSON value ({...} or [...]) from model output. */
-export function extractJson(text) {
-  const source = String(text ?? '')
-  const bounded = source.length > MAX_EXTRACT_JSON_CHARS
-    ? source.slice(0, MAX_EXTRACT_JSON_CHARS)
-    : source
-  const fenced = bounded.match(/```(?:json)?\s*([\s\S]*?)```/i)
-  const candidate = fenced ? fenced[1] : bounded
-  const start = candidate.search(/[[{]/)
-  if (start === -1) return undefined
-  const stack = []
-  let inString = false
-  let escaped = false
-  for (let index = start; index < candidate.length; index++) {
-    const char = candidate[index]
-    if (inString) {
-      if (escaped) escaped = false
-      else if (char === '\\') escaped = true
-      else if (char === '"') inString = false
-      continue
-    }
-    if (char === '"') {
-      inString = true
-      continue
-    }
-    if (char === '{') stack.push('}')
-    else if (char === '[') stack.push(']')
-    else if (char === '}' || char === ']') {
-      if (stack.length === 0 || stack.pop() !== char) return undefined
-      if (stack.length === 0) {
-        try {
-          const value = JSON.parse(candidate.slice(start, index + 1))
-          return typeof value === 'object' && value !== null ? value : undefined
-        } catch {
-          return undefined
-        }
-      }
-    }
-  }
-  return undefined
-}
-
-/** Legacy alias for callers of the earlier draft API. */
-export function parseModelJson(text) {
-  return extractJson(text)
-}
-
-/** Parse "x1,y1,x2,y2" (string) or {x1,y1,x2,y2} (object) into a valid pixel box. */
-export function parseBox(value) {
-  let box
-  if (typeof value === 'string') {
-    const parts = value.split(',').map((part) => Number(part.trim()))
-    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) return undefined
-    box = { x1: parts[0], y1: parts[1], x2: parts[2], y2: parts[3] }
-  } else if (value && typeof value === 'object') {
-    box = { x1: value.x1, y1: value.y1, x2: value.x2, y2: value.y2 }
-  } else {
-    return undefined
-  }
-  const { x1, y1, x2, y2 } = box
-  if (![x1, y1, x2, y2].every((n) => Number.isInteger(n))) return undefined
-  if (x1 < 0 || y1 < 0 || x2 <= x1 || y2 <= y1) return undefined
-  return { x1, y1, x2, y2 }
-}
-
-/** Fixed JSON contract for vision_detect. */
-export function visionDetectInstruction(target, width, height) {
-  return (
-    `The image is ${width}x${height} pixels. Find every "${String(target).slice(0, 300)}" in it. ` +
-    'Return ONE JSON object and nothing else, shaped EXACTLY as:\n' +
-    '{"elements":[{"label":"<short element name>","box":{"x1":0,"y1":0,"x2":0,"y2":0}},...]}\n' +
-    '- "elements" is a numbered list (array order = element number) of every match, from top-left to bottom-right in reading order;\n' +
-    '- every box is the tight bounding box in ORIGINAL image pixels, integers, 0 <= x1 < x2 <= ' +
-    `${width}, 0 <= y1 < y2 <= ${height}` +
-    ';\n- if nothing matches, return {"elements":[]}.'
-  )
-}
-
-/** Structured JSON contract for vision_describe's json:true mode. */
-export function describeStructuredInstruction(question) {
-  return (
-    `Look at the image and answer the question: 「${String(question).slice(0, 1500)}」. ` +
-    'Return ONE JSON object and nothing else, shaped EXACTLY as:\n' +
-    '{"summary":"<1-2 sentence answer to the question>",' +
-    '"layout":[{"region":"<e.g. top-left / header / center>","content":"<what is there>"}],' +
-    '"entities":[{"type":"<button|input|text|image|link|icon|other>","label":"<name or text>"}],' +
-    '"text":"<the full text visible in the image, transcribed in reading order, as faithful as possible>"}\n' +
-    '- "layout" lists the main regions in reading order (top-to-bottom, left-to-right);\n' +
-    '- "entities" lists notable elements; use only the listed type values;\n' +
-    '- "text" is the verbatim transcription; write "" when the image contains no text.'
-  )
-}
-
-/** Shared vision_describe prompt. */
-export function visionDescribePrompt(question, wantJson = false) {
-  const raw = String(question ?? '').trim()
-  const text = raw === ''
-    ? 'Describe the image accurately and answer based only on visible content.'
-    : raw
-  return wantJson ? text + '\n\n' + describeStructuredInstruction(text) : text
-}
-
-/** Normalize a vision_detect answer into the canonical shape, clamping boxes. */
-export function normalizeDetectResult(parsed, width, height) {
-  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.elements)) return undefined
-  const clamp = (value, min, max) => Math.max(min, Math.min(value, max))
-  const elements = []
-  for (const item of parsed.elements) {
-    if (!item || typeof item !== 'object' || !item.box || typeof item.box !== 'object') continue
-    const x1 = Math.round(Number(item.box.x1))
-    const y1 = Math.round(Number(item.box.y1))
-    const x2 = Math.round(Number(item.box.x2))
-    const y2 = Math.round(Number(item.box.y2))
-    if (![x1, y1, x2, y2].every(Number.isFinite)) continue
-    const box = {
-      x1: clamp(x1, 0, width - 1),
-      y1: clamp(y1, 0, height - 1),
-      x2: clamp(x2, 1, width),
-      y2: clamp(y2, 1, height),
-    }
-    if (box.x2 <= box.x1 || box.y2 <= box.y1) continue
-    elements.push({
-      number: elements.length + 1,
-      label: typeof item.label === 'string' && item.label.trim() !== '' ? item.label.trim() : `element ${elements.length + 1}`,
-      box,
-    })
-  }
-  return { width, height, elements }
-}
-
-/** Normalize a structured vision_describe answer with defaults for missing fields. */
-export function normalizeDescribeResult(parsed) {
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined
-  const layout = Array.isArray(parsed.layout) ? parsed.layout.filter((r) => r && typeof r === 'object' && typeof r.region === 'string' && typeof r.content === 'string') : []
-  const entities = Array.isArray(parsed.entities)
-    ? parsed.entities
-        .filter((e) => e && typeof e === 'object' && typeof e.type === 'string' && typeof e.label === 'string')
-        .map((e) => ({ type: e.type, label: e.label }))
-    : []
-  return {
-    summary: typeof parsed.summary === 'string' ? parsed.summary : '',
-    layout,
-    entities,
-    text: typeof parsed.text === 'string' ? parsed.text : '',
-  }
-}
-
-// ── pixel operations ───────────────────────────────────────────────────────
-
-/** Per-pixel RGBA comparison; returns ratio, mask and worst 8x8 cells. */
-export function computePixelDiff(bufferA, bufferB, threshold = 16, width = 0, height = 0) {
-  const length = Math.min(bufferA.length, bufferB.length)
-  const pixels = Math.floor(length / 4)
-  let differing = 0
-  const mask = new Uint8Array(pixels)
-  for (let i = 0; i < pixels; i++) {
-    const o = i * 4
-    const d =
-      Math.max(
-        Math.abs(bufferA[o] - bufferB[o]),
-        Math.abs(bufferA[o + 1] - bufferB[o + 1]),
-        Math.abs(bufferA[o + 2] - bufferB[o + 2]),
-      ) - threshold
-    if (d > 0) {
-      differing += 1
-      mask[i] = 1
-    }
-  }
-  const ratio = pixels === 0 ? 0 : differing / pixels
-  const cells = []
-  if (width > 0 && height > 0) {
-    const cols = 8
-    const rows = 8
-    const cw = Math.ceil(width / cols)
-    const ch = Math.ceil(height / rows)
-    for (let cy = 0; cy < rows; cy++) {
-      for (let cx = 0; cx < cols; cx++) {
-        let hit = 0
-        let total = 0
-        for (let y = cy * ch; y < Math.min((cy + 1) * ch, height); y++) {
-          for (let x = cx * cw; x < Math.min((cx + 1) * cw, width); x++) {
-            total += 1
-            if (mask[y * width + x]) hit += 1
-          }
-        }
-        if (total > 0 && hit > 0) {
-          cells.push({
-            x1: cx * cw,
-            y1: cy * ch,
-            x2: Math.min((cx + 1) * cw, width),
-            y2: Math.min((cy + 1) * ch, height),
-            ratio: hit / total,
-            differing: hit,
-            total,
-          })
-        }
-      }
-    }
-    cells.sort((a, b) => b.ratio - a.ratio)
-  }
-  return { differing, total: pixels, ratio, mask, cells }
-}
-
-function asBuffer(chunk) {
-  if (Buffer.isBuffer(chunk)) return chunk
-  if (chunk instanceof Uint8Array) return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength)
-  return Buffer.from(chunk ?? [])
-}
-
-class AsyncByteReader {
-  constructor(iterable) {
-    if (!iterable || typeof iterable[Symbol.asyncIterator] !== 'function') {
-      throw new TypeError('pixel diff stream must be async iterable')
-    }
-    this.iterator = iterable[Symbol.asyncIterator]()
-    this.buffer = Buffer.alloc(0)
-    this.done = false
-  }
-
-  async fill(minBytes) {
-    while (!this.done && this.buffer.length < minBytes) {
-      const next = await this.iterator.next()
-      if (next.done) {
-        this.done = true
-        break
-      }
-      const chunk = asBuffer(next.value)
-      if (chunk.length === 0) continue
-      this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk])
-    }
-  }
-
-  consume(bytes) {
-    const out = this.buffer.subarray(0, bytes)
-    this.buffer = this.buffer.subarray(bytes)
-    return out
-  }
-}
-
-function cellBounds(index, width, height, cols, rows) {
-  const cx = index % cols
-  const cy = Math.floor(index / cols)
-  const cw = Math.ceil(width / cols)
-  const ch = Math.ceil(height / rows)
-  const x1 = cx * cw
-  const y1 = cy * ch
-  const x2 = Math.min((cx + 1) * cw, width)
-  const y2 = Math.min((cy + 1) * ch, height)
-  return { x1, y1, x2, y2, total: Math.max(0, x2 - x1) * Math.max(0, y2 - y1) }
-}
-
-/**
- * Exact RGB pixel comparison over two RGBA async streams. The function never
- * materializes either full frame; it holds only the current upstream chunks
- * plus a bounded region counter grid.
- */
-export async function compareRgbaStreams(
-  streamA,
-  streamB,
-  { width, height, threshold = 16, cols = 8, rows = 8 } = {},
-) {
-  const w = Math.max(1, Math.floor(Number(width) || 1))
-  const h = Math.max(1, Math.floor(Number(height) || 1))
-  const limit = w * h
-  const gate = Number.isFinite(Number(threshold)) && Number(threshold) >= 0
-    ? Number(threshold)
-    : 16
-  const gridCols = Math.min(w, Math.max(1, Math.floor(Number(cols) || 8)))
-  const gridRows = Math.min(h, Math.max(1, Math.floor(Number(rows) || 8)))
-  const cellDiff = new Uint32Array(gridCols * gridRows)
-  const readerA = new AsyncByteReader(streamA)
-  const readerB = new AsyncByteReader(streamB)
-  let pixels = 0
-  let differing = 0
-
-  while (pixels < limit) {
-    await Promise.all([readerA.fill(4), readerB.fill(4)])
-    if (readerA.buffer.length < 4 || readerB.buffer.length < 4) break
-    const remainingBytes = (limit - pixels) * 4
-    const usable = Math.min(
-      remainingBytes,
-      Math.floor(Math.min(readerA.buffer.length, readerB.buffer.length) / 4) * 4,
-    )
-    if (usable <= 0) break
-    const a = readerA.consume(usable)
-    const b = readerB.consume(usable)
-    const chunkPixels = usable / 4
-    for (let i = 0; i < chunkPixels; i++) {
-      const o = i * 4
-      const different =
-        Math.max(
-          Math.abs(a[o] - b[o]),
-          Math.abs(a[o + 1] - b[o + 1]),
-          Math.abs(a[o + 2] - b[o + 2]),
-        ) > gate
-      if (!different) continue
-      differing += 1
-      const absolute = pixels + i
-      const x = absolute % w
-      const y = Math.floor(absolute / w)
-      const cx = Math.min(gridCols - 1, Math.floor((x * gridCols) / w))
-      const cy = Math.min(gridRows - 1, Math.floor((y * gridRows) / h))
-      cellDiff[cy * gridCols + cx] += 1
-    }
-    pixels += chunkPixels
-  }
-
-  if (pixels !== limit) {
-    throw new Error(`pixel diff stream ended early (${pixels}/${limit} pixels)`)
-  }
-  await Promise.all([readerA.fill(1), readerB.fill(1)])
-  if (readerA.buffer.length > 0 || readerB.buffer.length > 0) {
-    throw new Error('pixel diff stream produced more RGBA bytes than the declared dimensions')
-  }
-
-  const cells = []
-  for (let index = 0; index < cellDiff.length; index++) {
-    const hit = cellDiff[index]
-    if (hit === 0) continue
-    const bounds = cellBounds(index, w, h, gridCols, gridRows)
-    if (bounds.total <= 0) continue
-    cells.push({
-      x1: bounds.x1,
-      y1: bounds.y1,
-      x2: bounds.x2,
-      y2: bounds.y2,
-      ratio: hit / bounds.total,
-      differing: hit,
-      total: bounds.total,
-    })
-  }
-  cells.sort((a, b) => b.ratio - a.ratio)
-  return { differing, total: limit, ratio: limit === 0 ? 0 : differing / limit, mask: null, cells }
-}
-
-/** Render a diff heatmap: grayscale base, red where the mask marks a differing pixel. */
-export function renderDiffHeatmap(originalRaw, mask, width, height) {  const out = Buffer.alloc(width * height * 4)
-  for (let i = 0; i < width * height; i++) {
-    const o = i * 4
-    const gray = Math.round(
-      0.299 * originalRaw[o] + 0.587 * originalRaw[o + 1] + 0.114 * originalRaw[o + 2],
-    )
-    if (mask[i]) {
-      out[o] = 255
-      out[o + 1] = 0
-      out[o + 2] = 0
-      out[o + 3] = 255
-    } else {
-      out[o] = gray
-      out[o + 1] = gray
-      out[o + 2] = gray
-      out[o + 3] = 255
-    }
-  }
-  return out
-}
-
-/** Dominant colors via bin quantization of an RGBA raw buffer. */
-export function quantizeColors(raw, topN = 8, bins = 32) {
-  const step = 256 / bins
-  const counts = new Map()
-  const pixels = Math.floor(raw.length / 4)
-  for (let i = 0; i < pixels; i++) {
-    const o = i * 4
-    if (raw[o + 3] < 128) continue
-    const r = Math.floor(raw[o] / step) * step
-    const g = Math.floor(raw[o + 1] / step) * step
-    const b = Math.floor(raw[o + 2] / step) * step
-    const key = `${r},${g},${b}`
-    counts.set(key, (counts.get(key) ?? 0) + 1)
-  }
-  return [...counts.entries()]
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, topN)
-    .map(([key, count]) => {
-      const [r, g, b] = key.split(',').map(Number)
-      const hex = '#' + [r, g, b].map((v) => v.toString(16).padStart(2, '0')).join('')
-      return { hex, count, share: pixels === 0 ? 0 : count / pixels }
-    })
-}
-
-/** SVG overlay string drawing one red pixel box on a width x height canvas. */
-export function boxToSvg(box, width, height) {
-  return Buffer.from(
-    `<svg width="${width}" height="${height}">` +
-      `<rect x="${box.x1}" y="${box.y1}" width="${box.x2 - box.x1}" height="${box.y2 - box.y1}" ` +
-      `fill="none" stroke="#ff2d55" stroke-width="${Math.max(2, Math.round(Math.max(width, height) / 400))}"/></svg>`,
-  )
-}
-
-/** SVG overlay drawing numbered red boxes (detect inventory). */
-export function boxesToSvg(boxes, width, height) {
-  const stroke = Math.max(2, Math.round(Math.max(width, height) / 400))
-  const labelR = Math.max(10, stroke * 4)
-  const parts = [`<svg width="${width}" height="${height}">`]
-  for (let i = 0; i < boxes.length; i++) {
-    const box = boxes[i]
-    parts.push(
-      `<rect x="${box.x1}" y="${box.y1}" width="${box.x2 - box.x1}" height="${box.y2 - box.y1}" ` +
-        `fill="none" stroke="#ff2d55" stroke-width="${stroke}"/>`,
-    )
-    const cx = Math.max(labelR, Math.min(box.x1, width - labelR))
-    const cy = Math.max(labelR, Math.min(box.y1, height - labelR))
-    parts.push(
-      `<circle cx="${cx}" cy="${cy}" r="${labelR}" fill="#ff2d55"/>` +
-        `<text x="${cx}" y="${cy + labelR * 0.36}" text-anchor="middle" ` +
-        `font-family="sans-serif" font-size="${Math.round(labelR * 1.2)}" fill="#ffffff" ` +
-        `font-weight="bold">${i + 1}</text>`,
-    )
-  }
-  parts.push('</svg>')
-  return Buffer.from(parts.join(''))
-}
-
-export function scaledDimensions(width, height, maxPixels) {
-  const w = Math.max(0, Math.floor(Number(width) || 0))
-  const h = Math.max(0, Math.floor(Number(height) || 0))
-  const limit = Math.max(1, Math.floor(Number(maxPixels) || 1))
-  if (w <= 0 || h <= 0) return { width: w, height: h, scale: 1 }
-  const pixels = w * h
-  if (pixels <= limit) return { width: w, height: h, scale: 1 }
-  const scale = Math.sqrt(limit / pixels)
-  return {
-    width: Math.max(1, Math.floor(w * scale)),
-    height: Math.max(1, Math.floor(h * scale)),
-    scale,
-  }
-}
-
-export function scaleBox(box, fromWidth, fromHeight, toWidth, toHeight) {
-  const sx = fromWidth > 0 ? toWidth / fromWidth : 1
-  const sy = fromHeight > 0 ? toHeight / fromHeight : 1
-  return {
-    x1: Math.max(0, Math.round(box.x1 * sx)),
-    y1: Math.max(0, Math.round(box.y1 * sy)),
-    x2: Math.min(toWidth, Math.max(1, Math.round(box.x2 * sx))),
-    y2: Math.min(toHeight, Math.max(1, Math.round(box.y2 * sy))),
-  }
-}
-
-/** Draw one red pixel box onto an image buffer via sharp. */
-export async function annotateBoxBuffer(bytes, box) {
-  const sharp = await loadSharp()
-  if (!sharp) return bytes
-  const meta = await sharp(bytes, { failOn: 'none' }).metadata()
-  const width = meta.width ?? box.x2
-  const height = meta.height ?? box.y2
-  const preview = scaledDimensions(width, height, 4_000_000)
-  const displayBox = preview.scale === 1
-    ? box
-    : scaleBox(box, width, height, preview.width, preview.height)
-  let image = sharp(bytes, { failOn: 'none' })
-  if (preview.scale !== 1) image = image.resize(preview.width, preview.height, { fit: 'fill' })
-  return image
-    .composite([{ input: boxToSvg(displayBox, preview.width, preview.height), top: 0, left: 0 }])
-    .png()
-    .toBuffer()
-}
-
-/** Draw numbered boxes for a detected-element inventory onto an image buffer. */
-export async function annotateBoxesBuffer(bytes, boxes) {
-  const sharp = await loadSharp()
-  if (!sharp) return bytes
-  const meta = await sharp(bytes, { failOn: 'none' }).metadata()
-  const width = meta.width ?? 0
-  const height = meta.height ?? 0
-  if (width <= 0 || height <= 0 || boxes.length === 0) return bytes
-  const preview = scaledDimensions(width, height, 4_000_000)
-  const displayBoxes = preview.scale === 1
-    ? boxes
-    : boxes.map((box) => scaleBox(box, width, height, preview.width, preview.height))
-  let image = sharp(bytes, { failOn: 'none' })
-  if (preview.scale !== 1) image = image.resize(preview.width, preview.height, { fit: 'fill' })
-  return image
-    .composite([{ input: boxesToSvg(displayBoxes, preview.width, preview.height), top: 0, left: 0 }])
-    .png()
-    .toBuffer()
-}
-
-/** Remove a solid-ish background via border flood fill; background becomes transparent. */
-export function floodFillBackground(raw, width, height, tolerance = 40) {
-  const total = width * height
-  const out = Buffer.from(raw)
-  const marked = new Uint8Array(total)
-  let r = 0
-  let g = 0
-  let b = 0
-  const corners = [0, width - 1, (height - 1) * width, total - 1]
-  for (const c of corners) {
-    const o = c * 4
-    r += raw[o]
-    g += raw[o + 1]
-    b += raw[o + 2]
-  }
-  r /= 4
-  g /= 4
-  b /= 4
-  const queue = []
-  let head = 0
-  const push = (x, y) => {
-    const i = y * width + x
-    if (marked[i]) return
-    const o = i * 4
-    const d = Math.max(Math.abs(raw[o] - r), Math.abs(raw[o + 1] - g), Math.abs(raw[o + 2] - b))
-    if (d > tolerance) return
-    marked[i] = 1
-    queue.push(i)
-  }
-  for (let x = 0; x < width; x++) {
-    push(x, 0)
-    push(x, height - 1)
-  }
-  for (let y = 0; y < height; y++) {
-    push(0, y)
-    push(width - 1, y)
-  }
-  while (head < queue.length) {
-    const i = queue[head++]
-    const x = i % width
-    const y = (i - x) / width
-    if (x > 0) push(x - 1, y)
-    if (x < width - 1) push(x + 1, y)
-    if (y > 0) push(x, y - 1)
-    if (y < height - 1) push(x, y + 1)
-  }
-  for (let i = 0; i < total; i++) {
-    if (marked[i]) out[i * 4 + 3] = 0
-  }
-  return out
-}
-
-/** Cover a long/large image with bounded tiles in reading order. */
-export function boundedOcrTiles(
-  width,
-  height,
-  { chunkHeight = 1200, overlap = 120, maxTilePixels = 4_000_000 } = {},
-) {
-  const w = Math.max(1, Math.floor(Number(width) || 1))
-  const h = Math.max(1, Math.floor(Number(height) || 1))
-  const requestedHeight = Math.max(1, Math.min(h, Math.floor(Number(chunkHeight) || 1200)))
-  const pixelLimit = Math.max(1, Math.floor(Number(maxTilePixels) || 4_000_000))
-  const tileWidth = Math.min(w, Math.max(1, Math.floor(pixelLimit / requestedHeight)))
-  const tileHeight = Math.min(requestedHeight, Math.max(1, Math.floor(pixelLimit / tileWidth)))
-  const verticalOverlap = Math.min(
-    Math.max(0, Math.floor(Number(overlap) || 0)),
-    Math.max(0, Math.floor(tileHeight / 2)),
-  )
-  const verticalStep = Math.max(1, tileHeight - verticalOverlap)
-  const tiles = []
-  for (let top = 0; top < h; top += verticalStep) {
-    const bottom = Math.min(h, top + tileHeight)
-    for (let left = 0; left < w; left += tileWidth) {
-      const right = Math.min(w, left + tileWidth)
-      tiles.push({ left, right, top, bottom })
-    }
-    if (bottom >= h) break
-  }
-  return tiles
-}
-
-// ── potrace (worker-thread, hard timeout) ──────────────────────────────────
-
-function runPotraceWorker(workerData, source, timeoutMs) {
-  return new Promise((resolve, reject) => {
-    let settled = false
-    let worker
-    const finish = (error, svg) => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      void worker?.terminate()
-      if (error) reject(error)
-      else resolve(svg)
-    }
-    const timer = setTimeout(() => {
-      if (settled) return
-      settled = true
-      void worker?.terminate()
-      reject(
-        new Error(
-          'potrace timed out — the image is too large or too complex; crop it to the target region first',
-        ),
-      )
-    }, timeoutMs)
-    try {
-      worker = new Worker(source, { eval: true, workerData })
-      worker.once('message', (message) => {
-        if (message && message.error) finish(new Error(message.error))
-        else finish(undefined, message && message.svg)
-      })
-      worker.once('error', (error) => finish(error))
-      worker.once('exit', (code) => {
-        if (code !== 0 && !settled) finish(new Error(`potrace worker exited with code ${code}`))
-      })
-    } catch (error) {
-      finish(error)
-    }
-  })
-}
-
-/** Vectorize an image buffer into an SVG string via potrace posterization. */
-export function posterizeSvg(bytes, steps = 4, fillStrategy = 'dominant', timeoutMs = 60000) {
-  const potraceUrl = pathToFileURL(createRequire(import.meta.url).resolve('potrace')).href
-  const source = `
-    import('node:worker_threads').then(({ parentPort, workerData }) => {
-      import(workerData.potraceUrl).then((mod) => {
-        const potrace = mod.default ?? mod
-        potrace.posterize(Buffer.from(workerData.bytes), {
-          steps: workerData.steps,
-          fillStrategy: workerData.fillStrategy,
-        }, (error, svg) => {
-          parentPort.postMessage(error ? { error: String((error && error.message) || error) } : { svg })
-        })
-      }).catch((error) => {
-        parentPort.postMessage({ error: String((error && error.message) || error) })
-      })
-    })
-  `
-  return runPotraceWorker({ potraceUrl, bytes, steps, fillStrategy }, source, timeoutMs)
-}
-
-/**
- * Color-preserving vectorization: quantize into the top colors, trace one
- * 1-bit mask per color with potrace, emit a colored SVG (one path per color).
- */
-export function posterizeSvgColor(data, info, palette, timeoutMs = 60000) {
-  const sharpUrl = pathToFileURL(createRequire(import.meta.url).resolve('sharp')).href
-  const potraceUrl = pathToFileURL(createRequire(import.meta.url).resolve('potrace')).href
-  const source = `
-    import('node:worker_threads').then(({ parentPort, workerData }) => {
-      Promise.all([import(workerData.sharpUrl), import(workerData.potraceUrl)]).then(([sharpMod, potraceMod]) => {
-        const sharp = sharpMod.default ?? sharpMod
-        const potrace = potraceMod.default ?? potraceMod
-        const { width, height, palette } = workerData
-        const raw = Buffer.from(workerData.raw)
-        const hexRgb = (hex) => {
-          const n = parseInt(hex.slice(1), 16)
-          return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
-        }
-        const paletteRgb = palette.map((p) => hexRgb(p.hex))
-        const pixels = width * height
-        const masks = palette.map(() => Buffer.alloc(pixels))
-        for (let p = 0; p < pixels; p++) {
-          const o = p * 4
-          if (raw[o + 3] < 128) continue
-          let best = 0
-          let bestD = Infinity
-          for (let c = 0; c < paletteRgb.length; c++) {
-            const dr = raw[o] - paletteRgb[c][0]
-            const dg = raw[o + 1] - paletteRgb[c][1]
-            const db = raw[o + 2] - paletteRgb[c][2]
-            const d = dr * dr + dg * dg + db * db
-            if (d < bestD) { bestD = d; best = c }
-          }
-          masks[best][p] = 1
-        }
-        const paths = []
-        let pending = palette.length
-        const maybeDone = () => {
-          if (pending > 0) return
-          const pathSvg = paths.map((p) => '<path fill="' + p.hex + '" d="' + p.d + '"/>').join('')
-          parentPort.postMessage({
-            ok: true,
-            svg: '<svg xmlns="http://www.w3.org/2000/svg" width="' + width + '" height="' + height +
-              '" viewBox="0 0 ' + width + ' ' + height + '"><rect width="' + width + '" height="' + height +
-              '" fill="#ffffff"/>' + pathSvg + '</svg>',
-          })
-        }
-        if (pending === 0) { maybeDone(); return }
-        palette.forEach((entry, index) => {
-          const gray = Buffer.alloc(pixels)
-          const mask = masks[index]
-          for (let p = 0; p < pixels; p++) gray[p] = mask[p] ? 0 : 255
-          sharp(gray, { raw: { width, height, channels: 1 } })
-            .png()
-            .toBuffer()
-            .then((pngBuf) => {
-              potrace.trace(pngBuf, (err, svg) => {
-                pending -= 1
-                if (!err && svg) {
-                  const found = [...svg.matchAll(/d="([^"]+)"/g)].map((m) => m[1])
-                  for (const d of found) paths.push({ hex: entry.hex, d })
-                }
-                maybeDone()
-              })
-            })
-            .catch(() => {
-              pending -= 1
-              maybeDone()
-            })
-        })
-      }).catch((error) => {
-        parentPort.postMessage({ error: String((error && error.message) || error) })
-      })
-    })
-  `
-  return runPotraceWorker(
-    { sharpUrl, potraceUrl, width: info.width, height: info.height, palette, raw: data },
-    source,
-    timeoutMs,
-  )
-}
-
-// ── browser (HTML screenshot) ──────────────────────────────────────────────
-
-/** Cross-platform Chrome/Chromium/Edge discovery. */
-export function chromiumCandidates(env = {}, platform = typeof process !== 'undefined' ? process.platform : '') {
-  const out = []
-  const add = (value) => {
-    if (typeof value === 'string' && value !== '' && !out.includes(value)) out.push(value)
-  }
-  add(env.CHROME_PATH)
-  add(env.PUPPETEER_EXECUTABLE_PATH)
-
-  if (platform === 'win32') {
-    const pf = env.PROGRAMFILES
-    const pfx86 = env['PROGRAMFILES(X86)']
-    const local = env.LOCALAPPDATA
-    if (pf) {
-      add(winPath.join(pf, 'Google', 'Chrome', 'Application', 'chrome.exe'))
-      add(winPath.join(pf, 'Microsoft', 'Edge', 'Application', 'msedge.exe'))
-    }
-    if (pfx86) {
-      add(winPath.join(pfx86, 'Google', 'Chrome', 'Application', 'chrome.exe'))
-      add(winPath.join(pfx86, 'Microsoft', 'Edge', 'Application', 'msedge.exe'))
-    }
-    if (local) {
-      add(winPath.join(local, 'Google', 'Chrome', 'Application', 'chrome.exe'))
-      add(winPath.join(local, 'Microsoft', 'Edge', 'Application', 'msedge.exe'))
-      add(winPath.join(local, 'Chromium', 'Application', 'chrome.exe'))
-    }
-  } else if (platform === 'darwin') {
-    add('/Applications/Google Chrome.app/Contents/MacOS/Google Chrome')
-    add('/Applications/Chromium.app/Contents/MacOS/Chromium')
-    add('/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge')
-  } else {
-    add('/usr/bin/google-chrome')
-    add('/usr/bin/google-chrome-stable')
-    add('/usr/bin/chromium')
-    add('/usr/bin/chromium-browser')
-    add('/usr/bin/microsoft-edge')
-    add('/usr/bin/microsoft-edge-stable')
-  }
-  return out
-}
-
-/** Wake lazy/revealed content before a full-page capture. */
-export async function wakePageForFullCapture(page, viewportHeight) {
-  const step = Number.isInteger(viewportHeight) && viewportHeight > 0 ? viewportHeight : 720
-  await page.evaluate(() => {
-    document.documentElement.style.scrollBehavior = 'auto'
-  })
-  const total = await page.evaluate(() =>
-    Math.max(document.documentElement.scrollHeight, document.body ? document.body.scrollHeight : 0),
-  )
-  for (let y = 0; y < total; y += step) {
-    await page.evaluate((yy) => window.scrollTo(0, yy), y)
-    await new Promise((resolve) => setTimeout(resolve, 60))
-  }
-  await page.evaluate(() => window.scrollTo(0, 0))
-  await new Promise((resolve) => setTimeout(resolve, 800))
-}
-
-/** Full scrollable page height (CSS px). */
-export async function fullPageHeightOf(page) {
-  return await page.evaluate(() =>
-    Math.max(
-      document.documentElement.scrollHeight,
-      document.body ? document.body.scrollHeight : 0,
-      window.innerHeight,
-    ),
-  )
-}
-
-// ── model call (single configured endpoint) ────────────────────────────────
-
-/** Endpoint content-safety rejection markers (GLM: "系统检测到输入或生成内容
- *  可能包含不安全或敏感内容…"; OpenAI-style: content_filter/policy/safety…). */
-export const CONTENT_FILTER_RE =
-  /敏感|不安全|内容审核|内容安全|政策|content.?filter|safety|inappropriate|flagged|拒绝.?内容|违反.*(规范|政策|安全)|violat/i
-
-export function resolveApiKey(config) {
-  if (config.apiKey) return config.apiKey
-  if (config.apiKeyEnv) {
-    const fromEnv = process.env[config.apiKeyEnv]
-    if (fromEnv) return fromEnv
-  }
-  return process.env.OPENAI_API_KEY ?? ''
-}
-
-/** Turn image bytes into a data URL for the vision call.
- *  Defensive: attachment-service reads return Uint8Array (whose
- *  toString('base64') is a comma-joined number list, not base64), so always
- *  wrap in a real Buffer first. */
-export function bytesToDataUrl(bytes, mediaType) {
-  const mime = mediaType ?? 'image/png'
-  const buf = Buffer.isBuffer(bytes)
-    ? bytes
-    : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
-  return `data:${mime};base64,${buf.toString('base64')}`
-}
-
-/**
- * One OpenAI-compatible chat/completions call with image content parts.
- * This is the ONLY model-call path the ported tools use: the plugin's own
- * baseURL/apiKey/model settings drive every vision_* tool, exactly like
- * inspect_image.
- */
-export async function callVisionModel(getConfig, prompt, imageUrls, options = {}) {
-  const cfg = getConfig()
-  const key = resolveApiKey(cfg)
-  if (!key) {
-    throw new Error(
-      'tool-vision: vision API key missing: set the plugin config (apiKey / apiKeyEnv) or the OPENAI_API_KEY environment variable',
-    )
-  }
-  const sessionHeader = sessionHeaders(cfg, options.exec)
-  const base = cfg.baseURL.endsWith('/') ? cfg.baseURL : `${cfg.baseURL}/`
-  const endpoint = new URL('chat/completions', base)
-  const controller = new AbortController()
-  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : cfg.timeoutMs
-  const timer = setTimeout(
-    () => controller.abort(new Error(`tool-vision: vision request timed out after ${timeoutMs}ms`)),
-    timeoutMs,
-  )
-  const signal = options.signal
-  const onSignalAbort = () => controller.abort(signal?.reason)
-  if (signal) {
-    if (signal.aborted) controller.abort()
-    else signal.addEventListener('abort', onSignalAbort, { once: true })
-  }
-  const content = [
-    { type: 'text', text: prompt },
-    ...imageUrls.map((url) => ({ type: 'image_url', image_url: { url } })),
-  ]
-  const bodyOf = () => JSON.stringify({
-    model: cfg.model,
-    messages: [{ role: 'user', content }],
-    max_tokens: Number.isFinite(options.maxTokens) ? options.maxTokens : cfg.maxTokens,
-  })
-  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
-  const retryAfterOf = (response) => {
-    const header = response?.headers?.get?.('retry-after')
-    if (header) {
-      const seconds = Number(header)
-      if (Number.isFinite(seconds) && seconds > 0) return Math.min(seconds * 1000, 15000)
-    }
-    return 0
-  }
-  const MAX_TRANSIENT_RETRIES = 3
-  try {
-    let lastResponse = null
-    let lastBody = null
-    for (let attempt = 0; ; attempt++) {
-      const response = await fetch(endpoint, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${key}`,
-          ...sessionHeader,
-        },
-        body: bodyOf(),
-        signal: controller.signal,
-      })
-      lastResponse = response
-      lastBody = await response.json().catch(() => null)
-      // Transient failures (rate limit / 5xx) retry with backoff; everything
-      // else (4xx auth/format/content-filter) is terminal.
-      const retriable =
-        response.status === 429 ||
-        response.status === 408 ||
-        response.status === 500 ||
-        response.status === 502 ||
-        response.status === 503 ||
-        response.status === 504
-      if (!response.ok && retriable && attempt < MAX_TRANSIENT_RETRIES) {
-        const waitMs = retryAfterOf(response) || 800 * (attempt + 1)
-        await sleep(waitMs)
-        continue
-      }
-      break
-    }
-    const response = lastResponse
-    const body = lastBody
-    if (!response.ok) {
-      const detailText = body?.error?.message ?? response.statusText
-      throw new Error(
-        `tool-vision: vision endpoint returned ${response.status}: ${detailText} (endpoint ${endpoint})`,
-      )
-    }
-    const message = body?.choices?.[0]?.message
-    let answer = message?.content ?? ''
-    if (!answer.trim()) answer = message?.reasoning_content ?? ''
-    if (typeof answer !== 'string' || !answer.trim()) {
-      throw new Error('tool-vision: vision endpoint returned an empty response')
-    }
-    const trimmed = answer.trim()
-    // max_tokens truncation: glm-4v-flash caps at 1024; a truncated JSON or
-    // transcript must not masquerade as a complete answer.
-    const finishReason = body?.choices?.[0]?.finish_reason
-    if (finishReason === 'length') {
-      return `${trimmed}\n\n[注意:模型输出因 max_tokens 上限被截断(finish_reason=length);以上内容不完整。]`
-    }
-    return trimmed
-  } finally {
-    clearTimeout(timer)
-    signal?.removeEventListener('abort', onSignalAbort)
-  }
-}
-
-// ── shared tool plumbing ───────────────────────────────────────────────────
-
-export const stringOutput = {
-  schema: { type: 'string' },
-  render: (_args, value) => [{ type: 'text', text: value }],
-}
-
-/**
- * Build the 14 vision tools bound to this plugin instance.
- * @param {object} ctx - plugin context (attachments/fs services via ctx.get)
- * @param {() => object} getConfig - live settings getter
- */
-export function registerVisionTools(ctx, getConfig) {
-  const logger = ctx.logger
-
-  /** Single-endpoint model call wrapper with the router's ok:false contract.
-   *  `images` is a single Buffer, or an array of Buffers / data-URL strings. */
-  const answerVisionForTool = async (images, mediaType, instruction, options = {}) => {
-    try {
-      // Uniform pixel budget for EVERY model call: ground/detect/ocr/etc.
-      // must not ship raw 20MB images (base64 ~27MB -> endpoint 413/timeout).
-      // Downscale only Buffer inputs; pre-made data URLs pass through.
-      const bounded = Array.isArray(images)
-        ? await Promise.all(images.map(async (item) => (typeof item === 'string' ? item : bytesToDataUrl(await downscaleImage(item, 4_000_000), mediaType ?? 'image/png'))))
-        : [bytesToDataUrl(await downscaleImage(images, 4_000_000), mediaType)]
-      const text = await callVisionModel(getConfig, instruction, bounded, {
-        signal: options.signal ?? (options.exec && options.exec.signal),
-        exec: options.exec,
-      })
-      return { ok: true, text }
-    } catch (error) {
-      const raw = error && error.message ? String(error.message) : String(error)
-      // Endpoint content-safety rejections are NOT backend outages: the image
-      // itself was refused. Surface them distinctly so the model tells the
-      // user to pick a different image instead of reporting "vision down".
-      if (CONTENT_FILTER_RE.test(raw)) {
-        return {
-          ok: false,
-          code: 'VISION_CONTENT_FILTERED',
-          retryable: false,
-          contentFiltered: true,
-          message:
-            '图片被视觉端点的内容安全策略拒绝(检测到敏感或不安全内容)。' +
-            '这不是网络或配置问题,请换一张图片或调整图片内容后再试。',
-        }
-      }
-      return {
-        ok: false,
-        code: 'VISION_BACKEND_UNAVAILABLE',
-        retryable: false,
-        message: raw,
-      }
-    }
-  }
-
-  const saveArtifact = (exec, relPath, data) => writeArtifact(exec, relPath, data)
-  const artifactStem = (imagePath, suffix) => artifactStemOf(imagePath, suffix)
-
-  const tools = []
-
-  // ── vision_describe ──────────────────────────────────────────────────────
-  tools.push({
-    name: 'vision_describe',
-    description:
-      'Look at images with the configured vision model and answer a focused question about them. ' +
-      'For text-only sessions this is the bridge that provides image understanding. ' +
-      'Supports comparing multiple images (e.g. a design mock vs an implementation screenshot). Provide ' +
-      '`paths` (absolute local image file paths, png/jpeg/webp/gif) and/or ' +
-      '`attachmentIds` (ids of images the user uploaded in this conversation), 1-4 images in ' +
-      'total. `question` is the question to answer; be specific. Set `json: true` to require a ' +
-      'single valid JSON object as the answer. ' +
-      'FAILURE SEMANTICS: if the result is JSON with ok:false, the vision backend is unavailable. ' +
-      'Do NOT call vision_describe again with a reworded question — rephrasing cannot fix an auth, ' +
-      'rate-limit or outage problem. Answer from the information you already have and continue the ' +
-      'text task, telling the user vision is temporarily unavailable.',
-    parameters: {
-      type: 'object',
-      properties: {
-        paths: {
-          type: 'array',
-          items: { type: 'string' },
-          description:
-            'Absolute local image file paths and/or attachment ids (e.g. "sha256:...") of uploaded images, 1-4 images',
-        },
-        attachmentIds: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Attachment ids of images uploaded earlier in this conversation',
-        },
-        question: {
-          type: 'string',
-          description:
-            'The question for the vision model, e.g. "compare the two images and list the differences"',
-        },
-        json: {
-          type: 'boolean',
-          description: 'Require the answer to be a single valid JSON object',
-        },
-      },
-      required: ['question'],
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const attachments = ctx.get('attachments')
-      if (attachments === undefined) {
-        throw new Error('vision_describe: the durable attachment service is not available in this deployment')
-      }
-      const blocks = []
-      const contentIds = []
-      const paths = Array.isArray(args.paths) ? args.paths : []
-      const attachmentIds = Array.isArray(args.attachmentIds) ? args.attachmentIds : []
-      if (paths.length + attachmentIds.length === 0 || paths.length + attachmentIds.length > 4) {
-        throw new Error('vision_describe: provide 1-4 images via paths and/or attachmentIds')
-      }
-
-      for (const path of paths) {
-        let bytes
-        let mediaType
-        try {
-          ;({ bytes, mediaType } = await readImageBytes(ctx, exec, path))
-        } catch (error) {
-          throw new Error(
-            `vision_describe: failed to read ${path} (${error && error.message ? error.message : String(error)})`,
-          )
-        }
-        bytes = await downscaleImage(bytes, 4_000_000)
-        let ref
-        try {
-          ref = await attachments.saveImage({ data: bytes, mediaType })
-        } catch (error) {
-          throw new Error(
-            `vision_describe: image ${path} was rejected (${error && error.message ? error.message : String(error)})`,
-          )
-        }
-        contentIds.push(String(ref.attachmentId))
-        blocks.push({ type: 'image', attachment: ref })
-      }
-
-      for (const id of attachmentIds) {
-        const session = exec && exec.agent && exec.agent.session
-        const ref = lookupAttachment(session, String(id))
-        if (ref === undefined) {
-          throw new Error(
-            `vision_describe: unknown attachment id "${id}" (it must come from an image uploaded in this conversation)`,
-          )
-        }
-        let stored
-        try {
-          stored = await attachments.readImage(ref)
-        } catch (error) {
-          throw new Error(
-            `vision_describe: failed to read attachment ${id} (${error && error.message ? error.message : String(error)})`,
-          )
-        }
-        if (stored.data && stored.data.length > 0) {
-          const resized = await downscaleImage(stored.data, 4_000_000)
-          if (resized !== stored.data) {
-            try {
-              const resizedRef = await attachments.saveImage({
-                data: resized,
-                mediaType: stored.ref && stored.ref.mediaType ? stored.ref.mediaType : 'image/png',
-                ...(stored.ref && stored.ref.name ? { name: stored.ref.name } : {}),
-              })
-              stored = { ref: resizedRef, data: resized }
-            } catch {
-              stored = { ...stored, data: resized }
-            }
-          }
-        }
-        contentIds.push(String(ref.attachmentId))
-        blocks.push({ type: 'image', attachment: stored.ref })
-      }
-
-      const question = String(args.question ?? '')
-      const wantJson = args.json === true
-      const promptText = visionDescribePrompt(question, wantJson)
-      // Cache key carries the endpoint/model identity: switching the vision
-      // model must never serve stale answers from the previous model.
-      const cfg = getConfig()
-      const key = `${cfg.baseURL ?? ''}|${cfg.model ?? ''}|${contentIds.join('|')}|${wantJson ? 'json' : 'text'}|${question}`
-      const cache = visionCache
-      if (cacheEnabled()) {
-        const hit = cache.get(key)
-        if (hit !== undefined) return hit
-      }
-
-      // Call with all images as data URLs.
-      const imageUrls = []
-      for (const block of blocks) {
-        const stored = await attachments.readImage(block.attachment)
-        imageUrls.push(bytesToDataUrl(stored.data, stored.ref && stored.ref.mediaType ? stored.ref.mediaType : 'image/png'))
-      }
-      const vision = await answerVisionForTool(imageUrls, 'image/png', promptText, { exec })
-      if (vision.ok === false) return JSON.stringify(vision)
-
-      let text = vision.text
-      if (wantJson) {
-        for (let attempt = 0; attempt < 2; attempt++) {
-          const parsed = extractJson(text)
-          if (parsed !== undefined) {
-            const compact = JSON.stringify(normalizeDescribeResult(parsed) ?? parsed)
-            if (cacheEnabled()) cache.set(key, compact)
-            return compact
-          }
-          if (attempt === 0) {
-            const retry = await answerVisionForTool(imageUrls, 'image/png', promptText + '\n\nThat output was not valid JSON. Respond with ONLY a valid JSON object now.', { exec })
-            if (retry.ok === false) return JSON.stringify(retry)
-            text = retry.text
-          }
-        }
-        // Failure/fallback output must NOT be cached: it would poison the
-        // cache for the whole TTL with an error string masquerading as an
-        // answer.
-        return `vision_describe: the model did not produce valid JSON. Raw output:\n${text.slice(0, 2000)}`
-      }
-      if (text !== '') {
-        if (cacheEnabled()) cache.set(key, text)
-        return text
-      }
-      // Empty output is a failure signal, not a cacheable answer.
-      return '(the vision model returned empty content)'
-    },
-  })
-
-  // ── vision_materialize ───────────────────────────────────────────────────
-  tools.push({
-    name: 'vision_materialize',
-    description:
-      'Copy an uploaded image attachment (sha256:...) or readable local image into the session workspace and return a real filesystem path. ' +
-      'This tool performs NO vision model/network call. Use it after vision_describe returns ok:false when a local OCR/parser accepts only file_path. ' +
-      'Never guess the attachment store path or search for a same-named file.',
-    parameters: {
-      type: 'object',
-      properties: {
-        image: { type: 'string', description: 'Uploaded image attachment id (recommended, e.g. sha256:...) or a readable local image path' },
-      },
-      required: ['image'],
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const source = String(args.image ?? '')
-      const { bytes, mediaType } = await readImageBytes(ctx, exec, source)
-      const extension = mediaType === 'image/jpeg' ? '.jpg' : (EXT_BY_MEDIA[mediaType] ?? '.png')
-      const target = await saveArtifact(exec, `${artifactStem(source, 'materialized')}${extension}`, bytes)
-      return JSON.stringify({ path: target, bytes: bytes.length, mediaType })
-    },
-  })
-
-  // ── vision_ground ────────────────────────────────────────────────────────
-  tools.push({
-    name: 'vision_ground',
-    description:
-      'Locate a target in an image and return its ORIGINAL-pixel bounding box (x1/y1/x2/y2), ' +
-      'optionally producing an annotated PNG artifact. Pair with vision_crop and vision_pixel_diff ' +
-      'for a verify-able pixel loop (reference -> implementation -> screenshot -> metrics). ' +
-      'If the result is JSON with ok:false, the vision backend is unavailable — do not retry with ' +
-      'reworded instructions this turn.',
-    parameters: {
-      type: 'object',
-      properties: {
-        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
-        target: { type: 'string', description: 'What to locate, e.g. "the send button"' },
-        annotate: { type: 'boolean', description: 'Also write an annotated PNG with the box drawn (default true)' },
-      },
-      required: ['image', 'target'],
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const { bytes, mediaType } = await readImageBytes(ctx, exec, args.image)
-      const { width, height } = await imageDims(bytes)
-      if (width <= 0 || height <= 0) throw new Error('vision_ground: could not read image dimensions')
-      const instruction =
-        `Target to locate: "${String(args.target).slice(0, 500)}". ` +
-        `The image is ${width}x${height} pixels. Return ONE JSON object with integer fields ` +
-        `{"x1":...,"y1":...,"x2":...,"y2":...} — the tight bounding box of that target in ` +
-        `ORIGINAL image pixels (0 <= x1 < x2 <= ${width}, 0 <= y1 < y2 <= ${height}). ` +
-        `Output only the JSON object.`
-      const vision = await answerVisionForTool(bytes, mediaType, instruction, { exec })
-      if (vision.ok === false) return JSON.stringify(vision)
-      const parsed = extractJson(vision.text)
-      const box = parsed !== undefined ? parseBox(parsed) : undefined
-      if (box === undefined) {
-        throw new Error(`vision_ground: the vision model did not return a valid box. Raw output: ${vision.text.slice(0, 500)}`)
-      }
-      let clamped = {
-        x1: Math.max(0, Math.min(box.x1, width - 1)),
-        y1: Math.max(0, Math.min(box.y1, height - 1)),
-        x2: Math.max(1, Math.min(box.x2, width)),
-        y2: Math.max(1, Math.min(box.y2, height)),
-      }
-      if (clamped.x2 - clamped.x1 < 2 || clamped.y2 - clamped.y1 < 2) {
-        const retry = await answerVisionForTool(
-          bytes,
-          mediaType,
-          `Your previous box ${JSON.stringify(clamped)} was a degenerate sliver, not the target. ` +
-            `Return ONE JSON object with the FULL tight bounding box of the target in ORIGINAL ` +
-            `image pixels (0 <= x1 < x2 <= ${width}, 0 <= y1 < y2 <= ${height}). Output only the JSON object.`,
-          { exec },
-        )
-        if (retry.ok === false) return JSON.stringify(retry)
-        const retryParsed = extractJson(retry.text)
-        const retryBox = retryParsed !== undefined ? parseBox(retryParsed) : undefined
-        if (retryBox === undefined) {
-          throw new Error(
-            `vision_ground: the vision model returned a degenerate box (${clamped.x1},${clamped.y1},${clamped.x2},${clamped.y2}) ` +
-              `and the retry returned no valid box. Raw output: ${retry.text.slice(0, 500)}`,
-          )
-        }
-        clamped = {
-          x1: Math.max(0, Math.min(retryBox.x1, width - 1)),
-          y1: Math.max(0, Math.min(retryBox.y1, height - 1)),
-          x2: Math.max(1, Math.min(retryBox.x2, width)),
-          y2: Math.max(1, Math.min(retryBox.y2, height)),
-        }
-        if (clamped.x2 - clamped.x1 < 2 || clamped.y2 - clamped.y1 < 2) {
-          throw new Error(
-            `vision_ground: the vision model returned only degenerate boxes for a ${width}x${height} image. ` +
-              `Last raw output: ${retry.text.slice(0, 500)}`,
-          )
-        }
-      }
-      const result = { ...clamped, width, height }
-      if (args.annotate !== false) {
-        const annotated = await annotateBoxBuffer(bytes, clamped)
-        result.annotatedPath = await saveArtifact(exec, `${artifactStem(args.image, 'ground')}.png`, annotated)
-      }
-      return JSON.stringify(result)
-    },
-  })
-
-  // ── vision_detect ────────────────────────────────────────────────────────
-  tools.push({
-    name: 'vision_detect',
-    description:
-      'Find every element of a kind in an image (buttons, inputs, links, icons…) and return a ' +
-      'numbered inventory with ORIGINAL-pixel boxes, optionally annotated on the image. The model ' +
-      'can then reference "element #3" in follow-up vision_crop / vision_describe calls. ' +
-      'If the result is JSON with ok:false, the vision backend is unavailable — do not retry with ' +
-      'reworded instructions this turn.',
-    parameters: {
-      type: 'object',
-      properties: {
-        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
-        target: {
-          type: 'string',
-          description: 'What kind of elements to list, e.g. "buttons", "input fields", "navigation links" (default: interactive elements)',
-        },
-        annotate: {
-          type: 'boolean',
-          description: 'Also write an annotated PNG with numbered boxes (default true)',
-        },
-      },
-      required: ['image'],
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const { bytes, mediaType } = await readImageBytes(ctx, exec, args.image)
-      const { width, height } = await imageDims(bytes)
-      if (width <= 0 || height <= 0) throw new Error('vision_detect: could not read image dimensions')
-      const target = typeof args.target === 'string' && args.target.trim() !== '' ? args.target : 'interactive elements'
-      const vision = await answerVisionForTool(bytes, mediaType, visionDetectInstruction(target, width, height), { exec })
-      if (vision.ok === false) return JSON.stringify(vision)
-      let text = vision.text
-      let parsed = extractJson(text)
-      if (parsed === undefined) {
-        const retry = await answerVisionForTool(
-          bytes,
-          mediaType,
-          visionDetectInstruction(target, width, height) +
-            '\nYour previous answer was not valid JSON. Respond with ONLY the JSON object, no prose, no fences.',
-          { exec },
-        )
-        if (retry.ok === false) return JSON.stringify(retry)
-        parsed = extractJson(retry.text)
-        text = retry.text
-      }
-      const result = normalizeDetectResult(parsed, width, height)
-      if (result === undefined) {
-        throw new Error(`vision_detect: the vision model did not return a valid inventory. Raw output: ${text.slice(0, 500)}`)
-      }
-      if (args.annotate !== false && result.elements.length > 0) {
-        const annotated = await annotateBoxesBuffer(bytes, result.elements.map((e) => e.box))
-        result.annotatedPath = await saveArtifact(exec, `${artifactStem(args.image, 'detect')}.png`, annotated)
-      }
-      return JSON.stringify(result)
-    },
-  })
-
-  // ── vision_crop ──────────────────────────────────────────────────────────
-  tools.push({
-    name: 'vision_crop',
-    description:
-      'Crop a pixel region (x1,y1,x2,y2 in ORIGINAL pixels) out of an image and write the ' +
-      'result as a PNG artifact for a closer look. Very large regions are rendered as a bounded ' +
-      'preview; crop a smaller ORIGINAL-pixel region when tiny details must be preserved.',
-    parameters: {
-      type: 'object',
-      properties: {
-        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
-        region: {
-          type: 'string',
-          description: 'Pixel box "x1,y1,x2,y2" in original image coordinates',
-        },
-      },
-      required: ['image', 'region'],
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const { bytes } = await readImageBytes(ctx, exec, args.image)
-      const { width, height } = await imageDims(bytes)
-      const box = parseBox(args.region)
-      if (box === undefined) {
-        throw new Error(`vision_crop: invalid region "${args.region}" (expect "x1,y1,x2,y2" integers)`)
-      }
-      if (box.x2 > width || box.y2 > height) {
-        throw new Error(`vision_crop: region exceeds image bounds (${width}x${height})`)
-      }
-      const sharp = await loadSharp()
-      if (!sharp) throw new Error('vision_crop: the sharp image library is unavailable')
-      const sourceWidth = box.x2 - box.x1
-      const sourceHeight = box.y2 - box.y1
-      const preview = scaledDimensions(sourceWidth, sourceHeight, 4_000_000)
-      let pipeline = sharp(bytes, { failOn: 'none' }).extract({
-        left: box.x1,
-        top: box.y1,
-        width: sourceWidth,
-        height: sourceHeight,
-      })
-      if (preview.scale !== 1) {
-        pipeline = pipeline.resize(preview.width, preview.height, { fit: 'fill' })
-      }
-      const cropped = await pipeline.png().toBuffer()
-      const target = await saveArtifact(
-        exec,
-        `${artifactStem(args.image, `crop-${box.x1}-${box.y1}-${box.x2}-${box.y2}`)}.png`,
-        cropped,
-      )
-      const meta = await sharp(cropped).metadata()
-      return JSON.stringify({
-        path: target,
-        width: meta.width ?? preview.width,
-        height: meta.height ?? preview.height,
-        bytes: cropped.length,
-        ...(preview.scale !== 1
-          ? {
-              preview: true,
-              sourceRegion: box,
-              sourceWidth,
-              sourceHeight,
-              scale: preview.scale,
-              advice: 'This was a bounded preview of a large crop. Use vision_crop again with a smaller ORIGINAL-pixel region for tiny details.',
-            }
-          : {}),
-      })
-    },
-  })
-
-  // ── vision_present ───────────────────────────────────────────────────────
-  const visionPresentOutput = {
-    schema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string' },
-        label: { type: 'string' },
-        width: { type: 'number' },
-        height: { type: 'number' },
-        bytes: { type: 'number' },
-        safePresentation: { type: 'boolean' },
-        attachment: {
-          type: 'object',
-          properties: {
-            attachmentId: { type: 'string' },
-            mediaType: { type: 'string' },
-            bytes: { type: 'number' },
-            width: { type: 'number' },
-            height: { type: 'number' },
-            name: { type: 'string' },
-          },
-          required: ['attachmentId', 'mediaType', 'bytes', 'width', 'height'],
-          additionalProperties: false,
-        },
-      },
-      required: ['path', 'label', 'width', 'height', 'bytes', 'safePresentation', 'attachment'],
-      additionalProperties: false,
-    },
-    render: (_args, value) => {
-      const attachment = value.attachment
-      return [
-        {
-          type: 'text',
-          text: JSON.stringify({
-            path: value.path,
-            label: value.label,
-            width: value.width,
-            height: value.height,
-            bytes: value.bytes,
-            safePresentation: true,
-            attachmentId: String(attachment.attachmentId),
-          }),
-        },
-        { type: 'image', attachment },
-      ]
-    },
-  }
-  tools.push({
-    name: 'vision_present',
-    description:
-      'Present a generated local image directly to the user with the host-native image preview. ' +
-      'MANDATORY PRESENTATION RULE: when you generate, edit, screenshot, or export an image and want the user to see it, ' +
-      'you MUST call vision_present. read_image is only for model-side inspection; NEVER use read_image to present or send ' +
-      'an image to the user. The image is retained in the session UI but sanitized out of later text-only model requests.',
-    parameters: {
-      type: 'object',
-      properties: {
-        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
-        label: { type: 'string', description: 'Optional short user-facing label for the image' },
-      },
-      required: ['image'],
-      additionalProperties: false,
-    },
-    output: visionPresentOutput,
-    async execute(args, exec) {
-      const attachments = ctx.get('attachments')
-      if (attachments === undefined) {
-        throw new Error('vision_present: the durable attachment service is not available in this deployment')
-      }
-      const { bytes, mediaType } = await readImageBytes(ctx, exec, args.image)
-      const label =
-        typeof args.label === 'string' && args.label.trim() !== '' ? args.label.trim().slice(0, 200) : 'image'
-      const extension =
-        mediaType === 'image/jpeg' ? 'jpg' :
-        mediaType === 'image/webp' ? 'webp' :
-        mediaType === 'image/gif' ? 'gif' : 'png'
-      const target = await saveArtifact(exec, `${artifactStem(args.image, 'present')}.${extension}`, bytes)
-      let attachment
-      try {
-        attachment = await attachments.saveImage({
-          data: bytes,
-          mediaType,
-          name: label,
-        })
-      } catch (error) {
-        throw new Error(
-          `vision_present: failed to publish the image attachment (${error && error.message ? error.message : String(error)})`,
-        )
-      }
-      return {
-        path: target,
-        label,
-        width: attachment.width,
-        height: attachment.height,
-        bytes: attachment.bytes,
-        safePresentation: true,
-        attachment,
-      }
-    },
-  })
-
-  // ── vision_pixel_diff ────────────────────────────────────────────────────
-  tools.push({
-    name: 'vision_pixel_diff',
-    description:
-      'Compare two images pixel by pixel (sharp-based, no Python): returns the differing-pixel ' +
-      'ratio, the worst 8x8-grid regions as original-pixel boxes, and writes a red heatmap PNG ' +
-      'plus a JSON report as artifacts. Use it to verify an implementation against a reference.',
-    parameters: {
-      type: 'object',
-      properties: {
-        original: { type: 'string', description: 'Reference image path or attachment id (e.g. "sha256:...")' },
-        rebuilt: { type: 'string', description: 'Candidate image path or attachment id (e.g. "sha256:..."); resized to the original size before comparing' },
-        threshold: { type: 'number', description: 'Per-channel difference threshold, default 16' },
-      },
-      required: ['original', 'rebuilt'],
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const { bytes: originalBytes } = await readImageBytes(ctx, exec, args.original)
-      const { bytes: rebuiltBytes } = await readImageBytes(ctx, exec, args.rebuilt)
-      const sharp = await loadSharp()
-      if (!sharp) throw new Error('vision_pixel_diff: the sharp image library is unavailable')
-      const meta = await sharp(originalBytes, { failOn: 'none' }).metadata()
-      const width = meta.width ?? 0
-      const height = meta.height ?? 0
-      if (width <= 0 || height <= 0) throw new Error('vision_pixel_diff: could not read original dimensions')
-      const threshold = Number.isFinite(args.threshold) && args.threshold >= 0 ? Math.round(args.threshold) : 16
-      const pixels = width * height
-      let diff
-      let heatmapPng
-      let heatmapPreview = false
-      let heatmapWidth = width
-      let heatmapHeight = height
-      if (pixels <= 4_000_000) {
-        const originalRaw = await sharp(originalBytes, { failOn: 'none' })
-          .ensureAlpha()
-          .raw()
-          .toBuffer({ resolveWithObject: true })
-        const rebuiltRaw = await sharp(rebuiltBytes, { failOn: 'none' })
-          .resize(width, height, { fit: 'fill' })
-          .ensureAlpha()
-          .raw()
-          .toBuffer({ resolveWithObject: true })
-        diff = computePixelDiff(originalRaw.data, rebuiltRaw.data, threshold, width, height)
-        const heatmap = renderDiffHeatmap(originalRaw.data, diff.mask, width, height)
-        heatmapPng = await sharp(heatmap, { raw: { width, height, channels: 4 } })
-          .png()
-          .toBuffer()
-      } else {
-        // Exact large-image metrics from streaming RGBA; heatmap bounded to 4MP.
-        const originalStream = sharp(originalBytes, { failOn: 'none' }).ensureAlpha().raw()
-        const rebuiltStream = sharp(rebuiltBytes, { failOn: 'none' })
-          .resize(width, height, { fit: 'fill' })
-          .ensureAlpha()
-          .raw()
-        diff = await compareRgbaStreams(originalStream, rebuiltStream, { width, height, threshold })
-        const preview = scaledDimensions(width, height, 4_000_000)
-        heatmapWidth = preview.width
-        heatmapHeight = preview.height
-        heatmapPreview = true
-        const originalPreview = await sharp(originalBytes, { failOn: 'none' })
-          .resize(preview.width, preview.height, { fit: 'fill' })
-          .ensureAlpha()
-          .raw()
-          .toBuffer({ resolveWithObject: true })
-        const rebuiltPreview = await sharp(rebuiltBytes, { failOn: 'none' })
-          .resize(preview.width, preview.height, { fit: 'fill' })
-          .ensureAlpha()
-          .raw()
-          .toBuffer({ resolveWithObject: true })
-        const previewDiff = computePixelDiff(
-          originalPreview.data,
-          rebuiltPreview.data,
-          threshold,
-          preview.width,
-          preview.height,
-        )
-        const heatmap = renderDiffHeatmap(originalPreview.data, previewDiff.mask, preview.width, preview.height)
-        heatmapPng = await sharp(heatmap, {
-          raw: { width: preview.width, height: preview.height, channels: 4 },
-        }).png().toBuffer()
-      }
-      const worst = diff.cells.slice(0, 5).map((cell) => ({
-        x1: cell.x1,
-        y1: cell.y1,
-        x2: cell.x2,
-        y2: cell.y2,
-        ratio: Number(cell.ratio.toFixed(4)),
-        differing: cell.differing,
-      }))
-      const heatmapPath = await saveArtifact(exec, `${artifactStem(args.original, 'diff-heatmap')}.png`, heatmapPng)
-      const report = {
-        width,
-        height,
-        differingPixels: diff.differing,
-        totalPixels: diff.total,
-        differingRatio: Number(diff.ratio.toFixed(6)),
-        threshold,
-        worstRegions: worst,
-        heatmapPath,
-        heatmapWidth,
-        heatmapHeight,
-        heatmapPreview,
-      }
-      const reportPath = await saveArtifact(exec, `${artifactStem(args.original, 'diff-report')}.json`, Buffer.from(JSON.stringify(report, null, 2)))
-      return JSON.stringify({ ...report, reportPath })
-    },
-  })
-
-  // ── vision_colors ────────────────────────────────────────────────────────
-  tools.push({
-    name: 'vision_colors',
-    description:
-      'Extract the dominant colors of an image (sharp-based quantization) with their share of ' +
-      'pixels, e.g. to match a palette when rebuilding a UI.',
-    parameters: {
-      type: 'object',
-      properties: {
-        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
-        top: { type: 'number', description: 'How many colors to return, default 8' },
-      },
-      required: ['image'],
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const { bytes } = await readImageBytes(ctx, exec, args.image)
-      const top = Number.isInteger(args.top) && args.top > 0 ? args.top : 8
-      const sharp = await loadSharp()
-      if (!sharp) throw new Error('vision_colors: the sharp image library is unavailable')
-      const raw = await sharp(bytes, { failOn: 'none' })
-        .resize(64, 64, { fit: 'inside' })
-        .ensureAlpha()
-        .raw()
-        .toBuffer({ resolveWithObject: true })
-      const colors = quantizeColors(raw.data, Math.min(top, 32))
-      return JSON.stringify(colors)
-    },
-  })
-
-  // ── vision_ocr ───────────────────────────────────────────────────────────
-  tools.push({
-    name: 'vision_ocr',
-    description:
-      'Transcribe TEXT from an image with the vision model. ' +
-      'Returns the text and which engine produced it. ' +
-      'SCOPE: vision_ocr reads letters, it does NOT recognize people, objects or scenes. Never use it ' +
-      'as a fallback when vision_describe fails to identify who/what is in a picture ("这是谁" / ' +
-      '"这是什么东西" questions are answered by vision_describe, not OCR). If vision_describe returns ' +
-      'ok:false with a backend-unavailable code, calling vision_ocr instead will fail the same way — ' +
-      'do not chain these tools as retries of each other. ' +
-      'ACCURACY: OCR transcribes characters verbatim and is systematically unreliable for confusable ' +
-      'glyphs (1/l, 0/O), spacing and line breaks; prefer vision_describe / vision_detect for semantic ' +
-      'understanding and use OCR only when exact verbatim text is required (executable code, exact ' +
-      'quotation, forms/contracts, table digits, CAPTCHAs). Treat OCR output as evidence to verify, ' +
-      'never as ground truth.',
-    parameters: {
-      type: 'object',
-      properties: {
-        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
-        engine: {
-          type: 'string',
-          description: '"auto" (default) or "vision": transcribe with the configured vision model. "tesseract" is not available in this build.',
-        },
-      },
-      required: ['image'],
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const { bytes, mediaType } = await readImageBytes(ctx, exec, args.image)
-      const engine = args.engine === 'vision' ? 'vision' : 'auto'
-      if (args.engine === 'tesseract') {
-        throw new Error('vision_ocr: the local tesseract engine is not available in this build; use engine "auto" or "vision"')
-      }
-      const instruction =
-        '请原样转述图中的所有文字，保持阅读顺序（从上到下、从左到右）与段落结构，不要添加解释。只输出文字本身。'
-      const vision = await answerVisionForTool(bytes, mediaType, instruction, { exec })
-      if (vision.ok === false) {
-        return JSON.stringify({ engine: 'none', ...vision, text: '' })
-      }
-      return JSON.stringify({ engine, text: vision.text })
-    },
-  })
-
-  // ── vision_long_screenshot_ocr ───────────────────────────────────────────
-  tools.push({
-    name: 'vision_long_screenshot_ocr',
-    description:
-      'Transcribe a LONG screenshot (chat logs, long documents) into ordered Markdown. ' +
-      'Splits the image into overlapping horizontal chunks, OCRs each chunk with the vision ' +
-      'model, and stitches the text in reading order. Writes chunk PNGs, the Markdown, and a ' +
-      'manifest into the workspace artifacts directory.',
-    parameters: {
-      type: 'object',
-      properties: {
-        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
-        chunkHeight: { type: 'number', description: 'Chunk height in pixels, default 1200' },
-        overlap: { type: 'number', description: 'Overlap between adjacent chunks in pixels, default 120' },
-        engine: { type: 'string', description: '"auto" (default) or "vision": transcribe with the configured vision model.' },
-      },
-      required: ['image'],
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const { bytes, mediaType } = await readImageBytes(ctx, exec, args.image)
-      const sharp = await loadSharp()
-      if (!sharp) throw new Error('vision_long_screenshot_ocr: the sharp image library is unavailable')
-      const meta = await sharp(bytes, { failOn: 'none' }).metadata()
-      const width = meta.width ?? 0
-      const height = meta.height ?? 0
-      if (width <= 0 || height <= 0) {
-        throw new Error('vision_long_screenshot_ocr: could not read image dimensions')
-      }
-      const chunkHeight =
-        Number.isInteger(args.chunkHeight) && args.chunkHeight >= 400
-          ? Math.min(args.chunkHeight, 2000)
-          : 1200
-      const overlap =
-        Number.isInteger(args.overlap) && args.overlap >= 0
-          ? Math.min(args.overlap, Math.floor(chunkHeight / 2))
-          : 120
-      if (args.engine === 'tesseract') {
-        throw new Error('vision_long_screenshot_ocr: the local tesseract engine is not available in this build; use engine "auto" or "vision"')
-      }
-      const windows = boundedOcrTiles(width, height, {
-        chunkHeight,
-        overlap,
-        maxTilePixels: 4_000_000,
-      })
-      // Hard bounds: a tall screenshot must never turn into an unbounded,
-      // uncancellable model-call loop (router's 30s budget was dropped here,
-      // so re-introduce explicit limits).
-      const MAX_OCR_CHUNKS = 40
-      const OCR_TOTAL_BUDGET_MS = 120_000
-      const ocrStartedAt = Date.now()
-      const signal = exec && exec.signal
-      const stem = artifactStem(args.image, 'ocr')
-      const results = []
-      let visionFailed = false
-      for (let i = 0; i < windows.length; i++) {
-        if (signal?.aborted) break
-        if (i >= MAX_OCR_CHUNKS) {
-          results.push({
-            chunk: i + 1,
-            left: windows[i].left,
-            right: windows[i].right,
-            top: windows[i].top,
-            bottom: windows[i].bottom,
-            engine: 'skipped',
-            chars: 0,
-            text: '',
-            error: 'chunk limit reached',
-          })
-          continue
-        }
-        if (Date.now() - ocrStartedAt > OCR_TOTAL_BUDGET_MS) {
-          results.push({
-            chunk: i + 1,
-            left: windows[i].left,
-            right: windows[i].right,
-            top: windows[i].top,
-            bottom: windows[i].bottom,
-            engine: 'skipped',
-            chars: 0,
-            text: '',
-            error: 'OCR total budget exhausted',
-          })
-          continue
-        }
-        const { left, right, top, bottom } = windows[i]
-        const tileWidth = right - left
-        const tileHeight = bottom - top
-        const chunk = await sharp(bytes, { failOn: 'none' })
-          .extract({ left, top, width: tileWidth, height: tileHeight })
-          .png()
-          .toBuffer()
-        const chunkRel = `chunk-${String(i + 1).padStart(2, '0')}.png`
-        await writeArtifact(exec, join(stem, chunkRel), chunk)
-        let text = ''
-        let used = 'none'
-        // Upload JPEG without an alpha channel: some vision backends degrade
-        // on RGBA PNGs and hallucinate token-fragment text.
-        const visionBytes = await sharp(chunk, { failOn: 'none' })
-          .removeAlpha()
-          .jpeg({ quality: 92 })
-          .toBuffer()
-        const instruction =
-          '请原样转述这张长截图分片中的所有文字，保持阅读顺序（从上到下、从左到右），' +
-          '不要添加解释，只输出文字本身。如果画面中没有可见文字，只输出 EMPTY，不要编造内容。'
-        if (!visionFailed) {
-          const visionResult = await answerVisionForTool(visionBytes, 'image/jpeg', instruction, { exec })
-          if (visionResult.ok === false) {
-            // Backend failure: stop burning calls on the remaining chunks.
-            visionFailed = true
-            used = 'failed'
-          } else {
-            text = visionResult.text.trim()
-            if (text.length > 12000) {
-              const retry = await answerVisionForTool(
-                visionBytes,
-                'image/jpeg',
-                '重新转写这张图片中的真实文字，保持阅读顺序。只输出图中肉眼可见的文字，' +
-                  '禁止编造、禁止重复；总输出不超过 3000 字。没有任何文字就只输出 EMPTY。',
-                { exec },
-              )
-              if (retry.ok === false) {
-                visionFailed = true
-                used = 'failed'
-                text = ''
-              } else {
-                const retryText = retry.text.trim()
-                if (retryText !== '') text = retryText
-                used = 'vision'
-              }
-            } else {
-              used = 'vision'
-            }
-            if (text === 'EMPTY') text = ''
-          }
-        }
-        results.push({ chunk: i + 1, left, right, top, bottom, engine: used, chars: text.length, text })
-      }
-      const joined = results.map((r) => r.text).filter((t) => t !== '').join('\n\n')
-      const engines = {}
-      for (const r of results) engines[r.engine] = (engines[r.engine] ?? 0) + 1
-      const manifest = {
-        source: args.image,
-        width,
-        height,
-        chunkHeight,
-        overlap,
-        chunks: results.length,
-        engines,
-        perChunk: results.map(({ text, ...rest }) => rest),
-      }
-      const manifestPath = await writeArtifact(exec, join(stem, 'manifest.json'), JSON.stringify(manifest, null, 2))
-      const mdPath = await writeArtifact(exec, join(stem, 'ocr.md'), joined)
-      return JSON.stringify({
-        text: joined,
-        chunks: results.length,
-        engines,
-        markdownPath: mdPath,
-        manifestPath,
-        artifactsDir: dirname(mdPath),
-      })
-    },
-  })
-
-  // ── vision_trace ─────────────────────────────────────────────────────────
-  tools.push({
-    name: 'vision_trace',
-    description:
-      'Vectorize an image (icon/logo) into an SVG via a local potrace pipeline (no Python). ' +
-      'Default: COLOR-preserving vectorization — one path per dominant color with fill="#rrggbb". ' +
-      'Set color=false for the layered grayscale posterization, where `steps` (1-16, default 4) ' +
-      'controls levels. Writes the SVG as an artifact.',
-    parameters: {
-      type: 'object',
-      properties: {
-        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
-        steps: { type: 'number', description: 'Posterization steps, 1-16, default 4 (only when color=false)' },
-        color: { type: 'boolean', description: 'Preserve original colors (default true)' },
-        colors: { type: 'number', description: 'Number of dominant colors in color mode, 1-16, default 8' },
-      },
-      required: ['image'],
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const { bytes } = await readImageBytes(ctx, exec, args.image)
-      const steps = Number.isInteger(args.steps) && args.steps > 0 ? Math.min(args.steps, 16) : 4
-      const colorMode = args.color !== false
-      // Trace-specific pixel budget: vectorization gains nothing beyond ~1MP.
-      let traceBytes = bytes
-      if (bytes && bytes.length > 0) {
-        traceBytes = await downscaleImage(bytes, 1_000_000)
-      }
-      let svg
-      let colorCount = 0
-      try {
-        if (colorMode) {
-          const sharp = await loadSharp()
-          if (!sharp) throw new Error('vision_trace: the sharp image library is unavailable')
-          const colors = Number.isInteger(args.colors) && args.colors > 0 ? Math.min(args.colors, 16) : 8
-          const raw = await sharp(traceBytes, { failOn: 'none' }).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
-          const palette = quantizeColors(raw.data, colors)
-          colorCount = palette.length
-          svg = await posterizeSvgColor(raw.data, raw.info, palette, getConfig().timeoutMs || 60000)
-        } else {
-          svg = await posterizeSvg(traceBytes, steps, 'dominant', getConfig().timeoutMs || 60000)
-        }
-      } catch (error) {
-        throw new Error(
-          `vision_trace: potrace failed (${error && error.message ? error.message : String(error)}). ` +
-            'If potrace is missing, install the plugin dependencies in the profile (pnpm add potrace).',
-        )
-      }
-      const target = await saveArtifact(
-        exec,
-        `${artifactStem(args.image, colorMode ? 'trace-color' : `trace-${steps}`)}.svg`,
-        Buffer.from(svg),
-      )
-      return JSON.stringify({ path: target, bytes: Buffer.byteLength(svg), ...(colorMode ? { colors: colorCount } : {}) })
-    },
-  })
-
-  // ── vision_extract_foreground ────────────────────────────────────────────
-  tools.push({
-    name: 'vision_extract_foreground',
-    description:
-      'Remove a solid-ish background (border flood fill with color tolerance, no Python) and ' +
-      'write the cutout as a transparent PNG artifact. Best for logos on uniform backgrounds.',
-    parameters: {
-      type: 'object',
-      properties: {
-        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
-        tolerance: { type: 'number', description: 'Max per-channel color distance from the background, default 40' },
-      },
-      required: ['image'],
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const { bytes } = await readImageBytes(ctx, exec, args.image)
-      let fgBytes = bytes
-      if (bytes && bytes.length > 0) {
-        fgBytes = await downscaleImage(bytes, 4_000_000)
-      }
-      const tolerance = Number.isFinite(args.tolerance) && args.tolerance >= 0 ? Math.round(args.tolerance) : 40
-      const sharp = await loadSharp()
-      if (!sharp) throw new Error('vision_extract_foreground: the sharp image library is unavailable')
-      const { data, info } = await sharp(fgBytes, { failOn: 'none' })
-        .ensureAlpha()
-        .raw()
-        .toBuffer({ resolveWithObject: true })
-      const cutout = floodFillBackground(data, info.width, info.height, tolerance)
-      const png = await sharp(cutout, {
-        raw: { width: info.width, height: info.height, channels: 4 },
-      })
-        .png()
-        .toBuffer()
-      const target = await saveArtifact(exec, `${artifactStem(args.image, 'fg')}.png`, png)
-      return JSON.stringify({ path: target, width: info.width, height: info.height, bytes: png.length })
-    },
-  })
-
-  // ── vision_html_screenshot ───────────────────────────────────────────────
-  tools.push({
-    name: 'vision_html_screenshot',
-    description:
-      'Render a local .html/.htm file in the system Chrome (headless, network disabled by ' +
-      'default) and save a PNG screenshot as an artifact — the verify step of the ' +
-      'reference -> implementation -> screenshot -> pixel-diff loop. With fullPage: true the ' +
-      'page keeps the requested viewport but the whole scrollable height is captured and the ' +
-      'result JSON reports pageHeight (CSS px).',
-    parameters: {
-      type: 'object',
-      properties: {
-        source: { type: 'string', description: 'Local .html or .htm file path' },
-        width: { type: 'number', description: 'Viewport width, default 1200' },
-        height: { type: 'number', description: 'Viewport height, default 720' },
-        fullPage: {
-          type: 'boolean',
-          description:
-            'Capture the complete scrollable page height at the requested viewport width ' +
-            'instead of just the viewport (default false). Lazy-loaded images and ' +
-            'scroll-triggered reveals are woken first; the result JSON then includes ' +
-            'pageHeight (CSS px).',
-        },
-      },
-      required: ['source'],
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const source = String(args.source ?? '')
-      if (!/\.(html?|htm)$/i.test(source)) {
-        throw new Error('vision_html_screenshot: source must be a local .html/.htm file')
-      }
-      const fsService = ctx.get('fs')
-      if (fsService === undefined) {
-        throw new Error('vision_html_screenshot: the fs service is not available')
-      }
-      const resolved = await fsService.resolve(source)
-      const targetPath = toRealPath(fsService, resolved)
-      if (!existsSync(targetPath)) {
-        throw new Error(`vision_html_screenshot: file not found: ${source}`)
-      }
-      let puppeteer
-      try {
-        puppeteer = await import('puppeteer-core')
-      } catch {
-        throw new Error(
-          'vision_html_screenshot: puppeteer-core is not installed. Install the plugin dependencies in the profile (pnpm add puppeteer-core).',
-        )
-      }
-      const candidates = chromiumCandidates(
-        typeof process !== 'undefined' && process.env ? process.env : {},
-        typeof process !== 'undefined' ? process.platform : '',
-      )
-      const executablePath = candidates.find((p) => existsSync(p))
-      if (executablePath === undefined) {
-        throw new Error(
-          'vision_html_screenshot: no Chrome/Chromium/Edge found; install one or set CHROME_PATH / PUPPETEER_EXECUTABLE_PATH',
-        )
-      }
-      const width = Number.isInteger(args.width) && args.width > 0 ? args.width : 1200
-      const height = Number.isInteger(args.height) && args.height > 0 ? args.height : 720
-      const fullPage = args.fullPage === true
-      const launchArgs = ['--no-sandbox', '--disable-gpu', '--hide-scrollbars', '--incognito']
-      if (fullPage) {
-        launchArgs.push('--blink-settings=imagesLazyLoadingEnabled=false')
-      }
-      const browser = await puppeteer.default.launch({
-        executablePath,
-        headless: true,
-        args: launchArgs,
-      })
-      try {
-        const page = await browser.newPage()
-        await page.setViewport({ width, height })
-        // Honor the "network disabled by default" contract: the page may only
-        // load file:/data:/blob: subresources; everything else is aborted so
-        // a malicious local HTML cannot exfiltrate data or pull remote assets.
-        await page.setRequestInterception(true)
-        page.on('request', (request) => {
-          const url = request.url() ?? ''
-          if (/^(file|data|blob):/i.test(url)) request.continue()
-          else request.abort()
-        })
-        await page.goto(pathToFileURL(targetPath).href, { waitUntil: 'networkidle0', timeout: 30000 })
-        let pageHeight
-        if (fullPage) {
-          await wakePageForFullCapture(page, height)
-          pageHeight = await fullPageHeightOf(page)
-        }
-        const png = fullPage
-          ? await page.screenshot({ type: 'png', fullPage: true })
-          : await page.screenshot({ type: 'png' })
-        const stem = fullPage ? `shot-${width}x${height}-fullpage` : `shot-${width}x${height}`
-        const target = await saveArtifact(exec, `${artifactStem(source, stem)}.png`, png)
-        const result = { path: target, width, height, bytes: png.length }
-        if (fullPage) {
-          result.pageHeight = pageHeight
-        }
-        return JSON.stringify(result)
-      } finally {
-        await browser.close()
-      }
-    },
-  })
-
-  // ── vision_screenshot (privacy-gated: only registered when desktopScreenshot is enabled) ──
-  if (getConfig().desktopScreenshot === true) {
-    tools.push({
-      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: PowerShell CopyFromScreen; macOS: screencapture; Linux: ImageMagick import (falls back to scrot; either command must be installed). ' +
-      '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 recognition on the capture with the configured vision model and returns the description alongside the path.',
-    parameters: {
-      type: 'object',
-      properties: {
-        identify: {
-          type: 'boolean',
-          description:
-            'Also recognize the captured screen with the configured vision model and return the description text with the path. Default false.',
-        },
-      },
-      additionalProperties: false,
-    },
-    output: stringOutput,
-    async execute(args, exec) {
-      const tmp = join(
-        (typeof process !== 'undefined' && process.env && process.env.TMPDIR) || process.env.TEMP || '/tmp',
-        `vision-screenshot-${Date.now()}-${Math.floor(Math.random() * 1e9)}.png`,
-      )
-      const platform = process.platform
-      try {
-        if (platform === 'win32') {
-          const script = [
-            'Add-Type -AssemblyName System.Windows.Forms,System.Drawing',
-            '$b=[System.Windows.Forms.SystemInformation]::VirtualScreen',
-            '$bmp=New-Object System.Drawing.Bitmap($b.Width,$b.Height)',
-            '$g=[System.Drawing.Graphics]::FromImage($bmp)',
-            '$g.CopyFromScreen($b.X,$b.Y,0,0,$bmp.Size)',
-            `$bmp.Save('${tmp.replace(/'/g, "''")}')`,
-            '$g.Dispose();$bmp.Dispose()',
-          ].join('; ')
-          await promisify(execFile)('powershell.exe', ['-NoProfile', '-STA', '-Command', script], {
-            timeout: 60000,
-            windowsHide: true,
-          })
-        } else if (platform === 'darwin') {
-          await promisify(execFile)('screencapture', ['-x', '-m', tmp], {
-            timeout: 60000,
-            windowsHide: true,
-          })
-        } else {
-          try {
-            await promisify(execFile)('import', ['-window', 'root', tmp], { timeout: 60000 })
-          } catch {
-            await promisify(execFile)('scrot', [tmp], { timeout: 60000 })
-          }
-        }
-        if (!existsSync(tmp)) {
-          throw new Error(
-            `vision_screenshot: no output produced on ${platform} (is a screen available?)`,
-          )
-        }
-        const data = await readFileP(tmp)
-        const target = await saveArtifact(exec, `screenshot-${Date.now()}.png`, data)
-        const result = { path: target, bytes: data.length }
-        if (args.identify === true) {
-          let identifyBytes = data
-          try {
-            const sharp = await loadSharp()
-            if (sharp) {
-              const downscaled = await sharp(data, { failOn: 'none' })
-                .resize({ width: 1280, height: 1280, fit: 'inside', withoutEnlargement: true })
-                .png()
-                .toBuffer()
-              if (downscaled.length > 0 && downscaled.length < data.length) {
-                identifyBytes = downscaled
-              }
-            }
-          } catch {
-            /* keep the original capture */
-          }
-          const vision = await answerVisionForTool(
-            identifyBytes,
-            'image/png',
-            'Describe what is currently visible on the user\'s screen, in detail and in reading order. Mention the app/window names you can see.',
-            { exec },
-          )
-          if (vision.ok === false) {
-            result.identify = { ok: false, ...vision, text: '' }
-          } else {
-            result.identify = { ok: true, text: vision.text }
-          }
-        }
-        try {
-          await rmP(tmp, { force: true })
-        } catch {
-          /* best-effort cleanup */
-        }
-        return JSON.stringify(result)
-      } catch (error) {
-        throw new Error(
-          `vision_screenshot: failed (${error && error.message ? error.message : String(error)})`,
-        )
-      }
-    },
-    })
-  }
-
-  for (const def of tools) {
-    ctx.tools.register(def)
-  }
-  logger?.info?.('[tool-vision] registered %d pixel-level vision tools', tools.length)
-  return tools.length
-}
-
-// ── cache instance shared across tools ─────────────────────────────────────
-
-const visionCache = createCache(200, 3600 * 1000)
-let cacheDisabled = false
-
-function cacheEnabled() {
-  return !cacheDisabled
-}
-
-/** Test hook: reset the shared cache. */
-export function resetVisionCacheForTests() {
-  visionCache.clear()
-  cacheDisabled = false
-}
+// dsh-tool-vision — pixel-level vision tools (ported from dsh-vision-router).
+//
+// The 14 vision_* tools share ONE configured OpenAI-compatible endpoint
+// (the plugin's own baseURL/apiKey/model settings — the same GLM endpoint
+// inspect_image uses). No provider chain, no local models, no fallbacks:
+// the router's tool *semantics* (prompts, parameter contracts, pixel
+// post-processing) are kept; its routing/resilience machinery is not.
+//
+// Everything here is unit-testable without a harness: the only injected
+// dependencies are `ctx` (attachments/fs services), `getConfig` (live
+// settings) and `exec` (tool execution context).
+
+import { createHash } from 'node:crypto'
+import { join, dirname, isAbsolute, relative as relativePath, sep, win32 as winPath } from 'node:path'
+import { existsSync } from 'node:fs'
+import { mkdir as mkdirP, writeFile as writeFileP, readFile as readFileP, rm as rmP, stat as statP } from 'node:fs/promises'
+import { Worker } from 'node:worker_threads'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { pathToFileURL } from 'node:url'
+import { createRequire } from 'node:module'
+import { sessionHeaders } from './session-header.js'
+
+// ── image formats ──────────────────────────────────────────────────────────
+
+export const IMAGE_EXTENSIONS = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+  gif: 'image/gif',
+  bmp: 'image/bmp',
+  avif: 'image/avif',
+  svg: 'image/svg+xml',
+  ico: 'image/x-icon',
+}
+
+const EXT_BY_MEDIA = {
+  'image/png': '.png',
+  'image/jpeg': '.jpg',
+  'image/webp': '.webp',
+  'image/gif': '.gif',
+  'image/bmp': '.bmp',
+  'image/avif': '.avif',
+  'image/svg+xml': '.svg',
+  'image/x-icon': '.ico',
+}
+
+export function mediaTypeOf(path) {
+  const match = String(path).toLowerCase().match(/\.([a-z0-9]+)$/)
+  return match ? IMAGE_EXTENSIONS[match[1]] : undefined
+}
+
+/**
+ * Detect the image format from magic bytes instead of the file extension.
+ * Attachments are stored as content-addressed files WITHOUT an extension,
+ * so extension-based detection rejects them; the pixel tools must sniff.
+ */
+export function sniffMediaType(bytes) {
+  if (!bytes || bytes.length < 12) return undefined
+  const head = (offset, count) => {
+    const parts = []
+    for (let i = offset; i < offset + count; i++) parts.push(bytes[i].toString(16).padStart(2, '0'))
+    return parts.join('')
+  }
+  if (head(0, 8) === '89504e470d0a1a0a') return 'image/png'
+  if (head(0, 3) === 'ffd8ff') return 'image/jpeg'
+  const riff = head(0, 4)
+  const webp = head(8, 4)
+  if (riff === '52494646' && webp === '57454250') return 'image/webp'
+  if (riff === '47494638') return 'image/gif' // GIF87a / GIF89a
+  return undefined
+}
+
+// ── input resolution ───────────────────────────────────────────────────────
+
+export function basenameOf(path) {
+  const parts = String(path).split('/')
+  return parts[parts.length - 1] || undefined
+}
+
+/**
+ * True when the string is a durable attachment id such as "sha256:<hex>" —
+ * the form the harness uses for uploaded images.
+ */
+export function isAttachmentIdInput(input) {
+  return typeof input === 'string' && /^[a-z0-9]+:[0-9a-f]{32,}$/i.test(input.trim())
+}
+
+/** Cross-platform absolute-path test (posix drive-relative forms included). */
+export function isAbsolutePath(input) {
+  const value = String(input ?? '')
+  return isAbsolute(value) || winPath.isAbsolute(value)
+}
+
+/** Largest local image accepted by the pixel tools, in bytes. */
+export const MAX_IMAGE_BYTES = 20 * 1024 * 1024
+
+/** Resolve one tool argument (local path or attachment id) to image bytes. */
+export async function readImageBytes(ctx, exec, imagePath) {
+  const input = String(imagePath ?? '')
+  let bytes
+  let storedMediaType
+  if (isAttachmentIdInput(input)) {
+    const attachments = ctx.get('attachments')
+    if (attachments === undefined) {
+      throw new Error('tool-vision: the attachment service is not available in this deployment')
+    }
+    const session = exec && exec.agent && exec.agent.session
+    const ref = lookupAttachment(session, input.trim())
+    if (ref === undefined) {
+      throw new Error(
+        `tool-vision: unknown attachment id "${input}" (it must come from an image uploaded in this conversation)`,
+      )
+    }
+    let stored
+    try {
+      stored = await attachments.readImage(ref)
+    } catch (error) {
+      throw new Error(
+        `tool-vision: failed to read attachment ${input} (${error && error.message ? error.message : String(error)})`,
+      )
+    }
+    bytes = stored.data
+    if (bytes && bytes.length > MAX_IMAGE_BYTES) {
+      throw new Error(
+        `tool-vision: image too large: ${input} (${bytes.length} bytes, limit ${MAX_IMAGE_BYTES})`,
+      )
+    }
+    if (stored.ref && typeof stored.ref.mediaType === 'string') {
+      storedMediaType = stored.ref.mediaType
+    }
+  } else {
+    const fsService = ctx.get('fs')
+    if (fsService === undefined) throw new Error('tool-vision: the fs service is not available')
+    const resolved = await fsService.resolve(input)
+    const target = toRealPath(fsService, resolved)
+    // Second line of defense beyond the fs sandbox: a relative input must
+    // resolve inside the session workspace (refuse ../ escapes).
+    if (!isAbsolutePath(input)) {
+      const root = workspaceOf(exec)
+      const relative = relativePath(root, target)
+      if (relative === '..' || relative.startsWith('..' + sep) || isAbsolutePath(relative)) {
+        throw new Error(`tool-vision: path escapes the workspace: ${input}`)
+      }
+    }
+    // Pre-check size BEFORE reading: a huge file must not be buffered whole
+    // (readFileP has no limit and would OOM the process).
+    const info = await statP(target).catch(() => null)
+    if (info !== null && info.size > MAX_IMAGE_BYTES) {
+      throw new Error(
+        `tool-vision: image too large: ${input} (${info.size} bytes, limit ${MAX_IMAGE_BYTES})`,
+      )
+    }
+    bytes = await readFileP(target)
+    if (bytes.length > MAX_IMAGE_BYTES) {
+      throw new Error(`tool-vision: image too large: ${input} (${bytes.length} bytes, limit ${MAX_IMAGE_BYTES})`)
+    }
+  }
+  const mediaType = sniffMediaType(bytes) ?? storedMediaType ?? mediaTypeOf(input)
+  if (mediaType === undefined) {
+    throw new Error(`unsupported image format ${input} (png/jpeg/webp/gif only)`)
+  }
+  return { bytes, mediaType }
+}
+
+/** Find an uploaded attachment ref in the session's recorded upload index. */
+export function lookupAttachment(session, attachmentId) {
+  if (!session) return undefined
+  const recorded = session.recordedUploads
+  if (recorded) {
+    const ref = recorded.get ? recorded.get(attachmentId) : undefined
+    if (ref) return ref
+  }
+  const events = session.events ?? []
+  for (const event of events) {
+    const data = event && event.data
+    if (!data) continue
+    for (const block of Array.isArray(data.content) ? data.content : []) {
+      if (block && block.type === 'image' && block.attachment && block.attachment.attachmentId === attachmentId) {
+        return block.attachment
+      }
+    }
+    const message = data.message
+    if (message && Array.isArray(message.content)) {
+      for (const block of message.content) {
+        if (block && block.type === 'image' && block.attachment && block.attachment.attachmentId === attachmentId) {
+          return block.attachment
+        }
+      }
+    }
+  }
+  return undefined
+}
+
+/** Normalize an fs.resolve() result (string or { targetKey, displayPath }) to a real path. */
+export function toRealPath(fsService, resolved) {
+  if (typeof resolved === 'string') return resolved
+  if (typeof fsService?.processPath === 'function') {
+    const p = fsService.processPath(resolved)
+    if (typeof p === 'string' && p !== '') return p
+  }
+  const key = resolved?.targetKey
+  return typeof key === 'string' && key !== '' ? key : String(resolved ?? '')
+}
+
+// ── sharp (lazy) ───────────────────────────────────────────────────────────
+
+let sharpPromise = null
+
+/** Lazily load sharp; resolves null when the host cannot provide it. */
+export function loadSharp() {
+  if (!sharpPromise) {
+    sharpPromise = import('sharp')
+      .then((mod) => mod.default ?? mod)
+      .catch(() => null)
+  }
+  return sharpPromise
+}
+
+/**
+ * Downscale an image so its pixel count stays within maxPixels (router
+ * default 4MP). Returns the original buffer when the image is already small
+ * enough or when sharp is unavailable — pixel tools degrade gracefully
+ * instead of failing.
+ */
+export async function downscaleImage(bytes, maxPixels) {
+  if (!bytes || bytes.length === 0) return bytes
+  const sharp = await loadSharp()
+  if (!sharp) return bytes
+  try {
+    const image = sharp(bytes, { failOn: 'none' })
+    const meta = await image.metadata()
+    const width = Number(meta.width) || 0
+    const height = Number(meta.height) || 0
+    if (width <= 0 || height <= 0 || width * height <= maxPixels) return bytes
+    const scale = Math.sqrt(maxPixels / (width * height))
+    const resized = await image
+      .resize({
+        width: Math.max(1, Math.floor(width * scale)),
+        height: Math.max(1, Math.floor(height * scale)),
+        fit: 'inside',
+      })
+      .toBuffer()
+    return resized && resized.length > 0 ? resized : bytes
+  } catch {
+    return bytes
+  }
+}
+
+/** Image dimensions via sharp (0/0 when unavailable). */
+export async function imageDims(bytes) {
+  const sharp = await loadSharp()
+  if (!sharp) return { width: 0, height: 0 }
+  try {
+    const meta = await sharp(bytes, { failOn: 'none' }).metadata()
+    return { width: meta.width ?? 0, height: meta.height ?? 0 }
+  } catch {
+    return { width: 0, height: 0 }
+  }
+}
+
+// ── content-hash cache ─────────────────────────────────────────────────────
+
+export function sha256Of(bytes) {
+  return createHash('sha256').update(bytes).digest('hex')
+}
+
+/** Small LRU+TTL cache for repeated image+question calls (router semantics). */
+export function createCache(maxEntries, ttlMs) {
+  const map = new Map()
+  return {
+    get(key) {
+      const entry = map.get(key)
+      if (!entry) return undefined
+      if (entry.expires <= Date.now()) {
+        map.delete(key)
+        return undefined
+      }
+      map.delete(key)
+      map.set(key, entry)
+      return entry.value
+    },
+    set(key, value) {
+      if (map.size >= maxEntries) {
+        const oldest = map.keys().next().value
+        if (oldest !== undefined) map.delete(oldest)
+      }
+      map.set(key, { value, expires: Date.now() + ttlMs })
+    },
+    size() {
+      return map.size
+    },
+    clear() {
+      map.clear()
+    },
+  }
+}
+
+// ── artifacts (tool outputs land in the session workspace) ─────────────────
+
+export function workspaceOf(exec) {
+  const session = exec && exec.agent && exec.agent.session
+  const cwd = session && session.header && session.header.cwd
+  return typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd()
+}
+
+/** Write a tool artifact under <workspace>/.dsh-tool-vision/ and return its path.
+ *  Recursive: long-OCR writes stem/chunk-*.png subdirectories. */
+export async function writeArtifact(exec, relPath, data) {
+  const root = workspaceOf(exec)
+  const target = join(root, '.dsh-tool-vision', relPath)
+  await mkdirP(dirname(target), { recursive: true })
+  await writeFileP(target, data)
+  return target
+}
+
+/** Build an artifact filename stem from an input image reference. */
+export function artifactStemOf(imagePath, suffix) {
+  const base = String(basenameOf(imagePath) ?? 'image')
+    .replace(/\.(png|jpe?g|webp|gif)$/i, '')
+    .replace(/[^a-zA-Z0-9._-]/g, '-')
+    .slice(0, 32)
+  const fingerprint = createHash('sha256').update(String(imagePath)).digest('hex').slice(0, 8)
+  return `${base || 'image'}-${fingerprint}-${suffix}`
+}
+
+// ── JSON & prompt helpers ──────────────────────────────────────────────────
+
+const MAX_EXTRACT_JSON_CHARS = 200_000
+
+/** Extract the first balanced JSON value ({...} or [...]) from model output. */
+export function extractJson(text) {
+  const source = String(text ?? '')
+  const bounded = source.length > MAX_EXTRACT_JSON_CHARS
+    ? source.slice(0, MAX_EXTRACT_JSON_CHARS)
+    : source
+  const fenced = bounded.match(/```(?:json)?\s*([\s\S]*?)```/i)
+  const candidate = fenced ? fenced[1] : bounded
+  const start = candidate.search(/[[{]/)
+  if (start === -1) return undefined
+  const stack = []
+  let inString = false
+  let escaped = false
+  for (let index = start; index < candidate.length; index++) {
+    const char = candidate[index]
+    if (inString) {
+      if (escaped) escaped = false
+      else if (char === '\\') escaped = true
+      else if (char === '"') inString = false
+      continue
+    }
+    if (char === '"') {
+      inString = true
+      continue
+    }
+    if (char === '{') stack.push('}')
+    else if (char === '[') stack.push(']')
+    else if (char === '}' || char === ']') {
+      if (stack.length === 0 || stack.pop() !== char) return undefined
+      if (stack.length === 0) {
+        try {
+          const value = JSON.parse(candidate.slice(start, index + 1))
+          return typeof value === 'object' && value !== null ? value : undefined
+        } catch {
+          return undefined
+        }
+      }
+    }
+  }
+  return undefined
+}
+
+/** Legacy alias for callers of the earlier draft API. */
+export function parseModelJson(text) {
+  return extractJson(text)
+}
+
+/** Parse "x1,y1,x2,y2" (string) or {x1,y1,x2,y2} (object) into a valid pixel box. */
+export function parseBox(value) {
+  let box
+  if (typeof value === 'string') {
+    const parts = value.split(',').map((part) => Number(part.trim()))
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) return undefined
+    box = { x1: parts[0], y1: parts[1], x2: parts[2], y2: parts[3] }
+  } else if (value && typeof value === 'object') {
+    box = { x1: value.x1, y1: value.y1, x2: value.x2, y2: value.y2 }
+  } else {
+    return undefined
+  }
+  const { x1, y1, x2, y2 } = box
+  if (![x1, y1, x2, y2].every((n) => Number.isInteger(n))) return undefined
+  if (x1 < 0 || y1 < 0 || x2 <= x1 || y2 <= y1) return undefined
+  return { x1, y1, x2, y2 }
+}
+
+/** Fixed JSON contract for vision_detect. */
+export function visionDetectInstruction(target, width, height) {
+  return (
+    `The image is ${width}x${height} pixels. Find every "${String(target).slice(0, 300)}" in it. ` +
+    'Return ONE JSON object and nothing else, shaped EXACTLY as:\n' +
+    '{"elements":[{"label":"<short element name>","box":{"x1":0,"y1":0,"x2":0,"y2":0}},...]}\n' +
+    '- "elements" is a numbered list (array order = element number) of every match, from top-left to bottom-right in reading order;\n' +
+    '- every box is the tight bounding box in ORIGINAL image pixels, integers, 0 <= x1 < x2 <= ' +
+    `${width}, 0 <= y1 < y2 <= ${height}` +
+    ';\n- if nothing matches, return {"elements":[]}.'
+  )
+}
+
+/** Structured JSON contract for vision_describe's json:true mode. */
+export function describeStructuredInstruction(question) {
+  return (
+    `Look at the image and answer the question: 「${String(question).slice(0, 1500)}」. ` +
+    'Return ONE JSON object and nothing else, shaped EXACTLY as:\n' +
+    '{"summary":"<1-2 sentence answer to the question>",' +
+    '"layout":[{"region":"<e.g. top-left / header / center>","content":"<what is there>"}],' +
+    '"entities":[{"type":"<button|input|text|image|link|icon|other>","label":"<name or text>"}],' +
+    '"text":"<the full text visible in the image, transcribed in reading order, as faithful as possible>"}\n' +
+    '- "layout" lists the main regions in reading order (top-to-bottom, left-to-right);\n' +
+    '- "entities" lists notable elements; use only the listed type values;\n' +
+    '- "text" is the verbatim transcription; write "" when the image contains no text.'
+  )
+}
+
+/** Shared vision_describe prompt. */
+export function visionDescribePrompt(question, wantJson = false) {
+  const raw = String(question ?? '').trim()
+  const text = raw === ''
+    ? 'Describe the image accurately and answer based only on visible content.'
+    : raw
+  return wantJson ? text + '\n\n' + describeStructuredInstruction(text) : text
+}
+
+/** Normalize a vision_detect answer into the canonical shape, clamping boxes. */
+export function normalizeDetectResult(parsed, width, height) {
+  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.elements)) return undefined
+  const clamp = (value, min, max) => Math.max(min, Math.min(value, max))
+  const elements = []
+  for (const item of parsed.elements) {
+    if (!item || typeof item !== 'object' || !item.box || typeof item.box !== 'object') continue
+    const x1 = Math.round(Number(item.box.x1))
+    const y1 = Math.round(Number(item.box.y1))
+    const x2 = Math.round(Number(item.box.x2))
+    const y2 = Math.round(Number(item.box.y2))
+    if (![x1, y1, x2, y2].every(Number.isFinite)) continue
+    const box = {
+      x1: clamp(x1, 0, width - 1),
+      y1: clamp(y1, 0, height - 1),
+      x2: clamp(x2, 1, width),
+      y2: clamp(y2, 1, height),
+    }
+    if (box.x2 <= box.x1 || box.y2 <= box.y1) continue
+    elements.push({
+      number: elements.length + 1,
+      label: typeof item.label === 'string' && item.label.trim() !== '' ? item.label.trim() : `element ${elements.length + 1}`,
+      box,
+    })
+  }
+  return { width, height, elements }
+}
+
+/** Normalize a structured vision_describe answer with defaults for missing fields. */
+export function normalizeDescribeResult(parsed) {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined
+  const layout = Array.isArray(parsed.layout) ? parsed.layout.filter((r) => r && typeof r === 'object' && typeof r.region === 'string' && typeof r.content === 'string') : []
+  const entities = Array.isArray(parsed.entities)
+    ? parsed.entities
+        .filter((e) => e && typeof e === 'object' && typeof e.type === 'string' && typeof e.label === 'string')
+        .map((e) => ({ type: e.type, label: e.label }))
+    : []
+  return {
+    summary: typeof parsed.summary === 'string' ? parsed.summary : '',
+    layout,
+    entities,
+    text: typeof parsed.text === 'string' ? parsed.text : '',
+  }
+}
+
+// ── pixel operations ───────────────────────────────────────────────────────
+
+/** Per-pixel RGBA comparison; returns ratio, mask and worst 8x8 cells. */
+export function computePixelDiff(bufferA, bufferB, threshold = 16, width = 0, height = 0) {
+  const length = Math.min(bufferA.length, bufferB.length)
+  const pixels = Math.floor(length / 4)
+  let differing = 0
+  const mask = new Uint8Array(pixels)
+  for (let i = 0; i < pixels; i++) {
+    const o = i * 4
+    const d =
+      Math.max(
+        Math.abs(bufferA[o] - bufferB[o]),
+        Math.abs(bufferA[o + 1] - bufferB[o + 1]),
+        Math.abs(bufferA[o + 2] - bufferB[o + 2]),
+      ) - threshold
+    if (d > 0) {
+      differing += 1
+      mask[i] = 1
+    }
+  }
+  const ratio = pixels === 0 ? 0 : differing / pixels
+  const cells = []
+  if (width > 0 && height > 0) {
+    const cols = 8
+    const rows = 8
+    const cw = Math.ceil(width / cols)
+    const ch = Math.ceil(height / rows)
+    for (let cy = 0; cy < rows; cy++) {
+      for (let cx = 0; cx < cols; cx++) {
+        let hit = 0
+        let total = 0
+        for (let y = cy * ch; y < Math.min((cy + 1) * ch, height); y++) {
+          for (let x = cx * cw; x < Math.min((cx + 1) * cw, width); x++) {
+            total += 1
+            if (mask[y * width + x]) hit += 1
+          }
+        }
+        if (total > 0 && hit > 0) {
+          cells.push({
+            x1: cx * cw,
+            y1: cy * ch,
+            x2: Math.min((cx + 1) * cw, width),
+            y2: Math.min((cy + 1) * ch, height),
+            ratio: hit / total,
+            differing: hit,
+            total,
+          })
+        }
+      }
+    }
+    cells.sort((a, b) => b.ratio - a.ratio)
+  }
+  return { differing, total: pixels, ratio, mask, cells }
+}
+
+function asBuffer(chunk) {
+  if (Buffer.isBuffer(chunk)) return chunk
+  if (chunk instanceof Uint8Array) return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength)
+  return Buffer.from(chunk ?? [])
+}
+
+class AsyncByteReader {
+  constructor(iterable) {
+    if (!iterable || typeof iterable[Symbol.asyncIterator] !== 'function') {
+      throw new TypeError('pixel diff stream must be async iterable')
+    }
+    this.iterator = iterable[Symbol.asyncIterator]()
+    this.buffer = Buffer.alloc(0)
+    this.done = false
+  }
+
+  async fill(minBytes) {
+    while (!this.done && this.buffer.length < minBytes) {
+      const next = await this.iterator.next()
+      if (next.done) {
+        this.done = true
+        break
+      }
+      const chunk = asBuffer(next.value)
+      if (chunk.length === 0) continue
+      this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk])
+    }
+  }
+
+  consume(bytes) {
+    const out = this.buffer.subarray(0, bytes)
+    this.buffer = this.buffer.subarray(bytes)
+    return out
+  }
+}
+
+function cellBounds(index, width, height, cols, rows) {
+  const cx = index % cols
+  const cy = Math.floor(index / cols)
+  const cw = Math.ceil(width / cols)
+  const ch = Math.ceil(height / rows)
+  const x1 = cx * cw
+  const y1 = cy * ch
+  const x2 = Math.min((cx + 1) * cw, width)
+  const y2 = Math.min((cy + 1) * ch, height)
+  return { x1, y1, x2, y2, total: Math.max(0, x2 - x1) * Math.max(0, y2 - y1) }
+}
+
+/**
+ * Exact RGB pixel comparison over two RGBA async streams. The function never
+ * materializes either full frame; it holds only the current upstream chunks
+ * plus a bounded region counter grid.
+ */
+export async function compareRgbaStreams(
+  streamA,
+  streamB,
+  { width, height, threshold = 16, cols = 8, rows = 8 } = {},
+) {
+  const w = Math.max(1, Math.floor(Number(width) || 1))
+  const h = Math.max(1, Math.floor(Number(height) || 1))
+  const limit = w * h
+  const gate = Number.isFinite(Number(threshold)) && Number(threshold) >= 0
+    ? Number(threshold)
+    : 16
+  const gridCols = Math.min(w, Math.max(1, Math.floor(Number(cols) || 8)))
+  const gridRows = Math.min(h, Math.max(1, Math.floor(Number(rows) || 8)))
+  const cellDiff = new Uint32Array(gridCols * gridRows)
+  const readerA = new AsyncByteReader(streamA)
+  const readerB = new AsyncByteReader(streamB)
+  let pixels = 0
+  let differing = 0
+
+  while (pixels < limit) {
+    await Promise.all([readerA.fill(4), readerB.fill(4)])
+    if (readerA.buffer.length < 4 || readerB.buffer.length < 4) break
+    const remainingBytes = (limit - pixels) * 4
+    const usable = Math.min(
+      remainingBytes,
+      Math.floor(Math.min(readerA.buffer.length, readerB.buffer.length) / 4) * 4,
+    )
+    if (usable <= 0) break
+    const a = readerA.consume(usable)
+    const b = readerB.consume(usable)
+    const chunkPixels = usable / 4
+    for (let i = 0; i < chunkPixels; i++) {
+      const o = i * 4
+      const different =
+        Math.max(
+          Math.abs(a[o] - b[o]),
+          Math.abs(a[o + 1] - b[o + 1]),
+          Math.abs(a[o + 2] - b[o + 2]),
+        ) > gate
+      if (!different) continue
+      differing += 1
+      const absolute = pixels + i
+      const x = absolute % w
+      const y = Math.floor(absolute / w)
+      const cx = Math.min(gridCols - 1, Math.floor((x * gridCols) / w))
+      const cy = Math.min(gridRows - 1, Math.floor((y * gridRows) / h))
+      cellDiff[cy * gridCols + cx] += 1
+    }
+    pixels += chunkPixels
+  }
+
+  if (pixels !== limit) {
+    throw new Error(`pixel diff stream ended early (${pixels}/${limit} pixels)`)
+  }
+  await Promise.all([readerA.fill(1), readerB.fill(1)])
+  if (readerA.buffer.length > 0 || readerB.buffer.length > 0) {
+    throw new Error('pixel diff stream produced more RGBA bytes than the declared dimensions')
+  }
+
+  const cells = []
+  for (let index = 0; index < cellDiff.length; index++) {
+    const hit = cellDiff[index]
+    if (hit === 0) continue
+    const bounds = cellBounds(index, w, h, gridCols, gridRows)
+    if (bounds.total <= 0) continue
+    cells.push({
+      x1: bounds.x1,
+      y1: bounds.y1,
+      x2: bounds.x2,
+      y2: bounds.y2,
+      ratio: hit / bounds.total,
+      differing: hit,
+      total: bounds.total,
+    })
+  }
+  cells.sort((a, b) => b.ratio - a.ratio)
+  return { differing, total: limit, ratio: limit === 0 ? 0 : differing / limit, mask: null, cells }
+}
+
+/** Render a diff heatmap: grayscale base, red where the mask marks a differing pixel. */
+export function renderDiffHeatmap(originalRaw, mask, width, height) {  const out = Buffer.alloc(width * height * 4)
+  for (let i = 0; i < width * height; i++) {
+    const o = i * 4
+    const gray = Math.round(
+      0.299 * originalRaw[o] + 0.587 * originalRaw[o + 1] + 0.114 * originalRaw[o + 2],
+    )
+    if (mask[i]) {
+      out[o] = 255
+      out[o + 1] = 0
+      out[o + 2] = 0
+      out[o + 3] = 255
+    } else {
+      out[o] = gray
+      out[o + 1] = gray
+      out[o + 2] = gray
+      out[o + 3] = 255
+    }
+  }
+  return out
+}
+
+/** Dominant colors via bin quantization of an RGBA raw buffer. */
+export function quantizeColors(raw, topN = 8, bins = 32) {
+  const step = 256 / bins
+  const counts = new Map()
+  const pixels = Math.floor(raw.length / 4)
+  for (let i = 0; i < pixels; i++) {
+    const o = i * 4
+    if (raw[o + 3] < 128) continue
+    const r = Math.floor(raw[o] / step) * step
+    const g = Math.floor(raw[o + 1] / step) * step
+    const b = Math.floor(raw[o + 2] / step) * step
+    const key = `${r},${g},${b}`
+    counts.set(key, (counts.get(key) ?? 0) + 1)
+  }
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, topN)
+    .map(([key, count]) => {
+      const [r, g, b] = key.split(',').map(Number)
+      const hex = '#' + [r, g, b].map((v) => v.toString(16).padStart(2, '0')).join('')
+      return { hex, count, share: pixels === 0 ? 0 : count / pixels }
+    })
+}
+
+/** SVG overlay string drawing one red pixel box on a width x height canvas. */
+export function boxToSvg(box, width, height) {
+  return Buffer.from(
+    `<svg width="${width}" height="${height}">` +
+      `<rect x="${box.x1}" y="${box.y1}" width="${box.x2 - box.x1}" height="${box.y2 - box.y1}" ` +
+      `fill="none" stroke="#ff2d55" stroke-width="${Math.max(2, Math.round(Math.max(width, height) / 400))}"/></svg>`,
+  )
+}
+
+/** SVG overlay drawing numbered red boxes (detect inventory). */
+export function boxesToSvg(boxes, width, height) {
+  const stroke = Math.max(2, Math.round(Math.max(width, height) / 400))
+  const labelR = Math.max(10, stroke * 4)
+  const parts = [`<svg width="${width}" height="${height}">`]
+  for (let i = 0; i < boxes.length; i++) {
+    const box = boxes[i]
+    parts.push(
+      `<rect x="${box.x1}" y="${box.y1}" width="${box.x2 - box.x1}" height="${box.y2 - box.y1}" ` +
+        `fill="none" stroke="#ff2d55" stroke-width="${stroke}"/>`,
+    )
+    const cx = Math.max(labelR, Math.min(box.x1, width - labelR))
+    const cy = Math.max(labelR, Math.min(box.y1, height - labelR))
+    parts.push(
+      `<circle cx="${cx}" cy="${cy}" r="${labelR}" fill="#ff2d55"/>` +
+        `<text x="${cx}" y="${cy + labelR * 0.36}" text-anchor="middle" ` +
+        `font-family="sans-serif" font-size="${Math.round(labelR * 1.2)}" fill="#ffffff" ` +
+        `font-weight="bold">${i + 1}</text>`,
+    )
+  }
+  parts.push('</svg>')
+  return Buffer.from(parts.join(''))
+}
+
+export function scaledDimensions(width, height, maxPixels) {
+  const w = Math.max(0, Math.floor(Number(width) || 0))
+  const h = Math.max(0, Math.floor(Number(height) || 0))
+  const limit = Math.max(1, Math.floor(Number(maxPixels) || 1))
+  if (w <= 0 || h <= 0) return { width: w, height: h, scale: 1 }
+  const pixels = w * h
+  if (pixels <= limit) return { width: w, height: h, scale: 1 }
+  const scale = Math.sqrt(limit / pixels)
+  return {
+    width: Math.max(1, Math.floor(w * scale)),
+    height: Math.max(1, Math.floor(h * scale)),
+    scale,
+  }
+}
+
+export function scaleBox(box, fromWidth, fromHeight, toWidth, toHeight) {
+  const sx = fromWidth > 0 ? toWidth / fromWidth : 1
+  const sy = fromHeight > 0 ? toHeight / fromHeight : 1
+  return {
+    x1: Math.max(0, Math.round(box.x1 * sx)),
+    y1: Math.max(0, Math.round(box.y1 * sy)),
+    x2: Math.min(toWidth, Math.max(1, Math.round(box.x2 * sx))),
+    y2: Math.min(toHeight, Math.max(1, Math.round(box.y2 * sy))),
+  }
+}
+
+/** Draw one red pixel box onto an image buffer via sharp. */
+export async function annotateBoxBuffer(bytes, box) {
+  const sharp = await loadSharp()
+  if (!sharp) return bytes
+  const meta = await sharp(bytes, { failOn: 'none' }).metadata()
+  const width = meta.width ?? box.x2
+  const height = meta.height ?? box.y2
+  const preview = scaledDimensions(width, height, 4_000_000)
+  const displayBox = preview.scale === 1
+    ? box
+    : scaleBox(box, width, height, preview.width, preview.height)
+  let image = sharp(bytes, { failOn: 'none' })
+  if (preview.scale !== 1) image = image.resize(preview.width, preview.height, { fit: 'fill' })
+  return image
+    .composite([{ input: boxToSvg(displayBox, preview.width, preview.height), top: 0, left: 0 }])
+    .png()
+    .toBuffer()
+}
+
+/** Draw numbered boxes for a detected-element inventory onto an image buffer. */
+export async function annotateBoxesBuffer(bytes, boxes) {
+  const sharp = await loadSharp()
+  if (!sharp) return bytes
+  const meta = await sharp(bytes, { failOn: 'none' }).metadata()
+  const width = meta.width ?? 0
+  const height = meta.height ?? 0
+  if (width <= 0 || height <= 0 || boxes.length === 0) return bytes
+  const preview = scaledDimensions(width, height, 4_000_000)
+  const displayBoxes = preview.scale === 1
+    ? boxes
+    : boxes.map((box) => scaleBox(box, width, height, preview.width, preview.height))
+  let image = sharp(bytes, { failOn: 'none' })
+  if (preview.scale !== 1) image = image.resize(preview.width, preview.height, { fit: 'fill' })
+  return image
+    .composite([{ input: boxesToSvg(displayBoxes, preview.width, preview.height), top: 0, left: 0 }])
+    .png()
+    .toBuffer()
+}
+
+/** Remove a solid-ish background via border flood fill; background becomes transparent. */
+export function floodFillBackground(raw, width, height, tolerance = 40) {
+  const total = width * height
+  const out = Buffer.from(raw)
+  const marked = new Uint8Array(total)
+  let r = 0
+  let g = 0
+  let b = 0
+  const corners = [0, width - 1, (height - 1) * width, total - 1]
+  for (const c of corners) {
+    const o = c * 4
+    r += raw[o]
+    g += raw[o + 1]
+    b += raw[o + 2]
+  }
+  r /= 4
+  g /= 4
+  b /= 4
+  const queue = []
+  let head = 0
+  const push = (x, y) => {
+    const i = y * width + x
+    if (marked[i]) return
+    const o = i * 4
+    const d = Math.max(Math.abs(raw[o] - r), Math.abs(raw[o + 1] - g), Math.abs(raw[o + 2] - b))
+    if (d > tolerance) return
+    marked[i] = 1
+    queue.push(i)
+  }
+  for (let x = 0; x < width; x++) {
+    push(x, 0)
+    push(x, height - 1)
+  }
+  for (let y = 0; y < height; y++) {
+    push(0, y)
+    push(width - 1, y)
+  }
+  while (head < queue.length) {
+    const i = queue[head++]
+    const x = i % width
+    const y = (i - x) / width
+    if (x > 0) push(x - 1, y)
+    if (x < width - 1) push(x + 1, y)
+    if (y > 0) push(x, y - 1)
+    if (y < height - 1) push(x, y + 1)
+  }
+  for (let i = 0; i < total; i++) {
+    if (marked[i]) out[i * 4 + 3] = 0
+  }
+  return out
+}
+
+/** Cover a long/large image with bounded tiles in reading order. */
+export function boundedOcrTiles(
+  width,
+  height,
+  { chunkHeight = 1200, overlap = 120, maxTilePixels = 4_000_000 } = {},
+) {
+  const w = Math.max(1, Math.floor(Number(width) || 1))
+  const h = Math.max(1, Math.floor(Number(height) || 1))
+  const requestedHeight = Math.max(1, Math.min(h, Math.floor(Number(chunkHeight) || 1200)))
+  const pixelLimit = Math.max(1, Math.floor(Number(maxTilePixels) || 4_000_000))
+  const tileWidth = Math.min(w, Math.max(1, Math.floor(pixelLimit / requestedHeight)))
+  const tileHeight = Math.min(requestedHeight, Math.max(1, Math.floor(pixelLimit / tileWidth)))
+  const verticalOverlap = Math.min(
+    Math.max(0, Math.floor(Number(overlap) || 0)),
+    Math.max(0, Math.floor(tileHeight / 2)),
+  )
+  const verticalStep = Math.max(1, tileHeight - verticalOverlap)
+  const tiles = []
+  for (let top = 0; top < h; top += verticalStep) {
+    const bottom = Math.min(h, top + tileHeight)
+    for (let left = 0; left < w; left += tileWidth) {
+      const right = Math.min(w, left + tileWidth)
+      tiles.push({ left, right, top, bottom })
+    }
+    if (bottom >= h) break
+  }
+  return tiles
+}
+
+// ── potrace (worker-thread, hard timeout) ──────────────────────────────────
+
+function runPotraceWorker(workerData, source, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false
+    let worker
+    const finish = (error, svg) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      void worker?.terminate()
+      if (error) reject(error)
+      else resolve(svg)
+    }
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      void worker?.terminate()
+      reject(
+        new Error(
+          'potrace timed out — the image is too large or too complex; crop it to the target region first',
+        ),
+      )
+    }, timeoutMs)
+    try {
+      worker = new Worker(source, { eval: true, workerData })
+      worker.once('message', (message) => {
+        if (message && message.error) finish(new Error(message.error))
+        else finish(undefined, message && message.svg)
+      })
+      worker.once('error', (error) => finish(error))
+      worker.once('exit', (code) => {
+        if (code !== 0 && !settled) finish(new Error(`potrace worker exited with code ${code}`))
+      })
+    } catch (error) {
+      finish(error)
+    }
+  })
+}
+
+/** Vectorize an image buffer into an SVG string via potrace posterization. */
+export function posterizeSvg(bytes, steps = 4, fillStrategy = 'dominant', timeoutMs = 60000) {
+  const potraceUrl = pathToFileURL(createRequire(import.meta.url).resolve('potrace')).href
+  const source = `
+    import('node:worker_threads').then(({ parentPort, workerData }) => {
+      import(workerData.potraceUrl).then((mod) => {
+        const potrace = mod.default ?? mod
+        potrace.posterize(Buffer.from(workerData.bytes), {
+          steps: workerData.steps,
+          fillStrategy: workerData.fillStrategy,
+        }, (error, svg) => {
+          parentPort.postMessage(error ? { error: String((error && error.message) || error) } : { svg })
+        })
+      }).catch((error) => {
+        parentPort.postMessage({ error: String((error && error.message) || error) })
+      })
+    })
+  `
+  return runPotraceWorker({ potraceUrl, bytes, steps, fillStrategy }, source, timeoutMs)
+}
+
+/**
+ * Color-preserving vectorization: quantize into the top colors, trace one
+ * 1-bit mask per color with potrace, emit a colored SVG (one path per color).
+ */
+export function posterizeSvgColor(data, info, palette, timeoutMs = 60000) {
+  const sharpUrl = pathToFileURL(createRequire(import.meta.url).resolve('sharp')).href
+  const potraceUrl = pathToFileURL(createRequire(import.meta.url).resolve('potrace')).href
+  const source = `
+    import('node:worker_threads').then(({ parentPort, workerData }) => {
+      Promise.all([import(workerData.sharpUrl), import(workerData.potraceUrl)]).then(([sharpMod, potraceMod]) => {
+        const sharp = sharpMod.default ?? sharpMod
+        const potrace = potraceMod.default ?? potraceMod
+        const { width, height, palette } = workerData
+        const raw = Buffer.from(workerData.raw)
+        const hexRgb = (hex) => {
+          const n = parseInt(hex.slice(1), 16)
+          return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
+        }
+        const paletteRgb = palette.map((p) => hexRgb(p.hex))
+        const pixels = width * height
+        const masks = palette.map(() => Buffer.alloc(pixels))
+        for (let p = 0; p < pixels; p++) {
+          const o = p * 4
+          if (raw[o + 3] < 128) continue
+          let best = 0
+          let bestD = Infinity
+          for (let c = 0; c < paletteRgb.length; c++) {
+            const dr = raw[o] - paletteRgb[c][0]
+            const dg = raw[o + 1] - paletteRgb[c][1]
+            const db = raw[o + 2] - paletteRgb[c][2]
+            const d = dr * dr + dg * dg + db * db
+            if (d < bestD) { bestD = d; best = c }
+          }
+          masks[best][p] = 1
+        }
+        const paths = []
+        let pending = palette.length
+        const maybeDone = () => {
+          if (pending > 0) return
+          const pathSvg = paths.map((p) => '<path fill="' + p.hex + '" d="' + p.d + '"/>').join('')
+          parentPort.postMessage({
+            ok: true,
+            svg: '<svg xmlns="http://www.w3.org/2000/svg" width="' + width + '" height="' + height +
+              '" viewBox="0 0 ' + width + ' ' + height + '"><rect width="' + width + '" height="' + height +
+              '" fill="#ffffff"/>' + pathSvg + '</svg>',
+          })
+        }
+        if (pending === 0) { maybeDone(); return }
+        palette.forEach((entry, index) => {
+          const gray = Buffer.alloc(pixels)
+          const mask = masks[index]
+          for (let p = 0; p < pixels; p++) gray[p] = mask[p] ? 0 : 255
+          sharp(gray, { raw: { width, height, channels: 1 } })
+            .png()
+            .toBuffer()
+            .then((pngBuf) => {
+              potrace.trace(pngBuf, (err, svg) => {
+                pending -= 1
+                if (!err && svg) {
+                  const found = [...svg.matchAll(/d="([^"]+)"/g)].map((m) => m[1])
+                  for (const d of found) paths.push({ hex: entry.hex, d })
+                }
+                maybeDone()
+              })
+            })
+            .catch(() => {
+              pending -= 1
+              maybeDone()
+            })
+        })
+      }).catch((error) => {
+        parentPort.postMessage({ error: String((error && error.message) || error) })
+      })
+    })
+  `
+  return runPotraceWorker(
+    { sharpUrl, potraceUrl, width: info.width, height: info.height, palette, raw: data },
+    source,
+    timeoutMs,
+  )
+}
+
+// ── browser (HTML screenshot) ──────────────────────────────────────────────
+
+/** Cross-platform Chrome/Chromium/Edge discovery. */
+export function chromiumCandidates(env = {}, platform = typeof process !== 'undefined' ? process.platform : '') {
+  const out = []
+  const add = (value) => {
+    if (typeof value === 'string' && value !== '' && !out.includes(value)) out.push(value)
+  }
+  add(env.CHROME_PATH)
+  add(env.PUPPETEER_EXECUTABLE_PATH)
+
+  if (platform === 'win32') {
+    const pf = env.PROGRAMFILES
+    const pfx86 = env['PROGRAMFILES(X86)']
+    const local = env.LOCALAPPDATA
+    if (pf) {
+      add(winPath.join(pf, 'Google', 'Chrome', 'Application', 'chrome.exe'))
+      add(winPath.join(pf, 'Microsoft', 'Edge', 'Application', 'msedge.exe'))
+    }
+    if (pfx86) {
+      add(winPath.join(pfx86, 'Google', 'Chrome', 'Application', 'chrome.exe'))
+      add(winPath.join(pfx86, 'Microsoft', 'Edge', 'Application', 'msedge.exe'))
+    }
+    if (local) {
+      add(winPath.join(local, 'Google', 'Chrome', 'Application', 'chrome.exe'))
+      add(winPath.join(local, 'Microsoft', 'Edge', 'Application', 'msedge.exe'))
+      add(winPath.join(local, 'Chromium', 'Application', 'chrome.exe'))
+    }
+  } else if (platform === 'darwin') {
+    add('/Applications/Google Chrome.app/Contents/MacOS/Google Chrome')
+    add('/Applications/Chromium.app/Contents/MacOS/Chromium')
+    add('/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge')
+  } else {
+    add('/usr/bin/google-chrome')
+    add('/usr/bin/google-chrome-stable')
+    add('/usr/bin/chromium')
+    add('/usr/bin/chromium-browser')
+    add('/usr/bin/microsoft-edge')
+    add('/usr/bin/microsoft-edge-stable')
+  }
+  return out
+}
+
+/** Wake lazy/revealed content before a full-page capture. */
+export async function wakePageForFullCapture(page, viewportHeight) {
+  const step = Number.isInteger(viewportHeight) && viewportHeight > 0 ? viewportHeight : 720
+  await page.evaluate(() => {
+    document.documentElement.style.scrollBehavior = 'auto'
+  })
+  const total = await page.evaluate(() =>
+    Math.max(document.documentElement.scrollHeight, document.body ? document.body.scrollHeight : 0),
+  )
+  for (let y = 0; y < total; y += step) {
+    await page.evaluate((yy) => window.scrollTo(0, yy), y)
+    await new Promise((resolve) => setTimeout(resolve, 60))
+  }
+  await page.evaluate(() => window.scrollTo(0, 0))
+  await new Promise((resolve) => setTimeout(resolve, 800))
+}
+
+/** Full scrollable page height (CSS px). */
+export async function fullPageHeightOf(page) {
+  return await page.evaluate(() =>
+    Math.max(
+      document.documentElement.scrollHeight,
+      document.body ? document.body.scrollHeight : 0,
+      window.innerHeight,
+    ),
+  )
+}
+
+// ── model call (single configured endpoint) ────────────────────────────────
+
+/** Endpoint content-safety rejection markers (GLM: "系统检测到输入或生成内容
+ *  可能包含不安全或敏感内容…"; OpenAI-style: content_filter/policy/safety…). */
+export const CONTENT_FILTER_RE =
+  /敏感|不安全|内容审核|内容安全|政策|content.?filter|safety|inappropriate|flagged|拒绝.?内容|违反.*(规范|政策|安全)|violat/i
+
+export function resolveApiKey(config) {
+  if (config.apiKey) return config.apiKey
+  if (config.apiKeyEnv) {
+    const fromEnv = process.env[config.apiKeyEnv]
+    if (fromEnv) return fromEnv
+  }
+  return process.env.OPENAI_API_KEY ?? ''
+}
+
+/** Turn image bytes into a data URL for the vision call.
+ *  Defensive: attachment-service reads return Uint8Array (whose
+ *  toString('base64') is a comma-joined number list, not base64), so always
+ *  wrap in a real Buffer first. */
+export function bytesToDataUrl(bytes, mediaType) {
+  const mime = mediaType ?? 'image/png'
+  const buf = Buffer.isBuffer(bytes)
+    ? bytes
+    : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  return `data:${mime};base64,${buf.toString('base64')}`
+}
+
+/**
+ * One OpenAI-compatible chat/completions call with image content parts.
+ * This is the ONLY model-call path the ported tools use: the plugin's own
+ * baseURL/apiKey/model settings drive every vision_* tool, exactly like
+ * inspect_image.
+ */
+export async function callVisionModel(getConfig, prompt, imageUrls, options = {}) {
+  const cfg = getConfig()
+  const key = resolveApiKey(cfg)
+  if (!key) {
+    throw new Error(
+      'tool-vision: vision API key missing: set the plugin config (apiKey / apiKeyEnv) or the OPENAI_API_KEY environment variable',
+    )
+  }
+  const sessionHeader = sessionHeaders(cfg, options.exec)
+  const base = cfg.baseURL.endsWith('/') ? cfg.baseURL : `${cfg.baseURL}/`
+  const endpoint = new URL('chat/completions', base)
+  const controller = new AbortController()
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : cfg.timeoutMs
+  const timer = setTimeout(
+    () => controller.abort(new Error(`tool-vision: vision request timed out after ${timeoutMs}ms`)),
+    timeoutMs,
+  )
+  const signal = options.signal
+  const onSignalAbort = () => controller.abort(signal?.reason)
+  if (signal) {
+    if (signal.aborted) controller.abort()
+    else signal.addEventListener('abort', onSignalAbort, { once: true })
+  }
+  const content = [
+    { type: 'text', text: prompt },
+    ...imageUrls.map((url) => ({ type: 'image_url', image_url: { url } })),
+  ]
+  const bodyOf = () => JSON.stringify({
+    model: cfg.model,
+    messages: [{ role: 'user', content }],
+    max_tokens: Number.isFinite(options.maxTokens) ? options.maxTokens : cfg.maxTokens,
+  })
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+  const retryAfterOf = (response) => {
+    const header = response?.headers?.get?.('retry-after')
+    if (header) {
+      const seconds = Number(header)
+      if (Number.isFinite(seconds) && seconds > 0) return Math.min(seconds * 1000, 15000)
+    }
+    return 0
+  }
+  const MAX_TRANSIENT_RETRIES = 3
+  try {
+    let lastResponse = null
+    let lastBody = null
+    for (let attempt = 0; ; attempt++) {
+      const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${key}`,
+          ...sessionHeader,
+        },
+        body: bodyOf(),
+        signal: controller.signal,
+      })
+      lastResponse = response
+      lastBody = await response.json().catch(() => null)
+      // Transient failures (rate limit / 5xx) retry with backoff; everything
+      // else (4xx auth/format/content-filter) is terminal.
+      const retriable =
+        response.status === 429 ||
+        response.status === 408 ||
+        response.status === 500 ||
+        response.status === 502 ||
+        response.status === 503 ||
+        response.status === 504
+      if (!response.ok && retriable && attempt < MAX_TRANSIENT_RETRIES) {
+        const waitMs = retryAfterOf(response) || 800 * (attempt + 1)
+        await sleep(waitMs)
+        continue
+      }
+      break
+    }
+    const response = lastResponse
+    const body = lastBody
+    if (!response.ok) {
+      const detailText = body?.error?.message ?? response.statusText
+      throw new Error(
+        `tool-vision: vision endpoint returned ${response.status}: ${detailText} (endpoint ${endpoint})`,
+      )
+    }
+    const message = body?.choices?.[0]?.message
+    let answer = message?.content ?? ''
+    if (!answer.trim()) answer = message?.reasoning_content ?? ''
+    if (typeof answer !== 'string' || !answer.trim()) {
+      throw new Error('tool-vision: vision endpoint returned an empty response')
+    }
+    const trimmed = answer.trim()
+    // max_tokens truncation: glm-4v-flash caps at 1024; a truncated JSON or
+    // transcript must not masquerade as a complete answer.
+    const finishReason = body?.choices?.[0]?.finish_reason
+    if (finishReason === 'length') {
+      return `${trimmed}\n\n[注意:模型输出因 max_tokens 上限被截断(finish_reason=length);以上内容不完整。]`
+    }
+    return trimmed
+  } finally {
+    clearTimeout(timer)
+    signal?.removeEventListener('abort', onSignalAbort)
+  }
+}
+
+// ── shared tool plumbing ───────────────────────────────────────────────────
+
+export const stringOutput = {
+  schema: { type: 'string' },
+  render: (_args, value) => [{ type: 'text', text: value }],
+}
+
+/**
+ * Build the 14 vision tools bound to this plugin instance.
+ * @param {object} ctx - plugin context (attachments/fs services via ctx.get)
+ * @param {() => object} getConfig - live settings getter
+ */
+export function registerVisionTools(ctx, getConfig) {
+  const logger = ctx.logger
+
+  /** Single-endpoint model call wrapper with the router's ok:false contract.
+   *  `images` is a single Buffer, or an array of Buffers / data-URL strings. */
+  const answerVisionForTool = async (images, mediaType, instruction, options = {}) => {
+    try {
+      // Uniform pixel budget for EVERY model call: ground/detect/ocr/etc.
+      // must not ship raw 20MB images (base64 ~27MB -> endpoint 413/timeout).
+      // Downscale only Buffer inputs; pre-made data URLs pass through.
+      const bounded = Array.isArray(images)
+        ? await Promise.all(images.map(async (item) => (typeof item === 'string' ? item : bytesToDataUrl(await downscaleImage(item, 4_000_000), mediaType ?? 'image/png'))))
+        : [bytesToDataUrl(await downscaleImage(images, 4_000_000), mediaType)]
+      const text = await callVisionModel(getConfig, instruction, bounded, {
+        signal: options.signal ?? (options.exec && options.exec.signal),
+        exec: options.exec,
+      })
+      return { ok: true, text }
+    } catch (error) {
+      const raw = error && error.message ? String(error.message) : String(error)
+      // Endpoint content-safety rejections are NOT backend outages: the image
+      // itself was refused. Surface them distinctly so the model tells the
+      // user to pick a different image instead of reporting "vision down".
+      if (CONTENT_FILTER_RE.test(raw)) {
+        return {
+          ok: false,
+          code: 'VISION_CONTENT_FILTERED',
+          retryable: false,
+          contentFiltered: true,
+          message:
+            '图片被视觉端点的内容安全策略拒绝(检测到敏感或不安全内容)。' +
+            '这不是网络或配置问题,请换一张图片或调整图片内容后再试。',
+        }
+      }
+      return {
+        ok: false,
+        code: 'VISION_BACKEND_UNAVAILABLE',
+        retryable: false,
+        message: raw,
+      }
+    }
+  }
+
+  const saveArtifact = (exec, relPath, data) => writeArtifact(exec, relPath, data)
+  const artifactStem = (imagePath, suffix) => artifactStemOf(imagePath, suffix)
+
+  const tools = []
+
+  // ── vision_describe ──────────────────────────────────────────────────────
+  tools.push({
+    name: 'vision_describe',
+    description:
+      'Look at images with the configured vision model and answer a focused question about them. ' +
+      'For text-only sessions this is the bridge that provides image understanding. ' +
+      'Supports comparing multiple images (e.g. a design mock vs an implementation screenshot). Provide ' +
+      '`paths` (absolute local image file paths, png/jpeg/webp/gif) and/or ' +
+      '`attachmentIds` (ids of images the user uploaded in this conversation), 1-4 images in ' +
+      'total. `question` is the question to answer; be specific. Set `json: true` to require a ' +
+      'single valid JSON object as the answer. ' +
+      'FAILURE SEMANTICS: if the result is JSON with ok:false, the vision backend is unavailable. ' +
+      'Do NOT call vision_describe again with a reworded question — rephrasing cannot fix an auth, ' +
+      'rate-limit or outage problem. Answer from the information you already have and continue the ' +
+      'text task, telling the user vision is temporarily unavailable.',
+    parameters: {
+      type: 'object',
+      properties: {
+        paths: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Absolute local image file paths and/or attachment ids (e.g. "sha256:...") of uploaded images, 1-4 images',
+        },
+        attachmentIds: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Attachment ids of images uploaded earlier in this conversation',
+        },
+        question: {
+          type: 'string',
+          description:
+            'The question for the vision model, e.g. "compare the two images and list the differences"',
+        },
+        json: {
+          type: 'boolean',
+          description: 'Require the answer to be a single valid JSON object',
+        },
+      },
+      required: ['question'],
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const attachments = ctx.get('attachments')
+      if (attachments === undefined) {
+        throw new Error('vision_describe: the durable attachment service is not available in this deployment')
+      }
+      const blocks = []
+      const contentIds = []
+      const paths = Array.isArray(args.paths) ? args.paths : []
+      const attachmentIds = Array.isArray(args.attachmentIds) ? args.attachmentIds : []
+      if (paths.length + attachmentIds.length === 0 || paths.length + attachmentIds.length > 4) {
+        throw new Error('vision_describe: provide 1-4 images via paths and/or attachmentIds')
+      }
+
+      for (const path of paths) {
+        let bytes
+        let mediaType
+        try {
+          ;({ bytes, mediaType } = await readImageBytes(ctx, exec, path))
+        } catch (error) {
+          throw new Error(
+            `vision_describe: failed to read ${path} (${error && error.message ? error.message : String(error)})`,
+          )
+        }
+        bytes = await downscaleImage(bytes, 4_000_000)
+        let ref
+        try {
+          ref = await attachments.saveImage({ data: bytes, mediaType })
+        } catch (error) {
+          throw new Error(
+            `vision_describe: image ${path} was rejected (${error && error.message ? error.message : String(error)})`,
+          )
+        }
+        contentIds.push(String(ref.attachmentId))
+        blocks.push({ type: 'image', attachment: ref })
+      }
+
+      for (const id of attachmentIds) {
+        const session = exec && exec.agent && exec.agent.session
+        const ref = lookupAttachment(session, String(id))
+        if (ref === undefined) {
+          throw new Error(
+            `vision_describe: unknown attachment id "${id}" (it must come from an image uploaded in this conversation)`,
+          )
+        }
+        let stored
+        try {
+          stored = await attachments.readImage(ref)
+        } catch (error) {
+          throw new Error(
+            `vision_describe: failed to read attachment ${id} (${error && error.message ? error.message : String(error)})`,
+          )
+        }
+        if (stored.data && stored.data.length > 0) {
+          const resized = await downscaleImage(stored.data, 4_000_000)
+          if (resized !== stored.data) {
+            try {
+              const resizedRef = await attachments.saveImage({
+                data: resized,
+                mediaType: stored.ref && stored.ref.mediaType ? stored.ref.mediaType : 'image/png',
+                ...(stored.ref && stored.ref.name ? { name: stored.ref.name } : {}),
+              })
+              stored = { ref: resizedRef, data: resized }
+            } catch {
+              stored = { ...stored, data: resized }
+            }
+          }
+        }
+        contentIds.push(String(ref.attachmentId))
+        blocks.push({ type: 'image', attachment: stored.ref })
+      }
+
+      const question = String(args.question ?? '')
+      const wantJson = args.json === true
+      const promptText = visionDescribePrompt(question, wantJson)
+      // Cache key carries the endpoint/model identity: switching the vision
+      // model must never serve stale answers from the previous model.
+      const cfg = getConfig()
+      const key = `${cfg.baseURL ?? ''}|${cfg.model ?? ''}|${contentIds.join('|')}|${wantJson ? 'json' : 'text'}|${question}`
+      const cache = visionCache
+      if (cacheEnabled()) {
+        const hit = cache.get(key)
+        if (hit !== undefined) return hit
+      }
+
+      // Call with all images as data URLs.
+      const imageUrls = []
+      for (const block of blocks) {
+        const stored = await attachments.readImage(block.attachment)
+        imageUrls.push(bytesToDataUrl(stored.data, stored.ref && stored.ref.mediaType ? stored.ref.mediaType : 'image/png'))
+      }
+      const vision = await answerVisionForTool(imageUrls, 'image/png', promptText, { exec })
+      if (vision.ok === false) return JSON.stringify(vision)
+
+      let text = vision.text
+      if (wantJson) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+          const parsed = extractJson(text)
+          if (parsed !== undefined) {
+            const compact = JSON.stringify(normalizeDescribeResult(parsed) ?? parsed)
+            if (cacheEnabled()) cache.set(key, compact)
+            return compact
+          }
+          if (attempt === 0) {
+            const retry = await answerVisionForTool(imageUrls, 'image/png', promptText + '\n\nThat output was not valid JSON. Respond with ONLY a valid JSON object now.', { exec })
+            if (retry.ok === false) return JSON.stringify(retry)
+            text = retry.text
+          }
+        }
+        // Failure/fallback output must NOT be cached: it would poison the
+        // cache for the whole TTL with an error string masquerading as an
+        // answer.
+        return `vision_describe: the model did not produce valid JSON. Raw output:\n${text.slice(0, 2000)}`
+      }
+      if (text !== '') {
+        if (cacheEnabled()) cache.set(key, text)
+        return text
+      }
+      // Empty output is a failure signal, not a cacheable answer.
+      return '(the vision model returned empty content)'
+    },
+  })
+
+  // ── vision_materialize ───────────────────────────────────────────────────
+  tools.push({
+    name: 'vision_materialize',
+    description:
+      'Copy an uploaded image attachment (sha256:...) or readable local image into the session workspace and return a real filesystem path. ' +
+      'This tool performs NO vision model/network call. Use it after vision_describe returns ok:false when a local OCR/parser accepts only file_path. ' +
+      'Never guess the attachment store path or search for a same-named file.',
+    parameters: {
+      type: 'object',
+      properties: {
+        image: { type: 'string', description: 'Uploaded image attachment id (recommended, e.g. sha256:...) or a readable local image path' },
+      },
+      required: ['image'],
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const source = String(args.image ?? '')
+      const { bytes, mediaType } = await readImageBytes(ctx, exec, source)
+      const extension = mediaType === 'image/jpeg' ? '.jpg' : (EXT_BY_MEDIA[mediaType] ?? '.png')
+      const target = await saveArtifact(exec, `${artifactStem(source, 'materialized')}${extension}`, bytes)
+      return JSON.stringify({ path: target, bytes: bytes.length, mediaType })
+    },
+  })
+
+  // ── vision_ground ────────────────────────────────────────────────────────
+  tools.push({
+    name: 'vision_ground',
+    description:
+      'Locate a target in an image and return its ORIGINAL-pixel bounding box (x1/y1/x2/y2), ' +
+      'optionally producing an annotated PNG artifact. Pair with vision_crop and vision_pixel_diff ' +
+      'for a verify-able pixel loop (reference -> implementation -> screenshot -> metrics). ' +
+      'If the result is JSON with ok:false, the vision backend is unavailable — do not retry with ' +
+      'reworded instructions this turn.',
+    parameters: {
+      type: 'object',
+      properties: {
+        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
+        target: { type: 'string', description: 'What to locate, e.g. "the send button"' },
+        annotate: { type: 'boolean', description: 'Also write an annotated PNG with the box drawn (default true)' },
+      },
+      required: ['image', 'target'],
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const { bytes, mediaType } = await readImageBytes(ctx, exec, args.image)
+      const { width, height } = await imageDims(bytes)
+      if (width <= 0 || height <= 0) throw new Error('vision_ground: could not read image dimensions')
+      const instruction =
+        `Target to locate: "${String(args.target).slice(0, 500)}". ` +
+        `The image is ${width}x${height} pixels. Return ONE JSON object with integer fields ` +
+        `{"x1":...,"y1":...,"x2":...,"y2":...} — the tight bounding box of that target in ` +
+        `ORIGINAL image pixels (0 <= x1 < x2 <= ${width}, 0 <= y1 < y2 <= ${height}). ` +
+        `Output only the JSON object.`
+      const vision = await answerVisionForTool(bytes, mediaType, instruction, { exec })
+      if (vision.ok === false) return JSON.stringify(vision)
+      const parsed = extractJson(vision.text)
+      const box = parsed !== undefined ? parseBox(parsed) : undefined
+      if (box === undefined) {
+        throw new Error(`vision_ground: the vision model did not return a valid box. Raw output: ${vision.text.slice(0, 500)}`)
+      }
+      let clamped = {
+        x1: Math.max(0, Math.min(box.x1, width - 1)),
+        y1: Math.max(0, Math.min(box.y1, height - 1)),
+        x2: Math.max(1, Math.min(box.x2, width)),
+        y2: Math.max(1, Math.min(box.y2, height)),
+      }
+      if (clamped.x2 - clamped.x1 < 2 || clamped.y2 - clamped.y1 < 2) {
+        const retry = await answerVisionForTool(
+          bytes,
+          mediaType,
+          `Your previous box ${JSON.stringify(clamped)} was a degenerate sliver, not the target. ` +
+            `Return ONE JSON object with the FULL tight bounding box of the target in ORIGINAL ` +
+            `image pixels (0 <= x1 < x2 <= ${width}, 0 <= y1 < y2 <= ${height}). Output only the JSON object.`,
+          { exec },
+        )
+        if (retry.ok === false) return JSON.stringify(retry)
+        const retryParsed = extractJson(retry.text)
+        const retryBox = retryParsed !== undefined ? parseBox(retryParsed) : undefined
+        if (retryBox === undefined) {
+          throw new Error(
+            `vision_ground: the vision model returned a degenerate box (${clamped.x1},${clamped.y1},${clamped.x2},${clamped.y2}) ` +
+              `and the retry returned no valid box. Raw output: ${retry.text.slice(0, 500)}`,
+          )
+        }
+        clamped = {
+          x1: Math.max(0, Math.min(retryBox.x1, width - 1)),
+          y1: Math.max(0, Math.min(retryBox.y1, height - 1)),
+          x2: Math.max(1, Math.min(retryBox.x2, width)),
+          y2: Math.max(1, Math.min(retryBox.y2, height)),
+        }
+        if (clamped.x2 - clamped.x1 < 2 || clamped.y2 - clamped.y1 < 2) {
+          throw new Error(
+            `vision_ground: the vision model returned only degenerate boxes for a ${width}x${height} image. ` +
+              `Last raw output: ${retry.text.slice(0, 500)}`,
+          )
+        }
+      }
+      const result = { ...clamped, width, height }
+      if (args.annotate !== false) {
+        const annotated = await annotateBoxBuffer(bytes, clamped)
+        result.annotatedPath = await saveArtifact(exec, `${artifactStem(args.image, 'ground')}.png`, annotated)
+      }
+      return JSON.stringify(result)
+    },
+  })
+
+  // ── vision_detect ────────────────────────────────────────────────────────
+  tools.push({
+    name: 'vision_detect',
+    description:
+      'Find every element of a kind in an image (buttons, inputs, links, icons…) and return a ' +
+      'numbered inventory with ORIGINAL-pixel boxes, optionally annotated on the image. The model ' +
+      'can then reference "element #3" in follow-up vision_crop / vision_describe calls. ' +
+      'If the result is JSON with ok:false, the vision backend is unavailable — do not retry with ' +
+      'reworded instructions this turn.',
+    parameters: {
+      type: 'object',
+      properties: {
+        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
+        target: {
+          type: 'string',
+          description: 'What kind of elements to list, e.g. "buttons", "input fields", "navigation links" (default: interactive elements)',
+        },
+        annotate: {
+          type: 'boolean',
+          description: 'Also write an annotated PNG with numbered boxes (default true)',
+        },
+      },
+      required: ['image'],
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const { bytes, mediaType } = await readImageBytes(ctx, exec, args.image)
+      const { width, height } = await imageDims(bytes)
+      if (width <= 0 || height <= 0) throw new Error('vision_detect: could not read image dimensions')
+      const target = typeof args.target === 'string' && args.target.trim() !== '' ? args.target : 'interactive elements'
+      const vision = await answerVisionForTool(bytes, mediaType, visionDetectInstruction(target, width, height), { exec })
+      if (vision.ok === false) return JSON.stringify(vision)
+      let text = vision.text
+      let parsed = extractJson(text)
+      if (parsed === undefined) {
+        const retry = await answerVisionForTool(
+          bytes,
+          mediaType,
+          visionDetectInstruction(target, width, height) +
+            '\nYour previous answer was not valid JSON. Respond with ONLY the JSON object, no prose, no fences.',
+          { exec },
+        )
+        if (retry.ok === false) return JSON.stringify(retry)
+        parsed = extractJson(retry.text)
+        text = retry.text
+      }
+      const result = normalizeDetectResult(parsed, width, height)
+      if (result === undefined) {
+        throw new Error(`vision_detect: the vision model did not return a valid inventory. Raw output: ${text.slice(0, 500)}`)
+      }
+      if (args.annotate !== false && result.elements.length > 0) {
+        const annotated = await annotateBoxesBuffer(bytes, result.elements.map((e) => e.box))
+        result.annotatedPath = await saveArtifact(exec, `${artifactStem(args.image, 'detect')}.png`, annotated)
+      }
+      return JSON.stringify(result)
+    },
+  })
+
+  // ── vision_crop ──────────────────────────────────────────────────────────
+  tools.push({
+    name: 'vision_crop',
+    description:
+      'Crop a pixel region (x1,y1,x2,y2 in ORIGINAL pixels) out of an image and write the ' +
+      'result as a PNG artifact for a closer look. Very large regions are rendered as a bounded ' +
+      'preview; crop a smaller ORIGINAL-pixel region when tiny details must be preserved.',
+    parameters: {
+      type: 'object',
+      properties: {
+        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
+        region: {
+          type: 'string',
+          description: 'Pixel box "x1,y1,x2,y2" in original image coordinates',
+        },
+      },
+      required: ['image', 'region'],
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const { bytes } = await readImageBytes(ctx, exec, args.image)
+      const { width, height } = await imageDims(bytes)
+      const box = parseBox(args.region)
+      if (box === undefined) {
+        throw new Error(`vision_crop: invalid region "${args.region}" (expect "x1,y1,x2,y2" integers)`)
+      }
+      if (box.x2 > width || box.y2 > height) {
+        throw new Error(`vision_crop: region exceeds image bounds (${width}x${height})`)
+      }
+      const sharp = await loadSharp()
+      if (!sharp) throw new Error('vision_crop: the sharp image library is unavailable')
+      const sourceWidth = box.x2 - box.x1
+      const sourceHeight = box.y2 - box.y1
+      const preview = scaledDimensions(sourceWidth, sourceHeight, 4_000_000)
+      let pipeline = sharp(bytes, { failOn: 'none' }).extract({
+        left: box.x1,
+        top: box.y1,
+        width: sourceWidth,
+        height: sourceHeight,
+      })
+      if (preview.scale !== 1) {
+        pipeline = pipeline.resize(preview.width, preview.height, { fit: 'fill' })
+      }
+      const cropped = await pipeline.png().toBuffer()
+      const target = await saveArtifact(
+        exec,
+        `${artifactStem(args.image, `crop-${box.x1}-${box.y1}-${box.x2}-${box.y2}`)}.png`,
+        cropped,
+      )
+      const meta = await sharp(cropped).metadata()
+      return JSON.stringify({
+        path: target,
+        width: meta.width ?? preview.width,
+        height: meta.height ?? preview.height,
+        bytes: cropped.length,
+        ...(preview.scale !== 1
+          ? {
+              preview: true,
+              sourceRegion: box,
+              sourceWidth,
+              sourceHeight,
+              scale: preview.scale,
+              advice: 'This was a bounded preview of a large crop. Use vision_crop again with a smaller ORIGINAL-pixel region for tiny details.',
+            }
+          : {}),
+      })
+    },
+  })
+
+  // ── vision_present ───────────────────────────────────────────────────────
+  const visionPresentOutput = {
+    schema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string' },
+        label: { type: 'string' },
+        width: { type: 'number' },
+        height: { type: 'number' },
+        bytes: { type: 'number' },
+        safePresentation: { type: 'boolean' },
+        attachment: {
+          type: 'object',
+          properties: {
+            attachmentId: { type: 'string' },
+            mediaType: { type: 'string' },
+            bytes: { type: 'number' },
+            width: { type: 'number' },
+            height: { type: 'number' },
+            name: { type: 'string' },
+          },
+          required: ['attachmentId', 'mediaType', 'bytes', 'width', 'height'],
+          additionalProperties: false,
+        },
+      },
+      required: ['path', 'label', 'width', 'height', 'bytes', 'safePresentation', 'attachment'],
+      additionalProperties: false,
+    },
+    render: (_args, value) => {
+      const attachment = value.attachment
+      return [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            path: value.path,
+            label: value.label,
+            width: value.width,
+            height: value.height,
+            bytes: value.bytes,
+            safePresentation: true,
+            attachmentId: String(attachment.attachmentId),
+          }),
+        },
+        { type: 'image', attachment },
+      ]
+    },
+  }
+  tools.push({
+    name: 'vision_present',
+    description:
+      'Present a generated local image directly to the user with the host-native image preview. ' +
+      'MANDATORY PRESENTATION RULE: when you generate, edit, screenshot, or export an image and want the user to see it, ' +
+      'you MUST call vision_present. read_image is only for model-side inspection; NEVER use read_image to present or send ' +
+      'an image to the user. The image is retained in the session UI but sanitized out of later text-only model requests.',
+    parameters: {
+      type: 'object',
+      properties: {
+        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
+        label: { type: 'string', description: 'Optional short user-facing label for the image' },
+      },
+      required: ['image'],
+      additionalProperties: false,
+    },
+    output: visionPresentOutput,
+    async execute(args, exec) {
+      const attachments = ctx.get('attachments')
+      if (attachments === undefined) {
+        throw new Error('vision_present: the durable attachment service is not available in this deployment')
+      }
+      const { bytes, mediaType } = await readImageBytes(ctx, exec, args.image)
+      const label =
+        typeof args.label === 'string' && args.label.trim() !== '' ? args.label.trim().slice(0, 200) : 'image'
+      const extension =
+        mediaType === 'image/jpeg' ? 'jpg' :
+        mediaType === 'image/webp' ? 'webp' :
+        mediaType === 'image/gif' ? 'gif' : 'png'
+      const target = await saveArtifact(exec, `${artifactStem(args.image, 'present')}.${extension}`, bytes)
+      let attachment
+      try {
+        attachment = await attachments.saveImage({
+          data: bytes,
+          mediaType,
+          name: label,
+        })
+      } catch (error) {
+        throw new Error(
+          `vision_present: failed to publish the image attachment (${error && error.message ? error.message : String(error)})`,
+        )
+      }
+      return {
+        path: target,
+        label,
+        width: attachment.width,
+        height: attachment.height,
+        bytes: attachment.bytes,
+        safePresentation: true,
+        attachment,
+      }
+    },
+  })
+
+  // ── vision_pixel_diff ────────────────────────────────────────────────────
+  tools.push({
+    name: 'vision_pixel_diff',
+    description:
+      'Compare two images pixel by pixel (sharp-based, no Python): returns the differing-pixel ' +
+      'ratio, the worst 8x8-grid regions as original-pixel boxes, and writes a red heatmap PNG ' +
+      'plus a JSON report as artifacts. Use it to verify an implementation against a reference.',
+    parameters: {
+      type: 'object',
+      properties: {
+        original: { type: 'string', description: 'Reference image path or attachment id (e.g. "sha256:...")' },
+        rebuilt: { type: 'string', description: 'Candidate image path or attachment id (e.g. "sha256:..."); resized to the original size before comparing' },
+        threshold: { type: 'number', description: 'Per-channel difference threshold, default 16' },
+      },
+      required: ['original', 'rebuilt'],
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const { bytes: originalBytes } = await readImageBytes(ctx, exec, args.original)
+      const { bytes: rebuiltBytes } = await readImageBytes(ctx, exec, args.rebuilt)
+      const sharp = await loadSharp()
+      if (!sharp) throw new Error('vision_pixel_diff: the sharp image library is unavailable')
+      const meta = await sharp(originalBytes, { failOn: 'none' }).metadata()
+      const width = meta.width ?? 0
+      const height = meta.height ?? 0
+      if (width <= 0 || height <= 0) throw new Error('vision_pixel_diff: could not read original dimensions')
+      const threshold = Number.isFinite(args.threshold) && args.threshold >= 0 ? Math.round(args.threshold) : 16
+      const pixels = width * height
+      let diff
+      let heatmapPng
+      let heatmapPreview = false
+      let heatmapWidth = width
+      let heatmapHeight = height
+      if (pixels <= 4_000_000) {
+        const originalRaw = await sharp(originalBytes, { failOn: 'none' })
+          .ensureAlpha()
+          .raw()
+          .toBuffer({ resolveWithObject: true })
+        const rebuiltRaw = await sharp(rebuiltBytes, { failOn: 'none' })
+          .resize(width, height, { fit: 'fill' })
+          .ensureAlpha()
+          .raw()
+          .toBuffer({ resolveWithObject: true })
+        diff = computePixelDiff(originalRaw.data, rebuiltRaw.data, threshold, width, height)
+        const heatmap = renderDiffHeatmap(originalRaw.data, diff.mask, width, height)
+        heatmapPng = await sharp(heatmap, { raw: { width, height, channels: 4 } })
+          .png()
+          .toBuffer()
+      } else {
+        // Exact large-image metrics from streaming RGBA; heatmap bounded to 4MP.
+        const originalStream = sharp(originalBytes, { failOn: 'none' }).ensureAlpha().raw()
+        const rebuiltStream = sharp(rebuiltBytes, { failOn: 'none' })
+          .resize(width, height, { fit: 'fill' })
+          .ensureAlpha()
+          .raw()
+        diff = await compareRgbaStreams(originalStream, rebuiltStream, { width, height, threshold })
+        const preview = scaledDimensions(width, height, 4_000_000)
+        heatmapWidth = preview.width
+        heatmapHeight = preview.height
+        heatmapPreview = true
+        const originalPreview = await sharp(originalBytes, { failOn: 'none' })
+          .resize(preview.width, preview.height, { fit: 'fill' })
+          .ensureAlpha()
+          .raw()
+          .toBuffer({ resolveWithObject: true })
+        const rebuiltPreview = await sharp(rebuiltBytes, { failOn: 'none' })
+          .resize(preview.width, preview.height, { fit: 'fill' })
+          .ensureAlpha()
+          .raw()
+          .toBuffer({ resolveWithObject: true })
+        const previewDiff = computePixelDiff(
+          originalPreview.data,
+          rebuiltPreview.data,
+          threshold,
+          preview.width,
+          preview.height,
+        )
+        const heatmap = renderDiffHeatmap(originalPreview.data, previewDiff.mask, preview.width, preview.height)
+        heatmapPng = await sharp(heatmap, {
+          raw: { width: preview.width, height: preview.height, channels: 4 },
+        }).png().toBuffer()
+      }
+      const worst = diff.cells.slice(0, 5).map((cell) => ({
+        x1: cell.x1,
+        y1: cell.y1,
+        x2: cell.x2,
+        y2: cell.y2,
+        ratio: Number(cell.ratio.toFixed(4)),
+        differing: cell.differing,
+      }))
+      const heatmapPath = await saveArtifact(exec, `${artifactStem(args.original, 'diff-heatmap')}.png`, heatmapPng)
+      const report = {
+        width,
+        height,
+        differingPixels: diff.differing,
+        totalPixels: diff.total,
+        differingRatio: Number(diff.ratio.toFixed(6)),
+        threshold,
+        worstRegions: worst,
+        heatmapPath,
+        heatmapWidth,
+        heatmapHeight,
+        heatmapPreview,
+      }
+      const reportPath = await saveArtifact(exec, `${artifactStem(args.original, 'diff-report')}.json`, Buffer.from(JSON.stringify(report, null, 2)))
+      return JSON.stringify({ ...report, reportPath })
+    },
+  })
+
+  // ── vision_colors ────────────────────────────────────────────────────────
+  tools.push({
+    name: 'vision_colors',
+    description:
+      'Extract the dominant colors of an image (sharp-based quantization) with their share of ' +
+      'pixels, e.g. to match a palette when rebuilding a UI.',
+    parameters: {
+      type: 'object',
+      properties: {
+        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
+        top: { type: 'number', description: 'How many colors to return, default 8' },
+      },
+      required: ['image'],
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const { bytes } = await readImageBytes(ctx, exec, args.image)
+      const top = Number.isInteger(args.top) && args.top > 0 ? args.top : 8
+      const sharp = await loadSharp()
+      if (!sharp) throw new Error('vision_colors: the sharp image library is unavailable')
+      const raw = await sharp(bytes, { failOn: 'none' })
+        .resize(64, 64, { fit: 'inside' })
+        .ensureAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true })
+      const colors = quantizeColors(raw.data, Math.min(top, 32))
+      return JSON.stringify(colors)
+    },
+  })
+
+  // ── vision_ocr ───────────────────────────────────────────────────────────
+  tools.push({
+    name: 'vision_ocr',
+    description:
+      'Transcribe TEXT from an image with the vision model. ' +
+      'Returns the text and which engine produced it. ' +
+      'SCOPE: vision_ocr reads letters, it does NOT recognize people, objects or scenes. Never use it ' +
+      'as a fallback when vision_describe fails to identify who/what is in a picture ("这是谁" / ' +
+      '"这是什么东西" questions are answered by vision_describe, not OCR). If vision_describe returns ' +
+      'ok:false with a backend-unavailable code, calling vision_ocr instead will fail the same way — ' +
+      'do not chain these tools as retries of each other. ' +
+      'ACCURACY: OCR transcribes characters verbatim and is systematically unreliable for confusable ' +
+      'glyphs (1/l, 0/O), spacing and line breaks; prefer vision_describe / vision_detect for semantic ' +
+      'understanding and use OCR only when exact verbatim text is required (executable code, exact ' +
+      'quotation, forms/contracts, table digits, CAPTCHAs). Treat OCR output as evidence to verify, ' +
+      'never as ground truth.',
+    parameters: {
+      type: 'object',
+      properties: {
+        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
+        engine: {
+          type: 'string',
+          description: '"auto" (default) or "vision": transcribe with the configured vision model. "tesseract" is not available in this build.',
+        },
+      },
+      required: ['image'],
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const { bytes, mediaType } = await readImageBytes(ctx, exec, args.image)
+      const engine = args.engine === 'vision' ? 'vision' : 'auto'
+      if (args.engine === 'tesseract') {
+        throw new Error('vision_ocr: the local tesseract engine is not available in this build; use engine "auto" or "vision"')
+      }
+      const instruction =
+        '请原样转述图中的所有文字，保持阅读顺序（从上到下、从左到右）与段落结构，不要添加解释。只输出文字本身。'
+      const vision = await answerVisionForTool(bytes, mediaType, instruction, { exec })
+      if (vision.ok === false) {
+        return JSON.stringify({ engine: 'none', ...vision, text: '' })
+      }
+      return JSON.stringify({ engine, text: vision.text })
+    },
+  })
+
+  // ── vision_long_screenshot_ocr ───────────────────────────────────────────
+  tools.push({
+    name: 'vision_long_screenshot_ocr',
+    description:
+      'Transcribe a LONG screenshot (chat logs, long documents) into ordered Markdown. ' +
+      'Splits the image into overlapping horizontal chunks, OCRs each chunk with the vision ' +
+      'model, and stitches the text in reading order. Writes chunk PNGs, the Markdown, and a ' +
+      'manifest into the workspace artifacts directory.',
+    parameters: {
+      type: 'object',
+      properties: {
+        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
+        chunkHeight: { type: 'number', description: 'Chunk height in pixels, default 1200' },
+        overlap: { type: 'number', description: 'Overlap between adjacent chunks in pixels, default 120' },
+        engine: { type: 'string', description: '"auto" (default) or "vision": transcribe with the configured vision model.' },
+      },
+      required: ['image'],
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const { bytes, mediaType } = await readImageBytes(ctx, exec, args.image)
+      const sharp = await loadSharp()
+      if (!sharp) throw new Error('vision_long_screenshot_ocr: the sharp image library is unavailable')
+      const meta = await sharp(bytes, { failOn: 'none' }).metadata()
+      const width = meta.width ?? 0
+      const height = meta.height ?? 0
+      if (width <= 0 || height <= 0) {
+        throw new Error('vision_long_screenshot_ocr: could not read image dimensions')
+      }
+      const chunkHeight =
+        Number.isInteger(args.chunkHeight) && args.chunkHeight >= 400
+          ? Math.min(args.chunkHeight, 2000)
+          : 1200
+      const overlap =
+        Number.isInteger(args.overlap) && args.overlap >= 0
+          ? Math.min(args.overlap, Math.floor(chunkHeight / 2))
+          : 120
+      if (args.engine === 'tesseract') {
+        throw new Error('vision_long_screenshot_ocr: the local tesseract engine is not available in this build; use engine "auto" or "vision"')
+      }
+      const windows = boundedOcrTiles(width, height, {
+        chunkHeight,
+        overlap,
+        maxTilePixels: 4_000_000,
+      })
+      // Hard bounds: a tall screenshot must never turn into an unbounded,
+      // uncancellable model-call loop (router's 30s budget was dropped here,
+      // so re-introduce explicit limits).
+      const MAX_OCR_CHUNKS = 40
+      const OCR_TOTAL_BUDGET_MS = 120_000
+      const ocrStartedAt = Date.now()
+      const signal = exec && exec.signal
+      const stem = artifactStem(args.image, 'ocr')
+      const results = []
+      let visionFailed = false
+      for (let i = 0; i < windows.length; i++) {
+        if (signal?.aborted) break
+        if (i >= MAX_OCR_CHUNKS) {
+          results.push({
+            chunk: i + 1,
+            left: windows[i].left,
+            right: windows[i].right,
+            top: windows[i].top,
+            bottom: windows[i].bottom,
+            engine: 'skipped',
+            chars: 0,
+            text: '',
+            error: 'chunk limit reached',
+          })
+          continue
+        }
+        if (Date.now() - ocrStartedAt > OCR_TOTAL_BUDGET_MS) {
+          results.push({
+            chunk: i + 1,
+            left: windows[i].left,
+            right: windows[i].right,
+            top: windows[i].top,
+            bottom: windows[i].bottom,
+            engine: 'skipped',
+            chars: 0,
+            text: '',
+            error: 'OCR total budget exhausted',
+          })
+          continue
+        }
+        const { left, right, top, bottom } = windows[i]
+        const tileWidth = right - left
+        const tileHeight = bottom - top
+        const chunk = await sharp(bytes, { failOn: 'none' })
+          .extract({ left, top, width: tileWidth, height: tileHeight })
+          .png()
+          .toBuffer()
+        const chunkRel = `chunk-${String(i + 1).padStart(2, '0')}.png`
+        await writeArtifact(exec, join(stem, chunkRel), chunk)
+        let text = ''
+        let used = 'none'
+        // Upload JPEG without an alpha channel: some vision backends degrade
+        // on RGBA PNGs and hallucinate token-fragment text.
+        const visionBytes = await sharp(chunk, { failOn: 'none' })
+          .removeAlpha()
+          .jpeg({ quality: 92 })
+          .toBuffer()
+        const instruction =
+          '请原样转述这张长截图分片中的所有文字，保持阅读顺序（从上到下、从左到右），' +
+          '不要添加解释，只输出文字本身。如果画面中没有可见文字，只输出 EMPTY，不要编造内容。'
+        if (!visionFailed) {
+          const visionResult = await answerVisionForTool(visionBytes, 'image/jpeg', instruction, { exec })
+          if (visionResult.ok === false) {
+            // Backend failure: stop burning calls on the remaining chunks.
+            visionFailed = true
+            used = 'failed'
+          } else {
+            text = visionResult.text.trim()
+            if (text.length > 12000) {
+              const retry = await answerVisionForTool(
+                visionBytes,
+                'image/jpeg',
+                '重新转写这张图片中的真实文字，保持阅读顺序。只输出图中肉眼可见的文字，' +
+                  '禁止编造、禁止重复；总输出不超过 3000 字。没有任何文字就只输出 EMPTY。',
+                { exec },
+              )
+              if (retry.ok === false) {
+                visionFailed = true
+                used = 'failed'
+                text = ''
+              } else {
+                const retryText = retry.text.trim()
+                if (retryText !== '') text = retryText
+                used = 'vision'
+              }
+            } else {
+              used = 'vision'
+            }
+            if (text === 'EMPTY') text = ''
+          }
+        }
+        results.push({ chunk: i + 1, left, right, top, bottom, engine: used, chars: text.length, text })
+      }
+      const joined = results.map((r) => r.text).filter((t) => t !== '').join('\n\n')
+      const engines = {}
+      for (const r of results) engines[r.engine] = (engines[r.engine] ?? 0) + 1
+      const manifest = {
+        source: args.image,
+        width,
+        height,
+        chunkHeight,
+        overlap,
+        chunks: results.length,
+        engines,
+        perChunk: results.map(({ text, ...rest }) => rest),
+      }
+      const manifestPath = await writeArtifact(exec, join(stem, 'manifest.json'), JSON.stringify(manifest, null, 2))
+      const mdPath = await writeArtifact(exec, join(stem, 'ocr.md'), joined)
+      return JSON.stringify({
+        text: joined,
+        chunks: results.length,
+        engines,
+        markdownPath: mdPath,
+        manifestPath,
+        artifactsDir: dirname(mdPath),
+      })
+    },
+  })
+
+  // ── vision_trace ─────────────────────────────────────────────────────────
+  tools.push({
+    name: 'vision_trace',
+    description:
+      'Vectorize an image (icon/logo) into an SVG via a local potrace pipeline (no Python). ' +
+      'Default: COLOR-preserving vectorization — one path per dominant color with fill="#rrggbb". ' +
+      'Set color=false for the layered grayscale posterization, where `steps` (1-16, default 4) ' +
+      'controls levels. Writes the SVG as an artifact.',
+    parameters: {
+      type: 'object',
+      properties: {
+        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
+        steps: { type: 'number', description: 'Posterization steps, 1-16, default 4 (only when color=false)' },
+        color: { type: 'boolean', description: 'Preserve original colors (default true)' },
+        colors: { type: 'number', description: 'Number of dominant colors in color mode, 1-16, default 8' },
+      },
+      required: ['image'],
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const { bytes } = await readImageBytes(ctx, exec, args.image)
+      const steps = Number.isInteger(args.steps) && args.steps > 0 ? Math.min(args.steps, 16) : 4
+      const colorMode = args.color !== false
+      // Trace-specific pixel budget: vectorization gains nothing beyond ~1MP.
+      let traceBytes = bytes
+      if (bytes && bytes.length > 0) {
+        traceBytes = await downscaleImage(bytes, 1_000_000)
+      }
+      let svg
+      let colorCount = 0
+      try {
+        if (colorMode) {
+          const sharp = await loadSharp()
+          if (!sharp) throw new Error('vision_trace: the sharp image library is unavailable')
+          const colors = Number.isInteger(args.colors) && args.colors > 0 ? Math.min(args.colors, 16) : 8
+          const raw = await sharp(traceBytes, { failOn: 'none' }).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+          const palette = quantizeColors(raw.data, colors)
+          colorCount = palette.length
+          svg = await posterizeSvgColor(raw.data, raw.info, palette, getConfig().timeoutMs || 60000)
+        } else {
+          svg = await posterizeSvg(traceBytes, steps, 'dominant', getConfig().timeoutMs || 60000)
+        }
+      } catch (error) {
+        throw new Error(
+          `vision_trace: potrace failed (${error && error.message ? error.message : String(error)}). ` +
+            'If potrace is missing, install the plugin dependencies in the profile (pnpm add potrace).',
+        )
+      }
+      const target = await saveArtifact(
+        exec,
+        `${artifactStem(args.image, colorMode ? 'trace-color' : `trace-${steps}`)}.svg`,
+        Buffer.from(svg),
+      )
+      return JSON.stringify({ path: target, bytes: Buffer.byteLength(svg), ...(colorMode ? { colors: colorCount } : {}) })
+    },
+  })
+
+  // ── vision_extract_foreground ────────────────────────────────────────────
+  tools.push({
+    name: 'vision_extract_foreground',
+    description:
+      'Remove a solid-ish background (border flood fill with color tolerance, no Python) and ' +
+      'write the cutout as a transparent PNG artifact. Best for logos on uniform backgrounds.',
+    parameters: {
+      type: 'object',
+      properties: {
+        image: { type: 'string', description: 'Local image path (png/jpeg/webp/gif), workspace-relative or absolute; or the attachment id (e.g. "sha256:...") of an image uploaded in this conversation' },
+        tolerance: { type: 'number', description: 'Max per-channel color distance from the background, default 40' },
+      },
+      required: ['image'],
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const { bytes } = await readImageBytes(ctx, exec, args.image)
+      let fgBytes = bytes
+      if (bytes && bytes.length > 0) {
+        fgBytes = await downscaleImage(bytes, 4_000_000)
+      }
+      const tolerance = Number.isFinite(args.tolerance) && args.tolerance >= 0 ? Math.round(args.tolerance) : 40
+      const sharp = await loadSharp()
+      if (!sharp) throw new Error('vision_extract_foreground: the sharp image library is unavailable')
+      const { data, info } = await sharp(fgBytes, { failOn: 'none' })
+        .ensureAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true })
+      const cutout = floodFillBackground(data, info.width, info.height, tolerance)
+      const png = await sharp(cutout, {
+        raw: { width: info.width, height: info.height, channels: 4 },
+      })
+        .png()
+        .toBuffer()
+      const target = await saveArtifact(exec, `${artifactStem(args.image, 'fg')}.png`, png)
+      return JSON.stringify({ path: target, width: info.width, height: info.height, bytes: png.length })
+    },
+  })
+
+  // ── vision_html_screenshot ───────────────────────────────────────────────
+  tools.push({
+    name: 'vision_html_screenshot',
+    description:
+      'Render a local .html/.htm file in the system Chrome (headless, network disabled by ' +
+      'default) and save a PNG screenshot as an artifact — the verify step of the ' +
+      'reference -> implementation -> screenshot -> pixel-diff loop. With fullPage: true the ' +
+      'page keeps the requested viewport but the whole scrollable height is captured and the ' +
+      'result JSON reports pageHeight (CSS px).',
+    parameters: {
+      type: 'object',
+      properties: {
+        source: { type: 'string', description: 'Local .html or .htm file path' },
+        width: { type: 'number', description: 'Viewport width, default 1200' },
+        height: { type: 'number', description: 'Viewport height, default 720' },
+        fullPage: {
+          type: 'boolean',
+          description:
+            'Capture the complete scrollable page height at the requested viewport width ' +
+            'instead of just the viewport (default false). Lazy-loaded images and ' +
+            'scroll-triggered reveals are woken first; the result JSON then includes ' +
+            'pageHeight (CSS px).',
+        },
+      },
+      required: ['source'],
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const source = String(args.source ?? '')
+      if (!/\.(html?|htm)$/i.test(source)) {
+        throw new Error('vision_html_screenshot: source must be a local .html/.htm file')
+      }
+      const fsService = ctx.get('fs')
+      if (fsService === undefined) {
+        throw new Error('vision_html_screenshot: the fs service is not available')
+      }
+      const resolved = await fsService.resolve(source)
+      const targetPath = toRealPath(fsService, resolved)
+      if (!existsSync(targetPath)) {
+        throw new Error(`vision_html_screenshot: file not found: ${source}`)
+      }
+      let puppeteer
+      try {
+        puppeteer = await import('puppeteer-core')
+      } catch {
+        throw new Error(
+          'vision_html_screenshot: puppeteer-core is not installed. Install the plugin dependencies in the profile (pnpm add puppeteer-core).',
+        )
+      }
+      const candidates = chromiumCandidates(
+        typeof process !== 'undefined' && process.env ? process.env : {},
+        typeof process !== 'undefined' ? process.platform : '',
+      )
+      const executablePath = candidates.find((p) => existsSync(p))
+      if (executablePath === undefined) {
+        throw new Error(
+          'vision_html_screenshot: no Chrome/Chromium/Edge found; install one or set CHROME_PATH / PUPPETEER_EXECUTABLE_PATH',
+        )
+      }
+      const width = Number.isInteger(args.width) && args.width > 0 ? args.width : 1200
+      const height = Number.isInteger(args.height) && args.height > 0 ? args.height : 720
+      const fullPage = args.fullPage === true
+      const launchArgs = ['--no-sandbox', '--disable-gpu', '--hide-scrollbars', '--incognito']
+      if (fullPage) {
+        launchArgs.push('--blink-settings=imagesLazyLoadingEnabled=false')
+      }
+      const browser = await puppeteer.default.launch({
+        executablePath,
+        headless: true,
+        args: launchArgs,
+      })
+      try {
+        const page = await browser.newPage()
+        await page.setViewport({ width, height })
+        // Honor the "network disabled by default" contract: the page may only
+        // load file:/data:/blob: subresources; everything else is aborted so
+        // a malicious local HTML cannot exfiltrate data or pull remote assets.
+        await page.setRequestInterception(true)
+        page.on('request', (request) => {
+          const url = request.url() ?? ''
+          if (/^(file|data|blob):/i.test(url)) request.continue()
+          else request.abort()
+        })
+        await page.goto(pathToFileURL(targetPath).href, { waitUntil: 'networkidle0', timeout: 30000 })
+        let pageHeight
+        if (fullPage) {
+          await wakePageForFullCapture(page, height)
+          pageHeight = await fullPageHeightOf(page)
+        }
+        const png = fullPage
+          ? await page.screenshot({ type: 'png', fullPage: true })
+          : await page.screenshot({ type: 'png' })
+        const stem = fullPage ? `shot-${width}x${height}-fullpage` : `shot-${width}x${height}`
+        const target = await saveArtifact(exec, `${artifactStem(source, stem)}.png`, png)
+        const result = { path: target, width, height, bytes: png.length }
+        if (fullPage) {
+          result.pageHeight = pageHeight
+        }
+        return JSON.stringify(result)
+      } finally {
+        await browser.close()
+      }
+    },
+  })
+
+  // ── vision_screenshot (privacy-gated: only registered when desktopScreenshot is enabled) ──
+  if (getConfig().desktopScreenshot === true) {
+    tools.push({
+      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: PowerShell CopyFromScreen; macOS: screencapture; Linux: ImageMagick import (falls back to scrot; either command must be installed). ' +
+      '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 recognition on the capture with the configured vision model and returns the description alongside the path.',
+    parameters: {
+      type: 'object',
+      properties: {
+        identify: {
+          type: 'boolean',
+          description:
+            'Also recognize the captured screen with the configured vision model and return the description text with the path. Default false.',
+        },
+      },
+      additionalProperties: false,
+    },
+    output: stringOutput,
+    async execute(args, exec) {
+      const tmp = join(
+        (typeof process !== 'undefined' && process.env && process.env.TMPDIR) || process.env.TEMP || '/tmp',
+        `vision-screenshot-${Date.now()}-${Math.floor(Math.random() * 1e9)}.png`,
+      )
+      const platform = process.platform
+      try {
+        if (platform === 'win32') {
+          const script = [
+            'Add-Type -AssemblyName System.Windows.Forms,System.Drawing',
+            '$b=[System.Windows.Forms.SystemInformation]::VirtualScreen',
+            '$bmp=New-Object System.Drawing.Bitmap($b.Width,$b.Height)',
+            '$g=[System.Drawing.Graphics]::FromImage($bmp)',
+            '$g.CopyFromScreen($b.X,$b.Y,0,0,$bmp.Size)',
+            `$bmp.Save('${tmp.replace(/'/g, "''")}')`,
+            '$g.Dispose();$bmp.Dispose()',
+          ].join('; ')
+          await promisify(execFile)('powershell.exe', ['-NoProfile', '-STA', '-Command', script], {
+            timeout: 60000,
+            windowsHide: true,
+          })
+        } else if (platform === 'darwin') {
+          await promisify(execFile)('screencapture', ['-x', '-m', tmp], {
+            timeout: 60000,
+            windowsHide: true,
+          })
+        } else {
+          try {
+            await promisify(execFile)('import', ['-window', 'root', tmp], { timeout: 60000 })
+          } catch {
+            await promisify(execFile)('scrot', [tmp], { timeout: 60000 })
+          }
+        }
+        if (!existsSync(tmp)) {
+          throw new Error(
+            `vision_screenshot: no output produced on ${platform} (is a screen available?)`,
+          )
+        }
+        const data = await readFileP(tmp)
+        const target = await saveArtifact(exec, `screenshot-${Date.now()}.png`, data)
+        const result = { path: target, bytes: data.length }
+        if (args.identify === true) {
+          let identifyBytes = data
+          try {
+            const sharp = await loadSharp()
+            if (sharp) {
+              const downscaled = await sharp(data, { failOn: 'none' })
+                .resize({ width: 1280, height: 1280, fit: 'inside', withoutEnlargement: true })
+                .png()
+                .toBuffer()
+              if (downscaled.length > 0 && downscaled.length < data.length) {
+                identifyBytes = downscaled
+              }
+            }
+          } catch {
+            /* keep the original capture */
+          }
+          const vision = await answerVisionForTool(
+            identifyBytes,
+            'image/png',
+            'Describe what is currently visible on the user\'s screen, in detail and in reading order. Mention the app/window names you can see.',
+            { exec },
+          )
+          if (vision.ok === false) {
+            result.identify = { ok: false, ...vision, text: '' }
+          } else {
+            result.identify = { ok: true, text: vision.text }
+          }
+        }
+        try {
+          await rmP(tmp, { force: true })
+        } catch {
+          /* best-effort cleanup */
+        }
+        return JSON.stringify(result)
+      } catch (error) {
+        throw new Error(
+          `vision_screenshot: failed (${error && error.message ? error.message : String(error)})`,
+        )
+      }
+    },
+    })
+  }
+
+  for (const def of tools) {
+    ctx.tools.register(def)
+  }
+  logger?.info?.('[tool-vision] registered %d pixel-level vision tools', tools.length)
+  return tools.length
+}
+
+// ── cache instance shared across tools ─────────────────────────────────────
+
+const visionCache = createCache(200, 3600 * 1000)
+let cacheDisabled = false
+
+function cacheEnabled() {
+  return !cacheDisabled
+}
+
+/** Test hook: reset the shared cache. */
+export function resetVisionCacheForTests() {
+  visionCache.clear()
+  cacheDisabled = false
+}