@mengruo/dsh-vision-toolkit 0.1.3 → 0.1.4

package/src/client/paste-images.tsx

@@ -58,6 +58,8 @@ interface PasteOccurrence {
   source: string
   ref: string
   offset: number
+  /** DSH rc.8+ stores the full @label text; older releases used one placeholder. */
+  length?: number
   label: string
 }
 
@@ -166,6 +168,10 @@ function pasteLabel(file: File, index: number): string {
   return file.name.trim() || `clipboard-image-${index + 1}`
 }
 
+function occurrenceEnd(occurrence: PasteOccurrence): number {
+  return occurrence.offset + (occurrence.length ?? 1)
+}
+
 /** Owns browser File objects until DSH serializes the corresponding text references. */
 export class PasteImageController {
   private readonly records = new Map<string, PasteRecord>()
@@ -241,6 +247,7 @@ export class PasteImageController {
       if (before !== '' && !/\s$/u.test(before)) cursor = this.insertText(input, ' ', cursor)
       for (const [index, file] of files.entries()) {
         const ref = id()
+        const label = pasteLabel(file, index)
         const record: PasteRecord = { ref, file, batch, status: 'ready' }
         batch.records.push(record)
         this.records.set(ref, record)
@@ -248,11 +255,14 @@ export class PasteImageController {
         const accepted = input.insertReference({
           source: SOURCE,
           ref,
-          label: pasteLabel(file, index),
-          clipboardText: `[pasted image: ${pasteLabel(file, index)}]`,
+          label,
+          clipboardText: `[pasted image: ${label}]`,
         }, { start: cursor, end: cursor, draftRev: snapshot.draftRev })
         if (!accepted) throw new Error('The composer changed before pasted images could be inserted')
-        cursor += 1
+        const inserted = input.state.getSnapshot().occurrences.find(occurrence =>
+          occurrence.source === SOURCE && occurrence.ref === ref)
+        if (inserted === undefined) throw new Error('The pasted image reference was not present after insertion')
+        cursor = occurrenceEnd(inserted)
         const hasNext = index + 1 < files.length
         const suffix = input.state.getSnapshot().draft.slice(cursor)
         if (hasNext || (suffix !== '' && !/^\s/u.test(suffix))) cursor = this.insertText(input, ' ', cursor)
@@ -594,7 +604,7 @@ export class PasteImageController {
       insertText: (text: string, span: { start: number; end: number; draftRev: number }) => boolean
     }).insertText('', {
       start: current.offset,
-      end: current.offset + 1,
+      end: occurrenceEnd(current),
       draftRev: snapshot.draftRev,
     })
     if (!accepted) return

package/src/config.ts

@@ -131,6 +131,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[]
   /**
@@ -204,6 +212,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),
@@ -257,6 +267,8 @@ export interface ResolvedVisionToolkitConfig {
     agentVisionToolkitPath?: string
     python?: string
   }
+  storageDir?: string
+  storageHistory: string[]
   allowedDirs: string[]
   imageInputVariants: {
     enabled: boolean
@@ -455,6 +467,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 ?? [])
@@ -492,6 +508,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,
@@ -502,6 +520,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) {

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