dsh-vision-router 2.1.0 → 2.1.2

package/docs/releases/v2.1.1.md

@@ -0,0 +1,19 @@
+# v2.1.1
+
+This is an urgent browser-startup hotfix for DVR 2.1.0.
+
+## Fixed
+
+- Fixes #367: DSH Web could fail while applying `dsh-vision-router` with `cannot get property "remote.session" without inject`.
+- The 2.1.0 client Host compatibility prelude no longer probes the optional `remote.session` namespace through the traceable `ctx.remote` proxy. It resolves the optional namespace through `ctx.get('remote.session')` first and keeps a guarded fallback for older/non-Cordis harnesses.
+- The new Host model-catalog bridge still uses `remote.session.modelCatalog()` when available, while older supported Hosts keep the original `connection.api.llm.models()` path and exact legacy Remote/Connection surfaces.
+
+## Regression coverage
+
+- Adds a production-shaped regression where reading `ctx.remote.session` throws the exact #367 Cordis error while `ctx.get('remote.session')` succeeds.
+- Adds the same test to the default Node 22/24 suite and the Web compatibility suite.
+- Keeps a fail-closed legacy-host regression so the hotfix does not turn the optional alpha namespace into a hard browser dependency.
+
+## Upgrade
+
+Users on 2.1.0 who hit the browser loader failure should upgrade to 2.1.1 and restart the DSH Web/Desktop process. No settings migration is required.

package/docs/releases/v2.1.2.md

@@ -0,0 +1,30 @@
+# v2.1.2
+
+DVR 2.1.2 is a reliability hotfix for image-session ownership, delegated vision routing, text-only attachment projection, and composer Vision-mode authority. It also closes CI blind spots that could allow valid regression tests to exist without being executed by the normal release gate.
+
+## Fixed
+
+- Keeps uploaded image blocks as durable Session facts. Vision Router no longer rewrites the current user image into internal `[attached image: sha256:…]` marker text through the legacy pre-step path. Model-specific projection now stays at adapter/request boundaries instead of leaking into the conversation transcript.
+- Fixes #374 and the wider delegated call-config class: when Vision Router actually hands a request to another provider/model, source-route `maxTokens`, `reasoningEffort`, sampling and stop settings no longer override the target adapter's own defaults. This fixes GLM routes such as `glm-4v-flash` rejecting a Router-supplied 4096-token limit when the configured model cap is 1024.
+- Refines that handoff rule so transparent Vision Router twins keep caller-owned generation settings, while tool, Vision Chain and `agent/request` provider/model handoffs restore target-route authority. Reasoning memory is scoped to the relevant session and route instead of becoming cross-route state.
+- Keeps the `vision_describe` cache as a successful-answer cache. Structured Vision Router failures (`ok: false` with `VISION_*` errors) are no longer retained across turns, so repaired credentials or recovered backends can be retried immediately.
+- Recovers safely when a source adapter is incorrectly catalogued as image-capable. Generated Vision Router twins now recognize explicit runtime image-capability rejection before model-visible output, record bounded negative proof for the exact source route, and re-enter the canonical text-only fallback path instead of repeatedly sending raw pixels to a text-only backend. Generic 4xx/5xx, auth, rate-limit, media-format, cancellation and post-output failures do not trigger this fallback.
+- Resolves DSH text-only projected image handles such as `sha256:deadbeef` back to a canonical attachment only inside the current Session. Unique prefixes resolve, unknown or ambiguous prefixes fail closed, bounded cache eviction cannot erase ambiguity because durable Session history remains authoritative, and attachment-shaped input can no longer fall through into a guessed local filesystem path.
+- Makes the composer `👁 Vision` state the authoritative per-Session permission for Vision Router orchestration. Ordinary text-only and native-multimodal routes no longer receive Router-owned `vision_*` schemas, structured bootstrap, automatic deep-tool mounting or instant visual work while Vision is OFF. Native multimodal pixels remain Host-owned and continue to work normally without Router intervention.
+- Keeps the current Agent step internally stable if the model picker changes while it is running. The new selection is applied at the next real prompt-assembly boundary, while diagnostic/out-of-band prompt renders cannot clear or mutate the active step authority.
+- Keeps Settings `tool=false` as an independent global capability gate. Selecting a Vision Router wrapper cannot re-enable tools that the user explicitly disabled.
+
+## Regression and CI hardening
+
+- Adds production-shaped coverage for delegated target defaults, transparent wrapper behavior, `agent/request` route handoffs and ordinary non-delegated LLM calls.
+- Adds transcript ownership coverage ensuring accepted user images remain raw Session content and the retired pre-step bridge cannot synthesize attachment markers into durable history.
+- Adds false-multimodal metadata regressions across generated twins, custom wrappers, lazy source registration, route changes and negative-proof isolation.
+- Adds attachment-handle regressions for exact IDs, DSH short projected handles, cache eviction, same-Session prefix collisions, cross-Session isolation, malformed handles and attachment-vs-filesystem dispatch.
+- Adds Session Vision-mode regressions for OFF/ON isolation, native multimodal non-intervention, prompt-assembly visibility, PTC/scoped-tool behavior, mid-step picker changes, diagnostic assemblies, foreign `vision_*` tools and Settings `tool=false`.
+- Makes the default test manifest closed-world: every `tests/**/*.test.js` file must either run in the normal suite or have a documented PR-triggered specialist workflow owner.
+- Verifies specialist workflow ownership against the workflow source so exclusions cannot silently become stale or merely appear in a path trigger without being executed.
+- The final release head passes Node 22/24, DSH rc.6/rc.7/rc.8 contracts, P1/P2/P3 architecture gates, native multimodal cold/process restart coverage, Ubuntu/macOS/Windows host-sharp checks, and CodeQL with no new alerts.
+
+## Upgrade
+
+Upgrade to 2.1.2 and restart the DSH Web/Desktop process so the new runtime boundaries are loaded. No settings migration is required.

