dsh-vision-router 2.1.3 → 2.1.4

package/lib/catalog-corrections.js

@@ -16,6 +16,7 @@ import {
 } from './http-body-limit.js'
 import { stripTrailingSlashes } from './string-normalization.js'
 import { currentVisionProviderTransport } from './vision-provider-transport.js'
+import { directSessionAffinityHeaders } from './session-affinity.js'
 
 export const CATALOG_ROUTING_CORRECTIONS = [
   {
@@ -240,6 +241,7 @@ export async function callAnthropicCompatible(provider, messages, options = {})
     'anthropic-version': '2023-06-01',
     // Local keyless servers reject an empty x-api-key; omit it when allowed.
     ...(resolvedApiKey === '' ? {} : { 'x-api-key': resolvedApiKey }),
+    ...directSessionAffinityHeaders(provider, options.affinityId ?? options.sessionId),
   }
   const body = {
     model: provider.model,

package/lib/client-presentation-boundary.js

@@ -52,6 +52,109 @@ const VISION_TOGGLE_FIXED_SVG = String.raw`          React.createElement('svg',
               }))
             : null`
 
+const BITMAP_LIMITS_BASE = String.raw`      var maxBitmapSourceBytes = 64 * 1024 * 1024;
+      var maxBitmapDimension = 10000;
+      var maxBitmapPixels = 100000000;`
+
+const BITMAP_LIMITS_HARDENED = String.raw`      var maxBitmapSourceBytes = 64 * 1024 * 1024;
+      var maxBitmapDimension = 10000;
+      var maxBitmapPixels = 100000000;
+      // Source bytes are not a safe proxy for browser decode cost. A low-bit-depth
+      // BMP can be only a few MiB on the clipboard and still expand to hundreds
+      // of MiB once createImageBitmap/canvas materializes RGBA pixels.
+      var maxBitmapDecodedBytes = 128 * 1024 * 1024;
+      var maxBitmapBatchDecodedBytes = 256 * 1024 * 1024;`
+
+const BITMAP_DECODE_ALLOWED_BASE = String.raw`      function bitmapDecodeAllowed(file, info) {
+        if (!file || !info) return false;
+        if (!Number.isFinite(file.size) || file.size <= 0 || file.size > maxBitmapSourceBytes) return false;
+        if (!Number.isFinite(info.width) || !Number.isFinite(info.height) || info.width <= 0 || info.height <= 0) return false;
+        if (info.width > maxBitmapDimension || info.height > maxBitmapDimension) return false;
+        return info.width * info.height <= maxBitmapPixels;
+      }`
+
+const BITMAP_DECODE_ALLOWED_HARDENED = String.raw`      function bitmapDecodeAllowed(file, info) {
+        if (!file || !info) return false;
+        if (!Number.isFinite(file.size) || file.size <= 0 || file.size > maxBitmapSourceBytes) return false;
+        if (!Number.isFinite(info.width) || !Number.isFinite(info.height) || info.width <= 0 || info.height <= 0) return false;
+        if (info.width > maxBitmapDimension || info.height > maxBitmapDimension) return false;
+        var pixels = info.width * info.height;
+        if (!Number.isFinite(pixels) || pixels > maxBitmapPixels) return false;
+        return pixels * 4 <= maxBitmapDecodedBytes;
+      }`
+
+const BITMAP_NORMALIZE_BASE = String.raw`      function normalizeFile(file) {
+        return headType(file).then(function(info) {
+          var detected = info && info.type;
+          if (detected && supported[detected]) {
+            return mediaType(file && file.type) === detected ? file : retypeFile(file, detected);
+          }
+          if (detected === 'image/bmp' && bitmapDecodeAllowed(file, info)) return bitmapToPng(file);
+          return file;
+        }, function(){ return file; });
+      }`
+
+const BITMAP_NORMALIZE_HARDENED = String.raw`      function normalizeFile(file, decodeBudget) {
+        return headType(file).then(function(info) {
+          var detected = info && info.type;
+          if (detected && supported[detected]) {
+            return mediaType(file && file.type) === detected ? file : retypeFile(file, detected);
+          }
+          if (detected === 'image/bmp' && bitmapDecodeAllowed(file, info)) {
+            var decodedBytes = info.width * info.height * 4;
+            if (decodeBudget && decodedBytes > decodeBudget.remaining) return file;
+            if (decodeBudget) decodeBudget.remaining -= decodedBytes;
+            return bitmapToPng(file);
+          }
+          return file;
+        }, function(){ return file; });
+      }`
+
+const BITMAP_BATCH_BASE = String.raw`        Promise.all(files.map(function(file){
+          return needsInspection(file)
+            ? normalizeFile(file).catch(function(){ return file; })
+            : Promise.resolve(file);
+        })).then(function(normalized) {
+          return dedupeBatch(normalized).then(function(deduped) {
+            dispatchReplay(target, replayEvent(deduped, textEntries), fallback);
+          });
+        }, function() {
+          dispatchReplay(target, fallback, null);
+        });`
+
+const BITMAP_BATCH_HARDENED = String.raw`        // Decode BMPs serially under one paste-scoped RGBA budget. This keeps peak
+        // browser memory bounded before the Host attachment governor gets a turn.
+        var decodeBudget = { remaining: maxBitmapBatchDecodedBytes };
+        var normalized = [];
+        var normalizeChain = Promise.resolve();
+        files.forEach(function(file){
+          normalizeChain = normalizeChain.then(function(){
+            if (!needsInspection(file)) {
+              normalized.push(file);
+              return undefined;
+            }
+            return normalizeFile(file, decodeBudget).then(function(value){
+              normalized.push(value);
+            }, function(){
+              normalized.push(file);
+            });
+          });
+        });
+        normalizeChain.then(function() {
+          return dedupeBatch(normalized).then(function(deduped) {
+            dispatchReplay(target, replayEvent(deduped, textEntries), fallback);
+          });
+        }, function() {
+          dispatchReplay(target, fallback, null);
+        });`
+
+function replaceAllRequired(source, anchor, replacement, label) {
+  const parts = source.split(anchor)
+  const count = parts.length - 1
+  if (count === 0) throw new Error(`${label} transform anchor missing`)
+  return parts.join(replacement)
+}
+
 export function transformVisionModeToggleIcons(source = BASE_CLIENT_PRESENTATION_PRELUDE) {
   const input = String(source)
   if (!input.includes(VISION_TOGGLE_TEXT_GLYPH)) {
@@ -60,7 +163,24 @@ export function transformVisionModeToggleIcons(source = BASE_CLIENT_PRESENTATION
   return input.replace(VISION_TOGGLE_TEXT_GLYPH, VISION_TOGGLE_FIXED_SVG)
 }
 
-export const CLIENT_PRESENTATION_PRELUDE = transformVisionModeToggleIcons()
+export function transformBitmapDecodeBudget(source = BASE_CLIENT_PRESENTATION_PRELUDE) {
+  let output = String(source)
+  // The legacy prelude intentionally contains more than one clipboard owner.
+  // Harden every exact owner, not merely the first string match, so one stale
+  // path cannot retain unbounded parallel bitmap decoding.
+  output = replaceAllRequired(output, BITMAP_LIMITS_BASE, BITMAP_LIMITS_HARDENED, 'bitmap limits')
+  output = replaceAllRequired(
+    output,
+    BITMAP_DECODE_ALLOWED_BASE,
+    BITMAP_DECODE_ALLOWED_HARDENED,
+    'bitmap decoded-byte admission',
+  )
+  output = replaceAllRequired(output, BITMAP_NORMALIZE_BASE, BITMAP_NORMALIZE_HARDENED, 'bitmap normalization')
+  output = replaceAllRequired(output, BITMAP_BATCH_BASE, BITMAP_BATCH_HARDENED, 'bitmap batch serialization')
+  return output
+}
+
+export const CLIENT_PRESENTATION_PRELUDE = transformBitmapDecodeBudget(transformVisionModeToggleIcons())
 
 export {
   resolveVisionModePair,

package/lib/doctor-cli-p0.js

@@ -9,6 +9,7 @@ import {
 } from './dsh-host-capabilities.js'
 import {
   DSH_SUPPORT_WINDOW,
+  DSH_VERIFICATION_EVIDENCE,
   formatDshSupportWindowLines,
   supportWindowUpgradeAdvice,
 } from './dsh-support-window.js'
@@ -57,7 +58,7 @@ export async function probeDoctorHostCapabilities({ baseUrl, fetchImpl = globalT
     if (!response.ok) {
       return {
         ok: false,
-        source: 'runtime-route-unavailable',
+        source: response.status === 401 ? 'runtime-auth-required' : 'runtime-route-unavailable',
         status: response.status,
         capabilities: unknownSnapshot(),
       }
@@ -143,6 +144,7 @@ export async function run(argv = process.argv.slice(2), io = console, env = proc
       report.hostCapabilities = probe.capabilities
       report.hostCapabilitiesSource = probe.source
       report.hostSupportWindow = DSH_SUPPORT_WINDOW
+      report.hostVerificationEvidence = DSH_VERIFICATION_EVIDENCE
       report.hostSupportAdvice = supportWindowUpgradeAdvice(probe.capabilities)
       io.log(JSON.stringify(report, null, 2))
       return code

package/lib/doctor-cli.js

@@ -241,7 +241,10 @@ export async function run(argv = process.argv.slice(2), io = console, env = proc
 
   if (runtime) {
     if (!runtime.reachable) io.log(`– Runtime probe: DSH not reachable at ${runtime.baseUrl}; offline checks still completed.`)
-    else {
+    else if (runtime.authenticationRequired) {
+      io.log('? Runtime probe: DSH Web is reachable but browser authentication is required; plugin route health remains unknown.')
+      if (options.profile) io.log(`? runtime profile ownership unknown; authenticated route health is not attributed to ${options.profile}`)
+    } else {
       for (const route of runtime.routes) {
         io.log(`${route.ok ? '✓' : '✗'} runtime ${route.route} — ${route.ok ? 'route registered' : `status ${route.status ?? 'unreachable'}, route not confirmed`}`)
       }

package/lib/doctor-runtime.js

@@ -92,14 +92,17 @@ export async function probeRuntime({
   }))
 
   const reachable = routes.some((item) => !item.unreachable)
+  const authenticationRequired = reachable && routes.length > 0 && routes.every((item) => item.status === 401)
   const routeOk = !reachable || routes.every((item) => item.ok)
-  let ownership = { verified: false, requestedProfile, reason: requestedProfile ? 'profile-unknown' : 'not-requested' }
+  let ownership = authenticationRequired
+    ? { verified: false, requestedProfile, reason: 'runtime-auth-required' }
+    : { verified: false, requestedProfile, reason: requestedProfile ? 'profile-unknown' : 'not-requested' }
 
   // A DELETE contract proves route registration but not which DSH profile owns
   // the process. Reuse the existing GET-only log metadata route as a read-only
   // home identity proof. It never opens the log folder (that is POST only).
   // Only a unique applicable profile in that same DSH_HOME may be attributed.
-  if (reachable && routeOk && requestedProfile && typeof dshHome === 'string') {
+  if (reachable && routeOk && !authenticationRequired && requestedProfile && typeof dshHome === 'string') {
     try {
       const response = await fetchImpl(new URL('/_dsh/vision-router/logs', base).href, {
         method: 'GET',
@@ -131,8 +134,9 @@ export async function probeRuntime({
     reachable,
     routes,
     ownership,
+    authenticationRequired,
     routeOk,
-    ok: !reachable || (routeOk && (!requestedProfile || ownership.verified)),
+    ok: !reachable || authenticationRequired || (routeOk && (!requestedProfile || ownership.verified)),
   }
 }
 
@@ -302,6 +306,7 @@ function safeRuntime(runtime) {
     reachable: runtime.reachable,
     ok: runtime.ok,
     routeOk: runtime.routeOk,
+    authenticationRequired: runtime.authenticationRequired === true,
     ownership: runtime.ownership ? {
       requestedProfile: runtime.ownership.requestedProfile,
       verified: runtime.ownership.verified,

package/lib/dsh-support-window.js

@@ -1,9 +1,14 @@
 export const DSH_SUPPORT_WINDOW = Object.freeze({
   dvrTrain: '2.1.x',
   minimum: '0.1.0-rc.8',
-  previous: '0.1.1-rc.1',
-  current: '0.1.1-rc.2',
-  canary: '0.1.2-alpha.4',
+  currentStable: '0.1.2-rc.1',
+})
+
+export const DSH_VERIFICATION_EVIDENCE = Object.freeze({
+  exactStable: '0.1.2-rc.1',
+  exactPreview: '0.1.3-alpha.2',
+  stableCanaryDistTag: 'latest',
+  previewCanaryDistTag: 'alpha',
 })
 
 export function supportWindowUpgradeAdvice(capabilities = {}) {
@@ -38,11 +43,14 @@ export function formatDshSupportWindowLines(capabilities = {}) {
   return Object.freeze([
     'DSH Host support window:',
     `  DVR train: ${DSH_SUPPORT_WINDOW.dvrTrain}`,
-    `  minimum: ${DSH_SUPPORT_WINDOW.minimum}`,
-    `  previous: ${DSH_SUPPORT_WINDOW.previous}`,
-    `  current: ${DSH_SUPPORT_WINDOW.current}`,
-    `  canary only: ${DSH_SUPPORT_WINDOW.canary}`,
+    `  minimum supported Host: ${DSH_SUPPORT_WINDOW.minimum}`,
+    `  current stable Host: ${DSH_SUPPORT_WINDOW.currentStable}`,
     `  support floor: DVR ${DSH_SUPPORT_WINDOW.dvrTrain} -> DSH ${DSH_SUPPORT_WINDOW.minimum}`,
+    'DSH compatibility verification evidence:',
+    `  exact stable: ${DSH_VERIFICATION_EVIDENCE.exactStable}`,
+    `  exact preview (not a support claim): ${DSH_VERIFICATION_EVIDENCE.exactPreview}`,
+    `  scheduled stable canary: npm dist-tag ${DSH_VERIFICATION_EVIDENCE.stableCanaryDistTag}`,
+    `  scheduled preview canary: npm dist-tag ${DSH_VERIFICATION_EVIDENCE.previewCanaryDistTag}`,
     `  upgrade advice: ${advice.level} (${advice.code}) — ${advice.message}`,
   ])
 }

package/lib/live-model-discovery.js

@@ -7,7 +7,7 @@ import { MODEL_RESPONSE_MAX_BYTES, readResponseJsonBounded } from './http-body-l
 import { stripTrailingSlashes } from './string-normalization.js'
 
 export const LIVE_MODELS_PATH = '/_dsh/vision-router/live-models'
-export const LIVE_MODEL_CACHE_VERSION = 1
+export const LIVE_MODEL_CACHE_VERSION = 2
 export const DEFAULT_LIVE_MODEL_FRESH_MS = 15 * 60 * 1000
 export const DEFAULT_LIVE_MODEL_STALE_MS = 24 * 60 * 60 * 1000
 export const DEFAULT_LIVE_MODEL_TIMEOUT_MS = 6_000
@@ -66,23 +66,16 @@ export function liveModelCachePath(dshHome = resolveDshHome()) {
   return path.join(dshHome, 'cache', 'vision-router', 'live-models.json')
 }
 
-export function routeFingerprint({ provider, baseURL, api, credentialFingerprint }) {
+export function routeFingerprint({ provider, baseURL, api }) {
   return createHash('sha256')
     .update(JSON.stringify({
       provider: String(provider ?? ''),
       baseURL: String(baseURL ?? ''),
       api: String(api ?? ''),
-      credentialFingerprint: String(credentialFingerprint ?? ''),
     }))
     .digest('hex')
 }
 
-function credentialFingerprint(value) {
-  const text = typeof value === 'string' ? value : ''
-  if (text === '') return 'none'
-  return createHash('sha256').update(text).digest('hex').slice(0, 24)
-}
-
 function listingURL(baseURL) {
   return `${stripTrailingSlashes(baseURL)}/models`
 }
@@ -308,7 +301,7 @@ async function providerPlan(ctx, provider) {
   // DSH llm-pi-ai treats a named apiKeyEnv as mandatory. Sending `/models`
   // without that key is both misleading (the user sees a spurious 401) and can
   // poison route fingerprints/cache evidence. Defer instead; the browser's
-  // refresh polling and credentials/updated invalidation will retry once the
+  // refresh polling and credential-reference invalidation will retry once the
   // credential seam is ready or the user stores the key.
   if (credential.required && credential.value === undefined) {
     return {
@@ -328,7 +321,6 @@ async function providerPlan(ctx, provider) {
       provider,
       baseURL: transport.baseURL,
       api: transport.api,
-      credentialFingerprint: credentialFingerprint(apiKey),
     }),
   }
 }
@@ -550,13 +542,27 @@ export function installLiveModelDiscovery(ctx, options = {}) {
   }
   scheduleStartup()
 
-  const onInvalidate = () => manager.invalidate()
+  let credentialInvalidationQueued = false
+  let lifecycleDisposed = false
+  const onInvalidate = () => {
+    if (!lifecycleDisposed) manager.invalidate()
+  }
+  const onCredentialInvalidate = () => {
+    if (lifecycleDisposed || credentialInvalidationQueued) return
+    credentialInvalidationQueued = true
+    manager.invalidate()
+    Promise.resolve().then(() => { credentialInvalidationQueued = false })
+  }
   const disposers = []
   try {
-    for (const event of ['settings/document-updated', 'credentials/updated', 'llm/adapters-updated']) {
+    for (const event of ['settings/document-updated', 'llm/adapters-updated']) {
       const dispose = ctx?.on?.(event, onInvalidate)
       if (typeof dispose === 'function') disposers.push(dispose)
     }
+    for (const event of ['credentials/reference-updated', 'credentials/updated']) {
+      const dispose = ctx?.on?.(event, onCredentialInvalidate)
+      if (typeof dispose === 'function') disposers.push(dispose)
+    }
   } catch {
     // Event forwarding is an optimization; the request path still refreshes.
   }
@@ -584,6 +590,7 @@ export function installLiveModelDiscovery(ctx, options = {}) {
 
   try {
     ctx?.effect?.(() => () => {
+      lifecycleDisposed = true
       if (startupTimer !== undefined) clearTimeout(startupTimer)
       for (const dispose of disposers) {
         try { dispose() } catch { /* best effort */ }

package/lib/pi-ai-bridge-wire-compat.js

@@ -1,3 +1,6 @@
+import { currentVisionSessionAffinityId } from './session-affinity-runtime.js'
+import { isOfficialOpenCodeGoUrl, openCodeSessionAffinityHeaderForUrl } from './session-affinity.js'
+
 /**
  * DSH 0.1.1-rc.1 lets a pi-ai route/model declare OpenAI-completions wire
  * compatibility such as `compat.maxTokensField`, and route-owned request
@@ -10,7 +13,12 @@
  * wire fingerprint (`stream:false`, image_url content, /chat/completions), so a
  * narrowly scoped fetch wrapper can recover the exact resolved pi-ai
  * route/model by URL + model id and apply only the missing wire facts.
- * Normal DSH/pi-ai traffic is streaming and therefore never matches.
+ * Normal DSH/pi-ai traffic is streaming and therefore never matches that
+ * legacy rewrite. A second, orthogonal rule lives in the same fetch boundary:
+ * while a Vision Router-owned AsyncLocalStorage scope is active, requests to
+ * the official OpenCode Go endpoint receive x-opencode-session if upstream has
+ * not already supplied it. That rule is endpoint-scoped and self-retires when
+ * DSH/pi-ai learns the native header.
  */
 
 function isObject(value) {
@@ -38,6 +46,23 @@ function requestUrl(input) {
   return undefined
 }
 
+function requestMethod(input, init) {
+  if (typeof init?.method === 'string' && init.method !== '') return init.method.toUpperCase()
+  if (typeof Request !== 'undefined' && input instanceof Request) return input.method.toUpperCase()
+  return 'GET'
+}
+
+function isOpenCodeGoInferenceRequest(input, init) {
+  const url = requestUrl(input)
+  if (url === undefined || !isOfficialOpenCodeGoUrl(url) || requestMethod(input, init) !== 'POST') return false
+  try {
+    const pathname = new URL(url).pathname.replace(/\/$/, '')
+    return /\/(?:chat\/completions|responses|messages)$/i.test(pathname)
+  } catch {
+    return false
+  }
+}
+
 function parseJsonBody(init) {
   if (!init || typeof init.body !== 'string') return undefined
   try {
@@ -201,6 +226,28 @@ function mergeHeaders(profileHeaders, requestHeaders) {
   return { ...profileHeaders, ...(requestHeaders ?? {}) }
 }
 
+function combinedRequestHeaders(input, init) {
+  const merged = new Headers(
+    typeof Request !== 'undefined' && input instanceof Request ? input.headers : undefined,
+  )
+  new Headers(init?.headers ?? {}).forEach((value, name) => merged.set(name, value))
+  return merged
+}
+
+/**
+ * Pure scoped-header projection. Existing/native x-opencode-session always
+ * wins, making the compatibility layer a no-op as soon as upstream supports it.
+ */
+export function applyScopedOpenCodeSessionAffinity(input, init, affinityId) {
+  const url = requestUrl(input)
+  if (url === undefined || !isOfficialOpenCodeGoUrl(url)) return init
+  const headers = combinedRequestHeaders(input, init)
+  if (headers.has('x-opencode-session')) return init
+  const wire = openCodeSessionAffinityHeaderForUrl(url, affinityId)
+  headers.set('x-opencode-session', wire)
+  return { ...init, headers }
+}
+
 /** Pure request rewrite used by the installed fetch boundary and tests. */
 export function applyPiAiBridgeWireFacts(init, body, facts) {
   if (!facts || !isObject(body)) return init
@@ -230,8 +277,9 @@ export function applyPiAiBridgeWireFacts(init, body, facts) {
 }
 
 /**
- * Install one process fetch wrapper. It is inert for ordinary streaming DSH
- * calls and for Vision Router's unrelated HTTP providers. Cleanup disables the
+ * Install one process fetch wrapper. Ordinary DSH traffic remains inert; only
+ * the legacy non-streaming image bridge or an explicit Vision Router affinity
+ * scope can modify a request. Cleanup disables the
  * wrapper even if another later patch sits above it in the fetch chain.
  */
 export function installPiAiBridgeWireCompat(ctx, logger) {
@@ -240,8 +288,19 @@ export function installPiAiBridgeWireCompat(ctx, logger) {
   let active = true
   const wrapped = async (input, init) => {
     if (!active) return Reflect.apply(original, globalThis, [input, init])
+    let patchedInit = init
+
+    // This is not advisory: a Vision Router-owned request to OpenCode Go must
+    // either carry the exact safe affinity id or fail before the network. The
+    // check is scoped by AsyncLocalStorage, so unrelated Host/plugin traffic is
+    // untouched even though this wrapper is process-visible.
+    const scopedAffinity = currentVisionSessionAffinityId()
+    if (scopedAffinity !== undefined && isOpenCodeGoInferenceRequest(input, patchedInit)) {
+      patchedInit = applyScopedOpenCodeSessionAffinity(input, patchedInit, scopedAffinity)
+    }
+
     try {
-      const body = parseJsonBody(init)
+      const body = parseJsonBody(patchedInit)
       const url = requestUrl(input)
       const bridgeShape =
         body?.stream === false &&
@@ -252,8 +311,9 @@ export function installPiAiBridgeWireCompat(ctx, logger) {
       if (bridgeShape) {
         const facts = resolvePiAiBridgeWireFacts(ctx, url, body.model)
         if (facts !== undefined) {
-          const patched = applyPiAiBridgeWireFacts(init, body, facts)
-          if (patched !== init) {
+          const bridged = applyPiAiBridgeWireFacts(patchedInit, body, facts)
+          if (bridged !== patchedInit) {
+            patchedInit = bridged
             try {
               logger?.info?.(
                 'vision-router: applied pi-ai bridge wire compat [%s/%s] maxTokensField=%s headers=%d',
@@ -265,15 +325,14 @@ export function installPiAiBridgeWireCompat(ctx, logger) {
             } catch {
               // Diagnostics never affect the request.
             }
-            return Reflect.apply(original, globalThis, [input, patched])
           }
         }
       }
     } catch {
-      // Compatibility lookup is advisory. Any unexpected shape keeps the
-      // exact pre-existing request rather than turning a bridge into a crash.
+      // Legacy bridge lookup is advisory. Any unexpected shape keeps the
+      // exact request after the mandatory scoped affinity projection above.
     }
-    return Reflect.apply(original, globalThis, [input, init])
+    return Reflect.apply(original, globalThis, [input, patchedInit])
   }
   globalThis.fetch = wrapped
   const cleanup = () => {

package/lib/session-affinity-runtime.js

@@ -0,0 +1,104 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { rawSessionIdentity } from './session-affinity.js'
+
+const affinityRuntime = new AsyncLocalStorage()
+
+export function currentVisionSessionAffinityId() {
+  const state = affinityRuntime.getStore()
+  return state?.active === true ? state.affinityId : undefined
+}
+
+export function runWithVisionSessionAffinity(affinityId, callback) {
+  const raw = rawSessionIdentity(affinityId)
+  if (raw === undefined) return callback()
+  const state = { affinityId: raw, active: true }
+  let result
+  try {
+    result = affinityRuntime.run(state, callback)
+  } catch (error) {
+    state.active = false
+    throw error
+  }
+  if (result && typeof result.then === 'function') {
+    return Promise.resolve(result).finally(() => { state.active = false })
+  }
+  state.active = false
+  return result
+}
+
+/**
+ * Keep AsyncLocalStorage active across lazy AsyncIterable creation and every
+ * iterator operation. Adapter/network work often begins on next(), not when
+ * ctx.llm.stream() returns the iterable. Promise-returning test/compat streams
+ * are supported too because some older seams resolve the iterable lazily.
+ * One mutable state object is retired at stream completion so async work that
+ * outlives the model request cannot keep projecting the conversation id.
+ */
+export function streamWithVisionSessionAffinity(affinityId, streamFactory) {
+  const raw = rawSessionIdentity(affinityId)
+  if (raw === undefined) return streamFactory()
+  return {
+    [Symbol.asyncIterator]() {
+      const state = { affinityId: raw, active: true }
+      let iteratorPromise
+      const retire = () => { state.active = false }
+      const ensure = () => {
+        if (iteratorPromise === undefined) {
+          iteratorPromise = affinityRuntime.run(state, async () => {
+            const stream = await streamFactory()
+            if (!stream || typeof stream[Symbol.asyncIterator] !== 'function') {
+              throw new TypeError('scoped vision stream is not async iterable')
+            }
+            return stream[Symbol.asyncIterator]()
+          })
+        }
+        return iteratorPromise
+      }
+      return {
+        next(value) {
+          return affinityRuntime.run(state, async () => {
+            try {
+              const result = await (await ensure()).next(value)
+              if (result?.done === true) retire()
+              return result
+            } catch (error) {
+              retire()
+              throw error
+            }
+          })
+        },
+        return(value) {
+          if (iteratorPromise === undefined) {
+            retire()
+            return Promise.resolve({ done: true, value })
+          }
+          return affinityRuntime.run(state, async () => {
+            try {
+              const active = await iteratorPromise
+              return typeof active.return === 'function'
+                ? await active.return(value)
+                : { done: true, value }
+            } finally {
+              retire()
+            }
+          })
+        },
+        throw(error) {
+          if (iteratorPromise === undefined) {
+            retire()
+            return Promise.reject(error)
+          }
+          return affinityRuntime.run(state, async () => {
+            try {
+              const active = await iteratorPromise
+              if (typeof active.throw === 'function') return await active.throw(error)
+              throw error
+            } finally {
+              retire()
+            }
+          })
+        },
+      }
+    },
+  }
+}