@liustack/modlens 2.6.1 → 2.7.1

package/README.md

@@ -44,6 +44,8 @@ or do it yourself:
 npx -y skills add liustack/modlens
 ```
 
+Harnesses look for skills in different places: Claude Code reads `~/.claude/skills/`, Codex reads `~/.codex/skills/`, Pi and OpenCode read `~/.agents/skills/`. Symlinks work in all of them, so linking the skill folder once keeps every agent on the latest version.
+
 **3. Use it.** Paste an image path into the CLI and ask anything. The skill fires on its own.
 
 ## See it work
@@ -158,7 +160,9 @@ One catch: once text-only is declared, the Codex TUI **blocks Ctrl+V image paste
 
 No setup needed: drag the image file into the terminal, or type its path, and the skill takes over.
 
-Paste is trickier. If you run a text-only model behind `ANTHROPIC_BASE_URL`, Claude Code never writes pasted images to a regular temp file and has no modality switch, so a pasted image reaches the model as a pathless `[Unsupported Image]` placeholder (lenient gateways like DeepSeek's Anthropic endpoint) or breaks the request outright ([#62009](https://github.com/anthropics/claude-code/issues/62009)). But the bytes are not gone: Claude Code appends every user message, images included, to the local session transcript before the gateway ever sees it. That is what `modlens recover-paste` exploits: it pulls the most recent pasted images back out of the transcript and prints real file paths, ready for `modlens -i`. The skill runs this automatically when it spots the placeholder. Verified end to end in a real DeepSeek-gateway Claude Code session: paste an image, the model sees only the placeholder, recovers the file by session id, and answers with full image content. Transcripts are per-session files. Skills can pass the exact session via `--session` (Claude Code substitutes `${CLAUDE_SESSION_ID}` into skill text since v2.1.9); without it, recovery picks the transcript holding the newest pasted image by message timestamp, so concurrent sessions in the same project do not confuse it either way. [Pi](https://github.com/earendil-works/pi) stores sessions the same way (`~/.pi/agent/sessions/`, images as base64 in JSONL). [OpenCode](https://github.com/sst/opencode) keeps them in SQLite instead (`~/.local/share/opencode/opencode.db`, images as data URLs; reading it needs Node 22.5+ for node:sqlite). `recover-paste` auto-detects all three harnesses and picks whichever holds this project's newest pasted image, each verified against a real session. One honest caveat: transcript layouts are internal implementation details of those tools with no compatibility promise; if recovery ever breaks, dragging the file still works everywhere.
+Paste is trickier. If you run a text-only model behind `ANTHROPIC_BASE_URL`, Claude Code never writes pasted images to a regular temp file and has no modality switch, so a pasted image reaches the model as a pathless `[Unsupported Image]` placeholder (lenient gateways like DeepSeek's Anthropic endpoint) or breaks the request outright ([#62009](https://github.com/anthropics/claude-code/issues/62009)). But the bytes are not gone: Claude Code appends every user message, images included, to the local session transcript before the gateway ever sees it. That is what `modlens recover-paste` exploits: it pulls the most recent pasted images back out of the transcript and prints real file paths, ready for `modlens -i`. The skill runs this automatically when it spots the placeholder. Verified end to end in a real DeepSeek-gateway Claude Code session: paste an image, the model sees only the placeholder, recovers the file by session id, and answers with full image content. Transcripts are per-session files. Skills can pass the exact session via `--session` (Claude Code substitutes `${CLAUDE_SESSION_ID}` into skill text since v2.1.9); without it, recovery picks the transcript holding the newest pasted image by message timestamp, so concurrent sessions in the same project do not confuse it either way. [Pi](https://github.com/earendil-works/pi) stores sessions the same way (`~/.pi/agent/sessions/`, images as base64 in JSONL). [OpenCode](https://github.com/sst/opencode) keeps them in SQLite instead (`~/.local/share/opencode/opencode.db`, images as data URLs; reading it needs Node 22.5+ for node:sqlite). `recover-paste` first identifies the harness it is running inside, by walking the process ancestry and checking env fingerprints (`CLAUDECODE`, `PI_CODING_AGENT`, `CODEX_THREAD_ID`), and reads only that harness's storage, so one tool's stale sessions can never hijack another tool's paste; in Claude Code it even targets the exact session from the injected session id, and in Codex it refuses outright and points back to the path tag. Only when detection comes up empty does it fall back to racing all three stores by newest image timestamp. Verified live in all four harnesses: Claude Code recovers the paste via its injected session id, OpenCode runs the whole loop on DeepSeek with the skill firing on its own, Pi stays scoped to its own store, and Codex is refused with the path-tag guidance. One honest caveat: transcript layouts are internal implementation details of those tools with no compatibility promise; if recovery ever breaks, dragging the file still works everywhere.
+
+Pointing OpenCode at DeepSeek takes two lines of setup: `opencode auth login`, pick DeepSeek and paste your key (it lands in `~/.local/share/opencode/auth.json`), then set the default model in `~/.config/opencode/opencode.jsonc` to `deepseek/deepseek-v4-flash`. Pi reads its key from `~/.pi/agent/auth.json`.
 
 ## Why a bridge instead of a multimodal model?
 

package/README.zh-CN.md

@@ -44,6 +44,8 @@ agy    # 浏览器完成登录后退出
 npx -y skills add liustack/modlens
 ```
 
