dsh-vision-router 2.2.8 → 3.0.0

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

@@ -0,0 +1,246 @@
+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'
+
+function adapterAvailable(llm, provider) {
+  if (!llm || typeof llm.registration !== 'function') return false
+  try {
+    llm.registration(provider)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function probeModels(fetchImpl, baseURL, expectedModel, startedAt) {
+  try {
+    const response = await fetchImpl(`${String(baseURL).replace(/\/$/, '')}/models`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(8000),
+    })
+    const latencyMs = Date.now() - startedAt
+    if (!response.ok) {
+      return { ok: false, latencyMs, status: response.status, error: `HTTP ${response.status}` }
+    }
+    const data = await readResponseJsonBounded(
+      response,
+      METADATA_RESPONSE_MAX_BYTES,
+      { label: 'vision backend /models response' },
+    ).catch(() => undefined)
+    const models = data && Array.isArray(data.data) ? data.data : undefined
+    const count = models ? models.length : undefined
+    if (
+      typeof expectedModel === 'string' &&
+      expectedModel !== '' &&
+      models &&
+      !models.some((entry) => entry && String(entry.id) === expectedModel)
+    ) {
+      return {
+        ok: false,
+        latencyMs,
+        status: response.status,
+        models: count,
+        endpoint: baseURL,
+        error: `configured model "${expectedModel}" was not returned by /models`,
+      }
+    }
+    return { ok: true, latencyMs, status: response.status, models: count, endpoint: baseURL }
+  } catch (error) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - startedAt,
+      error: error && error.message ? error.message : String(error),
+    }
+  }
+}
+
+function getArray(factory) {
+  const value = typeof factory === 'function' ? factory() : factory
+  return Array.isArray(value) ? value : []
+}
+
+/**
+ * Product diagnostics/settings-support routes kept outside visual Core.
+ *
+ * The caller supplies three coherent domain faces instead of a Core facade:
+ * connection candidates/probes, capability snapshot production, and the
+ * Host-ownership state rendered in the connection response. Authentication
+ * and remote/local capability policy stay outside this module in the existing
+ * scoped WebServer boundary.
+ */
+export function installVisionDiagnosticsRoutes(ctx, options = {}) {
+  if (!ctx || typeof ctx.inject !== 'function') return ctx
+
+  const connection = options.connection ?? {}
+  const capabilities = options.capabilities ?? {}
+  const ownership = options.ownership ?? {}
+  const resolveCapability = connection.resolveCapability
+  const collectCapabilities = capabilities.collect
+  if (typeof resolveCapability !== 'function') {
+    throw new TypeError('vision diagnostics routes require a connection capability resolver')
+  }
+  if (typeof collectCapabilities !== 'function') {
+    throw new TypeError('vision diagnostics routes require a capability collector')
+  }
+
+  const llm = ctx.llm
+  const httpRoute = typeof connection.httpRoute === 'string' && connection.httpRoute !== ''
+    ? connection.httpRoute
+    : 'vision-http'
+  // 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()
+    let first
+    for (const pair of getArray(connection.candidatePairs)) {
+      if (!pair) continue
+      if (pair.provider !== httpRoute && !adapterAvailable(llm, pair.provider)) continue
+      const capability = await resolveCapability(pair.provider, pair.model)
+      if (capability?.attemptable !== false) {
+        first = pair
+        break
+      }
+    }
+
+    const localProbe = await probeLocalBackends(
+      getArray(connection.localBackends),
+      (provider) => scopedProbe(provider.name ?? provider.id, provider.baseURL, provider.model, started),
+      started,
+    )
+    if (localProbe !== undefined) return localProbe
+
+    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 scopedProbe(entry.name, entry.baseURL, entry.model, started)
+    }
+
+    if (first !== undefined) {
+      try {
+        await llm.resolveModelInfo(first.provider, first.model)
+        return {
+          ok: true,
+          latencyMs: Date.now() - started,
+          detail: `${first.provider}/${first.model} metadata resolved (no network call)`,
+        }
+      } catch (error) {
+        return {
+          ok: false,
+          latencyMs: Date.now() - started,
+          error: error && error.message ? error.message : String(error),
+        }
+      }
+    }
+
+    const httpFirst = httpBackends[0]
+    if (httpFirst !== undefined) return scopedProbe(httpFirst.provider ?? httpFirst.name ?? httpRoute, httpFirst.baseURL, httpFirst.model, started)
+    return { ok: false, error: 'no usable vision provider configured' }
+  }
+
+  ctx.inject(['webServer'], (webCtx) => {
+    webCtx.effect(() => {
+      return webCtx.webServer.register({
+        kind: 'exact',
+        path: VISION_TEST_CONNECTION_PATH,
+        handler: async (req, res) => {
+          if (req.method !== 'GET') {
+            res.setHeader('Allow', 'GET')
+            res.writeHead(405)
+            res.end()
+            return
+          }
+          try {
+            const result = await probeConnection()
+            const officialRouteAvailable = adapterAvailable(llm, 'deepseek-official')
+            result.stealth = {
+              configured: ownership.stealthConfigured,
+              active: false,
+              reason: ownership.hostOwnsOfficialDeepSeek && !officialRouteAvailable
+                ? 'host-owned-official-unavailable'
+                : undefined,
+              hostOwned: ownership.hostOwnsOfficialDeepSeek,
+            }
+            res.writeHead(result.ok ? 200 : 502, { 'content-type': 'application/json' })
+            res.end(JSON.stringify(result))
+          } catch (error) {
+            res.writeHead(500, { 'content-type': 'application/json' })
+            res.end(JSON.stringify({
+              ok: false,
+              error: error && error.message ? error.message : String(error),
+            }))
+          }
+        },
+      })
+    }, 'vision-router: test-connection route')
+  })
+
+  ctx.inject(['webServer'], (webCtx) => {
+    webCtx.effect(
+      () => webCtx.webServer.register({
+        kind: 'exact',
+        path: VISION_MODEL_CAPABILITIES_PATH,
+        handler: async (req, res) => {
+          if (req.method !== 'GET') {
+            res.setHeader('Allow', 'GET')
+            res.writeHead(405)
+            res.end()
+            return
+          }
+          try {
+            const snapshot = await collectCapabilities()
+            res.writeHead(200, { 'content-type': 'application/json' })
+            res.end(JSON.stringify({
+              capabilities: snapshot,
+              builtinFallback: getArray(capabilities.builtinFallback),
+              anonymousRpmPerModel: 2,
+            }))
+          } catch (error) {
+            res.writeHead(500, { 'content-type': 'application/json' })
+            res.end(JSON.stringify({
+              capabilities: {},
+              error: error && error.message ? error.message : String(error),
+            }))
+          }
+        },
+      }),
+      'vision-router: model capabilities route',
+    )
+  })
+
+  return ctx
+}

package/lib/vision-evidence-guidance.js

@@ -1,3 +1,5 @@
+import { visionRouterMessageSource } from './session-message-source-compat.js'
+
 export const VISION_SUCCESS_GUIDANCE =
   'Vision Router trusted execution metadata: the preceding vision_describe call SUCCEEDED. ' +
   'This metadata is not image content. If that successful evidence resolves the visual fact needed for the current task, stop making additional vision calls for that fact and continue the remaining user task from this evidence. ' +
@@ -34,6 +36,6 @@ export function visionDescribeSuccessContext(exec, result) {
     role: 'user',
     id: `vision-router-evidence-success-${String(exec.callId)}`,
     content: [{ type: 'text', text: VISION_SUCCESS_GUIDANCE }],
-    source: { kind: 'plugin', plugin: 'dsh-vision-router' },
+    source: visionRouterMessageSource(exec.agent.session),
   }
 }