agent_top_core/

model.rs

//! The data model shared by discovery, the TUI and the JSON output.

use serde::{Deserialize, Serialize};
use std::path::PathBuf;
use std::time::SystemTime;

/// Which agent harness a process or transcript belongs to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, PartialOrd, Ord)]
#[serde(rename_all = "kebab-case")]
pub enum Harness {
    Claude,
    Codex,
    Gemini,
    OpenCode,
    Kodelet,
    Aider,
    Copilot,
    Cursor,
    Unknown,
}

impl Harness {
    pub fn label(self) -> &'static str {
        match self {
            Harness::Claude => "claude",
            Harness::Codex => "codex",
            Harness::Gemini => "gemini",
            Harness::OpenCode => "opencode",
            Harness::Kodelet => "kodelet",
            Harness::Aider => "aider",
            Harness::Copilot => "copilot",
            Harness::Cursor => "cursor",
            Harness::Unknown => "unknown",
        }
    }

    /// How much of a session id identifies it to `agent-top trace --session`,
    /// which matches a prefix against the ids of every harness and fails when
    /// one matches more than one session. `None` means the whole id is needed:
    /// Kodelet's begin with a date that every session started that day shares.
    pub fn session_id_prefix_len(self) -> Option<usize> {
        match self {
            Harness::Kodelet => None,
            Harness::Claude
            | Harness::Codex
            | Harness::Gemini
            | Harness::OpenCode
            | Harness::Aider
            | Harness::Copilot
            | Harness::Cursor
            | Harness::Unknown => Some(8),
        }
    }
}

/// Coarse lifecycle state, in the htop sense.
///
/// `Running` means the agent is mid-turn (inference or tool execution),
/// `Idle` means the process is alive but waiting for a human, `Stopped` means
/// the transcript exists and was recently active but no process owns it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, PartialOrd, Ord)]
#[serde(rename_all = "kebab-case")]
pub enum AgentState {
    Running,
    Idle,
    Stopped,
}

impl AgentState {
    pub fn label(self) -> &'static str {
        match self {
            AgentState::Running => "running",
            AgentState::Idle => "idle",
            AgentState::Stopped => "stopped",
        }
    }
}

/// What the transcript says the agent was last doing. Harness-neutral.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "kebab-case")]
pub enum Activity {
    /// Mid-turn: a prompt or tool result was just submitted, or a tool call is pending.
    Working,
    /// The last thing that happened was the assistant ending its turn.
    Waiting,
    #[default]
    Unknown,
}

/// Token counts, split the way the Anthropic and OpenAI usage objects split them.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq)]
pub struct TokenUsage {
    pub input: u64,
    pub cache_write_5m: u64,
    pub cache_write_1h: u64,
    /// Cache creation a harness recorded without the TTL that decides its
    /// rate. No price table can cover it: charging either TTL's rate would be
    /// a guess about a lifetime nobody wrote down. Only a harness that reports
    /// its own costs can put a number against these tokens.
    #[serde(default)]
    pub cache_write_unsplit: u64,
    pub cache_read: u64,
    pub output: u64,
}

impl TokenUsage {
    pub fn cache_write(&self) -> u64 {
        self.cache_write_5m + self.cache_write_1h + self.cache_write_unsplit
    }

    /// Everything the model consumed or produced. This is the "TOKENS" column.
    pub fn total(&self) -> u64 {
        self.input + self.cache_write() + self.cache_read + self.output
    }

    /// The input side: everything sent to the model as the prompt, fresh input
    /// plus cache writes plus cache reads, but not the output it produced.
    pub fn prompt(&self) -> u64 {
        self.input + self.cache_write() + self.cache_read
    }

