dsh-valuz-genui

A DeepSeek Harness plugin that gives the model a generate_ui tool: the model itself authors an A2UI v0.9.1 document and passes it to generate_ui, and the browser renders it as an interactive surface inline in the chat — charts, KPI cards, tables, forms, dashboards — streaming as the model writes the call, and whose interactions come back to the model.

There is no nested model call: the UI is the model's own streamed output, so it appears live (like a fenced block), costs one model turn, and can't fail with a mid-stream error from a second request. It builds on the provider-agnostic valuz-genui core (76-component A2UI catalog, streaming sanitizer, React renderer).

How it works

• Authoring guide (system prompt + skill). The plugin teaches the model to author A2UI and deliver it by calling generate_ui with messages (the array of A2UI message objects). When the host supports skills, a compact guide (component names + purposes + message contract) is always on and the full field-signature catalog loads on demand via the genui skill; otherwise the full guide stays in the system prompt.
• Streaming render. As the model writes the generate_ui arguments, each tool-call-delta reaches the browser as a transient assistant/live-chunk before the tool runs. A conversation node keyed by the generate_ui call id folds those deltas, extracts the complete A2UI messages authored so far, and renders them with the valuz <A2UIRenderer> — which keeps the last good surface while the tail is still being written. So the surface builds up component by component, live.
• Settle + replay. When generate_ui executes (milliseconds — it only validates and never calls a model), it persists the canonical document to tool/result.meta. The node adopts that authoritative document. Live chunks are process-local and disappear when the model attempt settles, so after settling and on reload the node rebuilds from the durable tool/call arguments and tool/result.meta.
• Turn end. When the turn completes, its settled surfaces render again after the final reply, outside dsh's collapsed process view, and the in-process copy shrinks to a one-line reference.
• Interactions. A click/submit on a rendered surface is sent back to the model as an ordinary user message: <ui_action surface="…" component="…" name="…">{context}</ui_action> (model-visible ⟺ logged). The model answers in text or calls generate_ui again with the updated document.

Install

Compatibility

dsh 0.2 replaced the client Conversation APIs that 0.1.x uses, so 0.1.x fails to load there with pending (waiting for service: conversationEvents). dsh checks a plugin's declared peer ranges at install and startup, so an incompatible pairing is refused before it loads.

Into an existing profile that already has a model configured:

dsh plugin --profile web add @valuz/dsh-valuz-genui

The npm package ships a prebuilt lib/, so no build step or allowBuilds entry is needed. To pin an unreleased commit instead, install from git — pnpm ≥ 10 then blocks the git dependency's prepare build until you allow it; the first add fails and prints the exact key to copy into the profile's pnpm-workspace.yaml:

dsh plugin --profile web add github:valuz-ai/dsh-valuz-genui#<commit-sha>

allowBuilds:
  '@valuz/dsh-valuz-genui@https://codeload.github.com/valuz-ai/dsh-valuz-genui/tar.gz/<commit-sha>': true

Then restart dsh web and hard-refresh. Ask the model for a chart or dashboard to verify. No extra configuration is needed — the model authors the UI through whatever model the session is using.

Local development

The generation core and renderer come from npm (@valuz/genui-core, @valuz/a2ui, from valuz-ai/valuz-genui); the client bundle inlines them at build time:

git clone https://github.com/valuz-ai/dsh-valuz-genui.git
cd dsh-valuz-genui && pnpm install && pnpm run check
# install into a profile (rebuild lib/ first with pnpm run build)
dsh plugin --profile web add /absolute/path/to/dsh-valuz-genui

Restart dsh web and hard-refresh after each rebuild.

The tool

generate_ui(messages, title?)

• messages — the array of A2UI v0.9.1 message objects the model authored: createSurface first, then updateComponents / updateDataModel; exactly one component has id "root". Written as native JSON (not a stringified blob), so it streams and validates cleanly.
• title — optional short surface title.

The tool validates the document, pins the catalog id, drops schema-invalid components (siblings survive), and persists everything to tool/result.meta. The model receives a one-line receipt.

Configuration

Override the valuz-genui row by id in your profile's cordis.patch.yml:

Known Limitations and Deferred Work

• Placement inside completed turns. dsh folds a completed turn's process (skill load, reasoning, tool calls) into a collapsed "Completed in Ns" disclosure. The plugin therefore shows a completed turn's settled surfaces at the end of the turn, after the final reply, through dsh's conversation.chat.turnTail slot, and replaces each surface inside the process with a one-line reference. A later surface with the same title counts as a revision, so only the latest one appears at the turn's end; surfaces with different titles all appear. A surface that never settled (for example, an interrupted call) stays inside the process.
• Always-on prompt cost. Where the host supports skills (ctx.skills, e.g. the web profile), only a compact guide (~3.1k tokens: component names + one-line purposes + the message contract) stays always on, and the full field-signature catalog (~9k tokens) loads on demand through the genui skill. Where no skill capability exists (or alwaysOnFullGuide: true), the full guide stays in the system prompt. Both are stable prefixes (KV-cache-friendly). The model is told to load the genui skill before authoring; guessing fields drops components.
• Authoring quality depends on the model. A2UI's 76-component graph is richer — and harder to author inline — than a compact DSL. Complex dashboards may need prompt tuning; the sanitizer tolerates and drops malformed components rather than failing the whole surface.
• Client bundle is large (~3.5 MB). recharts, the A2UI renderer, and markdown-it are inlined. Phase 2 splits the chart engine into a lazily loaded plugin-served asset.
• Theme bridge is coarse. The renderer follows light/dark but does not yet map A2UI --va2-* tokens onto the host --dsw-alias-* scale. Core semantic tokens (background, text, border, accent) can be mapped through a registered a2ui theme extension; chart palettes live in JS and need renderer support.
• Interactions round-trip through the model. Every <ui_action> becomes a user message; there is no local-only handling yet.
• No surface under the PTC (Code Mode) preset. With tool-presentation: mode: code the model may only call run_code; generate_ui runs from inside the program, so the model streams TypeScript rather than messages (no live rendering), and the nested result is logged as tool/ptc-dispatch — which carries content but no meta — so the settled surface never appears either; only run_code's text receipt does. Use the Standard preset, or copy a preset with mode: both so generate_ui can still be called directly. Rendering under code would need this node to match tool/ptc-dispatch and dsh to carry presentationMeta on that event.
• No plugin-owned session events. Everything persisted goes through platform events (tool/call for the authored call, user/message for actions, tool/result.meta for the settled document), which is enough for the model-driven loop. Ephemeral surface state (form drafts, tab selection) is not model-visible and would belong in client-side storage, not the log. Only a surface update that no tool call produces (live data, host-pushed panels) would need plugin events, and dsh's Session.append has no way to mark an event ignorable, and dsh rejected event-type registration for third-party plugins.
• Host-contract hardening. The client bundle mirrors dsh's platform module list (PLATFORM_MODULES in packages/client/web/src/platform.ts) by hand, so a host that changes it can break loading. The dsh peer ranges are capped to one minor line (>=0.2.0-rc.2 <0.3.0), so a new dsh minor needs a plugin release. Planned: run check against the latest dsh release in CI and add a recorded-session replay snapshot that pins the streaming node end to end.

License

MIT