dsh-vision-router 2.2.8 → 3.0.0

package/lib/vision-execution-order-apply.js

@@ -1,61 +1,51 @@
 function pairIdentity(pair) {
-  const provider = typeof pair?.provider === 'string' ? pair.provider.trim() : ''
-  const model = typeof pair?.model === 'string' ? pair.model.trim() : ''
-  return provider !== '' && model !== '' ? `${provider}\u0000${model}` : undefined
+    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() : '';
+    return provider !== '' && model !== '' ? `${provider}\u0000${model}` : undefined;
 }
-
-/**
- * Apply an explicit P1 execution order to a base pair list without changing
- * the base set of executable routes.
- *
- * This is intentionally a stable reorder, not replacement:
- * - a scoped pair not present in `basePairs` is ignored (cannot invent a route);
- * - every base pair omitted by the planner is appended in its original order
- *   (cannot delete configured/local/discovered fallback);
- * - duplicate base/scoped identities collapse to the first base occurrence;
- * - no scoped order means byte-for-shape legacy behavior: a detached copy of
- *   the base list in the same order.
- *
- * The caller remains responsible for constructing `basePairs` with its normal
- * adapter/HTTP/local availability rules. This helper owns ordering only.
- */
 export function applyVisionExecutionOrder(basePairs, scopedOrder) {
-  const base = Array.isArray(basePairs)
-    ? basePairs.filter((pair) => pairIdentity(pair) !== undefined)
-    : []
-  const baseById = new Map()
-  for (const pair of base) {
-    const id = pairIdentity(pair)
-    if (!baseById.has(id)) baseById.set(id, pair)
-  }
-
-  if (!Array.isArray(scopedOrder) || scopedOrder.length === 0) {
-    return [...baseById.values()]
-  }
-
-  const out = []
-  const seen = new Set()
-  const addBasePair = (pair) => {
-    const id = pairIdentity(pair)
-    if (id === undefined || seen.has(id)) return
-    seen.add(id)
-    out.push(pair)
-  }
-
-  for (const requested of scopedOrder) {
-    const id = pairIdentity(requested)
-    if (id === undefined) continue
-    const pair = baseById.get(id)
-    if (pair !== undefined) addBasePair(pair)
-  }
-  for (const pair of baseById.values()) addBasePair(pair)
-  return out
+    const base = Array.isArray(basePairs)
+        ? basePairs.filter((pair) => pairIdentity(pair) !== undefined)
+        : [];
+    const baseById = new Map();
+    for (const pair of base) {
+        const id = pairIdentity(pair);
+        if (id !== undefined && !baseById.has(id))
+            baseById.set(id, pair);
+    }
+    if (!Array.isArray(scopedOrder) || scopedOrder.length === 0) {
+        return [...baseById.values()];
+    }
+    const out = [];
+    const seen = new Set();
+    const addBasePair = (pair) => {
+        const id = pairIdentity(pair);
+        if (id === undefined || seen.has(id))
+            return;
+        seen.add(id);
+        out.push(pair);
+    };
+    for (const requested of scopedOrder) {
+        const id = pairIdentity(requested);
+        if (id === undefined)
+            continue;
+        const pair = baseById.get(id);
+        if (pair !== undefined)
+            addBasePair(pair);
+    }
+    for (const pair of baseById.values())
+        addBasePair(pair);
+    return out;
 }
-
 export function sameVisionPairOrder(left, right) {
-  if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false
-  for (let index = 0; index < left.length; index += 1) {
-    if (pairIdentity(left[index]) !== pairIdentity(right[index])) return false
-  }
-  return true
+    if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length)
+        return false;
+    for (let index = 0; index < left.length; index += 1) {
+        if (pairIdentity(left[index]) !== pairIdentity(right[index]))
+            return false;
+    }
+    return true;
 }

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,79 +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
-
-const installed = []
-
+    : 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.
  *
@@ -84,121 +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)
+export function createVisionProviderTransport({ ctx, config = {}, fetchImpl = moduleFetch, importUndici = () => import('undici'), } = {}) {
+    if (typeof fetchImpl !== 'function') {
+        throw new TypeError('vision provider transport requires fetch');
     }
-    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()
-    }
-  }
-
-  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 });
         }
-      }
-      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,
-      })
-    },
-  })
-}
-
-/**
- * Scoped process/profile carrier for Router-owned compatibility calls whose
- * mature signatures do not yet accept an explicit VisionProviderTransport.
- * The registry never patches global fetch and is released with the public
- * plugin lifecycle. Remove it only after every production compatibility caller
- * receives the transport explicitly and no production code reads
- * currentVisionProviderTransport().
- */
-export function installVisionProviderTransport(transport) {
-  if (!transport || typeof transport.fetch !== 'function') {
-    throw new TypeError('invalid vision provider transport')
-  }
-  const token = Object.freeze({ transport })
-  installed.push(token)
-  let active = true
-  return () => {
-    if (!active) return
-    active = false
-    const index = installed.indexOf(token)
-    if (index >= 0) installed.splice(index, 1)
-  }
-}
-
-export function currentVisionProviderTransport() {
-  return installed[installed.length - 1]?.transport
+        finally {
+            lease.release();
+        }
+    };
+    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,
+            });
+        },
+    });
 }