hyperhive/frontend/packages/swarm-ui/src/pages/AgentsPage.tsx

// <AgentsPage> — the swarm's agent roster, merged with each agent's open
// config-PR status, swarm-wide health status, and declared wanted state
// in the same table. Three separate asks (a roster listing, a per-agent
// config-PR indicator, and per-agent status/liveness) that turned out to
// be one page: a roster with no per-row detail is thin, and neither a
// config-PR panel nor a status panel has anything to render against
// without a roster to embed in.
//
// One fetch, on a refresh-interval cadence like HivesPage: `GET
// /api/agents/status` — one row per roster agent (identity store is the
// roster, so a never-reported agent still gets a row), each already
// carrying its freshness/snapshot/config PR/wanted state. That merge
// used to be three separate fetches (`/api/agents`, `/api/config-prs`,
// `/api/agents/status`) joined client-side by name; per operator review
// feedback ("the view should be filled by a single backend call") the
// join moved server-side instead — see `swarm-controller/src/main.rs`'s
// `get_agents_status` handler for where `config_pr`/`wanted` get merged
// in and why that's the handler's job rather than
// `agent_status::AgentStatusReader`'s. No more per-page joining left to
// do here: the wire row *is* the table row.
//
// Owns the "+ agent" trigger too — the roster this populates is the
// natural home for the action that populates it; a separate top-level
// nav entry would be one click of indirection for no benefit. The form
// itself (`CreateAgentForm`) mounts inside a `Dialog` here rather than
// its own route.
//
// The "wanted" column is one `WantedMenu` badge+dropdown per row — see
// that component's own comment above `AgentsPage` for why.
import { useRef, useState } from "preact/hooks";
import type { ComponentChildren } from "preact";
import { ApiErrorPanel } from "@hive/shared/api-error-panel.js";
import { readApiError, type ProblemDetails } from "@hive/shared/api-error.js";
import { Badge, type BadgeTone } from "@hive/shared/badge.js";
import { Dropdown, type DropdownOption } from "@hive/shared/dropdown.js";
import { LinkIcon } from "@hive/shared/icons.js";
import { Button } from "../ui/button/Button.js";
import { ConfirmDialog } from "../ui/confirm-dialog/ConfirmDialog.js";
import { Dialog } from "../ui/dialog/Dialog.js";
import { Panel } from "../ui/panel/Panel.js";
import { RelativeTime } from "../ui/relative-time/RelativeTime.js";
import {
  RefreshIntervalPicker,
  useRefreshInterval,
  type RefreshIntervalMs,
} from "../ui/refresh-interval/RefreshInterval.js";
import { Table, type TableColumn } from "../ui/table/Table.js";
import { CreateAgentForm } from "./CreateAgentForm.js";
import { LinkMatrixAccountForm } from "./LinkMatrixAccountForm.js";

interface ConfigPrStatus {
  pr_number: number;
  html_url: string | null;
}

type Freshness = "fresh" | "stale" | "never_reported" | "unknown";

interface AgentStatusSnapshot {
  status_text: string | null;
  status_set_at: number | null;
  running: boolean;
}

// `"up"` / `"offline"` / `"destroyed"`, wire-spelled by
// `swarm_queue_client::wanted::AgentState::as_str` — kept as a bare
// `string | null` rather than a union, same reason
// `config_pr`'s shape isn't re-derived here: this page renders whatever
// the wire sends, it doesn't validate the enum client-side.
type Wanted = string | null;

// Mirrors `agent_status::AgentStatusRow` field-for-field — this *is* the
// table row now, not a shape assembled from it, so there's no separate
// join-result type to keep in sync with the wire contract by hand.
interface AgentRow {
  name: string;
  hive: string | null;
  freshness: Freshness;
  last_seen_unix: number | null;
  // `age_seconds` deliberately unused here, same reason as HivesPage:
  // `RelativeTime` recomputes age client-side from `last_seen_unix`
  // rather than rendering a once-computed-at-fetch value.
  snapshot: AgentStatusSnapshot | null;
  config_pr: ConfigPrStatus | null;
  wanted: Wanted;
}

// Same tone pairing as HivesPage — one freshness enum shared by both
// endpoints, so the same tone rule applies to both pages — but `unknown`'s
// label diverges deliberately: an agent outside the swarm-identity roster
// has a concrete next step (register it), while an unrecognized *hive* on
// HivesPage doesn't carry the same actionable meaning.
const FRESHNESS: Record<Freshness, { tone: BadgeTone; label: string }> = {
  fresh: { tone: "positive", label: "fresh" },
  stale: { tone: "warning", label: "stale" },
  never_reported: { tone: "neutral", label: "never reported" },
  // `unknown` means the agent reported into the KV bucket but isn't in
  // the swarm-identity roster — a real, distinct case ("hive-reported,
  // not yet in swarm level"), not just a fallback default, so it gets a
  // label that says what to do about it rather than reusing the enum
  // name as the label.
  unknown: { tone: "negative", label: "not in swarm identity" },
};

