feat(hub+cli): surface mermaid parse failures back to the agent so it can self-correct

[heavygee]

Summary

The web client already validates mermaid blocks before rendering (explicit mermaid.parse() + mermaid.render() wrapped in try/catch, securityLevel: 'strict', suppressErrorRendering: true, fallback to raw source on failure - see web/src/components/assistant-ui/mermaid-diagram.tsx). That stack prevents broken charts from XSS-ing or crashing the page (closed by #785) and is the foundation the lightbox in #737 / #741 sits on top of.

What it does not do: tell the agent that its diagram failed to parse. The validation loop is one-way. The user sees raw mermaid source in a code-block fallback; the agent sees nothing and happily emits another broken chart next turn. Over a long session, this produces a quiet UX regression - the operator stops getting diagrams entirely until they manually point out "your charts have been raw text for 20 messages."

This is the same class of gap that #675 / #676 closed for OpenCode errors ("invisible failure"), applied to the agent-side feedback path instead of the user-side display.

Current behavior

1. Agent emits a markdown mermaid code block in assistant text.
2. Hub stores + forwards the message verbatim. No mermaid awareness.
3. Browser tries mermaid.parse(code, { suppressErrors: true }).
4. Parse returns falsy or mermaid.render() throws → MermaidFallback renders the raw source in a <pre><code> block.
5. User sees the raw text. Agent receives no signal. Hub has no record that anything failed.

No SSE event, no tool-result reply, no system-channel hint into the transcript.

Proposed approaches (pick one, in increasing weight)

A. CLI-side post-emit re-parse (smallest)

In the CLI's outgoing assistant-text path, scan for ```mermaid fences, run a lightweight mermaid-parse (or call the existing client validator via bun/Node), and on failure inject a single system-channel turn back into the agent transcript:

The previous mermaid block did not parse:

<parser error excerpt, 1-3 lines>

The block was preserved in the user-visible message as raw text. Please re-emit it with corrected syntax if the diagram was intended.

• Pros: hub stays mermaid-unaware; same diff in one place; works for every UI client.
• Cons: CLI carries a mermaid dependency (it does not today); version drift between CLI parser and browser parser could disagree.

B. Client → hub → CLI signal (most accurate to what the user actually sees)

MermaidDiagram emits a typed event (mermaid-parse-failure) up to a session-level handler that POSTs to a new /api/sessions/:id/render-issues endpoint. Hub persists a small render_issues row (sessionId, messageId, kind=mermaid_parse_failure, snippet, parser version) and broadcasts via SSE so the CLI can convert it into a system-channel hint to the agent on the next turn.

• Pros: ground truth is "what the user actually saw fail in their browser." No CLI mermaid dependency. Captures parser-version drift exactly because it's the user's parser.
• Cons: needs a new endpoint, persistence row, SSE type, and CLI consumer. More surface to maintain.

C. Both A and B, layered

A for fast feedback in the same turn; B as the system of record so the agent gets a high-confidence hint on the next turn even if A missed. Probably overbuild for v1.

Acceptance criteria

• Agent receives a structured, low-noise signal when one of its emitted mermaid blocks fails to parse / render in at least one connected client.
• Signal is not delivered for every render (no thrash if 4 PWAs render the same broken chart - dedupe per messageId).
• User-visible fallback behavior is unchanged.
• No additional XSS surface; securityLevel: 'strict' and suppressErrorRendering: true stay in place.
• Optional: surface the same signal to the UI as a subtle marker on the failing message (e.g. small "diagram could not be rendered" pill) so the user knows the agent has been notified.

Out of scope

• Changing the fallback rendering itself (separate from feedback loop).
• Validating other content types (HTML, KaTeX, etc.) - same pattern applies but the surfaces and parsers differ.
• Lightbox / maximize work (tracked in feat(web): mermaid diagram lightbox / maximize on click #737 / feat(web): mermaid diagram lightbox on click #741).

Related

• Mermaid 代码块图表渲染失败会导致页面崩溃 #785 - Mermaid parse-failure page crash (closed; the hardening this issue depends on).
• feat(web): mermaid diagram lightbox / maximize on click #737 - Mermaid lightbox enhancement.
• feat(web): mermaid diagram lightbox on click #741 - Mermaid lightbox PR (sits on top of the parse-then-render gate).
• OpenCode error messages don't appear in the web UI like Claude Code does #675 / OpenCode errors don't appear in web UI (stderr / prompt failures / resume errors) #676 - Same class of "invisible failure" gap, closed for OpenCode errors on the user-side; this issue extends the principle to the agent-side.

Environment

• Reproduces on web PWA + mobile, any agent flavor that can emit markdown (Claude, Codex, Cursor, etc.).

[github-actions]

Confirmed. Current code matches the gap described: Mermaid parse/render failures are handled entirely inside the web renderer and are not propagated back through hub/CLI.

The smallest verified statement is: today the web client sets local renderError and falls back to raw source; I did not find any render-issues, mermaid_parse_failure, or mermaid-parse-failure path in hub/src, cli/src, or shared/src.

Given current dependencies, approach B fits the existing ownership best if the signal must reflect what the user actually saw: mermaid is only a web dependency right now, not a CLI dependency. A first implementation would need a typed client-to-hub report path, dedupe by messageId, and a CLI/agent feedback path. The existing fallback/security behavior can stay unchanged.

Relevant code:

• web/src/components/assistant-ui/mermaid-diagram.tsx:24 - Mermaid parse error handler is suppressed locally.
• web/src/components/assistant-ui/mermaid-diagram.tsx:26 - Mermaid initialized with securityLevel: 'strict' and suppressErrorRendering: true.
• web/src/components/assistant-ui/mermaid-diagram.tsx:107 - Browser calls mermaid.parse(code, { suppressErrors: true }) before rendering.
• web/src/components/assistant-ui/mermaid-diagram.tsx:109 - Falsy parse result sets local render error and returns.
• web/src/components/assistant-ui/mermaid-diagram.tsx:119 - Render exceptions are caught locally.
• web/src/components/assistant-ui/mermaid-diagram.tsx:133 - Failure path renders MermaidFallback with data-rendered="false".
• web/src/components/assistant-ui/markdown-text.tsx:60 - Markdown mermaid code blocks are wired to MermaidDiagram.
• shared/src/schemas.ts:304 - Current SSE/sync event union has session/message events, but no render-failure event type.
• hub/src/web/server.ts:237 - Current authenticated API routes are registered here; no render-issue route is registered.
• web/package.json:37 - mermaid dependency exists in the web package.
• cli/package.json:53 - CLI dependencies start here; no mermaid dependency found in the CLI package.

---

HAPI Bot

[heavygee]

Implementation direction: hub-side validation (revised from Approach B)

After working through the surface areas for Approach B (client → hub → CLI), we've revised to a simpler hub-side variant that achieves the same agent-feedback goal with far less plumbing.

Revised approach: hub validates at message-store time

Flow:

1. CLI sends a completed assistant message to the hub (this already happens)
2. Hub extracts ```mermaid fences from the message markdown
3. Hub validates each block — v1: check diagram type against the known-valid list; no new library dependency
4. If any block fails → hub stores a synthetic <render-issue> user message in the same session (no local_id, so invoked_at stamps immediately)
5. Existing update/new-message socket path delivers the synthetic message to the CLI
6. CLI passes it to the agent as a system-channel hint on the next turn (same mechanism as <task-notification>, <system-reminder>, etc.)

Why this over Approach B

	Approach B (client → hub → CLI)	Hub-side validation
Web client changes	Yes — POST on render failure	None
New HTTP endpoint	Yes	None
Browser-side dedup	Yes (Set keyed on codeHash)	Not needed (hub processes once)
New socket event	Yes	Not needed
Works without browser	No	Yes — headless, API, all clients
Catches render-only failures	Yes (browser ground truth)	No (parse only)

The main tradeoff: hub-side validation misses browser-specific render failures (CSS/plugin issues). In practice, agent mermaid failures are almost always parse-time syntax errors, not render-time environment issues, so the coverage is sufficient for v1. A follow-up can add @mermaid-js/parser for full parse parity if needed.

Files expected to change

• hub/src/ — message pipeline hook + block extractor + diagram-type validator
• cli/src/api/apiSession.ts — add <render-issue> to SYSTEM_INJECTION_PREFIXES

No schema bump, no web changes, no new socket event types.