Tool-produced images reach the model but are never visible to the user

[AndrosBravo]

A tool can return an image content block and the model receives it — but the human never sees it. The image is delivered, described, and stored, yet the Chat view shows nothing.

What I did

I wrote a Cordis plugin registering a generate_image tool, loaded from a user preset under $DSH_HOME/.agent-presets/. It calls an image model, stores the result through attachments.saveImages(), and returns

{ type: 'image', attachment: ImageAttachmentRef }

from output.render — the same shape packages/fs/tool-fs/src/read-image.ts uses.

What happens

The image is generated, normalized, and stored under $DSH_HOME/attachments/v1/objects/. A vision-capable conversation model receives it and describes its contents accurately (details that were never in the prompt), so the block reaches the model correctly.

But in the Chat view, document.querySelectorAll('img').length stays 0.

Where it seems to break

MessageItem.tsx renders images only for user message nodes — contentParts() collects type: 'image' blocks there. Content a plugin injects is projected as a context node (ContextMessageNodeView → ContextInjectionRow) because of its source: { kind: 'plugin' }, and collapses into a one-line row that cannot be expanded. Both exec.deferContext() and agent.inject() land on that path.

Notably, packages/core/tools/src/code-mode.ts:564 already special-cases exactly this: when a tool result contains an image block, it re-injects the content as a user message. So the capability is half-present — Code Mode handles it, the Standard-mode path has no equivalent, and even an injected message renders collapsed.

What I would hope for

A supported way for a tool-produced image to be visible to the user, not only to the model — either by rendering image blocks inside tool result cards, or by letting plugin-injected content with images render expanded rather than collapsed.

Happy to test any change against the plugin above.

Environment

dsh 0.1.1-rc.2 · Windows 11 · Node 24.13.1 · web profile

[weijiafu14]

你的诊断我可以给一份完全独立的、来自另一条代码路径的印证——我们撞上的是同一堵墙，而且我们的"解法"恰好证明了你要的那个声明机制是真缺的。

我们也做了这件事，代价是一张硬编码的逐包白名单

我维护 pi2dsh（把 Pi 生态插件翻译成 DSH 原生插件的兼容层）。里面有一个能力是"插件生成图片 → 存成 DSH 原生 attachment → 在 Web 里内联渲染出来"，端到端跑通、有 example。

但它是怎么"通"的——我们源码里就这一段：

const KNOWN_IMAGE_TOOLS_BY_PACKAGE: ReadonlyMap<string, ReadonlySet<string>> = new Map([
  ['@crazygit/pi-codex-image-gen', new Set(['codex_generate_image'])],
])

function isKnownImageTool(packageName: string, toolName: string): boolean {
  return KNOWN_IMAGE_TOOLS_BY_PACKAGE.get(packageName)?.has(toolName) === true
}

一个包名、一个工具名，写死。 而且我们在自己的项目守则里把它标成了唯一一条成文的破例，原话大意是：

上游没有"工具会输出图片"的声明机制，所以图片卡只能对逐包核证过输出契约的工具开放。这是缺口标记，不是可扩展方案——第二个生图包不会自动解锁。正解是推动上游加图片输出声明。

也就是说：我们不是解决了这个问题，我们是给一个具体的包开了后门，并且把这件事记为技术债。

这已经是同一个缺失声明的第三处特例了

把你找到的和我们的放一起：

谁	怎么处理"工具产出了图片"
DSH 自己	packages/core/tools/src/code-mode.ts:564 —— 工具结果含 image block 时把内容重新注入成 user 消息（你找到的）
DSH 自己（Standard 模式）	没有对等处理 —— 于是你看到 img 数量为 0
我们（外部兼容层）	一张写死的包名→工具名白名单

三处特例，零个声明。 我觉得这是你这份提案最有力的论据，比"我写了个插件但图片看不见"强得多——它说明：

1. 这个需求不是边缘的：DSH 内部已经为它写过一次特判；
2. 绕过去的成本是"每个实现者各自维护一张名单"：我们付了这个代价，而它按定义无法扩展；
3. 缺的东西很具体：不是"渲染能力"（Code Mode 已经证明渲染得出来），而是一个让工具声明"我的输出里会有图片"的契约。

