dsh-vision-router 2.2.0 → 2.2.2

package/lib/dsh-settings-017-compat.js

@@ -0,0 +1,416 @@
+const SETTINGS_NS = 'vision-router'
+export const LOCAL_SETTINGS_PATH = '/_dsh/vision-router/local-settings'
+export const DSH_017_SETTINGS_COMPAT_MARK = '__visionRouterDsh017ConfigEditorCompat'
+const BODY_LIMIT_BYTES = 256 * 1024
+const REVISION_REGISTRY_KEY = Symbol.for('dsh-vision-router.settings-017-revisions')
+
+function revisionRegistry() {
+  let registry = globalThis[REVISION_REGISTRY_KEY]
+  if (!(registry instanceof Map)) {
+    registry = new Map()
+    Object.defineProperty(globalThis, REVISION_REGISTRY_KEY, {
+      value: registry,
+      configurable: true,
+    })
+  }
+  return registry
+}
+
+function objectLike(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function plainObject(value) {
+  if (!objectLike(value)) return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+function clone(value) {
+  return value === undefined ? undefined : structuredClone(value)
+}
+
+function mergeResolved(base, overlay) {
+  if (!plainObject(base) || !plainObject(overlay)) return clone(overlay)
+  const next = clone(base)
+  for (const [key, value] of Object.entries(overlay)) {
+    next[key] = plainObject(value) && plainObject(next[key])
+      ? mergeResolved(next[key], value)
+      : clone(value)
+  }
+  return next
+}
+
+function jsonEqual(left, right) {
+  if (left === right) return true
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return Array.isArray(left) && Array.isArray(right)
+      && left.length === right.length
+      && left.every((value, index) => jsonEqual(value, right[index]))
+  }
+  if (!plainObject(left) || !plainObject(right)) return false
+  const leftKeys = Object.keys(left)
+  const rightKeys = Object.keys(right)
+  return leftKeys.length === rightKeys.length
+    && leftKeys.every((key) => Object.hasOwn(right, key) && jsonEqual(left[key], right[key]))
+}
+
+function logicalUserLayer(current, inherited) {
+  const user = Object.create(null)
+  const keys = new Set([
+    ...Object.keys(objectLike(current) ? current : {}),
+    ...Object.keys(objectLike(inherited) ? inherited : {}),
+  ])
+  for (const key of keys) {
+    const currentHas = objectLike(current) && Object.hasOwn(current, key)
+    const inheritedHas = objectLike(inherited) && Object.hasOwn(inherited, key)
+    if (currentHas === inheritedHas && (!currentHas || jsonEqual(current[key], inherited[key]))) continue
+    if (currentHas) user[key] = clone(current[key])
+  }
+  return user
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue)
+  if (!plainObject(value)) return value
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]))
+}
+
+function fingerprint(value) {
+  return JSON.stringify(stableValue(value))
+}
+
+function revisionKey(editor, namespace) {
+  let documentPath
+  try { documentPath = editor?.documentPath } catch {}
+  return `${String(documentPath ?? 'process-local-profile')}\u0000${namespace}`
+}
+
+/**
+ * Ordinary Config writes reload DVR, so a plugin-instance counter is unsafe.
+ * Keep one process-level monotonic counter per profile document + namespace.
+ * The registry survives DVR HMR and advances whenever the effective persisted
+ * layers observed at the compatibility boundary change. A process restart also
+ * resets every browser connection, which forces a fresh descriptor read.
+ */
+function revisionFor(editor, namespace, current, inherited) {
+  const key = revisionKey(editor, namespace)
+  const valueFingerprint = fingerprint({ current, inherited })
+  const registry = revisionRegistry()
+  const previous = registry.get(key)
+  if (!previous) {
+    const state = { fingerprint: valueFingerprint, revision: 0 }
+    registry.set(key, state)
+    return state.revision
+  }
+  if (previous.fingerprint !== valueFingerprint) {
+    previous.fingerprint = valueFingerprint
+    previous.revision += 1
+  }
+  return previous.revision
+}
+
+function serviceOf(ctx, name) {
+  try {
+    const value = typeof ctx?.get === 'function' ? ctx.get(name) : undefined
+    if (value !== undefined && value !== null) return value
+  } catch {}
+  try {
+    const value = ctx?.[name]
+    return value === undefined || value === null ? undefined : value
+  } catch {
+    return undefined
+  }
+}
+
+function configEditorRow(editor, namespace) {
+  const rows = typeof editor?.configuration === 'function' ? editor.configuration() : []
+  if (!Array.isArray(rows)) return undefined
+  return rows.find((row) => row?.entry?.options?.id === namespace)
+}
+
+function settingsConflict(expected, actual) {
+  const error = new Error(`Vision Router settings changed before this write landed (expected ${expected}, actual ${actual})`)
+  error.code = 'SETTINGS_CONFLICT'
+  error.expected = expected
+  error.actual = actual
+  return error
+}
+
+function admissionError(message) {
+  const error = new Error(message)
+  error.code = 'SETTINGS_INVALID_MUTATION'
+  return error
+}
+
+function validateOperations(ops) {
+  if (!Array.isArray(ops) || ops.length === 0) throw admissionError('settings operations must be a non-empty array')
+  return ops.map((op) => {
+    if (!objectLike(op) || (op.op !== 'set' && op.op !== 'unset')) {
+      throw admissionError('settings operation must be set or unset')
+    }
+    if (!Array.isArray(op.path) || op.path.length !== 1 || typeof op.path[0] !== 'string' || op.path[0] === '') {
+      throw admissionError('Vision Router settings compatibility accepts one top-level field per operation')
+    }
+    const key = op.path[0]
+    if (key === '__proto__' || key === 'prototype' || key === 'constructor') {
+      throw admissionError('unsafe settings field name')
+    }
+    return op.op === 'set'
+      ? { op: 'set', path: [key], value: clone(op.value) }
+      : { op: 'unset', path: [key] }
+  })
+}
+
+function applyOperations(current, inherited, ops) {
+  const next = clone(objectLike(current) ? current : {})
+  for (const op of ops) {
+    const key = op.path[0]
+    if (op.op === 'set') {
+      next[key] = clone(op.value)
+      continue
+    }
+    if (objectLike(inherited) && Object.hasOwn(inherited, key)) next[key] = clone(inherited[key])
+    else delete next[key]
+  }
+  return next
+}
+
+function createConfigEditorSettingsFacade(editor, entryConfig, namespace) {
+  const listeners = new Set()
+
+  function state() {
+    const row = configEditorRow(editor, namespace)
+    if (!row) return undefined
+    const current = objectLike(row.entry?.options?.config) ? row.entry.options.config : {}
+    const inherited = objectLike(row.inherited) ? row.inherited : {}
+    const base = mergeResolved(entryConfig, inherited)
+    const value = mergeResolved(entryConfig, current)
+    return {
+      row,
+      descriptor: {
+        ns: namespace,
+        value,
+        base,
+        user: logicalUserLayer(current, inherited),
+        revision: revisionFor(editor, namespace, current, inherited),
+        applies: true,
+      },
+    }
+  }
+
+  function notify(value) {
+    for (const listener of [...listeners]) {
+      try { listener(value, undefined) } catch {}
+    }
+  }
+
+  const scope = {
+    get() {
+      return state()?.descriptor.value ?? entryConfig
+    },
+    watch(listener) {
+      if (typeof listener !== 'function') return () => {}
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+
+  return {
+    [DSH_017_SETTINGS_COMPAT_MARK]: true,
+    get writable() {
+      return state() !== undefined
+    },
+    get(namespaceName) {
+      return namespaceName === namespace ? scope.get() : undefined
+    },
+    register(namespaceName) {
+      if (namespaceName !== namespace) {
+        throw new Error(`vision-router: unexpected settings namespace ${String(namespaceName)}`)
+      }
+      return scope
+    },
+    describe() {
+      const current = state()
+      return current ? [clone(current.descriptor)] : []
+    },
+    async mutate(namespaceName, operations, expectedRevision) {
+      if (namespaceName !== namespace) throw new Error(`No configurable plugin entry ${JSON.stringify(namespaceName)}`)
+      const before = state()
+      if (!before) throw new Error(`No configurable plugin entry ${JSON.stringify(namespace)}`)
+      if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+        throw admissionError('expectedRevision must be a non-negative safe integer')
+      }
+      if (expectedRevision !== before.descriptor.revision) {
+        throw settingsConflict(expectedRevision, before.descriptor.revision)
+      }
+      const ops = validateOperations(operations)
+      const entry = before.row.entry
+      await editor.edit(entry, (current, inherited) => applyOperations(current, inherited, ops))
+      const after = state()
+      if (!after) throw new Error('Vision Router configuration entry disappeared after the write')
+      notify(after.descriptor.value)
+      return clone(after.descriptor)
+    },
+  }
+}
+
+/**
+ * DSH 0.1.7 services may mount after DVR's apply() starts. Capture ConfigEditor
+ * through its own lifecycle injection and resolve the settings generation when
+ * each consumer actually accesses it. This avoids both startup-order races and
+ * undeclared child-context service reads.
+ */
+function contextWithLazySettingsCompatibility(ctx, entryConfig, namespace) {
+  const wrappers = new WeakMap()
+  const facades = new WeakMap()
+  let injectedEditor
+
+  try {
+    if (typeof ctx?.inject === 'function') {
+      ctx.inject(['configEditor'], (editorCtx) => {
+        injectedEditor = serviceOf(editorCtx, 'configEditor')
+      })
+    }
+  } catch {
+    // Older Hosts may not expose ConfigEditor; their native SettingsProvider stays authoritative.
+  }
+
+  function compatibleSettings(target) {
+    const settings = serviceOf(target, 'settings') ?? serviceOf(ctx, 'settings')
+    if (!settings || typeof settings.register === 'function') return settings
+    const editor = serviceOf(target, 'configEditor') ?? injectedEditor ?? serviceOf(ctx, 'configEditor')
+    if (typeof settings.describe !== 'function'
+        || !editor || typeof editor.edit !== 'function' || typeof editor.configuration !== 'function') {
+      return settings
+    }
+    let facade = facades.get(editor)
+    if (!facade) {
+      facade = createConfigEditorSettingsFacade(editor, entryConfig, namespace)
+      facades.set(editor, facade)
+    }
+    return facade
+  }
+
+  function wrap(target) {
+    if (!target || typeof target !== 'object') return target
+    const held = wrappers.get(target)
+    if (held) return held
+    const wrapped = new Proxy(target, {
+      get(object, property) {
+        if (property === 'settings') return compatibleSettings(object)
+        if (property === 'get') {
+          const get = Reflect.get(object, property, object)
+          if (typeof get !== 'function') return get
+          return (name, ...rest) => name === 'settings'
+            ? compatibleSettings(object)
+            : get.call(object, name, ...rest)
+        }
+        if (property === 'inject') {
+          const inject = Reflect.get(object, property, object)
+          if (typeof inject !== 'function') return inject
+          return (dependencies, callback, ...rest) => inject.call(
+            object,
+            dependencies,
+            typeof callback === 'function' && Array.isArray(dependencies) && dependencies.includes('settings')
+              ? (child) => callback(wrap(child))
+              : callback,
+            ...rest,
+          )
+        }
+        const value = Reflect.get(object, property, object)
+        return typeof value === 'function' ? value.bind(object) : value
+      },
+    })
+    wrappers.set(target, wrapped)
+    return wrapped
+  }
+
+  return wrap(ctx)
+}
+
+/**
+ * DSH 0.1.7 removes the legacy SettingsProvider.register() namespace API and
+ * makes ordinary plugin configuration profile-owned through ConfigEditor.
+ * Preserve DVR's mature settings consumers behind the old semantic face while
+ * leaving older Hosts on their native SettingsProvider whenever it is present.
+ */
+export function installDsh017SettingsCompatibility(ctx, entryConfig = {}, options = {}) {
+  const namespace = typeof options.namespace === 'string' && options.namespace !== '' ? options.namespace : SETTINGS_NS
+  return contextWithLazySettingsCompatibility(ctx, entryConfig, namespace)
+}
+
+function sendJson(res, status, body) {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  res.end(JSON.stringify(body))
+}
+
+async function readJson(req) {
+  let size = 0
+  const chunks = []
+  for await (const chunk of req) {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    size += bytes.length
+    if (size > BODY_LIMIT_BYTES) throw Object.assign(new Error('request body too large'), { statusCode: 413 })
+    chunks.push(bytes)
+  }
+  if (chunks.length === 0) return {}
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+function namespaceDescriptor(settings) {
+  const descriptors = settings.describe({ redactSecrets: true })
+  return Array.isArray(descriptors) ? descriptors.find((entry) => entry?.ns === SETTINGS_NS) : undefined
+}
+
+/** Local-only transport for the 0.1.7 browser, which no longer exposes settingsScope. */
+export function installDsh017LocalSettingsTransport(ctx) {
+  if (!ctx || typeof ctx.inject !== 'function') return
+  ctx.inject(['settings', 'webServer'], (webCtx) => {
+    if (webCtx.settings?.[DSH_017_SETTINGS_COMPAT_MARK] !== true) return
+    if (typeof webCtx.settings.describe !== 'function' || typeof webCtx.settings.mutate !== 'function') return
+    webCtx.effect(
+      () => webCtx.webServer.register({
+        kind: 'exact',
+        path: LOCAL_SETTINGS_PATH,
+        async handler(req, res) {
+          if (req.method === 'GET') {
+            const descriptor = namespaceDescriptor(webCtx.settings)
+            if (!descriptor) {
+              sendJson(res, 404, { ok: false, error: { code: 'settings-unavailable', message: 'Vision Router settings are unavailable' } })
+              return
+            }
+            sendJson(res, 200, { ok: true, value: { ...descriptor, writable: webCtx.settings.writable === true } })
+            return
+          }
+          if (req.method !== 'POST') {
+            res.setHeader('Allow', 'GET, POST')
+            sendJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'method not allowed' } })
+            return
+          }
+          try {
+            const payload = await readJson(req)
+            await webCtx.settings.mutate(SETTINGS_NS, payload?.ops, payload?.expectedRevision)
+            const descriptor = namespaceDescriptor(webCtx.settings)
+            if (!descriptor) throw new Error('Vision Router settings disappeared after the write')
+            sendJson(res, 200, { ok: true, value: { ...descriptor, writable: webCtx.settings.writable === true } })
+          } catch (error) {
+            const conflict = error?.code === 'SETTINGS_CONFLICT'
+            sendJson(res, error?.statusCode ?? (conflict ? 409 : 400), {
+              ok: false,
+              error: {
+                code: conflict ? 'settings-conflict' : 'settings-rejected',
+                message: error?.message ?? String(error),
+                ...(conflict ? { details: { expected: error.expected, actual: error.actual } } : {}),
+              },
+            })
+          }
+        },
+      }),
+      'vision-router: DSH 0.1.7 local settings transport',
+    )
+  })
+}

