dsh-vision-router 2.2.1 → 2.2.3

package/lib/dsh-settings-017-compat.js

@@ -0,0 +1,416 @@
+const SETTINGS_NS = 'vision-router'
+export const LOCAL_SETTINGS_PATH = '/_dsh/vision-router/local-settings'
+export const DSH_017_SETTINGS_COMPAT_MARK = '__visionRouterDsh017ConfigEditorCompat'
+const BODY_LIMIT_BYTES = 256 * 1024
+const REVISION_REGISTRY_KEY = Symbol.for('dsh-vision-router.settings-017-revisions')
+
+function revisionRegistry() {
+  let registry = globalThis[REVISION_REGISTRY_KEY]
+  if (!(registry instanceof Map)) {
+    registry = new Map()
+    Object.defineProperty(globalThis, REVISION_REGISTRY_KEY, {
+      value: registry,
+      configurable: true,
+    })
+  }
+  return registry
+}
+
+function objectLike(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function plainObject(value) {
+  if (!objectLike(value)) return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+function clone(value) {
+  return value === undefined ? undefined : structuredClone(value)
+}
+
+function mergeResolved(base, overlay) {
+  if (!plainObject(base) || !plainObject(overlay)) return clone(overlay)
+  const next = clone(base)
+  for (const [key, value] of Object.entries(overlay)) {
+    next[key] = plainObject(value) && plainObject(next[key])
+      ? mergeResolved(next[key], value)
+      : clone(value)
+  }
+  return next
+}
+
+function jsonEqual(left, right) {
+  if (left === right) return true
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return Array.isArray(left) && Array.isArray(right)
+      && left.length === right.length
+      && left.every((value, index) => jsonEqual(value, right[index]))
+  }
+  if (!plainObject(left) || !plainObject(right)) return false
+  const leftKeys = Object.keys(left)
+  const rightKeys = Object.keys(right)
+  return leftKeys.length === rightKeys.length
+    && leftKeys.every((key) => Object.hasOwn(right, key) && jsonEqual(left[key], right[key]))
+}
+
+function logicalUserLayer(current, inherited) {
+  const user = Object.create(null)
+  const keys = new Set([
+    ...Object.keys(objectLike(current) ? current : {}),
+    ...Object.keys(objectLike(inherited) ? inherited : {}),
+  ])
+  for (const key of keys) {
+    const currentHas = objectLike(current) && Object.hasOwn(current, key)
+    const inheritedHas = objectLike(inherited) && Object.hasOwn(inherited, key)
+    if (currentHas === inheritedHas && (!currentHas || jsonEqual(current[key], inherited[key]))) continue
+    if (currentHas) user[key] = clone(current[key])
+  }
+  return user
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue)
+  if (!plainObject(value)) return value
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]))
+}
+
+function fingerprint(value) {
+  return JSON.stringify(stableValue(value))
+}
+
+function revisionKey(editor, namespace) {
+  let documentPath
+  try { documentPath = editor?.documentPath } catch {}
+  return `${String(documentPath ?? 'process-local-profile')}\u0000${namespace}`
+}
+
+/**
+ * Ordinary Config writes reload DVR, so a plugin-instance counter is unsafe.
+ * Keep one process-level monotonic counter per profile document + namespace.
+ * The registry survives DVR HMR and advances whenever the effective persisted
+ * layers observed at the compatibility boundary change. A process restart also
+ * resets every browser connection, which forces a fresh descriptor read.
+ */
+function revisionFor(editor, namespace, current, inherited) {
+  const key = revisionKey(editor, namespace)
+  const valueFingerprint = fingerprint({ current, inherited })
+  const registry = revisionRegistry()
+  const previous = registry.get(key)
+  if (!previous) {
+    const state = { fingerprint: valueFingerprint, revision: 0 }
+    registry.set(key, state)
+    return state.revision
+  }
+  if (previous.fingerprint !== valueFingerprint) {
+    previous.fingerprint = valueFingerprint
+    previous.revision += 1
+  }
+  return previous.revision
+}
+
+function serviceOf(ctx, name) {
+  try {
+    const value = typeof ctx?.get === 'function' ? ctx.get(name) : undefined
+    if (value !== undefined && value !== null) return value
+  } catch {}
+  try {
+    const value = ctx?.[name]
+    return value === undefined || value === null ? undefined : value
+  } catch {
+    return undefined
+  }
+}
+
+function configEditorRow(editor, namespace) {
+  const rows = typeof editor?.configuration === 'function' ? editor.configuration() : []
+  if (!Array.isArray(rows)) return undefined
+  return rows.find((row) => row?.entry?.options?.id === namespace)
+}
+
+function settingsConflict(expected, actual) {
+  const error = new Error(`Vision Router settings changed before this write landed (expected ${expected}, actual ${actual})`)
+  error.code = 'SETTINGS_CONFLICT'
+  error.expected = expected
+  error.actual = actual
+  return error
+}
+
+function admissionError(message) {
+  const error = new Error(message)
+  error.code = 'SETTINGS_INVALID_MUTATION'
+  return error
+}
+
+function validateOperations(ops) {
+  if (!Array.isArray(ops) || ops.length === 0) throw admissionError('settings operations must be a non-empty array')
+  return ops.map((op) => {
+    if (!objectLike(op) || (op.op !== 'set' && op.op !== 'unset')) {
+      throw admissionError('settings operation must be set or unset')
+    }
+    if (!Array.isArray(op.path) || op.path.length !== 1 || typeof op.path[0] !== 'string' || op.path[0] === '') {
+      throw admissionError('Vision Router settings compatibility accepts one top-level field per operation')
+    }
+    const key = op.path[0]
+    if (key === '__proto__' || key === 'prototype' || key === 'constructor') {
+      throw admissionError('unsafe settings field name')
+    }
+    return op.op === 'set'
+      ? { op: 'set', path: [key], value: clone(op.value) }
+      : { op: 'unset', path: [key] }
+  })
+}
+
+function applyOperations(current, inherited, ops) {
+  const next = clone(objectLike(current) ? current : {})
+  for (const op of ops) {
+    const key = op.path[0]
+    if (op.op === 'set') {
+      next[key] = clone(op.value)
+      continue
+    }
+    if (objectLike(inherited) && Object.hasOwn(inherited, key)) next[key] = clone(inherited[key])
+    else delete next[key]
+  }
+  return next
+}
+
+function createConfigEditorSettingsFacade(editor, entryConfig, namespace) {
+  const listeners = new Set()
+
+  function state() {
+    const row = configEditorRow(editor, namespace)
+    if (!row) return undefined
+    const current = objectLike(row.entry?.options?.config) ? row.entry.options.config : {}
+    const inherited = objectLike(row.inherited) ? row.inherited : {}
+    const base = mergeResolved(entryConfig, inherited)
+    const value = mergeResolved(entryConfig, current)
+    return {
+      row,
+      descriptor: {
+        ns: namespace,
+        value,
+        base,
+        user: logicalUserLayer(current, inherited),
+        revision: revisionFor(editor, namespace, current, inherited),
+        applies: true,
+      },
+    }
+  }
+
+  function notify(value) {
+    for (const listener of [...listeners]) {
+      try { listener(value, undefined) } catch {}
+    }
+  }
+
+  const scope = {
+    get() {
+      return state()?.descriptor.value ?? entryConfig
+    },
+    watch(listener) {
+      if (typeof listener !== 'function') return () => {}
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+
+  return {
+    [DSH_017_SETTINGS_COMPAT_MARK]: true,
+    get writable() {
+      return state() !== undefined
+    },
+    get(namespaceName) {
+      return namespaceName === namespace ? scope.get() : undefined
+    },
+    register(namespaceName) {
+      if (namespaceName !== namespace) {
+        throw new Error(`vision-router: unexpected settings namespace ${String(namespaceName)}`)
+      }
+      return scope
+    },
+    describe() {
+      const current = state()
+      return current ? [clone(current.descriptor)] : []
+    },
+    async mutate(namespaceName, operations, expectedRevision) {
+      if (namespaceName !== namespace) throw new Error(`No configurable plugin entry ${JSON.stringify(namespaceName)}`)
+      const before = state()
+      if (!before) throw new Error(`No configurable plugin entry ${JSON.stringify(namespace)}`)
+      if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+        throw admissionError('expectedRevision must be a non-negative safe integer')
+      }
+      if (expectedRevision !== before.descriptor.revision) {
+        throw settingsConflict(expectedRevision, before.descriptor.revision)
+      }
+      const ops = validateOperations(operations)
+      const entry = before.row.entry
+      await editor.edit(entry, (current, inherited) => applyOperations(current, inherited, ops))
+      const after = state()
+      if (!after) throw new Error('Vision Router configuration entry disappeared after the write')
+      notify(after.descriptor.value)
+      return clone(after.descriptor)
+    },
+  }
+}
+
+/**
+ * DSH 0.1.7 services may mount after DVR's apply() starts. Capture ConfigEditor
+ * through its own lifecycle injection and resolve the settings generation when
+ * each consumer actually accesses it. This avoids both startup-order races and
+ * undeclared child-context service reads.
+ */
+function contextWithLazySettingsCompatibility(ctx, entryConfig, namespace) {
+  const wrappers = new WeakMap()
+  const facades = new WeakMap()
+  let injectedEditor
+
+  try {
+    if (typeof ctx?.inject === 'function') {
+      ctx.inject(['configEditor'], (editorCtx) => {
+        injectedEditor = serviceOf(editorCtx, 'configEditor')
+      })
+    }
+  } catch {
+    // Older Hosts may not expose ConfigEditor; their native SettingsProvider stays authoritative.
+  }
+
+  function compatibleSettings(target) {
+    const settings = serviceOf(target, 'settings') ?? serviceOf(ctx, 'settings')
+    if (!settings || typeof settings.register === 'function') return settings
+    const editor = serviceOf(target, 'configEditor') ?? injectedEditor ?? serviceOf(ctx, 'configEditor')
+    if (typeof settings.describe !== 'function'
+        || !editor || typeof editor.edit !== 'function' || typeof editor.configuration !== 'function') {
+      return settings
+    }
+    let facade = facades.get(editor)
+    if (!facade) {
+      facade = createConfigEditorSettingsFacade(editor, entryConfig, namespace)
+      facades.set(editor, facade)
+    }
+    return facade
+  }
+
+  function wrap(target) {
+    if (!target || typeof target !== 'object') return target
+    const held = wrappers.get(target)
+    if (held) return held
+    const wrapped = new Proxy(target, {
+      get(object, property) {
+        if (property === 'settings') return compatibleSettings(object)
+        if (property === 'get') {
+          const get = Reflect.get(object, property, object)
+          if (typeof get !== 'function') return get
+          return (name, ...rest) => name === 'settings'
+            ? compatibleSettings(object)
+            : get.call(object, name, ...rest)
+        }
+        if (property === 'inject') {
+          const inject = Reflect.get(object, property, object)
+          if (typeof inject !== 'function') return inject
+          return (dependencies, callback, ...rest) => inject.call(
+            object,
+            dependencies,
+            typeof callback === 'function' && Array.isArray(dependencies) && dependencies.includes('settings')
+              ? (child) => callback(wrap(child))
+              : callback,
+            ...rest,
+          )
+        }
+        const value = Reflect.get(object, property, object)
+        return typeof value === 'function' ? value.bind(object) : value
+      },
+    })
+    wrappers.set(target, wrapped)
+    return wrapped
+  }
+
+  return wrap(ctx)
+}
+
+/**
+ * DSH 0.1.7 removes the legacy SettingsProvider.register() namespace API and
+ * makes ordinary plugin configuration profile-owned through ConfigEditor.
+ * Preserve DVR's mature settings consumers behind the old semantic face while
+ * leaving older Hosts on their native SettingsProvider whenever it is present.
+ */
+export function installDsh017SettingsCompatibility(ctx, entryConfig = {}, options = {}) {
+  const namespace = typeof options.namespace === 'string' && options.namespace !== '' ? options.namespace : SETTINGS_NS
+  return contextWithLazySettingsCompatibility(ctx, entryConfig, namespace)
+}
+
+function sendJson(res, status, body) {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  res.end(JSON.stringify(body))
+}
+
+async function readJson(req) {
+  let size = 0
+  const chunks = []
+  for await (const chunk of req) {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    size += bytes.length
+    if (size > BODY_LIMIT_BYTES) throw Object.assign(new Error('request body too large'), { statusCode: 413 })
+    chunks.push(bytes)
+  }
+  if (chunks.length === 0) return {}
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+function namespaceDescriptor(settings) {
+  const descriptors = settings.describe({ redactSecrets: true })
+  return Array.isArray(descriptors) ? descriptors.find((entry) => entry?.ns === SETTINGS_NS) : undefined
+}
+
+/** Local-only transport for the 0.1.7 browser, which no longer exposes settingsScope. */
+export function installDsh017LocalSettingsTransport(ctx) {
+  if (!ctx || typeof ctx.inject !== 'function') return
+  ctx.inject(['settings', 'webServer'], (webCtx) => {
+    if (webCtx.settings?.[DSH_017_SETTINGS_COMPAT_MARK] !== true) return
+    if (typeof webCtx.settings.describe !== 'function' || typeof webCtx.settings.mutate !== 'function') return
+    webCtx.effect(
+      () => webCtx.webServer.register({
+        kind: 'exact',
+        path: LOCAL_SETTINGS_PATH,
+        async handler(req, res) {
+          if (req.method === 'GET') {
+            const descriptor = namespaceDescriptor(webCtx.settings)
+            if (!descriptor) {
+              sendJson(res, 404, { ok: false, error: { code: 'settings-unavailable', message: 'Vision Router settings are unavailable' } })
+              return
+            }
+            sendJson(res, 200, { ok: true, value: { ...descriptor, writable: webCtx.settings.writable === true } })
+            return
+          }
+          if (req.method !== 'POST') {
+            res.setHeader('Allow', 'GET, POST')
+            sendJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'method not allowed' } })
+            return
+          }
+          try {
+            const payload = await readJson(req)
+            await webCtx.settings.mutate(SETTINGS_NS, payload?.ops, payload?.expectedRevision)
+            const descriptor = namespaceDescriptor(webCtx.settings)
+            if (!descriptor) throw new Error('Vision Router settings disappeared after the write')
+            sendJson(res, 200, { ok: true, value: { ...descriptor, writable: webCtx.settings.writable === true } })
+          } catch (error) {
+            const conflict = error?.code === 'SETTINGS_CONFLICT'
+            sendJson(res, error?.statusCode ?? (conflict ? 409 : 400), {
+              ok: false,
+              error: {
+                code: conflict ? 'settings-conflict' : 'settings-rejected',
+                message: error?.message ?? String(error),
+                ...(conflict ? { details: { expected: error.expected, actual: error.actual } } : {}),
+              },
+            })
+          }
+        },
+      }),
+      'vision-router: DSH 0.1.7 local settings transport',
+    )
+  })
+}

