dsh-vision-router 2.2.8 → 3.0.0

package/lib/vision-attachment-handle-runtime.js

@@ -1,84 +1,91 @@
-const SHA256_HANDLE_PREFIX = /^sha256:/i
-const CANONICAL_SHA256_ID = /^sha256:[0-9a-f]{64}$/i
-const PROJECTED_SHA256_HANDLE = /^sha256:[0-9a-f]{8,63}$/i
-
+const SHA256_HANDLE_PREFIX = /^sha256:/i;
+const CANONICAL_SHA256_ID = /^sha256:[0-9a-f]{64}$/i;
+const PROJECTED_SHA256_HANDLE = /^sha256:[0-9a-f]{8,63}$/i;
 const TOOL_FIELDS = Object.freeze({
-  vision_describe: { arrays: ['attachmentIds', 'paths'] },
-  vision_bootstrap: { arrays: ['attachmentIds', 'paths'] },
-  vision_materialize: { scalars: ['image'] },
-  vision_ground: { scalars: ['image'] },
-  vision_detect: { scalars: ['image'] },
-  vision_crop: { scalars: ['image'] },
-  vision_present: { scalars: ['image'] },
-  vision_pixel_diff: { scalars: ['original', 'rebuilt'] },
-  vision_colors: { scalars: ['image'] },
-  vision_ocr: { scalars: ['image'] },
-  vision_trace: { scalars: ['image'] },
-  vision_extract_foreground: { scalars: ['image'] },
-})
-
-function isObject(value) {
-  return value !== null && typeof value === 'object'
+    vision_describe: { arrays: ['attachmentIds', 'paths'] },
+    vision_bootstrap: { arrays: ['attachmentIds', 'paths'] },
+    vision_materialize: { scalars: ['image'] },
+    vision_ground: { scalars: ['image'] },
+    vision_detect: { scalars: ['image'] },
+    vision_crop: { scalars: ['image'] },
+    vision_present: { scalars: ['image'] },
+    vision_pixel_diff: { scalars: ['original', 'rebuilt'] },
+    vision_colors: { scalars: ['image'] },
+    vision_ocr: { scalars: ['image'] },
+    vision_trace: { scalars: ['image'] },
+    vision_extract_foreground: { scalars: ['image'] },
+});
+function objectRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
 }
-
 function attachmentIdOf(ref) {
-  if (!ref || typeof ref !== 'object') return undefined
-  const value = ref.attachmentId ?? ref.id
-  if (value === undefined || value === null) return undefined
-  const id = String(value).trim()
-  return id === '' ? undefined : id
+    const value = objectRecord(ref);
+    if (value === undefined)
+        return undefined;
+    const raw = value.attachmentId ?? value.id;
+    if (raw === undefined || raw === null)
+        return undefined;
+    const id = String(raw).trim();
+    return id === '' ? undefined : id;
 }
-
 function sessionMessages(session) {
-  try {
-    if (!session || typeof session.deriveMessages !== 'function') return []
-    const messages = session.deriveMessages()
-    return Array.isArray(messages) ? messages : []
-  } catch {
-    return []
-  }
+    try {
+        if (!session || typeof session.deriveMessages !== 'function')
+            return [];
+        const messages = session.deriveMessages();
+        return Array.isArray(messages) ? messages : [];
+    }
+    catch {
+        return [];
+    }
 }
-
 function collectImageRefsFromBlocks(blocks, out) {
-  if (!Array.isArray(blocks)) return
-  for (const block of blocks) {
-    if (!block || typeof block !== 'object') continue
-    if (block.type === 'image' && block.attachment) out.push(block.attachment)
-    if (Array.isArray(block.content)) collectImageRefsFromBlocks(block.content, out)
-  }
+    if (!Array.isArray(blocks))
+        return;
+    for (const block of blocks) {
+        const value = objectRecord(block);
+        if (value === undefined)
+            continue;
+        if (value.type === 'image') {
+            const attachment = objectRecord(value.attachment);
+            if (attachment !== undefined)
+                out.push(attachment);
+        }
+        if (Array.isArray(value.content))
+            collectImageRefsFromBlocks(value.content, out);
+    }
 }
