dsh-vision-router 2.0.0 → 2.1.0

package/lib/doctor-vision-limits.js

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync, statSync, openSync, readSync, closeSync } from 'node:fs'
+
+const LIMIT_LINE = /vision-router: effective vision limits\s+taskTimeoutMs=(\d+)\s+taskSource=([^\s]+)\s+turnBudgetMs=(\d+)\s+turnSource=([^\s]+)/i
+const EXHAUSTED_LINE = /vision-router: vision turn deadline exhausted\s+turn=([^\s]+)\s+budgetMs=(\d+)\s+elapsedMs=([^\s]+)/i
+
+function readTail(file, maxBytes = 2 * 1024 * 1024) {
+  if (!file || !existsSync(file)) return ''
+  let fd
+  try {
+    const stat = statSync(file)
+    const size = Math.min(stat.size, maxBytes)
+    if (size <= 0) return ''
+    const buffer = Buffer.alloc(size)
+    fd = openSync(file, 'r')
+    readSync(fd, buffer, 0, size, Math.max(0, stat.size - size))
+    return buffer.toString('utf8')
+  } catch {
+    try { return readFileSync(file, 'utf8') } catch { return '' }
+  } finally {
+    if (fd !== undefined) closeSync(fd)
+  }
+}
+
+export function parseVisionLimitLog(text) {
+  let latest
+  let latestExhaustion
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const limit = LIMIT_LINE.exec(line)
+    if (limit) {
+      latest = {
+        taskTimeoutMs: Number(limit[1]),
+        taskSource: limit[2],
+        turnBudgetMs: Number(limit[3]),
+        turnSource: limit[4],
+      }
+    }
+    const exhausted = EXHAUSTED_LINE.exec(line)
+    if (exhausted) {
+      latestExhaustion = {
+        turn: exhausted[1],
+        budgetMs: Number(exhausted[2]),
+        elapsedMs: exhausted[3] === 'unknown' ? undefined : Number(exhausted[3]),
+      }
+    }
+  }
+  if (!latest && !latestExhaustion) return undefined
+  return {
+    ...latest,
+    latestExhaustion,
+    explicitTurnLimit: Number(latest?.turnBudgetMs) > 0,
+  }
+}
+
+export function inspectDoctorVisionLimits(logFile) {
+  return parseVisionLimitLog(readTail(logFile))
+}
+
+export function formatDoctorVisionLimits(limits) {
+  if (!limits) return []
+  const task = Number.isFinite(limits.taskTimeoutMs) ? `${limits.taskTimeoutMs / 1000}s` : 'unknown'
+  const turn = Number.isFinite(limits.turnBudgetMs)
+    ? limits.turnBudgetMs === 0 ? 'unlimited' : `${limits.turnBudgetMs / 1000}s`
+    : 'unknown'
+  const lines = [
+    `Vision task timeout: ${task}${limits.taskSource ? ` (${limits.taskSource})` : ''}`,
+    `Vision turn deadline: ${turn}${limits.turnSource ? ` (${limits.turnSource})` : ''}`,
+  ]
+  if (limits.explicitTurnLimit) {
+    lines.push('WARN: an explicit whole-turn vision deadline is active; v2 defaults to unlimited and long multi-image tasks may stop after this deadline.')
+  }
+  return lines
+}

package/lib/dsh-contract-compat.js

@@ -1,9 +1,30 @@
+import { inspectDshHostCapabilities } from './dsh-host-capabilities.js'
+
+/**
+ * Compatibility inventory
+ * Reason: preserve Vision Router's released behavior across the supported DSH Host window.
+ * Host gap: attachment ownership, settings-section and adapter-ownership seams differ across supported Hosts.
+ * First needed for: rc.6 minimum support and the later batch-attachment/settings migration.
+ * Feature detection: concrete attachment/settings/LLM methods only; never a DSH version string.
+ * Removal condition: the minimum supported Host natively provides every seam used below and the legacy profile overlay is outside the support window.
+ * Tests: rc6-rc7-compat, rc6-real-settings-persistence, attachment-admission-policy, DSH contract CI.
+ */
+
 const HOST_OWNED_ROUTES = new Set(['deepseek-official', 'deepseek-official-native'])
 
 const LEGACY_VISION_ATTACHMENT_BYTES = 20 * 1024 * 1024
 const LEGACY_VISION_ATTACHMENT_PIXELS = 100_000_000
 const DSH_RC8_DEFAULT_IMAGE_DIMENSION = 2000
