From 0a72f212da1d5d67ab58f50bfb8eec94e01a4d12 Mon Sep 17 00:00:00 2001 From: iris Date: Thu, 19 Nov 2026 19:07:02 +0100 Subject: [PATCH] swarm ui: a terminal keeps 2000 rows and folds a burst of rows in at once useSwarmTermStream appended each event with [...rows, row] and never dropped one, so a tab on a busy agent grew without bound in memory and DOM and each event cost a copy of the whole list. appendRows (a pure module, tested) folds a batch in with one copy, coalesces as before, and keeps the newest 2000. Events are collected for 50ms and folded in together, so a burst is one render. The comments that described the old coalescing in useSwarmTermStream.ts's header and in termMsg.ts's TermEnvelope doc named a hook that no longer exists (useLiveStream), so both now point at term-rows.ts, where the rule lives. --- docs/4-implementation/web-ui/swarm-ui.md | 5 ++ .../packages/shared/src/terminal/termMsg.ts | 6 +- .../swarm-ui/src/agent/terminal/term-rows.ts | 31 ++++++++++ .../src/agent/terminal/useSwarmTermStream.ts | 59 +++++++++++-------- .../packages/swarm-ui/test/term-rows.test.mjs | 57 ++++++++++++++++++ 5 files changed, 129 insertions(+), 29 deletions(-) create mode 100644 frontend/packages/swarm-ui/src/agent/terminal/term-rows.ts create mode 100644 frontend/packages/swarm-ui/test/term-rows.test.mjs diff --git a/docs/4-implementation/web-ui/swarm-ui.md b/docs/4-implementation/web-ui/swarm-ui.md index 319cf90ca..037e71236 100644 --- a/docs/4-implementation/web-ui/swarm-ui.md +++ b/docs/4-implementation/web-ui/swarm-ui.md @@ -192,6 +192,11 @@ scroll it, and it doesn't announce new rows, since many can arrive in a second. Once you scroll up it stops following the newest row, and a **latest** badge over its bottom-right corner scrolls back and follows again. +A terminal keeps its newest 2000 rows. When more arrive, the oldest drop off the +top: a terminal that follows the newest row doesn't show it, but one you scrolled far +up in loses what you were reading once 2000 rows have come in since. The terminal +adds rows that arrive within 50 ms of each other in one step, so a burst of rows is one redraw. + The page around it has a skip link (**skip to content**, the first Tab stop), a `
` landmark that takes the focus when a page opens, and a hidden `

` with the page's name. The active tab in the header carries `aria-current`. diff --git a/frontend/packages/shared/src/terminal/termMsg.ts b/frontend/packages/shared/src/terminal/termMsg.ts index 3faaf7224..00d7fc2dd 100644 --- a/frontend/packages/shared/src/terminal/termMsg.ts +++ b/frontend/packages/shared/src/terminal/termMsg.ts @@ -29,9 +29,9 @@ export interface TermMsg { /** One SSE frame / history array entry — `hive-agent`'s `TermEnvelope`. * `seq` is the live per-event dedup counter (`BusEvent::seq`); absent on - * history-replayed envelopes, see useLiveStream.ts's backfill dance. It is - * the only field left: the event's time rides on each row's own `ts`, where - * a consumer reading a bare row (the swarm queue's) can also see it. + * history-replayed envelopes. It is the only field left: the event's time + * rides on each row's own `ts`, where a consumer reading a bare row (the swarm + * queue's) can also see it. * * Local to the per-hive stream — the swarm relay carries no envelope. */ export interface TermEnvelope { diff --git a/frontend/packages/swarm-ui/src/agent/terminal/term-rows.ts b/frontend/packages/swarm-ui/src/agent/terminal/term-rows.ts new file mode 100644 index 000000000..e4c504d55 --- /dev/null +++ b/frontend/packages/swarm-ui/src/agent/terminal/term-rows.ts @@ -0,0 +1,31 @@ +// The rows a terminal keeps, and how a batch of new ones is folded in. A stream +// for a busy agent never ends, so the list is capped: the oldest rows drop off the +// front, and a tab open for days holds `MAX_ROWS` rows, not every row since. +import type { TermRow } from "@hive/shared/term-msg.js"; + +/** How many rows a terminal keeps. */ +export const MAX_ROWS = 2000; + +/** + * `rows` with `batch` appended, in order. A row with the same `coalesce_key` as + * the last one replaces it (keeping its `key`), so a progress line updates in + * place. At most `max` rows are kept, the newest. Copies the list once per + * batch, not once per row. + */ +export function appendRows( + rows: TermRow[], + batch: TermRow[], + max: number = MAX_ROWS, +): TermRow[] { + if (batch.length === 0) return rows; + const out = rows.slice(); + for (const row of batch) { + const last = out[out.length - 1]; + if (row.coalesce_key && last && last.coalesce_key === row.coalesce_key) { + out[out.length - 1] = { ...row, key: last.key }; + } else { + out.push(row); + } + } + return out.length > max ? out.slice(out.length - max) : out; +} diff --git a/frontend/packages/swarm-ui/src/agent/terminal/useSwarmTermStream.ts b/frontend/packages/swarm-ui/src/agent/terminal/useSwarmTermStream.ts index c5ed0a9c1..3dd33700d 100644 --- a/frontend/packages/swarm-ui/src/agent/terminal/useSwarmTermStream.ts +++ b/frontend/packages/swarm-ui/src/agent/terminal/useSwarmTermStream.ts @@ -1,14 +1,11 @@ // Live SSE consumer for the swarm-relayed agent terminal // (`GET /api/agents/{name}/term/stream`, swarm-controller's -// `term_stream.rs`). Deliberately NOT `@hive/agent`'s `useLiveStream` — -// that hook's wire shape is `TermEnvelope` (`{seq, msgs: []}`) plus a -// history/backfill dance; the swarm relay forwards one bare `TermMsg` -// per SSE event, its replayed rows first and in order on the same -// stream, so there's nothing to buffer/dedupe/backfill against. The -// browser's own `Last-Event-ID` resumes a reconnect, so rows are kept -// across one. Same row-coalescing -// rule as `useLiveStream`'s `appendRow` (ported, not imported — one -// small helper isn't worth a cross-package hop for). +// `term_stream.rs`). The relay forwards one bare `TermMsg` per SSE event, its +// replayed rows first and in order on the same stream, so there is nothing to +// buffer, dedupe or backfill against. The browser's own `Last-Event-ID` +// resumes a reconnect, so rows are kept across one. Rows that arrive within +// 50 ms are folded in together, and `term-rows.ts` holds the rules for that: +// coalesce by key, and keep the newest `MAX_ROWS`. import { useEffect, useRef, useState } from "preact/hooks"; import type { TermMsg, TermRow } from "@hive/shared/term-msg.js"; @@ -17,16 +14,13 @@ import { type ConnectionState, } from "../../ui/stream/connection.js"; import { probeSession } from "../../ui/session/session.js"; +import { appendRows } from "./term-rows.js"; export type { ConnectionState }; -function appendRow(rows: TermRow[], row: TermRow): TermRow[] { - const last = rows[rows.length - 1]; - if (row.coalesce_key && last && last.coalesce_key === row.coalesce_key) { - return [...rows.slice(0, -1), { ...row, key: last.key }]; - } - return [...rows, row]; -} +// Rows that arrive close together are folded in at once: a busy turn sends many a +// second, and each fold copies the list. +const BATCH_MS = 50; export interface UseSwarmTermStreamResult { rows: TermRow[]; @@ -48,6 +42,18 @@ export function useSwarmTermStream( setRows([]); setConnection("connecting"); keySeqRef.current = 0; + let batch: TermRow[] = []; + let timer: ReturnType | null = null; + function flush() { + timer = null; + const next = batch; + batch = []; + setRows((prev) => appendRows(prev, next)); + } + function push(row: TermRow) { + batch.push(row); + if (timer === null) timer = setTimeout(flush, BATCH_MS); + } const es = new EventSource(streamUrl); es.onopen = () => setConnection("open"); es.onmessage = (e) => { @@ -57,17 +63,15 @@ export function useSwarmTermStream( try { msg = JSON.parse(e.data); } catch { - setRows((prev) => - appendRow(prev, { - key, - level: "warn", - fromHistory: false, - summary: "[parse err] " + e.data, - }), - ); + push({ + key, + level: "warn", + fromHistory: false, + summary: "[parse err] " + e.data, + }); return; } - setRows((prev) => appendRow(prev, { ...msg, key, fromHistory: false })); + push({ ...msg, key, fromHistory: false }); }; es.onerror = () => { const state = connectionAfterError(es.readyState); @@ -75,7 +79,10 @@ export function useSwarmTermStream( // The browser gave up: say whether the session ended, which `EventSource` does not tell. if (state === "closed") probeSession(); }; - return () => es.close(); + return () => { + es.close(); + if (timer !== null) clearTimeout(timer); + }; }, [streamUrl, attempt]); return { rows, connection, reconnect: () => setAttempt((n) => n + 1) }; diff --git a/frontend/packages/swarm-ui/test/term-rows.test.mjs b/frontend/packages/swarm-ui/test/term-rows.test.mjs new file mode 100644 index 000000000..c599a1cf5 --- /dev/null +++ b/frontend/packages/swarm-ui/test/term-rows.test.mjs @@ -0,0 +1,57 @@ +// How a terminal folds new rows in: order, coalescing, and the cap. Run by +// `npm test`. +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { appendRows, MAX_ROWS } from "../src/agent/terminal/term-rows.ts"; + +const row = (key, extra = {}) => ({ key, summary: key, ...extra }); + +test("a batch is appended in order", () => { + const out = appendRows([row("a")], [row("b"), row("c")]); + assert.deepEqual( + out.map((r) => r.key), + ["a", "b", "c"], + ); +}); + +test("an empty batch returns the same list, so nothing re-renders", () => { + const rows = [row("a")]; + assert.equal(appendRows(rows, []), rows); +}); + +test("the input list is not changed", () => { + const rows = [row("a")]; + appendRows(rows, [row("b")]); + assert.equal(rows.length, 1); +}); + +test("a row with the last row's coalesce key replaces it and keeps its key", () => { + const rows = [row("a"), row("b", { coalesce_key: "p", summary: "1/3" })]; + const out = appendRows(rows, [ + row("c", { coalesce_key: "p", summary: "2/3" }), + row("d", { coalesce_key: "p", summary: "3/3" }), + ]); + assert.deepEqual( + out.map((r) => [r.key, r.summary]), + [ + ["a", "a"], + ["b", "3/3"], + ], + ); +}); + +test("a coalesce key that is not the last row's appends", () => { + const rows = [row("a", { coalesce_key: "p" }), row("b")]; + const out = appendRows(rows, [row("c", { coalesce_key: "p" })]); + assert.equal(out.length, 3); +}); + +test("only the newest rows are kept past the cap", () => { + const rows = Array.from({ length: 5 }, (_, i) => row("r" + i)); + const out = appendRows(rows, [row("r5"), row("r6")], 4); + assert.deepEqual( + out.map((r) => r.key), + ["r3", "r4", "r5", "r6"], + ); + assert.ok(MAX_ROWS >= 1000); +});