@anionex/dsh-vision-toolkit 0.1.45 → 0.1.46

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

@@ -391,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')
@@ -445,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
@@ -543,7 +550,9 @@ function presentUnderUpstreamRoute(
   let presented: Message[] | undefined
   messages.forEach((message, index) => {
     const source = message.source
-    if (message.role !== 'assistant' || source.kind !== 'model') return
+    // 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) {

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()

package/src/runtime.ts

@@ -6,7 +6,7 @@
  * @module dsh-vision-toolkit/runtime
  */
 
-import { createHash, randomUUID } from 'node:crypto'
+import { createHash, createHmac, randomBytes, randomUUID } from 'node:crypto'
 import { lstat, mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { basename, extname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -53,6 +53,26 @@ import {
 import { PLUGIN_VERSION } from './version.ts'
 
 const SVG_NAMESPACE = 'http://www.w3.org/2000/svg'
+
+/** Build one process-scoped provider-header resolver with a fresh, non-exported routing key. */
+export function createVisionProviderHeaderResolver(
+  hmacKey: Uint8Array = randomBytes(32),
+): (provider: ResolvedVisionToolkitConfig['provider'], operationKey: string) => Record<string, string> {
+  if (hmacKey.byteLength < 32) throw new TypeError('vision provider session HMAC key must contain at least 32 bytes')
+  const key = Buffer.from(hmacKey)
+  return (provider, operationKey) => {
+    if (provider.sessionHeaders.length === 0) return { ...provider.headers }
+    const sessionRoutingId = createHmac('sha256', key).update(operationKey).digest('hex').slice(0, 32)
+    return {
+      ...provider.headers,
+      ...Object.fromEntries(provider.sessionHeaders.map(name => [name, sessionRoutingId])),
+    }
+  }
+}
+
+/** Same operation key is stable within this process; a restart creates a fresh routing identity. */
+export const visionProviderHeaders = createVisionProviderHeaderResolver()
+
 const VISION_MODEL_TEST_IMAGE = fileURLToPath(new URL('../assets/vision-model-test.png', import.meta.url))
 const VISION_MODEL_TEST_PROMPT = 'This is an explicit service readiness test. Reply with one short sentence confirming that you received the image.'
 
@@ -506,6 +526,8 @@ interface OperationMetrics {
 interface OperationContext {
   signal: AbortSignal
   metrics: OperationMetrics
+  /** Session id when available, otherwise the workspace key used by the concurrency gate. */
+  operationKey: string
 }
 
 const REGION_PATTERN = /^\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*$/
@@ -820,7 +842,7 @@ export class VisionToolkitRuntime {
     const executionDeadline = createDeadline(options.signal, timeoutMs)
     try {
       if (executionDeadline.signal.aborted) throw this.operationError(tool, undefined, executionDeadline)
-      const value = await action({ signal: executionDeadline.signal, metrics })
+      const value = await action({ signal: executionDeadline.signal, metrics, operationKey: semaphore.key })
       if (executionDeadline.signal.aborted) throw this.operationError(tool, undefined, executionDeadline)
       this.ctx.logger.info(
         'dsh-vision-toolkit tool=%s outcome=ok totalMs=%d queueMs=%d upstreamMs=%d images=%d imageBytes=%d imagePixels=%d cacheHits=%d model=%s',
@@ -877,7 +899,14 @@ export class VisionToolkitRuntime {
       VISION_API_KEY: resolved.value,
       VISION_BASE_URL: this.config.provider.baseUrl,
       VISION_MODEL: this.config.provider.model,
-      VISION_API_PROTOCOL: this.config.provider.protocol === 'anthropic' ? 'anthropic' : 'chat_completions',
+      VISION_API_PROTOCOL: this.config.provider.protocol === 'anthropic'
+        ? 'anthropic'
+        : this.config.provider.protocol === 'responses'
+          ? 'responses'
+          : 'chat_completions',
+      ...(this.config.provider.protocol === 'responses' && this.config.provider.reasoningEffort !== undefined
+        ? { VISION_REASONING_EFFORT: this.config.provider.reasoningEffort }
+        : {}),
       VISION_ANTHROPIC_THINKING: this.config.provider.anthropicThinking,
       ...(sslVerify === undefined ? {} : { VISION_SSL_VERIFY: sslVerify }),
       VISION_USER_AGENT: this.config.provider.userAgent,
@@ -1159,6 +1188,7 @@ export class VisionToolkitRuntime {
         baseUrl: env.VISION_BASE_URL,
         model: env.VISION_MODEL,
         protocol: env.VISION_API_PROTOCOL,
+        reasoningEffort: env.VISION_REASONING_EFFORT ?? null,
         anthropicThinking: env.VISION_ANTHROPIC_THINKING,
         sslVerify: env.VISION_SSL_VERIFY ?? null,
         userAgent: env.VISION_USER_AGENT,
@@ -1176,16 +1206,25 @@ export class VisionToolkitRuntime {
   ): Promise<UpstreamRunResult> {
     const started = Date.now()
     if (env !== undefined) operation.metrics.usedVisionService = true
+    const headers = env === undefined ? undefined : visionProviderHeaders(this.config.provider, operation.operationKey)
     const result = await this.adapter.run(tool, args, {
       signal: operation.signal,
-      ...(env === undefined ? {} : { env }),
+      ...(env === undefined
+        ? {}
+        : {
+            env: headers !== undefined && Object.keys(headers).length > 0
+              ? { ...env, DSH_VISION_EXTRA_HEADERS: JSON.stringify(headers) }
+              : env,
+          }),
     })
     operation.metrics.upstreamMs += Date.now() - started
     if (result.outcome.exitCode !== 0) {
       throw this.adapter.classifyFailure(tool, result, {
         timedOut: false,
         cancelled: operation.signal.aborted,
-        ...(env === undefined ? {} : { secrets: [env.VISION_API_KEY] }),
+        ...(env === undefined
+          ? {}
+          : { secrets: [env.VISION_API_KEY, ...Object.values(headers ?? {})] }),
       })
     }
     if (result.stdoutTruncated || result.stderrTruncated) {
@@ -2109,6 +2148,7 @@ export class VisionToolkitRuntime {
             const headers: Record<string, string> = {
               Accept: 'application/json',
               'User-Agent': this.config.provider.userAgent,
+              ...visionProviderHeaders(this.config.provider, operation.operationKey),
             }
             if (this.config.provider.protocol === 'anthropic') {
               headers['x-api-key'] = resolvedCredential.value

package/src/settings-compat.ts

@@ -0,0 +1,56 @@
+import type { Context } from '@deepseek-ai/cordis'
+import { LegacyConfig, VISION_TOOLKIT_SETTINGS_NAMESPACE, resolveConfig, type VisionToolkitConfig } from './config.ts'
+
+type ChangeListener = (next: VisionToolkitConfig, previous: VisionToolkitConfig) => void | Promise<void>
+
+export interface VisionSettingsBinding {
+  get(): VisionToolkitConfig
+  update(patch: Partial<VisionToolkitConfig>): Promise<void>
+  watch(listener: ChangeListener): () => void
+}
+
+/** Bridge the registration API through 0.1.6 and the Config projection in 0.1.7. */
+export function bindVisionSettings(ctx: Context, base: VisionToolkitConfig): VisionSettingsBinding {
+  const service = ctx.settings as unknown as {
+    register?: (
+      ns: string,
+      schema: typeof LegacyConfig,
+      options: { base: VisionToolkitConfig; applies: 'live'; validate: (value: VisionToolkitConfig) => void },
+    ) => VisionSettingsBinding
+    describe(): Array<{ ns: string; value: unknown }>
+    update(ns: string, patch: object): Promise<void>
+  }
+  if (typeof service.register === 'function') {
+    return service.register(VISION_TOOLKIT_SETTINGS_NAMESPACE, LegacyConfig, {
+      base,
+      applies: 'live',
+      validate: value => { resolveConfig(value) },
+    })
+  }
+
+  // New Settings reads the Loader entry's exported Config. While apply() is
+  // running the entry is not yet active, so describe() cannot see it; the
+  // Loader-provided config is the initial value in that interval.
+  let latest = base
+  const read = (): VisionToolkitConfig => {
+    const row = service.describe().find(item => item.ns === VISION_TOOLKIT_SETTINGS_NAMESPACE)
+    return (row?.value as VisionToolkitConfig | undefined) ?? latest
+  }
+  return {
+    get: read,
+    update: patch => service.update(VISION_TOOLKIT_SETTINGS_NAMESPACE, patch),
+    watch(listener) {
+      const events = ctx as unknown as {
+        on(event: 'settings/document-updated', handler: (ns: string) => void): () => void
+      }
+      return events.on('settings/document-updated', ns => {
+        if (ns !== VISION_TOOLKIT_SETTINGS_NAMESPACE) return
+        const next = read()
+        if (JSON.stringify(next) === JSON.stringify(latest)) return
+        const previous = latest
+        latest = next
+        void listener(next, previous)
+      })
+    },
+  }
+}