@anionex/dsh-vision-toolkit 0.1.37 → 0.1.39

package/src/evidence-cache.ts

@@ -0,0 +1,418 @@
+/** Durable, Session-scoped cache for image descriptions used by model variants. */
+
+import { createHash } from 'node:crypto'
+import type { Context, Fiber } from '@deepseek-ai/cordis'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+import type { KvTable } from '@deepseek-ai/dsh-storage-domain'
+import { z } from 'zod'
+import type { ResolvedVisionToolkitConfig } from './config.ts'
+import { UPSTREAM_COMMIT } from './version.ts'
+
+/** 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),
+})
+
+type EvidenceRecord = z.infer<typeof evidenceRecordSchema>
+type EvidenceRecordKey = string & { readonly __evidenceRecordKey: unique symbol }
+
+/** 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<EvidenceRecordKey, string>(z.string().max(MAX_SCHEMA_RECORD_CHARS)),
+  },
+})
+
+/** Stable metadata for one description lookup. Raw focus prompts are never persisted. */
+export interface EvidenceCacheKey {
+  readonly digest: string
+  readonly contractVersion: number
+  readonly sessionId?: string
+  readonly sessionCreatedAt?: number
+  readonly sessionCwd?: string
+  readonly attachmentId: string
+  readonly promptHash: string
+  readonly runtimeHash: string
+}
+
+/** Optional durable layer behind the process-local promise/LRU cache. */
+export interface EvidencePersistence {
+  read(key: EvidenceCacheKey): Promise<ContentBlock | undefined>
+  write(key: EvidenceCacheKey, block: ContentBlock): Promise<void>
+}
+
+function hash(value: string): string {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+/** Fingerprint every runtime setting that can change the generated description. */
+export function evidenceRuntimeFingerprint(
+  config: ResolvedVisionToolkitConfig,
+  credentialSha256?: string,
+  sslVerify?: string,
+): string {
+  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: {
+  sessionId?: string
+  sessionIdentity?: SessionIdentity
+  attachmentId: string
+  prompt: string
+  runtimeHash: string
+}): EvidenceCacheKey {
+  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 {
+  private readonly entries = new Map<string, Promise<ContentBlock>>()
+
+  constructor(
+    private readonly limit: number,
+    private readonly persistence?: EvidencePersistence,
+  ) {}
+
+  /** Read a memory/durable hit or compute and persist one model-visible result. */
+  read(key: string | EvidenceCacheKey, load: () => Promise<ContentBlock>): Promise<ContentBlock> {
+    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 (): Promise<ContentBlock> => {
+      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: unknown) => {
+        // 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(): void {
+    this.entries.clear()
+  }
+}
+
+interface StorageBinding {
+  table: KvTable<EvidenceRecordKey, string>
+}
+
+interface SessionIdentity {
+  createdAt: number
+  cwd?: string
+}
+
+export interface SessionEvidenceStoreOptions {
+  maxEntries?: number
+  maxBytes?: number
+  maxEntryBytes?: number
+  now?: () => number
+}
+
+function identityOf(header: SessionHeader): SessionIdentity {
+  return Object.freeze({
+    createdAt: header.createdAt,
+    ...(header.cwd === undefined ? {} : { cwd: header.cwd }),
+  })
+}
+
+function sameIdentity(record: EvidenceRecord, header: SessionHeader): boolean {
+  return record.session.createdAt === header.createdAt && record.session.cwd === header.cwd
+}
+
+function matchesKey(record: EvidenceRecord, key: EvidenceCacheKey): boolean {
+  return record.contractVersion === key.contractVersion
+    && record.sessionId === key.sessionId
+    && record.attachmentId === key.attachmentId
+    && record.promptHash === key.promptHash
+    && record.runtimeHash === key.runtimeHash
+}
+
+function byteLength(text: string): number {
+  return Buffer.byteLength(text, 'utf8')
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function parseRecord(value: string): EvidenceRecord | undefined {
+  try {
+    const parsed: unknown = 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 implements EvidencePersistence {
+  private storage: StorageBinding | undefined
+  private storageFiber: (Fiber & PromiseLike<Fiber>) | undefined
+  private storageReady: Promise<void> | undefined
+  private mutationTail: Promise<void> = Promise.resolve()
+  private readonly flushes = new Map<string, Promise<boolean>>()
+  private warned = false
+  private readonly maxEntries: number
+  private readonly maxBytes: number
+  private readonly maxEntryBytes: number
+  private readonly now: () => number
+
+  constructor(
+    private readonly ctx: Context,
+    options: SessionEvidenceStoreOptions = {},
+  ) {
+    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: Context) => {
+      const domain = await storageCtx.storageDomain.open(evidenceCacheDomainSpec)
+      const binding: StorageBinding = { 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: unknown) => { this.warnOnce(error) },
+    )
+  }
+
+  /** Release the optional storage binding with the owning variant lifecycle. */
+  dispose(): void {
+    const fiber = this.storageFiber
+    this.storageFiber = undefined
+    this.storageReady = undefined
+    if (fiber !== undefined) void fiber.dispose().catch(error => { this.warnOnce(error) })
+  }
+
+  async read(key: EvidenceCacheKey): Promise<ContentBlock | undefined> {
+    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 as EvidenceRecordKey)
+    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: EvidenceCacheKey, block: ContentBlock): Promise<void> {
+    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: EvidenceRecord = Object.freeze({
+        contractVersion: key.contractVersion,
+        sessionId: key.sessionId as string,
+        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 as EvidenceRecordKey, JSON.stringify(record))
+        await this.prune(binding.table)
+      })
+    } catch (error) {
+      this.warnOnce(error)
+    }
+  }
+
+  private sessionFor(key: EvidenceCacheKey): ReturnType<Context['sessions']['get']> {
+    if (key.sessionId === undefined) return undefined
+    const session = this.ctx.sessions.get(key.sessionId as SessionId)
+    if (session === undefined) return undefined
+    if (key.sessionCreatedAt !== undefined
+      && (session.header.createdAt !== key.sessionCreatedAt || session.header.cwd !== key.sessionCwd)) {
+      return undefined
+    }
+    return session
+  }
+
+  private async prepareStorage(): Promise<StorageBinding | undefined> {
+    if (this.storage !== undefined) return this.storage
+    if (this.ctx.get('storageDomain') === undefined) return undefined
+    await this.storageReady
+    return this.storage
+  }
+
+  private enqueueMutation(operation: () => Promise<void>): Promise<void> {
+    const result = this.mutationTail.then(operation)
+    this.mutationTail = result.then(() => undefined, () => undefined)
+    return result
+  }
+
+  private flushSession(session: NonNullable<ReturnType<Context['sessions']['get']>>): Promise<boolean> {
+    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
+  }
+
+  private async prune(table: KvTable<EvidenceRecordKey, string>): Promise<void> {
+    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
+      }
+    }
+  }
+
+  private warnOnce(error: unknown): void {
+    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),
+    )
+  }
+}

