dsh-vision-router 1.7.5 → 1.7.7

package/entry.js

@@ -12,7 +12,9 @@ import { installVisionRouterFileLogging } from './lib/file-logger.js'
 import { contextWithDelegatedReplay } from './lib/replay-delegation.js'
 import { contextWithReplayEnvelopeV2Compat } from './lib/replay-envelope-v2-compat.js'
 import { contextWithVisionExecutionPolicy } from './lib/vision-execution-policy.js'
+import { contextWithVisionBackendRuntimePolicy } from './lib/vision-backend-runtime-policy.js'
 import { contextWithNativeImageCoexistence } from './lib/native-image-coexistence.js'
+import { installLegacyCoreVisionPolicyBridge } from './lib/legacy-core-vision-policy-bridge.js'
 import { installPiAiBridgeWireCompat } from './lib/pi-ai-bridge-wire-compat.js'
 import { installLiveModelDiscovery } from './lib/live-model-discovery.js'
 import { installVisionModelRegistry } from './lib/vision-model-registry.js'
@@ -56,10 +58,13 @@ export const SETTINGS_CONTRACT_REVISION = 4
 // for the settings namespace, so composition config and settings validation
 // agree on the same default.
 core.Config.set('progressiveTools', z.boolean().default(false))
-// Structured 1+x also has a turn-level wall-clock budget. Individual
-// visionTaskTimeoutMs budgets remain unchanged; this one prevents a deep turn
-// from multiplying them into several minutes of serial waiting.
-core.Config.set('visionTurnBudgetMs', z.number().step(1000).min(10000).max(600000).default(90000))
+// Keep the three timeout layers coherent: one provider call may use up to 120s,
+// one visual task (including fallbacks) shares 120s, and one visual turn shares
+// 120s. The runtime policy below reserves the final quarter of a multi-backend
+// task for fallback, so raising the task ceiling does not revive the historical
+// "120s per backend" stall that #117 removed.
+core.Config.set('visionTaskTimeoutMs', z.number().step(1000).min(1000).max(180000).default(120000))
+core.Config.set('visionTurnBudgetMs', z.number().step(1000).min(10000).max(600000).default(120000))
 
 // Both visible entry points — Settings > Vision Router and the legacy
 // Settings > Plugins compatibility card — edit the same Host-owned namespace.
