agentmon 0.1.0

data/lib/agentmon/model.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Agentmon
+  # The data model: every value that crosses a file boundary (a probe's output, a metric's output,
+  # a store record) is one of these. Stories build against these shapes, so they can be written in
+  # parallel; changing one is a contract change (docs/design.md).
+  #
+  # Units, everywhere:
+  #   sizes and cumulative I/O   bytes (Integer)
+  #   rates                      bytes per second (Float)
+  #   CPU time                   seconds (Float), never Mach ticks
+  #   CPU usage                  percent of one core (Float): 250.0 is two and a half cores busy
+  #   instants                   epoch seconds (Float); intervals use the monotonic clock
+  #   nil                        unknown (unreadable, or not measured yet), never 0
+
+  # One probe pass: what every probe returned at one instant. `parts[:processes]` and so on.
+  # `errors` maps a probe that raised to its message (its part keeps the previous value).
+  Sample = Data.define(:at, :mono, :parts, :errors) do
+    def initialize(at:, mono:, parts:, errors: {}) = super
+
+    def [](name) = parts[name]
+  end
+
+  # probes/processes.rb: one process. Cumulative counters are since the process started.
+  # `readable` is false for processes the kernel won't describe to us (root daemons): then only
+  # the ps fields (pid, ppid, path, resident, ps_cpu) are set and the rest are nil.
+  ProcessStat = Data.define(
+    :pid, :ppid,
+    :name,            # basename of the executable
+    :path,            # executable path as ps reports it (comm)
+    :readable,        # rusage was readable
+    :start_ticks,     # Mach ticks at start: [pid, start_ticks] survives pid reuse (nil if unreadable)
+    :started_at,      # epoch seconds (nil if unreadable)
+    :cpu_time,        # own user+system seconds
+    :child_cpu_time,  # user+system seconds of children it has reaped
+    :resident,        # bytes (rusage, or ps rss when unreadable)
+    :footprint,       # physical footprint, bytes: what Activity Monitor calls Memory
+    :peak_footprint,  # lifetime max footprint, bytes
+    :disk_read,       # cumulative bytes
+    :disk_written,    # cumulative bytes
+    :ps_cpu,          # ps %cpu (a decaying average): the fallback when rusage is unreadable
+    # Paging and scheduling, from the same two calls per process (rusage, PROC_PIDTASKALLINFO).
+    # nil when unreadable. Counts are cumulative event counts (Integer), not bytes.
+    :wired,           # wired (unpageable) bytes now
+    :pageins,         # count of faults that had to read a page from disk (rusage ri_pageins)
+    :faults,          # count of page faults of any kind (pti_faults: a 32-bit kernel counter, wraps)
+    :cow_faults,      # count of copy-on-write faults (pti_cow_faults: 32-bit, wraps)
+    :context_switches, # count (pti_csw: 32-bit, wraps)
+    :runnable_time,   # seconds its threads were runnable: on a CPU *or waiting for one*
+                      # (ri_runnable_time). Time spent waiting to run = runnable_time - cpu_time
+    :threads,         # threads now
+    :running_threads  # threads running now
+  ) do
+    # The paging and scheduling fields default to nil (unknown), so code written before they
+    # existed, and fixtures that don't care, still build ProcessStats.
+    def initialize(wired: nil, pageins: nil, faults: nil, cow_faults: nil, context_switches: nil, runnable_time: nil,
+                   threads: nil, running_threads: nil, **) = super
+
+    def identity = [pid, start_ticks]
+  end
+
+  # metrics/process_rates.rb output, per pid: rates between the previous sample and this one.
+  # A process seen for the first time (or unreadable) has ps's %cpu and nil for every other rate.
+  ProcessRates = Data.define(
+    :cpu,                    # percent of one core
+    :read_rate, :write_rate, # disk bytes/s
+    :pagein_rate,            # pageins/s: each one waited for the disk (the closest thing to I/O wait)
+    :fault_rate,             # page faults/s
+    :cow_fault_rate,         # copy-on-write faults/s
+    :context_switch_rate,    # context switches/s
+    :run_wait                # percent of one core spent runnable but not running, i.e. waiting for
+                             # a CPU: (Δrunnable_time - Δcpu_time) / interval x 100
+  ) do
+    def initialize(pagein_rate: nil, fault_rate: nil, cow_fault_rate: nil, context_switch_rate: nil, run_wait: nil,
+                   **) = super
+  end
+
+  # metrics/sessions.rb: who an agent session is. `kind` is :cli (an outermost claude/codex CLI
+  # process) or :app (a desktop app and all its helpers). `id` is stable across agentmon runs:
+  # "claude-4242-1790711088" (name, root pid, root start second).
+  # `label` is the one display string every consumer shows and searches: "claude 4242 · repo", or
+  # with a human name "Agentmon r2ui integration · claude 4242 · repo" (name first, so a table
+  # cut at a word boundary keeps it). `title`, `status`, `threads` come from SessionName (nil/[]
+  # when unknown).
+  SessionInfo = Data.define(:id, :kind, :name, :root_pid, :label, :cwd, :started_at, :title, :status, :threads) do
+    def initialize(title: nil, status: nil, threads: [], **) = super
+  end
+
+  # metrics/session_names.rb output, per session root pid: what the agent itself calls the session.
+  SessionName = Data.define(
+    :title,   # String: the session's name ("Agentmon r2ui integration"); for a codex process hosting
+              # several threads, its newest named thread plus " +N" for N more open threads; nil unknown
+    :status,  # "busy" / "idle" from Claude Code's session file; nil for codex or unknown
+    :threads  # Array of String: a codex process's open threads' names, newest first ([] for Claude)
+  )
+
+  # metrics/sessions.rb output: the sessions alive in this sample and which one each pid is in.
+  SessionMap = Data.define(:sessions, :by_pid) do
+    def of(pid) = (id = by_pid[pid]) && sessions.find { |s| s.id == id }
+  end
+
+  # metrics/session_ledger.rb output (one per session, alive or ended in the last
+  # SessionLedger::KEEP_ENDED seconds). Current values are 0 once it has ended.
+  Session = Data.define(
+    :id, :kind, :name, :root_pid, :label, :cwd,
+    :started_at,      # the root process's start (epoch), or first_seen_at when unknown
+    :first_seen_at,   # when agentmon first saw it
+    :last_seen_at,    # last sample it was alive in
+    :ended_at,        # nil while alive
+    :processes,       # live member processes
+    :cpu,             # percent, now
+    :footprint,       # bytes, now (readable members only)
+    :resident,        # bytes, now
+    :read_rate,       # bytes/s, now
+    :write_rate,      # bytes/s, now
+    :peak_footprint,  # max footprint seen over its life (bytes)
+    :cpu_seconds,     # CPU seconds over its life, reaped children included (see design.md)
+    :bytes_read,      # disk bytes read by members while observed (a lower bound)
+    :bytes_written,   # disk bytes written by members while observed (a lower bound)
+    # From the latest SessionInfo (SessionName): human name, Claude's "busy"/"idle", codex thread
+    # names newest first. nil/[] when unknown.
+    :title, :status, :threads
+  ) do
+    def initialize(title: nil, status: nil, threads: [], **) = super
+
+    def alive? = ended_at.nil?
+
+    def duration = (ended_at || last_seen_at) - (started_at || first_seen_at)
+
+    # The store line for kind "sessions" (docs/design.md, "Store").
+    def to_record = to_h.merge(kind: kind.to_s)
+  end
+
+  # metrics/process_rows.rb output: one row per process for tables (dashboard and CLI).
+  ProcessRow = Data.define(
+    :pid, :ppid, :name, :path, :cwd,
+    :session,         # session label, nil when it isn't in an agent session
+    :session_id,
+    :cpu,             # percent (rusage delta, or ps %cpu when unreadable or first seen)
+    :footprint, :resident, :peak_footprint,  # bytes
+    :read_rate, :write_rate,                 # bytes/s, nil until two samples
+    :cpu_time, :disk_written,                # seconds, bytes (cumulative)
+    :started_at, :readable,
+    # Paging and scheduling (from ProcessStat and ProcessRates); nil when unreadable or before two
+    # samples. Optional, so rows built without them still work.
+    :disk_read,                              # bytes (cumulative)
+    :wired,                                  # bytes now
+    :pageins, :faults, :cow_faults, :context_switches, # counts (cumulative)
+    :runnable_time,                          # seconds (cumulative), time on a CPU included
+    :threads, :running_threads,              # counts now
+    :pagein_rate, :fault_rate, :cow_fault_rate, :context_switch_rate, # per second
+    :run_wait,                               # percent of one core spent waiting for a CPU
+    # Network (metrics/network.rb, from nettop); nil when unknown (no snapshot yet, first sighting).
+    :net_in_rate, :net_out_rate              # bytes/s received / sent over all its sockets
+  ) do
+    def initialize(disk_read: nil, wired: nil, pageins: nil, faults: nil, cow_faults: nil, context_switches: nil,
+                   runnable_time: nil, threads: nil, running_threads: nil, pagein_rate: nil, fault_rate: nil,
+                   cow_fault_rate: nil, context_switch_rate: nil, run_wait: nil, net_in_rate: nil,
+                   net_out_rate: nil, **) = super
+  end
+
+  # probes/network.rb: one socket (flow) of a process as one `nettop -x -L 0` line prints it.
+  NetFlow = Data.define(
+    :protocol,     # "tcp4", "udp6", "quic4", ...
+    :local,        # local endpoint as nettop prints it: "192.0.2.5:55584" (IPv4 `:` port),
+    :remote,       # "2001:db8::1.443" (IPv6 `.` port), "*:*" / "*.*" wildcards
+    :remote_host,  # remote address or name without the port; nil for the `*` wildcard
+    :remote_port,  # Integer, nil for `*`
+    :interface,    # "en0", "lo0"; nil when nettop leaves it empty
+    :state,        # "Established", "Listen", ...; nil for stateless (UDP) or empty
+    :bytes_in,     # cumulative bytes received on this flow; nil when nettop leaves it empty
+    :bytes_out     # cumulative bytes sent, likewise
+  )
+
+  # probes/network.rb: one process's sockets in one nettop block.
+  NetProcess = Data.define(
+    :pid,
+    :name,         # nettop's (truncated) process name
+    :bytes_in,     # cumulative bytes received, as nettop counts them for the process
+    :bytes_out,    # cumulative bytes sent
+    :flows         # Array of NetFlow
+  )
+
+  # probes/network.rb: one complete nettop block (sample[:network]).
+  NetSnapshot = Data.define(
+    :at_mono,      # monotonic seconds when the block's header arrived (rates use these)
+    :processes     # { pid => NetProcess }; a process without sockets has no entry
+  )
+
+  # metrics/network.rb reading[:net_rates], per pid: between the two latest nettop snapshots.
+  NetRates = Data.define(:in_rate, :out_rate) # bytes/s; nil when unknown
+
+  # metrics/network.rb reading[:session_network]: one alive session's network, each pid once.
+  SessionNetwork = Data.define(
+    :session_id, :label,
+    :in_rate, :out_rate,   # bytes/s now, summed over members (nil when no member's rate is known)
+    :bytes_in, :bytes_out, # cumulative bytes received / sent by members while agentmon observed them
+    :in_trend, :out_trend, # the last 120 known rates (bytes/s), oldest first
+    :connections,          # count of member flows with a concrete remote (not `*`)
+    :remote_hosts,         # count of distinct remote hosts, loopback and link-local left out
+    :flags                 # Array of Symbols from the anomaly rule (:out_spike, :in_spike, :many_hosts); [] normal
+  )
+
+  # metrics/network.rb reading[:connections]: one flow of a process in an agent session with a
+  # concrete remote (no `*`, no Listen). Fields as NetFlow; rates bytes/s, nil the first time.
+  ConnectionRow = Data.define(
+    :pid, :name, :session_id,
+    :session,              # session label
+    :protocol, :local, :remote, :remote_host, :remote_port, :interface, :state,
+    :bytes_in, :bytes_out, # cumulative bytes on this flow
+    :in_rate, :out_rate    # bytes/s between the two latest snapshots
+  )
+
+  # probes/memory.rb (story a01): the machine's memory counters. Sizes in bytes; the counters
+  # (swapins .. pageins) are cumulative bytes since boot (pages x page size).
+  MemoryStat = Data.define(
+    :total,              # hw.memsize
+    :free,
+    :app,                # anonymous (internal) pages minus purgeable
+    :wired,
+    :compressed,         # pages occupied by the compressor
+    :compressor_stored,  # uncompressed bytes held in the compressor
+    :cached,             # file-backed + purgeable
+    :purgeable,
+    :swap_total, :swap_used,
+    :swapins, :swapouts, :compressions, :decompressions, :pageins,
+    :memorystatus_level  # kern.memorystatus_level: percent of memory available (100 = no pressure)
+  )
+
+  # metrics/memory.rb (story a02): Activity Monitor's breakdown plus rates and pressure.
+  MemoryView = Data.define(
+    :total, :used, :app, :wired, :compressed, :cached, :free, :swap_used, :swap_total,
+    :compression_ratio,  # compressor_stored / compressed (e.g. 3.1)
+    :swapin_rate, :swapout_rate, :compression_rate, :decompression_rate,  # bytes/s
+    :pressure,           # percent: 100 - memorystatus_level
+    :pressure_trend      # recent pressure values, oldest first (Array of Float)
+  )
+
+  # metrics/pressure_drivers.rb (story a03): sessions ranked by how much they push memory.
+  PressureDriver = Data.define(
+    :session_id, :label,
+    :footprint,     # bytes now
+    :share,         # percent of used memory
+    :growth_rate    # bytes/s of footprint change over the last minute
+  )
+
+  # metrics/session_memory.rb (story a20): one alive session's memory, largest footprint first.
+  # Sums over the session's live readable members, each process once. Compressed and swapped
+  # bytes per process need task_for_pid (root), so they aren't here; MemoryView has the machine's.
+  SessionMemory = Data.define(
+    :session_id, :label,
+    :processes,       # live members
+    :footprint,       # bytes now (Activity Monitor's Memory; includes the session's compressed pages)
+    :resident,        # bytes now
+    :wired,           # bytes now
+    :peak_footprint,  # bytes: largest footprint sum over its life (Session#peak_footprint)
+    :share,           # percent of MemoryView#used (nil while memory is unknown)
+    :growth_rate,     # bytes/s of footprint change over the last minute (0.0 until two samples)
+    :pageins,         # count, cumulative over live members
+    :pagein_rate,     # pageins/s now (nil until two samples)
+    :fault_rate       # page faults/s now (nil until two samples)
+  )
+end

