A local-first multi-agent app development platform, built on PenguinHarness
feat(server): images into the chat, generated files back out (#496)
Yaowei Zheng423ab1b3b95d
diff --git a/changelog/unreleased/2026-08-26-messaging-media.md b/changelog/unreleased/2026-08-26-messaging-media.mdnew file mode 100644index 00000000..4921af5e--- /dev/null+++ b/changelog/unreleased/2026-08-26-messaging-media.md@@ -0,0 +1,43 @@+# Pictures into the chat, generated files back out++- **Date:** 2026-08-26+- **Type:** feature+- **Scope:** `server`, `docs`+- **PR:** [#496](https://github.com/Prism-Shadow/penguin-harness/pull/496)++[中文版](2026-08-26-messaging-media.zh.md)++A picture pasted into Feishu or Telegram now reaches the Agent instead of the "text only" notice, and a run's reply is followed into the chat by the files it named. Both directions run over the existing connector seam, so a third channel implements them the same way.++## Inbound images++- An inbound image becomes the same input the web composer submits: the caption (where the channel has one) as user text, then one `image_url` part per image carrying a base64 `data:` URL. A model without vision folds those into scratchpad files exactly as it does for a pasted image.+- A caption counts as the message's text only for an actual PHOTO. Telegram attaches captions to documents, video and audio too, and none of those is delivered — a picture dragged in uncompressed arrives as a `document` — so running the model on the caption alone would have it answer confidently about a file it never received. Those keep getting the not-supported notice. A group's photo caption gets the same `@mention` stripping a text message does.+- Feishu takes the image from the message's `image_key` through `im.v1.messageResource.get`; Telegram takes the largest variant of `message.photo` through `getFile` and the file endpoint, with `message.caption` as the message's text.+- The connector seam carries images as lazily-fetched handles rather than bytes, so a redelivered message is dropped before anything is downloaded, and the size cap rides into the fetch — an oversize transfer is refused at the byte that crosses it instead of being buffered and measured afterwards.+- The ceiling is the server's existing inline-image limit (`INLINE_IMAGE_MAX_BYTES`, 20MB), since these images land in the conversation and the Trace exactly as the composer's do; it also matches Telegram's own 20MB bot download limit.+- In aggregate there is a second bound: a rolling per-binding byte budget (two full-size images per ten minutes). Per image the ceiling was always there; without a budget, anyone who can DM the bot could write a few hundred MB of base64 into one Session's Trace, which is read back whole into a single string on every history page and every resume. The composer reaches that ceiling only through an authenticated user; this path has no authentication at all. The overflow gets its own notice — nothing is wrong with the picture, there have just been too many.+- An image that is too large, one past the budget and one the channel refuses answer with **three different** bilingual notices, and none of them starts a Task — a model asked about a picture it never received would answer confidently about nothing. A refusal the bot's own permissions caused names the scopes and carries the channel's own console link, so it is ten seconds of work rather than a log to go and read: on Feishu, receiving a message and downloading the files in it are separate permissions, and an app can have the first without the second.+- The not-supported notice now names what is supported. Stickers, voice, video and files still get it; inbound files stay out of scope.++## Outbound files++- When a run ends, the files its reply MENTIONED AND THIS RUN PRODUCED follow the text into the chat: path-like tokens that resolve inside the Workspace, exist, and were written at or after the run started, wherever in the reply they appear — so what arrives is the output the Agent pointed at rather than everything the run happened to write. The Web App's file card reads inline code only, which is too strict for a chat, where a reply naming a file in an ordinary sentence would otherwise deliver nothing.+- The modification time is not a nicety, it is what keeps the loose match safe. A reply is steerable by whoever is in the chat, and on a mention-only rule a group member who asks "what's in secrets.json?" gets the file uploaded by the very sentence that declined to paste it — the refusal becomes the disclosure. "Files this run wrote" is also what the feature always claimed to be.+- `./chart.png` and `.eslintrc.json` now resolve. The edge-punctuation trim stripped leading dots along with trailing ones, so the first became an absolute path outside the Workspace and the second a file that is not there — and "saved to ./out/report.pdf" is an entirely ordinary way for a reply to hand something over.+- Images (`.png/.jpg/.jpeg/.gif/.webp`) are sent as pictures so a chart renders in the chat; everything else is sent as a file. The kind is decided by the file the read actually reached, not by the name the reply spelled: an in-Workspace `report.png -> report.pdf` (the everyday "latest" symlink) would otherwise be posted to the image endpoint named `report.pdf`, which Telegram rejects. Feishu uploads to `im.v1.image.create` / `im.v1.file.create` and sends the returned key; Telegram posts `sendPhoto` / `sendDocument` as multipart.+- Path resolution, containment and existence come from the same `WorkspaceFilesService` the Files panel reads through — a path that leaves the Workspace, by `..` or through a symlink, is refused there rather than by a second copy of the rules.+- Caps: at most 5 files per run, at most 10MB per image and 30MB per file — the tighter of each channel's own limits (Feishu 10MB image / 30MB file, Telegram 10MB `sendPhoto` / 50MB `sendDocument`). A file a cap drops is named in the chat; a batch cut short says how many were left behind.+- Every way a mentioned file does not arrive is now said in the chat: over a byte cap, past the count cap, no such file inside the Workspace, or an upload the channel refused — the last of which previously reached `error_records` and nowhere the person in the chat could look, so the feature simply appeared not to work. The one deliberate silence is a file the run did not write: a reply mentioning the config it read is the ordinary case, and announcing every one of those would bury the notices that matter.+- Sends ride the same per-entry chain as the text, so files arrive after the reply that named them and in the order it named them; a failed upload is recorded as an error and does not stop the files behind it.++## Why no Telegram upload ever left the process++- `sendPhoto` / `sendDocument` posted the literal 17 bytes `[object FormData]` as `text/plain`, and the Bot API answered "there is no document in the request". The startup entry replaces `globalThis.fetch` with **undici's** so outbound traffic follows the proxy dispatcher; undici's fetch brand-checks a FormData body against **its own** class, and `new FormData()` is Node's built-in — a different class. The check failed and the body fell through to `String(body)`.+- The transport now imports `fetch` AND `FormData` from undici, as a matched pair, with a comment at the construction site saying why: importing only `FormData` from undici while calling `globalThis.fetch` inverts exactly the same bug. Proxy support is unchanged — undici's fetch resolves the global dispatcher per call, which is the contract `net/proxy.ts` is written against. `Blob` needs no change: `globalThis.Blob` IS node:buffer's Blob, and undici's FormData accepts it.+- It failed 100% in production and 0% in CI, because `installGlobalProxyDispatcher()` runs only in the real server entry — in tests `globalThis.fetch` is still the runtime's own, and that pairing happens to work. So the guard is a test that drives the transport **exactly as production builds it**, points undici's global dispatcher at a local `http.createServer`, and asserts on the bytes that arrive: `multipart/form-data`, a `document` part, the file's name and its contents. Both realm mismatches turn it red.++## Two Feishu failures the adapter could not report++- A refusal to a **streamed** request arrives with the reason inside the response stream, unread: `im.v1.messageResource.get` is fetched as a stream, so on an error axios hands back the stream rather than a parsed `{code, msg}`, and reading it straight off yields "Request failed with status code 400" — the one thing the user cannot act on, hiding the one they can. The body is drained and parsed, and `code`, `msg` and `log_id` are reported the way the ordinary calls already report them.+- Every call this adapter makes now has a deadline. The Lark SDK's default transport is a bare `axios.create()` with no timeout, and every outbound message of a Session goes out on one serial chain — so a request the API accepts and never answers parked every later reply, approval notice and file for that Session, silently, with no error record and no status change, until the binding was toggled or the server restarted. Telegram has had one on both directions since it landed.diff --git a/changelog/unreleased/2026-08-26-messaging-media.zh.md b/changelog/unreleased/2026-08-26-messaging-media.zh.mdnew file mode 100644index 00000000..7f960858--- /dev/null+++ b/changelog/unreleased/2026-08-26-messaging-media.zh.md@@ -0,0 +1,43 @@+# 图片可以发进来,生成的文件可以发出去++- **Date:** 2026-08-26+- **Type:** feature+- **Scope:** `server`, `docs`+- **PR:** [#496](https://github.com/Prism-Shadow/penguin-harness/pull/496)++[English](2026-08-26-messaging-media.md)++粘贴进飞书或 Telegram 的图片现在会真正送达智能体,而不再只收到「仅支持文本」提示;一次运行结束后,回复中点名的文件也会跟着发进会话。两个方向都走既有的渠道连接器接缝,第三个渠道按同样的方式实现即可。++## 入站图片++- 入站图片会转成与网页输入框完全相同的输入:图片说明文字(渠道有的话)作为用户文本,随后每张图片一个 `image_url` 部分,内容为 base64 `data:` URL。不支持视觉的模型会像处理粘贴图片那样把它们折叠成 Scratchpad 文件。+- 只有**图片**消息的说明文字才算作该消息的文本。Telegram 的文件、视频、音频同样带说明文字,而它们的字节并不会送达——把图片以「原图」拖进来就会变成 `document`——仅凭说明文字运行只会让模型对一个它从未收到的文件侃侃而谈。这些类型仍然收到「暂不支持」提示。群聊中图片说明文字里的 `@` 机器人前缀,与文本消息同样会被剥离。+- 飞书通过消息的 `image_key` 调用 `im.v1.messageResource.get` 取图;Telegram 取 `message.photo` 中最大的一档,经 `getFile` 与文件端点下载,并把 `message.caption` 作为该消息的文本。+- 连接器接缝携带的是**延迟拉取的句柄**而非字节:被重复投递的消息在任何下载发生之前就被丢弃;上限也随拉取一起传入——超限的传输在越界的那个字节上就被拒绝,而不是先缓冲下来再测量。+- 上限沿用服务端既有的内联图片上限(`INLINE_IMAGE_MAX_BYTES`,20MB):这些图片与输入框粘贴的图片一样进入对话和 Trace;该数值也正好等于 Telegram 对机器人下载的 20MB 限制。+- 总量上另有一道约束:每个绑定一个滚动窗口的字节预算(十分钟两张满额图片)。单张上限一直都在,但没有总量预算时,任何能私聊机器人的人都可以往一个 Session 的 Trace 里写进几百 MB base64,而该文件在每次翻阅历史、每次恢复 Session 时都会被整体读进单个字符串。网页输入框要达到同一个天花板还得先通过鉴权,这条路径则完全没有鉴权。超出预算的那张有自己的提示语——图片本身没问题,只是短时间内太多了。+- 图片超过单张上限、超出窗口预算与渠道拒绝下载分别回复**三种不同的**双语提示,三种情况都不启动 Task——让模型去回答一张它根本没收到的图片,只会得到一本正经的胡说。因机器人自身权限被拒时,提示会点名所需权限并带上渠道给出的授权链接,于是这件事是十秒钟的操作,而不是一段要去翻的日志:在飞书上,「接收消息」与「读取消息中的资源文件」是两项独立权限,应用完全可能只有前者。+- 「暂不支持」提示改为点明现在支持什么。表情、语音、视频与文件仍收到该提示;入站文件不在本次范围内。++## 出站文件++- 一次运行结束时,回复中**提及且由本次运行产出**的文件会跟在文本之后发进会话:回复中形如路径、能解析到 Workspace 之内、确实存在、且修改时间不早于本次运行开始的片段,出现在回复的任何位置皆可——于是送达的是智能体指出的产物,而不是这次运行顺手写下的全部文件。Web 端「文件卡片」只认行内代码,用在会话里过于严格——把文件名写在普通句子里的回复将一个文件都发不出来。+- 「修改时间」这一条不是锦上添花,而是宽松匹配得以成立的前提。回复的内容可以被会话里的任何人引导,仅凭「提及」判断的话,群成员问一句「secrets.json 里是什么?」,那句「我不会把 secrets.json 贴在这里」本身就会把文件传上去——拒绝即泄露。而且「本次运行写下的文件」本来就是这个功能一直宣称的含义。+- `./chart.png` 与 `.eslintrc.json` 现在能被识别了。此前边缘标点的裁剪把开头的点和结尾的点一并去掉,于是前者变成了 Workspace 之外的绝对路径,后者变成了一个并不存在的文件——而「已保存到 ./out/report.pdf」正是回复交付文件时再普通不过的写法。+- 图片(`.png/.jpg/.jpeg/.gif/.webp`)按图片发送,图表因此能在会话里直接显示;其余按文件发送。类型由**读取时实际拿到的文件名**决定,而不是回复中写下的那个名字:Workspace 内一个 `report.png -> report.pdf` 的符号链接(再常见不过的「最新版」写法)否则会被当作图片发到图片端点,却带着 `report.pdf` 的文件名,Telegram 直接拒收。飞书先上传 `im.v1.image.create` / `im.v1.file.create`,再用返回的 key 发消息;Telegram 以 multipart 调用 `sendPhoto` / `sendDocument`。+- 路径解析、越界检查与存在性判断都取自 Files 面板所用的同一个 `WorkspaceFilesService`——离开 Workspace 的路径(无论经由 `..` 还是符号链接)在那里被拒绝,而不是由桥接层里另一份规则副本来判断。+- 上限:每次运行最多 5 个文件,单张图片最大 10MB、单个文件最大 30MB——取两个渠道各自限制中更紧的一个(飞书图片 10MB / 文件 30MB,Telegram `sendPhoto` 10MB / `sendDocument` 50MB)。被上限拦下的文件会在会话中点名;因数量上限截断时会说明还剩多少个未发送。+- 被提及的文件凡是没送到,现在都会在会话中说明:超过单个上限、超出数量上限、Workspace 内没有该文件、渠道拒绝上传——最后一种此前只写进 `error_records`,而那是会话里的人打不开的地方,于是这个功能看上去就是「不管用」。唯一有意保持沉默的是「本次运行没有写过的文件」:回复里提到自己读过的配置文件属于常态,逐一播报只会把真正要紧的提示淹掉。+- 发送与文本共用同一条按绑定串行的队列,因此文件排在点名它们的那条回复之后,且顺序与回复中出现的顺序一致;上传失败记入错误记录,不会中断其后的文件。++## Telegram 的文件为何一个也没发出去++- `sendPhoto` / `sendDocument` 实际发出的是 17 个字节的字符串 `[object FormData]`,`content-type` 为 `text/plain`,于是 Bot API 回答「there is no document in the request」。启动入口会把 `globalThis.fetch` 换成 **undici 的**,好让出站流量走代理调度器;而 undici 的 fetch 会用**它自己那份** FormData 类去做品牌检查,`new FormData()` 拿到的却是 Node 内置的那一个——两个不同的类。检查失败,请求体便退化成了 `String(body)`。+- 现在 `fetch` 与 `FormData` 都从 undici 导入,成对出现,并在构造处留了注释说明原因:只把 `FormData` 换成 undici 的、却仍调用 `globalThis.fetch`,会原封不动地把同一个 bug 反过来再犯一遍。代理不受影响——undici 的 fetch 每次调用都会解析全局调度器,这正是 `net/proxy.ts` 所依赖的契约。`Blob` 无需改动:`globalThis.Blob` 就是 node:buffer 的 Blob,undici 的 FormData 接受它。+- 这个故障在生产环境 100% 复现、在 CI 中 0% 复现,因为 `installGlobalProxyDispatcher()` 只在真实的服务端入口里执行——测试中 `globalThis.fetch` 仍是运行时自带的那个,而那种搭配恰好能工作。因此这次的防线是一个**按生产方式构造传输层**的测试:把 undici 的全局调度器指向本地 `http.createServer`,然后断言实际到达的字节——`multipart/form-data`、`document` 分段、文件名与文件内容。两种搭配错配都会让它变红。++## 两个飞书适配器此前报不出来的故障++- **流式**请求被拒时,原因藏在没人读过的响应流里:`im.v1.messageResource.get` 以流的方式发起,出错时 axios 交还的是响应流而非解析好的 `{code, msg}`,直接从错误对象上读只能得到「Request failed with status code 400」——恰恰是用户无法据以行动的那一句,把他们能行动的那一句盖住了。现在会把响应体读完并解析,像普通调用一样报出 `code`、`msg` 与 `log_id`。+- 该适配器发出的每一次调用现在都有超时。Lark SDK 默认的传输层是一个不带 `timeout` 的裸 `axios.create()`,而一个 Session 的全部出站消息共用一条串行队列——于是一个被服务端接受却永不作答的请求,会把该 Session 之后的每一条回复、审批提示与文件全部无声地卡住,既没有错误记录也没有状态变化,直到绑定被重新开关或服务器重启为止。Telegram 侧从落地起两个方向就都有超时。diff --git a/packages/docs/content/server-api.en.md b/packages/docs/content/server-api.en.mdindex 5a3de4cc..f820d77b 100644--- a/packages/docs/content/server-api.en.md+++ b/packages/docs/content/server-api.en.md@@ -319,7 +319,7 @@ A Session can be connected to a messaging bot — Feishu, Telegram and QQ are th| POST | /messaging/qq/scan/cancel | `{taskId}` — drop a scan the user walked away from, so its key is forgotten now rather than at the sweep || POST | /messaging/qq/test-message | Send a short fixed text to the last known chat; 409 `qq_no_chat` until the bot has been messaged once in QQ, and 502 `qq_send_failed` when no recent QQ message can be replied to (see below) |-Masked secrets are omitted from responses when none is stored (a cleared config), and a config without a secret cannot be enabled. `linePerMessage` is the one saved field that is not a credential: with it set, every non-blank line of a relayed assistant reply is sent as its own message (blank lines dropped, each line still chunked under the size cap, and the remainder combined into one last message past a per-reply message cap); it defaults to false, an omitted value on a PUT keeps the stored one, and it never applies to the notices or the test message. The one cross-Session rule is per bot account per channel and applies to the connection only: one account has one event stream, so at most one Session may have it enabled. Feishu's account identity is the `app_id`, Telegram's is the numeric bot id in front of the token's colon (robust against token rotation). Reads and the two tests are open to any Project member; PUT, the state toggle and DELETE are owner-only (vault semantics — the binding writes carry or act on the secret). Secrets never round-trip. Deleting the Session removes all its configs, and inbound processing accepts text messages only (other types get a bilingual "text only" reply). Telegram connects by draining the backlog first: messages sent while no connection existed are skipped, matching Feishu, where missed events are simply gone. A binding's runtime status additionally reports what the live connection has SEEN — `lastInboundAt` (when a message last arrived; absent while none has since this connection opened), `lastDeliveryError` (`{at, stage, detail}`, where `stage` is `inbound` when the message arrived and its Task never started, or `send` when a reply never reached the chat, and which no later success clears) and `lastConnectionError` (`{at, detail}` for the last connection failure, kept after the connection recovers — unlike `lastError`, which belongs to the `error` state and is gone the moment the state leaves it). All three are in-process and reset on every (re)connect — a re-enable or a credential save opens a new one — so an absent `lastInboundAt` means "nothing since this connection opened", never "nothing ever". They exist because a channel that withholds messages produces `connected` with no error at all.+Masked secrets are omitted from responses when none is stored (a cleared config), and a config without a secret cannot be enabled. `linePerMessage` is the one saved field that is not a credential: with it set, every non-blank line of a relayed assistant reply is sent as its own message (blank lines dropped, each line still chunked under the size cap, and the remainder combined into one last message past a per-reply message cap); it defaults to false, an omitted value on a PUT keeps the stored one, and it never applies to the notices or the test message. The one cross-Session rule is per bot account per channel and applies to the connection only: one account has one event stream, so at most one Session may have it enabled. Feishu's account identity is the `app_id`, Telegram's is the numeric bot id in front of the token's colon (robust against token rotation). Reads and the two tests are open to any Project member; PUT, the state toggle and DELETE are owner-only (vault semantics — the binding writes carry or act on the secret). Secrets never round-trip. Deleting the Session removes all its configs. Inbound processing accepts text and images: an image becomes an ordinary `image_url` input part (a PHOTO's caption is that message's text; a caption on any other media kind is not, since its bytes are never delivered and running the model on the caption alone answers about a file it never received), capped at the server's inline-image ceiling per image and by a rolling per-binding byte budget in aggregate — an inline image is written verbatim into the Trace, and this path, unlike the composer, has no authentication in front of it. An image over the ceiling, one past the budget and one the channel refuses answer with three different bilingual notices, and none of them runs half a message; a refusal the bot's own permissions caused names the scopes to grant and carries the channel's console link, which for Feishu is the usual case (receiving messages and downloading their attachments are separate scopes). Every other type still gets the bilingual "not supported" reply. Outbound, a finished run's reply is followed by the files it MENTIONED AND PRODUCED — path-like tokens that resolve inside the Workspace, exist, and were written at or after the run started, wherever in the reply they appear (the mention picks which output was the point; the mtime is what keeps a steerable reply from becoming a read primitive, since a reply that declines to paste a file still names it) — images as images and everything else as attachments, classified by the file the read actually reached rather than by the name the reply spelled, at most 5 per run and at most 10MB per image / 30MB per file (the tighter of each channel's own limits). Every way a mentioned file does not arrive is said in the chat — over a cap, past the count cap, no such file in the Workspace, or an upload the channel refused — except a file the run did not write, which is dropped silently because a reply naming the config it read is the ordinary case. Telegram connects by draining the backlog first: messages sent while no connection existed are skipped, matching Feishu, where missed events are simply gone. A binding's runtime status additionally reports what the live connection has SEEN — `lastInboundAt` (when a message last arrived; absent while none has since this connection opened), `lastDeliveryError` (`{at, stage, detail}`, where `stage` is `inbound` when the message arrived and its Task never started, or `send` when a reply never reached the chat, and which no later success clears) and `lastConnectionError` (`{at, detail}` for the last connection failure, kept after the connection recovers — unlike `lastError`, which belongs to the `error` state and is gone the moment the state leaves it). All three are in-process and reset on every (re)connect — a re-enable or a credential save opens a new one — so an absent `lastInboundAt` means "nothing since this connection opened", never "nothing ever". They exist because a channel that withholds messages produces `connected` with no error at all.**QQ is a reply-only channel, and it changes what delivery means.** The platform accepts no push this product may use: every outbound message is a *passive reply* carrying the `msg_id` of an inbound one, valid for a few minutes and capped at 4 replies per message in a single chat (5 in a group). Three consequences are visible through this API. A run that completes more assistant messages than the budget allows has them **coalesced** — the first `budget - 1` go out as they complete and the rest arrive combined in one final message, so nothing is dropped. `linePerMessage` is **clamped to that budget** rather than to the channel-neutral cap of 20. And a send with nothing to reply to — a turn started in the web app, or any reply after the window closed — is **refused rather than pushed**, surfacing as 502 `qq_send_failed` on the test endpoint and as one `messaging_send_failed` error record for a relayed reply. QQ's account identity is the App ID. Outbound files are refused on this channel: the platform's rich-media path requires a publicly reachable URL for the bytes.diff --git a/packages/docs/content/server-api.zh.md b/packages/docs/content/server-api.zh.mdindex 44ee8275..398ca192 100644--- a/packages/docs/content/server-api.zh.md+++ b/packages/docs/content/server-api.zh.md@@ -318,7 +318,7 @@ Session 可以接入消息软件机器人——目前的渠道是飞书、Telegr| POST | /messaging/qq/scan/cancel | `{taskId}`——用户中途离开时丢弃该任务,立即忘记其密钥,而不是等待过期清扫 || POST | /messaging/qq/test-message | 向最近一次收到消息的会话发送一条固定测试文本;在 QQ 里给机器人发过消息之前返回 409 `qq_no_chat`;没有可回复的近期消息时返回 502 `qq_send_failed`(见下) |-没有已存密钥的配置(被清除过的)不返回掩码字段,也无法启用。`linePerMessage` 是唯一一个不属于凭据的已存字段:开启后,转发的助手回复中每个非空行各自作为一条消息发出(空行忽略,单行仍按长度上限分段,超出每条回复的消息条数上限的部分合并为最后一条);默认为 false,PUT 省略该字段则保持已存值,且它不作用于通知与测试消息。唯一的跨 Session 规则按渠道内机器人账号计,且只作用于连接:一个账号只有一条事件流,因此至多一个 Session 能将其启用。飞书的账号身份是 `app_id`,Telegram 是 Token 冒号前的数字机器人 id(换发 Token 也不会改变)。读取与两个测试接口对任意 Project 成员开放;PUT、state 开关与 DELETE 仅限所有者(与 Vault 同口径——绑定写操作携带或作用于密钥)。密钥永不回传。删除 Session 会连带删除其全部渠道配置;入站仅处理文本消息(其他类型收到双语的“仅支持文本”回复)。Telegram 建立连接时先清空积压:无连接期间发来的消息会被跳过,与飞书“错过的事件即消失”同口径。绑定的运行时状态另外报出该连接**实际见到**的情况——`lastInboundAt`(最近一条消息到达的时间;自本次连接建立以来还没有收到过时该字段缺席)、`lastDeliveryError`(`{at, stage, detail}`,`stage` 为 `inbound` 表示消息已到达但其 Task 没能开始,为 `send` 表示回复没能送达聊天;后续的成功不会把它清掉),以及 `lastConnectionError`(`{at, detail}`,最近一次连接失败,并在连接恢复之后依然保留——不同于属于 `error` 状态、状态一离开就被抹掉的 `lastError`)。三者都只存在于进程内,且每次(重新)建立连接都会清空——重新启用连接或再保存一次凭证,都会开启一条新连接——所以 `lastInboundAt` 缺席只意味着「本次连接以来没有收到过」,而不是「从来没有收到过」。它们的存在是因为一个扣着消息不投递的渠道,表现出来正是 `connected` 且毫无报错。+没有已存密钥的配置(被清除过的)不返回掩码字段,也无法启用。`linePerMessage` 是唯一一个不属于凭据的已存字段:开启后,转发的助手回复中每个非空行各自作为一条消息发出(空行忽略,单行仍按长度上限分段,超出每条回复的消息条数上限的部分合并为最后一条);默认为 false,PUT 省略该字段则保持已存值,且它不作用于通知与测试消息。唯一的跨 Session 规则按渠道内机器人账号计,且只作用于连接:一个账号只有一条事件流,因此至多一个 Session 能将其启用。飞书的账号身份是 `app_id`,Telegram 是 Token 冒号前的数字机器人 id(换发 Token 也不会改变)。读取与两个测试接口对任意 Project 成员开放;PUT、state 开关与 DELETE 仅限所有者(与 Vault 同口径——绑定写操作携带或作用于密钥)。密钥永不回传。删除 Session 会连带删除其全部渠道配置。入站处理文本与图片:图片按普通 `image_url` 输入部分送入(**图片**消息的说明文字即该消息的文本;其他媒体类型的说明文字不是——其字节并不会送达,仅凭说明文字运行只会让模型对一个它从未收到的文件侃侃而谈),单张受服务端的内联图片上限约束,总量再受每个绑定一个滚动窗口的字节预算约束——内联图片会原样写入 Trace,而这条路径不像网页输入框,前面没有任何鉴权。超过单张上限、超出窗口预算与渠道拒绝下载分别回复三种不同的双语提示,且都不会把半条消息交给模型;因机器人自身权限被拒时,提示会点名所需权限并带上渠道给出的授权链接——飞书通常正是此种情况(接收消息与下载其中的附件是两项独立权限)。其余类型仍收到双语的“暂不支持”回复。出站方向,一次运行结束后会在回复文本之后发送该回复**提及且由本次运行产出**的文件——回复中形如路径、能解析到 Workspace 之内、确实存在、且修改时间不早于本次运行开始的片段,出现在回复的任何位置皆可(「提及」挑出这次真正要交付的那个产物;「修改时间」则确保一条可被会话中任何人引导的回复不会变成读取原语——拒绝粘贴某个文件的回复同样会点到它的名字)——图片按图片发送、其余按文件发送,且按**读取时实际拿到的文件名**分类,而非回复中写下的那个名字;每次运行最多 5 个,单个图片上限 10MB、单个文件上限 30MB(取两个渠道各自限制中更紧的一个)。被提及的文件凡是没送到,都会在会话中说明原因——超过上限、超出数量上限、Workspace 内没有该文件、渠道拒绝上传——唯独「本次运行没有写过」是静默跳过的,因为回复中提到自己读过的配置文件属于常态。Telegram 建立连接时先清空积压:无连接期间发来的消息会被跳过,与飞书“错过的事件即消失”同口径。绑定的运行时状态另外报出该连接**实际见到**的情况——`lastInboundAt`(最近一条消息到达的时间;自本次连接建立以来还没有收到过时该字段缺席)、`lastDeliveryError`(`{at, stage, detail}`,`stage` 为 `inbound` 表示消息已到达但其 Task 没能开始,为 `send` 表示回复没能送达聊天;后续的成功不会把它清掉),以及 `lastConnectionError`(`{at, detail}`,最近一次连接失败,并在连接恢复之后依然保留——不同于属于 `error` 状态、状态一离开就被抹掉的 `lastError`)。三者都只存在于进程内,且每次(重新)建立连接都会清空——重新启用连接或再保存一次凭证,都会开启一条新连接——所以 `lastInboundAt` 缺席只意味着「本次连接以来没有收到过」,而不是「从来没有收到过」。它们的存在是因为一个扣着消息不投递的渠道,表现出来正是 `connected` 且毫无报错。**QQ 是只能被动回复的渠道,这改变了「送达」的含义。** 平台不提供本产品可用的主动推送:每一条外发消息都是携带入站 `msg_id` 的*被动回复*,有效期只有几分钟,且单聊对同一条消息最多 4 条回复(群聊 5 条)。由此有三点在 API 上可见。一次运行完成的助手消息超过该额度时会被**合并**——前 `budget - 1` 条随完成即时发出,其余合并为最后一条送达,内容不丢。`linePerMessage` 的拆分上限**收敛到该额度**,而不是渠道无关的 20。而没有可回复对象的发送——在网页端发起的对话,或窗口关闭之后的回复——会被**拒绝而非主动推送**:测试接口上表现为 502 `qq_send_failed`,转发回复则记为一条 `messaging_send_failed` 错误记录。QQ 的账号身份是 App ID。该渠道拒绝外发文件:平台的富媒体接口要求为文件提供公网可达地址。diff --git a/packages/server/src/app.ts b/packages/server/src/app.tsindex d1bfb1dc..948f0f1b 100644--- a/packages/server/src/app.ts+++ b/packages/server/src/app.ts@@ -228,6 +228,8 @@ export interface BuildDepsOverrides {qqTailFlushMs?: number;/** Test hook: the bridge's pace between a per-line reply's messages (tests collapse it to zero). */messagingLineDelayMs?: number;+ /** Test hook: one binding's inbound image budget, so a budget test needs no 20MB buffers. */+ messagingInboundImageBudgetBytes?: number;/** Test double: the QQ scan-to-connect transport (avoids real q.qq.com requests). */qqScanTransport?: QQScanTransport;/**@@ -760,6 +762,9 @@ export function buildAppDeps(const messaging = new MessagingBridge({repo: messagingRepo,sessions: sessionsRepo,+ // The same service the Files panel reads through: mirroring a file the reply mentions+ // must obey exactly the containment rules browsing it does, not a second copy of them.+ files: workspaceFiles,channels,runner: manager,connectors: [@@ -779,6 +784,9 @@ export function buildAppDeps(...(overrides.messagingLineDelayMs !== undefined? { lineDelayMs: overrides.messagingLineDelayMs }: {}),+ ...(overrides.messagingInboundImageBudgetBytes !== undefined+ ? { inboundImageBudgetBytes: overrides.messagingInboundImageBudgetBytes }+ : {}),});// Scan-to-connect holds one AES key per in-flight bind task, in memory only: it decrypts// an App Secret, and a task lives for the couple of minutes a person spends scanning.diff --git a/packages/server/src/runtime/messaging/bridge.ts b/packages/server/src/runtime/messaging/bridge.tsindex bb6eda43..e4a4f0f1 100644--- a/packages/server/src/runtime/messaging/bridge.ts+++ b/packages/server/src/runtime/messaging/bridge.ts@@ -18,9 +18,13 @@* Task on the bound Session as an ordinary user input — exactly as if typed into the web* composer, no marker block and no special sender (the model deliberately does not learn* where the message came from) — with `queueIfBusy`: a busy Session queues it as a- * follow-up, never 409. Any non-text message gets a polite bilingual "text only" reply.- * Only once that work is done is the binding row's watermark advanced, so a process that- * dies mid-message has the channel replay it rather than find it already marked.+ * follow-up, never 409. A message carrying images becomes that same composer input with+ * the pictures attached: the caption's text (when there is one) plus one `image_url` part+ * per image, as a base64 `data:` URL, which is byte for byte the shape the web composer+ * submits. Anything else (sticker, voice, video, file) gets a polite bilingual "not+ * supported" reply. Only once that work is done is the binding row's watermark advanced,+ * so a process that dies mid-message has the channel replay it rather than find it already+ * marked.** Outbound (Session → channel): the bridge subscribes to the Session's in-process channel* and relays each of the main conversation's completed assistant messages on its own, the@@ -42,22 +46,33 @@* reply. An `approval_request` additionally sends a one-line notice that a tool call is* waiting in the web UI — on the same chain, so it lands between replies instead of inside* one.+ *+ * When the run ends, the files its reply MENTIONED follow the text into the chat (see+ * reply-files.ts): path-like tokens that resolve inside the Workspace and actually exist,+ * pictures sent as pictures and everything else as attachments. Not "every file the run+ * wrote": the Agent's own words are what say which output was the point, and a chat window+ * is a bad place to receive a directory. What the caps drop is named in the chat rather+ * than dropped quietly.*/-import { userText } from "@prismshadow/penguin-core";+import { imageUrlMessage, userText } from "@prismshadow/penguin-core";import type { OmniMessage } from "@prismshadow/penguin-core";import type { MessagingDeliveryError, MessagingRuntimeStatus } from "../../api/types.js";import type {MessagingBindingRow,MessagingBindingsRepo,} from "../../db/repos/messaging-bindings.js";+import { INLINE_IMAGE_MAX_BYTES } from "../../services/attachment-limits.js";import type { ChannelEvent, ChannelHub } from "../channel.js";import type { ErrorSink } from "../error-recorder.js";import type {MessagingChannelConnector,MessagingClient,+ MessagingInboundImage,MessagingInboundMessage,MessagingSendNote,} from "./connector.js";+import { MessagingMediaTooLargeError, MessagingPermissionError, isImageFileName } from "./media.js";+import { replyFileMentions } from "./reply-files.js";/*** Max characters per outbound text message, shared by every channel: it must sit under@@ -102,16 +117,210 @@ export const MESSAGING_MAX_LINE_MESSAGES = 20;*/export const MESSAGING_LINE_DELAY_MS = 1000;-// The three fixed outbound notices are user-facing chat content, deliberately bilingual+// The fixed outbound notices are user-facing chat content, deliberately bilingual// like the rest of the product's user-facing copy (the server has no locale for an// external chat, so both languages ride each notice).export const MESSAGING_TEXT_ONLY_NOTICE =- "Only text messages are supported for now. 目前仅支持文本消息。";+ "Only text and image messages are supported for now. 目前仅支持文本和图片消息。";+/**+ * The two ways an inbound image does not arrive, deliberately worded as two notices.+ *+ * One notice covering both ("too large, or the download failed") was the first version, and+ * it cost us: a Feishu app that had never been granted the resource-read scope refused+ * every image, and the report that came back was indistinguishable from a size complaint.+ * A message that names two causes names neither.+ */+export function messagingImageTooLargeNotice(): string {+ const mb = Math.floor(INLINE_IMAGE_MAX_BYTES / (1024 * 1024));+ return `That image is larger than the ${mb}MB limit, so it was not sent to the Agent. Try a smaller one. 该图片超过 ${mb}MB 上限,未发送给智能体,请改用更小的图片。`;+}++/** How much of a channel's own failure reason rides into the chat before it is cut. */+const MESSAGING_NOTICE_REASON_MAX = 200;++/** A channel's own reason, bounded — a chat bubble is not a log line. */+function noticeReason(reason: string): string {+ return reason.length > MESSAGING_NOTICE_REASON_MAX+ ? `${reason.slice(0, MESSAGING_NOTICE_REASON_MAX)}…`+ : reason;+}++/**+ * The actionable half of a permission refusal: the scopes that would satisfy the call, and+ * the channel's own console link to grant them. The link goes on its own line so both+ * clients keep it clickable, and NOTHING else off the channel's error travels with it —+ * the raw SDK error carries the request config, which is where credentials live.+ */+function permissionDetail(scopes: readonly string[], grantUrl: string | null): string {+ const list = scopes.join(", ");+ return grantUrl === null ? list : `${list}\n${grantUrl}`;+}++/**+ * An inbound image this bot's app is not permitted to download.+ *+ * Its own notice rather than a generic failure because it is the one transfer failure the+ * person in the chat can fix, in about ten seconds, provided they are told which permission+ * to grant and where — which the channel says in its refusal (see feishu-sdk's+ * scopeDenialDetail).+ */+export function messagingImagePermissionNotice(+ scopes: readonly string[],+ grantUrl: string | null,+): string {+ return `That image could not be downloaded: this bot's app is missing a permission. Grant it, then send the picture again. 无法下载该图片:机器人应用缺少所需权限,开通后重新发送即可。\n${permissionDetail(scopes, grantUrl)}`;+}++/**+ * An image the channel would not hand over, carrying the channel's OWN reason — "app has no+ * permission to access resource" is a scope to go and grant, and it reads nothing like a+ * timeout. The reason is machine text in parentheses after the bilingual sentence, so the+ * sentence stays readable in both languages whatever the channel says.+ *+ * The reason is safe to show: both adapters guarantee their error text names no URL and no+ * credential (see telegram-api's fetchErrorText — its file endpoint embeds the bot token).+ */+export function messagingImageFailedNotice(reason: string): string {+ return `That image could not be downloaded from the chat, so nothing was sent to the Agent. 无法从会话中下载该图片,未发送给智能体。(${noticeReason(reason)})`;+}++/**+ * Inbound imagery this binding's rolling budget refused (see+ * MESSAGING_INBOUND_IMAGE_BUDGET_BYTES). Deliberately not the size notice: nothing about+ * this picture is wrong, there have just been too many of them, and the fix is to wait+ * rather than to send a smaller one.+ */+export function messagingImageBudgetNotice(): string {+ return "Too many images from this chat just now, so this one was not sent to the Agent. Try again in a few minutes. 该会话短时间内发来的图片过多,本张未发送给智能体,请过几分钟再试。";+}export const MESSAGING_APPROVAL_NOTICE ="A tool call is waiting for your approval in the PenguinHarness web UI. 有工具调用正在等待你在网页端审批。";export const MESSAGING_TEST_MESSAGE ="PenguinHarness test message: this Session's messaging binding works. 测试消息:该会话的消息绑定工作正常。";+/**+ * Per-file ceilings for a mirrored file, and how many of them one run may send.+ *+ * The byte numbers are the tighter of each channel's own limit, because the file is read+ * once for whichever channel this Session happens to be bound to: Feishu accepts an image+ * up to 10MB and a file up to 30MB, Telegram's `sendPhoto` stops at 10MB and its+ * `sendDocument` at 50MB. 10MB for a picture and 30MB for anything else therefore hold+ * everywhere — better than the same reply succeeding on one channel and failing on the+ * other.+ *+ * The count is not anyone's API limit but a judgement about the medium: a reply naming more+ * than a handful of files is reporting on work rather than delivering it, and a chat is the+ * wrong place to receive twenty attachments. The remainder is counted in a notice, never+ * silently dropped — the Web App still has all of them.+ */+export const MESSAGING_OUTBOUND_IMAGE_MAX_BYTES = 10 * 1024 * 1024;+export const MESSAGING_OUTBOUND_FILE_MAX_BYTES = 30 * 1024 * 1024;+export const MESSAGING_OUTBOUND_FILE_MAX_COUNT = 5;++/**+ * How far before a run's start a file may have been written and still count as its output.+ *+ * Not slack in the rule but in the clock: mtime granularity is a filesystem property (one+ * second on HFS+, two on FAT), so a file the run wrote in its first moments can report a+ * timestamp a second or so behind the event that said the run had started. Small enough+ * that a file from an earlier turn never rides along.+ */+const MESSAGING_OUTBOUND_MTIME_GRACE_MS = 2_000;++/** One file a ceiling refused, named so the user knows which one to go and fetch. */+export function messagingFileTooLargeNotice(fileName: string, maxBytes: number): string {+ const mb = Math.floor(maxBytes / (1024 * 1024));+ return `"${fileName}" is over this channel's ${mb}MB limit and was not sent. 文件“${fileName}”超过该渠道 ${mb}MB 的上限,未发送。`;+}++/**+ * One file the channel would not take, with its own reason.+ *+ * Every other way a file does not arrive is named in the chat — over the byte cap, past the+ * count cap, an inbound refusal. A failed upload reached `error_records` and nothing else,+ * which the person in the chat cannot open, so the feature simply looked broken.+ */+export function messagingFileFailedNotice(fileName: string, reason: string): string {+ return `"${fileName}" could not be sent to the chat. 文件“${fileName}”未能发送到会话。(${noticeReason(reason)})`;+}++/** One file this bot's app is not permitted to upload — the fixable half of the above. */+export function messagingFilePermissionNotice(+ fileName: string,+ scopes: readonly string[],+ grantUrl: string | null,+): string {+ return `"${fileName}" could not be sent: this bot's app is missing a permission. 文件“${fileName}”未能发送:机器人应用缺少所需权限。\n${permissionDetail(scopes, grantUrl)}`;+}++/** How many names one drop notice lists before it stops: a signal, not an inventory. */+const MESSAGING_NOTICE_NAMES_MAX = 5;++/**+ * Files the reply named that the Workspace has nothing to send for — a path that resolves+ * outside it, a `~` path, or one that simply is not there.+ *+ * One notice for the batch, quoting the reply's own spelling. The two causes share a+ * sentence because they share the user's next move (look at the path) and share one true+ * statement: there is no such file in this Session's Workspace.+ */+export function messagingFilesMissingNotice(names: readonly string[]): string {+ const shown = names.slice(0, MESSAGING_NOTICE_NAMES_MAX);+ const list = shown.join(", ") + (names.length > shown.length ? ", …" : "");+ return `Named in the reply but not sent — no such file inside this Session's Workspace: ${list}. 回复中提及但未发送——该会话 Workspace 内没有这些文件:${list}。`;+}++/** The tail of a batch the count cap cut off. */+export function messagingFilesSkippedNotice(skipped: number): string {+ return `${skipped} more mentioned file(s) were not sent — at most ${MESSAGING_OUTBOUND_FILE_MAX_COUNT} ride along with one reply. 另有 ${skipped} 个提及的文件未发送——每条回复最多附带 ${MESSAGING_OUTBOUND_FILE_MAX_COUNT} 个。`;+}++/**+ * How many bytes of inbound imagery one binding may hand its Session inside a rolling+ * window, and how long that window is.+ *+ * Per image, the ceiling is the server's inline-image limit. In aggregate there was+ * nothing: every accepted image is written into the conversation as a base64 data URL, and+ * services/attachment-limits.ts says what that costs — the Trace JSONL is read back whole,+ * into a single JS string, on every history page and every Session resume, so a large+ * enough pile of inline images is not a slow Session but one that never recovers. The web+ * composer reaches the same ceiling only through an authenticated user; anyone who can DM+ * the bot reaches this one.+ *+ * A burst bound, not a lifetime one: two full-size images per ten minutes is far above any+ * real conversation (both channels re-encode a chat photo to a fraction of the ceiling) and+ * far below the pile that breaks a Session. Sustained abuse still costs the attacker time+ * they cannot compress.+ */+export const MESSAGING_INBOUND_IMAGE_BUDGET_BYTES = 2 * INLINE_IMAGE_MAX_BYTES;+const MESSAGING_INBOUND_IMAGE_WINDOW_MS = 10 * 60_000;++/**+ * One binding's rolling image budget. A fixed window rather than a sliding one, and a+ * counter rather than a list of transfers: a sliding window has to remember every accepted+ * image, which a thousand one-byte images turn into a thousand entries. The point is a+ * bound; a window that resets on its own is bounded in both bytes and memory.+ */+class InboundImageBudget {+ private windowStart = 0;+ private spent = 0;++ /** Bytes still allowed right now (a window older than the span has already lapsed). */+ remaining(now: number, budget: number): number {+ if (now - this.windowStart > MESSAGING_INBOUND_IMAGE_WINDOW_MS) return budget;+ return Math.max(0, budget - this.spent);+ }++ /** Records bytes actually accepted, opening a new window when the last one has lapsed. */+ spend(now: number, bytes: number): void {+ if (now - this.windowStart > MESSAGING_INBOUND_IMAGE_WINDOW_MS) {+ this.windowStart = now;+ this.spent = 0;+ }+ this.spent += bytes;+ }+}+/*** How many recently processed inbound message ids one binding remembers.*@@ -237,16 +446,43 @@ export interface MessagingTaskRunner {}/**- * Minimal dependency on the sessions index: existence checks for reconcile/cascade, and the- * Session's Project/Agent so a messaging failure can be filed under them (see recordError).+ * Minimal dependency on the sessions index: existence checks for reconcile/cascade, the+ * Session's Project/Agent so a messaging failure can be filed under them (see recordError),+ * and the one field an outbound file needs — the Workspace a mentioned path resolves against.*/export interface MessagingSessionIndex {- findById(sessionId: string): { projectId: string; agentId: string } | null;+ findById(sessionId: string): { projectId: string; agentId: string; workspace: string } | null;+}++/**+ * Minimal dependency on the Workspace file service. Narrow, but deliberately NOT a+ * reimplementation: both methods carry that service's containment rules (a path that leaves+ * the Workspace — by `..`, by an absolute path, or through a symlink — is refused there,+ * and reads happen on the canonical path). A second resolver living in the bridge is+ * exactly the kind of thing that ends up one security fix behind.+ */+export interface MessagingWorkspaceFiles {+ /**+ * The subset of `rels` that exist as regular files inside the Workspace, each with the+ * time it was last written — which is what separates a file this run produced from one+ * the reply merely named (see deliverFiles).+ */+ statExistingWithMtime(+ workspace: string,+ rels: string[],+ ): Promise<{ rel: string; mtimeMs: number }[]>;+ /** Reads a file, at most `maxBytes` of it. */+ read(+ workspace: string,+ rel: string,+ options?: { maxBytes?: number },+ ): Promise<{ data: Buffer; fileName: string }>;}export interface MessagingBridgeDeps {repo: MessagingBindingsRepo;sessions: MessagingSessionIndex;+ files: MessagingWorkspaceFiles;channels: ChannelHub;runner: MessagingTaskRunner;/** One connector per channel; a stored binding whose channel has no connector is skipped with an error record. */@@ -256,6 +492,8 @@ export interface MessagingBridgeDeps {now?: () => number;/** Test hook: the pace between a per-line reply's messages (default MESSAGING_LINE_DELAY_MS; tests collapse it to zero). */lineDelayMs?: number;+ /** Test hook: one binding's inbound image budget (default MESSAGING_INBOUND_IMAGE_BUDGET_BYTES). */+ inboundImageBudgetBytes?: number;}/** One connected (or connecting/errored) binding's in-memory state. */@@ -310,6 +548,17 @@ interface BridgeEntry {inCompaction: boolean;/** The run in progress already threaded its first outbound message onto the inbound one. */threadedThisRun: boolean;+ /**+ * When the run in progress started, as the bridge saw it (0 before it has seen one). The+ * cut-off for "a file this run produced" — see deliverFiles.+ */+ runStartedAt: number;+ /**+ * What this run has relayed so far, joined at the run's end to find the files the reply+ * mentions. Only text that actually mirrored is collected: a connection joined mid-run+ * relays none of that run's messages and must not send its files either.+ */+ replyText: string[];/*** Tail of this entry's outbound sends. Every relayed message AND every notice is appended* rather than started on its own, so outbound traffic completing in quick succession cannot@@ -340,16 +589,21 @@ export class MessagingBridge {* replay to catch.*/private readonly recentInbound = new Map<string, RecentInboundIds>();+ /** Inbound image budgets, keyed like recentInbound: per BINDING, surviving a reconnect. */+ private readonly imageBudgets = new Map<string, InboundImageBudget>();private readonly connectors: ReadonlyMap<string, MessagingChannelConnector>;private readonly now: () => number;private readonly log: (line: string) => void;private readonly lineDelayMs: number;+ private readonly inboundImageBudgetBytes: number;constructor(private readonly deps: MessagingBridgeDeps) {this.connectors = new Map(deps.connectors.map((c) => [c.channel, c]));this.now = deps.now ?? (() => Date.now());this.log = deps.log ?? (() => {});this.lineDelayMs = deps.lineDelayMs ?? MESSAGING_LINE_DELAY_MS;+ this.inboundImageBudgetBytes =+ deps.inboundImageBudgetBytes ?? MESSAGING_INBOUND_IMAGE_BUDGET_BYTES;}/**@@ -506,6 +760,8 @@ export class MessagingBridge {armed: runState === "idle",inCompaction: false,threadedThisRun: false,+ runStartedAt: 0,+ replyText: [],sendChain: Promise.resolve(),};this.entries.set(row.sessionId, entry);@@ -692,15 +948,36 @@ export class MessagingBridge {// off the row.this.deps.repo.recordChat(entry.sessionId, entry.channel, msg.chatId, isDirect);entry.lastInboundMessageId = isDirect ? null : msg.messageId;- if (msg.text === null || msg.text.trim() === "") {- await this.replyInbound(entry, msg, MESSAGING_TEXT_ONLY_NOTICE);+ // A caption is this message's text; an image with none carries no text at all.+ const text = msg.text !== null && msg.text.trim() !== "" ? msg.text : null;+ const images = msg.images ?? [];+ if (images.length === 0) {+ if (text === null) {+ await this.replyInbound(entry, msg, MESSAGING_TEXT_ONLY_NOTICE);+ } else {+ // An ordinary user input, exactly as if typed into the web composer: no marker+ // block, no special sender — the model deliberately does not learn the message+ // arrived through a messaging channel.+ await this.deps.runner.startTask(entry.sessionId, [userText(text)], {+ queueIfBusy: true,+ });+ }} else {- // An ordinary user input, exactly as if typed into the web composer: no marker- // block, no special sender — the model deliberately does not learn the message- // arrived through a messaging channel.- await this.deps.runner.startTask(entry.sessionId, [userText(msg.text)], {- queueIfBusy: true,- });+ const result = await this.inboundImageParts(entry, images);+ if ("notice" in result) {+ // The whole message stops here rather than running on the caption alone: a model+ // asked "what is wrong with this?" about a picture it never received answers+ // confidently about nothing, which is worse than a notice saying so.+ await this.replyInbound(entry, msg, result.notice);+ } else {+ // Text first, then the images — the same order and the same parts the web composer+ // submits, so a chat message with a picture is indistinguishable from a pasted one.+ await this.deps.runner.startTask(+ entry.sessionId,+ [...(text === null ? [] : [userText(text)]), ...result.parts],+ { queueIfBusy: true },+ );+ }}// The durable watermark goes LAST, and its own UPDATE is the price of that. What it// marks is a message this process finished with: the follow-up a busy Session queues@@ -721,6 +998,75 @@ export class MessagingBridge {}}+ /**+ * Downloads the message's images into `image_url` input parts, or the notice to answer+ * with when one of them could not be delivered.+ *+ * All-or-nothing on purpose: a message is one thing the user sent, and half of it+ * reaching the Agent is not a partial success but a misleading one. The cap is the+ * server's inline-image ceiling — the same number the web composer's uploads answer to,+ * because these images land in exactly the same place (the conversation, and from there+ * the Trace, which is read back whole on every resume). It happens to match Telegram's+ * own 20MB download ceiling for bots.+ *+ * A refusal for size is the user's to fix and is not an error record — they sent+ * something too big and the chat says so. A failure is somebody's fault (a scope the bot+ * was never granted, most likely) and lands in the error log with the channel's reason,+ * so it is diagnosable from the dashboard and not only from a chat bubble.+ */+ private async inboundImageParts(+ entry: BridgeEntry,+ images: readonly MessagingInboundImage[],+ ): Promise<{ parts: OmniMessage[] } | { notice: string }> {+ const budget = this.imageBudgetFor(entry);+ const parts: OmniMessage[] = [];+ for (const image of images) {+ const remaining = budget.remaining(this.now(), this.inboundImageBudgetBytes);+ if (remaining <= 0) return { notice: messagingImageBudgetNotice() };+ // The window's remainder rides into the fetch exactly as the ceiling does, so an+ // image that would overspend is refused at the byte that crosses rather than+ // buffered whole and measured afterwards.+ const cap = Math.min(INLINE_IMAGE_MAX_BYTES, remaining);+ try {+ const { data, mimeType } = await image.fetch(cap);+ budget.spend(this.now(), data.length);+ parts.push(imageUrlMessage(`data:${mimeType};base64,${data.toString("base64")}`));+ } catch (err) {+ const reason = err instanceof Error ? err.message : String(err);+ this.log(`[messaging] ${entry.channel} image fetch failed: ${reason}`);+ if (err instanceof MessagingMediaTooLargeError) {+ // Which ceiling stopped it decides what the chat is told: the server's limit is+ // fixed by sending a smaller picture, the window's budget only by waiting.+ return {+ notice:+ cap < INLINE_IMAGE_MAX_BYTES+ ? messagingImageBudgetNotice()+ : messagingImageTooLargeNotice(),+ };+ }+ this.recordError(entry.sessionId, err, "messaging_image_fetch_failed");+ return {+ notice:+ err instanceof MessagingPermissionError+ ? messagingImagePermissionNotice(err.scopes, err.grantUrl)+ : messagingImageFailedNotice(reason),+ };+ }+ }+ return { parts };+ }++ /** This binding's rolling image budget, created on first use (see InboundImageBudget). */+ private imageBudgetFor(entry: BridgeEntry): InboundImageBudget {+ const key = inboundKey(entry.sessionId, entry.channel);+ let budget = this.imageBudgets.get(key);+ if (budget === undefined) {+ budget = new InboundImageBudget();+ this.imageBudgets.set(key, budget);+ }+ return budget;+ }+/** Reply to the inbound message itself: threaded reply in groups, plain send in direct chats. */private async replyInbound(entry: BridgeEntry,@@ -789,6 +1135,7 @@ export class MessagingBridge {if (!entry.armed) return; // joined mid-run: this run's messages are not a replyconst body = text.trim();if (body === "") return;+ entry.replyText.push(body);entry.sendChain = entry.sendChain.then(() => this.deliverReply(entry, body));}@@ -797,10 +1144,24 @@ export class MessagingBridge {// A fresh run observed from its start gets one thread reply again. Only a real// idle -> running edge counts: task_state is re-published mid-run for queue and// steering changes, and re-arming there would thread every message of the run.- if (entry.active !== "running") entry.threadedThisRun = false;+ if (entry.active !== "running") {+ entry.threadedThisRun = false;+ // The cut-off the run's own output is judged against. Taken on the same edge, so a+ // task_state republished mid-run cannot move it forward past files already written.+ entry.runStartedAt = this.now();+ }} else if (state === "idle") {// A run joined midway ends here; from the next one on its messages mirror.entry.armed = true;+ // The run's files ride behind its text on the same chain — the reply first, then what+ // it produced. Taken and cleared here, so a task_state republished at idle cannot+ // send the same batch twice and the next run starts from nothing.+ const replyText = entry.replyText.join("\n\n");+ const since = entry.runStartedAt;+ entry.replyText = [];+ if (replyText !== "") {+ entry.sendChain = entry.sendChain.then(() => this.deliverFiles(entry, replyText, since));+ }}entry.active = state;}@@ -859,6 +1220,130 @@ export class MessagingBridge {}}+ /**+ * Sends the files THIS RUN produced and its reply mentioned, after its text.+ *+ * Two filters, and both are load-bearing. The reply having said the name is what picks+ * the one output that was the point out of the dozen a run writes. The file being newer+ * than the run's start is what keeps that from becoming an exfiltration primitive: the+ * reply is steerable by whoever is in the chat, and on a mention-only rule a group member+ * who asks "what is in secrets.json?" gets the file uploaded by the very refusal that+ * declined to paste it. Containment (the Workspace and nothing narrower) lives in the+ * file service either way — see MessagingWorkspaceFiles.+ *+ * A file the run did not write is dropped SILENTLY: a reply that mentions the config it+ * read is the ordinary case, and announcing every one of those would bury the notices+ * that matter. A file that could not be delivered at all is named, because a mention the+ * chat never receives with nothing to say why is how this feature reads as broken.+ *+ * Always plain sends, never a threaded reply: a run that mentions a file has by+ * definition already sent the text that mentions it, and that message took the group's+ * one reply-to. Nothing here throws — a batch that fails is recorded, and a single file+ * that fails does not stop the ones behind it.+ */+ private async deliverFiles(entry: BridgeEntry, replyText: string, since: number): Promise<void> {+ try {+ const row = this.deps.repo.find(entry.sessionId, entry.channel);+ if (!row || row.lastChatId === null) return; // no chat known yet: nothing mirrors+ const session = this.deps.sessions.findById(entry.sessionId);+ if (session === null) return; // deleted mid-run+ const mentions = replyFileMentions(replyText, session.workspace);+ if (mentions.length === 0) return; // the reply named no file at all: nothing to say+ const stats = await this.deps.files.statExistingWithMtime(+ session.workspace,+ mentions.flatMap((m) => (m.rel === null ? [] : [m.rel])),+ );+ const mtimeByRel = new Map(stats.map((f) => [f.rel, f.mtimeMs]));+ const produced: string[] = [];+ const missing: string[] = [];+ for (const mention of mentions) {+ const mtime = mention.rel === null ? undefined : mtimeByRel.get(mention.rel);+ if (mtime === undefined) missing.push(mention.mentioned);+ else if (mtime >= since - MESSAGING_OUTBOUND_MTIME_GRACE_MS) produced.push(mention.rel!);+ }+ if (produced.length === 0 && missing.length === 0) return;+ const client = await this.clientFor(entry.sessionId, row);+ for (const rel of produced.slice(0, MESSAGING_OUTBOUND_FILE_MAX_COUNT)) {+ try {+ await this.deliverOneFile(client, row.lastChatId, session.workspace, rel);+ } catch (err) {+ this.recordError(entry.sessionId, err, "messaging_file_send_failed");+ await this.noteFileFailure(client, row.lastChatId, rel, err);+ }+ }+ const skipped = produced.length - MESSAGING_OUTBOUND_FILE_MAX_COUNT;+ if (skipped > 0) {+ await client.sendText(row.lastChatId, messagingFilesSkippedNotice(skipped));+ }+ if (missing.length > 0) {+ await client.sendText(row.lastChatId, messagingFilesMissingNotice(missing));+ }+ } catch (err) {+ this.recordError(entry.sessionId, err, "messaging_send_failed");+ }+ }++ /**+ * Names one file that did not make it, in the chat.+ *+ * Every other way a file does not arrive is already visible there — over the byte cap,+ * past the count cap, an inbound refusal. A failed upload reached `error_records` alone,+ * which the person in the chat cannot open, so the feature just looked broken. A missing+ * permission gets its own wording: it is the one failure they can fix themselves, in+ * about ten seconds, given the scope name and the console link.+ *+ * Its own try/catch: a chat that will not take the notice must not take the rest of the+ * batch down with it, and the upload failure behind it is already recorded.+ */+ private async noteFileFailure(+ client: MessagingClient,+ chatId: string,+ rel: string,+ err: unknown,+ ): Promise<void> {+ // `rel` is always "/"-joined (see toWorkspaceRelative), so its base name is its tail.+ const fileName = rel.slice(rel.lastIndexOf("/") + 1);+ const text =+ err instanceof MessagingPermissionError+ ? messagingFilePermissionNotice(fileName, err.scopes, err.grantUrl)+ : messagingFileFailedNotice(fileName, err instanceof Error ? err.message : String(err));+ try {+ await client.sendText(chatId, text);+ } catch {+ // A channel that will not take the notice either is one problem, not two.+ }+ }++ /** One mirrored file: read under the outer ceiling, then sent as a picture or an attachment. */+ private async deliverOneFile(+ client: MessagingClient,+ chatId: string,+ workspace: string,+ rel: string,+ ): Promise<void> {+ // Read first, classify second. `rel` is the path the REPLY spelled, and the canonical+ // file behind it may not share its extension: an in-Workspace `report.png -> report.pdf`+ // (the everyday "latest" symlink) classified by the mention would go to the image+ // endpoint under the image ceiling and arrive named report.pdf, which Telegram refuses.+ // The read is bounded by the larger of the two ceilings either way.+ const file = await this.deps.files.read(workspace, rel, {+ // One byte past the ceiling is enough to know the file is over it — reading the whole+ // of a 2GB log to measure it would be the same mistake in the other direction.+ maxBytes: MESSAGING_OUTBOUND_FILE_MAX_BYTES + 1,+ });+ const asImage = isImageFileName(file.fileName);+ const maxBytes = asImage+ ? MESSAGING_OUTBOUND_IMAGE_MAX_BYTES+ : MESSAGING_OUTBOUND_FILE_MAX_BYTES;+ if (file.data.length > maxBytes) {+ await client.sendText(chatId, messagingFileTooLargeNotice(file.fileName, maxBytes));+ return;+ }+ const outbound = { fileName: file.fileName, data: file.data };+ if (asImage) await client.sendImage(chatId, outbound);+ else await client.sendFile(chatId, outbound);+ }+/** One-line notice (approval waiting) to the last known chat; silent before one exists. */private async deliverNotice(entry: BridgeEntry, text: string): Promise<void> {const target = await this.sendTarget(entry);diff --git a/packages/server/src/runtime/messaging/connector.ts b/packages/server/src/runtime/messaging/connector.tsindex bd88651c..af673939 100644--- a/packages/server/src/runtime/messaging/connector.ts+++ b/packages/server/src/runtime/messaging/connector.ts@@ -14,6 +14,36 @@/** Known messaging channels (the DB stores the discriminator as text; unknown values are skipped defensively). */export type MessagingChannel = "feishu" | "telegram" | "qq";+/** One inbound image's bytes, once fetched, with the MIME type the bridge needs for its data URL. */+export interface MessagingInboundImageData {+ data: Buffer;+ /** e.g. `image/png` — the connector's best answer, from the channel's own type or the bytes. */+ mimeType: string;+}++/**+ * An image attached to an inbound message: a handle, not the bytes.+ *+ * The bytes are deliberately NOT eagerly downloaded by the connector. Most of what makes+ * an inbound message uninteresting is decided after the event is normalized — a+ * redelivery is dropped before anything else happens — and a channel that downloaded+ * first would pay a full image transfer for every replay. Fetching lazily also puts the+ * cap where the transfer is: `fetch` refuses anything over `maxBytes` rather than handing+ * the bridge something it would only discard, which is what keeps a 100MB attachment from+ * ever being resident in this process.+ */+export interface MessagingInboundImage {+ /**+ * Downloads the image. Two distinct failures, and the bridge answers them differently:+ * `MessagingMediaTooLargeError` (see media.ts) for anything past `maxBytes`, which the+ * user fixes by sending something smaller, and any other Error — carrying the channel's+ * OWN reason, since a permission the bot lacks and a network blip are not the same+ * problem — for a transfer that could not be made at all. That reason reaches the chat,+ * so a connector must keep credentials out of it (see telegram-api's fetchErrorText).+ */+ fetch(maxBytes: number): Promise<MessagingInboundImageData>;+}+/** One inbound chat message, normalized across channels. */export interface MessagingInboundMessage {/**@@ -38,10 +68,18 @@ export interface MessagingInboundMessage {*/messageId: string;/**- * The message's plain text; null for anything that is not a text message (stickers,- * images, …) — the bridge answers those with the text-only notice.+ * The message's plain text; null for anything that carries none (stickers, voice,+ * files, …) — a message with neither text nor images gets the not-supported notice.+ * An image sent with a caption puts the caption here: the caption IS that message's+ * text, so a channel needs no second field for it and the bridge no second rule.*/text: string | null;+ /**+ * Images attached to this message (absent or empty when there are none). Handles rather+ * than bytes — see MessagingInboundImage. A channel that carries several images in one+ * message lists them in the order the user sees them.+ */+ images?: readonly MessagingInboundImage[];/** Sender display name when the channel's event carries one. */senderName?: string;}@@ -95,6 +133,13 @@ export interface MessagingAccountInfo {*/export type MessagingSendNote = string;+/** One file on its way out to a chat: the bytes, plus the name the chat should show. */+export interface MessagingOutboundFile {+ /** Display name — the base name of the Workspace-relative path the reply mentioned. */+ fileName: string;+ data: Buffer;+}+/** Outbound half of one bound account. Every method throws on failure with a readable reason. */export interface MessagingClient {/** Credential check (used by the test endpoint); resolving means the config signs in. */@@ -103,6 +148,14 @@ export interface MessagingClient {sendText(chatId: string, text: string): Promise<MessagingSendNote | void>;/** Replies a text message to a specific inbound message (threads correctly in group chats). */replyText(messageId: string, text: string): Promise<MessagingSendNote | void>;+ /**+ * Sends a picture into a chat, so a chart the Agent drew arrives as something the reader+ * can see rather than as a download. Channels that need an upload step first do it here —+ * the bridge holds bytes and a name, never a channel's file handle.+ */+ sendImage(chatId: string, file: MessagingOutboundFile): Promise<void>;+ /** Sends any other file into a chat as an attachment. */+ sendFile(chatId: string, file: MessagingOutboundFile): Promise<void>;}export interface MessagingChannelConnector {diff --git a/packages/server/src/runtime/messaging/feishu-connector.ts b/packages/server/src/runtime/messaging/feishu-connector.tsindex 6f2453ed..b8e05d76 100644--- a/packages/server/src/runtime/messaging/feishu-connector.ts+++ b/packages/server/src/runtime/messaging/feishu-connector.ts@@ -4,16 +4,18 @@* everything Feishu-specific: the config document's shape, the SDK adapter behind it* (injectable for tests — see feishu-sdk.ts), and the reduction of* `im.message.receive_v1` events to the bridge's normalized inbound shape (text extracted- * from the content JSON and its mention placeholders resolved — see resolveFeishuMentions;- * anything non-text reads as `text: null`).+ * from the content JSON and its mention placeholders resolved — see resolveFeishuMentions,+ * an `image` message's `image_key` turned into a lazy download handle; anything else+ * reads as neither text nor image).*/import type {MessagingChannelConnector,MessagingClient,MessagingConnection,MessagingConnectorHandlers,+ MessagingInboundImage,} from "./connector.js";-import type { FeishuCredentials, FeishuMention, FeishuSdk } from "./feishu-sdk.js";+import type { FeishuApiClient, FeishuCredentials, FeishuMention, FeishuSdk } from "./feishu-sdk.js";/** Default Feishu open-platform domain (Lark tenants override it in the form). */export const FEISHU_DEFAULT_DOMAIN = "https://open.feishu.cn";@@ -122,6 +124,18 @@ export function resolveFeishuMentions(return out.trim();}+/** The `image_key` of an image message's content JSON (null when unparseable). */+function imageKeyOfContent(content: string): string | null {+ try {+ const parsed = JSON.parse(content) as { image_key?: unknown };+ return typeof parsed.image_key === "string" && parsed.image_key !== ""+ ? parsed.image_key+ : null;+ } catch {+ return null;+ }+}+export class FeishuConnector implements MessagingChannelConnector {readonly channel = "feishu" as const;@@ -141,6 +155,11 @@ export class FeishuConnector implements MessagingChannelConnector {handlers: MessagingConnectorHandlers,): Promise<MessagingConnection> {const creds = this.credsOf(config);+ // One OpenAPI client per connection, shared by the identity lookup below and by every+ // inbound image's download — the event stream itself uses neither. It is built lazily so+ // that loading the SDK stays off the paths that never need it.+ let apiClient: Promise<FeishuApiClient> | null = null;+ const api = (): Promise<FeishuApiClient> => (apiClient ??= this.sdk.createClient(creds));/*** This bot's own open id: which mention in a group message is its own never changes while* the credentials do not, so one lookup per connection serves every inbound message.@@ -153,8 +172,7 @@ export class FeishuConnector implements MessagingChannelConnector {// identity the same way, from inside its poll loop. Until the answer lands, a mention of// this bot is named rather than dropped — the same degraded mode an app that cannot report// an identity at all already lives in.- void this.sdk- .createClient(creds)+ void api().then((client) => client.botOpenId()).then((id) => {botOpenId = id;@@ -166,14 +184,30 @@ export class FeishuConnector implements MessagingChannelConnector {});return this.sdk.connect(creds, {onMessage: (evt) => {- // Only `text` messages carry text; every other message type normalizes to null- // (the bridge answers those with the text-only notice).+ // Only `text` messages carry text — a Feishu image message has no caption field of+ // its own; every other message type normalizes to null (the bridge answers those+ // with the not-supported notice).const raw = evt.messageType === "text" ? textOfContent(evt.content) : null;+ const imageKey = evt.messageType === "image" ? imageKeyOfContent(evt.content) : null;+ const images: MessagingInboundImage[] =+ imageKey === null+ ? []+ : [+ {+ fetch: async (maxBytes) =>+ (await api()).fetchMessageImage({+ messageId: evt.messageId,+ fileKey: imageKey,+ maxBytes,+ }),+ },+ ];return handlers.onMessage({chatId: evt.chatId,chatKind: evt.chatType === "p2p" ? "direct" : "group",messageId: evt.messageId,text: raw === null ? null : resolveFeishuMentions(raw, evt.mentions, botOpenId),+ ...(images.length > 0 ? { images } : {}),...(evt.senderName !== undefined ? { senderName: evt.senderName } : {}),});},diff --git a/packages/server/src/runtime/messaging/feishu-sdk.ts b/packages/server/src/runtime/messaging/feishu-sdk.tsindex 131ad286..6bebb99d 100644--- a/packages/server/src/runtime/messaging/feishu-sdk.ts+++ b/packages/server/src/runtime/messaging/feishu-sdk.ts@@ -9,6 +9,12 @@* which would tax every typecheck for the handful of calls made here; the local interfaces* below are the contract, and the adapter casts the loaded module once.*/+import {+ MessagingMediaTooLargeError,+ MessagingPermissionError,+ collectUnderCap,+ sniffImageMime,+} from "./media.js";/** One credential set (a binding's stored values, or a test request's draft). */export interface FeishuCredentials {@@ -49,7 +55,24 @@ export interface FeishuInboundEvent {mentions?: FeishuMention[];}-/** OpenAPI half of the seam: credential probe + text sends. Every method throws on failure. */+/** The bytes of one downloaded resource, with the MIME type the caller needs for a data URL. */+export interface FeishuImageData {+ data: Buffer;+ mimeType: string;+}++/**+ * One file on its way into a chat. Structurally the connector seam's MessagingOutboundFile+ * — declared here rather than imported for the same reason FeishuApiClient mirrors+ * MessagingClient member for member: this module is the layer below the seam and stays+ * free of it, and the connector's assignment is what proves the two agree.+ */+export interface FeishuOutboundFile {+ fileName: string;+ data: Buffer;+}++/** OpenAPI half of the seam: credential probe, text sends, media in both directions. Every method throws on failure. */export interface FeishuApiClient {/*** Credential check: obtains a tenant access token (no scopes needed); throws with a@@ -71,6 +94,27 @@ export interface FeishuApiClient {* connection. A null answer degrades mention handling, it does not break it.*/botOpenId(): Promise<string | null>;+ /**+ * Downloads an image carried by an inbound message (`file_key` is the content JSON's+ * `image_key`). Throws `MessagingMediaTooLargeError` past `maxBytes`, and a plain Error+ * carrying the API's own reason otherwise. The resource endpoint is scoped to the+ * message, so a bot can only read images from conversations it is in — there is no+ * key-only fetch to abuse.+ *+ * It is also permissioned SEPARATELY from receiving messages: an app that happily+ * delivers `im.message.receive_v1` events still gets a refusal here until the resource+ * read scope is granted to it. Nothing in this process can fix that, which is exactly why+ * the API's reason has to survive all the way to the chat.+ */+ fetchMessageImage(args: {+ messageId: string;+ fileKey: string;+ maxBytes: number;+ }): Promise<FeishuImageData>;+ /** Uploads a picture (`im.v1.image.create`) and sends the resulting key as an `image` message. */+ sendImage(chatId: string, file: FeishuOutboundFile): Promise<void>;+ /** Uploads a file (`im.v1.file.create`) and sends the resulting key as a `file` message. */+ sendFile(chatId: string, file: FeishuOutboundFile): Promise<void>;}export interface FeishuEventHandlers {@@ -109,6 +153,8 @@ interface LarkModule {appSecret: string;domain: string;loggerLevel: number;+ /** Test seam: the SDK's `params.httpInstance`, which every call (token fetch included) goes through. */+ httpInstance?: unknown;}) => LarkClient;WSClient: new (params: {appId: string;@@ -129,6 +175,46 @@ interface LarkResponse {msg?: string;}+/** The `msg_type` values this adapter sends (Feishu has many more; these are the three it uses). */+type FeishuMessageType = "text" | "image" | "file";++/**+ * Feishu's upload categories. `stream` is the general one — the rest exist because the+ * client renders a preview for them, so mapping a `.pdf` or a `.xlsx` onto its own category+ * is what makes it open in the chat instead of only downloading.+ */+type FeishuFileType = "opus" | "mp4" | "pdf" | "doc" | "xls" | "ppt" | "stream";++const FEISHU_FILE_TYPE_BY_EXT: Readonly<Record<string, FeishuFileType>> = {+ opus: "opus",+ mp4: "mp4",+ pdf: "pdf",+ doc: "doc",+ docx: "doc",+ xls: "xls",+ xlsx: "xls",+ ppt: "ppt",+ pptx: "ppt",+};++/** The upload category for a file name; anything unrecognized uploads as a plain stream. */+function feishuFileTypeOf(fileName: string): FeishuFileType {+ const dot = fileName.lastIndexOf(".");+ if (dot < 0) return "stream";+ return FEISHU_FILE_TYPE_BY_EXT[fileName.slice(dot + 1).toLowerCase()] ?? "stream";+}++/**+ * The binary-download shape (`im.v1.messageResource.get`): the SDK hands back a stream+ * wrapper, not a `{code,msg}` envelope, because the endpoint answers with the file itself.+ * Typed as an async iterable of chunks rather than as node:stream's `Readable` — that is+ * all the adapter consumes, and it keeps the capped read (collectUnderCap) channel-neutral.+ */+interface LarkStreamResponse {+ getReadableStream(): AsyncIterable<Uint8Array>;+ headers?: Record<string, unknown>;+}+interface LarkClient {/*** The SDK's generic call, for endpoints its typed surface does not cover. Used for@@ -151,13 +237,29 @@ interface LarkClient {message: {create(payload: {params: { receive_id_type: "chat_id" };- data: { receive_id: string; content: string; msg_type: "text" };+ data: { receive_id: string; content: string; msg_type: FeishuMessageType };}): Promise<LarkResponse>;reply(payload: {path: { message_id: string };data: { content: string; msg_type: "text" };}): Promise<LarkResponse>;};+ messageResource: {+ get(payload: {+ path: { message_id: string; file_key: string };+ params: { type: string };+ }): Promise<LarkStreamResponse>;+ };+ image: {+ create(payload: {+ data: { image_type: "message"; image: Buffer };+ }): Promise<{ image_key?: string } | null>;+ };+ file: {+ create(payload: {+ data: { file_type: FeishuFileType; file_name: string; file: Buffer };+ }): Promise<{ file_key?: string } | null>;+ };};};}@@ -186,23 +288,202 @@ interface LarkEventDispatcher {}): LarkEventDispatcher;}-/** Readable failure text out of the SDK's throw shapes (axios errors carry the API body). */-function larkErrorText(err: unknown): string {- const axios = err as { response?: { data?: { msg?: string; code?: number } }; message?: string };- const body = axios.response?.data;- if (body?.msg) return body.code !== undefined ? `${body.msg} (code ${body.code})` : body.msg;- return err instanceof Error ? err.message : String(err);+/**+ * Feishu's `{code, msg, log_id}` refusal envelope, however it reached us. `log_id` is what+ * Feishu support asks for first, so it rides into the error record with the rest.+ */+interface LarkErrorEnvelope {+ code?: number;+ msg?: string;+ logId?: string;}-/** Non-zero `{code}` envelopes come back as resolved responses; converge them to throws. */-function ensureOk(res: LarkResponse, what: string): void {- if (res.code !== undefined && res.code !== 0) {- throw new Error(`${what} failed: ${res.msg ?? "unknown error"} (code ${res.code})`);+/** The tenant-scope denial: the app is missing a permission, and the `msg` says which. */+const FEISHU_SCOPE_DENIED_CODE = 99991672;++/** Reads an envelope out of a value that may or may not be one (a parsed body, a JSON error). */+function envelopeOf(body: unknown): LarkErrorEnvelope | null {+ if (typeof body !== "object" || body === null) return null;+ const { code, msg, log_id: logId } = body as { code?: unknown; msg?: unknown; log_id?: unknown };+ if (typeof code !== "number" && typeof msg !== "string") return null;+ return {+ ...(typeof code === "number" ? { code } : {}),+ ...(typeof msg === "string" ? { msg } : {}),+ ...(typeof logId === "string" ? { logId } : {}),+ };+}++/** The envelope carried by an SDK throw (axios puts the parsed API body on `response.data`). */+function larkErrorEnvelope(err: unknown): LarkErrorEnvelope | null {+ return envelopeOf((err as { response?: { data?: unknown } }).response?.data);+}++/** Readable text for a refusal: Feishu's own sentence when there is one, the SDK's otherwise. */+function envelopeText(envelope: LarkErrorEnvelope | null, err: unknown): string {+ const fallback = err instanceof Error ? err.message : String(err);+ if (envelope?.msg === undefined || envelope.msg === "") return fallback;+ const parts = [+ ...(envelope.code !== undefined ? [`code ${envelope.code}`] : []),+ ...(envelope.logId !== undefined ? [`log_id ${envelope.logId}`] : []),+ ];+ return parts.length > 0 ? `${envelope.msg} (${parts.join(", ")})` : envelope.msg;+}++/** How much of a refusal's `msg` is scanned for the grant link, and how long a link may be. */+const SCOPE_MSG_MAX = 2000;+const GRANT_URL_MAX = 500;++/**+ * The actionable half of a tenant-scope denial: which permissions would satisfy the call,+ * and the console link that grants them.+ *+ * Feishu writes both into `msg` — "One of the following scopes is required:+ * [im:resource:upload, im:resource]" followed by a per-app `…/app/<app-id>/auth?q=…` URL.+ * The link is app-specific and already correct, so it is extracted rather than rebuilt.+ * The prose around them is localized and must never be matched on: the CODE is the test.+ */+function scopeDenialDetail(msg: string): { scopes: string[]; grantUrl: string | null } {+ const text = msg.slice(0, SCOPE_MSG_MAX);+ const bracketed = /\[([^\]]+)\]/.exec(text);+ const scopes = (bracketed?.[1] ?? "")+ .split(",")+ .map((scope) => scope.trim())+ // A scope name is an ASCII colon-separated token; anything else is prose that happened+ // to sit in brackets, and naming it would send the user looking for a permission that+ // does not exist.+ .filter((scope) => /^[a-z][a-z0-9_.:-]*$/i.test(scope));+ // Only an https link, and only up to the first whitespace or CJK punctuation — the+ // sentence continues in Chinese right after the URL in Feishu's own wording.+ const url = /https:\/\/[^\s,。、))]+/.exec(text)?.[0] ?? null;+ return { scopes, grantUrl: url !== null && url.length <= GRANT_URL_MAX ? url : null };+}++/**+ * The error a refused call throws: a permission denial when Feishu said so by CODE, a plain+ * failure otherwise. Only the scope names and the console link travel with the first — the+ * SDK's own error object carries the request config, which is where credentials live.+ */+function larkFailure(envelope: LarkErrorEnvelope | null, err: unknown, what?: string): Error {+ const detail = envelopeText(envelope, err);+ // The operation stays in front of the API's own sentence: an error record that reads only+ // "invalid request" does not say which call made it.+ const text = what === undefined ? detail : `${what} failed: ${detail}`;+ if (envelope?.code === FEISHU_SCOPE_DENIED_CODE && envelope.msg !== undefined) {+ const { scopes, grantUrl } = scopeDenialDetail(envelope.msg);+ if (scopes.length > 0) return new MessagingPermissionError(scopes, grantUrl, text);+ }+ return new Error(text);+}++/**+ * How much of a failed download's body is read back to find the API's reason. A Feishu+ * error envelope is a few hundred bytes; the bound is there because the body is untrusted+ * and the process must not be made to hold whatever arrives.+ */+const ERROR_BODY_MAX_BYTES = 64 * 1024;++/** Whether a value is something `for await` can read (the error body of a streamed request). */+function isAsyncIterable(value: unknown): value is AsyncIterable<Uint8Array> {+ return (+ typeof value === "object" &&+ value !== null &&+ typeof (value as AsyncIterable<Uint8Array>)[Symbol.asyncIterator] === "function"+ );+}++/**+ * The refusal envelope of a request made with `responseType: "stream"` — the resource+ * download.+ *+ * That response type applies to the FAILURE as well: on a refusal the SDK hands back an+ * error whose `response.data` is the response STREAM, unread, not a parsed `{code,msg}`+ * envelope. Read straight off the error it yields nothing, and the report is "Request+ * failed with status code 400" — the one thing the user cannot act on, hiding the one they+ * can. The body is small and already in hand, so it is drained and parsed here.+ */+async function larkStreamErrorEnvelope(err: unknown): Promise<LarkErrorEnvelope | null> {+ const body = (err as { response?: { data?: unknown } }).response?.data;+ const direct = envelopeOf(body);+ if (direct !== null) return direct;+ if (!isAsyncIterable(body)) return null;+ try {+ const raw = await collectUnderCap(body, ERROR_BODY_MAX_BYTES, "The error body");+ return envelopeOf(JSON.parse(raw.toString("utf8")));+ } catch {+ // Not a JSON envelope (an HTML error page, a truncated body, a stream someone else+ // already consumed): the generic text is still better than throwing a second error out+ // of the error path.+ return null;}}+/**+ * Non-zero `{code}` envelopes come back as RESOLVED responses; converge them to throws, and+ * through the same reading as a rejection so a scope denial is one wherever it arrives.+ */+function ensureOk(res: LarkResponse, what: string): void {+ if (res.code === undefined || res.code === 0) return;+ throw larkFailure(envelopeOf(res), new Error("unknown error"), what);+}++/**+ * Per-call deadline for everything this adapter puts on the wire.+ *+ * The SDK's default transport is a bare `axios.create()` with NO timeout, so a request the+ * API accepts and never answers waits forever. That is not a slow send: every outbound+ * message of a Session goes out on one serial chain (MessagingBridge's `sendChain`), so one+ * request that never settles parks every later reply, approval notice and file for that+ * Session — silently, with no error record and no status change — until the binding is+ * toggled or the server restarts. The same stall on the inbound side parks the message with+ * neither delivery nor refusal. Telegram has had a deadline on both directions from the+ * start (see telegram-api's CALL_TIMEOUT_MS / TRANSFER_TIMEOUT_MS); this is Feishu's.+ *+ * One number for both kinds of call, unlike Telegram's two: the uploads and the resource+ * download move at most 30MB, and a chat send that has not answered in a minute is not+ * coming back.+ */+const FEISHU_CALL_TIMEOUT_MS = 60_000;++/**+ * `promise` with a deadline. The underlying request is NOT cancelled — the SDK exposes no+ * signal — so this frees the CALLER, not the socket: the send chain moves on and the+ * abandoned request is left to the runtime. That is the whole point; a leaked socket costs+ * one connection, a wedged chain costs the Session.+ */+function withDeadline<T>(promise: Promise<T>, timeoutMs: number, what: string): Promise<T> {+ // The abandoned promise still needs a handler, or its later rejection is an unhandled one.+ promise.catch(() => {});+ let timer: NodeJS.Timeout;+ const deadline = new Promise<never>((_resolve, reject) => {+ timer = setTimeout(+ () => reject(new Error(`${what} timed out after ${timeoutMs}ms`)),+ timeoutMs,+ );+ });+ return Promise.race([promise, deadline]).finally(() => {+ clearTimeout(timer);+ });+}+/** The production factory: lazy-loads the Lark SDK on first use. */-export function createLarkSdk(): FeishuSdk {+/**+ * `httpInstance` is the SDK's own injection point (`params.httpInstance`, used by every+ * call including the tenant-token fetch). Tests pass a stub that stands exactly where axios+ * stands, so the SDK's URL building, `:path` filling, param serialization and response+ * unwrapping all run for real — the layer a hand-written fake of this module's own+ * interface cannot reach, and where both of this adapter's protocol bugs lived. Production+ * passes nothing.+ *+ * `timeoutMs` overrides FEISHU_CALL_TIMEOUT_MS. Tests only — a deadline test cannot wait a+ * minute, and production has no reason to want a different one.+ */+export interface LarkSdkOpts {+ httpInstance?: unknown;+ timeoutMs?: number;+}++export function createLarkSdk(opts: LarkSdkOpts = {}): FeishuSdk {+ const timeoutMs = opts.timeoutMs ?? FEISHU_CALL_TIMEOUT_MS;let modPromise: Promise<LarkModule> | null = null;const load = (): Promise<LarkModule> => {modPromise ??= import("@larksuiteoapi/node-sdk").then(@@ -220,41 +501,63 @@ export function createLarkSdk(): FeishuSdk {appSecret: creds.appSecret,domain: creds.baseDomain,loggerLevel: lark.LoggerLevel.error,+ ...(opts.httpInstance !== undefined ? { httpInstance: opts.httpInstance } : {}),});+ /** Every call this client makes goes out under the deadline — see withDeadline. */+ const deadline = <T>(call: Promise<T>, what: string): Promise<T> =>+ withDeadline(call, timeoutMs, what);+ /** One `im.v1.message.create`, shared by every message kind: the content JSON differs, nothing else does. */+ const sendContent = async (+ chatId: string,+ msgType: FeishuMessageType,+ content: Record<string, string>,+ ): Promise<void> => {+ let res: LarkResponse;+ try {+ res = await deadline(+ client.im.v1.message.create({+ params: { receive_id_type: "chat_id" },+ data: { receive_id: chatId, content: JSON.stringify(content), msg_type: msgType },+ }),+ "Message send",+ );+ } catch (err) {+ throw larkFailure(larkErrorEnvelope(err), err);+ }+ ensureOk(res, "Message send");+ };+return {async checkCredentials(): Promise<null> {let res: LarkResponse;try {- res = await client.auth.v3.tenantAccessToken.internal({- data: { app_id: creds.appId, app_secret: creds.appSecret },- });+ res = await deadline(+ client.auth.v3.tenantAccessToken.internal({+ data: { app_id: creds.appId, app_secret: creds.appSecret },+ }),+ "Credential check",+ );} catch (err) {- throw new Error(larkErrorText(err));+ throw larkFailure(larkErrorEnvelope(err), err);}ensureOk(res, "Credential check");return null;},- async sendText(chatId: string, text: string): Promise<void> {- let res: LarkResponse;- try {- res = await client.im.v1.message.create({- params: { receive_id_type: "chat_id" },- data: { receive_id: chatId, content: JSON.stringify({ text }), msg_type: "text" },- });- } catch (err) {- throw new Error(larkErrorText(err));- }- ensureOk(res, "Message send");+ sendText(chatId: string, text: string): Promise<void> {+ return sendContent(chatId, "text", { text });},async replyText(messageId: string, text: string): Promise<void> {let res: LarkResponse;try {- res = await client.im.v1.message.reply({- path: { message_id: messageId },- data: { content: JSON.stringify({ text }), msg_type: "text" },- });+ res = await deadline(+ client.im.v1.message.reply({+ path: { message_id: messageId },+ data: { content: JSON.stringify({ text }), msg_type: "text" },+ }),+ "Message reply",+ );} catch (err) {- throw new Error(larkErrorText(err));+ throw larkFailure(larkErrorEnvelope(err), err);}ensureOk(res, "Message reply");},@@ -263,13 +566,82 @@ export function createLarkSdk(): FeishuSdk {// a thrown request, a non-zero envelope, a body without the field — answers// "unknown" so a connection is never refused over it.try {- const res = await client.request({ url: "/open-apis/bot/v3/info", method: "GET" });+ const res = await deadline(+ client.request({ url: "/open-apis/bot/v3/info", method: "GET" }),+ "Bot identity lookup",+ );if (res.code !== undefined && res.code !== 0) return null;return res.bot?.open_id ?? null;} catch {return null;}},+ async fetchMessageImage({ messageId, fileKey, maxBytes }): Promise<FeishuImageData> {+ let res: LarkStreamResponse;+ try {+ res = await deadline(+ client.im.v1.messageResource.get({+ path: { message_id: messageId, file_key: fileKey },+ params: { type: "image" },+ }),+ "Image download",+ );+ } catch (err) {+ throw larkFailure(await larkStreamErrorEnvelope(err), err);+ }+ const data = await collectUnderCap(res.getReadableStream(), maxBytes, "The image");+ // The response header states what the SENDER uploaded, which is a claim; the+ // magic bytes are the file. PNG is the last resort — a data URL needs some type,+ // and every provider that takes images at all takes that one.+ const declared = res.headers?.["content-type"];+ const headerType =+ typeof declared === "string" && declared.startsWith("image/")+ ? declared.split(";")[0]!.trim()+ : null;+ return { data, mimeType: sniffImageMime(data) ?? headerType ?? "image/png" };+ },+ async sendImage(chatId: string, file: FeishuOutboundFile): Promise<void> {+ // Two steps, as Feishu requires: the bytes are uploaded on their own and the+ // message carries only the key they were stored under.+ let uploaded: { image_key?: string } | null;+ try {+ uploaded = await deadline(+ client.im.v1.image.create({ data: { image_type: "message", image: file.data } }),+ "Image upload",+ );+ } catch (err) {+ throw larkFailure(larkErrorEnvelope(err), err);+ }+ // The upload endpoints resolve to their `data` object, so a refusal arrives as a+ // missing key rather than as a non-zero `{code}` this adapter could report.+ const imageKey = uploaded?.image_key;+ if (imageKey === undefined || imageKey === "") {+ throw new Error(`Image upload failed: ${file.fileName} returned no image_key`);+ }+ await sendContent(chatId, "image", { image_key: imageKey });+ },+ async sendFile(chatId: string, file: FeishuOutboundFile): Promise<void> {+ let uploaded: { file_key?: string } | null;+ try {+ uploaded = await deadline(+ client.im.v1.file.create({+ data: {+ file_type: feishuFileTypeOf(file.fileName),+ file_name: file.fileName,+ file: file.data,+ },+ }),+ "File upload",+ );+ } catch (err) {+ throw larkFailure(larkErrorEnvelope(err), err);+ }+ const fileKey = uploaded?.file_key;+ if (fileKey === undefined || fileKey === "") {+ throw new Error(`File upload failed: ${file.fileName} returned no file_key`);+ }+ await sendContent(chatId, "file", { file_key: fileKey });+ },};},diff --git a/packages/server/src/runtime/messaging/media.ts b/packages/server/src/runtime/messaging/media.tsnew file mode 100644index 00000000..066c7798--- /dev/null+++ b/packages/server/src/runtime/messaging/media.ts@@ -0,0 +1,140 @@+/**+ * The media questions every messaging channel has to answer the same way: which files the+ * chat should render as a picture rather than offer as an attachment, what MIME type a+ * downloaded image's bytes carry, and how to read a download without letting the remote+ * side decide how much memory it may use.+ *+ * It sits beside the connectors instead of inside one because the answers must not differ+ * per channel: a `.png` the Agent wrote has to arrive as a picture in Feishu AND in+ * Telegram, or the same reply reads differently depending on where it landed. The+ * connectors keep only what is genuinely channel-shaped (which endpoint, which field+ * name); the classification lives here.+ */++/**+ * The extensions sent as an image, mapped to the MIME type that names them.+ *+ * Deliberately the intersection of what both channels' image endpoints accept and both+ * clients render inline — Feishu's upload also takes BMP/ICO/TIFF/HEIC and Telegram's+ * `sendPhoto` re-encodes what it is given, but a set that holds on one channel and not the+ * other would make the same reply look different in two chats. SVG is excluded on purpose:+ * neither channel renders it as a picture, and it is a scriptable document (see+ * WorkspaceFileContent.scriptable) — it travels as a file attachment instead.+ */+const IMAGE_MIME_BY_EXT: Readonly<Record<string, string>> = {+ png: "image/png",+ jpg: "image/jpeg",+ jpeg: "image/jpeg",+ gif: "image/gif",+ webp: "image/webp",+};++/** The MIME type implied by a file name's extension, or null when it is not one of the image kinds. */+export function imageMimeOfName(name: string): string | null {+ const dot = name.lastIndexOf(".");+ if (dot < 0) return null;+ return IMAGE_MIME_BY_EXT[name.slice(dot + 1).toLowerCase()] ?? null;+}++/** Whether a file name should be sent as a picture (see IMAGE_MIME_BY_EXT for the set and why). */+export function isImageFileName(name: string): boolean {+ return imageMimeOfName(name) !== null;+}++/**+ * The image type the bytes themselves declare, or null for anything unrecognized.+ *+ * An inbound download names its type unreliably — Feishu's resource endpoint answers with+ * whatever content type the sender's upload carried, and a channel that answers+ * `application/octet-stream` would otherwise produce a data URL no provider accepts. The+ * magic bytes are the one source that cannot be wrong, so they win where they are+ * conclusive and the header stays the fallback.+ */+export function sniffImageMime(bytes: Uint8Array): string | null {+ const at = (i: number): number => bytes[i] ?? -1;+ if (at(0) === 0x89 && at(1) === 0x50 && at(2) === 0x4e && at(3) === 0x47) return "image/png";+ if (at(0) === 0xff && at(1) === 0xd8 && at(2) === 0xff) return "image/jpeg";+ if (at(0) === 0x47 && at(1) === 0x49 && at(2) === 0x46) return "image/gif";+ // RIFF....WEBP — the four-byte size field between the two tags is not part of the tag.+ if (+ at(0) === 0x52 &&+ at(1) === 0x49 &&+ at(2) === 0x46 &&+ at(3) === 0x46 &&+ at(8) === 0x57 &&+ at(9) === 0x45 &&+ at(10) === 0x42 &&+ at(11) === 0x50+ ) {+ return "image/webp";+ }+ return null;+}++/**+ * A transfer refused for its size, as opposed to one that failed.+ *+ * The distinction exists because the two have nothing in common but the outcome, and the+ * user's next move differs: a size refusal is theirs to fix by sending something smaller,+ * while a failure is a fault somewhere else — a permission the bot was never granted, a+ * network blip — that no amount of resending will clear. A notice that covers both says+ * neither, which is how a real permission error was first reported to us as "the image is+ * too large or the download failed".+ */+export class MessagingMediaTooLargeError extends Error {+ constructor(what: string, maxBytes: number) {+ super(`${what} is larger than the ${Math.floor(maxBytes / (1024 * 1024))}MB limit`);+ this.name = "MessagingMediaTooLargeError";+ }+}++/**+ * A transfer the channel refused because the bot's own app lacks a permission.+ *+ * Its own class because it is the one transfer failure the person in the chat can fix, and+ * only if they are told what to grant and where: "Request failed with status code 403" sends+ * them to a log, while the scope name and the console link are ten seconds of work. Feishu+ * hands both back in its refusal (`code` 99991672) — see the connector's scopeDenialDetail.+ *+ * `scopes` is what the channel said would satisfy the call (any ONE of them, in Feishu's+ * wording); `grantUrl` is the channel's own console link, or null when the refusal carried+ * none. Nothing else off the channel's error travels with it: the raw SDK error carries the+ * request config, and that is where credentials live.+ */+export class MessagingPermissionError extends Error {+ constructor(+ readonly scopes: readonly string[],+ readonly grantUrl: string | null,+ message: string,+ ) {+ super(message);+ this.name = "MessagingPermissionError";+ }+}++/**+ * Reads a download into memory, refusing at the byte that crosses `maxBytes`.+ *+ * Buffering `await res.arrayBuffer()` and checking the length afterwards would be a+ * remote-controlled allocation: a declared size is a claim, and both channels can serve+ * far more than this server wants to hold (Feishu's resource endpoint goes to 100MB). The+ * count is kept over the chunks actually received, so a lying `content-length` — or none+ * at all — buys nothing.+ *+ * `what` names the transfer in the error message; it must never carry a URL, since+ * Telegram's file endpoint embeds the bot token in one.+ */+export async function collectUnderCap(+ chunks: AsyncIterable<Uint8Array>,+ maxBytes: number,+ what: string,+): Promise<Buffer> {+ const parts: Uint8Array[] = [];+ let total = 0;+ for await (const chunk of chunks) {+ total += chunk.byteLength;+ if (total > maxBytes) throw new MessagingMediaTooLargeError(what, maxBytes);+ parts.push(chunk);+ }+ return Buffer.concat(parts);+}diff --git a/packages/server/src/runtime/messaging/reply-files.ts b/packages/server/src/runtime/messaging/reply-files.tsnew file mode 100644index 00000000..7051b940--- /dev/null+++ b/packages/server/src/runtime/messaging/reply-files.ts@@ -0,0 +1,223 @@+/**+ * Which files a reply MENTIONS: the path-like tokens in a run's assistant text, normalized+ * to Workspace-relative paths.+ *+ * The Agent's own words are what decide. A chart it hands over is named in the answer,+ * while the twelve intermediates it wrote on the way there are not, and mirroring the+ * filesystem instead would bury the one file the user asked for. Existence is checked+ * separately (WorkspaceFilesService), and that check is what makes a loose extraction safe:+ * a token that is not a real file in this Workspace costs nothing to have considered.+ *+ * ## Why this is looser than the Web App's file card+ *+ * The card (`packages/web/src/features/chat/message-files-card.tsx`) reads inline-code+ * spans only, and that was this module's first rule too. It does not survive contact with+ * a chat: a model that writes "已经把图表保存为 chart.png" or "Saved it at+ * /ws/out/chart.png" names the file perfectly clearly and matched nothing, so the feature+ * produced nothing at all for most real replies. The card can afford the strict rule+ * because it decorates Markdown that is already rendered — a path it misses is simply not+ * clickable, and the file is still one click away in the Files panel. Here the extraction+ * IS the feature: what it misses never reaches the user.+ *+ * So a token is a candidate wherever it appears — prose, a list, a code block — and+ * prose punctuation is stripped off its edges. The cost is precision: a reply that merely+ * mentions a file it read can now send it. That is bounded by three things — the file must+ * exist in the Workspace, at most a handful ride along per run, and the reply said the name+ * out loud.+ */+/**+ * Extensions that make a token look like a file path. The card's list verbatim: it is+ * broad on purpose (an Agent writes reports, data and code), and the existence check+ * behind it is what keeps a false positive harmless.+ */+const KNOWN_EXTENSIONS = new Set([+ // Text / code+ "txt",+ "md",+ "json",+ "js",+ "mjs",+ "cjs",+ "ts",+ "tsx",+ "jsx",+ "py",+ "sh",+ "bash",+ "yaml",+ "yml",+ "toml",+ "css",+ "html",+ "htm",+ "csv",+ "log",+ "xml",+ "ini",+ "conf",+ "rs",+ "go",+ "java",+ "c",+ "h",+ "cpp",+ "hpp",+ "sql",+ "rb",+ "php",+ // Images / documents+ "png",+ "jpg",+ "jpeg",+ "gif",+ "webp",+ "svg",+ "pdf",+ "doc",+ "docx",+ "xls",+ "xlsx",+ "ppt",+ "pptx",+ // Media / archives+ "zip",+ "tar",+ "gz",+ "mp4",+ "mp3",+ "wav",+]);++const URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;++/** Max length of a single path (matches the files/stat route's validation). */+const MAX_PATH_LEN = 512;++/**+ * What separates one token from the next: whitespace, Markdown's own decorations+ * (backticks, asterisks, brackets, parentheses, quotes, table pipes, autolink angles), and+ * CJK punctuation — a Chinese sentence puts no spaces around a filename, so without the+ * last group a whole clause arrives as one token and matches nothing.+ *+ * Deliberately NOT boundaries: the ASCII colon and the backslash (together they spell a+ * Windows path, `C:\ws\out.png`), and `_ - + ~ .`, all common inside real file names.+ */+const TOKEN_BOUNDARY = /[\s`*"'()[\]{}<>|,;、,。:;!?“”‘’()【】〔〕「」『』《》〈〉…—–]+/;++/**+ * Sentence punctuation left clinging to a token's edges ("report.md." → "report.md").+ *+ * The LEADING class deliberately excludes `.`: a dot in front of a path is part of it, not+ * prose. Stripping it turned `./chart.png` into `/chart.png`, which reads as an absolute+ * path outside the Workspace and is refused, and `.eslintrc.json` into a file that does not+ * exist — the two spellings an Agent reaches for most often after a bare name.+ */+const EDGE_PUNCTUATION = /^[,;:!?]+|[.,;:!?]+$/g;++/**+ * How many candidates are considered per reply. A bound, not a feature: a run that pastes a+ * directory listing into its answer would otherwise put hundreds of names through a stat+ * each. Well past any reply that is actually handing a file over — the batch itself caps at+ * a handful.+ */+const MAX_CANDIDATES = 50;++/**+ * Whether one token looks like a file path: no whitespace, no URL scheme, ends in a known+ * extension. Heuristic, not exhaustive — the card's test, unchanged; what changed around it+ * is which tokens are offered to it.+ */+function isFilePathLike(text: string): boolean {+ const s = text.trim();+ if (s.length === 0 || s.length > 200) return false;+ if (/\s/.test(s)) return false;+ if (URL_SCHEME_RE.test(s) || s.startsWith("www.")) return false;+ const m = /\.([A-Za-z0-9]{1,8})$/.exec(s);+ if (!m) return false;+ const ext = m[1]!.toLowerCase();+ if (/^\d+$/.test(ext)) return false; // version numbers like "v1.2" are not file paths+ return KNOWN_EXTENSIONS.has(ext);+}++/**+ * A mentioned path as a Workspace-relative one, or null when it cannot be resolved into+ * this Workspace: an absolute path outside it, a `~` path (this process cannot know whose+ * home that is), or a relative path whose `..` segments climb out. A Windows Workspace is+ * compared on "/" with a case-insensitive drive letter, since core spells model-visible+ * paths with forward slashes while `path.join` produces backslashes; a POSIX Workspace+ * converts nothing, because a backslash is a legal character in a POSIX file name.+ *+ * Refusing an escape here is a readability rule, not the security boundary — the+ * containment check in WorkspaceFilesService is, and every path still goes through it.+ */+function toWorkspaceRelative(mentioned: string, workspace: string): string | null {+ const s = mentioned.trim();+ if (s.length === 0 || s.length > MAX_PATH_LEN) return null;+ if (s.startsWith("~")) return null;+ const winWs = workspace.includes("\\") || /^[A-Za-z]:/.test(workspace);+ const normalize = (p: string): string => {+ if (!winWs) return p;+ const slashed = p.replaceAll("\\", "/");+ return /^[A-Za-z]:/.test(slashed) ? slashed[0]!.toLowerCase() + slashed.slice(1) : slashed;+ };+ const input = normalize(s);+ const ws = normalize(workspace);+ const absolute = input.startsWith("/") || (winWs && /^[a-z]:/.test(input));+ let rel = input;+ if (absolute) {+ if (!input.startsWith(`${ws}/`)) return null;+ rel = input.slice(ws.length + 1);+ }+ const stack: string[] = [];+ for (const seg of rel.split("/")) {+ if (seg === "" || seg === ".") continue;+ if (seg === "..") {+ if (stack.length === 0) return null;+ stack.pop();+ continue;+ }+ stack.push(seg);+ }+ return stack.length > 0 ? stack.join("/") : null;+}++/** One path-like token a reply wrote, and where it points. */+export interface ReplyFileMention {+ /**+ * The token exactly as the reply spelled it. A notice quotes THIS back, never the+ * normalized form: the chat gets to see the reply's own words, and nothing the reply did+ * not already say reaches it.+ */+ mentioned: string;+ /** Its Workspace-relative form, or null when it names nothing inside this Workspace. */+ rel: string | null;+}++/**+ * Every path-like token one run's assistant text mentions, in order of appearance.+ *+ * Deduplication is keyed on the NORMALIZED path where there is one, so a file named once+ * absolutely and once relatively is one file — otherwise a run that reports its output both+ * ways would send the same picture twice — and on the token itself where there is not.+ *+ * The unresolvable ones are returned rather than dropped because the caller has to say+ * something about them: a reply that names a file the chat then never receives, with+ * nothing anywhere to say why, is how this feature reads as broken.+ */+export function replyFileMentions(text: string, workspace: string): ReplyFileMention[] {+ const out: ReplyFileMention[] = [];+ const seen = new Set<string>();+ let considered = 0;+ for (const token of text.split(TOKEN_BOUNDARY)) {+ if (considered >= MAX_CANDIDATES) break;+ const candidate = token.replace(EDGE_PUNCTUATION, "");+ if (!isFilePathLike(candidate)) continue;+ considered += 1;+ const rel = toWorkspaceRelative(candidate, workspace);+ const key = rel ?? `\u0000${candidate}`;+ if (seen.has(key)) continue;+ seen.add(key);+ out.push({ mentioned: candidate, rel });+ }+ return out;+}diff --git a/packages/server/src/runtime/messaging/telegram-api.ts b/packages/server/src/runtime/messaging/telegram-api.tsindex 33ea26de..777fccef 100644--- a/packages/server/src/runtime/messaging/telegram-api.ts+++ b/packages/server/src/runtime/messaging/telegram-api.ts@@ -1,6 +1,8 @@/**- * The Telegram Bot API seam: the four methods the Telegram connector uses (`getMe`,- * `getWebhookInfo`, `sendMessage`, `getUpdates`), behind an injectable transport so unit+ * The Telegram Bot API seam: the methods the Telegram connector uses (`getMe`,+ * `getWebhookInfo`, `sendMessage`, `getUpdates`, the file download behind an inbound photo,+ * and the `sendPhoto` / `sendDocument` uploads behind an outbound one),+ * behind an injectable transport so unit* tests substitute a fake and never open real network. Telegram needs no SDK — the Bot API is plain HTTPS* POSTs against https://api.telegram.org — so the production transport is a thin fetch* wrapper.@@ -8,6 +10,8 @@* Wire types below mirror the Bot API JSON verbatim (snake_case): the transport does not* reshape payloads, so a test fake constructs exactly what the real API returns.*/+import { FormData, fetch as undiciFetch } from "undici";+import { MessagingMediaTooLargeError, collectUnderCap } from "./media.js";/** Telegram Bot API host. Deliberately not configurable: bindings carry only the token. */export const TELEGRAM_API_BASE = "https://api.telegram.org";@@ -52,6 +56,19 @@ export interface TelegramMessageEntity {user?: { id: number };}+/**+ * One size variant of an inbound photo. The Bot API sends a photo as an ARRAY of these —+ * the same picture re-encoded at several resolutions — and the connector picks the largest,+ * which is the one the user actually sent.+ */+export interface TelegramPhotoSize {+ file_id: string;+ width: number;+ height: number;+ /** The Bot API marks it optional, so the size comparison cannot rely on it alone. */+ file_size?: number;+}+/** The slice of a Bot API `Message` the connector consumes. */export interface TelegramMessage {message_id: number;@@ -64,11 +81,7 @@ export interface TelegramMessage {};/** Present only for text messages; anything else (photo, sticker, voice, …) omits it. */text?: string;- /**- * Spans over `text` (mentions, formatting, …); absent when the message has none. A- * captioned media message carries the same shapes over its caption under- * `caption_entities` instead — the day this connector reads captions, it reads that.- */+ /** Spans over `text` (mentions, formatting, …); absent when the message has none. */entities?: TelegramMessageEntity[];/*** "Unique identifier of a message thread or forum topic to which the message belongs; for@@ -90,12 +103,38 @@ export interface TelegramMessage {* for the reply-chain `message_thread_id` above, which is exactly what tells the two apart.*/is_topic_message?: boolean;+ /** Size variants of an inbound photo, smallest first; absent for every other message kind. */+ photo?: TelegramPhotoSize[];+ /** The text sent WITH a photo (or another media message) — a text message carries `text` instead. */+ caption?: string;+ /**+ * The same spans over `caption` that `entities` carries over `text`. A captioned photo is+ * how a group addresses this bot about a picture, so the caption needs the same mention+ * handling the text gets — see the connector's stripBotMention.+ */+ caption_entities?: TelegramMessageEntity[];from?: {first_name?: string;username?: string;};}+/** The slice of `getFile`'s result the connector consumes. */+export interface TelegramFile {+ /**+ * Path to pass to the file endpoint (valid at least an hour). Optional on the wire: a+ * file the bot may not download resolves without one.+ */+ file_path?: string;+ file_size?: number;+}++/** A downloaded file: the bytes, plus the path they came from (its extension names the type). */+export interface TelegramFileBytes {+ data: Buffer;+ filePath: string;+}+/*** The slice of `getWebhookInfo`'s result the connector consumes. `url` is the empty string* when no webhook is registered — that is the Bot API's own encoding, not a normalization.@@ -146,6 +185,23 @@ export interface TelegramBotClient {timeoutSec: number;signal: AbortSignal;}): Promise<TelegramUpdate[]>;+ /**+ * Downloads a file the bot can see, in two hops: `getFile` resolves a path, and the FILE+ * endpoint serves the bytes. That second URL is not the method endpoint — it is+ * `/file/bot<token>/<file_path>` — and it embeds the bot token, so no failure here may+ * ever echo it (see fetchErrorText). Throws when the transfer fails or exceeds+ * `maxBytes`; the Bot API itself refuses to serve a bot anything over 20MB this way, so+ * whichever ceiling is lower is the one that bites.+ */+ getFileBytes(args: { fileId: string; maxBytes: number }): Promise<TelegramFileBytes>;+ /**+ * Sends a picture into a chat as a photo, so it renders inline. Multipart upload from+ * bytes rather than by URL — the file lives in a Workspace this server can read and+ * Telegram cannot.+ */+ sendPhoto(args: { chatId: string; fileName: string; data: Buffer }): Promise<void>;+ /** Sends any other file into a chat as a document (the attachment form). */+ sendDocument(args: { chatId: string; fileName: string; data: Buffer }): Promise<void>;}/** Factory the Telegram connector is built over: the production fetch adapter, or a test fake. */@@ -153,6 +209,34 @@ export interface TelegramTransport {createClient(creds: TelegramCredentials): TelegramBotClient;}+/**+ * `fetch` AND `FormData` are imported from undici on purpose, and must stay a matched pair.+ *+ * The startup entry replaces `globalThis.fetch` with undici's so outbound traffic follows+ * the proxy dispatcher (see net/proxy.ts). undici's fetch brand-checks a FormData body+ * against ITS OWN class, and Node's built-in `FormData` is a different class, so a global+ * `new FormData()` fell through undici's body handling to `String(body)` — the Bot API+ * received the 17 bytes `[object FormData]` as `text/plain` and answered "there is no+ * document in the request". Every upload failed in production and none did in CI, where+ * `globalThis.fetch` is still the runtime's own and the pairing happens to match.+ *+ * Importing FormData from undici while calling `globalThis.fetch` inverts the same bug, so+ * the transport calls undici's fetch directly. That keeps the proxy: undici's fetch+ * resolves the global dispatcher per call, which is the contract net/proxy.ts is written+ * against. `Blob` needs no such treatment — `globalThis.Blob` IS node:buffer's Blob, and+ * undici's FormData accepts it (verified on the wire, not assumed).+ */+type TelegramFetch = typeof undiciFetch;++export interface TelegramTransportOpts {+ /**+ * Test seam: the `fetch` the transport calls. Only for the tests that assert on request+ * shape and error mapping — the multipart pairing above is provable only against a real+ * socket, so the tests that cover it drive the default.+ */+ fetch?: TelegramFetch;+}+// ---------------------------------------------------------------------------// Production adapter over fetch// ---------------------------------------------------------------------------@@ -160,6 +244,13 @@ export interface TelegramTransport {/** Overall per-request deadline for the short calls (getMe / sendMessage / the drain). */const CALL_TIMEOUT_MS = 15_000;+/**+ * Deadline for a file transfer, in either direction. Far longer than a method call: these+ * move megabytes over whatever link the server has, and a 15s ceiling would fail a picture+ * that was on its way perfectly well.+ */+const TRANSFER_TIMEOUT_MS = 60_000;+/** The `{ok, result, description, error_code}` envelope every Bot API response carries. */interface TelegramEnvelope<T> {ok?: boolean;@@ -220,41 +311,79 @@ function fetchErrorText(err: unknown): string {return String(err);}+/**+ * A response body as chunks. `Response.body` is a web ReadableStream, which is only+ * async-iterable under some lib configurations; reading it through its reader works under+ * all of them. Cancelling on the way out matters for the capped read — a transfer aborted+ * over the ceiling must not leave the socket draining the rest of the file.+ */+async function* bodyChunks(body: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array> {+ const reader = body.getReader();+ try {+ for (;;) {+ const { done, value } = await reader.read();+ if (done) return;+ if (value !== undefined) yield value;+ }+ } finally {+ await reader.cancel().catch(() => {});+ }+}+/** The production factory: plain HTTPS against the Bot API. */-export function createTelegramTransport(): TelegramTransport {+export function createTelegramTransport(opts: TelegramTransportOpts = {}): TelegramTransport {+ const doFetch = opts.fetch ?? undiciFetch;return {createClient(creds: TelegramCredentials): TelegramBotClient {- const call = async <T>(+ /** One Bot API method call: POST the body, then unwrap the `{ok, result}` envelope. */+ const send = async <T>(method: string,- payload: Record<string, unknown>,+ // The two body shapes this transport posts: a JSON string, or a multipart upload.+ body: string | FormData,+ headers: Record<string, string>,opts?: { signal?: AbortSignal; timeoutMs?: number },): Promise<T> => {const deadline = AbortSignal.timeout(opts?.timeoutMs ?? CALL_TIMEOUT_MS);const signal = opts?.signal ? AbortSignal.any([opts.signal, deadline]) : deadline;- let res: Response;+ let res: Awaited<ReturnType<TelegramFetch>>;try {- res = await fetch(`${TELEGRAM_API_BASE}/bot${creds.botToken}/${method}`, {+ res = await doFetch(`${TELEGRAM_API_BASE}/bot${creds.botToken}/${method}`, {method: "POST",- headers: { "content-type": "application/json" },- body: JSON.stringify(payload),+ headers,+ body,signal,});} catch (err) {throw new Error(`${method} failed: ${fetchErrorText(err)}`);}- const body = (await res.json().catch(() => null)) as TelegramEnvelope<T> | null;- if (body === null || body.ok !== true) {- const described = body?.description;+ const parsed = (await res.json().catch(() => null)) as TelegramEnvelope<T> | null;+ if (parsed === null || parsed.ok !== true) {+ const described = parsed?.description;const detail =(described !== undefined ? conflictText(described) : null) ??described ??`HTTP ${res.status}`;- const code = body?.error_code !== undefined ? ` (code ${body.error_code})` : "";- throw new TelegramApiError(`${method} failed: ${detail}${code}`, body?.error_code);+ const code = parsed?.error_code !== undefined ? ` (code ${parsed.error_code})` : "";+ throw new TelegramApiError(`${method} failed: ${detail}${code}`, parsed?.error_code);}- return body.result as T;+ return parsed.result as T;};+ const call = <T>(+ method: string,+ payload: Record<string, unknown>,+ opts?: { signal?: AbortSignal; timeoutMs?: number },+ ): Promise<T> =>+ send<T>(method, JSON.stringify(payload), { "content-type": "application/json" }, opts);++ /**+ * A file-carrying call. No content-type is set on purpose: fetch derives the+ * multipart one from the FormData, boundary included, and a hand-written header+ * would name a boundary the body does not use.+ */+ const callForm = (method: string, form: FormData): Promise<unknown> =>+ send<unknown>(method, form, {}, { timeoutMs: TRANSFER_TIMEOUT_MS });+// Chat ids are stored as text; the API wants the numeric form back (a string works// for @channel usernames only), so safe integers are converted.const wireChatId = (chatId: string): number | string => {@@ -292,6 +421,46 @@ export function createTelegramTransport(): TelegramTransport {// The overall deadline must outlive the server-side long poll.{ signal, timeoutMs: (timeoutSec + 15) * 1000 },),+ async getFileBytes({ fileId, maxBytes }): Promise<TelegramFileBytes> {+ const file = await call<TelegramFile>("getFile", { file_id: fileId });+ if (file.file_path === undefined || file.file_path === "") {+ throw new Error("getFile failed: this file cannot be downloaded");+ }+ // The declared size refuses an oversized transfer before it starts; the capped+ // read below is what actually holds, since the claim can be absent or wrong.+ if (file.file_size !== undefined && file.file_size > maxBytes) {+ throw new MessagingMediaTooLargeError("The image", maxBytes);+ }+ let res: Awaited<ReturnType<TelegramFetch>>;+ try {+ res = await doFetch(+ `${TELEGRAM_API_BASE}/file/bot${creds.botToken}/${file.file_path}`,+ {+ signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS),+ },+ );+ } catch (err) {+ throw new Error(`file download failed: ${fetchErrorText(err)}`);+ }+ // The URL carries the token, so a failure names the status and nothing else.+ if (!res.ok || res.body === null) {+ throw new Error(`file download failed: HTTP ${res.status}`);+ }+ const data = await collectUnderCap(bodyChunks(res.body), maxBytes, "The image");+ return { data, filePath: file.file_path };+ },+ async sendPhoto({ chatId, fileName, data }): Promise<void> {+ const form = new FormData();+ form.append("chat_id", String(wireChatId(chatId)));+ form.append("photo", new Blob([data]), fileName);+ await callForm("sendPhoto", form);+ },+ async sendDocument({ chatId, fileName, data }): Promise<void> {+ const form = new FormData();+ form.append("chat_id", String(wireChatId(chatId)));+ form.append("document", new Blob([data]), fileName);+ await callForm("sendDocument", form);+ },};},};diff --git a/packages/server/src/runtime/messaging/telegram-connector.ts b/packages/server/src/runtime/messaging/telegram-connector.tsindex 07490a03..76f3799c 100644--- a/packages/server/src/runtime/messaging/telegram-connector.ts+++ b/packages/server/src/runtime/messaging/telegram-connector.ts@@ -41,15 +41,18 @@ import type {MessagingClient,MessagingConnection,MessagingConnectorHandlers,+ MessagingInboundImage,MessagingInboundMessage,MessagingSendNote,} from "./connector.js";+import { imageMimeOfName } from "./media.js";import type {TelegramBotClient,TelegramBotUser,TelegramCredentials,TelegramMessage,TelegramMessageEntity,+ TelegramPhotoSize,TelegramTransport,TelegramUpdate,} from "./telegram-api.js";@@ -263,19 +266,59 @@ function topicIdOf(msg: TelegramMessage): number | undefined {: undefined;}+/**+ * The variant of an inbound photo to fetch: the largest, which is the picture as sent —+ * the smaller entries are thumbnails the Bot API generated. Compared on pixel count, since+ * `width`/`height` are always present while `file_size` is optional, with the byte size as+ * the tie-break between two variants of equal dimensions.+ */+function largestPhoto(sizes: readonly TelegramPhotoSize[]): TelegramPhotoSize | null {+ let best: TelegramPhotoSize | null = null;+ for (const size of sizes) {+ if (best === null) {+ best = size;+ continue;+ }+ const pixels = size.width * size.height;+ const bestPixels = best.width * best.height;+ if (pixels > bestPixels) best = size;+ else if (pixels === bestPixels && (size.file_size ?? 0) > (best.file_size ?? 0)) best = size;+ }+ return best;+}+/*** One update reduced to the bridge's normalized shape; null for updates that are not chat- * messages. `me` is this bot's own account (null before the first `getMe` of a connection- * has answered), used only to recognize its own mention.+ * messages. `bot` is captured by an inbound photo's `fetch`, so the bytes are pulled only+ * if the bridge asks for them. `me` is this bot's own account (null before the first `getMe`+ * of a connection has answered), used only to recognize its own mention.*/function normalizeUpdate(update: TelegramUpdate,+ bot: TelegramBotClient,me: TelegramBotUser | null,): MessagingInboundMessage | null {const msg = update.message;if (msg === undefined) return null;const senderName = msg.from?.first_name ?? msg.from?.username;const topicId = topicIdOf(msg);+ const photo = msg.photo !== undefined ? largestPhoto(msg.photo) : null;+ const images: MessagingInboundImage[] =+ photo === null+ ? []+ : [+ {+ fetch: async (maxBytes) => {+ const { data, filePath } = await bot.getFileBytes({+ fileId: photo.file_id,+ maxBytes,+ });+ // Telegram re-encodes what it serves as a photo, so the served path's+ // extension is the type; JPEG is what that re-encoding almost always yields.+ return { data, mimeType: imageMimeOfName(filePath) ?? "image/jpeg" };+ },+ },+ ];return {// The topic rides the chat id so the binding remembers the LAST one written in, the same// way it already remembers the last chat: a user who moves to a new topic gets the@@ -283,9 +326,19 @@ function normalizeUpdate(chatId: chatRefOf(msg.chat.id, topicId),chatKind: msg.chat.type === "private" ? "direct" : "group",messageId: replyRefOf(msg.chat.id, msg.message_id, topicId),- // Only text messages carry `text`; every other message type normalizes to null (the- // bridge answers those with the text-only notice).- text: typeof msg.text === "string" ? stripBotMention(msg.text, msg.entities, me) : null,+ // A text message carries `text`; a PHOTO carries its words in `caption` instead, which+ // is that message's text as far as the bridge is concerned. Every other media kind+ // (document, video, audio, voice, …) normalizes to null EVEN WHEN it has a caption:+ // its bytes are not delivered, so running the model on the caption alone would answer+ // confidently about a file it never received. A picture dragged in uncompressed+ // arrives as a document, which makes that the common case rather than a corner one.+ text:+ typeof msg.text === "string"+ ? stripBotMention(msg.text, msg.entities, me)+ : photo !== null && typeof msg.caption === "string"+ ? stripBotMention(msg.caption, msg.caption_entities, me)+ : null,+ ...(images.length > 0 ? { images } : {}),...(senderName !== undefined ? { senderName } : {}),};}@@ -332,6 +385,12 @@ export class TelegramConnector implements MessagingChannelConnector {// conversation is least able to spare it.return sendWithThreadFallback(bot, { chatId, text, replyToMessageId: messageId }, threadId);},+ async sendImage(chatId, file) {+ await bot.sendPhoto({ chatId, fileName: file.fileName, data: file.data });+ },+ async sendFile(chatId, file) {+ await bot.sendDocument({ chatId, fileName: file.fileName, data: file.data });+ },};}@@ -409,7 +468,7 @@ export class TelegramConnector implements MessagingChannelConnector {}for (const update of updates) {offset = update.update_id + 1;- const msg = normalizeUpdate(update, me);+ const msg = normalizeUpdate(update, bot, me);if (msg !== null) await handlers.onMessage(msg);}} catch (err) {diff --git a/packages/server/src/services/workspace-files-service.ts b/packages/server/src/services/workspace-files-service.tsindex a1c339b9..283889a9 100644--- a/packages/server/src/services/workspace-files-service.ts+++ b/packages/server/src/services/workspace-files-service.ts@@ -63,6 +63,13 @@ export interface WorkspaceFileReadOptions {maxBytes?: number;}+/** One existing file from a batch existence check, with the time it was last written. */+export interface WorkspaceFileStat {+ /** The path as it was asked for, not its canonical form. */+ rel: string;+ mtimeMs: number;+}+export class WorkspaceFilesService {/** Canonical path (realpath) of the Workspace root; 404 if it doesn't exist. */private async realBase(workspace: string): Promise<string> {@@ -180,18 +187,28 @@ export class WorkspaceFilesService {* leaking containment details. Returns the deduplicated existing items in input order.*/async statExisting(workspace: string, rels: string[]): Promise<string[]> {+ return (await this.statExistingWithMtime(workspace, rels)).map((f) => f.rel);+ }++ /**+ * The same check, with each file's modification time — for the caller that has to tell a+ * file this run wrote from one that was already sitting in the Workspace (the messaging+ * bridge sends only the former). Statting is what the check already does, so the time+ * costs nothing extra.+ */+ async statExistingWithMtime(workspace: string, rels: string[]): Promise<WorkspaceFileStat[]> {const unique = [...new Set(rels)];- const exists = await Promise.all(- unique.map(async (rel) => {+ const stats = await Promise.all(+ unique.map(async (rel): Promise<WorkspaceFileStat | null> => {try {const stat = await fs.stat(await this.resolveRead(workspace, rel));- return stat.isFile();+ return stat.isFile() ? { rel, mtimeMs: stat.mtimeMs } : null;} catch {- return false;+ return null;}}),);- return unique.filter((_, i) => exists[i]);+ return stats.filter((s): s is WorkspaceFileStat => s !== null);}/**diff --git a/packages/server/test/messaging-telegram.test.ts b/packages/server/test/messaging-telegram.test.tsindex 0a084faa..efa3b51a 100644--- a/packages/server/test/messaging-telegram.test.ts+++ b/packages/server/test/messaging-telegram.test.ts@@ -6,14 +6,18 @@* probe surfacing the bot username), the channel-agnostic GET the channel-aware editor* reads, and the connector's long-poll loop through a fake Bot API transport — offset* advancement, the connect-time backlog drain, inbound routing as plain user input,- * per-message mirroring with one reply thread per run in groups, 4096-safe chunking,+ * an inbound photo (largest variant, caption as the message text, a failed download+ * degrading to a notice), per-message mirroring with one reply thread per run in groups,+ * mentioned files leaving as a photo or a document, 4096-safe chunking,* non-text notices, poll-failure status flips, and the conflict path a second poller* produces (the 409 backoff, the connect-time webhook clear, and the actionable text the* transport maps a 409 to). No test opens real network.*/+import fs from "node:fs/promises";+import path from "node:path";import { afterEach, beforeEach, describe, expect, it } from "vitest";import { approvalDecision, assistantText, toolCall } from "@prismshadow/penguin-core";-import type { ApproveFn, OmniMessage, TextPayload } from "@prismshadow/penguin-core";+import type { ApproveFn, OmniMessage } from "@prismshadow/penguin-core";import type {FeishuBindingResponse,MessagingBindingsResponse,@@ -22,16 +26,21 @@ import type {} from "../src/api/types.js";import type { SessionRow } from "../src/db/repos/sessions.js";import type { RuntimeSession } from "../src/runtime/session-manager.js";+import { INLINE_IMAGE_MAX_BYTES } from "../src/services/attachment-limits.js";import {MESSAGING_APPROVAL_NOTICE,MESSAGING_TEXT_ONLY_NOTICE,MESSAGING_TEST_MESSAGE,+ messagingImageFailedNotice,} from "../src/runtime/messaging/bridge.js";+import { collectUnderCap } from "../src/runtime/messaging/media.js";import type {TelegramBotClient,TelegramBotUser,TelegramCredentials,+ TelegramFileBytes,TelegramTransport,+ TelegramTransportOpts,TelegramUpdate,TelegramWebhookInfo,} from "../src/runtime/messaging/telegram-api.js";@@ -66,8 +75,38 @@ interface SentMessage {threadId?: number;}+/**+ * One picture or attachment that reached the channel. Byte count rather than the bytes:+ * what the assertions care about is which file went where, in what order, and that the+ * caps let it through.+ */+interface SentMedia {+ kind: "photo" | "document";+ chatId: string;+ fileName: string;+ bytes: number;+}++/** Everything one client sent, in order — the ordering of text against media is the point. */+type Sent = SentMessage | SentMedia;++/** One file download the bridge asked for, cap included. */+interface FileFetch {+ fileId: string;+ maxBytes: number;+}++/** The bytes as a stream, so the fake reads them through the real capped reader. */+async function* oneChunk(bytes: Buffer): AsyncGenerator<Uint8Array> {+ yield bytes;+}++/** A JPEG's magic bytes plus a little payload: enough for a data URL to be asserted verbatim. */+const PHOTO_BYTES = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x11, 0x22, 0x33]);+class FakeBotClient implements TelegramBotClient {- readonly sends: SentMessage[] = [];+ readonly sends: Sent[] = [];+ readonly fileFetches: FileFetch[] = [];/** Every sendMessage ATTEMPT, failures included — `sends` records only what got through. */sendCalls = 0;getMeCalls = 0;@@ -127,6 +166,36 @@ class FakeBotClient implements TelegramBotClient {});}+ async sendPhoto(args: { chatId: string; fileName: string; data: Buffer }): Promise<void> {+ if (this.t.failMediaSend !== null) throw new Error(this.t.failMediaSend);+ this.sends.push({+ kind: "photo",+ chatId: args.chatId,+ fileName: args.fileName,+ bytes: args.data.length,+ });+ }++ async sendDocument(args: { chatId: string; fileName: string; data: Buffer }): Promise<void> {+ if (this.t.failMediaSend !== null) throw new Error(this.t.failMediaSend);+ this.sends.push({+ kind: "document",+ chatId: args.chatId,+ fileName: args.fileName,+ bytes: args.data.length,+ });+ }++ async getFileBytes(args: FileFetch): Promise<TelegramFileBytes> {+ this.fileFetches.push(args);+ if (this.t.failFileFetch !== null) throw new Error(this.t.failFileFetch);+ // The cap is enforced through the REAL machinery the transport uses, not a hand-written+ // imitation of it (see the Feishu suite's note: an imitation is free to disagree with+ // production about which failure this is).+ const data = await collectUnderCap(oneChunk(this.t.fileBytes), args.maxBytes, "The image");+ return { data, filePath: this.t.filePath };+ }+getUpdates(args: {offset?: number;timeoutSec: number;@@ -190,6 +259,14 @@ class FakeTelegramTransport {failThreadedSendCode = 400;/** Fails this many upcoming getUpdates calls. */failPolls = 0;+ /** Non-null makes getFileBytes throw with this message (an expired file_id, a network fault). */+ failFileFetch: string | null = null;+ /** Non-null makes an outbound photo/document send throw (the channel refusing an upload). */+ failMediaSend: string | null = null;+ /** What a file download resolves to; oversize bytes exercise the cap. */+ fileBytes: Buffer = PHOTO_BYTES;+ /** The path the Bot API served the bytes from — its extension names the type. */+ filePath = "photos/file_7.jpg";/** The webhook registered on the bot; the empty string means none, as the Bot API encodes it. */webhookUrl = "";/** getMe's `can_read_all_group_messages` (true = privacy mode OFF); undefined = the field is absent. */@@ -226,7 +303,8 @@ class FakeTelegramTransport {return client;}- allSends(): SentMessage[] {+ /** Everything sent through any client, in order (texts and media interleaved). */+ allSends(): Sent[] {return this.clients.flatMap((c) => c.sends);}@@ -234,6 +312,16 @@ class FakeTelegramTransport {allSendCalls(): number {return this.clients.reduce((n, c) => n + c.sendCalls, 0);}++ /** Just the text messages — for the assertions that read `.text`. */+ allTexts(): SentMessage[] {+ return this.allSends().filter((s): s is SentMessage => !("kind" in s));+ }++ /** Every file download asked of any client, in order. */+ allFileFetches(): FileFetch[] {+ return this.clients.flatMap((c) => c.fileFetches);+ }}/**@@ -251,6 +339,11 @@ class FakeFeishuSdk implements FeishuSdk {async botOpenId() {return null;},+ async fetchMessageImage(): Promise<never> {+ throw new Error("the feishu side of these tests never carries an image");+ },+ async sendImage() {},+ async sendFile() {},};}async connect(_creds: FeishuCredentials, handlers: FeishuEventHandlers) {@@ -269,10 +362,40 @@ function privateText(text: string, messageId = 1): TelegramUpdate["message"] {};}+/**+ * A private-chat photo message: the Bot API sends the same picture as several size+ * variants, thumbnails first, and `caption` carries whatever the user typed with it.+ */+function privatePhoto(caption?: string, messageId = 1): TelegramUpdate["message"] {+ return {+ message_id: messageId,+ chat: { id: 42424242, type: "private" },+ photo: [+ { file_id: "thumb-90", width: 90, height: 67, file_size: 1_200 },+ { file_id: "mid-320", width: 320, height: 240, file_size: 9_800 },+ { file_id: "full-1280", width: 1280, height: 960, file_size: 120_400 },+ ],+ ...(caption !== undefined ? { caption } : {}),+ from: { first_name: "Ada" },+ };+}++/**+ * One input part as the fake Sessions record it. Deliberately a loose shape rather than+ * core's payload union: a run's input mixes composer text with `image_url` parts, and the+ * assertions read one field of whichever arrived.+ */+interface InputPayload {+ type?: string;+ role?: string;+ text?: string;+ image_url?: string;+}+/** Fake Session: records each run's input payloads and replies with a fixed assistant text. */function echoFakeSession(sessionId: string,- runs: TextPayload[][],+ runs: InputPayload[][],reply = "Reply text",): RuntimeSession {return {@@ -283,7 +406,7 @@ function echoFakeSession(steer: () => false,skipReconnectWait: () => false,async *run(input: OmniMessage[]) {- runs.push(input.map((m) => m.payload as TextPayload));+ runs.push(input.map((m) => m.payload as InputPayload));yield assistantText(reply);},async *compact() {},@@ -366,7 +489,7 @@ describe("telegram binding routes and connector loop", () => {let api: ReturnType<typeof apiClient>;let fake: FakeTelegramTransport;let projectId: string;- let runs: TextPayload[][];+ let runs: InputPayload[][];/** The server log, so a delivery that succeeded only in a degraded form is observable. */let logLines: string[];@@ -929,7 +1052,7 @@ describe("telegram binding routes and connector loop", () => {fake.push(forumText("status?"));await waitFor(() => fake.allSends().length === 3, 5000);- const sends = fake.allSends();+ const sends = fake.allTexts();// Every one of them, not just the threaded first.expect(sends.map((x) => x.threadId)).toEqual([TOPIC, TOPIC, TOPIC]);expect(sends.map((x) => x.text)).toEqual(["first", "second", "third"]);@@ -945,12 +1068,12 @@ describe("telegram binding routes and connector loop", () => {fake.push(forumText("in the first topic", 201, TOPIC));await waitFor(() => runs.length === 1);await waitFor(() => fake.allSends().length === 1);- expect(fake.allSends()[0]!.threadId).toBe(TOPIC);+ expect(fake.allTexts()[0]!.threadId).toBe(TOPIC);fake.push(forumText("now over here", 202, 77));await waitFor(() => runs.length === 2);await waitFor(() => fake.allSends().length === 2);- expect(fake.allSends()[1]!.threadId).toBe(77);+ expect(fake.allTexts()[1]!.threadId).toBe(77);expect(t.deps.messagingRepo.find(SID, "telegram")?.lastChatId).toBe(`${FORUM_CHAT}:77`);});@@ -965,15 +1088,15 @@ describe("telegram binding routes and connector loop", () => {fake.push(forumText("do the thing", 203));// The notice is a bare send with no inbound message to thread onto — the shape that had// nothing at all to put it back in the topic.- await waitFor(() => fake.allSends().some((x) => x.text === MESSAGING_APPROVAL_NOTICE), 5000);- const notice = fake.allSends().find((x) => x.text === MESSAGING_APPROVAL_NOTICE)!;+ await waitFor(() => fake.allTexts().some((x) => x.text === MESSAGING_APPROVAL_NOTICE), 5000);+ const notice = fake.allTexts().find((x) => x.text === MESSAGING_APPROVAL_NOTICE)!;expect(notice.threadId).toBe(TOPIC);expect(notice.replyTo).toBeUndefined();// The test message reads the stored chat straight off the row, so it is the path that// would hand an encoded string to the API if the connector were not the one parsing it.expect((await api.post(`${BASE(SID2)}/test-message`, {})).status).toBe(200);- const test = fake.allSends().find((x) => x.text === MESSAGING_TEST_MESSAGE)!;+ const test = fake.allTexts().find((x) => x.text === MESSAGING_TEST_MESSAGE)!;expect(test.chatId).toBe(String(FORUM_CHAT));expect(test.threadId).toBe(TOPIC);@@ -994,7 +1117,7 @@ describe("telegram binding routes and connector loop", () => {fake.failThreadedSend = "sendMessage failed: Bad Request: message thread not found (code 400)";fake.push(forumText("still there?", 204));await waitFor(() => fake.allSends().length === 3, 5000);- const sends = fake.allSends();+ const sends = fake.allTexts();expect(sends.map((x) => x.text)).toEqual(["first", "second", "third"]);expect(sends.map((x) => x.threadId)).toEqual([undefined, undefined, undefined]);expect(sends.every((x) => x.chatId === String(FORUM_CHAT))).toBe(true);@@ -1052,7 +1175,7 @@ describe("telegram binding routes and connector loop", () => {fake.push(forumText("written in General", 205, null));await waitFor(() => runs.length === 1);await waitFor(() => fake.allSends().length === 1);- expect(fake.allSends()[0]!.threadId).toBeUndefined();+ expect(fake.allTexts()[0]!.threadId).toBeUndefined();// A send that carried no topic is never retried — one round trip, as before this existed.expect(fake.allSendCalls()).toBe(1);// The stored chat is the bare id every row written before this feature already holds, so@@ -1081,7 +1204,7 @@ describe("telegram binding routes and connector loop", () => {});await waitFor(() => runs.length === 1);await waitFor(() => fake.allSends().length === 1);- expect(fake.allSends()[0]!.threadId).toBeUndefined();+ expect(fake.allTexts()[0]!.threadId).toBeUndefined();expect(fake.allSendCalls()).toBe(1);expect(t.deps.messagingRepo.find(SID, "telegram")?.lastChatId).toBe("123456789");});@@ -1099,7 +1222,7 @@ describe("telegram binding routes and connector loop", () => {});await waitFor(() => runs.length === 1);await waitFor(() => fake.allSends().length === 1);- expect(fake.allSends()[0]!.threadId).toBeUndefined();+ expect(fake.allTexts()[0]!.threadId).toBeUndefined();expect(fake.allSendCalls()).toBe(1);expect(t.deps.messagingRepo.find(SID, "telegram")?.lastChatId).toBe("-1002233445566");});@@ -1117,7 +1240,7 @@ describe("telegram binding routes and connector loop", () => {});await waitFor(() => runs.length === 1);await waitFor(() => fake.allSends().length === 1);- expect(fake.allSends()[0]!.threadId).toBeUndefined();+ expect(fake.allTexts()[0]!.threadId).toBeUndefined();expect(fake.allSendCalls()).toBe(1);expect(t.deps.messagingRepo.find(SID, "telegram")?.lastChatId).toBe(String(FORUM_CHAT));});@@ -1134,7 +1257,7 @@ describe("telegram binding routes and connector loop", () => {).run(String(FORUM_CHAT), SID, "telegram");expect((await api.post(`${BASE(SID)}/test-message`, {})).status).toBe(200);- const sent = fake.allSends().find((x) => x.text === MESSAGING_TEST_MESSAGE)!;+ const sent = fake.allTexts().find((x) => x.text === MESSAGING_TEST_MESSAGE)!;expect(sent.chatId).toBe(String(FORUM_CHAT));expect(sent.threadId).toBeUndefined();});@@ -1149,13 +1272,14 @@ describe("telegram binding routes and connector loop", () => {from: { first_name: "Ada" },});await waitFor(() => fake.allSends().length > 0);- expect(fake.allSends()[0]!.text).toBe(MESSAGING_TEXT_ONLY_NOTICE);+ expect(fake.allTexts()[0]!.text).toBe(MESSAGING_TEXT_ONLY_NOTICE);expect(runs).toHaveLength(0);});- it("non-text messages get the bilingual text-only reply and start no task", async () => {+ it("a message that is neither text nor photo gets the bilingual notice and starts no task", async () => {await bindEnabled(SID);- // A photo message: a `message` update with no `text` field.+ // A sticker (or voice, or a document — inbound files stay out of scope): a `message`+ // update with neither `text` nor `photo`.fake.push({message_id: 21,chat: { id: 42424242, type: "private" },@@ -1171,6 +1295,109 @@ describe("telegram binding routes and connector loop", () => {expect(t.deps.messagingRepo.find(SID, "telegram")?.lastChatId).toBe("42424242");});+ it("a captioned document still gets the not-supported notice and starts no task", async () => {+ await bindEnabled(SID);+ // The common shape of this: a picture dragged into Telegram uncompressed arrives as a+ // `document`, caption and all, with no `photo` array. The caption is not this message+ // on its own — the file it describes is never downloaded — so falling back to it would+ // run the model on "summarize this for me" with nothing attached.+ fake.push({+ message_id: 22,+ chat: { id: 42424242, type: "private" },+ caption: "summarize this for me",+ from: { first_name: "Ada" },+ });+ await waitFor(() => fake.allSends().length > 0);+ expect(fake.allSends()).toContainEqual({+ chatId: "42424242",+ text: MESSAGING_TEXT_ONLY_NOTICE,+ });+ expect(runs).toHaveLength(0);+ });++ it("an inbound photo becomes an image_url part, downloaded at its largest size", async () => {+ await bindEnabled(SID);+ fake.push(privatePhoto(undefined, 31));+ await waitFor(() => runs.length === 1);+ // No caption: the picture is the whole message, and no text is invented around it.+ expect(runs[0]).toHaveLength(1);+ const part = runs[0]![0]!;+ expect(part.type).toBe("image_url");+ expect(part.image_url).toBe(`data:image/jpeg;base64,${PHOTO_BYTES.toString("base64")}`);+ // The largest variant, not the thumbnails the Bot API lists first, and under the+ // shared inline-image ceiling (which is also Telegram's own bot download ceiling).+ expect(fake.allFileFetches()).toEqual([+ { fileId: "full-1280", maxBytes: INLINE_IMAGE_MAX_BYTES },+ ]);+ });++ it("a photo's caption rides along as the message's text, ahead of the image", async () => {+ await bindEnabled(SID);+ fake.push(privatePhoto("what is wrong with this chart?", 32));+ await waitFor(() => runs.length === 1);+ // Text first, then the image — the web composer's order for a message with an attachment.+ expect(runs[0]!.map((p) => p.type)).toEqual(["text", "image_url"]);+ expect(runs[0]![0]!.text).toBe("what is wrong with this chart?");+ expect(runs[0]![0]!.role).toBe("user");+ expect("sender" in runs[0]![0]!).toBe(false);+ expect(runs[0]![1]!.image_url).toBe(`data:image/jpeg;base64,${PHOTO_BYTES.toString("base64")}`);+ });++ it("strips this bot's own @mention off a photo's caption, as it does off a text message", async () => {+ await bindEnabled(SID);+ // Addressing a bot in a group means naming it, and a picture posted to a group is+ // addressed in its CAPTION — Telegram marks the span in `caption_entities`, the+ // caption's own copy of `entities`.+ fake.push({+ message_id: 34,+ chat: { id: -1002233445566, type: "supergroup" },+ photo: [{ file_id: "full-1280", width: 1280, height: 960 }],+ caption: "@penguin_test_bot what is wrong with this chart?",+ caption_entities: [{ type: "mention", offset: 0, length: 17 }],+ from: { first_name: "Ada" },+ });+ await waitFor(() => runs.length === 1);+ expect(runs[0]![0]!.text).toBe("what is wrong with this chart?");+ });++ it("a photo that cannot be downloaded degrades to a notice, caption and all", async () => {+ await bindEnabled(SID);+ fake.failFileFetch = "getFile failed: file is temporarily unavailable";+ fake.push(privatePhoto("have a look", 33));+ await waitFor(() => fake.allSends().length > 0);+ expect(fake.allSends()).toContainEqual({+ chatId: "42424242",+ text: messagingImageFailedNotice("getFile failed: file is temporarily unavailable"),+ });+ // The caption does NOT run on its own: a question about a picture the model never+ // received would be answered confidently about nothing.+ expect(runs).toHaveLength(0);+ });++ it("sends the files the reply mentions as a photo and a document, after its text", async () => {+ // The Feishu suite carries the whole outbound-file rule (existence, caps, containment);+ // this is the channel half of it — a picture must reach Telegram as a photo, so it+ // renders in the chat, and everything else as a document.+ const ws = await fs.mkdtemp(path.join(t.root, "ws-"));+ await fs.writeFile(path.join(ws, "chart.png"), PHOTO_BYTES);+ await fs.writeFile(path.join(ws, "notes.md"), "hello");+ const row2 = sessionRowOf(SID2, projectId);+ row2.workspace = ws;+ t.deps.sessionsRepo.insert(row2);+ t.deps.manager.adopt(+ row2,+ echoFakeSession(SID2, runs, "Rendered `chart.png`, notes in `notes.md`."),+ );+ await bindEnabled(SID2, "7000000004:test-secret-FFFF-6666");+ fake.push(privateText("go"));+ await waitFor(() => fake.allSends().length === 3);+ expect(fake.allSends()).toEqual([+ { chatId: "42424242", text: "Rendered `chart.png`, notes in `notes.md`." },+ { kind: "photo", chatId: "42424242", fileName: "chart.png", bytes: PHOTO_BYTES.length },+ { kind: "document", chatId: "42424242", fileName: "notes.md", bytes: 5 },+ ]);+ });+it("relays each completed assistant message separately, in order, as it completes", async () => {const row2 = sessionRowOf(SID2, projectId);t.deps.sessionsRepo.insert(row2);@@ -1219,7 +1446,7 @@ describe("telegram binding routes and connector loop", () => {await bindEnabled(SID2, "7000000002:test-secret-DDDD-4444");fake.push(privateText("long one"));await waitFor(() => fake.allSends().length >= 3);- const sends = fake.allSends();+ const sends = fake.allTexts();expect(sends.map((s) => s.text.length)).toEqual([4000, 4000, 1000]);expect(sends.every((s) => s.chatId === "42424242")).toBe(true);expect(sends.map((s) => s.text).join("")).toBe("x".repeat(9000));@@ -1351,6 +1578,11 @@ class ConflictBotClient implements TelegramBotClient {return { url: this.t.webhookUrl };}async sendMessage(): Promise<void> {}+ getFileBytes(): Promise<TelegramFileBytes> {+ throw new Error("this outage suite never downloads a file");+ }+ async sendPhoto(): Promise<void> {}+ async sendDocument(): Promise<void> {}getUpdates(args: {offset?: number;timeoutSec: number;@@ -1557,20 +1789,20 @@ describe("telegram transport error mapping", () => {body: unknown,run: (bot: TelegramBotClient) => Promise<unknown>,): Promise<string> {- const original = globalThis.fetch;- globalThis.fetch = (async () =>+ // Through the transport's own fetch seam, not the global: the production transport+ // calls undici's fetch on purpose (see telegram-api's TelegramFetch), so replacing+ // `globalThis.fetch` would leave it talking to the real Bot API.+ const stub = (async () =>new Response(JSON.stringify(body), {status: 409,headers: { "content-type": "application/json" },- })) as typeof fetch;+ })) as unknown as TelegramTransportOpts["fetch"];try {- const bot = createTelegramTransport().createClient({ botToken: TOKEN });+ const bot = createTelegramTransport({ fetch: stub }).createClient({ botToken: TOKEN });await run(bot);return "";} catch (err) {return err instanceof Error ? err.message : String(err);- } finally {- globalThis.fetch = original;}}diff --git a/packages/server/test/messaging-wire.test.ts b/packages/server/test/messaging-wire.test.tsnew file mode 100644index 00000000..8bb343a5--- /dev/null+++ b/packages/server/test/messaging-wire.test.ts@@ -0,0 +1,571 @@+/**+ * Protocol tests for the two messaging adapters, at the boundary each one actually calls:+ * the Lark SDK's HTTP instance, and `fetch`.+ *+ * These exist because the suites next door could not have caught the two bugs that reached+ * a user. Those suites substitute a hand-written implementation of *our own* seam+ * (FeishuSdk, TelegramTransport), which proves the bridge drives the seam correctly and+ * proves nothing whatever about whether the adapter behind it speaks the real protocol —+ * every wire detail is stubbed out along with the wire. Both shipped bugs lived in that+ * gap: an image download whose refusal reason was silently discarded, and an upload path no+ * test had ever run against a real response shape.+ *+ * So the fake here is pushed down one layer, to the transport itself:+ *+ * - **Feishu**: `createLarkSdk({ httpInstance })` hands the real SDK a stand-in for axios,+ * so the SDK's own URL building, `:path` filling, param serialization, payload formatting+ * and response unwrapping all run for real. The stub must reproduce what the SDK's own+ * response interceptor does to an axios response — return `resp.data` (the parsed body),+ * or `{data, headers}` when the call asked for `$return_headers` — because that is the+ * contract the SDK's generated methods are written against. Errors are thrown in axios's+ * shape, `{response: {status, data}}`, and for a `responseType: "stream"` request the+ * error body is a stream too, which is the whole of bug 1.+ * - **Telegram**: the Bot API is plain HTTPS, so the stub is `globalThis.fetch`, and the+ * assertions are on the URLs, the multipart field names and the error text.+ *+ * No test opens a socket.+ */+import { createServer } from "node:http";+import type { AddressInfo } from "node:net";+import { Readable } from "node:stream";+import { Agent, getGlobalDispatcher, setGlobalDispatcher } from "undici";+import type { Dispatcher } from "undici";+import { afterEach, describe, expect, it } from "vitest";+import { createLarkSdk } from "../src/runtime/messaging/feishu-sdk.js";+import { createTelegramTransport } from "../src/runtime/messaging/telegram-api.js";+import type {+ TelegramTransport,+ TelegramTransportOpts,+} from "../src/runtime/messaging/telegram-api.js";+import {+ MessagingMediaTooLargeError,+ MessagingPermissionError,+} from "../src/runtime/messaging/media.js";++const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x01, 0x02, 0x03]);+const CREDS = { appId: "cli_wire", appSecret: "secret", baseDomain: "https://open.feishu.cn" };++/** One request as the stub saw it, before the SDK's response handling. */+interface WireCall {+ method?: string;+ url?: string;+ params?: unknown;+ data?: unknown;+ contentType?: unknown;+}++/**+ * What a stubbed route answers with: a parsed body, a stream, an axios-shaped throw, or+ * nothing at all — the request the API accepts and never answers.+ */+type Answer =+ | { body: unknown }+ | { stream: Buffer; headers?: Record<string, string> }+ | { status: number; streamError: unknown }+ | { stall: true };++/**+ * A stand-in for the axios instance the Lark SDK talks to, reproducing its response+ * interceptor (see the file header). `routes` answers by URL.+ */+function larkHttp(routes: (url: string) => Answer): {+ http: unknown;+ calls: WireCall[];+} {+ const calls: WireCall[] = [];+ const answer = (url: string, config?: Record<string, unknown>): unknown => {+ const found = routes(url);+ if ("stall" in found) return new Promise<never>(() => {});+ if ("body" in found) return found.body;+ if ("stream" in found) {+ const data = Readable.from([found.stream]);+ // $return_headers is what the download asks for; the interceptor pairs body + headers.+ return config?.$return_headers === true+ ? { data, headers: found.headers ?? {} }+ : (data as unknown);+ }+ const err = new Error(`Request failed with status code ${found.status}`) as Error & {+ response?: unknown;+ };+ err.response = { status: found.status, data: found.streamError };+ throw err;+ };+ return {+ calls,+ http: {+ // The SDK's TokenManager posts the token endpoint through the same instance.+ post: (url: string) => {+ calls.push({ method: "post", url });+ return Promise.resolve(answer(url));+ },+ request: (config: Record<string, unknown>) => {+ const headers = config.headers as Record<string, unknown> | undefined;+ calls.push({+ method: config.method as string,+ url: config.url as string,+ params: config.params,+ data: config.data,+ contentType: headers?.["Content-Type"],+ });+ return Promise.resolve(answer(config.url as string, config));+ },+ },+ };+}++/** The tenant-token exchange every Lark call makes first. */+const TOKEN_ANSWER: Answer = {+ body: { code: 0, msg: "ok", tenant_access_token: "t-abc", expire: 7200 },+};++describe("feishu adapter against the SDK's HTTP boundary", () => {+ it("downloads a message image from the resource endpoint and reads the type off the bytes", async () => {+ const { http, calls } = larkHttp((url) =>+ url.includes("tenant_access_token")+ ? TOKEN_ANSWER+ : // The header lies about the type on purpose: the bytes decide.+ { stream: PNG, headers: { "content-type": "application/octet-stream" } },+ );+ const client = await createLarkSdk({ httpInstance: http }).createClient(CREDS);+ const out = await client.fetchMessageImage({+ messageId: "om_wire_1",+ fileKey: "img_v2_wire",+ maxBytes: 20 * 1024 * 1024,+ });+ expect(out.data.equals(PNG)).toBe(true);+ expect(out.mimeType).toBe("image/png");+ // The message id and the image key ride in the PATH, and the resource type in a query+ // param — the shape no seam-level fake can check.+ const call = calls.at(-1)!;+ expect(call.method).toBe("GET");+ expect(call.url).toBe(+ "https://open.feishu.cn/open-apis/im/v1/messages/om_wire_1/resources/img_v2_wire",+ );+ expect(call.params).toEqual({ type: "image" });+ });++ it("reports the API's own refusal reason, which arrives as a STREAM (the shipped bug)", async () => {+ // A Feishu app that receives messages happily is still refused here until the resource+ // read scope is granted. Because the request asks for a stream, the ERROR body is a+ // stream too — reading `err.response.data.msg` finds nothing and leaves only "Request+ // failed with status code 403", which is what made the first bug report unactionable.+ const denial = {+ code: 99991672,+ msg: "Access denied. app has no permission to access resource",+ };+ const { http } = larkHttp((url) =>+ url.includes("tenant_access_token")+ ? TOKEN_ANSWER+ : { status: 403, streamError: Readable.from([Buffer.from(JSON.stringify(denial))]) },+ );+ const client = await createLarkSdk({ httpInstance: http }).createClient(CREDS);+ await expect(+ client.fetchMessageImage({ messageId: "om_x", fileKey: "img_x", maxBytes: 1024 * 1024 }),+ ).rejects.toThrow("Access denied. app has no permission to access resource (code 99991672)");+ });++ it("falls back to the generic text when the error body is not a Feishu envelope", async () => {+ const { http } = larkHttp((url) =>+ url.includes("tenant_access_token")+ ? TOKEN_ANSWER+ : { status: 502, streamError: Readable.from([Buffer.from("<html>bad gateway</html>")]) },+ );+ const client = await createLarkSdk({ httpInstance: http }).createClient(CREDS);+ await expect(+ client.fetchMessageImage({ messageId: "om_x", fileKey: "img_x", maxBytes: 1024 }),+ ).rejects.toThrow("Request failed with status code 502");+ });++ it("refuses a download past the cap as a size error, not as a failure", async () => {+ const { http } = larkHttp((url) =>+ url.includes("tenant_access_token") ? TOKEN_ANSWER : { stream: Buffer.alloc(4096) },+ );+ const client = await createLarkSdk({ httpInstance: http }).createClient(CREDS);+ await expect(+ client.fetchMessageImage({ messageId: "om_x", fileKey: "img_x", maxBytes: 1024 }),+ ).rejects.toBeInstanceOf(MessagingMediaTooLargeError);+ });++ it("reports the scopes to grant and the console link when the app lacks a permission", async () => {+ // The live failure: an app that receives messages happily is refused the upload until+ // one of these is granted. Feishu names both the scopes and a per-app grant URL in its+ // own `msg`, and the CODE is what identifies the case — the prose is localized.+ const denial = {+ code: 99991672,+ msg:+ "Access denied. One of the following scopes is required: [im:resource:upload, im:resource]. " ++ "应用尚未开通所需的应用身份权限:[im:resource:upload, im:resource],点击链接申请并开通任一权限即可:" ++ "https://open.feishu.cn/app/cli_wire/auth?q=im:resource:upload,im:resource&op_from=openapi&token_type=tenant",+ };+ const { http } = larkHttp((url) =>+ url.includes("tenant_access_token") ? TOKEN_ANSWER : { status: 403, streamError: denial },+ );+ const client = await createLarkSdk({ httpInstance: http }).createClient(CREDS);+ const err = await client+ .sendImage("oc_wire", { fileName: "chart.png", data: PNG })+ .then(() => null)+ .catch((e: unknown) => e);+ expect(err).toBeInstanceOf(MessagingPermissionError);+ const denied = err as MessagingPermissionError;+ expect(denied.scopes).toEqual(["im:resource:upload", "im:resource"]);+ expect(denied.grantUrl).toBe(+ "https://open.feishu.cn/app/cli_wire/auth?q=im:resource:upload,im:resource&op_from=openapi&token_type=tenant",+ );+ // The scope list and the link, and nothing else: the raw SDK error carries the request+ // config, which is where the app secret lives.+ expect(denied.message).not.toContain("secret");+ });++ it("reads a stream error's own code and msg, not the HTTP status (the second shipped bug)", async () => {+ // `messageResource.get` is fetched as a stream, so a REFUSAL arrives as a stream too —+ // Feishu's reason sits unread inside it, and reading the error straight off yields only+ // "Request failed with status code 400". `log_id` rides along because it is the first+ // thing Feishu support asks for.+ const body = { code: 234043, msg: "message id is invalid", log_id: "0214abc" };+ const { http } = larkHttp((url) =>+ url.includes("tenant_access_token")+ ? TOKEN_ANSWER+ : { status: 400, streamError: Readable.from([Buffer.from(JSON.stringify(body))]) },+ );+ const client = await createLarkSdk({ httpInstance: http }).createClient(CREDS);+ await expect(+ client.fetchMessageImage({ messageId: "om_x", fileKey: "img_x", maxBytes: 1024 }),+ ).rejects.toThrow("message id is invalid (code 234043, log_id 0214abc)");+ });++ it("carries the grant link out of a stream error too, so an inbound refusal is fixable", async () => {+ const denial = {+ code: 99991672,+ msg:+ "Access denied. One of the following scopes is required: [im:resource]. " ++ "点击链接申请并开通:https://open.feishu.cn/app/cli_wire/auth?q=im:resource&op_from=openapi",+ };+ const { http } = larkHttp((url) =>+ url.includes("tenant_access_token")+ ? TOKEN_ANSWER+ : {+ status: 403,+ streamError: Readable.from([Buffer.from(JSON.stringify(denial))]),+ },+ );+ const client = await createLarkSdk({ httpInstance: http }).createClient(CREDS);+ const err = await client+ .fetchMessageImage({ messageId: "om_x", fileKey: "img_x", maxBytes: 1024 })+ .then(() => null)+ .catch((e: unknown) => e);+ expect(err).toBeInstanceOf(MessagingPermissionError);+ expect((err as MessagingPermissionError).scopes).toEqual(["im:resource"]);+ expect((err as MessagingPermissionError).grantUrl).toBe(+ "https://open.feishu.cn/app/cli_wire/auth?q=im:resource&op_from=openapi",+ );+ });++ it("labels bytes that are not an image by the header, and PNG only as a last resort", async () => {+ // The reverse of the test above it: the sniff is inconclusive, so the header decides —+ // and where the header says nothing usable either, a data URL still needs some type.+ const notAnImage = Buffer.from("this is not an image at all");+ const { http } = larkHttp((url) =>+ url.includes("tenant_access_token")+ ? TOKEN_ANSWER+ : { stream: notAnImage, headers: { "content-type": "image/gif; charset=binary" } },+ );+ const client = await createLarkSdk({ httpInstance: http }).createClient(CREDS);+ const byHeader = await client.fetchMessageImage({+ messageId: "om_x",+ fileKey: "img_x",+ maxBytes: 1024,+ });+ expect(byHeader.mimeType).toBe("image/gif");++ const bare = larkHttp((url) =>+ url.includes("tenant_access_token")+ ? TOKEN_ANSWER+ : { stream: notAnImage, headers: { "content-type": "application/octet-stream" } },+ );+ const client2 = await createLarkSdk({ httpInstance: bare.http }).createClient(CREDS);+ const lastResort = await client2.fetchMessageImage({+ messageId: "om_x",+ fileKey: "img_x",+ maxBytes: 1024,+ });+ expect(lastResort.mimeType).toBe("image/png");+ });++ it("gives every call a deadline, so a request that never answers cannot wedge the chain", async () => {+ // The SDK's own transport is a bare `axios.create()` with no timeout. Every outbound+ // message of a Session goes out on one serial chain, so a request the API accepts and+ // never answers parks every later reply, notice and file for that Session — with no+ // error record and no status change — until the server restarts.+ let stalled = true;+ const { http } = larkHttp((url) => {+ if (url.includes("tenant_access_token")) return TOKEN_ANSWER;+ if (stalled) return { stall: true };+ return { body: { code: 0, msg: "success", data: {} } };+ });+ const client = await createLarkSdk({ httpInstance: http, timeoutMs: 40 }).createClient(CREDS);+ await expect(+ client.fetchMessageImage({ messageId: "om_x", fileKey: "img_x", maxBytes: 1024 }),+ ).rejects.toThrow(/timed out/);+ // And the caller is free again: what was queued behind the stall still goes out.+ stalled = false;+ await expect(client.sendText("oc_wire", "still working")).resolves.toBeUndefined();+ });++ it("uploads a picture, then sends the returned key as an image message", async () => {+ // The upload endpoints resolve to their INNER `data` object rather than the `{code,msg}`+ // envelope the JSON endpoints return — a difference invisible to a seam-level fake, and+ // the reason this path had never actually been run against a real response shape.+ const { http, calls } = larkHttp((url) => {+ if (url.includes("tenant_access_token")) return TOKEN_ANSWER;+ if (url.endsWith("/im/v1/images")) {+ return { body: { code: 0, msg: "success", data: { image_key: "img_v2_up" } } };+ }+ if (url.endsWith("/im/v1/messages")) return { body: { code: 0, msg: "success", data: {} } };+ throw new Error(`unstubbed ${url}`);+ });+ const client = await createLarkSdk({ httpInstance: http }).createClient(CREDS);+ await client.sendImage("oc_wire", { fileName: "chart.png", data: PNG });+ const upload = calls.find((c) => String(c.url).endsWith("/im/v1/images"))!;+ expect(upload.contentType).toBe("multipart/form-data");+ expect(upload.data).toMatchObject({ image_type: "message" });+ expect((upload.data as { image: Buffer }).image.equals(PNG)).toBe(true);+ const sent = calls.find((c) => String(c.url).endsWith("/im/v1/messages"))!;+ expect(sent.data).toEqual({+ receive_id: "oc_wire",+ content: JSON.stringify({ image_key: "img_v2_up" }),+ msg_type: "image",+ });+ });++ it("uploads other files under the category the client previews them by", async () => {+ const { http, calls } = larkHttp((url) => {+ if (url.includes("tenant_access_token")) return TOKEN_ANSWER;+ if (url.endsWith("/im/v1/files")) {+ return { body: { code: 0, msg: "success", data: { file_key: "file_v2_up" } } };+ }+ return { body: { code: 0, msg: "success", data: {} } };+ });+ const client = await createLarkSdk({ httpInstance: http }).createClient(CREDS);+ await client.sendFile("oc_wire", { fileName: "report.pdf", data: Buffer.from("%PDF-") });+ await client.sendFile("oc_wire", { fileName: "notes.md", data: Buffer.from("hi") });+ const uploads = calls.filter((c) => String(c.url).endsWith("/im/v1/files"));+ // A known category renders a preview in the client; everything else is a plain stream.+ expect(uploads.map((c) => (c.data as { file_type: string }).file_type)).toEqual([+ "pdf",+ "stream",+ ]);+ expect((uploads[1]!.data as { file_name: string }).file_name).toBe("notes.md");+ const sent = calls.filter((c) => String(c.url).endsWith("/im/v1/messages"));+ expect(sent[0]!.data).toMatchObject({+ msg_type: "file",+ content: JSON.stringify({ file_key: "file_v2_up" }),+ });+ });++ it("names the file when an upload comes back without a key", async () => {+ // A refused upload resolves to a `data`-less body, so the failure is a MISSING key+ // rather than a thrown error — the adapter has to notice that itself.+ const { http } = larkHttp((url) =>+ url.includes("tenant_access_token")+ ? TOKEN_ANSWER+ : { body: { code: 234020, msg: "image size exceeded" } },+ );+ const client = await createLarkSdk({ httpInstance: http }).createClient(CREDS);+ await expect(client.sendImage("oc_wire", { fileName: "chart.png", data: PNG })).rejects.toThrow(+ /chart\.png returned no image_key/,+ );+ });+});++describe("telegram adapter against the fetch boundary", () => {+ const TOKEN = "7000000001:SECRET-TOKEN-VALUE";+ const PHOTO = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x11, 0x22]);+ const DOC = Buffer.from("hello from the workspace");++ /** A recorded stub, handed to the transport through its own seam rather than to the global. */+ interface FetchStub {+ urls: string[];+ bodies: unknown[];+ transport: TelegramTransport;+ }++ /** Records every request and answers by URL. */+ function stubFetch(answer: (url: string) => Response | Promise<Response>): FetchStub {+ const urls: string[] = [];+ const bodies: unknown[] = [];+ const fetchImpl = ((url: string | URL, init?: RequestInit) => {+ urls.push(String(url));+ bodies.push(init?.body);+ return Promise.resolve(answer(String(url)));+ }) as unknown as TelegramTransportOpts["fetch"];+ return { urls, bodies, transport: createTelegramTransport({ fetch: fetchImpl }) };+ }++ const okJson = (result: unknown): Response =>+ new Response(JSON.stringify({ ok: true, result }), {+ headers: { "content-type": "application/json" },+ });++ it("downloads a photo in two hops: getFile, then the FILE endpoint", async () => {+ const stub = stubFetch((url) =>+ url.includes("/getFile")+ ? okJson({ file_path: "photos/file_7.jpg", file_size: PHOTO.length })+ : new Response(PHOTO, { headers: { "content-type": "image/jpeg" } }),+ );+ const bot = stub.transport.createClient({ botToken: TOKEN });+ const got = await bot.getFileBytes({ fileId: "full-1280", maxBytes: 20 * 1024 * 1024 });+ expect(got.data.equals(PHOTO)).toBe(true);+ expect(got.filePath).toBe("photos/file_7.jpg");+ // The second hop is /file/bot<token>/<path> — a different endpoint from the methods,+ // and the detail most easily got wrong.+ expect(stub.urls[0]).toBe(`https://api.telegram.org/bot${TOKEN}/getFile`);+ expect(stub.urls[1]).toBe(`https://api.telegram.org/file/bot${TOKEN}/photos/file_7.jpg`);+ });++ it("never puts the bot token in an error, though the download URL embeds it", async () => {+ // Transport failure first.+ const stub = stubFetch(() => {+ throw Object.assign(new Error("fetch failed"), { cause: new Error("ECONNREFUSED") });+ });+ const bot = stub.transport.createClient({ botToken: TOKEN });+ await expect(bot.getFileBytes({ fileId: "f", maxBytes: 1024 })).rejects.toThrow(+ /getFile failed/,+ );+ await expect(bot.getFileBytes({ fileId: "f", maxBytes: 1024 })).rejects.not.toThrow(+ /SECRET-TOKEN-VALUE/,+ );+ // Then an HTTP failure on the file endpoint itself, whose URL carries the token.+ const stub2 = stubFetch((url) =>+ url.includes("/getFile")+ ? okJson({ file_path: "photos/f.jpg" })+ : new Response("nope", { status: 404 }),+ );+ const err = await stub2.transport+ .createClient({ botToken: TOKEN })+ .getFileBytes({ fileId: "f", maxBytes: 1024 })+ .then(() => null)+ .catch((e: Error) => e);+ expect(err?.message).toBe("file download failed: HTTP 404");+ expect(err?.message).not.toContain("SECRET");+ });++ it("refuses a file the API already says is over the cap, as a size error", async () => {+ const stub = stubFetch(() =>+ okJson({ file_path: "photos/f.jpg", file_size: 30 * 1024 * 1024 }),+ );+ const bot = stub.transport.createClient({ botToken: TOKEN });+ await expect(+ bot.getFileBytes({ fileId: "f", maxBytes: 20 * 1024 * 1024 }),+ ).rejects.toBeInstanceOf(MessagingMediaTooLargeError);+ });++ it("posts a picture as multipart sendPhoto, and other files as sendDocument", async () => {+ const stub = stubFetch(() => okJson({}));+ const { urls, bodies } = stub;+ const bot = stub.transport.createClient({ botToken: TOKEN });+ await bot.sendPhoto({ chatId: "42424242", fileName: "chart.png", data: PHOTO });+ await bot.sendDocument({+ chatId: "-1002233445566",+ fileName: "notes.md",+ data: Buffer.from("hi"),+ });++ expect(urls[0]!.endsWith("/sendPhoto")).toBe(true);+ expect(urls[1]!.endsWith("/sendDocument")).toBe(true);+ const photo = bodies[0] as FormData;+ // The field name is the API's, not ours, and the file must arrive with its name on it.+ expect(photo.get("chat_id")).toBe("42424242");+ const file = photo.get("photo") as File;+ expect(file.name).toBe("chart.png");+ expect(file.size).toBe(PHOTO.length);+ const doc = bodies[1] as FormData;+ expect(doc.get("chat_id")).toBe("-1002233445566");+ expect((doc.get("document") as File).name).toBe("notes.md");+ });++ it("really posts multipart, driving the transport's OWN fetch at a real socket", async () => {+ // The one assertion no stub can make. The startup entry replaces `globalThis.fetch`+ // with undici's (net/proxy.ts), and undici's fetch brand-checks a FormData body against+ // its OWN class — so a global `new FormData()` fell through to `String(body)` and the+ // Bot API received the 17 bytes `[object FormData]` as text/plain: "there is no+ // document in the request". Every upload failed in production and none did in CI, where+ // `globalThis.fetch` is still the runtime's own and the pairing happens to match.+ //+ // So this test replaces neither: it takes the transport exactly as production builds+ // it, points undici's global dispatcher at a local server, and reads what arrived.+ const received: { path: string; contentType?: string; body: Buffer }[] = [];+ const server = createServer((req, res) => {+ const chunks: Buffer[] = [];+ req.on("data", (c: Buffer) => chunks.push(c));+ req.on("end", () => {+ received.push({+ path: req.url ?? "",+ ...(req.headers["content-type"] !== undefined+ ? { contentType: req.headers["content-type"] }+ : {}),+ body: Buffer.concat(chunks),+ });+ res.writeHead(200, { "content-type": "application/json" });+ res.end(JSON.stringify({ ok: true, result: {} }));+ });+ });+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));+ const port = (server.address() as AddressInfo).port;+ const previous = getGlobalDispatcher();+ const inner = new Agent();+ // Everything undici's fetch dispatches goes to the local server instead, request bytes+ // untouched — the Bot API host is not configurable, and should not become so for a test.+ const redirect: Pick<Dispatcher, "dispatch" | "close" | "destroy"> = {+ dispatch: (opts, handler) =>+ inner.dispatch({ ...opts, origin: `http://127.0.0.1:${port}` }, handler),+ close: () => inner.close(),+ destroy: () => inner.destroy(),+ };+ setGlobalDispatcher(redirect as Dispatcher);+ try {+ const bot = createTelegramTransport().createClient({ botToken: TOKEN });+ await bot.sendDocument({ chatId: "42424242", fileName: "notes.md", data: DOC });+ await bot.sendPhoto({ chatId: "42424242", fileName: "chart.png", data: PHOTO });+ } finally {+ setGlobalDispatcher(previous);+ await inner.close();+ await new Promise<void>((resolve) => server.close(() => resolve()));+ }++ expect(received).toHaveLength(2);+ const [doc, photo] = received;+ expect(doc!.path).toBe(`/bot${TOKEN}/sendDocument`);+ expect(doc!.contentType).toMatch(/^multipart\/form-data;/);+ const docBody = doc!.body.toString("latin1");+ expect(docBody).toContain('name="document"');+ expect(docBody).toContain('filename="notes.md"');+ expect(docBody).toContain(DOC.toString("latin1"));+ // The failure this guards against was a 17-byte `[object FormData]` body.+ expect(doc!.body.length).toBeGreaterThan(100);+ expect(docBody).not.toContain("[object FormData]");++ expect(photo!.path).toBe(`/bot${TOKEN}/sendPhoto`);+ expect(photo!.contentType).toMatch(/^multipart\/form-data;/);+ const photoBody = photo!.body.toString("latin1");+ expect(photoBody).toContain('name="photo"');+ expect(photoBody).toContain('filename="chart.png"');+ expect(photoBody).toContain(PHOTO.toString("latin1"));+ });++ it("surfaces a Bot API refusal of an upload with its description", async () => {+ const stub = stubFetch(+ () =>+ new Response(+ JSON.stringify({ ok: false, description: "PHOTO_INVALID_DIMENSIONS", error_code: 400 }),+ {+ status: 400,+ headers: { "content-type": "application/json" },+ },+ ),+ );+ const bot = stub.transport.createClient({ botToken: TOKEN });+ await expect(+ bot.sendPhoto({ chatId: "1", fileName: "chart.png", data: PHOTO }),+ ).rejects.toThrow("sendPhoto failed: PHOTO_INVALID_DIMENSIONS (code 400)");+ });+});diff --git a/packages/server/test/messaging.test.ts b/packages/server/test/messaging.test.tsindex 280a4908..2b79c69a 100644--- a/packages/server/test/messaging.test.ts+++ b/packages/server/test/messaging.test.ts@@ -6,14 +6,21 @@* save/enable split — PUT persists credentials only, POST /state owns the connection —* 409s, authz split, cascade on session delete), and the bridge's routing through a fake* Feishu SDK — inbound text becomes an ordinary user task- * exactly as if typed in the composer (no marker, no special sender; queueIfBusy),- * non-text gets the bilingual text-only reply, each completed assistant message mirrors on+ * exactly as if typed in the composer (no marker, no special sender; queueIfBusy), an+ * inbound image becomes the composer's `image_url` part (and a download that fails or+ * exceeds the inline-image cap degrades to a notice instead of a half-message),+ * anything else gets the bilingual not-supported reply, each completed assistant message+ * mirrors on* its own to the last known chat as soon as it completes (the run's first one threaded onto- * the inbound message in groups), an approval_request sends the one-line notice behind- * whatever is already going out, and a binding with `linePerMessage` set delivers a reply one- * message per non-blank line — paced, and with a refused message costing only itself — while- * an unset one is byte-for-byte the original single message. No test opens real network.+ * the inbound message in groups), the files the reply MENTIONED follow it (existing ones+ * only, pictures as pictures, capped by count and by size, escapes refused by the Workspace+ * file service), an approval_request sends the one-line notice behind whatever is already+ * going out, and a binding with `linePerMessage` set delivers a reply one message per+ * non-blank line — paced, and with a refused message costing only itself — while an unset+ * one is byte-for-byte the original single message. No test opens real network.*/+import fs from "node:fs/promises";+import path from "node:path";import { afterEach, beforeEach, describe, expect, it } from "vitest";import {assistantText,@@ -22,26 +29,47 @@ import {compactionEnd,toolCall,} from "@prismshadow/penguin-core";-import type { ApproveFn, OmniMessage, TextPayload } from "@prismshadow/penguin-core";+import type { ApproveFn, OmniMessage } from "@prismshadow/penguin-core";import type { FeishuBindingResponse, FeishuTestResponse } from "../src/api/types.js";import type { SessionRow } from "../src/db/repos/sessions.js";import type { RuntimeSession } from "../src/runtime/session-manager.js";+import { INLINE_IMAGE_MAX_BYTES } from "../src/services/attachment-limits.js";import {MESSAGING_APPROVAL_NOTICE,MESSAGING_MAX_LINE_MESSAGES,+ MESSAGING_OUTBOUND_FILE_MAX_COUNT,+ MESSAGING_OUTBOUND_IMAGE_MAX_BYTES,MESSAGING_TEST_MESSAGE,MESSAGING_TEXT_CHUNK_CHARS,MESSAGING_TEXT_ONLY_NOTICE,MessagingBridge,chunkMessagingText,+ messagingFileFailedNotice,+ messagingFilePermissionNotice,+ messagingFileTooLargeNotice,+ messagingFilesMissingNotice,+ messagingFilesSkippedNotice,+ messagingImageBudgetNotice,+ messagingImageFailedNotice,+ messagingImagePermissionNotice,+ messagingImageTooLargeNotice,splitReplyLines,} from "../src/runtime/messaging/bridge.js";import type { MessagingTaskRunner } from "../src/runtime/messaging/bridge.js";import { FeishuConnector } from "../src/runtime/messaging/feishu-connector.js";+import {+ MessagingPermissionError,+ collectUnderCap,+ imageMimeOfName,+ isImageFileName,+ sniffImageMime,+} from "../src/runtime/messaging/media.js";+import { replyFileMentions } from "../src/runtime/messaging/reply-files.js";import type {FeishuApiClient,FeishuCredentials,FeishuEventHandlers,+ FeishuImageData,FeishuInboundEvent,FeishuSdk,} from "../src/runtime/messaging/feishu-sdk.js";@@ -62,10 +90,41 @@ interface SentText {text: string;}+/**+ * One picture or attachment that reached the channel. Byte count rather than the bytes:+ * what the assertions care about is which file went where, in what order, and that the+ * caps let it through.+ */+interface SentMedia {+ kind: "image" | "file";+ target: string;+ fileName: string;+ bytes: number;+}++/** Everything one client sent, in order — the ordering of text against media is the point. */+type Sent = SentText | SentMedia;++/** One image download the bridge asked for, cap included (the fake stands in for the SDK adapter). */+interface ImageFetch {+ messageId: string;+ fileKey: string;+ maxBytes: number;+}++/** The bytes as a stream, so the fakes read them through the real capped reader. */+async function* oneChunk(bytes: Buffer): AsyncGenerator<Uint8Array> {+ yield bytes;+}++/** A PNG's magic bytes plus a little payload: enough for a data URL to be asserted verbatim. */+const IMAGE_BYTES = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x01, 0x02, 0x03]);+class FakeClient implements FeishuApiClient {- readonly sends: SentText[] = [];+ readonly sends: Sent[] = [];/** When each send was recorded, parallel to `sends`: what the pacing test measures. */readonly sentAt: number[] = [];+ readonly imageFetches: ImageFetch[] = [];checks = 0;constructor(readonly creds: FeishuCredentials,@@ -97,6 +156,34 @@ class FakeClient implements FeishuApiClient {if (this.sdk.stallBotOpenId) return new Promise<never>(() => {});return this.sdk.botOpenId;}+ async fetchMessageImage(args: ImageFetch): Promise<FeishuImageData> {+ this.imageFetches.push(args);+ if (this.sdk.failImageFetchWith !== null) throw this.sdk.failImageFetchWith;+ if (this.sdk.failImageFetch !== null) throw new Error(this.sdk.failImageFetch);+ // The cap is enforced through the REAL machinery the adapter uses, not a hand-written+ // imitation of it: a fake free to throw its own error shape is a fake free to disagree+ // with production about which failure this is (it did, once).+ const data = await collectUnderCap(oneChunk(this.sdk.imageBytes), args.maxBytes, "The image");+ return { data, mimeType: "image/png" };+ }+ async sendImage(chatId: string, file: { fileName: string; data: Buffer }): Promise<void> {+ this.sdk.failMediaSendOnce();+ this.sends.push({+ kind: "image",+ target: chatId,+ fileName: file.fileName,+ bytes: file.data.length,+ });+ }+ async sendFile(chatId: string, file: { fileName: string; data: Buffer }): Promise<void> {+ this.sdk.failMediaSendOnce();+ this.sends.push({+ kind: "file",+ target: chatId,+ fileName: file.fileName,+ bytes: file.data.length,+ });+ }}class FakeConnection {@@ -147,6 +234,24 @@ class FakeSdk implements FeishuSdk {createClientGate: Promise<void> | null = null;/** How many createClient calls the gate has held. */gated = 0;+ /** Non-null makes fetchMessageImage throw with this message (a dead image_key, a network fault). */+ failImageFetch: string | null = null;+ /** Non-null makes it throw THIS — for the failure shapes that carry data, not just text. */+ failImageFetchWith: Error | null = null;+ /** What an image download resolves to; oversize bytes exercise the cap. */+ imageBytes: Buffer = IMAGE_BYTES;+ /** Fails this many upcoming outbound image/file sends (the channel refusing an upload). */+ failMediaSends = 0;+ /** Non-null makes EVERY media send throw this — for the failure shapes that carry data. */+ failMediaSendWith: Error | null = null;+ /** Consumes one scheduled media-send failure, throwing when there is one. */+ failMediaSendOnce(): void {+ if (this.failMediaSendWith !== null) throw this.failMediaSendWith;+ if (this.failMediaSends > 0) {+ this.failMediaSends -= 1;+ throw new Error("upload rejected");+ }+ }async createClient(creds: FeishuCredentials): Promise<FeishuApiClient> {if (this.createClientGate !== null) {this.gated++;@@ -162,14 +267,22 @@ class FakeSdk implements FeishuSdk {handlers.onReady?.();return conn;}- /** All texts sent through any client, in order. */- allSends(): SentText[] {+ /** Everything sent through any client, in order (texts and media interleaved). */+ allSends(): Sent[] {return this.clients.flatMap((c) => c.sends);}/** Their timestamps, in the same order. */allSentAt(): number[] {return this.clients.flatMap((c) => c.sentAt);}+ /** Just the text messages — for the assertions that read `.text`. */+ allTexts(): SentText[] {+ return this.allSends().filter((s): s is SentText => s.kind === "send" || s.kind === "reply");+ }+ /** Every image download asked of any client, in order. */+ allImageFetches(): ImageFetch[] {+ return this.clients.flatMap((c) => c.imageFetches);+ }lastConnection(): FakeConnection {const conn = this.connections.at(-1);if (!conn) throw new Error("no fake connection was opened");@@ -177,10 +290,22 @@ class FakeSdk implements FeishuSdk {}}+/**+ * One input part as the fake Sessions record it. Deliberately a loose shape rather than+ * core's payload union: a run's input mixes composer text with `image_url` parts, and the+ * assertions read one field of whichever arrived.+ */+interface InputPayload {+ type?: string;+ role?: string;+ text?: string;+ image_url?: string;+}+/** Fake Session: records each run's input payloads and replies with a fixed assistant text. */function echoFakeSession(sessionId: string,- runs: TextPayload[][],+ runs: InputPayload[][],reply = "Reply text",): RuntimeSession {return {@@ -191,7 +316,7 @@ function echoFakeSession(steer: () => false,skipReconnectWait: () => false,async *run(input: OmniMessage[]) {- runs.push(input.map((m) => m.payload as TextPayload));+ runs.push(input.map((m) => m.payload as InputPayload));yield assistantText(reply);},async *compact() {},@@ -375,12 +500,119 @@ describe("splitReplyLines", () => {});});+describe("messaging media helpers", () => {+ it("classifies file names by extension, case-insensitively, and leaves SVG a file", () => {+ expect(imageMimeOfName("chart.PNG")).toBe("image/png");+ expect(imageMimeOfName("out/photo.jpeg")).toBe("image/jpeg");+ expect(isImageFileName("a.webp")).toBe(true);+ // Scriptable and unrenderable in both clients: it travels as an attachment.+ expect(isImageFileName("diagram.svg")).toBe(false);+ expect(isImageFileName("report.pdf")).toBe(false);+ expect(isImageFileName("Makefile")).toBe(false);+ });++ it("reads the type out of the bytes, which beats whatever a header claims", () => {+ expect(sniffImageMime(IMAGE_BYTES)).toBe("image/png");+ expect(sniffImageMime(Buffer.from([0xff, 0xd8, 0xff, 0xe0]))).toBe("image/jpeg");+ expect(sniffImageMime(Buffer.from("GIF89a"))).toBe("image/gif");+ // RIFF, a four-byte size field, then WEBP: the tag is split, so the sniff must skip it.+ const webp = Buffer.concat([Buffer.from("RIFF"), Buffer.alloc(4), Buffer.from("WEBPVP8 ")]);+ expect(sniffImageMime(webp)).toBe("image/webp");+ expect(sniffImageMime(Buffer.from("not an image"))).toBeNull();+ });++ it("stops a download at the byte that crosses the cap instead of buffering the rest", async () => {+ const chunks = async function* (sizes: number[]): AsyncGenerator<Uint8Array> {+ for (const size of sizes) yield Buffer.alloc(size, 0x7a);+ };+ expect((await collectUnderCap(chunks([4, 4, 2]), 10, "The image")).length).toBe(10);+ // The third chunk crosses: it is refused rather than collected and measured afterwards.+ await expect(collectUnderCap(chunks([4, 4, 4]), 10, "The image")).rejects.toThrow(+ /The image is larger than the/,+ );+ });++ it("lets a transfer that dies mid-stream fail, rather than returning the half it got", async () => {+ // The shape a real download fails in: the connection drops after some of the file has+ // already been buffered. Half an image handed on as a whole one would reach the model+ // as a corrupt picture and be answered anyway.+ const dies = async function* (): AsyncGenerator<Uint8Array> {+ yield Buffer.alloc(4, 0x7a);+ yield Buffer.alloc(4, 0x7a);+ throw new Error("socket hang up");+ };+ await expect(collectUnderCap(dies(), 1024, "The image")).rejects.toThrow("socket hang up");+ });+});++describe("replyFileMentions", () => {+ const WS = "/data/ws";+ /** Just the deliverable half: the resolvable mentions, in order. */+ const paths = (text: string, workspace = WS): (string | null)[] =>+ replyFileMentions(text, workspace)+ .map((m) => m.rel)+ .filter((rel) => rel !== null);++ // The regression that matters: this rule used to read inline-code spans only, which is+ // what the Web App's file card does. Applied to a chat it delivered almost nothing — a+ // model that writes a filename in a sentence, which is most of them, named no file at+ // all. Each line below is a way a reply really does hand a file over.+ it("finds a mentioned path however the reply happens to phrase it", () => {+ const cases: Array<[string, string[]]> = [+ ["Done — the chart is `chart.png`.", ["chart.png"]],+ ["Saved to `/data/ws/out/chart.png`.", ["out/chart.png"]],+ ["I've written the chart to chart.png for you.", ["chart.png"]],+ ["Saved it at /data/ws/out/chart.png — take a look.", ["out/chart.png"]],+ ["The report is report.md.", ["report.md"]],+ ["图表已生成:/data/ws/chart.png。", ["chart.png"]],+ ["已经把图表保存为 chart.png,请查收。", ["chart.png"]],+ ["Wrote **chart.png** to the workspace.", ["chart.png"]],+ ["See [the chart](chart.png).", ["chart.png"]],+ ["The chart (chart.png) is ready.", ["chart.png"]],+ ['Saved as "chart.png".', ["chart.png"]],+ ["- chart.png\n- report.md", ["chart.png", "report.md"]],+ // A leading dot is part of the path, not prose punctuation: stripping it turned+ // `./chart.png` into an absolute path outside the Workspace and `.eslintrc.json`+ // into a file that is not there.+ ["Saved to ./chart.png for you.", ["chart.png"]],+ ["See ./out/chart.png", ["out/chart.png"]],+ ["Config is in .eslintrc.json now.", [".eslintrc.json"]],+ ];+ for (const [text, expected] of cases) {+ expect(paths(text), text).toEqual(expected);+ }+ });++ it("still refuses what is not a Workspace file, which is what keeps the loose rule safe", () => {+ for (const text of [+ "See https://example.com/logo.png for the original.",+ "Check www.example.com/x.png.",+ "Upgraded to v1.2 and 3.14 today.",+ // Escapes are refused here as well as by the file service behind it.+ "Read ../../etc/passwd earlier.",+ "Compared against /etc/hostname just now.",+ "Config lives at ~/.penguinrc.toml.",+ ]) {+ expect(paths(text), text).toEqual([]);+ }+ });++ it("reads a Windows Workspace's path in either spelling, and dedupes on the result", () => {+ // core spells model-visible paths with "/" while path.join produces "\\"; the same file+ // named both ways is one file, and must not be sent twice.+ expect(paths("Wrote C:\\ws\\out\\chart.png just now.", "C:\\ws")).toEqual(["out/chart.png"]);+ expect(paths("Wrote C:/ws/out/chart.png, i.e. C:\\ws\\out\\chart.png.", "C:\\ws")).toEqual([+ "out/chart.png",+ ]);+ });+});+describe("messaging binding routes and bridge", () => {let t: TestApp;let api: ReturnType<typeof apiClient>;let fake: FakeSdk;let projectId: string;- let runs: TextPayload[][];+ let runs: InputPayload[][];/** Save credentials, then flip the toggle on — the two-step flow the flow tests need. */const bindEnabled = async (sid: string, body: Record<string, unknown> = PUT_BODY) => {@@ -397,6 +629,7 @@ describe("messaging binding routes and bridge", () => {new MessagingBridge({repo: t.deps.messagingRepo,sessions: t.deps.sessionsRepo,+ files: t.deps.workspaceFiles,channels: t.deps.channels,runner,connectors: [new FeishuConnector(fake)],@@ -780,16 +1013,16 @@ describe("messaging binding routes and bridge", () => {// the chat follows the run instead of receiving it as one block at the end.await waitFor(() => fake.allSends().length === 2);expect(t.deps.manager.statusOf(SID2)).toBe("running");- expect(fake.allSends().map((s) => s.text)).toEqual(["working on it", "still going"]);+ expect(fake.allTexts().map((s) => s.text)).toEqual(["working on it", "still going"]);release();await waitFor(() => fake.allSends().length === 3);// Order preserved, and no message carries another one's text: nothing was joined.- expect(fake.allSends().map((s) => s.text)).toEqual([+ expect(fake.allTexts().map((s) => s.text)).toEqual(["working on it","still going","here is the answer",]);- expect(fake.allSends().every((s) => !s.text.includes("\n\n"))).toBe(true);+ expect(fake.allTexts().every((s) => !s.text.includes("\n\n"))).toBe(true);expect(fake.allSends().every((s) => s.kind === "send" && s.target === "oc_chat_5")).toBe(true);});@@ -916,7 +1149,7 @@ describe("messaging binding routes and bridge", () => {await waitFor(() => fake.allSends().length === 3);// Splitting happens first, chunking after: the long line becomes two messages, and the// pieces reassemble into exactly the line that was sent.- expect(fake.allSends().map((s) => s.text)).toEqual([+ expect(fake.allTexts().map((s) => s.text)).toEqual(["head",long.slice(0, MESSAGING_TEXT_CHUNK_CHARS),long.slice(MESSAGING_TEXT_CHUNK_CHARS),@@ -928,7 +1161,7 @@ describe("messaging binding routes and bridge", () => {await bindReplying(lines.join("\n"), { appId: "cli_lines_cap", linePerMessage: true });await messageBot("oc_cap");await waitFor(() => fake.allSends().length === MESSAGING_MAX_LINE_MESSAGES);- const texts = fake.allSends().map((s) => s.text);+ const texts = fake.allTexts().map((s) => s.text);expect(texts.slice(0, -1)).toEqual(lines.slice(0, MESSAGING_MAX_LINE_MESSAGES - 1));// The tail rides the last message: the reply reaches the chat entire either way.expect(texts.at(-1)).toBe(lines.slice(MESSAGING_MAX_LINE_MESSAGES - 1).join("\n"));@@ -943,7 +1176,7 @@ describe("messaging binding routes and bridge", () => {fake.failSendAt = 3;await messageBot("oc_429");await waitFor(() => fake.allSends().length === 5);- expect(fake.allSends().map((s) => s.text)).toEqual(["l0", "l1", "l3", "l4", "l5"]);+ expect(fake.allTexts().map((s) => s.text)).toEqual(["l0", "l1", "l3", "l4", "l5"]);// The loss is recorded rather than swallowed (one row: the recorder dedupes a repeat of// the same code within its window).const errors = t.deps.db@@ -991,7 +1224,7 @@ describe("messaging binding routes and bridge", () => {await new Promise((resolve) => setTimeout(resolve, 10));release();await waitFor(() => fake.allSends().length === 4);- expect(fake.allSends().map((s) => s.text)).toEqual([+ expect(fake.allTexts().map((s) => s.text)).toEqual(["Line one."," Line two.","Line three.",@@ -1003,12 +1236,13 @@ describe("messaging binding routes and bridge", () => {it("the notices are not replies: linePerMessage never reaches them", async () => {await bindReplying(SPOKEN, { appId: "cli_lines_notice", linePerMessage: true });+ // A sticker: still out of scope, so it answers with the notice rather than running.await fake.lastConnection().fire({chatId: "oc_notice",chatType: "p2p",messageId: "om_notice",- messageType: "image",- content: JSON.stringify({ image_key: "img_1" }),+ messageType: "sticker",+ content: JSON.stringify({}),});await waitFor(() => fake.allSends().length > 0);// One send carrying the notice whole. The notices are single-line by construction, so@@ -1068,17 +1302,19 @@ describe("messaging binding routes and bridge", () => {content: JSON.stringify({ text: "summarize" }),});await waitFor(() => t.deps.manager.statusOf(SID2) === "idle");- expect(fake.allSends().map((s) => s.text)).toEqual(["the actual answer"]);+ expect(fake.allTexts().map((s) => s.text)).toEqual(["the actual answer"]);});- it("non-text messages get the bilingual text-only reply and start no task", async () => {+ it("a message that is neither text nor image gets the bilingual notice and starts no task", async () => {await bindEnabled(SID);+ // A file: inbound documents are deliberately out of scope, so they keep answering with+ // the notice — as do stickers, voice and video.await fake.lastConnection().fire({chatId: "oc_chat_1",chatType: "p2p",messageId: "om_2",- messageType: "image",- content: JSON.stringify({ image_key: "img_1" }),+ messageType: "file",+ content: JSON.stringify({ file_key: "file_1", file_name: "notes.pdf" }),});await waitFor(() => fake.allSends().length > 0);expect(fake.allSends()).toContainEqual({@@ -1091,6 +1327,166 @@ describe("messaging binding routes and bridge", () => {expect(t.deps.messagingRepo.find(SID, "feishu")?.lastChatId).toBe("oc_chat_1");});+ // —— Inbound images ————————————————————————————————————————————————————————+ // A picture pasted into the chat has to reach the model as the web composer's own input+ // shape: a base64 data URL in an `image_url` part. The download is lazy (a redelivery is+ // dropped before it happens) and capped by the server's inline-image ceiling.++ it("an inbound image becomes an image_url part carrying the downloaded bytes", async () => {+ await bindEnabled(SID);+ await fake.lastConnection().fire({+ chatId: "oc_chat_1",+ chatType: "p2p",+ messageId: "om_img_1",+ messageType: "image",+ content: JSON.stringify({ image_key: "img_v2_abc" }),+ });+ await waitFor(() => runs.length === 1);+ // Image only: no accompanying text is invented — a Feishu image message has no caption.+ expect(runs[0]).toHaveLength(1);+ const part = runs[0]![0]!;+ expect(part.type).toBe("image_url");+ expect(part.role).toBe("user");+ expect(part.image_url).toBe(`data:image/png;base64,${IMAGE_BYTES.toString("base64")}`);+ // Downloaded from the message that carried it, under the shared inline-image ceiling.+ expect(fake.allImageFetches()).toEqual([+ { messageId: "om_img_1", fileKey: "img_v2_abc", maxBytes: INLINE_IMAGE_MAX_BYTES },+ ]);+ // Nothing about the picture is announced back to the chat; the reply mirrors as usual.+ await waitFor(() => fake.allSends().length > 0);+ expect(fake.allTexts().map((s) => s.text)).toEqual(["Reply text"]);+ });++ it("an image the channel will not hand over reports the channel's OWN reason", async () => {+ await bindEnabled(SID);+ // The case that actually shipped broken: a Feishu app without the resource-read scope+ // refuses every image. The chat has to say THAT, not "too large or the download failed"+ // — one of those is a scope to go and grant, the other is unactionable.+ fake.failImageFetch = "Access denied. app has no permission to access resource (code 99991672)";+ await fake.lastConnection().fire({+ chatId: "oc_chat_1",+ chatType: "p2p",+ messageId: "om_img_2",+ messageType: "image",+ content: JSON.stringify({ image_key: "img_v2_gone" }),+ });+ await waitFor(() => fake.allSends().length > 0);+ const notice = fake.allTexts().at(-1)!.text;+ expect(notice).toBe(+ messagingImageFailedNotice(+ "Access denied. app has no permission to access resource (code 99991672)",+ ),+ );+ expect(notice).toContain("no permission to access resource");+ // A failure is somebody's fault and belongs in the error log, not only in a chat+ // bubble — with the channel's reason, so it is diagnosable from the dashboard.+ const recorded = imageFetchErrors();+ expect(recorded).toHaveLength(1);+ expect(recorded[0]).toContain("no permission to access resource");+ expect(runs).toHaveLength(0);+ });++ it("an image over the inline-image cap says so, with the limit, and is not an error record", async () => {+ await bindEnabled(SID);+ // One byte past the ceiling: the cap refuses it, and the user fixes that by sending+ // something smaller — a different notice from a failure, and nobody's fault.+ fake.imageBytes = Buffer.alloc(INLINE_IMAGE_MAX_BYTES + 1, 0x41);+ await fake.lastConnection().fire({+ chatId: "oc_chat_1",+ chatType: "p2p",+ messageId: "om_img_3",+ messageType: "image",+ content: JSON.stringify({ image_key: "img_v2_huge" }),+ });+ await waitFor(() => fake.allSends().length > 0);+ expect(fake.allTexts().at(-1)!.text).toBe(messagingImageTooLargeNotice());+ expect(messagingImageTooLargeNotice()).toContain("20MB");+ // Nobody's fault: the chat notice is the whole report, and the error log stays clean.+ expect(imageFetchErrors()).toHaveLength(0);+ expect(runs).toHaveLength(0);+ });++ it("an image the app has no permission to download says which scope to grant, and where", async () => {+ await bindEnabled(SID);+ // The same live failure as the upload side, inbound: receiving a message and reading+ // the files in it are separate permissions on Feishu, so an app can take the message+ // and be refused the picture. The scope name and the console link are the whole fix.+ fake.failImageFetchWith = new MessagingPermissionError(+ ["im:resource"],+ "https://open.feishu.cn/app/cli_x/auth?q=im:resource",+ "Access denied (code 99991672)",+ );+ await fake.lastConnection().fire({+ chatId: "oc_chat_1",+ chatType: "p2p",+ messageId: "om_img_scope",+ messageType: "image",+ content: JSON.stringify({ image_key: "img_v2_denied" }),+ });+ await waitFor(() => fake.allSends().length > 0);+ expect(fake.allTexts().at(-1)!.text).toBe(+ messagingImagePermissionNotice(+ ["im:resource"],+ "https://open.feishu.cn/app/cli_x/auth?q=im:resource",+ ),+ );+ // Still an error record: somebody has to grant it, and the dashboard is where that is+ // noticed when nobody is watching the chat.+ expect(imageFetchErrors()).toHaveLength(1);+ expect(runs).toHaveLength(0);+ });++ it("bounds inbound imagery per binding, refusing the overflow with its own notice", async () => {+ // Per image the ceiling is the inline-image limit; in aggregate there was nothing. Every+ // accepted image is written into the conversation as base64 and read back whole on every+ // history page and every resume, so a pile of them is a Session that never recovers —+ // and this path has no authentication at all.+ await boot({ messagingInboundImageBudgetBytes: IMAGE_BYTES.length * 2 });+ await bindEnabled(SID);+ const sendImage = async (n: number) => {+ await fake.lastConnection().fire({+ chatId: "oc_chat_1",+ chatType: "p2p",+ messageId: `om_budget_${n}`,+ messageType: "image",+ content: JSON.stringify({ image_key: `img_v2_${n}` }),+ });+ };+ await sendImage(1);+ await waitFor(() => runs.length === 1);+ await sendImage(2);+ await waitFor(() => runs.length === 2);+ // The budget is spent: the third is refused, and refused BEFORE the transfer — the+ // download that would blow the window never happens.+ await sendImage(3);+ await waitFor(() => fake.allSends().some((x) => x.kind === "send"));+ await settle(80);+ expect(fake.allImageFetches()).toHaveLength(2);+ expect(runs).toHaveLength(2);+ expect(fake.allTexts().at(-1)!.text).toBe(messagingImageBudgetNotice());+ // And it is NOT the size notice: nothing is wrong with the picture, there have just+ // been too many, and the fix is to wait rather than to send a smaller one.+ expect(messagingImageBudgetNotice()).not.toBe(messagingImageTooLargeNotice());+ });++ it("a redelivered image is dropped before anything is downloaded", async () => {+ await bindEnabled(SID);+ const image = {+ chatId: "oc_chat_1",+ chatType: "p2p",+ messageId: "om_img_replay",+ messageType: "image",+ content: JSON.stringify({ image_key: "img_v2_replay" }),+ };+ await fake.lastConnection().fire(image);+ await waitFor(() => runs.length === 1);+ await fake.lastConnection().fire(image);+ await settle(80);+ // The whole point of a lazy handle: the replay costs no image transfer at all.+ expect(fake.allImageFetches()).toHaveLength(1);+ expect(runs).toHaveLength(1);+ });+it("an approval_request sends the waiting-for-approval notice", async () => {const row2 = sessionRowOf(SID2, projectId);row2.approvalMode = "always-ask";@@ -1105,7 +1501,7 @@ describe("messaging binding routes and bridge", () => {content: JSON.stringify({ text: "do something risky" }),});await waitFor(() =>- fake.allSends().some((s) => s.text === MESSAGING_APPROVAL_NOTICE && s.target === "oc_chat_2"),+ fake.allTexts().some((s) => s.text === MESSAGING_APPROVAL_NOTICE && s.target === "oc_chat_2"),);t.deps.manager.decideApproval(SID2, "tc-feishu", "allow");await waitFor(() => t.deps.manager.statusOf(SID2) === "idle");@@ -1259,10 +1655,10 @@ describe("messaging binding routes and bridge", () => {chatId: "oc_chat_1",chatType: "p2p",messageId: "om_sticker",- messageType: "image",- content: JSON.stringify({ image_key: "img_1" }),+ messageType: "sticker",+ content: JSON.stringify({}),});- await waitFor(() => fake.allSends().some((x) => x.text === MESSAGING_TEXT_ONLY_NOTICE));+ await waitFor(() => fake.allTexts().some((x) => x.text === MESSAGING_TEXT_ONLY_NOTICE));const status = await statusOf(SID);// The question this line answers is whether the channel is delivering anything, and a// sticker answers it. Stamping only what starts a Task would report a mute bot for a@@ -1361,7 +1757,7 @@ describe("messaging binding routes and bridge", () => {content: JSON.stringify({ text: "again" }),});await waitFor(() => runs.length === 2);- await waitFor(() => fake.allSends().some((x) => x.text === "Reply text"));+ await waitFor(() => fake.allTexts().some((x) => x.text === "Reply text"));// The record stands, whole. Clearing it on success would erase every failure that comes// and goes — a send right revoked for a minute, a rate limit — as soon as the next@@ -1459,7 +1855,7 @@ describe("messaging binding routes and bridge", () => {await waitFor(() => runs.length === 1);expect(runs[0]![0]!.text).toBe("帮我看看 build 好了没 🚀");// The run's own reply mirrors back; what must NOT appear is the no-words notice.- expect(fake.allSends().some((x) => x.text === MESSAGING_TEXT_ONLY_NOTICE)).toBe(false);+ expect(fake.allTexts().some((x) => x.text === MESSAGING_TEXT_ONLY_NOTICE)).toBe(false);});it("a message that is nothing but a mention starts no Task", async () => {@@ -1474,7 +1870,7 @@ describe("messaging binding routes and bridge", () => {// Nothing but the mention: no words to run a Task on, so it takes the same branch a// sticker does rather than spending a turn on a bare placeholder.await waitFor(() => fake.allSends().length === 1);- expect(fake.allSends()[0]!.text).toBe(MESSAGING_TEXT_ONLY_NOTICE);+ expect(fake.allTexts()[0]!.text).toBe(MESSAGING_TEXT_ONLY_NOTICE);expect(runs).toHaveLength(0);});@@ -1558,6 +1954,316 @@ describe("messaging binding routes and bridge", () => {expect(runs[0]![0]!.text).toBe("@PenguinHarness status?");});+ // —— Outbound files ————————————————————————————————————————————————————————+ // When a run ends, the files its reply MENTIONED follow the text into the chat — the Web+ // App's file card rule, applied to the chat: inline-code paths that resolve inside the+ // Workspace and actually exist. Containment and existence come from the same service the+ // Files panel reads through, so an escape is refused there, not by a second copy of the+ // rules living in the bridge.++ /** A real Workspace directory for the second Session (WorkspaceFilesService does real IO). */+ const makeWorkspace = (): Promise<string> => fs.mkdtemp(path.join(t.root, "ws-"));++ /** Binds a second Session over that Workspace, replying with a fixed text. */+ const bindWithWorkspace = async (+ workspace: string,+ reply: string,+ appId: string,+ ): Promise<void> => {+ const row = sessionRowOf(SID2, projectId);+ row.workspace = workspace;+ t.deps.sessionsRepo.insert(row);+ t.deps.manager.adopt(row, echoFakeSession(SID2, runs, reply));+ await bindEnabled(SID2, { ...PUT_BODY, appId });+ };++ /**+ * Messages of the image-download failures recorded for this app. Read straight off the+ * table: the bridge records with no Project (it knows a Session id), which is exactly the+ * shape ErrorsRepo's project-scoped queries filter out.+ */+ const imageFetchErrors = (): string[] =>+ t.deps.db+ .prepare("SELECT message FROM error_records WHERE code = 'messaging_image_fetch_failed'")+ .all()+ .map((r) => r.message as string);++ let asks = 0;+ /** Message the bound Session from the chat, and wait for the run to start AND finish. */+ const askAndSettle = async (): Promise<void> => {+ const before = runs.length;+ asks += 1;+ await fake.lastConnection().fire({+ chatId: "oc_chat_files",+ chatType: "p2p",+ messageId: `om_files_${asks}`,+ messageType: "text",+ content: JSON.stringify({ text: "do the thing" }),+ });+ await waitFor(() => runs.length > before);+ await waitFor(() => t.deps.manager.statusOf(SID2) === "idle");+ };++ it("sends the files the reply mentions, after its text, pictures as pictures", async () => {+ const ws = await makeWorkspace();+ await fs.mkdir(path.join(ws, "out"), { recursive: true });+ await fs.writeFile(path.join(ws, "out/chart.png"), IMAGE_BYTES);+ await fs.writeFile(path.join(ws, "notes.md"), "hello");+ await bindWithWorkspace(+ ws,+ "Done — the chart is `out/chart.png` and the write-up is `notes.md`.",+ "cli_files",+ );+ await askAndSettle();+ await waitFor(() => fake.allSends().length === 3);+ // Text first, then the files in the order the reply named them; a .png rides as an+ // image so it renders, everything else as an attachment.+ expect(fake.allSends()).toEqual([+ {+ kind: "send",+ target: "oc_chat_files",+ text: "Done — the chart is `out/chart.png` and the write-up is `notes.md`.",+ },+ { kind: "image", target: "oc_chat_files", fileName: "chart.png", bytes: IMAGE_BYTES.length },+ { kind: "file", target: "oc_chat_files", fileName: "notes.md", bytes: 5 },+ ]);+ });++ it("delivers a file the reply names in a plain sentence, with no inline code", async () => {+ // The end-to-end shape of the bug a user hit: everything downstream of extraction was+ // right, and a reply phrased the way models actually phrase it produced nothing.+ const ws = await makeWorkspace();+ await fs.writeFile(path.join(ws, "chart.png"), IMAGE_BYTES);+ await bindWithWorkspace(ws, "已经把图表保存为 chart.png,请查收。", "cli_bare_path");+ await askAndSettle();+ await waitFor(() => fake.allSends().length === 2);+ expect(fake.allSends()[1]).toEqual({+ kind: "image",+ target: "oc_chat_files",+ fileName: "chart.png",+ bytes: IMAGE_BYTES.length,+ });+ });++ it("mentions the same file twice and sends it once, however it is spelled", async () => {+ const ws = await makeWorkspace();+ await fs.writeFile(path.join(ws, "report.csv"), "a,b\n");+ // Once relative, once absolute: one file, so one send — deduplication is keyed on the+ // normalized path, not on the spelling.+ await bindWithWorkspace(+ ws,+ `See \`report.csv\` — full path \`${ws}/report.csv\`.`,+ "cli_files_dupe",+ );+ await askAndSettle();+ await waitFor(() => fake.allSends().length === 2);+ expect(fake.allSends().filter((s): s is SentMedia => s.kind === "file")).toEqual([+ { kind: "file", target: "oc_chat_files", fileName: "report.csv", bytes: 4 },+ ]);+ });++ it("names a mentioned path that does not exist rather than dropping it in silence", async () => {+ await bindWithWorkspace(+ await makeWorkspace(),+ "I would have written `out/missing.png`, but the run failed.",+ "cli_ghost",+ );+ await askAndSettle();+ await waitFor(() => fake.allSends().length === 2);+ await settle(80);+ // Existence is still the rule and nothing exists, so no file goes. What changed is+ // that the chat is told: a name in the reply that never arrives, with nothing anywhere+ // to say why, is how this feature reads as broken.+ expect(fake.allSends().map((s) => s.kind)).toEqual(["send", "send"]);+ expect(fake.allTexts().at(-1)!.text).toBe(messagingFilesMissingNotice(["out/missing.png"]));+ });++ it("says nothing at all about a reply that named no file", async () => {+ // The ordinary reply. The notice above must not become a line under every answer.+ await bindWithWorkspace(await makeWorkspace(), "All done, nothing to hand over.", "cli_quiet");+ await askAndSettle();+ await settle(80);+ expect(fake.allSends().map((s) => s.kind)).toEqual(["send"]);+ });++ it("sends a file the run wrote and stays silent about one that was already there", async () => {+ const ws = await makeWorkspace();+ await fs.writeFile(path.join(ws, "secrets.json"), "{}");+ await fs.writeFile(path.join(ws, "chart.png"), IMAGE_BYTES);+ // The file the run did not write is dated well before it started. The mention rule+ // alone would upload it: the reply is steerable by anyone in the chat, so "what is in+ // secrets.json?" answered with "I will not paste secrets.json here" would have made+ // the refusal itself the disclosure.+ const longAgo = new Date(Date.now() - 3_600_000);+ await fs.utimes(path.join(ws, "secrets.json"), longAgo, longAgo);+ await bindWithWorkspace(+ ws,+ "I won't paste `secrets.json` here. The chart is `chart.png`.",+ "cli_fresh",+ );+ await askAndSettle();+ await waitFor(() => fake.allSends().length === 2);+ await settle(80);+ // The chart rides along; the pre-existing file is not sent AND not announced — a reply+ // that mentions a file it read is the ordinary case, and naming every one of those+ // would bury the notices that matter.+ expect(fake.allSends()).toEqual([+ {+ kind: "send",+ target: "oc_chat_files",+ text: "I won't paste `secrets.json` here. The chart is `chart.png`.",+ },+ { kind: "image", target: "oc_chat_files", fileName: "chart.png", bytes: IMAGE_BYTES.length },+ ]);+ });++ it("refuses a path that leaves the Workspace, by `..` or through a symlink", async () => {+ const ws = await makeWorkspace();+ await fs.writeFile(path.join(ws, "..", "outside.txt"), "secret");+ // A symlink is the case a lexical check alone would miss: the name is inside the+ // Workspace and only its canonical target leaves. WorkspaceFilesService resolves it.+ // Creating one needs a privilege Windows does not always grant; without it the link+ // simply does not exist, and the two lexical escapes still carry the test there.+ await fs+ .symlink(path.join(ws, "..", "outside.txt"), path.join(ws, "linked.txt"))+ .catch(() => undefined);+ await bindWithWorkspace(+ ws,+ "Look at `../outside.txt`, `/etc/hostname` and `linked.txt`.",+ "cli_escape",+ );+ await askAndSettle();+ await waitFor(() => fake.allSends().length === 2);+ await settle(80);+ // Nothing leaves the Workspace; the escapes are reported as what they are here — paths+ // with no file behind them — in the reply's own spelling, never a normalization of it.+ expect(fake.allSends().map((s) => s.kind)).toEqual(["send", "send"]);+ // Both escapes are named, in the reply's own spelling: the lexical one, which never+ // resolves, and the symlink, which resolves to a name the file service then refuses.+ // (`/etc/hostname` carries no extension, so it is never a candidate in the first place.)+ expect(fake.allTexts().at(-1)!.text).toContain("../outside.txt");+ expect(fake.allTexts().at(-1)!.text).toContain("linked.txt");+ });++ it("classifies by the file the read reached, not by the name the reply spelled", async () => {+ const ws = await makeWorkspace();+ await fs.writeFile(path.join(ws, "report.pdf"), "%PDF-1.4");+ // The everyday "latest" pattern, entirely inside the Workspace: the mentioned name ends+ // in .png, the file behind it is a PDF. Classified by the mention, it would go to the+ // image endpoint under the image ceiling and arrive named report.pdf — which Telegram+ // refuses outright.+ const linked = await fs+ .symlink(path.join(ws, "report.pdf"), path.join(ws, "report.png"))+ .then(() => true)+ .catch(() => false);+ if (!linked) return; // a Windows runner without the create-symlink privilege+ await bindWithWorkspace(ws, "The latest render is `report.png`.", "cli_symlink");+ await askAndSettle();+ await waitFor(() => fake.allSends().length === 2);+ expect(fake.allSends()[1]).toEqual({+ kind: "file",+ target: "oc_chat_files",+ fileName: "report.pdf",+ bytes: 8,+ });+ });++ it("names an upload the app has no permission for, with the scopes and the grant link", async () => {+ const ws = await makeWorkspace();+ await fs.writeFile(path.join(ws, "notes.md"), "hi");+ await bindWithWorkspace(ws, "Written up in `notes.md`.", "cli_scope");+ // The live failure: an app that receives messages happily is refused the upload until+ // a resource scope is granted. That reached `error_records` and nowhere the person in+ // the chat could look, so the feature simply appeared not to work.+ fake.failMediaSendWith = new MessagingPermissionError(+ ["im:resource:upload", "im:resource"],+ "https://open.feishu.cn/app/cli_scope/auth?q=im:resource:upload",+ "Access denied (code 99991672)",+ );+ await askAndSettle();+ await waitFor(() => fake.allSends().length === 2);+ const notice = fake.allTexts().at(-1)!.text;+ expect(notice).toBe(+ messagingFilePermissionNotice(+ "notes.md",+ ["im:resource:upload", "im:resource"],+ "https://open.feishu.cn/app/cli_scope/auth?q=im:resource:upload",+ ),+ );+ // Both halves are what the user acts on: what to grant, and where.+ expect(notice).toContain("im:resource:upload");+ expect(notice).toContain("https://open.feishu.cn/app/cli_scope/auth");+ });++ it("caps the batch by count and names how many were left behind", async () => {+ const names = ["a.md", "b.md", "c.md", "d.md", "e.md", "f.md", "g.md"];+ const ws = await makeWorkspace();+ for (const name of names) await fs.writeFile(path.join(ws, name), name);+ await bindWithWorkspace(ws, `Wrote ${names.map((n) => `\`${n}\``).join(", ")}.`, "cli_many");+ await askAndSettle();+ await waitFor(() => fake.allSends().length === MESSAGING_OUTBOUND_FILE_MAX_COUNT + 2);+ const sent = fake.allSends().filter((s): s is SentMedia => s.kind === "file");+ expect(sent).toHaveLength(MESSAGING_OUTBOUND_FILE_MAX_COUNT);+ expect(sent.map((s) => s.fileName)).toEqual(names.slice(0, MESSAGING_OUTBOUND_FILE_MAX_COUNT));+ // The remainder is counted in the chat — a cap that drops things quietly is a bug.+ expect(fake.allSends().at(-1)).toEqual({+ kind: "send",+ target: "oc_chat_files",+ text: messagingFilesSkippedNotice(names.length - MESSAGING_OUTBOUND_FILE_MAX_COUNT),+ });+ });++ it("names an oversize file instead of sending it, and keeps sending the rest", async () => {+ const ws = await makeWorkspace();+ await fs.writeFile(+ path.join(ws, "huge.png"),+ Buffer.alloc(MESSAGING_OUTBOUND_IMAGE_MAX_BYTES + 1),+ );+ await fs.writeFile(path.join(ws, "small.md"), "ok");+ await bindWithWorkspace(ws, "Both `huge.png` and `small.md` are ready.", "cli_huge");+ await askAndSettle();+ await waitFor(() => fake.allSends().length === 3);+ expect(fake.allSends()[1]).toEqual({+ kind: "send",+ target: "oc_chat_files",+ text: messagingFileTooLargeNotice("huge.png", MESSAGING_OUTBOUND_IMAGE_MAX_BYTES),+ });+ // One refusal does not cancel the batch behind it.+ expect(fake.allSends()[2]).toEqual({+ kind: "file",+ target: "oc_chat_files",+ fileName: "small.md",+ bytes: 2,+ });+ });++ it("a failing upload is recorded, not thrown, and the next file still goes", async () => {+ const ws = await makeWorkspace();+ await fs.writeFile(path.join(ws, "one.md"), "1");+ await fs.writeFile(path.join(ws, "two.md"), "2");+ await bindWithWorkspace(ws, "`one.md` and `two.md`.", "cli_upload_fail");+ // Only the first upload fails: the batch behind it must carry on rather than unwind.+ fake.failMediaSends = 1;+ await askAndSettle();+ await waitFor(() => fake.allSends().length === 3);+ await settle(80);+ // The failure is named in the chat, with the channel's own reason: `error_records` is+ // not somewhere the person in the chat can look, so an upload that failed was the one+ // drop they could not see at all.+ expect(fake.allSends()[1]).toEqual({+ kind: "send",+ target: "oc_chat_files",+ text: messagingFileFailedNotice("one.md", "upload rejected"),+ });+ // And the batch behind it carries on rather than unwinding.+ expect(fake.allSends()[2]).toEqual({+ kind: "file",+ target: "oc_chat_files",+ fileName: "two.md",+ bytes: 1,+ });+ });+// —— Inbound deduplication ————————————————————————————————————————————————// A channel can hand the bridge the same message twice: a Feishu long connection// replays across a reconnect, and any connector that resumes an unconfirmed stream can@@ -1615,7 +2321,7 @@ describe("messaging binding routes and bridge", () => {await waitFor(() => fake.allSends().length === 1);await fake.lastConnection().fire(sticker);await settle(80);- expect(fake.allSends().filter((x) => x.text === MESSAGING_TEXT_ONLY_NOTICE)).toHaveLength(1);+ expect(fake.allTexts().filter((x) => x.text === MESSAGING_TEXT_ONLY_NOTICE)).toHaveLength(1);});it("bounds what it remembers: an id far enough back is forgotten rather than kept forever", async () => {@@ -1725,11 +2431,11 @@ describe("messaging binding routes and bridge", () => {await successor.start();await fake.lastConnection().fire(sticker);await settle(80);- expect(fake.allSends().filter((x) => x.text === MESSAGING_TEXT_ONLY_NOTICE)).toHaveLength(1);+ expect(fake.allTexts().filter((x) => x.text === MESSAGING_TEXT_ONLY_NOTICE)).toHaveLength(1);// Control: a sticker the binding has never seen still gets its notice.await fake.lastConnection().fire({ ...sticker, messageId: "om_sticker_after_restart" });await waitFor(- () => fake.allSends().filter((x) => x.text === MESSAGING_TEXT_ONLY_NOTICE).length === 2,+ () => fake.allTexts().filter((x) => x.text === MESSAGING_TEXT_ONLY_NOTICE).length === 2,);} finally {successor.stop();@@ -1894,7 +2600,7 @@ describe("a redelivered inbound message", () => {let t: TestApp;let api: ReturnType<typeof apiClient>;let fake: FakeSdk;- let runs: TextPayload[][];+ let runs: InputPayload[][];let clock: number;beforeEach(async () => {