hyperhive/docs/terminal-rendering.md

Per-agent terminal: row taxonomy + inconsistencies

Snapshot of how the per-agent web UI's live pane renders each event kind today, written up so the next coherence pass has a reference to work from. Source of truth lives in hive-ag3nt/assets/app.js (renderStream, fmtToolUse, renderRichToolUse, renderToolResult, renderTaskEvent) + hive-fr0nt/assets/terminal.css (the shared .live .<class> styling).

Row taxonomy

CSS class	Prefix glyph	Color	Triggered by	Source
.turn-start	◆ TURN ← <from>	amber, bold, top-margin, amber left rule	LiveEvent::TurnStart	harness wake
.turn-body	(inline under turn-start)	fg dimmed 85%	same	the wake-prompt body
.turn-end-ok	✓ turn ok	green, green left rule	LiveEvent::TurnEnd { ok: true }	harness
.turn-end-fail	✗ turn fail — note	red, red left rule	LiveEvent::TurnEnd { ok: false }	harness
.text	none	fg/white, indented	claude assistant.content[].text	stream-json
.thinking	· or · thinking …	muted, italic	claude assistant.content[].thinking	stream-json
.tool-use	→ Name args…	cyan	assistant.content[].tool_use	stream-json
.tool-use <details>	→ Name path · +N	cyan, body is diff	rich tool_use (Write/Edit)	renderRichToolUse
.tool-use <details>	→ send → to · headline	cyan, body is text	mcp__hyperhive__send	renderRichToolUse
.tool-result	← <txt>	muted	short user.content[].tool_result (≤120c)	stream-json
.tool-result-block <details>	▸ ← Nl · headline	muted, body is text	long tool_result (>120c)	stream-json
.tool-use	⌁ task <id> started · <desc> [type]	cyan	claude Task-tool subagent event	renderTaskEvent
.turn-end-ok / .turn-end-fail / .tool-result	⌁ task <id> ✓/✗/◌ <status> · <desc> · → <output_file>	green / red / muted	claude Task-tool result	renderTaskEvent
.note	· <text>	muted	LiveEvent::Note (harness chatter, /cancel /compact /new-session, stderr lines, etc.)	harness
.sys	· {json…}	muted	anything renderStream doesn't recognise	catch-all
.result	(defined, never emitted today)	green	—	—
Banner shimmer	mauve	turn in flight (ref-counted)	setBannerActive

Where the inconsistencies live

1. Glyph vocabulary drifts:

   • tool_use uses →
   • tool_result uses ←
   • thinking uses ·
   • notes use ·
   • turn-end ok/fail use ✓ / ✗
   • turn-start uses ◆
   • task events use ⌁
   • The · glyph is overloaded across thinking, notes, sys.

2. What gets a <details> block vs a flat row is per-tool ad-hoc: Write/Edit always expand, send always expands, every other tool_use is flat regardless of input size. tool_result is flat if ≤120 chars otherwise <details>.

3. Stderr handling: claude's stderr lines come through as LiveEvent::Note with text: "stderr: <line>" — they render as muted · stderr: …, identical styling to harness notes about /compact / /model. No red-tinted "this is an error" affordance for stderr.

4. Catch-all .sys rows are visually identical to .note rows — both muted, both · prefix. They look like normal notes despite usually being "an event renderStream couldn't classify". Unmatched stream shapes (rate limit warnings under odd type/subtype combos, future claude additions, etc.) silently fall through.

5. .tool-use ranges from one-liner (Read foo.md) to multi-page collapsed diff — same color, same prefix glyph, very different visual weight. A small marker on the collapsed <details> summary would help (the ▸ is present in .tool-result-block summaries but absent in tool-use <details> summaries).

6. Cancel/compact/new-session notes are styled the same as autonomous harness chatter; nothing flags them as "operator initiated."

7. Turn-start / turn-end are visually overweight: the triggering event row + the closing row both get bold text, top margins, and a full coloured background tint. The coloured left rule alone already says "this is a turn boundary" — the heavy chrome adds noise without information. Drop the bold/margin/tint, keep the left rule.

