@anionex/dsh-vision-toolkit 0.1.39 → 0.1.40

package/src/runtime-manager.ts

@@ -7,6 +7,7 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import { resolveConfig, type ResolvedVisionToolkitConfig, type VisionToolkitConfig } from './config.ts'
+import { preflightSharedStorageBase } from './paths.ts'
 import { VisionToolkitRuntime } from './runtime.ts'
 import { UpstreamAdapter, type UpstreamVersionInfo } from './upstream.ts'
 
@@ -26,16 +27,30 @@ export interface RuntimeManagerStatus {
   lastError?: string
 }
 
+/** Storage selection paired to the active or validated startup generation. */
+export interface RuntimeStorageGeneration {
+  generation: number
+  storageDir?: string
+}
+
 /** Test seam for preparing one generation. */
 export type RuntimeGenerationFactory = (
   ctx: Context,
   config: ResolvedVisionToolkitConfig,
+  readableStorageDirs: readonly string[],
 ) => Promise<VisionToolkitRuntime>
 
-async function defaultFactory(ctx: Context, config: ResolvedVisionToolkitConfig): Promise<VisionToolkitRuntime> {
+/** Async commit prerequisite run after preparation and before a generation becomes active. */
+export type RuntimeGenerationBeforePublish = (candidate: PreparedRuntimeGeneration) => Promise<void>
+
+async function defaultFactory(
+  ctx: Context,
+  config: ResolvedVisionToolkitConfig,
+  readableStorageDirs: readonly string[],
+): Promise<VisionToolkitRuntime> {
   const adapter = new UpstreamAdapter(ctx, config)
   await adapter.prepare()
-  return new VisionToolkitRuntime(ctx, config, adapter)
+  return new VisionToolkitRuntime(ctx, config, adapter, readableStorageDirs)
 }
 
 function fingerprint(config: ResolvedVisionToolkitConfig): string {
@@ -57,6 +72,8 @@ export class VisionToolkitRuntimeManager {
   private generation = 0
   private reconfigureTicket = 0
   private lastError: string | undefined
+  private validatedStartupStorageDir: string | null | undefined
+  private readonly readableStorageDirs = new Set<string>()
 
   constructor(
     private readonly ctx: Context,
@@ -69,22 +86,69 @@ export class VisionToolkitRuntimeManager {
     return this.active.runtime
   }
 
+  /** Configuration belonging to the currently serving runtime generation. */
+  currentConfig(): ResolvedVisionToolkitConfig {
+    if (this.active === undefined) throw new Error('dsh-vision-toolkit runtime is not ready')
+    return this.active.config
+  }
+
   /** Whether at least one generation is available. */
   get ready(): boolean {
     return this.active !== undefined
   }
 
-  /** Resolve and fully prepare a candidate without changing the active runtime. */
-  async prepareCandidate(raw: VisionToolkitConfig): Promise<PreparedRuntimeGeneration> {
-    const config = resolveConfig(raw)
+  /** Storage config safe for paste writes even when initial runtime preparation failed. */
+  storageGeneration(): RuntimeStorageGeneration {
+    if (this.active !== undefined) {
+      return {
+        generation: this.generation,
+        ...(this.active.config.storageDir === undefined ? {} : { storageDir: this.active.config.storageDir }),
+      }
+    }
+    if (this.validatedStartupStorageDir === undefined) {
+      throw new Error('dsh-vision-toolkit storage configuration is not ready')
+    }
+    return {
+      generation: this.generation,
+      ...(this.validatedStartupStorageDir === null ? {} : { storageDir: this.validatedStartupStorageDir }),
+    }
+  }
+
+  /** Validated storage for best-effort consumers; undefined when startup preflight failed. */
+  validatedStorageDirectory(): string | undefined {
+    if (this.active !== undefined) return this.active.config.storageDir
+    return this.validatedStartupStorageDir ?? undefined
+  }
+
+  private async prepareResolvedCandidate(config: ResolvedVisionToolkitConfig): Promise<PreparedRuntimeGeneration> {
     const resolvedFingerprint = fingerprint(config)
     if (this.active?.fingerprint === resolvedFingerprint) {
       return { ...this.active, config }
     }
-    const runtime = await this.factory(this.ctx, config)
+    const runtime = await this.factory(
+      this.ctx,
+      config,
+      [...new Set([...this.readableStorageDirs, ...config.storageHistory])]
+        .filter(storageDir => storageDir !== config.storageDir),
+    )
     return { config, fingerprint: resolvedFingerprint, runtime }
   }
 
+  private rememberStorageDirectory(storageDir: string | undefined): void {
+    if (storageDir !== undefined) this.readableStorageDirs.add(storageDir)
+  }
+
+  private rememberStorageDirectories(storageDirs: readonly string[]): void {
+    for (const storageDir of storageDirs) this.rememberStorageDirectory(storageDir)
+  }
+
+  /** Resolve and fully prepare a candidate without changing the active runtime. */
+  async prepareCandidate(raw: VisionToolkitConfig): Promise<PreparedRuntimeGeneration> {
+    const config = resolveConfig(raw)
+    if (config.storageDir !== undefined) await preflightSharedStorageBase(config.storageDir)
+    return this.prepareResolvedCandidate(config)
+  }
+
   /**
    * Publish one already-prepared generation atomically.
    * @param candidate - generation returned by {@link prepareCandidate}.
@@ -97,6 +161,8 @@ export class VisionToolkitRuntimeManager {
     }
     this.reconfigureTicket += 1
     this.active = candidate
+    this.rememberStorageDirectories(candidate.config.storageHistory)
+    this.rememberStorageDirectory(candidate.config.storageDir)
     this.generation += 1
     this.lastError = undefined
     this.ctx.logger.info(
@@ -108,10 +174,21 @@ export class VisionToolkitRuntimeManager {
     )
   }
 
-  /** Prepare and publish the initial or explicitly validated generation. */
-  async initialize(raw: VisionToolkitConfig): Promise<void> {
+  /**
+   * Prepare and publish the initial or explicitly validated generation.
+   * @param raw - untrusted Settings generation to resolve and prepare.
+   * @param beforePublish - optional durable prerequisite run after preparation.
+   */
+  async initialize(raw: VisionToolkitConfig, beforePublish?: RuntimeGenerationBeforePublish): Promise<void> {
     try {
-      this.activateCandidate(await this.prepareCandidate(raw))
+      const config = resolveConfig(raw)
+      if (config.storageDir !== undefined) await preflightSharedStorageBase(config.storageDir)
+      this.validatedStartupStorageDir = config.storageDir ?? null
+      this.rememberStorageDirectories(config.storageHistory)
+      this.rememberStorageDirectory(config.storageDir)
+      const candidate = await this.prepareResolvedCandidate(config)
+      await beforePublish?.(candidate)
+      this.activateCandidate(candidate)
     } catch (error) {
       this.lastError = messageOf(error)
       throw error
@@ -121,13 +198,17 @@ export class VisionToolkitRuntimeManager {
   /**
    * Apply an externally committed Settings generation. Concurrent edits are
    * last-write-wins; a slower obsolete prepare can never overwrite a newer one.
+   * @param raw - externally committed Settings generation.
+   * @param beforePublish - optional durable prerequisite run after preparation.
    * @returns whether this call published a new active generation.
    */
-  async reconfigure(raw: VisionToolkitConfig): Promise<boolean> {
+  async reconfigure(raw: VisionToolkitConfig, beforePublish?: RuntimeGenerationBeforePublish): Promise<boolean> {
     const ticket = ++this.reconfigureTicket
     let candidate: PreparedRuntimeGeneration
     try {
       candidate = await this.prepareCandidate(raw)
+      if (ticket !== this.reconfigureTicket) return false
+      await beforePublish?.(candidate)
     } catch (error) {
       if (ticket === this.reconfigureTicket) this.lastError = messageOf(error)
       throw error
@@ -135,6 +216,8 @@ export class VisionToolkitRuntimeManager {
     if (ticket !== this.reconfigureTicket) return false
     const changed = this.active?.fingerprint !== candidate.fingerprint
     this.active = candidate
+    this.rememberStorageDirectories(candidate.config.storageHistory)
+    this.rememberStorageDirectory(candidate.config.storageDir)
     if (changed) {
       this.generation += 1
       this.ctx.logger.info(

package/src/runtime.ts

@@ -696,6 +696,7 @@ export class VisionToolkitRuntime {
     private readonly ctx: Context,
     private readonly config: ResolvedVisionToolkitConfig,
     adapter?: UpstreamAdapter,
+    private readonly readableStorageDirs: readonly string[] = [],
   ) {
     this.adapter = adapter ?? new UpstreamAdapter(ctx, config)
   }
@@ -705,6 +706,11 @@ export class VisionToolkitRuntime {
     return this.adapter.versionInfo
   }
 
+  /** Shared storage root belonging to this immutable runtime generation. */
+  get storageDirectory(): string | undefined {
+    return this.config.storageDir
+  }
+
   /** Stable identity for persisted image descriptions produced by this runtime. */
   get evidenceFingerprint(): string {
     return evidenceRuntimeFingerprint(this.config, undefined, process.env.VISION_SSL_VERIFY?.trim())
@@ -880,13 +886,13 @@ export class VisionToolkitRuntime {
   }
 
   private pathPolicy(workspace: string): Promise<PathPolicy> {
-    return createPathPolicy(workspace, this.config.allowedDirs)
+    return createPathPolicy(workspace, this.config.allowedDirs, this.config.storageDir, this.readableStorageDirs)
   }
 
   private async compressedImageRoot(policy: PathPolicy): Promise<string> {
-    const root = join(policy.workspace, '.dsh-vision-toolkit', 'tmp', 'compressed-images')
-    let current = policy.workspace
-    for (const segment of ['.dsh-vision-toolkit', 'tmp', 'compressed-images']) {
+    const root = join(policy.storageRoot, 'tmp', 'compressed-images')
+    let current = policy.storageRoot
+    for (const segment of ['tmp', 'compressed-images']) {
       current = join(current, segment)
       try {
         await mkdir(current, { mode: 0o700 })
@@ -897,13 +903,13 @@ export class VisionToolkitRuntime {
       if (info.isSymbolicLink() || !info.isDirectory()) {
         throw new VisionToolkitError('path', `compressed-image cache path is not a real directory: ${current}`)
       }
-      if (!isWithin(policy.workspace, current)) {
-        throw new VisionToolkitError('path', `compressed-image cache path escaped the workspace: ${current}`)
+      if (!isWithin(policy.storageRoot, current)) {
+        throw new VisionToolkitError('path', `compressed-image cache path escaped plugin storage: ${current}`)
       }
     }
     const canonical = await realpath(root)
-    if (!isWithin(policy.workspace, canonical)) {
-      throw new VisionToolkitError('path', 'compressed-image cache resolved outside the workspace')
+    if (!isWithin(policy.storageRoot, canonical)) {
+      throw new VisionToolkitError('path', 'compressed-image cache resolved outside plugin storage')
     }
     return canonical
   }
@@ -2078,7 +2084,7 @@ export class VisionToolkitRuntime {
       let artifactDirectory: HealthCheck
       try {
         // allowedDirs are session input roots; they do not affect output readiness.
-        const policy = await createPathPolicy(options.workspace, [])
+        const policy = await createPathPolicy(options.workspace, [], this.config.storageDir)
         artifactDirectory = await this.writableDirectoryCheck(policy.outputDir, 'Artifact directory')
       } catch {
         artifactDirectory = { status: 'error', detail: 'Artifact directory could not be prepared' }

package/src/storage-history.ts

@@ -0,0 +1,172 @@
+/** Durable configured-storage history used to authorize persisted image paths after Profile restarts. */
+
+import type { Context, Fiber } from '@deepseek-ai/cordis'
+import { defineDomain } from '@deepseek-ai/dsh-storage-domain'
+import type { DomainGlobal } from '@deepseek-ai/dsh-storage-domain'
+import { z } from 'zod'
+import { resolveConfig, type VisionToolkitConfig } from './config.ts'
+
+const storageHistoryStateSchema = z.object({
+  roots: z.array(z.string().min(1)),
+})
+
+type StorageHistoryState = z.infer<typeof storageHistoryStateSchema>
+
+/** Plugin-owned storage roots that survive Settings-provider and Profile restarts. */
+export const storageHistoryDomainSpec = defineDomain({
+  name: 'vision_toolkit_storage',
+  version: 0,
+  global: {
+    schema: storageHistoryStateSchema,
+    initial: { roots: [] },
+  },
+  tables: {},
+})
+
+interface StorageBinding {
+  accepting: boolean
+  global: DomainGlobal<StorageHistoryState>
+}
+
+function sameRoots(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((root, index) => root === right[index])
+}
+
+/**
+ * Return every configured root that must remain readable, including the active root.
+ * @param config - Settings generation to summarize.
+ * @returns normalized configured roots in retention order.
+ */
+export function configuredStorageRoots(config: VisionToolkitConfig): string[] {
+  const resolved = resolveConfig(config)
+  return [...new Set([
+    ...resolved.storageHistory,
+    ...(resolved.storageDir === undefined ? [] : [resolved.storageDir]),
+  ])]
+}
+
+/**
+ * Merge plugin-owned roots into a Settings generation without retaining its active root as history.
+ * @param config - Settings generation being restored.
+ * @param durableRoots - roots loaded from the plugin-owned sidecar.
+ * @returns the original generation when unchanged, otherwise a generation with restored history.
+ */
+export function restoreDurableStorageHistory(
+  config: VisionToolkitConfig,
+  durableRoots: readonly string[],
+): VisionToolkitConfig {
+  const resolved = resolveConfig(config)
+  const storageHistory = [...new Set([...resolved.storageHistory, ...durableRoots])]
+    .filter(root => root !== resolved.storageDir)
+  if (sameRoots(storageHistory, resolved.storageHistory)) return config
+  return { ...config, storageHistory }
+}
+
+/** Optional storage-domain sidecar for storage roots that Settings cannot persist itself. */
+export class StorageHistoryStore {
+  private storage: StorageBinding | undefined
+  private storageFiber: (Fiber & PromiseLike<Fiber>) | undefined
+  private storageReady: Promise<void> | undefined
+  private mutationTail: Promise<void> = Promise.resolve()
+  private desiredRoots: readonly string[] | undefined
+  private persistenceTicket = 0
+  private warned = false
+
+  constructor(private readonly ctx: Context) {
+    if (typeof ctx.inject !== 'function') return
+    this.storageFiber = ctx.inject(['storageDomain'], async (storageCtx: Context) => {
+      const domain = await storageCtx.storageDomain.open(storageHistoryDomainSpec)
+      const binding: StorageBinding = { accepting: true, global: domain.global }
+      this.storage = binding
+      try {
+        if (this.desiredRoots !== undefined) {
+          await this.write(binding, this.desiredRoots, this.persistenceTicket)
+        }
+      } catch (error) {
+        this.storage = undefined
+        await domain.close()
+        throw error
+      }
+      return async () => {
+        binding.accepting = false
+        if (this.storage === binding) this.storage = undefined
+        await this.mutationTail
+        await domain.close()
+      }
+    })
+    this.storageReady = Promise.resolve(this.storageFiber).then(
+      () => undefined,
+      (error: unknown) => { this.warnOnce(error) },
+    )
+  }
+
+  /**
+   * Restore durable roots into one Settings generation before runtime preparation.
+   * @param config - Settings generation to restore.
+   * @returns the generation with available durable roots merged into its history.
+   */
+  async restore(config: VisionToolkitConfig): Promise<VisionToolkitConfig> {
+    const binding = await this.prepareStorage()
+    return restoreDurableStorageHistory(config, binding?.global.get().roots ?? [])
+  }
+
+  /**
+   * Persist the active and historical configured roots.
+   * @param config - validated generation whose roots must survive restart.
+   * @returns false when no storage-domain is available; true after persistence or when there are no roots.
+   */
+  async persist(config: VisionToolkitConfig): Promise<boolean> {
+    const roots = configuredStorageRoots(config)
+    const ticket = ++this.persistenceTicket
+    this.desiredRoots = roots
+    if (roots.length === 0) return true
+    const binding = await this.prepareStorage()
+    if (binding === undefined) return false
+    await this.write(binding, roots, ticket)
+    return true
+  }
+
+  /** Release the optional storage-domain binding with the plugin lifecycle. */
+  dispose(): void {
+    const fiber = this.storageFiber
+    this.storageFiber = undefined
+    this.storageReady = undefined
+    if (fiber !== undefined) void fiber.dispose().catch(error => { this.warnOnce(error) })
+  }
+
+  private async prepareStorage(): Promise<StorageBinding | undefined> {
+    const current = this.activeStorage()
+    if (current !== undefined) return current
+    if (this.ctx.get('storageDomain') === undefined) return undefined
+    await this.storageReady
+    return this.activeStorage()
+  }
+
+  private activeStorage(): StorageBinding | undefined {
+    return this.storage?.accepting === true ? this.storage : undefined
+  }
+
+  private write(binding: StorageBinding, roots: readonly string[], ticket: number): Promise<void> {
+    return this.enqueueMutation(async () => {
+      if (!binding.accepting) throw new Error('the storage-domain provider changed while storage history was pending')
+      if (ticket !== this.persistenceTicket) return
+      if (sameRoots(binding.global.get().roots, roots)) return
+      await binding.global.set({ roots: [...roots] })
+    })
+  }
+
+  private enqueueMutation(operation: () => Promise<void>): Promise<void> {
+    const result = this.mutationTail.then(operation)
+    this.mutationTail = result.then(() => undefined, () => undefined)
+    return result
+  }
+
+  private warnOnce(error: unknown): void {
+    if (this.warned) return
+    this.warned = true
+    this.ctx.logger?.warn(
+      'dsh-vision-toolkit: configured storage history sidecar is unavailable. %s',
+      (error instanceof Error ? error.message : String(error)).slice(0, 500),
+    )
+  }
+}

package/src/web.ts

@@ -22,6 +22,7 @@ import {
 } from './paste-images.ts'
 import {
   resolveConfig,
+  retainedStorageHistory,
   isBuiltInFreeVisionProvider,
   VISION_TOOLKIT_SETTINGS_NAMESPACE,
   type ResolvedVisionToolkitConfig,
@@ -303,16 +304,22 @@ export class VisionToolkitWebBackend {
 
   private async save(request: SaveRequest): Promise<VisionToolkitSettingsSnapshot> {
     if (!this.ctx.settings.writable) throw new Error('settings provider is read-only')
+    const current = resolveConfig(descriptorOf(this.ctx).value as VisionToolkitConfig)
+    const storageHistory = retainedStorageHistory(request.value, current)
+    const value: VisionToolkitConfig = {
+      ...request.value,
+      ...(storageHistory.length === 0 ? {} : { storageHistory }),
+    }
     let candidate: PreparedRuntimeGeneration
     try {
-      candidate = await this.manager.prepareCandidate(request.value)
+      candidate = await this.manager.prepareCandidate(value)
     } catch (error) {
       this.manager.recordFailure(error)
       throw error
     }
     await this.ctx.settings.replace(
       VISION_TOOLKIT_SETTINGS_NAMESPACE,
-      request.value as object,
+      value as object,
       request.expectedRevision,
     )
     this.manager.activateCandidate(candidate)