feat(acp): bridge durable image prompts and replies

.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md
-2026-07-23-acp-automation-only-protocol.md: 56dcaf8b4327a008f26b884264958cac02d6541a
-2026-07-23-acp-automation-only-protocol.zh.md: a34e179a1d38c1867ea8165b149a9ec7716c1c0e
+2026-07-23-acp-automation-only-protocol.md: 3d13e3fb51819ef4f892f33f9c86554988576e36
+2026-07-23-acp-automation-only-protocol.zh.md: 224c1bd611aae23937f5610665c4bd316e15c425

.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.md

@@ -8,15 +8,17 @@ English | [中文](2026-07-23-acp-automation-only-protocol.zh.md)
 
 The ACP bridge had become a second interactive product UI. It translated durable events into editor cards, terminal metadata, diffs, plans, titles, reasoning, commands, modes, model and permission pickers, session navigation, and human elicitation. Those responsibilities duplicated the TUI and the Web client while coupling an automation transport to UI services, persistence queries, presentation policy, and editor-specific conventions.
 
-ACP still has one useful role: another agent or automated controller can start a harness process, create an isolated session, send text, receive the committed answer, cancel work, and answer a permission request. The out-of-process ACP subagent backend depends on that standard protocol boundary.
+ACP still has one useful role: another agent or automated controller can start a harness process, create an isolated session, send text or a narrowly supported inline image, receive the committed text/image answer, cancel work, and answer a permission request. The out-of-process ACP subagent backend depends on that standard protocol boundary.
 
 The snapshot suite complicates removal. Most ACP scenarios exercise the assembled agent backend rather than ACP presentation, so deleting the suite with the editor bridge would discard broad keyless behavioral coverage.
 
 ## Decision
 
-`@deepseek-ai/dsh-acp` is an automation transport under [`packages/acp/acp`](../../../../packages/acp/acp/README.md), outside the `ui` package group. Its public protocol is intentionally small: version negotiation, fresh text sessions with one in-flight prompt each, committed assistant text updates, per-session cancellation, concurrent sessions, and connection-owned teardown. Prompts carry the spec-required baseline only — text plus resource links flattened to bracketed textual references; the bridge rejects additional directories, MCP servers, beyond-baseline prompt content (image, audio, embedded resources), empty prompts, unknown sessions, and overlapping prompts.
+`@deepseek-ai/dsh-acp` is an automation transport under [`packages/acp/acp`](../../../../packages/acp/acp/README.md), outside the `ui` package group. Its public protocol is intentionally small: version negotiation, fresh sessions with one in-flight prompt each, committed assistant text/image updates, per-session cancellation, concurrent sessions, and connection-owned teardown. Prompts preserve text and supported raster images in wire order, while resource links flatten to bracketed textual references; the bridge rejects additional directories, MCP servers, audio, embedded resources, malformed or empty prompts, unknown sessions, and overlapping prompts.
 
-The bridge emits only committed `assistant/message` text. Reasoning, raw chunks, tool activity, todos, plans, titles, retry markers, terminal metadata, diffs, locations, and resource links remain in the durable session log or in UI-specific transports. It does not provide session load/list/delete, commands, modes, configuration selectors, model switching, plan review, or human elicitation.
+Image capability is truthful rather than structural: `initialize` advertises it only when a durable attachment store exists and the configured exact provider/model resolves with explicit image input. Each image prompt rechecks the session's latest exact route, strictly decodes every block, and delegates the complete batch to `AttachmentStore.saveImages()` before publishing the user event. Cancellation reserves and aborts the admission slot before any asynchronous work, waits for already-started writes to quiesce before the prompt settles, and never publishes a late message; a completed content-addressed write may remain unreachable because destructive rollback is not valid for a deduplicated store.
+
+The bridge emits only committed `assistant/message` text and images. A per-session promise chain preserves block and message order while assistant image references are asynchronously re-read and integrity-verified for ACP base64 delivery; a missing or corrupt object fails prompt delivery instead of becoming a placeholder. Reasoning, raw chunks, tool activity, todos, plans, titles, retry markers, terminal metadata, diffs, locations, and resource links remain in the durable session log or in UI-specific transports. It does not provide session load/list/delete, commands, modes, configuration selectors, model switching, plan review, or human elicitation.
 
 One-shot `session/request_permission` remains. It is a machine policy channel for bridge-owned agents, not a human approval UI: the answerer accepts only an exact agent object in the bridge's live session map, delegates foreign or call-less requests, and maps failed RPCs to the fail-closed unavailable outcome. The client chooses allow once, reject once, or cancel, and the bridge never turns that response into a durable grant. Asking policy stays in the approval seam and its producers; [`dsh-subagent-acp`](../../../../packages/subagent/subagent-acp/README.md) uses this channel programmatically.
 
@@ -24,13 +26,13 @@ The app composition contains the agent spine, persistence, checkpoint policy, an
 
 The transport programs interface-level agent, session, and approval services rather than the concrete agent loop. Tool execution stays inside the harness; ACP never delegates shell execution to an editor. stdout carries framed JSON-RPC only, so the app mounts no stdout logger and the bridge does not monkey-patch process output.
 
-Disconnect and plugin disposal share one memoized quiescence boundary. Both successful and failed transport closure settle pending prompts as cancelled, dispose every bridge-owned agent, and await loop and session cleanup. A create that loses the close race disposes its unpublished handle.
+Disconnect and plugin disposal share one memoized quiescence boundary. Both successful and failed transport closure cancel prompt admission and agents, drain ordered output, settle pending prompts as cancelled, dispose every bridge-owned agent, and await loop and session cleanup. A create that loses the close race disposes its unpublished handle.
 
 ## Snapshot boundary
 
 The ACP snapshot suite still boots the assembled ACP example and retains scenarios that pin backend behavior. Only scenarios driven through deleted UI methods leave the suite; semantic-checkpoint recovery runs through the headless `stream-json` example because ACP no longer loads sessions.
 
-Protocol and lifecycle tests pin stop-reason and prompt codecs, version negotiation, fresh-session creation, text and resource-link flattening, rejection of empty or unsupported prompts, exact-agent permission ownership, multi-session isolation, prompt settlement, per-session cancellation, failed transport closure, ACP-only reload cleanup, and teardown quiescence. Built and real-stdio smokes reject stray stdout. The `session/new` branch that loses a real stdio close race remains coverage-exempt because the in-memory transport cannot reproduce that ordering; it disposes the unpublished handle, while the surrounding disposal tests pin the no-orphan invariant.
+Protocol and lifecycle tests pin stop-reason codecs, version negotiation, truthful image capability, fresh-session creation, ordered text/image admission, resource-link flattening, all-member validation before writes, absence of inline base64 in durable events, rejection of empty or unsupported prompts, exact-agent permission ownership, multi-session isolation, prompt settlement after ordered output, verified assistant-image delivery, cancellation during admission without a late followup, failed transport closure, ACP-only reload cleanup, and teardown quiescence. An assembled keyless snapshot sends a real inline PNG through the runnable ACP example and pins only its durable reference in the session log. Built and real-stdio smokes reject stray stdout. The `session/new` branch that loses a real stdio close race remains coverage-exempt because the in-memory transport cannot reproduce that ordering; it disposes the unpublished handle, while the surrounding disposal tests pin the no-orphan invariant.
 
 ## Alternatives considered
 
@@ -44,10 +46,16 @@ Protocol and lifecycle tests pin stop-reason and prompt codecs, version negotiat
 
 **Delete the ACP snapshot suite or migrate every scenario in this change.** Rejected because most scenarios test the backend and remain valuable, while a full harness migration is an independent testing change. Only scenarios whose driver was a deleted UI method leave this suite.
 
+**Advertise image support whenever the ACP SDK has an image block.** Rejected because protocol vocabulary does not prove this deployment can persist bytes or that the configured exact route accepts visual input. Unknown capability is false at initialization; prompt admission rechecks the live route.
+
+**Flatten inline and assistant images to markers or persist ACP base64 in session events.** Rejected because markers silently lose model/user intent and base64 makes durable logs the binary store. ACP translates between its wire block and the existing durable `ImageBlock` reference at the transport boundary.
+
+**Create a generic RichContent service for ACP, MCP, and Web.** Rejected because core `ContentBlock` plus the attachment seam already own the shared contract. Each front door keeps only protocol parsing, capability proof, and lifecycle orchestration; shared batch limits and image validation stay in `AttachmentStore.saveImages()`.
+
 ## Consequences
 
 ACP has a narrow contract suitable for agents and automation, while TUI and Web own human interaction and presentation. The package has fewer injected services, dependencies, protocol branches, and lifecycle states, and it no longer claims compatibility as a general editor entry point.
 
-Automation clients receive complete committed text rather than token deltas or structured tool UI. They inspect durable logs or another API when they need reasoning, tool traces, titles, or richer state. Fresh-session-only operation also means callers that need durable browsing or resume use a host API rather than ACP.
+Automation clients receive complete committed text/images rather than token deltas or structured tool UI. They inspect durable logs or another API when they need reasoning, tool traces, titles, or richer state. Fresh-session-only operation also means callers that need durable browsing or resume use a host API rather than ACP.
 
 Backend snapshot coverage therefore remains transport-coupled to ACP even though that transport is incidental to the behavior under test.

.agents/notes/implemented/simplification/2026-07-23-acp-automation-only-protocol.zh.md

@@ -8,15 +8,17 @@ Status: implemented
 
 ACP（Agent Client Protocol）桥接层已经变成第二套交互式产品 UI。它将持久事件转换为编辑器卡片、终端元数据、diff、计划、标题、推理（reasoning）、命令、模式、模型和权限选择器、会话导航以及面向人类的询问。这些职责与 TUI 和 Web 客户端重复，同时将自动化传输层与 UI 服务、持久化查询、展示策略和编辑器特定约定耦合在一起。
 
-ACP 仍有一个有用的职责：另一个 agent（智能体）或自动化控制器可以启动 harness 进程、创建隔离会话、发送文本、接收已提交的回答、取消工作并回答权限请求。跨进程 ACP subagent 后端依赖这个标准协议边界。
+ACP 仍有一个有用的职责：另一个 agent（智能体）或自动化控制器可以启动 harness 进程、创建隔离会话、发送文本或范围狭窄的受支持内联图片、接收已提交的文本／图片回答、取消工作并回答权限请求。跨进程 ACP subagent 后端依赖这个标准协议边界。
 
 快照套件使移除工作更复杂。大多数 ACP 场景测试的是组装后的 agent 后端，而不是 ACP 展示层；如果随编辑器桥接层一起删除整个套件，就会丢失大量无密钥行为测试。
 
 ## 决策
 
-`@deepseek-ai/dsh-acp` 是位于 [`packages/acp/acp`](../../../../packages/acp/acp/README.md) 下、独立于 `ui` 包组的自动化传输层。其公开协议特意保持精简：版本协商、全新文本会话（每个会话最多允许一个进行中的提示词）、已提交的助手文本更新、按会话取消、并发会话，以及由连接负责的资源清理。提示词只承载规范要求的基线内容——文本，加上被展平为方括号文本引用的资源链接；桥接层会拒绝附加目录、MCP 服务器、超出基线的提示词内容（图片、音频、内嵌资源）、空提示词、未知会话和重叠提示词。
+`@deepseek-ai/dsh-acp` 是位于 [`packages/acp/acp`](../../../../packages/acp/acp/README.md) 下、独立于 `ui` 包组的自动化传输层。其公开协议特意保持精简：版本协商、全新会话（每个会话最多允许一个进行中的提示词）、已提交的助手文本／图片更新、按会话取消、并发会话，以及由连接负责的资源清理。提示词按协议顺序保留文本与受支持光栅图片，资源链接则展平为方括号文本引用；桥接层会拒绝附加目录、MCP 服务器、音频、嵌入资源、格式错误或空提示词、未知会话和重叠提示词。
 
-桥接层只发出已提交的 `assistant/message` 文本。推理、原始分片、工具活动、待办事项、计划、标题、重试标记、终端元数据、diff、位置和资源链接仍保留在持久会话日志或 UI 专用传输层中。它不提供会话加载、列出与删除、命令、模式、配置选择器、模型切换、plan 评审或面向人类的询问。
+图片能力必须真实，而不能只看结构：只有持久附件存储存在，且配置的确切提供方／模型解析后明确支持图片输入时，`initialize` 才会公布该能力。每个图片提示词都会重新检查会话的最新确切路由、严格解码全部块，并在发布用户事件前把完整批次委托给 `AttachmentStore.saveImages()`。取消会在任何异步工作前预留并中止准入槽位，使提示词在已经启动的写入停稳后才结算，而且绝不发布迟到消息；已经完成的内容寻址写入可能保持不可达，因为对去重存储执行破坏性回滚并不正确。
+
+桥接层只发出已提交的 `assistant/message` 文本与图片。每个会话使用一条 Promise 链，在异步重新读取并校验助手图片引用、将其转换为 ACP base64 交付时保持块与消息顺序；对象缺失或损坏会使提示词交付失败，而不是变成占位符。推理、原始分片、工具活动、待办事项、计划、标题、重试标记、终端元数据、diff、位置和资源链接仍保留在持久会话日志或 UI 专用传输层中。它不提供会话加载、列出与删除、命令、模式、配置选择器、模型切换、plan 评审或面向人类的询问。
 
 保留一次性 `session/request_permission`。它是为桥接层拥有的 agent 提供的机器策略通道，而不是面向人类的审批 UI：应答者只接受桥接层当前会话映射中登记的同一 agent 对象；外部请求或缺少调用标识的请求会继续委派；RPC 失败则映射为拒绝请求的 `unavailable` 结果。客户端可选择允许一次、拒绝一次或取消，桥接层绝不会将该响应转换为持久授权。询问策略仍归审批 seam 及其生产者所有；[`dsh-subagent-acp`](../../../../packages/subagent/subagent-acp/README.md) 会以程序化方式使用该通道。
 
@@ -24,13 +26,13 @@ ACP 仍有一个有用的职责：另一个 agent（智能体）或自动化控
 
 传输层调用 agent、会话和审批的接口服务，而不依赖具体的 agent loop。工具执行仍留在 harness 内；ACP 绝不会把 shell 执行委派给编辑器。stdout 只承载分帧 JSON-RPC，因此 app 不挂载 stdout logger，桥接层也不会 monkey-patch 进程输出。
 
-断开连接与插件 dispose（资源释放）共享同一个经记忆化的完全停稳边界。传输关闭无论成功还是失败，都会将待处理提示词以已取消状态结算，dispose 每个由桥接层拥有的 agent，并等待循环和会话清理完成。创建流程如果在与关闭的竞态中落败，就会 dispose 其尚未发布的 handle。
+断开连接与插件 dispose（资源释放）共享同一个经记忆化的完全停稳边界。传输关闭无论成功还是失败，都会取消提示词准入和 agent、排空有序输出、将待处理提示词以已取消状态结算、dispose 每个由桥接层拥有的 agent，并等待循环和会话清理完成。创建流程如果在与关闭的竞态中落败，就会 dispose 其尚未发布的 handle。
 
 ## 快照边界
 
 ACP 快照套件仍会启动组装后的 ACP 示例，并保留用于锁定后端行为的场景。从该套件移出的只有通过已删除的 UI 方法驱动的场景；由于 ACP 不再加载会话，语义检查点恢复通过 headless `stream-json` 示例执行。
 
-协议与生命周期测试会锁定停止原因编解码器和提示词编解码器、版本协商、新会话创建、文本与资源链接展平、拒绝空提示词或不受支持的提示词、基于同一 agent 对象的权限归属、多会话隔离、提示词结算、按会话取消、传输关闭失败、ACP 专属重载清理，以及拆卸完全停稳。构建产物冒烟测试与真实 stdio 冒烟测试会拒绝混入 stdout 的额外输出。`session/new` 中在真实 stdio 关闭竞态中落败的分支仍豁免覆盖率要求，因为内存传输层无法复现这一顺序；该分支会 dispose 尚未发布的 handle，而周边 dispose 测试会锁定无遗留资源不变式。
+协议与生命周期测试会锁定停止原因编解码器、版本协商、真实图片能力、新会话创建、有序文本／图片准入、资源链接展平、写入前校验全部成员、持久事件中不含内联 base64、拒绝空提示词或不受支持的提示词、基于同一 agent 对象的权限归属、多会话隔离、在有序输出后结算提示词、经过校验的助手图片交付、准入期间取消且不产生迟到 followup、传输关闭失败、ACP 专属重载清理，以及拆卸完全停稳。组装后的无密钥快照通过可运行 ACP 示例发送一张真实内联 PNG，并在会话日志中只固定其持久引用。构建产物冒烟测试与真实 stdio 冒烟测试会拒绝混入 stdout 的额外输出。`session/new` 中在真实 stdio 关闭竞态中落败的分支仍豁免覆盖率要求，因为内存传输层无法复现这一顺序；该分支会 dispose 尚未发布的 handle，而周边 dispose 测试会锁定无遗留资源不变式。
 
 ## 考虑过的替代方案
 
