dsh-vision-router 2.3.0 → 3.0.0

package/lib/vision-capability-evidence.js

@@ -0,0 +1,35 @@
+export const VISION_INTENTS = [
+    'structured',
+    'ocr',
+    'document',
+    'ui',
+    'grounding',
+    'detection',
+    'general',
+    'chart_diagram',
+    'code_screenshot',
+    'visual_compare',
+];
+export const BENCHMARK_AXES = [
+    'structured',
+    'ocr',
+    'document',
+    'grounding',
+    'general',
+];
+const DIRECT_TASK_AXIS = Object.freeze({
+    structured: 'structured',
+    ocr: 'ocr',
+    document: 'document',
+    grounding: 'grounding',
+    general: 'general',
+});
+export function normalizeVisionIntent(intent) {
+    return typeof intent === 'string'
+        && VISION_INTENTS.includes(intent)
+        ? intent
+        : 'general';
+}
+export function benchmarkAxisForVisionIntent(intent) {
+    return DIRECT_TASK_AXIS[normalizeVisionIntent(intent)];
+}

package/lib/vision-capability-fingerprint.js

@@ -0,0 +1,72 @@
+import { createHash } from 'node:crypto';
+import process from 'node:process';
+export const CAPABILITY_BENCHMARK_SUITE_REVISION = 5;
+// Renderer-only fixes must invalidate prior evidence even when the scoring and
+// prompt contract (the suite revision) is unchanged.
+export const CAPABILITY_BENCHMARK_RENDERER_SCOPE = `${process.platform}/${process.arch}-proof-badge-v2`;
+function isSensitiveKey(key) {
+    return /(^|[_-])(api[_-]?key|key|token|secret|password|authorization|auth|signature|sig)([_-]|$)/i
+        .test(String(key ?? ''));
+}
+function normalizeEndpoint(value) {
+    const raw = String(value ?? '').trim();
+    if (raw === '')
+        return '';
+    try {
+        const url = new URL(raw);
+        url.username = '';
+        url.password = '';
+        url.hash = '';
+        for (const key of [...url.searchParams.keys()]) {
+            if (isSensitiveKey(key))
+                url.searchParams.delete(key);
+        }
+        url.searchParams.sort();
+        const pathname = url.pathname === '/' ? '' : url.pathname.replace(/\/+$/, '');
+        return `${url.protocol.toLowerCase()}//${url.host.toLowerCase()}${pathname}${url.search}`;
+    }
+    catch {
+        return raw.replace(/\/+$/, '');
+    }
+}
+function sanitizeFingerprintValue(value, keyHint = '') {
+    if (value === null || value === undefined)
+        return value ?? null;
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeFingerprintValue(item));
+    }
+    if (typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([key]) => !isSensitiveKey(key))
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, child]) => [
+            key,
+            sanitizeFingerprintValue(child, key),
+        ]));
+    }
+    if (typeof value === 'string'
+        && /(endpoint|base[_-]?url|url)$/i.test(keyHint)) {
+        return normalizeEndpoint(value);
+    }
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (typeof value === 'number'
+        || typeof value === 'boolean'
+        || typeof value === 'string') {
+        return value;
+    }
+    return String(value);
+}
+export function capabilityBenchmarkFingerprint({ provider, model, endpoint, config, credentialFingerprint, } = {}) {
+    const payload = JSON.stringify({
+        schema: 'vision-capability-endpoint-v2',
+        suiteRevision: CAPABILITY_BENCHMARK_SUITE_REVISION,
+        rendererScope: CAPABILITY_BENCHMARK_RENDERER_SCOPE,
+        provider: String(provider ?? '').trim(),
+        model: String(model ?? '').trim(),
+        endpoint: normalizeEndpoint(endpoint),
+        config: sanitizeFingerprintValue(config && typeof config === 'object' ? config : null),
+        credentialFingerprint: String(credentialFingerprint ?? 'none'),
+    });
+    return `ep2_${createHash('sha256').update(payload).digest('hex').slice(0, 32)}`;
+}

