dsh-vision-router 2.2.8 → 3.0.0

package/lib/session-vision-mode-authority.js

@@ -1,164 +1,192 @@
-import { AsyncLocalStorage } from 'node:async_hooks'
-
-const VISION_ROUTER_ADAPTER_OWNER = Symbol.for('dsh-vision-router.adapter-owner')
-const VISION_ROUTER_OWNERSHIP = 'vision-router-owned'
-const DEFAULT_WRAPPER_ROUTE = 'deepseek-vision'
-const DEFAULT_CHAIN_ROUTE = 'vision-chain'
-const DEEPSEEK_SOURCE = 'deepseek-official'
-
-const authorityTurn = new AsyncLocalStorage()
-const agentAuthorities = new WeakMap()
-const assemblyAuthorities = new WeakMap()
-
-function isObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-}
-
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { parseSessionVisionPolicy } from './session-vision-policy.js';
+const VISION_ROUTER_ADAPTER_OWNER = Symbol.for('dsh-vision-router.adapter-owner');
+const VISION_ROUTER_OWNERSHIP = 'vision-router-owned';
+const DEFAULT_WRAPPER_ROUTE = 'deepseek-vision';
+const DEFAULT_CHAIN_ROUTE = 'vision-chain';
+const DEEPSEEK_SOURCE = 'deepseek-official';
+const authorityTurn = new AsyncLocalStorage();
+const agentAuthorities = new WeakMap();
+const assemblyAuthorities = new WeakMap();
+function objectRecord(value) {
+    return value !== null && (typeof value === 'object' || typeof value === 'function')
+        ? value
+        : undefined;
+}
+function property(value, key) {
+    return objectRecord(value)?.[key];
+}
 function isWeakKey(value) {
-  return (typeof value === 'object' && value !== null) || typeof value === 'function'
+    return (typeof value === 'object' && value !== null) || typeof value === 'function';
 }
-
 function routeFrom(value) {
-  if (!isObject(value)) return undefined
-  const provider = typeof value.provider === 'string' ? value.provider.trim() : ''
-  const model = typeof value.model === 'string' ? value.model.trim() : ''
-  return provider !== '' && model !== '' ? { provider, model } : undefined
+    const record = objectRecord(value);
+    if (!record || Array.isArray(value))
+        return undefined;
+    const provider = typeof record.provider === 'string' ? record.provider.trim() : '';
+    const model = typeof record.model === 'string' ? record.model.trim() : '';
+    return provider !== '' && model !== '' ? { provider, model } : undefined;
+}
+function contextGet(ctx, name) {
+    const record = objectRecord(ctx);
+    const get = record?.get;
+    if (typeof get !== 'function')
+        return undefined;
+    try {
+        return get.call(ctx, name);
+    }
+    catch {
+        return undefined;
+    }
 }