@@ -113,7 +118,12 @@ export function apply(ctx, config = {}) {
   // route is registered. The wrapper patches only webServer.register and hands
   // every injection callback the original child context identity unchanged.
   const localMutationCtx = installLocalMutationRouteBoundary(ctx)
-  const logging = installVisionRouterFileLogging(localMutationCtx)
+  // Normalize DSH 0.1.1's prepareCall contract at the deepest private LLM
+  // boundary. Higher Vision Router layers can finish wrapping adapter.stream
+  // before this boundary captures the final Host-visible adapter, so prepareCall
+  // cannot bypass local/runtime/replay stream behavior.
+  const adapterContractCtx = contextWithCoalescedAdapterUpdates(localMutationCtx)
+  const logging = installVisionRouterFileLogging(adapterContractCtx)
   const delegatedReplayCtx = contextWithDelegatedReplay(logging.ctx, {
     wrapperRoute:
       typeof config.wrapperRoute === 'string' && config.wrapperRoute !== ''
@@ -144,7 +154,7 @@ export function apply(ctx, config = {}) {
   // inference. Install this boundary before the local-vision stabilizer so the
   // final local vision-http adapter is observed after stabilization. Primary
   // local-Ollama image turns finish a cold model load in pre-step, before the
-  // 45s vision-task budget begins; fallback Ollama warms in the background.
+  // visual task budget begins; fallback Ollama warms in the background.
   const ollamaColdStartCtx = installOllamaColdStartGuard(hardenedCtx, hardenedConfig, core)
   // #141 stabilization boundary: keep the recently merged local-vision
   // behavior isolated from main's existing provider/router semantics. It
@@ -160,10 +170,14 @@ export function apply(ctx, config = {}) {
     ...bootConfig,
     progressiveTools: hardenedConfig.progressiveTools === true,
     guidanceOverrides: normalizeGuidanceOverrides(bootConfig.guidanceOverrides ?? hardenedConfig.guidanceOverrides),
+    visionTaskTimeoutMs:
+      Number.isFinite(Number(bootConfig.visionTaskTimeoutMs))
+        ? Number(bootConfig.visionTaskTimeoutMs)
+        : 120000,
     visionTurnBudgetMs:
       Number.isFinite(Number(bootConfig.visionTurnBudgetMs))
         ? Number(bootConfig.visionTurnBudgetMs)
-        : 90000,
+        : 120000,
   }
   // The batch-attachment API is the released, non-incidental discriminator
   // between the minimum Host contract and the newer Host-owned integration
@@ -204,23 +218,32 @@ export function apply(ctx, config = {}) {
   // so rc.7/rc.8's synthetic settings injection is visible to the boundary.
   // The secure screenshot renderer owns its exact FsTarget and active browser
   // cancellation directly, so it does not depend on this placement.
-  const toolRuntimeCtx = installVisionToolRuntimeBoundary(attachmentCompatCtx)
+  const toolRuntimeCtx = installVisionToolRuntimeBoundary(attachmentCompatCtx, runtimeConfig)
   // DSH 0.1.1 publishes an exact native image-capable DeepSeek model. Do not
   // put it ahead of Vision Router's own configured chain: only when the user
   // has explicitly selected any Host-native image route, preserve raw pixels
-  // and skip the hidden instant-local caption pass for that turn. The override
-  // is AsyncLocalStorage-scoped and never mutates settings or provider order.
+  // and skip the hidden instant-local caption pass for that turn. Ownership is
+  // AsyncLocalStorage-scoped and never mutates settings or provider order.
   const nativeImageCompat = contextWithNativeImageCoexistence(toolRuntimeCtx, runtimeConfig)
+  // index.js still carries legacy global wrapper/tool gates. Feed the new
+  // session policy into that core through one narrow compatibility bridge:
+  // native/owned/unknown routes preserve raw pixels, text-only routes are
+  // normalized by the core's own rewriteHistoryImages implementation, and the
+  // boot-only tool projection ends immediately after core.apply wires schema.
+  const legacyCoreCompat = installLegacyCoreVisionPolicyBridge(
+    nativeImageCompat.ctx,
+    nativeImageCompat.config,
+    { rewriteHistoryImages: core.rewriteHistoryImages },
+  )
   // Final structured-flow guard sits closest to core.apply so it sees the
   // actual tool registrations and pre-step listener. It makes bootstrap
   // one-shot, enforces fast/standard/deep/custom quotas, tracks mixed branches,
   // rejects empty/non-evidence results, and applies one shared visual deadline.
-  const structuredCtx = installStructuredFlowHardening(nativeImageCompat.ctx, nativeImageCompat.config)
-  // Newer DSH releases publish llm/adapters-updated synchronously from inside
-  // registerAdapter(). Coalesce only Vision Router's listener: nested events
-  // mark the topology dirty and the outer pass reruns to a fixed point, so we
-  // neither double-register a twin nor lose a provider added mid-pass.
-  const reconciledCtx = contextWithCoalescedAdapterUpdates(structuredCtx)
+  const structuredCtx = installStructuredFlowHardening(legacyCoreCompat.ctx, legacyCoreCompat.config)
+  // Adapter reconciliation + prepareCall normalization are already installed at
+  // the final Host registration boundary above. Wrapping again here would make
+  // prepareCall capture a pre-wrapper stream.
+  const reconciledCtx = structuredCtx
   // Discover the provider's actual /models list independently of DSH's static
   // catalog. The Host owns credentials/networking/cache; the browser receives
   // model ids only. A live hit is also the evidence required before an
@@ -259,22 +282,27 @@ export function apply(ctx, config = {}) {
   // maxTokensField + route headers at its final fetch boundary. Ordinary DSH
   // streams and unrelated Vision Router HTTP providers remain byte-identical.
   installPiAiBridgeWireCompat(reconciledCtx, logging.logger)
-  // Direct compatibility bridging is allowed only after DSH/pi-ai's exact
-  // pre-wire image-capability admission rejection, or a local UNKNOWN_MODEL
-  // backed by exact private-registry evidence. Record the same provenance in
-  // the persistent diagnostics log so one image turn clearly shows attempt ->
-  // adapter failure -> direct bridge -> success/fallback. Provider/network/auth
-  // failures remain authoritative and cannot be retried through a second path.
+  // Existing execution policy stays authoritative for adapter-observed failures:
+  // only exact local pre-wire admission failures may unlock the post-failure
+  // bridge. The outer runtime policy added below handles the complementary case
+  // where DSH would silently project pixels to SHA text before the adapter ever
+  // gets a chance to reject them.
   const executionCtx = contextWithVisionExecutionPolicy(reconciledCtx, {
     isBridgeEvidence: (provider, model) => liveDiscovery.hasModel(provider, model),
     evidenceSource: (provider, model) => liveDiscovery.evidenceSource?.(provider, model),
     logger: logging.logger,
   })
+  const backendRuntimeCtx = contextWithVisionBackendRuntimePolicy(executionCtx, {
+    config: runtimeConfig,
+    core,
+    evidenceSource: (provider, model) => liveDiscovery.evidenceSource?.(provider, model),
+    logger: logging.logger,
+  })
   // The smoke-test route sends only a built-in probe image to the exact selected
   // backend. It never walks the configured fallback chain, so a healthy OVH
   // fallback can no longer make a broken custom model look healthy. Its narrow
   // compatibility bridge uses the same live-discovery evidence gate as runtime.
-  installVisionBackendSmokeTest(executionCtx, runtimeConfig, core, {
+  installVisionBackendSmokeTest(backendRuntimeCtx, runtimeConfig, core, {
     logger: logging.logger,
     isBridgeEvidence: (provider, model) => liveDiscovery.hasModel(provider, model),
   })
@@ -283,7 +311,7 @@ export function apply(ctx, config = {}) {
   // for data until the OCR slice expires. Materialize only this exact
   // Tesseract-stdin call to a temporary image file; all other execFile calls
   // keep their native behavior.
-  installTesseractExecFileCompat(executionCtx)
+  installTesseractExecFileCompat(backendRuntimeCtx)
 
   // 启动诊断摘要只描述 composition/apply 的基础配置。设置服务可能稍后
   // 覆盖这些值；每个图片轮还会记录 current() 的实时决策，避免把这个
@@ -304,7 +332,8 @@ export function apply(ctx, config = {}) {
     /* diagnostics must never break apply */
   }
   try {
-    const result = core.apply(executionCtx, nativeImageCompat.config)
+    const result = core.apply(backendRuntimeCtx, legacyCoreCompat.config)
+    legacyCoreCompat.finishSchemaBootstrap()
     // On newer Hosts the Settings -> Models surface is backed by the
     // configurable-provider directory, not by the live adapter registry alone.
     // Publish the main DeepSeek + 自动识图 route as a derived alias of official
@@ -321,6 +350,7 @@ export function apply(ctx, config = {}) {
     }
     return result
   } catch (error) {
+    legacyCoreCompat.finishSchemaBootstrap()
     logging.logger.error(
       'vision-router: plugin apply failed: %s',
       error && error.stack ? error.stack : error && error.message ? error.message : String(error),

package/lib/adapter-update-coalescer.js

@@ -1,7 +1,84 @@
 const wrappedContexts = new WeakMap()
+const wrappedLlmServices = new WeakMap()
+const preparedAdapterCompat = new WeakMap()
 
 export const DEFAULT_ADAPTER_RECONCILE_MAX_PASSES = 32
 
+/**
+ * DSH 0.1.1 dispatches every model call through adapter.prepareCall(). Older
+ * Vision Router adapters are intentionally duck-typed objects and therefore do
+ * not inherit LlmAdapter's default implementation. Normalize only adapters
+ * registered through Vision Router's wrapped context so host/foreign adapters
+ * keep their native identity and behavior.
+ */
+export function ensureAdapterPrepareCall(adapter) {
+  if (!adapter || (typeof adapter !== 'object' && typeof adapter !== 'function')) return adapter
+  if (typeof adapter.prepareCall === 'function') return adapter
+
+  const cached = preparedAdapterCompat.get(adapter)
+  if (cached) return cached
+
+  const prepareCall = async (provider, model, signal) => {
+    const fallbackModel = { provider, id: model, name: model }
+    const resolved =
+      typeof adapter.resolveModel === 'function'
+        ? await adapter.resolveModel.call(adapter, provider, model, signal)
+        : fallbackModel
+    return {
+      model: resolved && typeof resolved === 'object' ? resolved : fallbackModel,
+      stream(options) {
+        return adapter.stream.call(adapter, options)
+      },
+    }
+  }
+
+  // Preserve the exact adapter object whenever possible. Some runtime paths
+  // retain registration.adapter and compare/reuse it later, so mutation is less
+  // surprising than substituting a wrapper. Frozen/sealed adapters fall back to
+  // a proxy that exposes only the missing contract method.
+  try {
+    Object.defineProperty(adapter, 'prepareCall', {
+      configurable: true,
+      writable: true,
+      value: prepareCall,
+    })
+    preparedAdapterCompat.set(adapter, adapter)
+    return adapter
+  } catch {
+    const wrapped = new Proxy(adapter, {
+      get(target, property) {
+        if (property === 'prepareCall') return prepareCall
+        const value = Reflect.get(target, property, target)
+        return typeof value === 'function' ? value.bind(target) : value
+      },
+    })
+    preparedAdapterCompat.set(adapter, wrapped)
+    return wrapped
+  }
+}
+
+function wrapLlmService(llm) {
+  if (!llm || (typeof llm !== 'object' && typeof llm !== 'function')) return llm
+  const cached = wrappedLlmServices.get(llm)
+  if (cached) return cached
+
+  const wrapped = new Proxy(llm, {
+    get(target, property) {
+      if (property === 'registerAdapter') {
+        const registerAdapter = Reflect.get(target, property, target)
+        if (typeof registerAdapter !== 'function') return registerAdapter
+        return (providers, adapter, ...rest) =>
+          registerAdapter.call(target, providers, ensureAdapterPrepareCall(adapter), ...rest)
+      }
+      const value = Reflect.get(target, property, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+
+  wrappedLlmServices.set(llm, wrapped)
+  return wrapped
+}
+
 /**
  * Turn a synchronous reconciliation pass into a bounded fixed-point runner.
  *
@@ -76,6 +153,10 @@ export function createCoalescingRunner(run, options = {}) {
  * registerAdapter() returns. Only Vision Router listeners registered through
  * this wrapped context are coalesced; host and other plugin listeners keep
  * their native event semantics.
+ *
+ * The same boundary also normalizes Vision Router-owned adapter registrations
+ * to the DSH 0.1.1 prepareCall contract. This stays scoped to the wrapped
+ * context instead of monkey-patching the Host LLM service process-wide.
  */
 export function contextWithCoalescedAdapterUpdates(ctx) {
   if (!ctx || (typeof ctx !== 'object' && typeof ctx !== 'function')) return ctx
@@ -84,6 +165,9 @@ export function contextWithCoalescedAdapterUpdates(ctx) {
 
   const wrapped = new Proxy(ctx, {
     get(target, property) {
+      if (property === 'llm') {
+        return wrapLlmService(Reflect.get(target, property, target))
+      }
       if (property === 'on') {
         const on = Reflect.get(target, property, target)
         if (typeof on !== 'function') return on

package/lib/legacy-core-vision-policy-bridge.js

@@ -0,0 +1,274 @@
+import {
+  IMAGE_OWNERSHIP,
+  currentSessionVisionPolicy,
+} from './native-image-coexistence.js'
+import { knownSessionVisionMemory } from './session-vision-state.js'
+
+function isObject(value) {
+  return value !== null && typeof value === 'object'
+}
+
+function projectedConfig(value, state) {
+  if (!isObject(value) || Array.isArray(value)) return value
+  const policy = currentSessionVisionPolicy()
+  let changed = false
+  const overrides = {}
+
+  // index.js still constructs the vision-tool definitions behind a boot-time
+  // `if (toolEnabled())`. Keep that legacy construction gate open only while
+  // apply() is wiring the schema. The runtime boundary observes the unprojected
+  // Settings service and remains authoritative for live execution permission.
+  if (state.schemaBootstrapping && value.tool === false) {
+    overrides.tool = true
+    changed = true
+  }
+
+  // Session ownership is stronger evidence than index.js's historical global
+  // wrapperRegistered flag. A native, Vision-Router-owned, or metadata-unknown
+  // route must not have raw pixels destructively rewritten by the legacy core.
+  if (policy?.preserveRawImages === true && value.rewriteImages !== false) {
+    overrides.rewriteImages = false
+    changed = true
+  }
+
+  // Native multimodal routes already see the pixels. Avoid the hidden local
+  // caption pass and the generic tool auto-mount reminder, while leaving the
+  // explicit structured 1+x flow untouched.
+  if (policy?.ownership === IMAGE_OWNERSHIP.NATIVE) {
+    if (value.instantDescribe !== false) {
+      overrides.instantDescribe = false
+      changed = true
+    }
+    if (value.autoActivateOnImage !== false) {
+      overrides.autoActivateOnImage = false
+      changed = true
+    }
+  }
+
+  return changed ? { ...value, ...overrides } : value
+}
+
+function configView(config, state) {
+  if (!isObject(config)) return config
+  // Do not use the caller's config as the Proxy target. DSH or a test Host may
+  // freeze parsed config objects; projecting tool/rewrite values through a
+  // frozen target would violate Proxy invariants for non-configurable,
+  // non-writable properties. An empty extensible facade keeps projection
+  // virtual while writes/deletes still forward to the original object.
+  return new Proxy({}, {
+    get(_target, property) {
+      const projected = projectedConfig(config, state)
+      const value = Reflect.get(projected, property, projected)
+      return typeof value === 'function' ? value.bind(projected) : value
+    },
+    has(_target, property) {
+      return property in projectedConfig(config, state)
+    },
+    ownKeys() {
+      return Reflect.ownKeys(projectedConfig(config, state))
+    },
+    getOwnPropertyDescriptor(_target, property) {
+      const projected = projectedConfig(config, state)
+      const descriptor = Object.getOwnPropertyDescriptor(projected, property)
+      return descriptor === undefined
+        ? undefined
+        : { ...descriptor, configurable: true }
+    },
+    getPrototypeOf() {
+      return Reflect.getPrototypeOf(config)
+    },
+    set(_target, property, value) {
+      return Reflect.set(config, property, value, config)
+    },
+    deleteProperty(_target, property) {
+      return Reflect.deleteProperty(config, property)
+    },
+  })
+}
+
+function scopeView(scope, state) {
+  if (!isObject(scope)) return scope
+  return new Proxy(scope, {
+    get(target, property) {
+      if (property === 'get') {
+        const get = Reflect.get(target, property, target)
+        if (typeof get !== 'function') return get
+        return (...args) => projectedConfig(get.apply(target, args), state)
+      }
+      if (property === 'watch') {
+        const watch = Reflect.get(target, property, target)
+        if (typeof watch !== 'function') return watch
+        return (callback, ...rest) =>
+          watch.call(
+            target,
+            (...args) => {
+              if (typeof callback !== 'function') return undefined
+              if (args.length === 0) return callback()
+              const [value, ...tail] = args
+              return callback(projectedConfig(value, state), ...tail)
+            },
+            ...rest,
+          )
+      }
+      const value = Reflect.get(target, property, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}
+
+function settingsView(settings, state) {
+  if (!isObject(settings)) return settings
+  return new Proxy(settings, {
+    get(target, property) {
+      if (property === 'get') {
+        const get = Reflect.get(target, property, target)
+        if (typeof get !== 'function') return get
+        return (namespace, ...args) => {
+          const value = get.call(target, namespace, ...args)
+          return namespace === 'vision-router' ? projectedConfig(value, state) : value
+        }
+      }
+      if (property === 'register') {
+        const register = Reflect.get(target, property, target)
+        if (typeof register !== 'function') return register
+        return (namespace, ...args) => {
+          const scope = register.call(target, namespace, ...args)
+          return namespace === 'vision-router' ? scopeView(scope, state) : scope
+        }
+      }
+      const value = Reflect.get(target, property, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}
+
+function childContextView(child, state) {
+  if (!isObject(child)) return child
+  const settings = settingsView(child.settings, state)
+  return new Proxy(child, {
+    get(target, property) {
+      if (property === 'settings') return settings
+      const value = Reflect.get(target, property, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}
+
+function rewriteTextOnlyDecision(payload, decision, rewriteHistoryImages) {
+  const policy = currentSessionVisionPolicy()
+  if (
+    decision?.kind === 'reject' ||
+    policy?.rewriteCurrentImages !== true ||
+    typeof rewriteHistoryImages !== 'function'
+  ) {
+    return decision
+  }
+
+  const source = Array.isArray(decision?.messages)
+    ? decision.messages
+    : Array.isArray(payload?.messages)
+      ? payload.messages
+      : undefined
+  if (!source) return decision
+
+  // Core registers the exact SessionMemoryView while processing this same
+  // pre-step. Reuse it here so a text-only fallback preserves cached visual
+  // descriptions instead of degrading them back to a generic attachment marker.
+  const memory = knownSessionVisionMemory(payload?.agent?.session)
+  const rewritten = rewriteHistoryImages(source, memory)
+  const messages = rewritten?.messages
+  if (!Array.isArray(messages) || messages === source) return decision
+  if (isObject(decision)) return { ...decision, messages }
+  return { kind: 'continue', messages }
+}
+
+/**
+ * Adapt the session-scoped ownership policy to the legacy monolithic core.
+ *
+ * The policy layer remains read-only. This bridge only projects legacy config
+ * reads while one pre-step is active and post-processes an explicitly text-only
+ * decision through index.js's exported rewriteHistoryImages implementation and
+ * the exact SessionMemoryView registered by core for that pre-step. No marker,
+ * rewrite algorithm, or cross-session image state is duplicated here.
+ */
+export function installLegacyCoreVisionPolicyBridge(
+  ctx,
+  config = {},
+  { rewriteHistoryImages } = {},
+) {
+  if (!isObject(ctx)) {
+    return {
+      ctx,
+      config,
+      finishSchemaBootstrap() {},
+    }
+  }
+
+  const state = { schemaBootstrapping: true }
+  const projectedBootConfig = configView(config, state)
+  const settingsCache = new WeakMap()
+
+  const wrapSettings = (settings) => {
+    if (!isObject(settings)) return settings
+    const cached = settingsCache.get(settings)
+    if (cached) return cached
+    const wrapped = settingsView(settings, state)
+    settingsCache.set(settings, wrapped)
+    return wrapped
+  }
+
+  const wrappedCtx = new Proxy(ctx, {
+    get(target, property) {
+      if (property === 'get') {
+        const get = Reflect.get(target, property, target)
+        if (typeof get !== 'function') return get
+        return (name, ...args) => {
+          const value = get.call(target, name, ...args)
+          return name === 'settings' ? wrapSettings(value) : value
+        }
+      }
+      if (property === 'inject') {
+        const inject = Reflect.get(target, property, target)
+        if (typeof inject !== 'function') return inject
+        return (dependencies, callback, ...rest) => {
+          if (
+            !Array.isArray(dependencies) ||
+            !dependencies.includes('settings') ||
+            typeof callback !== 'function'
+          ) {
+            return inject.call(target, dependencies, callback, ...rest)
+          }
+          return inject.call(
+            target,
+            dependencies,
+            (child) => callback(childContextView(child, state)),
+            ...rest,
+          )
+        }
+      }
+      if (property === 'on') {
+        const on = Reflect.get(target, property, target)
+        if (typeof on !== 'function') return on
+        return (event, handler, ...rest) => {
+          if (event !== 'agent/pre-step' || typeof handler !== 'function') {
+            return on.call(target, event, handler, ...rest)
+          }
+          return on.call(target, event, async function legacyCoreVisionPolicyPreStep(payload, next) {
+            const decision = await handler.call(this, payload, next)
+            return rewriteTextOnlyDecision(payload, decision, rewriteHistoryImages)
+          }, ...rest)
+        }
+      }
+      const value = Reflect.get(target, property, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+
+  return {
+    ctx: wrappedCtx,
+    config: projectedBootConfig,
+    finishSchemaBootstrap() {
+      state.schemaBootstrapping = false
+    },
+  }
+}

package/lib/local-vision-stabilizer.js

@@ -100,7 +100,11 @@ export function installLocalVisionStabilizer(ctx, config = {}, core) {
 
   const syncScreenshot = () => {
     if (!screenshotCandidate || !rawTools || typeof rawTools.register !== 'function') return
-    if (actualConfig().desktopScreenshot !== true) {
+    const current = actualConfig()
+    // desktopScreenshot owns schema exposure. The global tool toggle is a live
+    // execution permission enforced by the runtime boundary (and the captured
+    // execute guard below), so flipping it must not churn the tool schema.
+    if (current.desktopScreenshot !== true) {
       unmountScreenshot()
       return
     }
@@ -125,14 +129,28 @@ export function installLocalVisionStabilizer(ctx, config = {}, core) {
           }
           return (def) => {
             if (def && def.name === 'vision_screenshot') {
-              screenshotCandidate = def
+              const candidate =
+                typeof def.execute === 'function'
+                  ? {
+                      ...def,
+                      async execute(args, exec) {
+                        if (actualConfig().tool === false) {
+                          throw new Error(
+                            'vision_screenshot: vision tools are disabled in the Vision Router settings',
+                          )
+                        }
+                        return def.execute.call(this, args, exec)
+                      },
+                    }
+                  : def
+              screenshotCandidate = candidate
               syncScreenshot()
               let active = true
               return () => {
                 if (!active) return
                 active = false
-                if (screenshotCandidate === def) screenshotCandidate = undefined
-                if (screenshotMountedDef === def) unmountScreenshot()
+                if (screenshotCandidate === candidate) screenshotCandidate = undefined
+                if (screenshotMountedDef === candidate) unmountScreenshot()
               }
             }
             return target.register(def)
@@ -393,7 +411,13 @@ export function installLocalVisionStabilizer(ctx, config = {}, core) {
           res.end(JSON.stringify({ ok: false, error: 'cross-origin screenshot permission request rejected' }))
           return
         }
-        if (actualConfig().desktopScreenshot !== true) {
+        const current = actualConfig()
+        if (current.tool === false) {
+          res.writeHead(409, { 'content-type': 'application/json' })
+          res.end(JSON.stringify({ ok: false, error: 'vision tools are disabled' }))
+          return
+        }
+        if (current.desktopScreenshot !== true) {
           res.writeHead(409, { 'content-type': 'application/json' })
           res.end(JSON.stringify({ ok: false, error: 'desktop screenshot is disabled' }))
           return
@@ -493,4 +517,4 @@ export function installLocalVisionStabilizer(ctx, config = {}, core) {
   })
 
   return { ctx: stabilizedCtx, bootConfig }
-}
+}