dsh-vision-router 2.1.7 → 2.2.0

package/lib/artifact-boundary.js

@@ -1,6 +1,8 @@
 import { createVisionArtifactStore } from './vision-artifact-store.js'
 
 export {
+  ARTIFACT_HANDOFF_RUN_ID,
+  ARTIFACT_RUNS_DIR,
   DEFAULT_ARTIFACTS_DIR,
   normalizeArtifactsDir,
 } from './artifact-io.js'
@@ -23,3 +25,12 @@ export function resolveArtifactTarget(workspace, artifactsDir, relativePath, dep
 export function writeArtifactFile(workspace, artifactsDir, relativePath, data, deps = {}) {
   return createVisionArtifactStore({ workspace, artifactsDir, deps }).publish(relativePath, data)
 }
+
+/**
+ * Persistent writer for file-path handoffs such as vision_materialize. It uses
+ * the same store boundary but publishes under one stable reserved managed run,
+ * so later tools can reference it without losing retention governance.
+ */
+export function writePersistentArtifactFile(workspace, artifactsDir, relativePath, data, deps = {}) {
+  return createVisionArtifactStore({ workspace, artifactsDir, deps }).publishPersistent(relativePath, data)
+}

package/lib/artifact-io.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto'
-import { lstat, mkdir, realpath, rename, unlink, writeFile } from 'node:fs/promises'
+import { lstat, mkdir, realpath, rename, unlink, utimes, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import {
   currentVisionTurnBudget,
@@ -12,6 +12,7 @@ import {
 
 export const DEFAULT_ARTIFACTS_DIR = '.dsh-vision-router/artifacts'
 export const ARTIFACT_RUNS_DIR = '.runs'
+export const ARTIFACT_HANDOFF_RUN_ID = '.vision-run-handoff'
 
 function isPathInside(root, candidate) {
   const relative = path.relative(root, candidate)
@@ -99,7 +100,7 @@ async function safeLstat(target, lstatImpl) {
  * existing symlink is rejected even when it points somewhere else inside the
  * workspace. Artifacts outside a managed run keep their original root layout.
  */
-export async function resolveArtifactTarget(workspace, artifactsDir, relativePath, deps = {}) {
+async function resolveArtifactTargetForRun(workspace, artifactsDir, relativePath, deps = {}, runId) {
   const realpathImpl = deps.realpath ?? realpath
   const mkdirImpl = deps.mkdir ?? mkdir
   const lstatImpl = deps.lstat ?? lstat
@@ -108,7 +109,6 @@ export async function resolveArtifactTarget(workspace, artifactsDir, relativePat
   const workspaceReal = await realpathImpl(path.resolve(String(workspace ?? '')))
   throwIfVisionAborted()
   const relativeBase = normalizeArtifactsDir(artifactsDir)
-  const runId = currentArtifactRunId()
   const requestedTarget = normalizeRelativeArtifactPath(relativePath)
   const relativeTarget = runId
     ? normalizeRelativeArtifactPath(path.join(ARTIFACT_RUNS_DIR, runId, requestedTarget))
@@ -119,6 +119,7 @@ export async function resolveArtifactTarget(workspace, artifactsDir, relativePat
   }
 
   const lexicalRunsBase = runId ? path.resolve(lexicalBase, ARTIFACT_RUNS_DIR) : undefined
+  const lexicalRunBase = runId ? path.resolve(lexicalRunsBase, runId) : undefined
   if (lexicalRunsBase && !isPathInside(lexicalBase, lexicalRunsBase)) {
     throw new Error('vision-router: managed artifact runs must stay inside the artifacts directory')
   }
@@ -155,6 +156,7 @@ export async function resolveArtifactTarget(workspace, artifactsDir, relativePat
   }
 
   let runsBaseReal
+  let runBaseReal
   if (lexicalRunsBase) {
     const after = await safeLstat(lexicalRunsBase, lstatImpl)
     throwIfVisionAborted()
@@ -166,6 +168,16 @@ export async function resolveArtifactTarget(workspace, artifactsDir, relativePat
     if (!isPathInside(artifactsBaseReal, runsBaseReal)) {
       throw new Error('vision-router: managed artifact runs directory escapes the artifacts directory')
     }
+    const runInfo = await safeLstat(lexicalRunBase, lstatImpl)
+    throwIfVisionAborted()
+    if (!runInfo?.isDirectory?.() || runInfo.isSymbolicLink?.()) {
+      throw new Error('vision-router: managed artifact run must be a real directory')
+    }
+    runBaseReal = await realpathImpl(lexicalRunBase)
+    throwIfVisionAborted()
+    if (!isPathInside(runsBaseReal, runBaseReal)) {
+      throw new Error('vision-router: managed artifact run escapes the runs directory')
+    }
   }
 
   const target = path.join(parentReal, path.basename(lexicalTarget))
@@ -174,15 +186,33 @@ export async function resolveArtifactTarget(workspace, artifactsDir, relativePat
   if (existing?.isDirectory?.()) {
     throw new Error('vision-router: artifact target is a directory')
   }
-  return { target, parentReal, artifactsBaseReal, runsBaseReal, existing, runId }
+  return { target, parentReal, artifactsBaseReal, runsBaseReal, runBaseReal, existing, runId }
 }
 
-/** Hardened atomic publication primitive used by VisionArtifactStore. */
-export async function writeArtifactFile(workspace, artifactsDir, relativePath, data, deps = {}) {
+export function resolveArtifactTarget(workspace, artifactsDir, relativePath, deps = {}) {
+  return resolveArtifactTargetForRun(
+    workspace, artifactsDir, relativePath, deps, currentArtifactRunId(),
+  )
+}
+
+/**
+ * Resolve a stable cross-tool handoff artifact even when the caller is inside
+ * a random managed per-tool run. Handoff files share one reserved managed run,
+ * so their path is deterministic enough for later tool calls while existing
+ * retention still bounds their lifetime and total bytes.
+ */
+export function resolvePersistentArtifactTarget(workspace, artifactsDir, relativePath, deps = {}) {
+  return resolveArtifactTargetForRun(
+    workspace, artifactsDir, relativePath, deps, ARTIFACT_HANDOFF_RUN_ID,
+  )
+}
+
+async function writeArtifactFileForRun(workspace, artifactsDir, relativePath, data, deps, runId) {
   const writeFileImpl = deps.writeFile ?? writeFile
   const renameImpl = deps.rename ?? rename
   const unlinkImpl = deps.unlink ?? unlink
-  const resolved = await resolveArtifactTarget(workspace, artifactsDir, relativePath, deps)
+  const utimesImpl = deps.utimes ?? utimes
+  const resolved = await resolveArtifactTargetForRun(workspace, artifactsDir, relativePath, deps, runId)
   const temp = path.join(
     resolved.parentReal,
     `.dsh-vision-router-${process.pid}-${randomUUID()}.tmp`,
@@ -202,6 +232,11 @@ export async function writeArtifactFile(workspace, artifactsDir, relativePath, d
     }
     await renameImpl(temp, resolved.target)
     published = true
+    if (resolved.runId === ARTIFACT_HANDOFF_RUN_ID && resolved.runBaseReal) {
+      const touchedAt = new Date()
+      await utimesImpl(resolved.runBaseReal, touchedAt, touchedAt)
+      throwIfVisionAborted()
+    }
     if (resolved.runId) {
       // New managed runs live under `.runs`, so retention scans that directory
       // directly. Also schedule the old artifact root so pre-P2-B direct
@@ -218,3 +253,21 @@ export async function writeArtifactFile(workspace, artifactsDir, relativePath, d
     }
   }
 }
+
+/** Hardened atomic publication primitive used by VisionArtifactStore. */
+export async function writeArtifactFile(workspace, artifactsDir, relativePath, data, deps = {}) {
+  return writeArtifactFileForRun(
+    workspace, artifactsDir, relativePath, data, deps, currentArtifactRunId(),
+  )
+}
+
+/**
+ * Publish a stable workspace handoff artifact under the reserved managed run
+ * while preserving the exact same containment, symlink, cancellation, atomic
+ * write and retention checks as writeArtifactFile.
+ */
+export async function writePersistentArtifactFile(workspace, artifactsDir, relativePath, data, deps = {}) {
+  return writeArtifactFileForRun(
+    workspace, artifactsDir, relativePath, data, deps, ARTIFACT_HANDOFF_RUN_ID,
+  )
+}

package/lib/catalog-corrections.js

@@ -17,6 +17,7 @@ import {
 import { stripTrailingSlashes } from './string-normalization.js'
 import { currentVisionProviderTransport } from './vision-provider-transport.js'
 import { directSessionAffinityHeaders } from './session-affinity.js'
+import { isOffloadedImageBlock, offloadedImagePlaceholder } from './image-offload-compat.js'
 
 export const CATALOG_ROUTING_CORRECTIONS = [
   {
@@ -109,6 +110,10 @@ async function convertBlocks(blocks, bytesOf, depth = 0) {
     if (block.type === 'text' && typeof block.text === 'string' && block.text !== '') {
       out.push({ type: 'text', text: block.text })
     } else if (block.type === 'image') {
+      if (isOffloadedImageBlock(block)) {
+        out.push({ type: 'text', text: offloadedImagePlaceholder(block) })
+        continue
+      }
       if (typeof bytesOf !== 'function') continue
       let bytes
       try {

package/lib/client.js

@@ -231,14 +231,15 @@ window.__ModuleLoader__.load({
         '本地后端不受影响，仍在最前。关闭时保持既有顺序（付费在前、免费补全在后）。',
       hintDesktopScreenshot: '允许模型按需截取桌面屏幕用于识图。默认关闭；开启后才提供 vision_screenshot 工具。macOS 在保存开启时会立即触发一次屏幕录制授权检查；如果已经授权，系统不会重复弹窗。',
       hintStealth:
-        '只作用于官方 DeepSeek 路由：接管后模型选择器保持原样。需在 profile 补丁层 ' +
-        '（cordis.patch.yml）禁用官方 llm-deepseek 行后才真正接管；官方行还在时 ' +
-        '插件自动回退为选择器里的「自动识图」包装路由。opencode 等自定义路由与隐身模式无关，' +
-        '它们默认由「自动创建 + 自动识图模型组」处理；只有要限制范围时才用下方手动包装。改动后需重启 dsh 生效。',
+        '只作用于官方 DeepSeek 路由。新版 DSH 中官方 provider 始终归 Host 所有，Vision Router 只使用「+ 自动识图」' +
+        '包装，不再要求你禁用 llm-deepseek；旧版 Host 仍保留官方行缺失时的历史接管兼容。opencode 等自定义路由' +
+        '默认自动包装，只有要限制范围时才用下方手动包装。',
       stealthOfficialDeadHint:
-        '提示：检测到官方 DeepSeek 行当前被禁用（profile 补丁层），所以即使关闭隐身模式，' +
-        '本插件仍会接管 deepseek-official 路由，否则 DeepSeek 模型会从选择器消失。' +
-        '如需完全恢复官方原生行，请先把 cordis.patch.yml 里 llm-deepseek 的 disabled 改回 false 再重启。',
+        '提示：这是旧版 Host，且官方 DeepSeek 行当前被禁用；Vision Router 正使用兼容性 keep-alive 路由。' +
+        '如需恢复完全官方的原生行，请在 cordis.patch.yml 中重新启用 llm-deepseek 后重启。',
+      stealthOfficialHostOwnedHint:
+        '检测到官方 DeepSeek provider 被禁用或不可用，但当前 DSH 已由 Host 负责该路由。Vision Router 不会自行重建它。' +
+        '请重新启用 llm-deepseek，再通过「+ 自动识图」包装 /「👁 识图」处理图片任务。',
       numTimeoutMs: '单次识图请求超时（毫秒）',
       numVisionTaskTimeoutMs: '识图任务最长时间（毫秒）',
       numOcrTimeoutMs: 'OCR 最长时间（毫秒）',
@@ -507,16 +508,16 @@ window.__ModuleLoader__.load({
         'Local backends are unaffected and stay first. When off, the existing order is preserved (paid first, free appended last).',
       hintDesktopScreenshot: 'Lets the model capture the desktop on demand for image understanding. Off by default; vision_screenshot is exposed only when enabled. On macOS, saving the enabled setting immediately triggers a screen-recording permission check; if permission was already granted, macOS will not prompt again.',
       hintStealth:
-        'Only affects the official DeepSeek route: takes it over while the model picker looks exactly like stock. Requires the ' +
-        'official llm-deepseek row to be disabled in your profile patch layer (cordis.patch.yml); while the ' +
-        'stock row is present the plugin falls back to the visible auto-vision wrapper entry. Custom routes like opencode ' +
-        'are auto-wrapped by default; use the manual wrapper section below only when you want to restrict their scope. ' +
-        'Restart dsh after changing stealth/profile takeover.',
+        'Only affects the official DeepSeek route. On newer DSH Hosts the official provider stays Host-owned, so Vision Router ' +
+        'uses the “+ Auto Vision” wrapper and never asks you to disable llm-deepseek. Legacy Hosts retain the historical ' +
+        'takeover compatibility when the stock row is absent. Custom routes like opencode are auto-wrapped by default; use ' +
+        'the manual wrapper section below only when you want to restrict their scope.',
       stealthOfficialDeadHint:
-        'Notice: the official DeepSeek row is currently disabled (profile patch layer), so this plugin keeps ' +
-        'serving the deepseek-official route even with stealth mode off — otherwise the DeepSeek models would ' +
-        'vanish from the picker. To restore the fully official route, re-enable the llm-deepseek row in ' +
-        'cordis.patch.yml first, then restart.',
+        'Notice: on this legacy Host the official DeepSeek row is disabled, so Vision Router is using its compatibility ' +
+        'keep-alive route. To restore the fully official route, re-enable llm-deepseek in cordis.patch.yml and restart.',
+      stealthOfficialHostOwnedHint:
+        'The official DeepSeek provider is disabled or unavailable, but this DSH Host owns that provider route. Vision Router ' +
+        'will not recreate it. Re-enable llm-deepseek, then use the “+ Auto Vision” wrapper / Vision control for image tasks.',
       numTimeoutMs: 'Single vision request timeout (ms)',
       numVisionTaskTimeoutMs: 'Vision task maximum time (ms)',
       numOcrTimeoutMs: 'OCR maximum time (ms)',
@@ -3913,7 +3914,11 @@ window.__ModuleLoader__.load({
       const stealthNotice = () => {
         if (testState.status !== 'done') return null
         const state = testState.result && testState.result.stealth
-        if (!state || state.active !== true || state.reason !== 'official-unavailable') return null
+        if (!state) return null
+        if (state.reason === 'host-owned-official-unavailable') {
+          return h('p', { className: 'vr-hint vr-stealth-notice' }, t('stealthOfficialHostOwnedHint'))
+        }
+        if (state.active !== true || state.reason !== 'official-unavailable') return null
         return h('p', { className: 'vr-hint vr-stealth-notice' }, t('stealthOfficialDeadHint'))
       }
 

package/lib/core-primitives.js

@@ -72,6 +72,7 @@ import {
 } from './http-body-limit.js'
 import { writeArtifactFile } from './artifact-boundary.js'
 import { stripTrailingSlashes } from './string-normalization.js'
+import { isOffloadedImageBlock, offloadedImagePlaceholder } from './image-offload-compat.js'
 import { proxyHostMatchesAny } from './proxy-routing.js'
 import { parseVersionComparator } from './version-range.js'
 import { captureWindowsDesktop } from './windows-desktop-capture.js'
@@ -1454,6 +1455,108 @@ export async function ocrWithTesseract(bytes, timeoutMs = 60000) {
   return String(stdout ?? '')
 }
 
+const TESSERACT_OCR_PSMS = Object.freeze([6, 3, 11])
+const TESSERACT_REVIEW_THRESHOLD = 70
+const TESSERACT_CANDIDATE_MARGIN = 5
+const TESSERACT_CONFUSABLE_RUN = /[0O1IlL]{3,}/
+
+function median(values) {
+  if (!Array.isArray(values) || values.length === 0) return 0
+  const ordered = [...values].sort((a, b) => a - b)
+  const middle = Math.floor(ordered.length / 2)
+  return ordered.length % 2 === 0
+    ? (ordered[middle - 1] + ordered[middle]) / 2
+    : ordered[middle]
+}
+
+export function parseTesseractTsv(tsv) {
+  const words = []
+  for (const line of String(tsv ?? '').split(/\r?\n/).slice(1)) {
+    const columns = line.split('\t')
+    if (columns.length < 12) continue
+    const confidence = Number(columns[10])
+    const text = columns.slice(11).join('\t').trim()
+    if (text === '' || !Number.isFinite(confidence) || confidence < 0) continue
+    words.push({ text, confidence })
+  }
+  return words
+}
+
+export function assessTesseractOcr(text, tsv, psm = 6) {
+  const words = parseTesseractTsv(tsv)
+  const confidences = words.map((word) => word.confidence)
+  const precisionWords = words.filter((word) => /[0-9$%#:/._-]/.test(word.text))
+  const precisionConfidences = precisionWords.map((word) => word.confidence)
+  const riskyTokens = words
+    .map((word) => word.text)
+    .filter((token) => TESSERACT_CONFUSABLE_RUN.test(token))
+  const quality = precisionConfidences.length > 0
+    ? Math.min(...precisionConfidences)
+    : median(confidences)
+  return {
+    psm,
+    text: String(text ?? '').trim(),
+    words: words.length,
+    quality: Number.isFinite(quality) ? quality : 0,
+    riskyTokens,
+    uncertain: words.length === 0 || quality < TESSERACT_REVIEW_THRESHOLD || riskyTokens.length > 0,
+  }
+}
+
+export function selectTesseractOcrCandidate(candidates) {
+  const usable = (Array.isArray(candidates) ? candidates : []).filter((candidate) => candidate && candidate.text)
+  if (usable.length === 0) return undefined
+  let selected = usable[0]
+  for (const candidate of usable.slice(1)) {
+    if (candidate.quality >= selected.quality + TESSERACT_CANDIDATE_MARGIN) selected = candidate
+  }
+  return selected
+}
+
+export async function ocrWithTesseractAdaptive(bytes, timeoutMs = 12000, options = {}) {
+  const exec = typeof options.exec === 'function' ? options.exec : promisify(execFile)
+  const requestedBudget = Number(timeoutMs)
+  const budgetMs = Number.isFinite(requestedBudget) && requestedBudget > 0
+    ? Math.min(60000, requestedBudget)
+    : 12000
+  const started = Date.now()
+  const attemptedPsms = []
+  const remaining = () => Math.max(1, budgetMs - (Date.now() - started))
+  const run = async (psm) => {
+    attemptedPsms.push(psm)
+    const common = ['stdin', 'stdout', '-l', 'chi_sim+eng', '--psm', String(psm)]
+    const execOptions = () => ({
+      timeout: remaining(),
+      maxBuffer: 32 * 1024 * 1024,
+      input: bytes,
+    })
+    const { stdout: plain } = await exec('tesseract', common, execOptions())
+    const text = String(plain ?? '').trim()
+    if (text === '') return assessTesseractOcr('', '', psm)
+    try {
+      const { stdout: tsv } = await exec('tesseract', [...common, 'tsv'], execOptions())
+      return assessTesseractOcr(text, String(tsv ?? ''), psm)
+    } catch {
+      return { psm, text, words: 0, quality: 0, riskyTokens: [], uncertain: true }
+    }
+  }
+
+  const candidates = [await run(TESSERACT_OCR_PSMS[0])]
+  if (candidates[0].text !== '' && !candidates[0].uncertain) {
+    return { ...candidates[0], attemptedPsms }
+  }
+  for (const psm of TESSERACT_OCR_PSMS.slice(1)) {
+    if (Date.now() - started >= budgetMs) break
+    try {
+      candidates.push(await run(psm))
+    } catch {
+      // Keep the first successful local OCR result when an optional review pass fails.
+    }
+  }
+  const selected = selectTesseractOcrCandidate(candidates) ?? candidates[0]
+  return { ...selected, attemptedPsms }
+}
+
 /** Rough token estimate for one message (no tokenizer; conservative on purpose). */
 export function estimateTokens(message) {
   let chars = 0
@@ -1467,7 +1570,10 @@ export function estimateTokens(message) {
     if (typeof block.text === 'string') chars += block.text.length
     if (typeof block.arguments === 'string') chars += block.arguments.length
     if (typeof block.name === 'string') chars += block.name.length
-    if (block.type === 'image') images += 1
+    if (block.type === 'image') {
+      if (isOffloadedImageBlock(block)) chars += offloadedImagePlaceholder(block).length
+      else images += 1
+    }
     if (Array.isArray(block.content)) block.content.forEach(walk)
   }
   if (message === null || message === undefined) return 0
@@ -1949,6 +2055,9 @@ export function dedupeHttpProviders(pairs, httpProviders) {
 /** Convert harness image/text blocks plus resolved image bytes into OpenAI wire content. */
 export function toOpenAIContent(blocks, bytesOf) {
   return blocks.map((block) => {
+    if (isOffloadedImageBlock(block)) {
+      return { type: 'text', text: offloadedImagePlaceholder(block) }
+    }
     if (block && block.type === 'image' && block.attachment) {
       const bytes = bytesOf(block.attachment)
       const data = Buffer.from(bytes).toString('base64')
@@ -2162,9 +2271,10 @@ export function launchEnvironmentLike(env) {
 }
 
 /**
- * Rebuild the stock DeepSeek adapter from this plugin for the stealth
- * takeover: the `llm-deepseek` settings section + the credential seam + the
- * anonymous user id, exactly like the stock row does it.
+ * Legacy-only DeepSeek reconstruction for Host contracts that do not own the
+ * official provider lifecycle. Modern Hosts keep `deepseek-official` Host-owned
+ * because request-local attachment/file/image-access seams cannot be cloned
+ * safely here. Remove this helper when the legacy takeover window is retired.
  */
 export function createNativeDeepSeekAdapter(ctx) {
   const env = launchEnvironmentLike(
@@ -2262,7 +2372,7 @@ export async function buildInstantLocalMap(ctx, messages, provider, options = {}
   for (const message of messages) {
     if (!message || !Array.isArray(message.content)) continue
     for (const block of message.content) {
-      if (!block || block.type !== 'image' || !block.attachment) continue
+      if (!block || block.type !== 'image' || !block.attachment || isOffloadedImageBlock(block)) continue
       const attachment = block.attachment
       const id = attachment.attachmentId || attachment.id || ''
       if (id === '' || seen.has(id)) continue

package/lib/degraded-local-evidence.js

@@ -0,0 +1,39 @@
+/** Bounded policy for stopping Host tools from re-parsing images after vision degradation. */
+
+function flattenStrings(value, out = [], depth = 0) {
+  if (out.length >= 64 || depth > 6 || value == null) return out
+  if (typeof value === 'string') { out.push(value); return out }
+  if (Array.isArray(value)) {
+    for (const item of value) flattenStrings(item, out, depth + 1)
+    return out
+  }
+  if (typeof value === 'object') {
+    for (const item of Object.values(value)) flattenStrings(item, out, depth + 1)
+  }
+  return out
+}
+
+function normalizedEvidenceTokens(tokens) {
+  const out = []
+  for (const token of tokens) {
+    if (typeof token !== 'string' || token === '') continue
+    out.push(token)
+    if (token.startsWith('sha256:')) {
+      const digest = token.slice('sha256:'.length)
+      out.push(digest)
+      if (digest.length >= 16) out.push(digest.slice(0, 16))
+    }
+  }
+  return out
+}
+
+export function shouldBlockDegradedHostTool(name, args, evidenceTokens = []) {
+  if (name !== 'bash' && name !== 'read_image') return false
+  const tokens = normalizedEvidenceTokens(evidenceTokens)
+  if (tokens.length === 0) return false
+  const strings = flattenStrings(args)
+  return strings.some((text) => {
+    if (text.includes('.dsh/attachments') || text.includes('/attachments/v1/objects/')) return true
+    return tokens.some(token => text.includes(token))
+  })
+}

package/lib/dsh-contract-compat.js

@@ -26,6 +26,197 @@ const VISION_ROUTER_NORMALIZED_BYTES = LEGACY_VISION_ATTACHMENT_BYTES
 const HOST_CAPABILITIES_PATH = '/_dsh/vision-router/host-capabilities'
 const capabilityRouteInstalls = new WeakSet()
 
+function sessionQueryOf(ctx) {
+  if (!ctx || typeof ctx !== 'object') return undefined
+  try {
+    if (typeof ctx.get === 'function') {
+      const query = ctx.get('sessionQuery')
+      if (query && typeof query === 'object') return query
+    }
+  } catch {
+    // A partial/legacy Host may not expose SessionQuery through ctx.get().
+  }
+  try {
+    const query = ctx.sessionQuery
+    return query && typeof query === 'object' ? query : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Build the narrow bounded Session event reader used by durable surface repair.
+ * DSH rc.8+ exposes `sessionQuery.readEvent({ sessionId, seq })`; resolve the
+ * service at call time so Host service replacement/hot reload stays visible.
+ * Missing capability is explicit and lets isolated/legacy callers use their
+ * existing Session-local compatibility fallback. Once the Host advertises the
+ * reader, operational failures propagate instead of silently falling back to
+ * deprecated synchronous Session history.
+ */
+export function createSessionEventReader(ctx) {
+  return async function readSessionEvent(session, seq) {
+    const sessionId = session?.id
+    if (sessionId === undefined || sessionId === null) return { supported: false }
+    if (!Number.isSafeInteger(seq) || seq < 0 || Object.is(seq, -0)) {
+      throw new TypeError(`session event seq must be a non-negative safe integer, got ${String(seq)}`)
+    }
+    const query = sessionQueryOf(ctx)
+    if (!query || typeof query.readEvent !== 'function') return { supported: false }
+    const window = await query.readEvent({ sessionId, seq })
+    const event = window?.target
+    if (!event || typeof event !== 'object') {
+      throw new Error(`sessionQuery.readEvent returned no target for seq ${seq}`)
+    }
+    if (event.seq !== undefined && event.seq !== seq) {
+      throw new Error(`sessionQuery.readEvent returned seq ${String(event.seq)} for requested seq ${seq}`)
+    }
+    return { supported: true, event }
+  }
+}
+
+
+const SESSION_EVENT_TAIL_INITIAL_AFTER = 50
+const SESSION_EVENT_TAIL_MAX_EVENTS = 4096
+const SESSION_EVENT_TAIL_MAX_READS = 128
+
+function sessionQueryCode(error) {
+  return typeof error?.code === 'string' ? error.code : undefined
+}
+
+/**
+ * Read raw Session events strictly after one known committed seq through the
+ * Host-owned bounded `sessionQuery.readEvent()` window contract.
+ *
+ * The reader adapts to deployments that lower SessionQuery's configurable
+ * `readWindowMax`, never materializes the full Session log, and caps both
+ * events and Host reads. Missing capability is explicit. Operational failures
+ * from an advertised capability propagate to the caller; a cap is reported as
+ * `truncated` so routing can fail safe without a synchronous-history fallback.
+ */
+export function createSessionEventTailReader(ctx) {
+  let afterHint = SESSION_EVENT_TAIL_INITIAL_AFTER
+
+  const readWindow = async (query, sessionId, seq) => {
+    let after = afterHint
+    while (true) {
+      try {
+        const request = after > 0 ? { sessionId, seq, after } : { sessionId, seq }
+        const window = await query.readEvent(request)
+        afterHint = after
+        return { window, after }
+      } catch (error) {
+        if (sessionQueryCode(error) !== 'SESSION_QUERY_INVALID_WINDOW' || after <= 0) throw error
+        after = after <= 1 ? 0 : Math.floor(after / 2)
+      }
+    }
+  }
+
+  return async function readSessionEventTail(session, anchorSeq, options = {}) {
+    const sessionId = session?.id
+    if (sessionId === undefined || sessionId === null) return { supported: false }
+    if (!Number.isSafeInteger(anchorSeq) || anchorSeq < 0 || Object.is(anchorSeq, -0)) {
+      throw new TypeError(`session tail anchor seq must be a non-negative safe integer, got ${String(anchorSeq)}`)
+    }
+    const query = sessionQueryOf(ctx)
+    if (!query || typeof query.readEvent !== 'function') return { supported: false }
+
+    const collect = options?.collect !== false
+    const events = []
+    let capturedThroughSeq = anchorSeq
+    let cursor = anchorSeq
+    let inspected = 0
+    let reads = 0
+
+    while (reads < SESSION_EVENT_TAIL_MAX_READS) {
+      let result
+      try {
+        result = await readWindow(query, sessionId, cursor)
+      } catch (error) {
+        if (sessionQueryCode(error) === 'SESSION_QUERY_EVENT_NOT_FOUND' && cursor > anchorSeq) {
+          return { supported: true, events, capturedThroughSeq, truncated: false }
+        }
+        throw error
+      }
+      reads += 1
+
+      const window = result.window
+      const target = window?.target
+      if (!target || typeof target !== 'object' || target.seq !== cursor) {
+        throw new Error(`sessionQuery.readEvent returned an invalid target for seq ${cursor}`)
+      }
+      if (!Array.isArray(window.events) || window.events.length === 0) {
+        throw new Error(`sessionQuery.readEvent returned no event window for seq ${cursor}`)
+      }
+      const windowEvents = window.events
+      let expectedSeq = cursor
+      let endSeq = cursor
+      for (const event of windowEvents) {
+        const seq = event?.seq
+        if (!Number.isSafeInteger(seq) || seq !== expectedSeq) {
+          throw new Error(
+            `sessionQuery.readEvent returned non-contiguous seq ${String(seq)}; expected ${expectedSeq}`,
+          )
+        }
+        expectedSeq += 1
+        endSeq = seq
+        if (seq <= capturedThroughSeq) continue
+        capturedThroughSeq = seq
+        inspected += 1
+        if (collect) events.push(event)
+        if (inspected >= SESSION_EVENT_TAIL_MAX_EVENTS) {
+          return { supported: true, events, capturedThroughSeq, truncated: true }
+        }
+      }
+      if (Number.isSafeInteger(window?.endSeq) && window.endSeq !== endSeq) {
+        throw new Error(
+          `sessionQuery.readEvent returned endSeq ${String(window.endSeq)} for window ending at ${endSeq}`,
+        )
+      }
+
+      if (result.after > 0) {
+        if (endSeq <= cursor || windowEvents.length < result.after + 1) {
+          return { supported: true, events, capturedThroughSeq: Math.max(capturedThroughSeq, endSeq), truncated: false }
+        }
+        cursor = endSeq
+        continue
+      }
+
+      // `readWindowMax: 0` is a valid Host configuration. Walk exact seqs and
+      // use the typed EVENT_NOT_FOUND result as the logical tail sentinel.
+      cursor += 1
+    }
+
+    return { supported: true, events, capturedThroughSeq, truncated: true }
+  }
+}
+
+
+/**
+ * Build the narrow asynchronous Session-log reader used only for cold
+ * canonical attachment recovery after the bounded cache evicts a ref.
+ * Supported Hosts own replay validation through `sessionQuery.readSession()`;
+ * callers receive detached events and never touch synchronous Session history.
+ */
+export function createSessionLogReader(ctx) {
+  return async function readSessionLog(session) {
+    const sessionId = session?.id
+    if (sessionId === undefined || sessionId === null) return { supported: false }
+    const query = sessionQueryOf(ctx)
+    if (!query || typeof query.readSession !== 'function') return { supported: false }
+    const snapshot = await query.readSession(sessionId)
+    if (!snapshot || !Array.isArray(snapshot.events)) {
+      throw new Error('sessionQuery.readSession returned no event log')
+    }
+    const observedId = snapshot.session?.id
+    if (observedId !== undefined && observedId !== sessionId) {
+      throw new Error(
+        `sessionQuery.readSession returned session ${String(observedId)} for requested ${String(sessionId)}`,
+      )
+    }
+    return { supported: true, events: snapshot.events }
+  }
+}
+
 function attachmentStoreOf(ctx) {
   if (!ctx || typeof ctx !== 'object') return undefined
   try {
@@ -111,6 +302,17 @@ export function hasBatchAttachmentContract(ctx) {
   return !!store && typeof store.saveImages === 'function'
 }
 
+/**
+ * DSH Hosts on the canonical batch-attachment contract also keep the official
+ * DeepSeek provider Host-owned. Later generations add still more request-local
+ * file/image-access seams, so DVR may wrap this provider but must never rebuild
+ * or resurrect it. Keep this semantic fact
+ * centralized so Core does not grow a second Host-generation detector.
+ */
+export function hostOwnsOfficialDeepSeekProvider(ctx) {
+  return hasBatchAttachmentContract(ctx)
+}
+
 function exactAlphaNormalizationDefaults(policy) {
   return !!policy && typeof policy === 'object' &&
     policy.maxPixels === DSH_ALPHA_DEFAULT_NORMALIZED_PIXELS &&

package/lib/dsh-support-window.js

@@ -6,7 +6,7 @@ export const DSH_SUPPORT_WINDOW = Object.freeze({
 
 export const DSH_VERIFICATION_EVIDENCE = Object.freeze({
   exactStable: '0.1.5-rc.2',
-  exactPreview: '0.1.5-alpha.2',
+  exactPreview: '0.1.6-alpha.1',
   stableCanaryDistTag: 'latest',
   previewCanaryDistTag: 'alpha',
 })