-
 function selectionProjection(ctx, session) {
-  let projections
-  try {
-    projections = ctx?.sessionProjections
-  } catch {
-    projections = undefined
-  }
-  if (!projections) {
+    // sessionProjections is an optional Host capability, not a declared plugin
+    // dependency. Cordis service properties throw when read outside inject(), so
+    // capability detection must use Context#get rather than property access.
+    const projections = contextGet(ctx, 'sessionProjections');
+    const stateOf = property(projections, 'stateOf');
+    if (typeof stateOf !== 'function')
+        return undefined;
     try {
-      projections = ctx?.get?.('sessionProjections')
-    } catch {
-      projections = undefined
-    }
-  }
-  if (!projections || typeof projections.stateOf !== 'function') return undefined
-  try {
-    const state = projections.stateOf(session, 'modelSelection')
-    if (!isObject(state)) return undefined
-    return routeFrom(state.pending ?? state.next ?? state.lastUsed)
-  } catch {
-    return undefined
-  }
-}
-
+        const state = stateOf.call(projections, session, 'modelSelection');
+        const record = objectRecord(state);
+        if (!record || Array.isArray(state))
+            return undefined;
+        return routeFrom(record.pending ?? record.next ?? record.lastUsed);
+    }
+    catch {
+        return undefined;
+    }
+}
 function fallbackRoute(session, agent) {
-  try {
-    const header = typeof session?.requestHeader === 'function' ? session.requestHeader() : undefined
-    const direct = routeFrom(header?.config)
-    if (direct) return direct
-  } catch {
-    // Cold or partially restored Sessions may not expose a request header yet.
-  }
-
-  const candidates = [
-    agent?.options?.config,
-    agent?.options,
-    agent?.config,
-    session?.agent?.options?.config,
-    session?.agent?.options,
-    session?.options?.config,
-    session?.options,
-    session?.config,
-    session?.header?.config,
-    session?.header,
-  ]
-  for (const candidate of candidates) {
-    const route = routeFrom(candidate)
-    if (route) return route
-  }
-  return undefined
-}
-
+    try {
+        const requestHeader = property(session, 'requestHeader');
+        const header = typeof requestHeader === 'function'
+            ? requestHeader.call(session)
+            : undefined;
+        const direct = routeFrom(property(header, 'config'));
+        if (direct)
+            return direct;
+    }
+    catch {
+        // Cold or partially restored Sessions may not expose a request header yet.
+    }
+    const agentOptions = property(agent, 'options');
+    const sessionAgent = property(session, 'agent');
+    const sessionAgentOptions = property(sessionAgent, 'options');
+    const sessionOptions = property(session, 'options');
+    const sessionHeader = property(session, 'header');
+    const candidates = [
+        property(agentOptions, 'config'),
+        agentOptions,
+        property(agent, 'config'),
+        property(sessionAgentOptions, 'config'),
+        sessionAgentOptions,
+        property(sessionOptions, 'config'),
+        sessionOptions,
+        property(session, 'config'),
+        property(sessionHeader, 'config'),
+        sessionHeader,
+    ];
+    for (const candidate of candidates) {
+        const route = routeFrom(candidate);
+        if (route)
+            return route;
+    }
+    return undefined;
+}
 export function effectiveSessionModelSelection(ctx, agent) {
-  const session = agent?.session
-  if (!session) return undefined
-  return selectionProjection(ctx, session) ?? fallbackRoute(session, agent)
+    const session = property(agent, 'session');
+    if (!session)
+        return undefined;
+    return selectionProjection(ctx, session) ?? fallbackRoute(session, agent);
 }
-
 function liveConfig(ctx, fallback) {
-  try {
-    const settings = ctx?.get?.('settings')
-    const value = settings?.get?.('vision-router')
-    if (isObject(value)) return value
-  } catch {
-    // Composition config remains authoritative while Settings is unavailable.
-  }
-  return isObject(fallback) ? fallback : {}
-}
-
+    try {
+        const settings = contextGet(ctx, 'settings');
+        const get = property(settings, 'get');
+        const value = typeof get === 'function'
+            ? get.call(settings, 'vision-router')
+            : undefined;
+        const record = objectRecord(value);
+        if (record && !Array.isArray(value))
+            return record;
+    }
+    catch {
+        // Composition config remains authoritative while Settings is unavailable.
+    }
+    const record = objectRecord(fallback);
+    return record && !Array.isArray(fallback) ? record : {};
+}
 function registrationLookup(ctx) {
-  const registration = ctx?.llm?.registration
-  return typeof registration === 'function' ? registration : undefined
+    const llm = property(ctx, 'llm');
+    const registration = property(llm, 'registration');
+    return typeof registration === 'function'
+        ? { owner: llm, lookup: registration }
+        : undefined;
 }