8. Left-alignment is incoherent across row types: the ▸ disclosure marker on expandable rows doesn't sit in the same column as flat-row prefix glyphs (→, ←, ·), so the prefix column wanders by row kind. Expandable tool_use (→ Name …) and expandable tool_result (▸ ← Nl …) use different layouts from each other too. Pick one prefix column and align every row kind into it; the disclosure marker should be visually inside that column, not pushed to the side.

9. Continuation lines aren't inset: when a row's body wraps (e.g. → foo bar baz quux …), the second visual line starts at column 0 rather than under the f of foo, so wrapped content blurs into the next row. Want a text-indent / hanging-indent rule so continuation lines align with the start of the body, not the prefix glyph.

10. Most message-bearing rows are collapsed by default even when the body is the whole point: send, recv, ask, and friends hide their text behind a <details> summary. The summary headline is rarely enough context. Want these expanded by default, with collapse reserved for genuinely heavy payloads (multi-page diffs, long tool_result blocks).

11. Tools from extra MCP servers aren't pretty-printed: renderRichToolUse only special-cases the built-in hyperhive tools (Write/Edit/send). Anything coming from extraMcpServers (matrix, bitburner, …) falls through to the generic → Name args… JSON dump. Either a plugin-style hook in the renderer map, or at minimum a nicer generic args-pretty-printer that handles common shapes (single string arg, single dict arg, etc.).

12. No markdown rendering on message bodies: send / recv / ask / answer / agent text content all arrive as markdown-flavoured prose (bullets, fenced code, bold, links) but render as raw text. Want a minimal markdown pass — at least lists, fenced code, inline code, bold/italic, links — applied to message bodies and probably to the assistant.content[].text .text row.

Suggested coherence pass

Pick one scheme and audit all renderers to match. A concrete proposal:

• → cyan: outbound action (tool_use, send)
• ← muted: inbound result (tool_result)
• ◆ amber: turn framing (turn_start)
• ✓ / ✗: success / failure, green / red (turn_end, task_notification)
• ⌁ mauve: subagent / background event (task_*)
• · muted: ambient note, italic for thinking
• ! orange: caught error (stderr lines, .sys catch-all that landed something the renderer didn't recognise)

Plus: every tool_use <details> summary gets ▸ so collapsed content is visually announced. Operator-initiated notes get a distinct prefix (op· or similar) so they're easier to spot in the scrollback.

The .sys catch-all should escalate visually — a louder "unrecognised event" rendering surfaces silently-dropped event shapes for future fix-up rather than hiding them in the muted note stream.

Layout rules to apply uniformly

• One prefix column for every row kind — flat rows and expandable rows alike. The disclosure marker (▸) lives inside that column, not as a separate gutter, so glyph alignment doesn't shift between row types.
• Hanging indent on wrapped bodies so continuation lines start under the first character of the body, not under the prefix glyph. Probably display: grid with grid-template-columns: <prefix-col> 1fr per row, or text-indent/padding-left with negative text-indent.
• Turn boundaries are rule-only — drop the bold + margin
  • tint on .turn-start / .turn-body / .turn-end-*. The coloured left rule alone carries the boundary signal.
• Default-expanded message rows: send, recv, ask, answer, and short-ish text rows render their body inline (no <details>). Reserve collapse for genuinely heavy bodies — multi-page diffs, long tool_results, thinking blocks past N lines.

Renderer surface for extra MCP tools

renderRichToolUse currently switches on hard-coded tool names. Replace with a registry keyed by mcp__<server>__<tool> (and the built-in claude tool names) that maps to a (toolUse) -> Node renderer. Per-agent extra MCPs can register their own renderers via a small JS hook (loaded the same way extra-mcp.json is loaded server-side); the fallback is a generic args-pretty-printer that handles single-string and single-dict shapes nicely instead of dumping raw JSON.

Markdown rendering

Apply a minimal markdown pass to message bodies (send / recv / ask / answer) and to assistant text rows. Scope: paragraphs, lists, fenced + inline code, bold/italic, links. No HTML passthrough, no images, no tables — explicitly bounded so we don't import a kitchen-sink parser into the per-agent page. A small handwritten pass or a tiny dep (e.g. micromark / marked) both work.

Dashboard side (not covered here)

The main dashboard's message-flow pane is a different beast: broker messages render as .msgrow grid lines (ts / arrow / from / → / to / body) with separate styling. The current file focuses only on the per-agent terminal.