dsh-vision-router 2.3.0 → 3.0.1

package/lib/public-entry.js

@@ -34,6 +34,16 @@ function liveVisionConfig(ctx, fallback) {
  * settings therefore leave DSH/Host as the sole network authority.
  */
 export function apply(ctx, config = {}) {
+  // Cordis effect() is a required plugin-fiber primitive across the entire
+  // supported DSH window, not an optional capability. Refuse malformed/partial
+  // Hosts before any DVR route, wrapper, transport, watcher or global mutation
+  // can be published without a lifecycle owner.
+  let effect
+  try { effect = ctx?.effect } catch (error) { throw error }
+  if (typeof effect !== 'function') {
+    throw new TypeError('vision-router requires a Cordis lifecycle context with effect()')
+  }
+
   // 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.
@@ -57,13 +67,16 @@ export function apply(ctx, config = {}) {
     config: () => liveVisionConfig(hardening.ctx, config),
   })
   let transportReleased = false
+  let transportReleasePromise
   const releaseTransport = () => {
-    if (transportReleased) return
+    if (transportReleasePromise) return transportReleasePromise
+    if (transportReleased) return Promise.resolve()
     transportReleased = true
-    void transport.dispose()
+    transportReleasePromise = Promise.resolve().then(() => transport.dispose())
+    return transportReleasePromise
   }
   try {
-    runtimeCtx?.effect?.(
+    runtimeCtx.effect(
       () => releaseTransport,
       'vision-router: provider transport',
     )
@@ -72,7 +85,7 @@ export function apply(ctx, config = {}) {
     hardening.installClientBoundary()
     return result
   } catch (error) {
-    releaseTransport()
+    void releaseTransport().catch(() => {})
     throw error
   }
 }

package/lib/replay-delegation.js

@@ -548,15 +548,20 @@ export function contextWithDelegatedReplay(ctx, options = {}) {
     },
   })
   wrappedContexts.set(ctx, wrapped)
+  let lifecycleOwned = false
   try {
-    ctx.effect?.(
-      () => () => {
-        if (wrappedContexts.get(ctx) === wrapped) wrappedContexts.delete(ctx)
-      },
-      'vision-router: delegated replay context lifecycle',
-    )
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(
+        () => () => {
+          if (wrappedContexts.get(ctx) === wrapped) wrappedContexts.delete(ctx)
+        },
+        'vision-router: delegated replay context lifecycle',
+      )
+      lifecycleOwned = true
+    }
   } catch {
-    /* lifecycle hardening must not block plugin apply */
+    // The current caller may still use this private view.
   }
+  if (!lifecycleOwned && wrappedContexts.get(ctx) === wrapped) wrappedContexts.delete(ctx)
   return wrapped
 }

package/lib/replay-envelope-v2-compat.js

@@ -88,15 +88,20 @@ export function contextWithReplayEnvelopeV2Compat(ctx) {
     },
   })
   wrappedContexts.set(ctx, wrapped)
+  let lifecycleOwned = false
   try {
-    ctx.effect?.(
-      () => () => {
-        if (wrappedContexts.get(ctx) === wrapped) wrappedContexts.delete(ctx)
-      },
-      'vision-router: rc7 replay envelope compatibility lifecycle',
-    )
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(
+        () => () => {
+          if (wrappedContexts.get(ctx) === wrapped) wrappedContexts.delete(ctx)
+        },
+        'vision-router: rc7 replay envelope compatibility lifecycle',
+      )
+      lifecycleOwned = true
+    }
   } catch {
-    /* lifecycle hardening must not block plugin apply */
+    // The current caller can still use this one-shot compatibility view.
   }
+  if (!lifecycleOwned && wrappedContexts.get(ctx) === wrapped) wrappedContexts.delete(ctx)
   return wrapped
 }

package/lib/runtime-composition.js

