dsh-vision-router 2.1.1 → 2.1.2

package/lib/twin-image-capability-fallback.js

@@ -0,0 +1,428 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+const TWIN_SUFFIX = '-vision'
+const DEFAULT_MAIN_WRAPPER_ROUTE = 'deepseek-vision'
+const DEFAULT_CHAIN_ROUTE = 'vision-chain'
+const forcedTextBridgeScope = new AsyncLocalStorage()
+
+export const TWIN_IMAGE_CAPABILITY_NEGATIVE_TTL_MS = 60_000
+export const MAX_TWIN_IMAGE_CAPABILITY_NEGATIVE_MODELS = 64
+
+function isObject(value) {
+  return value !== null && (typeof value === 'object' || typeof value === 'function')
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0
+}
+
+function blocksHaveImage(content) {
+  if (!Array.isArray(content)) return false
+  for (const block of content) {
+    if (!block) continue
+    if (block.type === 'image') return true
+    if (Array.isArray(block.content) && blocksHaveImage(block.content)) return true
+  }
+  return false
+}
+
+export function twinRequestHasImage(messages) {
+  return (messages ?? []).some(
+    (message) => message && Array.isArray(message.content) && blocksHaveImage(message.content),
+  )
+}
+
+function failureText(failure, seen = new Set()) {
+  if (failure === undefined || failure === null) return ''
+  if (typeof failure === 'string') return failure
+  if (!isObject(failure) || seen.has(failure)) return ''
+  seen.add(failure)
+  const pieces = []
+  for (const key of ['message', 'detail', 'reason', 'error']) {
+    const value = failure[key]
+    if (typeof value === 'string') pieces.push(value)
+    else if (isObject(value)) {
+      const nested = failureText(value, seen)
+      if (nested !== '') pieces.push(nested)
+    }
+  }
+  if (isObject(failure.cause)) {
+    const nested = failureText(failure.cause, seen)
+    if (nested !== '') pieces.push(nested)
+  }
+  return pieces.join(' | ')
+}
+
+function failureCodes(failure, seen = new Set(), out = new Set()) {
+  if (!isObject(failure) || seen.has(failure)) return out
+  seen.add(failure)
+  if (typeof failure.code === 'string' && failure.code.trim() !== '') {
+    out.add(failure.code.trim().toUpperCase())
+  }
+  for (const key of ['error', 'cause', 'detail', 'reason']) {
+    failureCodes(failure[key], seen, out)
+  }
+  return out
+}
+
+/**
+ * True only for an explicit runtime rejection of image input. Generic 400s,
+ * max-token errors, auth failures, rate limits and transport errors must never
+ * trigger a second model call. Capability prose is deliberately end-bounded:
+ * "does not support image inputs larger than ..." describes a size/format
+ * restriction, not proof that the model is text-only.
+ */
+export function isImageInputUnsupportedFailure(failure) {
+  const text = failureText(failure)
+  const terminal = String.raw`(?:\s*(?:[.!?。！？]|$)|\s*\|)`
+  const explicitImageRejection = [
+    new RegExp(`does not support (?:images?|image inputs?|image content)${terminal}`, 'i'),
+    new RegExp(
+      `(?:images?|image inputs?|image content) (?:is|are) not supported(?:\\s+(?:by|for) (?:this|the) (?:model|endpoint))?${terminal}`,
+      'i',
+    ),
+    new RegExp(
+      `unsupported (?:images?|image inputs?|image content)(?:\\s+(?:by|for) (?:this|the) (?:model|endpoint))?${terminal}`,
+      'i',
+    ),
+    new RegExp(`cannot (?:accept|process|handle) (?:images?|image inputs?)${terminal}`, 'i'),
+    new RegExp(`(?:model|adapter).*text[- ]only.*(?:images?|image inputs?)${terminal}`, 'i'),
+    new RegExp(`(?:模型|适配器).*不支持(?:图片|图像)(?:输入)?${terminal}`),
+    new RegExp(`(?:图片|图像)输入(?:不被支持|暂不支持|不支持)${terminal}`),
+  ].some((pattern) => pattern.test(text))
+  if (explicitImageRejection) return true
+
+  const codes = failureCodes(failure)
+  return codes.has('MODEL_DOES_NOT_SUPPORT_IMAGES') || codes.has('UNSUPPORTED_IMAGE_INPUT')
+}
+
+function chunkFailure(chunk) {
+  if (!chunk || typeof chunk !== 'object') return undefined
+  if (chunk.type === 'finish' && chunk.reason && chunk.reason.kind === 'error') {
+    return chunk.reason.failure ?? chunk.reason
+  }
+  if (chunk.type === 'error') return chunk.failure ?? chunk.error ?? chunk
+  return undefined
+}
+
+function stripImageCapability(info) {
+  if (!info || typeof info !== 'object' || !Array.isArray(info.inputModalities)) return info
+  if (!info.inputModalities.includes('image')) return info
+  return {
+    ...info,
+    inputModalities: info.inputModalities.filter((item) => item !== 'image'),
+  }
+}
+
+function facadeFor(source, overrides = {}) {
+  const shell = Object.create(Reflect.getPrototypeOf(source))
+  const hasOverride = (property) => Object.prototype.hasOwnProperty.call(overrides, property)
+  const read = (target, property) => {
+    if (Object.prototype.hasOwnProperty.call(target, property)) {
+      return Reflect.get(target, property, target)
+    }
+    if (hasOverride(property)) return overrides[property]
+    const value = Reflect.get(source, property, source)
+    return typeof value === 'function' ? value.bind(source) : value
+  }
+  return new Proxy(shell, {
+    get(target, property) {
+      return read(target, property)
+    },
+    has(target, property) {
+      return Reflect.has(target, property) || hasOverride(property) || Reflect.has(source, property)
+    },
+    ownKeys(target) {
+      return [...new Set([...Reflect.ownKeys(target), ...Reflect.ownKeys(source), ...Reflect.ownKeys(overrides)])]
+    },
+    getOwnPropertyDescriptor(target, property) {
+      const own = Reflect.getOwnPropertyDescriptor(target, property)
+      if (own !== undefined) return own
+      if (!hasOverride(property) && !Reflect.has(source, property)) return undefined
+      const sourceDescriptor = Reflect.getOwnPropertyDescriptor(source, property)
+      return {
+        configurable: true,
+        enumerable: sourceDescriptor?.enumerable ?? true,
+        writable: false,
+        value: read(target, property),
+      }
+    },
+  })
+}
+
+function proxiedRegistrationWithoutImage(registration, provider, model) {
+  if (!registration || !isObject(registration)) return registration
+  const adapter = registration.adapter
+  if (!adapter || !isObject(adapter) || typeof adapter.resolveModel !== 'function') return registration
+  const adapterView = facadeFor(adapter, {
+    async resolveModel(requestedProvider, requestedModel, ...rest) {
+      const info = await adapter.resolveModel(requestedProvider, requestedModel, ...rest)
+      if (requestedProvider !== provider || requestedModel !== model) return info
+      return stripImageCapability(info)
+    },
+  })
+  return facadeFor(registration, { adapter: adapterView })
+}
+
+async function closeIterator(iterator) {
+  if (iterator && typeof iterator.return === 'function') {
+    try {
+      await iterator.return()
+    } catch {
+      // The failed attempt is already being abandoned. Cleanup errors must not
+      // replace the capability rejection or block the safe bridge retry.
+    }
+  }
+}
+
+/**
+ * Private Core-only boundary for generated `<provider>-vision` twins.
+ *
+ * Catalog metadata remains the optimistic fast path: a genuinely multimodal
+ * source still receives raw image blocks exactly as before. If that source
+ * explicitly rejects image input before producing any model-visible output,
+ * runtime evidence overrides the stale metadata for this request and the same
+ * twin is re-entered once under a scoped metadata view with `image` removed.
+ * The existing Core wrapper then performs its canonical image -> tool-marker /
+ * cached-description projection; this layer never duplicates that logic.
+ */
+export function contextWithTwinImageCapabilityFallback(ctx, options = {}) {
+  if (!ctx || typeof ctx !== 'object' || !ctx.llm) return ctx
+  const llm = ctx.llm
+  const configuredMainWrapperRoute = nonEmptyString(options.wrapperRoute)
+    ? options.wrapperRoute
+    : DEFAULT_MAIN_WRAPPER_ROUTE
+  const configuredChainRoute = nonEmptyString(options.chainRoute)
+    ? options.chainRoute
+    : DEFAULT_CHAIN_ROUTE
+  const currentOwnedRoutes = () => {
+    try {
+      const settings = ctx?.get?.('settings')
+      const current = settings?.get?.('vision-router')
+      if (current && typeof current === 'object' && !Array.isArray(current)) {
+        return new Set([
+          nonEmptyString(current.wrapperRoute) ? current.wrapperRoute : configuredMainWrapperRoute,
+          nonEmptyString(current.chainRoute) ? current.chainRoute : configuredChainRoute,
+        ])
+      }
+    } catch {
+      // Settings can be between generations; composition-time routes remain
+      // authoritative until the live namespace becomes readable again.
+    }
+    return new Set([configuredMainWrapperRoute, configuredChainRoute])
+  }
+  const logger = options.logger ?? ctx.logger
+  const ttlMs = Number.isFinite(Number(options.negativeTtlMs)) && Number(options.negativeTtlMs) > 0
+    ? Number(options.negativeTtlMs)
+    : TWIN_IMAGE_CAPABILITY_NEGATIVE_TTL_MS
+
+  // Runtime rejection is scoped to the exact source adapter + provider/model.
+  // One adapter instance may legitimately serve multiple provider routes, so
+  // adapter + model alone is not sufficient isolation. A provider reload or
+  // adapter replacement clears stale evidence by identity; the short TTL also
+  // self-heals an adapter whose capability changes in place.
+  const scopeToken = Object.freeze({})
+  const rejectedByAdapter = new WeakMap() // source adapter -> Map(provider\0model -> expiresAt)
+  const memoFor = (adapter) => {
+    if (!isObject(adapter)) return undefined
+    let memo = rejectedByAdapter.get(adapter)
+    if (memo === undefined) {
+      memo = new Map()
+      rejectedByAdapter.set(adapter, memo)
+    }
+    return memo
+  }
+  const rejectionKey = (provider, model) => `${provider}\u0000${model}`
+  const rejectionCached = (adapter, provider, model) => {
+    if (!isObject(adapter) || !nonEmptyString(provider) || !nonEmptyString(model)) return false
+    const memo = rejectedByAdapter.get(adapter)
+    if (memo === undefined) return false
+    const now = Date.now()
+    for (const [key, expiresAt] of memo) {
+      if (expiresAt <= now) memo.delete(key)
+    }
+    const key = rejectionKey(provider, model)
+    const expiresAt = memo.get(key)
+    if (expiresAt === undefined) return false
+    if (expiresAt <= now) {
+      memo.delete(key)
+      return false
+    }
+    // Refresh recency without extending the proof lifetime.
+    memo.delete(key)
+    memo.set(key, expiresAt)
+    return true
+  }
+  const rememberRejection = (adapter, provider, model) => {
+    if (!isObject(adapter) || !nonEmptyString(provider) || !nonEmptyString(model)) return
+    const memo = memoFor(adapter)
+    if (memo === undefined) return
+    const key = rejectionKey(provider, model)
+    if (!memo.has(key) && memo.size >= MAX_TWIN_IMAGE_CAPABILITY_NEGATIVE_MODELS) {
+      memo.delete(memo.keys().next().value)
+    }
+    memo.delete(key)
+    memo.set(key, Date.now() + ttlMs)
+  }
+
+  const sourceRegistration = (sourceProvider) => {
+    try {
+      return llm.registration(sourceProvider)
+    } catch {
+      return undefined
+    }
+  }
+
+  const wrapTwinAdapter = (adapter, sourceProvider) => {
+    if (!adapter || !isObject(adapter) || typeof adapter.stream !== 'function') return adapter
+    const stream = adapter.stream
+    return facadeFor(adapter, {
+      async *stream(options = {}) {
+        const messages = options.messages ?? []
+        if (!twinRequestHasImage(messages)) {
+          yield* stream.call(adapter, options)
+          return
+        }
+
+        const model = nonEmptyString(options.model) ? options.model : ''
+        const sourceAdapter = sourceRegistration(sourceProvider)?.adapter
+        const forceBridge = async function* () {
+          const store = { token: scopeToken, provider: sourceProvider, model }
+          const scopedIterator = stream.call(adapter, options)[Symbol.asyncIterator]()
+          let scopedFinished = false
+          try {
+            while (true) {
+              const step = await forcedTextBridgeScope.run(store, () => scopedIterator.next())
+              if (step.done) {
+                scopedFinished = true
+                return step.value
+              }
+              yield step.value
+            }
+          } finally {
+            if (!scopedFinished && typeof scopedIterator.return === 'function') {
+              await forcedTextBridgeScope.run(store, () => scopedIterator.return())
+            }
+          }
+        }
+
+        // Once this exact provider/model on this concrete source adapter has
+        // disproved its metadata, skip the known-bad raw-image attempt for the
+        // short proof lifetime without poisoning sibling routes on that adapter.
+        if (rejectionCached(sourceAdapter, sourceProvider, model)) {
+          yield* forceBridge()
+          return
+        }
+
+        const iterator = stream.call(adapter, options)[Symbol.asyncIterator]()
+        const bufferedUsage = []
+        let committed = false
+        let finished = false
+        try {
+          while (true) {
+            let step
+            try {
+              step = await iterator.next()
+            } catch (error) {
+              if (
+                !committed &&
+                !(options.signal && options.signal.aborted) &&
+                isImageInputUnsupportedFailure(error)
+              ) {
+                await closeIterator(iterator)
+                finished = true
+                rememberRejection(sourceAdapter, sourceProvider, model)
+                logger?.warn?.(
+                  'vision-router: source %s/%s rejected raw image input despite image-capable metadata; retrying once through the canonical text bridge',
+                  sourceProvider,
+                  model,
+                )
+                yield* forceBridge()
+                return
+              }
+              throw error
+            }
+
+            if (step.done) {
+              finished = true
+              for (const usage of bufferedUsage) yield usage
+              return step.value
+            }
+
+            const chunk = step.value
+            const failure = chunkFailure(chunk)
+            if (
+              !committed &&
+              failure !== undefined &&
+              !(options.signal && options.signal.aborted) &&
+              isImageInputUnsupportedFailure(failure)
+            ) {
+              await closeIterator(iterator)
+              finished = true
+              rememberRejection(sourceAdapter, sourceProvider, model)
+              logger?.warn?.(
+                'vision-router: source %s/%s rejected raw image input despite image-capable metadata; retrying once through the canonical text bridge',
+                sourceProvider,
+                model,
+              )
+              yield* forceBridge()
+              return
+            }
+
+            // Usage before any model-visible block is provisional. Do not
+            // publish accounting from a failed pre-validation attempt; flush
+            // it unchanged if that attempt actually commits.
+            if (!committed && chunk && chunk.type === 'usage') {
+              bufferedUsage.push(chunk)
+              continue
+            }
+
+            if (!committed) {
+              committed = true
+              for (const usage of bufferedUsage) yield usage
+              bufferedUsage.length = 0
+            }
+            yield chunk
+          }
+        } finally {
+          if (!finished) await closeIterator(iterator)
+        }
+      },
+    })
+  }
+
+  const llmProxy = facadeFor(llm, {
+    registration(provider, ...rest) {
+      const hit = llm.registration(provider, ...rest)
+      const scope = forcedTextBridgeScope.getStore()
+      if (!scope || scope.token !== scopeToken || provider !== scope.provider) return hit
+      return proxiedRegistrationWithoutImage(hit, scope.provider, scope.model)
+    },
+    registerAdapter(providers, adapter, ...rest) {
+      const route = Array.isArray(providers) && providers.length === 1 ? providers[0] : undefined
+      const looksLikeGeneratedTwin =
+        nonEmptyString(route) &&
+        !currentOwnedRoutes().has(route) &&
+        route.endsWith(TWIN_SUFFIX) &&
+        route.length > TWIN_SUFFIX.length
+      if (!looksLikeGeneratedTwin) return llm.registerAdapter(providers, adapter, ...rest)
+      const sourceProvider = route.slice(0, -TWIN_SUFFIX.length)
+      // This context is private to Core.apply, and Core creates its generated
+      // twins as single `<source>-vision` registrations. Do not require the
+      // source route to exist *yet*: explicit wrappedProviders are allowed to
+      // register before a settings-backed source adapter appears, then delegate
+      // lazily once that source is mounted. Main/custom wrapper and chain routes
+      // are excluded above, so preserving this lazy lifecycle does not broaden
+      // the boundary to other Core-owned registrations.
+      return llm.registerAdapter(providers, wrapTwinAdapter(adapter, sourceProvider), ...rest)
+    },
+  })
+
+  return new Proxy(ctx, {
+    get(target, property) {
+      if (property === 'llm') return llmProxy
+      const value = Reflect.get(target, property, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}

package/lib/vision-attachment-handle-runtime.js

@@ -0,0 +1,212 @@
+const SHA256_HANDLE_PREFIX = /^sha256:/i
+const CANONICAL_SHA256_ID = /^sha256:[0-9a-f]{64}$/i
+const PROJECTED_SHA256_HANDLE = /^sha256:[0-9a-f]{8,63}$/i
+
+const TOOL_FIELDS = Object.freeze({
+  vision_describe: { arrays: ['attachmentIds', 'paths'] },
+  vision_bootstrap: { arrays: ['attachmentIds', 'paths'] },
+  vision_materialize: { scalars: ['image'] },
+  vision_ground: { scalars: ['image'] },
+  vision_detect: { scalars: ['image'] },
+  vision_crop: { scalars: ['image'] },
+  vision_present: { scalars: ['image'] },
+  vision_pixel_diff: { scalars: ['original', 'rebuilt'] },
+  vision_colors: { scalars: ['image'] },
+  vision_ocr: { scalars: ['image'] },
+  vision_trace: { scalars: ['image'] },
+  vision_extract_foreground: { scalars: ['image'] },
+})
+
+function isObject(value) {
+  return value !== null && typeof value === 'object'
+}
+
+function attachmentIdOf(ref) {
+  if (!ref || typeof ref !== 'object') return undefined
+  const value = ref.attachmentId ?? ref.id
+  if (value === undefined || value === null) return undefined
+  const id = String(value).trim()
+  return id === '' ? undefined : id
+}
+
+function sessionEvents(session) {
+  try {
+    if (session && typeof session.snapshotEvents === 'function') {
+      const events = session.snapshotEvents()
+      return Array.isArray(events) ? events : []
+    }
+    return Array.isArray(session?.events) ? session.events : []
+  } catch {
+    return []
+  }
+}
+
+function collectImageRefsFromBlocks(blocks, out) {
+  if (!Array.isArray(blocks)) return
+  for (const block of blocks) {
+    if (!block || typeof block !== 'object') continue
+    if (block.type === 'image' && block.attachment) out.push(block.attachment)
+    if (Array.isArray(block.content)) collectImageRefsFromBlocks(block.content, out)
+  }
+}
+
+function collectImageRefsFromMessages(messages, out) {
+  if (!Array.isArray(messages)) return
+  for (const message of messages) collectImageRefsFromBlocks(message?.content, out)
+}
+
+function authorizedRefs(core, agent) {
+  const refs = []
+  const session = agent?.session
+  const events = sessionEvents(session)
+  if (typeof core?.collectEventAttachmentRefs === 'function') {
+    try {
+      const durable = core.collectEventAttachmentRefs(events)
+      if (Array.isArray(durable)) refs.push(...durable)
+    } catch {
+      // The resolver remains fail-closed; pending refs below may still suffice.
+    }
+  }
+  collectImageRefsFromMessages(agent?.inbox?.nextTurn, refs)
+  collectImageRefsFromMessages(agent?.inbox?.nextStep, refs)
+
+  const unique = new Map()
+  for (const ref of refs) {
+    const id = attachmentIdOf(ref)
+    if (id !== undefined && !unique.has(id)) unique.set(id, ref)
+  }
+  return [...unique.values()]
+}
+
+export function isProjectedAttachmentHandle(value) {
+  return typeof value === 'string' && PROJECTED_SHA256_HANDLE.test(value.trim())
+}
+
+function isSha256HandleLike(value) {
+  return typeof value === 'string' && SHA256_HANDLE_PREFIX.test(value.trim())
+}
+
+function isCanonicalSha256Id(value) {
+  return typeof value === 'string' && CANONICAL_SHA256_ID.test(value.trim())
+}
+
+/**
+ * Resolve DSH's model-facing text-only image alias back to one canonical
+ * attachment ref without changing durable attachment identity semantics.
+ *
+ * DSH currently projects `sha256:<full digest>` to a short `sha256:<prefix>`
+ * for text-only requests. The alias is not globally addressable: it is valid
+ * only when exactly one image authorized by the current Session has that
+ * prefix. Zero or multiple matches fail closed.
+ */
+export function resolveProjectedAttachmentHandle(handle, { core, sessionVisionIndex, agent } = {}) {
+  const token = typeof handle === 'string' ? handle.trim() : ''
+  if (!isProjectedAttachmentHandle(token)) return { kind: 'not-projected', value: handle }
+
+  const session = agent?.session
+  const refs = authorizedRefs(core, agent)
+  const wanted = token.toLowerCase()
+  const matches = refs.filter((ref) => {
+    const id = attachmentIdOf(ref)
+    return id !== undefined && id.toLowerCase().startsWith(wanted)
+  })
+
+  if (matches.length === 0) return { kind: 'unknown', handle: token }
+  if (matches.length > 1) return { kind: 'ambiguous', handle: token }
+
+  const candidate = matches[0]
+  const canonicalId = attachmentIdOf(candidate)
+  if (canonicalId === undefined) return { kind: 'unknown', handle: token }
+
+  // The Session event/inbox proves authorization; warm the canonical bounded
+  // index with that exact Host-owned ref, then require the index to hand it
+  // back. This keeps all downstream tools on the same recovery/identity seam.
+  try {
+    sessionVisionIndex?.recordAttachments?.(session, [candidate])
+  } catch {
+    // A durable event can still be recovered by lookupAttachment below.
+  }
+  if (!sessionVisionIndex || typeof sessionVisionIndex.lookupAttachment !== 'function') {
+    return { kind: 'unknown', handle: token }
+  }
+  const ref = sessionVisionIndex.lookupAttachment(session, canonicalId)
+  if (ref === undefined) return { kind: 'unknown', handle: token }
+  return { kind: 'resolved', handle: token, canonicalId, ref }
+}
+
+function canonicalizeValue(value, context) {
+  if (!isSha256HandleLike(value)) return value
+  if (isCanonicalSha256Id(value)) return value
+  if (!isProjectedAttachmentHandle(value)) {
+    throw new Error(
+      `${context.toolName}: invalid attachment handle "${String(value).trim()}" ` +
+        '(sha256 attachment handles must be a canonical id or a DSH-projected 8+ hex prefix)',
+    )
+  }
+  const result = resolveProjectedAttachmentHandle(value, context)
+  if (result.kind === 'resolved') return result.canonicalId
+  if (result.kind === 'ambiguous') {
+    throw new Error(
+      `${context.toolName}: ambiguous attachment handle "${result.handle}" ` +
+        '(multiple images in this conversation share that prefix; use a full attachment id or attach the image again)',
+    )
+  }
+  throw new Error(
+    `${context.toolName}: unknown attachment handle "${result.handle}" ` +
+      '(it is not authorized by an image in this conversation; attach the image again if needed)',
+  )
+}
+
+function canonicalizeArgs(args, context, fields) {
+  if (!isObject(args) || Array.isArray(args)) return args
+  let next
+  for (const field of fields.scalars ?? []) {
+    if (!Object.hasOwn(args, field)) continue
+    const value = canonicalizeValue(args[field], context)
+    if (value !== args[field]) {
+      next ??= { ...args }
+      next[field] = value
+    }
+  }
+  for (const field of fields.arrays ?? []) {
+    const values = args[field]
+    if (!Array.isArray(values)) continue
+    let changed = false
+    const mapped = values.map((value) => {
+      const canonical = canonicalizeValue(value, context)
+      if (canonical !== value) changed = true
+      return canonical
+    })
+    if (changed) {
+      next ??= { ...args }
+      next[field] = mapped
+    }
+  }
+  return next ?? args
+}
+
+/**
+ * Canonicalize only image-source arguments of Vision Router tools. Ordinary
+ * prose fields are never scanned, so a user mentioning `sha256:deadbeef` in a
+ * question cannot be rewritten accidentally. Local paths remain untouched.
+ * Any sha256-shaped source is reserved for attachment identity and therefore
+ * fails closed rather than falling through to cwd-relative filesystem lookup.
+ */
+export function wrapVisionAttachmentHandleDefinition(def, options = {}) {
+  if (!def || typeof def !== 'object' || typeof def.execute !== 'function') return def
+  const fields = TOOL_FIELDS[def.name]
+  if (!fields || !options.sessionVisionIndex) return def
+  const execute = def.execute
+  return {
+    ...def,
+    execute(args, exec) {
+      const nextArgs = canonicalizeArgs(args, {
+        core: options.core,
+        sessionVisionIndex: options.sessionVisionIndex,
+        agent: exec?.agent,
+        toolName: def.name,
+      }, fields)
+      return execute.call(def, nextArgs, exec)
+    },
+  }
+}