-
 function collectImageRefsFromMessages(messages, out) {
-  if (!Array.isArray(messages)) return
-  for (const message of messages) collectImageRefsFromBlocks(message?.content, out)
+    if (!Array.isArray(messages))
+        return;
+    for (const message of messages) {
+        collectImageRefsFromBlocks(objectRecord(message)?.content, out);
+    }
 }
-
 function authorizedRefs(agent) {
-  const refs = []
-  collectImageRefsFromMessages(sessionMessages(agent?.session), refs)
-  collectImageRefsFromMessages(agent?.inbox?.nextTurn, refs)
-  collectImageRefsFromMessages(agent?.inbox?.nextStep, refs)
-
-  const unique = new Map()
-  for (const ref of refs) {
-    const id = attachmentIdOf(ref)
-    if (id !== undefined && !unique.has(id)) unique.set(id, ref)
-  }
-  return [...unique.values()]
+    const refs = [];
+    collectImageRefsFromMessages(sessionMessages(agent?.session), refs);
+    collectImageRefsFromMessages(agent?.inbox?.nextTurn, refs);
+    collectImageRefsFromMessages(agent?.inbox?.nextStep, refs);
+    const unique = new Map();
+    for (const ref of refs) {
+        const id = attachmentIdOf(ref);
+        if (id !== undefined && !unique.has(id))
+            unique.set(id, ref);
+    }
+    return [...unique.values()];
 }
-
 export function isProjectedAttachmentHandle(value) {
-  return typeof value === 'string' && PROJECTED_SHA256_HANDLE.test(value.trim())
+    return typeof value === 'string' && PROJECTED_SHA256_HANDLE.test(value.trim());
 }
-
 function isSha256HandleLike(value) {
-  return typeof value === 'string' && SHA256_HANDLE_PREFIX.test(value.trim())
+    return typeof value === 'string' && SHA256_HANDLE_PREFIX.test(value.trim());
 }
-
 function isCanonicalSha256Id(value) {
-  return typeof value === 'string' && CANONICAL_SHA256_ID.test(value.trim())
+    return CANONICAL_SHA256_ID.test(value.trim());
 }