package/lib/fetch-wrapper-lifecycle.js

@@ -0,0 +1,56 @@
+// Lifecycle metadata only: no native fetch snapshot, dispatcher, or egress
+// policy is retained here. Weak keys let abandoned wrapper chains be collected.
+const installations = new WeakMap()
+
+function livePreviousDescriptor(descriptor) {
+  let previous = descriptor
+  while (previous && Object.hasOwn(previous, 'value')) {
+    const installation = installations.get(previous.value)
+    if (!installation?.disposed) break
+    previous = installation.previous
+  }
+  return previous
+}
+
+/** Preserve a live accessor-owned pipeline, including middleware recomposition. */
+export function captureFetchDelegate(target = globalThis) {
+  const descriptor = Object.getOwnPropertyDescriptor(target, 'fetch')
+  const current = target.fetch
+  if (typeof current !== 'function' || typeof descriptor?.get !== 'function') return current
+  return (input, init) => Reflect.apply(Reflect.apply(descriptor.get, target, []), target, [input, init])
+}
+
+/**
+ * Publish an already constructed fetch wrapper without calling a foreign
+ * accessor setter. Assignment is unsafe: a pipeline getter may return a
+ * function whose setter adopts our wrapper as its own delegate (#519).
+ *
+ * The caller captures the CURRENT Host chain at installation, never at module
+ * load, and disables its own behavior before restoring. Later Host replacements
+ * remain authoritative. Restore the exact previous descriptor only while our
+ * data property still owns the surface; never feed a wrapper back to a setter.
+ * Non-configurable accessors cannot be composed this way and fail before any
+ * mutation rather than silently bypassing a Host policy or explicit proxy.
+ */
+export function installFetchWrapper(wrapped, target = globalThis) {
+  if (typeof wrapped !== 'function') throw new TypeError('fetch wrapper must be a function')
+  const previous = Object.getOwnPropertyDescriptor(target, 'fetch')
+  if (previous && Object.hasOwn(previous, 'value') && previous.value === wrapped) return () => {}
+  const installed = previous && Object.hasOwn(previous, 'value')
+    ? { ...previous, value: wrapped }
+    : { configurable: true, enumerable: previous?.enumerable ?? true, writable: true, value: wrapped }
+  Object.defineProperty(target, 'fetch', installed)
+  const installation = { previous, disposed: false }
+  installations.set(wrapped, installation)
+  return () => {
+    if (installation.disposed) return
+    installation.disposed = true
+    const current = Object.getOwnPropertyDescriptor(target, 'fetch')
+    if (!current || !Object.hasOwn(current, 'value') || current.value !== wrapped ||
+        current.configurable !== installed.configurable ||
+        current.enumerable !== installed.enumerable || current.writable !== installed.writable) return
+    const restore = livePreviousDescriptor(previous)
+    if (restore) Object.defineProperty(target, 'fetch', restore)
+    else delete target.fetch
+  }
+}