    /// The share of the prompt served from cache (the cheap reads), in `0..=1`.
    /// A high number means most of the re-sent conversation was billed at the
    /// cache-read rate rather than full input; a low one on a long session is
    /// money left on the table. `None` when there was no prompt to judge, or
    /// the model does not cache at all.
    pub fn cache_hit_rate(&self) -> Option<f64> {
        let p = self.prompt();
        (p > 0).then(|| self.cache_read as f64 / p as f64)
    }

    pub fn add(&mut self, other: &TokenUsage) {
        self.input += other.input;
        self.cache_write_5m += other.cache_write_5m;
        self.cache_write_1h += other.cache_write_1h;
        self.cache_write_unsplit += other.cache_write_unsplit;
        self.cache_read += other.cache_read;
        self.output += other.output;
    }

    pub fn sub(&mut self, other: &TokenUsage) {
        self.input = self.input.saturating_sub(other.input);
        self.cache_write_5m = self.cache_write_5m.saturating_sub(other.cache_write_5m);
        self.cache_write_1h = self.cache_write_1h.saturating_sub(other.cache_write_1h);
        self.cache_write_unsplit = self.cache_write_unsplit.saturating_sub(other.cache_write_unsplit);
        self.cache_read = self.cache_read.saturating_sub(other.cache_read);
        self.output = self.output.saturating_sub(other.output);
    }
}

/// What a span measures. Tool calls came first and gave the type its name;
/// the other two label the time between them.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default, PartialOrd, Ord)]
#[serde(rename_all = "kebab-case")]
pub enum SpanKind {
    /// One tool call, from the harness issuing it to the result coming back.
    #[default]
    Tool,
    /// The model producing a response: from a prompt or tool results being
    /// submitted to the last block of the reply being written. The gap in a
    /// waterfall that is not a tool call is almost always one of these.
    Inference,
    /// One human turn: from the prompt to the model ending its reply.
    /// Contains every tool call and inference span issued in between.
    Turn,
}

impl SpanKind {
    pub const ALL: [SpanKind; 3] = [SpanKind::Tool, SpanKind::Inference, SpanKind::Turn];

    pub fn label(self) -> &'static str {
        match self {
            SpanKind::Tool => "tool",
            SpanKind::Inference => "inference",
            SpanKind::Turn => "turn",
        }
    }
}

/// One span of an agent trace: a tool call, an inference, or a turn.
///
/// Every harness writes the same shape in its own vocabulary — Claude pairs a
/// `tool_use` block with a `tool_result` block by `tool_use_id`, Codex pairs a
/// `function_call` with a `function_call_output` by `call_id` — and both stamp
/// each line with a timestamp. That is a span: a name, a start and a duration.
/// Only the call's metadata is kept; arguments and output are never read.
///
/// The name predates `kind`: the type carried only tool calls until 0.3.1 and
/// is kept for the sake of the published API.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ToolSpan {
    /// The harness's own call id, so a span survives across refreshes. For
    /// inference and turn spans, a counter the parser assigns.
    pub id: String,
    /// Tool name as the harness reports it (`Bash`, `exec_command`, ...), or
    /// `inference` / `turn`.
    pub name: String,
    pub started_at: SystemTime,
    /// Wall-clock duration, or `None` while the call is still in flight.
    pub duration_ms: Option<u64>,
    /// The call was issued by a subagent (Claude's `isSidechain`).
    pub sidechain: bool,
    /// The harness reported the result as an error.
    pub error: bool,
    /// Absent in snapshots written before 0.3.1, which held tool calls only.
    #[serde(default)]
    pub kind: SpanKind,
}

impl ToolSpan {
    pub fn is_open(&self) -> bool {
        self.duration_ms.is_none()
    }

    /// Duration if closed, otherwise how long it has been running as of `now`.
    pub fn elapsed_ms(&self, now: SystemTime) -> u64 {
        match self.duration_ms {
            Some(ms) => ms,
            None => now.duration_since(self.started_at).map(|d| d.as_millis() as u64).unwrap_or(0),
        }
    }