-
 /**
  * Resolve DSH's model-facing text-only image alias back to one canonical
  * attachment ref without changing durable attachment identity semantics.
@@ -89,91 +96,95 @@ function isCanonicalSha256Id(value) {
  * prefix. Zero or multiple matches fail closed.
  */
 export function resolveProjectedAttachmentHandle(handle, { sessionVisionIndex, agent } = {}) {
-  const token = typeof handle === 'string' ? handle.trim() : ''
-  if (!isProjectedAttachmentHandle(token)) return { kind: 'not-projected', value: handle }
-
-  const session = agent?.session
-  const refs = authorizedRefs(agent)
-  const wanted = token.toLowerCase()
-  const matches = refs.filter((ref) => {
-    const id = attachmentIdOf(ref)
-    return id !== undefined && id.toLowerCase().startsWith(wanted)
-  })
-
-  if (matches.length === 0) return { kind: 'unknown', handle: token }
-  if (matches.length > 1) return { kind: 'ambiguous', handle: token }
-
-  const candidate = matches[0]
-  const canonicalId = attachmentIdOf(candidate)
-  if (canonicalId === undefined) return { kind: 'unknown', handle: token }
-
-  // The Session event/inbox proves authorization; warm the canonical bounded
-  // index with that exact Host-owned ref, then require the index to hand it
-  // back. This keeps all downstream tools on the same recovery/identity seam.
-  try {
-    sessionVisionIndex?.recordAttachments?.(session, [candidate])
-  } catch {
-    // Authorization is still fail-closed if the bounded cache cannot be warmed.
-  }
-  if (!sessionVisionIndex || typeof sessionVisionIndex.lookupAttachment !== 'function') {
-    return { kind: 'unknown', handle: token }
-  }
-  const ref = sessionVisionIndex.lookupAttachment(session, canonicalId)
-  if (ref === undefined) return { kind: 'unknown', handle: token }
-  return { kind: 'resolved', handle: token, canonicalId, ref }
+    const token = typeof handle === 'string' ? handle.trim() : '';
+    if (!isProjectedAttachmentHandle(token))
+        return { kind: 'not-projected', value: handle };
+    const session = agent?.session;
+    const refs = authorizedRefs(agent);
+    const wanted = token.toLowerCase();
+    const matches = refs.filter((ref) => {
+        const id = attachmentIdOf(ref);
+        return id !== undefined && id.toLowerCase().startsWith(wanted);
+    });
+    if (matches.length === 0)
+        return { kind: 'unknown', handle: token };
+    if (matches.length > 1)
+        return { kind: 'ambiguous', handle: token };
+    const candidate = matches[0];
+    const canonicalId = attachmentIdOf(candidate);
+    if (candidate === undefined || canonicalId === undefined)
+        return { kind: 'unknown', handle: token };
+    // The Session event/inbox proves authorization; warm the canonical bounded
+    // index with that exact Host-owned ref, then require the index to hand it
+    // back. This keeps all downstream tools on the same recovery/identity seam.
+    try {
+        sessionVisionIndex?.recordAttachments?.(session, [candidate]);
+    }
+    catch {
+        // Authorization is still fail-closed if the bounded cache cannot be warmed.
+    }
+    if (!sessionVisionIndex || typeof sessionVisionIndex.lookupAttachment !== 'function') {
+        return { kind: 'unknown', handle: token };
+    }
+    const ref = sessionVisionIndex.lookupAttachment(session, canonicalId);
+    if (ref === undefined)
+        return { kind: 'unknown', handle: token };
+    return { kind: 'resolved', handle: token, canonicalId, ref };
 }
-
 function canonicalizeValue(value, context) {
-  if (!isSha256HandleLike(value)) return value
-  if (isCanonicalSha256Id(value)) return value
-  if (!isProjectedAttachmentHandle(value)) {
-    throw new Error(
-      `${context.toolName}: invalid attachment handle "${String(value).trim()}" ` +
-        '(sha256 attachment handles must be a canonical id or a DSH-projected 8+ hex prefix)',
-    )
-  }
-  const result = resolveProjectedAttachmentHandle(value, context)
-  if (result.kind === 'resolved') return result.canonicalId
-  if (result.kind === 'ambiguous') {
-    throw new Error(
-      `${context.toolName}: ambiguous attachment handle "${result.handle}" ` +
-        '(multiple images in this conversation share that prefix; use a full attachment id or attach the image again)',
-    )
-  }
-  throw new Error(
-    `${context.toolName}: unknown attachment handle "${result.handle}" ` +
-      '(it is not authorized by an image in this conversation; attach the image again if needed)',
-  )
+    if (!isSha256HandleLike(value))
+        return value;
+    if (isCanonicalSha256Id(value))
+        return value;
+    if (!isProjectedAttachmentHandle(value)) {
+        throw new Error(`${context.toolName}: invalid attachment handle "${value.trim()}" ` +
+            '(sha256 attachment handles must be a canonical id or a DSH-projected 8+ hex prefix)');
+    }
+    const result = resolveProjectedAttachmentHandle(value, context);
+    if (result.kind === 'resolved')
+        return result.canonicalId;
+    if (result.kind === 'ambiguous') {
+        throw new Error(`${context.toolName}: ambiguous attachment handle "${result.handle}" ` +
+            '(multiple images in this conversation share that prefix; use a full attachment id or attach the image again)');
+    }
+    if (result.kind === 'unknown') {
+        throw new Error(`${context.toolName}: unknown attachment handle "${result.handle}" ` +
+            '(it is not authorized by an image in this conversation; attach the image again if needed)');
+    }
+    return value;
 }
