dsh-vision-router 2.3.0 → 3.0.1

package/lib/settings-client-017-compat.js

@@ -14,14 +14,11 @@ export const SETTINGS_017_CLIENT_PRELUDE = String.raw`(function(){
   var connectionCache = typeof WeakMap === 'function' ? new WeakMap() : undefined;
 
   function safeGet(ctx, name) {
-    if (!ctx) return undefined;
+    if (!ctx || typeof ctx.get !== 'function') return undefined;
     try {
-      if (typeof ctx.get === 'function') {
-        var value = ctx.get(name);
-        if (value !== undefined && value !== null) return value;
-      }
-    } catch (_) {}
-    try { return ctx[name]; } catch (_) { return undefined; }
+      var value = ctx.get(name);
+      return value === undefined || value === null ? undefined : value;
+    } catch (_) { return undefined; }
   }
 
   function isLoopbackLocation(locationLike) {
@@ -200,18 +197,27 @@ export const SETTINGS_017_CLIENT_PRELUDE = String.raw`(function(){
       get: function(target, property) {
         if (property === 'settingsScope') {
           var original = safeGet(target, 'settingsScope');
-          if (original && typeof original.bind === 'function') return original;
           // DSH 0.1.7 configForms only mirrors Config fields declared volatile.
           // DVR must keep its public Config ordinary for the older supported Host
           // window, so its namespace intentionally uses the local-only ConfigEditor
-          // bridge while other namespaces may still delegate to native configForms.
+          // bridge. Even when a Host exposes a legacy-shaped settingsScope, its
+          // vision-router view may be empty; keep it only as the delegate for
+          // every other namespace instead of letting it bypass the local bridge.
           var official = configFormsBinder(target);
-          return syntheticBinder(ctx, official);
+          return syntheticBinder(
+            ctx,
+            original && typeof original.bind === 'function' ? original : official
+          );
         }
         if (property === 'get') {
           var getter = Reflect.get(target, property, target);
           if (typeof getter !== 'function') return getter;
           return function(name) {
+            if (name === 'settingsScope') {
+              var original = safeGet(target, 'settingsScope');
+              if (original && typeof original.bind === 'function') return original;
+              return syntheticBinder(ctx, configFormsBinder(target));
+            }
             var value = getter.call(target, name);
             return name === 'connection' ? normalizeConnection(value) : value;
           };

package/lib/structured-flow-hardening.js

@@ -630,7 +630,7 @@ function wrapSettingsScope(scope) {
   })
 }
 
-function wrapSettingsService(settings, setScope) {
+function wrapSettingsService(settings, bindScope) {
   if (!settings || typeof settings !== 'object') return settings
   return new Proxy(settings, {
     get(target, property) {
@@ -643,7 +643,7 @@ function wrapSettingsService(settings, setScope) {
       return (namespace, ...args) => {
         const scope = register.call(target, namespace, ...args)
         if (namespace !== 'vision-router') return scope
-        setScope(scope)
+        if (bindScope(scope) !== true) return scope
         return wrapSettingsScope(scope)
       }
     },
@@ -652,7 +652,8 @@ function wrapSettingsService(settings, setScope) {
 
 function wrapSettingsContext(childCtx, setScope) {
   if (!childCtx || typeof childCtx !== 'object' || !childCtx.settings) return childCtx
-  const settings = wrapSettingsService(childCtx.settings, setScope)
+  const bindScope = (scope) => setScope(scope, childCtx)
+  const settings = wrapSettingsService(childCtx.settings, bindScope)
   return new Proxy(childCtx, {
     get(target, property) {
       if (property === 'settings') return settings
@@ -666,7 +667,24 @@ export function installStructuredFlowHardening(ctx, config = {}) {
   if (!ctx || typeof ctx !== 'object') return ctx
   const states = new WeakMap()
   let settingsScope
-  const setSettingsScope = (scope) => { settingsScope = scope }
+  const setSettingsScope = (scope, ownerCtx) => {
+    if (!scope || (typeof scope !== 'object' && typeof scope !== 'function')) return false
+    // Settings is a dynamic child service. Never retain a scope unless the
+    // child fiber owns its lifetime; otherwise an HMR gap can read stale config.
+    try {
+      if (typeof ownerCtx?.effect !== 'function') return false
+      ownerCtx.effect(
+        () => () => {
+          if (settingsScope === scope) settingsScope = undefined
+        },
+        'vision-router: structured flow settings lifecycle',
+      )
+    } catch {
+      return false
+    }
+    settingsScope = scope
+    return true
+  }
   const activeConfig = () => {
     try {
       const value = settingsScope && typeof settingsScope.get === 'function' ? settingsScope.get() : config

package/lib/tesseract-exec-compat.js

@@ -326,7 +326,15 @@ export function installVisionRouterExecFileCompat(ctx, options = {}) {
   }
 
   if (ctx && typeof ctx.effect === 'function') {
-    ctx.effect(() => dispose, 'vision-router: execFile compatibility')
+    try {
+      ctx.effect(() => dispose, 'vision-router: execFile compatibility')
+    } catch (error) {
+      // The process-global execFile seam was already mutated above. If Cordis
+      // cannot own this generation, undo exactly this installation before the
+      // failure escapes so no orphan patch survives HMR/startup failure.
+      dispose()
+      throw error
+    }
   }
   return dispose
 }

package/lib/turn-budget-context.js

@@ -1,58 +1,64 @@
-import { AsyncLocalStorage } from 'node:async_hooks'
-
-const turnBudgetScope = new AsyncLocalStorage()
-
+import { AsyncLocalStorage } from 'node:async_hooks';
+const turnBudgetScope = new AsyncLocalStorage();
 function usableSignal(value) {
-  return value && typeof value === 'object' && typeof value.aborted === 'boolean' ? value : undefined
+    return value !== null
+        && typeof value === 'object'
+        && typeof value.aborted === 'boolean'
+        ? value
+        : undefined;
 }
-
 function finiteDeadline(value) {
-  const number = Number(value)
-  return Number.isFinite(number) ? number : undefined
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}
+function objectBudget(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
 }
-
 /**
  * Run one async tool execution inside an ambient turn-level budget.
  * Nested budgets may tighten the parent, but may not discard an earlier parent
  * deadline, cancellation signal or artifact-run identity.
  */
 export function runWithVisionTurnBudget(budget, fn) {
-  if (typeof fn !== 'function') throw new TypeError('runWithVisionTurnBudget: fn must be a function')
-  const parent = turnBudgetScope.getStore()
-  const parentSignal = usableSignal(parent?.signal)
-  const childSignal = usableSignal(budget?.signal)
-  const parentDeadline = finiteDeadline(parent?.deadlineAt)
-  const childDeadline = finiteDeadline(budget?.deadlineAt)
-  let next = budget
-  if (parentSignal && childSignal && parentSignal !== childSignal) {
-    next = { ...(next ?? {}), signal: AbortSignal.any([parentSignal, childSignal]) }
-  } else if (parentSignal && !childSignal) {
-    next = { ...(next ?? {}), signal: parentSignal }
-  }
-  if (parentDeadline !== undefined && (childDeadline === undefined || parentDeadline < childDeadline)) {
-    next = { ...(next ?? {}), deadlineAt: parentDeadline }
-  }
-  if (
-    typeof parent?.artifactRunId === 'string' &&
-    parent.artifactRunId !== '' &&
-    !(typeof next?.artifactRunId === 'string' && next.artifactRunId !== '')
-  ) {
-    next = { ...(next ?? {}), artifactRunId: parent.artifactRunId }
-  }
-  return turnBudgetScope.run(next, fn)
+    if (typeof fn !== 'function')
+        throw new TypeError('runWithVisionTurnBudget: fn must be a function');
+    const parent = turnBudgetScope.getStore();
+    const parentSignal = usableSignal(parent?.signal);
+    const childSignal = usableSignal(budget?.signal);
+    const parentDeadline = finiteDeadline(parent?.deadlineAt);
+    const childDeadline = finiteDeadline(budget?.deadlineAt);
+    let next = objectBudget(budget);
+    if (parentSignal && childSignal && parentSignal !== childSignal) {
+        next = { ...(next ?? {}), signal: AbortSignal.any([parentSignal, childSignal]) };
+    }
+    else if (parentSignal && !childSignal) {
+        next = { ...(next ?? {}), signal: parentSignal };
+    }
+    if (parentDeadline !== undefined && (childDeadline === undefined || parentDeadline < childDeadline)) {
+        next = { ...(next ?? {}), deadlineAt: parentDeadline };
+    }
+    if (typeof parent?.artifactRunId === 'string'
+        && parent.artifactRunId !== ''
+        && !(typeof next?.artifactRunId === 'string' && next.artifactRunId !== '')) {
+        next = { ...(next ?? {}), artifactRunId: parent.artifactRunId };
+    }
+    return turnBudgetScope.run(next, fn);
 }
-
 export function currentVisionTurnBudget() {
-  return turnBudgetScope.getStore()
+    return turnBudgetScope.getStore();
 }
-
 export function currentVisionTurnBudgetSignal() {
-  return turnBudgetScope.getStore()?.signal
+    return usableSignal(turnBudgetScope.getStore()?.signal);
 }
-
 export function remainingVisionTurnBudgetMs(now = Date.now) {
-  const budget = turnBudgetScope.getStore()
-  if (!budget || !Number.isFinite(Number(budget.deadlineAt))) return undefined
-  const clock = typeof now === 'function' ? now : Date.now
-  return Math.max(0, Number(budget.deadlineAt) - Number(clock()))
+    const budget = turnBudgetScope.getStore();
+    const deadlineAt = finiteDeadline(budget?.deadlineAt);
+    if (deadlineAt === undefined)
+        return undefined;
+    const clock = typeof now === 'function'
+        ? now
+        : Date.now;
+    return Math.max(0, deadlineAt - Number(clock()));
 }

package/lib/update-check.js

@@ -5,6 +5,15 @@ import { stripTrailingSlashes } from './string-normalization.js'
 const require = createRequire(import.meta.url)
 const packageJson = require('../package.json')
 
+// Capture the process fetch once, at module evaluation, exactly like the
+// Router-owned provider transport. Reading `globalThis.fetch` per call would
+// re-admit DVR's own later-installed process-wide wrappers (legacy proxy,
+// i18n/pi-ai bridge) into DVR's product-metadata requests, and would make the
+// transport used for a request depend on when the request happens to run.
+const moduleFetch = typeof globalThis.fetch === 'function'
+  ? globalThis.fetch.bind(globalThis)
+  : undefined
+
 export const PACKAGE_NAME = 'dsh-vision-router'
 export const CURRENT_VERSION = String(packageJson.version ?? '')
 export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org'
@@ -149,7 +158,7 @@ async function fetchLatestReleaseVersion({ fetchImpl, releaseApi, signal, timeou
  * read-only metadata request against npmjs instead of showing a false failure.
  */
 export async function checkPackageUpdate({
-  fetchImpl = globalThis.fetch,
+  fetchImpl = moduleFetch,
   currentVersion = CURRENT_VERSION,
   registry = registryBaseFromEnv(),
   fallbackRegistry = DEFAULT_NPM_REGISTRY,
@@ -247,7 +256,7 @@ export async function checkPackageUpdate({
  * settings card reuses that result, and the manual button can force a refresh.
  */
 export function createCachedUpdateChecker({
-  fetchImpl = (...args) => globalThis.fetch(...args),
+  fetchImpl = moduleFetch,
   currentVersion = CURRENT_VERSION,
   registry = registryBaseFromEnv(),
   fallbackRegistry = DEFAULT_NPM_REGISTRY,

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

@@ -1,84 +1,91 @@
-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 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'
+    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 objectRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
 }
-
 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
+    const value = objectRecord(ref);
+    if (value === undefined)
+        return undefined;
+    const raw = value.attachmentId ?? value.id;
+    if (raw === undefined || raw === null)
+        return undefined;
+    const id = String(raw).trim();
+    return id === '' ? undefined : id;
 }
-
 function sessionMessages(session) {
-  try {
-    if (!session || typeof session.deriveMessages !== 'function') return []
-    const messages = session.deriveMessages()
-    return Array.isArray(messages) ? messages : []
-  } catch {
-    return []
-  }
+    try {
+        if (!session || typeof session.deriveMessages !== 'function')
+            return [];
+        const messages = session.deriveMessages();
+        return Array.isArray(messages) ? messages : [];
+    }
+    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)
-  }
+    if (!Array.isArray(blocks))
+        return;
+    for (const block of blocks) {
+        const value = objectRecord(block);
+        if (value === undefined)
+            continue;
+        if (value.type === 'image') {
+            const attachment = objectRecord(value.attachment);
+            if (attachment !== undefined)
+                out.push(attachment);
+        }
+        if (Array.isArray(value.content))
+            collectImageRefsFromBlocks(value.content, out);
+    }
 }
-
 function collectImageRefsFromMessages(messages, out) {
-  if (!Array.isArray(messages)) return
-  for (const message of messages) collectImageRefsFromBlocks(message?.content, out)
+    if (!Array.isArray(messages))
+        return;
+    for (const message of messages) {
+        collectImageRefsFromBlocks(objectRecord(message)?.content, out);
+    }
 }
-
 function authorizedRefs(agent) {
-  const refs = []
-  collectImageRefsFromMessages(sessionMessages(agent?.session), refs)
-  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()]
+    const refs = [];
+    collectImageRefsFromMessages(sessionMessages(agent?.session), refs);
+    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())
+    return typeof value === 'string' && PROJECTED_SHA256_HANDLE.test(value.trim());
 }
-
 function isSha256HandleLike(value) {
-  return typeof value === 'string' && SHA256_HANDLE_PREFIX.test(value.trim())
+    return typeof value === 'string' && SHA256_HANDLE_PREFIX.test(value.trim());
 }
-
 function isCanonicalSha256Id(value) {
-  return typeof value === 'string' && CANONICAL_SHA256_ID.test(value.trim())
+    return 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.
@@ -89,91 +96,95 @@ function isCanonicalSha256Id(value) {
  * prefix. Zero or multiple matches fail closed.
  */
 export function resolveProjectedAttachmentHandle(handle, { 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(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 {
-    // Authorization is still fail-closed if the bounded cache cannot be warmed.
-  }
-  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 }
+    const token = typeof handle === 'string' ? handle.trim() : '';
+    if (!isProjectedAttachmentHandle(token))
+        return { kind: 'not-projected', value: handle };
+    const session = agent?.session;
+    const refs = authorizedRefs(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 (candidate === undefined || 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 {
+        // Authorization is still fail-closed if the bounded cache cannot be warmed.
+    }
+    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)',
-  )
+    if (!isSha256HandleLike(value))
+        return value;
+    if (isCanonicalSha256Id(value))
+        return value;
+    if (!isProjectedAttachmentHandle(value)) {
+        throw new Error(`${context.toolName}: invalid attachment handle "${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)');
+    }
+    if (result.kind === 'unknown') {
+        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)');
+    }
+    return value;
 }
-
 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
+    const record = objectRecord(args);
+    if (record === undefined)
+        return args;
+    let next;
+    for (const field of fields.scalars ?? []) {
+        if (!Object.hasOwn(record, field))
+            continue;
+        const value = canonicalizeValue(record[field], context);
+        if (value !== record[field]) {
+            next ??= { ...record };
+            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
+    for (const field of fields.arrays ?? []) {
+        const values = record[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 ??= { ...record };
+            next[field] = mapped;
+        }
     }
-  }
-  return next ?? args
+    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
@@ -182,19 +193,28 @@ function canonicalizeArgs(args, context, fields) {
  * 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, {
-        sessionVisionIndex: options.sessionVisionIndex,
-        agent: exec?.agent,
-        toolName: def.name,
-      }, fields)
-      return execute.call(def, nextArgs, exec)
-    },
-  }
+    // Tool definitions arrive from the Host registry at runtime. Static generic
+    // constraints cannot replace this boundary guard: partial/legacy Hosts may
+    // still pass nullish or malformed values before their own validation runs.
+    if (def === null || typeof def !== 'object' || typeof def.execute !== 'function')
+        return def;
+    const toolName = def.name;
+    const fields = typeof toolName === 'string'
+        ? TOOL_FIELDS[toolName]
+        : undefined;
+    const sessionVisionIndex = options.sessionVisionIndex;
+    if (!fields || !sessionVisionIndex || typeof toolName !== 'string')
+        return def;
+    const execute = def.execute;
+    return {
+        ...def,
+        execute(args, exec) {
+            const nextArgs = canonicalizeArgs(args, {
+                sessionVisionIndex,
+                ...(exec?.agent === undefined ? {} : { agent: exec.agent }),
+                toolName,
+            }, fields);
+            return execute.call(def, nextArgs, exec);
+        },
+    };
 }