A local plugin for image-heavy chats in Codex, Claude Code and other agents: earlier images stop going out with every message, and the model fetches the one it needs by its ID, also after compaction.
TypeScript ai-agentsclaude-codeclaude-code-plugincodexcodex-plugincontext-managementdeveloper-toolsimage-generationmcpmultimodal
fix(images): name Codex's viewed images when the code builds the path
chipfighter757e9eaa5eb2
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8b4f4cb..b71040a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,27 @@When a version is released, its section here becomes the GitHub release notes.+## [Unreleased]++Images Codex opens get their file names more often, and never someone else's.++### Fixed++- **File names for images Codex opens.** When Codex opened an image through a path it built in code (a folder plus the file name, for example), the image got no name in the panel or in the list after a compaction, so you could not refer to it by its file name. It now gets its name whenever the file name is written in the code.+- **No more names on the wrong image.** When Codex opened several images in one step and the name of one could not be told, the next one's name could land on it, and images the model fetched back in the same step could take a name too. A name now goes only to the image it belongs to; when that is unclear, the image gets none.++### How we tested++- Unit tests, and the image names in this machine's 163 Codex tasks read with the old and the new version: 20 images got their name, none got a different one, and the 10 that lost theirs had a wrong one (mostly a folder name).++<details>+<summary>Technical details</summary>++- The engine reads the `path` of each `view_image` call in code-mode source without running it, and takes its last string when that is an image file name: `p + "a.png"`, `` `${dir}/a.png` `` and `join(dir, "a.png")` give `a.png`; `p + name`, a bare `".png"`, `?:` and `||` give none.+- Images that `cam_view_image` returned in the same code are copies, known by the line before them, and take no name; the other images follow the calls in order only when their count matches the number of calls.++</details>+## [0.10.0] - 2026-11-01Long conversations keep their images. When Codex or Claude Code compacts a long conversation, or when you go back to an earlier Claude session, the images from earlier turns are no longer lost: they keep their numbers, and the model can still tell which is which and open the right one again.diff --git a/docs/design.md b/docs/design.mdindex 1ffe324..c71a20e 100644--- a/docs/design.md+++ b/docs/design.md@@ -56,6 +56,7 @@- **图片在请求和记录里的样子**:- 用户上传:用户消息里依次是 `<image name=[Image #N] path="…">`、图片、`</image>` 三段。`[Image #N]` 在每条消息里都从 1 开始。- 工具查看和生成:Codex 的工具都经 `exec`(代码模式)调用,图片在 `custom_tool_call_output` 里。查看的文件路径写在调用代码里;生成的图后面跟着一段说明保存路径的文字。+ - 查看的图的名字(v0.10.1,`images.ts` 的 `viewName`):只读代码、不执行。每次 `view_image` 调用取参数里 `path` 的最后一个字符串,是图片文件名才算(`p + "a.png"`、`` `${dir}/a.png` ``、`join(dir, "a.png")` 都是 a.png);名字没写出来(`p + name`、只写了 `".png"`)或是几个里挑一个(`?:`、`||`)的,留空。同一段代码里用 `cam_view_image` 取回的副本(前面那行标签认得出)不算;其余的图按调用顺序对应,图数和调用数对不上时都留空,宁缺不错。原来只认写死的路径,拼出来的路径没有名字;一次调用看不出名字时,后面调用的名字还会挪到前一张图上。- 托管生图的结果(`image_generation_call.result`)是必填字段,换不成文字,所以不能取消。- 桌面版的评论截图:用户在 Codex 里给 PDF 或网页加评论时,用户消息里先是评论的文字(PDF 的评论带 `PDF path: …`、`PDF page: 3/12` 两行),然后每条评论一段说明、紧跟一张不带标签的图。说明的原文见第 11 节。- **编号**:从任务的本地记录(rollout,只读)里按顺序找出所有图片出现记录,依次编号 IMG-001、IMG-002……记录只会追加,已有的编号不变。编号只由记录决定,插件服务和引擎各自计算,结果一致,不用共享状态。diff --git a/plugin/src/images.ts b/plugin/src/images.tsindex 9866ad9..c08816b 100644--- a/plugin/src/images.ts+++ b/plugin/src/images.ts@@ -102,9 +102,84 @@ function partDigest(part: Json): ImageDigest | null {return inline ? digest(part, part.image_url.slice(inline[0].length), inline[1]) : null;}+// v0.10.1 — reading the path of a view_image call in code-mode source, without running it.+const IMAGE_FILE = /^[^\\/]+\.(?:png|jpe?g|gif|webp|bmp|tiff?|avif|heic)$/i;+const CLOSE: Record<string, string> = { "{": "}", "(": ")", "[": "]" };+const skipSpace = (source: string, i: number) => { while (i < source.length && /\s/.test(source[i])) i++; return i; };++// A string literal at source[i] (a quote or a backtick): where it ends, and its text; a template's text is what follows+// its last substitution ("" when it ends with one).+function readString(source: string, i: number): { end: number; text: string } {+ const quote = source[i];+ let text = "";+ for (let j = i + 1; j < source.length; j++) {+ const ch = source[j];+ if (ch === "\\") { text += source[j + 1] ?? ""; j++; }+ else if (ch === quote) return { end: j + 1, text };+ else if (quote === "`" && ch === "$" && source[j + 1] === "{") { j = skipBracket(source, j + 1) - 1; text = ""; }+ else text += ch;+ }+ return { end: source.length, text };+}++// Past the bracket that closes the one at source[i], strings included.+function skipBracket(source: string, i: number): number {+ const open = [CLOSE[source[i]]];+ for (let j = i + 1; j < source.length; j++) {+ const ch = source[j];+ if (ch === '"' || ch === "'" || ch === "`") j = readString(source, j).end - 1;+ else if (CLOSE[ch]) open.push(CLOSE[ch]);+ else if (ch === open.at(-1)) { open.pop(); if (!open.length) return j + 1; }+ }+ return source.length;+}++// The next comma at this level, or `end`.+function nextComma(source: string, i: number, end: number): number {+ for (let j = i; j < end; j++) {+ const ch = source[j];+ if (ch === '"' || ch === "'" || ch === "`") j = readString(source, j).end - 1;+ else if (CLOSE[ch]) j = skipBracket(source, j) - 1;+ else if (ch === ",") return j;+ }+ return end;+}++// The file name a path expression writes: its last string (p + "a.png", `${dir}/a.png`, join(dir, "a.png")). Null when+// the name is not written (p + name, dir + "/" + f + ".png") or the path is one of several (a ? "x.png" : "y.png", ||).+function writtenName(expression: string): string | null {+ let last = "";+ for (let i = 0; i < expression.length; i++) {+ const ch = expression[i];+ if (ch === '"' || ch === "'" || ch === "`") { const string = readString(expression, i); last = string.text; i = string.end - 1; }+ else if (ch === "?" || ch === "|" || ch === "&") return null;+ }+ const name = baseName(last);+ return IMAGE_FILE.test(name) ? name : null;+}++// The name of the image a view_image call at source[at] (just after its "(") views, from the `path` of its argument.+function viewName(source: string, at: number): string | null {+ let i = skipSpace(source, at);+ if (source[i] !== "{") return null;+ const end = skipBracket(source, i) - 1;+ for (i++; i < end; i++) {+ i = skipSpace(source, i);+ let key = "";+ if (source[i] === '"' || source[i] === "'") { const string = readString(source, i); key = string.text; i = string.end; }+ else { const word = /^[\w$]+/.exec(source.slice(i, end))?.[0]; if (!word) return null; key = word; i += word.length; }+ i = skipSpace(source, i);+ const value = source[i] === ":" ? i + 1 : null;+ const stop = nextComma(source, value ?? i, end);+ if (key === "path") return value === null ? null : writtenName(source.slice(value, stop));+ i = stop;+ }+ return null;+}+// A tool output's images get names from the call that produced them: view_image paths, or the saved-image hint// that Codex's image generation adds next to its result.-function toolContext(call: Json | undefined, output: Json[]): { kind: ImageKind; names: string[] } {+function toolContext(call: Json | undefined, output: Json[]): { kind: ImageKind; names: (string | null)[] } {const hints = output.flatMap((part) => (typeof part?.text === "string" ? [...part.text.matchAll(/Generated images are saved to .*? as (.+?\.png) by default/g)].map((m) => baseName(m[1])) : []));if (hints.length) return { kind: "generated", names: hints };if (!call) return { kind: "tool", names: [] };@@ -115,9 +190,16 @@ function toolContext(call: Json | undefined, output: Json[]): { kind: ImageKind;return { kind: /imagegen|image_gen/.test(call.name ?? "") ? "generated" : "tool", names: [] };}const source = String(call.input ?? "");- // Paths written inline are read; paths passed through variables leave the names unknown.- const views = [...source.matchAll(/view_image\(\s*\{\s*path\s*:\s*(["'])((?:(?!\1)[^\\]|\\.)*)\1/g)].map((m) => baseName(m[2].replace(/\\(.)/g, "$1")));- if (views.length || source.includes("view_image")) return { kind: "view", names: views };+ // One name per view_image call (not our cam_view_image), null where the code does not write it. Images our+ // cam_view_image returned in the same code are copies, known by the line before them; the others follow the calls in+ // order only when each call brought one image, otherwise which image is which is unknown.+ const views = [...source.matchAll(/(?<![\w$])view_image\s*\(/g)].map((m) => viewName(source, m.index + m[0].length));+ if (views.length || source.includes("view_image")) {+ const viewed = output.flatMap((part, i) => (part?.type === "input_image" || part?.type === "output_image" ? [!FETCHED_LINE.test(output[i - 1]?.type === "input_text" ? String(output[i - 1].text) : "")] : []));+ if (views.length !== viewed.filter(Boolean).length) return { kind: "view", names: [] };+ let next = 0;+ return { kind: "view", names: viewed.map((own) => (own ? views[next++] : null)) };+ }return { kind: /image_gen|imagegen|generatedImage\(/.test(source) ? "generated" : "tool", names: [] };}diff --git a/spike/src/images.test.ts b/spike/src/images.test.tsindex 665fff5..f5523cc 100644--- a/spike/src/images.test.ts+++ b/spike/src/images.test.ts@@ -84,6 +84,38 @@ test("view_image through a variable path is still a viewed image; single-quotedassert.deepEqual(findImages(items).map((r) => [r.kind, r.name]), [["view", null], ["view", "e.png"]]);});+// v0.10.1 — a path built in code still names its image when the file name is written in it (the v10-compaction self-test,+// 2026-11-01: gpt-6-sol joined a folder and "a.png"), in the order of the calls.+const exec = (callId: string, input: string, images: Buffer[]) => [+ { type: "custom_tool_call", call_id: callId, name: "exec", input },+ { type: "custom_tool_call_output", id: `out_${callId}`, call_id: callId, output: images.map((bytes) => ({ type: "input_image", image_url: url(bytes) })) },+];++test("view_image paths built in code name their images when the file name is written in them", () => {+ const names = (input: string, count = 1) => findImages(exec("c", input, Array(count).fill(red))).map((r) => r.name);+ assert.deepEqual(names('const p="D:\\\\w\\\\";const r=await Promise.all([tools.view_image({path:p+"a.png"}),tools.view_image({path:p+"b.png"})]);for(let i=0;i<r.length;i++){text(i?"b.png":"a.png");image(r[i].image_url)}', 2), ["a.png", "b.png"]);+ assert.deepEqual(names("await tools.view_image({path: `${dir}/c.png`})"), ["c.png"], "a template string");+ assert.deepEqual(names('await tools.view_image({ detail: "original", path: path.join(dir, "d.png") })'), ["d.png"], "path not the first key, through join()");+});++test("a path whose file name is not written stays unnamed, and no name moves to another image", () => {+ const names = (input: string, count = 1) => findImages(exec("c", input, Array(count).fill(red))).map((r) => r.name);+ assert.deepEqual(names("await tools.view_image({path: dir + name})"), [null]);+ assert.deepEqual(names('await tools.view_image({path: dir + "/" + f + ".png"})'), [null], "only the extension is written");+ assert.deepEqual(names('await tools.view_image({path: dark ? "x.png" : "y.png"})'), [null], "one of two names");+ assert.deepEqual(names('await tools.view_image({path}); await tools.view_image({path: "e.png"})', 2), [null, "e.png"], "the first call's name is unknown");+ assert.deepEqual(names('for (const f of files) await tools.view_image({path: f}); await tools.view_image({path: "g.png"})', 3), [null, null, null], "more images than calls: which is which is unknown");+});++test("images the same code fetched with cam_view_image do not take a view_image call's name", () => {+ const fetched = (id: string, bytes: Buffer) => [{ type: "input_text", text: `[图片 ${id} 取回的原图|x.png|用户上传|第 1 轮|4×4]` }, { type: "input_image", image_url: url(bytes) }];+ const run = (input: string, output: Array<Record<string, any>>) => findImages([{ type: "custom_tool_call", call_id: "c", name: "exec", input }, { type: "custom_tool_call_output", id: "out", call_id: "c", output }]).map((r) => [r.name, r.fetchedId]);+ const fetch = 'const r = await tools.mcp__codex_attachment_manager__cam_view_image({ids:["IMG-017","IMG-018"]}); for (const c of r.content) c.type === "image" ? image(c) : text(c.text);';+ const view = 'const scene = await tools.view_image({path: "D:/w/t02.png"}); image(scene.image_url);';+ assert.deepEqual(run(fetch + view, [...fetched("IMG-017", red), ...fetched("IMG-018", red), { type: "input_image", image_url: url(blue) }]), [[null, "IMG-017"], [null, "IMG-018"], ["t02.png", null]], "fetched first");+ assert.deepEqual(run(view + fetch, [{ type: "input_image", image_url: url(blue) }, ...fetched("IMG-017", red)]), [["t02.png", null], [null, "IMG-017"]], "viewed first");+});+// v0.2 — Codex desktop (26.924) comments on a PDF or a web page: one text part with the comments (for a PDF with// "PDF path:" and "PDF page:" lines), then per comment a caption and the screenshot, a plain image without tags. Laid out// as in a real PDF comment the user made on 2026-09-29; the content here is made up.