-
 function currentAdapter(ctx, provider) {
-  const registration = registrationLookup(ctx)
-  if (!registration) return undefined
-  try {
-    return registration.call(ctx.llm, provider)?.adapter
-  } catch {
-    return undefined
-  }
-}
-
+    const registration = registrationLookup(ctx);
+    if (!registration)
+        return undefined;
+    try {
+        return property(registration.lookup.call(registration.owner, provider), 'adapter');
+    }
+    catch {
+        return undefined;
+    }
+}
 function adapterOwnedByVisionRouter(adapter) {
-  if (!isWeakKey(adapter)) return false
-  try {
-    return adapter[VISION_ROUTER_ADAPTER_OWNER] !== undefined
-  } catch {
-    return false
-  }
-}
-
+    if (!isWeakKey(adapter))
+        return false;
+    try {
+        return objectRecord(adapter)?.[VISION_ROUTER_ADAPTER_OWNER] !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
 function sameRoute(left, right) {
-  return !!left && !!right && left.provider === right.provider && left.model === right.model
+    const rightRoute = routeFrom(right);
+    return !!left
+        && !!rightRoute
+        && left.provider === rightRoute.provider
+        && left.model === rightRoute.model;
 }
-
 function configuredRoute(config, key, fallback) {
-  const value = typeof config?.[key] === 'string' ? config[key].trim() : ''
-  return value || fallback
+    const value = typeof config[key] === 'string' ? config[key].trim() : '';
+    return value || fallback;
 }
-
 function routeOwnedByVisionRouter(ctx, route, config, visionPolicy) {
-  if (!route) return false
-
-  const registration = registrationLookup(ctx)
-  if (registration) {
-    // On current DSH, the final Host-visible adapter marker is authoritative.
-    // If the configured route was replaced by a foreign adapter, fail closed
-    // rather than granting mode from a matching route name.
-    return adapterOwnedByVisionRouter(currentAdapter(ctx, route.provider))
-  }
-
-  // Minimum Host shims may not expose registration(). Native-image-coexistence
-  // already proved exact registration ownership for the same selected route;
-  // accept only that turn-local proof, never a generic -vision suffix.
-  if (
-    visionPolicy?.ownership === VISION_ROUTER_OWNERSHIP &&
-    sameRoute(route, visionPolicy.route)
-  ) {
-    return true
-  }
-
-  // Compatibility fallback for explicit historical routes only when the Host
-  // offers no registration identity at all. Current DSH never reaches this.
-  const wrapperRoute = configuredRoute(config, 'wrapperRoute', DEFAULT_WRAPPER_ROUTE)
-  const chainRoute = configuredRoute(config, 'chainRoute', DEFAULT_CHAIN_ROUTE)
-  if (route.provider === wrapperRoute || route.provider === chainRoute || route.provider === 'vision-http') {
-    return true
-  }
-  if (config?.stealth === true && route.provider === DEEPSEEK_SOURCE) return true
-  return false
-}
-
+    if (!route)
+        return false;
+    const registration = registrationLookup(ctx);
+    if (registration) {
+        // On current DSH, the final Host-visible adapter marker is authoritative.
+        // If the configured route was replaced by a foreign adapter, fail closed
+        // rather than granting mode from a matching route name.
+        return adapterOwnedByVisionRouter(currentAdapter(ctx, route.provider));
+    }
+    // Minimum Host shims may not expose registration(). Native-image-coexistence
+    // already proved exact registration ownership for the same selected route;
+    // accept only that turn-local proof, never a generic -vision suffix.
+    if (property(visionPolicy, 'ownership') === VISION_ROUTER_OWNERSHIP
+        && sameRoute(route, property(visionPolicy, 'route'))) {
+        return true;
+    }
+    // Compatibility fallback for explicit historical routes only when the Host
+    // offers no registration identity at all. Current DSH never reaches this.
+    const wrapperRoute = configuredRoute(config, 'wrapperRoute', DEFAULT_WRAPPER_ROUTE);
+    const chainRoute = configuredRoute(config, 'chainRoute', DEFAULT_CHAIN_ROUTE);
+    if (route.provider === wrapperRoute
+        || route.provider === chainRoute
+        || route.provider === 'vision-http') {
+        return true;
+    }
+    if (config.stealth === true && route.provider === DEEPSEEK_SOURCE)
+        return true;
+    return false;
+}
 /**
  * Resolve the one authoritative Vision-mode snapshot for the next Agent step.
  *
@@ -168,36 +196,46 @@ function routeOwnedByVisionRouter(ctx, route, config, visionPolicy) {
  * This prevents a stale ON header from granting tools after the user switched
  * Vision off (and the inverse when turning it back on).
  */
