dsh-vision-router 2.3.0 → 3.0.0

package/lib/session-vision-attachment-index.js

@@ -0,0 +1,143 @@
+import { legacySessionEvents } from './session-event-history-compat.js';
+function propertyBag(value) {
+    return value !== null && (typeof value === 'object' || typeof value === 'function')
+        ? value
+        : undefined;
+}
+function weakKey(value) {
+    return value !== null && (typeof value === 'object' || typeof value === 'function')
+        ? value
+        : undefined;
+}
+function attachmentRef(value) {
+    return propertyBag(value) ? value : undefined;
+}
+function attachmentIdOf(ref) {
+    const record = propertyBag(ref);
+    return String(record?.attachmentId ?? record?.id);
+}
+function iterableValues(value) {
+    const iterator = propertyBag(value)?.[Symbol.iterator];
+    if (typeof iterator !== 'function') {
+        throw new TypeError('Session attachment collector returned a non-iterable result');
+    }
+    return value;
+}
+function boundedMessage(error) {
+    const record = propertyBag(error);
+    const text = record?.message ?? error;
+    return String(text ?? '').slice(0, 400);
+}
+/**
+ * Attachment access boundary for one SessionVisionStateStore.
+ *
+ * The state store remains the sole bounded storage owner. This boundary owns
+ * only cache access plus target-only cold recovery from the durable Session
+ * event source. Synchronous lookup never performs historical I/O.
+ */
+export function createSessionVisionAttachmentIndex({ stateStore, collectEventAttachmentRefs, readSessionLog, logger, }) {
+    const runtimeStore = stateStore;
+    const lookup = runtimeStore.lookupAttachment;
+    const primitiveLookup = typeof lookup === 'function'
+        ? (session, attachmentId) => lookup.call(stateStore, session, attachmentId)
+        : undefined;
+    const attachmentRecoveryWarnings = new WeakMap();
+    const recordAttachments = (session, refs) => {
+        if (!session || !Array.isArray(refs) || refs.length === 0)
+            return;
+        stateStore.recordAttachments(session, refs);
+    };
+    const lookupAttachment = (session, attachmentId) => {
+        if (primitiveLookup === undefined)
+            return undefined;
+        return primitiveLookup(session, attachmentId);
+    };
+    const recoverAttachmentsFromEvents = (session, ids, events) => {
+        const found = new Map();
+        if (!Array.isArray(events)
+            || events.length === 0
+            || typeof collectEventAttachmentRefs !== 'function') {
+            return found;
+        }
+        const wanted = new Set(ids);
+        const collected = collectEventAttachmentRefs(events);
+        for (const value of iterableValues(collected)) {
+            if (!value)
+                continue;
+            const ref = attachmentRef(value);
+            if (ref === undefined)
+                continue;
+            const id = attachmentIdOf(ref);
+            if (wanted.has(id) && !found.has(id))
+                found.set(id, ref);
+        }
+        if (found.size > 0)
+            stateStore.recordAttachments(session, [...found.values()]);
+        return found;
+    };
+    const warnAttachmentRecoveryFailure = (session, attachmentId, error) => {
+        const message = boundedMessage(error);
+        const warningKey = `${String(attachmentId)}:${message}`;
+        const key = weakKey(session);
+        if (key !== undefined && attachmentRecoveryWarnings.get(key) === warningKey)
+            return;
+        if (key !== undefined)
+            attachmentRecoveryWarnings.set(key, warningKey);
+        logger?.warn?.('vision-router: session attachment recovery failed id=%s error=%s', String(attachmentId), message);
+    };
+    const resolveAttachments = async (session, attachmentIds) => {
+        const requested = [
+            ...new Set((Array.isArray(attachmentIds) ? attachmentIds : []).map((id) => String(id))),
+        ];
+        const resolved = new Map();
+        const missing = [];
+        for (const id of requested) {
+            const cached = lookupAttachment(session, id);
+            if (cached !== undefined)
+                resolved.set(id, cached);
+            else
+                missing.push(id);
+        }
+        if (missing.length === 0 || session === undefined)
+            return resolved;
+        let events;
+        if (typeof readSessionLog === 'function') {
+            let result;
+            try {
+                result = await readSessionLog(session);
+            }
+            catch (error) {
+                warnAttachmentRecoveryFailure(session, missing[0], error);
+                return resolved;
+            }
+            const resultRecord = propertyBag(result);
+            if (resultRecord?.supported === true) {
+                const key = weakKey(session);
+                if (key !== undefined)
+                    attachmentRecoveryWarnings.delete(key);
+                events = resultRecord.events;
+            }
+            else if (resultRecord?.supported !== false) {
+                warnAttachmentRecoveryFailure(session, missing[0], new Error('Session log reader returned an invalid capability result'));
+                return resolved;
+            }
+        }
+        // Explicitly unsupported SessionQuery keeps the released Session-local
+        // compatibility fallback. Advertised reader failures above never fall back.
+        if (events === undefined)
+            events = legacySessionEvents(session);
+        const recovered = recoverAttachmentsFromEvents(session, missing, events);
+        for (const [id, ref] of recovered)
+            resolved.set(id, ref);
+        return resolved;
+    };
+    const resolveAttachment = async (session, attachmentId) => {
+        return (await resolveAttachments(session, [attachmentId])).get(String(attachmentId));
+    };
+    return Object.freeze({
+        recordAttachments,
+        lookupAttachment,
+        resolveAttachment,
+        resolveAttachments,
+    });
+}

