@liustack/modlens 2.4.2 → 2.5.0

package/README.md

@@ -154,11 +154,11 @@ One catch: once text-only is declared, the Codex TUI **blocks Ctrl+V image paste
 - **Drag the image file into the terminal**, or type its path. The path lands as plain text, and the modlens skill picks it up from there.
 - Attach it with `codex exec -i image.png "..."`. The skill reads the path out of the message tag.
 
-## Using it in Claude Code (gateway models)
+## Using it in Claude Code and Pi (gateway models)
 
 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. 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.
+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), and `recover-paste` auto-detects both harnesses, verified live against a real pi 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.
 
 ## Why a bridge instead of a multimodal model?
 

package/README.zh-CN.md

@@ -154,11 +154,11 @@ Codex 只认 Responses API，DeepSeek 官方端点原生支持。先照着[官
 - **把图片文件拖进终端**，或者手打路径。路径以纯文本形式落进消息，modlens skill 接着从这里接手。
 - 用 `codex exec -i 图片.png "..."` skill 从这里把路径抠出来。
 
-## 在 Claude Code 里用（网关接第三方模型）
+## 在 Claude Code 和 Pi 里用（网关接第三方模型）
 
 不用任何配置：把图片文件拖进终端，或手打路径，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 看到占位符会自动跑这一步。会话记录本来就是一个会话一个文件。skill 可以通过 `--session` 传入精确会话（Claude Code 从 v2.1.9 起会把 `${CLAUDE_SESSION_ID}` 替换进 skill 文本），不传时按消息时间戳挑「持有最新粘贴图」的那份，两条路都不怕同项目并发多开。一句老实话：会话记录格式是 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 看到占位符会自动跑这一步。已在真实的 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），`recover-paste` 会自动探测两家宿主，已拿真实 pi 会话验证过。一句老实话：会话记录格式是这些工具的内部实现，没有兼容承诺，哪天捞不动了，拖文件永远是保底。
 
 ## 为什么外挂，而不是换多模态模型？
 

package/dist/main.js

@@ -850,123 +850,149 @@ const EXT_BY_MIME = {
   "image/webp": "webp",
   "image/gif": "gif"
 };
-function projectSlug(cwd) {
+function claudeProjectSlug(cwd) {
   return path.resolve(cwd).replace(/[/.]/g, "-");
 }
-function locateTranscript(cwd) {
-  const dir = path.join(os.homedir(), ".claude", "projects", projectSlug(cwd));
-  let entries;
-  try {
-    entries = fs.readdirSync(dir).filter((name) => name.endsWith(".jsonl"));
-  } catch {
-    throw new Error(
-      `No Claude Code transcripts found for this directory (${dir}). Run from the project the image was pasted in, or pass --transcript <path>.`
-    );
-  }
-  if (entries.length === 0) {
-    throw new Error(`No transcripts in ${dir}. Pass --transcript <path> to pick one manually.`);
-  }
-  let best = null;
-  for (const name of entries) {
-    const full = path.join(dir, name);
-    const timestamp = lastImageTimestamp(full);
-    if (timestamp && (!best || timestamp > best.timestamp)) {
-      best = { full, timestamp };
+function piSessionSlug(cwd) {
+  const resolved = path.resolve(cwd);
+  return `--${resolved.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+}
+const claudeAdapter = {
+  name: "claude-code",
+  sessionDir: (cwd) => path.join(os.homedir(), ".claude", "projects", claudeProjectSlug(cwd)),
+  matchesSession: (fileName, sessionId) => fileName === `${sessionId}.jsonl`,
+  extractUserImages: (line) => {
+    const message = line.message;
+    if (message?.role !== "user" || !Array.isArray(message.content)) {
+      return [];
     }
+    const images = [];
+    for (const block of message.content) {
+      const source = block?.source;
+      if (block?.type === "image" && source?.type === "base64" && source.data) {
+        images.push({ mediaType: source.media_type ?? "image/png", data: source.data });
+      }
+    }
+    return images;
   }
-  if (!best) {
-    throw new Error(
-      `No pasted images found in any transcript under ${dir}. The user may not have pasted any, or the transcript format changed; ask for a file path instead.`
-    );
+};
+const piAdapter = {
+  name: "pi",
+  sessionDir: (cwd) => path.join(os.homedir(), ".pi", "agent", "sessions", piSessionSlug(cwd)),
+  // pi files look like 2026-08-03T14-18-04-595Z_<uuid>.jsonl
+  matchesSession: (fileName, sessionId) => fileName.endsWith(`_${sessionId}.jsonl`),
+  extractUserImages: (line) => {
+    const message = line.message;
+    if (message?.role !== "user" || !Array.isArray(message.content)) {
+      return [];
+    }
+    const images = [];
+    for (const block of message.content) {
+      const typed = block;
+      if (typed?.type === "image" && typed.data) {
+        images.push({ mediaType: typed.mimeType ?? "image/png", data: typed.data });
+      }
+    }
+    return images;
   }
-  return best.full;
+};
+const ADAPTERS = [claudeAdapter, piAdapter];
+function lineTimestamp(line) {
+  const ts = line.timestamp;
+  return typeof ts === "string" ? ts : null;
 }
-function lastImageTimestamp(transcriptPath) {
+function forEachJsonLine(filePath, visit) {
   let raw;
   try {
-    raw = fs.readFileSync(transcriptPath, "utf-8");
+    raw = fs.readFileSync(filePath, "utf-8");
   } catch {
-    return null;
+    return;
   }
-  let latest = null;
   for (const line of raw.split("\n")) {
     if (!line.includes('"image"')) {
       continue;
     }
-    let parsed;
     try {
-      parsed = JSON.parse(line);
+      visit(JSON.parse(line));
     } catch {
-      continue;
     }
-    const entry = parsed;
-    if (entry.message?.role !== "user" || !Array.isArray(entry.message.content)) {
-      continue;
+  }
+}
+function newestImageTimestamp(adapter, filePath) {
+  let latest = null;
+  forEachJsonLine(filePath, (line) => {
+    if (adapter.extractUserImages(line).length === 0) {
+      return;
     }
-    const hasImage = entry.message.content.some(
-      (block) => block?.type === "image" && block.source?.type === "base64"
-    );
-    if (hasImage && entry.timestamp && (!latest || entry.timestamp > latest)) {
-      latest = entry.timestamp;
+    const ts = lineTimestamp(line);
+    if (ts && (!latest || ts > latest)) {
+      latest = ts;
     }
-  }
+  });
   return latest;
 }
-function extractUserImages(transcriptPath) {
-  let raw;
+function listTranscripts(adapter, cwd) {
   try {
-    raw = fs.readFileSync(transcriptPath, "utf-8");
-  } catch (error) {
-    throw new Error(`Cannot read transcript ${transcriptPath}: ${error.message}`);
+    return fs.readdirSync(adapter.sessionDir(cwd)).filter((name) => name.endsWith(".jsonl")).map((name) => path.join(adapter.sessionDir(cwd), name));
+  } catch {
+    return [];
   }
-  const images = [];
-  for (const line of raw.split("\n")) {
-    if (!line.includes('"image"')) {
-      continue;
-    }
-    let parsed;
-    try {
-      parsed = JSON.parse(line);
-    } catch {
-      continue;
-    }
-    const message = parsed.message;
-    if (message?.role !== "user" || !Array.isArray(message.content)) {
-      continue;
-    }
-    for (const block of message.content) {
-      const source = block?.source;
-      if (block?.type === "image" && source?.type === "base64" && source.data) {
-        images.push({ mediaType: source.media_type ?? "image/png", data: source.data });
+}
+function locateTranscript(cwd) {
+  const candidates = [];
+  for (const adapter of ADAPTERS) {
+    for (const transcript of listTranscripts(adapter, cwd)) {
+      const timestamp = newestImageTimestamp(adapter, transcript);
+      if (timestamp) {
+        candidates.push({ harness: adapter.name, transcript, timestamp });
       }
     }
   }
-  return images;
+  if (candidates.length === 0) {
+    const dirs = ADAPTERS.map((a) => a.sessionDir(cwd)).join(" , ");
+    throw new Error(
+      `No pasted images found in any session transcript for this directory (looked in: ${dirs}). The user may not have pasted any, or the transcript format changed; ask for a file path instead.`
+    );
+  }
+  candidates.sort((a, b) => a.timestamp < b.timestamp ? 1 : -1);
+  return { harness: candidates[0].harness, transcript: candidates[0].transcript };
 }
 function transcriptForSession(cwd, sessionId) {
-  const file = path.join(
-    os.homedir(),
-    ".claude",
-    "projects",
-    projectSlug(cwd),
-    `${sessionId}.jsonl`
+  for (const adapter of ADAPTERS) {
+    for (const transcript of listTranscripts(adapter, cwd)) {
+      if (adapter.matchesSession(path.basename(transcript), sessionId)) {
+        return { harness: adapter.name, transcript };
+      }
+    }
+  }
+  const dirs = ADAPTERS.map((a) => a.sessionDir(cwd)).join(" , ");
+  throw new Error(
+    `No transcript for session ${sessionId} under this project (looked in: ${dirs}). Check --cwd, or drop --session to auto-locate by newest pasted image.`
   );
-  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.`
-    );
+}
+function adapterFor(transcript) {
+  if (transcript.includes(`${path.sep}.pi${path.sep}`)) {
+    return piAdapter;
   }
-  return file;
+  return claudeAdapter;
+}
+function extractUserImages(transcriptPath) {
+  const adapter = adapterFor(transcriptPath);
+  const images = [];
+  forEachJsonLine(transcriptPath, (line) => {
+    images.push(...adapter.extractUserImages(line));
+  });
+  return images;
 }
 function recoverPastedImages(options = {}) {
   const cwd = options.cwd ?? process.cwd();
-  const transcript = options.transcript ?? (options.session ? transcriptForSession(cwd, options.session) : locateTranscript(cwd));
+  const located = options.transcript ? { harness: adapterFor(options.transcript).name, 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);
+  const all = extractUserImages(located.transcript);
   if (all.length === 0) {
     throw new Error(
-      `No pasted images found in ${transcript}. The user may not have pasted any, or the transcript format changed; ask for a file path instead.`
+      `No pasted images found in ${located.transcript}. The user may not have pasted any, or the transcript format changed; ask for a file path instead.`
     );
   }
   fs.mkdirSync(outDir, { recursive: true });
@@ -979,10 +1005,10 @@ function recoverPastedImages(options = {}) {
     fs.writeFileSync(filePath, buffer);
     return { path: filePath, mediaType: image.mediaType, bytes: buffer.length };
   });
-  return { transcript, images };
+  return { harness: located.harness, transcript: located.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.4.2");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.5.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").action(async (options) => {
   try {
     const timeoutMs = Number.parseInt(options.timeout, 10);

package/package.json

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

package/skills/modlens/SKILL.md

@@ -67,13 +67,13 @@ Harnesses rarely hand you a clean path. First identify which harness you are in,
 
 - 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 or Pi** (no path tag anywhere; the placeholder looks like `[Unsupported Image]` or a bare `[Image #1]`):
 
-- 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`.
+- Neither harness writes pasted images to a regular temp file, but both log them into local session transcripts (`~/.claude/projects/` and `~/.pi/agent/sessions/`). `recover-paste` auto-detects which harness owns the newest pasted image. 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.
+**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.
 
 ## Workflow