pi-image-slim 0.1.0 → 0.2.0

package/README.md

@@ -2,8 +2,8 @@
 
 [中文文档](./README.zh-CN.md)
 
-A [Pi](https://pi.dev) extension that shrinks screenshots and stops old ones from being
-re-uploaded.
+A [Pi](https://pi.dev) extension that shrinks screenshots, and optionally stops old ones from
+being re-uploaded.
 
 ## The problem
 
@@ -16,26 +16,26 @@ minute of uploading before the model even starts thinking.
 
 ## The fix
 
-Two things happen, at two different moments. Each can be turned off on its own.
+Two things can happen, at two different moments. The first is on by default; the second is
+opt-in.
 
-**When an image arrives**, it is compressed and described:
+**When an image arrives**, it is compressed:
 
 ```
-your screenshot  →  6.4x smaller WebP  +  one-line description
+your screenshot  →  6.4x smaller WebP
 ```
 
-**Once it falls out of the window**, it is replaced by text:
+**Once its turn is over**, it can be replaced by text (`"strip": true`):
 
 ```
 [image removed from history to save upload bandwidth. Re-read /proj/title.png if you need to see it again.]
 ```
 
-So each image is uploaded a small, bounded number of times, and what stays behind is a path
-plus a description — enough for the model to know what the picture was, and to fetch it again
-if it really needs to.
-
-If you would rather keep every image in view, set `"strip": false`. You still get the 6.4x
-compression, and the model never loses sight of anything.
+Compression is invisible — same picture, fewer bytes, the model sees exactly what it saw
+before. Replacement rewrites history, so it ships off and you decide. Switch it on when a slow
+link is the real problem: each image is then uploaded a small, bounded number of times, and
+what stays behind is a path plus a description — enough for the model to know what the picture
+was, and to fetch it again if it really needs to.
 
 ## Install
 
@@ -62,7 +62,7 @@ Four real screenshots from Pi's own docs, compressed to 1280 px / WebP / quality
 | **total** | **2.4 MB** | **377 KB** | **6.4x** |
 
 That saves bandwidth on the turn the image is sent, **and** disk space in the session file.
-Stripping saves bandwidth on every turn after that.
+Stripping, when you turn it on, saves bandwidth on every turn after that.
 
 ## Who this is for
 
@@ -79,8 +79,9 @@ Two hooks, nothing more.
 **`tool_result`** — runs when a tool returns an image.
 
 1. Re-encodes PNG/JPEG as WebP with the longest edge capped at `maxEdge` (`compress`).
-2. Asks the current model to describe the stored bytes in one line (`caption`).
-3. Writes both into the conversation as plain text:
+2. If stripping is on, asks the current model to describe the stored bytes in one line
+   (`caption`).
+3. Writes the path and that description into the conversation as plain text:
 
 ```
 Image file: /proj/docs/mockups/title.png
@@ -98,38 +99,44 @@ Image description: [2] Footer area: grey link list, copyright at the bottom.
 ```
 
 Because this is ordinary transcript text, it survives `/reload`, restarts, and compaction.
-The description is generated once, though its tokens are paid on every later request.
+The description is generated once, though its tokens are paid on every later request. With
+stripping off none of this is written: an image that never leaves context needs no address and
+no description, so that round trip is skipped too.
 
 **`before_provider_request`** — runs on the finished request body, just before it goes out.
 
-Every image outside the newest `keepImages` image-bearing messages becomes a placeholder
-(`strip`). Nothing else is touched. This pass never decodes anything: it swaps object pointers, so a 30 MB body costs
-about a millisecond.
+Every image whose turn is over becomes a placeholder (`strip`). Nothing else is touched. This
+pass never decodes anything: it swaps object pointers, so a 30 MB body costs about a
+millisecond.
 
 ### What the model sees
 
 | | Sent |
 | --- | --- |
-| The newest `keepImages` messages that carry an image | full image |
-| Anything older | placeholder + path |
+| Every image read since you last spoke | full image |
+| Images from earlier turns | placeholder + path |
 | The description note | always |
+| Nothing at all, with `strip: false` (the default) | full image, forever |
 
-### A window of messages, not of images
+### A window of turns, not of images
 
-The last two image-bearing messages are sent in full; everything older is a placeholder.
+Everything the agent has produced since you last spoke is sent verbatim. When you speak again,
+the previous turn's images become placeholders and the new turn starts clean. `keepTurns`
+(default `1`) moves that boundary further back.
 
-- Ten screenshots from **one** tool call share one message, so all ten arrive in full and the
-  model can compare them. The window counts messages, not pictures.
-- Each new screenshot pushes the oldest one out. The image is still there in the description
-  note, so the model knows what it was.
+- Ten screenshots in **one** turn stay visible for the whole turn, however many tool calls they
+  came from. A count-based window got this wrong: the third screenshot pushed the first one
+  out in the middle of the task that needed both.
 - The model needs another look → it `read`s the path, and that one image is uploaded again.
+- Nothing changes *within* a turn, so the request prefix is byte-identical on every step of a
+  loop and the prompt cache keeps hitting. The cut lands on a turn boundary, which costs
+  exactly one cache miss — in the request where those images actually went stale.
 
-The window is why this also works inside a single long task. While the agent works on its own
-there is no new user message, so a boundary based on "the last thing you typed" would never
-move and every screenshot would be re-uploaded on every step. Measured over a 30-step loop at
-68 KB per screenshot: **31 MB with a turn boundary, 4.1 MB with a window of 2** (ideal is 2 MB).
-
-Set `"keepImages": 1` for the strictest version — each image is then uploaded exactly once.
+The catch: an agent working on its own never sees a new user message, so the turn never ends
+and nothing would ever be stripped. Measured over a 30-step loop at 68 KB per screenshot that
+is **31 MB** (ideal: 2 MB). `maxKeptImages` is the escape hatch, and it stays at `0` — no cap —
+because cutting inside a turn buys bandwidth with a cache miss on every step, a trade only you
+can price. Set it to 6–8 on a slow link and the same loop costs 11–14 MB.
 
 ### Why WebP
 
@@ -151,17 +158,19 @@ A JSON file, not environment variables. Two locations, most specific last:
 {
   "maxEdge": 1280,
   "quality": 75,
-  "strip": true,
-  "keepImages": 2
+  "strip": false,
+  "keepTurns": 1,
+  "maxKeptImages": 0
 }
 ```
 
 | Key | Default | Meaning |
 | --- | --- | --- |
 | `compress` | `true` | Re-encode PNG/JPEG as WebP |
-| `caption` | `true` | Describe each image before the pixels go away |
-| `strip` | `true` | Replace old images with a placeholder |
-| `keepImages` | `2` | How many recent image messages stay intact (1-20) |
+| `caption` | `true` | Describe each image before the pixels go away (only used while `strip` is on) |
+| `strip` | `false` | Replace old images with a placeholder |
+| `keepTurns` | `1` | How many recent turns keep their images (1-20) |
+| `maxKeptImages` | `0` | Cap on image-bearing messages, even inside a kept turn; `0` = no cap |
 | `maxEdge` | `1280` | Ceiling for the **longer** side |
 | `quality` | `75` | WebP quality, 0-100 |
 | `captionTimeoutMs` | `20000` | Fall back to a bare path after this long; `0` = no limit |
@@ -169,20 +178,23 @@ A JSON file, not environment variables. Two locations, most specific last:
 Every key is optional. Unknown keys and bad values are ignored, and a malformed file falls
 back to defaults instead of breaking tool results. Run `/reload` after editing.
 
+0.1.x's `keepImages` is gone. It counted messages rather than turns, so it is ignored instead
+of being reinterpreted as `maxKeptImages` — that would quietly impose a cap nobody asked for.
+
 ### Pick your level
 
 | `compress` | `strip` | What happens |
 | --- | --- | --- |
-| `true` | `true` | **Default.** Smaller images, old ones become text. |
-| `true` | `false` | Images shrink ~6x, but the model keeps seeing all of them. |
+| `true` | `false` | **Default.** Images shrink ~6x, and the model keeps seeing all of them. |
+| `true` | `true` | Smaller images, and old ones become text. |
 | `false` | `true` | Full-size images, old ones become text. |
 
-`"strip": false` changes nothing about the conversation — the model can always look back at
-any image — while still cutting upload by about 84%. That is the safest setting if you are
-unsure.
+The default changes nothing about the conversation — the model can always look back at any
+image — while still cutting upload by about 84%. Turn `strip` on when that is not enough, on
+a slow, metered, or proxied link.
 
 `caption` only does something while `strip` is on: an image that never leaves context does
-not need a description, so the extra round trip is skipped automatically. `keepImages` below 1
+not need a description, so the extra round trip is skipped automatically. `keepTurns` below 1
 is ignored, because the model has to be able to see the image it just asked for.
 
 **Raise `maxEdge` if you work with small text** — 1568 is a common choice. Keep it at 2000 or
@@ -223,16 +235,18 @@ Images are detected in all of them, including images nested inside `tool_result`
 - **Reading an image costs one extra model round trip**, because the description is generated
   before the tool result is committed. Images are handled one at a time, so ten images means
   ten round trips.
-- **Prompt cache misses once**, on the turn after an image was read. The `tools` and `system`
-  layers still hit; only `messages` is invalidated.
+- **Prompt cache misses once per turn boundary**, when the previous turn's images are replaced.
+  The `tools` and `system` layers still hit; only `messages` is invalidated. With
+  `maxKeptImages` set, the cut moves every step and you pay that miss every step.
 - **A batch of images cannot be re-read.** When one call returns several images, Pi reports one
   `path`, so none of them can claim it. The descriptions survive; the pixels do not.
 - **The model may answer from the description instead of looking again.** For pixel-level
   work, ask it to re-`read` the file.
-- **Old images are invisible to the model within a long task.** With a window of 2, a
-  screenshot taken ten steps ago is a placeholder by the time the model wants to re-check it.
-  The description is still there; the pixels are one `read` away. Raise `keepImages` if you
-  work across many screenshots at once.
+- **A long task keeps every image it reads**, because the turn never ends. That is the price of
+  the cache-friendly cut. Lower `maxKeptImages` if the uploads hurt more than the misses.
+- **Turn boundaries depend on how Pi serialises a turn**, i.e. on a real `user` message and on
+  the synthetic carrier Pi creates for tool images. If a future Pi changes that shape, the
+  extension degrades safely: it finds no boundary and strips nothing.
 - **Old sessions are not retrofitted.** Only images read while the extension is active get
   compressed and described.
 - **Session files still keep the compressed image**, not just the text. Stripping only
@@ -245,7 +259,7 @@ git clone https://github.com/wiidede/pi-image-slim
 cd pi-image-slim
 pnpm install
 pnpm check       # lint + typecheck + tests
-pnpm test        # 59 tests, no network, no fixtures
+pnpm test        # 69 tests, no network, no fixtures
 ```
 
 ## License

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](./README.md)
 
-一个 [Pi](https://pi.dev) 扩展：压缩截图，并让旧图不再反复重传。
+一个 [Pi](https://pi.dev) 扩展：压缩截图；如果你需要，还能让旧图不再反复重传。
 
 ## 问题
 
@@ -12,23 +12,21 @@ Pi 每次请求都会把整个对话发一遍。prompt cache 让服务端算起
 
 ## 做法
 
-两个时刻，各做一件事，两件都能单独关掉。
+两个时刻，各做一件事。第一件默认开着，第二件要你自己开。
 
-**图片进来时**，压缩并描述：
+**图片进来时**，压缩：
 
 ```
-你的截图  →  小 6.4 倍的 WebP  +  一句描述
+你的截图  →  小 6.4 倍的 WebP
 ```
 
-**等它被挤出窗口后**，它被替换成文字：
+**等它那一轮结束之后**，可以换成文字（`"strip": true`）：
 
 ```
 [image removed from history to save upload bandwidth. Re-read /proj/title.png if you need to see it again.]
 ```
 
-于是每张图的上传次数是有界的、很少的几次，留下的是路径加描述——够模型知道那张图是什么，也够它真需要时再取回来。
-
-如果你更希望所有图片一直可见，设 `"strip": false`。照样能得到 6.4 倍的压缩，而且模型什么都不会丢。
+压缩是隐形的——同一张图，字节更少，模型看到的和以前完全一样。替换会改写对话历史，所以默认关着，由你决定。网络真的是瓶颈时再开：每张图的上传次数有界且很少，留下的是路径加描述——够模型知道那张图是什么，也够它真需要时再取回来。
 
 ## 安装
 
@@ -54,7 +52,7 @@ Pi 官方文档里的四张真实截图，压到 1280 px / WebP / 质量 75：
 | `doom-extension.png` | 167 KB | 44 KB | 3.7x |
 | **合计** | **2.4 MB** | **377 KB** | **6.4x** |
 
-这既省了图片被发送那一轮的带宽，**也**省了会话文件的磁盘空间。剥离则省掉之后每一轮的带宽。
+这既省了图片被发送那一轮的带宽，**也**省了会话文件的磁盘空间。打开剥离后，还能省掉之后每一轮的带宽。
 
 ## 适合谁
 
@@ -71,8 +69,8 @@ Pi 官方文档里的四张真实截图，压到 1280 px / WebP / 质量 75：
 **`tool_result`** —— 工具返回图片时触发。
 
 1. 把 PNG/JPEG 重新编码成 WebP，最长边限制在 `maxEdge`（`compress`）。
-2. 让当前模型对"真正会被存下来的那份字节"写一句描述（`caption`）。
-3. 两者都作为普通文本写进对话：
+2. 如果开着剥离，让当前模型对“真正会被存下来的那份字节”写一句描述（`caption`）。
+3. 把路径和描述作为普通文本写进对话：
 
 ```
 Image file: /proj/docs/mockups/title.png
@@ -87,31 +85,30 @@ Image description: [1] Header 区域：深色导航栏，右侧一个登录按
 Image description: [2] Footer 区域：灰色链接列表，版权信息在底部。
 ```
 
-因为这就是普通的对话记录，它能挺过 `/reload`、进程重启和上下文压缩。描述只生成一次，但它的 token 每轮都要重付。
+因为这就是普通的对话记录，它能挺过 `/reload`、进程重启和上下文压缩。描述只生成一次，但它的 token 每轮都要重付。没开剥离时这些一个字都不会写：永远不会离开上下文的图，既不需要地址也不需要描述，那次模型往返也一并省掉。
 
 **`before_provider_request`** —— 在请求体组装完、还没发出去的一刻触发。
 
-最近 `keepImages` 条带图消息之外的图片都变成占位符，其它什么都不动。这一遍**不解码任何数据**，只是替换对象指针，30 MB 的请求体大约一毫秒。
+轮次已经结束的图片变成占位符，其它什么都不动。这一遍**不解码任何数据**，只是替换对象指针，30 MB 的请求体大约一毫秒。
 
 ### 模型每轮看到什么
 
 | | 发送内容 |
 | --- | --- |
-| 最近 `keepImages` 条带图消息 | 完整图片 |
-| 更早的 | 占位符 + 路径 |
+| 你上次发言以来读进来的所有图 | 完整图片 |
+| 更早轮次里的图 | 占位符 + 路径 |
 | 那条描述 note | 始终保留 |
+| 默认（`strip: false`）时 | 完整图片，永远都在 |
 
-### 窗口按消息算，不按图片算
+### 窗口按轮算，不按图片算
 
-最近两条带图消息完整发送，更早的变成占位符。
+你上次发言之后 agent 产出的一切都完整发送。你再次开口时，上一轮的图片变成占位符，新一轮从干净的窗口开始。`keepTurns`（默认 `1`）把这个边界再往前推几轮。
 
-- **一次**工具调用返回的十张截图共享同一条消息，所以十张都完整送达，模型可以互相对比。窗口数的是消息，不是张数。
-- 每来一张新截图，最老的那条被挤出去。图虽然没了，描述还在，模型仍知道它是什么。
+- **同一轮**里的十张截图在整个那一轮里都完整可见，不管它们来自几次工具调用。按条数计窗口在这里是错的：第三张截图会把第一张挤出去，而任务正需要同时看这两张。
 - 模型要再看 → 它对路径 `read` 一次，那一张图会被重新上传。
+- **一轮之内什么都不变**，所以循环里每一步发出的前缀都逐字节相同，prompt cache 一直命中。切口落在轮次边界上，只花掉一次 miss——就发生在那些图真正过期的那次请求里。
 
-这个窗口也是它能在一个长任务里生效的原因。agent 自己干活时不会有新的用户消息，所以"以你最后一次发言为界"这条规则永远不会移动，每一步都会把所有截图重传一遍。实测 30 步、每步一张 68 KB 截图：**按轮划分是 31 MB，窗口为 2 是 4.1 MB**（理想值 2 MB）。
-
-想要最严格就把 `"keepImages"` 设成 `1`——那样每张图确实只上传一次。
+代价是：agent 自己干活时不会有新的用户消息，这一轮就不会结束，也就永远不会剥离。实测 30 步、每步一张 68 KB 截图：**31 MB**（理想值 2 MB）。`maxKeptImages` 就是为这个准备的，默认 `0`——不限，因为在一轮内部下刀等于每一步都拿一次缓存 miss 换带宽，这个価只有你自己能定。慢链路上把它设成 6–8，同样的循环降到 11–14 MB。
 
 ### 为什么是 WebP
 
@@ -130,34 +127,38 @@ Image description: [2] Footer 区域：灰色链接列表，版权信息在底
 {
   "maxEdge": 1280,
   "quality": 75,
-  "strip": true,
-  "keepImages": 2
+  "strip": false,
+  "keepTurns": 1,
+  "maxKeptImages": 0
 }
 ```
 
 | 键 | 默认 | 含义 |
 | --- | --- | --- |
 | `compress` | `true` | 把 PNG/JPEG 重新编码成 WebP |
-| `caption` | `true` | 像素丢掉之前先写一句描述 |
-| `strip` | `true` | 把旧图换成占位符 |
-| `keepImages` | `2` | 保留最近几条带图消息（1–20） |
+| `caption` | `true` | 像素丢掉之前先写一句描述（只在 `strip` 开着时生效） |
+| `strip` | `false` | 把旧图换成占位符 |
+| `keepTurns` | `1` | 保留最近几轮里的图片（1–20） |
+| `maxKeptImages` | `0` | 即使在保留的轮次里，也最多留下几条带图消息；`0` 表示不限 |
 | `maxEdge` | `1280` | **较长边**的上限 |
 | `quality` | `75` | WebP 质量，0–100 |
 | `captionTimeoutMs` | `20000` | 超过这么久就退回纯路径；`0` 表示不限时 |
 
 所有键都可选。未知的键和不合法的值会被忽略，文件格式坏了也只是退回默认值，不会弄坏工具结果。改完记得 `/reload`。
 
+0.1.x 的 `keepImages` 已经不存在了。它数的是消息条数而不是轮次，所以直接忽略，而不是悄悄当成 `maxKeptImages`——那会给用户强加一个他没要求的限制。
+
 ### 选一个档位
 
 | `compress` | `strip` | 效果 |
 | --- | --- | --- |
-| `true` | `true` | **默认。** 图片变小，旧的变成文字。 |
-| `true` | `false` | 图片小 6 倍左右，但模型始终能看到全部图片。 |
+| `true` | `false` | **默认。** 图片小 6 倍左右，模型始终能看到全部图片。 |
+| `true` | `true` | 图片变小，旧的变成文字。 |
 | `false` | `true` | 原图尺寸，旧的变成文字。 |
 
-`"strip": false` **完全不影响对话内容**——模型随时能回头看任何一张图——但上行带宽仍然能省大约 84%。拿不定主意时，选这个最稳。
+默认设置**完全不影响对话内容**——模型随时能回头看任何一张图——但上行带宽仍然能省大约 84%。这还不够、链路又慢又贵要走代理，再打开 `strip`。
 
-`caption` 只在 `strip` 开着时才有意义：永远不会离开上下文的图，不需要描述，所以那次额外的模型往返会自动跳过。`keepImages` 小于 1 会被忽略——模型总得能看见它刚要求的那张图。
+`caption` 只在 `strip` 开着时才有意义：永远不会离开上下文的图，不需要描述，所以那次额外的模型往返会自动跳过。`keepTurns` 小于 1 会被忽略——模型总得能看见它刚要求的那张图。
 
 **如果常看小字，把 `maxEdge` 调大** —— 1568 是常见选择。但别超过 2000：超过之后 Pi 自己的图片归一化会把结果重新编码，我们生成的 WebP 就白做了。
 
@@ -184,12 +185,12 @@ Image description: [2] Footer 区域：灰色链接列表，版权信息在底
 - **压缩会永久降低分辨率。** 重新 `read` 也找不回细节——Pi 每次读都会应用同样的缩放。需要看清小字就调大 `maxEdge`。
 - **描述可能是错的。** 一句自信但错误的描述比没有更糟，因为模型会照着它推理。描述由本来就要看这张图的模型当场生成，也没发给任何新的端点，但**没有被验证过**。设 `"caption": false` 可以关掉。
 - **批量返回的图无法重新读取。** 一次调用返回多张图时，Pi 只报一个 `path`，所以它们谁也用不上。描述还在，像素没了。
-- **长任务里旧的图对模型是不可见的。** 窗口为 2 时，十步之前的截图早就变成占位符了。描述还在，像素只差一次 `read`。如果你经常要同时对照很多张图，把 `keepImages` 调大。
+- **旧图在长任务里仍然保留**，因为那一轮没结束。这是缓存友好的代价。如果上传比 miss 更痛，把 `maxKeptImages` 调小。
 - **描述只生成一次，不会重试。** 如果那次请求超时，占位符就永远是纯路径。调大 `captionTimeoutMs` 可以降低概率。
 - **读一张图会多一次模型往返**，因为描述要在工具结果落盘前生成。图片是一张一张处理的，读十张就是十次往返。
-- **prompt cache 会 miss 一次**，发生在图片被读进来的下一轮。`tools` 和 `system` 层仍然命中，只有 `messages` 失效。
+- **prompt cache 每个轮次边界 miss 一次**，就是上一轮的图被替换的那一次。`tools` 和 `system` 层仍然命中，只有 `messages` 失效。一旦你设了 `maxKeptImages`，切口每一步都在动，那就每一步都要付这次 miss。
 - **模型可能照描述回答，而不是重新看图。** 做像素级的工作时，直接让它再 `read` 一次那个文件。
-- **轮次边界的判断依赖 Pi 的序列化细节**（那条合成的 `Attached image(s) from tool result:` 消息）。如果未来的 Pi 改了形状，扩展会安全降级：找不到边界，就什么都不剥离。
+- **轮次边界的判断依赖 Pi 的序列化细节**（真实的 `user` 消息，以及 Pi 为工具图片合成的那条 `Attached image(s) from tool result:` 消息）。如果未来的 Pi 改了形状，扩展会安全降级：找不到边界，就什么都不剥离。
 - **旧会话不会被追溯处理。** 只有扩展启用期间读进来的图才会被压缩和描述。
 - **会话文件里仍然保留压缩后的图片**，不只是文字。剥离只影响线上传输的部分。
 
@@ -200,7 +201,7 @@ git clone https://github.com/wiidede/pi-image-slim
 cd pi-image-slim
 pnpm install
 pnpm check       # lint + typecheck + 测试
-pnpm test        # 59 个测试，不联网，不依赖磁盘文件
+pnpm test        # 69 个测试，不联网，不依赖磁盘文件
 ```
 
 ## License

package/config.ts

@@ -25,14 +25,22 @@ export interface ImageSlimConfig {
   compress: boolean
   /** Ask the current model to describe each image before the pixels are dropped. */
   caption: boolean
-  /** Replace images from earlier turns with a text placeholder. */
+  /** Replace images from earlier turns with a text placeholder. Off by default. */
   strip: boolean
   /**
-   * How many of the newest image-bearing messages stay in full. Everything older
-   * becomes a placeholder. At least one is always kept: the model has to be able
-   * to see the image it just asked for.
+   * How many of the newest *turns* stay in full. A turn starts at a real user
+   * message, so everything the agent produced since the user last spoke is kept
+   * verbatim. At least one is always kept: the model has to be able to see the
+   * image it just asked for.
    */
-  keepImages: number
+  keepTurns: number
+  /**
+   * Hard cap on how many image-bearing messages survive, across all kept turns.
+   * `0` disables the cap. It exists for the one case a turn boundary never closes:
+   * an agent working on its own. Cutting inside a turn costs a cache miss per
+   * step, so this stays opt-in — lower it on a slow link.
+   */
+  maxKeptImages: number
   /** Longest edge kept when re-encoding. Applies to the longer of width/height. */
   maxEdge: number
   /** WebP quality, 0-100. */
@@ -44,8 +52,13 @@ export interface ImageSlimConfig {
 export const DEFAULTS: ImageSlimConfig = {
   compress: true,
   caption: true,
-  strip: true,
-  keepImages: 2,
+  // Stripping rewrites history, which is not something to do to someone who did
+  // not ask for it. Compression alone is invisible: same pixels, fewer bytes.
+  strip: false,
+  keepTurns: 1,
+  // No cap by default: an arbitrary cap inside a turn trades prompt cache for
+  // upload bandwidth, and only the user knows which one their link needs.
+  maxKeptImages: 0,
   maxEdge: 1280,
   quality: 75,
   captionTimeoutMs: 20_000,
@@ -88,7 +101,8 @@ function apply(config: ImageSlimConfig, raw: RawConfig): ImageSlimConfig {
     compress: asBoolean(raw.compress) ?? config.compress,
     caption: asBoolean(raw.caption) ?? config.caption,
     strip: asBoolean(raw.strip) ?? config.strip,
-    keepImages: asInteger(raw.keepImages, 1, 20) ?? config.keepImages,
+    keepTurns: asInteger(raw.keepTurns, 1, 20) ?? config.keepTurns,
+    maxKeptImages: asInteger(raw.maxKeptImages, 0, 200) ?? config.maxKeptImages,
     maxEdge: asInteger(raw.maxEdge, 1, 20_000) ?? config.maxEdge,
     quality: asInteger(raw.quality, 0, 100) ?? config.quality,
     captionTimeoutMs: asInteger(raw.captionTimeoutMs, 0, 600_000) ?? config.captionTimeoutMs,

package/index.ts

@@ -11,16 +11,15 @@
  *
  * The fix (two hooks)
  *   1. `tool_result`             — re-encode every image as WebP (capped longest
- *                                   edge), then ask the current model for a
- *                                   one-line description while the pixels are
- *                                   still visible. Write both the path and the
- *                                   description into a text note that stays in
+ *                                   edge). When stripping is on, also ask the
+ *                                   current model for a one-line description while
+ *                                   the pixels are still visible, and write the path
+ *                                   and description into a text note that stays in
  *                                   history.
  *   2. `before_provider_request` — the final serialized request body, one step
- *                                   before it goes on the wire. Images outside
- *                                   the newest `keepImages` image-bearing
- *                                   messages are replaced with a one-line text
- *                                   placeholder.
+ *                                   before it goes on the wire. Images from turns
+ *                                   older than the newest `keepTurns` are replaced
+ *                                   with a one-line text placeholder.
  *
  * Two stages of reduction
  *   Compression shrinks each image by roughly 3-8x, which cuts upload bandwidth
@@ -36,18 +35,26 @@
  *   bare path. It also means the strip pass never has to read pixels back out of
  *   a provider payload, so it stays a pure pointer swap.
  *
- * A sliding window of messages
- *   The newest `keepImages` messages that carry an image are sent verbatim;
- *   everything older becomes a placeholder. Three consequences:
+ * A window of turns, not of messages
+ *   Everything the agent produced since the newest `keepTurns` user messages were
+ *   spoken is sent verbatim; images from older turns become placeholders. Four
+ *   consequences:
  *
- *   · A tool that returns ten screenshots puts them in one message, so they
- *     travel together — reading ten images in one call still shows all ten.
- *   · The window does not care whether the user spoke. That matters: an agent
- *     working on its own keeps one user message at index 0 for the whole loop,
- *     so a turn-based rule strips nothing there and re-uploads every screenshot
- *     on every step. Measured over a 30-step loop, that is 31 MB instead of 2 MB.
- *   · Nothing depends on how Pi serialises a turn. The window is just "messages
- *     that contain an image", counted from the end.
+ *   · Reading ten screenshots in one turn keeps all ten visible for the rest of
+ *     that turn. A count-based window got this wrong: the third screenshot pushed
+ *     the first one out, in the middle of the task that needed both.
+ *   · Nothing changes *within* a turn, so the request prefix is byte-identical on
+ *     every step of a loop and the prompt cache keeps hitting. Stripping lands on
+ *     a turn boundary, which costs exactly one cache miss — in the request where
+ *     the images actually went stale.
+ *   · A turn boundary is a real user message. A tool that returns ten screenshots
+ *     hoists them into a synthetic user message of their own, and turning that
+ *     into a boundary would cut the turn in half, so carriers are skipped.
+ *   · An agent working on its own never sees a new user message: the turn never
+ *     ends, and a rule that only cuts at boundaries would strip nothing and
+ *     re-upload every screenshot on every step (31 MB over a 30-step loop,
+ *     measured). `maxKeptImages` is the answer, and it stays off by default — it
+ *     buys bandwidth with cache misses, which is a trade only the user can price.
  *
  * Properties
  *   · Compression is best-effort: a failure, an unsupported format, or a result
@@ -71,6 +78,7 @@ import { DEFAULTS, loadConfig } from './config.ts'
 import { compressImage } from './image.ts'
 import {
   collectImageParts,
+  isImageCarrier,
   isRecord,
   textPartFor,
   topLevelMessages,
@@ -188,25 +196,41 @@ function nearbyNote(messages: unknown[], index: number): ImageNote | undefined {
 // ─────────────────────────────────────────────────────────────
 
 /**
- * Replace every image outside the newest `keepImages` image-bearing messages
- * with a text placeholder, in place. Returns the number of images replaced.
- *
- * The unit is the *message*, not the image. A tool that returns ten screenshots
- * puts them all in one message, and they live or die together — so reading ten
- * images in one call still shows the model all ten.
+ * Index of the user message that opens the `keepTurns`-th newest turn. Everything
+ * at or after it is sent verbatim. Returns 0 — strip nothing — when the history
+ * holds fewer turns than that, which is also the safe answer when Pi's
+ * serialisation stops looking the way this expects.
+ */
+export function turnStart(messages: unknown[], keepTurns: number): number {
+  const starts: number[] = []
+  for (let i = 0; i < messages.length; i++) {
+    const message = messages[i]
+    if (isRecord(message) && message.role === 'user' && !isImageCarrier(message))
+      starts.push(i)
+  }
+  return starts.length < keepTurns
+    ? 0
+    : starts[starts.length - keepTurns]!
+}
+
+/**
+ * Replace every image older than the kept turns with a text placeholder, in
+ * place. Returns the number of images replaced.
  *
- * Counting messages instead of locating turn boundaries is what makes this hold
- * inside a single agent loop. `turnStart()` used to key on the last real user
- * message, which never moves while the agent works on its own, so a 30-step loop
- * kept every screenshot and re-uploaded the lot on every request. With a window,
- * each image is uploaded once and then dropped, whether or not the user spoke.
+ * The unit is the *message*: a tool that returns ten screenshots puts them all in
+ * one message, and they live or die together — reading ten images in one call
+ * still shows the model all ten.
  */
-export function stripOldImages(payload: unknown, api?: string, keepImages = DEFAULTS.keepImages): number {
+export function stripOldImages(
+  payload: unknown,
+  api?: string,
+  keepTurns = DEFAULTS.keepTurns,
+  maxKeptImages = DEFAULTS.maxKeptImages,
+): number {
   const messages = topLevelMessages(payload)
   if (!messages)
     return 0
 
-  // One pass to find where the kept window begins.
   const carriers: number[] = []
   for (let i = 0; i < messages.length; i++) {
     const refs: ImageRef[] = []
@@ -214,10 +238,19 @@ export function stripOldImages(payload: unknown, api?: string, keepImages = DEFA
     if (refs.length > 0)
       carriers.push(i)
   }
-  if (carriers.length <= keepImages)
+  if (carriers.length === 0)
     return 0
 
-  const keepFrom = carriers[carriers.length - keepImages]!
+  let keepFrom = turnStart(messages, keepTurns)
+
+  // The cap is off by default. When it is on it can only ever move the cut
+  // forward, never back — it exists to bound a turn that never ends, not to
+  // overrule the turns the user asked to keep.
+  if (maxKeptImages > 0 && carriers.length > maxKeptImages)
+    keepFrom = Math.max(keepFrom, carriers[carriers.length - maxKeptImages]!)
+
+  if (keepFrom <= 0)
+    return 0
 
   let removed = 0
   for (let i = 0; i < keepFrom; i++) {
@@ -383,7 +416,12 @@ export default function (pi: ExtensionAPI): void {
     if (!config.strip)
       return undefined
 
-    const removed = stripOldImages(event.payload, ctx.model?.api, config.keepImages)
+    const removed = stripOldImages(
+      event.payload,
+      ctx.model?.api,
+      config.keepTurns,
+      config.maxKeptImages,
+    )
     // Return undefined when nothing changed, so the body object is left alone.
     return removed > 0
       ? event.payload

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "pi-image-slim",
   "type": "module",
-  "version": "0.1.0",
-  "packageManager": "pnpm@12.15.0",
+  "version": "0.2.0",
   "description": "Pi extension that stops historical images from being re-uploaded on every request — each image is sent in full exactly once, then replaced by a path-carrying placeholder.",
   "author": "wiidede",
   "license": "MIT",
@@ -50,15 +49,6 @@
   "engines": {
     "node": ">=22.19.0"
   },
-  "scripts": {
-    "lint": "eslint .",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "check": "pnpm lint && pnpm typecheck && pnpm test",
-    "release": "pnpm check && bumpp",
-    "prepublishOnly": "pnpm check"
-  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
   },
@@ -77,5 +67,13 @@
     "pnpm": "^12.15.0",
     "typescript": "^6.0.3",
     "vitest": "^5.0.5"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "pnpm lint && pnpm typecheck && pnpm test",
+    "release": "pnpm check && bumpp"
   }
-}
+}

package/protocol.ts

@@ -59,6 +59,39 @@ export function isImagePart(part: unknown): boolean {
   return false
 }
 
+/**
+ * Is this user message an artefact of a tool returning images rather than the
+ * user actually speaking? Turn boundaries must never land on one of these.
+ *
+ * Pi hoists tool images out of the result: `openai-completions` pushes a
+ * synthetic user message with a fixed header, `anthropic-messages` wraps them in
+ * a `tool_result` block, google and bedrock leave a bare image part. A false
+ * positive here (calling a tool artefact a real turn) cuts the current turn in
+ * half, so the test is deliberately generous — mistaking a user's own pasted
+ * image for an artefact is harmless, because it sits *after* the turn start and
+ * is therefore kept either way.
+ */
+export function isImageCarrier(message: unknown): boolean {
+  if (!isRecord(message) || message.role !== 'user')
+    return false
+  // `content` for openai/anthropic/bedrock, `parts` for google.
+  for (const list of [message.content, message.parts]) {
+    if (!Array.isArray(list))
+      continue
+    for (const part of list) {
+      if (!isRecord(part))
+        continue
+      if (isImagePart(part) || part.type === 'tool_result')
+        return true
+      if (part.type === 'text' && typeof part.text === 'string'
+        && part.text.startsWith('Attached image(s) from tool result')) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
 /** Top-level message array: `messages` (openai), `input` (responses), `contents` (google). */
 export function topLevelMessages(payload: unknown): unknown[] | undefined {
   if (!isRecord(payload))