dsh-vision-router 2.1.1 → 2.1.2

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

@@ -0,0 +1,254 @@
+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)
+}
+
+function isWeakKey(value) {
+  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
+}
+
+function selectionProjection(ctx, session) {
+  let projections
+  try {
+    projections = ctx?.sessionProjections
+  } catch {
+    projections = undefined
+  }
+  if (!projections) {
+    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
+  }
+}
+
+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
+}
+
+export function effectiveSessionModelSelection(ctx, agent) {
+  const session = 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 : {}
+}
+
+function registrationLookup(ctx) {
+  const registration = ctx?.llm?.registration
+  return typeof registration === 'function' ? 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
+  }
+}
+
+function adapterOwnedByVisionRouter(adapter) {
+  if (!isWeakKey(adapter)) return false
+  try {
+    return adapter[VISION_ROUTER_ADAPTER_OWNER] !== undefined
+  } catch {
+    return false
+  }
+}
+
+function sameRoute(left, right) {
+  return !!left && !!right && left.provider === right.provider && left.model === right.model
+}
+
+function configuredRoute(config, key, 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
+}
+
+/**
+ * Resolve the one authoritative Vision-mode snapshot for the next Agent step.
+ *
+ * The current DSH modelSelection projection is checked before requestHeader(),
+ * because a composer toggle writes a pending model/selection event for the next
+ * request while the last durable request header still names the previous route.
+ * 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 }),
+  })
+}
+
+function normalizedAuthority(authority) {
+  return isObject(authority)
+    ? authority
+    : Object.freeze({ enabled: false, 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
+}
+
+/**
+ * Stage the authority captured by prompt assembly for exactly the immediately
+ * following pre-step. Keeping this separate from the active-step snapshot is
+ * important: a minimum/test Host may call pre-step directly more than once,
+ * 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
+}
+
+/** 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
+}
+
+/** 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)
+}
+
+export function currentSessionVisionModeAuthority() {
+  return authorityTurn.getStore()?.authority
+}
+
+export function sessionVisionModeAuthorityForAgent(agent) {
+  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)
+}
+
+/**
+ * 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
+ * picker change applies to the next assembled step instead of tearing the
+ * 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
+}

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

@@ -0,0 +1,408 @@
+import { currentSessionVisionPolicy } from './native-image-coexistence.js'
+import {
+  clearSessionVisionModeAuthorityForAgent,
+  rememberSessionVisionModeAssemblyAuthorityForAgent,
+  resolveSessionVisionModeAuthority,
+  runWithSessionVisionModeAuthority,
+  takeSessionVisionModeAssemblyAuthorityForAgent,
+  visionModeEnabledForAgent,
+} from './session-vision-mode-authority.js'
+
+const MODE_SYNC_VARIABLE = 'vision_router_mode_sync'
+
+function isObject(value) {
+  return value !== null && typeof value === 'object'
+}
+
+function assemblyAgent(context) {
+  if (isObject(context?.agent) && isObject(context.agent.session)) return context.agent
+  // DSH rc.7/rc.8 pass the Agent through AssembleContext.scope. Newer Hosts
+  // declaration-merge context.agent as well. Accept scope only when it is
+  // unmistakably an Agent so standing/scopeless assemblies cannot manufacture
+  // Session authority.
+  if (isObject(context?.scope) && isObject(context.scope.session)) return context.scope
+  return undefined
+}
+
+function isStepAssembly(context) {
+  // The Agent loop supplies the turn's AbortSignal to SystemPrompt. Diagnostic,
+  // presentation and standing assemblies may carry the same Agent/scope but no
+  // request signal. Only a real loop assembly may stage next-step authority or
+  // mutate that Agent's scoped tool mask.
+  return isObject(context) && context.signal !== undefined
+}
+
+function liveConfig(ctx, fallback) {
+  try {
+    const settings = ctx?.get?.('settings')
+    const value = settings?.get?.('vision-router')
+    if (value && typeof value === 'object' && !Array.isArray(value)) return value
+  } catch {
+    // Composition config stays authoritative while Settings is unavailable.
+  }
+  return fallback && typeof fallback === 'object' && !Array.isArray(fallback) ? fallback : {}
+}
+
+function visionToolSurfaceEnabled(ctx, config, authority) {
+  return authority?.enabled === true && liveConfig(ctx, config).tool !== false
+}
+
+function visionModeDisabledError(name) {
+  const error = new Error(
+    `${name}: Vision mode is off for this Session; enable the composer Vision control before using Vision Router tools`,
+  )
+  error.code = 'VISION_MODE_DISABLED'
+  return error
+}
+
+function ownedVisionToolNames(owned) {
+  return [...owned.keys()].sort()
+}
+
+function rememberOwnedTool(owned, name) {
+  owned.set(name, (owned.get(name) ?? 0) + 1)
+}
+
+function forgetOwnedTool(owned, name) {
+  const count = owned.get(name) ?? 0
+  if (count <= 1) owned.delete(name)
+  else owned.set(name, count - 1)
+}
+
+function disposeHeldRestriction(held) {
+  if (!held) return
+  const disposers = Array.isArray(held.disposers)
+    ? held.disposers
+    : typeof held.dispose === 'function'
+      ? [held.dispose]
+      : []
+  for (let index = disposers.length - 1; index >= 0; index -= 1) {
+    try { disposers[index]?.() } catch {}
+  }
+}
+
+function releaseAgentToolRestriction(agent, restrictions) {
+  if (!isObject(agent)) return
+  const held = restrictions.get(agent)
+  if (!held) return
+  disposeHeldRestriction(held)
+  restrictions.delete(agent)
+}
+
+function warnRestrictionFailure(agent, error, deny, failed = deny) {
+  try {
+    agent?.ctx?.logger?.warn?.(
+      'vision-router: failed to restrict Session vision tools while Vision mode is off: %s (deny=%s failed=%s)',
+      error?.message ?? String(error),
+      deny.join(','),
+      failed.join(','),
+    )
+  } catch {}
+}
+
+function syncAgentToolRestriction(agent, enabled, restrictions, owned) {
+  if (!isObject(agent)) return
+  if (enabled) {
+    releaseAgentToolRestriction(agent, restrictions)
+    return
+  }
+
+  const tools = agent?.ctx?.tools
+  const restrict = tools?.restrict
+  const deny = ownedVisionToolNames(owned)
+  if (typeof restrict !== 'function') return
+  if (deny.length === 0) {
+    releaseAgentToolRestriction(agent, restrictions)
+    return
+  }
+
+  const held = restrictions.get(agent)
+  const signature = deny.join('\u0000')
+  if (held?.signature === signature) return
+  releaseAgentToolRestriction(agent, restrictions)
+
+  try {
+    // Current DSH can mask all inherited plugin tools in one scoped operation.
+    const dispose = restrict.call(tools, { deny })
+    restrictions.set(agent, {
+      signature,
+      disposers: typeof dispose === 'function' ? [dispose] : [],
+    })
+    return
+  } catch (combinedError) {
+    // Some support-window Hosts validate a deny list all-or-nothing. One
+    // temporarily non-restrictable registration must not keep every other
+    // Vision Router capability visible, so retry each owned name separately.
+    const disposers = []
+    const failed = []
+    for (const name of deny) {
+      try {
+        const dispose = restrict.call(tools, { deny: [name] })
+        if (typeof dispose === 'function') disposers.push(dispose)
+      } catch {
+        failed.push(name)
+      }
+    }
+    if (disposers.length > 0) restrictions.set(agent, { signature, disposers })
+    if (failed.length > 0 || disposers.length === 0) {
+      warnRestrictionFailure(agent, combinedError, deny, failed.length > 0 ? failed : deny)
+    }
+  }
+}
+
+function projectAssemblyTools(assembly, enabled, owned) {
+  if (enabled || !isObject(assembly) || !Array.isArray(assembly.tools) || owned.size === 0) {
+    return assembly
+  }
+  const tools = assembly.tools.filter((tool) => {
+    const name = typeof tool?.name === 'string' ? tool.name : undefined
+    return name === undefined || !owned.has(name)
+  })
+  if (tools.length === assembly.tools.length) return assembly
+  return { ...assembly, tools }
+}
+
+function wrapTools(tools, ctx, config, owned) {
+  if (!isObject(tools)) return tools
+  return new Proxy(tools, {
+    get(target, property) {
+      if (property !== 'register') {
+        const value = Reflect.get(target, property, target)
+        return typeof value === 'function' ? value.bind(target) : value
+      }
+      const register = Reflect.get(target, property, target)
+      if (typeof register !== 'function') return register
+      return (definition, ...rest) => {
+        if (
+          !definition ||
+          typeof definition !== 'object' ||
+          typeof definition.name !== 'string' ||
+          !definition.name.startsWith('vision_') ||
+          typeof definition.execute !== 'function'
+        ) {
+          return register.call(target, definition, ...rest)
+        }
+        const execute = definition.execute
+        const registered = register.call(target, {
+          ...definition,
+          async execute(args, exec) {
+            if (
+              exec?.agent &&
+              !visionModeEnabledForAgent(ctx, exec.agent, liveConfig(ctx, config))
+            ) {
+              throw visionModeDisabledError(definition.name)
+            }
+            return execute.call(definition, args, exec)
+          },
+        }, ...rest)
+        rememberOwnedTool(owned, definition.name)
+        if (typeof registered !== 'function') return registered
+        let active = true
+        return () => {
+          if (!active) return
+          active = false
+          try {
+            return registered()
+          } finally {
+            forgetOwnedTool(owned, definition.name)
+          }
+        }
+      }
+    },
+  })
+}
+
+/**
+ * Explicit Session Vision-mode authority boundary.
+ *
+ * DSH's per-Session model selection is the product switch: an adapter route
+ * owned by Vision Router means ON; an ordinary Host route means OFF. This
+ * boundary snapshots that fact at prompt assembly, keeps registration global,
+ * and projects visibility/execution authority per Agent. Global `tool=false`
+ * remains a second independent gate: selecting a Router route never expands a
+ * capability the user disabled in Settings.
+ *
+ * There are two model-facing gates on purpose. Current DSH exposes
+ * agent-scoped tools.restrict(), and a private prompt variable applies that mask
+ * before tool providers / Code Mode SDK rendering. The authoritative
+ * system-prompt/assemble waterfall then removes any owned native schemas that a
+ * support-window Host still contributed despite the mask. Execution is guarded
+ * again at the tool body, so stale schemas/direct dispatch cannot read images.
+ *
+ * Assembly snapshots are keyed by the concrete AssembleContext, not by Agent.
+ * An out-of-band diagnostic assembly can therefore render the next live
+ * selection without clearing or overwriting the immutable authority already
+ * active for a running step. Only a request assembly carrying DSH's turn signal
+ * is promoted for the immediately following agent/pre-step.
+ *
+ * It deliberately lives outside the retired legacy-core policy bridge, whose
+ * identity-only closure contract remains frozen.
+ */
+export function installSessionVisionModeBoundary(ctx, config = {}) {
+  if (!isObject(ctx)) return { ctx, config }
+  const restrictions = new WeakMap()
+  const assemblySnapshots = new WeakMap()
+  const ownedVisionTools = new Map()
+  let toolsView
+
+  const resolveForAgent = (agent, options = {}) => resolveSessionVisionModeAuthority(
+    ctx,
+    agent,
+    liveConfig(ctx, config),
+    options,
+  )
+
+  const clearAgent = (agent) => {
+    clearSessionVisionModeAuthorityForAgent(agent)
+  }
+
+  const syncForAgent = (agent) => {
+    if (!isObject(agent)) return
+    const authority = resolveForAgent(agent)
+    syncAgentToolRestriction(
+      agent,
+      visionToolSurfaceEnabled(ctx, config, authority),
+      restrictions,
+      ownedVisionTools,
+    )
+  }
+
+  const captureForAssembly = (context) => {
+    if (!isObject(context)) return undefined
+    const agent = assemblyAgent(context)
+    if (!isObject(agent)) return undefined
+    const authority = resolveForAgent(agent)
+    assemblySnapshots.set(context, authority)
+    if (isStepAssembly(context)) {
+      // Stage the next step without touching agentAuthorities: a previous step
+      // may still be executing tools under its already-promoted snapshot.
+      rememberSessionVisionModeAssemblyAuthorityForAgent(authority, agent)
+      syncAgentToolRestriction(
+        agent,
+        visionToolSurfaceEnabled(ctx, config, authority),
+        restrictions,
+        ownedVisionTools,
+      )
+    }
+    return authority
+  }
+
+  // DSH evaluates prompt variables synchronously before tool providers. The
+  // side effect therefore updates scoped visibility before native schemas and
+  // 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')
+    if (typeof systemPrompt?.variable === 'function') {
+      systemPrompt.variable(MODE_SYNC_VARIABLE, (context) => {
+        captureForAssembly(context)
+        return ''
+      })
+    }
+  } catch {
+    // The final assembly projection and execution guard below remain available
+    // on minimum/support-window Hosts without prompt variables.
+  }
+
+  // The returned assembly is the model-facing authority in DSH. Filter only
+  // definitions that were registered through this plugin boundary; a foreign
+  // plugin is free to own a vision_* name without being coupled to our switch.
+  try {
+    ctx.on?.('system-prompt/assemble', async (assembly, context, next) => {
+      const agent = assemblyAgent(context)
+      let authority = isObject(context) ? assemblySnapshots.get(context) : undefined
+      if (!authority && isObject(context)) authority = captureForAssembly(context)
+      if (!authority && isObject(agent)) authority = resolveForAgent(agent)
+      const transformed = typeof next === 'function' ? await next() : assembly
+      return projectAssemblyTools(
+        transformed,
+        visionToolSurfaceEnabled(ctx, config, authority),
+        ownedVisionTools,
+      )
+    })
+  } catch {
+    // Pre-step/execution guards still fail closed on Hosts without this event.
+  }
+
+  // A waking Agent enters `running` before its first prompt/tool assembly.
+  // Refresh visibility there as an early fallback, but do not persist the step
+  // snapshot until prompt assembly itself: a picker change between wakeup and
+  // assembly must still win for that request.
+  try {
+    ctx.on?.('agent/status', ({ agent, status }) => {
+      if (status === 'running') {
+        clearAgent(agent)
+        syncForAgent(agent)
+      } else if (status === 'idle') {
+        clearAgent(agent)
+      }
+    })
+    ctx.on?.('agent/created', ({ agent }) => {
+      clearAgent(agent)
+      syncForAgent(agent)
+    })
+    ctx.on?.('agent/disposed', ({ agent }) => {
+      clearAgent(agent)
+      releaseAgentToolRestriction(agent, restrictions)
+    })
+  } catch {
+    // 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, {
+    get(target, property) {
+      if (property === 'tools') {
+        if (!toolsView) {
+          toolsView = wrapTools(
+            Reflect.get(target, property, target),
+            target,
+            config,
+            ownedVisionTools,
+          )
+        }
+        return toolsView
+      }
+      if (property === 'on') {
+        const on = Reflect.get(target, property, target)
+        if (typeof on !== 'function') return on
+        return (event, handler, ...rest) => {
+          if (event !== 'agent/pre-step' || typeof handler !== 'function') {
+            return on.call(target, event, handler, ...rest)
+          }
+          return on.call(target, event, async function sessionVisionModeAwarePreStep(payload, next) {
+            const agent = payload?.agent
+            // Prompt assembly is the DSH selection-snapshot boundary. Consume
+            // exactly that staged snapshot here; direct/minimum Host pre-step
+            // calls resolve fresh authority instead of reusing an old step.
+            const authority = takeSessionVisionModeAssemblyAuthorityForAgent(agent)
+              ?? resolveSessionVisionModeAuthority(
+                target,
+                agent,
+                liveConfig(target, config),
+                {
+                  turn: payload?.turn,
+                  visionPolicy: currentSessionVisionPolicy(),
+                },
+              )
+            syncAgentToolRestriction(
+              agent,
+              visionToolSurfaceEnabled(target, config, authority),
+              restrictions,
+              ownedVisionTools,
+            )
+            return runWithSessionVisionModeAuthority(
+              authority,
+              agent,
+              () => handler.call(this, payload, next),
+            )
+          }, ...rest)
+        }
+      }
+      const value = Reflect.get(target, property, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+
+  return { ctx: wrapped, config }
+}