    pub fn ended_at(&self, now: SystemTime) -> SystemTime {
        self.started_at + std::time::Duration::from_millis(self.elapsed_ms(now))
    }
}

/// One MCP server an agent uses, seen from either side or both: the process
/// table has the server's pid, CPU and memory; the transcript has how often
/// the agent called it. Claude Code names an MCP tool `mcp__<server>__<tool>`,
/// which is where the server name and the call count come from.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct McpServer {
    /// The server's name as the harness configured it, or, for a process the
    /// transcript never named, the program it is running.
    pub name: String,
    pub pid: Option<u32>,
    pub cmdline: Option<String>,
    pub cpu_percent: f32,
    pub rss_bytes: u64,
    pub age_secs: Option<u64>,
    /// Tool calls the agent made to this server, from the transcript.
    pub calls: u64,
    /// Of those, how many the harness reported as errors.
    pub errors: u64,
    pub last_call: Option<SystemTime>,
    /// How the process and the transcript's server were put together, for
    /// the UI to label a guess as one.
    pub matched_by: McpMatch,
}

/// How an `McpServer` row was formed.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum McpMatch {
    /// A process under the agent that no transcript server names. Either it
    /// has not been called yet, or its name does not appear in its command.
    ProcessOnly,
    /// A server the transcript calls with no process under the agent: an HTTP
    /// server, or one that has exited.
    TranscriptOnly,
    /// The server's name appears in the process's command line.
    Name,
    /// One unmatched process and one unmatched server were left; they are
    /// taken to be the same. A guess.
    Sole,
}

/// Where a stretch of a session's context came from.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ContextOrigin {
    /// A built-in tool of the harness (`Bash`, `Read`, `exec_command`, ...).
    Tool,
    /// An MCP server; `name` is the server, not the tool.
    Mcp,
    /// Everything that is not a tool result: the system prompt, the user's
    /// own messages, a compaction summary.
    #[default]
    Other,
}

/// One source of a session's context: what its results have added to the
/// prompt, and what sending that on every inference since has cost.
///
/// The tokens are the growth of the prompt between one response and the
/// next, attributed to the tool results submitted in between; the cost is
/// those tokens charged at the prompt rate of every response that carried
/// them, the first read included. The rows sum to the session's prompt-side
/// cost. See `docs/accounting.md`.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
pub struct ContextSource {
    pub name: String,
    pub origin: ContextOrigin,
    /// Tool results attributed to this source. Zero for `Other`.
    pub calls: u64,
    /// Tokens the source added to the prompt over the session.
    pub tokens: u64,
    /// USD those tokens have cost across every response that read them.
    /// An estimate; zero when the model has no price.
    pub cost_usd: f64,
}

/// Role of a process inside an agent's tree.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ProcKind {
    /// A harness process, whether at the root or nested under another process.
    /// Older snapshots called nested harness processes `subagent`.
    #[serde(alias = "subagent")]
    Agent,
    /// A Model Context Protocol server or helper.
    Mcp,
    /// A shell spawned to run a tool call.
    Shell,
    /// Anything else the agent launched (test runners, sleep, caffeinate, ...).
    Tool,
}

impl ProcKind {
    pub fn label(self) -> &'static str {
        match self {
            ProcKind::Agent => "agent",
            ProcKind::Mcp => "mcp",
            ProcKind::Shell => "shell",
            ProcKind::Tool => "tool",
        }
    }
}

/// One process, with its descendants.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProcNode {
    pub pid: u32,
    pub ppid: Option<u32>,
    pub name: String,
    pub cmdline: String,
    pub kind: ProcKind,
    pub harness: Option<Harness>,
    pub cpu_percent: f32,
    pub rss_bytes: u64,
    pub age_secs: u64,
    pub cwd: Option<PathBuf>,
    pub children: Vec<ProcNode>,
}