-export function resolveSessionVisionModeAuthority(
-  ctx,
-  agent,
-  fallbackConfig = {},
-  options = {},
-) {
-  const route = effectiveSessionModelSelection(ctx, agent)
-  const config = liveConfig(ctx, fallbackConfig)
-  const enabled = routeOwnedByVisionRouter(ctx, route, config, options.visionPolicy)
-  return Object.freeze({
-    enabled,
-    route: route ? Object.freeze({ ...route }) : undefined,
-    reason: enabled ? 'vision-router-route' : route ? 'ordinary-route' : 'unknown-route',
-    ...(options.turn === undefined ? {} : { turn: options.turn }),
-  })
-}
-
+export function resolveSessionVisionModeAuthority(ctx, agent, fallbackConfig = {}, options = {}) {
+    const route = routeFrom(options.route) ?? effectiveSessionModelSelection(ctx, agent);
+    const sessionPolicy = parseSessionVisionPolicy(options.sessionPolicy);
+    const config = liveConfig(ctx, fallbackConfig);
+    const routeEnabled = routeOwnedByVisionRouter(ctx, route, config, options.visionPolicy);
+    const enabled = sessionPolicy?.enabled ?? routeEnabled;
+    return Object.freeze({
+        enabled,
+        route: route ? Object.freeze({ ...route }) : undefined,
+        reason: sessionPolicy !== undefined
+            ? 'session-policy'
+            : routeEnabled
+                ? 'vision-router-route'
+                : route
+                    ? 'ordinary-route'
+                    : 'unknown-route',
+        ...(options.turn === undefined ? {} : { turn: options.turn }),
+    });
+}
 function normalizedAuthority(authority) {
-  return isObject(authority)
-    ? authority
-    : Object.freeze({ enabled: false, reason: 'unknown-route' })
+    const record = objectRecord(authority);
+    if (record && !Array.isArray(authority)) {
+        // Compatibility callers already provide the immutable authority envelope.
+        // Preserve that exact snapshot rather than rebuilding it and changing
+        // historical property-presence semantics.
+        return authority;
+    }
+    return Object.freeze({
+        enabled: false,
+        route: undefined,
+        reason: 'unknown-route',
+    });
 }
-
 /** Persist the immutable authority for the currently entered step. */
 export function rememberSessionVisionModeAuthorityForAgent(authority, agent) {
-  const snapshot = normalizedAuthority(authority)
-  if (isWeakKey(agent)) agentAuthorities.set(agent, snapshot)
-  return snapshot
+    const snapshot = normalizedAuthority(authority);
+    if (isWeakKey(agent))
+        agentAuthorities.set(agent, snapshot);
+    return snapshot;
 }
-
 /**
  * Stage the authority captured by prompt assembly for exactly the immediately
  * following pre-step. Keeping this separate from the active-step snapshot is
@@ -205,40 +243,37 @@ export function rememberSessionVisionModeAuthorityForAgent(authority, agent) {
  * and an old completed-step snapshot must never masquerade as a new assembly.
  */
 export function rememberSessionVisionModeAssemblyAuthorityForAgent(authority, agent) {
-  const snapshot = normalizedAuthority(authority)
-  if (isWeakKey(agent)) assemblyAuthorities.set(agent, snapshot)
-  return snapshot
+    const snapshot = normalizedAuthority(authority);
+    if (isWeakKey(agent))
+        assemblyAuthorities.set(agent, snapshot);
+    return snapshot;
 }
-
 /** Consume at most one prompt-assembly snapshot for the following pre-step. */
 export function takeSessionVisionModeAssemblyAuthorityForAgent(agent) {
-  if (!isWeakKey(agent)) return undefined
-  const snapshot = assemblyAuthorities.get(agent)
-  assemblyAuthorities.delete(agent)
-  return snapshot
+    if (!isWeakKey(agent))
+        return undefined;
+    const snapshot = assemblyAuthorities.get(agent);
+    assemblyAuthorities.delete(agent);
+    return snapshot;
 }
-
 /** Store one immutable step snapshot and keep it ambient while Core assembles it. */
 export function runWithSessionVisionModeAuthority(authority, agent, callback) {
-  const snapshot = rememberSessionVisionModeAuthorityForAgent(authority, agent)
-  return authorityTurn.run({ authority: snapshot }, callback)
+    const snapshot = rememberSessionVisionModeAuthorityForAgent(authority, agent);
+    return authorityTurn.run({ authority: snapshot }, callback);
 }
-
 export function currentSessionVisionModeAuthority() {
-  return authorityTurn.getStore()?.authority
+    return authorityTurn.getStore()?.authority;
 }