建议把这三行放进原帖——"内部特判 + 外部白名单 + 标准路径无支持"这个组合，比任何单方证据都更能说明该补的是声明而不是补丁。

顺带说一个我们的观察，可能对设计有用

我们那张白名单的判据是"逐包核证过输出契约"——也就是我们人工验证过那个工具确实返回符合预期形状的 image block，才敢让它的输出走图片卡。

这背后有个真实顾虑：如果任何工具都能声明"我输出图片"，那渲染层就要处理任意插件返回的任意形状（坏的 attachment ref、指向不存在对象的引用、超大图、非图片却声称是图片）。所以如果上游要加这个声明，它大概率需要配一个"宿主侧验证"环节——声明只是意图，实际渲染前仍应校验 attachment 确实存在且是合法图片。

这一点值得你在提案里主动写上（"声明 + 宿主校验"而不是"声明即渲染"）——评审对"让插件决定 UI 渲染什么"的第一反应通常是警惕，你先把这层答了，阻力会小很多。

关于你的两个期望，我的看法

要么在 tool result 卡片里渲染 image block，要么让插件注入的内容能展开渲染

前者更值得推。 后者（让 context 节点可展开）会顺带改变所有插件注入内容的呈现——那是一个更大的产品决策，会引出"哪些注入该展开、会不会刷屏"之类的讨论。而"tool result 卡片能渲染它自己返回的 image block"是一个范围明确、语义自洽的诉求：图片是那次工具调用的产物，它属于那张卡片。

（另外你提到 exec.deferContext() 和 agent.inject() 都落到 context 节点那条路——这一点很有价值，因为它说明这不是某一个 API 的问题，而是"插件产出的内容"整体被归到了一个折叠的呈现里。值得在原帖里强调。）

边界与利益相关

我们不修 DSH 自家组件——MessageItem.tsx、ContextInjectionRow、code-mode.ts 都在 DSH 里。第一节引的是我们自己源码里的实际代码和守则；我没有跑过你那个插件，也没有读过 MessageItem.tsx，你的渲染链路分析我完全采信。

利益相关：我维护 pi2dsh，它就是那张白名单的所有者，所以我是这个声明机制的直接受益者——上游一旦有了声明，我们那张白名单就能删掉。这一点先说在前面。这条不推销：你要的是 DSH 开一个契约，装我们的东西对此毫无帮助（我们和你卡在同一堵墙前，只是我们选择了给一个包开后门）。

[AndrosBravo]

Correction to my own report — the capability already exists, and I missed it.

I should have searched before posting. #2995 covers adjacent ground, and @weijiafu14's answer there already points at the mechanism I claimed was missing: a tool registers its Web result card at mount time, and the completed tool row renders the pixels inline through the session-authorized attachment endpoint. Working reference: https://github.com/weijiafu14/pi2dsh/tree/main/examples/codex-image-gen

So the "root cause" section above is wrong. I returned { type: 'image', attachment } from output.render and then tried to surface it by injecting context — which is exactly the path that collapses into a ContextInjectionRow. That was my mistake, not a missing host capability.

What I think still stands, as a much smaller docs point:

docs/cookbook/adding-a-tool.md documents presentCall / presentResult and enumerates the card kinds — generic, terminal, diff — but the word image never appears in that file. A plugin author following the cookbook end to end has no way to discover that a tool result can display an image at all, and output.render returning an image block looks like the obvious answer precisely because read-image.ts does exactly that.

One line in the tool-authoring cookbook pointing from image content blocks to the result-card path would have saved this entire thread.

Happy for this to be closed as covered by #2995.

[denial123789]

The correction identifies the key boundary: output.render is model-facing content, while Web dispatches the durable tool-call node through the keyed tool.call.toolview slot. A result-card integration therefore needs two deliberate paths: save and reference the attachment for the model, then register a client row under the exact controlled wire tool name and retrieve bytes through the current Session-authorized attachment path. Context injection is not a display API and changes transcript semantics.

