dsh-vision-router 2.1.0 → 2.1.2

package/lib/grounding-coordinate-runtime.js

@@ -0,0 +1,246 @@
+import { randomUUID } from 'node:crypto'
+import { unlink } from 'node:fs/promises'
+import path from 'node:path'
+import { writeArtifactFile } from './artifact-boundary.js'
+import {
+  createGroundingFrame,
+  groundingFrameBoxToSource,
+} from './grounding-coordinate-frame.js'
+import { wrapVisionAttachmentHandleDefinition } from './vision-attachment-handle-runtime.js'
+
+const GROUNDING_TOOL_NAMES = new Set(['vision_ground', 'vision_detect'])
+let sharpPromise
+
+function loadSharp() {
+  if (!sharpPromise) {
+    sharpPromise = import('sharp').then((mod) => mod.default ?? mod).catch((error) => {
+      sharpPromise = undefined
+      throw error
+    })
+  }
+  return sharpPromise
+}
+
+function workspaceOf(exec) {
+  const cwd = exec?.agent?.session?.header?.cwd
+  return typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd()
+}
+
+function artifactsDirOf(config) {
+  return typeof config?.artifactsDir === 'string' && config.artifactsDir !== ''
+    ? config.artifactsDir
+    : '.dsh-vision-router/artifacts'
+}
+
+function contextService(ctx, name) {
+  try {
+    if (typeof ctx?.get === 'function') return ctx.get(name)
+  } catch {
+    return undefined
+  }
+  return ctx?.[name]
+}
+
+async function readSourceBytes(ctx, core, sessionVisionIndex, exec, image) {
+  const source = String(image ?? '')
+  if (core?.isAttachmentIdInput?.(source)) {
+    const session = exec?.agent?.session
+    const ref = sessionVisionIndex?.lookupAttachment?.(session, source.trim())
+    if (ref === undefined) {
+      throw new Error(
+        `vision-router: unknown attachment id "${source}" (it must come from an image uploaded in this conversation)`,
+      )
+    }
+    const attachments = contextService(ctx, 'attachments')
+    if (!attachments || typeof attachments.readImage !== 'function') {
+      throw new Error('vision-router: the attachment service is not available in this deployment')
+    }
+    const stored = await attachments.readImage(ref, exec?.signal)
+    if (!stored?.data) throw new Error(`vision-router: failed to read attachment ${source}`)
+    return Buffer.from(stored.data)
+  }
+
+  const fs = contextService(ctx, 'fs')
+  if (!fs || typeof fs.resolve !== 'function' || typeof fs.readBytes !== 'function') {
+    throw new Error('vision-router: the fs service is not available')
+  }
+  const target = await fs.resolve(source)
+  return Buffer.from(await fs.readBytes(target, undefined, 20 * 1024 * 1024))
+}
+
+async function buildGroundingFrame(bytes) {
+  const sharp = await loadSharp()
+  const meta = await sharp(bytes, { failOn: 'none' }).metadata()
+  const width = Number(meta.width ?? 0)
+  const height = Number(meta.height ?? 0)
+  if (width <= 0 || height <= 0) throw new Error('could not read image dimensions')
+  const frame = createGroundingFrame(width, height)
+  const framed = await sharp(bytes, { failOn: 'none' })
+    .resize(frame.renderedWidth, frame.renderedHeight, { fit: 'fill' })
+    .extend({
+      top: frame.top,
+      bottom: frame.bottom,
+      left: frame.left,
+      right: frame.right,
+      background: { r: 0, g: 0, b: 0, alpha: 1 },
+    })
+    .png()
+    .toBuffer()
+  return { frame, framed, width, height }
+}
+
+function parseToolResult(raw) {
+  if (typeof raw !== 'string' || raw.trim() === '') return undefined
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+async function removeInternalFrame(workspace, publishedPath) {
+  if (typeof publishedPath !== 'string' || publishedPath === '') return
+  const target = path.isAbsolute(publishedPath) ? publishedPath : path.resolve(workspace, publishedPath)
+  try {
+    await unlink(target)
+  } catch {
+    // The internal frame is best-effort cleanup. Artifact retention may already
+    // have removed it after the delegated tool completed.
+  }
+}
+
+async function executeInGroundingFrame({
+  ctx,
+  core,
+  config,
+  sessionVisionIndex,
+  def,
+  execute,
+  args,
+  exec,
+}) {
+  const source = String(args?.image ?? '')
+  const bytes = await readSourceBytes(ctx, core, sessionVisionIndex, exec, source)
+  const { frame, framed, width, height } = await buildGroundingFrame(bytes)
+  const workspace = workspaceOf(exec)
+  const artifactsDir = artifactsDirOf(config)
+  const internalName = `.grounding-frame-${randomUUID()}.png`
+  const framePath = await writeArtifactFile(workspace, artifactsDir, internalName, framed)
+
+  try {
+    const raw = await execute(
+      {
+        ...(args ?? {}),
+        image: framePath,
+        // Core's annotation would be in the protocol frame. Re-publish only an
+        // original-raster annotation after the deterministic inverse transform.
+        annotate: false,
+      },
+      exec,
+    )
+    const delegated = parseToolResult(raw)
+    if (!delegated || delegated.ok === false) return raw
+
+    if (def.name === 'vision_ground') {
+      const mapped = groundingFrameBoxToSource(delegated, frame)
+      if (!mapped) {
+        throw new Error('vision_ground: the model box falls entirely outside the letterboxed source raster')
+      }
+      const result = { ...mapped, width, height }
+      if (args?.annotate !== false) {
+        if (typeof core?.annotateBoxBuffer !== 'function') {
+          throw new Error('vision_ground: core annotation helper is unavailable')
+        }
+        const annotated = await core.annotateBoxBuffer(bytes, mapped)
+        const stem = core?.artifactStemOf?.(source, 'ground') ?? `image-ground-${Date.now()}`
+        result.annotatedPath = await writeArtifactFile(workspace, artifactsDir, `${stem}.png`, annotated)
+      }
+      return JSON.stringify(result)
+    }
+
+    const elements = []
+    for (const item of Array.isArray(delegated.elements) ? delegated.elements : []) {
+      const mapped = groundingFrameBoxToSource(item?.box, frame)
+      if (!mapped) continue
+      elements.push({
+        ...item,
+        number: elements.length + 1,
+        box: mapped,
+      })
+    }
+    const result = { width, height, elements }
+    if (args?.annotate !== false && elements.length > 0) {
+      if (typeof core?.annotateBoxesBuffer !== 'function') {
+        throw new Error('vision_detect: core annotation helper is unavailable')
+      }
+      const annotated = await core.annotateBoxesBuffer(bytes, elements.map((item) => item.box))
+      const stem = core?.artifactStemOf?.(source, 'detect') ?? `image-detect-${Date.now()}`
+      result.annotatedPath = await writeArtifactFile(workspace, artifactsDir, `${stem}.png`, annotated)
+    }
+    return JSON.stringify(result)
+  } finally {
+    await removeInternalFrame(workspace, framePath)
+  }
+}
+
+function wrapGroundingDefinition(ctx, options, def) {
+  if (!def || !GROUNDING_TOOL_NAMES.has(def.name) || typeof def.execute !== 'function') return def
+  const execute = def.execute
+  return {
+    ...def,
+    execute(args, exec) {
+      return executeInGroundingFrame({
+        ctx,
+        ...options,
+        def,
+        execute,
+        args,
+        exec,
+      })
+    },
+  }
+}
+
+/**
+ * Give vision_ground / vision_detect one explicit provider-independent
+ * coordinate protocol: the model always receives an exact 1000x1000
+ * letterboxed raster, while callers always receive Host-canonical source
+ * pixels. The same registration seam also canonicalizes DSH text-only image
+ * handles before any Vision Router tool sees them, so short model-facing
+ * sha256 prefixes can never fall through into filesystem-path resolution.
+ * Core still owns provider selection, fallback, retry and failure semantics.
+ */
+export function contextWithGroundingCoordinateFrame(ctx, options = {}) {
+  if (!ctx || (typeof ctx !== 'object' && typeof ctx !== 'function')) return ctx
+  const sourceTools = ctx.tools ?? contextService(ctx, 'tools')
+  if (!sourceTools || typeof sourceTools.register !== 'function') return ctx
+
+  const tools = new Proxy(sourceTools, {
+    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)
+      return (def, ...rest) => {
+        const grounded = wrapGroundingDefinition(ctx, options, def)
+        const attachmentResolved = wrapVisionAttachmentHandleDefinition(grounded, options)
+        return register.call(target, attachmentResolved, ...rest)
+      }
+    },
+  })
+
+  return new Proxy(ctx, {
+    get(target, property) {
+      if (property === 'tools') return tools
+      if (property === 'get') {
+        const get = Reflect.get(target, property, target)
+        if (typeof get !== 'function') return get
+        return (name, ...rest) => name === 'tools' ? tools : get.call(target, name, ...rest)
+      }
+      const value = Reflect.get(target, property, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    },
+  })
+}

