@mengruo/dsh-vision-toolkit 0.1.2 → 0.1.4

package/src/client/index.tsx

@@ -71,15 +71,28 @@ const en = {
   anthropicThinkingHint: 'omit has the broadest compatibility. Use disabled or adaptive only when the selected model documents that mode; restore omit first after HTTP 400.',
   userAgent: 'User-Agent',
   language: 'Output language',
-  limits: 'Limits',
+  limits: 'Timeout and concurrency',
   timeout: 'Request timeout (ms)',
+  t1: 't1 — single-request hedge (s)',
+  t1Hint: 'When a single request exceeds t1, keep it running and start the next model in parallel.',
+  t2: 't2 — cumulative cutoff (s)',
+  t2Hint: 'Terminate the model once its accumulated request time reaches t2.',
+  hardTimeout: 'Global hard timeout (s)',
+  hardTimeoutHint: 'Wall-clock ceiling for one tool call; on timeout every request is cancelled.',
+  sessionConcurrency: 'Per-session max concurrency',
+  sessionConcurrencyHint: 'Maximum concurrent vision calls in one session; excess is rejected immediately.',
+  minAvailable: 'Minimum available time (s)',
+  minAvailableHint: 'No new request is issued once the remaining budget drops below this value.',
   maxBytes: 'Maximum image bytes',
   maxPixels: 'Maximum image pixels',
-  concurrency: 'Concurrent calls per session',
+  concurrency: 'Concurrency (per model)',
   runtime: 'Runtime',
   runtimeMode: 'Runtime mode',
   toolkitPath: 'Pinned checkout path',
   python: 'Python override',
+  storage: 'Local files',
+  storageDir: 'Default save directory',
+  storageDirHint: 'Leave blank to keep .dsh-vision-toolkit in each workspace. On POSIX systems, set an absolute shared root such as /tmp/dsh-vision-toolkit to store artifacts, pasted images, and caches in an automatically generated per-user, workspace-specific child directory. Windows shared roots remain disabled until their ACLs can be verified safely.',
   allowedDirs: 'Additional allowed directories',
   allowedDirsHint: 'One path per line. The session workspace is always allowed.',
   save: 'Save and apply',
@@ -102,7 +115,7 @@ const en = {
   connectionHint: 'The API connection test only queries GET /models. The vision model test sends the bundled diagnostic image and verifies one real multimodal request.',
   saveBeforeTesting: 'Save service changes before testing the connection.',
   advanced: 'Advanced settings',
-  advancedHint: 'Credential name, provider compatibility, output language, resource limits, runtime source, Python, and additional readable directories.',
+  advancedHint: 'Credential name, provider compatibility, output language, resource limits, default save directory, runtime source, Python, and additional readable directories.',
   imageInput: 'Image input',
   hiddenVariants: 'Transparent variant routing',
   hiddenVariantsLabel: 'Keep the original model names and enable images automatically',
@@ -274,15 +287,28 @@ const zh: Record<LocaleKey, string> = {
   anthropicThinkingHint: 'omit 兼容性最好。仅当所选模型明确支持时使用 disabled 或 adaptive；遇到 HTTP 400 时先恢复 omit。',
   userAgent: 'User-Agent',
   language: '结果语言',
-  limits: '资源与并发限制',
+  limits: '超时与并发限制',
   timeout: '单次请求超时（毫秒）',
+  t1: 't1（单次请求阈值，秒）',
+  t1Hint: '单次请求超过 t1 时，继续请求并并行调用下一个模型。',
+  t2: 't2（累计终止阈值，秒）',
+  t2Hint: '该模型累计请求时长达到 t2 时终止。',
+  hardTimeout: '全局硬超时（秒）',
+  hardTimeoutHint: '单次工具调用的墙钟上限，超时终止所有任务。',
+  sessionConcurrency: '单会话最大并发',
+  sessionConcurrencyHint: '同一会话最多同时运行的视觉任务数，超出直接返回错误。',
+  minAvailable: '最低可用时间（秒）',
+  minAvailableHint: '剩余时间额度低于该值时不再发起新请求。',
   maxBytes: '单张图片大小上限（字节）',
   maxPixels: '单张图片最大像素数',
-  concurrency: '单个会话最多并发任务数',
+  concurrency: '并发（每个模型）',
   runtime: '工具运行环境',
   runtimeMode: '环境来源',
   toolkitPath: 'agent-vision-toolkit 目录',
   python: 'Python 解释器（可选）',
+  storage: '本地文件',
+  storageDir: '默认保存目录',
+  storageDirHint: '留空时继续在各工作区创建 .dsh-vision-toolkit。在 POSIX 系统上填写绝对路径共享根目录（例如 /tmp/dsh-vision-toolkit）后，产物、粘贴图片和缓存会保存到自动生成的当前用户、工作区专属子目录中。Windows 共享目录会保持禁用，直到能够安全校验 ACL 权限。',
   allowedDirs: '允许读取的其他目录',
   allowedDirsHint: '每行填写一个目录。当前会话的工作目录始终可以读取，无需重复填写。',
   save: '保存设置',
@@ -305,7 +331,7 @@ const zh: Record<LocaleKey, string> = {
   connectionHint: '“测试 API 连接”只请求 GET /models；“测试视觉模型”会发送插件自带的诊断图片，验证一次真实多模态调用。',
   saveBeforeTesting: '修改服务配置后，请先保存，再执行 API 或视觉模型测试。',
   advanced: '高级设置',
-  advancedHint: '凭据名称、服务兼容参数、结果语言、资源限制、运行环境来源、Python 和额外可读目录。一般无需修改。',
+  advancedHint: '凭据名称、服务兼容参数、结果语言、资源限制、默认保存目录、运行环境来源、Python 和额外可读目录。一般无需修改。',
   imageInput: '图片输入',
   hiddenVariants: '透明变体路由',
   hiddenVariantsLabel: '保留原模型名并自动启用图片能力',
@@ -501,7 +527,8 @@ interface ProviderValue {
   protocol?: 'openai' | 'anthropic'
   anthropicThinking?: 'omit' | 'disabled' | 'adaptive'
   userAgent?: string
-  timeoutMs?: number
+  t1Seconds?: number
+  t2Seconds?: number
   maxImageBytes?: number
   maxImagePixels?: number
   concurrency?: number
@@ -519,11 +546,15 @@ interface SettingsValue {
   }
   providers?: ProviderValue[]
   language?: 'zh' | 'en'
-  timeoutMs?: number
+  hardTimeoutSeconds?: number
+  sessionMaxConcurrency?: number
+  minAvailableSeconds?: number
   maxImageBytes?: number
   maxImagePixels?: number
   concurrency?: number
   runtime?: { mode?: 'managed' | 'external'; agentVisionToolkitPath?: string; python?: string }
+  storageDir?: string
+  storageHistory?: string[]
   allowedDirs?: string[]
   imageInputVariants?: {
     enabled?: boolean
@@ -1140,7 +1171,8 @@ interface ProviderDraft {
   protocol: 'openai' | 'anthropic'
   anthropicThinking: 'omit' | 'disabled' | 'adaptive'
   userAgent: string
-  timeoutMs: string
+  t1Seconds: string
+  t2Seconds: string
   maxImageBytes: string
   maxImagePixels: string
   concurrency: string
@@ -1150,13 +1182,16 @@ interface ProviderDraft {
 interface Draft {
   providers: ProviderDraft[]
   language: 'zh' | 'en'
-  timeoutMs: string
+  hardTimeoutSeconds: string
+  sessionMaxConcurrency: string
+  minAvailableSeconds: string
   maxImageBytes: string
   maxImagePixels: string
   concurrency: string
   runtimeMode: 'managed' | 'external'
   toolkitPath: string
   python: string
+  storageDir: string
   allowedDirs: string
   hiddenVariants: boolean
   variantEnabled: boolean
@@ -1179,7 +1214,6 @@ function autoCredentialName(id: string): string {
 }
 
 interface ProviderDefaults {
-  timeoutMs: number
   maxImageBytes: number
   maxImagePixels: number
   concurrency: number
@@ -1197,7 +1231,8 @@ function emptyProviderDraft(defaults: ProviderDefaults): ProviderDraft {
     protocol: 'openai',
     anthropicThinking: 'omit',
     userAgent: DEFAULT_USER_AGENT,
-    timeoutMs: String(defaults.timeoutMs),
+    t1Seconds: '90',
+    t2Seconds: '90',
     maxImageBytes: String(defaults.maxImageBytes),
     maxImagePixels: String(defaults.maxImagePixels),
     concurrency: String(defaults.concurrency),
@@ -1218,7 +1253,8 @@ function providerDraftOf(value: ProviderValue | undefined, fallback: ProviderVal
     protocol: source?.protocol ?? 'openai',
     anthropicThinking: source?.anthropicThinking ?? 'omit',
     userAgent: source?.userAgent ?? DEFAULT_USER_AGENT,
-    timeoutMs: String(source?.timeoutMs ?? defaults.timeoutMs),
+    t1Seconds: String(source?.t1Seconds ?? 90),
+    t2Seconds: String(source?.t2Seconds ?? 90),
     maxImageBytes: String(source?.maxImageBytes ?? defaults.maxImageBytes),
     maxImagePixels: String(source?.maxImagePixels ?? defaults.maxImagePixels),
     concurrency: String(source?.concurrency ?? defaults.concurrency),
@@ -1228,7 +1264,6 @@ function providerDraftOf(value: ProviderValue | undefined, fallback: ProviderVal
 
 function draftOf(value: SettingsValue): Draft {
   const globalDefaults: ProviderDefaults = {
-    timeoutMs: value.timeoutMs ?? 30000,
     maxImageBytes: value.maxImageBytes ?? 4194304,
     maxImagePixels: value.maxImagePixels ?? 20000000,
     concurrency: value.concurrency ?? 4,
@@ -1240,13 +1275,16 @@ function draftOf(value: SettingsValue): Draft {
   return {
     providers,
     language: value.language ?? 'zh',
-    timeoutMs: String(globalDefaults.timeoutMs),
+    hardTimeoutSeconds: String(value.hardTimeoutSeconds ?? 180),
+    sessionMaxConcurrency: String(value.sessionMaxConcurrency ?? 6),
+    minAvailableSeconds: String(value.minAvailableSeconds ?? 20),
     maxImageBytes: String(globalDefaults.maxImageBytes),
     maxImagePixels: String(globalDefaults.maxImagePixels),
     concurrency: String(globalDefaults.concurrency),
     runtimeMode: value.runtime?.mode ?? 'managed',
     toolkitPath: value.runtime?.agentVisionToolkitPath ?? '',
     python: value.runtime?.python ?? '',
+    storageDir: value.storageDir ?? '',
     allowedDirs: (value.allowedDirs ?? []).join('\n'),
     hiddenVariants: value.imageInputVariants?.hidden ?? true,
     variantEnabled: value.imageInputVariants?.enabled ?? true,
@@ -1282,7 +1320,8 @@ function valueOf(draft: Draft, t: Translate): SettingsValue {
     protocol: provider.protocol,
     anthropicThinking: provider.anthropicThinking,
     ...(provider.userAgent.trim() === DEFAULT_USER_AGENT ? {} : { userAgent: provider.userAgent.trim() }),
-    ...(provider.timeoutMs.trim().length === 0 ? {} : { timeoutMs: positiveInteger(provider.timeoutMs, t('timeout'), t) }),
+    ...(provider.t1Seconds.trim().length === 0 ? {} : { t1Seconds: positiveInteger(provider.t1Seconds, t('t1'), t) }),
+    ...(provider.t2Seconds.trim().length === 0 ? {} : { t2Seconds: positiveInteger(provider.t2Seconds, t('t2'), t) }),
     ...(provider.maxImageBytes.trim().length === 0 ? {} : { maxImageBytes: positiveInteger(provider.maxImageBytes, t('maxBytes'), t) }),
     ...(provider.maxImagePixels.trim().length === 0 ? {} : { maxImagePixels: positiveInteger(provider.maxImagePixels, t('maxPixels'), t) }),
     ...(provider.concurrency.trim().length === 0 ? {} : { concurrency: positiveInteger(provider.concurrency, t('concurrency'), t) }),
@@ -1300,7 +1339,9 @@ function valueOf(draft: Draft, t: Translate): SettingsValue {
     },
     providers,
     language: draft.language,
-    timeoutMs: positiveInteger(draft.timeoutMs, t('timeout'), t),
+    hardTimeoutSeconds: positiveInteger(draft.hardTimeoutSeconds, t('hardTimeout'), t),
+    sessionMaxConcurrency: positiveInteger(draft.sessionMaxConcurrency, t('sessionConcurrency'), t),
+    minAvailableSeconds: positiveInteger(draft.minAvailableSeconds, t('minAvailable'), t),
     maxImageBytes: positiveInteger(draft.maxImageBytes, t('maxBytes'), t),
     maxImagePixels: positiveInteger(draft.maxImagePixels, t('maxPixels'), t),
     concurrency: positiveInteger(draft.concurrency, t('concurrency'), t),
@@ -1309,6 +1350,7 @@ function valueOf(draft: Draft, t: Translate): SettingsValue {
       ...(draft.runtimeMode === 'external' ? { agentVisionToolkitPath: draft.toolkitPath.trim() } : {}),
       ...(draft.python.trim().length === 0 ? {} : { python: draft.python.trim() }),
     },
+    ...(draft.storageDir.trim().length === 0 ? {} : { storageDir: draft.storageDir.trim() }),
     allowedDirs: draft.allowedDirs.split(/\r?\n/).map(entry => entry.trim()).filter(Boolean),
     imageInputVariants: {
       ...(draft.variantEnabled ? {} : { enabled: false }),
@@ -1488,7 +1530,6 @@ function LoadedSettings({ controller, t }: SettingsInjected) {
     setDraft(current => current === undefined ? current : {
       ...current,
       providers: [...current.providers, emptyProviderDraft({
-        timeoutMs: Number(current.timeoutMs) || 30000,
         maxImageBytes: Number(current.maxImageBytes) || 4194304,
         maxImagePixels: Number(current.maxImagePixels) || 20000000,
         concurrency: Number(current.concurrency) || 4,
@@ -1626,7 +1667,8 @@ function LoadedSettings({ controller, t }: SettingsInjected) {
               <Field label={t('protocol')}><select aria-label={t('protocol')} disabled={!snapshot.writable || busy} value={selectedProvider.protocol} onChange={(event) => { updateProvider(selectedIndex, 'protocol', event.target.value as 'openai' | 'anthropic') }}><option value="openai">OpenAI Chat Completions</option><option value="anthropic">Anthropic Messages</option></select></Field>
               {selectedProvider.protocol === 'anthropic' ? <Field label={t('anthropicThinking')} hint={t('anthropicThinkingHint')}><select aria-label={t('anthropicThinking')} value={selectedProvider.anthropicThinking} onChange={(event) => { updateProvider(selectedIndex, 'anthropicThinking', event.target.value as 'omit' | 'disabled' | 'adaptive') }}><option value="omit">omit (widest compatibility)</option><option value="disabled">disabled (model support required)</option><option value="adaptive">adaptive (model support required)</option></select></Field> : null}
               <Field label={t('userAgent')}><Input aria-label={t('userAgent')} value={selectedProvider.userAgent} onChange={(event) => { updateProvider(selectedIndex, 'userAgent', event.target.value) }} /></Field>
-              <Field label={t('timeout')}><Input aria-label={t('timeout')} inputMode="numeric" value={selectedProvider.timeoutMs} onChange={(event) => { updateProvider(selectedIndex, 'timeoutMs', event.target.value) }} /></Field>
+              <Field label={t('t1')} hint={t('t1Hint')}><Input aria-label={t('t1')} inputMode="numeric" value={selectedProvider.t1Seconds} onChange={(event) => { updateProvider(selectedIndex, 't1Seconds', event.target.value) }} /></Field>
+              <Field label={t('t2')} hint={t('t2Hint')}><Input aria-label={t('t2')} inputMode="numeric" value={selectedProvider.t2Seconds} onChange={(event) => { updateProvider(selectedIndex, 't2Seconds', event.target.value) }} /></Field>
               <Field label={t('maxBytes')}><Input aria-label={t('maxBytes')} inputMode="numeric" value={selectedProvider.maxImageBytes} onChange={(event) => { updateProvider(selectedIndex, 'maxImageBytes', event.target.value) }} /></Field>
               <Field label={t('maxPixels')}><Input aria-label={t('maxPixels')} inputMode="numeric" value={selectedProvider.maxImagePixels} onChange={(event) => { updateProvider(selectedIndex, 'maxImagePixels', event.target.value) }} /></Field>
               <Field label={t('concurrency')}><Input aria-label={t('concurrency')} inputMode="numeric" value={selectedProvider.concurrency} onChange={(event) => { updateProvider(selectedIndex, 'concurrency', event.target.value) }} /></Field>
@@ -1703,13 +1745,23 @@ function LoadedSettings({ controller, t }: SettingsInjected) {
             <Field label={t('language')}><select value={draft.language} onChange={(event) => { update('language', event.target.value as 'zh' | 'en') }}><option value="zh">中文</option><option value="en">English</option></select></Field>
           </div></section>
 
+          <section className="dvt-panel"><div className="dvt-panel-title"><h3>{t('limits')}</h3></div><div className="dvt-form-grid">
+            <Field label={t('hardTimeout')} hint={t('hardTimeoutHint')}><Input aria-label={t('hardTimeout')} inputMode="numeric" value={draft.hardTimeoutSeconds} onChange={(event) => { update('hardTimeoutSeconds', event.target.value) }} /></Field>
+            <Field label={t('sessionConcurrency')} hint={t('sessionConcurrencyHint')}><Input aria-label={t('sessionConcurrency')} inputMode="numeric" value={draft.sessionMaxConcurrency} onChange={(event) => { update('sessionMaxConcurrency', event.target.value) }} /></Field>
+            <Field label={t('minAvailable')} hint={t('minAvailableHint')}><Input aria-label={t('minAvailable')} inputMode="numeric" value={draft.minAvailableSeconds} onChange={(event) => { update('minAvailableSeconds', event.target.value) }} /></Field>
+          </div></section>
+
           <section className="dvt-panel"><div className="dvt-panel-title"><h3>{t('imageInput')}</h3></div><label className="dvt-check"><input type="checkbox" checked={draft.hiddenVariants} disabled={!snapshot.writable || busy} onChange={(event) => { update('hiddenVariants', event.target.checked) }} /><span>{t('hiddenVariantsLabel')}</span><small>{t('hiddenVariantsHint')}</small></label></section>
 
+          <section className="dvt-panel"><div className="dvt-panel-title"><h3>{t('storage')}</h3></div><div className="dvt-form-grid">
+            <Field label={t('storageDir')} hint={t('storageDirHint')}><Input aria-label={t('storageDir')} placeholder="/tmp/dsh-vision-toolkit" value={draft.storageDir} onChange={(event) => { update('storageDir', event.target.value) }} /></Field>
+            <Field label={t('allowedDirs')} hint={t('allowedDirsHint')}><textarea rows={3} value={draft.allowedDirs} onChange={(event) => { update('allowedDirs', event.target.value) }} /></Field>
+          </div></section>
+
           <section className="dvt-panel"><div className="dvt-panel-title"><h3>{t('runtime')}</h3><span className={`dvt-badge ${snapshot.runtime.ready ? 'ok' : 'error'}`}>{snapshot.runtime.ready ? snapshot.runtime.upstream?.source === 'managed' ? t('runtimeManaged') : snapshot.runtime.upstream?.source === 'external' ? t('runtimeExternal') : t('runtimeReady') : t('runtimeUnavailable')}</span></div><div className="dvt-form-grid">
             <Field label={t('runtimeMode')}><select value={draft.runtimeMode} onChange={(event) => { update('runtimeMode', event.target.value as 'managed' | 'external') }}><option value="managed">{t('runtimeManaged')}</option><option value="external">{t('runtimeExternal')}</option></select></Field>
             {draft.runtimeMode === 'external' ? <Field label={t('toolkitPath')}><Input value={draft.toolkitPath} onChange={(event) => { update('toolkitPath', event.target.value) }} /></Field> : null}
             <Field label={t('python')}><Input placeholder="python3" value={draft.python} onChange={(event) => { update('python', event.target.value) }} /></Field>
-            <Field label={t('allowedDirs')} hint={t('allowedDirsHint')}><textarea rows={3} value={draft.allowedDirs} onChange={(event) => { update('allowedDirs', event.target.value) }} /></Field>
           </div>
           {snapshot.runtime.upstream === undefined ? null : <div className="dvt-runtime-facts"><code>{snapshot.runtime.upstream.path}</code><code>{snapshot.runtime.upstream.python} · {snapshot.runtime.upstream.pythonVersion}</code><code>{snapshot.runtime.upstream.runtimeHome}</code></div>}
           </section>

package/src/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

@@ -77,8 +77,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. */
@@ -109,13 +111,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. */
@@ -125,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[]
   /**
@@ -179,14 +193,17 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
     protocol: z.union(['openai', 'anthropic'] as const).default('openai'),
     anthropicThinking: z.union(['omit', 'disabled', 'adaptive'] as const).default('omit'),
     userAgent: z.string(),
-    timeoutMs: z.number(),
+    t1Seconds: z.number(),
+    t2Seconds: z.number(),
     maxImageBytes: z.number(),
     maxImagePixels: z.number(),
     concurrency: z.number(),
     attempts: z.number(),
   })).default([]),
   language: z.union(['zh', 'en'] as const).default('zh'),
-  timeoutMs: z.number().default(30000),
+  hardTimeoutSeconds: z.number().default(180),
+  sessionMaxConcurrency: z.number().default(6),
+  minAvailableSeconds: z.number().default(20),
   maxImageBytes: z.number().default(4194304),
   maxImagePixels: z.number().default(20000000),
   concurrency: z.number().default(4),
@@ -195,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),
@@ -216,7 +235,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
@@ -236,7 +256,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
@@ -245,6 +267,8 @@ export interface ResolvedVisionToolkitConfig {
     agentVisionToolkitPath?: string
     python?: string
   }
+  storageDir?: string
+  storageHistory: string[]
   allowedDirs: string[]
   imageInputVariants: {
     enabled: boolean
@@ -254,7 +278,7 @@ export interface ResolvedVisionToolkitConfig {
   }
 }
 
-const MAX_TIMEOUT_MS = 600000
+const MAX_TIMEOUT_SECONDS = 600
 const MAX_IMAGE_BYTES = 268435456
 const MAX_IMAGE_PIXELS = 268435456
 const MAX_CONCURRENCY = 16
@@ -264,7 +288,6 @@ const DEFAULT_PROVIDER_ATTEMPTS = 3
 
 /** Global limits a provider inherits when it does not set its own. */
 interface ProviderDefaults {
-  timeoutMs: number
   maxImageBytes: number
   maxImagePixels: number
   concurrency: number
@@ -343,9 +366,13 @@ function resolveProvider(
   if (userAgent.length === 0) {
     throw new VisionToolkitError('config', `${label}.userAgent must not be empty`)
   }
-  const timeoutMs = input.timeoutMs ?? defaults.timeoutMs
-  if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > MAX_TIMEOUT_MS) {
-    throw new VisionToolkitError('config', `${label}.timeoutMs must be an integer between 1000 and ${MAX_TIMEOUT_MS}`)
+  const t1Seconds = input.t1Seconds ?? 90
+  if (!Number.isInteger(t1Seconds) || t1Seconds < 1 || t1Seconds > MAX_TIMEOUT_SECONDS) {
+    throw new VisionToolkitError('config', `${label}.t1Seconds must be an integer between 1 and ${MAX_TIMEOUT_SECONDS}`)
+  }
+  const t2Seconds = input.t2Seconds ?? 90
+  if (!Number.isInteger(t2Seconds) || t2Seconds < 1 || t2Seconds > MAX_TIMEOUT_SECONDS) {
+    throw new VisionToolkitError('config', `${label}.t2Seconds must be an integer between 1 and ${MAX_TIMEOUT_SECONDS}`)
   }
   const maxImageBytes = input.maxImageBytes ?? defaults.maxImageBytes
   if (!Number.isInteger(maxImageBytes) || maxImageBytes < 1024 || maxImageBytes > MAX_IMAGE_BYTES) {
@@ -375,7 +402,8 @@ function resolveProvider(
     protocol,
     anthropicThinking,
     userAgent,
-    timeoutMs,
+    t1Seconds,
+    t2Seconds,
     maxImageBytes,
     maxImagePixels,
     concurrency,
@@ -397,9 +425,17 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
   if (language !== 'zh' && language !== 'en') {
     throw new VisionToolkitError('config', 'language must be "zh" or "en"')
   }
-  const timeoutMs = config.timeoutMs ?? 30000
-  if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > MAX_TIMEOUT_MS) {
-    throw new VisionToolkitError('config', `timeoutMs must be an integer between 1000 and ${MAX_TIMEOUT_MS}`)
+  const hardTimeoutSeconds = config.hardTimeoutSeconds ?? 180
+  if (!Number.isInteger(hardTimeoutSeconds) || hardTimeoutSeconds < 1 || hardTimeoutSeconds > MAX_TIMEOUT_SECONDS) {
+    throw new VisionToolkitError('config', `hardTimeoutSeconds must be an integer between 1 and ${MAX_TIMEOUT_SECONDS}`)
+  }
+  const sessionMaxConcurrency = config.sessionMaxConcurrency ?? 6
+  if (!Number.isInteger(sessionMaxConcurrency) || sessionMaxConcurrency < 1 || sessionMaxConcurrency > MAX_CONCURRENCY) {
+    throw new VisionToolkitError('config', `sessionMaxConcurrency must be an integer between 1 and ${MAX_CONCURRENCY}`)
+  }
+  const minAvailableSeconds = config.minAvailableSeconds ?? 20
+  if (!Number.isInteger(minAvailableSeconds) || minAvailableSeconds < 1 || minAvailableSeconds > MAX_TIMEOUT_SECONDS) {
+    throw new VisionToolkitError('config', `minAvailableSeconds must be an integer between 1 and ${MAX_TIMEOUT_SECONDS}`)
   }
   const maxImageBytes = config.maxImageBytes ?? 4194304
   if (!Number.isInteger(maxImageBytes) || maxImageBytes < 1024 || maxImageBytes > MAX_IMAGE_BYTES) {
@@ -431,12 +467,16 @@ 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 ?? [])
     .map(provider => provider.trim())
     .filter(provider => provider.length > 0)
-  const providerDefaults: ProviderDefaults = { timeoutMs, maxImageBytes, maxImagePixels, concurrency }
+  const providerDefaults: ProviderDefaults = { maxImageBytes, maxImagePixels, concurrency }
   const configuredProviders = config.providers ?? []
   if (configuredProviders.length > MAX_PROVIDERS) {
     throw new VisionToolkitError('config', `providers must have at most ${MAX_PROVIDERS} entries`)
@@ -457,7 +497,9 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
     },
     providers,
     language,
-    timeoutMs,
+    hardTimeoutSeconds,
+    sessionMaxConcurrency,
+    minAvailableSeconds,
     maxImageBytes,
     maxImagePixels,
     concurrency,
@@ -466,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,
@@ -476,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,11 +5,35 @@
  * @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',

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,
@@ -108,11 +108,14 @@ export function evidenceRuntimeFingerprint(
       attempts: provider.attempts,
     })),
     language: config.language,
-    timeoutMs: config.timeoutMs,
+    hardTimeoutSeconds: config.hardTimeoutSeconds,
+    sessionMaxConcurrency: config.sessionMaxConcurrency,
+    minAvailableSeconds: config.minAvailableSeconds,
     concurrency: config.concurrency,
     maxImageBytes: config.maxImageBytes,
     maxImagePixels: config.maxImagePixels,
     runtime: config.runtime,
+    storageDir: config.storageDir ?? null,
   }))
 }