Drop classifyEvent.ts, render TermMsg directly
Per review: StreamRow was meant to match what the server sends in TermMsg, not be a separate model needing a translation step. - classifyEvent.ts and streamRow.ts deleted; termMsg.ts holds the wire types (TermMsg/TermEnvelope) plus TermRow, a TermMsg with just the key/fromHistory bookkeeping Preact needs for list rendering. - Row.tsx renders a TermRow directly: level -> CSS class, empty summary + markdown body -> flat row, everything else with a body -> expandable details gated by the operator's preference. No separate classification step. - useLiveStream.ts drops ClassifyCtx (a single incrementing key counter didn't need a whole context object) and maps envelopes to rows inline. - docs/terminal-rendering.md trimmed substantially — was documenting more implementation detail than useful; points at stream_enrich.rs for the per-tool specifics instead of duplicating them in prose.
This commit is contained in:
iris
parent
5eefaa951d
commit
cebf3c6ced
6 changed files with 156 additions and 436 deletions
|
|
@ -1,264 +1,51 @@
|
|||
# Per-agent terminal: row taxonomy (as built)
|
||||
|
||||
Snapshot of how the per-agent web UI's live pane renders each
|
||||
event kind today. Every row on the wire is one **`TermMsg`**
|
||||
The per-agent web UI's live pane renders one row per `TermMsg`
|
||||
(`hive-agent/src/term_msg.rs`): `{icon?, level: debug|info|warn|error,
|
||||
summary, body?, body_format?: markdown|diff, coalesce_key?}` — six
|
||||
fields, the same shape for every row, no `kind` tag. A raw claude
|
||||
`stream-json` line (`LiveEvent::Stream`) can classify into zero, one, or
|
||||
several `TermMsg`s (an assistant message with both a text block and a
|
||||
tool_use block produces two); other `LiveEvent` variants
|
||||
(`TurnStart`/`TurnEnd`/`Note`) map straight to one each, and the five
|
||||
agent-state variants (`StatusChanged`/`ModelChanged`/`EffortChanged`/
|
||||
`TokenUsageChanged`/`TurnStateChanged`) always produce zero — they never
|
||||
render as terminal rows, the header/badges read `/api/state` instead.
|
||||
summary, body?, body_format?: markdown|diff, coalesce_key?}`. Classification
|
||||
(icon, summary text, whether a tool call gets an expandable body) happens
|
||||
server-side, once — `term_msg.rs` + `stream_enrich.rs` — and is served
|
||||
identically by both `GET /api/events/history` and `GET /api/events/stream`
|
||||
as `TermEnvelope { ts, seq?, msgs: TermMsg[] }` frames
|
||||
(`hive-agent/src/web_ui/stream.rs`).
|
||||
|
||||
Classification happens **server-side**, once, in
|
||||
`hive-agent/src/term_msg.rs` (top-level dispatch) +
|
||||
`hive-agent/src/stream_enrich.rs` (the `Stream` payload's per-tool/
|
||||
per-event breakdown — icon, summary text, expandable body). Both the
|
||||
live SSE tail (`GET /api/events/stream`) and the paginated history
|
||||
replay (`GET /api/events/history`) call the same `classify()` and
|
||||
serve identically-shaped `TermEnvelope { ts, seq?, msgs: TermMsg[] }`
|
||||
frames (`hive-agent/src/web_ui/stream.rs`) — the sqlite event log still
|
||||
stores the raw, unclassified event, so classification logic can change
|
||||
without a DB migration.
|
||||
The frontend renders a `TermMsg` close to as-is
|
||||
(`frontend/packages/agent/src/components/Row.tsx`): `level` picks the
|
||||
CSS colour (`terminal.css`'s `.live .level-*`), an empty `summary` +
|
||||
markdown `body` renders as a flat row with just the body (assistant
|
||||
text), and any other bodied row is an expandable `<details>`, opened by
|
||||
default according to the operator's expand-tool-output preference
|
||||
(`getExpandDetailsPref()`) — uniformly, no per-tool override. There's no
|
||||
separate client-side row model or classification step.
|
||||
|
||||
The frontend (`frontend/packages/agent/src/lib/classifyEvent.ts`) is a
|
||||
thin adapter: `TermMsg` → `StreamRow` (`lib/streamRow.ts`), rendered by
|
||||
`components/Row.tsx`. It does **not** re-derive icons, summaries, or
|
||||
per-tool formatting — that all happened server-side already. Its only
|
||||
real decision is body layout: an empty-`summary` + markdown-`body` row
|
||||
renders as a flat row with just the body (assistant text); every other
|
||||
bodied row is an expandable `<details>`, opened by default according to
|
||||
the operator's expand-tool-output preference (`getExpandDetailsPref()`,
|
||||
`@hive/shared/prefs.ts`) — uniformly, no per-tool server override.
|
||||
`frontend/packages/shared/src/terminal/terminal.css` supplies the
|
||||
`.live .level-*` colour rules + shared row layout.
|
||||
## Layout
|
||||
|
||||
## Layout contract
|
||||
Every row shares one prefix column via `padding-left` + negative
|
||||
`text-indent` on `.live .row`; an icon (when set) sits in a fixed-width
|
||||
`.row-glyph` cell so icons of different rendered widths still line up.
|
||||
`<details>` summaries reuse the same metrics, with the disclosure caret
|
||||
leading the summary text rather than the icon.
|
||||
|
||||
Every row — flat `<div class="row …">` and expandable
|
||||
`<details class="row …">` alike — shares one prefix column.
|
||||
The mechanism is `padding-left + negative text-indent` on
|
||||
`.live .row`: the row's first inline box gets pulled back
|
||||
into the column at ~0.5em, and wrapped continuation lines
|
||||
hang under the body, not under the glyph.
|
||||
## Levels
|
||||
|
||||
Rows that carry an icon (the per-tool emoji, `🧠`/`💭`
|
||||
thinking, etc.) set the `StreamRow.icon` prop, which
|
||||
`components/Row.tsx` renders into a
|
||||
fixed-width `.row-glyph` cell (`display: inline-block;
|
||||
width: 1.4em`) rather than as a bare first character. The
|
||||
constant cell width means every icon's left edge lines up in
|
||||
the column regardless of the glyph's rendered width (emoji
|
||||
differ; some carry a variation selector) — a flat row's `🧠`
|
||||
and a `details` summary's `🖥️` align. Rows with a plain
|
||||
single-char glyph (`◆ · ! ←`) still pass it inline; it lands
|
||||
at the same ~0.5em left edge.
|
||||
|
||||
`<details>` summaries inherit those metrics. The icon (when
|
||||
present) sits in the `.row-glyph` cell; the summary text lives
|
||||
in a `.summary-text` span and the disclosure caret (`▸` / `▾`)
|
||||
is supplied by CSS `.summary-text::before` so it **leads the
|
||||
text, not the icon** — a leading caret on the icon would push
|
||||
it out of the shared column. Icon-less summaries have no
|
||||
`.row-glyph`, so the caret falls into the prefix column like
|
||||
the old directional glyph. The summary text carries no
|
||||
`→` / `←`; the row colour (cyan = outbound, muted = inbound)
|
||||
carries the direction.
|
||||
|
||||
Child blocks inside a row (the `.md` markdown wrapper, an
|
||||
inner `<details>`) get `text-indent: 0` so their content
|
||||
lays out from the body column instead of inheriting the
|
||||
parent's negative pull.
|
||||
|
||||
## Row taxonomy
|
||||
|
||||
Every row carries a **level** (`debug`/`info`/`warn`/`error`), which is
|
||||
the *only* thing that drives its colour — `frontend/packages/shared/src/
|
||||
terminal/terminal.css`'s `.live .level-debug/-info/-warn/-error` rules.
|
||||
There's no separate per-row-kind class any more (no `.turn-start`,
|
||||
`.tool-use`, `.tool-result.error`, `.sys`, …) — structural identity
|
||||
(this is a turn boundary, this is a tool call, this is an error) is
|
||||
carried by the row's **icon** and **summary text** instead, computed
|
||||
server-side once and read verbatim by the client.
|
||||
|
||||
| Level | Colour | Used for |
|
||||
| Level | Colour | Roughly |
|
||||
|---|---|---|
|
||||
| `debug` | muted | thinking, thinking-token ticks, plugin-install/status ticks, ambient harness chatter, unrecognised-system-subtype notes |
|
||||
| `info` | default fg | turn start/ok, assistant text, tool calls + their (non-error) results, operator-initiated notes |
|
||||
| `warn` | amber, left rule | stderr lines, an unrecognised stream-json shape, API retry backoff |
|
||||
| `error` | red, left rule | turn failed, a tool result with `is_error: true`, a hard API error |
|
||||
| `debug` | muted | thinking, coalesced ticks, ambient harness chatter |
|
||||
| `info` | default fg | turn start/ok, assistant text, tool calls + results |
|
||||
| `warn` | amber, left rule | stderr, an unrecognised event shape, API retries |
|
||||
| `error` | red, left rule | turn failed, a tool result with `is_error: true` |
|
||||
|
||||
Representative summaries (icon + text, `hive-agent/src/term_msg.rs` +
|
||||
`stream_enrich.rs`):
|
||||
|
||||
| Row | icon | level | summary | body |
|
||||
|---|---|---|---|---|
|
||||
| turn start | `◆` | info | `TURN ← <from>` | the wake-prompt text (plain) |
|
||||
| turn ok | `✅` | info | `turn ok` | — |
|
||||
| turn failed | `❌` | error | `turn fail — <note>` | — |
|
||||
| assistant text | — | info | *(empty)* | the text itself (markdown) — renders as a flat row, no prefix line |
|
||||
| thinking | `💭` | debug | the thinking text (or `thinking …`) | — |
|
||||
| thinking-token tick | `🧠` | debug | `thinking… ~N tokens` (`coalesce_key: "thinking-tok"`, in-place updates) | — |
|
||||
| tool call | per-tool, see [salient-arg formatting](#salient-arg-formatting) | info | `<short-name> <args…>` | some tools: diff (Edit) / markdown (`send`) / plain (long `mcp__bash__run` cmd) |
|
||||
| tool result, short | `←` | info | the trimmed result text | — |
|
||||
| tool result, long | — | info | `Nl · headline…` | the full text (plain) |
|
||||
| tool result, `recv`-correlated | — | info | `recv ← <summary>` | the full text (markdown) |
|
||||
| tool result, error (short) | `✗` | error | the trimmed error text | — |
|
||||
| tool result, error (long) | — | error | `Nl · headline…` | the full error text (plain) |
|
||||
| subagent task start/notify (dead path — `Task` not in the agent allow-list) | `⌁` | info | `task <id> started · <desc> [type]` / `task <id> ✓/✗/◌ <status> · <desc> · → <file>` | — |
|
||||
| plugin install / status tick | — | debug | `⚙ plugin install · loading…\|✓ done` / `⚙ status` (both `coalesce_key`-collapsed) | — |
|
||||
| commands changed | — | debug | `⚙ commands changed · N available` | one `/name` per line (plain) |
|
||||
| compact boundary / API retry / API error / unrecognised system subtype | — | debug / warn / error / debug | `⚙ compact · …` / `⚠ api retry · …` / `✗ api error · …` / `⚙ <subtype>` | — |
|
||||
| harness note | — | debug | the note text | — |
|
||||
| stderr line | — | warn | `stderr: <line>` | — |
|
||||
| operator-initiated note | — | info | `operator: <text>` | — |
|
||||
| unrecognised stream-json shape | `!` | warn | trimmed raw JSON | — |
|
||||
|
||||
Whether a bodied row renders open or collapsed is a **client-only**
|
||||
decision — the operator's expand-tool-output preference
|
||||
(`getExpandDetailsPref()`), applied uniformly to every row with a body.
|
||||
There's no server-side per-tool override any more (the old `recv`/`send`
|
||||
"always default-open" special case is gone).
|
||||
|
||||
## Classification pipeline
|
||||
|
||||
1. `hive-agent/src/term_msg.rs::classify()` is the top-level dispatch,
|
||||
called once per `LiveEvent` at SSE-emit time (both the live tail and
|
||||
history replay — see `web_ui/stream.rs`):
|
||||
- `TurnStart`/`TurnEnd`/`Note` map straight to one `TermMsg` each.
|
||||
- The five agent-state variants (`StatusChanged`/…) always produce
|
||||
zero — never rendered as terminal rows.
|
||||
- `Stream(value)` delegates to `stream_enrich::classify_stream_value`.
|
||||
2. `classify_stream_value` walks one raw claude `stream-json` line:
|
||||
- top-level `result` / `rate_limit_event` → dropped (no rows).
|
||||
- `type: "system"` → `classify_system`, which computes
|
||||
`(category, summary, body)` per `subtype` (`system_fields()`) and
|
||||
maps `category` to a level + optional `coalesce_key`:
|
||||
`"thinking_tok"` → debug, coalesced; `"details"` (currently just
|
||||
`commands_changed`) → debug, with an expandable body; `"note"` →
|
||||
level varies by subtype (`api_error` → error, `api_retry` → warn,
|
||||
`plugin_install`/`status` → debug + coalesced, everything else →
|
||||
debug).
|
||||
- `subtype: "task_started" | "task_notification"` (regardless of
|
||||
top-level `type`) → `classify_task_event`.
|
||||
- `type: "assistant"` → walk `message.content[]`: `text` → info row,
|
||||
empty summary, markdown body; `thinking` → debug row with `💭`;
|
||||
`tool_use` → `classify_tool_use` (records `id → name` in the
|
||||
connection/page-scoped `ClassifyCtx` for the next step, computes
|
||||
icon + summary via `fmt_tool_use()`/`tool_icon()`, and a body via
|
||||
`rich_tool_body()` for the fixed set of tools that have one).
|
||||
- `type: "user"` → walk `message.content[]` for `tool_result`:
|
||||
`classify_tool_result` correlates `tool_use_id` against the
|
||||
`ClassifyCtx` to spot a `recv` result (rendered `recv ← …` with a
|
||||
markdown body), strips the `<tool_use_error>` wrapper on errors,
|
||||
and otherwise picks short-flat vs. long-with-body by length.
|
||||
- Unrecognised shape → warn row, trimmed raw JSON, `!` icon.
|
||||
3. `frontend/packages/agent/src/lib/classifyEvent.ts::classifyEvent`
|
||||
maps each `TermMsg` in the envelope to a `StreamRow`
|
||||
(`lib/streamRow.ts`) — `level` → `level-*` CSS class, `body_format`
|
||||
→ which of `markdown`/`diff`/`plain` body prop to set, empty-summary
|
||||
markdown body → the flat "assistant text" shape, everything else
|
||||
with a body → an expandable `<details>` gated by the operator's
|
||||
preference. `components/Row.tsx` renders the result.
|
||||
|
||||
`ClassifyCtx` (tool_use `id → name` correlation, needed for step 2's
|
||||
`recv` detection) is scoped per SSE connection on the live path and per
|
||||
page on the history path — it does not cross the live/history boundary,
|
||||
so a `recv` result whose `tool_use` fell on the other side of a
|
||||
reconnect or page load renders as a plain block instead of default-open
|
||||
markdown. Accepted, documented degradation
|
||||
(`hive-agent/src/term_msg.rs`'s `ClassifyCtx` doc), not a bug.
|
||||
|
||||
### Salient-arg formatting
|
||||
|
||||
Server-side (`fmt_tool_use()` and its per-tool-family helpers in
|
||||
`hive-agent/src/stream_enrich.rs`), computed into the `TermMsg`'s
|
||||
`summary` field and read verbatim by the client. The `short` name strips the
|
||||
`mcp__hyperhive__` / `mcp__bash__` / `mcp__matrix__` prefix and
|
||||
appends `*` (e.g. `recv*`, `run*`, `send_message*`). Unprefixed
|
||||
tools (Read, Write, etc.) keep their name as-is.
|
||||
|
||||
| Tool | Rendered as |
|
||||
|------|-------------|
|
||||
| **Claude built-ins** | |
|
||||
| `Read` | `Read <path>` |
|
||||
| `Write` | flat, same shape as Read: `Write <path>` — no diff/count (`content` can be megabytes and is one-sided; open the file to inspect it) |
|
||||
| `Edit` | rich diff row `Edit <path> · -N +N` (just `+N` for a pure insert, i.e. empty `old_string`) |
|
||||
| `Glob` | `Glob <pattern>` |
|
||||
| `Grep` | `Grep <pattern>` |
|
||||
| `Bash` | `Bash [bg] $ <cmd>` (dead path — built-in `Bash` isn't in the agent allow-list either; shell execution goes through `mcp__bash__run` / `run*` below instead) |
|
||||
| `TodoWrite` | `TodoWrite (N items)` (dead path — `TodoWrite` isn't in the agent allow-list; its state lives in claude's in-process session and evaporates on `/compact`, so agents plan in `/state` notes instead) |
|
||||
| **Core hyperhive** | |
|
||||
| `send*` | rich renderer: `send* → to · NL` (markdown body, expand state now follows the operator's preference like every other bodied row — see [Row taxonomy](#row-taxonomy)) |
|
||||
| `recv*` | `recv*()` · `recv* wait Ns` · `recv* max N` |
|
||||
| `remind*` | `remind* +Xm "preview"` or `remind* at HH:MMZ "preview"` |
|
||||
| `set_status*` | `set_status* "text"` |
|
||||
| `get_loose_ends*` | `get_loose_ends*()` or `get_loose_ends* [agent]` |
|
||||
| `get_agent_meta*` | `get_agent_meta*()` or `get_agent_meta* name` |
|
||||
| `cancel_loose_end*` | `cancel_loose_end* kind #id` |
|
||||
| `ack_until*` | `ack_until* ≤N` |
|
||||
| `mark_todos_done*` | `mark_todos_done* [id1, id2, …]` (first 8 ids, `…` past that) |
|
||||
| **Lifecycle** | |
|
||||
| `kill*/restart*/start*/update*` | `kill* name` (etc.) |
|
||||
| `get_logs*` | `get_logs* name` or `get_logs* name NL` |
|
||||
| `get_host_journal*` | `get_host_journal*()` or with `[container] · [/grep/] · NL` |
|
||||
| **Approvals / config** | |
|
||||
| `request_init_config*` | `request_init_config* name` |
|
||||
| `request_update_meta_inputs*` | `request_update_meta_inputs* [inp1, …]` or `all` |
|
||||
| **Scheduling** | |
|
||||
| `list_schedules*` | `list_schedules*()` |
|
||||
| `cancel_schedule*` | `cancel_schedule* #id all` or `#id [t1, t2]` |
|
||||
| `fire_schedule_now*` | `fire_schedule_now* #id` |
|
||||
| `edit_schedule*` | `edit_schedule* #id · body · interval · next · +N tgt · -N tgt` (only changed fields shown) |
|
||||
| `request_schedule_prompt*` | `request_schedule_prompt* → t1, t2 at HH:MMZ` (+ `+Ns` if recurring) |
|
||||
| **Bash MCP** | |
|
||||
| `run*` | `run* [bg] $ cmd` (also rich renderer for full cmd body) |
|
||||
| `status*` (bash) | `status* id:xyz` or `status* id:xyz · wait Ns` |
|
||||
| `kill*` (bash) | `kill* id` or `kill* id [force]` |
|
||||
| **Matrix MCP** | |
|
||||
| `send_message*/send_dm*/send_reply*` | `send_message* → room: "body"` / `send_dm* → @user: "body"` |
|
||||
| `send_reaction*` | `send_reaction* room emoji` |
|
||||
| `read_room*` | `read_room* room` or `read_room* room [N]` |
|
||||
| `mark_read*` | `mark_read* room` |
|
||||
| `join_room*/open_dm*` | `join_room* room` / `open_dm* @user` |
|
||||
| `invite_user*` | `invite_user* @user → room` |
|
||||
| `download_file*` | `download_file* room` |
|
||||
| **Everything else** | `fmt_args_generic` — see [Extra-MCP tools](#extra-mcp-tools) |
|
||||
Per-tool icon + summary formatting (what a `Read`/`Edit`/`send` call's row
|
||||
actually says) lives in `stream_enrich.rs`'s `fmt_tool_use()` family —
|
||||
read that when you need the specifics, this doc doesn't duplicate it.
|
||||
|
||||
## Markdown
|
||||
|
||||
`frontend/packages/agent/src/lib/markdown.ts`'s `renderMarkdown(text)`
|
||||
runs `marked.parse(text)` through DOMPurify and is rendered into a
|
||||
`<div class="md">` by `components/Row.tsx`'s `MarkdownBody`. CSS in
|
||||
`terminal.css` scopes paragraph / code / list / blockquote / link
|
||||
styling under `.live .row .md` so the markdown body doesn't bleed into
|
||||
the row's own text-indent. Applied to any `TermMsg` with
|
||||
`body_format: "markdown"` — assistant text, `send`'s body, a
|
||||
`recv`-correlated tool result.
|
||||
|
||||
## Extra-MCP tools
|
||||
|
||||
`fmt_args_generic(name, input)` (`hive-agent/src/stream_enrich.rs`)
|
||||
is the fallback when a tool isn't in the built-in `fmt_tool_use`
|
||||
switch, computed into the `TermMsg`'s `summary` field server-side:
|
||||
|
||||
- single string field → `name k: "v"`
|
||||
- single number/bool field → `name k: v`
|
||||
- multi-field → first 4 pairs trimmed to `k: "v"` /
|
||||
`k: [N]` / `k: {…}` with a `…+N` overflow
|
||||
|
||||
This keeps less-frequent tools that don't have a specific
|
||||
`fmt_tool_use` case from dumping raw JSON. Common matrix and
|
||||
hyperhive tools have their own cases and skip this path.
|
||||
`frontend/packages/agent/src/lib/markdown.ts`'s `renderMarkdown()` runs
|
||||
`marked.parse()` through DOMPurify into a `<div class="md">`. Applied to
|
||||
any `TermMsg` with `body_format: "markdown"`.
|
||||
|
||||
## Dashboard side (not covered here)
|
||||
|
||||
The main dashboard's message-flow pane is a different
|
||||
shape: broker messages render as `.msgrow` grid lines (ts /
|
||||
arrow / from / → / to / body) with their own styling.
|
||||
`.live .msgrow` explicitly resets `text-indent: 0` so the
|
||||
per-agent terminal's hanging-indent metrics don't leak into
|
||||
the flex-grid broker rows.
|
||||
The main dashboard's message-flow pane is a different shape: broker
|
||||
messages render as `.msgrow` grid lines, not agent-terminal rows.
|
||||
|
|
|
|||
Loading…
Reference in a new issue