package/lib/agent-request-route-authority.js

@@ -0,0 +1,94 @@
+import { projectDelegatedCallConfig } from './delegated-call-config.js'
+import { contextWithTwinImageCapabilityFallback } from './twin-image-capability-fallback.js'
+
+const routeAuthorityOptionsByContext = new WeakMap()
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function routeOf(value) {
+  if (!isObject(value)) return undefined
+  const provider = typeof value.provider === 'string' && value.provider !== '' ? value.provider : undefined
+  const model = typeof value.model === 'string' && value.model !== '' ? value.model : undefined
+  return provider !== undefined && model !== undefined ? { provider, model } : undefined
+}
+
+/**
+ * A completed `agent/request` route change is an authority handoff: generation
+ * defaults from the source provider/model must not be mistaken for explicit
+ * target-model config. Payload/lifecycle fields remain untouched.
+ *
+ * Fail closed on incomplete route evidence. If either side lacks an exact
+ * provider+model tuple, preserve the handler result rather than guessing.
+ */
+export function projectAgentRequestRouteHandoff(sourceConfig, resultConfig) {
+  const source = routeOf(sourceConfig)
+  const target = routeOf(resultConfig)
+  if (source === undefined || target === undefined) return resultConfig
+  if (source.provider === target.provider && source.model === target.model) return resultConfig
+  return projectDelegatedCallConfig(resultConfig)
+}
+
+/**
+ * Runtime composition can publish route identities before Core.apply without
+ * changing the mature `contextWithAgentRequestRouteAuthority(backendRuntimeCtx)`
+ * boundary shape. The WeakMap keeps this per-context and garbage-collectable.
+ */
+export function configureAgentRequestRouteAuthority(ctx, options = {}) {
+  if (!isObject(ctx)) return ctx
+  routeAuthorityOptionsByContext.set(ctx, {
+    wrapperRoute: options.wrapperRoute,
+    chainRoute: options.chainRoute,
+    logger: options.logger,
+  })
+  return ctx
+}
+
+/**
+ * Private Core-facing context. It wraps only `agent/request` handlers and only
+ * projects a result when that handler demonstrably changed provider/model.
+ * Ordinary request handlers and direct LLM calls retain caller identity.
+ *
+ * This is also the final Core-facing adapter-registration boundary, so it owns
+ * the generated-twin runtime capability correction: if a `<provider>-vision`
+ * twin trusted image metadata but the live source explicitly rejects raw image
+ * input before producing output, the twin is re-entered once through Core's
+ * existing text bridge instead of leaking that 400 to the user. Keeping the
+ * fallback here means the deeper prepareCall/ownership layers still observe the
+ * final wrapped stream and retain their existing contracts.
+ */
+export function contextWithAgentRequestRouteAuthority(ctx, options) {
+  if (!isObject(ctx)) return ctx
+  const fallbackOptions = isObject(options)
+    ? options
+    : routeAuthorityOptionsByContext.get(ctx) ?? {}
+  const routeAuthorityCtx = new Proxy(ctx, {
+    get(target, property) {
+      if (property !== 'on') {
+        const value = Reflect.get(target, property, target)
+        return typeof value === 'function' ? value.bind(target) : value
+      }
+      const on = Reflect.get(target, property, target)
+      if (typeof on !== 'function') return on
+      return (event, handler, ...rest) => {
+        if (event !== 'agent/request' || typeof handler !== 'function') {
+          return on.call(target, event, handler, ...rest)
+        }
+        return on.call(target, event, async function routeAuthorityAwareRequest(payload, next) {
+          let sourceConfig
+          const captureNext = typeof next === 'function'
+            ? async (...args) => {
+                const value = await next(...args)
+                if (sourceConfig === undefined) sourceConfig = value
+                return value
+              }
+            : next
+          const result = await handler.call(this, payload, captureNext)
+          return projectAgentRequestRouteHandoff(sourceConfig, result)
+        }, ...rest)
+      }
+    },
+  })
+  return contextWithTwinImageCapabilityFallback(routeAuthorityCtx, fallbackOptions)
+}