package/lib/dsh-support-window.js

@@ -1,12 +1,12 @@
 export const DSH_SUPPORT_WINDOW = Object.freeze({
-  dvrTrain: '2.1.x',
+  dvrTrain: '2.2.x',
   minimum: '0.1.0-rc.8',
-  currentStable: '0.1.5-rc.2',
+  currentStable: '0.1.5-rc.3',
 })
 
 export const DSH_VERIFICATION_EVIDENCE = Object.freeze({
-  exactStable: '0.1.5-rc.2',
-  exactPreview: '0.1.6-alpha.1',
+  exactStable: '0.1.5-rc.3',
+  exactPreview: '0.1.7-rc.2',
   stableCanaryDistTag: 'latest',
   previewCanaryDistTag: 'alpha',
 })

package/lib/public-entry.js

@@ -7,6 +7,10 @@ import {
   installVisionProviderTransport,
 } from './vision-provider-transport.js'
 import { installLegacyGlobalProxyBoundary } from './legacy-global-proxy-boundary.js'
+import { installDsh017SettingsCompatibility } from './dsh-settings-017-compat.js'
+import { installDsh017RootLocalSettingsTransport } from './web/dsh-settings-017-root-transport.js'
+import { installSettings017ClientCompatibility } from './settings-client-017-compat.js'
+import { installVisionRouterMessageSourceBoundary } from './session-message-source-compat.js'
 
 export * from '../entry.js'
 
