feat(agent+ui): resource metrics in heartbeat — CPU/mem/disk health bars

Migration (0006):
  • 3 nullable float columns added to agents table:
    cpu_percent, memory_percent, disk_percent

Server:
  • HeartbeatRequest accepts optional cpu_percent, memory_percent, disk_percent
  • Heartbeat handler persists provided (non-None) metric values to the agent
    record; omitted / None fields leave existing values unchanged
  • AgentOut exposes the three metric fields (None when not yet reported)

Agent:
  • _collect_resource_metrics() — uses psutil when installed, falls back
    gracefully to None values; any psutil error is caught
  • _heartbeat_loop: calls _collect_resource_metrics via asyncio.to_thread
    and merges the result into the heartbeat POST body

UI (Agents.tsx):
  • MetricBar component: compact horizontal bar (green/yellow/red based on
    threshold) with a percentage label
  • CPU / Memory / Disk columns shown when at least one agent has reported
    metrics; hidden otherwise (clean view for fresh deployments)
  • Last-heartbeat timestamp replaces the stale 'last_seen' field
  • agents.ts interface updated with cpu/memory/disk_percent and last_heartbeat

Tests:
  • 10 new tests: _collect_resource_metrics (4), heartbeat stores/skips metrics
    (3), AgentOut schema (3)
  • test_agent_auto_update.py: patched _collect_resource_metrics to avoid
    asyncio.to_thread blocking the single-yield test loop
  • 611 total tests pass

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AbfhpQR6qzZAXcTacEcZvn

Author: claude

agent/core.py

@@ -320,9 +320,10 @@ async def _heartbeat_loop(self) -> None:
 
             try:
                 async with self._build_client() as client:
+                    metrics = await asyncio.to_thread(_collect_resource_metrics)
                     resp = await client.post(
                         f"/api/v1/agents/{cfg.agent_id}/heartbeat",
-                        json={"agent_version": _agent_version()},
+                        json={"agent_version": _agent_version(), **metrics},
                     )
                     resp.raise_for_status()
                     consecutive_failures = 0
@@ -586,3 +587,20 @@ def _agent_version() -> str:
         return version("discoverykastle-agent")
     except Exception:
         return "dev"
+
+
+def _collect_resource_metrics() -> dict[str, float | None]:
+    """
+    Return current CPU, memory, and disk utilisation as percentages.
+
+    Uses ``psutil`` when available; falls back to ``None`` values so that
+    agents without psutil still send valid heartbeats.
+    """
+    try:
+        import psutil
+        cpu = psutil.cpu_percent(interval=0.1)
+        mem = psutil.virtual_memory().percent
+        disk = psutil.disk_usage("/").percent
+        return {"cpu_percent": cpu, "memory_percent": mem, "disk_percent": disk}
+    except Exception:
+        return {"cpu_percent": None, "memory_percent": None, "disk_percent": None}

alembic/versions/0006_agent_resource_metrics.py

