dsh-tool-vision 0.6.3 → 0.7.0

package/README.md

@@ -10,12 +10,12 @@ Part of the [DeepSeek Harness Enhancement Suite](https://github.com/Scorp1o117/d
 
 External vision model for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
 
-DSH 0.1.1 adds native image input for DeepSeek's vision catalog. This plugin
-remains useful when you want a separate OpenAI-compatible vision endpoint,
-pixel-level image tools, screenshots, or a text-model bridge. The harness
-derives every model request strictly from the session log (`llm/stream`
-requests must equal the durable derivation — the agent-loop invariant), so the
-bridge keeps its conversion inside that durable path:
+DSH 0.1.1 adds native image input for DeepSeek's vision catalog. This plugin
+remains useful when you want a separate OpenAI-compatible vision endpoint,
+pixel-level image tools, screenshots, or a text-model bridge. The harness
+derives every model request strictly from the session log (`llm/stream`
+requests must equal the durable derivation — the agent-loop invariant), so the
+bridge keeps its conversion inside that durable path:
 
 1. **`inspect_image` tool** — sends an image (local file, or http(s) URL) to
    **any OpenAI-compatible** `/chat/completions` endpoint that supports
@@ -82,6 +82,9 @@ Or load it from a local path without npm:
 | `bridgePreviewScanIntervalMs` | `2000` | Fallback scan interval for the preview scanner (ms); `0` disables the fallback. |
 | `bridgePreviewHideHint` | `true` | Hide the bridged hint text once the preview image has loaded (kept on failure — safe degradation). |
 | `bridgeAutoImage` | `true` | While the bridge is on, report image input capability for **every** model to the host admission gate, so pasted images are accepted on text-only models without hand-editing provider configs. |
+| `sendSessionHeader` | `true` | Send a stable session-id header on vision requests. OpenCode Go and similar gateways require `x-opencode-session` (one stable id per conversation); requests without it may error from 2026-09-06. |
+| `sessionHeaderName` | `x-opencode-session` | Header name carrying the session id. |
+| `sessionId` | `''` | Fixed session id for calls without a dsh session context; empty = auto (current dsh session id, else a stable per-process random id). |
 
 ## Image bridge setup
 
@@ -166,11 +169,11 @@ Example endpoints (`baseURL`):
 > - This plugin is a standard **profile bundle** (`dsh.bundle.patch`):
 >   `dsh plugin --profile web add dsh-tool-vision` installs and mounts it in
 >   one step — no manual `cordis.patch.yml` edits needed.
-> - Settings changes hot-apply (no restart needed).
-> - Version 0.6.3 and newer require DSH `0.1.0-rc.7` or newer and are tested
->   against `0.1.0-rc.7`, `0.1.0-rc.8`, and `0.1.1-rc.1`.
-> - DSH `0.1.0-rc.6` users must pin `dsh-tool-vision@0.6.1`, the last release
->   carrying the legacy settings-allowlist compatibility patch.
+> - Settings changes hot-apply (no restart needed).
+> - Version 0.6.3 and newer require DSH `0.1.0-rc.7` or newer and are tested
+>   against `0.1.0-rc.7`, `0.1.0-rc.8`, and `0.1.1-rc.1`.
+> - DSH `0.1.0-rc.6` users must pin `dsh-tool-vision@0.6.1`, the last release
+>   carrying the legacy settings-allowlist compatibility patch.
 
 ## Pixel-level vision tools (v0.6.0, ported from dsh-vision-router)
 

package/README.zh.md

@@ -57,6 +57,9 @@ DSH 0.1.1 已为 DeepSeek 视觉模型目录加入原生图片输入。本插件
 | `bridgePreviewScanIntervalMs` | `2000` | 预览兜底扫描间隔（毫秒）；`0` 关闭兜底 |
 | `bridgePreviewHideHint` | `true` | 图片加载成功后隐藏桥接提示文本（失败时保留，安全降级） |
 | `bridgeAutoImage` | `true` | 桥接开启时向宿主准入检查报告**所有**模型都支持图片输入，纯文本模型也能直接粘贴图片，无需手动改 provider 配置 |
+| `sendSessionHeader` | `true` | 给视觉请求发送稳定的会话标识头。OpenCode Go 等网关要求每请求带 `x-opencode-session`（一个对话一个稳定 ID），缺失的请求在 2026-09-06 起可能报错 |
+| `sessionHeaderName` | `x-opencode-session` | 承载会话 ID 的头名 |
+| `sessionId` | `''` | 固定会话 ID（后台/无 dsh 会话调用时用）；留空则自动：优先取当前 dsh 会话 ID，否则用进程级稳定随机 ID |
 
 ## 图片桥配置
 

package/client.js

@@ -80,6 +80,11 @@ window.__ModuleLoader__.load({
       fieldBridgePreviewHideHint: "图片加载成功后隐藏桥接提示文本",
       fieldBridgeAutoImage: "自动声明图片能力（纯文本模型也能粘贴图片）",
       fieldDesktopScreenshot: "桌面截屏工具（vision_screenshot，默认关闭）",
+      fieldSendSessionHeader: "发送会话标识头（x-opencode-session）",
+      fieldSessionHeaderName: "会话标识头名称",
+      fieldSessionId: "固定会话 ID（留空 = 自动）",
+      hintSendSessionHeader: "OpenCode Go 等网关要求每个请求带稳定的会话标识（一个对话一个 ID）；请求不带可能报错。默认发送：优先用当前 dsh 会话 ID，无会话上下文时用下方固定 ID，再否则用进程级随机 ID。",
+      hintSessionId: "后台/无会话调用时使用的固定会话标识（如 dsh-vision-<hostname>）；留空则每进程自动生成一个稳定 ID。",
       hintBridgePreview: "纯展示层：不影响模型侧文本与 inspect_image 调用。",
       hintBridgePreviewScanIntervalMs: "默认 2000ms；越小响应越快，越大越省资源。",
       hintBridgePreviewHideHint: "加载失败时保留文本（安全降级，绝不出现既无图又无字）。",
@@ -119,6 +124,11 @@ window.__ModuleLoader__.load({
       fieldBridgePreviewHideHint: "Hide the bridged hint text once the image has loaded",
       fieldBridgeAutoImage: "Auto-declare image capability (paste images on text-only models)",
       fieldDesktopScreenshot: "Desktop screenshot tool (vision_screenshot, off by default)",
+      fieldSendSessionHeader: "Send session-id header (x-opencode-session)",
+      fieldSessionHeaderName: "Session-id header name",
+      fieldSessionId: "Fixed session id (empty = auto)",
+      hintSendSessionHeader: "OpenCode Go and similar gateways require a stable per-conversation id on every request; requests without it may error. When on: prefer the current dsh session id, else the fixed id below, else a per-process random id.",
+      hintSessionId: "Fixed session id used for background calls without a dsh session; leave empty for a per-process stable random id.",
       hintBridgePreview: "Pure display layer: the model-facing text and the inspect_image chain are untouched.",
       hintBridgePreviewScanIntervalMs: "Default 2000ms; lower is snappier, higher is cheaper.",
       hintBridgePreviewHideHint: "Text is kept on load failure (safe degradation, never no image AND no text).",
@@ -150,7 +160,10 @@ window.__ModuleLoader__.load({
       { key: "bridgePreviewScanIntervalMs", label: "fieldBridgePreviewScanIntervalMs", type: "number" },
       { key: "bridgePreviewHideHint", label: "fieldBridgePreviewHideHint", type: "checkbox" },
       { key: "bridgeAutoImage", label: "fieldBridgeAutoImage", type: "checkbox" },
-      { key: "desktopScreenshot", label: "fieldDesktopScreenshot", type: "checkbox" }
+      { key: "desktopScreenshot", label: "fieldDesktopScreenshot", type: "checkbox" },
+      { key: "sendSessionHeader", label: "fieldSendSessionHeader", type: "checkbox" },
+      { key: "sessionHeaderName", label: "fieldSessionHeaderName", type: "text" },
+      { key: "sessionId", label: "fieldSessionId", type: "text" }
     ];
     var ZH_HINTS = {
       apiKey: "apiKeyHint",
@@ -183,11 +196,16 @@ window.__ModuleLoader__.load({
       var [error, setError] = react.useState(null);
 
       react.useEffect(function () {
-        if (typeof scope.load === "function") scope.load();
+        if (typeof scope.load === "function") scope.load();
         var alive = true;
         var sync = function () { if (alive) setSnapshot(scope.getSnapshot()); };
         var un = typeof scope.subscribe === "function" ? scope.subscribe(sync) : null;
-        return function () { alive = false; if (un) un(); if (scope.dispose) scope.dispose(); };
+        // The settings scope is bound once for this plugin (apply) and shared
+        // across every mount of this section. Unmounting the section must only
+        // unsubscribe — never dispose the scope, or a later remount would find
+        // a `disposed` scope whose write queue no-ops, silently dropping saves
+        // (the value then reverts on the next describe).
+        return function () { alive = false; if (un) un(); };
       }, [scope]);
       // Seed the draft ONLY when the snapshot becomes ready — never on value
       // churn. settingsScope.getSnapshot() returns a fresh object per call,
@@ -246,7 +264,7 @@ window.__ModuleLoader__.load({
         });
         Promise.all(writes).then(function () {
           setBusy(false); setNotice(t("saved"));
-          if (typeof scope.load === "function") scope.load();
+          if (typeof scope.load === "function") scope.load();
         }).catch(function (e) {
           setBusy(false); setError(t("error") + ": " + String(e && e.message || e));
         });
@@ -482,7 +500,7 @@ window.__ModuleLoader__.load({
       var t = ctx.locale.bind(NS);
       ctx.effect(function () { return ctx.locale.register(NS, { zh: zh, en: en }); }, "dsh-tool-vision: dictionaries");
       var scope = ctx.settingsScope.bind({ namespace: "tool-vision" });
-      if (typeof scope.load === "function") scope.load();
+      if (typeof scope.load === "function") scope.load();
       attachBridgePreview(ctx, scope);
       ctx.slots.inject("settings.section", function () {
         return ctx.slots.register({

package/cordis.patch.yml

@@ -1,8 +1,8 @@
-# dsh-tool-vision — bundle patch layer
-#
-# Declares the plugin as a Cordis loader entry, making the package a standard
-# profile bundle: `dsh plugin --profile <p> add dsh-tool-vision` installs and
-# mounts it without manual cordis.patch.yml edits.
-- insert:
-    - id: tool-vision
-      name: 'dsh-tool-vision'
+# dsh-tool-vision — bundle patch layer
+#
+# Declares the plugin as a Cordis loader entry, making the package a standard
+# profile bundle: `dsh plugin --profile <p> add dsh-tool-vision` installs and
+# mounts it without manual cordis.patch.yml edits.
+- insert:
+    - id: tool-vision
+      name: 'dsh-tool-vision'

package/index.js

@@ -41,15 +41,15 @@ import { extname, isAbsolute, join, resolve as resolvePath, sep } from "node:pat
 import os from "node:os";
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import { registerVisionTools, CONTENT_FILTER_RE } from "./lib/vision-tools.js";
+import { sessionHeaders } from "./lib/session-header.js";
 
 /** Cordis plugin name. */
 const name = "tool-vision";
 /** The tool registry, the llm seam (model capability lookup), the attachment store, and the host web server. */
 const inject = ["tools", "llm", "attachments", "webServer"];
 /** Settings namespace owned by this plugin (Web UI settings section). */
-const NS = settingsNamespace("tool-vision");
+const NS = "tool-vision";
 
 /**
  * Invisible prefix stamped onto every bridged hint text block. The browser
@@ -123,6 +123,17 @@ const Config = z.object({
    * provider model configs.
    */
   bridgeAutoImage: z.boolean().default(true),
+  /** Send a stable per-conversation id header (`x-opencode-session`) on vision
+   * requests. OpenCode Go (and similar OpenAI-compatible gateways) require it
+   * on every request; requests without the header may error. The value is the
+   * current dsh session id when the call runs inside one, else `sessionId`
+   * below, else a stable per-process random id. Set false to disable. */
+  sendSessionHeader: z.boolean().default(true),
+  /** Header name carrying the session id. */
+  sessionHeaderName: z.string().default("x-opencode-session"),
+  /** Fixed session id override for callers without a dsh session context.
+   * Empty = auto (per-process stable id). */
+  sessionId: z.string().default(""),
 });
 
 const MIME_BY_EXT = {
@@ -476,7 +487,7 @@ async function toImageUrl(target, cwd, config) {
 }
 
 /** One OpenAI-compatible chat/completions call with an image_url content part. */
-async function callVision(config, imageUrl, question, detail, signal) {
+async function callVision(config, imageUrl, question, detail, signal, exec) {
   const key = resolveApiKey(config);
   if (!key) {
     throw new Error(
@@ -485,6 +496,7 @@ async function callVision(config, imageUrl, question, detail, signal) {
   }
   const base = config.baseURL.endsWith("/") ? config.baseURL : `${config.baseURL}/`;
   const endpoint = new URL("chat/completions", base);
+  const sessionHeader = sessionHeaders(config, exec);
   const controller = new AbortController();
   const timer = setTimeout(
     () => controller.abort(new Error(`vision request timed out after ${config.timeoutMs}ms`)),
@@ -505,6 +517,7 @@ async function callVision(config, imageUrl, question, detail, signal) {
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${key}`,
+        ...sessionHeader,
       },
       body: JSON.stringify({
         model: config.model,
@@ -541,18 +554,24 @@ function apply(ctx, config) {
   // ── settings-backed configuration ─────────────────────────────────────────
   // The composition entry stays the `base` layer; a registered `tool-vision`
   // settings section (Web UI section, settings.yaml) overlays it live, so
-  // edits hot-apply without a restart. `installSettingsSection` hands
-  // `setSource` a GETTER (`() => scope.get()`), not the config object — keep
-  // it and call it at use time, or `getConfig()` would return a function and
-  // every `cfg.*` read would be undefined (apiKey included).
+  // edits hot-apply without a restart. `sourceGetter` is a GETTER
+  // (`() => scope.get()`), not the config object — keep it and call it at use
+  // time, or `getConfig()` would return a function and every `cfg.*` read
+  // would be undefined (apiKey included).
   let current = config;
   let sourceGetter = null;
   const getConfig = () => (sourceGetter ? sourceGetter() : current);
-  installSettingsSection(ctx, NS, Config, config, {
-    setSource: (getter) => {
-      sourceGetter = getter;
-    },
-    onChange: () => {},
+  // Compat shim: dsh-settings 0.1.2-rc.1 removed the module-level
+  // `installSettingsSection` export (the provider now lives at ctx.settings).
+  // Inline the same logic via ctx.inject(["settings"]) — works on both
+  // 0.1.1 (module export wrapper) and 0.1.2 (ctx.settings) hosts.
+  ctx.inject(["settings"], (sctx) => {
+    const scope = sctx.settings.register(NS, Config, { base: config });
+    sourceGetter = () => scope.get();
+    sctx.effect(() => () => {
+      sourceGetter = null;
+    });
+    scope.watch(() => {});
   });
 
   // ── image bridge: pasted images become inspect_image hints on text-only models ──
@@ -608,7 +627,7 @@ function apply(ctx, config) {
       const cwd = exec.agent?.session?.header?.cwd ?? process.cwd();
       const { url, note } = await toImageUrl(args.path, cwd, cfg);
       try {
-        const answer = await callVision(cfg, url, args.question, args.detail, exec.signal);
+        const answer = await callVision(cfg, url, args.question, args.detail, exec.signal, exec);
         return note === url ? answer : `${answer}\n\n(image: ${note})`;
       } catch (error) {
         const raw = error && error.message ? String(error.message) : String(error);

package/lib/session-header.js

@@ -0,0 +1,57 @@
+// dsh-tool-vision — x-opencode-session request header helper.
+//
+// OpenCode Go (and other OpenAI-compatible gateways) ask clients to tag every
+// request with a stable per-conversation identifier so they can attribute and
+// optimize the service. Requests without the header started erroring after
+// 2026-09-06.
+//
+// This module centralizes how the plugin picks that identifier:
+//
+//   1. A real dsh session id, when the tool call runs inside one
+//      (`exec.agent?.session?.id`, or the same id on the exec context).
+//      This is the ideal "one stable ID per conversation".
+//   2. Otherwise the configured `sessionId` (a fixed override the user can
+//      set in the settings panel, useful for background/standalone callers).
+//   3. Otherwise a per-process random id, generated once. Stable for the
+//      lifetime of the plugin process, so every untagged background call
+//      from this instance still shares one stable id.
+
+import { randomUUID } from 'node:crypto'
+
+export const DEFAULT_SESSION_HEADER = 'x-opencode-session'
+
+let fallbackId = ''
+function getFallbackId() {
+  if (!fallbackId) fallbackId = `dsh-vision-${randomUUID()}`
+  return fallbackId
+}
+
+/**
+ * Pick a stable per-conversation id for the outgoing vision request.
+ *
+ * @param {object} cfg live tool-vision config (may carry `sessionId`).
+ * @param {object|undefined} exec tool execution context, when available.
+ * @returns {string|undefined} the id to send, or undefined if header disabled.
+ */
+export function resolveSessionId(cfg, exec) {
+  if (cfg?.sendSessionHeader === false) return undefined
+  // Prefer an explicit, stable configured id when the user set one.
+  if (cfg?.sessionId) return String(cfg.sessionId)
+  // Real conversation id from the tool execution context, when present.
+  const agentSessionId =
+    exec?.agent?.session?.id ??
+    exec?.session?.id ??
+    exec?.sessionId ??
+    exec?.agent?.session?.header?.sessionId
+  if (agentSessionId) return String(agentSessionId)
+  // Background / untagged call: one stable id per plugin process.
+  return getFallbackId()
+}
+
+/** Build the header object to merge into a vision request's headers. */
+export function sessionHeaders(cfg, exec) {
+  const id = resolveSessionId(cfg, exec)
+  if (!id) return {}
+  const headerName = cfg?.sessionHeaderName || DEFAULT_SESSION_HEADER
+  return { [headerName]: id }
+}

package/lib/vision-tools.js

@@ -19,6 +19,7 @@ import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
+import { sessionHeaders } from './session-header.js'
 
 // ── image formats ──────────────────────────────────────────────────────────
 
@@ -1144,6 +1145,7 @@ export async function callVisionModel(getConfig, prompt, imageUrls, options = {}
       'tool-vision: vision API key missing: set the plugin config (apiKey / apiKeyEnv) or the OPENAI_API_KEY environment variable',
     )
   }
+  const sessionHeader = sessionHeaders(cfg, options.exec)
   const base = cfg.baseURL.endsWith('/') ? cfg.baseURL : `${cfg.baseURL}/`
   const endpoint = new URL('chat/completions', base)
   const controller = new AbortController()
@@ -1186,6 +1188,7 @@ export async function callVisionModel(getConfig, prompt, imageUrls, options = {}
         headers: {
           'Content-Type': 'application/json',
           Authorization: `Bearer ${key}`,
+          ...sessionHeader,
         },
         body: bodyOf(),
         signal: controller.signal,
@@ -1263,6 +1266,7 @@ export function registerVisionTools(ctx, getConfig) {
         : [bytesToDataUrl(await downscaleImage(images, 4_000_000), mediaType)]
       const text = await callVisionModel(getConfig, instruction, bounded, {
         signal: options.signal ?? (options.exec && options.exec.signal),
+        exec: options.exec,
       })
       return { ok: true, text }
     } catch (error) {

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "dsh-tool-vision",
-    "version": "0.6.3",
+    "version": "0.7.0",
     "description": "DeepSeek Harness 外置视觉模型插件：inspect_image 把本地图片或 http(s) 图片 URL 发给任意 OpenAI 兼容端点，视觉模型看图的文字回答直接带回对话；附 Web UI 设置栏。",
     "type": "module",
     "main": "index.js",
     "scripts": {
-        "test": "node tests/preview-regex.test.mjs && node tests/preview-route.test.mjs && node tests/auto-image.test.mjs && node --test tests/vision-tools.test.js tests/vision-tools-tools.test.js && node tests/settings-scope-compat.test.mjs"
+        "test": "node tests/preview-regex.test.mjs && node tests/preview-route.test.mjs && node tests/auto-image.test.mjs && node --test tests/vision-tools.test.js tests/vision-tools-tools.test.js && node tests/settings-scope-compat.test.mjs"
     },
     "exports": {
         ".": "./index.js",
@@ -59,8 +59,8 @@
     },
     "peerDependencies": {
         "react": "^18.2.0",
-        "@deepseek-ai/dsh-settings": "^0.1.0-rc.7 || ^0.1.1-rc.1",
-        "@deepseek-ai/dsh-tools": "^0.1.0-rc.7 || ^0.1.1-rc.1"
+        "@deepseek-ai/dsh-settings": "^0.1.0-rc.7 || ^0.1.1-rc.1 || ^0.1.2-rc.1",
+        "@deepseek-ai/dsh-tools": "^0.1.0-rc.7 || ^0.1.1-rc.1 || ^0.1.2-rc.1"
     },
     "optionalDependencies": {
         "potrace": "^2.1.8",
@@ -68,4 +68,3 @@
         "sharp": ">=0.35.3 <1"
     }
 }
-