package/lib/legacy-global-proxy-boundary.js

@@ -1,3 +1,4 @@
+import { captureFetchDelegate, installFetchWrapper } from './fetch-wrapper-lifecycle.js'
 // H2: retain the legacy Host-owned proxy override as a scoped compatibility
 // transport, not as process-wide routing authority. The wrapper is always
 // transparent unless one DVR-owned visual adapter call is active (or the
@@ -184,7 +185,7 @@ function proxyHostsOf(config) {
  * the narrow legacy direct whole-turn fallback above.
  */
 export function installLegacyGlobalProxyBoundary(ctx, config = {}, options = {}) {
-  const originalFetch = typeof options.originalFetch === 'function' ? options.originalFetch : globalThis.fetch
+  const originalFetch = typeof options.originalFetch === 'function' ? options.originalFetch : captureFetchDelegate()
   const importUndici = typeof options.importUndici === 'function' ? options.importUndici : () => import('undici')
   if (typeof originalFetch !== 'function') return () => {}
 
@@ -227,14 +228,14 @@ export function installLegacyGlobalProxyBoundary(ctx, config = {}, options = {})
     })
   }
 
-  globalThis.fetch = scopedFetch
+  const restoreFetch = installFetchWrapper(scopedFetch)
   let disposed = false
   const dispose = () => {
     if (disposed) return
     disposed = true
     active = false
     void dispatcherPool.dispose()
-    if (globalThis.fetch === scopedFetch) globalThis.fetch = originalFetch
+    restoreFetch()
   }
   if (typeof ctx?.effect === 'function') {
     try {

package/lib/pi-ai-bridge-wire-compat.js

@@ -1,3 +1,4 @@
+import { captureFetchDelegate, installFetchWrapper } from './fetch-wrapper-lifecycle.js'
 import { currentVisionSessionAffinityId } from './session-affinity-runtime.js'
 import { isOfficialOpenCodeGoUrl, openCodeSessionAffinityHeaderForUrl } from './session-affinity.js'
 
@@ -283,7 +284,7 @@ export function applyPiAiBridgeWireFacts(init, body, facts) {
  * wrapper even if another later patch sits above it in the fetch chain.
  */
 export function installPiAiBridgeWireCompat(ctx, logger) {
-  const original = globalThis.fetch
+  const original = captureFetchDelegate()
   if (typeof original !== 'function') return () => {}
   let active = true
   const wrapped = async (input, init) => {
@@ -334,10 +335,10 @@ export function installPiAiBridgeWireCompat(ctx, logger) {
     }
     return Reflect.apply(original, globalThis, [input, patchedInit])
   }
-  globalThis.fetch = wrapped
+  const restoreFetch = installFetchWrapper(wrapped)
   const cleanup = () => {
     active = false
-    if (globalThis.fetch === wrapped) globalThis.fetch = original
+    restoreFetch()
   }
   try {
     ctx?.effect?.(() => cleanup, 'vision-router: pi-ai bridge wire compatibility')

package/lib/pixel-diff-stream.js

@@ -37,12 +37,18 @@ class AsyncByteReader {
 function cellBounds(index, width, height, cols, rows) {
   const cx = index % cols
   const cy = Math.floor(index / cols)
-  const cw = Math.ceil(width / cols)
-  const ch = Math.ceil(height / rows)
-  const x1 = cx * cw
-  const y1 = cy * ch
-  const x2 = Math.min((cx + 1) * cw, width)
-  const y2 = Math.min((cy + 1) * ch, height)
+  // Uniform boundaries mirror the counting map floor(x * cells / extent)
+  // exactly: with cells <= extent (the grid clamp above guarantees it),
+  // ceil(c * extent / cells) rises by at least 1 per cell, so every cell is
+  // non-empty and every pixel lands inside the cell the counters credited
+  // it to. The previous ceil-stride bounds drifted from that map whenever
+  // extent was not a multiple of cells, shifting worst-region boxes and, on
+  // tiny extents, dropping counted pixels from cells whose bounds collapsed
+  // to zero width.
+  const x1 = Math.ceil((cx * width) / cols)
+  const y1 = Math.ceil((cy * height) / rows)
+  const x2 = Math.ceil(((cx + 1) * width) / cols)
+  const y2 = Math.ceil(((cy + 1) * height) / rows)
   return { x1, y1, x2, y2, total: Math.max(0, x2 - x1) * Math.max(0, y2 - y1) }
 }
 

package/lib/public-entry.js

@@ -7,6 +7,10 @@ import {
   installVisionProviderTransport,
 } from './vision-provider-transport.js'
 import { installLegacyGlobalProxyBoundary } from './legacy-global-proxy-boundary.js'
+import { installDsh017SettingsCompatibility } from './dsh-settings-017-compat.js'
+import { installDsh017RootLocalSettingsTransport } from './web/dsh-settings-017-root-transport.js'
+import { installSettings017ClientCompatibility } from './settings-client-017-compat.js'
+import { installVisionRouterMessageSourceBoundary } from './session-message-source-compat.js'
 
 export * from '../entry.js'
 
@@ -33,7 +37,23 @@ function liveVisionConfig(ctx, fallback) {
  * settings therefore leave DSH/Host as the sole network authority.
  */
 export function apply(ctx, config = {}) {
-  const hardening = createVisionToggleRootHardening(ctx, config)
+  // DSH 0.1.7 replaces SettingsProvider.register() with profile-owned
+  // ConfigEditor writes for ordinary fields. Feature-detect that exact contract
+  // and present DVR's mature settings face without changing older Hosts.
+  const settingsCtx = installDsh017SettingsCompatibility(ctx, config, {
+    namespace: 'vision-router',
+    Config: base.Config,
+  })
+  // The 0.1.7 browser no longer exposes settingsScope. Keep the server route on
+  // the application root so ConfigEditor reconciliation cannot dispose an
+  // in-flight Settings POST, while each DVR generation supplies the live facade.
+  installDsh017RootLocalSettingsTransport(settingsCtx)
+  installSettings017ClientCompatibility(settingsCtx)
+  // Session V3 and V4 disagree on plugin message attribution. Normalize only
+  // DVR-authored contexts at the final hook-publication seam using the Session's
+  // own durable header version, never a DSH package-version guess.
+  const sessionSourceCtx = installVisionRouterMessageSourceBoundary(settingsCtx)
+  const hardening = createVisionToggleRootHardening(sessionSourceCtx, config)
   const runtimeCtx = contextWithVisionRoutingTopologyRefresh(hardening.ctx)
   const transport = createVisionProviderTransport({
     ctx: hardening.ctx,

package/lib/session-message-source-compat.js

@@ -0,0 +1,92 @@
+const LEGACY_SOURCE = Object.freeze({ kind: 'plugin', plugin: 'dsh-vision-router' })
+const PRODUCER_SOURCE = Object.freeze({ kind: 'plugin:dsh-vision-router' })
+
+function sourceKindForSession(session) {
+  const version = Number(session?.header?.version)
+  return Number.isInteger(version) && version >= 4 ? PRODUCER_SOURCE : LEGACY_SOURCE
+}
+
+function isVisionRouterSource(source) {
+  return !!source && typeof source === 'object' && !Array.isArray(source) && (
+    (source.kind === 'plugin' && source.plugin === 'dsh-vision-router') ||
+    source.kind === 'plugin:dsh-vision-router'
+  )
+}
+
+/** Return the canonical DVR message source for one live Session format. */
+export function visionRouterMessageSource(session) {
+  return { ...sourceKindForSession(session) }
+}
+
+/** Normalize one DVR-authored message without touching user/model/tool sources. */
+export function normalizeVisionRouterMessageSource(message, session) {
+  if (!message || typeof message !== 'object' || Array.isArray(message)) return message
+  if (!isVisionRouterSource(message.source)) return message
+  const source = sourceKindForSession(session)
+  if (message.source.kind === source.kind
+      && (source.kind !== 'plugin' || message.source.plugin === source.plugin)
+      && Object.keys(message.source).length === Object.keys(source).length) {
+    return message
+  }
+  return { ...message, source: { ...source } }
+}
+
+function normalizeMessageList(list, session) {
+  if (!Array.isArray(list)) return list
+  let changed = false
+  const next = list.map((message) => {
+    const normalized = normalizeVisionRouterMessageSource(message, session)
+    if (normalized !== message) changed = true
+    return normalized
+  })
+  return changed ? next : list
+}
+
+function normalizePreStepResult(result, payload) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return result
+  const messages = normalizeMessageList(result.messages, payload?.agent?.session)
+  return messages === result.messages ? result : { ...result, messages }
+}
+
+function normalizePostExecuteResult(result, exec) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return result
+  const additionalContexts = normalizeMessageList(result.additionalContexts, exec?.agent?.session)
+  return additionalContexts === result.additionalContexts ? result : { ...result, additionalContexts }
+}
+
+function normalizeHookResult(event, args, result) {
+  if (event === 'agent/pre-step') return normalizePreStepResult(result, args[0])
+  if (event === 'tools/post-execute') return normalizePostExecuteResult(result, args[0])
+  return result
+}
+
+/**
+ * DSH Session V3 requires the historical {kind:'plugin', plugin:...} source,
+ * while V4 rejects that wrapper in favor of producer-owned source kinds. Keep
+ * every existing DVR message producer unchanged and normalize at the final
+ * hook publication boundary using the Session's own durable header version.
+ */
+export function installVisionRouterMessageSourceBoundary(ctx) {
+  if (!ctx || typeof ctx !== 'object') return ctx
+  return 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/pre-step' && event !== 'tools/post-execute') || typeof handler !== 'function') {
+          return on.call(target, event, handler, ...rest)
+        }
+        return on.call(target, event, function sourceCompatibleHook(...args) {
+          const output = handler.apply(this, args)
+          return output && typeof output.then === 'function'
+            ? output.then((value) => normalizeHookResult(event, args, value))
+            : normalizeHookResult(event, args, output)
+        }, ...rest)
+      }
+    },
+  })
+}