package/lib/legacy-core-vision-policy-bridge.js

@@ -1,150 +1,21 @@
-import { currentSessionSurfacePolicy } from './session-surface-policy.js'
-import { knownSessionVisionMemory } from './session-vision-state.js'
-
-function isObject(value) {
-  return value !== null && typeof value === 'object'
-}
-
-function collectAttachmentIds(messages) {
-  const ids = []
-  const seen = new Set()
-  const pending = []
-  for (const message of messages ?? []) {
-    if (message && Array.isArray(message.content)) pending.push(...message.content)
-  }
-  while (pending.length > 0) {
-    const block = pending.pop()
-    if (!block || typeof block !== 'object') continue
-    if (block.type === 'image') {
-      const ref = block.attachment
-      const raw = ref && (ref.attachmentId ?? ref.id)
-      if (raw !== undefined && raw !== null) {
-        const id = String(raw)
-        if (id !== '' && !seen.has(id)) {
-          seen.add(id)
-          ids.push(id)
-        }
-      }
-    }
-    if (Array.isArray(block.content)) pending.push(...block.content)
-  }
-  return ids.reverse()
-}
-
-function appendVisionRouterAttachmentHint(payload, decision, config) {
-  const policy = currentSessionSurfacePolicy(config)
-  if (decision?.kind === 'reject' || policy.ownership !== 'vision-router-owned') {
-    return decision
-  }
-
-  // Vision Router-owned wrappers may deliberately preserve raw pixels when the
-  // delegated source model is itself multimodal. The provider wire carries the
-  // bytes, but not DSH's durable attachmentId, so a model that chooses a
-  // precision Vision Router tool would otherwise have to guess an id. Surface
-  // the exact current-turn ids as read-only model context while leaving the raw
-  // image blocks and the session-scoped lookup fence unchanged.
-  const source = Array.isArray(payload?.messages) ? payload.messages : []
-  const ids = collectAttachmentIds(source)
-  if (ids.length === 0) return decision
-
-  const baseMessages = Array.isArray(decision?.messages)
-    ? decision.messages
-    : source
-  const turn = Number.isInteger(payload?.turn) ? payload.turn : 'current'
-  const step = Number.isInteger(payload?.step) ? payload.step : 'step'
-  const hintId = `vision-router-attachment-refs-${turn}-${step}`
-  if (baseMessages.some((message) => message?.id === hintId)) return decision
-
-  const quoted = ids.map((id) => `"${id}"`).join(', ')
-  const hint = {
-    role: 'user',
-    id: hintId,
-    content: [{
-      type: 'text',
-      text: `Vision Router attachment references for the image(s) in this step: ${quoted}. If a Vision Router tool requires attachmentIds or an attachment-id image argument, use only these exact ids. Never guess or invent an attachment id.`,
-    }],
-    source: { kind: 'plugin', plugin: 'dsh-vision-router' },
-  }
-  const messages = [...baseMessages, hint]
-  return isObject(decision)
-    ? { ...decision, messages }
-    : { kind: 'continue', messages }
-}
-
-function rewriteTextOnlyDecision(payload, decision, rewriteHistoryImages, config) {
-  const policy = currentSessionSurfacePolicy(config)
-  if (
-    decision?.kind === 'reject' ||
-    policy.rewriteCurrentImages !== true ||
-    typeof rewriteHistoryImages !== 'function'
-  ) {
-    return decision
-  }
-
-  const source = Array.isArray(decision?.messages)
-    ? decision.messages
-    : Array.isArray(payload?.messages)
-      ? payload.messages
-      : undefined
-  if (!source) return decision
-
-  // Core registers the exact SessionMemoryView while processing this same
-  // pre-step. Reuse it here so a text-only fallback preserves cached visual
-  // descriptions instead of degrading them back to a generic attachment marker.
-  const memory = knownSessionVisionMemory(payload?.agent?.session)
-  const rewritten = rewriteHistoryImages(source, memory)
-  const messages = rewritten?.messages
-  if (!Array.isArray(messages) || messages === source) return decision
-  if (isObject(decision)) return { ...decision, messages }
-  return { kind: 'continue', messages }
-}
-
 /**
- * Preserve the two remaining pre-step compatibility behaviors without
- * impersonating Settings/config for Core.
+ * Retired pre-step compatibility shell.
+ *
+ * This module remains as a stable internal import while the 2.x composition is
+ * still being collapsed, but it deliberately owns no runtime behavior.
+ *
+ * Historical versions intercepted `agent/pre-step` for two model-only concerns:
+ * rewriting text-only image messages into `[attached image: ...]` markers and
+ * appending a synthetic attachment-id user message for Vision Router wrappers.
+ * DSH persists every admitted pre-step message as `user/message`, so both
+ * transforms crossed the durable transcript boundary and could surface in the
+ * Web conversation. User-owned image messages must instead remain byte-for-byte
+ * Session facts; request-only image projection belongs to the selected adapter.
  *
- * Ownership classification remains native-image-coexistence's responsibility.
- * Core consumes its five policy-derived switches through CoreVisionSurface.
- * This boundary only reuses the exact SessionMemoryView for a text-only image
- * rewrite and surfaces current durable attachment ids for a Vision Router-owned
- * route. Every other context service, Settings object, injected child and config
- * value passes through unchanged.
+ * Keep this function identity-only until runtime-composition removes the import
+ * in a dedicated closure cleanup. No Settings/config/service identity is
+ * impersonated and no `agent/pre-step` listener is installed here.
  */
