@mengruo/dsh-vision-toolkit 0.1.3 → 0.1.5

package/src/config.ts

@@ -77,6 +77,10 @@ export interface VisionProviderConfig {
   anthropicThinking?: 'omit' | 'disabled' | 'adaptive'
   /** Outbound User-Agent for provider requests and connection tests. */
   userAgent?: string
+  /** Whether to request a streamed (SSE) completion instead of one JSON response (default false). */
+  stream?: boolean
+  /** Whether to upload images to object storage and send the model a URL instead of base64 (default false). */
+  uploadViaUrl?: boolean
   /** t1: per-request hedge threshold in seconds. A single request exceeding t1 keeps running while the next provider starts in parallel. */
   t1Seconds?: number
   /** t2: per-provider cumulative cutoff in seconds. Total accumulated request time reaching t2 terminates the provider. */
@@ -106,6 +110,10 @@ export interface VisionToolkitConfig {
     anthropicThinking?: 'omit' | 'disabled' | 'adaptive'
     /** Outbound User-Agent for provider requests and connection tests. */
     userAgent?: string
+    /** Whether to request a streamed (SSE) completion instead of one JSON response (default false). */
+    stream?: boolean
+    /** Whether to upload images to object storage and send the model a URL instead of base64 (default false). */
+    uploadViaUrl?: boolean
   }
   /** Ordered online vision providers; array order is the failover priority. */
   providers?: VisionProviderConfig[]
@@ -123,6 +131,21 @@ export interface VisionToolkitConfig {
   maxImagePixels?: number
   /** Default per-model in-flight request cap inherited by providers that do not set their own. */
   concurrency?: number
+  /**
+   * Optional S3-compatible object storage used by the URL image-transfer path.
+   * `endpoint`, `bucket`, and `credential` are required to enable URL transfer;
+   * `publicBase` is optional and falls back to presigned URLs when unset.
+   */
+  objectStorage?: {
+    /** S3-compatible API endpoint (e.g. R2, MinIO, Tencent COS). */
+    endpoint?: string
+    /** Bucket name. */
+    bucket?: string
+    /** DSH Credential reference holding "accessKeyId:secretAccessKey". */
+    credential?: string
+    /** Public base URL (custom domain / r2.dev); when unset, presigned URLs are used. */
+    publicBase?: string
+  }
   runtime?: {
     /** `managed` uses the packaged snapshot and isolated venv; `external` uses a clean pinned checkout. */
     mode?: 'managed' | 'external'
@@ -131,6 +154,14 @@ export interface VisionToolkitConfig {
     /** Optional Python 3.11+ bootstrap/interpreter override. */
     python?: string
   }
+  /**
+   * Optional shared storage root. When set, every workspace gets an isolated,
+   * automatically generated child directory below this root instead of writing
+   * `.dsh-vision-toolkit` into the workspace.
+   */
+  storageDir?: string
+  /** Internal read-only history used to keep persisted paths valid after storage moves. */
+  storageHistory?: string[]
   /** Extra directories (besides the workspace) inputs may come from. */
   allowedDirs?: string[]
   /**
@@ -174,6 +205,7 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
     protocol: z.union(['openai', 'anthropic'] as const).default('openai'),
     anthropicThinking: z.union(['omit', 'disabled', 'adaptive'] as const).default('omit'),
     userAgent: z.string().default(DEFAULT_VISION_USER_AGENT),
+    stream: z.boolean().default(false),
   }),
   providers: z.array(z.object({
     name: z.string(),
@@ -185,6 +217,8 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
     protocol: z.union(['openai', 'anthropic'] as const).default('openai'),
     anthropicThinking: z.union(['omit', 'disabled', 'adaptive'] as const).default('omit'),
     userAgent: z.string(),
+    stream: z.boolean().default(false),
+    uploadViaUrl: z.boolean().default(false),
     t1Seconds: z.number(),
     t2Seconds: z.number(),
     maxImageBytes: z.number(),
@@ -199,11 +233,19 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
   maxImageBytes: z.number().default(4194304),
   maxImagePixels: z.number().default(20000000),
   concurrency: z.number().default(4),
+  objectStorage: z.object({
+    endpoint: z.string().default(''),
+    bucket: z.string().default(''),
+    credential: z.string().default(''),
+    publicBase: z.string().default(''),
+  }),
   runtime: z.object({
     mode: z.union(['managed', 'external'] as const).default('managed'),
     agentVisionToolkitPath: z.string(),
     python: z.string(),
   }),
+  storageDir: z.string(),
+  storageHistory: z.array(z.string()).default([]),
   allowedDirs: z.array(z.string()).default([]),
   imageInputVariants: z.object({
     enabled: z.boolean().default(true),
@@ -225,6 +267,8 @@ export interface ResolvedProvider {
   protocol: 'openai' | 'anthropic'
   anthropicThinking: 'omit' | 'disabled' | 'adaptive'
   userAgent: string
+  stream: boolean
+  uploadViaUrl: boolean
   t1Seconds: number
   t2Seconds: number
   maxImageBytes: number
@@ -242,6 +286,8 @@ export interface ResolvedVisionToolkitConfig {
     protocol: 'openai' | 'anthropic'
     anthropicThinking: 'omit' | 'disabled' | 'adaptive'
     userAgent: string
+    stream: boolean
+    uploadViaUrl: boolean
   }
   /** Ordered failover pool; array order is the priority, highest first. */
   providers: ResolvedProvider[]
@@ -252,11 +298,19 @@ export interface ResolvedVisionToolkitConfig {
   maxImageBytes: number
   maxImagePixels: number
   concurrency: number
+  objectStorage: {
+    endpoint: string
+    bucket: string
+    credential?: CredentialRef
+    publicBase?: string
+  }
   runtime: {
     mode: 'managed' | 'external'
     agentVisionToolkitPath?: string
     python?: string
   }
+  storageDir?: string
+  storageHistory: string[]
   allowedDirs: string[]
   imageInputVariants: {
     enabled: boolean
@@ -354,6 +408,8 @@ function resolveProvider(
   if (userAgent.length === 0) {
     throw new VisionToolkitError('config', `${label}.userAgent must not be empty`)
   }
+  const stream = input.stream === true
+  const uploadViaUrl = input.uploadViaUrl === true
   const t1Seconds = input.t1Seconds ?? 90
   if (!Number.isInteger(t1Seconds) || t1Seconds < 1 || t1Seconds > MAX_TIMEOUT_SECONDS) {
     throw new VisionToolkitError('config', `${label}.t1Seconds must be an integer between 1 and ${MAX_TIMEOUT_SECONDS}`)
@@ -390,6 +446,8 @@ function resolveProvider(
     protocol,
     anthropicThinking,
     userAgent,
+    stream,
+    uploadViaUrl,
     t1Seconds,
     t2Seconds,
     maxImageBytes,
@@ -455,7 +513,24 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
   if (python !== undefined && python.length === 0) {
     throw new VisionToolkitError('config', 'runtime.python must not be empty')
   }
+  const storageDir = config.storageDir?.trim()
+  const storageHistory = [...new Set((config.storageHistory ?? [])
+    .map(dir => dir.trim())
+    .filter(dir => dir.length > 0 && dir !== storageDir))]
   const allowedDirs = (config.allowedDirs ?? []).map(dir => dir.trim()).filter(dir => dir.length > 0)
+  const objectStorageInput = config.objectStorage ?? {}
+  const objectStorageEndpoint = objectStorageInput.endpoint?.trim() ?? ''
+  const objectStorageBucket = objectStorageInput.bucket?.trim() ?? ''
+  const objectStoragePublicBase = objectStorageInput.publicBase?.trim()
+  let objectStorageCredential: CredentialRef | undefined
+  const objectStorageCredentialSource = objectStorageInput.credential?.trim()
+  if (objectStorageCredentialSource !== undefined && objectStorageCredentialSource.length > 0) {
+    try {
+      objectStorageCredential = credentialRef(objectStorageCredentialSource)
+    } catch (error) {
+      throw new VisionToolkitError('config', `objectStorage.credential "${objectStorageCredentialSource}" is not a valid credential reference`, { cause: error })
+    }
+  }
   const imageInputVariants = config.imageInputVariants ?? {}
   const variantProviders = (imageInputVariants.providers ?? [])
     .map(provider => provider.trim())
@@ -478,6 +553,8 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
       protocol: primary.protocol,
       anthropicThinking: primary.anthropicThinking,
       userAgent: primary.userAgent,
+      stream: primary.stream,
+      uploadViaUrl: primary.uploadViaUrl,
     },
     providers,
     language,
@@ -487,11 +564,19 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
     maxImageBytes,
     maxImagePixels,
     concurrency,
+    objectStorage: {
+      endpoint: objectStorageEndpoint,
+      bucket: objectStorageBucket,
+      ...(objectStorageCredential === undefined ? {} : { credential: objectStorageCredential }),
+      ...(objectStoragePublicBase === undefined || objectStoragePublicBase.length === 0 ? {} : { publicBase: objectStoragePublicBase }),
+    },
     runtime: {
       mode,
       ...(toolkitPath !== undefined ? { agentVisionToolkitPath: toolkitPath } : {}),
       ...(python !== undefined ? { python } : {}),
     },
+    ...(storageDir === undefined || storageDir.length === 0 ? {} : { storageDir }),
+    storageHistory,
     allowedDirs,
     imageInputVariants: {
       enabled: imageInputVariants.enabled ?? true,
@@ -502,6 +587,49 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
   }
 }
 
+/** Merge prior storage roots into the next resolved generation's read-only history. */
+export function retainedStorageHistory(
+  next: VisionToolkitConfig,
+  previous: VisionToolkitConfig,
+): string[] {
+  const resolvedNext = resolveConfig(next)
+  const resolvedPrevious = resolveConfig(previous)
+  return [...new Set([
+    ...resolvedPrevious.storageHistory,
+    ...resolvedNext.storageHistory,
+    ...(resolvedPrevious.storageDir === undefined ? [] : [resolvedPrevious.storageDir]),
+  ])].filter(storageDir => storageDir !== resolvedNext.storageDir)
+}
+
+export interface WatchedSettingsGeneration {
+  /** Configuration to activate now; omitted after a successful history writeback. */
+  config?: VisionToolkitConfig
+  /** Whether the derived history still needs plugin-owned durable persistence. */
+  requiresDurableStorageHistory?: boolean
+  /** Non-fatal internal-history persistence error. */
+  persistenceError?: unknown
+}
+
+/** Prepare one live Settings generation without letting internal history writeback block activation. */
+export async function prepareWatchedSettingsGeneration(
+  next: VisionToolkitConfig,
+  previous: VisionToolkitConfig,
+  writable: boolean,
+  persistStorageHistory: (storageHistory: string[]) => Promise<void>,
+): Promise<WatchedSettingsGeneration> {
+  const storageHistory = retainedStorageHistory(next, previous)
+  if (JSON.stringify(storageHistory) === JSON.stringify(resolveConfig(next).storageHistory)) return { config: next }
+
+  const config = { ...next, storageHistory }
+  if (!writable) return { config, requiresDurableStorageHistory: true }
+  try {
+    await persistStorageHistory(storageHistory)
+    return {}
+  } catch (persistenceError) {
+    return { config, requiresDurableStorageHistory: true, persistenceError }
+  }
+}
+
 /** Whether a resolved provider should use the bundled public key instead of DSH credentials. */
 export function isBuiltInFreeVisionProvider(provider: ResolvedVisionToolkitConfig['provider']): boolean {
   return String(provider.credential) === BUILT_IN_FREE_VISION_CREDENTIAL

package/src/errors.ts

@@ -5,18 +5,41 @@
  * @module dsh-vision-toolkit/errors
  */
 
-/** Discriminant tag for every Vision Toolkit failure. */
+/**
+ * Discriminant tag for every Vision Toolkit failure.
+ *
+ * The remote vision-provider failures are split by a machine-routable taxonomy
+ * so the failover loop can decide, per error, whether to retry the SAME
+ * provider or advance to the next one:
+ *
+ * - `auth`           401/403 — credential is wrong or unauthorized. Never retry.
+ * - `quota`          402 — account out of quota/unpaid. Never retry.
+ * - `rate_limit`     429 — throttled. Park and revisit, never retry in place.
+ * - `server`         5xx — transient provider fault. Worth a same-provider retry.
+ * - `network`        connection refused / DNS / socket — transient. Worth a retry.
+ * - `region`         provider unavailable in this region. Never retry.
+ * - `tos`            rejected by content/safety policy. Never retry.
+ * - `invalid_request` 400/404/422 — bad request or unknown model. Never retry.
+ * - `service`        fallback for unclassifiable remote failures. Never retry.
+ */
 export const VISION_TOOLKIT_ERROR_CODES = [
   'config',
   'input',
   'capacity',
+  'auth',
+  'quota',
+  'rate_limit',
+  'server',
+  'network',
+  'region',
+  'tos',
+  'invalid_request',
   'service',
   'runtime',
   'output',
   'timeout',
   'cancelled',
   'path',
-  'rate_limit',
 ] as const
 
 /** Stable machine-readable error category. */

package/src/evidence-cache.ts

@@ -73,7 +73,7 @@ function hash(value: string): string {
   return createHash('sha256').update(value).digest('hex')
 }
 
-/** Fingerprint every runtime setting that can change the generated description. */
+/** Fingerprint every runtime setting that can change generated evidence or its embedded path. */
 export function evidenceRuntimeFingerprint(
   config: ResolvedVisionToolkitConfig,
   credentialSha256?: string,
@@ -115,6 +115,7 @@ export function evidenceRuntimeFingerprint(
     maxImageBytes: config.maxImageBytes,
     maxImagePixels: config.maxImagePixels,
     runtime: config.runtime,
+    storageDir: config.storageDir ?? null,
   }))
 }
 

package/src/exposure.ts

@@ -8,7 +8,7 @@
 
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import type { Session } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import { defineTool, type ToolDefinition } from '@deepseek-ai/dsh-tools'
 import type { Context } from '@deepseek-ai/cordis'
 import { VISION_SKILLS_CONTENT, VISION_SKILLS_NAME } from './skill.ts'
@@ -78,10 +78,24 @@ function isBundledSkillResult(value: unknown): boolean {
     && isBundledSkillContent(value.content)
 }
 
+/**
+ * Iterate a Session's durable event log across runtime lines. dsh 0.1.2-alpha
+ * replaced the `events` getter with `snapshotEvents()` (session-log-read-intent):
+ * iterating the removed `session.events` throws `session.events is not iterable`
+ * and takes down `agent/created` → session restore. Prefer the snapshot accessor
+ * and fall back to the legacy rc-line `events` getter so both lines work.
+ */
+function sessionEventLog(session: Session): readonly SessionEvent[] {
+  const snapshot = (session as { snapshotEvents?: () => readonly SessionEvent[] }).snapshotEvents
+  return typeof snapshot === 'function'
+    ? snapshot.call(session)
+    : (session as { events: readonly SessionEvent[] }).events
+}
+
 /** Whether durable history proves that this Session loaded the bundled Skill. */
 function hasLoadedVisionSkill(session: Session): boolean {
   const nativeCalls = new Set<string>()
-  for (const event of session.events) {
+  for (const event of sessionEventLog(session)) {
     if (event.type === 'user/message') {
       const source = event.data.source
       if (source.kind === 'skill-invocation'

package/src/image-input-variants.ts

@@ -142,18 +142,21 @@ async function materializeImage(
   data: Uint8Array,
   extension: string,
   sessionId: string | undefined,
+  storageDir: string | undefined,
 ): Promise<MaterializedImage> {
   const session = sessionId === undefined ? undefined : ctx.sessions.get(sessionId as never)
   const cwd = session?.header.cwd
   if (sessionId !== undefined && cwd !== undefined && isAbsolute(cwd)) {
-    const root = await sessionPasteRoot(ctx, sessionId)
+    const root = await sessionPasteRoot(ctx, sessionId, storageDir)
     const identity = createHash('sha256')
       .update(`${sessionId}\u0000${String(block.attachment.attachmentId)}`)
       .digest('hex')
       .slice(0, 32)
-    const file = join(root.visibleRoot, `attachment-${identity}${extension}`)
+    const filename = `attachment-${identity}${extension}`
+    const writePath = join(root.writeRoot, filename)
+    const file = join(root.visibleRoot, filename)
     try {
-      await writeFile(file, Buffer.from(data), { mode: 0o600, flag: 'wx' })
+      await writeFile(writePath, Buffer.from(data), { mode: 0o600, flag: 'wx' })
     } catch (error) {
       if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) throw error
     }
@@ -357,6 +360,7 @@ async function readImageBlock(
   block: ImageBlock,
   query: string,
   sessionId?: string,
+  storageDir?: string,
 ): Promise<ContentBlock> {
   const attachments = ctx.get('attachments')
   const current = runtime()
@@ -371,7 +375,7 @@ async function readImageBlock(
   let pathEvidence = ''
   try {
     const stored = await attachments.readImage(block.attachment)
-    const materialized = await materializeImage(ctx, block, stored.data, extension, sessionId)
+    const materialized = await materializeImage(ctx, block, stored.data, extension, sessionId, storageDir)
     temporaryDirectory = materialized.temporaryDirectory
     if (materialized.persistent) pathEvidence = imagePathEvidence(materialized.file)
 
@@ -414,6 +418,7 @@ async function readImageBlock(
  * @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.
+ * @param storageDir - optional shared plugin storage root.
  * @returns the rewritten message list.
  */
 export async function convertImagesToEvidence(
@@ -424,6 +429,7 @@ export async function convertImagesToEvidence(
   signal?: AbortSignal,
   sessionId?: string,
   runtimeHash = 'process-only-runtime',
+  storageDir?: string,
 ): Promise<Message[]> {
   const session = sessionId === undefined ? undefined : ctx.sessions.get(sessionId as never)
   const sessionIdentity = session === undefined
@@ -480,7 +486,7 @@ export async function convertImagesToEvidence(
           prompt: query,
           runtimeHash,
         }), () =>
-          readImageBlock(ctx, runtime, block, query, sessionId)),
+          readImageBlock(ctx, runtime, block, query, sessionId, storageDir)),
         signal,
       ),
       signal,
@@ -517,6 +523,7 @@ export class ImageInputVariantAdapter extends LlmAdapter {
     private readonly runtime: () => VisionToolkitRuntime | undefined,
     private readonly cache: EvidenceCache,
     private readonly hidden: () => boolean = () => false,
+    private readonly startupStorageDirectory: () => string | undefined = () => undefined,
   ) {
     super()
   }
@@ -589,6 +596,7 @@ export class ImageInputVariantAdapter extends LlmAdapter {
 
   override async *stream(options: GenerateOptions): AsyncGenerator<StreamChunk> {
     const current = this.runtime()
+    const storageDir = current === undefined ? this.startupStorageDirectory() : current.storageDirectory
     let captured: CapturedEvidenceRuntime | undefined
     if (current !== undefined && options.messages.some(message => contentHasImage(message.content))) {
       try {
@@ -610,7 +618,12 @@ export class ImageInputVariantAdapter extends LlmAdapter {
       options.messages,
       options.signal,
       options.sessionId === undefined ? undefined : String(options.sessionId),
-      captured?.evidenceFingerprint ?? 'process-only-runtime',
+      captured?.evidenceFingerprint ?? createHash('sha256')
+        .update('process-only-runtime')
+        .update('\0')
+        .update(storageDir ?? '')
+        .digest('hex'),
+      storageDir,
     )
     // Delegate through the host service under the upstream route: the variant
     // is a wire-only facade, and the upstream route owns retry and replay.
@@ -846,6 +859,7 @@ export function installImageInputVariants(
   ctx: Context,
   getConfig: () => ResolvedVisionToolkitConfig,
   getRuntime: () => VisionToolkitRuntime | undefined,
+  getStartupStorageDirectory: () => string | undefined = () => undefined,
 ): { dispose: () => void; reconcile: () => void } {
   const evidenceStore = new SessionEvidenceStore(ctx)
   const evidenceCache = new EvidenceCache(EVIDENCE_CACHE_LIMIT, evidenceStore)
@@ -991,6 +1005,7 @@ export function installImageInputVariants(
               getRuntime,
               evidenceCache,
               () => getConfig().imageInputVariants.hidden,
+              getStartupStorageDirectory,
             ),
           )
           registrations.set(upstream, { dispose, retryPolicyKey: upstreamRetryPolicyKey })

package/src/index.ts

@@ -18,13 +18,16 @@ import { ArtifactAccessController, prepareArtifactAccessKey } from './artifact-a
 import {
   Config,
   VISION_TOOLKIT_SETTINGS_NAMESPACE,
+  prepareWatchedSettingsGeneration,
   resolveConfig,
+  type ResolvedVisionToolkitConfig,
   type VisionToolkitConfig,
 } from './config.ts'
 import { VisionToolExposure } from './exposure.ts'
 import { createPasteTakeoverResolver, installImageInputVariants } from './image-input-variants.ts'
 import { VisionToolkitRuntimeManager } from './runtime-manager.ts'
 import { VISION_SKILLS_SKILL } from './skill.ts'
+import { StorageHistoryStore } from './storage-history.ts'
 import { createVisionTools } from './tools.ts'
 import { PLUGIN_VERSION } from './version.ts'
 import { installVisionToolkitWeb, VisionToolkitWebBackend } from './web.ts'
@@ -51,8 +54,33 @@ export async function apply(ctx: Context, config: VisionToolkitConfig = {}): Pro
   const artifacts = new ArtifactAccessController(await prepareArtifactAccessKey())
   const lifecycle = new AbortController()
   const disposers: Array<() => void> = []
+  const storageHistory = new StorageHistoryStore(ctx)
+  disposers.push(() => { storageHistory.dispose() })
+  let storageHistoryWarningReported = false
   let operationalDisposers: { activationTool: () => void; exposure: () => void; skill: () => void } | undefined
 
+  const persistStorageHistory = async (candidate: VisionToolkitConfig, required: boolean): Promise<void> => {
+    try {
+      const persisted = await storageHistory.persist(candidate)
+      if (persisted) return
+      const error = new Error(
+        'configured storage history requires @deepseek-ai/dsh-storage-domain when Settings cannot persist it',
+      )
+      if (required) throw error
+      if (!storageHistoryWarningReported) {
+        storageHistoryWarningReported = true
+        ctx.logger.warn('dsh-vision-toolkit: %s', error.message)
+      }
+    } catch (error) {
+      if (required) throw error
+      if (!storageHistoryWarningReported) {
+        storageHistoryWarningReported = true
+        const message = error instanceof Error ? error.message : String(error)
+        ctx.logger.warn('dsh-vision-toolkit: configured storage history was not persisted. %s', message)
+      }
+    }
+  }
+
   const ensureOperational = (): void => {
     if (!manager.ready || operationalDisposers !== undefined) return
     const exposure = new VisionToolExposure(ctx, () => createVisionTools(
@@ -84,10 +112,16 @@ export async function apply(ctx: Context, config: VisionToolkitConfig = {}): Pro
     }
   }
 
+  const initialConfig = await storageHistory.restore(settings.get())
   try {
-    await manager.initialize(settings.get())
+    await manager.initialize(initialConfig, candidate => persistStorageHistory(candidate.config, false))
     ensureOperational()
   } catch (error) {
+    const resolvedInitial = resolveConfig(initialConfig)
+    if (resolvedInitial.storageDir === undefined
+      || manager.validatedStorageDirectory() === resolvedInitial.storageDir) {
+      await persistStorageHistory(initialConfig, false)
+    }
     const message = error instanceof Error ? error.message : String(error)
     ctx.logger.error(
       'dsh-vision-toolkit %s: runtime not ready; the vision-skills skill, activation bootstrap, and Agent-scoped visual tools are NOT registered. Settings remain available for repair. %s',
@@ -97,29 +131,54 @@ export async function apply(ctx: Context, config: VisionToolkitConfig = {}): Pro
   }
 
   const backend = new VisionToolkitWebBackend(ctx, manager, artifacts, ensureOperational)
+  const currentConfig = (): ResolvedVisionToolkitConfig => manager.ready
+    ? manager.currentConfig()
+    : resolveConfig(settings.get())
   const pastedImages = new PastedImageBackend(ctx, {
     maxUploadBytes: () => MAX_PASTE_IMAGE_BYTES,
+    storageGeneration: () => manager.storageGeneration(),
   })
   // Image-input variants register asynchronously once eligible routes exist;
   // the runtime getter stays lazy so variants appear even when the runtime
   // becomes ready after the first sweep.
   const variants = installImageInputVariants(
     ctx,
-    () => resolveConfig(settings.get()),
+    currentConfig,
     () => manager.ready ? manager.current() : undefined,
+    () => manager.validatedStorageDirectory(),
   )
   installVisionToolkitWeb(
     ctx,
     backend,
     artifacts,
     pastedImages,
-    createPasteTakeoverResolver(ctx, () => resolveConfig(settings.get())),
-    () => ({ hidden: resolveConfig(settings.get()).imageInputVariants.hidden }),
+    createPasteTakeoverResolver(ctx, currentConfig),
+    () => ({ hidden: currentConfig().imageInputVariants.hidden }),
   )
   disposers.push(variants.dispose)
-  disposers.push(settings.watch(async (next) => {
+  disposers.push(settings.watch(async (next, previous) => {
     try {
-      await manager.reconfigure(next)
+      const prepared = await prepareWatchedSettingsGeneration(
+        next,
+        previous,
+        ctx.settings.writable,
+        storageHistory => settings.update({ storageHistory }),
+      )
+      if (prepared.persistenceError !== undefined) {
+        const message = prepared.persistenceError instanceof Error
+          ? prepared.persistenceError.message
+          : String(prepared.persistenceError)
+        ctx.logger.warn('dsh-vision-toolkit: activating Settings without persisting internal storage history. %s', message)
+      }
+      if (prepared.config === undefined) return
+      const candidate = await storageHistory.restore(prepared.config)
+      await manager.reconfigure(
+        candidate,
+        generation => persistStorageHistory(
+          generation.config,
+          prepared.requiresDurableStorageHistory === true,
+        ),
+      )
       ensureOperational()
       variants.reconcile()
     } catch (error) {