dsh-vision-router 2.2.8 → 3.0.0

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

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