Commit graph hyperhive/docs/terminal-rendering.md
Author SHA1 Message Date
iris
1b8b83fee1 fix(terminal-rendering): move fmtToolUse table after numbered list
The heading was inserted between items 3 and 4, breaking GFM ordered
list numbering (Forgejo renders items 4+ restarting at 1). Move the
subsection to after item 5 and update the in-prose reference to use
an anchor link instead of 'see table below'.
2026-07-04 18:56:59 +02:00
iris
8f876d0154 docs(terminal-rendering): expand fmtToolUse with complete pattern table
Replace the sparse 3-line prose description of fmtToolUse with a full
reference table covering every tool case added over the past several
PRs. Adds a new subsection listing the short-name convention (* suffix),
all Claude built-ins (Read/Write/Edit/Glob/Grep/Bash/TodoWrite), the
full hyperhive MCP surface (recv/send/ask/answer/remind/set_status/
get_loose_ends/get_agent_meta/cancel_loose_end/ack_until/kill/restart/
start/update/get_logs/get_host_journal/request_apply_commit/
request_init_config/request_update_meta_inputs), all scheduling tools
(list_schedules/cancel_schedule/fire_schedule_now/edit_schedule/
request_schedule_prompt — added in the previous PR), bash MCP tools
(run/status/kill), and matrix MCP tools (send_message/send_dm/
send_reply/send_reaction/read_room/mark_read/join_room/open_dm/
invite_user/download_file).
2026-07-04 18:56:59 +02:00
iris
cea2f2faff docs(terminal-rendering): expand fmtToolUse description to cover new cases
The renderer dispatch section only mentioned recv and Bash as fmtToolUse
examples. Update the description to cover the full range: matrix tools,
remind, scheduling, and the fmtArgsGeneric fallback.
2026-07-04 13:12:17 +02:00
iris
44bb64fa1f docs(terminal-rendering): fix stale send_message fmtArgsGeneric example
mcp__matrix__send_message now has a specific fmtToolUse case and no
longer falls through to fmtArgsGeneric. Update the prose to reflect
that common tools have specific cases.
2026-07-04 13:12:17 +02:00
iris
6c56bf76d6 feat(agent-term): matrix-tool icons + formatters, fill remaining fmtToolUse gaps
Add specific icons for matrix tools that had the generic 💬 fallback:
- mcp__matrix__read_room → 📖
- mcp__matrix__mark_read → 👁️
- mcp__matrix__list_rooms / list_room_members / list_invites → 📋
- mcp__bash__kill → 🛑 (was generic 🔧)

Add fmtToolUse cases for high-use tools that fell through to fmtArgsGeneric:
- set_status: 'set_status* "idle"' instead of 'set_status text: "idle"'
- get_loose_ends: 'get_loose_ends* [iris]' or 'get_loose_ends*()'
- get_agent_meta: 'get_agent_meta* iris' or 'get_agent_meta*()'
- cancel_loose_end: 'cancel_loose_end* question #42'
- bash kill: 'kill* abc123 [force]'
- Matrix tools: 'read_room* !abc1234 [50]', 'mark_read* !abc1234',
  'send_message* → !room: "body"', 'send_dm* → @mara: "body"',
  'send_reply*', 'send_reaction*', 'join_room*', 'open_dm*',
  'invite_user*', 'download_file*'

Also extend the short-name shortening to cover mcp__matrix__ prefix
(was only hyperhive + bash), so matrix tool rows show 'read_room*'
instead of 'mcp__matrix__read_room' as the prefix.