@@ -44,10 +46,16 @@ ACP 快照套件仍会启动组装后的 ACP 示例，并保留用于锁定后
 
 **删除 ACP 快照套件，或在本次变更中迁移每个场景。** 不予采用，因为大多数场景测试后端且仍有价值，而完整的 harness 迁移是一项独立的测试变更。只有通过已删除的 UI 方法驱动的场景才离开该套件。
 
+**只要 ACP SDK 具有图片块就公布图片支持。** 不予采用，因为协议词汇不能证明当前部署可以持久化字节，也不能证明配置的确切路由接受视觉输入。初始化时能力未知即为 false；提示词准入会重新检查实时路由。
+
+**把内联图片和助手图片展平为标记，或把 ACP base64 持久化进会话事件。** 不予采用，因为标记会静默丢失模型／用户意图，base64 则会让持久日志变成二进制存储。ACP 在传输边界把自身协议块与现有持久 `ImageBlock` 引用相互转换。
+
+**为 ACP、MCP 和 Web 创建通用 RichContent 服务。** 不予采用，因为核心 `ContentBlock` 与附件 seam 已经拥有共享契约。每个入口只保留协议解析、能力证明与生命周期编排；共享批次限制和图片校验留在 `AttachmentStore.saveImages()` 中。
+
 ## 结果
 
 ACP 具有适合 agent 与自动化的精简约定，而 TUI 和 Web 拥有面向人类的交互与展示。该包注入的服务、依赖、协议分支和生命周期状态更少，也不再将自身定位为通用编辑器入口。
 
-自动化客户端收到完整的已提交文本，而不是 token 增量或结构化工具 UI。当它们需要推理、工具跟踪信息、标题或更丰富的状态时，需要查看持久日志或其他 API。只支持全新会话也意味着，需要浏览持久会话或恢复会话的调用方必须使用 host API，而不是 ACP。
+自动化客户端收到完整的已提交文本／图片，而不是 token 增量或结构化工具 UI。当它们需要推理、工具跟踪信息、标题或更丰富的状态时，需要查看持久日志或其他 API。只支持全新会话也意味着，需要浏览持久会话或恢复会话的调用方必须使用 host API，而不是 ACP。
 
 因此，后端快照测试仍与 ACP 传输层耦合，尽管对于受测行为而言，该传输层只是附带因素。

docs/config-catalog.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
-config-catalog.md: 369490ec41480b8c46355f0edc3eb97f2f0c76cb
-config-catalog.zh.md: a735d7021d44dda3cffa49c31430249f70431720
+config-catalog.md: 27ed96659fd23bd33495a632aa0fd552f44e0163
+config-catalog.zh.md: 01a74bd8f06dcce5b5281f12796b151246b73f35

docs/config-catalog.md