-export function installLegacyCoreVisionPolicyBridge(
-  ctx,
-  config = {},
-  { rewriteHistoryImages } = {},
-) {
-  if (!isObject(ctx)) return { ctx, config }
-
-  const wrappedCtx = new Proxy(ctx, {
-    get(target, property) {
-      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 legacyCoreVisionPolicyPreStep(payload, next) {
-            const decision = await handler.call(this, payload, next)
-            const rewritten = rewriteTextOnlyDecision(
-              payload,
-              decision,
-              rewriteHistoryImages,
-              config,
-            )
-            return appendVisionRouterAttachmentHint(payload, rewritten, config)
-          }, ...rest)
-        }
-      }
-      const value = Reflect.get(target, property, target)
-      return typeof value === 'function' ? value.bind(target) : value
-    },
-  })
-
-  return {
-    ctx: wrappedCtx,
-    config,
-  }
+export function installLegacyCoreVisionPolicyBridge(ctx, config = {}) {
+  return { ctx, config }
 }

package/lib/runtime-composition.js

@@ -15,6 +15,7 @@ import { createCoreVisionSurfaceRuntime } from './core-vision-surface.js'
 import { installSessionVisionIndexBoundary } from './session-vision-index.js'
 import { createSessionVisionRuntime } from './session-vision-runtime.js'
 import { installLegacyCoreVisionPolicyBridge } from './legacy-core-vision-policy-bridge.js'
