agentmon 0.1.0

data/lib/agentmon/ui/theme.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# The dashboard's look and the terminal window title.
+#
+# Theme (r2ui's `theme`, lipgloss colours): panel titles and the focused border in agentmon's
+# orange accent, which also draws session sparklines and the active scope ("[Agents]"); memory
+# pressure (gauges, percent cells) goes green under 70%, amber, then red from 90%.
+#
+# Window title, kept current as sessions start and end and pressure moves:
+#
+#   agentmon · 3 sessions · 42% pressure
+#   agentmon · 1 session                    (pressure left out until memory data is available)
+module Agentmon
+  module UI
+    # The title text for a Reading (nil before the first one).
+    module ThemeTitle
+      ACCENT = "#D97757"
+
+      module_function
+
+      def title(reading)
+        parts = ["agentmon"]
+        return parts.first unless reading
+
+        alive = (reading[:session_ledger] || []).count { |s| s.ended_at.nil? }
+        parts << "#{alive} #{alive == 1 ? "session" : "sessions"}"
+        pressure = reading[:memory]&.pressure
+        parts << "#{pressure.round}% pressure" if pressure
+        parts.join(" · ")
+      end
+    end
+  end
+
+  dashboard do |engine|
+    theme do
+      title foreground: UI::ThemeTitle::ACCENT, bold: true
+      focus foreground: UI::ThemeTitle::ACCENT
+      accent foreground: UI::ThemeTitle::ACCENT
+      selected reverse: true, foreground: UI::ThemeTitle::ACCENT
+      ok foreground: "#5FAF5F"
+      warn foreground: "#E5A50A"
+      alert foreground: "#E5484D", bold: true
+    end
+
+    # Runs after every update; reads the latest reading without sampling (the panels' feeds keep it
+    # fresh), so a keypress never waits on `ps`.
+    window_title { UI::ThemeTitle.title(engine.current(max_age: Float::INFINITY)) }
+  end
+end

