From fa2a75d4994722caef73b7e6bb9f1bafbb62b63b Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 16 Nov 2026 00:28:54 +0100 Subject: [PATCH] swarm ui: an open todos section on the agent card --- docs/2-handbook/swarm/ui.md | 4 ++ docs/4-implementation/web-ui/swarm-ui.md | 7 ++- .../swarm-ui/src/agent/detail/AgentDetail.tsx | 5 +- .../swarm-ui/src/agent/detail/sections.ts | 11 ++-- .../src/agent/terminal/AgentTodos.css | 42 ++++++++++++++++ .../src/agent/terminal/AgentTodos.tsx | 50 +++++++++++++++++++ .../src/agent/terminal/agent-todos.ts | 29 +++++++++++ .../src/agent/terminal/useAgentTodos.ts | 23 +++++++++ .../swarm-ui/test/agent-todos.test.mjs | 36 +++++++++++++ .../swarm-ui/test/detail-sections.test.mjs | 5 +- 10 files changed, 200 insertions(+), 12 deletions(-) create mode 100644 frontend/packages/swarm-ui/src/agent/terminal/AgentTodos.css create mode 100644 frontend/packages/swarm-ui/src/agent/terminal/AgentTodos.tsx create mode 100644 frontend/packages/swarm-ui/src/agent/terminal/agent-todos.ts create mode 100644 frontend/packages/swarm-ui/src/agent/terminal/useAgentTodos.ts create mode 100644 frontend/packages/swarm-ui/test/agent-todos.test.mjs diff --git a/docs/2-handbook/swarm/ui.md b/docs/2-handbook/swarm/ui.md index 5286c2322..ed1970e5b 100644 --- a/docs/2-handbook/swarm/ui.md +++ b/docs/2-handbook/swarm/ui.md @@ -29,6 +29,10 @@ declared state, destroy included. A card shows **updating** while the hive updates the agent, from the moment the update stops its container until the container is back up, so the stopped agent doesn't read as lost. +An agent's card also lists its **open todos**: what each says, which part of the +system raised it and how long ago. The list is read only and follows the agent's +own within a few seconds. + Type `/` in an agent's message box and a menu lists what that agent accepts: the swarm's own commands (`/compact`, `/clear-todos`) and the skills the agent's harness published. Arrow keys move, Tab completes, Esc closes. Skills diff --git a/docs/4-implementation/web-ui/swarm-ui.md b/docs/4-implementation/web-ui/swarm-ui.md index a6a91e41e..6c61ae04f 100644 --- a/docs/4-implementation/web-ui/swarm-ui.md +++ b/docs/4-implementation/web-ui/swarm-ui.md @@ -98,8 +98,8 @@ and config PR. While the agent list loads for the first time, the page shows gre placeholder cards with the same layout as the real ones, so the cards don't jump when the data arrives. The placeholders stand still where motion is off. -An opened card has four sections, and each reads nothing until you open it. -**status** and **terminal** start open, the other two folded: +An opened card has six sections, and each reads nothing until you open it. +**status** and **terminal** start open, the other four folded: - **status**: how fresh the agent's last report is (with its age), its turn state, context and cost, its hive, links to its profile and its config repo on the swarm's forge (built from the forge entry @@ -109,7 +109,10 @@ An opened card has four sections, and each reads nothing until you open it. - **terminal**: the live terminal with its message box. Typing `/` opens a menu filled from `GET /api/agents//commands`, which lists the swarm's own commands and the skills the agent published. +- **open todos**: the agent's open todos from `GET /api/agents//todos`, newest first, each with + its subsystem, one line of text and how long ago it changed. Read only; refetched every ten seconds. - **subagents**: the agent's subagents and their terminal preview (next section). +- **background tasks**: the agent's bash tasks (see the section on them below). - **settings**: inference, instructions, resource caps, internet, allowed domains and permissions, then the agent's linked accounts and the menu that links another. Internet, allowed domains and permissions show a badge; select diff --git a/frontend/packages/swarm-ui/src/agent/detail/AgentDetail.tsx b/frontend/packages/swarm-ui/src/agent/detail/AgentDetail.tsx index f8e33e9ca..358aeeeb1 100644 --- a/frontend/packages/swarm-ui/src/agent/detail/AgentDetail.tsx +++ b/frontend/packages/swarm-ui/src/agent/detail/AgentDetail.tsx @@ -43,6 +43,7 @@ import { startsOpen, type DetailSection, } from "./sections.js"; +import { AgentTodos } from "../terminal/AgentTodos.js"; import { BashTasks } from "../terminal/BashTasks.js"; import { SubagentTerms } from "../terminal/SubagentTerms.js"; import { WantedMenu } from "../roster/WantedMenu.js"; @@ -317,6 +318,8 @@ function SectionBody({ case "terminal": // The agent's live terminal and its input box. return ; + case "todos": + return ; case "subagents": return ; case "tasks": @@ -332,7 +335,7 @@ export function AgentDetail({ }: { row: AgentRow; actions: AgentActions; - /** Add the live terminal, subagents and background tasks sections. */ + /** Add the live terminal, todos, subagents and background tasks sections. */ withTerminal?: boolean; /** * An opened card, whose header already shows the state rows. Without it diff --git a/frontend/packages/swarm-ui/src/agent/detail/sections.ts b/frontend/packages/swarm-ui/src/agent/detail/sections.ts index 50ce94b07..d61f81353 100644 --- a/frontend/packages/swarm-ui/src/agent/detail/sections.ts +++ b/frontend/packages/swarm-ui/src/agent/detail/sections.ts @@ -4,29 +4,26 @@ /** One folded block of an opened agent card. */ export type DetailSection = - | "status" - | "terminal" - | "subagents" - | "tasks" - | "settings"; + "status" | "terminal" | "todos" | "subagents" | "tasks" | "settings"; /** What each section's header says. */ export const SECTION_TITLE: Record = { status: "status", terminal: "terminal", + todos: "open todos", subagents: "subagents", tasks: "background tasks", settings: "settings", }; /** - * The sections a card shows, top to bottom. The terminal, subagents and tasks are + * The sections a card shows, top to bottom. The terminal, todos, subagents and tasks are * left out where the page is already beside a terminal (the terminal page's * details popover). */ export function sectionsFor(withTerminal: boolean): DetailSection[] { return withTerminal - ? ["status", "terminal", "subagents", "tasks", "settings"] + ? ["status", "terminal", "todos", "subagents", "tasks", "settings"] : ["status", "settings"]; } diff --git a/frontend/packages/swarm-ui/src/agent/terminal/AgentTodos.css b/frontend/packages/swarm-ui/src/agent/terminal/AgentTodos.css new file mode 100644 index 000000000..c5decfaa5 --- /dev/null +++ b/frontend/packages/swarm-ui/src/agent/terminal/AgentTodos.css @@ -0,0 +1,42 @@ +/* — the rows of an agent's open todos. */ +.ui-agent-todos-count { + margin: 0 0 0.5em; + color: var(--muted); +} + +.ui-agent-todos-list { + display: flex; + flex-direction: column; + gap: 0.35em; + margin: 0; + padding: 0; + list-style: none; +} + +.ui-agent-todos-item { + display: grid; + grid-template-columns: 6em minmax(0, 1fr) auto; + align-items: baseline; + gap: 0.75em; +} + +.ui-agent-todos-subsystem { + overflow: hidden; + color: var(--blue); + font-family: var(--mono, monospace); + font-size: 0.85em; + text-overflow: ellipsis; + white-space: nowrap; +} + +.ui-agent-todos-summary { + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.ui-agent-todos-age { + color: var(--muted); + font-size: 0.85em; + white-space: nowrap; +} diff --git a/frontend/packages/swarm-ui/src/agent/terminal/AgentTodos.tsx b/frontend/packages/swarm-ui/src/agent/terminal/AgentTodos.tsx new file mode 100644 index 000000000..59df3d080 --- /dev/null +++ b/frontend/packages/swarm-ui/src/agent/terminal/AgentTodos.tsx @@ -0,0 +1,50 @@ +// — an agent's open todos, in its card's "todos" section: what each +// says, which subsystem raised it and since when. The list is +// `GET /api/agents/{name}/todos` (`useAgentTodos`), which swarm-controller reads +// from what the agent's harness published. Read-only. +// +// Mount it keyed by agent name: the refresh timer is armed once per mount. +import { ApiErrorPanel } from "@hive/shared/api-error-panel.js"; +import { Hint } from "../../ui/hint/Hint.js"; +import { RelativeTime } from "../../ui/relative-time/RelativeTime.js"; +import { todosLabel } from "./agent-todos.js"; +import { useAgentTodos } from "./useAgentTodos.js"; +import "./AgentTodos.css"; + +export function AgentTodos({ agentName }: { agentName: string }) { + const { todos, error } = useAgentTodos(agentName); + return ( +
+ {error && ( + + )} + {todos === null ? ( + error ? null : ( + … + ) + ) : todos.length === 0 ? ( + {todosLabel(todos)} + ) : ( + <> +

{todosLabel(todos)}

+
    + {todos.map((t) => ( +
  • + {t.subsystem} + + {t.summary} + + + + +
  • + ))} +
+ + )} +
+ ); +} diff --git a/frontend/packages/swarm-ui/src/agent/terminal/agent-todos.ts b/frontend/packages/swarm-ui/src/agent/terminal/agent-todos.ts new file mode 100644 index 000000000..a17cee074 --- /dev/null +++ b/frontend/packages/swarm-ui/src/agent/terminal/agent-todos.ts @@ -0,0 +1,29 @@ +// An agent's open todos as `GET /api/agents/{name}/todos` serves them: what the +// agent's harness last published, newest first. + +/** One row of `GET /api/agents/{name}/todos`. */ +export interface AgentTodo { + /** The harness's own id for it. */ + id: number; + /** What produced it: `matrix`, `forge`, `bash`, … */ + subsystem: string; + /** What it says, as one line. */ + summary: string; + /** Where it came from, when the producer says. */ + source?: string; + /** Unix seconds when it was last updated. */ + updated_unix: number; +} + +/** Newest first; ties by id, the higher one first. */ +export function sortTodos(todos: AgentTodo[]): AgentTodo[] { + return [...todos].sort( + (a, b) => b.updated_unix - a.updated_unix || b.id - a.id, + ); +} + +/** The count in words: `no open todos`, `1 open todo`, `3 open todos`. */ +export function todosLabel(todos: AgentTodo[]): string { + if (todos.length === 0) return "no open todos"; + return todos.length === 1 ? "1 open todo" : `${todos.length} open todos`; +} diff --git a/frontend/packages/swarm-ui/src/agent/terminal/useAgentTodos.ts b/frontend/packages/swarm-ui/src/agent/terminal/useAgentTodos.ts new file mode 100644 index 000000000..7ea75b396 --- /dev/null +++ b/frontend/packages/swarm-ui/src/agent/terminal/useAgentTodos.ts @@ -0,0 +1,23 @@ +// An agent's open todos, refetched on a timer: `GET /api/agents/{name}/todos`. +// `null` until the first answer; a failed fetch sets `error` and keeps the last +// list. Mount per agent name: the poll belongs to one agent. +import type { ProblemDetails } from "@hive/shared/api-error.js"; +import { fetchJson, usePolled } from "../../ui/polled/usePolled.js"; +import { sortTodos, type AgentTodo } from "./agent-todos.js"; + +const REFRESH_MS = 10_000; + +export function useAgentTodos(agentName: string): { + todos: AgentTodo[] | null; + error: ProblemDetails | null; +} { + const { data, error } = usePolled(REFRESH_MS, async (signal) => + sortTodos( + await fetchJson( + `/api/agents/${encodeURIComponent(agentName)}/todos`, + signal, + ), + ), + ); + return { todos: data, error }; +} diff --git a/frontend/packages/swarm-ui/test/agent-todos.test.mjs b/frontend/packages/swarm-ui/test/agent-todos.test.mjs new file mode 100644 index 000000000..4f9cba1c6 --- /dev/null +++ b/frontend/packages/swarm-ui/test/agent-todos.test.mjs @@ -0,0 +1,36 @@ +// An agent's open todos: their order and the count in words. Run by `npm test`. +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { sortTodos, todosLabel } from "../src/agent/terminal/agent-todos.ts"; + +const todo = (id, updated_unix) => ({ + id, + subsystem: "forge", + summary: `todo ${id}`, + updated_unix, +}); + +test("the newest todo comes first and a tie goes to the higher id", () => { + const ids = sortTodos([ + todo(1, 100), + todo(2, 300), + todo(3, 300), + todo(4, 200), + ]).map((t) => t.id); + assert.deepEqual(ids, [3, 2, 4, 1]); +}); + +test("sorting leaves the list it was given alone", () => { + const list = [todo(1, 100), todo(2, 200)]; + sortTodos(list); + assert.deepEqual( + list.map((t) => t.id), + [1, 2], + ); +}); + +test("the count reads in words", () => { + assert.equal(todosLabel([]), "no open todos"); + assert.equal(todosLabel([todo(1, 1)]), "1 open todo"); + assert.equal(todosLabel([todo(1, 1), todo(2, 2)]), "2 open todos"); +}); diff --git a/frontend/packages/swarm-ui/test/detail-sections.test.mjs b/frontend/packages/swarm-ui/test/detail-sections.test.mjs index 63b5d88ba..cb1eeb4d9 100644 --- a/frontend/packages/swarm-ui/test/detail-sections.test.mjs +++ b/frontend/packages/swarm-ui/test/detail-sections.test.mjs @@ -8,17 +8,18 @@ import { startsOpen, } from "../src/agent/detail/sections.ts"; -test("a card holds status, terminal, subagents, background tasks, then settings", () => { +test("a card holds status, terminal, open todos, subagents, background tasks, then settings", () => { assert.deepEqual(sectionsFor(true), [ "status", "terminal", + "todos", "subagents", "tasks", "settings", ]); }); -test("a page beside a terminal leaves the terminal, subagents and tasks out", () => { +test("a page beside a terminal leaves the terminal, todos, subagents and tasks out", () => { assert.deepEqual(sectionsFor(false), ["status", "settings"]); });