+import { installSessionVisionModeBoundary } from './session-vision-mode-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'
@@ -28,6 +29,11 @@ import { installTesseractExecFileCompat } from './tesseract-exec-compat.js'
 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'
 import { installVisionRoutingRuntime } from './vision-routing-runtime.js'
 import { createCapabilityProfileStore } from './vision-capability-probe.js'
 import { installCapabilityBenchmarkService } from './vision-capability-benchmark-service.js'
@@ -186,25 +192,32 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
     runtimeI18nCore,
     { logger: logging.logger, index: sessionVisionRuntime.index },
   )
-  // Only the real pre-step compatibility behaviors remain here. Session policy
-  // is not projected through fake Settings/config views; Core's policy-derived
-  // switches come exclusively from CoreVisionSurfaceRuntime.
+  // The retired bridge stays identity-only. Session mode is a new explicit
+  // boundary because it owns a different concern: per-Agent visibility and
+  // execution authority derived from DSH's modelSelection projection.
   const legacyCoreCompat = installLegacyCoreVisionPolicyBridge(
     sessionIndexCtx,
     nativeImageCompat.config,
     { rewriteHistoryImages: core.rewriteHistoryImages },
   )
+  const sessionVisionModeCompat = installSessionVisionModeBoundary(
+    legacyCoreCompat.ctx,
+    legacyCoreCompat.config,
+  )
 
   // Final structured-flow guard sits closest to core.apply so it sees the
   // actual tool registrations and pre-step listener. The diagnostic observer
   // remains immediately inside it so existing timeout/budget semantics stay
   // unchanged.
   const limitDiagnosticCtx = installVisionLimitDiagnostics(
-    legacyCoreCompat.ctx,
-    legacyCoreCompat.config,
+    sessionVisionModeCompat.ctx,
+    sessionVisionModeCompat.config,
     logging.logger,
   )