@@ -17,6 +17,9 @@ import { createSessionVisionRuntime } from './session-vision-runtime.js'
 import { runCoreApplyLifecycle } from './core-apply-lifecycle.js'
 import { installLegacyCoreVisionPolicyBridge } from './legacy-core-vision-policy-bridge.js'
 import { installSessionVisionModeBoundary } from './session-vision-mode-boundary.js'
+import { resolveSessionVisionModeAuthority } from './session-vision-mode-authority.js'
+import { createSessionVisionPolicyRuntimeStore } from './session-vision-policy-domain.js'
+import { installSessionVisionDelegationBoundary } from './session-vision-delegation-boundary.js'
 import { installPiAiBridgeWireCompat } from './pi-ai-bridge-wire-compat.js'
 import { installLiveModelDiscovery } from './live-model-discovery.js'
 import { installVisionModelRegistry } from './vision-model-registry.js'
@@ -30,7 +33,6 @@ import { installLocalMutationRouteBoundary } from './web-capability-boundary.js'
 import { installScreenshotSourceBoundary } from './screenshot-source-boundary.js'
 import { installVisionToolRuntimeBoundary } from './vision-tool-runtime-boundary.js'
 import {
-  configureAgentRequestRouteAuthority,
   contextWithAgentRequestRouteAuthority,
 } from './agent-request-route-authority.js'
 import { contextWithGroundingCoordinateFrame } from './grounding-coordinate-runtime.js'
@@ -96,7 +98,7 @@ function legacyCoreVisionSettings(ctx, fallback) {
   return { ...current, autoActivateOnImage: false }
 }
 