data/lib/agentmon/ui.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Agentmon
+  # Builds the r2ui dashboard from the registered pieces: each resource (its definition, then its
+  # extensions), the dashboard-level blocks, then the rows with their panels in order. Every block
+  # gets the Engine, so sources read `engine.current[...]`.
+  #
+  #   Agentmon::UI.install(engine:)            # into R2UI.registry, as the :agentmon dashboard
+  #   R2UI.snapshot(:agentmon, width: 140, height: 40)
+  module UI
+    DASHBOARD = :agentmon
+    # The panel that has key focus when the dashboard opens.
+    FOCUS = :process
+
+    module_function
+
+    # `view:` (a registered Agentmon.view name) builds the dashboard from that view's rows instead
+    # of the registry layout (docs/views.md); resources then get the views' decorations.
+    def install(engine:, view: nil, registry: Agentmon.registry, into: R2UI.registry)
+      spec = view && (registry[:view, view] or raise Error, "no layout #{view} (#{layouts(registry).join(", ")})")
+      Views.installing = spec
+      registry.resources.each do |name, blocks|
+        into.add_resource(R2UI::DSL::Resource.build(name) { blocks.each { |b| instance_exec(engine, &b) } })
+      end
+      if spec
+        into.add_resource(Views.signals_resource(engine))
+        into.add_dashboard(Views.dashboard(spec, engine, registry))
+      else
+        into.add_dashboard(build_dashboard(engine, registry))
+      end
+    ensure
+      Views.installing = nil
+    end
+
+    # The registered view names, for --layout.
+    def layouts(registry = Agentmon.registry) = registry.all(:view).map(&:name)
+
+    def build_dashboard(engine, registry)
+      layout = registry.layout
+      extras = registry.dashboard_blocks
+      R2UI::DSL::Dashboard.build(DASHBOARD) do
+        title "agentmon"
+        extras.each { |b| instance_exec(engine, &b) }
+        layout.each do |spec, panels|
+          row(height: spec.height) do
+            panels.each do |p|
+              items = p.block && proc { instance_exec(engine, &p.block) }
+              panel(p.name, resource: p.resource, span: p.span, title: p.title, **p.options, &items)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  # A broken probe, metric or recorder shows on the left of the status bar ("⚠ metric memory:
+  # NoMethodError: ..."), instead of the table's sort line, until it recovers. r2ui's `status` hook
+  # is process-wide, so it checks that the agentmon dashboard is the one drawing.
+  R2UI.extension :agentmon_errors do
+    status do
+      problems = dashboard.name == UI::DASHBOARD ? Agentmon.engine_errors : {}
+      (name, message = problems.first) && "⚠ #{name}: #{message}#{" (+#{problems.size - 1} more)" if problems.size > 1}"
+    end
+  end
+
+  # The dashboard opens with keys on the Processes panel, whatever panels come before it (r2ui
+  # otherwise focuses the first panel with a table). Runs in App.new, so snapshots see it too.
+  R2UI.extension :agentmon_focus do
+    setup do
+      next unless dashboard.name == UI::DASHBOARD
+
+      panel = dashboard.panels.find { |p| p.name == UI::FOCUS }
+      app.focus = panel if panel
+    end
+  end
+
+  # The rows panels go in. Stories add panels to these (or register rows of their own).
+  row :top, order: 10, height: 14
+  row :main, order: 100
+end

data/lib/agentmon/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Agentmon
+  VERSION = "0.1.0"
+end

data/lib/agentmon/views/dense.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+# dense: htop-like, sessions first (docs/views.md). Home is the machine strip, every agent session
+# (by name when Claude Code or Codex knows one) with its CPU, footprint, disk and network, and all
+# agents together; Enter on a session drills into it (its CPU, memory and network strip, its
+# processes, connections and the process detail; Escape returns). Its real home frame, from
+# `COLUMNS=100 LINES=50 bundle exec exe/agentmon --layout dense | cat` (one sample, so sparklines
+# and areas are still empty and network rates still settling):
+#
+# ╭─ CPU ──────────────────────────────────╮╭─ Memory ─────────────────╮╭─ I/O ──────────────────────╮
+# │CPU  ⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀ 38.2%││used     ⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀   25G││net in  ⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀ 843B/s│
+# │user ⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀ 25.3%││pressure ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣤ 48.0%││net out ⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀ 1.1K/s│
+# │load 1m         5.5  load 5m         6.2││swap     ⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀  255M││disk rd ⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀   0B/s│
+# │load 15m        6.0  cores            10││compr    ⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀   11G││disk wr ⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀ 209K/s│
+# ╰────────────────────────────────────────╯╰──────────────────────────╯╰────────────────────────────╯
+# ╭─ Sessions ─[Live] All ───────────────────────────────────────────────────────────────────────────╮
+# │ Session                  Procs          CPU▼  Footprint     Read    Write   Net in        Net out│
+# │ Claude 21354                46 ⠀⠀⠀⠀⢀   41.1%       3.8G     0B/s     0B/s     0B/s ⠀⠀⠀⠀⢀     0B/s│
+# │ Agentmon r2ui…               5 ⠀⠀⠀⠀⢀   13.7%       372M     0B/s     0B/s     0B/s ⠀⠀⠀⠀⢀     0B/s│
+# │ ChatGPT 2388                18 ⠀⠀⠀⠀⢀    9.2%       3.3G     0B/s     0B/s     0B/s ⠀⠀⠀⠀⢀     0B/s│
+# │ Project history…             1 ⠀⠀⠀⠀⢀    0.4%       285M     0B/s     0B/s          ⠀⠀⠀⠀⢀         │
+# │ EPK component review…        1 ⠀⠀⠀⠀⢀    0.2%       262M     0B/s     0B/s          ⠀⠀⠀⠀⢀         │
+# │ Weekly session themes…       1 ⠀⠀⠀⠀⢀    0.2%       181M     0B/s     0B/s     0B/s ⠀⠀⠀⠀⢀     0B/s│
+# │ Mods in Desktop vs…          1 ⠀⠀⠀⠀⢀    0.1%       226M     0B/s     0B/s          ⠀⠀⠀⠀⢀         │
+# │ Set up a Homebrew tap…       1 ⠀⠀⠀⠀⢀    0.1%       200M     0B/s     0B/s          ⠀⠀⠀⠀⢀         │
+# │ Build Magrathea local…      25 ⠀⠀⠀⠀⢀    0.0%      1022M     0B/s     0B/s     0B/s ⠀⠀⠀⠀⢀     0B/s│
+# │ codex 3064 · Resources       4 ⠀⠀⠀⠀⢀    0.0%        76M     0B/s     0B/s     0B/s ⠀⠀⠀⠀⢀     0B/s│
+# │                                                                                                  │
+#   ... 19 more empty table lines ...
+# ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+# ╭─ All agents ───────────────────────────────────╮╭─ Agents network ───────────────────────────────╮
+# │procs               103  resident           9.6G││hosts                19  conns                65│
+# │CPU                                         6.5%││net in                                      0B/s│
+# │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀││⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│
+# │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀││⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│
+# │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀││⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│
+# │footprint                                   9.6G││net out                                     0B/s│
+# │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸││⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│
+# │⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸││⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀│
+# ╰────────────────────────────────────────────────╯╰────────────────────────────────────────────────╯
+#  sessions · ⏎ open a session
+#
+# Drilled into "Agentmon r2ui integration" (a pty at 100×50: `/` integration, Enter). The Memory
+# panel's RAM meter is the machine (25G of 32G used) with this session's footprint as the accent
+# slice at the left, the rest of used memory dim and free memory empty:
+#
+# ╭─ CPU ─────────────────────────╮╭─ Memory ──────────────────────╮╭─ Network ──────────────────────╮
+# │CPU     ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀ 0.2%││RAM ▕▏████▌ ▏ 324M 1% · 25G/32G││net in  ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣸⣄⣀⣀ 0B/s│
+# │disk rd ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀ 0B/s││pressure                  47.0%││net out ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣇⣀⣀ 0B/s│
+# │disk wr ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀ 0B/s││resident                   439M││received                    1.1K│
+# │procs                         3││wired                        0B││sent                         51K│
+# │cores                        10││growth                  +9.6K/s││hosts                          2│
+# ╰───────────────────────────────╯╰───────────────────────────────╯╰────────────────────────────────╯
+# ╭─ Processes ─[Agents] All  Busy  Heavy  Writing  Waiting ─────────────────────────────────────────╮
+# │      Pid Name                      CPU▼  Footprint   Wait     Read    Write   Net in  Net out    │
+# │    22602 claude                    1.6%       321M   1.6%     0B/s     0B/s     0B/s     0B/s    │
+# │▴    6766 sleep                     0.0%       832K   0.0%     0B/s     0B/s     0B/s     0B/s    │
+# │▾    6543 zsh                       0.0%       2.5M   0.0%     0B/s     0B/s     0B/s     0B/s    │
+# │                                                                                                  │
+#   ... 19 more empty table lines ...
+# ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+# ╭─ Connections ────────────────────────────────────────────────────────────────────────────────────╮
+# │ Process            Remote                         State             In     Out▼     Recv     Sent│
+# │ claude 22602       160.79.104.10:443              Established     0B/s     0B/s      39K     2.9M│
+# │ claude 22602       160.79.104.10:443              Established     0B/s     0B/s     918K     4.5M│
+# │ claude 22602       160.79.104.10:443              Established     0B/s     0B/s     234K     540K│
+# │ claude 22602       ….bc.googleusercontent.com:443 Established     0B/s     0B/s      26K     8.3M│
+# │ claude 22602       160.79.104.10:443              Established     0B/s     0B/s      13K      25K│
+# │ claude 22602       160.79.104.10:443              Established     0B/s     0B/s     3.2K     4.8K│
+# ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+# ╭─ Detail ─────────────────────────────────────────────────────────────────────────────────────────╮
+# │claude  pid 22602                                                                                 │
+# │Command    /Users/ryan…          Resident   435M                  Started    3h 2m ago            │
+# │Directory  ~/The Source…         Peak       368M                  Open files 21                   │
+# │Session    Agentmon r2ui…        CPU time   4m 30s                Threads    24 (0 running)       │
+# │Footprint  321M                  Written    109M                  CPU wait   1.6% now, 3m 23s…    │
+# ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+#  ▸ Agentmon r2ui integration · claude 22602 · agentmon · busy · esc back to sessions
+#
+# Sessions has no Age column, and its label (the session's name first) is 23 wide with Procs at
+# 5: one cell more pushes Write off at 100 columns. The drilled-in Processes table leaves the sort
+# sparkline off so all nine columns fit.
+module Agentmon
+  view :dense, title: "agentmon" do
+    # Home: the machine strip, every agent session with its breakdown, all agents together.
+    row height: 6 do
+      panel :cpu, title: "CPU", span: 3 do
+        spark "system.cpu"
+        spark "system.user"
+        stat "system.load1", "system.load5", "system.load15", "system.ncpu", columns: 2
+      end
+      panel :memory, title: "Memory", span: 2 do
+        spark "memory.used"
+        spark "memory.pressure"
+        spark "memory.swap_used"
+        spark "memory.compressed", label: "compr"
+      end
+      panel :io, title: "I/O", span: 2 do
+        spark "system.net_in_rate", label: "net in"
+        spark "system.net_out_rate", label: "net out"
+        spark "system.disk_read_rate", label: "disk rd"
+        spark "system.disk_write_rate", label: "disk wr"
+      end
+    end
+    row do
+      top :session, title: "Sessions", by: :cpu, spark: %i[cpu net_out_rate],
+                    columns: %i[label processes cpu footprint read_rate write_rate net_in_rate net_out_rate],
+                    widths: { label: 23, processes: 5 }
+    end
+    row height: 10 do
+      panel :agents, title: "All agents" do
+        stat "focus.processes", "focus.resident", columns: 2
+        trend "focus.cpu", "focus.footprint", height: nil
+      end
+      panel :agents_io, title: "Agents network" do
+        stat "focus.remote_hosts", "focus.connections", columns: 2
+        trend "focus.net_in_rate", "focus.net_out_rate", height: nil
+      end
+    end
+
+    # Drilled into one session (Enter on Sessions, F on a process; Escape returns).
+    focused do
+      row height: 7 do
+        panel :s_cpu, title: "CPU" do
+          spark "focus.cpu"
+          spark "focus.read_rate", label: "disk rd"
+          spark "focus.write_rate", label: "disk wr"
+          stat "focus.processes", "system.ncpu", columns: 2
+        end
+        panel :s_memory, title: "Memory" do
+          # The machine's RAM with the session as the accent slice; pressure as a stat (a second
+          # meter's "pressure" label would leave the RAM bar under 6 cells at 100 columns).
+          meter "memory.used", part: "focus.footprint", label: "RAM"
+          stat "memory.pressure", "focus.resident", "focus.wired", "focus.growth_rate", "focus.pagein_rate",
+               columns: 2
+        end
+        panel :s_net, title: "Network" do
+          spark "focus.net_in_rate"
+          spark "focus.net_out_rate"
+          stat "focus.bytes_in", "focus.bytes_out", "focus.remote_hosts", "focus.connections", columns: 2
+        end
+      end
+      row do
+        top :process, title: "Processes", by: :cpu, spark: false,
+                      columns: %i[pid name cpu footprint run_wait read_rate write_rate net_in_rate net_out_rate],
+                      widths: { name: 22 }
+      end
+      row height: 9 do
+        top :connection, title: "Connections", by: :out_rate, spark: false, widths: { process: 18 },
+                         columns: %i[process protocol remote_text state in_rate out_rate bytes_in bytes_out]
+      end
+      row height: 7 do
+        detail :process, columns: 3
+      end
+    end
+  end
+end

data/lib/agentmon/views/history.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Agentmon
+  module Views
+    # The last CAPACITY values of every signal a view draws (docs/views.md, "History"), appended
+    # once per Reading: `record` ignores a second call with the same `at` for a key, so a view
+    # drawn many times between samples (animation frames) appends each sample once.
+    #
+    #   history.record("memory.used", reading.at, value)
+    #   history["memory.used"]   # => [..., 23.1e9], oldest first (frozen)
+    #
+    # Unknown (nil) values are not appended, but their `at` still counts as seen. Meant for one
+    # drawing thread: no lock.
+    class History
+      CAPACITY = 120 # four minutes at 2 s
+
+      attr_reader :capacity
+
+      def initialize(capacity: CAPACITY)
+        raise ArgumentError, "capacity must be a positive Integer" unless capacity.is_a?(Integer) && capacity.positive?
+
+        @capacity = capacity
+        @series = {}
+        @last_at = {}
+      end
+
+      # Appends value.to_f to key's series unless `at` was already recorded for it; returns the
+      # series (frozen).
+      def record(key, at, value)
+        if !@last_at.key?(key) || @last_at[key] != at
+          @last_at[key] = at
+          append(key, value.to_f) unless value.nil?
+        end
+        self[key]
+      end
+
+      # The series for `key`, oldest first: a frozen Array, [] when unknown.
+      def [](key) = @series.fetch(key) { EMPTY }
+
+      def keys = @last_at.keys
+
+      def forget(key)
+        @last_at.delete(key)
+        @series.delete(key)
+        nil
+      end
+
+      EMPTY = [].freeze
+      private_constant :EMPTY
+
+      private
+
+      # Keeps each stored series frozen: a new Array per append, so a series handed out earlier
+      # never changes under its holder.
+      def append(key, value)
+        series = [*@series[key], value]
+        series.shift(series.size - capacity) if series.size > capacity
+        @series[key] = series.freeze
+      end
+    end
+  end
+end

data/lib/agentmon/views/signals.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+module Agentmon
+  module Views
+    # A named number on the machine with a unit (docs/views.md, "Vocabulary"): "system.cpu" is
+    # reading[:system].cpu. `max` is its natural maximum (percent: 100), `of` another signal's name
+    # that is its whole ("memory.used" of "memory.total"). Either may be nil.
+    Signal = Data.define(:name, :metric, :member, :label, :unit, :max, :of)
+
+    # Signals: parse a name into a Signal (defaults, then inference from the member name, then
+    # overrides), read its value from a Reading (nil is unknown, never 0) and format it.
+    #
+    #   s = Signals.parse("memory.used")      # label "used", unit :bytes, of "memory.total"
+    #   Signals.value(s, reading)             # => 23.1e9, or nil
+    #   Signals.fraction(s, reading)          # => 0.71 (value / total, or / max), or nil
+    #   Signals.format(Signals.value(s, reading), s.unit) # => "21G"
+    #
+    # The virtual metric :focus is the focused session, else every agent session together
+    # (Signals::Focus.value).
+    module Signals
+      PART = /\A[a-z_][a-z0-9_]*\z/
+      EVENT_STEMS = %w[pagein fault cow_fault context_switch].freeze
+      PERCENT_MEMBERS = %w[cpu pressure share user system run_wait].freeze
+      INTEGER_MEMBERS = %w[processes threads ncpu count].freeze
+
+      def self.entry(label, unit, max: nil, of: nil) = { label:, unit:, max:, of: }.freeze
+      private_class_method :entry
+
+      DEFAULTS = {
+        "system.cpu" => entry("CPU", :percent, max: 100),
+        "system.user" => entry("user", :percent, max: 100),
+        "system.system" => entry("system", :percent, max: 100),
+        "system.ncpu" => entry("cores", :integer),
+        "system.load1" => entry("load 1m", :number),
+        "system.load5" => entry("load 5m", :number),
+        "system.load15" => entry("load 15m", :number),
+        "system.net_in_rate" => entry("net in", :bytes_per_sec),
+        "system.net_out_rate" => entry("net out", :bytes_per_sec),
+        "system.disk_read_rate" => entry("disk read", :bytes_per_sec),
+        "system.disk_write_rate" => entry("disk write", :bytes_per_sec),
+        "memory.used" => entry("used", :bytes, of: "memory.total"),
+        "memory.total" => entry("total", :bytes),
+        "memory.app" => entry("app", :bytes),
+        "memory.wired" => entry("wired", :bytes),
+        "memory.compressed" => entry("compressed", :bytes),
+        "memory.cached" => entry("cached", :bytes),
+        "memory.free" => entry("free", :bytes),
+        "memory.swap_used" => entry("swap", :bytes, of: "memory.swap_total"),
+        "memory.swap_total" => entry("swap total", :bytes),
+        "memory.compression_ratio" => entry("ratio", :ratio),
+        "memory.pressure" => entry("pressure", :percent, max: 100),
+        "memory.swapin_rate" => entry("swap in", :bytes_per_sec),
+        "memory.swapout_rate" => entry("swap out", :bytes_per_sec),
+        "memory.compression_rate" => entry("compress", :bytes_per_sec),
+        "memory.decompression_rate" => entry("decompress", :bytes_per_sec),
+        "focus.cpu" => entry("CPU", :percent, max: 100),
+        "focus.footprint" => entry("footprint", :bytes, of: "memory.used"),
+        "focus.resident" => entry("resident", :bytes),
+        "focus.wired" => entry("wired", :bytes),
+        "focus.peak_footprint" => entry("peak", :bytes),
+        "focus.growth_rate" => entry("growth", :signed_bytes_per_sec),
+        "focus.pagein_rate" => entry("pageins", :per_sec),
+        "focus.processes" => entry("procs", :integer),
+        "focus.read_rate" => entry("read", :bytes_per_sec),
+        "focus.write_rate" => entry("write", :bytes_per_sec),
+        "focus.net_in_rate" => entry("net in", :bytes_per_sec),
+        "focus.net_out_rate" => entry("net out", :bytes_per_sec),
+        "focus.bytes_in" => entry("received", :bytes),
+        "focus.bytes_out" => entry("sent", :bytes),
+        "focus.connections" => entry("conns", :integer),
+        "focus.remote_hosts" => entry("hosts", :integer)
+      }.freeze
+
+      module_function
+
+      # A Signal for "metric.member"; ArgumentError when the name isn't one.
+      def parse(name, label: nil, unit: nil, max: nil, of: nil)
+        name = name.to_s
+        parts = name.split(".", -1)
+        unless parts.size == 2 && parts.all? { |part| PART.match?(part) }
+          raise ArgumentError, "bad signal #{name.inspect}: expected \"metric.member\" (e.g. \"system.cpu\")"
+        end
+
+        metric, member = parts
+        defaults = DEFAULTS.fetch(name, {})
+        inferred = infer(member)
+        pick = ->(key, override) { override.nil? ? (defaults[key].nil? ? inferred[key] : defaults[key]) : override }
+        Signal.new(name:, metric: metric.to_sym, member: member.to_sym, label: pick[:label, label],
+                   unit: pick[:unit, unit]&.to_sym, max: pick[:max, max], of: pick[:of, of]&.to_s)
+      end
+
+      # Label, unit and max guessed from a member name.
+      def infer(member)
+        member = member.to_s
+        rate = member.end_with?("_rate")
+        stem = rate ? member.delete_suffix("_rate") : member
+        label = stem.tr("_", " ")
+        unit, max =
+          if rate
+            [EVENT_STEMS.include?(stem) ? :per_sec : :bytes_per_sec, nil]
+          elsif PERCENT_MEMBERS.include?(member) || member.end_with?("_pct", "_percent")
+            [:percent, 100]
+          elsif member.start_with?("load")
+            [:number, nil]
+          elsif INTEGER_MEMBERS.include?(member) || member.end_with?("_count")
+            [:integer, nil]
+          elsif member.end_with?("ratio")
+            [:ratio, nil]
+          else
+            [:bytes, nil]
+          end
+        { label:, unit:, max: }
+      end
+
+      # The metric's value in `reading` (the virtual :focus is Focus.value); nil when missing or
+      # when the reading raises.
+      def metric_value(reading, metric)
+        return nil if reading.nil?
+
+        metric = metric.to_sym
+        metric == :focus ? Focus.value(reading) : reading[metric]
+      rescue StandardError
+        nil
+      end
+
+      # A member of a Data/Struct or Hash (symbol or string key); only Numeric results count.
+      def read(object, member)
+        value = fetch(object, member)
+        value.is_a?(Numeric) ? value : nil
+      end
+
+      def value(signal, reading) = read(metric_value(reading, signal.metric), signal.member)
+
+      # The `of` signal's value, nil when there is none or it is unknown.
+      def total(signal, reading)
+        return nil unless signal.of
+
+        value(parse(signal.of), reading)
+      end
+
+      # value / (total || max) clamped to 0..1; nil when the value or the scale is unknown.
+      def fraction(signal, reading)
+        current = value(signal, reading) or return nil
+        scale = total(signal, reading) || signal.max
+        return nil if scale.nil? || !scale.positive?
+
+        (current.to_f / scale).clamp(0.0, 1.0)
+      end
+
+      # A trend the metric already keeps (`member_trend`, else the member without `_rate`), or nil.
+      def trend(signal, reading)
+        object = metric_value(reading, signal.metric) or return nil
+        member = signal.member.to_s
+        [member, member.delete_suffix("_rate")].uniq.each do |base|
+          series = fetch(object, :"#{base}_trend")
+          return series if series.is_a?(Array)
+        end
+        nil
+      end
+
+      # `value` as text in `unit`; nil for nil.
+      def format(value, unit)
+        return nil if value.nil?
+
+        case unit
+        when :integer then value.round.to_s
+        when :percent, :bytes, :bytes_per_sec, :number, :ratio then R2UI::Format.call(unit, value)
+        when :per_sec then per_sec(value)
+        when :signed_bytes_per_sec then signed_bytes_per_sec(value)
+        else value.to_s
+        end
+      end
+
+      def per_sec(value)
+        return "0/s" if value.zero?
+
+        value.abs >= 10 ? "#{value.round}/s" : Kernel.format("%.1f/s", value)
+      end
+
+      def signed_bytes_per_sec(value)
+        return "0B/s" if value.zero?
+
+        "#{value.positive? ? "+" : "-"}#{R2UI::Format.bytes(value.abs)}/s"
+      end
+
+      def fetch(object, member)
+        case object
+        when nil then nil
+        when Hash
+          key = member.to_sym
+          object.key?(key) ? object[key] : object[member.to_s]
+        when Data then object.to_h[member.to_sym]
+        when Struct then object.members.include?(member.to_sym) ? object[member.to_sym] : nil
+        else
+          name = member.to_sym
+          object.respond_to?(name) && object.method(name).arity.zero? ? object.public_send(name) : nil
+        end
+      rescue StandardError
+        nil
+      end
+
+      # The virtual metric :focus: the focused session, else every agent session together.
+      # FocusedReading already narrows :session_ledger and :session_memory to the focused session,
+      # so this only aggregates what the reading gives (:session_network too).
+      module Focus
+        LEDGER_SUMS = %i[processes read_rate write_rate].freeze
+        MEMORY_SUMS = %i[footprint resident wired peak_footprint growth_rate pagein_rate].freeze
+        # focus member => SessionNetwork member summed into it.
+        NETWORK_SUMS = { net_in_rate: :in_rate, net_out_rate: :out_rate, bytes_in: :bytes_in, bytes_out: :bytes_out,
+                         connections: :connections, remote_hosts: :remote_hosts }.freeze
+        # focus trend => SessionNetwork trend, used when focused on one session (else History).
+        NETWORK_TRENDS = { net_in_trend: :in_trend, net_out_trend: :out_trend }.freeze
+
+        module_function
+
+        # A Hash: cpu (percent of the machine), processes, read_rate, write_rate (alive sessions),
+        # footprint .. pagein_rate (session memory), net_in_rate .. remote_hosts (session network;
+        # remote_hosts sums each session's count, so a host two sessions share counts twice),
+        # label, focused, and when focused the session's net_in_trend/net_out_trend. Unknown sums
+        # are nil; an empty list sums to 0.
+        def value(reading)
+          ledger = safe(reading, :session_ledger)
+          alive = ledger&.select { |s| s.ended_at.nil? }
+          memory = safe(reading, :session_memory)
+          network = safe(reading, :session_network)
+          focus = reading.respond_to?(:focus) ? reading.focus : nil
+
+          result = { cpu: cpu(alive, safe(reading, :system)) }
+          LEDGER_SUMS.each { |key| result[key] = sum(alive, key) }
+          MEMORY_SUMS.each { |key| result[key] = sum(memory, key) }
+          NETWORK_SUMS.each { |key, member| result[key] = sum(network, member) }
+          trends(network).each { |key, series| result[key] = series } if focus && network&.size == 1
+          result[:label] = focus ? label(focus, ledger, memory) : "all agents"
+          result[:focused] = !focus.nil?
+          result
+        end
+
+        # The one session's own rate trends (Arrays only).
+        def trends(network)
+          NETWORK_TRENDS.filter_map do |key, member|
+            series = Signals.fetch(network.first, member)
+            [key, series] if series.is_a?(Array)
+          end
+        end
+
+        # Sum of alive sessions' CPU (percent of one core) / ncpu: percent of the machine.
+        def cpu(alive, system)
+          ncpu = system.respond_to?(:ncpu) ? system.ncpu : nil
+          return nil if alive.nil? || !ncpu.is_a?(Numeric) || !ncpu.positive?
+          return 0.0 if alive.empty?
+
+          total = sum(alive, :cpu)
+          total && (total.to_f / ncpu)
+        end
+
+        # nil for an unknown list; 0 for an empty one; nil when no item knows the member.
+        def sum(items, member)
+          return nil if items.nil?
+          return 0 if items.empty?
+
+          known = items.filter_map { |item| Signals.read(item, member) }
+          known.empty? ? nil : known.sum
+        end
+
+        def label(focus, ledger, memory)
+          session = ledger&.find { |s| s.id == focus }
+          row = memory&.find { |m| m.session_id == focus }
+          session&.label || row&.label || focus.to_s
+        end
+
+        def safe(reading, name)
+          reading[name]
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end