-  const structuredCtx = installStructuredFlowHardening(limitDiagnosticCtx, legacyCoreCompat.config)
+  const structuredCtx = installStructuredFlowHardening(
+    limitDiagnosticCtx,
+    sessionVisionModeCompat.config,
+  )
   const backgroundProfiling = installBackgroundCapabilityProfiling(
     structuredCtx,
     runtimeConfig,
@@ -249,11 +262,21 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
     logger: logging.logger,
   })
 
+  // Ground/detect own one explicit raster-coordinate boundary. It wraps only
+  // the tool-registration view, before runtime-performance observation. That
+  // leaves adapter sampling on the same execution seam while backend preflight
+  // remains the final outer Core-visible policy boundary.
+  const groundingCoordinateCtx = contextWithGroundingCoordinateFrame(executionCtx, {
+    core,
+    config: runtimeConfig,
+    sessionVisionIndex: sessionVisionRuntime.index,
+  })
+
   // Only real visual-tool adapter streams are timed, and only while live Auto
   // authority permits future-routing observation. Benchmark/background calls
   // have no visual-tool scope and cannot contaminate this store.
   const performanceCtx = contextWithVisionRuntimePerformance(
-    executionCtx,
+    groundingCoordinateCtx,
     runtimePerformanceStore,
     {
       logger: logging.logger,
@@ -295,6 +318,16 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
   })
   installTesseractExecFileCompat(backendRuntimeCtx)
 