data/lib/agentmon/probes/cwd.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# sample[:cwd]: { pid => working directory } for every process lsof can see.
+#
+# lsof costs ~0.4 s for the whole machine, so it runs at most every CWD_EVERY seconds and the
+# sampler reuses the last map in between (`every:`). A process newer than the map has no cwd until
+# the next run. Session labels ("claude 4242 · repo") and the Directory column come from here.
+module Agentmon
+  module Probes
+    module Cwd
+      CWD_EVERY = 10
+      LSOF = %w[lsof -d cwd -Fpn].freeze
+
+      module_function
+
+      def read(text = IO.popen(LSOF, err: File::NULL, &:read)) = parse(text)
+
+      # lsof -F output: "p<pid>" then "n<path>" lines.
+      def parse(text)
+        pid = nil
+        text.each_line.with_object({}) do |line, cwds|
+          case line[0]
+          when "p" then pid = line[1..].to_i
+          when "n" then cwds[pid] = line[1..].chomp if pid
+          end
+        end
+      end
+    end
+  end
+
+  probe(:cwd, every: Probes::Cwd::CWD_EVERY) { Probes::Cwd.read }
+end

data/lib/agentmon/probes/memory.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "fiddle"
+
+# sample[:memory]: the machine's memory counters, as a MemoryStat (lib/agentmon/model.rb), in
+# bytes. The same numbers Activity Monitor's Memory tab and vm_stat show, e.g. on a 32 GiB Mac:
+#
+#   total 32.0G   app 10.4G   wired 4.3G   compressed 9.4G (stores 24.3G)   cached 5.3G
+#   swap 1.9G of 3.0G used   memorystatus_level 55 (pressure 45%)
+#
+# No subprocesses: host_statistics64(HOST_VM_INFO64) through Fiddle for the page counts
+# (pages x vm_kernel_page_size: 16 KiB on Apple Silicon, 4 KiB on Intel), and sysctlbyname for
+# hw.memsize, vm.swapusage, vm.page_pageable_internal_count and kern.memorystatus_level. A read
+# takes well under a millisecond.
+#
+#   app        = pageable internal (anonymous) pages - purgeable pages
+#   cached     = file-backed pages + purgeable pages
+#   compressed = pages the compressor occupies; compressor_stored = pages stored in it
+#   free       = free pages minus speculative ones (those are file-backed, so already in cached)
+#   swapins, swapouts, compressions, decompressions, pageins: cumulative bytes since boot
+#
+# A sysctl that fails leaves its fields nil (swap, memorystatus_level); without
+# vm.page_pageable_internal_count, app uses the anonymous page count instead. Off macOS the probe
+# is nil.
+module Agentmon
+  module Probes
+    module Memory
+      HOST_VM_INFO64 = 4
+      # struct vm_statistics64 (xnu osfmk/mach/vm_statistics.h): 152 bytes, 38 integer_t's.
+      VM_SIZE = 152
+      VM_COUNT = VM_SIZE / 4
+      VM_FORMAT = "L<4Q<9L<2Q<4L<4Q<"
+      VM_FIELDS = %i[
+        free_count active_count inactive_count wire_count
+        zero_fill_count reactivations pageins pageouts faults cow_faults lookups hits purges
+        purgeable_count speculative_count
+        decompressions compressions swapins swapouts
+        compressor_page_count throttled_count external_page_count internal_page_count
+        total_uncompressed_pages_in_compressor
+      ].freeze
+      # struct xsw_usage: xsu_total, xsu_avail, xsu_used (uint64), xsu_pagesize, xsu_encrypted.
+      SWAP_SIZE = 32
+
+      module_function
+
+      # Reads the live machine. Raises when host_statistics64 fails.
+      def read
+        decode(vm: Native.vm_statistics, page_size: Native.page_size, memsize: Native.sysctl_int("hw.memsize"),
+               swap: Native.sysctl("vm.swapusage", SWAP_SIZE),
+               pageable_internal: Native.sysctl_int("vm.page_pageable_internal_count"),
+               memorystatus_level: Native.sysctl_int("kern.memorystatus_level"))
+      end
+
+      # Builds the MemoryStat from the raw kernel answers: `vm` is a vm_statistics64 as the kernel
+      # wrote it, `swap` an xsw_usage (or nil), the rest Integers (or nil). Pure; tests feed it
+      # recorded bytes.
+      def decode(vm:, page_size:, memsize:, swap: nil, pageable_internal: nil, memorystatus_level: nil)
+        raise ArgumentError, "vm_statistics64 is #{vm.bytesize} bytes, want #{VM_SIZE}" if vm.bytesize < VM_SIZE
+
+        v = VM_FIELDS.zip(vm.byteslice(0, VM_SIZE).unpack(VM_FORMAT)).to_h
+        bytes = ->(pages) { pages * page_size }
+        purgeable = v[:purgeable_count]
+        internal = pageable_internal || v[:internal_page_count]
+        swap_total, _avail, swap_used = swap&.byteslice(0, 24)&.unpack("Q<3")
+        MemoryStat.new(
+          total: memsize,
+          free: bytes[[v[:free_count] - v[:speculative_count], 0].max],
+          app: bytes[[internal - purgeable, 0].max],
+          wired: bytes[v[:wire_count]],
+          compressed: bytes[v[:compressor_page_count]],
+          compressor_stored: bytes[v[:total_uncompressed_pages_in_compressor]],
+          cached: bytes[v[:external_page_count] + purgeable],
+          purgeable: bytes[purgeable],
+          swap_total:, swap_used:,
+          swapins: bytes[v[:swapins]], swapouts: bytes[v[:swapouts]],
+          compressions: bytes[v[:compressions]], decompressions: bytes[v[:decompressions]],
+          pageins: bytes[v[:pageins]],
+          memorystatus_level:
+        )
+      end
+
+      # The Fiddle calls. Buffers are per call, so reads from several threads don't share memory.
+      module Native
+        module_function
+
+        def vm_statistics
+          buffer = Fiddle::Pointer.malloc(VM_SIZE, Fiddle::RUBY_FREE)
+          count = Fiddle::Pointer.malloc(4, Fiddle::RUBY_FREE)
+          count[0, 4] = [VM_COUNT].pack("L")
+          result = functions[:host_statistics64].call(host, HOST_VM_INFO64, buffer, count)
+          raise Error, "host_statistics64 failed (kern_return_t #{result})" unless result.zero?
+
+          buffer[0, VM_SIZE]
+        end
+
+        # vm_kernel_page_size, a libSystem global (vm_size_t).
+        def page_size = @page_size ||= Fiddle::Pointer.new(lib["vm_kernel_page_size"])[0, 8].unpack1("Q")
+
+        # The sysctl's raw bytes (at most `size`), or nil when it fails.
+        def sysctl(name, size)
+          buffer = Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE)
+          length = Fiddle::Pointer.malloc(8, Fiddle::RUBY_FREE)
+          length[0, 8] = [size].pack("Q")
+          return nil unless functions[:sysctlbyname].call(name, buffer, length, nil, 0).zero?
+
+          buffer[0, length[0, 8].unpack1("Q")]
+        end
+
+        # An integer sysctl of 4 or 8 bytes (they differ by name and OS version), or nil.
+        def sysctl_int(name)
+          raw = sysctl(name, 8)
+          case raw&.bytesize
+          when 4 then raw.unpack1("l<")
+          when 8 then raw.unpack1("q<")
+          end
+        end
+
+        # mach_host_self() returns a send right each call; take it once.
+        def host = @host ||= functions[:mach_host_self].call
+
+        def lib = @lib ||= Fiddle.dlopen(nil)
+
+        def functions
+          @functions ||= {
+            mach_host_self: Fiddle::Function.new(lib["mach_host_self"], [], -Fiddle::TYPE_INT),
+            host_statistics64: Fiddle::Function.new(lib["host_statistics64"],
+                                                    [-Fiddle::TYPE_INT, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP,
+                                                     Fiddle::TYPE_VOIDP], Fiddle::TYPE_INT),
+            sysctlbyname: Fiddle::Function.new(lib["sysctlbyname"],
+                                               [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP,
+                                                Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T], Fiddle::TYPE_INT)
+          }
+        end
+      end
+    end
+  end
+
+  probe(:memory) { Darwin.available? ? Probes::Memory.read : nil }
+end