@liustack/modlens 3.12.0 → 3.12.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 3.12.1 - 2026-08-14
+
+- **claude-cli reads the envelope's `structured_output` first ([#22](https://github.com/liustack/modlens/issues/22)).** Newer claude CLI builds ship the schema-parsed object beside the `result` string, and the parser only hard-parsed the string, so an unescaped newline in the OCR text failed the whole read while the good object sat unread — intermittently, since it depended on what the model emitted. The parse order is now `structured_output`, then fence-tolerant extraction of the result string, then the error, matching the antigravity provider. Thanks to @lin-nanxing for the precise diagnosis, down to the code lines.
+- **A `read_image` name collision no longer kills the whole dsh plugin ([#21](https://github.com/liustack/modlens/issues/21)).** Hosts with a durable attachment store mount dsh's own native `read_image` (from `dsh-tool-fs`), the duplicate registration threw, and the whole plugin fiber failed — vision wrapper included. The registration now falls back to `modlens_read_image` on a name collision (valuable exactly there: the native tool is gated on the model declaring image input and vanishes for text-only models, so the renamed bridge is the only image path left), the name is configurable via the plugin row's `toolName`, and any other registration error degrades loudly instead of taking the plugin down. Thanks to @abyss-stars for the root-cause analysis and the interim patch.
+
 ## 3.12.0 - 2026-08-14
 
 - **The API providers work behind a proxy ([#20](https://github.com/liustack/modlens/issues/20)).** Node's fetch ignores `HTTP_PROXY`/`HTTPS_PROXY` entirely, so machines that reach the internet through a proxy could not use `gemini-api` at all, and the failure surfaced as a bare `fetch failed`. The three inline API providers now honor the standard environment variables (`NO_PROXY` included, via undici's `EnvHttpProxyAgent`), with an explicit setting as the escape hatch: `modlens config set proxy <url>` for all API providers, `<provider>.proxy` to scope it to one. A connect-level failure now names the unreachable host and points at both knobs instead of saying `fetch failed`. Scope is deliberate and documented: the proxy applies to API requests only, while the remote-image download path keeps its direct, IP-pinned connection, because its SSRF guards validate the exact address being contacted and a proxy would blind them. Thanks to @soloyu for a report that arrived with the diagnosis, the fix direction, and the security boundary already thought through.

package/dist/main.js

@@ -28031,14 +28031,12 @@ function parseClaudeCliOutput(stdout) {
       `Claude CLI reported ${envelope.subtype ?? "an error"}: ${truncate(envelope.result ?? "")}`
     );
   }
-  if (typeof envelope.result !== "string" || !envelope.result.trim()) {
+  if (envelope.structured_output === void 0 && (typeof envelope.result !== "string" || !envelope.result.trim())) {
     throw new Error("Claude CLI output contains no result. Check login state (run: claude).");
   }
-  let result;
-  try {
-    result = JSON.parse(envelope.result);
-  } catch {
-    throw new Error(`Claude CLI returned non-JSON result: ${truncate(envelope.result)}`);
+  const result = envelope.structured_output ?? (typeof envelope.result === "string" ? extractJson(envelope.result) : null);
+  if (result === null || result === void 0) {
+    throw new Error(`Claude CLI returned non-JSON result: ${truncate(envelope.result ?? "")}`);
   }
   return {
     result,
@@ -30702,7 +30700,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.12.0");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.12.1");
 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"}}'`

package/dsh/index.js

@@ -47,8 +47,16 @@ export function apply(ctx, config = {}) {
   // the developer-preview registry accepts these and out-of-tree resolution
   // of @deepseek-ai/dsh-tools is not yet reliable), so this plugin owns its
   // own argument validation inside execute.
-  ctx.tools.register({
-    name: 'read_image',
+  //
+  // 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.
+  const readImageTool = (toolName) => ({
+    name: toolName,
     description:
       'Read an image through the modlens vision bridge. Use whenever a message references an image the current model cannot see: a local file path or an http(s) URL to a screenshot, photo, chart, diagram, or document scan. Returns structured evidence with every word transcribed (ocr.full_text), layout regions in reading order, semantics, and an uncertainty list; quote the evidence instead of guessing. Requires a configured modlens engine (run `npx @liustack/modlens doctor` in a terminal to check).',
     parameters: {
@@ -106,6 +114,24 @@ export function apply(ctx, config = {}) {
       return parsed.result
     },
   })
+  const preferred = config.toolName || '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}`)
+    }
+  }
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liustack/modlens",
-  "version": "3.12.0",
+  "version": "3.12.1",
   "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.12.0):
+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.12.1):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.12.0: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.12.0 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.12.0 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.12.1: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.12.1 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.12.1 <args>`.
 4. Otherwise tell the user no JavaScript runtime was found and that installing Node 22.13+ (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.12.0
+- Pinned CLI version: 3.12.1
 - 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.12.0'
+$Pinned = '3.12.1'
 # -------------------------------------------------------------------------------
 
 $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.12.0"
+PINNED="3.12.1"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"