@mengruo/dsh-vision-toolkit 0.1.1 → 0.1.3

package/src/config.ts

@@ -9,7 +9,7 @@
 import z from '@deepseek-ai/schemastery'
 import type Schema from '@deepseek-ai/schemastery'
 import { credentialRef, type CredentialRef } from '@deepseek-ai/dsh-credentials'
-import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
 import { VisionToolkitError } from './errors.ts'
 import {
   BUILT_IN_FREE_VISION_BASE_URL,
@@ -24,8 +24,21 @@ export {
   BUILT_IN_FREE_VISION_MODEL,
 } from './defaults.ts'
 
+/**
+ * The namespace pattern the removed `settingsNamespace` helper enforced.
+ * dsh 0.1.2-alpha dropped that export; importing a missing named export is a
+ * module-evaluation error that stops the host from booting, so the check is
+ * inlined here instead of imported. The namespace is a static string, so no
+ * runtime dependency on `@deepseek-ai/dsh-settings` is needed.
+ */
+const SETTINGS_NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*$/
+
 /** Settings document namespace owned by this plugin. */
-export const VISION_TOOLKIT_SETTINGS_NAMESPACE = settingsNamespace('vision-toolkit')
+export const VISION_TOOLKIT_SETTINGS_NAMESPACE = 'vision-toolkit' as SettingsNamespace
+
+if (!SETTINGS_NAMESPACE_PATTERN.test(VISION_TOOLKIT_SETTINGS_NAMESPACE)) {
+  throw new TypeError(`settings namespace "${VISION_TOOLKIT_SETTINGS_NAMESPACE}" must match ${String(SETTINGS_NAMESPACE_PATTERN)}`)
+}
 
 /** Browser-compatible default shared with the vendored Python client. */
 export const DEFAULT_VISION_USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36'
@@ -64,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. */
@@ -96,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. */
@@ -166,14 +185,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),
@@ -203,7 +225,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
@@ -223,7 +246,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
@@ -241,7 +266,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
@@ -251,7 +276,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
@@ -330,9 +354,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) {
@@ -362,7 +390,8 @@ function resolveProvider(
     protocol,
     anthropicThinking,
     userAgent,
-    timeoutMs,
+    t1Seconds,
+    t2Seconds,
     maxImageBytes,
     maxImagePixels,
     concurrency,
@@ -384,9 +413,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) {
@@ -423,7 +460,7 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
   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`)
@@ -444,7 +481,9 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
     },
     providers,
     language,
-    timeoutMs,
+    hardTimeoutSeconds,
+    sessionMaxConcurrency,
+    minAvailableSeconds,
     maxImageBytes,
     maxImagePixels,
     concurrency,

package/src/errors.ts

@@ -16,6 +16,7 @@ export const VISION_TOOLKIT_ERROR_CODES = [
   'timeout',
   'cancelled',
   'path',
+  'rate_limit',
 ] as const
 
 /** Stable machine-readable error category. */

package/src/evidence-cache.ts

@@ -108,7 +108,9 @@ 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,