@anionex/dsh-vision-toolkit 0.1.39 → 0.1.40

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

package/src/paste-images.ts

@@ -1,11 +1,13 @@
-/** Workspace-local storage for images pasted into the DSH Web composer. */
+/** Plugin-managed storage for images pasted into the DSH Web composer. */
 
 import { createHash, randomUUID } from 'node:crypto'
-import { lstat, mkdir, open, realpath, rename, rm } from 'node:fs/promises'
+import { constants as fsConstants } from 'node:fs'
+import { copyFile, lstat, mkdir, open, realpath, rename, rm } from 'node:fs/promises'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-session'
+import { resolveWorkspaceStorage } from './paths.ts'
 import { sameOriginPost } from './web-request.ts'
 
 /** Exact route used by the browser paste integration. */
@@ -51,6 +53,7 @@ export interface PasteVerdict {
 }
 
 const MAX_NAME_BYTES = 180
+const MAX_STORAGE_GENERATION_RETRIES = 4
 
 /**
  * Hard per-image upload ceiling for pastes. Files between the configured
@@ -151,7 +154,7 @@ export function safePastedImageName(raw: string, mediaType: string): string {
 export function ensurePathInside(root: string, target: string): void {
   const rel = relative(root, target)
   if (rel !== '' && (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))) {
-    throw new Error(`resolved pasted-image path escapes its workspace root: ${target}`)
+    throw new Error(`resolved pasted-image path escapes its managed root: ${target}`)
   }
 }
 
@@ -168,7 +171,7 @@ async function ensureManagedDirectory(workspace: string, path: string): Promise<
   }
   const entry = await lstat(path)
   if (entry.isSymbolicLink()) {
-    throw new Error(`resolved pasted-image path escapes its workspace root: symbolic link ${path}`)
+    throw new Error(`resolved pasted-image path escapes its managed root: symbolic link ${path}`)
   }
   if (!entry.isDirectory()) throw new Error(`pasted-image path is not a directory: ${path}`)
   const canonical = await realpath(path)
@@ -178,29 +181,33 @@ async function ensureManagedDirectory(workspace: string, path: string): Promise<
 
 /**
  * Resolve the managed per-session image directory used by both browser pastes
- * and native attachment bridging. Keeping both flows under the same workspace
- * root makes the resulting absolute path valid for the model's visual tools.
+ * and native attachment bridging. A configured shared storage root receives a
+ * stable workspace-specific child, keeping projects isolated without writing
+ * plugin files into the project directory.
  */
