@mengruo/dsh-vision-toolkit 0.1.5 → 0.1.6-beta.0

package/src/client/index.tsx

@@ -77,6 +77,8 @@ const en = {
   streamHint: 'Request a streamed (SSE) completion instead of one JSON response. Use it for endpoints with weak non-streaming support or that time out on long outputs.',
   uploadViaUrl: 'Transfer images via URL',
   uploadViaUrlHint: 'Upload each image to the configured object storage and send the model a URL instead of base64. Requires object storage (below); region crops fall back to base64.',
+  videoSupport: 'Enable video support',
+  videoSupportHint: 'OpenAI-compatible video understanding. This setting is hidden for Anthropic providers and is currently a placeholder with no effect yet.',
   language: 'Output language',
   limits: 'Timeout and concurrency',
   timeout: 'Request timeout (ms)',
@@ -131,8 +133,10 @@ const en = {
   runHealth: 'Run health check',
   testConnection: 'Test API connection',
   testModel: 'Test vision model',
+  testVideo: 'Test video call',
   testing: 'Checking…',
   testingModel: 'Testing model…',
+  testingVideo: 'Testing video…',
   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',
@@ -141,6 +145,14 @@ const en = {
   hiddenVariants: 'Transparent variant routing',
   hiddenVariantsLabel: 'Keep the original model names and enable images automatically',
   hiddenVariantsHint: 'Text-only models keep one model-selector entry with the original name while the session runs on the image-capable variant. Pasted images, image history, and the built-in read_image tool keep working; disable to restore the explicit (Vision Toolkit) entries.',
+  toolVisibility: 'Tool visibility',
+  toolVisibilityHint: 'Which groups of vision tools an Agent sees. Applies to the next Agent conversation: an already-active Agent keeps its activation-time set until it is reloaded.',
+  toolVisibilityLocal: 'Local tools',
+  toolVisibilityLocalHint: 'trace / crop / pixel diff / foreground / colors / HTML screenshot / video info. Local processing, no on-line parallel limits.',
+  toolVisibilityOnline: 'Online image tools',
+  toolVisibilityOnlineHint: 'glance / ground / detect / long-screenshot OCR, plus the concurrency/status probe. On-line service calls share the session concurrency budget.',
+  toolVisibilityVideo: 'Video tools',
+  toolVisibilityVideoHint: 'video understanding (experimental). Calling it without an enabled video-capable service returns "video understanding unavailable".',
   pluginVersion: 'Plugin',
   upstreamVersion: 'Upstream',
   activeGeneration: 'Runtime generation',
@@ -312,6 +324,8 @@ const zh: Record<LocaleKey, string> = {
   streamHint: '以流式（SSE）方式请求补全，而非一次性返回 JSON。适合对非流式支持不佳、长输出易连接超时的端点。',
   uploadViaUrl: '通过 URL 传输图片',
   uploadViaUrlHint: '把每张图片上传到下方配置的对象存储，将 URL 传给模型而不是 base64。需要先配置对象存储；使用 region 裁剪时回退为 base64。',
+  videoSupport: '启用视频支持',
+  videoSupportHint: 'OpenAI 兼容接口的视频理解能力。Anthropic 服务不显示此项；当前为占位设置，尚未生效。',
   language: '结果语言',
   limits: '超时与并发限制',
   timeout: '单次请求超时（毫秒）',
@@ -366,8 +380,10 @@ const zh: Record<LocaleKey, string> = {
   runHealth: '检查本地环境',
   testConnection: '测试 API 连接',
   testModel: '测试视觉模型',
+  testVideo: '测试视频调用',
   testing: '检查中…',
   testingModel: '正在测试模型…',
+  testingVideo: '正在测试视频…',
   connectionHint: '“测试 API 连接”只请求 GET /models；“测试视觉模型”会发送插件自带的诊断图片，验证一次真实多模态调用。',
   saveBeforeTesting: '修改服务配置后，请先保存，再执行 API 或视觉模型测试。',
   advanced: '高级设置',
@@ -376,6 +392,14 @@ const zh: Record<LocaleKey, string> = {
   hiddenVariants: '透明变体路由',
   hiddenVariantsLabel: '保留原模型名并自动启用图片能力',
   hiddenVariantsHint: '文本模型在模型列表中只显示原名称，会话实际运行在支持图片的变体路由上：粘贴图片、历史图片和内置 read_image 工具均可正常使用。关闭后恢复显示显式的（Vision Toolkit）条目。',
+  toolVisibility: '工具可见性',
+  toolVisibilityHint: 'Agent 可见的视觉工具分组。仅在下一个 agent 对话中生效：已激活的 agent 保持激活时的工具集，直到重载。',
+  toolVisibilityLocal: '本地工具',
+  toolVisibilityLocalHint: 'trace / crop / 像素对比 / 前景提取 / 取色 / HTML 截图 / 视频信息。本地处理，不受联机并发限制。',
+  toolVisibilityOnline: '联机图片工具',
+  toolVisibilityOnlineHint: 'glance / ground / detect / 长截图 OCR，以及并发/状态查询。联机调用共享会话并发额度。',
+  toolVisibilityVideo: '视频工具',
+  toolVisibilityVideoHint: '视频理解（测试）。调用时若没有已启用且支持视频的服务，将返回“视频理解不可用”。',
   pluginVersion: '插件版本',
   upstreamVersion: '工具包版本',
   activeGeneration: '本次运行已应用',
@@ -569,6 +593,7 @@ interface ProviderValue {
   userAgent?: string
   stream?: boolean
   uploadViaUrl?: boolean
+  videoSupport?: boolean
   t1Seconds?: number
   t2Seconds?: number
   maxImageBytes?: number
@@ -587,6 +612,7 @@ interface SettingsValue {
     userAgent?: string
     stream?: boolean
     uploadViaUrl?: boolean
+    videoSupport?: boolean
   }
   providers?: ProviderValue[]
   language?: 'zh' | 'en'
@@ -612,6 +638,11 @@ interface SettingsValue {
     autoSwitch?: boolean
     hidden?: boolean
   }
+  toolVisibility?: {
+    local?: boolean
+    online?: boolean
+    video?: boolean
+  }
 }
 
 type PluginUpdateUnavailableReason =
@@ -1049,7 +1080,8 @@ interface SettingsState {
   update?: PluginUpdateCheck | undefined
   restart?: PluginUpdateResult | undefined
   storageTest?: { detail: string } | undefined
-  action?: 'save' | 'health' | 'connection' | 'model' | 'check-update' | 'apply-update' | 'test-storage' | undefined
+  videoTest?: { detail: string } | undefined
+  action?: 'save' | 'health' | 'connection' | 'model' | 'check-update' | 'apply-update' | 'test-storage' | 'test-video' | undefined
   message?: string | undefined
   error?: string | undefined
 }
@@ -1198,6 +1230,20 @@ export class VisionSettingsController {
     }
   }
 
+  async runVideoTest(providerIndex?: number): Promise<void> {
+    this.set({ ...this.state, action: 'test-video', error: undefined, message: undefined })
+    try {
+      const result = await apiRequest<{ detail: string }>({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ action: 'test-video', ...(providerIndex === undefined ? {} : { providerIndex }) }),
+      })
+      this.set({ ...this.state, action: undefined, videoTest: result })
+    } catch (error) {
+      this.set({ ...this.state, action: undefined, error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+
   async checkUpdate(): Promise<void> {
     this.set({ ...this.state, action: 'check-update', error: undefined, message: undefined })
     try {
@@ -1248,6 +1294,7 @@ interface ProviderDraft {
   userAgent: string
   stream: boolean
   uploadViaUrl: boolean
+  videoSupport: boolean
   t1Seconds: string
   t2Seconds: string
   maxImageBytes: string
@@ -1277,6 +1324,9 @@ interface Draft {
   variantEnabled: boolean
   variantProviders: string
   variantAutoSwitch: boolean
+  toolVisibilityLocal: boolean
+  toolVisibilityOnline: boolean
+  toolVisibilityVideo: boolean
 }
 
 function randomProviderId(): string {
@@ -1313,6 +1363,7 @@ function emptyProviderDraft(defaults: ProviderDefaults): ProviderDraft {
     userAgent: DEFAULT_USER_AGENT,
     stream: false,
     uploadViaUrl: false,
+    videoSupport: false,
     t1Seconds: '90',
     t2Seconds: '90',
     maxImageBytes: String(defaults.maxImageBytes),
@@ -1337,6 +1388,7 @@ function providerDraftOf(value: ProviderValue | undefined, fallback: ProviderVal
     userAgent: source?.userAgent ?? DEFAULT_USER_AGENT,
     stream: source?.stream === true,
     uploadViaUrl: source?.uploadViaUrl === true,
+    videoSupport: source?.videoSupport === true,
     t1Seconds: String(source?.t1Seconds ?? 90),
     t2Seconds: String(source?.t2Seconds ?? 90),
     maxImageBytes: String(source?.maxImageBytes ?? defaults.maxImageBytes),
@@ -1377,6 +1429,9 @@ function draftOf(value: SettingsValue): Draft {
     variantEnabled: value.imageInputVariants?.enabled ?? true,
     variantProviders: (value.imageInputVariants?.providers ?? []).join('\n'),
     variantAutoSwitch: value.imageInputVariants?.autoSwitch ?? true,
+    toolVisibilityLocal: value.toolVisibility?.local ?? true,
+    toolVisibilityOnline: value.toolVisibility?.online ?? true,
+    toolVisibilityVideo: value.toolVisibility?.video ?? false,
   }
 }
 
@@ -1409,6 +1464,7 @@ function valueOf(draft: Draft, t: Translate): SettingsValue {
     ...(provider.userAgent.trim() === DEFAULT_USER_AGENT ? {} : { userAgent: provider.userAgent.trim() }),
     ...(provider.stream ? { stream: true } : {}),
     ...(provider.uploadViaUrl ? { uploadViaUrl: true } : {}),
+    ...(provider.videoSupport ? { videoSupport: true } : {}),
     ...(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) }),
@@ -1427,6 +1483,7 @@ function valueOf(draft: Draft, t: Translate): SettingsValue {
       userAgent: primary?.userAgent.trim() || DEFAULT_USER_AGENT,
       stream: primary?.stream === true,
       uploadViaUrl: primary?.uploadViaUrl === true,
+      videoSupport: primary?.videoSupport === true,
     },
     providers,
     language: draft.language,
@@ -1461,6 +1518,11 @@ function valueOf(draft: Draft, t: Translate): SettingsValue {
       ...(draft.variantAutoSwitch ? {} : { autoSwitch: false }),
       hidden: draft.hiddenVariants,
     },
+    toolVisibility: {
+      local: draft.toolVisibilityLocal,
+      online: draft.toolVisibilityOnline,
+      video: draft.toolVisibilityVideo,
+    },
   }
 }
 
@@ -1803,6 +1865,7 @@ function LoadedSettings({ controller, t }: SettingsInjected) {
               <Field label={t('userAgent')}><Input aria-label={t('userAgent')} value={selectedProvider.userAgent} onChange={(event) => { updateProvider(selectedIndex, 'userAgent', event.target.value) }} /></Field>
               <Field label={t('stream')} hint={t('streamHint')}><select aria-label={t('stream')} disabled={!snapshot.writable || busy} value={selectedProvider.stream ? 'enabled' : 'disabled'} onChange={(event) => { updateProvider(selectedIndex, 'stream', event.target.value === 'enabled') }}><option value="disabled">{t('disabled')}</option><option value="enabled">{t('enabled')}</option></select></Field>
               <Field label={t('uploadViaUrl')} hint={t('uploadViaUrlHint')}><select aria-label={t('uploadViaUrl')} disabled={!snapshot.writable || busy} value={selectedProvider.uploadViaUrl ? 'enabled' : 'disabled'} onChange={(event) => { updateProvider(selectedIndex, 'uploadViaUrl', event.target.value === 'enabled') }}><option value="disabled">{t('disabled')}</option><option value="enabled">{t('enabled')}</option></select></Field>
+              {selectedProvider.protocol === 'openai' ? <Field label={t('videoSupport')} hint={t('videoSupportHint')}><select aria-label={t('videoSupport')} disabled={!snapshot.writable || busy} value={selectedProvider.videoSupport ? 'enabled' : 'disabled'} onChange={(event) => { updateProvider(selectedIndex, 'videoSupport', event.target.value === 'enabled') }}><option value="disabled">{t('disabled')}</option><option value="enabled">{t('enabled')}</option></select></Field> : null}
               <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>
@@ -1814,12 +1877,14 @@ function LoadedSettings({ controller, t }: SettingsInjected) {
             <div className="dvt-provider-tests">
               <Button size="sm" variant="outline" disabled={busy || !snapshot.runtime.ready} onClick={() => { void controller.runHealth('connection', selectedIndex) }}>{state.action === 'connection' ? t('testing') : t('testConnection')}</Button>
               <Button size="sm" variant="primary" disabled={busy || !snapshot.runtime.ready} onClick={() => { void controller.runHealth('model', selectedIndex) }}>{state.action === 'model' ? t('testingModel') : t('testModel')}</Button>
+              {selectedProvider.protocol === 'openai' ? <Button size="sm" variant="primary" disabled={busy || !snapshot.runtime.ready} onClick={() => { void controller.runVideoTest(selectedIndex) }}>{state.action === 'test-video' ? t('testingVideo') : t('testVideo')}</Button> : null}
             </div>
             {providerHealth === undefined ? null : <div className="dvt-provider-test-result">{(['service', 'model'] as const).map(name => {
               const check = providerHealth.checks[name]
               if (check === undefined) return null
               return <div key={name} data-status={check.status}><span>{t(HEALTH_NAME_KEYS[name] ?? 'health')}</span><strong>{t(HEALTH_STATUS_KEYS[check.status])}</strong><p>{healthDetail(name, check.detail, t)}</p></div>
             })}</div>}
+            {state.videoTest === undefined ? null : <div className="dvt-provider-test-result"><div data-status="ok"><span>{t('videoSupport')}</span><strong>{t('statusOk')}</strong><p>{state.videoTest.detail}</p></div></div>}
           </div>
         )}
       </section>
@@ -1887,6 +1952,12 @@ function LoadedSettings({ controller, t }: SettingsInjected) {
 
           <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"><div><h3>{t('toolVisibility')}</h3><p>{t('toolVisibilityHint')}</p></div></div>
+            <label className="dvt-check"><input type="checkbox" checked={draft.toolVisibilityLocal} disabled={!snapshot.writable || busy} onChange={(event) => { update('toolVisibilityLocal', event.target.checked) }} /><span>{t('toolVisibilityLocal')}</span><small>{t('toolVisibilityLocalHint')}</small></label>
+            <label className="dvt-check"><input type="checkbox" checked={draft.toolVisibilityOnline} disabled={!snapshot.writable || busy} onChange={(event) => { update('toolVisibilityOnline', event.target.checked) }} /><span>{t('toolVisibilityOnline')}</span><small>{t('toolVisibilityOnlineHint')}</small></label>
+            <label className="dvt-check"><input type="checkbox" checked={draft.toolVisibilityVideo} disabled={!snapshot.writable || busy} onChange={(event) => { update('toolVisibilityVideo', event.target.checked) }} /><span>{t('toolVisibilityVideo')} <em>（测试）</em></span><small>{t('toolVisibilityVideoHint')}</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>

package/src/config.ts

@@ -81,6 +81,8 @@ export interface VisionProviderConfig {
   stream?: boolean
   /** Whether to upload images to object storage and send the model a URL instead of base64 (default false). */
   uploadViaUrl?: boolean
+  /** OpenAI-compatible video understanding (default false); Anthropic providers ignore this placeholder flag. */
+  videoSupport?: boolean
   /** 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. */
@@ -114,6 +116,8 @@ export interface VisionToolkitConfig {
     stream?: boolean
     /** Whether to upload images to object storage and send the model a URL instead of base64 (default false). */
     uploadViaUrl?: boolean
+    /** OpenAI-compatible video understanding (default false); Anthropic providers ignore this placeholder flag. */
+    videoSupport?: boolean
   }
   /** Ordered online vision providers; array order is the failover priority. */
   providers?: VisionProviderConfig[]
@@ -194,6 +198,21 @@ export interface VisionToolkitConfig {
      */
     hidden?: boolean
   }
+  /**
+   * Per-group tool visibility, applied when each Agent's visual tool set is
+   * materialized (a session-head snapshot: an already-active Agent keeps its
+   * activation-time set; a change only affects the next Agent's tool set).
+   * Tools are grouped into three buckets; a bucket that is off contributes none
+   * of its tools to an Agent's visible surface.
+   */
+  toolVisibility?: {
+    /** Local-processing tools (no on-line fan-out, no concurrency charge). Default true. */
+    local?: boolean
+    /** On-line image tools plus the concurrency/status probe. Default true. */
+    online?: boolean
+    /** Video-understanding tool (experimental). Default false. */
+    video?: boolean
+  }
 }
 
 /** Configuration schema with the documented P0 defaults. */
@@ -206,6 +225,8 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
     anthropicThinking: z.union(['omit', 'disabled', 'adaptive'] as const).default('omit'),
     userAgent: z.string().default(DEFAULT_VISION_USER_AGENT),
     stream: z.boolean().default(false),
+    uploadViaUrl: z.boolean().default(false),
+    videoSupport: z.boolean().default(false),
   }),
   providers: z.array(z.object({
     name: z.string(),
@@ -219,6 +240,7 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
     userAgent: z.string(),
     stream: z.boolean().default(false),
     uploadViaUrl: z.boolean().default(false),
+    videoSupport: z.boolean().default(false),
     t1Seconds: z.number(),
     t2Seconds: z.number(),
     maxImageBytes: z.number(),
@@ -253,6 +275,11 @@ export const Config: Schema<VisionToolkitConfig> = z.object({
     autoSwitch: z.boolean().default(true),
     hidden: z.boolean().default(true),
   }),
+  toolVisibility: z.object({
+    local: z.boolean().default(true),
+    online: z.boolean().default(true),
+    video: z.boolean().default(false),
+  }),
 })
 
 /** One resolved online vision provider, with every default materialized. */
@@ -269,6 +296,7 @@ export interface ResolvedProvider {
   userAgent: string
   stream: boolean
   uploadViaUrl: boolean
+  videoSupport: boolean
   t1Seconds: number
   t2Seconds: number
   maxImageBytes: number
@@ -288,6 +316,7 @@ export interface ResolvedVisionToolkitConfig {
     userAgent: string
     stream: boolean
     uploadViaUrl: boolean
+    videoSupport: boolean
   }
   /** Ordered failover pool; array order is the priority, highest first. */
   providers: ResolvedProvider[]
@@ -318,6 +347,11 @@ export interface ResolvedVisionToolkitConfig {
     autoSwitch: boolean
     hidden: boolean
   }
+  toolVisibility: {
+    local: boolean
+    online: boolean
+    video: boolean
+  }
 }
 
 const MAX_TIMEOUT_SECONDS = 600
@@ -410,6 +444,7 @@ function resolveProvider(
   }
   const stream = input.stream === true
   const uploadViaUrl = input.uploadViaUrl === true
+  const videoSupport = input.videoSupport === true
   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}`)
@@ -448,6 +483,7 @@ function resolveProvider(
     userAgent,
     stream,
     uploadViaUrl,
+    videoSupport,
     t1Seconds,
     t2Seconds,
     maxImageBytes,
@@ -535,6 +571,7 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
   const variantProviders = (imageInputVariants.providers ?? [])
     .map(provider => provider.trim())
     .filter(provider => provider.length > 0)
+  const toolVisibility = config.toolVisibility ?? {}
   const providerDefaults: ProviderDefaults = { maxImageBytes, maxImagePixels, concurrency }
   const configuredProviders = config.providers ?? []
   if (configuredProviders.length > MAX_PROVIDERS) {
@@ -555,6 +592,7 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
       userAgent: primary.userAgent,
       stream: primary.stream,
       uploadViaUrl: primary.uploadViaUrl,
+      videoSupport: primary.videoSupport,
     },
     providers,
     language,
@@ -584,6 +622,11 @@ export function resolveConfig(config: VisionToolkitConfig = {}): ResolvedVisionT
       autoSwitch: imageInputVariants.autoSwitch ?? true,
       hidden: imageInputVariants.hidden ?? true,
     },
+    toolVisibility: {
+      local: toolVisibility.local ?? true,
+      online: toolVisibility.online ?? true,
+      video: toolVisibility.video ?? false,
+    },
   }
 }
 

package/src/exposure.ts

@@ -12,7 +12,7 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import { defineTool, type ToolDefinition } from '@deepseek-ai/dsh-tools'
 import type { Context } from '@deepseek-ai/cordis'
 import { VISION_SKILLS_CONTENT, VISION_SKILLS_NAME } from './skill.ts'
-import { VISION_TOOL_NAMES } from './tools.ts'
+import { VISION_TOOL_NAMES, type ToolVisibility } from './tools.ts'
 
 /** Small bootstrap tool retained only until the current Agent gains visual tools. */
 export const VISION_TOOLKIT_ACTIVATE = 'vision_toolkit_activate'
@@ -139,17 +139,21 @@ export class VisionToolExposure {
 
   /**
    * @param ctx - Plugin context with Tool and Agent registries.
-   * @param createTools - Fresh definitions bound to the current runtime generation.
+   * @param createTools - Fresh definitions bound to the current runtime
+   *   generation, filtered by a tool-visibility snapshot.
+   * @param resolveVisibility - Live resolver for the current tool-visibility
+   *   snapshot; read once per activation (a session-head snapshot).
    */
   constructor(
     private readonly ctx: Context,
-    private readonly createTools: () => ToolDefinition[],
+    private readonly createTools: (snapshot: ToolVisibility) => ToolDefinition[],
+    private readonly resolveVisibility: () => ToolVisibility = () => ({ local: true, online: true, video: false }),
   ) {
     this.activationTool = defineTool({
       name: VISION_TOOLKIT_ACTIVATE,
-      description: `Activate the independent Vision Toolkit execution tools for this Agent: ${Object.values(VISION_TOOL_NAMES).join(', ')}. `
-        + `Loading the ${VISION_SKILLS_NAME} Skill normally activates them automatically; call this once when the visual tools are still absent, then use them for image understanding, OCR, UI detection, and related tasks. `
-        + 'It is safe to call before the Skill is loaded, and this activation tool disappears after success.',
+      description: `Report and (re)mount the Vision Toolkit execution tools for this Agent: the currently visible subset of ${Object.values(VISION_TOOL_NAMES).join(', ')} plus optional video understanding. `
+        + `The visual tool set is normally mounted automatically when the ${VISION_SKILLS_NAME} Skill loads; call this ONLY when the user explicitly asks you to refresh or reload the current session's vision tools, or to list which vision tools are currently available. `
+        + 'It restores the tool set to the latest Settings snapshot and returns the tool names actually mounted.',
       parameters: {},
       output: {
         schema: {
@@ -166,9 +170,12 @@ export class VisionToolExposure {
         if (exec.agent === undefined) {
           throw new Error(`${VISION_TOOLKIT_ACTIVATE}: an Agent Session is required`)
         }
-        return Promise.resolve(this.activate(exec.agent))
+        // An already-active Agent is reloaded (re-reads the latest Settings
+        // snapshot) rather than returning the stale set, so the tool genuinely
+        // refreshes the visible tool list on an explicit user request.
+        return Promise.resolve(this.reload(exec.agent))
       },
-      presentCall: () => ({ card: 'generic', title: 'Activate vision tools', kind: 'execute' }),
+      presentCall: () => ({ card: 'generic', title: 'Refresh or list vision tools', kind: 'execute' }),
     })
   }
 
@@ -222,7 +229,7 @@ export class VisionToolExposure {
     if (state === undefined) throw new Error(`dsh-vision-toolkit: Agent ${String(agent.id)} has no exposure state`)
     if (state.active) return { activated: false, tools: [...state.toolNames] }
 
-    const definitions = this.createTools()
+    const definitions = this.createTools(this.resolveVisibility())
     const toolDisposers: Array<() => void> = []
     try {
       for (const definition of definitions) toolDisposers.push(agent.ctx.tools.register(definition))
@@ -241,6 +248,24 @@ export class VisionToolExposure {
     return { activated: true, tools: [...state.toolNames] }
   }
 
+  /**
+   * Explicit refresh/reload from the bootstrap tool. An inactive Agent is
+   * mounted; an active Agent is torn down and re-mounted from the *current*
+   * Settings snapshot, so the returned tool list reflects the latest
+   * `toolVisibility` instead of the stale activation-time set.
+   */
+  private reload(agent: Agent): VisionToolkitActivationResult {
+    this.attach(agent)
+    const state = this.states.get(agent)
+    if (state === undefined) return { activated: false, tools: [] }
+    if (!state.active) return this.activate(agent)
+    // Dispose the current tool generation (including the hide-restriction on
+    // the bootstrap gauntlet) and rebuild from the fresh snapshot.
+    this.disposeState(state)
+    this.states.set(agent, { active: false, toolDisposers: [], toolNames: [] })
+    return this.activate(agent)
+  }
+
   /** Whether the session is attached to the live SessionStore (production). */
   private isLiveSession(session: Session): boolean {
     return this.ctx.sessions.get(session.id) === session

package/src/index.ts

@@ -83,11 +83,16 @@ export async function apply(ctx: Context, config: VisionToolkitConfig = {}): Pro
 
   const ensureOperational = (): void => {
     if (!manager.ready || operationalDisposers !== undefined) return
-    const exposure = new VisionToolExposure(ctx, () => createVisionTools(
-      () => manager.current(),
-      value => artifacts.presentationMeta(value),
-      lifecycle.signal,
-    ))
+    const exposure = new VisionToolExposure(
+      ctx,
+      (visibility) => createVisionTools(
+        () => manager.current(),
+        value => artifacts.presentationMeta(value),
+        lifecycle.signal,
+        visibility,
+      ),
+      () => manager.currentConfig().toolVisibility,
+    )
     let activationTool: (() => void) | undefined
     let exposureDisposer: (() => void) | undefined
     let skill: (() => void) | undefined

package/src/paths.ts

@@ -16,6 +16,12 @@ import { VisionToolkitError } from './errors.ts'
 /** Supported input image extensions (the upstream client's allowlist). */
 export const SUPPORTED_IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp'] as const
 
+/** Supported input video extensions probed with the bundled ffprobe binary. */
+export const SUPPORTED_VIDEO_EXTENSIONS = [
+  '.mp4', '.mov', '.webm', '.mkv', '.avi', '.m4v',
+  '.mpg', '.mpeg', '.wmv', '.flv', '.ts', '.m2ts', '.3gp',
+] as const
+
 /** Resolved path policy for one tool invocation. */
 export interface PathPolicy {
   /** Real workspace root. */
@@ -399,6 +405,11 @@ export function resolveHtmlFile(raw: string, policy: PathPolicy): Promise<{ path
   return resolveAuthorizedFile(raw, policy, ['.html', '.htm'], 'HTML source')
 }
 
+/** Validate one input video path against the video extension allowlist. */
+export function resolveInputVideo(raw: string, policy: PathPolicy): Promise<{ path: string; bytes: number }> {
+  return resolveAuthorizedFile(raw, policy, SUPPORTED_VIDEO_EXTENSIONS, 'video')
+}
+
 /**
  * Resolve an optional user-supplied output filename inside the plugin output
  * directory. Absolute paths, `..` segments, and wrong extensions are rejected.