+  // 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, {
+    wrapperRoute: runtimeConfig.wrapperRoute,
+    chainRoute: runtimeConfig.chainRoute,
+    logger: logging.logger,
+  })
+  const coreRequestAuthorityCtx = contextWithAgentRequestRouteAuthority(backendRuntimeCtx)
+
   try {
     const c = hardenedConfig && typeof hardenedConfig === 'object' ? hardenedConfig : {}
     const local = c.localOllama && typeof c.localOllama === 'object' ? c.localOllama : {}
@@ -316,8 +349,8 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
       withVisionCircuitBreakerObserver(
         breakerShadowHealth.capture,
         () => core.apply(
-          backendRuntimeCtx,
-          legacyCoreCompat.config,
+          coreRequestAuthorityCtx,
+          sessionVisionModeCompat.config,
           {
             sessionVision: sessionVisionRuntime,
             coreVisionSurface: coreVisionSurfaceRuntime,
@@ -345,4 +378,4 @@ export function applyVisionRuntimeComposition(ctx, config = {}, core) {
     )
     throw error
   }
-}
+}

package/lib/session-surface-policy.js

@@ -1,4 +1,5 @@
 import { currentSessionVisionPolicy } from './native-image-coexistence.js'
+import { currentSessionVisionModeAuthority } from './session-vision-mode-authority.js'
 
 const OWNERSHIP = Object.freeze({
   PLUGIN_OWNED: 'vision-router-owned',
@@ -22,62 +23,87 @@ function normalizedOwnership(policy) {
  * Resolve one immutable, read-only snapshot of the Vision Router capability
  * surface for the current session.
  *
- * This layer does not classify model capability and does not grant authority.
- * `visionPolicy` is evidence produced by native-image-coexistence; this module
- * only projects that already-authoritative ownership decision onto the legacy
- * configuration/surface questions that used to be answered in several places.
+ * Image ownership and Vision-mode authority are intentionally distinct. The
+ * native-image policy answers who can consume raw pixels; the mode authority
+ * answers whether this Session explicitly selected a Vision Router-owned
+ * wrapper/twin for the current step. Only the latter can grant plugin tools or
+ * automatic visual work. This prevents a historical image, a native multimodal
+ * source model, or a stale request header from silently turning Vision back on.
+ *
+ * Durable transcript invariant: once a real session policy exists, Core may
+ * observe/index image blocks but may never replace a user-owned image message
+ * before the Agent loop appends it to the Session log. Image projection belongs
+ * at the adapter/request boundary. The historical `rewriteCurrentImages` bit is
+ * therefore intentionally ignored even when an older policy producer still
+ * exposes it; the compatibility field below is permanently false.
  */
 export function resolveSessionSurfacePolicy({
   visionPolicy,
+  visionModeAuthority,
   config = {},
   schemaBootstrapping = false,
 } = {}) {
   const source = isObject(visionPolicy) ? visionPolicy : undefined
+  const authority = isObject(visionModeAuthority) ? visionModeAuthority : undefined
   const value = isObject(config) ? config : {}
   const ownership = normalizedOwnership(source)
-  const native = ownership === OWNERSHIP.NATIVE
   const pluginOwned = ownership === OWNERSHIP.PLUGIN_OWNED
-  const textOnly = ownership === OWNERSHIP.TEXT_ONLY
 
-  // No active session policy means no session-specific rewrite/preservation
-  // authority. This distinction is important: absence is not the same as an
-  // explicit UNKNOWN capability snapshot, whose contract is non-destructive.
-  const preserveRawImages = source?.preserveRawImages === true
-  const rewriteCurrentImages = source?.rewriteCurrentImages === true
-  const allowStructuredBootstrap = source?.allowStructuredBootstrap !== false
-  const allowGenericAutoMount = source?.suppressGenericAutoMount !== true
+  // During schema bootstrap there is no real Session policy, so global Settings
+  // still decide which definitions Core registers. During a real step, an
+  // explicit authority snapshot wins; direct helper callers fall back to the
+  // already-classified plugin ownership instead of inventing an enabled mode.
+  const visionModeEnabled = authority !== undefined
+    ? authority.enabled === true
+    : source === undefined
+      ? true
+      : pluginOwned
+
+  // No active session policy means no session-specific preservation authority.
+  // During a real pre-step, every ownership result — including explicit
+  // text-only and unknown — preserves the durable user message unchanged.
+  const preserveRawImages = source !== undefined
+  const rewriteCurrentImages = false
+  const allowStructuredBootstrap = visionModeEnabled
+  const allowGenericAutoMount = visionModeEnabled
 
   const surface = Object.freeze({
     preserveRawImages,
     rewriteCurrentImages,
-    visionTools: value.tool !== false,
+    visionTools: value.tool !== false && visionModeEnabled,
     structuredBootstrap:
-      value.structuredVisionBootstrap === true && allowStructuredBootstrap,
+      value.structuredVisionBootstrap === true && visionModeEnabled,
     genericAutoMount:
-      value.autoActivateOnImage !== false && allowGenericAutoMount,
+      value.autoActivateOnImage !== false && visionModeEnabled,
     instantDescribe:
-      value.instantDescribe !== false && !native,
+      value.instantDescribe !== false && visionModeEnabled,
   })
 
   const overrides = {}
-  if (schemaBootstrapping === true && value.tool === false) overrides.tool = true
-  if (preserveRawImages && value.rewriteImages !== false) overrides.rewriteImages = false
-  if (native && value.instantDescribe !== false) overrides.instantDescribe = false
-  if (native && value.autoActivateOnImage !== false) overrides.autoActivateOnImage = false
-  if (!allowStructuredBootstrap && value.structuredVisionBootstrap !== false) {
-    overrides.structuredVisionBootstrap = false
+  if (schemaBootstrapping === true && source === undefined && value.tool === false) {
+    overrides.tool = true
+  }
+  // Core's historical rewriteImages switch controls an agent/pre-step message
+  // transform. Disable it for every real session policy so neither current nor
+  // historical user image blocks can be persisted as internal attachment text.
+  // Vision Router-owned adapters still perform their private request projection.
+  if (source !== undefined && value.rewriteImages !== false) overrides.rewriteImages = false
+
+  // The composer/model selection is the Session authority. When it is OFF,
+  // suppress every automatic/plugin-owned visual surface while preserving the
+  // durable image itself. Settings remain unchanged; these are turn-local Core
+  // projections only.
+  if (source !== undefined && !visionModeEnabled) {
+    if (value.tool !== false) overrides.tool = false
+    if (value.instantDescribe !== false) overrides.instantDescribe = false
+    if (value.autoActivateOnImage !== false) overrides.autoActivateOnImage = false
+    if (value.structuredVisionBootstrap !== false) overrides.structuredVisionBootstrap = false
   }
 
   return Object.freeze({
     ownership,
-    participates:
-      source !== undefined && (
-        pluginOwned ||
-        textOnly ||
-        surface.visionTools ||
-        surface.structuredBootstrap ||
-        surface.genericAutoMount
-      ),
+    visionModeEnabled,
+    participates: source !== undefined,
     preserveRawImages,
     rewriteCurrentImages,
     allowStructuredBootstrap,
@@ -87,10 +113,11 @@ export function resolveSessionSurfacePolicy({
   })
 }
 
-/** Read the turn-local ownership snapshot and resolve its capability surface. */
+/** Read the turn-local ownership + mode snapshots and resolve the Core surface. */
 export function currentSessionSurfacePolicy(config = {}, options = {}) {
   return resolveSessionSurfacePolicy({
     visionPolicy: currentSessionVisionPolicy(),
+    visionModeAuthority: currentSessionVisionModeAuthority(),
     config,
     schemaBootstrapping: options?.schemaBootstrapping === true,
   })