package/lib/vision-capability-identity.js

@@ -1,73 +1,128 @@
-import { createHash } from 'node:crypto'
-import { capabilityBenchmarkFingerprint } from './vision-capability-benchmark.js'
-
+import { createHash } from 'node:crypto';
+import { capabilityBenchmarkFingerprint } from './vision-capability-fingerprint.js';
+function propertyBag(value) {
+    return value !== null && (typeof value === 'object' || typeof value === 'function')
+        ? value
+        : undefined;
+}
 function nonEmpty(value) {
-  return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function contextGetter(ctx) {
+    const get = propertyBag(ctx)?.get;
+    return typeof get === 'function'
+        ? (name) => get.call(ctx, name)
+        : undefined;
+}
+function credentialValue(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
 }
-
 export function visionCredentialFingerprint(value) {
-  const text = typeof value === 'string' ? value : ''
-  if (text === '') return 'none'
-  return `cred_${createHash('sha256').update(text).digest('hex').slice(0, 24)}`
+    const text = typeof value === 'string' ? value : '';
+    if (text === '')
+        return 'none';
+    return `cred_${createHash('sha256').update(text).digest('hex').slice(0, 24)}`;
 }
-
-// Capability identity deliberately excludes credential identity. Credentials
-// decide whether a route can be accessed right now; they do not define what
-// the same model deployment is capable of. Deployment/project identity must
-// be represented explicitly in endpoint/config when it actually changes the
-// served model, rather than inferred from secret material.
-export function capabilityEvidenceFingerprint({
-  provider,
-  model,
-  endpoint,
-  config,
-} = {}) {
-  return capabilityBenchmarkFingerprint({ provider, model, endpoint, config })
+/**
+ * Capability identity deliberately excludes credential identity.
+ *
+ * Credentials decide whether a route can be accessed right now; they do not
+ * define what the same model deployment is capable of. Deployment/project
+ * identity belongs in endpoint/config when it actually changes the served
+ * model, never in secret material.
+ */
+export function capabilityEvidenceFingerprint({ provider, model, endpoint, config, } = {}) {
+    return capabilityBenchmarkFingerprint({ provider, model, endpoint, config });
 }
-
 export async function resolveVisionCredential(ctx, ref) {
-  const key = nonEmpty(ref)
-  if (key === undefined) return { required: false, value: undefined, fingerprint: 'none', source: 'none' }
-
-  let credentials
-  try { credentials = ctx?.get?.('credentials') } catch { credentials = undefined }
-  if (credentials !== undefined) {
+    const key = nonEmpty(ref);
+    if (key === undefined) {
+        return {
+            required: false,
+            value: undefined,
+            fingerprint: 'none',
+            source: 'none',
+        };
+    }
+    let credentials;
     try {
-      const hit = await credentials?.resolve?.(key)
-      const value = hit && typeof hit.value === 'string' && hit.value !== '' ? hit.value : undefined
-      return {
-        required: true,
-        value,
-        fingerprint: value === undefined ? 'unresolved' : visionCredentialFingerprint(value),
-        source: value === undefined ? 'credentials-miss' : 'credentials',
-      }
-    } catch {
-      return { required: true, value: undefined, fingerprint: 'unresolved', source: 'credentials-error' }
+        credentials = contextGetter(ctx)?.('credentials');
+    }
+    catch {
+        credentials = undefined;
+    }
+    if (credentials !== undefined) {
+        try {
+            const resolve = propertyBag(credentials)?.resolve;
+            const hit = typeof resolve === 'function'
+                ? await resolve.call(credentials, key)
+                : undefined;
+            const value = credentialValue(propertyBag(hit)?.value);
+            return {
+                required: true,
+                value,
+                fingerprint: value === undefined
+                    ? 'unresolved'
+                    : visionCredentialFingerprint(value),
+                source: value === undefined ? 'credentials-miss' : 'credentials',
+            };
+        }
+        catch {
+            return {
+                required: true,
+                value: undefined,
+                fingerprint: 'unresolved',
+                source: 'credentials-error',
+            };
+        }
+    }
+    let launchEnvironment;
+    try {
+        launchEnvironment = contextGetter(ctx)?.('launchEnvironment');
+    }
+    catch {
+        return {
+            required: true,
+            value: undefined,
+            fingerprint: 'unresolved',
+            source: 'launch-environment-error',
+        };
     }
-  }
-
-  try {
-    const launchEnvironment = ctx?.get?.('launchEnvironment')
     if (launchEnvironment !== undefined) {
-      const hit = launchEnvironment?.get?.(key)
-      const value = hit && typeof hit.value === 'string' && hit.value !== '' ? hit.value : undefined
-      return {
+        try {
+            const get = propertyBag(launchEnvironment)?.get;
+            const hit = typeof get === 'function'
+                ? get.call(launchEnvironment, key)
+                : undefined;
+            const value = credentialValue(propertyBag(hit)?.value);
+            return {
+                required: true,
+                value,
+                fingerprint: value === undefined
+                    ? 'unresolved'
+                    : visionCredentialFingerprint(value),
+                source: value === undefined
+                    ? 'launch-environment-miss'
+                    : 'launch-environment',
+            };
+        }
+        catch {
+            return {
+                required: true,
+                value: undefined,
+                fingerprint: 'unresolved',
+                source: 'launch-environment-error',
+            };
+        }
+    }
+    const ambient = process.env[key];
+    const value = typeof ambient === 'string' && ambient !== '' ? ambient : undefined;
+    return {
         required: true,
         value,
-        fingerprint: value === undefined ? 'unresolved' : visionCredentialFingerprint(value),
-        source: value === undefined ? 'launch-environment-miss' : 'launch-environment',
-      }
-    }
-  } catch {
-    return { required: true, value: undefined, fingerprint: 'unresolved', source: 'launch-environment-error' }
-  }
-
-  const ambient = process.env[key]
-  const value = typeof ambient === 'string' && ambient !== '' ? ambient : undefined
-  return {
-    required: true,
-    value,
-    fingerprint: value === undefined ? 'unresolved' : visionCredentialFingerprint(value),
-    source: value === undefined ? 'ambient-miss' : 'ambient',
-  }
+        fingerprint: value === undefined
+            ? 'unresolved'
+            : visionCredentialFingerprint(value),
+        source: value === undefined ? 'ambient-miss' : 'ambient',
+    };
 }

package/lib/vision-capability-router.js

@@ -5,26 +5,18 @@
 // health only gates temporary availability. Model names/families never create
 // capability scores and unmeasured tasks never reorder the user's chain.
 
-export const VISION_INTENTS = Object.freeze([
-  'structured',
-  'ocr',
-  'document',
-  'ui',
-  'grounding',
-  'detection',
-  'general',
-  'chart_diagram',
-  'code_screenshot',
-  'visual_compare',
-])
-
-export const BENCHMARK_AXES = Object.freeze([
-  'structured',
-  'ocr',
-  'document',
-  'grounding',
-  'general',
-])
+import {
+  BENCHMARK_AXES,
+  VISION_INTENTS,
+  benchmarkAxisForVisionIntent,
+  normalizeVisionIntent,
+} from './vision-capability-evidence.js'
+
+export {
+  BENCHMARK_AXES,
+  VISION_INTENTS,
+  benchmarkAxisForVisionIntent,
+} from './vision-capability-evidence.js'
 
 // Internal compatibility vocabulary. `privacy` is the historical scorer name
 // for the user-facing `local` preference; unlike the old implementation it is
@@ -33,14 +25,6 @@ export const VISION_STRATEGIES = Object.freeze(['quality', 'balanced', 'speed',
 
 export const AUTO_REORDER_MIN_ADVANTAGE = 0.08
 
-const DIRECT_TASK_AXIS = Object.freeze({
-  structured: 'structured',
-  ocr: 'ocr',
-  document: 'document',
-  grounding: 'grounding',
-  general: 'general',
-})
-
 const BOOTSTRAP_VISUAL_INTENT = Object.freeze({
   chat: 'ui',
   document: 'document',
@@ -60,7 +44,7 @@ function clamp01(value, fallback = 0) {
 }
 
 function normalizedIntent(intent) {
-  return VISION_INTENTS.includes(intent) ? intent : 'general'
+  return normalizeVisionIntent(intent)
 }
 
 function normalizedStrategy(strategy) {
@@ -72,10 +56,6 @@ function cleanEnum(value, allowed) {
   return allowed.has(text) ? text : 'unknown'
 }
 
-export function benchmarkAxisForVisionIntent(intent) {
-  return DIRECT_TASK_AXIS[normalizedIntent(intent)]
-}
-
 export function inferBootstrapVisionIntents(bootstrap = {}) {
   const source = bootstrap && typeof bootstrap === 'object' && !Array.isArray(bootstrap) ? bootstrap : {}
   const visualKind = cleanEnum(source.visual_kind, BOOTSTRAP_VISUAL_KINDS)

package/lib/vision-chunk-assembler.js

@@ -0,0 +1,95 @@
+function propertyBag(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : undefined;
+}
+function failureMessage(failure) {
+    const message = propertyBag(failure)?.message;
+    return message ? String(message) : String(failure);
+}
+/**
+ * Minimal DVR text assembler over the public DSH StreamChunk contract.
+ *
+ * Current DSH failures arrive inside the terminal finish reason. The two
+ * standalone terminal shapes remain explicit compatibility input for released
+ * historical/partial adapters. Runtime shape checks stay in place because JS
+ * callers may still provide malformed chunks.
+ */
+export function createChunkAssembler() {
+    const parts = new Map();
+    const order = [];
+    let finishKind;
+    let failure;
+    const pushUnknown = (value) => {
+        const chunk = propertyBag(value);
+        if (chunk === undefined || typeof chunk.type !== 'string')
+            return;
+        switch (chunk.type) {
+            case 'block-start': {
+                if (!parts.has(chunk.index)) {
+                    order.push(chunk.index);
+                    parts.set(chunk.index, { type: chunk.blockType, text: '' });
+                }
+                break;
+            }
+            case 'text-delta': {
+                const part = parts.get(chunk.index);
+                if (part !== undefined)
+                    part.text += (chunk.text ?? '');
+                break;
+            }
+            case 'reasoning-delta':
+            case 'tool-call-delta':
+            case 'usage':
+                break;
+            case 'block-end': {
+                const part = parts.get(chunk.index);
+                const block = propertyBag(chunk.block);
+                if (part !== undefined && typeof block?.text === 'string') {
+                    part.text = block.text;
+                }
+                break;
+            }
+            case 'finish': {
+                const reason = propertyBag(chunk.reason);
+                if (reason !== undefined
+                    && (reason.kind === 'error' || reason.kind === 'aborted')) {
+                    failure = reason.failure;
+                }
+                finishKind =
+                    reason !== undefined && reason.kind
+                        ? String(reason.kind)
+                        : 'stop';
+                break;
+            }
+            case 'error':
+            case 'aborted':
+                failure = chunk.failure;
+                break;
+            default:
+                break;
+        }
+    };
+    return {
+        push(chunk) {
+            pushUnknown(chunk);
+        },
+        finish() {
+            if (failure)
+                throw new Error(failureMessage(failure));
+            if (finishKind !== undefined
+                && finishKind !== 'stop'
+                && finishKind !== 'max-tokens') {
+                throw new Error(`vision call finished with "${finishKind}"`);
+            }
+            return order
+                .map((index) => parts.get(index))
+                .filter((part) => part !== undefined && part.type === 'text')
+                .map((part) => part.text)
+                .join('')
+                .trim();
+        },
+    };
+}
+const _officialFailureAuthority = undefined;
+void _officialFailureAuthority;

package/lib/vision-diagnostics-routes.js

@@ -1,9 +1,18 @@
+import {
+  currentLegacyGlobalProxyFetch,
+  legacyGlobalProxyPairFor,
+  runWithLegacyGlobalProxyScope,
+} from './legacy-global-proxy-boundary.js'
 import { probeLocalBackends } from './local-connection-probe.js'
 import {
   METADATA_RESPONSE_MAX_BYTES,
   readResponseJsonBounded,
 } from './http-body-limit.js'
 
+const moduleFetch = typeof globalThis.fetch === 'function'
+  ? globalThis.fetch.bind(globalThis)
+  : undefined
+
 export const VISION_TEST_CONNECTION_PATH = '/_dsh/vision-router/test-connection'
 export const VISION_MODEL_CAPABILITIES_PATH = '/_dsh/vision-router/model-capabilities'
 
@@ -92,7 +101,28 @@ export function installVisionDiagnosticsRoutes(ctx, options = {}) {
   const httpRoute = typeof connection.httpRoute === 'string' && connection.httpRoute !== ''
     ? connection.httpRoute
     : 'vision-http'
-  const fetchImpl = typeof options.fetchImpl === 'function' ? options.fetchImpl : globalThis.fetch
+  // The proxy boundary installs its wrapper after apply(), so a capture taken here
+  // would make "test connection" report failures that real vision turns (which run
+  // inside the adapter's proxy scope) do not have. Use the fetch the boundary
+  // currently owns, with the module-load capture as the fallback.
+  const injectedFetch = typeof options.fetchImpl === 'function' ? options.fetchImpl : undefined
+  const resolveFetch = () => injectedFetch ?? currentLegacyGlobalProxyFetch() ?? moduleFetch
+  const connectionConfig = () => {
+    try {
+      const live = ctx?.get?.('settings')?.get?.('vision-router')
+      if (live !== null && typeof live === 'object' && !Array.isArray(live)) return live
+    } catch {
+      // No settings namespace on this Host: probes stay unscoped, as before.
+    }
+    return {}
+  }
+  const scopedProbe = (providerName, baseURL, expectedModel, startedAt) => {
+    const work = () => probeModels(resolveFetch(), baseURL, expectedModel, startedAt)
+    const pair = legacyGlobalProxyPairFor(connectionConfig(), providerName)
+    return pair === undefined
+      ? work()
+      : runWithLegacyGlobalProxyScope(pair.provider, pair.model, work)
+  }
 
   const probeConnection = async () => {
     const started = Date.now()
@@ -109,7 +139,7 @@ export function installVisionDiagnosticsRoutes(ctx, options = {}) {
 
     const localProbe = await probeLocalBackends(
       getArray(connection.localBackends),
-      (provider) => probeModels(fetchImpl, provider.baseURL, provider.model, started),
+      (provider) => scopedProbe(provider.name ?? provider.id, provider.baseURL, provider.model, started),
       started,
     )
     if (localProbe !== undefined) return localProbe
@@ -117,7 +147,7 @@ export function installVisionDiagnosticsRoutes(ctx, options = {}) {
     const httpBackends = getArray(connection.httpBackends)
     if (first !== undefined && first.provider === httpRoute) {
       const entry = httpBackends.find((provider) => `${provider.name}/${provider.model}` === first.model)
-      if (entry !== undefined) return probeModels(fetchImpl, entry.baseURL, entry.model, started)
+      if (entry !== undefined) return scopedProbe(entry.name, entry.baseURL, entry.model, started)
     }
 
     if (first !== undefined) {
@@ -138,7 +168,7 @@ export function installVisionDiagnosticsRoutes(ctx, options = {}) {
     }
 
     const httpFirst = httpBackends[0]
-    if (httpFirst !== undefined) return probeModels(fetchImpl, httpFirst.baseURL, httpFirst.model, started)
+    if (httpFirst !== undefined) return scopedProbe(httpFirst.provider ?? httpFirst.name ?? httpRoute, httpFirst.baseURL, httpFirst.model, started)
     return { ok: false, error: 'no usable vision provider configured' }
   }
 

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;
 }