dsh-vision-router 2.3.0 → 3.0.0

package/lib/vision-execution-order.js

@@ -1,21 +1,21 @@
-import { AsyncLocalStorage } from 'node:async_hooks'
-
-const executionOrderScope = new AsyncLocalStorage()
-
+import { AsyncLocalStorage } from 'node:async_hooks';
+const executionOrderScope = new AsyncLocalStorage();
 function normalizedPair(pair) {
-  const provider = typeof pair?.provider === 'string' ? pair.provider.trim() : ''
-  const model = typeof pair?.model === 'string' ? pair.model.trim() : ''
-  if (provider === '' || model === '') {
-    throw new TypeError('vision execution order entries require non-empty provider and model')
-  }
-  return Object.freeze({ provider, model })
+    const value = pair !== null && typeof pair === 'object'
+        ? pair
+        : {};
+    const provider = typeof value.provider === 'string' ? value.provider.trim() : '';
+    const model = typeof value.model === 'string' ? value.model.trim() : '';
+    if (provider === '' || model === '') {
+        throw new TypeError('vision execution order entries require non-empty provider and model');
+    }
+    return Object.freeze({ provider, model });
 }
-
 function normalizedOrder(order) {
-  if (!Array.isArray(order)) throw new TypeError('vision execution order must be an array')
-  return Object.freeze(order.map(normalizedPair))
+    if (!Array.isArray(order))
+        throw new TypeError('vision execution order must be an array');
+    return Object.freeze(order.map(normalizedPair));
 }
-
 /**
  * Run one Router-owned visual execution with an explicit provider/model order.
  *
@@ -24,15 +24,15 @@ function normalizedOrder(order) {
  * Host services, or mutable caller objects.
  */
 export function withVisionExecutionOrder(order, fn) {
-  if (typeof fn !== 'function') throw new TypeError('withVisionExecutionOrder requires a function')
-  const scopedOrder = normalizedOrder(order)
-  return executionOrderScope.run({ order: scopedOrder }, fn)
+    if (typeof fn !== 'function')
+        throw new TypeError('withVisionExecutionOrder requires a function');
+    const scopedOrder = normalizedOrder(order);
+    return executionOrderScope.run({ order: scopedOrder }, fn);
 }
-
 /**
  * Current Router-owned visual order for this async call chain, or undefined
  * outside an explicit visual execution scope.
  */
 export function currentVisionExecutionOrder() {
-  return executionOrderScope.getStore()?.order
+    return executionOrderScope.getStore()?.order;
 }

package/lib/vision-execution-policy.js

@@ -517,15 +517,20 @@ export function contextWithVisionExecutionPolicy(ctx, options = {}) {
     },
   })
   wrappedContexts.set(ctx, wrapped)
+  let lifecycleOwned = false
   try {
-    ctx.effect?.(
-      () => () => {
-        if (wrappedContexts.get(ctx) === wrapped) wrappedContexts.delete(ctx)
-      },
-      'vision-router: strict vision execution policy context',
-    )
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(
+        () => () => {
+          if (wrappedContexts.get(ctx) === wrapped) wrappedContexts.delete(ctx)
+        },
+        'vision-router: strict vision execution policy context',
+      )
+      lifecycleOwned = true
+    }
   } catch {
-    /* lifecycle hardening must never block plugin apply */
+    // The current caller may still use this private view.
   }
+  if (!lifecycleOwned && wrappedContexts.get(ctx) === wrapped) wrappedContexts.delete(ctx)
   return wrapped
 }

package/lib/vision-model-registry.js