@@ -27,7 +27,7 @@ export interface AcpConfig {
 
 Depends on: `Stream` (`@agentclientprotocol/sdk`)
 
-Source: [`packages/acp/acp/src/index.ts:70`](../packages/acp/acp/src/index.ts)
+Source: [`packages/acp/acp/src/index.ts:71`](../packages/acp/acp/src/index.ts)
 
 ## `@deepseek-ai/dsh-acp-demo`
 

docs/config-catalog.zh.md

@@ -29,7 +29,7 @@ export interface AcpConfig {
 
 依赖：`Stream`（`@agentclientprotocol/sdk`）
 
-来源：[`packages/acp/acp/src/index.ts:70`](../packages/acp/acp/src/index.ts)
+来源：[`packages/acp/acp/src/index.ts:71`](../packages/acp/acp/src/index.ts)
 
 ## `@deepseek-ai/dsh-acp-demo`
 

examples/acp-agent/code-mode-image.cordis.snapshot.yml

@@ -0,0 +1,42 @@
+# Keyless replay combines Code Mode with the durable image store and an exact
+# image-capable replay route. The scenario generates its tiny PNG inside the
+# run_code program, then exercises read_image as a nested dispatch.
+- id: base
+  name: '@deepseek-ai/cordis-plugin-include'
+  config:
+    path: ./cordis.yml
+    patches:
+      - id: llm-deepseek
+        name: '@deepseek-ai/dsh-llm-deepseek'
+        disabled: true
+      - id: acp-agent
+        name: '@deepseek-ai/dsh-acp-demo'
+        config:
+          provider: deepseek-official
+          model: deepseek-v4-flash
+          persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
+          persistenceCompression: none
+          workspaceContext:
+            maxBytes: 65536
+          tools:
+            mode: code
+          persona: |
+            You are a coding assistant powered by the {{model}} model. Your working directory is {{cwd}}.
+
+            Verify your work by running the code or tests. Keep answers brief and factual.
+      - insert:
+          - id: attachment-local
+            name: '@deepseek-ai/dsh-attachment-local'
+          - id: code-runtime
+            name: '@deepseek-ai/dsh-code-runtime-worker'
+          - id: llm-replay
+            name: '@deepseek-ai/dsh-llm-replay'
+            config:
+              providers:
+                - id: deepseek-official
+                  name: DeepSeek
+                  models:
+                    - id: deepseek-v4-flash
+                      inputModalities: [text, image]
+                    - id: deepseek-v4-pro
+                      inputModalities: [text]

examples/acp-agent/code-mode-image.cordis.yml

@@ -0,0 +1,29 @@
+# Code Mode image overlay: mounts the worker runtime and durable attachment
+# store so a nested read_image result can cross the generic rich-result bridge.
+# The authored snapshot is replay-only; the live config retains the ordinary
+# exact provider route for manual use.
+- id: base
+  name: '@deepseek-ai/cordis-plugin-include'
+  config:
+    path: ./cordis.yml
+    patches:
+      - id: acp-agent
+        name: '@deepseek-ai/dsh-acp-demo'
+        config:
+          provider: deepseek-official
+          model: deepseek-v4-pro
+          persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
+          persistenceCompression: !!js "process.env.DSH_SNAPSHOT === undefined ? 'zstd' : 'none'"
+          workspaceContext:
+            maxBytes: 65536
+          tools:
+            mode: code
+          persona: |
+            You are a coding assistant powered by the {{model}} model. Your working directory is {{cwd}}.
+
+            Verify your work by running the code or tests. Keep answers brief and factual.
+      - insert:
+          - id: attachment-local
+            name: '@deepseek-ai/dsh-attachment-local'
+          - id: code-runtime
+            name: '@deepseek-ai/dsh-code-runtime-worker'

examples/acp-agent/tests/acp.snapshot.ts

@@ -32,6 +32,7 @@ const AGENT = {
 // The Code Mode overlay configs (include-patched variants of cordis.yml; the
 // replay swap resolves each one's sibling `*cordis.snapshot.yml`).
 const CODE_MODE_CONFIG = fileURLToPath(new URL('../code-mode.cordis.yml', import.meta.url))
+const CODE_MODE_IMAGE_CONFIG = fileURLToPath(new URL('../code-mode-image.cordis.yml', import.meta.url))
 const CODE_MODE_WORKSPACE_CONTEXT_CONFIG = fileURLToPath(new URL('../code-mode-workspace-context.cordis.yml', import.meta.url))
 const BOTH_MODE_CONFIG = fileURLToPath(new URL('../both-mode.cordis.yml', import.meta.url))
 const WORKSPACE_CONTEXT_CONFIG = fileURLToPath(new URL('../workspace-context.cordis.yml', import.meta.url))
@@ -212,6 +213,13 @@ const SCENARIOS: Scenario[] = [
     headerClass: 'image',
     configPath: IMAGE_TEXT_ROUTE_CONFIG,
   },
+  {
+    name: 'inline-image-prompt',
+    hasModelTurn: true,
+    recorded: false,
+    headerClass: 'image',
+    configPath: IMAGE_CONFIG,
+  },
   {
     name: 'pty-tools',
     hasModelTurn: true,
@@ -539,6 +547,16 @@ const SCENARIOS: Scenario[] = [
   // tools:sdk section rides in the prompt, and the program's tool calls land as
   // tool/code-dispatch events. Each overlay composes and pins its own header class.
   { name: 'code-mode-turn', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'code', configPath: CODE_MODE_CONFIG },
+  {
+    name: 'code-mode-read-image',
+    hasModelTurn: true,
+    recorded: false,
+    pinsHeader: true,
+    headerClass: 'code-image',
+    toolSchemasSource: 'code-mode-turn',
+    configPath: CODE_MODE_IMAGE_CONFIG,
+    posixOnly: true,
+  },
   // A nested fs dispatch inside run_code discovers workspace instructions. The
   // projection enters the inbox after the outer result and becomes model-visible
   // on the following step, retaining workspace provenance end to end.

examples/acp-agent/tests/snapshots/code-mode-read-image/input.json

@@ -0,0 +1,14 @@
+{
+  "steps": [
+    {
+      "op": "initialize"
+    },
+    {
+      "op": "newSession"
+    },
+    {
+      "op": "prompt",
+      "text": "Using ONE run_code program, create a one-pixel PNG with Node.js, call read_image on it, then reply with exactly the single word DONE."
+    }
+  ]
+}

examples/acp-agent/tests/snapshots/code-mode-read-image/session.jsonl

@@ -0,0 +1,33 @@
+{"type":"session","version":0,"id":"44444444-4444-4444-8444-444444444444","createdAt":1783952000000,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"agent/inbox/spliced","seq":0,"time":1786431644501,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Using ONE run_code program, create a one-pixel PNG with Node.js, call read_image on it, then reply with exactly the single word DONE."}],"source":{"kind":"user"},"role":"user","id":"08e67dbb-9432-4fe4-b7da-4483998c0a31"}]}}
+{"type":"turn/start","seq":1,"time":1786431644502,"data":{"turn":1}}
+{"type":"agent/inbox/spliced","seq":2,"time":1786431644502,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","seq":3,"time":1786431644557,"data":{"turn":1,"step":1}}
+{"type":"user/message","seq":4,"time":1786431644558,"data":{"content":[{"type":"text","text":"Using ONE run_code program, create a one-pixel PNG with Node.js, call read_image on it, then reply with exactly the single word DONE."}],"source":{"kind":"user"},"role":"user","id":"08e67dbb-9432-4fe4-b7da-4483998c0a31"},"surfaceOp":"append"}
+{"type":"user/message","seq":5,"time":1786431644558,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"99b9db8d-e4ec-4ea9-b5e2-1e4c0ff6354b"},"surfaceOp":"append"}
+{"type":"session/title","seq":6,"time":1786431644558,"data":{"title":"Using ONE run_code program, create","messageSeqs":[4],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":7,"time":1786431644559,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","seq":8,"time":1786431644560,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"assistant/chunk","seq":9,"time":1783952000009,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":10,"time":1786431644571,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"code-image-call","name":"run_code","arguments":"{\"code\":\"const bytes = [137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,0,1,0,0,0,1,8,2,0,0,0,144,119,83,222,0,0,0,12,73,68,65,84,120,156,99,248,207,192,0,0,3,1,1,0,201,254,146,239,0,0,0,0,73,69,78,68,174,66,96,130];\\nawait tools.bash({ command: \\\"node -e \\\\\\\"require('node:fs').writeFileSync('red.png',Buffer.from([137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,0,1,0,0,0,1,8,2,0,0,0,144,119,83,222,0,0,0,12,73,68,65,84,120,156,99,248,207,192,0,0,3,1,1,0,201,254,146,239,0,0,0,0,73,69,78,68,174,66,96,130]));\\\\\\\"\\\", description: \\\"Create a one pixel PNG\\\" });\\nconst image = await tools.read_image({ file_path: \\\"red.png\\\" });\\nreturn image.path;\",\"description\":\"Create and inspect one image\"}"}}}}
+{"type":"assistant/chunk","seq":11,"time":1786431644572,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":12,"time":1786431644572,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":13,"time":1786431644572,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"code-image-call","name":"run_code","arguments":"{\"code\":\"const bytes = [137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,0,1,0,0,0,1,8,2,0,0,0,144,119,83,222,0,0,0,12,73,68,65,84,120,156,99,248,207,192,0,0,3,1,1,0,201,254,146,239,0,0,0,0,73,69,78,68,174,66,96,130];\\nawait tools.bash({ command: \\\"node -e \\\\\\\"require('node:fs').writeFileSync('red.png',Buffer.from([137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,0,1,0,0,0,1,8,2,0,0,0,144,119,83,222,0,0,0,12,73,68,65,84,120,156,99,248,207,192,0,0,3,1,1,0,201,254,146,239,0,0,0,0,73,69,78,68,174,66,96,130]));\\\\\\\"\\\", description: \\\"Create a one pixel PNG\\\" });\\nconst image = await tools.read_image({ file_path: \\\"red.png\\\" });\\nreturn image.path;\",\"description\":\"Create and inspect one image\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"644382c5-5a05-4bda-b8dc-b9195d6a7d8b"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[9,10,11,12],"surfaceOp":"append"}
+{"type":"tool/call","seq":14,"time":1786431644573,"data":{"turn":1,"step":1,"callId":"code-image-call","name":"run_code","arguments":"{\"code\":\"const bytes = [137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,0,1,0,0,0,1,8,2,0,0,0,144,119,83,222,0,0,0,12,73,68,65,84,120,156,99,248,207,192,0,0,3,1,1,0,201,254,146,239,0,0,0,0,73,69,78,68,174,66,96,130];\\nawait tools.bash({ command: \\\"node -e \\\\\\\"require('node:fs').writeFileSync('red.png',Buffer.from([137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,0,1,0,0,0,1,8,2,0,0,0,144,119,83,222,0,0,0,12,73,68,65,84,120,156,99,248,207,192,0,0,3,1,1,0,201,254,146,239,0,0,0,0,73,69,78,68,174,66,96,130]));\\\\\\\"\\\", description: \\\"Create a one pixel PNG\\\" });\\nconst image = await tools.read_image({ file_path: \\\"red.png\\\" });\\nreturn image.path;\",\"description\":\"Create and inspect one image\"}"}}
+{"type":"tool/code-dispatch-start","seq":15,"time":1786431644697,"data":{"rootCallId":"code-image-call","parentCallId":"code-image-call","subCallId":"code-image-call:code:1","name":"bash","arguments":{"command":"node -e \"require('node:fs').writeFileSync('red.png',Buffer.from([137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,0,1,0,0,0,1,8,2,0,0,0,144,119,83,222,0,0,0,12,73,68,65,84,120,156,99,248,207,192,0,0,3,1,1,0,201,254,146,239,0,0,0,0,73,69,78,68,174,66,96,130]));\"","description":"Create a one pixel PNG"}}}
+{"type":"tool/code-dispatch","seq":16,"time":1786431644828,"data":{"rootCallId":"code-image-call","parentCallId":"code-image-call","subCallId":"code-image-call:code:1","name":"bash","arguments":{"command":"node -e \"require('node:fs').writeFileSync('red.png',Buffer.from([137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,0,1,0,0,0,1,8,2,0,0,0,144,119,83,222,0,0,0,12,73,68,65,84,120,156,99,248,207,192,0,0,3,1,1,0,201,254,146,239,0,0,0,0,73,69,78,68,174,66,96,130]));\"","description":"Create a one pixel PNG"},"isError":false,"content":[{"type":"text","text":"(no output)"}]}}
+{"type":"tool/code-dispatch-start","seq":17,"time":1786431644829,"data":{"rootCallId":"code-image-call","parentCallId":"code-image-call","subCallId":"code-image-call:code:2","name":"read_image","arguments":{"file_path":"red.png"}}}
+{"type":"tool/code-dispatch","seq":18,"time":1786431644871,"data":{"rootCallId":"code-image-call","parentCallId":"code-image-call","subCallId":"code-image-call:code:2","name":"read_image","arguments":{"file_path":"red.png"},"isError":false,"content":[{"type":"text","text":"<path>{{cwd}}/red.png</path>\n<type>image</type>\n<content>\nimage/png image, 1x1 px, 69 bytes\n</content>"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"red.png"}}]}}
+{"type":"tool/result","seq":19,"time":1786431644874,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"code-image-call"},"content":[{"type":"tool-result","toolCallId":"code-image-call","content":[{"type":"text","text":"{{cwd}}/red.png"}],"isError":false}],"role":"user","id":"73e999fa-4aab-4609-970d-4c675e3557f1"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"agent/inbox/spliced","seq":20,"time":1786431644874,"data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"<path>{{cwd}}/red.png</path>\n<type>image</type>\n<content>\nimage/png image, 1x1 px, 69 bytes\n</content>"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"red.png"}}],"source":{"kind":"plugin","plugin":"tools-code-mode"},"role":"user","id":"99bca54a-c323-4df8-8695-7ef17d02dd65"}]}}
+{"type":"step/end","seq":21,"time":1786431644874,"data":{"turn":1,"step":1}}
+{"type":"agent/inbox/spliced","seq":22,"time":1786431644874,"data":{"target":"next-step","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","seq":23,"time":1786431644884,"data":{"turn":1,"step":2}}
+{"type":"user/message","seq":24,"time":1786431644885,"data":{"content":[{"type":"text","text":"<path>{{cwd}}/red.png</path>\n<type>image</type>\n<content>\nimage/png image, 1x1 px, 69 bytes\n</content>"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"red.png"}}],"source":{"kind":"plugin","plugin":"tools-code-mode"},"role":"user","id":"99bca54a-c323-4df8-8695-7ef17d02dd65"},"surfaceOp":"append"}
+{"type":"assistant/chunk","seq":25,"time":1786431644889,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":26,"time":1786431644889,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}}
+{"type":"assistant/chunk","seq":27,"time":1786431644890,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":28,"time":1786431644890,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":29,"time":1786431644890,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"a6da60ea-d420-432b-ba00-9b99af045110"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[25,26,27,28],"surfaceOp":"append"}
+{"type":"step/end","seq":30,"time":1786431644890,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":31,"time":1786431644890,"data":{"turn":1,"reason":{"kind":"completed"}}}

examples/acp-agent/tests/snapshots/code-mode-read-image/stdout.expected.jsonl

@@ -0,0 +1,4 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"promptCapabilities":{"image":true,"audio":false,"embeddedContext":false}},"authMethods":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"DONE"}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}

examples/acp-agent/tests/snapshots/inline-image-prompt/input.json

@@ -0,0 +1,28 @@
+{
+  "steps": [
+    {
+      "op": "initialize"
+    },
+    {
+      "op": "newSession"
+    },
+    {
+      "op": "promptContent",
+      "content": [
+        {
+          "type": "text",
+          "text": "Inspect this image, then reply with exactly "
+        },
+        {
+          "type": "image",
+          "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC",
+          "mimeType": "image/png"
+        },
+        {
+          "type": "text",
+          "text": "the single word DONE."
+        }
+      ]
+    }
+  ]
+}

examples/acp-agent/tests/snapshots/inline-image-prompt/session.jsonl

@@ -0,0 +1,17 @@
+{"type":"session","version":0,"id":"44444444-4444-4444-8444-444444444444","createdAt":1783952000000,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"agent/inbox/spliced","seq":0,"time":1783952000001,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Inspect this image, then reply with exactly "},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","width":1,"height":1,"bytes":69}},{"type":"text","text":"the single word DONE."}],"source":{"kind":"user"},"role":"user","id":"0c0c0c0c-0000-4000-8000-000000000001"}]}}
+{"type":"turn/start","seq":1,"time":1783952000002,"data":{"turn":1}}
+{"type":"agent/inbox/spliced","seq":2,"time":1783952000002,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","seq":3,"time":1783952000003,"data":{"turn":1,"step":1}}
+{"type":"user/message","seq":4,"time":1783952000003,"data":{"content":[{"type":"text","text":"Inspect this image, then reply with exactly "},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","width":1,"height":1,"bytes":69}},{"type":"text","text":"the single word DONE."}],"source":{"kind":"user"},"role":"user","id":"0c0c0c0c-0000-4000-8000-000000000001"},"surfaceOp":"append"}
+{"type":"user/message","seq":5,"time":1783952000004,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"0c0c0c0c-0000-4000-8000-000000000002"},"surfaceOp":"append"}
+{"type":"session/title","seq":6,"time":1783952000004,"data":{"title":"Inspect this image, then reply","messageSeqs":[4],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":7,"time":1783952000005,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","seq":8,"time":1783952000005,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"assistant/chunk","seq":9,"time":1783952000006,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":10,"time":1783952000007,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}}
+{"type":"assistant/chunk","seq":11,"time":1783952000008,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":12,"time":1783952000009,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":13,"time":1783952000009,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"0c0c0c0c-0000-4000-8000-000000000003"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[9,10,11,12],"surfaceOp":"append"}
+{"type":"step/end","seq":14,"time":1783952000010,"data":{"turn":1,"step":1}}
+{"type":"turn/end","seq":15,"time":1783952000010,"data":{"turn":1,"reason":{"kind":"completed"}}}

examples/acp-agent/tests/snapshots/inline-image-prompt/stdout.expected.jsonl

@@ -0,0 +1,4 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"promptCapabilities":{"image":true,"audio":false,"embeddedContext":false}},"authMethods":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"DONE"}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}

examples/acp-agent/tests/snapshots/read-image/stdout.expected.jsonl

@@ -1,4 +1,4 @@
-{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"promptCapabilities":{"image":true,"audio":false,"embeddedContext":false}},"authMethods":[]}}
 {"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"DONE"}}}}
 {"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}

packages/acp/acp/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/acp/acp/README.md
-README.md: 9cc4a5e271c7200f6ad8799a4b8fa9e64b2ca893
-README.zh.md: eafae5602bdeb408ef548a9e706e059bd99bde17
+README.md: 40d4b2df18f8102a352d8a8eb438e88da7fe720c
+README.zh.md: 57b7e5a3f987861cfe0c5453f5d5a26d565f77ed

packages/acp/acp/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Automation-only [Agent Client Protocol](https://agentclientprotocol.com) server over JSON-RPC stdio. Programmatic clients create fresh harness agents, send text prompts, collect committed assistant text, resolve one-shot permission requests by policy, and cancel work. The primary in-repository client is [`dsh-subagent-acp`](../../subagent/subagent-acp/README.md).
+Automation-only [Agent Client Protocol](https://agentclientprotocol.com) server over JSON-RPC stdio. Programmatic clients create fresh harness agents, send text/image prompts, collect committed assistant text/images, resolve one-shot permission requests by policy, and cancel work. The primary in-repository client is [`dsh-subagent-acp`](../../subagent/subagent-acp/README.md).
 
 This package is a transport adapter, not a UI integration or a capability seam. It does not expose editor navigation, transcript replay, commands, modes, configuration pickers, elicitation, reasoning, plans, titles, or tool presentation. Interactive rendering and human questions belong to the Web host and client modules.
 
@@ -21,21 +21,21 @@ Both fields are optional so another agent/request listener may supply the target
 
 | Method | Behavior |
 |---|---|
-| `initialize` | Negotiates the supported version and advertises baseline-only prompts (no image, audio, or embedded-context capability). No session, editor, terminal, filesystem, or MCP capability is advertised. |
+| `initialize` | Negotiates the supported version. Image prompts are advertised only when a durable attachment store is mounted and the configured exact provider/model resolves with explicit image input; audio and embedded context stay false. No session, editor, terminal, filesystem, or MCP capability is advertised. |
 | `authenticate` | No-op because the server advertises no authentication methods. |
 | `session/new` | Creates a fresh agent with an absolute primary `cwd`; empty `additionalDirectories` and `mcpServers` are accepted, non-empty values reject. |
-| `session/prompt` | Concatenates text blocks, renders baseline resource links as bracketed textual references, rejects empty or beyond-baseline input, permits one in-flight request per session, and waits for the whole agent to become idle. Normal quiescence reports `end_turn`; explicit ACP cancellation, disposal, or a prompt whose admission was discarded (a turnless slot) reports `cancelled`. |
-| `session/cancel` | Cancels only the addressed agent and settles its pending prompt as `cancelled`; unknown ids are no-ops. |
-| `session/update` | Emits one `agent_message_chunk` per non-empty text block in a committed `assistant/message`. Raw deltas and non-message events are omitted. |
+| `session/prompt` | Preserves ordered text and supported inline image blocks, renders resource links as bracketed textual references, and rejects audio, embedded resources, malformed/empty input, or an image when capability was not advertised. It validates the whole image batch and rechecks the session's latest exact route before any save, commits every image before the user event, permits one in-flight request per session, and waits for admission, whole-agent idle, and ordered output delivery. Normal quiescence reports `end_turn`; explicit ACP cancellation, disposal, or a prompt whose admission was discarded (a turnless slot) reports `cancelled`. |
+| `session/cancel` | Cancels only the addressed agent and marks any already-started admission so the pending prompt waits for it to quiesce, publishes no late user message, and settles as `cancelled`; unknown ids are no-ops. |
+| `session/update` | Emits one `agent_message_chunk` per non-empty text or image block in a committed `assistant/message`, preserving order. Images are re-read and integrity-verified before inline base64 delivery. Raw deltas and non-message events are omitted. |
 | `session/request_permission` | Offers one-shot allow/reject choices for bridge-owned approval requests carrying a tool call id. Clients may answer automatically. |
 
 One connection may own several sessions. The bridge keys records by branded session id and checks exact agent identity before routing events or permission requests. Each session has an independent prompt slot, workspace, cancellation path, and disposer.
 
-Committed-message output intentionally trades token-by-token latency for a clean automation result. Uncommitted provider chunks and retry attempts cannot leak partial text; reasoning and tool activity remain in the session log for observability through other interfaces.
+Committed-message output intentionally trades token-by-token latency for a clean automation result. Uncommitted provider chunks and retry attempts cannot leak partial text or images; reasoning and tool activity remain in the session log for observability through other interfaces. Per-session delivery is serialized because attachment reads are asynchronous, and a missing or corrupt committed image fails the prompt response instead of emitting a placeholder.
 
 ## Lifecycle
 
-Client disconnect and Cordis disposal share one memoized teardown. The bridge first rejects new sessions and prompts, settles pending prompts, then drains continuable descendants only below this connection's exact owned Agents before disposing those handles in parallel and awaiting every result before reporting any failure. Other frontends sharing the Context retain their continuable forests and admission. An ACP-only plugin reload therefore leaves no orphan agent.
+Client disconnect and Cordis disposal share one memoized teardown. The bridge first rejects new sessions and prompts, cancels and quiesces prompt admission, agent activity, and ordered output delivery, then drains continuable descendants only below this connection's exact owned Agents before disposing those handles in parallel and awaiting every result before reporting any failure. Other frontends sharing the Context retain their continuable forests and admission. An ACP-only plugin reload therefore leaves no orphan agent.
 
 ACP requires each prompt response to carry a `stopReason`, but the bridge does not claim a prompt-specific turn outcome. Committed assistant messages stream across the owned activity, and steering or injected work may contribute before idle. Token-limit turn endings therefore do not become prompt-level ACP stop reasons (they settle as `end_turn`); a model error on the correlated turn rejects the prompt immediately.
 
@@ -45,15 +45,15 @@ ACP requires each prompt response to carry a `stopReason`, but the bridge does n
 
 ## Model Experience
 
-### Prompt text
+### Prompt text and images
 
 #### What the model sees
 
-`session/prompt` text blocks are concatenated verbatim into one user message; a baseline resource link appears in that message as a bracketed `[resource_link name=… uri=…]` reference the model may open with its own tools. Protocol metadata, client capabilities, permission choices, and session ids never enter the model request.
+`session/prompt` preserves text/image order in one user message; adjacent text is concatenated, and a resource link appears as a bracketed `[resource_link name=… uri=…]` reference the model may open with its own tools. Inline image base64 is discarded after batch admission, so the durable message contains only verified attachment references. Protocol metadata, client capabilities, permission choices, and session ids never enter the model request.
 
 #### Token effect
 
-Prompt tokens are data-dependent and remain in that session's history until compaction. Concurrent ACP sessions retain independent contexts.
+Prompt tokens and image charges are data-dependent and remain in that session's history until compaction. Concurrent ACP sessions retain independent contexts.
 
 #### KV Cache effect
 
@@ -76,6 +76,6 @@ Append-only through the owning tool result.
 ## Known Limitations and Deferred Work
 
 - **Fresh sessions only** — load, list, resume, delete, and fork are unsupported.
-- **Baseline prompts and one workspace only** — images, audio, embedded resources, non-empty additional directories, and MCP servers reject; resource links flatten to textual references rather than fetched content.
+- **Raster images and one workspace only** — image prompts require a durable store plus an exact route that declares image input; only PNG, JPEG, WebP, and GIF are accepted. Audio, embedded resources, non-empty additional directories, and MCP servers reject; resource links flatten to textual references rather than fetched content.
 - **Committed answers only** — live progress, reasoning, tool activity, plans, titles, and usage stay off the wire.
 - **Connection-owned lifetime** — one connection releases all of its sessions; per-session close is not implemented.

packages/acp/acp/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-通过 JSON-RPC stdio 提供的仅面向自动化的 [ACP（Agent Client Protocol）](https://agentclientprotocol.com) 服务器。程序化客户端可以创建新 harness agent（智能体）、发送文本提示词、收集已提交的 assistant 文本、按策略响应一次性权限请求并取消工作。仓库中的主要客户端是 [`dsh-subagent-acp`](../../subagent/subagent-acp/README.md)。
+通过 JSON-RPC stdio 提供的仅面向自动化的 [ACP（Agent Client Protocol）](https://agentclientprotocol.com) 服务器。程序化客户端可以创建新 harness agent（智能体）、发送文本／图片提示词、收集已提交的 assistant 文本／图片、按策略响应一次性权限请求并取消工作。仓库中的主要客户端是 [`dsh-subagent-acp`](../../subagent/subagent-acp/README.md)。
 
 此包是传输适配器，而非 UI 集成或能力 seam。它不公开编辑器导航、transcript（文本记录）回放、命令、模式、配置选择器、信息征集、推理（reasoning）、计划、标题或工具展示。交互式渲染与向用户提问属于 Web 宿主和客户端模块。
 
@@ -21,21 +21,21 @@
 
 | 方法 | 行为 |
 |---|---|
-| `initialize` | 协商受支持的版本，并仅公布基线提示词（无图像、音频或嵌入上下文能力）。不公布会话、编辑器、终端、文件系统或 MCP 能力。 |
+| `initialize` | 协商受支持的版本。只有挂载持久附件存储，且配置的确切提供方／模型解析后明确支持图片输入时，才公布图片提示词能力；音频与嵌入上下文保持 false。不公布会话、编辑器、终端、文件系统或 MCP 能力。 |
 | `authenticate` | 空操作，因为服务器不公布身份验证方法。 |
 | `session/new` | 以绝对路径作为主 `cwd` 创建新 agent；接受空的 `additionalDirectories` 和 `mcpServers`，拒绝非空值。 |
-| `session/prompt` | 拼接文本块，将基线资源链接渲染为带方括号的文本引用，拒绝空输入或超出基线的输入，每个会话只允许一个正在处理的请求，并等待整个 agent 进入空闲状态。正常完全停稳时报告 `end_turn`；显式 ACP 取消、资源释放，或准入被丢弃的提示词（无轮次槽位）时报告 `cancelled`。 |
-| `session/cancel` | 仅取消指定的 agent，并将其待处理提示词结算为 `cancelled`；未知 id 为空操作。 |
-| `session/update` | 为每个非空文本块发出一个 `agent_message_chunk`；这些文本块来自已提交的 `assistant/message`。省略原始增量和非消息事件。 |
+| `session/prompt` | 保留文本与受支持内联图片块的顺序，将资源链接渲染为带方括号的文本引用，并拒绝音频、嵌入资源、格式错误／空输入，或在未公布能力时提交图片。它会先校验完整图片批次并重新检查会话的最新确切路由，再保存任一成员；在用户事件前提交全部图片；每个会话只允许一个正在处理的请求，并等待准入、整个 agent 空闲和有序输出交付全部停稳。正常完全停稳时报告 `end_turn`；显式 ACP 取消、资源释放，或准入被丢弃的提示词（无轮次槽位）时报告 `cancelled`。 |
+| `session/cancel` | 仅取消指定的 agent，并标记已经启动的准入工作，使待处理提示词等待其停稳、不发布迟到的用户消息，随后以 `cancelled` 结算；未知 id 为空操作。 |
+| `session/update` | 为已提交 `assistant/message` 中的每个非空文本或图片块发出一个 `agent_message_chunk`，并保留顺序。图片在以内联 base64 交付前会重新读取并校验完整性。省略原始增量和非消息事件。 |
 | `session/request_permission` | 为携带工具调用 id、由桥接层拥有的批准请求提供一次性允许／拒绝选项。客户端可以自动回答。 |
 
 一个连接可以拥有多个会话。桥接层以带品牌的会话 id 作为记录键，并在路由事件或权限请求前检查 agent 是否为同一对象。每个会话都有独立的提示词槽位、工作区、取消路径和资源释放器。
 
-已提交消息输出有意牺牲逐 token 输出的低延迟，以换取干净的自动化结果。未提交的提供方分片和重试尝试无法泄漏部分文本；推理与工具活动仍保留在会话日志中，以便其他界面观测。
+已提交消息输出有意牺牲逐 token 输出的低延迟，以换取干净的自动化结果。未提交的提供方分片和重试尝试无法泄漏部分文本或图片；推理与工具活动仍保留在会话日志中，以便其他界面观测。由于附件读取是异步的，每个会话会串行交付内容；已提交图片缺失或损坏时，提示词响应会失败，而不会发出占位符。
 
 ## 生命周期
 
-客户端断开与 Cordis 释放共用同一个记忆化清理流程。桥接层先拒绝新会话和提示词，结算待处理提示词，然后只 drain 此连接确切拥有的 Agent 之下的可继续后代，再并行释放这些 handle，并等待全部结果结算后才报告失败。其他共享该上下文的前端会保留其可继续森林和准入。因此，仅 ACP 的插件重载不会遗留 agent。
+客户端断开与 Cordis 释放共用同一个记忆化清理流程。桥接层先拒绝新会话和提示词，取消并等待提示词准入、agent 活动和有序输出交付全部停稳，然后只 drain 此连接确切拥有的 Agent 之下的可继续后代，再并行释放这些 handle，并等待全部结果结算后才报告失败。其他共享该上下文的前端会保留其可继续森林和准入。因此，仅 ACP 的插件重载不会遗留 agent。
 
 ACP 要求每个提示词响应都携带 `stopReason`，但桥接层不声称它表示提示词专属的轮次结果。已提交的 assistant 消息会在整个自有活动期间流式输出，agent 进入空闲状态前发生的 steering（中途引导）或注入工作也可能参与其中。因此，因 token 上限而结束的轮次不会成为提示词级 ACP 停止原因（它们以 `end_turn` 结算）；关联轮次上的模型错误会立即拒绝该提示词。
 
@@ -45,15 +45,15 @@ ACP 要求每个提示词响应都携带 `stopReason`，但桥接层不声称它
 
 ## 模型体验
 
-### 提示词文本
+### 提示词文本与图片
 
 #### 模型看到的内容
 
-`session/prompt` 文本块会原样拼接为一条用户消息；基线资源链接会在该消息中表示为带方括号的 `[resource_link name=… uri=…]` 引用，模型可以使用自身工具打开它。协议元数据、客户端能力、权限选择和会话 id 绝不进入模型请求。
+`session/prompt` 会在一条用户消息中保留文本／图片顺序；相邻文本会拼接，资源链接则表示为带方括号的 `[resource_link name=… uri=…]` 引用，模型可以使用自身工具打开它。内联图片 base64 在批量准入后即被丢弃，因此持久消息只包含经过校验的附件引用。协议元数据、客户端能力、权限选择和会话 id 绝不进入模型请求。
 
 #### Token 影响
 
-提示词 token 取决于数据，并保留在该会话的历史中直到上下文压缩（context compaction）。并发 ACP 会话保留独立上下文。
+提示词 token 与图片费用取决于数据，并保留在该会话的历史中直到上下文压缩（context compaction）。并发 ACP 会话保留独立上下文。
 
 #### KV Cache 影响
 
@@ -76,6 +76,6 @@ ACP 要求每个提示词响应都携带 `stopReason`，但桥接层不声称它
 ## 已知限制与暂缓事项
 
 - **仅新会话**：不支持加载、列出、恢复、删除和 fork。
-- **仅基线提示词和一个 workspace**：图像、音频、嵌入资源、非空附加目录和 MCP 服务器都会被拒绝；资源链接只会展平为文本引用，不会获取其内容。
+- **仅光栅图片和一个 workspace**：图片提示词要求持久存储以及明确声明支持图片输入的确切路由；只接受 PNG、JPEG、WebP 和 GIF。音频、嵌入资源、非空附加目录和 MCP 服务器都会被拒绝；资源链接只会展平为文本引用，不会获取其内容。
 - **仅已提交答案**：实时进度、推理、工具活动、计划、标题和用量不会通过协议传输。
 - **由连接管理的生命周期**：一个连接会释放其所有会话；尚未实现单个会话关闭功能。

packages/acp/acp/package.json

@@ -36,13 +36,16 @@
     "@deepseek-ai/schemastery": "workspace:^"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh-attachment": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-attachment": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",

packages/acp/acp/src/codec.ts

@@ -3,7 +3,7 @@
  * @module @deepseek-ai/dsh-acp/codec
  */
 
-import type { ContentBlock as AcpContentBlock, StopReason } from '@agentclientprotocol/sdk'
+import type { StopReason } from '@agentclientprotocol/sdk'
 import type { TurnEndReason } from '@deepseek-ai/dsh-session'
 
 /**
@@ -32,35 +32,3 @@ export function turnEndToStopReason(reason: TurnEndReason): StopReason {
       return 'end_turn'
   }
 }
-
-/**
- * Flatten an ACP prompt's baseline blocks to text. Text blocks concatenate
- * verbatim; resource links become explicit textual references so a baseline
- * client can point at files without the bridge silently dropping that context.
- * @param prompt - supported ACP prompt blocks.
- * @returns text in wire order, with resource links rendered as bracketed references.
- */
-export function acpPromptToText(prompt: readonly AcpContentBlock[]): string {
-  return prompt.flatMap((block): string[] => {
-    switch (block.type) {
-      case 'text':
-        return [block.text]
-      case 'resource_link':
-        return [`\n[resource_link name=${JSON.stringify(block.name)} uri=${JSON.stringify(block.uri)}]\n`]
-      default:
-        return []
-    }
-  }).join('')
-}
-
-/**
- * Whether a prompt carries content beyond the ACP baseline. The spec requires
- * every agent to accept `text` and `resource_link`; richer inline payloads
- * (image, audio, embedded resource) are optional capabilities this bridge does
- * not advertise, so they are rejected rather than silently dropped.
- * @param prompt - ACP prompt blocks to inspect.
- * @returns `true` when any block is neither `text` nor `resource_link`.
- */
-export function promptHasUnsupportedContent(prompt: readonly AcpContentBlock[]): boolean {
-  return prompt.some(block => block.type !== 'text' && block.type !== 'resource_link')
-}

packages/acp/acp/src/content.ts

@@ -0,0 +1,238 @@
+/** ACP wire-content admission and projection owned by the ACP adapter. @module */
+
+import type { ContentBlock as AcpContentBlock } from '@agentclientprotocol/sdk'
+import type { Context } from '@deepseek-ai/cordis'
+import { AttachmentError } from '@deepseek-ai/dsh-attachment'
+import type { ImageAttachmentRef, ImageMediaType, SaveImageAttachment } from '@deepseek-ai/dsh-attachment'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+
+/** Raster formats shared by ACP image blocks and the core attachment vocabulary. */
+const IMAGE_MEDIA_TYPES: readonly ImageMediaType[] = [
+  'image/png',
+  'image/jpeg',
+  'image/webp',
+  'image/gif',
+]
+
+/** Canonical RFC 4648 base64, excluding whitespace and URL-safe aliases. */
+const CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+
+/** Content-admission failure category used by the protocol handler. */
+export type AcpContentFailureKind = 'invalid' | 'internal'
+
+/** Error with a stable ACP request-failure category and no raw binary payload. */
+export class AcpContentError extends Error {
+  /** Whether the bridge should report invalid params or an internal failure. */
+  readonly kind: AcpContentFailureKind
+
+  /**
+   * @param message - safe protocol-facing detail without inline binary data.
+   * @param kind - request-failure category.
+   * @param options - optional causal chain for diagnostics.
+   */
+  constructor(message: string, kind: AcpContentFailureKind, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'AcpContentError'
+    this.kind = kind
+  }
+}
+
+/** Narrow a wire MIME string to the durable raster vocabulary. */
+function imageMediaType(value: string): ImageMediaType | undefined {
+  return IMAGE_MEDIA_TYPES.includes(value as ImageMediaType) ? value as ImageMediaType : undefined
+}
+
+/** Strictly decode one ACP inline image without accepting base64 aliases. */
+function decodeImage(block: Extract<AcpContentBlock, { type: 'image' }>): SaveImageAttachment {
+  const mediaType = imageMediaType(block.mimeType)
+  if (mediaType === undefined) {
+    throw new AcpContentError('image mimeType must be image/png, image/jpeg, image/webp, or image/gif', 'invalid')
+  }
+  if (!CANONICAL_BASE64.test(block.data)) {
+    throw new AcpContentError('image data must be canonical base64', 'invalid')
+  }
+  const data = Buffer.from(block.data, 'base64')
+  if (data.toString('base64') !== block.data) {
+    throw new AcpContentError('image data must be canonical base64', 'invalid')
+  }
+  return { data, mediaType }
+}
+
+/** Resolve the exact current route and require explicit image input support. */
+async function assertImageRoute(ctx: Context, agent: Agent, signal: AbortSignal): Promise<void> {
+  const routed = agent.session.requestHeader()?.config
+  const provider = routed?.provider ?? agent.options.provider
+  const model = routed?.model ?? agent.options.model
+  const llm = ctx.get('llm')
+  if (provider === undefined || model === undefined || llm === undefined) {
+    throw new AcpContentError('the current model route could not be resolved for image input', 'invalid')
+  }
+  let info: Awaited<ReturnType<typeof llm.resolveModelInfo>>
+  try {
+    info = await llm.resolveModelInfo(provider, model, signal)
+  } catch (error: unknown) {
+    throw new AcpContentError('the current model route could not be verified for image input', 'invalid', { cause: error })
+  }
+  if (info.inputModalities === undefined || !info.inputModalities.includes('image')) {
+    throw new AcpContentError(`model "${model}" does not declare image input`, 'invalid')
+  }
+}
+
+/**
+ * Determine whether initialization may truthfully advertise inline image prompts.
+ * Unknown service, route, capability, or deployment media support is negative.
+ * @param ctx - bridge context carrying optional attachment and model services.
+ * @param provider - configured provider route used for newly created sessions.
+ * @param model - configured exact model id used for newly created sessions.
+ * @returns whether this bridge can admit images at initialization time.
+ */
+export async function supportsAcpImagePrompts(
+  ctx: Context,
+  provider: string | undefined,
+  model: string | undefined,
+): Promise<boolean> {
+  const attachments = ctx.get('attachments')
+  const llm = ctx.get('llm')
+  if (attachments === undefined || llm === undefined || provider === undefined || model === undefined) return false
+  if (!attachments.imageLimits.mediaTypes.some(mediaType => IMAGE_MEDIA_TYPES.includes(mediaType))) return false
+  try {
+    const info = await llm.resolveModelInfo(provider, model)
+    return info.inputModalities?.includes('image') === true
+  } catch {
+    return false
+  }
+}
+
+/** Render one baseline resource link into the core's current text vocabulary. */
+function resourceLinkText(block: Extract<AcpContentBlock, { type: 'resource_link' }>): string {
+  return `\n[resource_link name=${JSON.stringify(block.name)} uri=${JSON.stringify(block.uri)}]\n`
+}
+
+/**
+ * Admit one ACP prompt into ordered durable core content.
+ * Every wire block and image is validated before the ordered image batch starts
+ * writing; cancellation after a successful content-addressed write may leave an
+ * unreachable object but never queues a late user message.
+ * @param ctx - bridge context carrying attachment and model services.
+ * @param agent - destination agent whose latest exact route controls admission.
+ * @param prompt - untrusted ACP prompt blocks in wire order.
+ * @param imageEnabled - capability result advertised during initialization.
+ * @param signal - admission cancellation signal.
+ * @returns core content with durable image references in wire order.
+ */
+export async function admitAcpPrompt(
+  ctx: Context,
+  agent: Agent,
+  prompt: readonly AcpContentBlock[],
+  imageEnabled: boolean,
+  signal: AbortSignal,
+): Promise<ContentBlock[]> {
+  const images: SaveImageAttachment[] = []
+  for (const block of prompt) {
+    switch (block.type) {
+      case 'text':
+      case 'resource_link':
+        break
+      case 'image':
+        if (!imageEnabled) throw new AcpContentError('inline image prompts were not advertised by this connection', 'invalid')
+        images.push(decodeImage(block))
+        break
+      case 'audio':
+        throw new AcpContentError('audio prompt content is not supported', 'invalid')
+      case 'resource':
+        throw new AcpContentError('embedded resource prompt content is not supported', 'invalid')
+      /* v8 ignore next 2 -- ACP ContentBlock is a closed generated union. */
+      default:
+        throw new AcpContentError('unsupported ACP prompt content', 'invalid')
+    }
+  }
+
+  let refs: readonly ImageAttachmentRef[] = []
+  if (images.length > 0) {
+    const attachments = ctx.get('attachments')
+    if (attachments === undefined) throw new AcpContentError('no attachment store is mounted', 'invalid')
+    await assertImageRoute(ctx, agent, signal)
+    signal.throwIfAborted()
+    try {
+      refs = await attachments.saveImages(images)
+    } catch (error: unknown) {
+      if (error instanceof AttachmentError && error.code !== 'ATTACHMENT_WRITE_FAILED') {
+        throw new AcpContentError(error.message, 'invalid', { cause: error })
+      }
+      throw new AcpContentError('unable to persist the prompt image batch', 'internal', { cause: error })
+    }
+    signal.throwIfAborted()
+  }
+
+  const content: ContentBlock[] = []
+  let pendingText = ''
+  let imageIndex = 0
+  const flushText = (): void => {
+    if (pendingText.length === 0) return
+    content.push({ type: 'text', text: pendingText })
+    pendingText = ''
+  }
+  for (const block of prompt) {
+    switch (block.type) {
+      case 'text':
+        pendingText += block.text
+        break
+      case 'resource_link':
+        pendingText += resourceLinkText(block)
+        break
+      case 'image': {
+        flushText()
+        const ref = refs[imageIndex++] as ImageAttachmentRef
+        content.push({ type: 'image', attachment: ref })
+        break
+      }
+      /* v8 ignore start -- the validation pass above rejects both tags before reconstruction. */
+      case 'audio':
+      case 'resource':
+        break
+      /* v8 ignore stop */
+      /* v8 ignore next 2 -- validated by the first closed-union switch. */
+      default:
+        break
+    }
+  }
+  flushText()
+  if (!content.some(block => block.type === 'image' || (block.type === 'text' && block.text.trim().length > 0))) {
+    throw new AcpContentError('empty prompt', 'invalid')
+  }
+  return content
+}
+
+/**
+ * Translate one committed assistant block to ACP wire content.
+ * Images are re-read and integrity-verified before inline base64 delivery;
+ * unsupported core output blocks stay off the automation wire.
+ * @param ctx - bridge context carrying the authoritative attachment store.
+ * @param block - committed core assistant block.
+ * @returns ACP text/image content, or undefined for non-output blocks.
+ */
+export async function assistantBlockToAcp(
+  ctx: Context,
+  block: ContentBlock,
+): Promise<AcpContentBlock | undefined> {
+  if (block.type === 'text') {
+    return block.text.length === 0 ? undefined : { type: 'text', text: block.text }
+  }
+  if (block.type !== 'image') return undefined
+  const attachments = ctx.get('attachments')
+  if (attachments === undefined) {
+    throw new AcpContentError('cannot deliver assistant image: no attachment store is mounted', 'internal')
+  }
+  let stored: Awaited<ReturnType<typeof attachments.readImage>>
+  try {
+    stored = await attachments.readImage(block.attachment)
+  } catch (error: unknown) {
+    throw new AcpContentError('cannot deliver assistant image: the attachment is unavailable or corrupt', 'internal', { cause: error })
+  }
+  return {
+    type: 'image',
+    data: Buffer.from(stored.data).toString('base64'),
+    mimeType: stored.ref.mediaType,
+  }
+}

packages/acp/acp/src/index.ts

@@ -2,9 +2,9 @@
  * Automation-only Agent Client Protocol server over JSON-RPC stdio.
  *
  * The bridge exposes fresh harness sessions to trusted programmatic clients. It
- * carries prompt text, committed assistant text, cancellation, and one-shot
- * permission decisions; presentation and human-interaction features stay with
- * the harness's UI modules.
+ * carries prompt text/images, committed assistant text/images, cancellation,
+ * and one-shot permission decisions; presentation and human-interaction
+ * features stay with the harness's UI modules.
  *
  * @module @deepseek-ai/dsh-acp
  */
@@ -37,7 +37,8 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session'
 // Side-effect type import: declaration-merges the approval waterfall answered below.
 import type {} from '@deepseek-ai/dsh-user-approval'
-import { acpPromptToText, promptHasUnsupportedContent, turnEndToStopReason } from './codec.ts'
+import { AcpContentError, admitAcpPrompt, assistantBlockToAcp, supportsAcpImagePrompts } from './content.ts'
+import { turnEndToStopReason } from './codec.ts'
 
 export const name = 'acp'
 /** The bridge creates and owns agents; every other concern is carried by the agent composition. */
@@ -86,14 +87,27 @@ interface SessionRecord {
   agent: Agent
   /** Exact owned-agent disposer; resolves after registry, loop, and session teardown. */
   dispose: () => Promise<void>
-  /** In-flight prompt and its captured turn number for exact settlement. */
+  /** Ordered assistant-output delivery; every task contains its own failure. */
+  outputTail: Promise<void>
+  /** In-flight admission/turn/output lifecycle for exact settlement. */
   inflight: {
     resolve: (reason: StopReason) => void
     reject: (error: Error) => void
-    messageId: string
+    /** Set only after rich-content admission succeeds and the message is built. */
+    messageId: string | undefined
     turn: number | undefined
     /** The correlated turn's ending, set at turn/end and settled at whole-agent idle. */
     endReason: TurnEndReason | undefined
+    /** Admission quiescence gate, including any attachment write already in progress. */
+    admissionDone: Promise<void>
+    finishAdmission: () => void
+    admissionController: AbortController
+    cancelRequested: boolean
+    settlementStarted: boolean
+    /** Conversion failure for committed output owned by this prompt's turn. */
+    outputError: Error | undefined
+    /** Failure before a correlated turn exists. */
+    agentError: Error | undefined
   } | undefined
 }
 
@@ -110,6 +124,7 @@ export function apply(ctx: Context, config: AcpConfig): void {
   const sessions = new Map<SessionId, SessionRecord>()
   let closed = false
   let conn: AgentSideConnection
+  let imagePromptEnabled = false
 
   /** Return the bridge-owned record for an agent, rejecting same-id impostors. */
   const ownedRecord = (agent: Agent): SessionRecord | undefined => {
@@ -127,19 +142,15 @@ export function apply(ctx: Context, config: AcpConfig): void {
     return record
   }
 
-  /** Send a protocol update without letting a disconnected client fail an agent turn. */
-  const notify = (notification: SessionNotification): void => {
-    /* v8 ignore next 3 -- only a transport write failure reaches this guard. */
-    void conn.sessionUpdate(notification).catch((error: unknown) => {
+  /** Send one ordered protocol update while containing transport-only failure. */
+  const notify = async (notification: SessionNotification): Promise<void> => {
+    try {
+      await conn.sessionUpdate(notification)
+    /* v8 ignore start -- the ACP SDK contains notification-handler failures; only a transport write failure reaches this guard. */
+    } catch (error: unknown) {
       logger.warn(`acp: session/update failed: ${String(error)}`)
-    })
-  }
-
-  const settlePrompt = (record: SessionRecord, reason: StopReason): void => {
-    const inflight = record.inflight
-    if (inflight === undefined) return
-    record.inflight = undefined
-    inflight.resolve(reason)
+    }
+    /* v8 ignore stop */
   }
 
   const rejectFromError = (
@@ -149,48 +160,89 @@ export function apply(ctx: Context, config: AcpConfig): void {
     inflight.reject(internalError(`turn failed: ${reason.error.message}`))
   }
 
-  // Emit only committed assistant text. Raw chunks, reasoning, tools, plans,
-  // titles, and retry markers are presentation or trace data and stay off the
-  // automation wire.
+  /**
+   * Settle one exact prompt only after admission, agent activity, and ordered
+   * assistant delivery have all reached quiescence.
+   */
+  const settleAfterQuiescence = (
+    record: SessionRecord,
+    inflight: NonNullable<SessionRecord['inflight']>,
+  ): void => {
+    if (inflight.settlementStarted) return
+    inflight.settlementStarted = true
+    void (async () => {
+      await inflight.admissionDone
+      await record.agent.whenIdle()
+      // session/event enqueues synchronously before the agent becomes idle;
+      // reading the live tail here includes every committed output task.
+      await record.outputTail
+      /* v8 ignore next -- this prompt owns the slot until this exact settlement clears it. */
+      if (record.inflight !== inflight) return
+      record.inflight = undefined
+      if (inflight.cancelRequested) {
+        inflight.resolve('cancelled')
+        return
+      }
+      if (inflight.outputError !== undefined) {
+        inflight.reject(internalError(`assistant output delivery failed: ${inflight.outputError.message}`))
+        return
+      }
+      if (inflight.agentError !== undefined) {
+        inflight.reject(internalError(`turn failed: ${inflight.agentError.message}`))
+        return
+      }
+      const end = inflight.endReason
+      if (end === undefined) {
+        inflight.resolve('cancelled')
+      } else if (end.kind === 'error') {
+        rejectFromError(inflight, end)
+      } else {
+        // Token-limit and other non-terminal endings are not prompt-level stop
+        // reasons; ordinary quiescence reports end_turn.
+        inflight.resolve(end.kind === 'max-tokens' ? 'end_turn' : turnEndToStopReason(end))
+      }
+    })()
+    /* v8 ignore start -- admissionDone only resolves, whenIdle is a quiescence gate, and outputTail contains its own failures. */
+      .catch((error: unknown) => {
+        if (record.inflight !== inflight) return
+        record.inflight = undefined
+        inflight.reject(internalError(`prompt settlement failed: ${errorChain(error)}`))
+      })
+    /* v8 ignore stop */
+  }
+
+  // Emit only committed assistant text/images. Raw chunks, reasoning, tools,
+  // plans, titles, and retry markers are presentation or trace data and stay
+  // off the automation wire. One per-session chain preserves block/message
+  // order across asynchronous attachment reads.
   ctx.on('session/event', (session, event: SessionEvent) => {
     const record = sessions.get(session.header.id)
     if (record === undefined || record.agent.session !== session) return
     try {
       if (event.type === 'assistant/message') {
-        for (const block of event.data.message.content) {
-          if (block.type === 'text' && block.text.length > 0) {
-            notify({
-              sessionId: record.agent.session.id,
-              update: {
-                sessionUpdate: 'agent_message_chunk',
-                content: { type: 'text', text: block.text },
-              },
-            })
-          } else if (block.type === 'image') {
-            notify({
+        const inflight = record.inflight?.turn === event.data.turn ? record.inflight : undefined
+        const previous = record.outputTail
+        const delivery = previous.then(async () => {
+          for (const block of event.data.message.content) {
+            const content = await assistantBlockToAcp(ctx, block)
+            if (content === undefined) continue
+            await notify({
               sessionId: record.agent.session.id,
-              update: {
-                sessionUpdate: 'agent_message_chunk',
-                content: {
-                  type: 'text',
-                  text: `[image attachment ${block.attachment.attachmentId}]`,
-                },
-              },
+              update: { sessionUpdate: 'agent_message_chunk', content },
             })
           }
-        }
+        })
+        record.outputTail = delivery.catch((error: unknown) => {
+          // assistantBlockToAcp owns conversion failures and always throws Error.
+          const failure = error as Error
+          if (inflight !== undefined) inflight.outputError ??= failure
+          logger.warn(`acp: assistant output conversion failed: ${errorChain(error)}`)
+        })
       }
     } finally {
       const inflight = record.inflight
       if (inflight !== undefined && event.type === 'turn/end' && inflight.turn === event.data.turn) {
-        if (event.data.reason.kind === 'error') {
-          // Model failures surface immediately as prompt errors; ordinary
-          // endings wait for whole-agent idle below.
-          record.inflight = undefined
-          rejectFromError(inflight, event.data.reason)
-        } else {
-          inflight.endReason = event.data.reason
-        }
+        inflight.endReason = event.data.reason
       }
     }
   })
@@ -205,8 +257,8 @@ export function apply(ctx: Context, config: AcpConfig): void {
     const record = ownedRecord(agent)
     const inflight = record?.inflight
     if (record === undefined || inflight === undefined || inflight.turn === turn) return
-    record.inflight = undefined
-    inflight.reject(internalError(`turn failed: ${errorChain(error)}`))
+    inflight.agentError = new Error(errorChain(error))
+    settleAfterQuiescence(record, inflight)
   })
 
   // Permission requests are a machine policy channel for ACP clients such as
@@ -231,17 +283,18 @@ export function apply(ctx: Context, config: AcpConfig): void {
   const makeAgent = (connection: AgentSideConnection): AcpAgent => {
     conn = connection
     return {
-      initialize(_params: InitializeRequest): Promise<InitializeResponse> {
+      async initialize(_params: InitializeRequest): Promise<InitializeResponse> {
         // Single-version agent: the spec's "same version if supported, else
         // the latest supported" both resolve to this server's one version.
-        return Promise.resolve({
+        imagePromptEnabled = await supportsAcpImagePrompts(ctx, config.provider, config.model)
+        return {
           protocolVersion: PROTOCOL_VERSION,
           agentInfo: { name: 'deepseek-harness-acp', version: '0.0.1' },
           agentCapabilities: {
-            promptCapabilities: { image: false, audio: false, embeddedContext: false },
+            promptCapabilities: { image: imagePromptEnabled, audio: false, embeddedContext: false },
           },
           authMethods: [],
-        })
+        }
       },
 
       authenticate(_params: AuthenticateRequest): Promise<void> {
@@ -269,6 +322,7 @@ export function apply(ctx: Context, config: AcpConfig): void {
         sessions.set(sessionId, {
           agent: handle.agent,
           dispose: () => handle.dispose(),
+          outputTail: Promise.resolve(),
           inflight: undefined,
         })
         return { sessionId }
@@ -280,66 +334,91 @@ export function apply(ctx: Context, config: AcpConfig): void {
         if (record.inflight !== undefined) {
           throw invalidParams('a prompt is already in flight for this session')
         }
-        if (promptHasUnsupportedContent(params.prompt)) {
-          throw invalidParams('only text and resource_link prompt content is supported')
+        const completion = Promise.withResolvers<StopReason>()
+        const admission = Promise.withResolvers<void>()
+        const admissionController = new AbortController()
+        const inflight: NonNullable<SessionRecord['inflight']> = {
+          resolve: completion.resolve,
+          reject: completion.reject,
+          messageId: undefined,
+          turn: undefined,
+          endReason: undefined,
+          admissionDone: admission.promise,
+          finishAdmission: admission.resolve,
+          admissionController,
+          cancelRequested: false,
+          settlementStarted: false,
+          outputError: undefined,
+          agentError: undefined,
         }
-        const text = acpPromptToText(params.prompt)
-        if (text.trim().length === 0) throw invalidParams('empty prompt')
-
-        // Not driving a retired agent is this bridge's contract: an
-        // agent-loop-only reload disposes the loop's agents while the bridge
-        // record survives, so validate the record against the live registry
-        // before sending — a disposed machine would accept the item silently.
-        if (ctx.agents.get(record.agent.id) !== record.agent) {
-          throw internalError('prompt was not queued: the agent was disposed outside the bridge')
-        }
-        const message = createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
-        const stopReason = await new Promise<StopReason>((resolve, reject) => {
-          // Arm the slot before followup() so a listener-driven synchronous
-          // turn cannot slip past correlation; a synchronous followup()
-          // failure (invalid input) must free the slot again or the session
-          // would reject every later prompt as already in flight.
-          const inflight: NonNullable<SessionRecord['inflight']> = {
-            resolve, reject, messageId: message.id, turn: undefined, endReason: undefined,
+        // Reserve the one-prompt slot before the first asynchronous route or
+        // attachment operation so concurrent prompts and cancellation observe
+        // admission as genuinely in flight.
+        record.inflight = inflight
+
+        let admissionFailed = false
+        let admissionFailure: unknown
+        try {
+          // Do not persist rich content for a retired destination. Re-check
+          // after admission too because an agent-loop reload may race storage.
+          if (ctx.agents.get(record.agent.id) !== record.agent) {
+            throw internalError('prompt was not queued: the agent was disposed outside the bridge')
           }
-          record.inflight = inflight
-          try {
-            record.agent.followup(message)
-            // The machine's send() contains listener failures and accepts
-            // any typed input; this guards a future synchronous throw so the
-            // slot cannot wedge.
-            /* v8 ignore start -- future-proofing guard, see above */
-          } catch (error: unknown) {
-            record.inflight = undefined
-            const detail = error instanceof Error ? error.message : String(error)
-            throw internalError(`prompt was not queued: ${detail}`)
+          const content = await admitAcpPrompt(
+            ctx,
+            record.agent,
+            params.prompt,
+            imagePromptEnabled,
+            admissionController.signal,
+          )
+          // No await may separate this final abort check from followup: a
+          // cancellation that wins admission must never enqueue a late turn.
+          admissionController.signal.throwIfAborted()
+          if (ctx.agents.get(record.agent.id) !== record.agent) {
+            throw internalError('prompt was not queued: the agent was disposed outside the bridge')
           }
-          /* v8 ignore stop */
-          // Settlement waits for whole-agent idle: a correlated turn/end arms
-          // `endReason`, while a turnless slot (admission discarded the
-          // prompt) stays cancelled. Other producers may run further turns
-          // before quiescence; the prompt settles only when the agent stops.
-          void record.agent.whenIdle().then(() => {
-            if (record.inflight !== inflight) return
-            record.inflight = undefined
-            const end = inflight.endReason
-            if (end === undefined) {
-              inflight.resolve('cancelled')
-            } else {
-              // Token-limit and other non-terminal endings are not prompt-level
-              // stop reasons (see README); only normal quiescence reports end_turn.
-              inflight.resolve(end.kind === 'max-tokens' ? 'end_turn' : turnEndToStopReason(end))
-            }
-          })
-        })
+          const message = createUserMessage({ content, source: { kind: 'user' } })
+          inflight.messageId = message.id
+          record.agent.followup(message)
+        } catch (error: unknown) {
+          admissionFailed = true
+          admissionFailure = error
+        } finally {
+          inflight.finishAdmission()
+        }
+
+        if (inflight.cancelRequested) {
+          settleAfterQuiescence(record, inflight)
+          return { stopReason: await completion.promise }
+        }
+        if (admissionFailed) {
+          record.inflight = undefined
+          if (admissionFailure instanceof AcpContentError) {
+            throw admissionFailure.kind === 'invalid'
+              ? invalidParams(admissionFailure.message)
+              : internalError(admissionFailure.message)
+          }
+          if (admissionFailure instanceof RequestError) throw admissionFailure
+          // The admission codec and same-process agent seam throw Error values.
+          const detail = (admissionFailure as Error).message
+          throw internalError(`prompt was not queued: ${detail}`)
+        }
+
+        settleAfterQuiescence(record, inflight)
+        const stopReason = await completion.promise
         return { stopReason }
       },
 
       cancel(params: CancelNotification): Promise<void> {
         const record = sessions.get(SessionId(params.sessionId))
         if (record === undefined) return Promise.resolve()
+        const inflight = record.inflight
+        if (inflight !== undefined) {
+          inflight.cancelRequested = true
+          inflight.admissionController.abort(new Error('ACP prompt cancelled'))
+          settleAfterQuiescence(record, inflight)
+        }
         record.agent.cancel({ kind: 'user' })
-        settlePrompt(record, 'cancelled')
         return Promise.resolve()
       },
     }
@@ -362,10 +441,24 @@ export function apply(ctx: Context, config: AcpConfig): void {
     // on persistence or scoped cleanup, and the top-level agents must not keep
     // running model and tool calls for its whole duration.
     for (const record of records) {
+      const inflight = record.inflight
+      if (inflight !== undefined) {
+        inflight.cancelRequested = true
+        inflight.admissionController.abort(new Error('ACP bridge disposed'))
+        settleAfterQuiescence(record, inflight)
+      }
       record.agent.cancel({ kind: 'user' })
-      settlePrompt(record, 'cancelled')
     }
     quiescing = (async () => {
+      // Preserve the same prompt boundary during connection teardown: a rich
+      // admission already writing must stop before its slot settles, and every
+      // committed output conversion must drain while attachment services remain
+      // available. session/event enqueues output synchronously before idle.
+      await Promise.all(records.map(async (record) => {
+        await record.inflight?.admissionDone
+        await record.agent.whenIdle()
+        await record.outputTail
+      }))
       // Continuable subagents outlive the turn that started them, and their
       // Activations own descendant teardown. Drain only these sessions' forests
       // child-first BEFORE disposing the top-level agents, so no descendant is

packages/acp/acp/tests/bridge.spec.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
+import { AttachmentError } from '@deepseek-ai/dsh-attachment'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { makeBridgeHarness, textResponse, type BridgeHarness } from './harness.ts'
 
@@ -28,6 +29,17 @@ describe('automation-only ACP bridge', () => {
     })
   })
 
+  it('advertises image prompts only with an exact capable route and attachment store', async () => {
+    harness = await makeBridgeHarness({ imageCapable: true })
+    const capable = await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    expect(capable.agentCapabilities?.promptCapabilities?.image).toBe(true)
+    await harness.dispose()
+
+    harness = await makeBridgeHarness({ imageCapable: true, attachments: false })
+    const noStore = await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    expect(noStore.agentCapabilities?.promptCapabilities?.image).toBe(false)
+  })
+
   it('negotiates an unsupported version and accepts the required no-op authentication call', async () => {
     harness = await makeBridgeHarness()
     const response = await harness.client.initialize({ protocolVersion: 0, clientCapabilities: {} })
@@ -77,6 +89,73 @@ describe('automation-only ACP bridge', () => {
     expect(harness.adapter.requests[0]?.messages.at(-1)?.content).toEqual([{ type: 'text', text: 'first second' }])
   })
 
+  it('admits mixed text/image prompts in wire order and logs references only', async () => {
+    harness = await makeBridgeHarness({ imageCapable: true, script: [textResponse('done')] })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const resolve = vi.spyOn(harness.ctx.llm, 'resolveModelInfo')
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+
+    await harness.client.prompt({
+      sessionId,
+      prompt: [
+        { type: 'text', text: 'before' },
+        { type: 'image', data: 'AQ==', mimeType: 'image/png' },
+        { type: 'text', text: 'between' },
+        { type: 'image', data: 'Ag==', mimeType: 'image/jpeg' },
+        { type: 'text', text: 'after' },
+      ],
+    })
+
+    expect(resolve).toHaveBeenCalledWith('mock', 'mock', expect.any(AbortSignal))
+    expect(harness.attachments?.saved.map(input => [...input.data])).toEqual([[1], [2]])
+    const requestContent = harness.adapter.requests[0]?.messages.at(-1)?.content
+    expect(requestContent?.map(block => block.type)).toEqual(['text', 'image', 'text', 'image', 'text'])
+    expect(requestContent?.[0]).toEqual({ type: 'text', text: 'before' })
+    expect(requestContent?.[2]).toEqual({ type: 'text', text: 'between' })
+    expect(requestContent?.[4]).toEqual({ type: 'text', text: 'after' })
+    const firstImage = requestContent?.[1]
+    const secondImage = requestContent?.[3]
+    if (firstImage?.type !== 'image' || secondImage?.type !== 'image') throw new Error('expected ordered image blocks')
+    expect(firstImage.attachment.mediaType).toBe('image/png')
+    expect(firstImage.attachment.bytes).toBe(1)
+    expect(secondImage.attachment.mediaType).toBe('image/jpeg')
+    expect(secondImage.attachment.bytes).toBe(1)
+    const agent = harness.ctx.agents.get(SessionId(sessionId))
+    expect(JSON.stringify(agent?.session.events)).not.toContain('AQ==')
+  })
+
+  it('rejects a malformed image batch atomically and frees the prompt slot', async () => {
+    harness = await makeBridgeHarness({ imageCapable: true, script: [textResponse('recovered')] })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+
+    await expect(harness.client.prompt({
+      sessionId,
+      prompt: [
+        { type: 'image', data: 'AQ==', mimeType: 'image/png' },
+        { type: 'image', data: 'not base64', mimeType: 'image/png' },
+      ],
+    })).rejects.toThrow(/canonical base64/)
+    expect(harness.attachments?.saved).toEqual([])
+
+    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'retry' }] }))
+      .resolves.toEqual({ stopReason: 'end_turn' })
+  })
+
+  it('reports durable image write failures as internal prompt failures', async () => {
+    harness = await makeBridgeHarness({ imageCapable: true })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    vi.spyOn(harness.attachments!, 'saveImages').mockRejectedValueOnce(
+      new AttachmentError('disk failed', 'ATTACHMENT_WRITE_FAILED'),
+    )
+
+    await expect(harness.client.prompt({
+      sessionId,
+      prompt: [{ type: 'image', data: 'AQ==', mimeType: 'image/png' }],
+    })).rejects.toThrow(/unable to persist the prompt image batch/)
+  })
+
   it('renders the deployment persona for an ACP-created agent', async () => {
     harness = await makeBridgeHarness({ persona: 'Automation persona for {{model}} in {{cwd}}.', script: [textResponse('ok')] })
     await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
@@ -107,7 +186,7 @@ describe('automation-only ACP bridge', () => {
     })).resolves.toHaveProperty('sessionId')
   })
 
-  it('rejects empty and beyond-baseline prompts before a turn starts', async () => {
+  it('rejects empty and unadvertised image prompts before a turn starts', async () => {
     harness = await makeBridgeHarness()
     await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
     const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
@@ -117,7 +196,7 @@ describe('automation-only ACP bridge', () => {
     await expect(harness.client.prompt({
       sessionId,
       prompt: [{ type: 'image', data: '', mimeType: 'image/png' }],
-    })).rejects.toThrow(/only text and resource_link/)
+    })).rejects.toThrow(/inline image prompts were not advertised/)
     expect(harness.ctx.agents.get(SessionId(sessionId))?.session.events.some(event => event.type === 'turn/start')).toBe(false)
   })
 

packages/acp/acp/tests/codec.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import type { TurnEndReason } from '@deepseek-ai/dsh-session'
-import { acpPromptToText, turnEndToStopReason } from '../src/codec.ts'
+import { turnEndToStopReason } from '../src/codec.ts'
 
 describe('ACP codec', () => {
   it.each([
@@ -13,12 +13,4 @@ describe('ACP codec', () => {
   ] satisfies Array<[TurnEndReason, string]>)('maps %o to %s', (reason, expected) => {
     expect(turnEndToStopReason(reason)).toBe(expected)
   })
-
-  it('drops unsupported blocks from baseline text conversion', () => {
-    expect(acpPromptToText([{
-      type: 'image',
-      data: '',
-      mimeType: 'image/png',
-    }])).toBe('')
-  })
 })

packages/acp/acp/tests/content.spec.ts

@@ -0,0 +1,232 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { Context } from '@deepseek-ai/cordis'
+import { AttachmentError, AttachmentId } from '@deepseek-ai/dsh-attachment'
+import type { ImageAttachmentRef, SaveImageAttachment } from '@deepseek-ai/dsh-attachment'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import {
+  AcpContentError,
+  admitAcpPrompt,
+  assistantBlockToAcp,
+  supportsAcpImagePrompts,
+} from '../src/content.ts'
+
+const REF: ImageAttachmentRef = {
+  attachmentId: AttachmentId(`sha256:${'1'.repeat(64)}`),
+  mediaType: 'image/png',
+  bytes: 1,
+  width: 1,
+  height: 1,
+}
+
+interface AdmissionFixture {
+  ctx: Context
+  agent: Agent
+  saveImages: ReturnType<typeof vi.fn<(inputs: readonly SaveImageAttachment[]) => Promise<readonly ImageAttachmentRef[]>>>
+  resolveModelInfo: ReturnType<typeof vi.fn>
+}
+
+function admissionFixture(options: {
+  attachments?: boolean
+  llm?: boolean
+  provider?: string | undefined
+  model?: string | undefined
+  header?: { provider?: string; model?: string }
+} = {}): AdmissionFixture {
+  const saveImages = vi.fn(async (inputs: readonly SaveImageAttachment[]) => inputs.map((input, index) => ({
+    ...REF,
+    attachmentId: AttachmentId(`sha256:${String(index + 1).padStart(64, '0')}`),
+    mediaType: input.mediaType,
+    bytes: input.data.byteLength,
+  })))
+  const resolveModelInfo = vi.fn(async (provider: string, model: string) => ({
+    provider,
+    id: model,
+    name: model,
+    inputModalities: ['text', 'image'] as const,
+  }))
+  const attachments = options.attachments === false ? undefined : { saveImages }
+  const llm = options.llm === false ? undefined : { resolveModelInfo }
+  const ctx = {
+    get(name: string) {
+      if (name === 'attachments') return attachments
+      if (name === 'llm') return llm
+      return undefined
+    },
+  } as unknown as Context
+  const provider = 'provider' in options ? options.provider : 'mock'
+  const model = 'model' in options ? options.model : 'vision'
+  const agent = {
+    options: { provider, model },
+    session: { requestHeader: () => options.header === undefined ? undefined : { config: options.header } },
+  } as unknown as Agent
+  return { ctx, agent, saveImages, resolveModelInfo }
+}
+
+describe('ACP rich content codec', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('advertises image input only when every deployment prerequisite is explicit', async () => {
+    const absent = (attachments: unknown, llm: unknown): Context => ({
+      get: (name: string) => name === 'attachments' ? attachments : name === 'llm' ? llm : undefined,
+    }) as unknown as Context
+    const store = { imageLimits: { mediaTypes: ['image/png'] } }
+    const noMediaStore = { imageLimits: { mediaTypes: [] } }
+    const imageLlm = { resolveModelInfo: vi.fn().mockResolvedValue({ inputModalities: ['text', 'image'] }) }
+    const textLlm = { resolveModelInfo: vi.fn().mockResolvedValue({ inputModalities: ['text'] }) }
+    const unknownLlm = { resolveModelInfo: vi.fn().mockResolvedValue({}) }
+    const brokenLlm = { resolveModelInfo: vi.fn().mockRejectedValue(new Error('catalog down')) }
+
+    await expect(supportsAcpImagePrompts(absent(undefined, imageLlm), 'p', 'm')).resolves.toBe(false)
+    await expect(supportsAcpImagePrompts(absent(store, undefined), 'p', 'm')).resolves.toBe(false)
+    await expect(supportsAcpImagePrompts(absent(store, imageLlm), undefined, 'm')).resolves.toBe(false)
+    await expect(supportsAcpImagePrompts(absent(store, imageLlm), 'p', undefined)).resolves.toBe(false)
+    await expect(supportsAcpImagePrompts(absent(noMediaStore, imageLlm), 'p', 'm')).resolves.toBe(false)
+    await expect(supportsAcpImagePrompts(absent(store, brokenLlm), 'p', 'm')).resolves.toBe(false)
+    await expect(supportsAcpImagePrompts(absent(store, unknownLlm), 'p', 'm')).resolves.toBe(false)
+    await expect(supportsAcpImagePrompts(absent(store, textLlm), 'p', 'm')).resolves.toBe(false)
+    await expect(supportsAcpImagePrompts(absent(store, imageLlm), 'p', 'm')).resolves.toBe(true)
+  })
+
+  it('validates every rich wire block before any image write', async () => {
+    const fixture = admissionFixture()
+    const signal = new AbortController().signal
+
+    await expect(admitAcpPrompt(fixture.ctx, fixture.agent, [
+      { type: 'image', data: 'AQ==', mimeType: 'image/tiff' },
+    ] as never, true, signal)).rejects.toThrow(/mimeType/)
+    await expect(admitAcpPrompt(fixture.ctx, fixture.agent, [
+      { type: 'image', data: 'not base64', mimeType: 'image/png' },
+    ], true, signal)).rejects.toThrow(/canonical base64/)
+    await expect(admitAcpPrompt(fixture.ctx, fixture.agent, [
+      { type: 'image', data: 'AB==', mimeType: 'image/png' },
+    ], true, signal)).rejects.toThrow(/canonical base64/)
+    await expect(admitAcpPrompt(fixture.ctx, fixture.agent, [
+      { type: 'audio', data: 'AQ==', mimeType: 'audio/wav' },
+    ], true, signal)).rejects.toThrow(/audio prompt/)
+    await expect(admitAcpPrompt(fixture.ctx, fixture.agent, [
+      { type: 'resource', resource: { uri: 'file:///tmp/a', text: 'a' } },
+    ], true, signal)).rejects.toThrow(/embedded resource/)
+    expect(fixture.saveImages).not.toHaveBeenCalled()
+  })
+
+  it('requires the advertised capability, store, and exact image-capable route', async () => {
+    const prompt = [{ type: 'image', data: 'AQ==', mimeType: 'image/png' }] as const
+    const capable = admissionFixture()
+    await expect(admitAcpPrompt(capable.ctx, capable.agent, prompt, false, new AbortController().signal))
+      .rejects.toThrow(/not advertised/)
+
+    const noStore = admissionFixture({ attachments: false })
+    await expect(admitAcpPrompt(noStore.ctx, noStore.agent, prompt, true, new AbortController().signal))
+      .rejects.toThrow(/no attachment store/)
+
+    const noProvider = admissionFixture({ provider: undefined })
+    await expect(admitAcpPrompt(noProvider.ctx, noProvider.agent, prompt, true, new AbortController().signal))
+      .rejects.toThrow(/route could not be resolved/)
+    const noModel = admissionFixture({ model: undefined })
+    await expect(admitAcpPrompt(noModel.ctx, noModel.agent, prompt, true, new AbortController().signal))
+      .rejects.toThrow(/route could not be resolved/)
+    const noLlm = admissionFixture({ llm: false })
+    await expect(admitAcpPrompt(noLlm.ctx, noLlm.agent, prompt, true, new AbortController().signal))
+      .rejects.toThrow(/route could not be resolved/)
+
+    const broken = admissionFixture()
+    broken.resolveModelInfo.mockRejectedValueOnce(new Error('catalog down'))
+    await expect(admitAcpPrompt(broken.ctx, broken.agent, prompt, true, new AbortController().signal))
+      .rejects.toThrow(/route could not be verified/)
+    const unknown = admissionFixture()
+    unknown.resolveModelInfo.mockResolvedValueOnce({ provider: 'mock', id: 'vision', name: 'vision' })
+    await expect(admitAcpPrompt(unknown.ctx, unknown.agent, prompt, true, new AbortController().signal))
+      .rejects.toThrow(/does not declare image input/)
+    const textOnly = admissionFixture()
+    textOnly.resolveModelInfo.mockResolvedValueOnce({
+      provider: 'mock', id: 'vision', name: 'vision', inputModalities: ['text'],
+    })
+    await expect(admitAcpPrompt(textOnly.ctx, textOnly.agent, prompt, true, new AbortController().signal))
+      .rejects.toThrow(/does not declare image input/)
+
+    const routed = admissionFixture({ provider: 'fallback', model: 'fallback', header: { provider: 'live', model: 'vision-2' } })
+    await expect(admitAcpPrompt(routed.ctx, routed.agent, prompt, true, new AbortController().signal)).resolves.toHaveLength(1)
+    expect(routed.resolveModelInfo).toHaveBeenCalledWith('live', 'vision-2', expect.any(AbortSignal))
+  })
+
+  it('classifies image-policy failures separately from durable write failures', async () => {
+    const fixture = admissionFixture()
+    const prompt = [{ type: 'image', data: 'AQ==', mimeType: 'image/png' }] as const
+    fixture.saveImages.mockRejectedValueOnce(new AttachmentError('too many', 'TOO_MANY_IMAGES'))
+    await expect(admitAcpPrompt(fixture.ctx, fixture.agent, prompt, true, new AbortController().signal))
+      .rejects.toMatchObject({ kind: 'invalid', message: 'too many' })
+    fixture.saveImages.mockRejectedValueOnce(new AttachmentError('disk failed', 'ATTACHMENT_WRITE_FAILED'))
+    await expect(admitAcpPrompt(fixture.ctx, fixture.agent, prompt, true, new AbortController().signal))
+      .rejects.toMatchObject({ kind: 'internal', message: 'unable to persist the prompt image batch' })
+    fixture.saveImages.mockRejectedValueOnce(new Error('unknown store failure'))
+    await expect(admitAcpPrompt(fixture.ctx, fixture.agent, prompt, true, new AbortController().signal))
+      .rejects.toBeInstanceOf(AcpContentError)
+  })
+
+  it('honors cancellation on both sides of the durable image write', async () => {
+    const prompt = [{ type: 'image', data: 'AQ==', mimeType: 'image/png' }] as const
+    const before = admissionFixture()
+    const beforeController = new AbortController()
+    beforeController.abort(new Error('cancel before write'))
+    await expect(admitAcpPrompt(before.ctx, before.agent, prompt, true, beforeController.signal))
+      .rejects.toThrow('cancel before write')
+    expect(before.saveImages).not.toHaveBeenCalled()
+
+    const after = admissionFixture()
+    const afterController = new AbortController()
+    after.saveImages.mockImplementationOnce(async () => {
+      afterController.abort(new Error('cancel after write'))
+      return [REF]
+    })
+    await expect(admitAcpPrompt(after.ctx, after.agent, prompt, true, afterController.signal))
+      .rejects.toThrow('cancel after write')
+    expect(after.saveImages).toHaveBeenCalledOnce()
+  })
+
+  it('reconstructs image-only and baseline prompts without empty text blocks', async () => {
+    const fixture = admissionFixture()
+    const imageOnly = await admitAcpPrompt(fixture.ctx, fixture.agent, [
+      { type: 'image', data: 'AQ==', mimeType: 'image/png' },
+    ], true, new AbortController().signal)
+    expect(imageOnly).toHaveLength(1)
+    expect(imageOnly[0]?.type).toBe('image')
+    await expect(admitAcpPrompt(fixture.ctx, fixture.agent, [
+      { type: 'text', text: 'before' },
+      { type: 'resource_link', name: 'Guide', uri: 'https://example.test/guide' },
+      { type: 'text', text: 'after' },
+    ], true, new AbortController().signal)).resolves.toEqual([{
+      type: 'text',
+      text: 'before\n[resource_link name="Guide" uri="https://example.test/guide"]\nafter',
+    }])
+    await expect(admitAcpPrompt(fixture.ctx, fixture.agent, [
+      { type: 'text', text: ' \n ' },
+    ], true, new AbortController().signal)).rejects.toThrow(/empty prompt/)
+  })
+
+  it('projects only non-empty text and verified durable images to ACP', async () => {
+    const fixture = admissionFixture()
+    await expect(assistantBlockToAcp(fixture.ctx, { type: 'text', text: '' })).resolves.toBeUndefined()
+    await expect(assistantBlockToAcp(fixture.ctx, { type: 'text', text: 'hello' })).resolves.toEqual({
+      type: 'text', text: 'hello',
+    })
+    await expect(assistantBlockToAcp(fixture.ctx, { type: 'reasoning', text: 'private' })).resolves.toBeUndefined()
+
+    const noStore = admissionFixture({ attachments: false })
+    await expect(assistantBlockToAcp(noStore.ctx, { type: 'image', attachment: REF }))
+      .rejects.toThrow(/no attachment store/)
+    const readImage = vi.fn().mockRejectedValue(new AttachmentError('gone', 'ATTACHMENT_NOT_FOUND'))
+    const missingCtx = { get: (name: string) => name === 'attachments' ? { readImage } : undefined } as unknown as Context
+    await expect(assistantBlockToAcp(missingCtx, { type: 'image', attachment: REF }))
+      .rejects.toThrow(/unavailable or corrupt/)
+    const storedCtx = {
+      get: (name: string) => name === 'attachments'
+        ? { readImage: vi.fn().mockResolvedValue({ ref: REF, data: Uint8Array.of(1) }) }
+        : undefined,
+    } as unknown as Context
+    await expect(assistantBlockToAcp(storedCtx, { type: 'image', attachment: REF })).resolves.toEqual({
+      type: 'image', data: 'AQ==', mimeType: 'image/png',
+    })
+  })
+})

packages/acp/acp/tests/dispose.spec.ts

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { StreamChunk } from '@deepseek-ai/dsh-llm'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { makeBridgeHarness, type BridgeHarness } from './harness.ts'
 
@@ -26,6 +27,37 @@ describe('ACP connection ownership', () => {
     expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
   })
 
+  it('disposal drains asynchronous assistant image delivery before releasing sessions', async () => {
+    const script: StreamChunk[][] = []
+    harness = await makeBridgeHarness({ script })
+    const ref = await harness.attachments!.saveImage({ data: Uint8Array.of(4), mediaType: 'image/png' })
+    script.push([
+      { type: 'block-start', index: 0, blockType: 'image' },
+      { type: 'block-end', index: 0, block: { type: 'image', attachment: ref } },
+      { type: 'finish', reason: { kind: 'stop' } },
+    ])
+    const readStarted = Promise.withResolvers<undefined>()
+    const releaseRead = Promise.withResolvers<undefined>()
+    harness.attachments!.beforeRead = () => {
+      readStarted.resolve(undefined)
+      return releaseRead.promise
+    }
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    const prompt = harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'show it' }] })
+    await readStarted.promise
+
+    let disposed = false
+    const disposal = harness.acpFiber.dispose().finally(() => { disposed = true })
+    await Promise.resolve()
+    expect(disposed).toBe(false)
+
+    releaseRead.resolve(undefined)
+    await disposal
+    await expect(prompt).resolves.toEqual({ stopReason: 'cancelled' })
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
+  })
+
   it('drains continuable subagents before disposing its own sessions', async () => {
     harness = await makeBridgeHarness()
     const order: string[] = []

packages/acp/acp/tests/edges.spec.ts

@@ -54,6 +54,51 @@ describe('ACP automation output boundary', () => {
     expect(harness.updates).toHaveLength(0)
   })
 
+  it('delivers output from a bridge-owned session driven by another in-process producer', async () => {
+    harness = await makeBridgeHarness({ script: [textResponse('external')] })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
+
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'plugin', plugin: 'test' } }))
+    await agent.whenIdle()
+
+    expect(harness.updates).toEqual([{
+      sessionUpdate: 'agent_message_chunk',
+      content: { type: 'text', text: 'external' },
+    }])
+  })
+
+  it('contains output conversion failure outside an ACP prompt', async () => {
+    harness = await makeBridgeHarness({ script: [[
+      { type: 'block-start', index: 0, blockType: 'image' },
+      {
+        type: 'block-end',
+        index: 0,
+        block: {
+          type: 'image',
+          attachment: {
+            attachmentId: `sha256:${'a'.repeat(64)}` as never,
+            mediaType: 'image/png',
+            bytes: 1,
+            width: 1,
+            height: 1,
+          },
+        },
+      },
+      { type: 'finish', reason: { kind: 'stop' } },
+    ]] })
+    const warn = vi.spyOn(harness.ctx.logger, 'warn')
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
+
+    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'go' }], source: { kind: 'plugin', plugin: 'test' } }))
+    await agent.whenIdle()
+    await vi.waitFor(() => { expect(warn).toHaveBeenCalledWith(expect.stringContaining('output conversion failed')) })
+    expect(harness.updates).toEqual([])
+  })
+
   // `session/update` is a JSON-RPC notification, so a client-side handler
   // failure never reaches the bridge; this pins that the prompt still settles
   // normally with such a client. The bridge's own write-failure guard is

packages/acp/acp/tests/harness.ts

@@ -1,6 +1,7 @@
 /** In-memory ACP transport fixture over the real agent factory and loop. */
 
 import { Context } from '@deepseek-ai/cordis'
+import { createHash } from 'node:crypto'
 import {
   ClientSideConnection,
   ndJsonStream,
@@ -11,7 +12,9 @@ import {
   type SessionNotification,
   type Stream,
 } from '@agentclientprotocol/sdk'
-import { type GenerateOptions, LlmAdapter, type StreamChunk } from '@deepseek-ai/dsh-llm'
+import AttachmentStore, { AttachmentError, AttachmentId } from '@deepseek-ai/dsh-attachment'
+import type { ImageAttachmentLimits, ImageAttachmentRef, SaveImageAttachment, StoredImageAttachment } from '@deepseek-ai/dsh-attachment'
+import { type GenerateOptions, LlmAdapter, type LlmResolvedModelInfo, type StreamChunk } from '@deepseek-ai/dsh-llm'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import * as AcpPlugin from '../src/index.ts'
@@ -21,7 +24,10 @@ import type { AcpConfig } from '../src/index.ts'
 class MockAdapter extends LlmAdapter {
   readonly requests: GenerateOptions[] = []
 
-  constructor(private readonly script: (StreamChunk[] | 'hang')[]) {
+  constructor(
+    private readonly script: (StreamChunk[] | 'hang')[],
+    private readonly imageCapable: boolean,
+  ) {
     super()
   }
 
@@ -31,7 +37,21 @@ class MockAdapter extends LlmAdapter {
   }
 
   override listModels(provider: string) {
-    return Promise.resolve(provider === 'mock' ? [{ provider: 'mock', id: 'mock', name: 'Mock' }] : [])
+    return Promise.resolve(provider === 'mock' ? [{
+      provider: 'mock',
+      id: 'mock',
+      name: 'Mock',
+      inputModalities: this.imageCapable ? ['text', 'image'] as const : ['text'] as const,
+    }] : [])
+  }
+
+  override resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo> {
+    return Promise.resolve({
+      provider,
+      id: model,
+      name: model,
+      inputModalities: this.imageCapable ? ['text', 'image'] : ['text'],
+    })
   }
 
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
@@ -57,6 +77,49 @@ class MockAdapter extends LlmAdapter {
   }
 }
 
+const IMAGE_LIMITS: ImageAttachmentLimits = {
+  maxImageBytes: 1024,
+  maxImagesPerMessage: 4,
+  maxMessageImageBytes: 2048,
+  maxImagePixels: 1024,
+  mediaTypes: ['image/png', 'image/jpeg', 'image/webp', 'image/gif'],
+}
+
+/** In-memory durable store for ACP wire-order and lifecycle tests. */
+class MemoryAttachmentStore extends AttachmentStore {
+  readonly imageLimits = IMAGE_LIMITS
+  readonly saved: SaveImageAttachment[] = []
+  readonly objects = new Map<string, StoredImageAttachment>()
+  beforeValidate: (() => Promise<void>) | undefined
+  beforeRead: (() => Promise<void>) | undefined
+
+  async validateImage(input: SaveImageAttachment): Promise<void> {
+    await this.beforeValidate?.()
+    if (input.data.byteLength === 0) throw new AttachmentError('Image is empty.', 'INVALID_IMAGE')
+  }
+
+  saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef> {
+    this.saved.push(input)
+    const digest = createHash('sha256').update(input.data).digest('hex')
+    const ref: ImageAttachmentRef = {
+      attachmentId: AttachmentId(`sha256:${digest}`),
+      mediaType: input.mediaType,
+      bytes: input.data.byteLength,
+      width: 1,
+      height: 1,
+    }
+    this.objects.set(ref.attachmentId, { ref, data: Uint8Array.from(input.data) })
+    return Promise.resolve(ref)
+  }
+
+  async readImage(ref: ImageAttachmentRef): Promise<StoredImageAttachment> {
+    await this.beforeRead?.()
+    const stored = this.objects.get(ref.attachmentId)
+    if (stored === undefined) throw new AttachmentError('Attachment object is missing.', 'ATTACHMENT_NOT_FOUND')
+    return { ref: stored.ref, data: Uint8Array.from(stored.data) }
+  }
+}
+
 /** Scripted text response ending in a clean stop. */
 export function textResponse(text: string): StreamChunk[] {
   return [
@@ -93,6 +156,7 @@ export interface BridgeHarness {
   ctx: Context
   client: ClientSideConnection
   adapter: MockAdapter
+  attachments: MemoryAttachmentStore | undefined
   updates: CapturedUpdate[]
   sessionUpdates: { sessionId: string; update: CapturedUpdate }[]
   permissionRequests: RequestPermissionRequest[]
@@ -113,10 +177,13 @@ export async function makeBridgeHarness(options: {
   script?: (StreamChunk[] | 'hang')[]
   config?: AcpConfigOverrides
   persona?: string
+  imageCapable?: boolean
+  attachments?: boolean
 } = {}): Promise<BridgeHarness> {
-  const adapter = new MockAdapter(options.script ?? [])
+  const adapter = new MockAdapter(options.script ?? [], options.imageCapable === true)
   const ctx = new Context()
   await mountAgentLoopTestDependencies(ctx, { systemPrompt: { persona: options.persona ?? '' } })
+  if (options.attachments !== false) await ctx.plugin(MemoryAttachmentStore)
   const loopFiber = await ctx.plugin(AgentLoop, { agents: [] })
   ctx.llm.registerAdapter(['mock'], adapter)
 
@@ -135,6 +202,7 @@ export async function makeBridgeHarness(options: {
   const harness: BridgeHarness = {
     ctx,
     adapter,
+    attachments: ctx.get('attachments') as MemoryAttachmentStore | undefined,
     updates,
     sessionUpdates,
     permissionRequests,

packages/acp/acp/tests/turns.spec.ts

@@ -1,4 +1,4 @@
-import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { createUserMessage, type StreamChunk } from '@deepseek-ai/dsh-llm'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import { SessionId } from '@deepseek-ai/dsh-session'
@@ -41,35 +41,100 @@ describe('ACP prompt lifecycle', () => {
     await vi.waitFor(() => { expect(messageText(harness!)).toBe('cut off') })
   })
 
-  it('renders an assistant image as an explicit attachment placeholder', async () => {
-    const attachmentId = `sha256:${'a'.repeat(64)}` as never
-    harness = await makeBridgeHarness({
-      script: [[
-        { type: 'block-start', index: 0, blockType: 'image' },
-        {
-          type: 'block-end',
-          index: 0,
-          block: {
-            type: 'image',
-            attachment: {
-              attachmentId,
-              mediaType: 'image/png',
-              bytes: 1,
-              width: 1,
-              height: 1,
-            },
-          },
+  it('delivers a committed assistant image as verified ACP base64', async () => {
+    const script: StreamChunk[][] = []
+    harness = await makeBridgeHarness({ script })
+    const ref = await harness.attachments!.saveImage({ data: Uint8Array.of(1), mediaType: 'image/png' })
+    script.push([
+      { type: 'block-start', index: 0, blockType: 'image' },
+      {
+        type: 'block-end',
+        index: 0,
+        block: {
+          type: 'image',
+          attachment: ref,
         },
-        { type: 'finish', reason: { kind: 'stop' } },
-      ]],
-    })
+      },
+      { type: 'finish', reason: { kind: 'stop' } },
+    ])
     const sessionId = await newSession(harness)
     await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'show it' }] })
-    await vi.waitFor(() => {
-      expect(messageText(harness!)).toBe(`[image attachment ${String(attachmentId)}]`)
+    expect(harness.updates).toContainEqual({
+      sessionUpdate: 'agent_message_chunk',
+      content: { type: 'image', data: 'AQ==', mimeType: 'image/png' },
     })
   })
 
+  it('preserves committed text/image/text order on the ACP wire', async () => {
+    const script: StreamChunk[][] = []
+    harness = await makeBridgeHarness({ script })
+    const ref = await harness.attachments!.saveImage({ data: Uint8Array.of(2), mediaType: 'image/jpeg' })
+    script.push([
+      { type: 'block-start', index: 0, blockType: 'text' },
+      { type: 'block-end', index: 0, block: { type: 'text', text: 'before' } },
+      { type: 'block-start', index: 1, blockType: 'image' },
+      { type: 'block-end', index: 1, block: { type: 'image', attachment: ref } },
+      { type: 'block-start', index: 2, blockType: 'text' },
+      { type: 'block-end', index: 2, block: { type: 'text', text: 'after' } },
+      { type: 'finish', reason: { kind: 'stop' } },
+    ])
+    const sessionId = await newSession(harness)
+
+    await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'show it' }] })
+
+    expect(harness.updates).toEqual([
+      { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'before' } },
+      { sessionUpdate: 'agent_message_chunk', content: { type: 'image', data: 'Ag==', mimeType: 'image/jpeg' } },
+      { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'after' } },
+    ])
+  })
+
+  it('does not settle a prompt before ordered output delivery drains', async () => {
+    const script: StreamChunk[][] = []
+    harness = await makeBridgeHarness({ script })
+    const ref = await harness.attachments!.saveImage({ data: Uint8Array.of(3), mediaType: 'image/png' })
+    script.push([
+      { type: 'block-start', index: 0, blockType: 'image' },
+      { type: 'block-end', index: 0, block: { type: 'image', attachment: ref } },
+      { type: 'finish', reason: { kind: 'stop' } },
+    ])
+    const readStarted = Promise.withResolvers<undefined>()
+    const delivery = Promise.withResolvers<undefined>()
+    harness.attachments!.beforeRead = () => {
+      readStarted.resolve(undefined)
+      return delivery.promise
+    }
+    const sessionId = await newSession(harness)
+    let settled = false
+
+    const prompt = harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })
+      .finally(() => { settled = true })
+    await readStarted.promise
+    expect(settled).toBe(false)
+    delivery.resolve(undefined)
+    await expect(prompt).resolves.toEqual({ stopReason: 'end_turn' })
+  })
+
+  it('fails prompt delivery when a committed image attachment is missing', async () => {
+    const missing = {
+      attachmentId: `sha256:${'a'.repeat(64)}` as never,
+      mediaType: 'image/png' as const,
+      bytes: 1,
+      width: 1,
+      height: 1,
+    }
+    harness = await makeBridgeHarness({ script: [[
+      { type: 'block-start', index: 0, blockType: 'image' },
+      { type: 'block-end', index: 0, block: { type: 'image', attachment: missing } },
+      { type: 'finish', reason: { kind: 'stop' } },
+    ]] })
+    const sessionId = await newSession(harness)
+
+    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'show it' }] }))
+      .rejects.toThrow(/assistant output delivery failed/)
+    expect(harness.updates).toEqual([])
+  })
+
   it('rejects a failed turn and never publishes its partial chunks', async () => {
     harness = await makeBridgeHarness({ script: [errorResponse('provider boom')] })
     const sessionId = await newSession(harness)
@@ -194,6 +259,84 @@ describe('ACP prompt lifecycle', () => {
     await expect(first).resolves.toEqual({ stopReason: 'cancelled' })
   })
 
+  it('reserves the prompt slot during image admission and cancels without a late followup', async () => {
+    harness = await makeBridgeHarness({ imageCapable: true, script: [] })
+    const validationStarted = Promise.withResolvers<undefined>()
+    const releaseValidation = Promise.withResolvers<undefined>()
+    harness.attachments!.beforeValidate = () => {
+      validationStarted.resolve(undefined)
+      return releaseValidation.promise
+    }
+    const sessionId = await newSession(harness)
+    let settled = false
+    const first = harness.client.prompt({
+      sessionId,
+      prompt: [{ type: 'image', data: 'AQ==', mimeType: 'image/png' }],
+    }).finally(() => { settled = true })
+    await validationStarted.promise
+
+    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'second' }] }))
+      .rejects.toThrow(/already in flight/)
+    await harness.client.cancel({ sessionId })
+    expect(settled).toBe(false)
+    releaseValidation.resolve(undefined)
+
+    await expect(first).resolves.toEqual({ stopReason: 'cancelled' })
+    expect(harness.adapter.requests).toEqual([])
+    const events = harness.ctx.agents.get(SessionId(sessionId))?.session.events ?? []
+    expect(events.some(event => event.type === 'user/message' || event.type === 'turn/start')).toBe(false)
+  })
+
+  it('does not queue admitted content into an agent retired during storage', async () => {
+    harness = await makeBridgeHarness({ imageCapable: true, script: [] })
+    const validationStarted = Promise.withResolvers<undefined>()
+    const releaseValidation = Promise.withResolvers<undefined>()
+    harness.attachments!.beforeValidate = () => {
+      validationStarted.resolve(undefined)
+      return releaseValidation.promise
+    }
+    const sessionId = await newSession(harness)
+    const prompt = harness.client.prompt({
+      sessionId,
+      prompt: [{ type: 'image', data: 'AQ==', mimeType: 'image/png' }],
+    })
+    await validationStarted.promise
+
+    await harness.loopFiber.dispose()
+    releaseValidation.resolve(undefined)
+
+    await expect(prompt).rejects.toThrow(/disposed outside the bridge/)
+    expect(harness.attachments!.saved).toHaveLength(1)
+    expect(harness.adapter.requests).toEqual([])
+  })
+
+  it('honors cancellation in the admission-to-followup handoff gap', async () => {
+    harness = await makeBridgeHarness({ imageCapable: true, script: [] })
+    const sessionId = await newSession(harness)
+    const saveImages = harness.attachments!.saveImages.bind(harness.attachments!)
+    vi.spyOn(harness.attachments!, 'saveImages').mockImplementationOnce(async (inputs) => {
+      const refs = await saveImages(inputs)
+      queueMicrotask(() => { void harness!.client.cancel({ sessionId }) })
+      return refs
+    })
+
+    await expect(harness.client.prompt({
+      sessionId,
+      prompt: [{ type: 'image', data: 'AQ==', mimeType: 'image/png' }],
+    })).resolves.toEqual({ stopReason: 'cancelled' })
+    expect(harness.adapter.requests).toEqual([])
+  })
+
+  it('wraps an unexpected same-process followup failure and frees the prompt slot', async () => {
+    harness = await makeBridgeHarness({ script: [] })
+    const sessionId = await newSession(harness)
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
+    vi.spyOn(agent, 'followup').mockImplementationOnce(() => { throw new Error('synthetic followup failure') })
+
+    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }))
+      .rejects.toThrow(/prompt was not queued: synthetic followup failure/)
+  })
+
   it('cancels a running turn and records the aborted outcome', async () => {
     harness = await makeBridgeHarness({ script: ['hang'] })
     const sessionId = await newSession(harness)

packages/support/acp-snapshot/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/support/acp-snapshot/README.md
-README.md: 06f1cb67cfcd954254db480ea696d10d81b37438
-README.zh.md: c4a5643f8c5d7e5b62a160cd32e5969187d34046
+README.md: 31f4ec0caeb995a10202d4a452ee7e433749762f
+README.zh.md: f97bac11de690fe980595c77375aead47b3b0214

packages/support/acp-snapshot/README.md

@@ -61,7 +61,7 @@ Every scenario compares `stdout.expected.jsonl` with cwd-rooted separators canon
 
 The example also ships a `cordis.snapshot.yml` replay overlay next to its `cordis.yml` (the bin swaps them under `DSH_SNAPSHOT=replay` — [single-source replay config Agent Note](../../../.agents/notes/archived/testing/2026-07-04-single-source-acp-replay-config.md)); replay fixtures are served by [`dsh-llm-replay`](../llm-replay/README.md), which this package points at via the `DSH_SNAPSHOT_*` env vars it sets on the child. `pnpm run test:snapshot:record` calls the live LLM and rewrites the recorded scenarios' model fixtures; `pnpm run test:snapshot:refresh` stays keyless, runs the replay overlay, and rewrites stdout, comparable session-log expected outputs, and owned prompt and tool-schema sidecars from the committed model scripts. Fixture roles, record/replay/refresh semantics, and scenario-table fields are documented on `Scenario` and in the [snapshot Agent Note](../../../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md).
 
-Constraints: `suite.ts` and `harness.ts` import vitest (the harness polls its durable-boundary waits through `vi.waitFor`), so the package entry is importable only inside a vitest run (the launcher and normalizers have no such dependency but ship from the same entry). The launcher and suite factory are ACP-specific by design — the launcher speaks the SDK's `ClientSideConnection` — while the normalizers are transport-neutral session-log/text helpers also consumed by the JSON-RPC and Web snapshot recorders. Input scripts cover initialization, fresh-session creation, text prompting, cancellation, expected RPC failures, and durable turn-boundary waits. Permission round-trips are a FIFO queue of option-kind selections (`allow_once`, `reject_once`, …) mapped to the agent-issued `optionId`; an absent or exhausted queue answers `cancelled`, and an unoffered kind rejects the run.
+Constraints: `suite.ts` and `harness.ts` import vitest (the harness polls its durable-boundary waits through `vi.waitFor`), so the package entry is importable only inside a vitest run (the launcher and normalizers have no such dependency but ship from the same entry). The launcher and suite factory are ACP-specific by design — the launcher speaks the SDK's `ClientSideConnection` — while the normalizers are transport-neutral session-log/text helpers also consumed by the JSON-RPC and Web snapshot recorders. Input scripts cover initialization, fresh-session creation, shorthand text prompts, exact structured ACP prompt blocks, cancellation, expected RPC failures, and durable turn-boundary waits. Permission round-trips are a FIFO queue of option-kind selections (`allow_once`, `reject_once`, …) mapped to the agent-issued `optionId`; an absent or exhausted queue answers `cancelled`, and an unoffered kind rejects the run.
 
 ## Model Experience
 

packages/support/acp-snapshot/README.zh.md

@@ -61,7 +61,7 @@ defineAcpSnapshotSuite({
 
 示例还发布 `cordis.snapshot.yml` 回放 overlay，位于 `cordis.yml` 旁边（bin 在 `DSH_SNAPSHOT=replay` 下交换它们，见[单源回放配置 Agent Note](../../../.agents/notes/archived/testing/2026-07-04-single-source-acp-replay-config.md)）；回放 fixture 由 [`dsh-llm-replay`](../llm-replay/README.md) 提供，该包通过对子级设置的 `DSH_SNAPSHOT_*` env var 指向它。`pnpm run test:snapshot:record` 调用实时 LLM，并重写已记录场景的模型 fixture；`pnpm run test:snapshot:refresh` 保持无密钥，运行回放 overlay，并从已提交模型脚本重写 stdout、可比较会话日志预期输出，以及各 pin 自有的提示词与工具 schema sidecar。Fixture 角色、录制/回放/刷新语义和场景表字段记录在 `Scenario` 以及[快照 Agent Note](../../../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md) 中。
 
-约束：`suite.ts` 与 `harness.ts` 导入 vitest（harness 通过 `vi.waitFor` 轮询其持久边界等待），因此包入口只能在 vitest 运行中导入（启动器和规范化器没有此依赖，但从同一入口发布）。启动器和套件工厂按设计专用于 ACP，启动器使用 SDK 的 `ClientSideConnection`；规范化器是与传输无关的会话日志/文本辅助工具，还由 JSON-RPC 和 Web 快照录制器消费。输入脚本覆盖初始化、新建会话、文本提示、取消、预期 RPC 失败和持久轮次边界等待。权限往返是选项类别选择（`allow_once`、`reject_once` 等）的 FIFO 队列，映射到 agent 发出的 `optionId`；缺少或耗尽的队列回答 `cancelled`，未提供类别会拒绝运行。
+约束：`suite.ts` 与 `harness.ts` 导入 vitest（harness 通过 `vi.waitFor` 轮询其持久边界等待），因此包入口只能在 vitest 运行中导入（启动器和规范化器没有此依赖，但从同一入口发布）。启动器和套件工厂按设计专用于 ACP，启动器使用 SDK 的 `ClientSideConnection`；规范化器是与传输无关的会话日志/文本辅助工具，还由 JSON-RPC 和 Web 快照录制器消费。输入脚本覆盖初始化、新建会话、文本提示简写、精确结构化 ACP 提示词块、取消、预期 RPC 失败和持久轮次边界等待。权限往返是选项类别选择（`allow_once`、`reject_once` 等）的 FIFO 队列，映射到 agent 发出的 `optionId`；缺少或耗尽的队列回答 `cancelled`，未提供类别会拒绝运行。
 
 ## 模型体验
 

packages/support/acp-snapshot/src/harness.ts

@@ -25,6 +25,7 @@ import { vi } from 'vitest'
 import {
   ClientSideConnection,
   PROTOCOL_VERSION,
+  type ContentBlock as AcpContentBlock,
   type RequestPermissionRequest,
   type RequestPermissionResponse,
   type SessionNotification,
@@ -69,6 +70,7 @@ export type InputStep =
   | { op: 'newSession' }
   | { op: 'newSessionExpectError'; additionalDirectories?: string[] }
   | { op: 'prompt'; text: string }
+  | { op: 'promptContent'; content: AcpContentBlock[] }
   | { op: 'promptAndWaitForAgentMessage'; text: string; waitForText: string }
   | { op: 'promptExpectError'; text: string }
   | {
@@ -422,6 +424,12 @@ async function runStep(
       await client.prompt({ sessionId, prompt: [{ type: 'text', text: step.text }] })
       return
     }
+    case 'promptContent': {
+      const sessionId = getSessionId()
+      if (sessionId === undefined) throw new Error('snapshot-harness: promptContent before newSession')
+      await client.prompt({ sessionId, prompt: step.content })
+      return
+    }
     case 'promptAndWaitForAgentMessage': {
       const sessionId = getSessionId()
       if (sessionId === undefined) throw new Error('snapshot-harness: promptAndWaitForAgentMessage before newSession')

packages/support/acp-snapshot/tests/harness.spec.ts

@@ -407,6 +407,24 @@ describe('runScenario', () => {
     expect((JSON.parse(sessionLine) as { cwd?: string }).cwd).toBe(result.cwd)
   })
 
+  it('drives a structured prompt-content step without flattening its wire blocks', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({})
+    const result = await runScenario(
+      {
+        steps: [...boot, {
+          op: 'promptContent',
+          content: [
+            { type: 'text', text: 'before' },
+            { type: 'image', data: 'AQ==', mimeType: 'image/png' },
+            { type: 'text', text: 'after' },
+          ],
+        }],
+      },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    expect(result.rawStdout).toContain('"stopReason":"end_turn"')
+  })
+
   it('forwards override/child fixture paths into the child env and captures stderr', { timeout: 20_000 }, async () => {
     const { dir, fixtureFile } = await scenario({ echoEnv: true, stderrNote: 'fake bin booted' })
     const childFiles = [join(dir, 'session.1.jsonl'), join(dir, 'session.2.jsonl')]
@@ -1097,6 +1115,7 @@ describe('runScenario', () => {
 
   it.each([
     [{ op: 'prompt', text: 'x' }, /prompt before newSession/],
+    [{ op: 'promptContent', content: [{ type: 'text', text: 'x' }] }, /promptContent before newSession/],
     [{ op: 'promptAndWaitForAgentMessage', text: 'x', waitForText: 'later' }, /promptAndWaitForAgentMessage before newSession/],
     [{ op: 'promptExpectError', text: 'x' }, /promptExpectError before newSession/],
     [{ op: 'promptAndCancel', text: 'x' }, /promptAndCancel before newSession/],

pnpm-lock.yaml

@@ -778,6 +778,9 @@ importers:
       '@deepseek-ai/dsh-agent-loop-testkit':
         specifier: workspace:^
         version: link:../../support/agent-loop-testkit
+      '@deepseek-ai/dsh-attachment':
+        specifier: workspace:^
+        version: link:../../attachment/attachment
       '@deepseek-ai/dsh-invariants':
         specifier: workspace:^
         version: link:../../support/invariants