dsh-vision-router 2.3.0 → 3.0.1

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-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),
+    });
+}

package/lib/session-surface-policy.js

@@ -1,117 +1,8 @@
 import { currentSessionVisionPolicy } from './native-image-coexistence.js'
 import { currentSessionVisionModeAuthority } from './session-vision-mode-authority.js'
+import { resolveSessionSurfacePolicy } from './session-surface-policy-domain.js'
 
-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 isObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-}
-
-function normalizedOwnership(policy) {
-  if (!isObject(policy)) return undefined
-  return KNOWN_OWNERSHIP.has(policy.ownership) ? policy.ownership : OWNERSHIP.UNKNOWN
-}
-
-/**
- * Resolve one immutable, read-only snapshot of the Vision Router capability
- * surface for the current session.
- *
- * Image ownership and Vision-mode authority are intentionally distinct. The
- * native-image policy answers who can consume raw pixels; the mode authority
- * answers whether this Session explicitly selected a Vision Router-owned
- * wrapper/twin for the current step. Only the latter can grant plugin tools or
- * automatic visual work. This prevents a historical image, a native multimodal
- * source model, or a stale request header from silently turning Vision back on.
- *
- * Durable transcript invariant: once a real session policy exists, Core may
- * observe/index image blocks but may never replace a user-owned image message
- * before the Agent loop appends it to the Session log. Image projection belongs
- * at the adapter/request boundary. The historical `rewriteCurrentImages` bit is
- * therefore intentionally ignored even when an older policy producer still
- * exposes it; the compatibility field below is permanently false.
- */
-export function resolveSessionSurfacePolicy({
-  visionPolicy,
-  visionModeAuthority,
-  config = {},
-  schemaBootstrapping = false,
-} = {}) {
-  const source = isObject(visionPolicy) ? visionPolicy : undefined
-  const authority = isObject(visionModeAuthority) ? visionModeAuthority : undefined
-  const value = isObject(config) ? config : {}
-  const ownership = normalizedOwnership(source)
-  const pluginOwned = ownership === OWNERSHIP.PLUGIN_OWNED
-
-  // During schema bootstrap there is no real Session policy, so global Settings
-  // still decide which definitions Core registers. During a real step, an
-  // explicit authority snapshot wins; direct helper callers fall back to the
-  // already-classified plugin ownership instead of inventing an enabled mode.
-  const visionModeEnabled = authority !== undefined
-    ? authority.enabled === true
-    : source === undefined
-      ? true
-      : pluginOwned
-
-  // No active session policy means no session-specific preservation authority.
-  // During a real pre-step, every ownership result — including explicit
-  // text-only and unknown — preserves the durable user message unchanged.
-  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
-  }
-  // Core's historical rewriteImages switch controls an agent/pre-step message
-  // transform. Disable it for every real session policy so neither current nor
-  // historical user image blocks can be persisted as internal attachment text.
-  // Vision Router-owned adapters still perform their private request projection.
-  if (source !== undefined && value.rewriteImages !== false) overrides.rewriteImages = false
-
-  // The composer/model selection is the Session authority. When it is OFF,
-  // suppress every automatic/plugin-owned visual surface while preserving the
-  // durable image itself. Settings remain unchanged; these are turn-local Core
-  // projections only.
-  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),
-  })
-}
+export { resolveSessionSurfacePolicy } from './session-surface-policy-domain.js'
 
 /** Read the turn-local ownership + mode snapshots and resolve the Core surface. */
 export function currentSessionSurfacePolicy(config = {}, options = {}) {

package/lib/session-turn-resolver.js

@@ -1,10 +1,6 @@
 function projectionServiceOf(ctx) {
-  try {
-    const service = ctx?.sessionProjections
-    if (service && typeof service.stateOf === 'function') return service
-  } catch {
-    // Some compatibility contexts expose services only through get().
-  }
+  // sessionProjections is optional here; probing the Cordis service property
+  // outside inject() would turn this reader into a hard pending dependency.
   try {
     const service = ctx?.get?.('sessionProjections')
     return service && typeof service.stateOf === 'function' ? service : undefined