dsh-vision-router 2.2.8 → 3.0.0

package/lib/session-affinity.js

@@ -1,93 +1,106 @@
-const MAX_SESSION_AFFINITY_ID_LENGTH = 512
-
-/** Preserve DSH's in-process session identity exactly; no wire rules belong here. */
+const MAX_SESSION_AFFINITY_ID_LENGTH = 512;
+function propertyBag(value) {
+    return value !== null && (typeof value === 'object' || typeof value === 'function')
+        ? value
+        : undefined;
+}
+function wireAsciiIdentity(text) {
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        const edge = index === 0 || index === text.length - 1;
+        if (edge) {
+            if (code < 33 || code > 126)
+                return false;
+        }
+        else if (code < 32 || code > 126) {
+            return false;
+        }
+    }
+    return true;
+}
 export function rawSessionIdentity(value) {
-  if (value === undefined || value === null) return undefined
-  try {
-    return String(value)
-  } catch {
-    return undefined
-  }
+    if (value === undefined || value === null)
+        return undefined;
+    try {
+        return String(value);
+    }
+    catch {
+        return undefined;
+    }
 }
-
-/** Read the live DSH session id across released/alpha session shapes without rewriting it. */
 export function sessionIdentityOf(session) {
-  if (!session) return undefined
-  try {
-    const direct = rawSessionIdentity(session.id)
-    if (direct !== undefined) return direct
-  } catch {
-    /* continue to persisted/header shapes */
-  }
-  try {
-    const header = rawSessionIdentity(session.header?.id)
-    if (header !== undefined) return header
-  } catch {
-    /* continue to requestHeader() */
-  }
-  try {
-    if (typeof session.requestHeader === 'function') {
-      return rawSessionIdentity(session.requestHeader()?.id)
+    const source = propertyBag(session);
+    if (source === undefined)
+        return undefined;
+    try {
+        const direct = rawSessionIdentity(source.id);
+        if (direct !== undefined)
+            return direct;
     }
-  } catch {
-    /* no usable session identity */
-  }
-  return undefined
+    catch { }
+    try {
+        const header = rawSessionIdentity(propertyBag(source.header)?.id);
+        if (header !== undefined)
+            return header;
+    }
+    catch { }
+    try {
+        const requestHeader = source.requestHeader;
+        if (typeof requestHeader === 'function') {
+            return rawSessionIdentity(propertyBag(requestHeader.call(session))?.id);
+        }
+    }
+    catch { }
+    return undefined;
 }
-
-/**
- * Admit an opaque identity to an HTTP header without changing it. Fetch/undici
- * requires ByteString-compatible header values; use visible ASCII so behavior
- * is identical across Node 22/24 and HTTP implementations. Leading/trailing
- * whitespace is rejected because Headers would normalize it, violating the
- * requirement to preserve the DSH identity unchanged.
- */
 export function wireSessionAffinityId(value) {
-  const text = rawSessionIdentity(value)
-  if (text === undefined || text === '' || text.length > MAX_SESSION_AFFINITY_ID_LENGTH) return undefined
-  if (text.trim() !== text) return undefined
-  if (!/^[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?$/.test(text)) return undefined
-  return text
+    const text = rawSessionIdentity(value);
+    if (text === undefined
+        || text === ''
+        || text.length > MAX_SESSION_AFFINITY_ID_LENGTH) {
+        return undefined;
+    }
+    if (text.trim() !== text)
+        return undefined;
+    return wireAsciiIdentity(text) ? text : undefined;
 }
-
 export function isOfficialOpenCodeGoUrl(value) {
-  try {
-    const url = new URL(String(value))
-    return (
-      url.protocol === 'https:' &&
-      url.hostname.toLowerCase() === 'opencode.ai' &&
-      /^\/zen\/go(?:\/|$)/i.test(url.pathname)
-    )
-  } catch {
-    return false
-  }
+    try {
+        const url = new URL(String(value));
+        return (url.protocol === 'https:'
+            && url.hostname.toLowerCase() === 'opencode.ai'
+            && /^\/zen\/go(?:\/|$)/i.test(url.pathname));
+    }
+    catch {
+        return false;
+    }
 }
-
 export function isOpenCodeGoProvider(provider) {
-  return isOfficialOpenCodeGoUrl(provider?.baseURL ?? provider?.baseUrl ?? '')
+    const source = propertyBag(provider);
+    return isOfficialOpenCodeGoUrl(source?.baseURL ?? source?.baseUrl ?? '');
 }
-
 function invalidAffinityError(sessionId) {
-  const raw = rawSessionIdentity(sessionId)
-  const error = new Error(
-    raw === undefined || raw === ''
-      ? 'OpenCode Go requires a stable session identity; refusing a direct request without one'
-      : 'OpenCode Go session identity is not safe for an HTTP header; refusing to rewrite or truncate it',
-  )
-  error.code = raw === undefined || raw === '' ? 'OPENCODE_SESSION_REQUIRED' : 'OPENCODE_SESSION_INVALID'
-  return error
+    const raw = rawSessionIdentity(sessionId);
+    const code = raw === undefined || raw === ''
+        ? 'OPENCODE_SESSION_REQUIRED'
+        : 'OPENCODE_SESSION_INVALID';
+    return Object.assign(new Error(code === 'OPENCODE_SESSION_REQUIRED'
+        ? 'OpenCode Go requires a stable session identity; refusing a direct request without one'
+        : 'OpenCode Go session identity is not safe for an HTTP header; refusing to rewrite or truncate it'), { code });
 }
-
 export function directSessionAffinityHeaders(provider, sessionId) {
-  if (!isOpenCodeGoProvider(provider)) return {}
-  const wire = wireSessionAffinityId(sessionId)
-  if (wire === undefined) throw invalidAffinityError(sessionId)
-  return { 'x-opencode-session': wire }
+    if (!isOpenCodeGoProvider(provider))
+        return {};
+    const wire = wireSessionAffinityId(sessionId);
+    if (wire === undefined)
+        throw invalidAffinityError(sessionId);
+    return { 'x-opencode-session': wire };
 }
-
 export function openCodeSessionAffinityHeaderForUrl(url, sessionId) {
-  if (!isOfficialOpenCodeGoUrl(url)) return undefined
-  const wire = wireSessionAffinityId(sessionId)
-  if (wire === undefined) throw invalidAffinityError(sessionId)
-  return wire
+    if (!isOfficialOpenCodeGoUrl(url))
+        return undefined;
+    const wire = wireSessionAffinityId(sessionId);
+    if (wire === undefined)
+        throw invalidAffinityError(sessionId);
+    return wire;
 }

package/lib/session-event-history-compat.js

@@ -0,0 +1,30 @@
+function propertyBag(value) {
+    return value !== null && (typeof value === 'object' || typeof value === 'function')
+        ? value
+        : undefined;
+}
+/**
+ * Read the released Session-local event snapshot used only when the Host does
+ * not advertise the asynchronous SessionQuery capability.
+ *
+ * Durable-data compatibility is intentionally separate from the current Host
+ * floor: this helper feature-detects historical Session shapes at runtime and
+ * never claims that either shape exists through a static Host type.
+ */
+export function legacySessionEvents(session) {
+    const source = propertyBag(session);
+    if (source === undefined)
+        return undefined;
+    try {
+        const snapshotEvents = source.snapshotEvents;
+        if (typeof snapshotEvents === 'function') {
+            const events = snapshotEvents.call(session);
+            return Array.isArray(events) ? events : undefined;
+        }
+        const events = source.events;
+        return Array.isArray(events) ? events : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -62,9 +62,13 @@ function normalizeHookResult(event, args, 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.
+ * while V4 rejects that wrapper in favor of producer-owned source kinds.
+ *
+ * Session-facing DVR producers are responsible for calling
+ * visionRouterMessageSource(session) when they create a message. This final
+ * publication boundary is deliberately defense-in-depth: it protects legacy
+ * or future producers that accidentally reach a hook with the wrong DVR source,
+ * but producer correctness must not depend on this proxy being the sole owner.
  */
 export function installVisionRouterMessageSourceBoundary(ctx) {
   if (!ctx || typeof ctx !== 'object') return ctx

package/lib/session-query-readers.js

@@ -0,0 +1,263 @@
+const disposeSymbol = Symbol.dispose;
+const SESSION_EVENT_TAIL_INITIAL_AFTER = 50;
+const SESSION_EVENT_TAIL_MAX_EVENTS = 4096;
+const SESSION_EVENT_TAIL_MAX_READS = 128;
+function objectRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : undefined;
+}
+function propertyBag(value) {
+    return value !== null && (typeof value === 'object' || typeof value === 'function')
+        ? value
+        : undefined;
+}
+function sessionIdOf(session) {
+    return propertyBag(session)?.id;
+}
+function sessionQueryOf(ctx) {
+    const context = objectRecord(ctx);
+    if (context === undefined)
+        return undefined;
+    // sessionQuery is an optional capability. Cordis service property reads may
+    // register a hard pending dependency outside inject(); Context#get is the
+    // non-owning capability probe and is the only supported lookup here.
+    try {
+        const get = context.get;
+        if (typeof get !== 'function')
+            return undefined;
+        return objectRecord(get.call(ctx, 'sessionQuery'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function sessionQueryCode(error) {
+    const code = propertyBag(error)?.code;
+    return typeof code === 'string' ? code : undefined;
+}
+/**
+ * Build the narrow bounded Session event reader used by durable surface repair.
+ *
+ * The Host SessionQuery service is intentionally discovered by capability at
+ * runtime instead of imported as a concrete service graph. DVR owns only the
+ * small supported/unsupported reader port returned from this adapter.
+ */
+export function createSessionEventReader(ctx) {
+    return async function readSessionEvent(session, seqValue) {
+        const sessionId = sessionIdOf(session);
+        if (sessionId === undefined || sessionId === null)
+            return { supported: false };
+        if (typeof seqValue !== 'number'
+            || !Number.isSafeInteger(seqValue)
+            || seqValue < 0
+            || Object.is(seqValue, -0)) {
+            throw new TypeError(`session event seq must be a non-negative safe integer, got ${String(seqValue)}`);
+        }
+        const seq = seqValue;
+        const query = sessionQueryOf(ctx);
+        const readEvent = query?.readEvent;
+        if (query === undefined || typeof readEvent !== 'function') {
+            return { supported: false };
+        }
+        const window = await readEvent.call(query, { sessionId, seq });
+        const event = propertyBag(window)?.target;
+        const eventRecord = objectRecord(event);
+        if (eventRecord === undefined) {
+            throw new Error(`sessionQuery.readEvent returned no target for seq ${seq}`);
+        }
+        if (eventRecord.seq !== undefined && eventRecord.seq !== seq) {
+            throw new Error(`sessionQuery.readEvent returned seq ${String(eventRecord.seq)} for requested seq ${seq}`);
+        }
+        return { supported: true, event };
+    };
+}
+/**
+ * Read raw Session events strictly after one known committed seq through the
+ * Host-owned bounded SessionQuery window contract.
+ */
+export function createSessionEventTailReader(ctx) {
+    let afterHint = SESSION_EVENT_TAIL_INITIAL_AFTER;
+    const readWindow = async (query, sessionId, seq) => {
+        let after = afterHint;
+        while (true) {
+            try {
+                const request = after > 0 ? { sessionId, seq, after } : { sessionId, seq };
+                const readEvent = query.readEvent;
+                if (typeof readEvent !== 'function') {
+                    throw new TypeError('sessionQuery.readEvent is unavailable');
+                }
+                const window = await readEvent.call(query, request);
+                afterHint = after;
+                return { window, after };
+            }
+            catch (error) {
+                if (sessionQueryCode(error) !== 'SESSION_QUERY_INVALID_WINDOW' || after <= 0) {
+                    throw error;
+                }
+                after = after <= 1 ? 0 : Math.floor(after / 2);
+            }
+        }
+    };
+    return async function readSessionEventTail(session, anchorSeqValue, options = {}) {
+        const sessionId = sessionIdOf(session);
+        if (sessionId === undefined || sessionId === null)
+            return { supported: false };
+        if (typeof anchorSeqValue !== 'number'
+            || !Number.isSafeInteger(anchorSeqValue)
+            || anchorSeqValue < 0
+            || Object.is(anchorSeqValue, -0)) {
+            throw new TypeError(`session tail anchor seq must be a non-negative safe integer, got ${String(anchorSeqValue)}`);
+        }
+        const anchorSeq = anchorSeqValue;
+        const query = sessionQueryOf(ctx);
+        if (query === undefined || typeof query.readEvent !== 'function') {
+            return { supported: false };
+        }
+        const collect = propertyBag(options)?.collect !== false;
+        const events = [];
+        let capturedThroughSeq = anchorSeq;
+        let cursor = anchorSeq;
+        let inspected = 0;
+        let reads = 0;
+        while (reads < SESSION_EVENT_TAIL_MAX_READS) {
+            let result;
+            try {
+                result = await readWindow(query, sessionId, cursor);
+            }
+            catch (error) {
+                if (sessionQueryCode(error) === 'SESSION_QUERY_EVENT_NOT_FOUND'
+                    && cursor > anchorSeq) {
+                    return {
+                        supported: true,
+                        events,
+                        capturedThroughSeq,
+                        truncated: false,
+                    };
+                }
+                throw error;
+            }
+            reads += 1;
+            const window = propertyBag(result.window);
+            const target = window?.target;
+            const targetRecord = objectRecord(target);
+            if (targetRecord === undefined || targetRecord.seq !== cursor) {
+                throw new Error(`sessionQuery.readEvent returned an invalid target for seq ${cursor}`);
+            }
+            const windowEvents = window?.events;
+            if (!Array.isArray(windowEvents) || windowEvents.length === 0) {
+                throw new Error(`sessionQuery.readEvent returned no event window for seq ${cursor}`);
+            }
+            let expectedSeq = cursor;
+            let endSeq = cursor;
+            for (const event of windowEvents) {
+                const seqValue = propertyBag(event)?.seq;
+                if (typeof seqValue !== 'number'
+                    || !Number.isSafeInteger(seqValue)
+                    || seqValue !== expectedSeq) {
+                    throw new Error(`sessionQuery.readEvent returned non-contiguous seq ${String(seqValue)}; expected ${expectedSeq}`);
+                }
+                const seq = seqValue;
+                expectedSeq += 1;
+                endSeq = seq;
+                if (seq <= capturedThroughSeq)
+                    continue;
+                capturedThroughSeq = seq;
+                inspected += 1;
+                if (collect)
+                    events.push(event);
+                if (inspected >= SESSION_EVENT_TAIL_MAX_EVENTS) {
+                    return {
+                        supported: true,
+                        events,
+                        capturedThroughSeq,
+                        truncated: true,
+                    };
+                }
+            }
+            const windowEndSeq = window?.endSeq;
+            if (typeof windowEndSeq === 'number'
+                && Number.isSafeInteger(windowEndSeq)
+                && windowEndSeq !== endSeq) {
+                throw new Error(`sessionQuery.readEvent returned endSeq ${String(windowEndSeq)} for window ending at ${endSeq}`);
+            }
+            if (result.after > 0) {
+                if (endSeq <= cursor || windowEvents.length < result.after + 1) {
+                    return {
+                        supported: true,
+                        events,
+                        capturedThroughSeq: Math.max(capturedThroughSeq, endSeq),
+                        truncated: false,
+                    };
+                }
+                cursor = endSeq;
+                continue;
+            }
+            // readWindowMax: 0 is valid. Walk exact seqs and use EVENT_NOT_FOUND as
+            // the logical tail sentinel.
+            cursor += 1;
+        }
+        return {
+            supported: true,
+            events,
+            capturedThroughSeq,
+            truncated: true,
+        };
+    };
+}
+/**
+ * Build the asynchronous Session-log reader used by cold attachment recovery
+ * and batched surface repair.
+ *
+ * Prefer the Host observation lease when available and always dispose the lease
+ * after copying out the raw event array. Older supported capability shapes keep
+ * the released readSession() path.
+ */
+export function createSessionLogReader(ctx) {
+    return async function readSessionLog(session) {
+        const sessionId = sessionIdOf(session);
+        if (sessionId === undefined || sessionId === null)
+            return { supported: false };
+        const query = sessionQueryOf(ctx);
+        if (query === undefined)
+            return { supported: false };
+        const observeSession = query.observeSession;
+        if (typeof observeSession === 'function') {
+            let observation;
+            try {
+                observation = await observeSession.call(query, sessionId, { projectionMode: 'none' });
+                const observationBag = propertyBag(observation);
+                const events = observationBag?.events;
+                if (!Array.isArray(events)) {
+                    throw new Error('sessionQuery.observeSession returned no event log');
+                }
+                const observedId = propertyBag(observationBag?.header)?.id;
+                if (observedId !== undefined && observedId !== sessionId) {
+                    throw new Error(`sessionQuery.observeSession returned session ${String(observedId)} for requested ${String(sessionId)}`);
+                }
+                return { supported: true, events };
+            }
+            finally {
+                const dispose = disposeSymbol === undefined
+                    ? undefined
+                    : propertyBag(observation)?.[disposeSymbol];
+                if (typeof dispose === 'function')
+                    dispose.call(observation);
+            }
+        }
+        const readSession = query.readSession;
+        if (typeof readSession !== 'function')
+            return { supported: false };
+        const snapshot = await readSession.call(query, sessionId);
+        const snapshotBag = propertyBag(snapshot);
+        const events = snapshotBag?.events;
+        if (!Array.isArray(events)) {
+            throw new Error('sessionQuery.readSession returned no event log');
+        }
+        const observedId = propertyBag(snapshotBag?.session)?.id;
+        if (observedId !== undefined && observedId !== sessionId) {
+            throw new Error(`sessionQuery.readSession returned session ${String(observedId)} for requested ${String(sessionId)}`);
+        }
+        return { supported: true, events };
+    };
+}

package/lib/session-surface-compat.js

@@ -1,41 +1,40 @@
+function propertyBag(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : undefined;
+}
 function nonNegativeSafeInteger(value) {
-  return Number.isSafeInteger(value) && value >= 0 && !Object.is(value, -0)
+    return (typeof value === 'number'
+        && Number.isSafeInteger(value)
+        && value >= 0
+        && !Object.is(value, -0));
 }
-
 /**
  * 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, 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.
- *
- * Returns undefined when the Host does not expose a supported logical Session
- * format. Callers can then keep request-local safety behavior while skipping
- * optional durable surface hygiene.
+ * startSeq/endSeq, and reviewed format v4 keeps that shape. Unknown future
+ * formats fail closed instead of being guessed from package version.
  */
-export function sessionSurfaceReplacementIntent(session, seq) {
-  if (!nonNegativeSafeInteger(seq)) {
-    throw new TypeError('session surface replacement seq must be a non-negative safe integer')
-  }
-
-  const version = session?.header?.version
-  if (!nonNegativeSafeInteger(version)) return undefined
-
-  if (version <= 2) {
-    return {
-      surfaceOp: { op: 'replace', start: seq, end: seq },
-      sourceEventSeqs: [seq],
+export function sessionSurfaceReplacementIntent(session, seqValue) {
+    if (!nonNegativeSafeInteger(seqValue)) {
+        throw new TypeError('session surface replacement seq must be a non-negative safe integer');
+    }
+    const seq = seqValue;
+    const version = propertyBag(propertyBag(session)?.header)?.version;
+    if (!nonNegativeSafeInteger(version))
+        return undefined;
+    if (version <= 2) {
+        return {
+            surfaceOp: { op: 'replace', start: seq, end: seq },
+            sourceEventSeqs: [seq],
+        };
     }
-  }
-
-  if (version === 3 || version === 4) {
-    return {
-      surfaceOp: { op: 'replace', startSeq: seq, endSeq: seq },
-      sourceEventSeqs: [seq],
+    if (version === 3 || version === 4) {
+        return {
+            surfaceOp: { op: 'replace', startSeq: seq, endSeq: seq },
+            sourceEventSeqs: [seq],
+        };
     }
-  }
-
-  return undefined
+    return undefined;
 }

package/lib/session-surface-policy-domain.js

@@ -0,0 +1,85 @@
+const OWNERSHIP = Object.freeze({
+    PLUGIN_OWNED: 'vision-router-owned',
+    NATIVE: 'native-image',
+    TEXT_ONLY: 'text-only',
+    UNKNOWN: 'unknown',
+});
+const KNOWN_OWNERSHIP = new Set(Object.values(OWNERSHIP));
+function objectRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function normalizedOwnership(policy) {
+    const source = objectRecord(policy);
+    if (source === undefined)
+        return undefined;
+    return typeof source.ownership === 'string'
+        && KNOWN_OWNERSHIP.has(source.ownership)
+        ? source.ownership
+        : OWNERSHIP.UNKNOWN;
+}
+/**
+ * Resolve one immutable Core-facing capability snapshot for the current Session.
+ *
+ * Image ownership and Vision-mode authority remain separate facts. Durable
+ * transcript preservation is fail-safe: every real Session policy preserves
+ * the user-owned image, while the step authority alone decides whether DVR
+ * automatic/tool surfaces are active.
+ */
+export function resolveSessionSurfacePolicy({ visionPolicy, visionModeAuthority, config = {}, schemaBootstrapping = false, } = {}) {
+    const source = objectRecord(visionPolicy);
+    const authority = objectRecord(visionModeAuthority);
+    const value = objectRecord(config) ?? {};
+    const ownership = normalizedOwnership(source);
+    const pluginOwned = ownership === OWNERSHIP.PLUGIN_OWNED;
+    const visionModeEnabled = authority !== undefined
+        ? authority.enabled === true
+        : source === undefined
+            ? true
+            : pluginOwned;
+    const preserveRawImages = source !== undefined;
+    const rewriteCurrentImages = false;
+    const allowStructuredBootstrap = visionModeEnabled;
+    const allowGenericAutoMount = visionModeEnabled;
+    const surface = Object.freeze({
+        preserveRawImages,
+        rewriteCurrentImages,
+        visionTools: value.tool !== false && visionModeEnabled,
+        structuredBootstrap: value.structuredVisionBootstrap === true && visionModeEnabled,
+        genericAutoMount: value.autoActivateOnImage !== false && visionModeEnabled,
+        instantDescribe: value.instantDescribe !== false && visionModeEnabled,
+    });
+    const overrides = {};
+    if (schemaBootstrapping === true
+        && source === undefined
+        && value.tool === false) {
+        overrides.tool = true;
+    }
+    if (source !== undefined && value.rewriteImages !== false) {
+        overrides.rewriteImages = false;
+    }
+    if (source !== undefined && !visionModeEnabled) {
+        if (value.tool !== false)
+            overrides.tool = false;
+        if (value.instantDescribe !== false)
+            overrides.instantDescribe = false;
+        if (value.autoActivateOnImage !== false) {
+            overrides.autoActivateOnImage = false;
+        }
+        if (value.structuredVisionBootstrap !== false) {
+            overrides.structuredVisionBootstrap = false;
+        }
+    }
+    return Object.freeze({
+        ownership,
+        visionModeEnabled,
+        participates: source !== undefined,
+        preserveRawImages,
+        rewriteCurrentImages,
+        allowStructuredBootstrap,
+        allowGenericAutoMount,
+        surface,
+        legacyConfigOverrides: Object.freeze(overrides),
+    });
+}