package/lib/session-vision-delegation-boundary.js

@@ -0,0 +1,34 @@
+import { materializeDelegatedSessionVisionPolicy, } from './session-vision-delegation.js';
+/**
+ * Materialize inherited DVR authority for exact runtime-owned child Agents.
+ *
+ * DSH awaits serial `agent/created` listeners before releasing queued work,
+ * so the snapshot is durable before the child can assemble its first prompt.
+ * Runtime ownership is revalidated with `agents.isOwnedBy`; ambient initiator
+ * presence alone is never treated as delegation authority.
+ */
+export function installSessionVisionDelegationBoundary(ctx, store, resolveParentAuthority) {
+    const currentInitiator = ctx.agents?.currentInitiator;
+    const isOwnedBy = ctx.agents?.isOwnedBy;
+    const on = ctx.on;
+    if (typeof currentInitiator !== 'function'
+        || typeof isOwnedBy !== 'function'
+        || typeof on !== 'function') {
+        return false;
+    }
+    on.call(ctx, 'agent/created', async ({ agent: child }) => {
+        if (typeof store.hydrate === 'function') {
+            await store.hydrate(child.id);
+        }
+        const parent = currentInitiator.call(ctx.agents);
+        if (parent === undefined || parent.id === child.id)
+            return;
+        if (!isOwnedBy.call(ctx.agents, child.id, parent))
+            return;
+        if (typeof store.hydrate === 'function') {
+            await store.hydrate(parent.id);
+        }
+        await materializeDelegatedSessionVisionPolicy(store, parent, child, resolveParentAuthority);
+    });
+    return true;
+}

package/lib/session-vision-delegation.js

@@ -0,0 +1,22 @@
+import { delegatedSessionVisionPolicy, } from './session-vision-policy.js';
+/**
+ * Materialize one child-local DVR policy snapshot at the delegation boundary.
+ *
+ * Child-local durable truth wins when it already exists. Otherwise the direct
+ * parent's durable policy wins over route-derived compatibility authority, and
+ * the resulting enabled bit is copied into the child as a delegation snapshot.
+ * Later parent changes therefore cannot retroactively mutate an existing child.
+ */
+export async function materializeDelegatedSessionVisionPolicy(store, parent, child, resolveParentAuthority) {
+    if (parent.id === child.id) {
+        throw new TypeError('Session Vision delegation requires distinct parent and child ids');
+    }
+    const existing = store.get(child.id);
+    if (existing !== undefined) {
+        return Object.freeze({ status: 'existing', policy: existing });
+    }
+    const parentPolicy = store.get(parent.id);
+    const enabled = parentPolicy?.enabled ?? resolveParentAuthority(parent).enabled;
+    const policy = await store.set(child.id, delegatedSessionVisionPolicy(enabled, parent.id));
+    return Object.freeze({ status: 'materialized', policy });
+}

