@liustack/modlens 3.13.0 → 3.14.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 3.14.0 - 2026-08-14
+
+- **dsh: pasting into a text-only model now just works — the paste becomes a file path.** The plugin grows a browser half (a hand-written bundle in dsh's client plugin protocol, zero dependencies, loaded automatically under the web profile). A capture-phase listener takes over image pastes before the composer's own intake: the bytes go to the plugin's `/modlens/paste` route on the dsh web server (loopback-bound, magic-byte checked, 25 MB cap, private 0600 temp file), and the composer receives the file path as plain text — the exact shape Pi, OpenCode, and Claude Code hand their models, and the modlens skill's primary trigger. Image admission never fires because the message carries no image attachment; verified end to end with a native text-only DeepSeek-V4-Flash, whose visible reasoning quoted the modlens skill rule and went for the path. The takeover is conditional: `(modlens vision)` variants and known vision models keep the native paste flow (thumbnails and all), and `pasteToPath: false` turns the feature off. The host route rides a scoped `ctx.inject(['webServer'], ...)`, so headless profiles never see any of it.
+- **The CLI survives Electron hosts ([#25](https://github.com/liustack/modlens/issues/25)).** In the packaged dsh desktop app, `process.execPath` is the Electron binary, and commander's Electron auto-detection then mis-slices argv so the script path lands as a stray positional (`too many arguments for 'analyze'`). The CLI now parses argv with explicit node semantics — it is always spawned script-first, whatever binary hosts it — and the plugin's spawns set `ELECTRON_RUN_AS_NODE` for good measure. Thanks to @hi-fangj for tracing it into commander's `_prepareUserArgs`.
+
 ## 3.13.0 - 2026-08-14
 
 - **Proxy support actually works now ([#23](https://github.com/liustack/modlens/issues/23)).** 3.12.0's proxy path was broken on arrival, twice over: the bundled copy of undici had its internal `node:http2` references destroyed by bundling (the embedded `ProxyAgent` threw `http2.connect is not a function`), and handing any undici 8 dispatcher to the host's built-in fetch (a different undici major) fails with `UND_ERR_INVALID_ARG` regardless. undici is no longer bundled — it resolves from `node_modules`, shrinking the CLI bundle from 1.17 MB to 131 KB — and the proxied path now uses undici's own fetch so dispatcher and fetch are same-sourced, with the dispatcher closed after the response so its keep-alive pool cannot pin the process open. A new integration test drives the built CLI through a real local HTTP proxy, the exact coverage whose absence let 3.12.0 ship broken (and whose first draft repeated a classic mistake: `spawnSync` freezes the test's own fake servers, so the CLI must be spawned async); both the env-var and explicit-setting forms were also verified against a real LAN proxy. Independent review of the fix then caught the same cross-version boundary hiding in the no-proxy remote-image path — the IP-pinned download `Agent` was still handed to the host's fetch — so that path is now same-sourced too, and the Node floor rises to 22.19 (undici 8's own engine requirement, which externalizing made load-bearing). Thanks to @JooJeen for a diagnosis that had already isolated both layers.

package/dist/main.js

@@ -3737,7 +3737,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.13.0");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.14.0");
 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"}}'`
@@ -3904,4 +3904,4 @@ config.command("show").description("Print the effective config (file merged with
     process.exitCode = 1;
   }
 });
-await program.parseAsync();
+await program.parseAsync(process.argv, { from: "node" });

package/docs/harness-setup.md

@@ -57,3 +57,21 @@ 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.
+
+### Paste-to-path (web profile)
+
+Pasting an image into the dsh Web UI under a **text-only model** used to die at
+image admission. The plugin now ships a browser half (loaded automatically by
+dsh's client plugin system) that takes over the paste in exactly that case:
+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
+carries no image attachment.
+
+The takeover is conditional: when the selected model is a `(modlens vision)`
+variant or a known vision model, the native paste flow is left alone (variants
+convert at request time with the thumbnail preserved; vision models read
+images themselves). `pasteToPath: false` in the plugin row turns the whole
+feature off.

package/dsh/client.js

@@ -0,0 +1,126 @@
+// Browser half of the modlens dsh plugin: paste-to-path.
+//
+// A capture-phase paste listener runs before the composer's own handler.
+// When the clipboard carries image files, the default intake (attachment ->
+// host image admission -> "model does not support images" for text-only
+// models) is suppressed; the bytes go to the plugin's host route
+// (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.
+//
+// Hand-written in the lazy-CJS bundle protocol (window.__ModuleLoader__.load
+// with a factory returning cordis-plugin exports), so no build step and no
+// imports from dsh client packages — the same zero-dependency stance as the
+// host half.
+window.__ModuleLoader__.load({
+  id: '@liustack/modlens',
+  factory: () => {
+    var module = { exports: {} }
+    var exports = module.exports
+
+    function imageFilesOf(event) {
+      var items = event.clipboardData && event.clipboardData.items
+      if (!items) return []
+      var files = []
+      for (var i = 0; i < items.length; i++) {
+        var item = items[i]
+        if (item.kind !== 'file') continue
+        var file = item.getAsFile()
+        if (file && /^image\//.test(file.type)) files.push(file)
+      }
+      return files
+    }
+
+    function insertText(target, text) {
+      var el =
+        target && (target.tagName === 'TEXTAREA' || target.tagName === 'INPUT')
+          ? target
+          : document.activeElement
+      if (!el || (el.tagName !== 'TEXTAREA' && el.tagName !== 'INPUT')) return
+      el.focus()
+      // execCommand fires the input event React's controlled textarea needs;
+      // the prototype-setter dance is the fallback for engines dropping it.
+      var inserted = false
+      try {
+        inserted = document.execCommand('insertText', false, text)
+      } catch {
+        inserted = false
+      }
+      if (!inserted) {
+        var proto =
+          el.tagName === 'TEXTAREA' ? window.HTMLTextAreaElement.prototype : window.HTMLInputElement.prototype
+        var setter = Object.getOwnPropertyDescriptor(proto, 'value').set
+        setter.call(el, el.value + text)
+        el.dispatchEvent(new Event('input', { bubbles: true }))
+      }
+    }
+
+    function uploadOne(file) {
+      return file.arrayBuffer().then((buffer) =>
+        fetch('/modlens/paste', { method: 'POST', body: buffer }).then((res) => {
+          if (!res.ok) {
+            return res
+              .json()
+              .catch(() => ({}))
+              .then((body) => {
+                throw new Error(body.error || `paste upload failed (${res.status})`)
+              })
+          }
+          return res.json()
+        }),
+      )
+    }
+
+    // The takeover is for text-only models: the (modlens vision) variants
+    // convert pastes at request time with the thumbnail preserved, and real
+    // vision models read images natively — both keep the original paste UX.
+    // The model selector button's accessible label is the only client-side
+    // source of the current model; when it cannot be found, taking over is
+    // the safe default (text-only is the common case this exists for).
+    var VISION_HINT = /\(modlens vision\)|deepseek-(vl|ocr)|janus|glm-[\d.]*v\b|vision|image/i
+
+    function currentModelLabel() {
+      var buttons = document.querySelectorAll('button[aria-label]')
+      for (var i = 0; i < buttons.length; i++) {
+        var label = buttons[i].getAttribute('aria-label') || ''
+        if (/选择模型|select model|current model/i.test(label)) return label
+      }
+      return ''
+    }
+
+    function onPaste(event) {
+      var files = imageFilesOf(event)
+      if (files.length === 0) return
+      if (VISION_HINT.test(currentModelLabel())) return
+      // Take the paste before the composer's intake starts an attachment (and
+      // with it the host-side image admission a text-only model fails).
+      event.preventDefault()
+      event.stopImmediatePropagation()
+      var target = event.target
+      Promise.all(files.map(uploadOne))
+        .then((results) => {
+          var text = results
+            .map((r) => r.path)
+            .filter(Boolean)
+            .join(' ')
+          if (text) insertText(target, `${text} `)
+        })
+        .catch((error) => {
+          console.error(`[modlens] paste-to-path failed: ${error && error.message ? error.message : error}`)
+        })
+    }
+
+    function apply(ctx) {
+      document.addEventListener('paste', onPaste, true)
+      // cordis effect: unregister on plugin disposal (HMR, profile reload).
+      if (typeof ctx.effect === 'function') {
+        ctx.effect(() => () => document.removeEventListener('paste', onPaste, true), 'modlens: paste-to-path listener')
+      }
+    }
+
+    exports.apply = apply
+    exports.inject = []
+    return module.exports
+  },
+})

package/dsh/index.js

@@ -43,6 +43,24 @@ export function apply(ctx, config = {}) {
   if (config.visionProvider !== false) {
     registerVisionProvider(ctx, config)
   }
+  // Paste-to-path: the browser half (dsh/client.js) intercepts image pastes
+  // and POSTs the bytes here; the file lands in a private temp dir and the
+  // path text goes into the composer instead of an image attachment. A
+  // text-only model then never trips image admission, and the path is the
+  // same trigger shape Pi, OpenCode, and Claude Code hand their models.
+  // webServer exists only under the web profile, and this cordis has no
+  // optional-inject form, so the route rides a scoped ctx.inject: the closure
+  // runs when the service appears and never runs where it does not (headless
+  // stays untouched, and the plugin itself never waits on it).
+  if (config.pasteToPath !== false && typeof ctx.inject === 'function') {
+    ctx.inject(['webServer'], (scope) => {
+      try {
+        registerPasteRoute(scope)
+      } catch (error) {
+        console.error(`[modlens] paste-to-path route skipped: ${error}`)
+      }
+    })
+  }
   // Registered as a raw JSON-Schema tool definition (no dsh package imports:
   // 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
@@ -134,6 +152,68 @@ export function apply(ctx, config = {}) {
   }
 }
 
+// Image magic bytes for the paste route: refuse anything that is not a real
+// image before a byte touches disk. Mirrors the CLI's sniffing table.
+const PASTE_SNIFFS = [
+  { ext: '.png', test: (b) => b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 },
+  { ext: '.jpg', test: (b) => b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
+  { ext: '.gif', test: (b) => b.length >= 6 && b.toString('ascii', 0, 3) === 'GIF' },
+  { ext: '.webp', test: (b) => b.length >= 12 && b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP' },
+  { ext: '.heic', test: (b) => b.length >= 12 && b.toString('ascii', 4, 8) === 'ftyp' },
+]
+const PASTE_MAX_BYTES = 25 * 1024 * 1024
+
+/**
+ * POST /modlens/paste: image bytes in, `{ path }` out. Bound to the dsh web
+ * server, which listens on loopback by default; the file is private (0600)
+ * in a fresh unpredictable temp dir, magic-byte checked and size-capped.
+ */
+function registerPasteRoute(ctx) {
+  ctx.webServer.register({
+    name: 'modlens-paste',
+    kind: 'exact',
+    path: '/modlens/paste',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') {
+        res.writeHead(405).end()
+        return
+      }
+      try {
+        const chunks = []
+        let total = 0
+        for await (const chunk of req) {
+          total += chunk.length
+          if (total > PASTE_MAX_BYTES) {
+            res.writeHead(413, { 'content-type': 'application/json' })
+            res.end(JSON.stringify({ error: `image over the ${PASTE_MAX_BYTES}-byte limit` }))
+            req.destroy()
+            return
+          }
+          chunks.push(chunk)
+        }
+        const buffer = Buffer.concat(chunks)
+        const sniff = PASTE_SNIFFS.find((s) => s.test(buffer))
+        if (!sniff) {
+          res.writeHead(400, { 'content-type': 'application/json' })
+          res.end(JSON.stringify({ error: 'not a recognized image (png/jpeg/gif/webp/heic)' }))
+          return
+        }
+        const { mkdtemp, writeFile } = await import('node:fs/promises')
+        const { tmpdir } = await import('node:os')
+        const { join } = await import('node:path')
+        const dir = await mkdtemp(join(tmpdir(), 'modlens-dsh-paste-'))
+        const file = join(dir, `paste${sniff.ext}`)
+        await writeFile(file, buffer, { mode: 0o600 })
+        res.writeHead(200, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ path: file }))
+      } catch (error) {
+        res.writeHead(500, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ error: String(error && error.message ? error.message : error) }))
+      }
+    },
+  })
+}
+
 /**
  * Phase 3: the paste unlock. dsh's image admission asks the selected
  * provider's adapter for inputModalities, and the DeepSeek adapter hardcodes
@@ -444,7 +524,13 @@ async function readImageBlock(ctx, block, signal) {
 
 function run(command, args, signal) {
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], signal })
+    const child = spawn(command, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      signal,
+      // In the packaged desktop app process.execPath is the Electron binary;
+      // this makes it behave as plain node for the spawned CLI (issue #25).
+      env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+    })
     let stdout = ''
     let stderr = ''
     child.stdout.on('data', (chunk) => {

package/package.json

@@ -1,80 +1,86 @@
 {
-  "name": "@liustack/modlens",
-  "version": "3.13.0",
-  "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
-  "type": "module",
-  "bin": {
-    "modlens": "./dist/main.js"
-  },
-  "scripts": {
-    "dev": "vite build --watch",
-    "build": "vite build",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "coverage": "vitest run --coverage",
-    "lint": "biome check src scripts dsh",
-    "format": "biome check --write src scripts",
-    "eval": "node evals/run.mjs",
-    "release": "node scripts/release.mjs",
-    "prepublishOnly": "pnpm build",
-    "docs:list": "node scripts/docs-list.js"
-  },
-  "files": [
-    "dist",
-    "docs",
-    "skills/modlens/SKILL.md",
-    "skills/modlens/scripts",
-    "skills/modlens/references",
-    "CHANGELOG.md",
-    "SECURITY.md",
-    "dsh",
-    "cordis.patch.yml"
-  ],
-  "keywords": [
-    "cli",
-    "vision",
-    "ocr",
-    "antigravity",
-    "agent-skill",
-    "claude-code",
-    "skill",
-    "image-to-text",
-    "multimodal",
-    "modlens"
-  ],
-  "author": "Leon Liu",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/liustack/modlens.git"
-  },
-  "bugs": {
-    "url": "https://github.com/liustack/modlens/issues"
-  },
-  "homepage": "https://github.com/liustack/modlens#readme",
-  "engines": {
-    "node": ">=22.19"
-  },
-  "dependencies": {
-    "commander": "^13.1.0",
-    "undici": "^8.10.0"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.7",
-    "@types/node": "^22.19.7",
-    "@vitest/coverage-v8": "^3.2.7",
-    "typescript": "^5.9.3",
-    "vite": "^6.4.1",
-    "vitest": "^3.2.7"
-  },
-  "exports": {
-    ".": "./dsh/index.js",
-    "./dsh": "./dsh/index.js",
-    "./package.json": "./package.json"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
+    "name": "@liustack/modlens",
+    "version": "3.14.0",
+    "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
+    "type": "module",
+    "bin": {
+        "modlens": "./dist/main.js"
+    },
+    "scripts": {
+        "dev": "vite build --watch",
+        "build": "vite build",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest run",
+        "coverage": "vitest run --coverage",
+        "lint": "biome check src scripts dsh",
+        "format": "biome check --write src scripts",
+        "eval": "node evals/run.mjs",
+        "release": "node scripts/release.mjs",
+        "prepublishOnly": "pnpm build",
+        "docs:list": "node scripts/docs-list.js"
+    },
+    "files": [
+        "dist",
+        "docs",
+        "skills/modlens/SKILL.md",
+        "skills/modlens/scripts",
+        "skills/modlens/references",
+        "CHANGELOG.md",
+        "SECURITY.md",
+        "dsh",
+        "cordis.patch.yml"
+    ],
+    "keywords": [
+        "cli",
+        "vision",
+        "ocr",
+        "antigravity",
+        "agent-skill",
+        "claude-code",
+        "skill",
+        "image-to-text",
+        "multimodal",
+        "modlens"
+    ],
+    "author": "Leon Liu",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/liustack/modlens.git"
+    },
+    "bugs": {
+        "url": "https://github.com/liustack/modlens/issues"
+    },
+    "homepage": "https://github.com/liustack/modlens#readme",
+    "engines": {
+        "node": ">=22.19"
+    },
+    "dependencies": {
+        "commander": "^13.1.0",
+        "undici": "^8.10.0"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.5.7",
+        "@types/node": "^22.19.7",
+        "@vitest/coverage-v8": "^3.2.7",
+        "typescript": "^5.9.3",
+        "vite": "^6.4.1",
+        "vitest": "^3.2.7"
+    },
+    "exports": {
+        ".": "./dsh/index.js",
+        "./dsh": "./dsh/index.js",
+        "./package.json": "./package.json",
+        "./client": "./dsh/client.js"
+    },
+    "dsh": {
+        "bundle": {
+            "patch": "./cordis.patch.yml"
+        },
+        "client": {
+            "inject": [],
+            "platform": "web",
+            "immediately": true
+        }
     }
-  }
 }

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.13.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.14.0):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.13.0: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.13.0 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.13.0 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.14.0: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.14.0 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.14.0 <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.13.0
+- Pinned CLI version: 3.14.0
 - 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.13.0'
+$Pinned = '3.14.0'
 # -------------------------------------------------------------------------------
 
 $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.13.0"
+PINNED="3.14.0"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"