@anionex/dsh-vision-toolkit 0.1.44 → 0.1.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anionex/dsh-vision-toolkit",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "description": "DeepSeek Harness-native integration for agent-vision-toolkit: image Q&A, OCR, grounding, UI restoration, pixel diff, Artifacts, and Web UI.",
   "keywords": [
     "deepseek",
@@ -55,6 +55,7 @@
     "runtime",
     "vendor",
     "cordis.patch.yml",
+    "CHANGELOG.md",
     "README.md",
     "README.zh.md",
     "LICENSE"
@@ -96,7 +97,7 @@
       "upstreamSkillCommit": "77c24ad5b5d7a123119862893129f939307f1d3f"
     },
     "compatibility": {
-      "dsh": ">=0.1.0-rc.8 <0.2.0",
+      "dsh": ">=0.1.0-rc.8 <0.2.0 || 0.2.0-rc.2",
       "dshReleases": {
         "0.1.0-rc.8": "compatible",
         "0.1.1-rc.1": "compatible",
@@ -109,7 +110,8 @@
         "0.1.3-alpha.2": "compatible",
         "0.1.5-alpha.1": "compatible",
         "0.1.5-alpha.2": "compatible",
-        "0.1.5-rc.1": "compatible"
+        "0.1.5-rc.1": "compatible",
+        "0.2.0-rc.2": "compatible"
       },
       "profiles": [
         "web",
@@ -124,25 +126,25 @@
     "zod": "4.4.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-api-remotes": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-attachment": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-locale": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-input-trigger": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-tool": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-credentials": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-host-webserver": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-session": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-settings": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-skill": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-storage-domain": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-subprocess": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
-    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-agent": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-api-remotes": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-attachment": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-input-trigger": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-tool": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-credentials": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-skill": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-storage-domain": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-subprocess": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.8 <0.2.0 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1 || 0.2.0-rc.2",
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/schemastery": "^3.18.1",
     "react": "^18.2.0"

package/src/client/index.tsx

@@ -43,6 +43,8 @@ const DEFAULT_USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKi
 const BUILT_IN_FREE_VISION_BASE_URL = 'https://vision.anionex.me/v1'
 const BUILT_IN_FREE_VISION_CREDENTIAL = 'ANIONEX_FREE_VISION'
 const BUILT_IN_FREE_VISION_MODEL = 'gemini-3.7-flash'
+const MAX_REASONING_EFFORT_LENGTH = 64
+const REASONING_EFFORT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u
 const AIHUBMIX_TUTORIAL_URL_EN = 'https://github.com/Anionex/dsh-vision-toolkit/blob/main/docs/aihubmix-gemini-vision.md'
 const AIHUBMIX_TUTORIAL_URL_ZH = 'https://github.com/Anionex/dsh-vision-toolkit/blob/main/docs/aihubmix-gemini-vision.zh.md'
 
@@ -66,6 +68,9 @@ const en = {
   credentialHint: 'The built-in free provider needs no user key. For a custom provider, this is the DSH credential reference used to store its key.',
   model: 'Model',
   protocol: 'API protocol',
+  reasoningEffort: 'Vision service reasoning effort',
+  reasoningEffortHint: 'Optional. Common values: none, minimal, low, medium, high, xhigh. Supported values and billing depend on the model or proxy; higher effort may increase tokens, latency, and cost. Requests send store:false, but you should still verify the provider\'s data-retention policy.',
+  reasoningEffortInvalid: 'Vision service reasoning effort must be at most 64 ASCII letters, digits, dots, underscores, or hyphens.',
   anthropicThinking: 'Anthropic thinking',
   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',
@@ -257,6 +262,9 @@ const zh: Record<LocaleKey, string> = {
   credentialHint: '内置免费视觉服务无需用户密钥；切换到自定义服务时，此处是保存其密钥的 DSH 凭据名称。',
   model: '模型名称',
   protocol: 'API 协议',
+  reasoningEffort: '视觉服务推理强度',
+  reasoningEffortHint: '可选。常见值：none、minimal、low、medium、high、xhigh。实际支持值和计费由模型或代理决定；较高强度可能增加 token、延迟和费用。请求会发送 store:false，但仍应核查服务商的数据保留政策。',
+  reasoningEffortInvalid: '视觉服务推理强度最多 64 位，只能包含 ASCII 字母、数字、点、下划线或连字符。',
   anthropicThinking: 'Anthropic thinking',
   anthropicThinkingHint: 'omit 兼容性最好。仅当所选模型明确支持时使用 disabled 或 adaptive；遇到 HTTP 400 时先恢复 omit。',
   userAgent: 'User-Agent',
@@ -486,9 +494,12 @@ interface SettingsValue {
     baseUrl?: string
     credential?: string
     model?: string
-    protocol?: 'openai' | 'anthropic'
+    protocol?: 'openai' | 'responses' | 'anthropic'
+    reasoningEffort?: string
     anthropicThinking?: 'omit' | 'disabled' | 'adaptive'
     userAgent?: string
+    headers?: Record<string, string>
+    sessionHeaders?: string[]
   }
   language?: 'zh' | 'en'
   timeoutMs?: number
@@ -1094,9 +1105,12 @@ interface Draft {
   baseUrl: string
   credential: string
   model: string
-  protocol: 'openai' | 'anthropic'
+  protocol: 'openai' | 'responses' | 'anthropic'
+  reasoningEffort: string
   anthropicThinking: 'omit' | 'disabled' | 'adaptive'
   userAgent: string
+  providerHeaders: Record<string, string>
+  providerSessionHeaders: string[]
   language: 'zh' | 'en'
   timeoutMs: string
   maxImageBytes: string
@@ -1119,8 +1133,11 @@ function draftOf(value: SettingsValue): Draft {
     credential: value.provider?.credential ?? BUILT_IN_FREE_VISION_CREDENTIAL,
     model: value.provider?.model ?? BUILT_IN_FREE_VISION_MODEL,
     protocol: value.provider?.protocol ?? 'openai',
+    reasoningEffort: value.provider?.protocol === 'responses' ? value.provider.reasoningEffort ?? '' : '',
     anthropicThinking: value.provider?.anthropicThinking ?? 'omit',
     userAgent: value.provider?.userAgent ?? DEFAULT_USER_AGENT,
+    providerHeaders: { ...(value.provider?.headers ?? {}) },
+    providerSessionHeaders: [...(value.provider?.sessionHeaders ?? [])],
     language: value.language ?? 'zh',
     timeoutMs: String(value.timeoutMs ?? 30000),
     maxImageBytes: String(value.maxImageBytes ?? 4194304),
@@ -1155,14 +1172,22 @@ function apiKeyFailure(value: string, t: Translate): string | undefined {
 }
 
 function valueOf(draft: Draft, t: Translate): SettingsValue {
+  const reasoningEffort = draft.reasoningEffort.trim()
+  if (draft.protocol === 'responses' && reasoningEffort.length > 0
+    && (reasoningEffort.length > MAX_REASONING_EFFORT_LENGTH || !REASONING_EFFORT_PATTERN.test(reasoningEffort))) {
+    throw new Error(t('reasoningEffortInvalid'))
+  }
   return {
     provider: {
       baseUrl: draft.baseUrl.trim(),
       credential: draft.credential.trim(),
       model: draft.model.trim(),
       protocol: draft.protocol,
+      ...(draft.protocol === 'responses' && reasoningEffort.length > 0 ? { reasoningEffort } : {}),
       anthropicThinking: draft.anthropicThinking,
       userAgent: draft.userAgent.trim(),
+      ...(Object.keys(draft.providerHeaders).length === 0 ? {} : { headers: { ...draft.providerHeaders } }),
+      ...(draft.providerSessionHeaders.length === 0 ? {} : { sessionHeaders: [...draft.providerSessionHeaders] }),
     },
     language: draft.language,
     timeoutMs: positiveInteger(draft.timeoutMs, t('timeout'), t),
@@ -1426,7 +1451,8 @@ function LoadedSettings({ controller, t }: SettingsInjected) {
       <section className="dvt-panel dvt-essential"><div className="dvt-panel-title"><div><h3>{t('provider')}</h3><p>{t('providerHint')}</p></div><span className={`dvt-badge ${snapshot.credential.configured ? 'ok' : 'error'}`}>{snapshot.credential.configured ? t('configured') : t('missing')}</span></div>
         <p className="dvt-tutorial-link"><a href={aihubmixTutorialUrl} target="_blank" rel="noreferrer">{t('aihubmixTutorial')}</a></p>
         <div className="dvt-form-grid">
-          <Field label={t('protocol')}><select disabled={!snapshot.writable || busy} value={draft.protocol} onChange={(event) => { update('protocol', event.target.value as 'openai' | 'anthropic') }}><option value="openai">OpenAI Chat Completions</option><option value="anthropic">Anthropic Messages</option></select></Field>
+          <Field label={t('protocol')}><select disabled={!snapshot.writable || busy} value={draft.protocol} onChange={(event) => { update('protocol', event.target.value as 'openai' | 'responses' | 'anthropic') }}><option value="openai">OpenAI Chat Completions</option><option value="responses">OpenAI Responses</option><option value="anthropic">Anthropic Messages</option></select></Field>
+          {draft.protocol === 'responses' ? <Field label={t('reasoningEffort')} hint={t('reasoningEffortHint')}><Input aria-label={t('reasoningEffort')} disabled={!snapshot.writable || busy} placeholder="none / minimal / low / medium / high / xhigh" value={draft.reasoningEffort} onChange={(event) => { update('reasoningEffort', event.target.value); setDraftError(undefined) }} /></Field> : null}
           <Field label={t('baseUrl')}><Input disabled={!snapshot.writable || busy} value={draft.baseUrl} onChange={(event) => { update('baseUrl', event.target.value) }} /></Field>
           <Field label={t('model')}><Input disabled={!snapshot.writable || busy} value={draft.model} onChange={(event) => { update('model', event.target.value) }} /></Field>
           <Field label={t('apiKey')} hint={keyLocked ? t('apiKeyLocked') : snapshot.credential.source === undefined ? t('apiKeyHint') : `${t('apiKeyHint')} ${t('sourceHint', { source: t('source'), value: credentialSource(snapshot.credential.source, t) })}`}><Input aria-label={t('apiKey')} type="password" autoComplete="new-password" disabled={busy || keyLocked} placeholder={snapshot.credential.configured ? t('apiKeyPlaceholderConfigured') : t('apiKeyPlaceholderMissing')} value={apiKey} onChange={(event) => { setApiKey(event.target.value); setDraftError(undefined) }} /></Field>

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 type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
+import SettingsService, { type SettingsNamespace } from '@deepseek-ai/dsh-settings'
 import { VisionToolkitError } from './errors.ts'
 import {
   BUILT_IN_FREE_VISION_BASE_URL,
@@ -66,12 +66,18 @@ export interface VisionToolkitConfig {
     credential?: string
     /** Multimodal model name. */
     model?: string
-    /** Vision request protocol: OpenAI Chat Completions or Anthropic Messages. */
-    protocol?: 'openai' | 'anthropic'
+    /** Vision request protocol: OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages. */
+    protocol?: 'openai' | 'responses' | 'anthropic'
+    /** Optional provider-specific reasoning effort for OpenAI Responses requests. */
+    reasoningEffort?: string
     /** Anthropic thinking field behavior; `omit` leaves model defaults untouched. */
     anthropicThinking?: 'omit' | 'disabled' | 'adaptive'
     /** Outbound User-Agent for provider requests and connection tests. */
     userAgent?: string
+    /** Non-secret deployment metadata sent with provider requests. */
+    headers?: Record<string, string>
+    /** Header names whose values are derived from the current operation identity. */
+    sessionHeaders?: string[]
   }
   /** Vision output language (`zh` or `en`). */
   language?: 'zh' | 'en'
@@ -134,14 +140,17 @@ export interface VisionToolkitConfig {
 }
 
 /** Configuration schema with the documented P0 defaults. */
-export const Config: Schema<VisionToolkitConfig> = z.object({
+export const LegacyConfig: Schema<VisionToolkitConfig> = z.object({
   provider: z.object({
     baseUrl: z.string().default(BUILT_IN_FREE_VISION_BASE_URL),
     credential: z.string().default(BUILT_IN_FREE_VISION_CREDENTIAL),
     model: z.string().default(BUILT_IN_FREE_VISION_MODEL),
-    protocol: z.union(['openai', 'anthropic'] as const).default('openai'),
+    protocol: z.union(['openai', 'responses', 'anthropic'] as const).default('openai'),
+    reasoningEffort: z.string(),
     anthropicThinking: z.union(['omit', 'disabled', 'adaptive'] as const).default('omit'),
     userAgent: z.string().default(DEFAULT_VISION_USER_AGENT),
+    headers: z.dict(z.string()).default({}),
+    sessionHeaders: z.array(z.string()).default([]),
   }),
   language: z.union(['zh', 'en'] as const).default('zh'),
   timeoutMs: z.number().default(30000),
@@ -164,15 +173,54 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
   }),
 })
 
+/** New Settings reads this metadata; older Schemastery has no .volatile() method. */
+export const VolatileConfig: Schema<VisionToolkitConfig> = (() => {
+  const schema = new z(LegacyConfig.toJSON()) as Schema<VisionToolkitConfig>
+  const markFields = (node: Schema): void => {
+    if (node.type === 'object') {
+      for (const field of Object.values(node.dict ?? {})) markFields(field as Schema)
+    } else {
+      node.meta.volatile = true
+    }
+  }
+  markFields(schema)
+  return schema
+})()
+
+/** Cordis resolves this export before apply(); select the host's schema dialect here. */
+export const Config: Schema<VisionToolkitConfig> = typeof (SettingsService.prototype as { register?: unknown }).register === 'function'
+  ? LegacyConfig
+  : VolatileConfig
+
+/** Resolve Schemastery's live field wrappers into ordinary config data. */
+export function plainVisionConfig(value: VisionToolkitConfig): VisionToolkitConfig {
+  const visit = (current: unknown): unknown => {
+    if (current !== null && typeof current === 'object'
+      && typeof (current as { get?: unknown }).get === 'function'
+      && Symbol.for('cosmokit.volatile.write') in current) {
+      return visit((current as { get(): unknown }).get())
+    }
+    if (Array.isArray(current)) return current.map(visit)
+    if (current !== null && typeof current === 'object') {
+      return Object.fromEntries(Object.entries(current).map(([key, child]) => [key, visit(child)]))
+    }
+    return current
+  }
+  return visit(value) as VisionToolkitConfig
+}
+
 /** Configuration after static validation, with every default materialized. */
 export interface ResolvedVisionToolkitConfig {
   provider: {
     baseUrl: string
     credential: CredentialRef
     model: string
-    protocol: 'openai' | 'anthropic'
+    protocol: 'openai' | 'responses' | 'anthropic'
+    reasoningEffort?: string
     anthropicThinking: 'omit' | 'disabled' | 'adaptive'
     userAgent: string
+    headers: Record<string, string>
+    sessionHeaders: string[]
   }
   language: 'zh' | 'en'
   timeoutMs: number
@@ -199,6 +247,107 @@ const MAX_TIMEOUT_MS = 600000
 const MAX_IMAGE_BYTES = 268435456
 const MAX_IMAGE_PIXELS = 268435456
 const MAX_CONCURRENCY = 16
+const MAX_REASONING_EFFORT_LENGTH = 64
+const REASONING_EFFORT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u
+const MAX_PROVIDER_HEADER_COUNT = 32
+const MAX_PROVIDER_HEADER_NAME_BYTES = 128
+const MAX_PROVIDER_HEADER_VALUE_BYTES = 4096
+const MAX_PROVIDER_HEADER_BYTES = 16 * 1024
+
+/** Headers owned by the client or HTTP transport cannot be taken over by configuration. */
+const RESERVED_PROVIDER_HEADER_NAMES = new Set([
+  'authorization',
+  'connection',
+  'content-length',
+  'content-type',
+  'cookie',
+  'expect',
+  'host',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'proxy-connection',
+  'set-cookie',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+  'user-agent',
+  'www-authenticate',
+  'x-api-key',
+  'anthropic-version',
+])
+
+function headerBytes(value: string): number {
+  return Buffer.byteLength(value, 'utf8')
+}
+
+/** Validate one header without echoing its potentially sensitive value. */
+function assertSendableHeader(field: string, name: string, value: string): void {
+  if (headerBytes(name) > MAX_PROVIDER_HEADER_NAME_BYTES) {
+    throw new VisionToolkitError('config', `${field} entry "${name}" exceeds the ${MAX_PROVIDER_HEADER_NAME_BYTES}-byte name limit`)
+  }
+  if (headerBytes(value) > MAX_PROVIDER_HEADER_VALUE_BYTES) {
+    throw new VisionToolkitError('config', `${field} entry "${name}" exceeds the ${MAX_PROVIDER_HEADER_VALUE_BYTES}-byte value limit`)
+  }
+  try {
+    new Headers([[name, value]])
+  } catch {
+    throw new VisionToolkitError(
+      'config',
+      `${field} entry "${name}" is not a valid HTTP header; use a valid field name and a single-line value`,
+    )
+  }
+}
+
+function normalizeProviderHeaders(provider: NonNullable<VisionToolkitConfig['provider']>): {
+  headers: Record<string, string>
+  sessionHeaders: string[]
+} {
+  const normalized = new Map<string, string>()
+  for (const [rawName, value] of Object.entries(provider.headers ?? {})) {
+    const name = rawName.trim().toLowerCase()
+    if (name.length === 0) throw new VisionToolkitError('config', 'provider.headers has an entry with an empty name')
+    if (RESERVED_PROVIDER_HEADER_NAMES.has(name)) {
+      throw new VisionToolkitError('config', `provider.headers must not set "${name}"; the client or HTTP transport owns it`)
+    }
+    if (normalized.has(name)) {
+      throw new VisionToolkitError('config', `provider.headers contains the duplicate name "${name}"`)
+    }
+    assertSendableHeader('provider.headers', name, value)
+    normalized.set(name, value)
+  }
+
+  const sessions = new Set<string>()
+  for (const rawName of provider.sessionHeaders ?? []) {
+    const name = rawName.trim().toLowerCase()
+    if (name.length === 0) throw new VisionToolkitError('config', 'provider.sessionHeaders has an empty entry')
+    if (RESERVED_PROVIDER_HEADER_NAMES.has(name)) {
+      throw new VisionToolkitError('config', `provider.sessionHeaders must not name "${name}"; the client or HTTP transport owns it`)
+    }
+    if (sessions.has(name)) {
+      throw new VisionToolkitError('config', `provider.sessionHeaders contains the duplicate name "${name}"`)
+    }
+    if (normalized.has(name)) {
+      throw new VisionToolkitError('config', `provider.headers and provider.sessionHeaders both name "${name}"`)
+    }
+    assertSendableHeader('provider.sessionHeaders', name, '0'.repeat(32))
+    sessions.add(name)
+  }
+
+  if (normalized.size + sessions.size > MAX_PROVIDER_HEADER_COUNT) {
+    throw new VisionToolkitError('config', `provider headers must contain at most ${MAX_PROVIDER_HEADER_COUNT} entries in total`)
+  }
+  const compareNames = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0
+  const entries = [...normalized.entries()].sort(([left], [right]) => compareNames(left, right))
+  const sessionHeaders = [...sessions].sort(compareNames)
+  const totalBytes = entries.reduce((total, [name, value]) => total + headerBytes(name) + headerBytes(value) + 4, 0)
+    + sessionHeaders.reduce((total, name) => total + headerBytes(name) + 32 + 4, 0)
+  if (totalBytes > MAX_PROVIDER_HEADER_BYTES) {
+    throw new VisionToolkitError('config', `provider headers exceed the ${MAX_PROVIDER_HEADER_BYTES}-byte total limit`)
+  }
+  return { headers: Object.fromEntries(entries), sessionHeaders }
+}
 
 /**
  * Validate and normalize a config object (partial inputs receive the same
@@ -230,8 +379,16 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
     throw new VisionToolkitError('config', 'provider.model must not be empty')
   }
   const protocol = provider.protocol ?? 'openai'
-  if (protocol !== 'openai' && protocol !== 'anthropic') {
-    throw new VisionToolkitError('config', 'provider.protocol must be "openai" or "anthropic"')
+  if (protocol !== 'openai' && protocol !== 'responses' && protocol !== 'anthropic') {
+    throw new VisionToolkitError('config', 'provider.protocol must be "openai", "responses", or "anthropic"')
+  }
+  const reasoningEffort = protocol === 'responses' ? provider.reasoningEffort?.trim() : undefined
+  if (reasoningEffort !== undefined && reasoningEffort.length > 0
+    && (reasoningEffort.length > MAX_REASONING_EFFORT_LENGTH || !REASONING_EFFORT_PATTERN.test(reasoningEffort))) {
+    throw new VisionToolkitError(
+      'config',
+      `provider.reasoningEffort must be 1-${MAX_REASONING_EFFORT_LENGTH} ASCII letters, digits, dots, underscores, or hyphens`,
+    )
   }
   const anthropicThinking = provider.anthropicThinking ?? 'omit'
   if (anthropicThinking !== 'omit' && anthropicThinking !== 'disabled' && anthropicThinking !== 'adaptive') {
@@ -241,6 +398,7 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
   if (userAgent.length === 0) {
     throw new VisionToolkitError('config', 'provider.userAgent must not be empty')
   }
+  const { headers, sessionHeaders } = normalizeProviderHeaders(provider)
   const language = config.language ?? 'zh'
   if (language !== 'zh' && language !== 'en') {
     throw new VisionToolkitError('config', 'language must be "zh" or "en"')
@@ -289,7 +447,11 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
     .map(provider => provider.trim())
     .filter(provider => provider.length > 0)
   return {
-    provider: { baseUrl, credential, model, protocol, anthropicThinking, userAgent },
+    provider: {
+      baseUrl, credential, model, protocol,
+      ...(reasoningEffort === undefined || reasoningEffort.length === 0 ? {} : { reasoningEffort }),
+      anthropicThinking, userAgent, headers, sessionHeaders,
+    },
     language,
     timeoutMs,
     maxImageBytes,

package/src/evidence-cache.ts

@@ -89,7 +89,10 @@ export function evidenceRuntimeFingerprint(
       },
       model: config.provider.model,
       protocol: config.provider.protocol,
+      reasoningEffort: config.provider.reasoningEffort ?? null,
       anthropicThinking: config.provider.anthropicThinking,
+      headersSha256: hash(JSON.stringify(config.provider.headers)),
+      sessionHeaders: config.provider.sessionHeaders,
       sslVerify: sslVerify ?? null,
       userAgent: config.provider.userAgent,
     },

package/src/image-input-variants.ts

@@ -14,7 +14,7 @@ import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { isAbsolute, join, resolve } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
-import LlmService, { LlmAdapter, contentHasImage } from '@deepseek-ai/dsh-llm'
+import LlmService, { LlmAdapter, contentHasImage, freezeMessage } from '@deepseek-ai/dsh-llm'
 import type {
   ContentBlock,
   GenerateOptions,
@@ -23,6 +23,7 @@ import type {
   LlmProviderInfo,
   LlmResolvedModelInfo,
   Message,
+  ModelMessageSource,
   ResolvedRetryPolicy,
   StreamChunk,
 } from '@deepseek-ai/dsh-llm'
@@ -390,7 +391,11 @@ async function readImageBlock(
     // deadline still bounds it.
     const result = await current.glance(
       { images: [materialized.file], query },
-      { signal: new AbortController().signal, workspace: materialized.workspace },
+      {
+        signal: new AbortController().signal,
+        workspace: materialized.workspace,
+        ...(sessionId === undefined ? {} : { sessionId }),
+      },
     )
     const answer = result.answer.trim()
     if (answer.length === 0) throw new Error('the Vision Toolkit returned an empty description')
@@ -444,7 +449,10 @@ export async function convertImagesToEvidence(
   for (const message of messages) {
     let hint = ''
     let hintSource: VisionHintSource = 'user'
-    if (message.role === 'user' && message.source.kind === 'user') {
+    // `source` is declared required but is optional at runtime: the official
+    // createUserMessage() never writes one. A user-role message that does not
+    // declare its producer is still the current user turn.
+    if (message.role === 'user' && (message.source?.kind ?? 'user') === 'user') {
       const itemUserText = userMessageText(message)
       if (itemUserText.length > 0) {
         lastUserText = itemUserText
@@ -508,6 +516,82 @@ export async function convertImagesToEvidence(
   return converted
 }
 
+/**
+ * Present one delegated request's assistant history under the upstream route,
+ * restoring the adapter-private replay state the host withholds from a facade.
+ *
+ * The host hands `replayState` to a target adapter only while that exact
+ * adapter instance owns both the historical provider and the target provider.
+ * A variant route is a different instance, so history produced under the
+ * upstream route arrives stripped, and history produced under the variant
+ * route is stripped again inside the delegation (the upstream adapter does not
+ * own the variant route either). Losing that state costs provider-native
+ * fidelity — thinking signatures, native effort binding, response ids — which
+ * makes an upstream that needs reasoning continuity answer without thinking
+ * while still being asked for it, and the host reports only a state it could
+ * not use, never one it withheld.
+ *
+ * The durable transcript is the authority for what was withheld: history
+ * messages of this wrapper's own routes are matched by id, and only the request
+ * copy is re-provenanced. The Session itself is never touched, so the durable
+ * log keeps the route the user actually selected.
+ * @param upstream - upstream route the delegated request is dispatched under.
+ * @param messages - messages about to be delegated to that route.
+ * @param transcript - reads the durable Session transcript on demand, if any.
+ * @returns the messages to delegate: the input array when nothing needed repair.
+ */
+function presentUnderUpstreamRoute(
+  upstream: string,
+  messages: Message[],
+  transcript: () => readonly Message[] | undefined,
+): Message[] {
+  const variant = variantProviderId(upstream)
+  let durable: Map<string, Message> | undefined
+  let presented: Message[] | undefined
+  messages.forEach((message, index) => {
+    const source = message.source
+    // Without provenance there is no route to prove and nothing to restore;
+    // skip it exactly like history produced under another route.
+    if (message.role !== 'assistant' || source?.kind !== 'model') return
+    if (source.provider !== upstream && source.provider !== variant) return
+    let replayState = source.replayState
+    if (replayState === undefined) {
+      durable ??= new Map(
+        (transcript() ?? [])
+          .filter(candidate => candidate.role === 'assistant')
+          .map(candidate => [String(candidate.id), candidate] as const),
+      )
+      const withheld = durable.get(String(message.id))
+      // Provenance and shape must still describe this very message: a Session
+      // that was rewritten under us (a fold, a rewind) must not have one
+      // message's state reattached to another's content.
+      if (withheld !== undefined && withheld.source.kind === 'model'
+        && withheld.source.provider === source.provider
+        && withheld.source.replayState !== undefined
+        && sameBlockShape(withheld.content, message.content)) {
+        replayState = withheld.source.replayState
+      }
+    }
+    // Nothing withheld and no re-provenancing to do: leave the message alone.
+    if (source.provider === upstream && replayState === undefined) return
+    const replayed: ModelMessageSource = {
+      kind: 'model',
+      provider: upstream,
+      model: source.model,
+      ...(replayState === undefined ? {} : { replayState }),
+    }
+    presented ??= [...messages]
+    presented[index] = freezeMessage({ ...message, source: replayed })
+  })
+  return presented ?? messages
+}
+
+/** Whether two block lists carry the same block types in the same order. */
+function sameBlockShape(left: readonly ContentBlock[], right: readonly ContentBlock[]): boolean {
+  return left.length === right.length
+    && left.every((block, index) => block.type === right[index]?.type)
+}
+
 /**
  * The adapter behind one variant route: model metadata declares image input,
  * and every stream rewrites image blocks before delegating to the upstream
@@ -539,6 +623,18 @@ export class ImageInputVariantAdapter extends LlmAdapter {
     return this.llm.providerRetryPolicy(this.upstream)
   }
 
+  /**
+   * Read the durable transcript of one Session, when the host still holds it.
+   * Only `presentUnderUpstreamRoute` consumes it, and only for messages whose
+   * replay state the host withheld from this facade route.
+   * @param sessionId - Session whose history is being delegated, if any.
+   * @returns the durable messages, or undefined without a live Session.
+   */
+  private durableTranscript(sessionId: GenerateOptions['sessionId']): readonly Message[] | undefined {
+    if (sessionId === undefined) return undefined
+    return this.ctx.sessions.get(sessionId as never)?.deriveMessages()
+  }
+
   override async listModels(provider: string): Promise<readonly LlmModelInfo[]> {
     const models = await this.llm.listModels(this.upstream)
     return models.filter(shouldWrapModel).map((model) => ({
@@ -605,9 +701,17 @@ export class ImageInputVariantAdapter extends LlmAdapter {
         .digest('hex'),
       storageDir,
     )
-    // Delegate through the host service under the upstream route: the variant
-    // is a wire-only facade, and the upstream route owns retry and replay.
-    yield* this.llm.stream({ ...options, provider: this.upstream, messages })
+    // Delegate through the host service under the upstream route, so the
+    // upstream's own middleware, retry policy, and replay handling still apply.
+    // Replay state is host-owned and route-scoped, so the history this facade
+    // route cannot receive back is restored before that delegation: the durable
+    // log keeps the user's route, only the delegated copy is re-provenanced.
+    const delegated = presentUnderUpstreamRoute(
+      this.upstream,
+      messages,
+      () => this.durableTranscript(options.sessionId),
+    )
+    yield* this.llm.stream({ ...options, provider: this.upstream, messages: delegated })
   }
 }
 

package/src/index.ts

@@ -16,9 +16,8 @@ import type {} from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-settings'
 import { ArtifactAccessController, prepareArtifactAccessKey } from './artifact-access.ts'
 import {
-  Config,
-  VISION_TOOLKIT_SETTINGS_NAMESPACE,
   prepareWatchedSettingsGeneration,
+  plainVisionConfig,
   resolveConfig,
   type ResolvedVisionToolkitConfig,
   type VisionToolkitConfig,
@@ -28,6 +27,7 @@ import { createPasteTakeoverResolver, installImageInputVariants } from './image-
 import { VisionToolkitRuntimeManager } from './runtime-manager.ts'
 import { VISION_SKILLS_SKILL } from './skill.ts'
 import { StorageHistoryStore } from './storage-history.ts'
+import { bindVisionSettings } from './settings-compat.ts'
 import { createVisionTools } from './tools.ts'
 import { PLUGIN_VERSION } from './version.ts'
 import { installVisionToolkitWeb, VisionToolkitWebBackend } from './web.ts'
@@ -35,7 +35,7 @@ import { MAX_PASTE_IMAGE_BYTES, PastedImageBackend } from './paste-images.ts'
 
 export const name = '@anionex/dsh-vision-toolkit'
 
-export { Config }
+export { Config } from './config.ts'
 
 export const inject = ['tools', 'credentials', 'skills', 'subprocess', 'settings', 'agents', 'sessions']
 
@@ -45,11 +45,7 @@ export async function apply(ctx: Context, config: VisionToolkitConfig = {}): Pro
   // or Tool becomes visible. The custom Web editor preflights runtime changes
   // before persistence; hand-edited settings still fail loud here or retain
   // the last serving generation when changed live.
-  const settings = ctx.settings.register(VISION_TOOLKIT_SETTINGS_NAMESPACE, Config, {
-    base: config,
-    applies: 'live',
-    validate: (value) => { resolveConfig(value) },
-  })
+  const settings = bindVisionSettings(ctx, plainVisionConfig(config))
   const manager = new VisionToolkitRuntimeManager(ctx)
   const artifacts = new ArtifactAccessController(await prepareArtifactAccessKey())
   const lifecycle = new AbortController()