package/lib/client-host-compat-prelude.js

@@ -20,11 +20,22 @@ export const CLIENT_HOST_COMPAT_PRELUDE = String.raw`(function(){
   var LEGACY_CREDENTIAL_EVENT = 'credentials/updated';
   var HOST_CREDENTIAL_EVENT = 'credentials/reference-updated';
 
-  function hasHostCatalog(remote) {
-    return !!(
-      remote && remote.session &&
-      typeof remote.session.modelCatalog === 'function'
-    );
+  function optionalHostSession(ctx, remote) {
+    try {
+      if (ctx && typeof ctx.get === 'function') {
+        var session = ctx.get('remote.session');
+        if (session) return session;
+      }
+    } catch (_) {}
+    try {
+      return remote && remote.session;
+    } catch (_) {
+      return undefined;
+    }
+  }
+
+  function hasHostCatalog(session) {
+    return !!(session && typeof session.modelCatalog === 'function');
   }
 
   function wrapCatalogResult(value) {
@@ -37,23 +48,23 @@ export const CLIENT_HOST_COMPAT_PRELUDE = String.raw`(function(){
     return value;
   }
 
-  function catalogModels(remote) {
+  function catalogModels(session) {
     return function models() {
-      return Promise.resolve(remote.session.modelCatalog()).then(wrapCatalogResult);
+      return Promise.resolve(session.modelCatalog()).then(wrapCatalogResult);
     };
   }
 
-  function compatibleApi(originalApi, remote) {
+  function compatibleApi(originalApi, session) {
     var originalLlm = originalApi && originalApi.llm;
     var llm = originalLlm && (typeof originalLlm === 'object' || typeof originalLlm === 'function')
       ? new Proxy(originalLlm, {
           get: function(target, property) {
-            if (property === 'models') return catalogModels(remote);
+            if (property === 'models') return catalogModels(session);
             var value = Reflect.get(target, property, target);
             return typeof value === 'function' ? value.bind(target) : value;
           }
         })
-      : { models: catalogModels(remote) };
+      : { models: catalogModels(session) };
     if (originalApi && (typeof originalApi === 'object' || typeof originalApi === 'function')) {
       return new Proxy(originalApi, {
         get: function(target, property) {
@@ -66,10 +77,10 @@ export const CLIENT_HOST_COMPAT_PRELUDE = String.raw`(function(){
     return { llm: llm };
   }
 
-  function compatibleConnection(connection, remote) {
-    if (!hasHostCatalog(remote)) return connection;
+  function compatibleConnection(connection, session) {
+    if (!hasHostCatalog(session)) return connection;
     if (!connection || (typeof connection !== 'object' && typeof connection !== 'function')) return connection;
-    var api = compatibleApi(connection.api, remote);
+    var api = compatibleApi(connection.api, session);
     return new Proxy(connection, {
       get: function(target, property) {
         if (property === 'api') return api;
@@ -79,8 +90,8 @@ export const CLIENT_HOST_COMPAT_PRELUDE = String.raw`(function(){
     });
   }
 
-  function compatibleRemote(remote) {
-    if (!hasHostCatalog(remote)) return remote;
+  function compatibleRemote(remote, session) {
+    if (!hasHostCatalog(session)) return remote;
     if (!remote || (typeof remote !== 'object' && typeof remote !== 'function')) return remote;
     return new Proxy(remote, {
       get: function(target, property) {
@@ -140,7 +151,8 @@ export const CLIENT_HOST_COMPAT_PRELUDE = String.raw`(function(){
 
   function compatibleContext(ctx) {
     if (!ctx || typeof ctx !== 'object' || typeof Proxy !== 'function') return ctx;
-    var remote = compatibleRemote(ctx.remote);
+    var session = optionalHostSession(ctx, ctx.remote);
+    var remote = compatibleRemote(ctx.remote, session);
     var locale = compatibleLocale(ctx.locale);
     return new Proxy(ctx, {
       get: function(target, property) {
@@ -151,7 +163,7 @@ export const CLIENT_HOST_COMPAT_PRELUDE = String.raw`(function(){
           if (typeof get !== 'function') return get;
           return function(name) {
             var value = get.call(target, name);
-            return name === 'connection' ? compatibleConnection(value, remote) : value;
+            return name === 'connection' ? compatibleConnection(value, session) : value;
           };
         }
         var value = Reflect.get(target, property, target);

package/lib/delegated-call-config.js

@@ -0,0 +1,27 @@
+const ROUTE_OWNED_CALL_FIELDS = Object.freeze([
+  'reasoningEffort',
+  'temperature',
+  'maxTokens',
+  'stop',
+])
+
+/**
+ * Project an internal Vision Router delegation onto a different provider/model.
+ *
+ * The delegated route owns its own call defaults and compatibility. Carry the
+ * request payload and lifecycle through, but never leak source-route sampling,
+ * reasoning or output-limit state into the target adapter. DSH will materialize
+ * the target adapter's configured defaults when these fields are absent.
+ *
+ * Direct transports owned by Vision Router do not use this projection; their
+ * wire compatibility remains the Router's responsibility.
+ */
+export function projectDelegatedCallConfig(options) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) return options
+  if (!ROUTE_OWNED_CALL_FIELDS.some((field) => Object.hasOwn(options, field))) return options
+  const next = { ...options }
+  for (const field of ROUTE_OWNED_CALL_FIELDS) delete next[field]
+  return next
+}
+
+export const delegatedRouteOwnedCallFields = ROUTE_OWNED_CALL_FIELDS

package/lib/doctor.js

@@ -303,12 +303,53 @@ function stripYamlComment(line) {
   return line
 }
 
+function yamlIndent(line) {
+  return /^(\s*)/.exec(line)?.[1].length ?? 0
+}
+
+function rowIsInsideInsert(lines, rowIndex, rowIndent) {
+  for (let cursor = rowIndex - 1; cursor >= 0; cursor -= 1) {
+    const candidate = lines[cursor]
+    if (/^\s*$/.test(candidate)) continue
+    const indent = yamlIndent(candidate)
+    if (indent >= rowIndent) continue
+    return /^\s*-?\s*insert\s*:\s*$/.test(candidate)
+  }
+  return false
+}
+
+function inspectVisionRouterPatchRows(lines) {
+  let mountRows = 0
+  let overrideRows = 0
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const idMatch = /^(\s*)-\s+id\s*:\s*['"]?([^'"\s]+)['"]?\s*$/.exec(lines[index])
+    if (!idMatch) continue
+    const rowIndent = idMatch[1].length
+    let pluginName
+    for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+      const candidate = lines[cursor]
+      if (/^\s*$/.test(candidate)) continue
+      const indent = yamlIndent(candidate)
+      if (indent <= rowIndent) break
+      const nameMatch = /^\s*name\s*:\s*['"]?([^'"\s]+)['"]?\s*$/.exec(candidate)
+      if (nameMatch) pluginName = nameMatch[1]
+    }
+    if (idMatch[2] !== 'vision-router' && pluginName !== PLUGIN_NAME) continue
+    if (rowIsInsideInsert(lines, index, rowIndent)) mountRows += 1
+    else overrideRows += 1
+  }
+
+  return { mountRows, overrideRows }
+}
+
 export function inspectProfilePatch(patchPath) {
   if (!existsSync(patchPath)) {
     return {
       path: patchPath,
       exists: false,
       visionRouterRows: 0,
+      visionRouterOverrideRows: 0,
       manualVisionRouter: false,
       disablesOfficialDeepSeek: false,
     }
@@ -317,14 +358,13 @@ export function inspectProfilePatch(patchPath) {
   try {
     text = readFileBounded(patchPath).toString('utf8')
   } catch (error) {
-    return { path: patchPath, exists: true, visionRouterRows: 0, manualVisionRouter: false, disablesOfficialDeepSeek: false, error: error instanceof Error ? error.message : String(error), oversized: error?.code === 'DOCTOR_INPUT_TOO_LARGE' }
+    return { path: patchPath, exists: true, visionRouterRows: 0, visionRouterOverrideRows: 0, manualVisionRouter: false, disablesOfficialDeepSeek: false, error: error instanceof Error ? error.message : String(error), oversized: error?.code === 'DOCTOR_INPUT_TOO_LARGE' }
   }
   const lines = text.split(/\r?\n/).map(stripYamlComment)
-  let visionRouterRows = 0
+  const { mountRows: visionRouterRows, overrideRows: visionRouterOverrideRows } = inspectVisionRouterPatchRows(lines)
   let disablesOfficialDeepSeek = false
   for (let index = 0; index < lines.length; index += 1) {
     const line = lines[index]
-    if (/^\s*name\s*:\s*['"]?dsh-vision-router['"]?\s*$/.test(line)) visionRouterRows += 1
     if (!/^\s*-?\s*id\s*:\s*['"]?llm-deepseek['"]?\s*$/.test(line)) continue
     for (let cursor = index + 1; cursor < Math.min(lines.length, index + 12); cursor += 1) {
       if (/^\s*-\s+id\s*:/.test(lines[cursor])) break
@@ -338,6 +378,7 @@ export function inspectProfilePatch(patchPath) {
     path: patchPath,
     exists: true,
     visionRouterRows,
+    visionRouterOverrideRows,
     manualVisionRouter: visionRouterRows > 0,
     disablesOfficialDeepSeek,
   }
@@ -581,4 +622,4 @@ export function doctorProfiles({ dshHome = resolveDshHome(), profile, fix = fals
       && applicable.every(profileHealthy)
       && (log.settingsSaveFailures?.length ?? 0) === 0,
   }
-}
+}

package/lib/grounding-coordinate-frame.js

@@ -0,0 +1,93 @@
+export const GROUNDING_FRAME_SIZE = 1000
+
+function finitePositiveInteger(value, name) {
+  const number = Number(value)
+  if (!Number.isFinite(number) || number <= 0) {
+    throw new TypeError(`${name} must be a positive finite number`)
+  }
+  return Math.max(1, Math.round(number))
+}
+
+/**
+ * Build the exact geometry used to letterbox a source raster into the
+ * grounding protocol's square frame. The rendered dimensions are integers so
+ * callers can resize to these exact values before extending the canvas; the
+ * inverse therefore never depends on a backend's resize policy.
+ */
+export function createGroundingFrame(width, height, frameSize = GROUNDING_FRAME_SIZE) {
+  const sourceWidth = finitePositiveInteger(width, 'width')
+  const sourceHeight = finitePositiveInteger(height, 'height')
+  const size = finitePositiveInteger(frameSize, 'frameSize')
+  const scale = Math.min(size / sourceWidth, size / sourceHeight)
+  const renderedWidth = Math.max(1, Math.min(size, Math.round(sourceWidth * scale)))
+  const renderedHeight = Math.max(1, Math.min(size, Math.round(sourceHeight * scale)))
+  const left = Math.floor((size - renderedWidth) / 2)
+  const top = Math.floor((size - renderedHeight) / 2)
+  const right = size - renderedWidth - left
+  const bottom = size - renderedHeight - top
+
+  return Object.freeze({
+    frameWidth: size,
+    frameHeight: size,
+    sourceWidth,
+    sourceHeight,
+    renderedWidth,
+    renderedHeight,
+    left,
+    top,
+    right,
+    bottom,
+    scaleX: renderedWidth / sourceWidth,
+    scaleY: renderedHeight / sourceHeight,
+  })
+}
+
+function finiteCoordinate(value) {
+  const number = Number(value)
+  return Number.isFinite(number) ? number : undefined
+}
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(value, max))
+}
+
+/** Map a box reported in the explicit square grounding frame back to source pixels. */
+export function groundingFrameBoxToSource(box, frame) {
+  if (!box || !frame) return undefined
+  const x1 = finiteCoordinate(box.x1)
+  const y1 = finiteCoordinate(box.y1)
+  const x2 = finiteCoordinate(box.x2)
+  const y2 = finiteCoordinate(box.y2)
+  if ([x1, y1, x2, y2].some((value) => value === undefined)) return undefined
+
+  const raw = {
+    x1: (x1 - frame.left) / frame.scaleX,
+    y1: (y1 - frame.top) / frame.scaleY,
+    x2: (x2 - frame.left) / frame.scaleX,
+    y2: (y2 - frame.top) / frame.scaleY,
+  }
+  const mapped = {
+    x1: Math.floor(clamp(raw.x1, 0, frame.sourceWidth)),
+    y1: Math.floor(clamp(raw.y1, 0, frame.sourceHeight)),
+    x2: Math.ceil(clamp(raw.x2, 0, frame.sourceWidth)),
+    y2: Math.ceil(clamp(raw.y2, 0, frame.sourceHeight)),
+  }
+  if (mapped.x2 <= mapped.x1 || mapped.y2 <= mapped.y1) return undefined
+  return mapped
+}
+
+/** Map source-pixel geometry into the square frame, useful for protocol tests. */
+export function sourceBoxToGroundingFrame(box, frame) {
+  if (!box || !frame) return undefined
+  const x1 = finiteCoordinate(box.x1)
+  const y1 = finiteCoordinate(box.y1)
+  const x2 = finiteCoordinate(box.x2)
+  const y2 = finiteCoordinate(box.y2)
+  if ([x1, y1, x2, y2].some((value) => value === undefined)) return undefined
+  return {
+    x1: frame.left + x1 * frame.scaleX,
+    y1: frame.top + y1 * frame.scaleY,
+    x2: frame.left + x2 * frame.scaleX,
+    y2: frame.top + y2 * frame.scaleY,
+  }
+}