pi-image-slim 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wiidede
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,253 @@
-# Temporary Holding Version
+# pi-image-slim
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文文档](./README.zh-CN.md)
+
+A [Pi](https://pi.dev) extension that shrinks screenshots and stops old ones from being
+re-uploaded.
+
+## The problem
+
+Pi sends the whole conversation with every request. Prompt caching makes that cheap for the
+server, but not for your uplink — an image that entered the conversation is uploaded again on
+**every single turn**, forever.
+
+Read 30 MB of screenshots and you upload 30 MB per turn. On a 500 KB/s connection that is a
+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.
+
+**When an image arrives**, it is compressed and described:
+
+```
+your screenshot  →  6.4x smaller WebP  +  one-line description
+```
+
+**Once it falls out of the window**, it is replaced by text:
+
+```
+[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.
+
+## Install
+
+```bash
+pi install npm:pi-image-slim
+```
+
+Or try it without touching your settings:
+
+```bash
+pi -e npm:pi-image-slim
+```
+
+## Measured
+
+Four real screenshots from Pi's own docs, compressed to 1280 px / WebP / quality 75:
+
+| File | Before | After | |
+| --- | --- | --- | --- |
+| `tree-view.png` | 275 KB | 68 KB | 4.0x |
+| `interactive-mode.png` | 506 KB | 84 KB | 6.0x |
+| `exy.png` | 1475 KB | 179 KB | 8.2x |
+| `doom-extension.png` | 167 KB | 44 KB | 3.7x |
+| **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.
+
+## Who this is for
+
+- You read screenshots, mockups, or browser captures into Pi
+- You are on a slow, metered, or proxied connection
+- Requests feel slow while the model seems idle
+
+If you paste one image and never look back, you do not need this.
+
+## How it works
+
+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:
+
+```
+Image file: /proj/docs/mockups/title.png
+Image description: A dark settings panel with three toggles, the middle one off.
+```
+
+When one call returns several images, they are numbered instead, and no path is claimed —
+Pi reports a single `path` for the whole call, so pointing every placeholder at it would send
+the model to a file holding only one of the pictures:
+
+```
+Image batch: 2 images from one call, no single file to re-read.
+Image description: [1] Header area: dark nav bar, a sign-in button on the right.
+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.
+
+**`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.
+
+### What the model sees
+
+| | Sent |
+| --- | --- |
+| The newest `keepImages` messages that carry an image | full image |
+| Anything older | placeholder + path |
+| The description note | always |
+
+### A window of messages, not of images
+
+The last two image-bearing messages are sent in full; everything older is a placeholder.
+
+- 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.
+- The model needs another look → it `read`s the path, and that one image is uploaded again.
+
+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.
+
+### Why WebP
+
+Measured on real screenshots it beats JPEG by 30-45% at the same visual quality, and roughly
+ties on photos. AVIF compresses further but Anthropic rejects it with a 400, and Pi rewrites
+unknown formats to PNG — which makes them bigger. Compression is best-effort: an unsupported
+format, a failure, or a result that is not actually smaller all leave the original alone.
+
+## Configuration
+
+A JSON file, not environment variables. Two locations, most specific last:
+
+| Path | Scope |
+| --- | --- |
+| `<agent-dir>/pi-image-slim.json` | every project (defaults to `~/.pi/agent`) |
+| `.pi/pi-image-slim.json` | this project only |
+
+```json
+{
+  "maxEdge": 1280,
+  "quality": 75,
+  "strip": true,
+  "keepImages": 2
+}
+```
+
+| 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) |
+| `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 |
+
+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.
+
+### 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. |
+| `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.
+
+`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
+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
+below: above that, Pi's own image normalisation re-encodes the result and throws the WebP
+away.
+
+**`maxEdge` measures the longer side**, so a 1200×4000 phone screenshot shrinks by its height
+just like a wide desktop capture shrinks by its width.
+
+## Disable
+
+There is no `enabled` key and no environment variable. To turn it off, disable the extension
+in your Pi config or uninstall it — one way instead of three.
+
+## Compatibility
+
+The placeholder shape is chosen from the model's API, so switching providers does not produce
+a 400:
+
+| API | Part |
+| --- | --- |
+| `openai-completions`, `anthropic-messages`, `mistral-conversations`, `pi-messages` | `{ type: "text", text }` |
+| `openai-responses`, `azure-openai-responses`, `openai-codex-responses` | `{ type: "input_text", text }` |
+| `google-generative-ai`, `google-vertex`, `bedrock-converse-stream` | `{ text }` |
+
+Images are detected in all of them, including images nested inside `tool_result`.
+
+## Caveats
+
+- **Compression lowers resolution permanently.** Re-`read`ing the file will not bring back a
+  detail — Pi applies the same resize every time. Raise `maxEdge` for small text.
+- **A description can be wrong.** A confident but incorrect one is worse than none, because
+  the model will reason from it. Descriptions come from the same model that already saw the
+  image, and nothing is sent anywhere new, but they are not verified. Set
+  `"caption": false` to turn them off.
+- **A description is written once and never retried.** If that request times out, the
+  placeholder stays path-only. Raise `captionTimeoutMs` to make that less likely.
+- **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.
+- **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.
+- **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
+  affects what goes over the wire.
+
+## Development
+
+```bash
+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
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,208 @@
+# pi-image-slim
+
+[English](./README.md)
+
+一个 [Pi](https://pi.dev) 扩展：压缩截图，并让旧图不再反复重传。
+
+## 问题
+
+Pi 每次请求都会把整个对话发一遍。prompt cache 让服务端算起来便宜，但省不了你的上行带宽——一张图一旦进了对话，之后**每一轮**都会被重新上传，永远如此。
+
+读了 30 MB 截图，就是每轮上传 30 MB。在 500 KB/s 的链路上，模型还没开始思考，光上传就要一分钟。
+
+## 做法
+
+两个时刻，各做一件事，两件都能单独关掉。
+
+**图片进来时**，压缩并描述：
+
+```
+你的截图  →  小 6.4 倍的 WebP  +  一句描述
+```
+
+**等它被挤出窗口后**，它被替换成文字：
+
+```
+[image removed from history to save upload bandwidth. Re-read /proj/title.png if you need to see it again.]
+```
+
+于是每张图的上传次数是有界的、很少的几次，留下的是路径加描述——够模型知道那张图是什么，也够它真需要时再取回来。
+
+如果你更希望所有图片一直可见，设 `"strip": false`。照样能得到 6.4 倍的压缩，而且模型什么都不会丢。
+
+## 安装
+
+```bash
+pi install npm:pi-image-slim
+```
+
+或者不改配置先试试：
+
+```bash
+pi -e npm:pi-image-slim
+```
+
+## 实测
+
+Pi 官方文档里的四张真实截图，压到 1280 px / WebP / 质量 75：
+
+| 文件 | 压缩前 | 压缩后 | |
+| --- | --- | --- | --- |
+| `tree-view.png` | 275 KB | 68 KB | 4.0x |
+| `interactive-mode.png` | 506 KB | 84 KB | 6.0x |
+| `exy.png` | 1475 KB | 179 KB | 8.2x |
+| `doom-extension.png` | 167 KB | 44 KB | 3.7x |
+| **合计** | **2.4 MB** | **377 KB** | **6.4x** |
+
+这既省了图片被发送那一轮的带宽，**也**省了会话文件的磁盘空间。剥离则省掉之后每一轮的带宽。
+
+## 适合谁
+
+- 你会把截图、设计稿、浏览器抓图读进 Pi
+- 你在用慢速、计费或需要代理的网络
+- 你感觉请求很慢，但模型看起来在发呆
+
+如果你只是偶尔贴一张图就再也不看，那不需要装这个。
+
+## 它怎么工作
+
+两个钩子，没有别的。
+
+**`tool_result`** —— 工具返回图片时触发。
+
+1. 把 PNG/JPEG 重新编码成 WebP，最长边限制在 `maxEdge`（`compress`）。
+2. 让当前模型对"真正会被存下来的那份字节"写一句描述（`caption`）。
+3. 两者都作为普通文本写进对话：
+
+```
+Image file: /proj/docs/mockups/title.png
+Image description: A dark settings panel with three toggles, the middle one off.
+```
+
+一次调用返回多张图时，描述会带序号，而且**不写路径**——Pi 对整次调用只报一个 `path`，把它写给每张图会让占位符指向一个只含其中一张的文件：
+
+```
+Image batch: 2 images from one call, no single file to re-read.
+Image description: [1] Header 区域：深色导航栏，右侧一个登录按钮。
+Image description: [2] Footer 区域：灰色链接列表，版权信息在底部。
+```
+
+因为这就是普通的对话记录，它能挺过 `/reload`、进程重启和上下文压缩。描述只生成一次，但它的 token 每轮都要重付。
+
+**`before_provider_request`** —— 在请求体组装完、还没发出去的一刻触发。
+
+最近 `keepImages` 条带图消息之外的图片都变成占位符，其它什么都不动。这一遍**不解码任何数据**，只是替换对象指针，30 MB 的请求体大约一毫秒。
+
+### 模型每轮看到什么
+
+| | 发送内容 |
+| --- | --- |
+| 最近 `keepImages` 条带图消息 | 完整图片 |
+| 更早的 | 占位符 + 路径 |
+| 那条描述 note | 始终保留 |
+
+### 窗口按消息算，不按图片算
+
+最近两条带图消息完整发送，更早的变成占位符。
+
+- **一次**工具调用返回的十张截图共享同一条消息，所以十张都完整送达，模型可以互相对比。窗口数的是消息，不是张数。
+- 每来一张新截图，最老的那条被挤出去。图虽然没了，描述还在，模型仍知道它是什么。
+- 模型要再看 → 它对路径 `read` 一次，那一张图会被重新上传。
+
+这个窗口也是它能在一个长任务里生效的原因。agent 自己干活时不会有新的用户消息，所以"以你最后一次发言为界"这条规则永远不会移动，每一步都会把所有截图重传一遍。实测 30 步、每步一张 68 KB 截图：**按轮划分是 31 MB，窗口为 2 是 4.1 MB**（理想值 2 MB）。
+
+想要最严格就把 `"keepImages"` 设成 `1`——那样每张图确实只上传一次。
+
+### 为什么是 WebP
+
+在真实截图上实测，同视觉质量下比 JPEG 小 30–45%，照片类内容则大致持平。AVIF 能再小些，但 Anthropic 直接 400 拒绝，而 Pi 会把不认识的格式重写成 PNG——反而更大。压缩是尽力而为的：不支持的格式、失败、或者结果没变小，都保持原字节不动。
+
+## 配置
+
+用 JSON 文件，不用环境变量。两个位置，越靠后优先级越高：
+
+| 路径 | 作用范围 |
+| --- | --- |
+| `<agent-dir>/pi-image-slim.json` | 所有项目（默认为 `~/.pi/agent`） |
+| `.pi/pi-image-slim.json` | 仅当前项目 |
+
+```json
+{
+  "maxEdge": 1280,
+  "quality": 75,
+  "strip": true,
+  "keepImages": 2
+}
+```
+
+| 键 | 默认 | 含义 |
+| --- | --- | --- |
+| `compress` | `true` | 把 PNG/JPEG 重新编码成 WebP |
+| `caption` | `true` | 像素丢掉之前先写一句描述 |
+| `strip` | `true` | 把旧图换成占位符 |
+| `keepImages` | `2` | 保留最近几条带图消息（1–20） |
+| `maxEdge` | `1280` | **较长边**的上限 |
+| `quality` | `75` | WebP 质量，0–100 |
+| `captionTimeoutMs` | `20000` | 超过这么久就退回纯路径；`0` 表示不限时 |
+
+所有键都可选。未知的键和不合法的值会被忽略，文件格式坏了也只是退回默认值，不会弄坏工具结果。改完记得 `/reload`。
+
+### 选一个档位
+
+| `compress` | `strip` | 效果 |
+| --- | --- | --- |
+| `true` | `true` | **默认。** 图片变小，旧的变成文字。 |
+| `true` | `false` | 图片小 6 倍左右，但模型始终能看到全部图片。 |
+| `false` | `true` | 原图尺寸，旧的变成文字。 |
+
+`"strip": false` **完全不影响对话内容**——模型随时能回头看任何一张图——但上行带宽仍然能省大约 84%。拿不定主意时，选这个最稳。
+
+`caption` 只在 `strip` 开着时才有意义：永远不会离开上下文的图，不需要描述，所以那次额外的模型往返会自动跳过。`keepImages` 小于 1 会被忽略——模型总得能看见它刚要求的那张图。
+
+**如果常看小字，把 `maxEdge` 调大** —— 1568 是常见选择。但别超过 2000：超过之后 Pi 自己的图片归一化会把结果重新编码，我们生成的 WebP 就白做了。
+
+**`maxEdge` 量的是较长边**，所以 1200×4000 的手机竖屏截图按高度缩，和宽屏截图按宽度缩是一个道理。
+
+## 关闭
+
+没有 `enabled` 键，也没有环境变量。想关掉就在 Pi 的配置里禁用这个扩展，或者直接卸载——只有一种方式，而不是三种。
+
+## 兼容性
+
+占位符的形状按模型的 API 生成，所以换供应商不会 400：
+
+| API | 形状 |
+| --- | --- |
+| `openai-completions`、`anthropic-messages`、`mistral-conversations`、`pi-messages` | `{ type: "text", text }` |
+| `openai-responses`、`azure-openai-responses`、`openai-codex-responses` | `{ type: "input_text", text }` |
+| `google-generative-ai`、`google-vertex`、`bedrock-converse-stream` | `{ text }` |
+
+这些协议里的图片都能认出来，包括嵌在 `tool_result` 里的。
+
+## 注意事项
+
+- **压缩会永久降低分辨率。** 重新 `read` 也找不回细节——Pi 每次读都会应用同样的缩放。需要看清小字就调大 `maxEdge`。
+- **描述可能是错的。** 一句自信但错误的描述比没有更糟，因为模型会照着它推理。描述由本来就要看这张图的模型当场生成，也没发给任何新的端点，但**没有被验证过**。设 `"caption": false` 可以关掉。
+- **批量返回的图无法重新读取。** 一次调用返回多张图时，Pi 只报一个 `path`，所以它们谁也用不上。描述还在，像素没了。
+- **长任务里旧的图对模型是不可见的。** 窗口为 2 时，十步之前的截图早就变成占位符了。描述还在，像素只差一次 `read`。如果你经常要同时对照很多张图，把 `keepImages` 调大。
+- **描述只生成一次，不会重试。** 如果那次请求超时，占位符就永远是纯路径。调大 `captionTimeoutMs` 可以降低概率。
+- **读一张图会多一次模型往返**，因为描述要在工具结果落盘前生成。图片是一张一张处理的，读十张就是十次往返。
+- **prompt cache 会 miss 一次**，发生在图片被读进来的下一轮。`tools` 和 `system` 层仍然命中，只有 `messages` 失效。
+- **模型可能照描述回答，而不是重新看图。** 做像素级的工作时，直接让它再 `read` 一次那个文件。
+- **轮次边界的判断依赖 Pi 的序列化细节**（那条合成的 `Attached image(s) from tool result:` 消息）。如果未来的 Pi 改了形状，扩展会安全降级：找不到边界，就什么都不剥离。
+- **旧会话不会被追溯处理。** 只有扩展启用期间读进来的图才会被压缩和描述。
+- **会话文件里仍然保留压缩后的图片**，不只是文字。剥离只影响线上传输的部分。
+
+## 开发
+
+```bash
+git clone https://github.com/wiidede/pi-image-slim
+cd pi-image-slim
+pnpm install
+pnpm check       # lint + typecheck + 测试
+pnpm test        # 59 个测试，不联网，不依赖磁盘文件
+```
+
+## License
+
+MIT

package/caption.ts

@@ -0,0 +1,104 @@
+/**
+ * Image descriptions — the "compression" half that keeps meaning instead of pixels.
+ *
+ * Once an image leaves the current turn its bytes are dropped and only a
+ * placeholder remains. A path is an address, not information: the model cannot
+ * answer anything about the picture without spending a tool round trip (and
+ * re-uploading the image) to `read` it again.
+ *
+ * So each image is described once, in the turn it was read, by the same model
+ * that is about to look at it. Nothing leaves for a second endpoint, and a
+ * description costs a few dozen tokens where the image cost thousands.
+ *
+ * There is deliberately no cache and no store here. The caller writes the
+ * description into the transcript as message text, which is where it needs to be
+ * anyway: a side table keyed by image hash would be lost on `/reload` and would
+ * silently degrade every existing placeholder back to a bare path.
+ */
+
+const CAPTION_PROMPT = [
+  'Describe the image for a future reader who can no longer see it.',
+  'One or two sentences, under 40 words. Name the kind of image (screenshot, photo, diagram, chart),',
+  'the main subject, and any text, labels, numbers, colours, or UI state that someone would likely ask about later.',
+  'Do not speculate, do not describe how it was produced, and do not mention that it is an image.',
+].join(' ')
+
+/** The subset of `ExtensionContext` a caption needs, so this stays testable. */
+export interface CaptionContext {
+  model?: { input?: readonly string[] } | undefined
+  signal?: AbortSignal | undefined
+  modelRegistry: {
+    complete: (
+      model: never,
+      context: never,
+      options?: { signal?: AbortSignal },
+    ) => Promise<{ content: readonly { type: string, text?: string }[] }>
+  }
+}
+
+export interface CaptionRequest {
+  model: unknown
+  base64: string
+  mimeType: string
+  /** Abort the request after this many milliseconds. `0` means no limit. */
+  timeoutMs?: number
+}
+
+/**
+ * Combine the caller's signal with a timeout, so an aborted session and an
+ * over-budget request both cancel the model call.
+ */
+function withTimeout(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal | undefined {
+  if (!timeoutMs || timeoutMs <= 0)
+    return signal
+  const timeout = AbortSignal.timeout(timeoutMs)
+  if (!signal)
+    return timeout
+  return AbortSignal.any([signal, timeout])
+}
+
+/**
+ * Ask the current model to describe one image.
+ * Never rejects: a missing description only makes the placeholder less useful.
+ */
+export async function captionImage(ctx: CaptionContext, request: CaptionRequest): Promise<string | undefined> {
+  // A model without image input cannot describe one.
+  if (!ctx.model?.input?.includes('image'))
+    return undefined
+
+  try {
+    const response = await ctx.modelRegistry.complete(
+      request.model as never,
+      {
+        systemPrompt: CAPTION_PROMPT,
+        messages: [
+          {
+            role: 'user',
+            content: [
+              { type: 'image', data: request.base64, mimeType: request.mimeType },
+              { type: 'text', text: 'Describe this image.' },
+            ],
+            timestamp: Date.now(),
+          },
+        ],
+      } as never,
+      {
+        signal: withTimeout(ctx.signal, request.timeoutMs ?? 0),
+      } as never,
+    )
+
+    const text = response.content
+      .filter(part => part.type === 'text' && typeof part.text === 'string')
+      .map(part => part.text!.trim())
+      .filter(Boolean)
+      .join(' ')
+      .replace(/\s+/g, ' ')
+
+    return text || undefined
+  }
+  catch {
+    // Timeout, abort, provider error, malformed response — all mean the same
+    // thing to a caller: fall back to a bare path placeholder.
+    return undefined
+  }
+}