impl ProcNode {
    /// CPU, RSS, process count and MCP server count summed over the whole
    /// subtree. An MCP process's own children (an `npx` wrapper's `node`) are
    /// the same server, so they add to the process count and not to the
    /// server count.
    pub fn totals(&self) -> (f32, u64, usize, usize) {
        let mut cpu = self.cpu_percent;
        let mut rss = self.rss_bytes;
        let mut count = 1;
        let mut mcp = usize::from(self.kind == ProcKind::Mcp);
        for c in &self.children {
            let (ccpu, crss, ccount, cmcp) = c.totals();
            cpu += ccpu;
            rss += crss;
            count += ccount;
            if self.kind != ProcKind::Mcp {
                mcp += cmcp;
            }
        }
        (cpu, rss, count, mcp)
    }

    /// The MCP servers in this tree: each `Mcp` node whose parent is not one.
    /// A server started through `npx` or `uvx` is two or three processes; the
    /// top one stands for the server.
    pub fn mcp_roots(&self) -> Vec<&ProcNode> {
        let mut out = Vec::new();
        self.collect_mcp_roots(&mut out);
        out
    }

    fn collect_mcp_roots<'a>(&'a self, out: &mut Vec<&'a ProcNode>) {
        if self.kind == ProcKind::Mcp {
            out.push(self);
            return;
        }
        for c in &self.children {
            c.collect_mcp_roots(out);
        }
    }

    pub fn walk<'a>(&'a self, depth: usize, f: &mut dyn FnMut(&'a ProcNode, usize)) {
        f(self, depth);
        for c in &self.children {
            c.walk(depth + 1, f);
        }
    }
}

/// A logical subagent relationship explicitly recorded by the harness.
/// This is session lineage, not an OS process relationship or a history fork.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SubagentInfo {
    pub parent_session_id: String,
    #[serde(default)]
    pub nickname: Option<String>,
    #[serde(default)]
    pub role: Option<String>,
}

/// A single row in the agent table.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Agent {
    /// Stable identity across refreshes: `pid:<n>` for live agents, `session:<id>` for stopped ones.
    pub id: String,
    pub name: String,
    pub harness: Harness,
    pub state: AgentState,
    pub activity: Activity,
    pub pid: Option<u32>,
    pub session_id: Option<String>,
    /// Explicit logical parent and identity, when the transcript records them.
    /// Usage remains per session; adding hierarchy must not count it twice.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub subagent: Option<SubagentInfo>,
    pub session_path: Option<PathBuf>,
    pub cwd: Option<PathBuf>,
    pub model: Option<String>,
    pub harness_version: Option<String>,
    pub usage: TokenUsage,
    /// USD spent on messages whose model had a known price.
    pub cost_usd: f64,
    /// `cost_usd` by kind of token, so a figure that differs from another
    /// tool's can be traced to the one line that differs.
    #[serde(default)]
    pub cost_breakdown: CostBreakdown,
    /// Where this row's costs came from; `None` when it has no known price.
    #[serde(default)]
    pub price_source: Option<PriceSource>,
    /// Tokens on messages whose model had no known price (so `cost_usd` is a floor).
    pub unpriced_tokens: u64,
    pub turns: u64,
    pub subagent_turns: u64,
    /// See `SessionSummary::folds_child_usage`. Claude Code, Gemini CLI and
    /// OpenCode fold a child's usage into its parent, the way those harnesses
    /// bill it; Codex and Kodelet give each child its own row instead.
    #[serde(default)]
    pub folds_child_usage: bool,
    pub tool_calls: u64,
    /// The count is only known retained/observed calls, not an exact lifetime
    /// total. Kodelet compaction discards old calls without a cumulative count.
    #[serde(default)]
    pub tool_calls_lower_bound: bool,
    /// Server-side web searches the model ran, billed per search on top of
    /// tokens. Counted for every harness; priced only where the price table
    /// has a rate (Anthropic's, for Claude Code).
    #[serde(default)]
    pub web_searches: u64,
    /// The most recent spans, oldest first: tool calls, inferences and turns.
    /// Bounded; see `harness::MAX_SPANS`.
    pub spans: Vec<ToolSpan>,
    /// Seconds since the process started (live) or since the last transcript write (stopped).
    pub age_secs: u64,
    /// Seconds since the transcript was last written.
    pub idle_secs: Option<u64>,
    pub cpu_percent: f32,
    pub rss_bytes: u64,
    pub process_count: usize,
    pub mcp_count: usize,
    /// The MCP servers this agent uses, one row each, from the process tree
    /// and the transcript. See `McpServer`.
    #[serde(default)]
    pub mcp_servers: Vec<McpServer>,
    /// What each tool's results added to the prompt and what carrying it has
    /// cost, largest first. See `ContextSource`.
    #[serde(default)]
    pub context: Vec<ContextSource>,
    pub tree: Option<ProcNode>,
    /// How the session was attributed to the process, for debugging attribution.
    pub attribution: Attribution,
    /// True when another row shares this pid and carries its CPU, memory and
    /// process counts. One Codex app-server hosts many conversations, so its
    /// threads each get a row while the process is only counted once.
    /// Absent in snapshots written before 0.2.0.
    #[serde(default)]
    pub shares_process: bool,
    /// Set when the transcript parsed but its usage records did not, which
    /// means this row's tokens and cost are not to be believed. Almost always a
    /// harness that changed its format under us.
    pub parse_warning: Option<String>,
    /// How close the session is to its rate limit, when the harness reports it.
    #[serde(default)]
    pub rate_limit: Option<RateLimit>,
    /// The session's cost as the harness itself last recorded it, beside
    /// `cost_usd` and never mixed into it. See `HarnessCost`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub harness_cost: Option<HarnessCost>,
}

