@anionex/dsh-vision-toolkit 0.1.37 → 0.1.38

package/lib/evidence-cache.js

@@ -0,0 +1,350 @@
+/** Durable, Session-scoped cache for image descriptions used by model variants. */
+import { createHash } from 'node:crypto';
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+import { z } from 'zod';
+import { UPSTREAM_COMMIT } from "./version.js";
+/** Bump only when the model-visible evidence contract changes incompatibly. */
+export const EVIDENCE_CONTRACT_VERSION = 1;
+/** Persistent cache bounds keep the Profile storage proportional and predictable. */
+const DEFAULT_PERSISTED_ENTRY_LIMIT = 512;
+const DEFAULT_PERSISTED_BYTE_LIMIT = 8 * 1024 * 1024;
+const DEFAULT_PERSISTED_ENTRY_BYTE_LIMIT = 64 * 1024;
+const MAX_SCHEMA_TEXT_CHARS = 256 * 1024;
+const MAX_SCHEMA_RECORD_CHARS = 512 * 1024;
+const hexDigestSchema = z.string().regex(/^[0-9a-f]{64}$/u);
+const sessionIdentitySchema = z.object({
+    createdAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    cwd: z.string().optional(),
+});
+const evidenceRecordSchema = z.object({
+    contractVersion: z.number().int().nonnegative(),
+    sessionId: z.string().min(1),
+    session: sessionIdentitySchema,
+    attachmentId: z.string().min(1),
+    promptHash: hexDigestSchema,
+    runtimeHash: hexDigestSchema,
+    text: z.string().min(1).max(MAX_SCHEMA_TEXT_CHARS),
+    storedAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+});
+/** Plugin-owned sidecar domain; the host backend handles atomicity and file safety. */
+export const evidenceCacheDomainSpec = defineDomain({
+    name: 'vision_toolkit_evidence',
+    version: 0,
+    tables: {
+        // Keep the durable boundary tolerant of one damaged cache payload: each
+        // record is parsed and validated independently below, so corruption causes
+        // a miss instead of preventing the entire optional domain from opening.
+        evidence: domainTable(z.string().max(MAX_SCHEMA_RECORD_CHARS)),
+    },
+});
+function hash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+/** Fingerprint every runtime setting that can change the generated description. */
+export function evidenceRuntimeFingerprint(config, credentialSha256, sslVerify) {
+    return hash(JSON.stringify({
+        upstreamCommit: UPSTREAM_COMMIT,
+        provider: {
+            baseUrl: config.provider.baseUrl,
+            credential: {
+                ref: String(config.provider.credential),
+                sha256: credentialSha256 ?? null,
+            },
+            model: config.provider.model,
+            protocol: config.provider.protocol,
+            anthropicThinking: config.provider.anthropicThinking,
+            sslVerify: sslVerify ?? null,
+            userAgent: config.provider.userAgent,
+        },
+        language: config.language,
+        timeoutMs: config.timeoutMs,
+        concurrency: config.concurrency,
+        maxImageBytes: config.maxImageBytes,
+        maxImagePixels: config.maxImagePixels,
+        runtime: config.runtime,
+    }));
+}
+/** Build a non-secret cache key from the Session, attachment, focus, and runtime contract. */
+export function createEvidenceCacheKey(input) {
+    const promptHash = hash(input.prompt);
+    const digest = hash(JSON.stringify([
+        EVIDENCE_CONTRACT_VERSION,
+        input.sessionId ?? '',
+        input.sessionIdentity?.createdAt ?? '',
+        input.sessionIdentity?.cwd ?? '',
+        input.attachmentId,
+        promptHash,
+        input.runtimeHash,
+    ]));
+    return Object.freeze({
+        digest,
+        contractVersion: EVIDENCE_CONTRACT_VERSION,
+        ...(input.sessionId === undefined ? {} : { sessionId: input.sessionId }),
+        ...(input.sessionIdentity === undefined ? {} : { sessionCreatedAt: input.sessionIdentity.createdAt }),
+        ...(input.sessionIdentity?.cwd === undefined ? {} : { sessionCwd: input.sessionIdentity.cwd }),
+        attachmentId: input.attachmentId,
+        promptHash,
+        runtimeHash: input.runtimeHash,
+    });
+}
+/** Bounded promise cache; concurrent readers join one load and rejected loads are evicted. */
+export class EvidenceCache {
+    limit;
+    persistence;
+    entries = new Map();
+    constructor(limit, persistence) {
+        this.limit = limit;
+        this.persistence = persistence;
+    }
+    /** Read a memory/durable hit or compute and persist one model-visible result. */
+    read(key, load) {
+        const memoryKey = typeof key === 'string' ? key : key.digest;
+        const existing = this.entries.get(memoryKey);
+        if (existing !== undefined) {
+            // Refresh recency: Map iteration order is insertion order.
+            this.entries.delete(memoryKey);
+            this.entries.set(memoryKey, existing);
+            return existing;
+        }
+        const pending = (async () => {
+            if (typeof key !== 'string' && this.persistence !== undefined) {
+                try {
+                    const persisted = await this.persistence.read(key);
+                    if (persisted !== undefined)
+                        return persisted;
+                }
+                catch {
+                    // Persistence is an optimization; a damaged/unavailable sidecar must
+                    // never block the model request from recomputing evidence.
+                }
+            }
+            const block = await load();
+            if (typeof key !== 'string' && this.persistence !== undefined) {
+                try {
+                    await this.persistence.write(key, block);
+                }
+                catch {
+                    // Keep the process-local result even when durability fails.
+                }
+            }
+            return block;
+        })().then(block => block, (error) => {
+            // Only evict our own entry: this promise may have been LRU-evicted and
+            // the key re-populated by a newer read meanwhile.
+            if (this.entries.get(memoryKey) === pending) {
+                this.entries.delete(memoryKey);
+            }
+            throw error;
+        });
+        this.entries.set(memoryKey, pending);
+        while (this.entries.size > this.limit) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+        return pending;
+    }
+    /** Drop process-local descriptions; durable rows stay versioned by their runtime fingerprint. */
+    clear() {
+        this.entries.clear();
+    }
+}
+function identityOf(header) {
+    return Object.freeze({
+        createdAt: header.createdAt,
+        ...(header.cwd === undefined ? {} : { cwd: header.cwd }),
+    });
+}
+function sameIdentity(record, header) {
+    return record.session.createdAt === header.createdAt && record.session.cwd === header.cwd;
+}
+function matchesKey(record, key) {
+    return record.contractVersion === key.contractVersion
+        && record.sessionId === key.sessionId
+        && record.attachmentId === key.attachmentId
+        && record.promptHash === key.promptHash
+        && record.runtimeHash === key.runtimeHash;
+}
+function byteLength(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function parseRecord(value) {
+    try {
+        const parsed = JSON.parse(value);
+        const result = evidenceRecordSchema.safeParse(parsed);
+        return result.success ? result.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Official DSH storage-domain sidecar used to survive Profile restarts. */
+export class SessionEvidenceStore {
+    ctx;
+    storage;
+    storageFiber;
+    storageReady;
+    mutationTail = Promise.resolve();
+    flushes = new Map();
+    warned = false;
+    maxEntries;
+    maxBytes;
+    maxEntryBytes;
+    now;
+    constructor(ctx, options = {}) {
+        this.ctx = ctx;
+        this.maxEntries = options.maxEntries ?? DEFAULT_PERSISTED_ENTRY_LIMIT;
+        this.maxBytes = options.maxBytes ?? DEFAULT_PERSISTED_BYTE_LIMIT;
+        this.maxEntryBytes = options.maxEntryBytes ?? DEFAULT_PERSISTED_ENTRY_BYTE_LIMIT;
+        this.now = options.now ?? Date.now;
+        if (typeof ctx.inject !== 'function')
+            return;
+        this.storageFiber = ctx.inject(['storageDomain'], async (storageCtx) => {
+            const domain = await storageCtx.storageDomain.open(evidenceCacheDomainSpec);
+            const binding = { table: domain.table('evidence') };
+            try {
+                await this.enqueueMutation(async () => { await this.prune(binding.table); });
+                this.storage = binding;
+            }
+            catch (error) {
+                await domain.close();
+                throw error;
+            }
+            return async () => {
+                if (this.storage === binding)
+                    this.storage = undefined;
+                await this.mutationTail;
+                await domain.close();
+            };
+        });
+        this.storageReady = Promise.resolve(this.storageFiber).then(() => undefined, (error) => { this.warnOnce(error); });
+    }
+    /** Release the optional storage binding with the owning variant lifecycle. */
+    dispose() {
+        const fiber = this.storageFiber;
+        this.storageFiber = undefined;
+        this.storageReady = undefined;
+        if (fiber !== undefined)
+            void fiber.dispose().catch(error => { this.warnOnce(error); });
+    }
+    async read(key) {
+        const session = this.sessionFor(key);
+        if (session === undefined)
+            return undefined;
+        const binding = await this.prepareStorage();
+        if (binding === undefined)
+            return undefined;
+        const stored = binding.table.get(key.digest);
+        const record = stored === undefined ? undefined : parseRecord(stored);
+        if (record === undefined || !matchesKey(record, key) || !sameIdentity(record, session.header)) {
+            return undefined;
+        }
+        if (byteLength(record.text) > this.maxEntryBytes)
+            return undefined;
+        return { type: 'text', text: record.text };
+    }
+    async write(key, block) {
+        if (block.type !== 'text' || block.text.length === 0 || byteLength(block.text) > this.maxEntryBytes)
+            return;
+        const session = this.sessionFor(key);
+        if (session === undefined)
+            return;
+        const binding = await this.prepareStorage();
+        if (binding === undefined)
+            return;
+        try {
+            const participated = await this.flushSession(session);
+            if (!participated)
+                return;
+            const record = Object.freeze({
+                contractVersion: key.contractVersion,
+                sessionId: key.sessionId,
+                session: identityOf(session.header),
+                attachmentId: key.attachmentId,
+                promptHash: key.promptHash,
+                runtimeHash: key.runtimeHash,
+                text: block.text,
+                storedAt: this.now(),
+            });
+            await this.enqueueMutation(async () => {
+                await binding.table.put(key.digest, JSON.stringify(record));
+                await this.prune(binding.table);
+            });
+        }
+        catch (error) {
+            this.warnOnce(error);
+        }
+    }
+    sessionFor(key) {
+        if (key.sessionId === undefined)
+            return undefined;
+        const session = this.ctx.sessions.get(key.sessionId);
+        if (session === undefined)
+            return undefined;
+        if (key.sessionCreatedAt !== undefined
+            && (session.header.createdAt !== key.sessionCreatedAt || session.header.cwd !== key.sessionCwd)) {
+            return undefined;
+        }
+        return session;
+    }
+    async prepareStorage() {
+        if (this.storage !== undefined)
+            return this.storage;
+        if (this.ctx.get('storageDomain') === undefined)
+            return undefined;
+        await this.storageReady;
+        return this.storage;
+    }
+    enqueueMutation(operation) {
+        const result = this.mutationTail.then(operation);
+        this.mutationTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    flushSession(session) {
+        const key = `${session.id}\u0000${session.header.createdAt}\u0000${session.header.cwd ?? ''}`;
+        const existing = this.flushes.get(key);
+        if (existing !== undefined)
+            return existing;
+        const pending = this.ctx.sessions.flush(session).finally(() => {
+            if (this.flushes.get(key) === pending)
+                this.flushes.delete(key);
+        });
+        this.flushes.set(key, pending);
+        return pending;
+    }
+    async prune(table) {
+        const records = [...table.entries()].map(([key, stored]) => {
+            const record = parseRecord(stored);
+            return {
+                key,
+                bytes: byteLength(stored),
+                storedAt: record?.storedAt ?? -1,
+                valid: record !== undefined && byteLength(record.text) <= this.maxEntryBytes,
+            };
+        });
+        let totalBytes = records.reduce((sum, record) => sum + record.bytes, 0);
+        let totalEntries = records.length;
+        records.sort((left, right) => Number(left.valid) - Number(right.valid)
+            || left.storedAt - right.storedAt
+            || left.key.localeCompare(right.key));
+        for (const record of records) {
+            if (record.valid && totalEntries <= this.maxEntries && totalBytes <= this.maxBytes)
+                break;
+            if (await table.delete(record.key)) {
+                totalEntries -= 1;
+                totalBytes -= record.bytes;
+            }
+        }
+    }
+    warnOnce(error) {
+        if (this.warned)
+            return;
+        this.warned = true;
+        this.ctx.logger?.warn('dsh-vision-toolkit: persistent image evidence cache is unavailable; using the process cache only. %s', messageOf(error).slice(0, 500));
+    }
+}
+//# sourceMappingURL=evidence-cache.js.map

package/lib/evidence-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-cache.js","sourceRoot":"","sources":["../src/evidence-cache.ts"],"names":[],"mappings":"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"}

package/lib/image-input-variants.js

@@ -13,7 +13,9 @@ import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { LlmAdapter, contentHasImage } from '@deepseek-ai/dsh-llm';
+import { createEvidenceCacheKey, EvidenceCache, SessionEvidenceStore, } from "./evidence-cache.js";
 import { sessionPasteRoot } from "./paste-images.js";
+export { EvidenceCache } from "./evidence-cache.js";
 /** Provider-id prefix for the variant routes this plugin registers. */
 export const VARIANT_PROVIDER_PREFIX = 'vision-toolkit-';
 /** Display suffix shared by variant provider names and variant model names. */
@@ -138,63 +140,10 @@ function assistantMessageText(message) {
         .filter(text => text.trim().length > 0)
         .join('\n\n');
 }
-function cacheKey(attachmentId, prompt, sessionId) {
-    return `${sessionId ?? ''}\u0000${attachmentId}\u0000${prompt}`;
-}
 function contentHasText(blocks, text) {
     return blocks.some(block => (block.type === 'text' && block.text === text)
         || (block.type === 'tool-result' && contentHasText(block.content, text)));
 }
-/** Bounded promise cache for one attachment's description; failed reads are not retained. */
-export class EvidenceCache {
-    limit;
-    entries = new Map();
-    constructor(limit) {
-        this.limit = limit;
-    }
-    /**
-     * Read one attachment-and-prompt key's entry or compute it. Concurrent readers join the in-flight
-     * computation; a settled failure is evicted so a fixed configuration gets a
-     * fresh chance.
-     * @param key - the attachment identity plus the exact focus prompt.
-     * @param load - computes the description; must resolve `{ ok, block }` and never reject.
-     * @returns the cached or computed block.
-     */
-    read(key, load) {
-        const existing = this.entries.get(key);
-        if (existing !== undefined) {
-            // Refresh recency: Map iteration order is insertion order.
-            this.entries.delete(key);
-            this.entries.set(key, existing);
-            return existing;
-        }
-        const pending = load().then((result) => {
-            // Only evict our own entry: this promise may have been LRU-evicted and
-            // the key re-populated by a newer read meanwhile.
-            if (!result.ok && this.entries.get(key) === pending) {
-                this.entries.delete(key);
-            }
-            return result.block;
-        }, (error) => {
-            if (this.entries.get(key) === pending) {
-                this.entries.delete(key);
-            }
-            throw error;
-        });
-        this.entries.set(key, pending);
-        while (this.entries.size > this.limit) {
-            const oldest = this.entries.keys().next().value;
-            if (oldest === undefined)
-                break;
-            this.entries.delete(oldest);
-        }
-        return pending;
-    }
-    /** Drop every cached description (runtime reconfiguration invalidates provider-specific reads). */
-    clear() {
-        this.entries.clear();
-    }
-}
 /**
  * Wait on a shared promise without inheriting its lifetime: the caller's
  * abort rejects this wait immediately, while the underlying read keeps
@@ -309,24 +258,24 @@ function createLimiter(limit) {
 }
 /**
  * Read one image block into a Vision Toolkit description text block. Never
- * throws: failures degrade to an explanatory block with `ok: false`, so the
- * caller can decide what a failure means (the cache refuses to memoize it).
+ * throws: failures become model-visible explanatory blocks and are cached like
+ * successful descriptions so replayed history stays byte-identical.
  * @param ctx - plugin context; reads the optional `attachments` service.
- * @param runtime - the currently serving Vision Toolkit runtime, if ready.
+ * @param runtime - the immutable runtime snapshot captured for this conversion.
  * @param block - the image block to describe.
  * @param query - the exact focus-hinted prompt sent to the vision model.
  * @param sessionId - the live Session identity, used to keep a model-visible copy.
- * @returns the outcome and its model-facing replacement block.
+ * @returns the model-facing replacement block.
  */
 async function readImageBlock(ctx, runtime, block, query, sessionId) {
     const attachments = ctx.get('attachments');
     const current = runtime();
     if (attachments === undefined) {
-        return { ok: false, block: { type: 'text', text: `${UNAVAILABLE_PREFIX}the DSH attachment service is not ready] The vision tool is temporarily unavailable; let the user know.` } };
+        return { type: 'text', text: `${UNAVAILABLE_PREFIX}the DSH attachment service is not ready] The vision tool is temporarily unavailable; let the user know.` };
     }
     const extension = MEDIA_EXTENSIONS[block.attachment.mediaType];
     if (extension === undefined) {
-        return { ok: false, block: { type: 'text', text: `${UNAVAILABLE_PREFIX}unsupported image media type ${block.attachment.mediaType}] The vision tool is temporarily unavailable; let the user know.` } };
+        return { type: 'text', text: `${UNAVAILABLE_PREFIX}unsupported image media type ${block.attachment.mediaType}] The vision tool is temporarily unavailable; let the user know.` };
     }
     let temporaryDirectory;
     let pathEvidence = '';
@@ -340,10 +289,7 @@ async function readImageBlock(ctx, runtime, block, query, sessionId) {
         // can still use the path with a later visual-tool call if the bridge is
         // temporarily unavailable on this turn.
         if (current === undefined) {
-            return {
-                ok: false,
-                block: { type: 'text', text: `${pathEvidence}${pathEvidence === '' ? '' : '\n'}${UNAVAILABLE_PREFIX}the Vision Toolkit runtime is not ready] The vision tool is temporarily unavailable; let the user know.` },
-            };
+            return { type: 'text', text: `${pathEvidence}${pathEvidence === '' ? '' : '\n'}${UNAVAILABLE_PREFIX}the Vision Toolkit runtime is not ready] The vision tool is temporarily unavailable; let the user know.` };
         }
         // A fresh signal on purpose: the cached run must not die with its first
         // caller (their abort used to cancel every concurrent joiner); the runtime
@@ -352,15 +298,12 @@ async function readImageBlock(ctx, runtime, block, query, sessionId) {
         const answer = result.answer.trim();
         if (answer.length === 0)
             throw new Error('the Vision Toolkit returned an empty description');
-        return { ok: true, block: { type: 'text', text: `${pathEvidence}${pathEvidence === '' ? '' : '\n'}${DESCRIPTION_PREFIX}${answer}` } };
+        return { type: 'text', text: `${pathEvidence}${pathEvidence === '' ? '' : '\n'}${DESCRIPTION_PREFIX}${answer}` };
     }
     catch (error) {
         return {
-            ok: false,
-            block: {
-                type: 'text',
-                text: `${pathEvidence}${pathEvidence === '' ? '' : '\n'}${UNAVAILABLE_PREFIX}${messageOf(error).slice(0, 300)}] The vision tool is temporarily unavailable; let the user know.`,
-            },
+            type: 'text',
+            text: `${pathEvidence}${pathEvidence === '' ? '' : '\n'}${UNAVAILABLE_PREFIX}${messageOf(error).slice(0, 300)}] The vision tool is temporarily unavailable; let the user know.`,
         };
     }
     finally {
@@ -374,14 +317,22 @@ async function readImageBlock(ctx, runtime, block, query, sessionId) {
  * The original messages are returned untouched when nothing carries an image;
  * converted messages are new objects, so the durable request stays immutable.
  * @param ctx - plugin context for the attachments service.
- * @param runtime - the currently serving runtime (lazily read per conversion).
- * @param cache - shared per-adapter description cache.
+ * @param runtime - the immutable runtime snapshot captured for this conversion.
+ * @param cache - shared process/durable description cache.
  * @param messages - the assembled request messages.
  * @param signal - the caller's cancellation for this conversion pass.
  * @param sessionId - the live Session identity, when available.
+ * @param runtimeHash - stable fingerprint of the vision provider and evidence runtime.
  * @returns the rewritten message list.
  */
-export async function convertImagesToEvidence(ctx, runtime, cache, messages, signal, sessionId) {
+export async function convertImagesToEvidence(ctx, runtime, cache, messages, signal, sessionId, runtimeHash = 'process-only-runtime') {
+    const session = sessionId === undefined ? undefined : ctx.sessions.get(sessionId);
+    const sessionIdentity = session === undefined
+        ? undefined
+        : {
+            createdAt: session.header.createdAt,
+            ...(session.header.cwd === undefined ? {} : { cwd: session.header.cwd }),
+        };
     const plans = [];
     let lastUserText = '';
     let lastAssistantText = '';
@@ -426,7 +377,13 @@ export async function convertImagesToEvidence(ctx, runtime, cache, messages, sig
     const converted = await Promise.all(plans.map(async ({ message, query }) => {
         if (query === undefined)
             return message;
-        const content = await convertBlocks(message.content, (block) => abortableWait(limit(() => cache.read(cacheKey(String(block.attachment.attachmentId), query, sessionId), () => readImageBlock(ctx, runtime, block, query, sessionId)), signal), signal));
+        const content = await convertBlocks(message.content, (block) => abortableWait(limit(() => cache.read(createEvidenceCacheKey({
+            ...(sessionId === undefined ? {} : { sessionId }),
+            ...(sessionIdentity === undefined ? {} : { sessionIdentity }),
+            attachmentId: String(block.attachment.attachmentId),
+            prompt: query,
+            runtimeHash,
+        }), () => readImageBlock(ctx, runtime, block, query, sessionId)), signal), signal));
         return { ...message, content };
     }));
     if (!messages.some(message => contentHasText(message.content, CHANNEL_NOTE))) {
@@ -456,7 +413,6 @@ export class ImageInputVariantAdapter extends LlmAdapter {
     runtime;
     cache;
     hidden;
-    lastRuntime;
     constructor(ctx, llm, upstream, upstreamName, runtime, cache, hidden = () => false) {
         super();
         this.ctx = ctx;
@@ -503,14 +459,23 @@ export class ImageInputVariantAdapter extends LlmAdapter {
         };
     }
     async *stream(options) {
-        // A reconfigured runtime is a NEW instance; descriptions read through the
-        // previous provider must not be replayed for the new one.
         const current = this.runtime();
-        if (current !== this.lastRuntime) {
-            this.cache.clear();
-            this.lastRuntime = current;
+        let captured;
+        if (current !== undefined && options.messages.some(message => contentHasImage(message.content))) {
+            try {
+                captured = await current.captureEvidenceRuntime();
+            }
+            catch (error) {
+                // Keep the established graceful-degradation path. The unavailable block
+                // is cached under this fallback fingerprint so historical replay stays
+                // stable; a later successful credential capture produces a different key.
+                captured = Object.freeze({
+                    evidenceFingerprint: current.evidenceFingerprint,
+                    glance: async () => { throw error; },
+                });
+            }
         }
-        const messages = await convertImagesToEvidence(this.ctx, this.runtime, this.cache, options.messages, options.signal, options.sessionId === undefined ? undefined : String(options.sessionId));
+        const messages = await convertImagesToEvidence(this.ctx, () => captured, this.cache, options.messages, options.signal, options.sessionId === undefined ? undefined : String(options.sessionId), captured?.evidenceFingerprint ?? 'process-only-runtime');
         // Delegate through the host service under the upstream route: the variant
         // is a wire-only facade, and the upstream route owns retry and replay.
         yield* this.llm.stream({ ...options, provider: this.upstream, messages });
@@ -739,6 +704,8 @@ export function createPasteTakeoverResolver(ctx, getConfig) {
  * @returns the disposer and a manual re-sweep trigger (settings changes).
  */
 export function installImageInputVariants(ctx, getConfig, getRuntime) {
+    const evidenceStore = new SessionEvidenceStore(ctx);
+    const evidenceCache = new EvidenceCache(EVIDENCE_CACHE_LIMIT, evidenceStore);
     const registrations = new Map();
     // The host snapshots adapter provider metadata (including the group display
     // name) at registration time, so a transparent-routing toggle must rebuild
@@ -868,7 +835,7 @@ export function installImageInputVariants(ctx, getConfig, getRuntime) {
                 if (disposed)
                     return;
                 try {
-                    const dispose = llm.registerAdapter([variantId], new ImageInputVariantAdapter(ctx, llm, upstream, provider.name, getRuntime, new EvidenceCache(EVIDENCE_CACHE_LIMIT), () => getConfig().imageInputVariants.hidden));
+                    const dispose = llm.registerAdapter([variantId], new ImageInputVariantAdapter(ctx, llm, upstream, provider.name, getRuntime, evidenceCache, () => getConfig().imageInputVariants.hidden));
                     registrations.set(upstream, dispose);
                     stale.delete(upstream);
                 }
@@ -894,6 +861,7 @@ export function installImageInputVariants(ctx, getConfig, getRuntime) {
             disposed = true;
             clearInterval(timer);
             releaseAll();
+            evidenceStore.dispose();
         },
         reconcile: () => { sweep(); },
     };