package/src/image-input-variants.ts

@@ -29,8 +29,15 @@ import type {
 import type {} from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-attachment'
 import type { ResolvedVisionToolkitConfig } from './config.ts'
+import {
+  createEvidenceCacheKey,
+  EvidenceCache,
+  SessionEvidenceStore,
+} from './evidence-cache.ts'
 import { sessionPasteRoot, type PasteSelectionQuery, type PasteVerdict } from './paste-images.ts'
-import type { VisionToolkitRuntime } from './runtime.ts'
+import type { CapturedEvidenceRuntime, VisionToolkitRuntime } from './runtime.ts'
+
+export { EvidenceCache } from './evidence-cache.ts'
 
 /** Provider-id prefix for the variant routes this plugin registers. */
 export const VARIANT_PROVIDER_PREFIX = 'vision-toolkit-'
@@ -189,69 +196,12 @@ function assistantMessageText(message: Message): string {
     .join('\n\n')
 }
 
-function cacheKey(attachmentId: string, prompt: string, sessionId?: string): string {
-  return `${sessionId ?? ''}\u0000${attachmentId}\u0000${prompt}`
-}
-
 function contentHasText(blocks: readonly ContentBlock[], text: string): boolean {
   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 {
-  private readonly entries = new Map<string, Promise<ContentBlock>>()
-
-  constructor(private readonly limit: number) {}
-
-  /**
-   * 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: string, load: () => Promise<{ ok: boolean; block: ContentBlock }>): Promise<ContentBlock> {
-    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: unknown) => {
-        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(): void {
-    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
@@ -379,30 +329,30 @@ function createLimiter(limit: number): <T>(task: () => Promise<T>, signal?: Abor
 
 /**
  * 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: Context,
-  runtime: () => VisionToolkitRuntime | undefined,
+  runtime: () => CapturedEvidenceRuntime | undefined,
   block: ImageBlock,
   query: string,
   sessionId?: string,
-): Promise<{ ok: boolean; block: ContentBlock }> {
+): Promise<ContentBlock> {
   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: string | undefined
   let pathEvidence = ''
@@ -416,10 +366,7 @@ async function readImageBlock(
     // 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
@@ -430,14 +377,11 @@ async function readImageBlock(
     )
     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 {
     if (temporaryDirectory !== undefined) {
@@ -451,21 +395,30 @@ async function readImageBlock(
  * 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: Context,
-  runtime: () => VisionToolkitRuntime | undefined,
+  runtime: () => CapturedEvidenceRuntime | undefined,
   cache: EvidenceCache,
   messages: readonly Message[],
   signal?: AbortSignal,
   sessionId?: string,
+  runtimeHash = 'process-only-runtime',
 ): Promise<Message[]> {
+  const session = sessionId === undefined ? undefined : ctx.sessions.get(sessionId as never)
+  const sessionIdentity = session === undefined
+    ? undefined
+    : {
+        createdAt: session.header.createdAt,
+        ...(session.header.cwd === undefined ? {} : { cwd: session.header.cwd }),
+      }
   const plans: Array<{ message: Message; query?: string }> = []
   let lastUserText = ''
   let lastAssistantText = ''
@@ -507,7 +460,13 @@ export async function convertImagesToEvidence(
     if (query === undefined) return message
     const content = await convertBlocks(message.content, (block) => abortableWait(
       limit(
-        () => cache.read(cacheKey(String(block.attachment.attachmentId), query, sessionId), () =>
+        () => cache.read(createEvidenceCacheKey({
+          ...(sessionId === undefined ? {} : { sessionId }),
+          ...(sessionIdentity === undefined ? {} : { sessionIdentity }),
+          attachmentId: String(block.attachment.attachmentId),
+          prompt: query,
+          runtimeHash,
+        }), () =>
           readImageBlock(ctx, runtime, block, query, sessionId)),
         signal,
       ),
@@ -537,8 +496,6 @@ export async function convertImagesToEvidence(
  * retry policy, and replay handling still apply).
  */
 export class ImageInputVariantAdapter extends LlmAdapter {
-  private lastRuntime: VisionToolkitRuntime | undefined
-
   constructor(
     private readonly ctx: Context,
     private readonly llm: LlmService,
@@ -594,20 +551,29 @@ export class ImageInputVariantAdapter extends LlmAdapter {
   }
 
   override async *stream(options: GenerateOptions): AsyncGenerator<StreamChunk> {
-    // 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: CapturedEvidenceRuntime | undefined
+    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,
+      () => 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.
@@ -844,6 +810,8 @@ export function installImageInputVariants(
   getConfig: () => ResolvedVisionToolkitConfig,
   getRuntime: () => VisionToolkitRuntime | undefined,
 ): { dispose: () => void; reconcile: () => void } {
+  const evidenceStore = new SessionEvidenceStore(ctx)
+  const evidenceCache = new EvidenceCache(EVIDENCE_CACHE_LIMIT, evidenceStore)
   const registrations = new Map<string, () => void>()
   // The host snapshots adapter provider metadata (including the group display
   // name) at registration time, so a transparent-routing toggle must rebuild
@@ -975,7 +943,7 @@ export function installImageInputVariants(
               upstream,
               provider.name,
               getRuntime,
-              new EvidenceCache(EVIDENCE_CACHE_LIMIT),
+              evidenceCache,
               () => getConfig().imageInputVariants.hidden,
             ),
           )
@@ -1007,6 +975,7 @@ export function installImageInputVariants(
       disposed = true
       clearInterval(timer)
       releaseAll()
+      evidenceStore.dispose()
     },
     reconcile: () => { sweep() },
   }