package/lib/session-vision-index.js

@@ -1,6 +1,8 @@
 import { currentSessionSurfacePolicy } from './session-surface-policy.js'
 import { sessionSurfaceReplacementIntent } from './session-surface-compat.js'
 import { createSessionVisionStateStore } from './session-vision-state.js'
+import { legacySessionEvents } from './session-event-history-compat.js'
+import { createSessionVisionAttachmentIndex } from './session-vision-attachment-index.js'
 
 const MAX_PENDING_REPAIR_EVENTS = 256
 const MAX_REPAIR_OVERFLOW_RANGES = 32
@@ -11,21 +13,6 @@ function isObject(value) {
   return value !== null && typeof value === 'object'
 }
 
-function legacySessionEvents(session) {
-  try {
-    // dsh 0.1.2-alpha.4 removed the bare `session.events` array in favor of
-    // `session.snapshotEvents()`; both are handled so one build runs on both
-    // harness generations.
-    if (session && typeof session.snapshotEvents === 'function') {
-      const events = session.snapshotEvents()
-      return Array.isArray(events) ? events : undefined
-    }
-    return Array.isArray(session?.events) ? session.events : undefined
-  } catch {
-    return undefined
-  }
-}
-
 function surfaceNodes(session) {
   try {
     return Array.isArray(session?.surface?.nodes) ? session.surface.nodes : undefined
@@ -52,9 +39,10 @@ function isReplacementEvent(event) {
 /**
  * Session visual data-plane index.
  *
- * SessionVisionStateStore remains the bounded storage owner. This object owns
- * target-only durable attachment recovery, event-feed-backed tool-result image
- * surface repair and expired structured guard-stop surface repair.
+ * SessionVisionStateStore remains the bounded storage owner. Attachment cache
+ * access and target-only durable recovery are delegated to one typed attachment
+ * index; this object owns event-feed-backed tool-result image surface repair and
+ * expired structured guard-stop surface repair.
  *
  * Supported DSH Hosts expose the post-commit `session/event` feed. Production
  * surface repair consumes only the exact frozen events observed on that feed;
@@ -83,9 +71,24 @@ export function createSessionVisionIndex({
   if (!store || typeof store !== 'object') {
     throw new TypeError('session vision index requires a state store')
   }
-  const primitiveLookup = typeof store.lookupAttachment === 'function'
-    ? store.lookupAttachment.bind(store)
-    : undefined
+  const attachmentIndex = createSessionVisionAttachmentIndex({
+    stateStore: store,
+    collectEventAttachmentRefs:
+      typeof core.collectEventAttachmentRefs === 'function'
+        ? (events) => core.collectEventAttachmentRefs(events)
+        : undefined,
+    readSessionLog,
+    logger,
+  })
+  const {
+    recordAttachments,
+    lookupAttachment,
+    resolveAttachment,
+    resolveAttachments,
+  } = attachmentIndex
+
+  // Surface repair/feed state remains owned by SessionVisionIndex. Attachment
+  // cache/recovery state lives exclusively in SessionVisionAttachmentIndex.
   const toolSurfaceScans = new WeakMap()
   const guardSurfaceScans = new WeakMap()
   const pendingToolRepairEvents = new WeakMap()
@@ -97,93 +100,8 @@ export function createSessionVisionIndex({
   const repairFeedOverflowWarnings = new WeakSet()
   const repairFeedObserverWarnings = new WeakMap()
   const surfaceFeedBackfills = new WeakMap()
-  const attachmentRecoveryWarnings = new WeakMap()
   let surfaceEventFeedActive = false
 
-  const recordAttachments = (session, refs) => {
-    if (!session || !Array.isArray(refs) || refs.length === 0) return
-    store.recordAttachments(session, refs)
-  }
-
-  // Synchronous lookup is cache-only. Projected short handles first warm this
-  // cache from current derived messages and must not trigger historical I/O.
-  const lookupAttachment = (session, id) => {
-    if (!primitiveLookup) return undefined
-    return primitiveLookup(session, id)
-  }
-
-  const recoverAttachmentsFromEvents = (session, ids, events) => {
-    const found = new Map()
-    if (!Array.isArray(events) || events.length === 0 || typeof core.collectEventAttachmentRefs !== 'function') {
-      return found
-    }
-    const wanted = new Set(ids.map((id) => String(id)))
-    for (const ref of core.collectEventAttachmentRefs(events)) {
-      if (!ref) continue
-      const id = String(ref.attachmentId ?? ref.id)
-      if (wanted.has(id) && !found.has(id)) found.set(id, ref)
-    }
-    if (found.size > 0) store.recordAttachments(session, [...found.values()])
-    return found
-  }
-
-  const warnAttachmentRecoveryFailure = (session, id, error) => {
-    const message = boundedMessage(error)
-    const key = `${String(id)}:${message}`
-    if (attachmentRecoveryWarnings.get(session) === key) return
-    attachmentRecoveryWarnings.set(session, key)
-    logger?.warn?.(
-      'vision-router: session attachment recovery failed id=%s error=%s',
-      String(id),
-      message,
-    )
-  }
-
-  const resolveAttachments = async (session, ids) => {
-    const requested = [...new Set((Array.isArray(ids) ? ids : []).map((id) => String(id)))]
-    const resolved = new Map()
-    const missing = []
-    for (const id of requested) {
-      const cached = lookupAttachment(session, id)
-      if (cached !== undefined) resolved.set(id, cached)
-      else missing.push(id)
-    }
-    if (missing.length === 0 || session === undefined) return resolved
-
-    let events
-    if (typeof readSessionLog === 'function') {
-      let result
-      try {
-        result = await readSessionLog(session)
-      } catch (error) {
-        warnAttachmentRecoveryFailure(session, missing[0], error)
-        return resolved
-      }
-      if (result?.supported === true) {
-        attachmentRecoveryWarnings.delete(session)
-        events = result.events
-      } else if (result?.supported !== false) {
-        warnAttachmentRecoveryFailure(
-          session,
-          missing[0],
-          new Error('Session log reader returned an invalid capability result'),
-        )
-        return resolved
-      }
-    }
-
-    // Historical/partial Hosts without SessionQuery keep the released fallback.
-    // Public rc8+ Hosts use readSessionLog above and never touch sync history.
-    if (events === undefined) events = legacySessionEvents(session)
-    const recovered = recoverAttachmentsFromEvents(session, missing, events)
-    for (const [id, ref] of recovered) resolved.set(id, ref)
-    return resolved
-  }
-
-  const resolveAttachment = async (session, id) => {
-    return (await resolveAttachments(session, [id])).get(String(id))
-  }
-
   const pendingSurfaceScan = (scans, session) => {
     if (!session) return undefined
     const nodes = surfaceNodes(session)
@@ -732,7 +650,7 @@ export function createSessionVisionIndex({
     if (typeof core.rewriteImageBlocks === 'function') {
       const found = core.rewriteImageBlocks(messages)
       if (Array.isArray(found?.attachments) && found.attachments.length > 0) {
-        store.recordAttachments(session, found.attachments)
+        recordAttachments(session, found.attachments)
       }
     }
     await ensureSurfaceEventFeedBackfill(session)