Let html_render and html_preview reuse a previewed page instead of resending its HTML

[FreeRikato]

Problem

When an agent shows a visual, it sends the whole HTML document on every call:

1. html_preview at 728px, dark
2. html_preview again at 390px, light (the loop the tool descriptions encourage)
3. html_render to publish

The server already holds the exact page after the first preview, but nothing lets the agent refer to it, so the page goes out three times. Output tokens are the slowest and most expensive part of a turn: a 30 KB page (a chart with embedded data) costs about 90 KB of agent output instead of 30 KB, plus the time to generate it. #17798 reports the same cost.

Proposal

html_preview returns a previewId for the page it rendered. Later html_preview and html_render calls from the same thread can pass previewId instead of html.

html_preview { html, width: 728 }                       -> screenshot + previewId
html_preview { previewId, width: 390, appearance: light } -> screenshot
html_render  { previewId, title, height }               -> published page

Measured on one page through the real tools:

Call	Today	With previewId
html_preview (728, dark)	1,428 bytes	1,428 bytes
html_preview (390, light)	1,428 bytes	85 bytes
html_render	about 1,450 bytes	96 bytes

Shape of the change:

• Previewed pages stay in server memory only, for the thread that previewed them: 30 minutes, 20 per thread, 100 overall, oldest evicted first.
• An unknown, expired or other thread's id fails with invalid_request and a message telling the agent to send html again; ids reveal nothing across threads, and a restart just means one resend.
• html keeps working exactly as today; previewId is optional, and exactly one of the two is required.
• No client, contract or provider adapter changes: clients read the same htmlRender reference.
• The tool descriptions and the visuals orchestration instruction tell agents to send the page once.

Not proposed

• A workspace file path input (the server-read concern raised in feat: agents can show HTML pages inline in threads #15916).
• Reusing an already published render with new data (Let an HTML render be reused with fresh data instead of rewritten #17466).
• Any change to how html_render sizes or scrolls its frame.

Questions for maintainers

• Is this direction acceptable, or would you rather solve the repeated HTML another way?
• Are in-memory, thread-scoped ids with these limits the right shape, or would you prefer different limits or scoping?

I have an implementation with tests, including a real headless-browser run, ready to reopen as #18528 if the direction is approved.

[wicolian]

much needed

[spadaval]

A file path input would be a useful addition to previewId, or an alternative to it. Agents usually write the page to disk with their own edit tools anyway, and edit tools change one part of a page instead of rewriting the whole thing. So with a path:

• Revising a page is cheap. The agent edits the file and previews again, so it no longer sends the whole document for each change it makes after a preview. A previewId only saves resending a page that hasn't changed.
• It works across turns. A page written in an earlier turn, or by a script, can be published without being read back into context. A previewId expires and is lost when the server restarts. This also helps with Let an HTML render be reused with fresh data instead of rewritten #17466.

html_preview { path: "report.html", width: 728 }
html_preview { path: "report.html", width: 390, appearance: "light" }
html_render  { path: "report.html", title, height }

#17798 set path aside because of the #15916 concern about the server reading paths the agent picks. Some scoping could address that:

• Resolve the path against the calling thread's worktree, or the project's workspaceRoot if the thread has none. Take the thread from the verified MCP credential, as html_render already does with requireThreadScope. Reject anything that resolves outside that root after realpath, which also catches .. and symlinks that lead out of it.
• The agent can already read these files with its own tools, so the server reads nothing the caller couldn't already read. html_preview is already limited to agents T3 launched, because its headless browser can open local files on the host.
• The server reads the file once, applies the same 512 KB page limit, and then handles it exactly like inline html: the same image inlining, theme injection and stored attachment. The published render stays a snapshot and does not track the file.
• Callers pass exactly one of html or path (and previewId, if that is added too).

Would maintainers accept a workspace-scoped path like this? If so, I can put up a focused PR.

---

Drafted by Claude Opus 5.5 in Claude Code (via T3 Code); reviewed and posted by @spadaval.

[juliusmarminge]

Closing as a duplicate of #23303, which tracks the same request. Please follow along there.