// The one thing that differs between the "offline" and "paused" confirm
// dialogs `confirmTarget` drives — everything else (button row, open/close
// wiring) is the shared `ConfirmDialog`.
const CONFIRM_COPY: Record<
  "offline" | "paused",
  {
    label: string;
    confirmLabel: string;
    message: (agentName: string) => ComponentChildren;
  }
> = {
  offline: {
    label: "stop agent",
    confirmLabel: "stop",
    message: (agentName) => (
      <p>
        Declare <strong>{agentName}</strong> offline? The hive brings its
        container down on its next reconcile sweep.
      </p>
    ),
  },
  paused: {
    label: "pause agent",
    confirmLabel: "pause",
    message: (agentName) => (
      <p>
        Declare <strong>{agentName}</strong> paused? Its container stays up —
        the web UI and MCP daemons keep running — but its turn loop parks on the
        hive's next reconcile sweep. Select "up" again to resume it.
      </p>
    ),
  },
};

// Same 30s default + same reasoning as HivesPage: no inputs on this page
// for a refresh to clobber, so the out-of-the-box behaviour should just
// solve staleness rather than require an opt-in every visit.
const DEFAULT_INTERVAL_MS: RefreshIntervalMs = 30_000;

// The "wanted" column's control: one badge showing the current
// declaration, opening a `Dropdown` with the four explicit states —
// replaces the old toggle-badge-plus-separate-destroy-badge pair.
// Explicit options also fix a real bug the toggle had: for an
// undeclared row, the toggle inferred a target as "the opposite of
// `snapshot.running`", so a click on an undeclared-but-running agent
// silently declared it *offline* rather than making its real state
// explicit — a dropdown just lets "up" be picked directly regardless
// of what's inferred, no flip-to-the-opposite-of-a-guess involved
// (mara: "when no state is declared, i want to set it to online").
// Presentational only, same split as `StatusChips`'s `Picker`/
// `StatusMenu`: the caller owns what each selection actually does.
//
// "paused" has no separate resume option here — selecting "up" from a
// paused row is the resume, same PUT either way (`declareState`'s
// backend counterpart, `hive-c0re`'s `decide_pause`, treats a declared
// `Up` with the marker still set as "clear it"). A dedicated "resume"
// entry would just be a second spelling of the option already above it.
function WantedMenu({
  row,
  pending,
  onSelectUp,
  onSelectOffline,
  onSelectPaused,
  onDestroy,
}: {
  row: AgentRow;
  pending: boolean;
  onSelectUp: (row: AgentRow) => void;
  onSelectOffline: (row: AgentRow) => void;
  onSelectPaused: (row: AgentRow) => void;
  onDestroy: (row: AgentRow) => void;
}) {
  const [open, setOpen] = useState(false);
  const anchorRef = useRef<HTMLDivElement>(null);
  const destroyed = row.wanted === "destroyed";
  const tone: BadgeTone =
    row.wanted === "up"
      ? "positive"
      : row.wanted === "paused"
        ? "warning"
        : destroyed
          ? "negative"
          : "neutral";
  const options: DropdownOption[] = [
    { value: "up", label: "up" },
    { value: "paused", label: "paused" },
    { value: "offline", label: "offline" },
    { value: "destroy", label: "destroy", danger: true },
  ];

  return (
    <div class="ui-dropdown-anchor" ref={anchorRef}>
      <Badge
        tone={tone}
        value={pending ? "…" : (row.wanted ?? "no declaration")}
        // `destroyed` blocks opening the menu at all — same UX-only
        // guard as before (real enforcement is server-side, see
        // `declareState`'s caller), just applied to the trigger instead
        // of a `disabled` toggle badge.
        onClick={row.hive && !destroyed ? () => setOpen((o) => !o) : undefined}
        expanded={open}
        disabled={pending || !row.hive || destroyed}
        title={
          destroyed
            ? `${row.name} is destroyed — redeploy via "+ agent" to bring it back`
            : row.hive
              ? `declare a new state for ${row.name}`
              : "no hive on record for this agent — nothing to declare against"
        }
      />
      <Dropdown
        open={open}
        options={options}
        activeValue={row.wanted ?? undefined}
        label={`declare ${row.name}`}
        onSelect={(value) => {
          setOpen(false);
          if (value === "up") onSelectUp(row);
          else if (value === "offline") onSelectOffline(row);
          else if (value === "paused") onSelectPaused(row);
          else onDestroy(row);
        }}
        onClose={() => setOpen(false)}
        anchorRef={anchorRef}
      />
    </div>
  );
}