@@ -222,16 +222,23 @@ export function installVisionModelRegistry(ctx, liveDiscovery, options = {}) {
   if (!liveDiscovery || typeof liveDiscovery.snapshot !== 'function') return liveDiscovery
   if (liveDiscovery.snapshot.__visionRouterRegistry === true) return liveDiscovery
 
-  const originalSnapshot = liveDiscovery.snapshot.bind(liveDiscovery)
+  const originalSnapshot = liveDiscovery.snapshot
   const originalHasModel = typeof liveDiscovery.hasModel === 'function'
-    ? liveDiscovery.hasModel.bind(liveDiscovery)
-    : () => false
+    ? liveDiscovery.hasModel
+    : undefined
   const originalEvidenceSource = typeof liveDiscovery.evidenceSource === 'function'
-    ? liveDiscovery.evidenceSource.bind(liveDiscovery)
+    ? liveDiscovery.evidenceSource
     : undefined
+  const callSnapshot = (request) => Reflect.apply(originalSnapshot, liveDiscovery, [request])
+  const callHasModel = (provider, model) => originalHasModel === undefined
+    ? false
+    : Reflect.apply(originalHasModel, liveDiscovery, [provider, model])
+  const callEvidenceSource = (provider, model) => originalEvidenceSource === undefined
+    ? undefined
+    : Reflect.apply(originalEvidenceSource, liveDiscovery, [provider, model])
 
   const wrappedSnapshot = async (request) => decorateVisionModelSnapshot(
-    await originalSnapshot(request),
+    await callSnapshot(request),
     { ctx, config: options.config ?? {} },
   )
   // Diagnostics-only provenance. This must never become the admission oracle:
@@ -239,15 +246,15 @@ export function installVisionModelRegistry(ctx, liveDiscovery, options = {}) {
   // endpoint evidence OR exact endpoint-scoped trusted hint).
   const wrappedEvidenceSource = (provider, model) => {
     if (isProviderActive(ctx, provider) && hasTrustedVisionHint(ctx, provider, model)) return 'known'
-    if (originalHasModel(provider, model)) return 'live'
+    if (callHasModel(provider, model)) return 'live'
     try {
-      return originalEvidenceSource?.(provider, model)
+      return callEvidenceSource(provider, model)
     } catch {
       return undefined
     }
   }
   const wrappedHasModel = (provider, model) => (
-    originalHasModel(provider, model) ||
+    callHasModel(provider, model) ||
     (isProviderActive(ctx, provider) && hasTrustedVisionHint(ctx, provider, model))
   )
 
@@ -258,17 +265,23 @@ export function installVisionModelRegistry(ctx, liveDiscovery, options = {}) {
   liveDiscovery.hasModel = wrappedHasModel
   liveDiscovery.evidenceSource = wrappedEvidenceSource
 
+  const restore = () => {
+    if (liveDiscovery.snapshot === wrappedSnapshot) liveDiscovery.snapshot = originalSnapshot
+    if (liveDiscovery.hasModel === wrappedHasModel) {
+      if (originalHasModel === undefined) delete liveDiscovery.hasModel
+      else liveDiscovery.hasModel = originalHasModel
+    }
+    if (liveDiscovery.evidenceSource === wrappedEvidenceSource) {
+      if (originalEvidenceSource === undefined) delete liveDiscovery.evidenceSource
+      else liveDiscovery.evidenceSource = originalEvidenceSource
+    }
+  }
   try {
-    ctx?.effect?.(() => () => {
-      if (liveDiscovery.snapshot === wrappedSnapshot) liveDiscovery.snapshot = originalSnapshot
-      if (liveDiscovery.hasModel === wrappedHasModel) liveDiscovery.hasModel = originalHasModel
-      if (liveDiscovery.evidenceSource === wrappedEvidenceSource) {
-        if (originalEvidenceSource === undefined) delete liveDiscovery.evidenceSource
-        else liveDiscovery.evidenceSource = originalEvidenceSource
-      }
-    }, 'vision-router: private model registry sources')
+    ctx?.effect?.(() => restore, 'vision-router: private model registry sources')
   } catch {
-    // The manager itself is disposed with the plugin; restoration is hygiene.
+    // The manager can outlive this failed composition attempt. Do not leave
+    // generation-specific method projections installed without an owner.
+    restore()
   }
   return liveDiscovery
 }

package/lib/vision-provider-transport.js

@@ -1,77 +1,76 @@
-import {
-  ERROR_RESPONSE_MAX_BYTES,
-  MODEL_RESPONSE_MAX_BYTES,
-  readResponseJsonBounded,
-  readResponseTextBounded,
-} from './http-body-limit.js'
-import { effectiveProxyUrlForUndici } from './proxy-url-compat.js'
-import { createProxyDispatcherPool } from './proxy-dispatcher-pool.js'
-import {
-  createPerHopProxyDispatcher,
-  proxyDispatcherLike,
-  proxyHostMatchesAny,
-  visionProxyOverrideConfigured,
-} from './proxy-routing.js'
-
+import { ERROR_RESPONSE_MAX_BYTES, MODEL_RESPONSE_MAX_BYTES, readResponseJsonBounded, readResponseTextBounded, } from './http-body-limit.js';
+import { effectiveProxyUrlForUndici } from './proxy-url-compat.js';
+import { createProxyDispatcherPool } from './proxy-dispatcher-pool.js';
+import { createPerHopProxyDispatcher, proxyDispatcherLike, proxyHostMatchesAny, visionProxyOverrideConfigured, } from './proxy-routing.js';
 const DEFAULT_PROXY_HOSTS = Object.freeze([
-  'api.openrouter.ai',
-  'openrouter.ai',
-  'api.openai.com',
-  'api.anthropic.com',
-  'api.groq.com',
-  'api.mistral.ai',
-  'api.together.xyz',
-  'generativelanguage.googleapis.com',
-  'api.x.ai',
-])
-
-// Capture before core.apply installs the legacy process-wide fetch patch. The
-// Router-owned transport uses this original function explicitly, so direct
-// provider calls are not coupled to later globalThis.fetch mutation.
-const moduleFetch =
-  typeof globalThis.fetch === 'function'
+    'api.openrouter.ai',
+    'openrouter.ai',
+    'api.openai.com',
+    'api.anthropic.com',
+    'api.groq.com',
+    'api.mistral.ai',
+    'api.together.xyz',
+    'generativelanguage.googleapis.com',
+    'api.x.ai',
+]);
+const capturedHostFetch = typeof globalThis.fetch === 'function'
     ? globalThis.fetch.bind(globalThis)
