diff --git a/docs/4-implementation/web-ui/swarm-ui.md b/docs/4-implementation/web-ui/swarm-ui.md index 7483bf922..070d3d754 100644 --- a/docs/4-implementation/web-ui/swarm-ui.md +++ b/docs/4-implementation/web-ui/swarm-ui.md @@ -43,7 +43,10 @@ Everything it shows comes from [`swarm-controller`](../../../swarm-controller/RE Pages that refresh on a timer share one polling rule: the page sends no new request while the last one is still running, so an older answer never overtakes a slow one, and a failed refresh keeps the rows already on screen under an -error. While a page is fetching, its refresh picker shows a spinner in place of +error. A list that isn't live says so: under a failed refresh it reads "showing the +last answer, from" and the time, and a page opened on the answer saved from the last +visit says that until a fresh one arrives (the alerts, builds, review runs, hives, +schedules and flows lists). While a page is fetching, its refresh picker shows a spinner in place of the clock, for at least 0.4 seconds so a quick answer still reads as a refresh. On a folded card (jobs, builds, hives) the picker sits in the card's header, left of the chevron, and shows once the card is open; selecting it doesn't fold the card. @@ -72,7 +75,8 @@ An agent created here or with `swarmctl agent create` starts `paused`; set it `up` from its card. A card shows **login needed** when the agent's own turn-state header says its claude has no session, and a **log in** button that runs the claude login from a dialog: open the URL it shows, then paste -the code back. When the secret store has the login, the dialog closes and a +the code back. A failed login offers **try again** in the same dialog. When the +secret store has the login, the dialog closes and a short toast in the top-right corner says so. The credentials go to the agent through the secret store ([`claude-login.md`](../../2-handbook/swarm/claude-login.md)). The agent's own web UI login still works too. The settings section of an opened card has a **claude login** row: when @@ -80,6 +84,11 @@ the swarm stored the agent's login, or that none is, with a **log in** button (**log in again** when the swarm holds one) that opens the same dialog, and a **delete login** action that asks first. +A card shows its freshness when the agent isn't **fresh**: **stale** with how long ago the hive last +reported it, **never reported**, or **not in swarm identity**. A fresh agent shows nothing, so the +badge is the reason a card matched the status filter. A failed state change shows its reason in a panel +under the card's header, not in a hover title. + A card shows **updating** when the agent's status snapshot has `updating` set. The hive sets it when an update stops a running container and clears it when the tail reconcile or start settles the agent, whether the container came back @@ -537,7 +546,7 @@ error and the agent gets nothing. While the agent is in a turn, a **cancel turn** badge appears among the state badges over the terminal, in its own tab. It asks the agent's harness to stop the turn, then shows whether one was running ("turn cancelled" or "nothing was -running"); a failure shows "cancel failed" with the reason on hover, and a click +running"); a failure shows "cancel failed: " and the reason in the badge, and a click tries again. Subagents have no message box and no cancel badge. The message doesn't go through the agent's hive, so the hive dashboard's diff --git a/frontend/packages/swarm-ui/src/App.tsx b/frontend/packages/swarm-ui/src/App.tsx index a4006a3a0..0ecb9e2f9 100644 --- a/frontend/packages/swarm-ui/src/App.tsx +++ b/frontend/packages/swarm-ui/src/App.tsx @@ -1,6 +1,13 @@ // Root shell component — routing only. Each route's content is its own // page component under `./pages/`; this file just maps paths to them. -import { Redirect, Route, Router, Switch, useSearch } from "wouter-preact"; +import { + Link, + Redirect, + Route, + Router, + Switch, + useSearch, +} from "wouter-preact"; import { MOVED_ROUTES, movedHref } from "./shell/routes.js"; import { Shell } from "./shell/Shell.js"; import { useGuardedLocation } from "./shell/useGuardedLocation.js"; @@ -28,6 +35,9 @@ function NotFound() { return (

no route here.

+

+ back to the start page +

); } diff --git a/frontend/packages/swarm-ui/src/agent/claude-login/ClaudeLoginDialog.tsx b/frontend/packages/swarm-ui/src/agent/claude-login/ClaudeLoginDialog.tsx index e9390eada..4ad7a0617 100644 --- a/frontend/packages/swarm-ui/src/agent/claude-login/ClaudeLoginDialog.tsx +++ b/frontend/packages/swarm-ui/src/agent/claude-login/ClaudeLoginDialog.tsx @@ -42,6 +42,8 @@ export function ClaudeLoginDialog({ }) { const [step, setStep] = useState({ step: "starting" }); const [code, setCode] = useState(""); + // Bumped by "try again": the effect below starts a new login for it. + const [attempt, setAttempt] = useState(0); useEffect(() => { let live = true; @@ -65,7 +67,13 @@ export function ClaudeLoginDialog({ return () => { live = false; }; - }, [agent]); + }, [agent, attempt]); + + function tryAgain() { + setCode(""); + setStep({ step: "starting" }); + setAttempt((n) => n + 1); + } function close() { if (leavesLoginRunning(step)) { @@ -104,7 +112,7 @@ export function ClaudeLoginDialog({ return ( - {step.step === "starting" &&

starting the login…

} + {step.step === "starting" &&

starting the login…

} {(step.step === "code" || step.step === "submitting") && ( <>

@@ -114,7 +122,7 @@ export function ClaudeLoginDialog({

)} {step.step === "failed" && ( - + <> + + + )}
diff --git a/frontend/packages/swarm-ui/src/agent/roster/AgentCard.tsx b/frontend/packages/swarm-ui/src/agent/roster/AgentCard.tsx index 4a19a1700..4c086da09 100644 --- a/frontend/packages/swarm-ui/src/agent/roster/AgentCard.tsx +++ b/frontend/packages/swarm-ui/src/agent/roster/AgentCard.tsx @@ -14,6 +14,7 @@ // ` - {problem !== null && (step !== "identity" || name !== "") && ( - - {problem} + {shownProblem !== null && ( + + {shownProblem} )} {step === "summary" ? ( @@ -567,6 +599,9 @@ export function CreateAgentForm({ disabled={ result.status === "submitting" || !hivesReady || !catalogue } + describedBy={ + createProblem !== null ? "create-agent-hint" : undefined + } > {result.status === "submitting" ? "creating…" : "create"} @@ -575,6 +610,9 @@ export function CreateAgentForm({ variant="primary" type="submit" disabled={problem !== null} + describedBy={ + problem !== null ? "create-agent-hint" : undefined + } > next diff --git a/frontend/packages/swarm-ui/src/pages/CreateAgentSteps.ts b/frontend/packages/swarm-ui/src/pages/CreateAgentSteps.ts index 93437f0ed..203575da5 100644 --- a/frontend/packages/swarm-ui/src/pages/CreateAgentSteps.ts +++ b/frontend/packages/swarm-ui/src/pages/CreateAgentSteps.ts @@ -73,6 +73,21 @@ export function stepProblem(step: Step, input: StepInputs): string | null { } } +/** + * The last step a tab can go to. The tabs reach as far as the operator has + * got (`reached`, an index into `STEPS`), but not past a step whose inputs are + * not valid now (`firstBad`, its index, or -1 for none), and never behind the + * current step (`at`). + */ +export function lastReachableStep( + reached: number, + firstBad: number, + at: number, +): number { + const limit = firstBad === -1 ? reached : Math.min(reached, firstBad); + return Math.max(limit, at); +} + /** One line of the summary: a setting and what will be sent for it. */ export interface SummaryRow { label: string; diff --git a/frontend/packages/swarm-ui/src/pages/builds/BuildsPage.tsx b/frontend/packages/swarm-ui/src/pages/builds/BuildsPage.tsx index 0121930de..fd03e9608 100644 --- a/frontend/packages/swarm-ui/src/pages/builds/BuildsPage.tsx +++ b/frontend/packages/swarm-ui/src/pages/builds/BuildsPage.tsx @@ -23,6 +23,7 @@ import { type RefreshIntervalMs, } from "../../ui/refresh-interval/RefreshInterval.js"; import { fetchJson, usePolled } from "../../ui/polled/usePolled.js"; +import { StaleNote } from "../../ui/polled/StaleNote.js"; import { RelativeTime } from "../../ui/relative-time/RelativeTime.js"; import { durationLabel } from "../../util.js"; import { @@ -100,6 +101,7 @@ function BuildsBody() { const { data: runs, error, + updatedAt, refreshing, } = usePolled(intervalMs, (signal) => fetchJson(RUNS, signal), { cacheKey: "builds", @@ -153,6 +155,11 @@ function BuildsBody() { problem={error} /> ) : null} + {missing ? ( the build in this link is no longer listed: the builder keeps only its diff --git a/frontend/packages/swarm-ui/src/pages/notifications/FlowEditorPage.tsx b/frontend/packages/swarm-ui/src/pages/notifications/FlowEditorPage.tsx index 8cba2829f..78562910f 100644 --- a/frontend/packages/swarm-ui/src/pages/notifications/FlowEditorPage.tsx +++ b/frontend/packages/swarm-ui/src/pages/notifications/FlowEditorPage.tsx @@ -12,6 +12,7 @@ // were changed elsewhere, and the editor offers to reload or to keep the draft // on top of the latest. import { useCallback, useEffect, useState } from "preact/hooks"; +import { usePageTitle } from "../../shell/page-title.js"; import { Link, useLocation, @@ -76,6 +77,7 @@ export function FlowEditorPage({ // With `from` an archetype flow: the one agent this copy is for. const agent = search.get("agent"); const [, navigate] = useLocation(); + usePageTitle(isNew ? "new flow" : `flow ${flowId}`); const [view, setView] = useState(null); const [draft, setDraft] = useState(null); // What a new draft started as, so leaving it untouched is not "unsaved". diff --git a/frontend/packages/swarm-ui/src/pages/notifications/NotificationsPage.tsx b/frontend/packages/swarm-ui/src/pages/notifications/NotificationsPage.tsx index 6a7fbb54a..16b51ad1e 100644 --- a/frontend/packages/swarm-ui/src/pages/notifications/NotificationsPage.tsx +++ b/frontend/packages/swarm-ui/src/pages/notifications/NotificationsPage.tsx @@ -22,6 +22,7 @@ import { type RefreshIntervalMs, } from "../../ui/refresh-interval/RefreshInterval.js"; import { fetchJson, usePolled } from "../../ui/polled/usePolled.js"; +import { StaleNote } from "../../ui/polled/StaleNote.js"; import { Deliveries, DeliveriesSkeleton } from "./Deliveries.js"; import { FlowListSkeleton } from "./FlowListSkeleton.js"; import { NEW_FLOW_PATH, withMembersAs } from "./FlowDraft.js"; @@ -45,6 +46,7 @@ export function NotificationRouter() { const { data: view, error, + updatedAt, refreshing: flowsRefreshing, refresh, } = usePolled(intervalMs, (signal) => @@ -126,6 +128,11 @@ export function NotificationRouter() { {error ? ( ) : null} + {actionError ? ( ) : null} + {runs !== null && runs.length === 0 && !error ? ( No runs yet. ) : null} diff --git a/frontend/packages/swarm-ui/src/pages/schedules/SchedulesPage.tsx b/frontend/packages/swarm-ui/src/pages/schedules/SchedulesPage.tsx index 4711ebd51..1f18d1216 100644 --- a/frontend/packages/swarm-ui/src/pages/schedules/SchedulesPage.tsx +++ b/frontend/packages/swarm-ui/src/pages/schedules/SchedulesPage.tsx @@ -22,6 +22,7 @@ import { type RefreshIntervalMs, } from "../../ui/refresh-interval/RefreshInterval.js"; import { fetchJson, usePolled } from "../../ui/polled/usePolled.js"; +import { StaleNote } from "../../ui/polled/StaleNote.js"; import type { TableColumn } from "../../ui/table/Table.js"; import type { AgentRow } from "../../agent/AgentTypes.js"; import { ScheduleCard, ScheduleListSkeleton } from "./ScheduleCard.js"; @@ -64,6 +65,7 @@ function SchedulesBody() { const { data: schedules, error, + updatedAt, refreshing: schedulesRefreshing, refresh, } = usePolled(intervalMs, (signal) => @@ -180,6 +182,11 @@ function SchedulesBody() { {error ? ( ) : null} + {actionError ? ( ) : null} + {!error && hives === null ? ( ) : null} diff --git a/frontend/packages/swarm-ui/src/shell/Shell.tsx b/frontend/packages/swarm-ui/src/shell/Shell.tsx index 5ef26d6b0..930bc1a66 100644 --- a/frontend/packages/swarm-ui/src/shell/Shell.tsx +++ b/frontend/packages/swarm-ui/src/shell/Shell.tsx @@ -29,6 +29,7 @@ import { useEffect, useRef, useState } from "preact/hooks"; import type { ComponentChildren } from "preact"; import { Link, useLocation } from "wouter-preact"; +import { usePageTitleValue } from "./page-title.js"; import { LinksMenu } from "./LinksMenu.js"; import { UserMenu } from "./UserMenu.js"; import { useHideDebug } from "./useHideDebug.js"; @@ -408,7 +409,9 @@ export function Shell({ children }: { children: ComponentChildren }) { // top-level route takes its nav label, a terminal route takes the // label its page registered as a dynamic tab. An unmatched path gets // the bare brand. + const pageTitle = usePageTitleValue(); const pageLabel = + pageTitle ?? navItems.find((item) => item.href === location)?.label ?? tabs.find((tab) => tab.href === location)?.label; useEffect(() => { diff --git a/frontend/packages/swarm-ui/src/shell/page-title.ts b/frontend/packages/swarm-ui/src/shell/page-title.ts new file mode 100644 index 000000000..aa2039f9b --- /dev/null +++ b/frontend/packages/swarm-ui/src/shell/page-title.ts @@ -0,0 +1,44 @@ +// The title a page gives itself, for the browser tab and the page's heading: for +// a route the shell cannot name from its nav items or open tabs, such as the +// flow editor, where several tabs would otherwise all read as the bare brand. +// A page calls `usePageTitle("flow fan-out")`; the shell reads it with +// `usePageTitleValue()` and falls back to its own label when none is set. +import { useEffect, useState } from "preact/hooks"; + +let current: string | undefined; +const listeners = new Set<() => void>(); + +/** Set the page's title (or clear it with `undefined`). */ +export function setPageTitle(title: string | undefined): void { + if (current === title) return; + current = title; + listeners.forEach((fn) => fn()); +} + +export function getPageTitle(): string | undefined { + return current; +} + +/** Subscribe to changes; returns the way to stop. */ +export function subscribePageTitle(fn: () => void): () => void { + listeners.add(fn); + return () => listeners.delete(fn); +} + +/** Give the page this title while it is mounted. */ +export function usePageTitle(title: string | undefined): void { + useEffect(() => { + setPageTitle(title); + return () => setPageTitle(undefined); + }, [title]); +} + +/** The title a page has set, if any, following changes. */ +export function usePageTitleValue(): string | undefined { + const [title, setTitle] = useState(getPageTitle()); + useEffect(() => { + setTitle(getPageTitle()); + return subscribePageTitle(() => setTitle(getPageTitle())); + }, []); + return title; +} diff --git a/frontend/packages/swarm-ui/src/ui/hint/Hint.tsx b/frontend/packages/swarm-ui/src/ui/hint/Hint.tsx index de5f7637b..53430ce58 100644 --- a/frontend/packages/swarm-ui/src/ui/hint/Hint.tsx +++ b/frontend/packages/swarm-ui/src/ui/hint/Hint.tsx @@ -16,12 +16,15 @@ export function Hint({ tone = "muted", as: Tag = "p", role, + id, class: extraClass, children, }: { tone?: HintTone; as?: "p" | "span" | "div"; role?: "status" | "alert"; + /** For a control's `aria-describedby`: the hint says why it is off. */ + id?: string; class?: string; children: ComponentChildren; }) { @@ -30,6 +33,7 @@ export function Hint({ .join(" "); return ( diff --git a/frontend/packages/swarm-ui/src/ui/polled/StaleNote.tsx b/frontend/packages/swarm-ui/src/ui/polled/StaleNote.tsx new file mode 100644 index 000000000..b396f925a --- /dev/null +++ b/frontend/packages/swarm-ui/src/ui/polled/StaleNote.tsx @@ -0,0 +1,36 @@ +// — says how old a polled list is when it is not live: under a failed +// refresh it shows the last good answer, and with a `cacheKey` the first paint is +// the answer saved on the last visit. Neither says so by itself, so a list such as +// "nothing is alerting" could be days old without a mark. Renders nothing for a +// list that is current. +import { Hint } from "../hint/Hint.js"; +import { RelativeTime } from "../relative-time/RelativeTime.js"; + +export function StaleNote({ + updatedAt, + failed, + hasData, +}: { + /** When the last live answer arrived (`usePolled`), or null if none has. */ + updatedAt: number | null; + /** The latest refresh failed. */ + failed: boolean; + /** The page has a list to show at all. */ + hasData: boolean; +}) { + if (!hasData) return null; + if (updatedAt === null) { + return ( + + showing the answer saved from your last visit, until a fresh one + arrives. + + ); + } + if (!failed) return null; + return ( + + showing the last answer, from . + + ); +} diff --git a/frontend/packages/swarm-ui/src/ui/polled/usePolled.ts b/frontend/packages/swarm-ui/src/ui/polled/usePolled.ts index cc07ca48e..ffb759508 100644 --- a/frontend/packages/swarm-ui/src/ui/polled/usePolled.ts +++ b/frontend/packages/swarm-ui/src/ui/polled/usePolled.ts @@ -1,4 +1,6 @@ // A resource refetched on a timer: `{ data, error, refreshing, refresh, setData }`. +// `updatedAt` is when the last live answer arrived, for saying how old a list +// is under a failed refresh (`StaleNote`). // `data` is `null` until the first answer (or, with a `cacheKey`, the saved one // of the last visit, which is shown at once and replaced by the fresh answer; // see `answer-cache.ts`); a failed fetch sets `error` and @@ -53,6 +55,9 @@ export function usePolled( ): { data: T | null; error: ProblemDetails | null; + /** When the last live answer arrived; null until one has (a saved answer + * from the last visit is not one). */ + updatedAt: number | null; refreshing: boolean; refresh: () => void; setData: (update: (prev: T | null) => T | null) => void; @@ -64,6 +69,7 @@ export function usePolled( cacheKey === undefined ? null : readAnswer(cacheKey), ); const [error, setError] = useState(null); + const [updatedAt, setUpdatedAt] = useState(null); const [refreshing, setRefreshing] = useState(false); const fetcherRef = useRef(fetcher); @@ -83,6 +89,7 @@ export function usePolled( } setData(next); setError(null); + setUpdatedAt(Date.now()); }, onError: (e) => setError(toProblem(e)), onBusy: (busy) => hold.busy(busy), @@ -99,5 +106,12 @@ export function usePolled( ); useRefreshInterval(intervalMs, () => poller.tick()); - return { data, error, refreshing, refresh: () => poller.refetch(), setData }; + return { + data, + error, + updatedAt, + refreshing, + refresh: () => poller.refetch(), + setData, + }; } diff --git a/frontend/packages/swarm-ui/test/create-agent-steps.test.mjs b/frontend/packages/swarm-ui/test/create-agent-steps.test.mjs index 67f2da36f..95bf8fe91 100644 --- a/frontend/packages/swarm-ui/test/create-agent-steps.test.mjs +++ b/frontend/packages/swarm-ui/test/create-agent-steps.test.mjs @@ -3,6 +3,7 @@ import assert from "node:assert/strict"; import { test } from "node:test"; import { + lastReachableStep, nameProblem, nextStep, previousStep, @@ -99,3 +100,16 @@ test("the summary lists what is sent and what stays at its default", () => { assert.equal(rows({ permissions: [] }).permissions, "none"); assert.equal(rows({ agentsMd: "x" }).instructions, "AGENTS.md, 1 word"); }); + +test("the tabs go forward as far as the operator has been, not past a bad step", () => { + // On the summary (4) having been there: every step is open. + assert.equal(lastReachableStep(4, -1, 4), 4); + // Back on the identity step (0) after reaching the summary: still open to 4. + assert.equal(lastReachableStep(4, -1, 0), 4); + // The name went bad (step 0): only the current step is open. + assert.equal(lastReachableStep(4, 0, 0), 0); + // A bad permissions step (2) stops the tabs there. + assert.equal(lastReachableStep(4, 2, 0), 2); + // Never behind the current step. + assert.equal(lastReachableStep(1, 0, 3), 3); +}); diff --git a/frontend/packages/swarm-ui/test/page-title.test.mjs b/frontend/packages/swarm-ui/test/page-title.test.mjs new file mode 100644 index 000000000..6c7d9939e --- /dev/null +++ b/frontend/packages/swarm-ui/test/page-title.test.mjs @@ -0,0 +1,28 @@ +// The title a page gives itself: set, change, clear, and who hears of it. +// Run by `npm test`. +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { + getPageTitle, + setPageTitle, + subscribePageTitle, +} from "../src/shell/page-title.ts"; + +test("a page sets its title and clears it again", () => { + setPageTitle("flow fan-out"); + assert.equal(getPageTitle(), "flow fan-out"); + setPageTitle(undefined); + assert.equal(getPageTitle(), undefined); +}); + +test("a subscriber hears of a change, not of the same title set again", () => { + let heard = 0; + const stop = subscribePageTitle(() => heard++); + setPageTitle("a"); + setPageTitle("a"); + setPageTitle("b"); + assert.equal(heard, 2); + stop(); + setPageTitle(undefined); + assert.equal(heard, 2); +});