@liustack/modlens 3.16.2 → 3.16.3

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 3.16.3 - 2026-08-15
+
+- **The dsh tool is registered under a name of its own, so the model can actually see it ([#34](https://github.com/liustack/modlens/issues/34)).** A host with a durable attachment store mounts its own `read_image`, and 3.13.0 handled that by catching the duplicate-registration error and renaming. That catch never fired. dsh's tool registry is layered and a scoped tool shadows a global one, so a host `read_image` in the agent-preset scope and ours registered globally are not a duplicate at all: the registration succeeded, nothing was logged, and the model kept resolving the host tool, which refuses a text-only model outright. Nor is the collision cheap to detect, so the tool now takes the name `modlens_read_image` instead of competing for `read_image`, and the model finds it through the schema that reaches it every request regardless of the name. `toolName` still pins whatever a host prefers. Thanks to @ingleav626-art, who instrumented the registry and brought back the layer that made the old fix dead code.
+- **A region kind outside the common list no longer fails the read ([#34](https://github.com/liustack/modlens/issues/34)).** `layout.regions[].type` was a closed enum, so a model answering `link` on any web screenshot or `search` on a portal produced a result the schema rejected, losing the entire read over a descriptive label. Region kinds are an open set: the same reporter found that extending the list to 13 values still was not enough. The field is a free string now, and the common vocabulary moved into its schema description, where it guides every provider that enforces the schema server-side without constraining any of them.
+
 ## 3.16.2 - 2026-08-14
 
 - **The claude-cli provider starts on Windows ([#31](https://github.com/liustack/modlens/issues/31)).** npm installs every JS CLI as a trio, and both ways of reaching it failed: the bare name found none of them (ENOENT, reported as "not installed" next to a `claude --version` that worked fine), and handing spawn the `.cmd` hit Node's post-CVE refusal to run batch files without a shell (EINVAL). Wrapping it in `cmd.exe` turned out to be a trap, since a cmd command line cannot carry a raw newline and our provider arguments are whole multi-line vision prompts, so a wrapped prompt truncates at its first line break and the rest is read as a second command. modlens instead reads the shim, takes the Node entry it points at, and spawns Node on it directly: no shell, no escaping, and the child is the real provider, so a timeout's SIGTERM lands on it rather than an intermediate. The reading is conservative by construction. Every line of the shim must be accounted for, the interpreter is read rather than inferred (cmd-shim will happily generate a python shim for a file named `.js`), and a shim carrying anything this cannot reproduce faithfully, an environment assignment, cmd control syntax, an argument whose quoting it cannot prove, is declined and left to a spawn error that names the provider, the command, and the real error code. Nine rounds of independent review shaped that boundary, each round adding a shape it had to refuse rather than guess at. Thanks to @zhang66633 for a report that arrived with both failure modes already isolated.

package/README.md

@@ -34,9 +34,9 @@ Issues are welcome any time: [open one](https://github.com/liustack/modlens/issu
 
 ## Highlights
 
-**🥇 The first vision plugin for DeepSeek Harness (dsh):** one command, `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest`, and the text-only DeepSeek model behind dsh reads images through a native `read_image` tool. If dsh warns `declares no dsh.bundle`, pnpm's release-age gate installed an old version: see [troubleshooting](docs/troubleshooting.md#dsh-says-declares-no-dshbundle--installed-as-a-plain-dependency) for the one-line fix.
+**🥇 The first vision plugin for DeepSeek Harness (dsh):** one command, `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest`, and the text-only DeepSeek model behind dsh reads images through a native `modlens_read_image` tool. If dsh warns `declares no dsh.bundle`, pnpm's release-age gate installed an old version: see [troubleshooting](docs/troubleshooting.md#dsh-says-declares-no-dshbundle--installed-as-a-plain-dependency) for the one-line fix.
 
-Pasting an image works two ways. **① Just paste.** On a text-only model the pasted image lands as a private temp file and its path enters the composer — the same interaction OpenCode and Pi ship — and the `read_image` tool takes it from there. **② Pick a `(modlens vision)` entry** in the model selector (it remembers your choice, so once is enough), then paste: the thumbnail stays visible in your message, closer to the Codex app feel, and the image is converted to structured evidence at request time, answered by the same underlying route. The plugin auto-discovers every provider route carrying text-only DeepSeek or GLM models and adds a wrapped entry per route (a stock install gets **`DeepSeek-V4-Flash (modlens vision)`** and **`DeepSeek-V4-Pro (modlens vision)`**; extra routes like opencode-go or zai get their own); the two families' own vision models are excluded automatically. Which paste route applies is the host's per-model call: only a model its metadata positively confirms text-only is taken over, anything unconfirmed is left alone, so vision models keep their native paste ([details](docs/harness-setup.md)).
+Pasting an image works two ways. **① Just paste.** On a text-only model the pasted image lands as a private temp file and its path enters the composer — the same interaction OpenCode and Pi ship — and the `modlens_read_image` tool takes it from there. **② Pick a `(modlens vision)` entry** in the model selector (it remembers your choice, so once is enough), then paste: the thumbnail stays visible in your message, closer to the Codex app feel, and the image is converted to structured evidence at request time, answered by the same underlying route. The plugin auto-discovers every provider route carrying text-only DeepSeek or GLM models and adds a wrapped entry per route (a stock install gets **`DeepSeek-V4-Flash (modlens vision)`** and **`DeepSeek-V4-Pro (modlens vision)`**; extra routes like opencode-go or zai get their own); the two families' own vision models are excluded automatically. Which paste route applies is the host's per-model call: only a model its metadata positively confirms text-only is taken over, anything unconfirmed is left alone, so vision models keep their native paste ([details](docs/harness-setup.md)).
 
 **Paste an image and it reads it.** No saving to a file and passing a path first.
 

package/README.zh-CN.md

@@ -34,11 +34,11 @@ DeepSeek 和 GLM 的主力对话模型是纯文本的，无法进行图片识别
 
 ## 亮点
 
-**🥇 全网第一个支持 DeepSeek Harness（dsh）的外挂视觉识别插件：**一条命令 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest`，dsh 背后的纯文本 DeepSeek 模型即可通过原生 `read_image` 工具读图。如果 dsh 提示 `declares no dsh.bundle`，是 pnpm 的发布冷静期装了旧版，一行命令可解，见[故障排查](docs/troubleshooting.zh-CN.md#dsh-提示-declares-no-dshbundle--installed-as-a-plain-dependency)。
+**🥇 全网第一个支持 DeepSeek Harness（dsh）的外挂视觉识别插件：**一条命令 `npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest`，dsh 背后的纯文本 DeepSeek 模型即可通过原生 `modlens_read_image` 工具读图。如果 dsh 提示 `declares no dsh.bundle`，是 pnpm 的发布冷静期装了旧版，一行命令可解，见[故障排查](docs/troubleshooting.zh-CN.md#dsh-提示-declares-no-dshbundle--installed-as-a-plain-dependency)。
 
 DeepSeek Harness 粘贴识图有两种玩法。
 
-**① 直接粘贴** 贴进来的图片自主转换成文件路径进输入框（与 OpenCode、Pi 同款交互），`read_image` 工具接手读图。
+**① 直接粘贴** 贴进来的图片自主转换成文件路径进输入框（与 OpenCode、Pi 同款交互），`modlens_read_image` 工具接手读图。
 
 **② 切到带 `(modlens vision)` 后缀的模型变体**（选择器有记忆，选一次就行）再粘贴：缩略图直接可见、所见即所得，体验更接近 Codex App。变体由插件自动发现生成：每条承载纯文本 DeepSeek 或 GLM 模型的 provider 路由各得一组包装条目（默认安装下就是 **`DeepSeek-V4-Flash (modlens vision)`** 和 **`DeepSeek-V4-Pro (modlens vision)`**，装了 opencode-go、zai 等额外路由的机器会各自多出一组），两家自己的视觉型号自动排除。走哪条通路由 host 依据真实模型元数据逐个裁决：只有被元数据确认纯文本的模型才会被接管，确认不了的一律不动，视觉模型因此保留原生贴图（[细节](docs/harness-setup.zh-CN.md)）。
 
@@ -72,7 +72,7 @@ agy                                                           # 浏览器完成
 npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest
 ```
 
-装完即有 `read_image` 工具，选「(modlens vision)」模型变体即可直接粘贴识图。引擎配置同样在 `~/.modlens`，详见[宿主接入](docs/harness-setup.zh-CN.md)。
+装完即有 `modlens_read_image` 工具，选「(modlens vision)」模型变体即可直接粘贴识图。引擎配置同样在 `~/.modlens`，详见[宿主接入](docs/harness-setup.zh-CN.md)。
 
 ## 用法
 

package/dist/main.js

@@ -501,7 +501,7 @@ async function apiFetch(url, init, proxy, env = process.env) {
   }
 }
 const JSON_TEMPLATE_INSTRUCTION = `Respond with ONE JSON object only, no markdown fences, no commentary. Fill this exact structure with your findings from the image (do not repeat this template literally, replace every value):
-{"summary":"one paragraph describing the image","ocr":{"full_text":"all visible text","lines":[{"text":"one line","language":"en"}]},"layout":{"regions":[{"type":"title|subtitle|paragraph|list|table|chart|form|code|image|icon|other","reading_order":1,"text":"region text"}]},"semantics":{"scene":"what kind of scene","intent":"what the image is for","entities":[{"name":"entity","type":"kind","evidence":"where seen"}],"relations":[{"subject":"a","predicate":"relates to","object":"b"}]},"visual":{"dominant_colors":["color"],"style":"visual style","notes":["notable visual detail"]},"uncertainty":["anything unreadable or ambiguous"]}`;
+{"summary":"one paragraph describing the image","ocr":{"full_text":"all visible text","lines":[{"text":"one line","language":"en"}]},"layout":{"regions":[{"type":"a short kind, e.g. title, heading, paragraph, list, table, chart, form, code, image, icon, link, nav, button, search, or any other short label that fits better","reading_order":1,"text":"region text"}]},"semantics":{"scene":"what kind of scene","intent":"what the image is for","entities":[{"name":"entity","type":"kind","evidence":"where seen"}],"relations":[{"subject":"a","predicate":"relates to","object":"b"}]},"visual":{"dominant_colors":["color"],"style":"visual style","notes":["notable visual detail"]},"uncertainty":["anything unreadable or ambiguous"]}`;
 function buildVisionPrompt(options) {
   const readInstruction = options.imageKind === "inline" ? "Analyze the image attached to this message." : options.imageKind === "remote" ? `Fetch the image at this URL and analyze it: ${options.imageSource}` : `Read the image file at this path and analyze it: ${options.imageSource}`;
   const basePrompt = `${readInstruction}
@@ -553,21 +553,18 @@ const VISION_RESULT_SCHEMA = {
           items: {
             type: "object",
             properties: {
+              // Deliberately not an enum. Region kinds are an
+              // open set: a closed list rejected `link` on any
+              // web screenshot and `search` on a portal, and a
+              // rejected result fails the whole read over a
+              // descriptive label (issue #34). The common
+              // vocabulary moves into the description, which
+              // guides without constraining and rides along to
+              // every provider that enforces this schema
+              // server-side.
               type: {
                 type: "string",
-                enum: [
-                  "title",
-                  "subtitle",
-                  "paragraph",
-                  "list",
-                  "table",
-                  "chart",
-                  "form",
-                  "code",
-                  "image",
-                  "icon",
-                  "other"
-                ]
+                description: "A short kind for this region. Prefer a common one where it fits: title, heading, paragraph, list, table, chart, form, code, image, icon, link, nav, button, search. Any other short label is fine when none of those describe it."
               },
               reading_order: { type: "number" },
               text: { type: "string" }
@@ -4072,7 +4069,7 @@ function parsePositiveInt(raw, flag) {
   }
   return Number.parseInt(raw, 10);
 }
-program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.16.2");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.16.3");
 program.command("analyze", { isDefault: true }).description("Analyze an image into structured JSON evidence (default command)").requiredOption("-i, --input <path|url>", "Input image path or https URL").option("-o, --output <path>", "Write result JSON to a file").option("-m, --model <name>", "Provider model name").option("-p, --provider <name>", `Vision provider (${listProviders().join(", ")})`).option("--prompt <text>", "Extra focus for this image").option("--timeout <ms>", "Provider timeout in milliseconds", "180000").option("--provider-bin <path>", "Provider binary path (default: agy)").option("--workdir <path>", "Working directory for the provider").option(
   "--extra-body <json>",
   `JSON merged into the API request body, e.g. '{"thinking":{"type":"disabled"}}'`
@@ -4182,7 +4179,7 @@ program.command("doctor").description(
       configPath: CONFIG_PATH,
       // Lets doctor name an installed skill copy that is older than
       // the CLI reporting on it (issue #33).
-      version: "3.16.2"
+      version: "3.16.3"
     });
     const output = options.json ? JSON.stringify(report, null, 2) : renderDoctorReport(report);
     process.stdout.write(`${output}

package/docs/harness-setup.md

@@ -58,7 +58,7 @@ dsh is different from the other harnesses: modlens plugs in as a native tool, no
 npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest
 ```
 
-This registers a `read_image` tool whose schema reaches the model on every request (no trigger heuristics), runs the modlens CLI shipped inside the same package, and returns the structured evidence as the tool's canonical JSON output. Engines, reuse grants, and guard rules stay in `~/.modlens/config.json`, shared with every other harness. dsh is in developer preview and its plugin surface may change; the plugin keeps its touch small (raw tool registration, the llm adapter surface for the vision variants, the attachment reader, and one agent pre-step hook) and degrades loudly if any of them moves.
+This registers a `modlens_read_image` tool whose schema reaches the model on every request (no trigger heuristics), runs the modlens CLI shipped inside the same package, and returns the structured evidence as the tool's canonical JSON output. Engines, reuse grants, and guard rules stay in `~/.modlens/config.json`, shared with every other harness. dsh is in developer preview and its plugin surface may change; the plugin keeps its touch small (raw tool registration, the llm adapter surface for the vision variants, the attachment reader, and one agent pre-step hook) and degrades loudly if any of them moves.
 
 ### Paste-to-path (web profile)
 
@@ -69,7 +69,7 @@ the image bytes go to the plugin's `/modlens/paste` route on the dsh web
 server (loopback, magic-byte checked, 25 MB cap), land as a private temp file,
 and the composer receives the file path as plain text — the same shape Pi,
 OpenCode, and Claude Code hand their models, and the modlens skill's and
-`read_image` tool's primary trigger. Admission never fires because the message
+`modlens_read_image` tool's primary trigger. Admission never fires because the message
 carries no image attachment.
 
 The takeover is conditional, and the decision is the host's: the browser half

package/docs/harness-setup.zh-CN.md

@@ -58,10 +58,10 @@ dsh 与其他 harness 不同：modlens 以原生工具的形式接入，而不
 npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest
 ```
 
-这会注册一个 `read_image` 工具，它的 schema 随每次请求抵达模型（不靠触发启发式），运行同一个包里自带的 modlens CLI，并把结构化证据作为工具的标准 JSON 输出返回。引擎、复用授权和 guard 规则仍在 `~/.modlens/config.json` 里，与其他所有 harness 共享。dsh 还在开发者预览阶段，插件接口可能变化。这个插件刻意保持很小的接触面（原生工具注册、视觉变体所用的 llm 适配层、附件读取器，以及一个 agent 执行前钩子），其中任何一处变动，它都会大声报错而不是无声退化。
+这会注册一个 `modlens_read_image` 工具，它的 schema 随每次请求抵达模型（不靠触发启发式），运行同一个包里自带的 modlens CLI，并把结构化证据作为工具的标准 JSON 输出返回。引擎、复用授权和 guard 规则仍在 `~/.modlens/config.json` 里，与其他所有 harness 共享。dsh 还在开发者预览阶段，插件接口可能变化。这个插件刻意保持很小的接触面（原生工具注册、视觉变体所用的 llm 适配层、附件读取器，以及一个 agent 执行前钩子），其中任何一处变动，它都会大声报错而不是无声退化。
 
 ### 粘贴转路径（paste-to-path，web profile）
 
-过去在 dsh Web UI 里，**纯文本模型**下粘贴图片会死在图片准入检查这一步。插件现在带了一个浏览器端半边（由 dsh 的客户端插件系统自动加载），恰好在这种情况下接管粘贴：图片字节发到插件在 dsh web 服务器上的 `/modlens/paste` 路由（仅回环地址，校验 magic byte，上限 25 MB），落成一个私有临时文件，输入框收到的则是纯文本的文件路径。这与 Pi、OpenCode、Claude Code 递给模型的形态一致，也正是 modlens skill 和 `read_image` 工具的首要触发条件。消息里不带图片附件，准入检查根本不会触发。
+过去在 dsh Web UI 里，**纯文本模型**下粘贴图片会死在图片准入检查这一步。插件现在带了一个浏览器端半边（由 dsh 的客户端插件系统自动加载），恰好在这种情况下接管粘贴：图片字节发到插件在 dsh web 服务器上的 `/modlens/paste` 路由（仅回环地址，校验 magic byte，上限 25 MB），落成一个私有临时文件，输入框收到的则是纯文本的文件路径。这与 Pi、OpenCode、Claude Code 递给模型的形态一致，也正是 modlens skill 和 `modlens_read_image` 工具的首要触发条件。消息里不带图片附件，准入检查根本不会触发。
 
 接管是有条件的，且裁决权在 host 一侧：浏览器半边先向插件路由询问当前选中的模型是否纯文本，host 用 provider 注册表里声明的模型元数据（`inputModalities`）回答，而不是靠名称猜。`(modlens vision)` 变体和任何声明支持图片输入的模型都保留原生粘贴流程（变体在发请求时转换且保留缩略图，视觉模型自己读图），host 认不出的模型同样不接管：在 host 确认该接管之前，粘贴一律走原生路径。模型元数据里没有声明输入模态的，一律算认不出：元数据缺失绝不当成「已确认纯文本」。裁决还有 60 秒时效，模型中途变了会重新问询，不会永远信旧答案。在插件配置行里设 `pasteToPath: false` 可整体关掉这个功能：策略端点 404 时浏览器半边彻底停手。若路由在裁决确认后中途消失，失败结果返回前那个短暂窗口（一次本地往返）内发生的粘贴会丢失，之后客户端清空全部裁决，后续粘贴一律走原生路径。

package/docs/output-schema.md

@@ -44,7 +44,7 @@ The CLI prints one JSON object to stdout:
   "layout": {
     "regions": [
       {
-        "type": "title|subtitle|paragraph|list|table|chart|form|code|image|icon|other",
+        "type": "string (a short kind: title, paragraph, list, table, chart, form, code, image, icon, link, nav, ...)",
         "reading_order": 1,
         "text": "string"
       }
@@ -71,4 +71,6 @@ The CLI prints one JSON object to stdout:
 
 Required fields: `summary`, `ocr`, `layout`, `semantics`, `visual`, `uncertainty` — every top-level field, `visual` included. (Earlier docs called `visual` optional; the enforced schema has always required it, so build to the schema.)
 
-Changes from v1: pixel `bbox` coordinates and numeric `confidence` scores were removed. Vision models fabricate both, so v2 stops pretending to provide them. `layout.regions[].type` gained `code`.
+`layout.regions[].type` is a free string, not a closed list. Region kinds are an open set: a fixed enum rejected `link` on any web screenshot and `search` on a portal, and a rejected result fails the whole read over a descriptive label. The field's schema `description` names the common vocabulary as guidance, which reaches every provider that enforces this schema server-side, so an unlisted kind costs nothing.
+
+Changes from v1: pixel `bbox` coordinates and numeric `confidence` scores were removed. Vision models fabricate both, so v2 stops pretending to provide them.

package/docs/output-schema.zh-CN.md

@@ -44,7 +44,7 @@ CLI 向 stdout 打印一个 JSON 对象：
   "layout": {
     "regions": [
       {
-        "type": "title|subtitle|paragraph|list|table|chart|form|code|image|icon|other",
+        "type": "string (a short kind: title, paragraph, list, table, chart, form, code, image, icon, link, nav, ...)",
         "reading_order": 1,
         "text": "string"
       }
@@ -71,4 +71,6 @@ CLI 向 stdout 打印一个 JSON 对象：
 
 必填字段：`summary`、`ocr`、`layout`、`semantics`、`visual`、`uncertainty`，也就是每一个顶层字段，`visual` 也不例外。（早期文档把 `visual` 写成可选，但强制执行的 schema 一直要求它，请以 schema 为准。）
 
-相对 v1 的变化：删掉了像素级 `bbox` 坐标和数值型 `confidence` 分数。视觉模型会凭空编造这两样，v2 不再假装提供。`layout.regions[].type` 新增了 `code`。
+`layout.regions[].type` 是自由字符串，不是封闭列表。区域类型本质是开放集合：固定枚举会让任何网页截图里的 `link`、门户页里的 `search` 直接落选，而一次落选就为了一个描述性标签废掉整次识别。常用词表写在该字段的 schema `description` 里作为指引，凡是在服务端强制执行这份 schema 的 provider 都会收到，没列到的类型不会有任何代价。
+
+相对 v1 的变化：删掉了像素级 `bbox` 坐标和数值型 `confidence` 分数。视觉模型会凭空编造这两样，v2 不再假装提供。

package/docs/troubleshooting.md

@@ -156,6 +156,29 @@ The trade-off is honest either way: an explicit `@latest` (or the exclusion)
 opts modlens out of pnpm's supply-chain cooling-off window, so new releases
 install immediately.
 
+## dsh: the model cannot see the read_image tool
+
+The plugin registers its tool as `modlens_read_image`, not `read_image`. dsh's
+tool registry is layered, and a scoped tool shadows a global one: a host
+`read_image` mounted in the agent-preset scope and a plugin's registered
+globally are not a duplicate at all, so the registration succeeds silently and
+the model still resolves the host's, which refuses a text-only model outright
+([#34](https://github.com/liustack/modlens/issues/34)). Under our own name
+there is nothing to shadow it, and the model finds the tool through its
+schema, which reaches it on every request regardless of the name.
+
+If the model still cannot see it, check the harness log for
+`[modlens] ... registration skipped`. `toolName` in the plugin row pins a
+different name, but pick one nothing else uses: any name a scoped tool already
+holds will be shadowed exactly the way `read_image` is, which puts you back in
+this section.
+
+```yaml
+- id: modlens
+  config:
+    toolName: vision_read_image
+```
+
 ## fetch failed, or could not connect
 
 ```

package/docs/troubleshooting.zh-CN.md

@@ -142,6 +142,18 @@ minimumReleaseAgeExclude:
 
 然后执行 `npx -y @deepseek-ai/dsh plugin --profile <name> update @liustack/modlens`。两种方式的代价都摆在明面上：显式 `@latest`（或这条排除）让 modlens 退出 pnpm 的供应链冷静期，新版本会立即装上。
 
+## dsh：模型看不到 read_image 工具
+
+插件注册的工具名是 `modlens_read_image`，不是 `read_image`。dsh 的工具注册表是分层的，scoped 层会遮蔽全局层：宿主的 `read_image` 挂在 agent preset 作用域、插件注册在全局层，两者根本不算重名，于是注册静默成功，模型解析到的仍是宿主那个，而它对纯文本模型直接拒绝（[#34](https://github.com/liustack/modlens/issues/34)）。用自己的名字就没有东西会遮蔽它，模型是通过工具 schema 找到它的，而 schema 每次请求都会送达，与叫什么名字无关。
+
+如果模型仍然看不到，去 harness 日志里搜 `[modlens] ... registration skipped`。想改名就在插件配置行里设 `toolName`，但要挑一个别人没用的：任何已被某个 scoped 工具占用的名字，都会像 `read_image` 一样被遮蔽，那就又绕回本节了。
+
+```yaml
+- id: modlens
+  config:
+    toolName: vision_read_image
+```
+
 ## fetch failed 或连接失败
 
 ```

package/dsh/client.js

@@ -7,7 +7,7 @@
 // (POST /modlens/paste), land as a private temp file, and the returned path
 // is inserted into the composer as plain text. A text-only model then sees
 // exactly what Pi, OpenCode, and Claude Code hand their models: a file path,
-// which is also the modlens skill's and read_image tool's primary trigger.
+// which is also the modlens skill's and the read tool's primary trigger.
 //
 // Hand-written in the lazy-CJS bundle protocol (window.__ModuleLoader__.load
 // with a factory returning cordis-plugin exports), so no build step and no

package/dsh/index.js

@@ -1,8 +1,10 @@
-// DeepSeek Harness (dsh) plugin: registers a read_image tool backed by the
-// modlens CLI that ships in this very package. dsh models are text-only, so
-// the tool is the vision bridge; unlike prompt-triggered skills, a registered
-// tool schema reaches the model on every request, so there is no trigger
-// gamble. The engine is spawned from ../dist/main.js inside this package:
+// DeepSeek Harness (dsh) plugin: registers a modlens_read_image tool backed
+// by the modlens CLI that ships in this very package. dsh models are
+// text-only, so the tool is the vision bridge; unlike prompt-triggered
+// skills, a registered tool schema reaches the model on every request, so
+// there is no trigger gamble. The name is ours rather than the host's
+// `read_image` (see the registration in apply, and issue #34).
+// The engine is spawned from ../dist/main.js inside this package:
 // no PATH lookup, no npx, the plugin and its engine version-lock together.
 //
 // Loaded via the cordis.patch.yml row `@liustack/modlens/dsh` (see the
@@ -66,13 +68,11 @@ export function apply(ctx, config = {}) {
   // of @deepseek-ai/dsh-tools is not yet reliable), so this plugin owns its
   // own argument validation inside execute.
   //
-  // The name can collide: hosts with a durable attachment store mount their
-  // own native read_image (dsh-tool-fs), and a duplicate registration throws,
-  // which used to fail the whole plugin fiber (issue #21). The collision
-  // falls back to a prefixed name — valuable exactly there, since the native
-  // tool is gated on the model declaring image input and vanishes for
-  // text-only models — and any other registration error degrades loudly
-  // instead of taking the vision wrapper down with it.
+  // The name is ours by default (see the registration below): hosts with a
+  // durable attachment store mount their own native read_image (dsh-tool-fs),
+  // which is gated on the model declaring image input and so refuses the
+  // text-only models this plugin exists for. Any registration error degrades
+  // loudly instead of taking the vision wrapper down with it (issue #21).
   const readImageTool = (toolName) => ({
     name: toolName,
     description:
@@ -100,7 +100,7 @@ export function apply(ctx, config = {}) {
     isConcurrencySafe: () => true,
     presentCall: (args) => ({
       card: 'generic',
-      title: 'read_image',
+      title: toolName,
       kind: 'read',
       rawInput: args,
       ...(typeof args?.path === 'string' && !/^https?:\/\//i.test(args.path)
@@ -109,7 +109,7 @@ export function apply(ctx, config = {}) {
     }),
     async execute(args, exec) {
       if (typeof args?.path !== 'string' || args.path.trim() === '') {
-        throw new Error('read_image needs a non-empty string "path".')
+        throw new Error(`${toolName} needs a non-empty string "path".`)
       }
       const cliArgs = [CLI_PATH, '-i', args.path, '--timeout', String(CLI_TIMEOUT_MS)]
       if (args.prompt) {
@@ -130,21 +130,24 @@ export function apply(ctx, config = {}) {
       return parsed.result
     },
   })
-  const preferred = config.toolName || 'read_image'
+  // A name of our own rather than the host's. dsh's registry is layered and
+  // a scoped tool shadows a global one, so a host `read_image` mounted in the
+  // agent-preset scope and ours registered globally are not a duplicate at
+  // all: the registration succeeds, nothing throws, and the model still
+  // resolves the host's (issue #34). Detecting that from here would mean
+  // walking every agent (`agents.list()` plus `agent/created`) and asking
+  // `tools.get(name, agent)` per scope, then mutating a global catalog per
+  // agent. Not entering the collision is cheaper: no host tool is known to
+  // use this name, and the model finds ours through its schema, which reaches
+  // it on every request regardless of what the tool is called. `toolName`
+  // still pins whatever a host prefers.
+  const preferred = config.toolName || 'modlens_read_image'
   try {
     ctx.tools.register(readImageTool(preferred))
   } catch (error) {
-    const fallback = 'modlens_read_image'
-    if (preferred !== fallback && /already|duplicate/i.test(String(error))) {
-      try {
-        ctx.tools.register(readImageTool(fallback))
-        console.error(`[modlens] tool name "${preferred}" is taken by the host; registered as "${fallback}" instead`)
-      } catch (retryError) {
-        console.error(`[modlens] read_image registration skipped: ${retryError}`)
-      }
-    } else {
-      console.error(`[modlens] read_image registration skipped: ${error}`)
-    }
+    // Same-layer duplicate of the chosen name, or a preview-era surface
+    // change: degrade loudly instead of taking the whole plugin down.
+    console.error(`[modlens] ${preferred} registration skipped: ${error}`)
   }
 }
 
@@ -381,7 +384,7 @@ function registerPasteRoute(ctx, host) {
  * turns the image into evidence text before the delegated request goes out;
  * the upstream serializer's own image rejection stays as the fail-closed
  * backstop. Guarded feature-detection: if the llm registration surface moved
- * (developer preview), the plugin quietly stays a read_image-only tool.
+ * (developer preview), the plugin quietly stays a read-only-tool plugin.
  *
  * Two modes (issue #29, design contributed by @zlycode01):
  * - `config.upstream` set: wrap exactly that one route, legacy behavior.
@@ -469,7 +472,7 @@ function registerVisionProvider(ctx, config) {
         console.error(`[modlens] vision provider ${providerId} already registered, keeping the existing one`)
         return true
       }
-      // A preview-era surface change: degrade to the read_image-only plugin,
+      // A preview-era surface change: degrade to the tool-only plugin,
       // but say so in the harness log instead of vanishing (a swallowed
       // TypeError here once hid a missing base method).
       console.error(`[modlens] vision provider registration skipped (${providerId}): ${error}`)

package/dsh/vision-schema.json

@@ -1 +1 @@
-{"type":"object","properties":{"summary":{"type":"string"},"ocr":{"type":"object","properties":{"full_text":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"language":{"type":"string"}},"required":["text"]}}},"required":["full_text","lines"]},"layout":{"type":"object","properties":{"regions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["title","subtitle","paragraph","list","table","chart","form","code","image","icon","other"]},"reading_order":{"type":"number"},"text":{"type":"string"}},"required":["type","reading_order","text"]}}},"required":["regions"]},"semantics":{"type":"object","properties":{"scene":{"type":"string"},"intent":{"type":"string"},"entities":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"evidence":{"type":"string"}},"required":["name","type"]}},"relations":{"type":"array","items":{"type":"object","properties":{"subject":{"type":"string"},"predicate":{"type":"string"},"object":{"type":"string"}},"required":["subject","predicate","object"]}}},"required":["scene","entities"]},"visual":{"type":"object","properties":{"dominant_colors":{"type":"array","items":{"type":"string"}},"style":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}},"uncertainty":{"type":"array","items":{"type":"string"}}},"required":["summary","ocr","layout","semantics","visual","uncertainty"]}
+{"type":"object","properties":{"summary":{"type":"string"},"ocr":{"type":"object","properties":{"full_text":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"language":{"type":"string"}},"required":["text"]}}},"required":["full_text","lines"]},"layout":{"type":"object","properties":{"regions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"A short kind for this region. Prefer a common one where it fits: title, heading, paragraph, list, table, chart, form, code, image, icon, link, nav, button, search. Any other short label is fine when none of those describe it."},"reading_order":{"type":"number"},"text":{"type":"string"}},"required":["type","reading_order","text"]}}},"required":["regions"]},"semantics":{"type":"object","properties":{"scene":{"type":"string"},"intent":{"type":"string"},"entities":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"evidence":{"type":"string"}},"required":["name","type"]}},"relations":{"type":"array","items":{"type":"object","properties":{"subject":{"type":"string"},"predicate":{"type":"string"},"object":{"type":"string"}},"required":["subject","predicate","object"]}}},"required":["scene","entities"]},"visual":{"type":"object","properties":{"dominant_colors":{"type":"array","items":{"type":"string"}},"style":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}},"uncertainty":{"type":"array","items":{"type":"string"}}},"required":["summary","ocr","layout","semantics","visual","uncertainty"]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@liustack/modlens",
-    "version": "3.16.2",
+    "version": "3.16.3",
     "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
     "type": "module",
     "bin": {

package/skills/modlens/SKILL.md

@@ -20,11 +20,11 @@ powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 <args>
 
 It resolves a working runtime (PATH `modlens`, then `npx`, then `bunx`) and forwards your arguments unchanged. Exit 78 means no runtime: relay the `nextSteps` from its stderr JSON instead of retrying.
 
-If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.16.2):
+If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.16.3):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.16.2: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.16.2 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.16.2 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.16.3: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.16.3 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.16.3 <args>`.
 4. Otherwise tell the user no JavaScript runtime was found and that installing Node 22.19+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not claim modlens itself failed.
 
 `references/runtime.md` documents the pin and the diagnostic fields.

package/skills/modlens/references/runtime.md

@@ -8,7 +8,7 @@ shell syntax.
 
 ## Pinned version
 
-- Pinned CLI version: 3.16.2
+- Pinned CLI version: 3.16.3
 - npm package: `@liustack/modlens`
 - CLI binary name: `modlens`
 

package/skills/modlens/scripts/run.ps1

@@ -24,7 +24,7 @@ $ErrorActionPreference = 'Stop'
 # package.json version, and the release script rewrites it on every bump.
 $Package = '@liustack/modlens'
 $Bin = 'modlens'
-$Pinned = '3.16.2'
+$Pinned = '3.16.3'
 # -------------------------------------------------------------------------------
 
 $NativeNote = 'no native artifact is published for this tool yet; phase A ships npm launch paths only'

package/skills/modlens/scripts/run.sh

@@ -22,7 +22,7 @@ set -eu
 # package.json version, and the release script rewrites it on every bump.
 PKG="@liustack/modlens"
 BIN="modlens"
-PINNED="3.16.2"
+PINNED="3.16.3"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"