-    : undefined
-
+    : undefined;
+const moduleFetch = capturedHostFetch
+    ? (input, init) => capturedHostFetch(input, init)
+    : undefined;
+function objectRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
 function live(value) {
-  return typeof value === 'function' ? value() : value
+    return typeof value === 'function' ? value() : value;
 }
-
 function asObject(value) {
-  return value && typeof value === 'object' && !Array.isArray(value) ? value : {}
+    return objectRecord(value) ?? {};
 }
-
 function asUrl(input) {
-  try {
-    return input instanceof URL ? input : new URL(typeof input === 'string' ? input : input?.url)
-  } catch {
-    return undefined
-  }
+    try {
+        if (input instanceof URL)
+            return input;
+        if (typeof input === 'string')
+            return new URL(input);
+        const raw = objectRecord(input)?.url;
+        return typeof raw === 'string' ? new URL(raw) : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
-
 function proxySettings(config) {
-  const value = asObject(live(config))
-  const proxy = visionProxyOverrideConfigured(value) ? value.proxy.trim() : undefined
-  const proxyHosts = Array.isArray(value.proxyHosts)
-    ? value.proxyHosts.filter((host) => typeof host === 'string' && host.trim() !== '').map((host) => host.trim())
-    : [...DEFAULT_PROXY_HOSTS]
-  return { proxy, proxyHosts }
+    const value = asObject(live(config));
+    const rawProxy = value.proxy;
+    const proxy = visionProxyOverrideConfigured(value) && typeof rawProxy === 'string'
+        ? rawProxy.trim()
+        : undefined;
+    const proxyHosts = Array.isArray(value.proxyHosts)
+        ? value.proxyHosts
+            .filter((host) => typeof host === 'string' && host.trim() !== '')
+            .map((host) => host.trim())
+        : [...DEFAULT_PROXY_HOSTS];
+    return { proxy, proxyHosts };
 }
-
 function credentialService(ctx) {
-  try {
-    return ctx?.get?.('credentials')
-  } catch {
-    return undefined
-  }
+    try {
+        const service = ctx?.get?.('credentials');
+        return service !== null && (typeof service === 'object' || typeof service === 'function')
+            ? service
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
-
 function envCredential(ref) {
-  if (typeof process === 'undefined' || !process.env) return undefined
-  const value = process.env[ref]
-  return typeof value === 'string' && value !== '' ? value : undefined
+    const value = process.env[ref];
+    return typeof value === 'string' && value !== '' ? value : undefined;
 }
-
 /**
  * Router-owned provider transport.
  *
@@ -82,94 +81,85 @@ function envCredential(ref) {
  * policy remains authoritative. It intentionally does not cover update checks,
  * GitHub/npm maintenance traffic or Host-owned LLM adapter requests.
  */
-export function createVisionProviderTransport({
-  ctx,
-  config = {},
-  fetchImpl = moduleFetch,
-  importUndici = () => import('undici'),
-} = {}) {
-  if (typeof fetchImpl !== 'function') {
-    throw new TypeError('vision provider transport requires fetch')
-  }
-
-  let disposed = false
-  let disposePromise
-  const dispatcherPool = createProxyDispatcherPool({
-    importUndici,
-    label: 'vision provider transport',
-  })
-
-  const fetchProvider = async (input, init = {}, context = {}) => {
-    if (disposed) return fetchImpl(input, init)
-    const url = asUrl(input)
-    const { proxy, proxyHosts } = proxySettings(config)
-    const effectiveProxyUrl = proxy ? effectiveProxyUrlForUndici(proxy) : undefined
-    dispatcherPool.reconcile(effectiveProxyUrl)
-    if (!url || !effectiveProxyUrl || context.allowProxy === false || !proxyHostMatchesAny(url.hostname, proxyHosts)) {
-      return fetchImpl(input, init)
-    }
-    const lease = await dispatcherPool.acquire(effectiveProxyUrl)
-    try {
-      const fallbackDispatcher = proxyDispatcherLike(init?.dispatcher)
-        ? init.dispatcher
-        : lease.getGlobalDispatcher()
-      const dispatcher = createPerHopProxyDispatcher(lease.dispatcher, fallbackDispatcher, proxyHosts)
-      return await fetchImpl(input, { ...init, dispatcher })
-    } finally {
-      lease.release()
+export function createVisionProviderTransport({ ctx, config = {}, fetchImpl = moduleFetch, importUndici = () => import('undici'), } = {}) {
+    if (typeof fetchImpl !== 'function') {
+        throw new TypeError('vision provider transport requires fetch');
     }
-  }
-
-  const dispose = () => {
-    if (disposePromise) return disposePromise
-    disposed = true
-    disposePromise = dispatcherPool.dispose()
-    return disposePromise
-  }
-
-  return Object.freeze({
-    fetch: fetchProvider,
-    dispose,
-
-    async resolveCredential(ref) {
-      const name = typeof ref === 'string' ? ref.trim() : ''
-      if (!name) return undefined
-      const credentials = credentialService(ctx)
-      if (credentials && typeof credentials.resolve === 'function') {
+    let disposed = false;
+    let disposePromise;
+    const dispatcherPool = createProxyDispatcherPool({
+        importUndici,
+        label: 'vision provider transport',
+    });
+    const fetchProvider = async (input, init = {}, context = {}) => {
+        if (disposed)
+            return fetchImpl(input, init);
+        const url = asUrl(input);
+        const { proxy, proxyHosts } = proxySettings(config);
+        const effectiveProxyUrl = proxy ? effectiveProxyUrlForUndici(proxy) : undefined;
+        dispatcherPool.reconcile(effectiveProxyUrl);
+        if (!url
+            || !effectiveProxyUrl
+            || context.allowProxy === false
+            || !proxyHostMatchesAny(url.hostname, proxyHosts)) {
+            return fetchImpl(input, init);
+        }
+        const lease = await dispatcherPool.acquire(effectiveProxyUrl);
         try {
-          const hit = await credentials.resolve(name)
-          if (hit && typeof hit.value === 'string' && hit.value !== '') return hit.value
-        } catch {
-          // Environment remains the compatibility fallback.
+            const fallbackDispatcher = proxyDispatcherLike(init.dispatcher)
+                ? init.dispatcher
+                : lease.getGlobalDispatcher();
+            const dispatcher = createPerHopProxyDispatcher(lease.dispatcher, fallbackDispatcher, proxyHosts);
+            return await fetchImpl(input, { ...init, dispatcher });
+        }
+        finally {
+            lease.release();
         }
-      }
-      return envCredential(name)
-    },
-
-    readErrorText(response, options = {}) {
-      return readResponseTextBounded(
-        response,
-        options.maxBytes ?? ERROR_RESPONSE_MAX_BYTES,
-        { label: options.label ?? 'vision provider error response' },
-      )
-    },
-
-    readModelJson(response, options = {}) {
-      return readResponseJsonBounded(
-        response,
-        options.maxBytes ?? MODEL_RESPONSE_MAX_BYTES,
-        { label: options.label ?? 'vision provider response' },
-      )
-    },
-
-    proxyDecision(input) {
-      const url = asUrl(input)
-      const { proxy, proxyHosts } = proxySettings(config)
-      return Object.freeze({
-        proxied: Boolean(url && proxy && proxyHostMatchesAny(url.hostname, proxyHosts)),
-        proxy,
-        hostname: url?.hostname,
-      })
-    },
-  })
+    };
+    const dispose = () => {
+        if (disposePromise)
+            return disposePromise;
+        disposed = true;
+        disposePromise = dispatcherPool.dispose();
+        return disposePromise;
+    };
+    return Object.freeze({
+        fetch: fetchProvider,
+        dispose,
+        async resolveCredential(ref) {
+            const name = typeof ref === 'string' ? ref.trim() : '';
+            if (!name)
+                return undefined;
+            const credentials = credentialService(ctx);
+            try {
+                const resolve = credentials?.resolve;
+                if (typeof resolve === 'function') {
+                    const hit = await Reflect.apply(resolve, credentials, [name]);
+                    const value = objectRecord(hit)?.value;
+                    if (typeof value === 'string' && value !== '')
+                        return value;
+                }
+            }
+            catch {
+                // A missing/partial/throwing Host credential service must not suppress
+                // the supported environment-variable compatibility fallback.
+            }
+            return envCredential(name);
+        },
+        readErrorText(response, options = {}) {
+            return readResponseTextBounded(response, options.maxBytes ?? ERROR_RESPONSE_MAX_BYTES, { label: options.label ?? 'vision provider error response' });
+        },
+        readModelJson(response, options = {}) {
+            return readResponseJsonBounded(response, options.maxBytes ?? MODEL_RESPONSE_MAX_BYTES, { label: options.label ?? 'vision provider response' });
+        },
+        proxyDecision(input) {
+            const url = asUrl(input);
+            const { proxy, proxyHosts } = proxySettings(config);
+            return Object.freeze({
+                proxied: Boolean(url && proxy && proxyHostMatchesAny(url.hostname, proxyHosts)),
+                proxy,
+                hostname: url?.hostname,
+            });
+        },
+    });
 }

package/lib/vision-routing-authority.js

@@ -1,46 +1,42 @@
-import { normalizeVisionRoutingMode } from './vision-routing-product.js'
-
-export const BACKGROUND_MEASUREMENT_MODES = Object.freeze(['off', 'local-free', 'all'])
-
-const BACKGROUND_MEASUREMENT_SET = new Set(BACKGROUND_MEASUREMENT_MODES)
-const MANUAL_MEASUREMENT_GRANT = Symbol('vision-router-manual-measurement-grant')
-
+import { normalizeVisionRoutingMode, } from './vision-routing-product.js';
+export const BACKGROUND_MEASUREMENT_MODES = Object.freeze(['off', 'local-free', 'all']);
+const BACKGROUND_MEASUREMENT_SET = new Set(BACKGROUND_MEASUREMENT_MODES);
+const MANUAL_MEASUREMENT_GRANT = Symbol('vision-router-manual-measurement-grant');
 function plainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
-
 export function normalizeBackgroundMeasurementAuthority(value, fallback = 'off') {
-  const normalizedFallback = BACKGROUND_MEASUREMENT_SET.has(fallback) ? fallback : 'off'
-  return typeof value === 'string' && BACKGROUND_MEASUREMENT_SET.has(value.trim())
-    ? value.trim()
-    : normalizedFallback
+    const normalizedFallback = typeof fallback === 'string' && BACKGROUND_MEASUREMENT_SET.has(fallback)
+        ? fallback
+        : 'off';
+    const candidate = typeof value === 'string' ? value.trim() : '';
+    return BACKGROUND_MEASUREMENT_SET.has(candidate)
+        ? candidate
+        : normalizedFallback;
 }
-
 /**
  * Resolve only user-delegated v2 authority. Evidence, preference, credentials,
  * capability gaps, or internal shadow switches must never widen this result.
  */
 export function resolveVisionRoutingAuthority(config = {}) {
-  const source = plainObject(config) ? config : {}
-  const execution = normalizeVisionRoutingMode(source.routingMode)
-  const backgroundMeasurement = normalizeBackgroundMeasurementAuthority(source.backgroundBenchmarking)
-  const autoSelectionAuthorized = execution === 'auto'
-  const backgroundMeasurementAuthorized = backgroundMeasurement !== 'off'
-
-  return Object.freeze({
-    execution,
-    autoSelectionAuthorized,
-    backgroundMeasurement,
-    backgroundMeasurementAuthorized,
-    // Current background profiler is useful only for Auto preparation, but the
-    // standing measurement grant remains independent from execution authority.
-    backgroundMeasurementActive: autoSelectionAuthorized && backgroundMeasurementAuthorized,
-    ephemeralRuntimeObservation: autoSelectionAuthorized,
-    // No v2 setting currently grants durable user-specific behavioral learning.
-    persistentLearning: false,
-  })
+    const source = plainObject(config) ? config : {};
+    const execution = normalizeVisionRoutingMode(source.routingMode);
+    const backgroundMeasurement = normalizeBackgroundMeasurementAuthority(source.backgroundBenchmarking);
+    const autoSelectionAuthorized = execution === 'auto';
+    const backgroundMeasurementAuthorized = backgroundMeasurement !== 'off';
+    return Object.freeze({
+        execution,
+        autoSelectionAuthorized,
+        backgroundMeasurement,
+        backgroundMeasurementAuthorized,
+        // Current background profiler is useful only for Auto preparation, but the
+        // standing measurement grant remains independent from execution authority.
+        backgroundMeasurementActive: autoSelectionAuthorized && backgroundMeasurementAuthorized,
+        ephemeralRuntimeObservation: autoSelectionAuthorized,
+        // No v2 setting currently grants durable user-specific behavioral learning.
+        persistentLearning: false,
+    });
 }
-
 /**
  * A manual measurement grant is intentionally opaque and process-local. The
  * local HTTP action creates one only after an explicit user POST. Requiring the
@@ -48,23 +44,26 @@ export function resolveVisionRoutingAuthority(config = {}) {
  * inheriting "manual" semantics by convention.
  */
 export function grantManualMeasurementFromUserAction(source = 'local-ui') {
-  if (source !== 'local-ui') {
-    throw new TypeError('manual measurement authority source must be local-ui')
-  }
-  return Object.freeze({
-    kind: 'manual-measurement',
-    source,
-    [MANUAL_MEASUREMENT_GRANT]: true,
-  })
+    if (source !== 'local-ui') {
+        throw new TypeError('manual measurement authority source must be local-ui');
+    }
+    const grant = {
+        kind: 'manual-measurement',
+        source,
+        [MANUAL_MEASUREMENT_GRANT]: true,
+    };
+    return Object.freeze(grant);
 }
-
 export function hasManualMeasurementAuthority(value) {
-  return !!value && value[MANUAL_MEASUREMENT_GRANT] === true && value.kind === 'manual-measurement'
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return candidate[MANUAL_MEASUREMENT_GRANT] === true && candidate.kind === 'manual-measurement';
 }
-
 export function assertManualMeasurementAuthority(value) {
-  if (hasManualMeasurementAuthority(value)) return value
-  const error = new Error('explicit manual measurement authority is required')
-  error.code = 'CAPABILITY_BENCHMARK_AUTHORITY_REQUIRED'
-  throw error
+    if (hasManualMeasurementAuthority(value))
+        return value;
+    const error = new Error('explicit manual measurement authority is required');
+    error.code = 'CAPABILITY_BENCHMARK_AUTHORITY_REQUIRED';
+    throw error;
 }