/// A harness's own running total for a session, read from its transcript.
/// Claude Code writes one; the other harnesses do not, or (OpenCode, Kodelet)
/// their costs are already the row's `cost_usd`.
///
/// It is a different measurement from `cost_usd`, not a correction to it: it
/// is priced at the harness's private table, and it includes requests the
/// transcript never records. Claude Code writes it when a session exits, so
/// while a session runs it is the figure from the last exit.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq)]
pub struct HarnessCost {
    pub usd: f64,
    /// The harness said some of its usage had no price, so `usd` is a floor.
    pub lower_bound: bool,
    /// The timestamp of the last transcript line before the record, which
    /// carries none of its own.
    pub as_of: Option<SystemTime>,
    /// No usage has been recorded since, in the transcript or a subagent's.
    /// False for a live session that has done anything since it last exited:
    /// `usd` leaves that out.
    pub current: bool,
}

/// One rolling usage window a harness reports against a rate limit: how much
/// of it is spent and when it rolls over. Codex writes two, a short window and
/// a long one, on every usage record.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq)]
pub struct RateWindow {
    /// Percent of the window used, 0..=100.
    pub used_percent: f64,
    /// The window length in minutes (Codex: 300 for the short one, 10080 weekly).
    pub window_minutes: u64,
    /// When the window rolls over and the usage resets, if the harness says.
    pub resets_at: Option<SystemTime>,
}

/// What a harness reports about how close a session is to its rate limit. Only
/// the harnesses that write it (Codex today) populate this; the rest leave it
/// `None`. Read-only, like everything else: a number the harness already wrote.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
pub struct RateLimit {
    /// The short rolling window.
    pub primary: Option<RateWindow>,
    /// The long rolling window.
    pub secondary: Option<RateWindow>,
    /// The plan the limit is for (Codex: `plus`, `pro`, ...).
    pub plan: Option<String>,
    /// True when the harness says the limit is currently hit.
    pub reached: bool,
}

