@mengruo/dsh-vision-toolkit 0.1.2 → 0.1.4

package/lib/types/config.d.ts

@@ -33,8 +33,10 @@ export interface VisionProviderConfig {
     anthropicThinking?: 'omit' | 'disabled' | 'adaptive';
     /** Outbound User-Agent for provider requests and connection tests. */
     userAgent?: string;
-    /** Per-provider single request timeout in milliseconds. */
-    timeoutMs?: number;
+    /** t1: per-request hedge threshold in seconds. A single request exceeding t1 keeps running while the next provider starts in parallel. */
+    t1Seconds?: number;
+    /** t2: per-provider cumulative cutoff in seconds. Total accumulated request time reaching t2 terminates the provider. */
+    t2Seconds?: number;
     /** Per-provider maximum input image bytes; larger images skip to a later provider or are compressed. */
     maxImageBytes?: number;
     /** Per-provider maximum decoded pixel count per input image. */
@@ -64,13 +66,17 @@ export interface VisionToolkitConfig {
     providers?: VisionProviderConfig[];
     /** Vision output language (`zh` or `en`). */
     language?: 'zh' | 'en';
-    /** Single remote/upstream call budget in milliseconds. */
-    timeoutMs?: number;
+    /** Global hard timeout in seconds for one tool invocation; the call never exceeds it. */
+    hardTimeoutSeconds?: number;
+    /** Per-session cap on concurrent tool operations (default 6). */
+    sessionMaxConcurrency?: number;
+    /** Minimum remaining budget in seconds required before issuing a new request (default 20). */
+    minAvailableSeconds?: number;
     /** Maximum input image size in bytes; larger images are auto-compressed (lossless first). */
     maxImageBytes?: number;
     /** Maximum decoded pixel count per input image; larger images are auto-downscaled to fit. */
     maxImagePixels?: number;
-    /** In-flight tool execution cap per session. */
+    /** Default per-model in-flight request cap inherited by providers that do not set their own. */
     concurrency?: number;
     runtime?: {
         /** `managed` uses the packaged snapshot and isolated venv; `external` uses a clean pinned checkout. */
@@ -80,6 +86,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[];
     /**
@@ -127,7 +141,8 @@ export interface ResolvedProvider {
     protocol: 'openai' | 'anthropic';
     anthropicThinking: 'omit' | 'disabled' | 'adaptive';
     userAgent: string;
-    timeoutMs: number;
+    t1Seconds: number;
+    t2Seconds: number;
     maxImageBytes: number;
     maxImagePixels: number;
     concurrency: number;
@@ -146,7 +161,9 @@ export interface ResolvedVisionToolkitConfig {
     /** Ordered failover pool; array order is the priority, highest first. */
     providers: ResolvedProvider[];
     language: 'zh' | 'en';
-    timeoutMs: number;
+    hardTimeoutSeconds: number;
+    sessionMaxConcurrency: number;
+    minAvailableSeconds: number;
     maxImageBytes: number;
     maxImagePixels: number;
     concurrency: number;
@@ -155,6 +172,8 @@ export interface ResolvedVisionToolkitConfig {
         agentVisionToolkitPath?: string;
         python?: string;
     };
+    storageDir?: string;
+    storageHistory: string[];
     allowedDirs: string[];
     imageInputVariants: {
         enabled: boolean;
@@ -172,6 +191,18 @@ export interface ResolvedVisionToolkitConfig {
  * @returns the fully defaulted, validated configuration.
  */
 export declare function resolveConfig(config?: VisionToolkitConfig): ResolvedVisionToolkitConfig;
+/** Merge prior storage roots into the next resolved generation's read-only history. */
+export declare function retainedStorageHistory(next: VisionToolkitConfig, previous: VisionToolkitConfig): string[];
+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 declare function prepareWatchedSettingsGeneration(next: VisionToolkitConfig, previous: VisionToolkitConfig, writable: boolean, persistStorageHistory: (storageHistory: string[]) => Promise<void>): Promise<WatchedSettingsGeneration>;
 /** Whether a resolved provider should use the bundled public key instead of DSH credentials. */
 export declare function isBuiltInFreeVisionProvider(provider: ResolvedVisionToolkitConfig['provider']): boolean;
 //# sourceMappingURL=config.d.ts.map

package/lib/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}

package/lib/types/errors.d.ts

@@ -4,8 +4,24 @@
  * that never contains credentials or raw upstream stack traces.
  * @module dsh-vision-toolkit/errors
  */
-/** Discriminant tag for every Vision Toolkit failure. */
-export declare const VISION_TOOLKIT_ERROR_CODES: readonly ["config", "input", "capacity", "service", "runtime", "output", "timeout", "cancelled", "path"];
+/**
+ * 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 declare const VISION_TOOLKIT_ERROR_CODES: readonly ["config", "input", "capacity", "auth", "quota", "rate_limit", "server", "network", "region", "tos", "invalid_request", "service", "runtime", "output", "timeout", "cancelled", "path"];
 /** Stable machine-readable error category. */
 export type VisionToolkitErrorCode = typeof VISION_TOOLKIT_ERROR_CODES[number];
 /** Error with a stable category; safe to surface to the model. */

package/lib/types/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yDAAyD;AACzD,eAAO,MAAM,0BAA0B,0GAU7B,CAAA;AAEV,8CAA8C;AAC9C,MAAM,MAAM,sBAAsB,GAAG,OAAO,0BAA0B,CAAC,MAAM,CAAC,CAAA;AAE9E,kEAAkE;AAClE,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;gBAEzB,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKzF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAO3E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAGvG"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,0BAA0B,kMAkB7B,CAAA;AAEV,8CAA8C;AAC9C,MAAM,MAAM,sBAAsB,GAAG,OAAO,0BAA0B,CAAC,MAAM,CAAC,CAAA;AAE9E,kEAAkE;AAClE,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;gBAEzB,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKzF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAO3E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAGvG"}

package/lib/types/evidence-cache.d.ts

@@ -31,7 +31,7 @@ export interface EvidencePersistence {
     read(key: EvidenceCacheKey): Promise<ContentBlock | undefined>;
     write(key: EvidenceCacheKey, block: ContentBlock): Promise<void>;
 }
-/** Fingerprint every runtime setting that can change the generated description. */
+/** Fingerprint every runtime setting that can change generated evidence or its embedded path. */
 export declare function evidenceRuntimeFingerprint(config: ResolvedVisionToolkitConfig, credentialSha256?: string, sslVerify?: string): string;
 /** Build a non-secret cache key from the Session, attachment, focus, and runtime contract. */
 export declare function createEvidenceCacheKey(input: {

package/lib/types/evidence-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evidence-cache.d.ts","sourceRoot":"","sources":["../../src/evidence-cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"evidence-cache.d.ts","sourceRoot":"","sources":["../../src/evidence-cache.ts"],"names":[],"mappings":"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"}

package/lib/types/exposure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exposure.d.ts","sourceRoot":"","sources":["../../src/exposure.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,qFAAqF;AACrF,eAAO,MAAM,uBAAuB,4BAA4B,CAAA;AAEhE,sEAAsE;AACtE,eAAO,MAAM,8BAA8B,iBAAiB,CAAA;AAE5D,gFAAgF;AAChF,eAAO,MAAM,gCAAgC,gFAAgF,CAAA;AAS7H,4DAA4D;AAC5D,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AA8ED;;;;;GAKG;AACH,qBAAa,kBAAkB;IAU3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAV9B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAA;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,SAAS,CAAQ;IAEzB;;;OAGG;gBAEgB,GAAG,EAAE,OAAO,EACZ,WAAW,EAAE,MAAM,cAAc,EAAE;IA6BtD,uEAAuE;IACvE,OAAO,IAAI,MAAM,IAAI;IAoCrB,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,QAAQ;IA0BhB,6EAA6E;IAC7E,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,6BAA6B;IAQrC,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,MAAM;IAOd,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,YAAY;CAIrB"}
+{"version":3,"file":"exposure.d.ts","sourceRoot":"","sources":["../../src/exposure.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,qFAAqF;AACrF,eAAO,MAAM,uBAAuB,4BAA4B,CAAA;AAEhE,sEAAsE;AACtE,eAAO,MAAM,8BAA8B,iBAAiB,CAAA;AAE5D,gFAAgF;AAChF,eAAO,MAAM,gCAAgC,gFAAgF,CAAA;AAS7H,4DAA4D;AAC5D,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AA4FD;;;;;GAKG;AACH,qBAAa,kBAAkB;IAU3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAV9B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAA;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,SAAS,CAAQ;IAEzB;;;OAGG;gBAEgB,GAAG,EAAE,OAAO,EACZ,WAAW,EAAE,MAAM,cAAc,EAAE;IA6BtD,uEAAuE;IACvE,OAAO,IAAI,MAAM,IAAI;IAoCrB,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,QAAQ;IA0BhB,6EAA6E;IAC7E,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,6BAA6B;IAQrC,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,MAAM;IAOd,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,YAAY;CAIrB"}

package/lib/types/image-input-variants.d.ts

@@ -52,9 +52,10 @@ export declare function abortableWait<T>(promise: Promise<T>, signal: AbortSigna
  * @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 declare function convertImagesToEvidence(ctx: Context, runtime: () => CapturedEvidenceRuntime | undefined, cache: EvidenceCache, messages: readonly Message[], signal?: AbortSignal, sessionId?: string, runtimeHash?: string): Promise<Message[]>;
+export declare function convertImagesToEvidence(ctx: Context, runtime: () => CapturedEvidenceRuntime | undefined, cache: EvidenceCache, messages: readonly Message[], signal?: AbortSignal, sessionId?: string, runtimeHash?: string, storageDir?: string): Promise<Message[]>;
 /**
  * The adapter behind one variant route: model metadata declares image input,
  * and every stream rewrites image blocks before delegating to the upstream
@@ -69,7 +70,8 @@ export declare class ImageInputVariantAdapter extends LlmAdapter {
     private readonly runtime;
     private readonly cache;
     private readonly hidden;
-    constructor(ctx: Context, llm: LlmService, upstream: string, upstreamName: string, runtime: () => VisionToolkitRuntime | undefined, cache: EvidenceCache, hidden?: () => boolean);
+    private readonly startupStorageDirectory;
+    constructor(ctx: Context, llm: LlmService, upstream: string, upstreamName: string, runtime: () => VisionToolkitRuntime | undefined, cache: EvidenceCache, hidden?: () => boolean, startupStorageDirectory?: () => string | undefined);
     providerInfo(provider: string): LlmProviderInfo;
     providerRetryPolicy(_provider: string): ResolvedRetryPolicy;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;
@@ -142,7 +144,7 @@ export declare function createPasteTakeoverResolver(ctx: Context, getConfig: ()
  * @param getRuntime - the currently serving Vision Toolkit runtime, if ready.
  * @returns the disposer and a manual re-sweep trigger (settings changes).
  */
-export declare function installImageInputVariants(ctx: Context, getConfig: () => ResolvedVisionToolkitConfig, getRuntime: () => VisionToolkitRuntime | undefined): {
+export declare function installImageInputVariants(ctx: Context, getConfig: () => ResolvedVisionToolkitConfig, getRuntime: () => VisionToolkitRuntime | undefined, getStartupStorageDirectory?: () => string | undefined): {
     dispose: () => void;
     reconcile: () => void;
 };

package/lib/types/image-input-variants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-input-variants.d.ts","sourceRoot":"","sources":["../../src/image-input-variants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,UAAU,EAAE,EAAE,UAAU,EAAmB,MAAM,sBAAsB,CAAA;AAC9E,OAAO,KAAK,EAEV,eAAe,EAEf,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,OAAO,EACP,mBAAmB,EACnB,WAAW,EACZ,MAAM,sBAAsB,CAAA;AAI7B,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAEL,aAAa,EAEd,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAoB,KAAK,mBAAmB,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACjG,OAAO,KAAK,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAEjF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEnD,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,oBAAoB,CAAA;AAExD,+EAA+E;AAC/E,eAAO,MAAM,cAAc,sBAAsB,CAAA;AA8CjD,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAcD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,iBAAiB,CAAC,GAAG,OAAO,CAEpF;AAED,iGAAiG;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAgGtD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAoBjG;AAgKD;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,uBAAuB,GAAG,SAAS,EAClD,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,MAAM,CAAC,EAAE,WAAW,EACpB,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,SAAyB,GACnC,OAAO,CAAC,OAAO,EAAE,CAAC,CA4EpB;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,UAAU;IAEpD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBANN,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,oBAAoB,GAAG,SAAS,EAC/C,KAAK,EAAE,aAAa,EACpB,MAAM,GAAE,MAAM,OAAqB;IAK7C,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe;IAO/C,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB;IAIrD,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC;IAW9D,YAAY,CACzB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC;IAoBhC;;;;;OAKG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QACT,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAA;QACpC,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,aAAa,CAAC,WAAW,CAAC,CAAA;KAC7D,CAAC;IAOc,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc,CAAC,WAAW,CAAC;CA6B9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc7F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAwCpG;AA0DD;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,2BAA2B,GAC3C,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,mBAAmB,EAAE,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAyCpG;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,2BAA2B,EAC5C,UAAU,EAAE,MAAM,oBAAoB,GAAG,SAAS,GACjD;IAAE,OAAO,EAAE,MAAM,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,IAAI,CAAA;CAAE,CAmLhD"}
+{"version":3,"file":"image-input-variants.d.ts","sourceRoot":"","sources":["../../src/image-input-variants.ts"],"names":[],"mappings":"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"}

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,EACL,MAAM,EAGN,KAAK,mBAAmB,EACzB,MAAM,aAAa,CAAA;AAUpB,eAAO,MAAM,IAAI,gCAAgC,CAAA;AAEjD,OAAO,EAAE,MAAM,EAAE,CAAA;AAEjB,eAAO,MAAM,MAAM,UAAqF,CAAA;AAExG,qFAAqF;AACrF,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAqG/F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,EACL,MAAM,EAKN,KAAK,mBAAmB,EACzB,MAAM,aAAa,CAAA;AAWpB,eAAO,MAAM,IAAI,gCAAgC,CAAA;AAEjD,OAAO,EAAE,MAAM,EAAE,CAAA;AAEjB,eAAO,MAAM,MAAM,UAAqF,CAAA;AAExG,qFAAqF;AACrF,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CA6J/F"}

package/lib/types/paste-images.d.ts

@@ -1,4 +1,4 @@
-/** Workspace-local storage for images pasted into the DSH Web composer. */
+/** Plugin-managed storage for images pasted into the DSH Web composer. */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Context } from '@deepseek-ai/cordis';
 /** Exact route used by the browser paste integration. */
@@ -55,19 +55,27 @@ export interface PasteRoot {
 }
 /**
  * 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 declare function sessionPasteRoot(ctx: Context, sessionId: string): Promise<PasteRoot>;
+export declare function sessionPasteRoot(ctx: Context, sessionId: string, storageDir?: string): Promise<PasteRoot>;
+export interface PasteStorageGeneration {
+    generation: number;
+    storageDir?: string;
+}
 /** 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. */
 export declare class PastedImageBackend {
     private readonly ctx;
     private readonly runtime;
     constructor(ctx: Context, runtime: PasteImageRuntime);
+    private storageGeneration;
     handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
 }
 //# sourceMappingURL=paste-images.d.ts.map

package/lib/types/paste-images.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paste-images.d.ts","sourceRoot":"","sources":["../../src/paste-images.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAI3E,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,yDAAyD;AACzD,eAAO,MAAM,kBAAkB,sCAAsC,CAAA;AAErE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,sCAAsC,CAAA;AAErE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,6FAA6F;IAC7F,QAAQ,EAAE,OAAO,CAAA;IACjB,iGAAiG;IACjG,UAAU,CAAC,EAAE,gBAAgB,CAAA;CAC9B;AAID;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAmB,CAAA;AAqErD,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAiB1E;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAKnE;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB;AAkBD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAoB1F;AAuCD,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,cAAc,IAAI,MAAM,CAAA;CACzB;AAED,6DAA6D;AAC7D,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,iBAAiB;IAGvC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CA+BvE"}
+{"version":3,"file":"paste-images.d.ts","sourceRoot":"","sources":["../../src/paste-images.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAK1E,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,yDAAyD;AACzD,eAAO,MAAM,kBAAkB,sCAAsC,CAAA;AAErE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,sCAAsC,CAAA;AAErE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,6FAA6F;IAC7F,QAAQ,EAAE,OAAO,CAAA;IACjB,iGAAiG;IACjG,UAAU,CAAC,EAAE,gBAAgB,CAAA;CAC9B;AAKD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAmB,CAAA;AAqErD,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAiB1E;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAKnE;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB;AAkBD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,CAAC,CAmBpB;AA2DD,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAID,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,cAAc,IAAI,MAAM,CAAA;IACxB,gBAAgB,CAAC,IAAI,MAAM,GAAG,SAAS,CAAA;IACvC,iBAAiB,CAAC,IAAI,sBAAsB,CAAA;CAC7C;AAED,6DAA6D;AAC7D,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,iBAAiB;IAG7C,OAAO,CAAC,iBAAiB;IAUnB,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CA+CvE"}

package/lib/types/paths.d.ts

@@ -5,6 +5,7 @@
  * link is allowed only when its real target stays inside the fence.
  * @module dsh-vision-toolkit/paths
  */
+import type { Stats } from 'node:fs';
 /** Supported input image extensions (the upstream client's allowlist). */
 export declare const SUPPORTED_IMAGE_EXTENSIONS: readonly [".png", ".jpg", ".jpeg", ".gif", ".webp"];
 /** Resolved path policy for one tool invocation. */
@@ -15,9 +16,20 @@ export interface PathPolicy {
     tempDir: string;
     /** Real allowed roots: workspace, platform temp, and configured directories. */
     allowedDirs: string[];
+    /** Real plugin-managed root containing artifacts and transient files. */
+    storageRoot: string;
     /** Real plugin-managed output directory inside the fence. */
     outputDir: string;
 }
+/** Resolved plugin storage for one workspace. */
+export interface WorkspaceStorage {
+    /** Real workspace root. */
+    workspace: string;
+    /** Real plugin-managed root for this workspace. */
+    root: string;
+    /** Absolute user-visible spelling of the same managed root. */
+    visibleRoot: string;
+}
 /** Whether `child` equals or lies under `parent` on the same path root. */
 export declare function isWithin(parent: string, child: string): boolean;
 /** Current platform temporary directory before realpath canonicalization. */
@@ -28,16 +40,30 @@ export declare function platformTempDirectory(platform?: NodeJS.Platform, enviro
  * unchanged, and the normal realpath fence still validates the result.
  */
 export declare function normalizePlatformTempPath(raw: string, platform?: NodeJS.Platform, tempDirectory?: string): string;
+/** Stable opaque per-user workspace id used below a shared storage root. */
+export declare function workspaceStorageId(workspace: string, userIdentity?: string): string;
+export declare function assertSecureWorkspaceStorage(info: Stats, requested: string): void;
+/** Resolve a shared base and prove every POSIX ancestor is protected from replacement. */
+export declare function assertSecureSharedStorageBase(requested: string): Promise<string>;
+/** Validate and write-probe a configured shared root before Settings activation. */
+export declare function preflightSharedStorageBase(storageDirRaw: string): Promise<string>;
+/**
+ * Resolve the plugin-managed root for one workspace. Blank configuration keeps
+ * the legacy workspace-local `.dsh-vision-toolkit` directory. A configured
+ * shared root receives one stable, automatically generated workspace child.
+ */
+export declare function resolveWorkspaceStorage(workspaceRaw: string, storageDirRaw?: string): Promise<WorkspaceStorage>;
 /**
- * Build the per-invocation path policy: realpath the workspace, resolve and
- * realpath the platform temp directory and allowed directories, and create
- * the output directory inside the fence.
+ * Build the per-invocation path policy: resolve workspace storage, realpath the
+ * platform temp directory and allowed directories, and create the artifact
+ * directory inside the managed root.
  * @param workspaceRaw - session workspace (or process cwd fallback).
  * @param allowedDirs - configured extra allowed roots.
- * @param outputDirRaw - configured output directory (default `.dsh-vision-toolkit/artifacts`).
+ * @param storageDirRaw - optional shared storage root.
+ * @param readableStorageDirs - previously validated shared roots retained for persisted input paths.
  * @returns the resolved policy.
  */
-export declare function createPathPolicy(workspaceRaw: string, allowedDirs: readonly string[], outputDirRaw?: string): Promise<PathPolicy>;
+export declare function createPathPolicy(workspaceRaw: string, allowedDirs: readonly string[], storageDirRaw?: string, readableStorageDirs?: readonly string[]): Promise<PathPolicy>;
 /**
  * Validate one input image path and return its fence-checked absolute path
  * and byte size.

package/lib/types/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/paths.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAMpC,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,qDAAsD,CAAA;AAE7F,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAA;IACf,gFAAgF;IAChF,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAA;IACnB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG/D;AAQD,6EAA6E;AAC7E,wBAAgB,qBAAqB,CACnC,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,WAAW,GAAE,MAAM,CAAC,UAAwB,GAC3C,MAAM,CAIR;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,aAAa,GAAE,MAAwC,GACtD,MAAM,CAKR;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,YAAY,GAAE,MAES,GACtB,MAAM,CAOR;AAYD,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAKjF;AAED,0FAA0F;AAC1F,wBAAsB,6BAA6B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6CtF;AAyBD,oFAAoF;AACpF,wBAAsB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAqBvF;AAgCD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,YAAY,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAqB3B;AAqBD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,aAAa,CAAC,EAAE,MAAM,EACtB,mBAAmB,GAAE,SAAS,MAAM,EAAO,GAC1C,OAAO,CAAC,UAAU,CAAC,CAqCrB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAEhH;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CA2B1C;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAEzG;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,MAAM,CAiBR;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKhF;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAmB/G;AAED,6EAA6E;AAC7E,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAI/E;AAuBD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAmBjH;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BhH;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB7G;AAED,gEAAgE;AAChE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAIxE"}

package/lib/types/runtime-manager.d.ts

@@ -22,8 +22,15 @@ export interface RuntimeManagerStatus {
     upstream?: UpstreamVersionInfo;
     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) => Promise<VisionToolkitRuntime>;
+export type RuntimeGenerationFactory = (ctx: Context, config: ResolvedVisionToolkitConfig, readableStorageDirs: readonly string[]) => Promise<VisionToolkitRuntime>;
+/** Async commit prerequisite run after preparation and before a generation becomes active. */
+export type RuntimeGenerationBeforePublish = (candidate: PreparedRuntimeGeneration) => Promise<void>;
 /** Internal runtime source with prepare-before-swap semantics. */
 export declare class VisionToolkitRuntimeManager {
     private readonly ctx;
@@ -32,11 +39,22 @@ export declare class VisionToolkitRuntimeManager {
     private generation;
     private reconfigureTicket;
     private lastError;
+    private validatedStartupStorageDir;
+    private readonly readableStorageDirs;
     constructor(ctx: Context, factory?: RuntimeGenerationFactory);
     /** The currently serving runtime; unavailable until one generation prepares. */
     current(): VisionToolkitRuntime;
+    /** Configuration belonging to the currently serving runtime generation. */
+    currentConfig(): ResolvedVisionToolkitConfig;
     /** Whether at least one generation is available. */
     get ready(): boolean;
+    /** Storage config safe for paste writes even when initial runtime preparation failed. */
+    storageGeneration(): RuntimeStorageGeneration;
+    /** Validated storage for best-effort consumers; undefined when startup preflight failed. */
+    validatedStorageDirectory(): string | undefined;
+    private prepareResolvedCandidate;
+    private rememberStorageDirectory;
+    private rememberStorageDirectories;
     /** Resolve and fully prepare a candidate without changing the active runtime. */
     prepareCandidate(raw: VisionToolkitConfig): Promise<PreparedRuntimeGeneration>;
     /**
@@ -44,14 +62,20 @@ export declare class VisionToolkitRuntimeManager {
      * @param candidate - generation returned by {@link prepareCandidate}.
      */
     activateCandidate(candidate: PreparedRuntimeGeneration): void;
-    /** Prepare and publish the initial or explicitly validated generation. */
-    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.
+     */
+    initialize(raw: VisionToolkitConfig, beforePublish?: RuntimeGenerationBeforePublish): Promise<void>;
     /**
      * 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.
      */
-    reconfigure(raw: VisionToolkitConfig): Promise<boolean>;
+    reconfigure(raw: VisionToolkitConfig, beforePublish?: RuntimeGenerationBeforePublish): Promise<boolean>;
     /** Record a failed preflight while retaining the previous generation. */
     recordFailure(error: unknown): void;
     /** Secret-free status snapshot for health/configuration surfaces. */

package/lib/types/runtime-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-manager.d.ts","sourceRoot":"","sources":["../../src/runtime-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAiB,KAAK,2BAA2B,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACvG,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAEzE,wDAAwD;AACxD,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,2BAA2B,CAAA;IACnC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,oBAAoB,CAAA;CAC9B;AAED,4DAA4D;AAC5D,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,2BAA2B,CAAA;IAC1C,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,8CAA8C;AAC9C,MAAM,MAAM,wBAAwB,GAAG,CACrC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,2BAA2B,KAChC,OAAO,CAAC,oBAAoB,CAAC,CAAA;AAqBlC,kEAAkE;AAClE,qBAAa,2BAA2B;IAOpC,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,UAAU,CAAI;IACtB,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,SAAS,CAAoB;gBAGlB,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,wBAAyC;IAGrE,gFAAgF;IAChF,OAAO,IAAI,oBAAoB;IAK/B,oDAAoD;IACpD,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,iFAAiF;IAC3E,gBAAgB,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAUpF;;;OAGG;IACH,iBAAiB,CAAC,SAAS,EAAE,yBAAyB,GAAG,IAAI;IAmB7D,0EAA0E;IACpE,UAAU,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IASzD;;;;OAIG;IACG,WAAW,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IA0B7D,yEAAyE;IACzE,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAInC,qEAAqE;IACrE,MAAM,IAAI,oBAAoB;CAgB/B"}
+{"version":3,"file":"runtime-manager.d.ts","sourceRoot":"","sources":["../../src/runtime-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAiB,KAAK,2BAA2B,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEvG,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAEzE,wDAAwD;AACxD,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,2BAA2B,CAAA;IACnC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,oBAAoB,CAAA;CAC9B;AAED,4DAA4D;AAC5D,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,2BAA2B,CAAA;IAC1C,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,8CAA8C;AAC9C,MAAM,MAAM,wBAAwB,GAAG,CACrC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,2BAA2B,EACnC,mBAAmB,EAAE,SAAS,MAAM,EAAE,KACnC,OAAO,CAAC,oBAAoB,CAAC,CAAA;AAElC,8FAA8F;AAC9F,MAAM,MAAM,8BAA8B,GAAG,CAAC,SAAS,EAAE,yBAAyB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAyBpG,kEAAkE;AAClE,qBAAa,2BAA2B;IASpC,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAT1B,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,UAAU,CAAI;IACtB,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,SAAS,CAAoB;IACrC,OAAO,CAAC,0BAA0B,CAA2B;IAC7D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAoB;gBAGrC,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,wBAAyC;IAGrE,gFAAgF;IAChF,OAAO,IAAI,oBAAoB;IAK/B,2EAA2E;IAC3E,aAAa,IAAI,2BAA2B;IAK5C,oDAAoD;IACpD,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,yFAAyF;IACzF,iBAAiB,IAAI,wBAAwB;IAgB7C,4FAA4F;IAC5F,yBAAyB,IAAI,MAAM,GAAG,SAAS;YAKjC,wBAAwB;IActC,OAAO,CAAC,wBAAwB;IAIhC,OAAO,CAAC,0BAA0B;IAIlC,iFAAiF;IAC3E,gBAAgB,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAMpF;;;OAGG;IACH,iBAAiB,CAAC,SAAS,EAAE,yBAAyB,GAAG,IAAI;IAqB7D;;;;OAIG;IACG,UAAU,CAAC,GAAG,EAAE,mBAAmB,EAAE,aAAa,CAAC,EAAE,8BAA8B,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBzG;;;;;;OAMG;IACG,WAAW,CAAC,GAAG,EAAE,mBAAmB,EAAE,aAAa,CAAC,EAAE,8BAA8B,GAAG,OAAO,CAAC,OAAO,CAAC;IA8B7G,yEAAyE;IACzE,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAInC,qEAAqE;IACrE,MAAM,IAAI,oBAAoB;CAgB/B"}

package/lib/types/runtime.d.ts

@@ -29,6 +29,8 @@ export declare class Semaphore {
     constructor(limit: number);
     /** Whether no active or queued caller still owns this gate. */
     get idle(): boolean;
+    /** Free slots still claimable without queuing. */
+    get available(): number;
     /** Acquire one slot, aborting while queued when `signal` fires. */
     acquire(signal: AbortSignal, permits?: number): Promise<void>;
     /** Release owned permits and wake FIFO waiters whose full weight now fits. */
@@ -197,7 +199,6 @@ export interface LongScreenshotOcrRequest {
     overlap?: number;
     prompt?: string;
     jobs?: number;
-    chunkTimeoutSeconds?: number;
     splitOnly?: boolean;
     resume?: boolean;
 }
@@ -317,6 +318,9 @@ export interface VisionToolkitHealthResult {
         python: HealthCheck;
         dependencies: HealthCheck;
         chrome: HealthCheck;
+        credential: HealthCheck;
+        artifactDirectory: HealthCheck;
+        tempDirectory: HealthCheck;
         service: HealthCheck;
         model: HealthCheck;
     };
@@ -329,7 +333,8 @@ export interface VisionToolkitHealthResult {
 /** Shared per-call execution options. */
 export interface ToolCallOptions {
     signal: AbortSignal;
-    timeoutMs?: number;
+    /** Override the global hard timeout (seconds) for this call. */
+    timeoutSeconds?: number;
     workspace: string;
     /** Session identity for the per-session concurrency cap. */
     sessionId?: string;
@@ -353,26 +358,53 @@ interface ResolvedProviderEnv {
     provider: ResolvedProvider;
     env: UpstreamEnvironment;
 }
+/** Live concurrency accounting returned by the availability query tool. */
+export interface ConcurrencyStatus {
+    /** New tool calls this session may start right now. */
+    available: number;
+    /** Per-session cap on concurrent tool operations. */
+    sessionMax: number;
+    /** Tool operations currently in flight in this session. */
+    sessionInUse: number;
+    /** Free per-session slots. */
+    sessionFree: number;
+    /** Total free model-request slots summed across enabled providers. */
+    modelFree: number;
+    /** Per-provider breakdown. */
+    models: Array<{
+        name: string;
+        concurrency: number;
+        inUse: number;
+        free: number;
+    }>;
+}
 /** Runtime facade used by every native tool. */
 export declare class VisionToolkitRuntime {
     private readonly ctx;
     private readonly config;
+    private readonly readableStorageDirs;
     private readonly semaphores;
     private readonly glanceCache;
     private readonly providerGates;
     private readonly adapter;
-    constructor(ctx: Context, config: ResolvedVisionToolkitConfig, adapter?: UpstreamAdapter);
+    constructor(ctx: Context, config: ResolvedVisionToolkitConfig, adapter?: UpstreamAdapter, readableStorageDirs?: readonly string[]);
     /** Pinned and prepared upstream identity. */
     get upstreamVersion(): UpstreamVersionInfo;
+    /** Per-session cap on concurrent tool operations. */
+    get sessionMaxConcurrency(): number;
+    /** Shared storage root belonging to this immutable runtime generation. */
+    get storageDirectory(): string | undefined;
     /** Stable identity for persisted image descriptions produced by this runtime. */
     get evidenceFingerprint(): string;
     /** Capture the credential and provider identity used by one evidence conversion. */
     captureEvidenceRuntime(): Promise<CapturedEvidenceRuntime>;
-    private timeout;
-    /** Overall operation budget: the slowest enabled provider's timeout, else the global default. */
-    private operationTimeoutMs;
+    /** Global hard timeout (ms) for one tool invocation, honoring the per-call override. */
+    private hardTimeoutMs;
     private operationError;
-    private semaphore;
+    /** Per-session concurrency gate; callers acquire without queuing (excess is rejected). */
+    private sessionGate;
+    /** Live concurrency accounting for the calling session across the enabled provider pool. */
+    concurrencyStatus(options: ToolCallOptions): ConcurrencyStatus;
     private runOperation;
     /** Highest-priority enabled provider, falling back to the first entry. */
     private get primaryProvider();
@@ -403,12 +435,42 @@ export declare class VisionToolkitRuntime {
      */
     private prepareVisionImage;
     /**
-     * Run one online-vision upstream command across the enabled provider pool in
-     * priority order. A provider is skipped when its size limits or concurrency
-     * are exhausted, retried up to its attempt count, and the next provider
-     * takes over on failure. Throws once every provider has failed.
+     * Hedge-based failover across the enabled provider pool. The highest-priority
+     * provider runs first; when one of its requests crosses t1 it keeps running
+     * while the next provider starts in parallel. A provider whose cumulative
+     * request time reaches t2 is terminated. A 429 provider is parked and moved
+     * past immediately; parked providers are revisited at a 10s cadence once
+     * every other provider is exhausted. The result always prefers the earliest
+     * (highest-priority) provider.
+     */
+    private runVisionHedge;
+    /** Remaining request budget (ms) for one provider: the tighter of its t2 and the global deadline. */
+    private providerRequestBudget;
+    /**
+     * Advance to the next provider after one provider reached a terminal
+     * failure. This is what makes failover work for FAST failures too: the
+     * hedge timer only launches the next provider when the current one is SLOW
+     * (crosses t1), so a quick auth/5xx/network failure must explicitly launch
+     * the successor. Never advances when a higher-priority provider superseded
+     * this task, when the whole operation was cancelled, or when the global
+     * deadline has too little room left for another request. `launch` is
+     * idempotent, so an earlier hedge timer cannot cause a double launch.
+     */
+    private advanceAfterFailure;
+    /**
+     * Run one provider to a terminal state: retryable errors retry within
+     * `attempts`, a single request crossing t1 hedges the next provider, and the
+     * provider is terminated once its cumulative time reaches t2. A 429 parks the
+     * provider and moves on. No request is issued once the remaining budget drops
+     * below the configured minimum available time.
+     */
+    private runProviderTask;
+    /**
+     * Revisit parked (429) providers in priority order at a 10s cadence until one
+     * succeeds or every provider exhausts its budget. Returns a success result or
+     * `undefined` when the global deadline or minimum available time stops the loop.
      */
-    private runVisionWithFailover;
+    private revisitRateLimited;
     private glanceCacheKey;
     private runUpstream;
     private probeGeneratedImage;
@@ -436,6 +498,7 @@ export declare class VisionToolkitRuntime {
     dominantColors(request: DominantColorsRequest, options: ToolCallOptions): Promise<DominantColorsResult>;
     /** html_screenshot: render only a path-fenced local HTML file in the pinned Chrome adapter. */
     htmlScreenshot(request: HtmlScreenshotRequest, options: ToolCallOptions): Promise<HtmlScreenshotResult>;
+    private writableDirectoryCheck;
     /** Health: inspect local readiness, and optionally probe one provider's `/models` plus one real multimodal request. */
     health(testConnection: boolean, options: ToolCallOptions, testModel?: boolean, provider?: ResolvedProvider): Promise<VisionToolkitHealthResult>;
     /** Report the packaged upstream snapshot version. */