Two safety details are worth keeping in the example: derive replay UI from the frozen completed result rather than provider state, and abort/revoke attachment loads on Session change or component disposal. Missing or unauthorized images should retain readable fallback text. We turned the corrected route, package split, lifecycle, failure matrix, and fourteen acceptance gates into a source-pinned guide: https://sandbaseai.github.io/deepseek-harness-handbook/tool-image-result-card.html

Disclosure: I contribute to this independent community handbook.

[AndrosBravo]

Retracting my previous comment — I over-corrected. The original report stands.

I read "already working" in #2995 and assumed it meant a stock capability I had missed. I should have checked what it actually required before retracting. Having now traced it properly:

Surface	Renders images?
User message nodes (MessageItem → contentParts)	yes
Assistant message content (AssistantMarkdown → renderMessageImages)	yes
Plugin-injected context (ContextInjectionRow)	no — no image/attachment reference
Tool result cards (packages/client/ui-tool/src)	no — the word attachment never appears in that package

The decisive evidence: read_image — the host's own image tool — declares only presentCall(): GenericCallView with card: 'generic' and has no presentResult. There is also no image card kind anywhere; the seven kinds in the codebase are chart, diff, generic, read, search, terminal, web.

So a tool that returns { type: 'image', attachment } has no rendering path in the stock Web client. read_image itself delivers the image to the model and shows the user a generic card.

What pi2dsh does is register its own Web result card through the client slot system — that is a client-side UI plugin shipped by a separate project, not something a host-side tool plugin can do. That is a meaningful reference implementation, and it is also exactly why the gap is real: the capability requires building and shipping client UI, which is out of reach for a plugin author following docs/cookbook/adding-a-tool.md.

The ask, restated precisely: either let tool result cards render image content blocks natively, or document the client-side card path in the tool-authoring cookbook so plugin authors know it exists. Right now the cookbook enumerates generic / terminal / diff and never mentions images at all.

Apologies for the noise of correcting my own correction.

[nokkies]

Reproduced and fixed locally. Your trace is right up to the last step, where the behaviour is slightly different from "shows nothing" — and the difference is what makes the fix small.

The image is not dropped, it is rendered as JSON

ContextInjectionRow is expandable — it is a DisclosureRow with its own open state. Expand it and the block is there. The problem is in the body: ModelFacingContent renders text runs as text and routes every other block to the unknown-block JSON fallback, and an image block is "every other block". So the picture arrives as a JSON dump labelled as a shape this UI does not recognise, which is exactly consistent with your querySelectorAll('img').length === 0.

That reframing matters because it means nothing is being filtered out on the way in. Only the presentation is wrong.

The renderer is already in the props

ContextMessageNodeView destructures { node, t }, but its props are ChatNodeViewProps<'context'>, which derives from ChatNodeOwnerProps — and that interface already carries:

/** Render a historical image group through the attachment slot. */
renderMessageImages: RenderMessageImages

So the node view already receives the attachment-slot renderer and simply never used it. Threading it down to the body is the entire fix; no slot contract changes, no new plumbing.

Two details worth keeping when it lands:

• Group adjacent images. contentRuns already coalesces adjacent text runs; extending it to coalesce adjacent image blocks makes several pictures render as one gallery instead of a column of singletons, which is how a user message presents the same blocks.
• Keep order. That run model already treats ordering as load-bearing — a block stays between the text around it rather than being hoisted or vanishing — and images have to obey the same rule, or a tool that interleaves commentary and pictures renders scrambled.
• Keep the renderer optional. A caller with no attachment slot then keeps the JSON fallback rather than losing the block entirely.

This also fixes code-mode's own images

Worth noting because you found that special case and it looks like precedent for a workaround. code-mode.ts re-injects an image-bearing tool result with exec.deferContext(createUserMessage({ content, source: { kind: 'plugin', plugin: 'tools-code-mode' } })) — a plugin source, so it lands on the exact path you are describing. That special case successfully gets the image to the model, and the reader was the one participant it left out. Both are fixed by the same change, so no separate handling is needed for plugin tools versus code mode.

Test

Asserting what you measured rather than an internal: expand the disclosure, then two img elements present, one grouped gallery call rather than two, and no unknown-block fallback. It fails against current behaviour.