@liustack/modlens 3.13.0 → 3.15.0

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,21 +152,93 @@ 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
  * text-only, so pastes are refused before any plugin hook runs. This wrapper
  * registers a NEW provider whose model metadata declares image input and
  * whose stream() is a one-line delegation back to the real route. Pick the
- * wrapped model in the model selector, paste, and the pre-step rewrite below
+ * wrapped model in the model selector, paste, and the request-time rewrite
  * 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.
+ *
+ * Two modes (issue #29, design contributed by @zlycode01):
+ * - `config.upstream` set: wrap exactly that one route, legacy behavior.
+ * - unset: auto-discovery — every registered provider route carrying
+ *   wrappable text-only family models gets its own `modlens-<provider>`
+ *   wrapper, so a machine with several subscription packages (opencode-go,
+ *   zai, ...) wraps them all instead of hand-picking one. A `discover` array
+ *   of provider ids narrows the set. Routes that register late (llm-pi-ai
+ *   mounts its routes after settings load) are picked up by re-sweeping on
+ *   the registry's own `llm/adapters-updated` notification, no polling. The
+ *   deepseek-official wrap keeps its historical `deepseek-modlens` id, so a
+ *   selector remembering that provider survives the upgrade.
  */
 function registerVisionProvider(ctx, config) {
-  const upstream = config.upstream || 'deepseek-official'
-  const providerId = config.providerId || 'deepseek-modlens'
   // Wrap only the text-only members of these families. Their own vision
   // models (present or future: deepseek-vl/ocr/janus, glm-4.5v, glm-5v-...)
   // need no bridge and are excluded by name and by declared modality.
@@ -164,58 +254,148 @@ function registerVisionProvider(ctx, config) {
   if (typeof ctx.llm?.registerAdapter !== 'function' || typeof ctx.llm?.stream !== 'function') {
     return
   }
-  const withVision = (info) => ({
-    ...info,
-    provider: providerId,
-    inputModalities: ['text', 'image'],
-  })
-  try {
-    ctx.llm.registerAdapter([providerId], {
-      // Duck-typing LlmAdapter: providerInfo/providerRetryPolicy are base-class
-      // defaults a plain object must supply itself (their absence is exactly
-      // the silent registration failure this catch used to swallow).
-      providerInfo(provider) {
-        return { id: provider, name: 'DeepSeek (modlens vision)' }
-      },
-      providerRetryPolicy() {
-        return undefined
-      },
-      async listModels(_provider, signal) {
-        try {
-          const models = await ctx.llm.listModels(upstream, signal)
-          return models.filter(shouldWrap).map((model) => ({
-            ...withVision(model),
-            name: `${model.name ?? model.id} (modlens vision)`,
-          }))
-        } catch {
-          return []
-        }
-      },
-      async resolveModel(_provider, model, signal) {
-        const info = await ctx.llm.resolveModelInfo(upstream, model, signal)
-        if (!shouldWrap(info)) {
-          throw new Error(`model "${model}" is outside the modlens vision wrap scope`)
-        }
-        return { ...withVision(info), id: model }
-      },
-      stream(options) {
-        // Convert at request time, not at log time: the durable session log
-        // keeps the real image blocks (so the UI shows the paste natively),
-        // and only the wire messages carry evidence text. Cached per
-        // attachment, since the same history rides every later step.
-        const self = this
-        return (async function* () {
-          const messages = await convertImagesToEvidence(ctx, options.messages, options.signal, self)
-          yield* ctx.llm.stream({ ...options, provider: upstream, messages })
-        })()
-      },
-      evidenceCache: new Map(),
+
+  const registerWrapper = (upstream, providerId, displayName) => {
+    const withVision = (info) => ({
+      ...info,
+      provider: providerId,
+      inputModalities: ['text', 'image'],
+    })
+    try {
+      ctx.llm.registerAdapter([providerId], {
+        // Duck-typing LlmAdapter: providerInfo/providerRetryPolicy are
+        // base-class defaults a plain object must supply itself (their
+        // absence is exactly the silent registration failure this catch
+        // used to swallow).
+        providerInfo(provider) {
+          return { id: provider, name: displayName }
+        },
+        providerRetryPolicy() {
+          return undefined
+        },
+        async listModels(_provider, signal) {
+          try {
+            const models = await ctx.llm.listModels(upstream, signal)
+            return models.filter(shouldWrap).map((model) => ({
+              ...withVision(model),
+              name: `${model.name ?? model.id} (modlens vision)`,
+            }))
+          } catch {
+            return []
+          }
+        },
+        async resolveModel(_provider, model, signal) {
+          const info = await ctx.llm.resolveModelInfo(upstream, model, signal)
+          if (!shouldWrap(info)) {
+            throw new Error(`model "${model}" is outside the modlens vision wrap scope`)
+          }
+          return { ...withVision(info), id: model }
+        },
+        stream(options) {
+          // Convert at request time, not at log time: the durable session
+          // log keeps the real image blocks (so the UI shows the paste
+          // natively), and only the wire messages carry evidence text.
+          // Cached per attachment, since the same history rides every step.
+          const self = this
+          return (async function* () {
+            const messages = await convertImagesToEvidence(ctx, options.messages, options.signal, self)
+            yield* ctx.llm.stream({ ...options, provider: upstream, messages })
+          })()
+        },
+        evidenceCache: new Map(),
+      })
+      return true
+    } catch (error) {
+      // A duplicate means a concurrent or earlier registration already won:
+      // that is success for the claim, not a reason to retry forever.
+      if (/already|duplicate/i.test(String(error))) {
+        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,
+      // 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}`)
+      return false
+    }
+  }
+
+  if (config.upstream) {
+    registerWrapper(
+      config.upstream,
+      config.providerId || 'deepseek-modlens',
+      'DeepSeek (modlens vision)',
+    )
+    return
+  }
+
+  // Auto-discovery. `wrapped` guards duplicates across sweeps and the
+  // self-nesting case (our own wrappers appear in listProviders too). Two
+  // re-entrancy rules matter because registerAdapter itself broadcasts
+  // llm/adapters-updated, so every successful wrap re-triggers a sweep:
+  // an id is claimed in `wrapped` BEFORE any await (a concurrent sweep must
+  // skip it while this one is still probing), and sweeps are serialized on
+  // one promise chain so two can never interleave their probes at all.
+  const discover = Array.isArray(config.discover) ? new Set(config.discover) : null
+  const wrapped = new Set(['deepseek-modlens'])
+  const sweepOnce = async () => {
+    try {
+      await sweepBody()
+    } catch (error) {
+      // A sweep failure must never become an unhandled rejection inside the
+      // host process; the next topology notification simply tries again.
+      console.error(`[modlens] vision provider discovery sweep failed: ${error}`)
+    }
+  }
+  const sweepBody = async () => {
+    if (typeof ctx.llm.listProviders !== 'function') {
+      // Older registry surface: fall back to the single legacy wrap once.
+      if (!wrapped.has('__legacy_fallback__')) {
+        wrapped.add('__legacy_fallback__')
+        registerWrapper('deepseek-official', 'deepseek-modlens', 'DeepSeek (modlens vision)')
+      }
+      return
+    }
+    for (const info of ctx.llm.listProviders()) {
+      const id = info?.id
+      if (!id || wrapped.has(id) || String(id).startsWith('modlens-')) continue
+      if (discover && !discover.has(id)) continue
+      // Claim before the await: the probe may suspend, and the sweep a
+      // registration triggers must not probe the same id concurrently.
+      wrapped.add(id)
+      let models = []
+      try {
+        models = await ctx.llm.listModels(id)
+      } catch {
+        // Unreachable route today; release the claim so a later topology
+        // change retries it.
+        wrapped.delete(id)
+        continue
+      }
+      if (!models.some(shouldWrap)) {
+        // No eligible models yet: release, the route may gain some later.
+        wrapped.delete(id)
+        continue
+      }
+      const providerId = id === 'deepseek-official' ? 'deepseek-modlens' : `modlens-${id}`
+      const base = info.name ?? id
+      if (!registerWrapper(id, providerId, `${base} (modlens vision)`)) {
+        wrapped.delete(id)
+      }
+    }
+  }
+  // Serialize: a sweep triggered mid-sweep runs after, never interleaved.
+  // The first sweep is invoked directly so its synchronous prefix (the
+  // legacy fallback, the pre-await claims) completes during apply().
+  let sweeping = sweepOnce()
+  const sweep = () => {
+    sweeping = sweeping.then(sweepOnce, sweepOnce)
+    return sweeping
+  }
+  if (typeof ctx.on === 'function') {
+    ctx.on('llm/adapters-updated', () => {
+      void sweep()
     })
-  } catch (error) {
-    // DUPLICATE_ADAPTER or a preview-era surface change: degrade to the
-    // read_image-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: ${error}`)
   }
 }
 
@@ -444,7 +624,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.15.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.15.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.15.0: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.15.0 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.15.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/configure.md

@@ -1,5 +1,7 @@
 # Configuring ModLens
 
+English | [中文](configure.zh-CN.md)
+
 Read this when the user asks how to set up, configure, or switch ModLens providers. Prefer running the commands for the user over explaining them.
 
 ## Where config lives