export function AgentsPage() {
  const [rows, setRows] = useState<AgentRow[] | null>(null);
  const [error, setError] = useState<ProblemDetails | null>(null);
  const [intervalMs, setIntervalMs] =
    useState<RefreshIntervalMs>(DEFAULT_INTERVAL_MS);
  const [createOpen, setCreateOpen] = useState(false);
  // Per-agent, not one page-wide flag: one row's declare-in-flight
  // shouldn't disable every other row's button.
  const [pendingAgents, setPendingAgents] = useState<ReadonlySet<string>>(
    new Set(),
  );
  const [actionErrors, setActionErrors] = useState<
    ReadonlyMap<string, ProblemDetails>
  >(new Map());
  // The row pending destroy confirmation, `null` when the dialog is
  // closed — not a boolean, so the dialog can name the agent without a
  // second piece of state to keep in sync with it. Kept apart from
  // `confirmTarget` below rather than folded into it as a third state:
  // destroy is categorically different (irreversible, longer warning,
  // danger-styled), not one more case of the same "confirm before parking
  // a running agent" shape "offline"/"paused" share.
  const [destroyTarget, setDestroyTarget] = useState<AgentRow | null>(null);
  // "offline" and "paused" are the *same* confirm shape — same button
  // treatment, same "disruptive to a running turn loop, unlike up" reason
  // for needing a confirm at all — so one union state + one `ConfirmDialog`
  // covers both instead of two near-identical copies (argus, PR review: "a
  // shared confirm-dialog-body-generator would drop real line count").
  // `CONFIRM_COPY` below supplies the one thing that differs.
  const [confirmTarget, setConfirmTarget] = useState<{
    row: AgentRow;
    state: "offline" | "paused";
  } | null>(null);
  // The row currently showing the "link a matrix account" dialog — same
  // null-means-closed shape as `destroyTarget`/`stopTarget`, own piece of
  // state rather than folded into either since this dialog isn't a
  // confirmation of a `declareState` call, it's an unrelated action with
  // its own form (`LinkMatrixAccountForm`).
  const [matrixTarget, setMatrixTarget] = useState<AgentRow | null>(null);

  async function refresh() {
    const res = await fetch("/api/agents/status");
    if (!res.ok) {
      setError(await readApiError(res));
      return;
    }
    setRows((await res.json()) as AgentRow[]);
    // A refresh that succeeds clears a previous failure — otherwise a
    // transient error would sit on screen forever after the data itself
    // has recovered.
    setError(null);
  }

  useRefreshInterval(intervalMs, () => {
    refresh().catch((e: unknown) => setError({ detail: String(e) }));
  });

  // The one PUT every `WantedMenu` selection ends at, whether or not it
  // went through a `ConfirmDialog` first (`confirmStop`/`destroyAgent`
  // for "offline"/"destroy"; called directly for "up", which needs no
  // confirmation): "PUT a new `wanted` declaration, track per-agent
  // pending/error state, patch the response back into `rows`" is the
  // same shape regardless of target state or how the caller got here.
  async function declareState(row: AgentRow, target: string) {
    if (!row.hive) return;
    setPendingAgents((prev) => new Set(prev).add(row.name));
    setActionErrors((prev) => {
      const next = new Map(prev);
      next.delete(row.name);
      return next;
    });
    try {
      const res = await fetch(
        `/api/hives/${encodeURIComponent(row.hive)}/agents/${encodeURIComponent(row.name)}/state`,
        {
          method: "PUT",
          headers: { "content-type": "application/json" },
          body: JSON.stringify({ state: target }),
        },
      );
      if (!res.ok) {
        const problem = await readApiError(res);
        setActionErrors((prev) => new Map(prev).set(row.name, problem));
        return;
      }
      // The PUT response is the hive's whole declaration set (every
      // agent's `wanted` state) — same shape `GET /api/hives/{hive}/wanted`
      // returns — so patch just that field into the rows already on
      // screen rather than firing a second, full `/api/agents/status`
      // round-trip merely to learn one hive's `wanted` column changed.
      // Everything else on the grid (freshness, snapshot, config PR)
      // still catches up on the next interval-driven `refresh()`.
      const declared = (await res.json()) as { agent: string; state: string }[];
      setRows((prev) => {
        if (!prev) return prev;
        const byAgent = new Map(declared.map((d) => [d.agent, d.state]));
        return prev.map((r) =>
          r.hive === row.hive && byAgent.has(r.name)
            ? { ...r, wanted: byAgent.get(r.name) ?? r.wanted }
            : r,
        );
      });
    } catch (e: unknown) {
      setActionErrors((prev) =>
        new Map(prev).set(row.name, { detail: String(e) }),
      );
    } finally {
      setPendingAgents((prev) => {
        const next = new Set(prev);
        next.delete(row.name);
        return next;
      });
    }
  }

  // Fires from the `confirmTarget` confirm `Dialog` (covers both "offline"
  // and "paused" — see that state's own comment). Used to be a native
  // `window.confirm` for the "offline" case (stop is reversible, a later
  // start un-does it, so a lighter-weight prompt than destroy's felt
  // proportionate) — mara, reviewing the destroy confirm: use the shared
  // component everywhere we already confirm before acting, not just for
  // destroy. Once `ConfirmDialog` existed as a one-line-per-caller
  // component, the "native is lighter" argument no longer bought
  // consistency anything.
  async function confirmDeclare() {
    if (!confirmTarget) return;
    const { row, state } = confirmTarget;
    setConfirmTarget(null);
    await declareState(row, state);
  }

  // Fires from the `destroyTarget` confirm `Dialog`, never directly off
  // a row click — see `destroyTarget`/`WantedMenu`'s "destroy" option.
  // Unlike the "up"/"offline" directions, there's no "current state" to
  // read: destroy is a one-way declaration, not a flip.
  async function destroyAgent(row: AgentRow) {
    setDestroyTarget(null);
    await declareState(row, "destroyed");
  }

  const columns: TableColumn<AgentRow>[] = [
    {
      key: "name",
      header: "name",
      render: (a) => a.name,
      sortBy: (a) => a.name,
      filterValue: (a) => a.name,
    },
    {
      key: "hive",
      header: "hive",
      render: (a) => a.hive ?? "—",
      sortBy: (a) => a.hive ?? "",
      // "—" (not "") so the missing-hive option in the filter list reads
      // the same as the cell itself, rather than showing a blank choice.
      // Multiselect, not single-value `"select"` — an operator narrowing
      // to a handful of hives at once shouldn't need to filter one at a
      // time.
      filterValues: (a) => [a.hive ?? "—"],
      filterMode: "multiselect",
    },
    {
      key: "status",
      header: "status",
      // Technical freshness only — the agent's own free-text status
      // string used to be concatenated into this same badge, which
      // stuffed a full sentence into a pill meant for a short discrete
      // label and blew the row out (mara: "looks messy"). That string
      // now lives in its own "message" column below.
      sortBy: (a) => FRESHNESS[a.freshness].label,
      // Multiselect, same reasoning as the hive column above.
      filterValues: (a) => [FRESHNESS[a.freshness].label],
      filterMode: "multiselect",
      render: (a) => {
        const { tone, label } = FRESHNESS[a.freshness];
        return (
          <Badge
            tone={tone}
            title={
              a.freshness === "unknown"
                ? "reported by its hive but not registered in swarm-level identity — needs migration"
                : undefined
            }
            value={
              <>
                {label}
                {a.last_seen_unix !== null ? (
                  <>
                    {" "}
                    (<RelativeTime epochMs={a.last_seen_unix * 1000} />)
                  </>
                ) : null}
              </>
            }
          />
        );
      },
    },
    {
      key: "message",
      header: "message",
      cellClass: "ui-table-prose",
      // Plain text, not a Badge — the agent's own free-form status
      // sentence, as distinct from the technical freshness state in the
      // "status" column. A `running: false` snapshot always carries
      // `status_text: null` (the wire contract's own rule), so a stopped
      // agent just shows an em dash here rather than a stale message.
      render: (a) => a.snapshot?.status_text ?? "—",
      filterValue: (a) => a.snapshot?.status_text ?? "",
    },
    {
      key: "wanted",
      header: "wanted",
      // One `WantedMenu` (badge + dropdown, defined above) per row —
      // real per-badge logic lives there, this column just wires its
      // callbacks to the page's own state/handlers.
      sortBy: (a) => a.wanted ?? "",
      // Multiselect, same reasoning as the hive column above.
      filterValues: (a) => [a.wanted ?? "no declaration"],
      filterMode: "multiselect",
      render: (a) => {
        const err = actionErrors.get(a.name);
        return (
          <>
            <WantedMenu
              row={a}
              pending={pendingAgents.has(a.name)}
              onSelectUp={(row) => void declareState(row, "up")}
              onSelectOffline={(row) =>
                setConfirmTarget({ row, state: "offline" })
              }
              onSelectPaused={(row) =>
                setConfirmTarget({ row, state: "paused" })
              }
              onDestroy={setDestroyTarget}
            />
            {err ? (
              <Badge
                tone="negative"
                value="failed"
                title={err.detail ?? "the declaration failed"}
              />
            ) : null}
          </>
        );
      },
    },
    {
      key: "matrix",
      header: "matrix",
      // Icon-only trigger, quiet variant (no permanent pill fill) — same
      // "chrome, not a status chip" reasoning as `LinksMenu`/`SettingsMenu`'s
      // own `Badge` triggers (see `@hive/shared/badge/Badge.tsx`'s
      // `BadgeVariant` doc). Disabled with no hive on record, same guard
      // `WantedMenu` uses — the endpoint is hive-scoped, there's nothing
      // to PUT against without one.
      render: (a) => (
        <Badge
          variant="quiet"
          icon={<LinkIcon />}
          value="link account"
          onClick={a.hive ? () => setMatrixTarget(a) : undefined}
          disabled={!a.hive}
          title={
            a.hive
              ? `link a matrix account to ${a.name}`
              : "no hive on record for this agent — nothing to link against"
          }
        />
      ),
    },
    {
      key: "config-pr",
      header: "config PR",
      sortBy: (a) => a.config_pr?.pr_number ?? 0,
      filterValue: (a) => (a.config_pr ? `#${a.config_pr.pr_number}` : ""),
      render: (a) =>
        a.config_pr ? (
          <Badge
            tone="warning"
            value={
              a.config_pr.html_url ? (
                <a href={a.config_pr.html_url} target="_blank" rel="noreferrer">
                  #{a.config_pr.pr_number}
                </a>
              ) : (
                `#${a.config_pr.pr_number}`
              )
            }
          />
        ) : (
          "—"
        ),
    },
  ];

  return (
    <Panel
      title="agents"
      icon="👥"
      actions={
        <>
          <Button variant="primary" onClick={() => setCreateOpen(true)}>
            + agent
          </Button>
          <RefreshIntervalPicker
            id="agents-refresh"
            value={intervalMs}
            onChange={setIntervalMs}
          />
        </>
      }
    >
      {error ? (
        <ApiErrorPanel
          context="failed to load the agent roster"
          problem={error}
        />
      ) : null}
      {!error && rows === null ? <p>loading…</p> : null}
      {rows ? (
        <Table
          columns={columns}
          rows={rows}
          rowKey={(a) => a.name}
          emptyMessage="no agents yet — the swarm-wide identity store has no agents registered on any hive"
          storageKey="swarm-ui:agents:table-filters"
        />
      ) : null}
      <Dialog
        open={createOpen}
        onClose={() => setCreateOpen(false)}
        label="create agent"
      >
        <CreateAgentForm />
      </Dialog>
      <Dialog
        open={matrixTarget !== null}
        onClose={() => setMatrixTarget(null)}
        label="link a matrix account"
      >
        {/* `matrixTarget.hive` is non-null here — the trigger badge above
            is disabled without one, so this can only open with a real
            hive to PUT against. */}
        {matrixTarget?.hive ? (
          <LinkMatrixAccountForm
            hive={matrixTarget.hive}
            agent={matrixTarget.name}
          />
        ) : null}
      </Dialog>
      <ConfirmDialog
        open={confirmTarget !== null}
        label={confirmTarget ? CONFIRM_COPY[confirmTarget.state].label : ""}
        onCancel={() => setConfirmTarget(null)}
        onConfirm={() => void confirmDeclare()}
        confirmLabel={
          confirmTarget
            ? CONFIRM_COPY[confirmTarget.state].confirmLabel
            : undefined
        }
      >
        {confirmTarget
          ? CONFIRM_COPY[confirmTarget.state].message(confirmTarget.row.name)
          : null}
      </ConfirmDialog>
      <ConfirmDialog
        open={destroyTarget !== null}
        label="destroy agent"
        onCancel={() => setDestroyTarget(null)}
        onConfirm={() => destroyTarget && void destroyAgent(destroyTarget)}
        confirmLabel="destroy"
      >
        {destroyTarget ? (
          <p>
            Destroy <strong>{destroyTarget.name}</strong>? The hive tears its
            container down on its next reconcile sweep. This is not reversible
            from here — bringing it back means redeploying via "+ agent", which
            reuses the agent's existing identity, config repo, and forge
            collaborator access rather than starting over.
          </p>
        ) : null}
      </ConfirmDialog>
    </Panel>
  );
}