@@ -0,0 +1,35 @@
+"""Add resource metric columns to agents table
+
+Revision ID: 0006
+Revises: 0005
+Create Date: 2026-09-06 00:00:00.000000
+
+Adds three nullable float columns to the ``agents`` table so that resource
+metrics reported in heartbeats (CPU %, memory %, disk %) can be stored and
+exposed in the API.  All columns are nullable — agents that do not report
+metrics (older versions, or psutil not installed) leave them NULL.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0006"
+down_revision: Union[str, None] = "0005"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("agents", sa.Column("cpu_percent", sa.Float, nullable=True))
+    op.add_column("agents", sa.Column("memory_percent", sa.Float, nullable=True))
+    op.add_column("agents", sa.Column("disk_percent", sa.Float, nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("agents", "disk_percent")
+    op.drop_column("agents", "memory_percent")
+    op.drop_column("agents", "cpu_percent")

server/api/agents.py

@@ -69,6 +69,10 @@ class AgentOut(BaseModel):
     status: str
     authorized_cidrs: list[str]
     last_heartbeat: datetime | None
+    # Resource metrics — None when the agent has not reported them yet
+    cpu_percent: float | None = None
+    memory_percent: float | None = None
+    disk_percent: float | None = None
     created_at: datetime
 
 
@@ -216,8 +220,13 @@ class CertRenewResponse(BaseModel):
 
 
 class HeartbeatRequest(BaseModel):
-    """Optional body sent by the agent with its current version."""
+    """Optional body sent by the agent with its current version and resource metrics."""
     agent_version: str | None = None
+    # Resource utilisation — collected via psutil on the agent host.
+    # Values are percentages (0.0–100.0).  Omitted when psutil is unavailable.
+    cpu_percent: float | None = None
+    memory_percent: float | None = None
+    disk_percent: float | None = None
 
 
 @router.post("/{agent_id}/heartbeat", response_model=HeartbeatResponse)
@@ -241,6 +250,14 @@ async def heartbeat(
     if body.agent_version and body.agent_version != agent.version:
         agent.version = body.agent_version
 
+    # Persist resource metrics when provided.
+    if body.cpu_percent is not None:
+        agent.cpu_percent = body.cpu_percent
+    if body.memory_percent is not None:
+        agent.memory_percent = body.memory_percent
+    if body.disk_percent is not None:
+        agent.disk_percent = body.disk_percent
+
     agent.last_heartbeat = datetime.utcnow()
     agent.status = "online"
     await db.commit()

server/models/agent.py

@@ -17,6 +17,12 @@ class Agent(Base):
     status: Mapped[str] = mapped_column(String(20), nullable=False, default="offline")
     authorized_cidrs: Mapped[list[str]] = mapped_column(ARRAY(String), default=list)
     last_heartbeat: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    # Resource metrics — populated from heartbeat payloads when psutil is
+    # available on the agent host.  Nullable so older agent versions that
+    # do not send metrics don't fail.
+    cpu_percent: Mapped[float | None] = mapped_column(nullable=True)
+    memory_percent: Mapped[float | None] = mapped_column(nullable=True)
+    disk_percent: Mapped[float | None] = mapped_column(nullable=True)
     created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
     updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
 

server/static/ui/assets/index-C5c7_b5A.css

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Discoverykastle</title>
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-    <script type="module" crossorigin src="/assets/index-pILZ0F_3.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-C5c7_b5A.css">
+    <script type="module" crossorigin src="/assets/index-DF9VHKCk.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CTgcwoO2.css">
   </head>
   <body class="bg-surface-0 text-gray-100 antialiased">
     <div id="root"></div>

server/static/ui/assets/index-CTgcwoO2.css

@@ -80,15 +80,22 @@ async def _fake_post(url, **kwargs):
         mock_client.__aexit__ = AsyncMock(return_value=False)
         mock_client.post = AsyncMock(side_effect=_fake_post)
 
+        # Stub out resource-metric collection (runs in a thread) so it
+        # resolves instantly and the heartbeat POST is reached before the
+        # task is cancelled.
+        _empty_metrics = {"cpu_percent": None, "memory_percent": None, "disk_percent": None}
         with patch.object(agent, "_build_client", return_value=mock_client):
             with patch("agent.core._agent_version", return_value="0.1.0"):
-                loop_task = asyncio.create_task(agent._heartbeat_loop())
-                await asyncio.sleep(0)
-                loop_task.cancel()
-                try:
-                    await loop_task
-                except asyncio.CancelledError:
-                    pass
+                with patch("agent.core._collect_resource_metrics", return_value=_empty_metrics):
+                    loop_task = asyncio.create_task(agent._heartbeat_loop())
+                    await asyncio.sleep(0)   # cert-renewal noop
+                    await asyncio.sleep(0)   # to_thread for metrics
+                    await asyncio.sleep(0)   # POST
+                    loop_task.cancel()
+                    try:
+                        await loop_task
+                    except asyncio.CancelledError:
+                        pass
 
         assert len(posted_bodies) >= 1
         assert posted_bodies[0].get("agent_version") == "0.1.0"