+const DSH_ALPHA_DEFAULT_IMAGE_DIMENSION = 8192
 const VISION_ROUTER_IMAGE_DIMENSION = 10_000
+const DSH_ALPHA_DEFAULT_NORMALIZED_PIXELS = 2048 * 2048
+const DSH_ALPHA_DEFAULT_NORMALIZED_DIMENSION = 8192
+const DSH_ALPHA_DEFAULT_NORMALIZED_BYTES = 4 * 1024 * 1024
+const VISION_ROUTER_NORMALIZED_PIXELS = LEGACY_VISION_ATTACHMENT_PIXELS
+const VISION_ROUTER_NORMALIZED_DIMENSION = VISION_ROUTER_IMAGE_DIMENSION
+const VISION_ROUTER_NORMALIZED_BYTES = LEGACY_VISION_ATTACHMENT_BYTES
+const HOST_CAPABILITIES_PATH = '/_dsh/vision-router/host-capabilities'
+const capabilityRouteInstalls = new WeakSet()
 
 function attachmentStoreOf(ctx) {
   if (!ctx || typeof ctx !== 'object') return undefined
@@ -23,6 +44,61 @@ function attachmentStoreOf(ctx) {
   }
 }
 
+function sendCapabilityJson(res, status, body) {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  res.end(JSON.stringify(body))
+}
+
+/**
+ * Expose the same side-effect-free Host capability snapshot Doctor consumes.
+ * The endpoint is GET-only and contains no settings values, credentials,
+ * provider ids or version-derived guesses. Failing to install it is advisory.
+ */
+export function installDshHostCapabilityDiagnostics(ctx) {
+  if (!ctx || (typeof ctx !== 'object' && typeof ctx !== 'function')) return false
+  if (capabilityRouteInstalls.has(ctx)) return true
+  capabilityRouteInstalls.add(ctx)
+  try {
+    if (typeof ctx.inject !== 'function') return false
+    ctx.inject(['webServer'], (webCtx) => {
+      try {
+        webCtx.effect(
+          () => webCtx.webServer.register({
+            kind: 'exact',
+            path: HOST_CAPABILITIES_PATH,
+            handler: async (req, res) => {
+              if (req.method !== 'GET') {
+                res.setHeader('Allow', 'GET')
+                sendCapabilityJson(res, 405, { ok: false, error: 'method not allowed' })
+                return
+              }
+              let capabilities
+              try {
+                capabilities = inspectDshHostCapabilities(webCtx)
+              } catch {
+                capabilities = undefined
+              }
+              sendCapabilityJson(res, 200, {
+                ok: true,
+                capabilities: capabilities ?? {},
+              })
+            },
+          }),
+          'vision-router: host capability diagnostics route',
+        )
+      } catch {
+        // Diagnostics must never veto webServer injection or plugin startup.
+      }
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
 /**
  * Detect the released batch-attachment contract directly. DSH rc.6 exposes
  * validateImage/saveImage/readImage only; rc.7+ adds AttachmentStore.saveImages().
@@ -35,22 +111,58 @@ export function hasBatchAttachmentContract(ctx) {
   return !!store && typeof store.saveImages === 'function'
 }
 
+function exactAlphaNormalizationDefaults(policy) {
+  return !!policy && typeof policy === 'object' &&
+    policy.maxPixels === DSH_ALPHA_DEFAULT_NORMALIZED_PIXELS &&
+    policy.maxDimension === DSH_ALPHA_DEFAULT_NORMALIZED_DIMENSION &&
+    policy.maxBytes === DSH_ALPHA_DEFAULT_NORMALIZED_BYTES
+}
+
+function knownVisionRouterAdmissionShape(limits) {
+  if (!limits || typeof limits !== 'object') return false
+  if (
+    limits.maxImageBytes !== LEGACY_VISION_ATTACHMENT_BYTES ||
+    limits.maxImagePixels !== LEGACY_VISION_ATTACHMENT_PIXELS
+  ) return false
+  return limits.maxImageDimension === DSH_RC8_DEFAULT_IMAGE_DIMENSION ||
+    limits.maxImageDimension === DSH_ALPHA_DEFAULT_IMAGE_DIMENSION
+}
+
+function replaceFrozenPolicy(store, property, next) {
+  let changed = false
+  try {
+    changed = Reflect.set(store, property, next)
+  } catch {
+    changed = false
+  }
+  return changed && store[property] === next
+}
+
 /**
- * Repair one historical Vision Router profile overlay on DSH rc.8.
+ * Repair historical Vision Router profile overlays across supported DSH Hosts.
+ *
+ * DSH patch rows replace the WHOLE config object instead of deep-merging it.
+ * Old Vision Router profiles therefore retain a later `attachment-local` row
+ * containing only the released 20MiB / 100MP admission pair. On rc.8 that
+ * shadowed the later 10000px bundle value and rematerialized the Host's 2000px
+ * default. On 0.1.2-alpha.1 the same stale row additionally omits the new
+ * normalization fields, rematerializing 8192px admission plus the Host's
+ * 4.2MP / 4MiB canonical-image defaults.
  *
- * Before rc.8 introduced maxImageDimension, Vision Router wrote a profile-local
- * attachment-local override containing only 20MiB / 100MP. DSH patch rows
- * replace the WHOLE config object instead of deep-merging it, so that later
- * profile layer shadows the newer bundle row and rc.8 silently rematerializes
- * its own 2000px default. Plugin updates cannot delete a user's profile layer.
+ * This migration never edits a user's profile file and never creates another
+ * attachment owner. LocalAttachmentStore exposes the resolved immutable
+ * `imageLimits` and (alpha+) `normalizationPolicy` objects, and reads those
+ * properties for every later validate/save. We replace only those policy
+ * objects on one exact historical fingerprint:
  *
- * The historical 20MiB + 100MP pair is therefore the migration fingerprint.
- * Only when that exact pair is combined with rc.8's exact 2000px default do we
- * raise the live store policy to Vision Router's 10000px contract. Explicitly
- * customised dimensions or unrelated attachment deployments are never touched.
- * LocalAttachmentStore reads `this.imageLimits` for every validation/save, so
- * replacing this immutable policy object repairs authoritative admission as
- * well as the limits projected to the browser for error copy.
+ * - admission bytes === 20MiB and pixels === 100MP; and
+ * - dimension is rc.8's 2000px default or alpha's 8192px default; and
+ * - normalization, when repaired, is EXACTLY alpha.1's 4.2MP/8192px/4MiB
+ *   default tuple.
+ *
+ * Any custom admission dimension or any custom normalization tuple is left
+ * untouched. This is capability/shape detection only; no DSH version string is
+ * consulted.
  */
 export function ensureVisionAttachmentAdmissionPolicy(ctx, logger, options = {}) {
   const store = attachmentStoreOf(ctx)
@@ -62,41 +174,96 @@ export function ensureVisionAttachmentAdmissionPolicy(ctx, logger, options = {})
   const targetDimension = Number.isInteger(options.maxImageDimension)
     ? Math.max(1, options.maxImageDimension)
     : VISION_ROUTER_IMAGE_DIMENSION
-  const legacy =
-    limits.maxImageBytes === LEGACY_VISION_ATTACHMENT_BYTES &&
-    limits.maxImagePixels === LEGACY_VISION_ATTACHMENT_PIXELS &&
-    limits.maxImageDimension === DSH_RC8_DEFAULT_IMAGE_DIMENSION
+  const targetNormalizedPixels = Number.isInteger(options.normalizedImageMaxPixels)
+    ? Math.max(1, options.normalizedImageMaxPixels)
+    : VISION_ROUTER_NORMALIZED_PIXELS
+  const targetNormalizedDimension = Number.isInteger(options.normalizedImageMaxDimension)
+    ? Math.max(1, options.normalizedImageMaxDimension)
+    : VISION_ROUTER_NORMALIZED_DIMENSION
+  const targetNormalizedBytes = Number.isInteger(options.normalizedImageMaxBytes)
+    ? Math.max(1, options.normalizedImageMaxBytes)
+    : VISION_ROUTER_NORMALIZED_BYTES
 
-  if (!legacy) return { changed: false, reason: 'not-legacy-overlay', limits }
+  if (!knownVisionRouterAdmissionShape(limits)) {
+    return { changed: false, reason: 'not-legacy-overlay', limits }
+  }
 
-  const next = Object.freeze({ ...limits, maxImageDimension: targetDimension })
-  let changed = false
-  try {
-    changed = Reflect.set(store, 'imageLimits', next)
-  } catch {
-    changed = false
+  const repairNormalization =
+    limits.maxImageDimension === DSH_ALPHA_DEFAULT_IMAGE_DIMENSION &&
+    exactAlphaNormalizationDefaults(store.normalizationPolicy)
+  const repairDimension =
+    limits.maxImageDimension === DSH_RC8_DEFAULT_IMAGE_DIMENSION ||
+    repairNormalization
+
+  if (!repairDimension && !repairNormalization) {
+    return { changed: false, reason: 'not-legacy-overlay', limits }
   }
-  if (!changed || store.imageLimits !== next) {
-    try {
-      logger?.warn?.(
-        'vision-router: detected the legacy attachment-local 20MiB/100MP overlay but could not repair maxImageDimension; DSH may still enforce 2000px',
-      )
-    } catch {
-      // Diagnostics must never break Host startup.
+
+  if (repairDimension) {
+    const nextLimits = Object.freeze({ ...limits, maxImageDimension: targetDimension })
+    if (!replaceFrozenPolicy(store, 'imageLimits', nextLimits)) {
+      try {
+        logger?.warn?.(
+          'vision-router: detected the legacy attachment-local admission overlay but could not repair maxImageDimension; DSH may still enforce the Host default',
+        )
+      } catch {
+        // Diagnostics must never break Host startup.
+      }
+      return { changed: false, reason: 'limits-readonly', limits }
+    }
+  }
+
+  if (repairNormalization) {
+    const nextNormalization = Object.freeze({
+      maxPixels: targetNormalizedPixels,
+      maxDimension: targetNormalizedDimension,
+      maxBytes: targetNormalizedBytes,
+    })
+    if (!replaceFrozenPolicy(store, 'normalizationPolicy', nextNormalization)) {
+      // If admission was already repaired above, leave that safe improvement in
+      // place but report the unresolved canonical-image blocker explicitly.
+      try {
+        logger?.warn?.(
+          'vision-router: detected the legacy attachment-local alpha normalization defaults but could not repair normalizationPolicy; canonical images may still be downscaled',
+        )
+      } catch {
+        // Diagnostics must never break Host startup.
+      }
+      return {
+        changed: repairDimension,
+        reason: 'normalization-policy-readonly',
+        limits: store.imageLimits,
+        normalizationPolicy: store.normalizationPolicy,
+      }
     }
-    return { changed: false, reason: 'limits-readonly', limits }
   }
 
   try {
-    logger?.info?.(
-      'vision-router: repaired legacy attachment-local overlay — maxImageDimension %d -> %d',
-      DSH_RC8_DEFAULT_IMAGE_DIMENSION,
-      targetDimension,
-    )
+    if (repairNormalization) {
+      logger?.info?.(
+        'vision-router: repaired legacy attachment-local policy — admission %dpx; canonical image %dpx/%dpx/%d bytes',
+        store.imageLimits.maxImageDimension,
+        store.normalizationPolicy.maxPixels,
+        store.normalizationPolicy.maxDimension,
+        store.normalizationPolicy.maxBytes,
+      )
+    } else {
+      logger?.info?.(
+        'vision-router: repaired legacy attachment-local overlay — maxImageDimension %d -> %d',
+        DSH_RC8_DEFAULT_IMAGE_DIMENSION,
+        targetDimension,
+      )
+    }
   } catch {
     // Diagnostics must never break Host startup.
   }
-  return { changed: true, reason: 'legacy-overlay-repaired', limits: next }
+
+  return {
+    changed: true,
+    reason: repairNormalization ? 'legacy-alpha-policy-repaired' : 'legacy-overlay-repaired',
+    limits: store.imageLimits,
+    ...(repairNormalization ? { normalizationPolicy: store.normalizationPolicy } : {}),
+  }
 }
 
 /**
@@ -269,6 +436,7 @@ export function installHostSettingsCompatibility(ctx, entryConfig, options = {})
  * host context passes through untouched.
  */
 export function attachmentContextForContract(ctx, logger, options = {}) {
+  installDshHostCapabilityDiagnostics(ctx)
   if (hasBatchAttachmentContract(ctx)) return ctx
   const install = options.installAndroidAttachmentCompat
   if (typeof install !== 'function') return ctx
@@ -280,4 +448,4 @@ export function attachmentContextForContract(ctx, logger, options = {}) {
 // releases do not accrete `if (rc8) / if (rc9)` branches.
 export const isRc7ContractRuntime = hasBatchAttachmentContract
 export const protectRc7ProviderOwnership = protectHostProviderOwnership
-export const installRc7SettingsCompatibility = installHostSettingsCompatibility
+export const installRc7SettingsCompatibility = installHostSettingsCompatibility

package/lib/dsh-host-capabilities.js

@@ -0,0 +1,107 @@
+const UNKNOWN = 'unknown'
+
+function serviceOf(ctx, name) {
+  if (!ctx || (typeof ctx !== 'object' && typeof ctx !== 'function')) return undefined
+  try {
+    if (typeof ctx.get === 'function') {
+      const service = ctx.get(name)
+      if (service !== undefined && service !== null) return service
+    }
+  } catch {
+    // Capability diagnostics are advisory and must not break plugin startup.
+  }
+  try {
+    const service = ctx[name]
+    return service === undefined || service === null ? undefined : service
+  } catch {
+    return undefined
+  }
+}
+
+function hasFunction(value, name) {
+  try {
+    return !!value && typeof value[name] === 'function'
+  } catch {
+    return false
+  }
+}
+
+function known(value) {
+  return value === true || value === false ? value : UNKNOWN
+}
+
+/**
+ * Return a side-effect-free capability snapshot of the mounted DSH Host.
+ *
+ * The probe deliberately never registers adapters, tools, jobs, settings or
+ * client surfaces just to learn whether a feature exists. If a capability
+ * cannot be proven from a stable readable seam, it is reported as `unknown`
+ * rather than inferred from a DSH version string.
+ */
+export function inspectDshHostCapabilities(ctx) {
+  const attachments = serviceOf(ctx, 'attachments')
+  const llm = serviceOf(ctx, 'llm')
+  const jobs = serviceOf(ctx, 'jobs')
+  const settings = serviceOf(ctx, 'settings')
+  const tools = serviceOf(ctx, 'tools')
+
+  let maxImageDimension = false
+  try {
+    const value = attachments?.imageLimits?.maxImageDimension
+    maxImageDimension = Number.isFinite(Number(value)) && Number(value) > 0
+  } catch {
+    maxImageDimension = false
+  }
+
+  const adapterRegistration = hasFunction(llm, 'registerAdapter')
+  const prepareCall = hasFunction(llm, 'prepareCall')
+  const toolRegistration = hasFunction(tools, 'register') || hasFunction(tools, 'registerTool')
+  const toolExecution = hasFunction(tools, 'call') || hasFunction(tools, 'execute') || hasFunction(tools, 'invoke')
+
+  return Object.freeze({
+    batchAttachments: hasFunction(attachments, 'saveImages'),
+    maxImageDimension,
+    adapterRegistration,
+    // replace() lives on the handle returned by registerAdapter(). A read-only
+    // Doctor cannot prove the handle shape without mutating Host topology, so
+    // an observable registration seam means "unknown", not "no".
+    registrationReplace: adapterRegistration ? UNKNOWN : false,
+    jobs: jobs === undefined ? false : true,
+    // No stable read-only client-surface capability flag exists across the
+    // supported Host window yet.
+    surfaceReplacement: UNKNOWN,
+    // DSH SettingsProvider.register() is the public live-namespace seam; get()
+    // and watch() belong to the returned SettingsScope rather than the service.
+    // Detect the stable service method and do not manufacture a registration.
+    settingsLiveNamespace: hasFunction(settings, 'register'),
+    // Browser exposure is a presentation capability and is not safely implied
+    // by the Host settings service alone.
+    settingsWebExposure: UNKNOWN,
+    prepareCall,
+    toolRegistration,
+    toolExecution,
+  })
+}
+
+export function normalizeDshHostCapabilities(value) {
+  const source = value && typeof value === 'object' ? value : {}
+  return Object.freeze({
+    batchAttachments: known(source.batchAttachments),
+    maxImageDimension: known(source.maxImageDimension),
+    adapterRegistration: known(source.adapterRegistration),
+    registrationReplace: known(source.registrationReplace),
+    jobs: known(source.jobs),
+    surfaceReplacement: known(source.surfaceReplacement),
+    settingsLiveNamespace: known(source.settingsLiveNamespace),
+    settingsWebExposure: known(source.settingsWebExposure),
+    prepareCall: known(source.prepareCall),
+    toolRegistration: known(source.toolRegistration),
+    toolExecution: known(source.toolExecution),
+  })
+}
+
+export function formatDshHostCapability(value) {
+  if (value === true) return 'yes'
+  if (value === false) return 'no'
+  return UNKNOWN
+}

package/lib/dsh-support-window.js

@@ -0,0 +1,48 @@
+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',
+})
+
+export function supportWindowUpgradeAdvice(capabilities = {}) {
+  const batchAttachments = capabilities?.batchAttachments
+  const maxImageDimension = capabilities?.maxImageDimension
+
+  if (batchAttachments === false || maxImageDimension === false) {
+    return Object.freeze({
+      level: 'required',
+      code: 'HOST_BELOW_CURRENT_FLOOR_CAPABILITIES',
+      message: `Host lacks attachment capabilities expected by DVR ${DSH_SUPPORT_WINDOW.dvrTrain}; the minimum supported Host is DSH ${DSH_SUPPORT_WINDOW.minimum}`,
+    })
+  }
+
+  if (batchAttachments === 'unknown' || maxImageDimension === 'unknown') {
+    return Object.freeze({
+      level: 'unknown',
+      code: 'HOST_CURRENT_FLOOR_UNKNOWN',
+      message: `DVR ${DSH_SUPPORT_WINDOW.dvrTrain} requires DSH ${DSH_SUPPORT_WINDOW.minimum} or newer, but this read-only probe cannot prove the relevant Host capabilities`,
+    })
+  }
+
+  return Object.freeze({
+    level: 'ok',
+    code: 'HOST_CURRENT_FLOOR_CAPABLE',
+    message: `Host exposes the attachment capabilities expected by the DVR ${DSH_SUPPORT_WINDOW.dvrTrain} support floor`,
+  })
+}
+
+export function formatDshSupportWindowLines(capabilities = {}) {
+  const advice = supportWindowUpgradeAdvice(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}`,
+    `  support floor: DVR ${DSH_SUPPORT_WINDOW.dvrTrain} -> DSH ${DSH_SUPPORT_WINDOW.minimum}`,
+    `  upgrade advice: ${advice.level} (${advice.code}) — ${advice.message}`,
+  ])
+}

package/lib/http-compat.js

@@ -1,3 +1,5 @@
+import { currentVisionProviderTransport } from './vision-provider-transport.js'
+
 const GLM_4V_FLASH = /^glm-4v-flash(?:$|[-_.])/i
 export const DEFAULT_HTTP_ERROR_DETAIL_MAX_BYTES = 64 * 1024
 
@@ -262,6 +264,11 @@ function nextCompatibilityBody(body, detail) {
 /**
  * Fetch wrapper for vision-router's own OpenAI-compatible requests only.
  *
+ * When the P2 provider transport is installed, every active Router-owned call
+ * goes through that facade. The `fetchImpl` parameter remains as a compatibility
+ * fallback for direct/unit callers, so the behavior outside the public plugin
+ * composition is unchanged.
+ *
  * Layer 1: generic request shape (works for unknown/new models).
  * Layer 2: known model-family presets.
  * Layer 3: bounded, evidence-driven retries when the server reports an output
@@ -270,18 +277,27 @@ function nextCompatibilityBody(body, detail) {
  * sequentially without creating an unbounded retry loop.
  */
 export async function fetchWithOpenAICompatibility(fetchImpl, input, init, context = {}) {
-  if (typeof fetchImpl !== 'function' || context.active !== true) {
-    return fetchImpl(input, init)
+  if (typeof fetchImpl !== 'function') throw new TypeError('fetch implementation is required')
+  const transport = context.active === true ? currentVisionProviderTransport() : undefined
+  const requestFetch = transport
+    ? (nextInput, nextInit) => transport.fetch(nextInput, nextInit, {
+        providerName: context.providerName,
+        allowProxy: context.allowProxy !== false,
+      })
+    : fetchImpl
+
+  if (context.active !== true) {
+    return requestFetch(input, init)
   }
   if (!isCompatibleChatCompletionRequest(input, init)) {
-    return fetchImpl(input, init)
+    return requestFetch(input, init)
   }
 
   let parsed
   try {
     parsed = JSON.parse(init.body)
   } catch {
-    return fetchImpl(input, init)
+    return requestFetch(input, init)
   }
 
   const url = typeof input === 'string' || input instanceof URL ? input : input?.url
@@ -291,7 +307,7 @@ export async function fetchWithOpenAICompatibility(fetchImpl, input, init, conte
     prompt: context.prompt,
   })
   let requestBody = prepared.body
-  let response = await fetchImpl(input, { ...init, body: JSON.stringify(requestBody) })
+  let response = await requestFetch(input, { ...init, body: JSON.stringify(requestBody) })
 
   for (let correction = 0; correction < 2; correction++) {
     if (response.ok || (response.status !== 400 && response.status !== 422)) return response
@@ -308,7 +324,7 @@ export async function fetchWithOpenAICompatibility(fetchImpl, input, init, conte
     }
 
     requestBody = retryBody
-    response = await fetchImpl(input, { ...init, body: JSON.stringify(requestBody) })
+    response = await requestFetch(input, { ...init, body: JSON.stringify(requestBody) })
   }
 
   return response

package/lib/image-resource-governor.js

@@ -1,6 +1,7 @@
 import { currentVisionTurnBudgetSignal } from './turn-budget-context.js'
 
 const MIB = 1024 * 1024
+export const DEFAULT_IMAGE_RESOURCE_MAX_BYPASSES = 2
 
 function abortError() {
   const error = new Error('image resource wait aborted')
@@ -108,9 +109,14 @@ export function boundedOcrTiles(
 }
 
 export class ImageResourceGovernor {
-  constructor({ maxBytes = 256 * MIB, maxConcurrent = 2 } = {}) {
+  constructor({
+    maxBytes = 256 * MIB,
+    maxConcurrent = 2,
+    maxBypasses = DEFAULT_IMAGE_RESOURCE_MAX_BYPASSES,
+  } = {}) {
     this.maxBytes = Math.max(1, Math.floor(Number(maxBytes) || 256 * MIB))
     this.maxConcurrent = Math.max(1, Math.floor(Number(maxConcurrent) || 2))
+    this.maxBypasses = Math.max(0, Math.floor(Number(maxBypasses) || 0))
     this.activeBytes = 0
     this.activeCount = 0
     this.activeExclusive = false
@@ -156,17 +162,35 @@ export class ImageResourceGovernor {
     })
   }
 
+  /**
+   * Find work that fits the current byte/concurrency window without letting a
+   * large request permanently pin every smaller request behind it. Each blocked
+   * non-exclusive request may be bypassed only a small, fixed number of times;
+   * after that it becomes a fairness barrier until capacity is released.
+   * Exclusive work is always a barrier immediately.
+   */
+  _nextRunnable() {
+    const bypassed = []
+    for (let index = 0; index < this.queue.length; index++) {
+      const item = this.queue[index]
+      if (!item || item.settled) continue
+      if (this._canRun(item.request)) return { index, item, bypassed }
+      if (item.request.exclusive || item.bypassCount >= this.maxBypasses) return undefined
+      bypassed.push(item)
+    }
+    return undefined
+  }
+
   _drain() {
     while (this.queue.length > 0) {
-      const item = this.queue[0]
-      if (item.settled) {
-        this.queue.shift()
-        continue
-      }
-      if (!this._canRun(item.request)) break
-      this.queue.shift()
-      this._grant(item)
-      if (item.request.exclusive) break
+      while (this.queue[0]?.settled) this.queue.shift()
+      if (this.queue.length === 0) return
+      const selected = this._nextRunnable()
+      if (!selected) return
+      this.queue.splice(selected.index, 1)
+      for (const item of selected.bypassed) item.bypassCount += 1
+      this._grant(selected.item)
+      if (selected.item.request.exclusive) return
     }
   }
 
@@ -186,6 +210,7 @@ export class ImageResourceGovernor {
         reject,
         settled: false,
         abortHandler: undefined,
+        bypassCount: 0,
       }
       item.abortHandler = () => {
         if (item.settled) return