impl RateLimit {
    /// The window closest to its limit, for a one-glance figure.
    pub fn tightest(&self) -> Option<&RateWindow> {
        [self.primary.as_ref(), self.secondary.as_ref()]
            .into_iter()
            .flatten()
            .max_by(|a, b| a.used_percent.partial_cmp(&b.used_percent).unwrap_or(std::cmp::Ordering::Equal))
    }
}

/// USD by kind of token, accumulated message by message at each message's
/// own model price, so a session that changed model part way is still exact.
/// The lines sum to `Agent::cost_usd`.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq)]
pub struct CostBreakdown {
    pub input: f64,
    pub cache_write_5m: f64,
    pub cache_write_1h: f64,
    /// What a harness recorded against `TokenUsage::cache_write_unsplit`.
    /// Always zero when the cost came from a price table.
    #[serde(default)]
    pub cache_write_unsplit: f64,
    pub cache_read: f64,
    pub output: f64,
    /// Server-side web searches, billed per search on top of the tokens.
    pub web_search: f64,
}

impl CostBreakdown {
    pub fn total(&self) -> f64 {
        self.input + self.cache_write_5m + self.cache_write_1h + self.cache_write_unsplit + self.cache_read + self.output + self.web_search
    }

    pub fn add(&mut self, o: &CostBreakdown) {
        self.input += o.input;
        self.cache_write_5m += o.cache_write_5m;
        self.cache_write_1h += o.cache_write_1h;
        self.cache_write_unsplit += o.cache_write_unsplit;
        self.cache_read += o.cache_read;
        self.output += o.output;
        self.web_search += o.web_search;
    }

    pub fn sub(&mut self, o: &CostBreakdown) {
        self.input -= o.input;
        self.cache_write_5m -= o.cache_write_5m;
        self.cache_write_1h -= o.cache_write_1h;
        self.cache_write_unsplit -= o.cache_write_unsplit;
        self.cache_read -= o.cache_read;
        self.output -= o.output;
        self.web_search -= o.web_search;
    }
}

/// Where costs came from: list prices, a user's price file, or the harness's
/// own recorded accounting. The UI says which rather than implying a bill.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum PriceSource {
    Builtin,
    UserFile,
    Harness,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum Attribution {
    /// The harness told us (Claude's `~/.claude/sessions/<pid>.json`).
    HarnessRegistry,
    /// A `--resume <id>` style argument on the command line.
    CommandLine,
    /// The process has the transcript open (Codex keeps every live thread's
    /// rollout open); exact.
    OpenFile,
    /// Matched by working directory and start time; may be wrong with concurrent sessions.
    CwdHeuristic,
    /// No transcript found; process only.
    None,
    /// No process; transcript only.
    TranscriptOnly,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct HostStats {
    pub hostname: Option<String>,
    pub cpu_percent: f32,
    pub cpu_count: usize,
    pub mem_used_bytes: u64,
    pub mem_total_bytes: u64,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct Totals {
    pub agents: usize,
    pub running: usize,
    pub idle: usize,
    pub stopped: usize,
    pub tokens: u64,
    pub cost_usd: f64,
    pub unpriced_tokens: u64,
    pub processes: usize,
    pub mcp_processes: usize,
    pub orphaned_mcp: usize,
    pub cpu_percent: f32,
    pub rss_bytes: u64,
}

/// Version of the `--json` document. Bumped when a field changes meaning or
/// disappears; new fields alone do not bump it.
pub const SNAPSHOT_SCHEMA_VERSION: u32 = 1;

/// What the collector remembers about an orphaned MCP process: when it first
/// saw it, and, if it watched the process lose its parent, which agent that
/// was. Memory lasts for the run; a process that was already an orphan when
/// agent-top started has no parent on record.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct OrphanOrigin {
    pub pid: u32,
    pub first_seen: SystemTime,
    /// When the process was first seen without its parent, if the parent was
    /// seen before that.
    pub orphaned_at: Option<SystemTime>,
    pub parent: Option<OrphanParent>,
}

/// The agent an orphan used to belong to.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct OrphanParent {
    pub pid: u32,
    pub agent_id: String,
    pub name: String,
}