-function installHostAndSecurityBoundaries(ctx, config, core) {
+function installHostAndSecurityBoundaries(ctx, config, core, providerTransport) {
   // SessionVisionIndex calls planGuardStopShadows before Core.apply. Keep that
   // one helper behind the live-locale facade; the final Core itself still gets
   // the ordinary composition identity and is localized by the scoped context.
@@ -135,11 +137,14 @@ function installHostAndSecurityBoundaries(ctx, config, core) {
     config,
     core,
   )
-  const ollamaColdStartCtx = installOllamaColdStartGuard(hardenedCtx, hardenedConfig, core)
+  const ollamaColdStartCtx = installOllamaColdStartGuard(hardenedCtx, hardenedConfig, core, {
+    logger: logging.logger,
+  })
   const { ctx: stabilizedCtx, bootConfig } = installLocalVisionStabilizer(
     ollamaColdStartCtx,
     hardenedConfig,
     core,
+    { providerTransport },
   )
 
   const routingProduct = resolveVisionRoutingProduct(bootConfig)
@@ -228,20 +233,35 @@ function createRuntimeOwners(host, core) {
     nativeImageCompat.config,
     { rewriteHistoryImages: core.rewriteHistoryImages },
   )
+  const sessionVisionPolicyStore = createSessionVisionPolicyRuntimeStore(legacyCoreCompat.ctx)
+  legacyCoreCompat.ctx.inject?.(['agents'], (agentsCtx) => {
+    installSessionVisionDelegationBoundary(
+      agentsCtx,
+      sessionVisionPolicyStore,
+      (parent) => resolveSessionVisionModeAuthority(
+        agentsCtx,
+        parent,
+        legacyCoreCompat.config,
+        { sessionPolicy: sessionVisionPolicyStore.get(String(parent.id)) },
+      ),
+    )
+  })
   const sessionVisionModeCompat = installSessionVisionModeBoundary(
     legacyCoreCompat.ctx,
     legacyCoreCompat.config,
+    { sessionVisionPolicyStore },
   )
 
   return {
     coreVisionSurfaceRuntime,
     nativeImageCompat,
     sessionVisionModeCompat,
+    sessionVisionPolicyStore,
     sessionVisionRuntime,
   }
 }
 
-function installRoutingAndHostProducts(host, owners, core) {
+function installRoutingAndHostProducts(host, owners, core, providerTransport) {
   const { capabilityStore, logging, runtimeConfig, runtimePerformanceStore } = host
   const { sessionVisionModeCompat } = owners
   // Final structured-flow guard sits closest to core.apply so it sees the
@@ -262,7 +282,7 @@ function installRoutingAndHostProducts(host, owners, core) {
     runtimeConfig,
     core,
     capabilityStore,
-    { logger: logging.logger },
+    { logger: logging.logger, providerTransport },
   )
   const sessionTurnResolver = createSessionTurnResolver(backgroundProfiling.ctx)
   const sessionEventTailReader = createSessionEventTailReader(backgroundProfiling.ctx)
@@ -377,12 +397,11 @@ function installExecutionBoundaries(host, owners, routing, core, providerTranspo
   // Core owns exactly one agent/request routing hook. Protect the completed
   // provider/model handoff at that event boundary so future route-switch logic
   // cannot accidentally carry source-model call defaults into the target.
-  configureAgentRequestRouteAuthority(backendRuntimeCtx, {
+  const coreRequestAuthorityCtx = contextWithAgentRequestRouteAuthority(backendRuntimeCtx, {
     wrapperRoute: runtimeConfig.wrapperRoute,
     chainRoute: runtimeConfig.chainRoute,
     logger: logging.logger,
   })
-  const coreRequestAuthorityCtx = contextWithAgentRequestRouteAuthority(backendRuntimeCtx)
 
   return { coreRequestAuthorityCtx }
 }
@@ -461,9 +480,10 @@ function applyMatureCoreBridge(host, owners, routing, execution, core, runtime)
 }
 
 export function applyVisionRuntimeComposition(ctx, config = {}, core, runtime = {}) {
-  const host = installHostAndSecurityBoundaries(ctx, config, core)
+  const providerTransport = runtime?.providerTransport
+  const host = installHostAndSecurityBoundaries(ctx, config, core, providerTransport)
   const owners = createRuntimeOwners(host, core)
-  const routing = installRoutingAndHostProducts(host, owners, core)
-  const execution = installExecutionBoundaries(host, owners, routing, core, runtime?.providerTransport)
+  const routing = installRoutingAndHostProducts(host, owners, core, providerTransport)
+  const execution = installExecutionBoundaries(host, owners, routing, core, providerTransport)
   return applyMatureCoreBridge(host, owners, routing, execution, core, runtime)
 }

package/lib/screenshot-source-boundary.js

@@ -110,7 +110,7 @@ function wrapTools(tools, ctx, core) {
 export function installScreenshotSourceBoundary(ctx, core) {
   if (!ctx || (typeof ctx !== 'object' && typeof ctx !== 'function')) return ctx
   const cached = wrappedContexts.get(ctx)
-  if (cached) return cached
+  if (cached?.core === core) return cached.wrapped
   let wrapped
   wrapped = new Proxy(ctx, {
     get(target, property) {
@@ -119,6 +119,6 @@ export function installScreenshotSourceBoundary(ctx, core) {
       return typeof value === 'function' ? value.bind(target) : value
     },
   })
-  wrappedContexts.set(ctx, wrapped)
+  wrappedContexts.set(ctx, { core, wrapped })
   return wrapped
 }

package/lib/session-affinity-runtime.js

@@ -1,104 +1,120 @@
-import { AsyncLocalStorage } from 'node:async_hooks'
-import { rawSessionIdentity } from './session-affinity.js'
-
-const affinityRuntime = new AsyncLocalStorage()
-
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { rawSessionIdentity } from './session-affinity.js';
+const affinityRuntime = new AsyncLocalStorage();
+function propertyBag(value) {
+    return value !== null && (typeof value === 'object' || typeof value === 'function')
+        ? value
+        : undefined;
+}
+function isPromiseLike(value) {
+    return typeof propertyBag(value)?.then === 'function';
+}
 export function currentVisionSessionAffinityId() {
-  const state = affinityRuntime.getStore()
-  return state?.active === true ? state.affinityId : undefined
+    const state = affinityRuntime.getStore();
+    return state?.active === true ? state.affinityId : undefined;
 }
-
 export function runWithVisionSessionAffinity(affinityId, callback) {
-  const raw = rawSessionIdentity(affinityId)
-  if (raw === undefined) return callback()
-  const state = { affinityId: raw, active: true }
-  let result
-  try {
-    result = affinityRuntime.run(state, callback)
-  } catch (error) {
-    state.active = false
-    throw error
-  }
-  if (result && typeof result.then === 'function') {
-    return Promise.resolve(result).finally(() => { state.active = false })
-  }
-  state.active = false
-  return result
+    const raw = rawSessionIdentity(affinityId);
+    if (raw === undefined)
+        return callback();
+    const state = {
+        affinityId: raw,
+        active: true,
+    };
+    let result;
+    try {
+        result = affinityRuntime.run(state, callback);
+    }
+    catch (error) {
+        state.active = false;
+        throw error;
+    }
+    if (isPromiseLike(result)) {
+        return Promise.resolve(result).finally(() => {
+            state.active = false;
+        });
+    }
+    state.active = false;
+    return result;
 }
-
-/**
- * Keep AsyncLocalStorage active across lazy AsyncIterable creation and every
- * iterator operation. Adapter/network work often begins on next(), not when
- * ctx.llm.stream() returns the iterable. Promise-returning test/compat streams
- * are supported too because some older seams resolve the iterable lazily.
- * One mutable state object is retired at stream completion so async work that
- * outlives the model request cannot keep projecting the conversation id.
- */
 export function streamWithVisionSessionAffinity(affinityId, streamFactory) {
-  const raw = rawSessionIdentity(affinityId)
-  if (raw === undefined) return streamFactory()
-  return {
-    [Symbol.asyncIterator]() {
-      const state = { affinityId: raw, active: true }
-      let iteratorPromise
-      const retire = () => { state.active = false }
-      const ensure = () => {
-        if (iteratorPromise === undefined) {
-          iteratorPromise = affinityRuntime.run(state, async () => {
-            const stream = await streamFactory()
-            if (!stream || typeof stream[Symbol.asyncIterator] !== 'function') {
-              throw new TypeError('scoped vision stream is not async iterable')
-            }
-            return stream[Symbol.asyncIterator]()
-          })
-        }
-        return iteratorPromise
-      }
-      return {
-        next(value) {
-          return affinityRuntime.run(state, async () => {
-            try {
-              const result = await (await ensure()).next(value)
-              if (result?.done === true) retire()
-              return result
-            } catch (error) {
-              retire()
-              throw error
-            }
-          })
-        },
-        return(value) {
-          if (iteratorPromise === undefined) {
-            retire()
-            return Promise.resolve({ done: true, value })
-          }
-          return affinityRuntime.run(state, async () => {
-            try {
-              const active = await iteratorPromise
-              return typeof active.return === 'function'
-                ? await active.return(value)
-                : { done: true, value }
-            } finally {
-              retire()
-            }
-          })
-        },
-        throw(error) {
-          if (iteratorPromise === undefined) {
-            retire()
-            return Promise.reject(error)
-          }
-          return affinityRuntime.run(state, async () => {
-            try {
-              const active = await iteratorPromise
-              if (typeof active.throw === 'function') return await active.throw(error)
-              throw error
-            } finally {
-              retire()
-            }
-          })
+    const raw = rawSessionIdentity(affinityId);
+    if (raw === undefined)
+        return streamFactory();
+    return {
+        [Symbol.asyncIterator]() {
+            const state = {
+                affinityId: raw,
+                active: true,
+            };
+            let iteratorPromise;
+            const retire = () => {
+                state.active = false;
+            };
+            const ensure = () => {
+                if (iteratorPromise === undefined) {
+                    iteratorPromise = affinityRuntime.run(state, async () => {
+                        const stream = await streamFactory();
+                        if (stream === null
+                            || (typeof stream !== 'object' && typeof stream !== 'function')
+                            || typeof stream[Symbol.asyncIterator] !== 'function') {
+                            throw new TypeError('scoped vision stream is not async iterable');
+                        }
+                        return stream[Symbol.asyncIterator]();
+                    });
+                }
+                return iteratorPromise;
+            };
+            return {
+                next(value) {
+                    return affinityRuntime.run(state, async () => {
+                        try {
+                            const result = await (await ensure()).next(value);
+                            if (result?.done === true)
+                                retire();
+                            return result;
+                        }
+                        catch (error) {
+                            retire();
+                            throw error;
+                        }
+                    });
+                },
+                return(value) {
+                    if (iteratorPromise === undefined) {
+                        retire();
+                        return Promise.resolve({ done: true, value });
+                    }
+                    return affinityRuntime.run(state, async () => {
+                        try {
+                            const active = await ensure();
+                            return typeof active.return === 'function'
+                                ? await active.return(value)
+                                : { done: true, value };
+                        }
+                        finally {
+                            retire();
+                        }
+                    });
+                },
+                throw(error) {
+                    if (iteratorPromise === undefined) {
+                        retire();
+                        return Promise.reject(error);
+                    }
+                    return affinityRuntime.run(state, async () => {
+                        try {
+                            const active = await ensure();
+                            if (typeof active.throw === 'function')
+                                return await active.throw(error);
+                            throw error;
+                        }
+                        finally {
+                            retire();
+                        }
+                    });
+                },
+            };
         },
-      }
-    },
-  }
+    };
 }

package/lib/session-affinity.js

@@ -1,93 +1,106 @@
-const MAX_SESSION_AFFINITY_ID_LENGTH = 512
-
-/** Preserve DSH's in-process session identity exactly; no wire rules belong here. */
+const MAX_SESSION_AFFINITY_ID_LENGTH = 512;
+function propertyBag(value) {
+    return value !== null && (typeof value === 'object' || typeof value === 'function')
+        ? value
+        : undefined;
+}
+function wireAsciiIdentity(text) {
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        const edge = index === 0 || index === text.length - 1;
+        if (edge) {
+            if (code < 33 || code > 126)
+                return false;
+        }
+        else if (code < 32 || code > 126) {
+            return false;
+        }
+    }
+    return true;
+}
 export function rawSessionIdentity(value) {
-  if (value === undefined || value === null) return undefined
-  try {
-    return String(value)
-  } catch {
-    return undefined
-  }
+    if (value === undefined || value === null)
+        return undefined;
+    try {
+        return String(value);
+    }
+    catch {
+        return undefined;
+    }
 }
-
-/** Read the live DSH session id across released/alpha session shapes without rewriting it. */
 export function sessionIdentityOf(session) {
-  if (!session) return undefined
-  try {
-    const direct = rawSessionIdentity(session.id)
-    if (direct !== undefined) return direct
-  } catch {
-    /* continue to persisted/header shapes */
-  }
-  try {
-    const header = rawSessionIdentity(session.header?.id)
-    if (header !== undefined) return header
-  } catch {
-    /* continue to requestHeader() */
-  }
-  try {
-    if (typeof session.requestHeader === 'function') {
-      return rawSessionIdentity(session.requestHeader()?.id)
+    const source = propertyBag(session);
+    if (source === undefined)
+        return undefined;
+    try {
+        const direct = rawSessionIdentity(source.id);
+        if (direct !== undefined)
+            return direct;
     }
-  } catch {
-    /* no usable session identity */
-  }
-  return undefined
+    catch { }
+    try {
+        const header = rawSessionIdentity(propertyBag(source.header)?.id);
+        if (header !== undefined)
+            return header;
+    }
+    catch { }
+    try {
+        const requestHeader = source.requestHeader;
+        if (typeof requestHeader === 'function') {
+            return rawSessionIdentity(propertyBag(requestHeader.call(session))?.id);
+        }
+    }
+    catch { }
+    return undefined;
 }
-
-/**
- * Admit an opaque identity to an HTTP header without changing it. Fetch/undici
- * requires ByteString-compatible header values; use visible ASCII so behavior
- * is identical across Node 22/24 and HTTP implementations. Leading/trailing
- * whitespace is rejected because Headers would normalize it, violating the
- * requirement to preserve the DSH identity unchanged.
- */
 export function wireSessionAffinityId(value) {
-  const text = rawSessionIdentity(value)
-  if (text === undefined || text === '' || text.length > MAX_SESSION_AFFINITY_ID_LENGTH) return undefined
-  if (text.trim() !== text) return undefined
-  if (!/^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/.test(text)) return undefined
-  return text
+    const text = rawSessionIdentity(value);
+    if (text === undefined
+        || text === ''
+        || text.length > MAX_SESSION_AFFINITY_ID_LENGTH) {
+        return undefined;
+    }
+    if (text.trim() !== text)
+        return undefined;
+    return wireAsciiIdentity(text) ? text : undefined;
 }
-
 export function isOfficialOpenCodeGoUrl(value) {
-  try {
-    const url = new URL(String(value))
-    return (
-      url.protocol === 'https:' &&
-      url.hostname.toLowerCase() === 'opencode.ai' &&
-      /^\/zen\/go(?:\/|$)/i.test(url.pathname)
-    )
-  } catch {
-    return false
-  }
+    try {
+        const url = new URL(String(value));
+        return (url.protocol === 'https:'
+            && url.hostname.toLowerCase() === 'opencode.ai'
+            && /^\/zen\/go(?:\/|$)/i.test(url.pathname));
+    }
+    catch {
+        return false;
+    }
 }
-
 export function isOpenCodeGoProvider(provider) {
-  return isOfficialOpenCodeGoUrl(provider?.baseURL ?? provider?.baseUrl ?? '')
+    const source = propertyBag(provider);
+    return isOfficialOpenCodeGoUrl(source?.baseURL ?? source?.baseUrl ?? '');
 }
-
 function invalidAffinityError(sessionId) {
-  const raw = rawSessionIdentity(sessionId)
-  const error = new Error(
-    raw === undefined || raw === ''
-      ? 'OpenCode Go requires a stable session identity; refusing a direct request without one'
-      : 'OpenCode Go session identity is not safe for an HTTP header; refusing to rewrite or truncate it',
-  )
-  error.code = raw === undefined || raw === '' ? 'OPENCODE_SESSION_REQUIRED' : 'OPENCODE_SESSION_INVALID'
-  return error
+    const raw = rawSessionIdentity(sessionId);
+    const code = raw === undefined || raw === ''
+        ? 'OPENCODE_SESSION_REQUIRED'
+        : 'OPENCODE_SESSION_INVALID';
+    return Object.assign(new Error(code === 'OPENCODE_SESSION_REQUIRED'
+        ? 'OpenCode Go requires a stable session identity; refusing a direct request without one'
+        : 'OpenCode Go session identity is not safe for an HTTP header; refusing to rewrite or truncate it'), { code });
 }
-
 export function directSessionAffinityHeaders(provider, sessionId) {
-  if (!isOpenCodeGoProvider(provider)) return {}
-  const wire = wireSessionAffinityId(sessionId)
-  if (wire === undefined) throw invalidAffinityError(sessionId)
-  return { 'x-opencode-session': wire }
+    if (!isOpenCodeGoProvider(provider))
+        return {};
+    const wire = wireSessionAffinityId(sessionId);
+    if (wire === undefined)
+        throw invalidAffinityError(sessionId);
+    return { 'x-opencode-session': wire };
 }
-
 export function openCodeSessionAffinityHeaderForUrl(url, sessionId) {
-  if (!isOfficialOpenCodeGoUrl(url)) return undefined
-  const wire = wireSessionAffinityId(sessionId)
-  if (wire === undefined) throw invalidAffinityError(sessionId)
-  return wire
+    if (!isOfficialOpenCodeGoUrl(url))
+        return undefined;
+    const wire = wireSessionAffinityId(sessionId);
+    if (wire === undefined)
+        throw invalidAffinityError(sessionId);
+    return wire;
 }