Two small helpers added: fmtRoom (truncates !id before ':' for
readability; keeps #alias intact) and fmtUser (@user:server → @user).

Closes #2198. Updates terminal-rendering.md icon list.
2026-07-04 13:12:17 +02:00
iris
1011428cc7 docs(terminal-rendering): document plugin_install, commands_changed, compact_boundary rows
The renderer dispatch section was missing entries for three system
subtypes that now have specific renderers (added in the preceding
commits on this branch). Update the row taxonomy table and the
numbered dispatch description to cover all four system-subtype
handlers (thinking_tokens was already documented; 1b–1e are new).
2026-07-04 11:59:37 +02:00
iris
57f936af63 fix(agent): strip tool_use_error tags and render errors in red
When a tool call fails, claude wraps the result text in
<tool_use_error>...</tool_use_error> XML tags. The terminal was
displaying these raw, producing output like:
  '<tool_use_error>File has not been read yet.</tool_use_error>'

Fix renderToolResult in app.js:
- Check c.is_error on the tool_result content block.
- Strip the <tool_use_error>...</tool_use_error> wrapper from the text.
- Render error results with a '✗' prefix under '.tool-result.error'
  (flat, ≤120c) or '.tool-result-block.error' (<details>, longer text).

Add .live .tool-result.error { color: var(--red); } to terminal.css
so error results are visually distinct (red, same as turn-end-fail).

Update terminal-rendering.md row taxonomy to document the two new
error row classes.

Closes #2104.
2026-07-01 18:34:03 +02:00
iris
1c47bd4333 agent-ui: real fixed-width icon column for terminal rows
Replaces the first-character-glyph + negative-text-indent trick (which let a
wide emoji or a leading disclosure caret knock the icon out of column) with a
genuine icon cell.

terminal.js: row() / details() / detailsDiff() take an optional `icon` that
goes in a fixed-width `.row-glyph` element (inline-block, 1.4em). Details
summaries wrap their text in a `.summary-text` span; the disclosure caret
moves to `.summary-text::before` so it leads the text, not the icon — keeping
the icon in the shared column. terminal.css carries the cell + caret rules.

app.js passes the per-tool emoji as `icon` for the flat tool-use row and every
expandable tool summary (Write/Edit/send/ask/answer/bash) plus the 💭 thinking
row, instead of string-prefixing it. A details `🖥️` now lines up under a flat
row's `🧠` regardless of emoji width. Doc: terminal-rendering.md layout
contract updated. Closes #1844.
2026-06-22 00:41:24 +02:00
iris
fb58f0e5b9 agent-ui: per-tool emoji icons + thinking/turn-end glyphs in terminal
Following the 🧠 thinking-tokens indicator (operator liked it), give terminal
rows evocative glyphs:
- 💭 thinking prose (pairs with the 🧠 token counter)
- / turn-end ok/fail (was ✓/✗)
- per-tool icons via toolIcon(name): 📤 send · 📥 recv ·  ask · ✍️ answer
  ·  remind · 🏷️ set_status · 🪢 loose-ends · ↻/⏹️/▶️/🔄 lifecycle · 📦
  request_* · ⏱️ schedule · 🖥️ bash · 💬 matrix · 📖 Read · 💾 Write · ✏️
  Edit · 🔍 Glob/Grep · 🔧 default — on both flat rows and the rich
  send/ask/answer/Write/Edit summaries.

Dropped the original 🐝 task-row glyphs: claude's nested-agent Task tool is
intentionally omitted from agents' allow-list (mcp.rs), so those rows never
render for agents. Doc table updated.

Closes the emojify-terminal request.
2026-06-21 23:15:25 +02:00
iris
63a79d76ba agent-ui: collapse streamed thinking_tokens ticks into one live row
claude streams a running 'estimated_tokens' counter as system/thinking_tokens
events — many per turn (thousands in a long turn). renderStream rendered each
as a '⚙ thinking_tokens' note, flooding the terminal scrollback. Coalesce
consecutive ticks into a single '🧠 thinking … ~N tokens' note row that
updates in place; reuse the row only while it's still the last one rendered
(nextElementSibling == null) so any other event starts a fresh one. Closes
#1818.
2026-06-21 22:09:31 +02:00
iris
6b4b0f11c0 docs(web-ui): document turn start/end times + duration on the agent terminal
Follow-up to the turn-time feature: the terminal now stamps a wall-clock
time on the turn-start / turn-end rows and an elapsed duration on
turn-end, sourced from a per-event `ts` (unix seconds) that the backend
serializes as a flattened sibling of the event tag on both the live SSE
frame and each history row.

- terminal-rendering.md: add the `.turn-time` row to the taxonomy table
  + a note on the ts source and the graceful degradation when a frame
  omits ts.
- web-ui/agent.md: note the ts sibling on the emitted events, and the
  time/duration suffixes on the TurnStart / TurnEnd renderings.
2026-06-10 15:38:04 +02:00
iris
5ca96b8c85 docs: scrub self-ref cookies across 5 files (#719 batch 2)
All five files scrubbed to 0 issue-ref cookies. Most refs were
'(closes #NNN)' style attribution after closed work landed.

- docs/turn-loop.md: 6 → 0 (#598 unified binary, #419 auth-fail,
  #542 mtime resumption, #519 role markers, #442 spawn path,
  #474/#478 partial edit)
- docs/approvals.md: 5 → 0 (#317 flake validation, #250 withdraw,
  #441 rebuild-queue dispatch, #753 manager port hash, #425
  crash-watch grace)
- docs/terminal-rendering.md: 2 → 0 (#666 ask-operator inline)
- docs/conventions.md: 3 → 0 (#753 port hash, #692 parent
  sentinel, #486 reparenting)
- docs/security.md: 4 → 0 (#240 + #658 ×2 + #673/#678 attribution)

Combined with PR #810 (docs/web-ui.md 14→0), this PR closes the
small / medium files. Remaining: agent-hierarchy.md (13),
gotchas.md (13), persistence.md (13). gateway.md is atlas's lane.
2026-05-31 15:39:09 +02:00
iris
a9114342e4 agent/terminal: neutral [resolved] label for closed asks (argus #668)
Loose-ends endpoint only carries pending state — a question
disappearing from the list can mean answered, cancelled by asker,
or TTL expired. Previous [answered ✓] glyph implied successful
operator response across all three paths.

Rename .ask-answered-tag → .ask-resolved-tag and use the neutral
[resolved] label. Full resolution detail (who answered with what)
remains visible via the question's history in the side panel.

Addresses argus review note on #668.
2026-05-30 21:45:33 +02:00
iris
e056e82d6d agent/terminal: inline answer form under ask → operator rows (#666)
When an agent calls mcp__hyperhive__ask with to==operator (the
default), the rich tool-use renderer now mounts an empty
ask-answer-inline-slot inside the expanded ask row and enqueues a
loose-ends refresh. A new reconcileAskBinds() walks waiting slots
on every loose-ends update, matches each against pending
operator-bound questions by question text, and injects the same
inline answer form the side panel uses (buildAnswerForm → POST to
the host dashboard answer-question endpoint). When a question
resolves, the form gets replaced by a struck-through [answered ✓]
tag so the scrollback reflects the closed state.

Lets the operator respond to agent questions inline in the live
terminal without context-switching to the loose-ends side panel or
the dashboard Y3R C4LL tab.

Refreshes loose-ends both on tool_use render (best-effort, may
miss the question before the broker persists it) and on the
matching tool_result (the right moment — MCP has just returned the
assigned id). Slots are pruned on /clear and defensively filtered
for isConnected on each reconcile.

closes #666
2026-05-30 21:45:33 +02:00
iris
229c4292e9 frontend: cut over Rust binaries to ServeDir; delete legacy assets
Phase 4 of #273 — the actual switch. Both axum routers now serve
their static surface via `tower_http::services::ServeDir` mounted
as a fallback service, reading the dist path from `HIVE_STATIC_DIR`
(set by Phase 3's NixOS module wiring).

Deletes:
- `hive-c0re/assets/{index.html, app.js, dashboard.css}`
- `hive-ag3nt/assets/{index.html, app.js, agent.css, stats.html,
   stats.js, screen.html}`
- The whole `hive-fr0nt/` crate (workspace member dropped, both
  hive-c0re and hive-ag3nt drop their `hive-fr0nt.workspace = true`
  dep). Its contents now live as `@hive/shared` under
  `frontend/packages/shared/`.

Rust changes:
- `hive-c0re/src/dashboard.rs`: remove `serve_index`, `serve_css`,
  `serve_app_js`, `serve_shared_js`, `serve_marked_js`,
  `serve_favicon` (all six `include_str!` handlers); replace their
  routes with a single `.fallback_service(ServeDir::new(static_dir))`
  on the router. Fail closed (anyhow::bail) if `HIVE_STATIC_DIR` is
  unset or not a directory at startup.
- `hive-ag3nt/src/web_ui.rs`: remove `serve_index`, `serve_css`,
  `serve_app_js`, `serve_shared_js`, `serve_marked_js`,
  `serve_stats`, `serve_stats_js`, `serve_screen`; same
  `fallback_service` pattern. `serve_icon` stays (consumes
  `/etc/hyperhive/icon.svg` + `branding/hyperhive.svg` fallback,
  neither of which lives under the frontend dist).
- `AgentLink` URLs for stats/screen switched from `/stats` / `/screen`
  to `/stats.html` / `/screen.html` since ServeDir doesn't auto-
  append the extension and the on-disk filename is the natural URL
  post-cutover.
- `Cargo.toml` (workspace): drop `hive-fr0nt` member + workspace
  dep, add `tower-http = { version = "0.6", features = ["fs"] }`.
- `hive-c0re/Cargo.toml` + `hive-ag3nt/Cargo.toml`: drop the
  `hive-fr0nt.workspace = true` dep, add `tower-http.workspace =
  true`.

Docs updated:
- `CLAUDE.md`: file map reflects `frontend/` (was `hive-fr0nt/` +
  `assets/`) and the ServeDir/HIVE_STATIC_DIR shape.
- `docs/web-ui.md` 'Shape (shared by both)' section: describes the
  ServeDir fallback + bundled-by-esbuild surface, no more
  `include_str!` references.
- `docs/terminal-rendering.md`: src paths point at
  `frontend/packages/{agent,shared}/src/`; marked is the npm dep,
  not vendored UMD.

Validation:
- `cargo check --workspace` — clean (5 warnings, all pre-existing
  in `rebuild_queue.rs`, none on changed files).
- `cargo clippy --workspace --all-targets` — clean (11 warnings,
  same pre-existing source).
- `cd frontend && npm run build` from the prior commit's lockfile
  produces the dist directories the new routers consume:
    dashboard: `dist/{index.html, static/{app.js, dashboard.css}}`
    agent:     `dist/{index.html, stats.html, screen.html,
                       static/{app.js, stats.js, agent.css}}`
  (favicon.svg lands in dashboard/ during the nix build —
  `nix/frontend.nix` install phase copies `branding/hyperhive.svg`
  there, since it's outside the npm tree.)

Refs #273.
2026-05-23 14:51:01 +02:00
iris
9b9277db78 fix: vendor marked UMD build so window.marked is defined (issue #244) 2026-05-22 16:33:13 +02:00
iris
4539091f3c terminal: show recv wait/max params + bash [bg] flag
recv tool-use rows rendered as a bare recv() regardless of args,
hiding whether a turn is parked on a long-poll (wait_seconds) or
draining a burst (max). fmtToolUse now surfaces both. Bash rows
gain a [bg] flag when run_in_background is set.

closes #158
2026-05-21 17:57:24 +02:00
müde
69a3ca7469 docs: prune landed todos + refresh scratchpad + as-built terminal-rendering
todo: drop landed entries (terminal coherence pass, get_state_file
defense-in-depth, self-management of loose ends, persist+cold-load
ctx-badge).

claude.md:
- scratchpad: new just-landed entries for ctx+cost badge split,
  terminal coherence pass, loose_ends rename + cancel_loose_end,
  whoami, reminder failure persistence, path linkify, tombstones+
  meta_inputs events, agent open-threads section + container pending-
  reminder chip + task event rendering. drops the meta-flake
  "just landed" — structural facts live in the file map +
  approvals.md, the narrative was no longer load-bearing.
- file map: hive-fr0nt now lists MARKED_JS + marked.min.js + the
  unified prefix-column terminal.css update.
- reading paths: terminal-rendering.md description matches as-built.

docs/terminal-rendering.md: rewritten as as-built reference. layout
contract documents the padding-left + negative text-indent prefix
column + how details inherits it. row taxonomy reflects current
state (notes split into .note / .note.stderr / .note.op; .sys is
amber; recv tool_results default-open with markdown body via
tool_use_id correlation; rich send/ask/answer renderers). new
sections for renderer dispatch flow, markdown integration,
fmtArgsGeneric extra-MCP fallback, dashboard msgrow text-indent
reset.
2026-05-18 19:25:50 +02:00
müde
8a3e8bfb7f todo + terminal-rendering: ctx-badge cold-load, auto session-reset, more coherence-pass gripes 2026-05-18 18:00:46 +02:00
müde
5389875079 docs: terminal-rendering.md — row taxonomy + inconsistencies + coherence proposal 2026-05-18 11:27:35 +02:00