@liustack/modlens 2.3.2 → 2.4.1

package/README.md

@@ -149,7 +149,7 @@ 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. Transcripts are per-session files; recovery picks the one holding the newest pasted image by message timestamp, so concurrent sessions in the same project do not confuse it. One honest caveat: the transcript layout is Claude Code internals 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. 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. One honest caveat: the transcript layout is Claude Code internals with no compatibility promise; if recovery ever breaks, dragging the file still works everywhere.
 
 ## Why a bridge instead of a multimodal model?
 

package/README.zh-CN.md

@@ -149,7 +149,7 @@ 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 看到占位符会自动跑这一步。会话记录本来就是一个会话一个文件，recover-paste 按消息时间戳挑「持有最新粘贴图」的那份，同项目并发开多个会话也不会拿错。一句老实话：会话记录格式是 Claude Code 的内部实现，没有兼容承诺，哪天捞不动了，拖文件永远是保底。
+粘贴要多说两句。走 `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 看到占位符会自动跑这一步。会话记录本来就是一个会话一个文件。skill 可以通过 `--session` 传入精确会话（Claude Code 从 v2.1.9 起会把 `${CLAUDE_SESSION_ID}` 替换进 skill 文本），不传时按消息时间戳挑「持有最新粘贴图」的那份，两条路都不怕同项目并发多开。一句老实话：会话记录格式是 Claude Code 的内部实现，没有兼容承诺，哪天捞不动了，拖文件永远是保底。
 
 ## 为什么外挂，而不是换多模态模型？
 

package/dist/main.js

@@ -943,8 +943,24 @@ function extractUserImages(transcriptPath) {
   }
   return images;
 }
+function transcriptForSession(cwd, sessionId) {
+  const file = path.join(
+    os.homedir(),
+    ".claude",
+    "projects",
+    projectSlug(cwd),
+    `${sessionId}.jsonl`
+  );
+  if (!fs.existsSync(file)) {
+    throw new Error(
+      `No transcript for session ${sessionId} under this project (${file}). Check --cwd, or drop --session to auto-locate by newest pasted image.`
+    );
+  }
+  return file;
+}
 function recoverPastedImages(options = {}) {
-  const transcript = options.transcript ?? locateTranscript(options.cwd ?? process.cwd());
+  const cwd = options.cwd ?? process.cwd();
+  const transcript = options.transcript ?? (options.session ? transcriptForSession(cwd, options.session) : locateTranscript(cwd));
   const count = Math.max(1, options.count ?? 1);
   const outDir = options.outDir ?? path.join(os.tmpdir(), "modlens-paste");
   const all = extractUserImages(transcript);
@@ -966,7 +982,7 @@ function recoverPastedImages(options = {}) {
   return { transcript, images };
 }
 const program = new Command();
-program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.3.2");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.4.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);
@@ -1000,7 +1016,10 @@ 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)"
-).option("--count <n>", "How many recent pasted images to recover", "1").option("--out-dir <path>", "Directory to write recovered images to").option("--transcript <path>", "Explicit transcript .jsonl (default: newest for cwd)").option("--cwd <path>", "Project directory the image was pasted in", process.cwd()).action(async (options) => {
+).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) => {
   try {
     const count = Number.parseInt(options.count, 10);
     if (!Number.isFinite(count) || count <= 0) {
@@ -1010,6 +1029,7 @@ program.command("recover-paste").description(
       count,
       outDir: options.outDir,
       transcript: options.transcript,
+      session: options.session,
       cwd: options.cwd
     });
     process.stdout.write(`${JSON.stringify(result, null, 2)}

package/package.json

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

package/skills/modlens/SKILL.md

@@ -61,14 +61,19 @@ Speed expectations: `gemini-api` typically 5-10 seconds, `antigravity-cli` 15-40
 
 ## Finding the image path in the chat
 
-Harnesses rarely hand you a clean path. Look for these signals:
-
-- Codex wraps every pasted or attached image in a text tag like
-  `<image name=[Image #1] path="/tmp/xxxx.png">`. Extract the `path` value and run modlens on it. Pasted images live in a temp file the harness already created.
-- A placeholder like `image content omitted because you do not support image input` means the harness stripped an image for you. The path tag next to it still holds the real file. Use it.
-- Claude Code never writes pasted images to a regular temp file. Behind a text-only gateway you will only see a placeholder like `[Unsupported Image]` or `[Image #1]`, with no path. When that happens, run `modlens recover-paste` (add `--count <n>` for several images): it recovers the pasted image bytes from the local session transcripts and prints real file paths as JSON. Feed that path to `modlens -i`.
-  You do not need to know which session you are; you cannot know it (no env var carries a session id) and the command does not take one. It scans every transcript of the current project directory and picks the session holding the newest pasted-image message by timestamp, which is necessarily the one the user just pasted into, even with concurrent sessions. Run it from the project directory the conversation is happening in. If recovery fails (transcript format is Claude Code internals and may change), fall back to asking the user to drag the image file into the terminal or type its path.
-- If the user mentions an image but no tag or path appears anywhere in the message, ask for the file path instead of guessing.
+Harnesses rarely hand you a clean path. First identify which harness you are in, then use its route. Never mix routes across harnesses.
+
+**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.
+
+**Claude Code** (no path tag anywhere; the placeholder looks like `[Unsupported Image]` or a bare `[Image #1]`, and `${CLAUDE_SESSION_ID}` below reads as a UUID):
+
+- Claude Code never writes pasted images to a regular temp file, but it logs them into its local session transcript. Run `modlens recover-paste` (add `--count <n>` for several images): it recovers the pasted image bytes and prints real file paths as JSON. Feed that path to `modlens -i`.
+- Session targeting: your session id is ${CLAUDE_SESSION_ID}. If that value reads as a UUID, pass it as `--session <uuid>` for exact targeting. If it reads as a literal placeholder, omit `--session`: the command auto-locates by scanning this project's transcripts 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.
+- If recovery fails (transcript format is Claude Code 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, `${CLAUDE_SESSION_ID}` still a literal placeholder, no Claude Code transcripts): do not guess and do not run `recover-paste`. Ask the user for the image file path, or suggest dragging the file into the terminal.
 
 ## Workflow