@@ -33,7 +37,23 @@ function liveVisionConfig(ctx, fallback) {
  * settings therefore leave DSH/Host as the sole network authority.
  */
 export function apply(ctx, config = {}) {
-  const hardening = createVisionToggleRootHardening(ctx, config)
+  // DSH 0.1.7 replaces SettingsProvider.register() with profile-owned
+  // ConfigEditor writes for ordinary fields. Feature-detect that exact contract
+  // and present DVR's mature settings face without changing older Hosts.
+  const settingsCtx = installDsh017SettingsCompatibility(ctx, config, {
+    namespace: 'vision-router',
+    Config: base.Config,
+  })
+  // The 0.1.7 browser no longer exposes settingsScope. Keep the server route on
+  // the application root so ConfigEditor reconciliation cannot dispose an
+  // in-flight Settings POST, while each DVR generation supplies the live facade.
+  installDsh017RootLocalSettingsTransport(settingsCtx)
+  installSettings017ClientCompatibility(settingsCtx)
+  // Session V3 and V4 disagree on plugin message attribution. Normalize only
+  // DVR-authored contexts at the final hook-publication seam using the Session's
+  // own durable header version, never a DSH package-version guess.
+  const sessionSourceCtx = installVisionRouterMessageSourceBoundary(settingsCtx)
+  const hardening = createVisionToggleRootHardening(sessionSourceCtx, config)
   const runtimeCtx = contextWithVisionRoutingTopologyRefresh(hardening.ctx)
   const transport = createVisionProviderTransport({
     ctx: hardening.ctx,

package/lib/remote-settings-bridge.js

@@ -40,6 +40,7 @@ export const REMOTE_SETTINGS_READABLE_FIELDS = Object.freeze([
   'visionTaskTimeoutMs',
   'visionTurnBudgetMs',
   'ocrTimeoutMs',
+  'ocrEngine',
   'freeFallback',
   'freeCloudFirst',
   'autoWrapProviders',

package/lib/runtime-i18n-boundary.js

@@ -183,6 +183,10 @@ function translateLegacyRuntimeText(value, i18n) {
       'In structured mode, vision_ocr with an omitted engine or engine=auto uses vision-model OCR (engine=vision) directly instead of accepting the first non-empty local Tesseract result; explicit engine=tesseract or engine=vision is always preserved.',
       'For vision_ocr, engine=auto always tries local Tesseract first and falls back to the vision model only when local OCR fails or returns no text; structured mode does not change this order. Use explicit engine=vision to force vision-model OCR.',
     )
+    .replace(
+      '不要默认把 OCR 当第二步；仅在需要逐字保真时用 vision_ocr，并把结果当作需要结合上下文验证的证据。UI/截图语义通常用 vision_describe 或 vision_detect，精确定位用 vision_ground。vision_ocr 未显式指定 engine 时遵循设置中的 OCR 默认引擎；单次显式 engine=tesseract/vision 始终优先。完成至少 1 次后续证据调用后，证据充分就直接作答，不要为了流程继续调用。',
+      'Do not default to OCR as the second step. Use vision_ocr only for verbatim evidence. If it returns uncertain:true, verify the ambiguous text against context when possible; if uncertain:false and the text is sufficient, answer without redundant verification. For UI/screenshot semantics use vision_describe or vision_detect; use vision_ground for precise localization. When vision_ocr has no explicit engine, it follows the configured Default OCR engine; per-call engine=tesseract/vision always wins. After at least 1 follow-up evidence call, answer once the evidence is sufficient instead of calling more tools just for the workflow.',
+    )
     .replace(
       '不要默认把 OCR 当第二步；仅在需要逐字保真时用 vision_ocr，并把结果当作需要结合上下文验证的证据。UI/截图语义通常用 vision_describe 或 vision_detect，精确定位用 vision_ground。vision_ocr 的 engine=auto 始终先尝试本地 Tesseract，失败或空结果时再回退视觉模型；结构化模式不会改变这一顺序。完成至少 1 次后续证据调用后，证据充分就直接作答，不要为了流程继续调用。',
       'Do not default to OCR as the second step. Use vision_ocr only for verbatim evidence. If it returns uncertain:true, verify the ambiguous text against context when possible; if uncertain:false and the text is sufficient, answer without redundant verification. For UI/screenshot semantics use vision_describe or vision_detect; use vision_ground for precise localization. For vision_ocr, engine=auto always tries local Tesseract first and falls back to the vision model only when local OCR fails or returns no text; structured mode does not change this order. After at least 1 follow-up evidence call, answer once the evidence is sufficient instead of calling more tools just for the workflow.',

package/lib/session-message-source-compat.js

@@ -0,0 +1,92 @@
+const LEGACY_SOURCE = Object.freeze({ kind: 'plugin', plugin: 'dsh-vision-router' })
+const PRODUCER_SOURCE = Object.freeze({ kind: 'plugin:dsh-vision-router' })
+
+function sourceKindForSession(session) {
+  const version = Number(session?.header?.version)
+  return Number.isInteger(version) && version >= 4 ? PRODUCER_SOURCE : LEGACY_SOURCE
+}
+
+function isVisionRouterSource(source) {
+  return !!source && typeof source === 'object' && !Array.isArray(source) && (
+    (source.kind === 'plugin' && source.plugin === 'dsh-vision-router') ||
+    source.kind === 'plugin:dsh-vision-router'
+  )
+}
+
+/** Return the canonical DVR message source for one live Session format. */
+export function visionRouterMessageSource(session) {
+  return { ...sourceKindForSession(session) }
+}
+
+/** Normalize one DVR-authored message without touching user/model/tool sources. */
+export function normalizeVisionRouterMessageSource(message, session) {
+  if (!message || typeof message !== 'object' || Array.isArray(message)) return message
+  if (!isVisionRouterSource(message.source)) return message
+  const source = sourceKindForSession(session)
+  if (message.source.kind === source.kind
+      && (source.kind !== 'plugin' || message.source.plugin === source.plugin)
+      && Object.keys(message.source).length === Object.keys(source).length) {
+    return message
+  }
+  return { ...message, source: { ...source } }
+}
+
+function normalizeMessageList(list, session) {
+  if (!Array.isArray(list)) return list
+  let changed = false
+  const next = list.map((message) => {
+    const normalized = normalizeVisionRouterMessageSource(message, session)
+    if (normalized !== message) changed = true
+    return normalized
+  })
+  return changed ? next : list
+}
+
+function normalizePreStepResult(result, payload) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return result
+  const messages = normalizeMessageList(result.messages, payload?.agent?.session)
+  return messages === result.messages ? result : { ...result, messages }
+}
+
+function normalizePostExecuteResult(result, exec) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return result
+  const additionalContexts = normalizeMessageList(result.additionalContexts, exec?.agent?.session)
+  return additionalContexts === result.additionalContexts ? result : { ...result, additionalContexts }
+}
+
+function normalizeHookResult(event, args, result) {
+  if (event === 'agent/pre-step') return normalizePreStepResult(result, args[0])
+  if (event === 'tools/post-execute') return normalizePostExecuteResult(result, args[0])
+  return result
+}
+
+/**
+ * DSH Session V3 requires the historical {kind:'plugin', plugin:...} source,
+ * while V4 rejects that wrapper in favor of producer-owned source kinds. Keep
+ * every existing DVR message producer unchanged and normalize at the final
+ * hook publication boundary using the Session's own durable header version.
+ */
+export function installVisionRouterMessageSourceBoundary(ctx) {
+  if (!ctx || typeof ctx !== 'object') return ctx
+  return new Proxy(ctx, {
+    get(target, property) {
+      if (property !== 'on') {
+        const value = Reflect.get(target, property, target)
+        return typeof value === 'function' ? value.bind(target) : value
+      }
+      const on = Reflect.get(target, property, target)
+      if (typeof on !== 'function') return on
+      return (event, handler, ...rest) => {
+        if ((event !== 'agent/pre-step' && event !== 'tools/post-execute') || typeof handler !== 'function') {
+          return on.call(target, event, handler, ...rest)
+        }
+        return on.call(target, event, function sourceCompatibleHook(...args) {
+          const output = handler.apply(this, args)
+          return output && typeof output.then === 'function'
+            ? output.then((value) => normalizeHookResult(event, args, value))
+            : normalizeHookResult(event, args, output)
+        }, ...rest)
+      }
+    },
+  })
+}

package/lib/session-surface-compat.js

@@ -6,7 +6,8 @@ function nonNegativeSafeInteger(value) {
  * Build the Host-owned Session surface replacement intent for one exact node.
  *
  * DSH Session format v3 renamed replacement endpoints from start/end to
- * startSeq/endSeq. The field change belongs to the Session format contract,
+ * startSeq/endSeq, and reviewed format v4 keeps that replacement shape. The
+ * field change belongs to the Session format contract,
  * not to a DSH package-version heuristic, so dispatch on session.header.version
  * and refuse unknown future formats instead of guessing forward compatibility.
  *
@@ -29,7 +30,7 @@ export function sessionSurfaceReplacementIntent(session, seq) {
     }
   }
 
-  if (version === 3) {
+  if (version === 3 || version === 4) {
     return {
       surfaceOp: { op: 'replace', startSeq: seq, endSeq: seq },
       sourceEventSeqs: [seq],

package/lib/session-vision-index.js

@@ -91,6 +91,7 @@ export function createSessionVisionIndex({
   const repairReadWarnings = new WeakMap()
   const repairFeedOverflowWarnings = new WeakSet()
   const repairFeedObserverWarnings = new WeakMap()
+  const surfaceFeedBackfills = new WeakMap()
   const attachmentRecoveryWarnings = new WeakMap()
   let surfaceEventFeedActive = false
 
@@ -357,6 +358,54 @@ export function createSessionVisionIndex({
     surfaceEventFeedActive = true
   }
 
+  const backfillSurfaceEventFeed = async (session) => {
+    let events
+    if (typeof readSessionLog === 'function') {
+      let result
+      try {
+        result = await readSessionLog(session)
+      } catch (error) {
+        warnRepairReadFailure(session, surfaceNodes(session)?.[0] ?? 0, error)
+        return
+      }
+      if (result?.supported === true) {
+        if (!Array.isArray(result.events)) {
+          warnRepairReadFailure(session, surfaceNodes(session)?.[0] ?? 0, new Error('Session log reader returned no event log'))
+          return
+        }
+        events = result.events
+      } else if (result?.supported !== false) {
+        warnRepairReadFailure(session, surfaceNodes(session)?.[0] ?? 0, new Error('Session log reader returned an invalid capability result'))
+        return
+      }
+    }
+
+    // Event-feed activation can happen after a live Session already contains
+    // committed events (enable/re-enable/HMR). Backfill exactly once from one
+    // snapshot, then return to the O(new events) feed path. Older partial Hosts
+    // without SessionQuery retain the Session-local compatibility snapshot.
+    if (events === undefined) events = legacySessionEvents(session)
+    if (!Array.isArray(events)) return
+
+    const nodes = surfaceNodes(session)
+    if (!nodes || nodes.length === 0) return
+    for (const seq of nodes) {
+      const event = events[seq]
+      if (!event || typeof event !== 'object' || (event.seq !== undefined && event.seq !== seq)) continue
+      recordSessionEvent(session, event)
+    }
+  }
+
+  const ensureSurfaceEventFeedBackfill = async (session) => {
+    if (!surfaceEventFeedActive || !session) return
+    let task = surfaceFeedBackfills.get(session)
+    if (!task) {
+      task = backfillSurfaceEventFeed(session)
+      surfaceFeedBackfills.set(session, task)
+    }
+    await task
+  }
+
   const consumePendingRepairEvents = (pendingBySession, session) => {
     const pending = pendingBySession.get(session)
     if (!pending || pending.size === 0) return []
@@ -532,6 +581,7 @@ export function createSessionVisionIndex({
         store.recordAttachments(session, found.attachments)
       }
     }
+    await ensureSurfaceEventFeedBackfill(session)
     await repairToolResultSurface(session)
     await repairGuardStopSurface(session)
     return decision