-export async function sessionPasteRoot(ctx: Context, sessionId: string): Promise<PasteRoot> {
+export async function sessionPasteRoot(
+  ctx: Context,
+  sessionId: string,
+  storageDir?: string,
+): Promise<PasteRoot> {
   const session = ctx.sessions.get(sessionId as never)
   if (session === undefined) throw new Error(`live Session not found: ${sessionId}`)
   const cwd = session.header.cwd
   if (cwd === undefined || !isAbsolute(cwd)) throw new Error(`Session has no absolute workspace: ${sessionId}`)
 
-  const visibleWorkspace = resolve(cwd)
-  const workspace = await realpath(visibleWorkspace)
-  const pluginRoot = join(visibleWorkspace, '.dsh-vision-toolkit')
-  await ensureManagedDirectory(workspace, pluginRoot)
+  const storage = await resolveWorkspaceStorage(resolve(cwd), storageDir)
+  const pluginRoot = storage.root
   const temporaryRoot = join(pluginRoot, 'tmp')
-  await ensureManagedDirectory(workspace, temporaryRoot)
+  await ensureManagedDirectory(pluginRoot, temporaryRoot)
   const requestedRoot = join(temporaryRoot, 'pasted-images')
-  const root = await ensureManagedDirectory(workspace, requestedRoot)
+  const root = await ensureManagedDirectory(temporaryRoot, requestedRoot)
+  const visibleRoot = join(storage.visibleRoot, 'tmp', 'pasted-images')
 
   const sessionKey = createHash('sha256').update(sessionId).digest('hex').slice(0, 20)
   const requestedSessionRoot = join(requestedRoot, sessionKey)
   const sessionRoot = await ensureManagedDirectory(root, requestedSessionRoot)
   ensurePathInside(root, sessionRoot)
-  return { writeRoot: sessionRoot, visibleRoot: requestedSessionRoot }
+  return { writeRoot: sessionRoot, visibleRoot: join(visibleRoot, sessionKey) }
 }
 
 async function writeImage(
@@ -240,9 +247,38 @@ async function writeImage(
   }
 }
 
+async function copyImage(
+  source: string,
+  directory: string,
+  filename: string,
+): Promise<string> {
+  const id = randomUUID()
+  const finalPath = join(directory, `${id}-${filename}`)
+  const stagingPath = join(directory, `.${id}.partial`)
+  ensurePathInside(directory, finalPath)
+  ensurePathInside(directory, stagingPath)
+  try {
+    await copyFile(source, stagingPath, fsConstants.COPYFILE_EXCL)
+    await rename(stagingPath, finalPath)
+    return finalPath
+  } catch (error) {
+    await rm(stagingPath, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
+export interface PasteStorageGeneration {
+  generation: number
+  storageDir?: string
+}
+
+class PasteStorageChangedError extends Error {}
+
 /** Runtime limit face kept separate for focused backend tests. */
 export interface PasteImageRuntime {
   maxUploadBytes(): number
+  storageDirectory?(): string | undefined
+  storageGeneration?(): PasteStorageGeneration
 }
 
 /** Same-origin, live-Session-bound image upload endpoint. */
@@ -252,6 +288,16 @@ export class PastedImageBackend {
     private readonly runtime: PasteImageRuntime,
   ) {}
 
+  private storageGeneration(): PasteStorageGeneration {
+    const current = this.runtime.storageGeneration?.()
+    if (current !== undefined) return current
+    const storageDir = this.runtime.storageDirectory?.()
+    return {
+      generation: 0,
+      ...(storageDir === undefined ? {} : { storageDir }),
+    }
+  }
+
   async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
     if (req.method !== 'POST') {
       res.setHeader('Allow', 'POST')
@@ -263,6 +309,7 @@ export class PastedImageBackend {
       return
     }
 
+    let managedPath: string | undefined
     try {
       const url = new URL(req.url ?? PASTE_IMAGES_ROUTE, 'http://dsh.internal')
       const sessionId = singleQuery(url, 'sessionId')
@@ -273,12 +320,27 @@ export class PastedImageBackend {
       if (contentLength !== undefined && Number(contentLength) !== size) {
         throw new TypeError('Content-Length does not match the declared size')
       }
-      const directory = await sessionPasteRoot(this.ctx, sessionId)
-      const writtenPath = await writeImage(req, directory.writeRoot, filename, size, this.runtime.maxUploadBytes())
-      const absolutePath = join(directory.visibleRoot, basename(writtenPath))
-      responseJson(res, 201, { ok: true, value: { absolutePath, filename, bytes: size } })
+      let storage = this.storageGeneration()
+      let directory = await sessionPasteRoot(this.ctx, sessionId, storage.storageDir)
+      managedPath = await writeImage(req, directory.writeRoot, filename, size, this.runtime.maxUploadBytes())
+      for (let attempt = 0; attempt < MAX_STORAGE_GENERATION_RETRIES; attempt += 1) {
+        const current = this.storageGeneration()
+        if (current.generation === storage.generation && current.storageDir === storage.storageDir) {
+          const absolutePath = join(directory.visibleRoot, basename(managedPath))
+          responseJson(res, 201, { ok: true, value: { absolutePath, filename, bytes: size } })
+          return
+        }
+        const nextDirectory = await sessionPasteRoot(this.ctx, sessionId, current.storageDir)
+        const migratedPath = await copyImage(managedPath, nextDirectory.writeRoot, filename)
+        await rm(managedPath, { force: true }).catch(() => {})
+        managedPath = migratedPath
+        directory = nextDirectory
+        storage = current
+      }
+      throw new PasteStorageChangedError('Vision Toolkit settings changed repeatedly during image copy; retry the paste')
     } catch (error) {
-      const status = error instanceof RangeError ? 413 : 400
+      if (managedPath !== undefined) await rm(managedPath, { force: true }).catch(() => {})
+      const status = error instanceof PasteStorageChangedError ? 409 : error instanceof RangeError ? 413 : 400
       this.ctx.logger.warn('dsh-vision-toolkit pasted image rejected: %s', message(error))
       requestError(res, status, 'paste-image-rejected', message(error))
     }