/// Which rule a piece of advice came from. See `advice`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum AdviceRule {
    /// A tool or MCP server whose results are large per call and have been
    /// re-read on every response since: the biggest line in the bill hiding
    /// behind a few calls.
    ExpensiveSource,
    /// An MCP server attached to a live agent that has answered no calls in
    /// a long while.
    IdleMcpServer,
    /// An MCP server whose memory has climbed steadily with no calls to
    /// explain it.
    GrowingMcpServer,
}

impl AdviceRule {
    pub fn label(self) -> &'static str {
        match self {
            AdviceRule::ExpensiveSource => "expensive source",
            AdviceRule::IdleMcpServer => "idle mcp server",
            AdviceRule::GrowingMcpServer => "growing mcp server",
        }
    }
}

/// One sentence of advice about one agent, with the numbers that back it and
/// the thing you could do. Nothing is done for you: agent-top only points.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct Advice {
    pub agent_id: String,
    pub agent_name: String,
    pub rule: AdviceRule,
    /// The tool, or the MCP server, the advice is about.
    pub subject: String,
    /// The server's process, when the advice is about one.
    pub pid: Option<u32>,
    /// What was seen, with its numbers.
    pub headline: String,
    /// What you might do about it.
    pub action: String,
    /// The evidence as numbers, for scripts: zero where a rule has none.
    #[serde(default)]
    pub cost_usd: f64,
    #[serde(default)]
    pub tokens: u64,
    #[serde(default)]
    pub calls: u64,
    #[serde(default)]
    pub rss_bytes: u64,
}

/// Everything the UI needs for one frame.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Snapshot {
    pub schema_version: u32,
    pub taken_at: SystemTime,
    pub host: HostStats,
    pub agents: Vec<Agent>,
    /// MCP-looking processes with no live agent ancestor: leak candidates.
    pub orphans: Vec<ProcNode>,
    /// One entry per orphan, saying where it came from when that is known.
    #[serde(default)]
    pub orphan_origins: Vec<OrphanOrigin>,
    /// What looks like a bad deal on this machine right now, and what could
    /// be done about it. See `advice`.
    #[serde(default)]
    pub advice: Vec<Advice>,
    pub totals: Totals,
}

impl Snapshot {
    pub fn compute_totals(&mut self) {
        let mut t = Totals::default();
        for a in &self.agents {
            t.agents += 1;
            match a.state {
                AgentState::Running => t.running += 1,
                AgentState::Idle => t.idle += 1,
                AgentState::Stopped => t.stopped += 1,
            }
            t.tokens += a.usage.total();
            t.cost_usd += a.cost_usd;
            t.unpriced_tokens += a.unpriced_tokens;
            t.processes += a.process_count;
            t.mcp_processes += a.mcp_count;
            t.cpu_percent += a.cpu_percent;
            t.rss_bytes += a.rss_bytes;
        }
        t.orphaned_mcp = self.orphans.len();
        self.totals = t;
    }
}

#[cfg(test)]
mod usage_tests {
    use super::TokenUsage;

    #[test]
    fn cache_hit_rate_is_reads_over_the_prompt() {
        let u = TokenUsage { input: 200, cache_read: 800, output: 50, ..Default::default() };
        // Prompt is 1000 (output excluded); 800 of it from cache.
        assert_eq!(u.prompt(), 1000);
        assert!((u.cache_hit_rate().unwrap() - 0.8).abs() < 1e-9);
        // A cache write counts as prompt input, not as a hit.
        let u = TokenUsage { input: 100, cache_write_5m: 900, ..Default::default() };
        assert_eq!(u.cache_hit_rate(), Some(0.0));
        // Nothing to judge.
        assert_eq!(TokenUsage::default().cache_hit_rate(), None);
    }
}