@anionex/dsh-vision-toolkit 0.1.38 → 0.1.40

package/src/client/index.tsx

@@ -67,6 +67,9 @@ const en = {
   runtimeMode: 'Runtime mode',
   toolkitPath: 'Pinned checkout path',
   python: 'Python override',
+  storage: 'Local files',
+  storageDir: 'Default save directory',
+  storageDirHint: 'Leave blank to keep .dsh-vision-toolkit in each workspace. On POSIX systems, set an absolute shared root such as /tmp/dsh-vision-toolkit to store artifacts, pasted images, and caches in an automatically generated per-user, workspace-specific child directory. Windows shared roots remain disabled until their ACLs can be verified safely.',
   allowedDirs: 'Additional allowed directories',
   allowedDirsHint: 'One path per line. The session workspace is always allowed.',
   save: 'Save and apply',
@@ -89,7 +92,7 @@ const en = {
   connectionHint: 'The API connection test only queries GET /models. The vision model test sends the bundled diagnostic image and verifies one real multimodal request.',
   saveBeforeTesting: 'Save service changes before testing the connection.',
   advanced: 'Advanced settings',
-  advancedHint: 'Credential name, provider compatibility, output language, resource limits, runtime source, Python, and additional readable directories.',
+  advancedHint: 'Credential name, provider compatibility, output language, resource limits, default save directory, runtime source, Python, and additional readable directories.',
   imageInput: 'Image input',
   hiddenVariants: 'Transparent variant routing',
   hiddenVariantsLabel: 'Keep the original model names and enable images automatically',
@@ -255,6 +258,9 @@ const zh: Record<LocaleKey, string> = {
   runtimeMode: '环境来源',
   toolkitPath: 'agent-vision-toolkit 目录',
   python: 'Python 解释器（可选）',
+  storage: '本地文件',
+  storageDir: '默认保存目录',
+  storageDirHint: '留空时继续在各工作区创建 .dsh-vision-toolkit。在 POSIX 系统上填写绝对路径共享根目录（例如 /tmp/dsh-vision-toolkit）后，产物、粘贴图片和缓存会保存到自动生成的当前用户、工作区专属子目录中。Windows 共享目录会保持禁用，直到能够安全校验 ACL 权限。',
   allowedDirs: '允许读取的其他目录',
   allowedDirsHint: '每行填写一个目录。当前会话的工作目录始终可以读取，无需重复填写。',
   save: '保存设置',
@@ -277,7 +283,7 @@ const zh: Record<LocaleKey, string> = {
   connectionHint: '“测试 API 连接”只请求 GET /models；“测试视觉模型”会发送插件自带的诊断图片，验证一次真实多模态调用。',
   saveBeforeTesting: '修改服务配置后，请先保存，再执行 API 或视觉模型测试。',
   advanced: '高级设置',
-  advancedHint: '凭据名称、服务兼容参数、结果语言、资源限制、运行环境来源、Python 和额外可读目录。一般无需修改。',
+  advancedHint: '凭据名称、服务兼容参数、结果语言、资源限制、默认保存目录、运行环境来源、Python 和额外可读目录。一般无需修改。',
   imageInput: '图片输入',
   hiddenVariants: '透明变体路由',
   hiddenVariantsLabel: '保留原模型名并自动启用图片能力',
@@ -478,6 +484,8 @@ interface SettingsValue {
   maxImagePixels?: number
   concurrency?: number
   runtime?: { mode?: 'managed' | 'external'; agentVisionToolkitPath?: string; python?: string }
+  storageDir?: string
+  storageHistory?: string[]
   allowedDirs?: string[]
   imageInputVariants?: {
     enabled?: boolean
@@ -1085,6 +1093,7 @@ interface Draft {
   runtimeMode: 'managed' | 'external'
   toolkitPath: string
   python: string
+  storageDir: string
   allowedDirs: string
   hiddenVariants: boolean
   variantEnabled: boolean
@@ -1108,6 +1117,7 @@ function draftOf(value: SettingsValue): Draft {
     runtimeMode: value.runtime?.mode ?? 'managed',
     toolkitPath: value.runtime?.agentVisionToolkitPath ?? '',
     python: value.runtime?.python ?? '',
+    storageDir: value.storageDir ?? '',
     allowedDirs: (value.allowedDirs ?? []).join('\n'),
     hiddenVariants: value.imageInputVariants?.hidden ?? true,
     variantEnabled: value.imageInputVariants?.enabled ?? true,
@@ -1152,6 +1162,7 @@ function valueOf(draft: Draft, t: Translate): SettingsValue {
       ...(draft.runtimeMode === 'external' ? { agentVisionToolkitPath: draft.toolkitPath.trim() } : {}),
       ...(draft.python.trim().length === 0 ? {} : { python: draft.python.trim() }),
     },
+    ...(draft.storageDir.trim().length === 0 ? {} : { storageDir: draft.storageDir.trim() }),
     allowedDirs: draft.allowedDirs.split(/\r?\n/).map(entry => entry.trim()).filter(Boolean),
     imageInputVariants: {
       ...(draft.variantEnabled ? {} : { enabled: false }),
@@ -1463,11 +1474,15 @@ function LoadedSettings({ controller, t }: SettingsInjected) {
 
           <section className="dvt-panel"><div className="dvt-panel-title"><h3>{t('imageInput')}</h3></div><label className="dvt-check"><input type="checkbox" checked={draft.hiddenVariants} disabled={!snapshot.writable || busy} onChange={(event) => { update('hiddenVariants', event.target.checked) }} /><span>{t('hiddenVariantsLabel')}</span><small>{t('hiddenVariantsHint')}</small></label></section>
 
+          <section className="dvt-panel"><div className="dvt-panel-title"><h3>{t('storage')}</h3></div><div className="dvt-form-grid">
+            <Field label={t('storageDir')} hint={t('storageDirHint')}><Input aria-label={t('storageDir')} placeholder="/tmp/dsh-vision-toolkit" value={draft.storageDir} onChange={(event) => { update('storageDir', event.target.value) }} /></Field>
+            <Field label={t('allowedDirs')} hint={t('allowedDirsHint')}><textarea rows={3} value={draft.allowedDirs} onChange={(event) => { update('allowedDirs', event.target.value) }} /></Field>
+          </div></section>
+
           <section className="dvt-panel"><div className="dvt-panel-title"><h3>{t('runtime')}</h3><span className={`dvt-badge ${snapshot.runtime.ready ? 'ok' : 'error'}`}>{snapshot.runtime.ready ? snapshot.runtime.upstream?.source === 'managed' ? t('runtimeManaged') : snapshot.runtime.upstream?.source === 'external' ? t('runtimeExternal') : t('runtimeReady') : t('runtimeUnavailable')}</span></div><div className="dvt-form-grid">
             <Field label={t('runtimeMode')}><select value={draft.runtimeMode} onChange={(event) => { update('runtimeMode', event.target.value as 'managed' | 'external') }}><option value="managed">{t('runtimeManaged')}</option><option value="external">{t('runtimeExternal')}</option></select></Field>
             {draft.runtimeMode === 'external' ? <Field label={t('toolkitPath')}><Input value={draft.toolkitPath} onChange={(event) => { update('toolkitPath', event.target.value) }} /></Field> : null}
             <Field label={t('python')}><Input placeholder="python3" value={draft.python} onChange={(event) => { update('python', event.target.value) }} /></Field>
-            <Field label={t('allowedDirs')} hint={t('allowedDirsHint')}><textarea rows={3} value={draft.allowedDirs} onChange={(event) => { update('allowedDirs', event.target.value) }} /></Field>
           </div>
           {snapshot.runtime.upstream === undefined ? null : <div className="dvt-runtime-facts"><code>{snapshot.runtime.upstream.path}</code><code>{snapshot.runtime.upstream.python} · {snapshot.runtime.upstream.pythonVersion}</code><code>{snapshot.runtime.upstream.runtimeHome}</code></div>}
           </section>

package/src/config.ts

@@ -9,7 +9,7 @@
 import z from '@deepseek-ai/schemastery'
 import type Schema from '@deepseek-ai/schemastery'
 import { credentialRef, type CredentialRef } from '@deepseek-ai/dsh-credentials'
-import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
 import { VisionToolkitError } from './errors.ts'
 import {
   BUILT_IN_FREE_VISION_BASE_URL,
@@ -24,8 +24,21 @@ export {
   BUILT_IN_FREE_VISION_MODEL,
 } from './defaults.ts'
 
+/**
+ * The namespace pattern the removed `settingsNamespace` helper enforced.
+ * dsh 0.1.2-alpha dropped that export; importing a missing named export is a
+ * module-evaluation error that stops the host from booting, so the check is
+ * inlined here instead of imported. The namespace is a static string, so no
+ * runtime dependency on `@deepseek-ai/dsh-settings` is needed.
+ */
+const SETTINGS_NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*$/
+
 /** Settings document namespace owned by this plugin. */
-export const VISION_TOOLKIT_SETTINGS_NAMESPACE = settingsNamespace('vision-toolkit')
+export const VISION_TOOLKIT_SETTINGS_NAMESPACE = 'vision-toolkit' as SettingsNamespace
+
+if (!SETTINGS_NAMESPACE_PATTERN.test(VISION_TOOLKIT_SETTINGS_NAMESPACE)) {
+  throw new TypeError(`settings namespace "${VISION_TOOLKIT_SETTINGS_NAMESPACE}" must match ${String(SETTINGS_NAMESPACE_PATTERN)}`)
+}
 
 /** Browser-compatible default shared with the vendored Python client. */
 export const DEFAULT_VISION_USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36'
@@ -78,6 +91,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[]
   /**
@@ -132,6 +153,8 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
     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),
@@ -161,6 +184,8 @@ export interface ResolvedVisionToolkitConfig {
     agentVisionToolkitPath?: string
     python?: string
   }
+  storageDir?: string
+  storageHistory: string[]
   allowedDirs: string[]
   imageInputVariants: {
     enabled: boolean
@@ -254,6 +279,10 @@ 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 imageInputVariants = config.imageInputVariants ?? {}
   const variantProviders = (imageInputVariants.providers ?? [])
@@ -271,6 +300,8 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
       ...(toolkitPath !== undefined ? { agentVisionToolkitPath: toolkitPath } : {}),
       ...(python !== undefined ? { python } : {}),
     },
+    ...(storageDir === undefined || storageDir.length === 0 ? {} : { storageDir }),
+    storageHistory,
     allowedDirs,
     imageInputVariants: {
       enabled: imageInputVariants.enabled ?? true,
@@ -281,6 +312,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/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,
@@ -99,6 +99,7 @@ export function evidenceRuntimeFingerprint(
     maxImageBytes: config.maxImageBytes,
     maxImagePixels: config.maxImagePixels,
     runtime: config.runtime,
+    storageDir: config.storageDir ?? null,
   }))
 }
 

package/src/image-input-variants.ts

@@ -23,6 +23,7 @@ import type {
   LlmProviderInfo,
   LlmResolvedModelInfo,
   Message,
+  ResolvedRetryPolicy,
   StreamChunk,
 } from '@deepseek-ai/dsh-llm'
 // Type-only imports activate the host service declarations on Context.
@@ -94,6 +95,18 @@ export function variantProviderId(upstream: string): string {
   return `${VARIANT_PROVIDER_PREFIX}${upstream}`
 }
 
+/** Stable semantic key for detecting a provider retry-policy replacement. */
+function retryPolicyKey(policy: ResolvedRetryPolicy): string {
+  const backoff = [policy.initialDelayMs, policy.maxDelayMs, policy.jitterRatio]
+  if (policy.mode === 'always') return JSON.stringify([policy.mode, ...backoff])
+  return JSON.stringify([
+    policy.mode,
+    policy.maxRetries,
+    [...policy.retryableCodes].sort(),
+    ...backoff,
+  ])
+}
+
 /**
  * Whether one model earns an image-input variant: the host must positively
  * declare it text-only. A model with unknown modalities is left alone — its
@@ -129,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
     }
@@ -344,6 +360,7 @@ async function readImageBlock(
   block: ImageBlock,
   query: string,
   sessionId?: string,
+  storageDir?: string,
 ): Promise<ContentBlock> {
   const attachments = ctx.get('attachments')
   const current = runtime()
@@ -358,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)
 
@@ -401,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(
@@ -411,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
@@ -467,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,
@@ -504,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()
   }
@@ -515,6 +535,10 @@ export class ImageInputVariantAdapter extends LlmAdapter {
     }
   }
 
+  override providerRetryPolicy(_provider: string): ResolvedRetryPolicy {
+    return this.llm.providerRetryPolicy(this.upstream)
+  }
+
   override async listModels(provider: string): Promise<readonly LlmModelInfo[]> {
     const models = await this.llm.listModels(this.upstream)
     return models.filter(shouldWrapModel).map((model) => ({
@@ -552,6 +576,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 {
@@ -573,7 +598,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.
@@ -809,13 +839,13 @@ 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)
-  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
-  // every wrapper for the new names to reach the model selector.
+  const registrations = new Map<string, { dispose: () => void; retryPolicyKey: string }>()
+  // The host snapshots adapter provider metadata and retry policy at registration
+  // time, so changes to either require rebuilding the wrapper route.
   let lastHidden = false
   // Upstream ids observed missing and the timestamp of the first missing
   // observation. A wrapper is only released after its upstream stays absent
@@ -832,12 +862,12 @@ export function installImageInputVariants(
   let sweepQueued = false
 
   const release = (upstream: string): void => {
-    const dispose = registrations.get(upstream)
-    if (dispose === undefined) return
+    const registration = registrations.get(upstream)
+    if (registration === undefined) return
     registrations.delete(upstream)
     stale.delete(upstream)
     try {
-      dispose()
+      registration.dispose()
     } catch (error) {
       ctx.logger.warn(
         'dsh-vision-toolkit: image-input variant release failed for "%s": %s',
@@ -916,18 +946,28 @@ export function installImageInputVariants(
           continue
         }
         const eligible = models.some(shouldWrapModel)
-        const registered = registrations.has(upstream)
-        if (registered && live.has(variantId)) {
+        let upstreamRetryPolicyKey: string
+        try {
+          upstreamRetryPolicyKey = retryPolicyKey(llm.providerRetryPolicy(upstream))
+        } catch {
+          // Preserve an existing wrapper through a transient upstream registry
+          // gap; the next topology event or periodic sweep will retry the probe.
+          continue
+        }
+        let registration = registrations.get(upstream)
+        if (registration !== undefined && live.has(variantId)) {
           // Re-read the live registry after the await: a rebuild inside the
           // probe window can drop our wrapper without touching our map.
           const liveNow = new Set(llm.listProviders().map(provider => provider.id))
           if (liveNow.has(variantId)) {
-            // Healthy handle: only react when the route lost every eligible model.
-            if (!eligible) release(upstream)
-            continue
+            if (eligible && registration.retryPolicyKey === upstreamRetryPolicyKey) continue
+            // Eligibility and retry policy are registration-time facts. Rebuild
+            // whenever either no longer matches the live upstream route.
+            release(upstream)
+            registration = undefined
           }
         }
-        if (registered) {
+        if (registration !== undefined) {
           // Dead handle from a registry rebuild/reset: drop it and register a
           // fresh wrapper below.
           release(upstream)
@@ -945,9 +985,10 @@ export function installImageInputVariants(
               getRuntime,
               evidenceCache,
               () => getConfig().imageInputVariants.hidden,
+              getStartupStorageDirectory,
             ),
           )
-          registrations.set(upstream, dispose)
+          registrations.set(upstream, { dispose, retryPolicyKey: upstreamRetryPolicyKey })
           stale.delete(upstream)
         } catch (error) {
           ctx.logger.warn(

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) {