-
 export function sessionVisionModeAuthorityForAgent(agent) {
-  return isWeakKey(agent) ? agentAuthorities.get(agent) : undefined
+    return isWeakKey(agent) ? agentAuthorities.get(agent) : undefined;
 }
-
 /** Drop completed/abandoned step and staged assembly snapshots. */
 export function clearSessionVisionModeAuthorityForAgent(agent) {
-  if (!isWeakKey(agent)) return
-  agentAuthorities.delete(agent)
-  assemblyAuthorities.delete(agent)
+    if (!isWeakKey(agent))
+        return;
+    agentAuthorities.delete(agent);
+    assemblyAuthorities.delete(agent);
 }
-
 /**
  * Execution-time fail-closed check. Real Agent steps use the prompt-assembly
  * snapshot after pre-step promotes it to the active step, so a concurrent
@@ -246,9 +281,11 @@ export function clearSessionVisionModeAuthorityForAgent(agent) {
  * current request in half. Direct/internal calls with an Agent but no captured
  * step resolve the live DSH selection synchronously.
  */
-export function visionModeEnabledForAgent(ctx, agent, fallbackConfig = {}) {
-  if (!isWeakKey(agent)) return true
-  const snapshot = agentAuthorities.get(agent)
-  if (snapshot) return snapshot.enabled === true
-  return resolveSessionVisionModeAuthority(ctx, agent, fallbackConfig).enabled === true
+export function visionModeEnabledForAgent(ctx, agent, fallbackConfig = {}, options = {}) {
+    if (!isWeakKey(agent))
+        return true;
+    const snapshot = agentAuthorities.get(agent);
+    if (snapshot)
+        return snapshot.enabled === true;
+    return resolveSessionVisionModeAuthority(ctx, agent, fallbackConfig, options).enabled === true;
 }

package/lib/session-vision-mode-boundary.js

@@ -1,4 +1,5 @@
 import { currentSessionVisionPolicy } from './native-image-coexistence.js'
+import { userSessionVisionPolicy } from './session-vision-policy.js'
 import {
   clearSessionVisionModeAuthorityForAgent,
   rememberSessionVisionModeAssemblyAuthorityForAgent,
@@ -245,7 +246,7 @@ function projectAssemblyTools(assembly, enabled, owned) {
   return { ...assembly, tools }
 }
 
-function wrapTools(tools, ctx, config, owned) {
+function wrapTools(tools, ctx, config, owned, sessionPolicyForAgent) {
   if (!isObject(tools)) return tools
   return new Proxy(tools, {
     get(target, property) {
@@ -272,7 +273,12 @@ function wrapTools(tools, ctx, config, owned) {
           async execute(args, exec) {
             if (
               exec?.agent &&
-              !visionModeEnabledForAgent(ctx, exec.agent, liveConfig(ctx, config))
+              !visionModeEnabledForAgent(
+                ctx,
+                exec.agent,
+                liveConfig(ctx, config),
+                { sessionPolicy: sessionPolicyForAgent(exec.agent) },
+              )
             ) {
               throw visionModeDisabledError(definition.name)
             }
@@ -322,19 +328,47 @@ function wrapTools(tools, ctx, config, owned) {
  * It deliberately lives outside the retired legacy-core policy bridge, whose
  * identity-only closure contract remains frozen.
  */
-export function installSessionVisionModeBoundary(ctx, config = {}) {
+export function installSessionVisionModeBoundary(ctx, config = {}, runtime = {}) {
   if (!isObject(ctx)) return { ctx, config }
   const restrictions = new WeakMap()
   const activeRestrictions = new Set()
   const assemblySnapshots = new WeakMap()
   const ownedVisionTools = new Map()
+  const sessionVisionPolicyStore = runtime?.sessionVisionPolicyStore
   let toolsView
 
+  // This boundary can install Agent-scoped restrictions whose lifetime exceeds
+  // the plugin generation. Establish the generation owner before registering
+  // prompt/event hooks that can ever create those restrictions.
+  try {
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(
+        () => () => releaseAllAgentToolRestrictions(activeRestrictions),
+        'vision-router: Session Vision restriction lifecycle',
+      )
+    }
+  } catch {
+    return { ctx, config }
+  }
+
+  const sessionPolicyForAgent = (agent) => {
+    const id = typeof agent?.id === 'string' ? agent.id : ''
+    if (id === '' || typeof sessionVisionPolicyStore?.get !== 'function') return undefined
+    try {
+      return sessionVisionPolicyStore.get(id)
+    } catch {
+      return undefined
+    }
+  }
+
   const resolveForAgent = (agent, options = {}) => resolveSessionVisionModeAuthority(
     ctx,
     agent,
     liveConfig(ctx, config),
-    options,
+    {
+      ...options,
+      sessionPolicy: options.sessionPolicy ?? sessionPolicyForAgent(agent),
+    },
   )
 
   const clearAgent = (agent) => {
@@ -381,7 +415,7 @@ export function installSessionVisionModeBoundary(ctx, config = {}) {
   // Code Mode's tools:sdk are generated for real Agent-loop assemblies. The
   // returned variable is unused and never reaches the model.
   try {
-    const systemPrompt = ctx?.systemPrompt ?? ctx?.get?.('systemPrompt')
+    const systemPrompt = ctx?.get?.('systemPrompt')
     if (typeof systemPrompt?.variable === 'function') {
       systemPrompt.variable(MODE_SYNC_VARIABLE, (context) => {
         captureForAssembly(context)
@@ -437,27 +471,34 @@ export function installSessionVisionModeBoundary(ctx, config = {}) {
     ctx.on?.('agent/disposed', ({ agent }) => {
       clearAgent(agent)
       releaseAgentToolRestriction(agent, restrictions, activeRestrictions)
+      const id = typeof agent?.id === 'string' ? agent.id : ''
+      if (id !== '') {
+        try { sessionVisionPolicyStore?.release?.(id) } catch {}
+      }
     })
-  } catch {
-    // Minimum Hosts may not expose every lifecycle event. Prompt assembly and
-    // execution guards preserve the safety boundary without making apply fail.
-  }
 
-  // tools.restrict() is invoked through the long-lived Agent scope so its
-  // disposer belongs to that scope, not to this plugin fiber. A Settings/HMR
-  // recompose can therefore retire this boundary while the Agent survives. If
-  // we do not release those masks here, the next boundary generation cannot
-  // discover or dispose the old WeakMap entries and Vision tools stay hidden
-  // even after the Session selects a Router-owned route again.
-  try {
-    if (typeof ctx.effect === 'function') {
-      ctx.effect(
-        () => () => releaseAllAgentToolRestrictions(activeRestrictions),
-        'vision-router: Session Vision restriction lifecycle',
+    // DSH persists explicit composer/model-picker intent as model/selection.
+    // Materialize the matching DVR Session authority from that exact durable
+    // event so a delegated snapshot can always be overridden by a later user
+    // choice. Route-derived compatibility remains the fallback until a Session
+    // has made an explicit selection.
+    ctx.on?.('session/event', (session, event) => {
+      if (event?.type !== 'model/selection') return
+      const id = typeof session?.id === 'string' ? session.id : ''
+      if (id === '' || typeof sessionVisionPolicyStore?.set !== 'function') return
+      const authority = resolveSessionVisionModeAuthority(
+        ctx,
+        { id, session },
+        liveConfig(ctx, config),
+        { route: event.data },
       )
-    }
+      void sessionVisionPolicyStore
+        .set(id, userSessionVisionPolicy(authority.enabled))
+        .catch(() => {})
+    })
   } catch {
-    // Agent disposal / live enable transitions still release their own masks.
+    // Minimum Hosts may not expose every lifecycle event. Prompt assembly and
+    // execution guards preserve the safety boundary without making apply fail.
   }
 
   const wrapped = new Proxy(ctx, {
@@ -469,6 +510,7 @@ export function installSessionVisionModeBoundary(ctx, config = {}) {
             target,
             config,
             ownedVisionTools,
+            sessionPolicyForAgent,
           )
         }
         return toolsView
@@ -493,6 +535,7 @@ export function installSessionVisionModeBoundary(ctx, config = {}) {
                 {
                   turn: payload?.turn,
                   visionPolicy: currentSessionVisionPolicy(),
+                  sessionPolicy: sessionPolicyForAgent(agent),
                 },
               )
             syncAgentToolRestriction(