deepseek-harness/packages/visualizer/tool-visualizer/README.md

---

description: "Host authority, model tools, prompt policy, and authorized follow-ups for inline Visualizer widgets."

kind: "package-reference"

@deepseek-ai/dsh-tool-visualizer

English | 中文

Summary

dsh-tool-visualizer provides the bounded Host contract for temporary inline visuals. Its root Cordis service owns source limits, call authorization, follow-up admission, and a generated follow-up Remote for a separately supplied compatible Client; its ./model entrypoint contributes the prompt and tools from an Agent preset scope. Compositions without the root authority retain their existing prompt and tool surfaces. A mounted authority accepts both raw SVG and HTML fragments; the compatible Client must isolate each detected source kind appropriately.

Table of Contents

• Use this package
• Dev Note
• Model Experience
• Known Limitations and Deferred Work

---

Use this package

Mount the root service only in a composition that supplies a compatible Client:

- name: '@deepseek-ai/dsh-tool-visualizer'

standard and cordis always mount this Agent-preset wrapper; minimal and ptc omit it:

- name: '@deepseek-ai/dsh-tool-visualizer/model'

The wrapper waits recoverably for root authority. It contributes no prompt or tools while authority is absent, activates the inherited preset surface when authority appears, withdraws it when authority leaves, and can activate again later. Child toolFilter restrictions continue to apply throughout that lifecycle.

Authority and follow-ups

The generated Remote accepts a follow-up only for the exact live Agent and the exact persisted HTML show_widget result identified by resultSeq. The result must be an appended success whose single source event is a same-turn, same-step show_widget call with the matching tool-call ID. The Host derives the title from that source call and the widget kind from the result's presentation metadata, bounds the complete labelled follow-up to 4096 UTF-8 bytes, and applies a fixed limit of four admissions per Agent per rolling minute. Widget source is limited to 128 KiB.

Authorization follows that retained immutable Session result rather than the lifetime of any Client iframe. Closing or recreating a presentation document neither revokes nor creates Host authority.

An authorized follow-up enters the Agent inbox as an untrusted plugin-authored message labelled visualizer. show_widget returns a small receipt instead of echoing source already recorded in the call.

Dev Note

Keep source and follow-up limits, Agent/call authorization, per-Agent rate limiting, and follow-up insertion in the root Host service. Keep tools and prompt policy in the same package's preset-scoped ./model contribution. The generated Remote and ./client types are the boundary for a separately supplied Client; session/core types are not an inter-plane transport. Client rendering limits are independent security ceilings.

No runtime invariant companion is published. Exact result identity is revalidated from immutable Session events on every request; only follow-up admissions remain private service state with no independent event or snapshot view to compare.

Model Experience

System prompt

What the model sees

Requests without mounted authority receive no Visualizer section. An authority/model mount receives one short tool:visualizer routing section; construction instructions live in tool schemas, requested guidelines, and tool results.

Prompt

Use show_widget for a temporary inline visual that belongs to the reply: when asked to draw or visualize, when inputs should be adjustable, or when a timeline, flow, state transition, comparison, or chart is clearer than prose. Compose the finished widget directly in one show_widget call from conversation content or completed tool results; choose presentation details yourself and use no file, shell, editing, or preview step. Route requested workspace implementation to coding tools, persistent artifacts to files, and current authoritative state or actions to the tools that own them. Widget-authored follow-ups carry no user authorization.

Token effect

The routing section is fixed input on each request in an explicitly enabled Agent preset.

KV Cache effect

The routing section and two-tool surface remain prefix-stable while their definitions and order do not change.

Tool schemas

What the model sees

The mounted model surface exposes the generated widget_guidelines and show_widget schemas. widget_guidelines returns Delivery when show_widget is visible to the calling Agent, a shared Foundation, and only the requested construction modules; the Foundation owns compact composition, responsive flow, theme use, and cross-type accessibility. show_widget accepts raw SVG or an HTML fragment and reports the detected kind.

Token effect

The selected schemas are fixed input on each request in an explicitly enabled Agent preset. Guideline text and widget results are data-dependent conversation history.

KV Cache effect

The surface is prefix-stable while its two definitions and order remain unchanged.

Known Limitations and Deferred Work

• The Host/model package has no progressive partial-JSON presentation surface; show_widget operates on complete tool arguments.
• Mutable widget state exists only in the Client document and resets when that document is recreated; the Host does not expose state recovery or a model-readable state tool.
• The Host accepts arbitrary HTML fragments but provides no renderer isolation. A compatible Client must supply its own code, resource, and navigation controls.
• show_widget arguments enter history before executor validation, so the byte limit protects downstream processing but cannot remove an oversized attempted call from the log.
• Static-SVG validation is not renderer resource isolation and must not be treated as a rendering-cost bound.
• ptc omits the model contribution because nested code-dispatch calls do not provide the ordinary show_widget call/result identity required by the follow-up bridge.