-
 function canonicalizeArgs(args, context, fields) {
-  if (!isObject(args) || Array.isArray(args)) return args
-  let next
-  for (const field of fields.scalars ?? []) {
-    if (!Object.hasOwn(args, field)) continue
-    const value = canonicalizeValue(args[field], context)
-    if (value !== args[field]) {
-      next ??= { ...args }
-      next[field] = value
+    const record = objectRecord(args);
+    if (record === undefined)
+        return args;
+    let next;
+    for (const field of fields.scalars ?? []) {
+        if (!Object.hasOwn(record, field))
+            continue;
+        const value = canonicalizeValue(record[field], context);
+        if (value !== record[field]) {
+            next ??= { ...record };
+            next[field] = value;
+        }
     }
-  }
-  for (const field of fields.arrays ?? []) {
-    const values = args[field]
-    if (!Array.isArray(values)) continue
-    let changed = false
-    const mapped = values.map((value) => {
-      const canonical = canonicalizeValue(value, context)
-      if (canonical !== value) changed = true
-      return canonical
-    })
-    if (changed) {
-      next ??= { ...args }
-      next[field] = mapped
+    for (const field of fields.arrays ?? []) {
+        const values = record[field];
+        if (!Array.isArray(values))
+            continue;
+        let changed = false;
+        const mapped = values.map((value) => {
+            const canonical = canonicalizeValue(value, context);
+            if (canonical !== value)
+                changed = true;
+            return canonical;
+        });
+        if (changed) {
+            next ??= { ...record };
+            next[field] = mapped;
+        }
     }
-  }
-  return next ?? args
+    return next ?? args;
 }
-
 /**
  * Canonicalize only image-source arguments of Vision Router tools. Ordinary
  * prose fields are never scanned, so a user mentioning `sha256:deadbeef` in a
@@ -182,19 +193,28 @@ function canonicalizeArgs(args, context, fields) {
  * fails closed rather than falling through to cwd-relative filesystem lookup.
  */
 export function wrapVisionAttachmentHandleDefinition(def, options = {}) {
-  if (!def || typeof def !== 'object' || typeof def.execute !== 'function') return def
-  const fields = TOOL_FIELDS[def.name]
-  if (!fields || !options.sessionVisionIndex) return def
-  const execute = def.execute
-  return {
-    ...def,
-    execute(args, exec) {
-      const nextArgs = canonicalizeArgs(args, {
-        sessionVisionIndex: options.sessionVisionIndex,
-        agent: exec?.agent,
-        toolName: def.name,
-      }, fields)
-      return execute.call(def, nextArgs, exec)
-    },
-  }
+    // Tool definitions arrive from the Host registry at runtime. Static generic
+    // constraints cannot replace this boundary guard: partial/legacy Hosts may
+    // still pass nullish or malformed values before their own validation runs.
+    if (def === null || typeof def !== 'object' || typeof def.execute !== 'function')
+        return def;
+    const toolName = def.name;
+    const fields = typeof toolName === 'string'
+        ? TOOL_FIELDS[toolName]
+        : undefined;
+    const sessionVisionIndex = options.sessionVisionIndex;
+    if (!fields || !sessionVisionIndex || typeof toolName !== 'string')
+        return def;
+    const execute = def.execute;
+    return {
+        ...def,
+        execute(args, exec) {
+            const nextArgs = canonicalizeArgs(args, {
+                sessionVisionIndex,
+                ...(exec?.agent === undefined ? {} : { agent: exec.agent }),
+                toolName,
+            }, fields);
+            return execute.call(def, nextArgs, exec);
+        },
+    };
 }

package/lib/vision-backend-runtime-policy.js

@@ -215,7 +215,7 @@ function failureStream(message, code = 'VISION_IMAGE_DELIVERY_UNAVAILABLE') {
   }
 }
 
-function directStream(ctx, core, plan, call, logger, source) {
+function directStream(ctx, core, plan, call, logger, source, providerTransport) {
   return {
     async *[Symbol.asyncIterator]() {
       const started = Date.now()
@@ -252,6 +252,7 @@ function directStream(ctx, core, plan, call, logger, source) {
             maxTokens: call.maxTokens ?? 4096,
             signal: call.signal,
             sessionId: call.sessionId,
+            providerTransport,
             resolveCredential: async (ref) => ref === keyRef ? apiKey : undefined,
           },
         )
@@ -349,7 +350,7 @@ function llmWithRuntimePolicy(ctx, llm, options) {
                 )
                 return
               }
-              yield* directStream(ctx, core, plan, call, logger, source)
+              yield* directStream(ctx, core, plan, call, logger, source, options.providerTransport)
               return
             }
 
@@ -414,5 +415,21 @@ export function contextWithVisionBackendRuntimePolicy(ctx, options = {}) {
     ? finalContextDecorator(wrapped)
     : wrapped
   wrappedContexts.set(ctx, result)
+  let lifecycleOwned = false
+  try {
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(
+        () => () => {
+          if (wrappedContexts.get(ctx) === result) wrappedContexts.delete(ctx)
+        },
+        'vision-router: backend runtime policy context lifecycle',
+      )
+      lifecycleOwned = true
+    }
+  } catch {
+    // The current caller can still use this one-shot policy view.
+  }
+  // options contains generation-owned config/transport/evidence closures.
+  if (!lifecycleOwned && wrappedContexts.get(ctx) === result) wrappedContexts.delete(ctx)
   return result
 }

package/lib/vision-background-benchmark.js

@@ -552,6 +552,7 @@ export function createBackgroundCapabilityProfiler({
   let lastForegroundAt = Number(now())
   let runningController
   let runningWork
+  let tickTask
   let topologyDirty = false
   let lastAuthority = resolveVisionRoutingAuthority(activeSettings(ctx, config))
   const backoff = new Map()
@@ -689,7 +690,7 @@ export function createBackgroundCapabilityProfiler({
     }
   }
 
-  const tick = async () => {
+  const runTick = async () => {
     if (stopped || runningController) return
     const currentNow = Number(now())
     const current = activeSettings(ctx, config)
@@ -864,6 +865,32 @@ export function createBackgroundCapabilityProfiler({
     }
   }
 
+  const tick = () => {
+    if (tickTask) return tickTask
+    let tracked
+    // `tracked` is assigned before any rejection can be observed: the timer
+    // callback and the lifecycle disposer both call tick(), and a background
+    // scan that throws must degrade to a logged failure instead of an
+    // unhandled process-level rejection.
+    tracked = Promise.resolve()
+      .then(runTick)
+      .catch((error) => {
+        try {
+          logger?.warn?.(
+            'vision-router: background benchmark tick failed: %s',
+            bounded(error?.message ?? error),
+          )
+        } catch {
+          /* diagnostics only */
+        }
+      })
+      .finally(() => {
+        if (tickTask === tracked) tickTask = undefined
+      })
+    tickTask = tracked
+    return tracked
+  }
+
   const foregroundStart = () => {
     activeForeground += 1
     lastForegroundAt = Number(now())
@@ -893,6 +920,7 @@ export function createBackgroundCapabilityProfiler({
     if (timer !== undefined) clearTimer(timer)
     timer = undefined
     yieldBackground('background profiler stopped')
+    return tickTask ?? Promise.resolve()
   }
 
   schedule(idleMs)
@@ -1022,17 +1050,26 @@ export function installBackgroundCapabilityProfiling(ctx, config, core, store, o
     // Event-driven wakeups are an optimization; the short authority scan remains.
   }
 
+  let lifecycleOwned = true
   try {
-    ctx?.effect?.(() => () => {
+    ctx?.effect?.(() => async () => {
       for (const dispose of eventDisposers.splice(0)) {
         try { dispose() } catch {}
       }
-      profiler.stop()
+      await profiler.stop()
     }, 'vision-router: background capability profiler')
   } catch {
-    // Cleanup registration is best-effort; the profiler remains process-scoped.
+    lifecycleOwned = false
+    for (const dispose of eventDisposers.splice(0)) {
+      try { dispose() } catch {}
+    }
+    void profiler.stop().catch(() => {})
   }
 
+  // An inactive/unowned generation must not continue admitting client scripts,
+  // routes, or tool wrappers after its profiler ownership was rejected.
+  if (!lifecycleOwned) return { ctx, profiler }
+
   installVisionExactCheckClient(ctx)
 
   try {

package/lib/vision-background-failure-policy.js

@@ -1,47 +1,47 @@
-export const BACKGROUND_AUTH_STOP_TTL_MS = 10 * 60 * 1000
-export const BACKGROUND_ENDPOINT_STOP_TTL_MS = 6 * 60 * 60 * 1000
-export const BACKGROUND_TRANSIENT_RETRY_MS = 30 * 60 * 1000
-
+export const BACKGROUND_AUTH_STOP_TTL_MS = 10 * 60 * 1000;
+export const BACKGROUND_ENDPOINT_STOP_TTL_MS = 6 * 60 * 60 * 1000;
+export const BACKGROUND_TRANSIENT_RETRY_MS = 30 * 60 * 1000;
 const DEFAULT_POLICY = Object.freeze({
-  retryable: true,
-  persist: false,
-  retryAfterMs: undefined,
-  ttlMs: undefined,
-})
-
-const POLICIES = Object.freeze({
-  auth: Object.freeze({
-    retryable: false,
-    persist: false,
-    ttlMs: BACKGROUND_AUTH_STOP_TTL_MS,
-  }),
-  protocol: Object.freeze({
-    retryable: false,
-    persist: true,
-    ttlMs: BACKGROUND_ENDPOINT_STOP_TTL_MS,
-  }),
-  unavailable: Object.freeze({
-    retryable: false,
-    persist: true,
-    ttlMs: BACKGROUND_ENDPOINT_STOP_TTL_MS,
-  }),
-  'unsupported-image': Object.freeze({
-    retryable: false,
-    persist: false,
-  }),
-  'visual-proof': Object.freeze({
     retryable: true,
     persist: false,
-    retryAfterMs: BACKGROUND_TRANSIENT_RETRY_MS,
-  }),
-  infrastructure: Object.freeze({
-    retryable: true,
-    persist: false,
-    retryAfterMs: BACKGROUND_TRANSIENT_RETRY_MS,
-  }),
-})
-
+    retryAfterMs: undefined,
+    ttlMs: undefined,
+});
+const POLICIES = Object.freeze({
+    auth: Object.freeze({
+        retryable: false,
+        persist: false,
+        ttlMs: BACKGROUND_AUTH_STOP_TTL_MS,
+    }),
+    protocol: Object.freeze({
+        retryable: false,
+        persist: true,
+        ttlMs: BACKGROUND_ENDPOINT_STOP_TTL_MS,
+    }),
+    unavailable: Object.freeze({
+        retryable: false,
+        persist: true,
+        ttlMs: BACKGROUND_ENDPOINT_STOP_TTL_MS,
+    }),
+    'unsupported-image': Object.freeze({
+        retryable: false,
+        persist: false,
+    }),
+    'visual-proof': Object.freeze({
+        retryable: true,
+        persist: false,
+        retryAfterMs: BACKGROUND_TRANSIENT_RETRY_MS,
+    }),
+    infrastructure: Object.freeze({
+        retryable: true,
+        persist: false,
+        retryAfterMs: BACKGROUND_TRANSIENT_RETRY_MS,
+    }),
+});
 /** Failure lifetime is separate from failure classification. */
 export function backgroundFailurePolicy(errorClass) {
-  return POLICIES[String(errorClass ?? '')] ?? DEFAULT_POLICY
+    const key = String(errorClass ?? '');
+    return Object.prototype.hasOwnProperty.call(POLICIES, key)
+        ? POLICIES[key]
+        : DEFAULT_POLICY;
 }