@liustack/modlens 3.11.0 → 3.12.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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.
+
 ## 3.11.0 - 2026-08-14
 
 - **A full-project audit, all ten findings fixed, then re-reviewed until clean.** An independent deep review of the whole repository (P0: none) surfaced ten conditional-but-real defects. Every fix went back through further independent review rounds, which caught real bugs in the first fixes themselves (case and Unicode boundaries, a cancellation regression); the final round accepted with no blocking findings. Each item below carries a regression test — the suite grew by 32 cases.

package/dist/main.js

@@ -27414,6 +27414,51 @@ async function readCapped(response2, url) {
   }
   return Buffer.concat(chunks);
 }
+function apiProxyDispatcher(explicitProxy, env) {
+  const proxy = explicitProxy?.trim();
+  if (proxy) {
+    return new undiciExports.ProxyAgent(proxy);
+  }
+  if (env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy) {
+    return new undiciExports.EnvHttpProxyAgent();
+  }
+  return void 0;
+}
+const CONNECT_CODES = /* @__PURE__ */ new Set([
+  "UND_ERR_CONNECT_TIMEOUT",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ENOTFOUND",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ETIMEDOUT"
+]);
+function connectFailureHint(error, url) {
+  const cause = error instanceof Error ? error.cause : void 0;
+  if (!cause?.code || !CONNECT_CODES.has(cause.code)) {
+    return null;
+  }
+  let host;
+  try {
+    host = new URL(url).host;
+  } catch {
+    return null;
+  }
+  return `Could not connect to ${host} (${cause.code}). The request never reached the network. If this machine reaches the internet through a proxy, set HTTPS_PROXY/HTTP_PROXY, or run: modlens config set proxy <url>`;
+}
+async function apiFetch(url, init, proxy, env = process.env) {
+  const dispatcher2 = apiProxyDispatcher(proxy, env);
+  try {
+    return await fetch(
+      url,
+      // `dispatcher` is a Node/undici extension to fetch's options.
+      dispatcher2 ? { ...init, dispatcher: dispatcher2 } : init
+    );
+  } catch (error) {
+    const hint = connectFailureHint(error, url);
+    throw hint ? new Error(hint, { cause: error }) : error;
+  }
+}
 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"]}`;
 function buildVisionPrompt(options) {
@@ -27735,43 +27780,47 @@ async function executeAnthropicApi(options) {
 
 Report your findings by calling the ${TOOL_NAME} tool.`;
   const startedAt = Date.now();
-  const response2 = await fetch(`${baseUrl}/v1/messages`, {
-    method: "POST",
-    headers: {
-      "x-api-key": apiKey,
-      "anthropic-version": "2023-06-01",
-      "Content-Type": "application/json"
+  const response2 = await apiFetch(
+    `${baseUrl}/v1/messages`,
+    {
+      method: "POST",
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(
+        mergeExtraBody(
+          {
+            model,
+            max_tokens: 4096,
+            tools: [
+              {
+                name: TOOL_NAME,
+                description: "Report the structured visual evidence extracted from the image.",
+                input_schema: VISION_RESULT_SCHEMA
+              }
+            ],
+            tool_choice: { type: "tool", name: TOOL_NAME },
+            messages: [
+              {
+                role: "user",
+                content: [
+                  { type: "image", source: imageSource },
+                  { type: "text", text: prompt }
+                ]
+              }
+            ]
+          },
+          options.settings?.extraBody,
+          ["model", "messages", "tools", "tool_choice", "stream"],
+          "anthropic"
+        )
+      ),
+      signal: AbortSignal.timeout(options.timeoutMs)
     },
-    body: JSON.stringify(
-      mergeExtraBody(
-        {
-          model,
-          max_tokens: 4096,
-          tools: [
-            {
-              name: TOOL_NAME,
-              description: "Report the structured visual evidence extracted from the image.",
-              input_schema: VISION_RESULT_SCHEMA
-            }
-          ],
-          tool_choice: { type: "tool", name: TOOL_NAME },
-          messages: [
-            {
-              role: "user",
-              content: [
-                { type: "image", source: imageSource },
-                { type: "text", text: prompt }
-              ]
-            }
-          ]
-        },
-        options.settings?.extraBody,
-        ["model", "messages", "tools", "tool_choice", "stream"],
-        "anthropic"
-      )
-    ),
-    signal: AbortSignal.timeout(options.timeoutMs)
-  });
+    options.settings?.proxy
+  );
   if (!response2.ok) {
     const body2 = await response2.text();
     throw new Error(
@@ -27982,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,
@@ -28032,39 +28079,48 @@ async function executeGeminiApi(options) {
     extraPrompt: options.extraPrompt
   });
   const startedAt = Date.now();
-  const response2 = await fetch(`${baseUrl}/v1beta/models/${model}:generateContent`, {
-    method: "POST",
-    headers: {
-      "x-goog-api-key": apiKey,
-      "Content-Type": "application/json"
-    },
-    body: JSON.stringify(
-      mergeExtraBody(
-        {
-          contents: [
-            {
-              parts: [
-                { inline_data: { mime_type: image.mimeType, data: image.data } },
-                { text: prompt }
-              ]
+  const response2 = await apiFetch(
+    `${baseUrl}/v1beta/models/${model}:generateContent`,
+    {
+      method: "POST",
+      headers: {
+        "x-goog-api-key": apiKey,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(
+        mergeExtraBody(
+          {
+            contents: [
+              {
+                parts: [
+                  {
+                    inline_data: {
+                      mime_type: image.mimeType,
+                      data: image.data
+                    }
+                  },
+                  { text: prompt }
+                ]
+              }
+            ],
+            generationConfig: {
+              responseMimeType: "application/json",
+              responseJsonSchema: VISION_RESULT_SCHEMA
             }
+          },
+          options.settings?.extraBody,
+          [
+            "contents",
+            "generationConfig.responseMimeType",
+            "generationConfig.responseJsonSchema"
           ],
-          generationConfig: {
-            responseMimeType: "application/json",
-            responseJsonSchema: VISION_RESULT_SCHEMA
-          }
-        },
-        options.settings?.extraBody,
-        [
-          "contents",
-          "generationConfig.responseMimeType",
-          "generationConfig.responseJsonSchema"
-        ],
-        "gemini-api"
-      )
-    ),
-    signal: AbortSignal.timeout(options.timeoutMs)
-  });
+          "gemini-api"
+        )
+      ),
+      signal: AbortSignal.timeout(options.timeoutMs)
+    },
+    options.settings?.proxy
+  );
   if (!response2.ok) {
     const body2 = await response2.text();
     throw new Error(
@@ -28114,33 +28170,37 @@ async function executeOpenaiCompat(options) {
 
 ${JSON_TEMPLATE_INSTRUCTION}`;
   const startedAt = Date.now();
-  const response2 = await fetch(`${baseUrl}/chat/completions`, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      "Content-Type": "application/json"
+  const response2 = await apiFetch(
+    `${baseUrl}/chat/completions`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(
+        mergeExtraBody(
+          {
+            model,
+            messages: [
+              {
+                role: "user",
+                content: [
+                  { type: "image_url", image_url: { url: imageUrl } },
+                  { type: "text", text: prompt }
+                ]
+              }
+            ]
+          },
+          options.settings?.extraBody,
+          ["model", "messages", "stream"],
+          "openai"
+        )
+      ),
+      signal: AbortSignal.timeout(options.timeoutMs)
     },
-    body: JSON.stringify(
-      mergeExtraBody(
-        {
-          model,
-          messages: [
-            {
-              role: "user",
-              content: [
-                { type: "image_url", image_url: { url: imageUrl } },
-                { type: "text", text: prompt }
-              ]
-            }
-          ]
-        },
-        options.settings?.extraBody,
-        ["model", "messages", "stream"],
-        "openai"
-      )
-    ),
-    signal: AbortSignal.timeout(options.timeoutMs)
-  });
+    options.settings?.proxy
+  );
   if (!response2.ok) {
     const body2 = await response2.text();
     throw new Error(
@@ -28210,7 +28270,7 @@ function providerAliases() {
 function listProviders() {
   return [...new Set(Object.values(PROVIDERS).map((provider) => provider.name))];
 }
-const STRING_FIELDS = ["apiKey", "baseUrl", "model"];
+const STRING_FIELDS = ["apiKey", "baseUrl", "model", "proxy"];
 const REUSE_HARNESSES = ["claude", "codex", "opencode", "pi", "grok"];
 const CONFIG_DIR = path.join(os.homedir(), ".modlens");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
@@ -28251,6 +28311,9 @@ function resolveProviderSettings(providerName, config2, env = process.env) {
   };
   const bindings = ENV_BINDINGS[providerName] ?? {};
   const settings = { ...fromFile };
+  if (!settings.proxy && config2.proxy?.trim()) {
+    settings.proxy = config2.proxy.trim();
+  }
   for (const [field, envName] of Object.entries(bindings)) {
     const value = env[envName]?.trim();
     if (value) {
@@ -28263,6 +28326,12 @@ function setConfigValue(dottedKey, value, configPath = CONFIG_PATH) {
   const config2 = loadConfigFile(configPath);
   if (dottedKey === "provider") {
     config2.provider = value;
+  } else if (dottedKey === "proxy") {
+    if (value.trim() === "") {
+      delete config2.proxy;
+    } else {
+      config2.proxy = value.trim();
+    }
   } else if (dottedKey.startsWith("reuse.")) {
     const harness = dottedKey.slice("reuse.".length);
     if (!REUSE_HARNESSES.includes(harness)) {
@@ -28307,7 +28376,7 @@ function setConfigValue(dottedKey, value, configPath = CONFIG_PATH) {
       }
     } else if (!STRING_FIELDS.includes(field)) {
       throw new Error(
-        `Unknown config field: ${field}. Use apiKey, baseUrl, model, or extraBody.`
+        `Unknown config field: ${field}. Use apiKey, baseUrl, model, proxy, or extraBody.`
       );
     } else {
       config2.providers ??= {};
@@ -28409,6 +28478,11 @@ function renderEffectiveConfig(config2, env = process.env) {
   if (config2.provider?.trim()) {
     effective.provider = config2.provider.trim();
   }
+  if (config2.proxy?.trim()) {
+    effective.proxy = `${config2.proxy.trim()} (file)`;
+  } else if (env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy) {
+    effective.proxy = `${env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy} (env)`;
+  }
   if (config2.guards) {
     const guards = {};
     if (config2.guards.denyModels !== void 0) {
@@ -30626,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.11.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/docs/cli.md

@@ -95,6 +95,6 @@ Five providers: `antigravity-cli` (no key), `gemini-api` (fastest free route), `
 Other subcommands:
 
 - `modlens guard [--model <id>]`: should the engine run for the active model at all? Exit 0 allow, 1 deny, verdict as JSON.
-- `modlens config <init|set|show>`: keys are `provider`, `reuse.<claude|codex|opencode|pi|grok>`, `guards.<denyModels|allowModels|denyWhenUnknown>`, and `<provider>.<apiKey|baseUrl|model|extraBody>`.
+- `modlens config <init|set|show>`: keys are `provider`, `proxy` (HTTP/HTTPS proxy for the API providers, `HTTPS_PROXY`/`HTTP_PROXY` also honored), `reuse.<claude|codex|opencode|pi|grok>`, `guards.<denyModels|allowModels|denyWhenUnknown>`, and `<provider>.<apiKey|baseUrl|model|proxy|extraBody>`.
 - `modlens doctor`: Node and node:sqlite, provider readiness, the failover chains for this machine, the detected harness, the guard's rules with a live verdict, and the Reuse section with per-harness grant decisions and discovered vision. Spends no quota; `--json` for a machine-readable report.
 

package/docs/troubleshooting.md

@@ -154,6 +154,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.
 
+## fetch failed, or could not connect
+
+```
+Could not connect to generativelanguage.googleapis.com (UND_ERR_CONNECT_TIMEOUT). The request never reached the network. ...
+```
+
+The API request never left the machine. On networks that reach the internet
+through a proxy this is expected: Node's fetch ignores the proxy environment
+variables by default. modlens honors them once you ask it to route that way,
+in either form:
+
+```bash
+HTTPS_PROXY=http://127.0.0.1:7890 modlens -i shot.png -p gemini-api   # env (NO_PROXY honored too)
+modlens config set proxy http://127.0.0.1:7890                        # persistent, all API providers
+modlens config set openai.proxy http://127.0.0.1:7890                 # one provider only
+```
+
+The proxy applies to API provider requests only. The remote-image download
+path keeps its direct, IP-pinned connection on purpose: its SSRF guards
+validate the exact address being contacted, and a proxy would blind them. On
+a proxied machine, prefer local files or let the failover chain hand remote
+URLs to a provider that fetches them upstream.
+
 ## Config file problems
 
 ```

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.11.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.11.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.11.0: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.11.0 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.11.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/configure.md

@@ -22,6 +22,7 @@ Everything lives under four top-level keys, all optional. This example shows eve
 ```json
 {
   "provider": "gemini-api",
+  "proxy": "http://127.0.0.1:7890",
   "reuse": { "claude": true, "codex": true, "opencode": false, "pi": true, "grok": true },
   "guards": {
     "allowModels": ["deepseek-v4-*", "glm-5.*", "minimax-m2.5*", "qwen3-coder*"],

package/skills/modlens/references/runtime.md

@@ -8,7 +8,7 @@ shell syntax.
 
 ## Pinned version
 
-- Pinned CLI version: 3.11.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.11.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.11.0"
+PINNED="3.12.1"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"