+各家 harness 找 skill 的位置不一样：Claude Code 读 `~/.claude/skills/`，Codex 读 `~/.codex/skills/`，Pi 和 OpenCode 读 `~/.agents/skills/`。软链接在哪家都好使，把 skill 目录链一次，各家永远用最新版。
+
 **3. 用起来。** 在 cli 里粘贴个图片路径，随便问，skill 会自动触发。
 
 ## 看看效果
@@ -158,7 +160,9 @@ Codex 只认 Responses API，DeepSeek 官方端点原生支持。先照着[官
 
 不用任何配置：把图片文件拖进终端，或手打路径，skill 直接接手。
 
-粘贴要多说两句。走 `ANTHROPIC_BASE_URL` 网关跑纯文本模型时，Claude Code 粘贴的图片从不写普通临时文件，也没有声明模型无视觉的开关，粘贴的图要么变成一个不带路径的 `[Unsupported Image]` 占位符到达模型（DeepSeek 的 Anthropic 兼容端点这类宽容网关），要么直接把请求搞挂（[#62009](https://github.com/anthropics/claude-code/issues/62009)）。但图片字节没有蒸发：Claude Code 在网关看到消息之前，就把每条用户消息（含图片）原样写进了本地会话记录。`modlens recover-paste` 干的就是这件事：从会话记录里把最近粘贴的图捞回来，落成真实文件路径，直接喂给 `modlens -i`。skill 看到占位符会自动跑这一步。已在真实的 DeepSeek 网关 Claude Code 会话里端到端验证：粘贴一张图，模型只看到占位符，按会话 ID 捞回文件，带着完整图片内容回答。会话记录本来就是一个会话一个文件。skill 可以通过 `--session` 传入精确会话（Claude Code 从 v2.1.9 起会把 `${CLAUDE_SESSION_ID}` 替换进 skill 文本），不传时按消息时间戳挑「持有最新粘贴图」的那份，两条路都不怕同项目并发多开。[Pi](https://github.com/earendil-works/pi) 的会话存储和它同构（`~/.pi/agent/sessions/`，图片以 base64 存 JSONL）。[OpenCode](https://github.com/sst/opencode) 换了个存法，图片以 data URL 塞进 SQLite（`~/.local/share/opencode/opencode.db`，读它需要 Node 22.5+ 的 node:sqlite）。`recover-paste` 会自动探测三家宿主，挑出持有本项目最新粘贴图的那家，都拿真实会话验证过。一句老实话：会话记录格式是这些工具的内部实现，没有兼容承诺，哪天捞不动了，拖文件永远是保底。
+粘贴要多说两句。走 `ANTHROPIC_BASE_URL` 网关跑纯文本模型时，Claude Code 粘贴的图片从不写普通临时文件，也没有声明模型无视觉的开关，粘贴的图要么变成一个不带路径的 `[Unsupported Image]` 占位符到达模型（DeepSeek 的 Anthropic 兼容端点这类宽容网关），要么直接把请求搞挂（[#62009](https://github.com/anthropics/claude-code/issues/62009)）。但图片字节没有蒸发：Claude Code 在网关看到消息之前，就把每条用户消息（含图片）原样写进了本地会话记录。`modlens recover-paste` 干的就是这件事：从会话记录里把最近粘贴的图捞回来，落成真实文件路径，直接喂给 `modlens -i`。skill 看到占位符会自动跑这一步。已在真实的 DeepSeek 网关 Claude Code 会话里端到端验证：粘贴一张图，模型只看到占位符，按会话 ID 捞回文件，带着完整图片内容回答。会话记录本来就是一个会话一个文件。skill 可以通过 `--session` 传入精确会话（Claude Code 从 v2.1.9 起会把 `${CLAUDE_SESSION_ID}` 替换进 skill 文本），不传时按消息时间戳挑「持有最新粘贴图」的那份，两条路都不怕同项目并发多开。[Pi](https://github.com/earendil-works/pi) 的会话存储和它同构（`~/.pi/agent/sessions/`，图片以 base64 存 JSONL）。[OpenCode](https://github.com/sst/opencode) 换了个存法，图片以 data URL 塞进 SQLite（`~/.local/share/opencode/opencode.db`，读它需要 Node 22.5+ 的 node:sqlite）。`recover-paste` 会先搞清楚自己正跑在哪家宿主里（沿进程祖先链往上找，再核对 `CLAUDECODE`、`PI_CODING_AGENT`、`CODEX_THREAD_ID` 这些环境变量指纹），然后只读那一家的存储，别家的陈年会话再也没机会冒充。在 Claude Code 里还会直接用注入的会话 ID 精确定位，在 Codex 里则干脆拒绝执行并把你指回 path tag。实在识别不出来才退回按最新图片时间戳在三家赛跑。四家宿主全部活体验证过：Claude Code 靠注入的会话 ID 精确捞回粘贴，OpenCode 上 DeepSeek 全程自动触发 skill 跑完整条链路，Pi 只认自家存储不受别家污染，Codex 被拒之门外并指回 path tag。一句老实话：会话记录格式是这些工具的内部实现，没有兼容承诺，哪天捞不动了，拖文件永远是保底。
+
+OpenCode 接 DeepSeek 只要两步：`opencode auth login` 选 DeepSeek 贴上 key（落在 `~/.local/share/opencode/auth.json`），再把 `~/.config/opencode/opencode.jsonc` 的默认模型设成 `deepseek/deepseek-v4-flash`。Pi 的 key 放 `~/.pi/agent/auth.json`。
 
 ## 为什么外挂，而不是换多模态模型？
 

package/dist/main.js

@@ -2,6 +2,7 @@
 import { Command } from "commander";
 import * as fs from "fs";
 import * as path from "path";
+import * as childProcess from "child_process";
 import { spawn } from "child_process";
 import * as os from "os";
 import * as crypto from "crypto";
@@ -1064,6 +1065,64 @@ const opencodeAdapter = {
     };
   }
 };
+const HARNESS_BY_BASENAME = {
+  claude: "claude-code",
+  "claude-code": "claude-code",
+  pi: "pi",
+  opencode: "opencode",
+  codex: "codex"
+};
+function harnessFromPsTable(psOutput, startPid) {
+  const table = /* @__PURE__ */ new Map();
+  for (const line of psOutput.split("\n")) {
+    const match = /^\s*(\d+)\s+(\d+)\s+(.+)$/.exec(line);
+    if (match) {
+      table.set(Number(match[1]), { ppid: Number(match[2]), command: match[3] });
+    }
+  }
+  let pid = table.get(startPid)?.ppid;
+  for (let hops = 0; hops < 50 && pid !== void 0 && pid > 1; hops++) {
+    const proc = table.get(pid);
+    if (!proc) {
+      return null;
+    }
+    for (const token of proc.command.trim().split(/\s+/).slice(0, 8)) {
+      const mapped = HARNESS_BY_BASENAME[path.basename(token)];
+      if (mapped) {
+        return mapped;
+      }
+    }
+    pid = proc.ppid;
+  }
+  return null;
+}
+function detectHarness() {
+  const override = process.env.MODLENS_HARNESS;
+  if (override) {
+    return override === "none" ? null : override;
+  }
+  try {
+    const ps = childProcess.execFileSync("ps", ["-Ao", "pid=,ppid=,command="], {
+      encoding: "utf-8",
+      maxBuffer: 16 * 1024 * 1024
+    });
+    const found = harnessFromPsTable(ps, process.pid);
+    if (found) {
+      return found;
+    }
+  } catch {
+  }
+  if (process.env.PI_CODING_AGENT) {
+    return "pi";
+  }
+  if (process.env.CODEX_THREAD_ID || process.env.CODEX_SANDBOX) {
+    return "codex";
+  }
+  if (process.env.CLAUDECODE || process.env.CLAUDE_CODE_SESSION_ID) {
+    return "claude-code";
+  }
+  return null;
+}
 const ADAPTERS = [claudeAdapter, piAdapter, opencodeAdapter];
 function sourceForExplicitPath(filePath) {
   if (filePath.endsWith(".db")) {
@@ -1078,9 +1137,9 @@ function sourceForExplicitPath(filePath) {
   }
   return jsonlSource("claude-code", filePath, claudeExtractLine);
 }
-function locateSource(cwd) {
+function locateSource(cwd, adapters = ADAPTERS) {
   let best = null;
-  for (const adapter of ADAPTERS) {
+  for (const adapter of adapters) {
     let candidate = null;
     try {
       candidate = adapter.findNewest(cwd);
@@ -1091,15 +1150,15 @@ function locateSource(cwd) {
     }
   }
   if (!best) {
-    const dirs = ADAPTERS.map((a) => a.describe(cwd)).join(" , ");
+    const dirs = adapters.map((a) => a.describe(cwd)).join(" , ");
     throw new Error(
       `No pasted images found in any session storage for this directory (looked in: ${dirs}). The user may not have pasted any, or the storage format changed; ask for a file path instead.`
     );
   }
   return best.ref;
 }
-function sourceForSession(cwd, sessionId) {
-  for (const adapter of ADAPTERS) {
+function sourceForSession(cwd, sessionId, adapters = ADAPTERS) {
+  for (const adapter of adapters) {
     try {
       const ref = adapter.findSession(cwd, sessionId);
       if (ref) {
@@ -1108,14 +1167,42 @@ function sourceForSession(cwd, sessionId) {
     } catch {
     }
   }
-  const dirs = ADAPTERS.map((a) => a.describe(cwd)).join(" , ");
+  const dirs = adapters.map((a) => a.describe(cwd)).join(" , ");
   throw new Error(
     `No session ${sessionId} with pasted images under this project (looked in: ${dirs}). Check --cwd, or drop --session to auto-locate by newest pasted image.`
   );
 }
 function recoverPastedImages(options = {}) {
   const cwd = options.cwd ?? process.cwd();
-  const source = options.transcript ? sourceForExplicitPath(options.transcript) : options.session ? sourceForSession(cwd, options.session) : locateSource(cwd);
+  const detected = options.transcript ? null : options.harness ?? detectHarness();
+  if (detected === "codex") {
+    throw new Error(
+      "This is a Codex session: pasted images already exist as temp files, and each image tag in the message carries its path. Read the path from the tag instead of running recover-paste."
+    );
+  }
+  const scoped = detected && detected !== "none" ? detected : null;
+  if (scoped && !ADAPTERS.some((adapter) => adapter.name === scoped)) {
+    throw new Error(
+      `Unknown harness "${scoped}". Supported: claude-code, pi, opencode (or none to scan all).`
+    );
+  }
+  const adapters = scoped ? ADAPTERS.filter((adapter) => adapter.name === scoped) : ADAPTERS;
+  let source = null;
+  if (options.transcript) {
+    source = sourceForExplicitPath(options.transcript);
+  } else if (options.session) {
+    source = sourceForSession(cwd, options.session, adapters);
+  } else {
+    const envSession = detected === "claude-code" ? process.env.CLAUDE_CODE_SESSION_ID : void 0;
+    if (envSession) {
+      try {
+        source = sourceForSession(cwd, envSession, adapters);
+      } catch {
+        source = null;
+      }
+    }
+    source ??= locateSource(cwd, adapters);
+  }
   const count = Math.max(1, options.count ?? 1);
   const outDir = options.outDir ?? path.join(os.tmpdir(), "modlens-paste");
   const all = source.extract();
@@ -1142,10 +1229,14 @@ function recoverPastedImages(options = {}) {
     }
     return recovered;
   });
-  return { harness: source.harness, transcript: source.location, images };
+  const result = { harness: source.harness, transcript: source.location, images };
+  if (scoped) {
+    result.detected = scoped;
+  }
+  return result;
 }
 const program = new Command();
-program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.6.1");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.7.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").action(async (options) => {
   try {
     const timeoutMs = Number.parseInt(options.timeout, 10);
@@ -1178,11 +1269,14 @@ program.command("analyze", { isDefault: true }).description("Analyze an image in
   }
 });
 program.command("recover-paste").description(
-  "Recover images pasted into Claude Code from the session transcript (they never hit disk otherwise)"
+  "Recover images pasted into Claude Code, Pi, or OpenCode from local session storage (they never hit disk otherwise)"
 ).option("--count <n>", "How many recent pasted images to recover", "1").option("--out-dir <path>", "Directory to write recovered images to").option(
   "--session <id>",
   "Claude Code session id for exact targeting (skills get it via ${CLAUDE_SESSION_ID})"
-).option("--transcript <path>", "Explicit transcript .jsonl (overrides --session)").option("--cwd <path>", "Project directory the image was pasted in", process.cwd()).action(async (options) => {
+).option("--transcript <path>", "Explicit transcript .jsonl or .db (overrides --session)").option(
+  "--harness <name>",
+  "Force the storage scope: claude-code, pi, opencode, or none (default: auto-detect via process ancestry and env)"
+).option("--cwd <path>", "Project directory the image was pasted in", process.cwd()).action(async (options) => {
   try {
     const count = Number.parseInt(options.count, 10);
     if (!Number.isFinite(count) || count <= 0) {
@@ -1193,7 +1287,8 @@ program.command("recover-paste").description(
       outDir: options.outDir,
       transcript: options.transcript,
       session: options.session,
-      cwd: options.cwd
+      cwd: options.cwd,
+      harness: options.harness
     });
     process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);

package/package.json

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

package/skills/modlens/SKILL.md

@@ -65,14 +65,14 @@ Harnesses rarely hand you a clean path. First identify which harness you are in,
 
 **Codex** (you see a text tag like `<image name=[Image #1] path="/tmp/xxxx.png">`):
 
-- Extract the `path` value from the tag and run modlens on it. Pasted images live in a temp file Codex already created; a stripped image keeps its path tag next to the placeholder. Do NOT use `recover-paste` here: it reads Claude Code session files, which do not exist for Codex.
+- Extract the `path` value from the tag and run modlens on it. Pasted images live in a temp file Codex already created; a stripped image keeps its path tag next to the placeholder. Do NOT use `recover-paste` here: it detects Codex and refuses with this same guidance.
 
 **Claude Code, Pi, or OpenCode** (no path tag anywhere; the image reads as `[Unsupported Image]`, a bare `[Image #1]`, or an attachment you simply cannot see):
 
-- None of these harnesses writes pasted images to a regular temp file, but all of them persist user messages locally before any gateway strips them: Claude Code and Pi in session JSONL files (`~/.claude/projects/`, `~/.pi/agent/sessions/`), OpenCode in a SQLite database (`~/.local/share/opencode/opencode.db`, read via node:sqlite, needs Node 22.5+). `recover-paste` scans all three and auto-detects which harness owns the newest pasted image for this project. Run `modlens recover-paste` (add `--count <n>` for several images): it recovers the pasted image bytes and prints real file paths as JSON, ordered oldest to newest, so the LAST path is the user's most recent paste. Analyze that one first. Entries carry `filename` (the original attachment name) when the harness stored one; if the user's message or an error mentions a filename, match on it.
+- None of these harnesses writes pasted images to a regular temp file, but all of them persist user messages locally before any gateway strips them: Claude Code and Pi in session JSONL files (`~/.claude/projects/`, `~/.pi/agent/sessions/`), OpenCode in a SQLite database (`~/.local/share/opencode/opencode.db`, read via node:sqlite, needs Node 22.5+). Run `modlens recover-paste` from the project directory the conversation is happening in (add `--count <n>` for several images). It detects which harness it is running inside (process ancestry, then env fingerprints) and reads ONLY that harness's storage, so another tool's old sessions cannot leak in. In Claude Code it also targets your exact session automatically via the injected CLAUDE_CODE_SESSION_ID; `--session <id>` (e.g. from the ${CLAUDE_SESSION_ID} substitution) is only needed to override.
+- The output is JSON with real file paths, ordered oldest to newest, so the LAST path is the user's most recent paste. Analyze that one first. Entries carry `filename` (the original attachment name) when the harness stored one; if the user's message or an error mentions a filename, match on it.
 - Run every command yourself: `recover-paste`, then `modlens -i <path>` on the recovered file, then answer from the JSON. Never ask the user to run modlens or to relay paths.
-- Sanity-check the `harness` field in the output against the harness you are actually running in. If they differ (say it reports `claude-code` while you are in OpenCode), the images are probably stale pastes from another tool's sessions in the same project: check `filename` against what the user sent, and when in doubt ask for the file instead of describing the wrong image.
-- Session targeting: your session id is ${CLAUDE_SESSION_ID}. If that value reads as a UUID, pass it as `--session <uuid>` for exact targeting (on OpenCode, the session id or slug works too). If it reads as a literal placeholder, omit `--session`: the command auto-locates by scanning this project's sessions for the newest pasted-image message, which is the session the user just pasted into, even with concurrent sessions. Run it from the project directory the conversation is happening in.
+- The output's `detected` field names the harness scope that was applied. If it is absent, detection failed and every store was scanned by newest-image timestamp: before describing anything, check that `harness` and `filename` match what you expect, force the scope with `--harness <claude-code|pi|opencode>` if they do not, and when in doubt ask the user for the file instead of describing the wrong image.
 - If recovery fails (session storage is each harness's internals and may change), ask the user to drag the image file into the terminal or type its path.
 
 **Any other harness, or nothing matches** (no path tag and `recover-paste` reports no transcripts): do not guess. Ask the user for the image file path, or suggest dragging the file into the terminal.