ski/

status.rs

//! `ski status` — a plain-language readout of what ski actually did in your
//! recent conversations. ski's hot path is deliberately silent (it never prints
//! into your session), so without this the only "is it helping me?" answers are
//! `ski doctor` ("is it wired?") and `ski history` ("what did telemetry log?" —
//! empty unless you opted in). This fills the gap in between: it reads the
//! per-session dedup ledgers ([`crate::session`]) that ski writes on **every**
//! prompt regardless of telemetry, and turns them into three counts a user
//! cares about —
//!
//! - **assists**: ski surfaced a skill and the model then invoked it (the win);
//! - **surfaced, unused**: ski put a skill forward the model didn't reach for;
//! - **self-loads**: the model found a skill on its own while ski stayed silent
//!   (a recall miss — where ski could do better).
//!
//! The classification is a heuristic over the ledger's `(source, confidence)`
//! record: a `Model` load carries a non-zero confidence only if ski had
//! recommended it first (see [`crate::session::Session::mark_used`]), so
//! `Model` + confidence 0 is a genuine self-load, and `Model` + confidence > 0 is
//! an assist. [`summarize`] is pure and unit-tested; only [`run`] touches disk,
//! and (like every read path in ski) it fails open — an unreadable or malformed
//! ledger is skipped, never fatal.

use crate::session::{Record, Session, Source};
use std::time::{SystemTime, UNIX_EPOCH};

/// How ski's ledger explains one skill's presence in a conversation.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Kind {
    /// ski surfaced it and the model then invoked it — the outcome ski exists for.
    Assist,
    /// ski surfaced it; the model hasn't invoked it (ignored, or simply not needed).
    Surfaced,
    /// The model loaded it on its own while ski stayed silent — a recall miss.
    SelfLoad,
}

/// One skill's line in a session summary.
#[derive(Clone, Debug, PartialEq)]
pub struct SkillRow {
    pub id: String,
    pub kind: Kind,
    /// The confidence ski last showed for it (0.0 for a pure self-load).
    pub confidence: f32,
}

/// One conversation's summary, newest-first in the [`Report`].
#[derive(Clone, Debug, PartialEq)]
pub struct SessionRow {
    pub id: String,
    /// Unix seconds of the ledger's last write (from [`Session::updated`]).
    pub updated: u64,
    pub skills: Vec<SkillRow>,
}

/// The whole readout: recency-ordered per-session rows plus aggregate counts
/// taken over *every* session on record (not just the displayed ones).
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Report {
    pub sessions: Vec<SessionRow>,
    /// Total conversations with a ledger on disk.
    pub total_sessions: usize,
    /// Skills ski surfaced (assists + surfaced-unused), across all sessions.
    pub surfaced: u64,
    /// Of those, the ones the model then invoked.
    pub assisted: u64,
    /// Skills the model loaded itself while ski stayed silent.
    pub self_loads: u64,
}

fn classify(r: &Record) -> Kind {
    match r.source {
        Source::Ski => Kind::Surfaced,
        // A model load keeps any confidence ski had shown; a non-zero value means
        // ski recommended it first (an assist), zero means a genuine self-load.
        Source::Model if r.confidence > 0.0 => Kind::Assist,
        Source::Model => Kind::SelfLoad,
    }
}

/// Rank kinds for display: assists first (the wins), then surfaced-unused, then
/// self-loads.
fn kind_order(k: Kind) -> u8 {
    match k {
        Kind::Assist => 0,
        Kind::Surfaced => 1,
        Kind::SelfLoad => 2,
    }
}

/// Turn loaded ledgers into a [`Report`]. Pure — the caller supplies
/// `(session_id, Session)` pairs (from disk in [`run`], hand-built in tests).
/// Sessions are ordered newest-first by `updated`; `limit` caps how many appear
/// in `sessions`, but the aggregate counts span all of them.
pub fn summarize(mut sessions: Vec<(String, Session)>, limit: usize) -> Report {
    let mut report = Report {
        total_sessions: sessions.len(),
        ..Report::default()
    };
    // Aggregate over every session before truncating the displayed set.
    for (_, s) in &sessions {
        for r in s.loaded.values() {
            match classify(r) {
                Kind::Assist => {
                    report.surfaced += 1;
                    report.assisted += 1;
                }
                Kind::Surfaced => report.surfaced += 1,
                Kind::SelfLoad => report.self_loads += 1,
            }
        }
    }

    // Newest first; ties broken by id so the order is deterministic.
    sessions.sort_by(|a, b| b.1.updated.cmp(&a.1.updated).then(a.0.cmp(&b.0)));
    sessions.truncate(limit);

    for (id, s) in sessions {
        let mut skills: Vec<SkillRow> = s
            .loaded
            .iter()
            .map(|(sid, r)| SkillRow {
                id: sid.clone(),
                kind: classify(r),
                confidence: r.confidence,
            })
            .collect();
        // Assists, then surfaced, then self-loads; within a kind, higher
        // confidence first, then id for stability.
        skills.sort_by(|a, b| {
            kind_order(a.kind)
                .cmp(&kind_order(b.kind))
                .then(
                    b.confidence
                        .partial_cmp(&a.confidence)
                        .unwrap_or(std::cmp::Ordering::Equal),
                )
                .then(a.id.cmp(&b.id))
        });
        report.sessions.push(SessionRow {
            id,
            updated: s.updated,
            skills,
        });
    }
    report
}

/// `ski status`: scan the session ledgers and print the readout. `limit` caps
/// the number of conversations shown (aggregate counts still span all).
pub fn run(limit: usize) -> anyhow::Result<()> {
    let dir = crate::paths::sessions_dir();
    let mut sessions: Vec<(String, Session)> = Vec::new();
    if let Ok(entries) = std::fs::read_dir(&dir) {
        for entry in entries.flatten() {
            let path = entry.path();
            if path.extension().and_then(|e| e.to_str()) != Some("json") {
                continue;
            }
            // Skip a session with an empty ledger (e.g. one re-armed on compaction):
            // it has nothing to report and would just add noise.
            let session = Session::load(&path);
            if session.loaded.is_empty() {
                continue;
            }
            let id = path
                .file_stem()
                .and_then(|s| s.to_str())
                .unwrap_or("?")
                .to_string();
            sessions.push((id, session));
        }
    }

    let report = summarize(sessions, limit);
    print_report(&report, limit, &dir);
    Ok(())
}

fn print_report(report: &Report, limit: usize, dir: &std::path::Path) {
    if report.total_sessions == 0 {
        println!(
            "no conversations on record yet — ski logs activity per session as you \
             use it.\ncheck back after a few prompts (state dir: {})",
            tilde(dir)
        );
        return;
    }

    let convo = if report.total_sessions == 1 {
        "conversation"
    } else {
        "conversations"
    };
    println!(
        "ski activity — {} {} on record ({})\n",
        report.total_sessions,
        convo,
        tilde(dir)
    );

    // Aggregate headline. Lead with the win (assists), then the two ways ski and
    // the model can diverge.
    println!(
        "  {:>4}  skills ski surfaced that the model then invoked   (assists)",
        report.assisted
    );
    println!(
        "  {:>4}  skills ski surfaced the model didn't invoke",
        report.surfaced.saturating_sub(report.assisted)
    );
    println!(
        "  {:>4}  skills the model found itself, ski stayed silent  (recall misses)",
        report.self_loads
    );

    if report.sessions.is_empty() {
        return;
    }

    let shown = report.sessions.len();
    let more = report.total_sessions.saturating_sub(shown);
    println!("\n  recent conversations (newest first):");
    for s in &report.sessions {
        println!("\n  {}   {}", s.id, ago(s.updated));
        for sk in &s.skills {
            let (tag, note) = match sk.kind {
                Kind::Assist => (
                    "used",
                    format!("surfaced at {:.2}, model invoked it", sk.confidence),
                ),
                Kind::Surfaced => (
                    "sent",
                    format!("surfaced at {:.2}, not invoked", sk.confidence),
                ),
                Kind::SelfLoad => ("miss", "model loaded it, ski was silent".to_string()),
            };
            println!("    {tag}  {:<26}  {note}", sk.id);
        }
    }
    if more > 0 {
        let hint = if limit == usize::MAX {
            String::new()
        } else {
            format!(
                " (raise --limit, or --limit {} for all)",
                report.total_sessions
            )
        };
        println!(
            "\n  … and {} older conversation{}{}",
            more,
            if more == 1 { "" } else { "s" },
            hint
        );
    }
    println!(
        "\n  legend: used = ski assist · sent = surfaced, unused · miss = self-load\n  \
         for prompt-level detail, enable telemetry then see `ski history` / `ski suggest`."
    );
}

/// Coarse "time since" for a Unix-seconds stamp. Diagnostics only, so an
/// out-of-range or clock-skewed value degrades to "just now" rather than
/// underflowing.
fn ago(updated: u64) -> String {
    let now = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0);
    let secs = now.saturating_sub(updated);
    if updated == 0 {
        "time unknown".to_string()
    } else if secs < 90 {
        "just now".to_string()
    } else if secs < 3600 {
        format!("{}m ago", secs / 60)
    } else if secs < 86_400 {
        format!("{}h ago", secs / 3600)
    } else {
        format!("{}d ago", secs / 86_400)
    }
}

/// Shorten a path under `$HOME` to `~/…` for display (mirrors `doctor::tilde`).
fn tilde(path: &std::path::Path) -> String {
    if let Some(home) = std::env::var_os("HOME") {
        if let Ok(rest) = path.strip_prefix(&home) {
            return format!("~/{}", rest.display());
        }
    }
    path.display().to_string()
}

#[cfg(test)]
mod tests {
    use super::*;

    fn ski(conf: f32) -> Record {
        Record {
            source: Source::Ski,
            confidence: conf,
        }
    }
    fn model(conf: f32) -> Record {
        Record {
            source: Source::Model,
            confidence: conf,
        }
    }

    fn session(updated: u64, loaded: &[(&str, Record)]) -> Session {
        Session {
            loaded: loaded.iter().map(|(k, v)| (k.to_string(), *v)).collect(),
            updated,
            ..Session::default()
        }
    }

    #[test]
    fn classify_distinguishes_assist_from_self_load() {
        // Ski recommendation the model hasn't used -> surfaced.
        assert_eq!(classify(&ski(0.7)), Kind::Surfaced);
        // Model load carrying a prior recommendation's confidence -> assist.
        assert_eq!(classify(&model(0.7)), Kind::Assist);
        // Model load with no prior recommendation -> genuine self-load.
        assert_eq!(classify(&model(0.0)), Kind::SelfLoad);
    }

    #[test]
    fn summarize_counts_across_all_sessions() {
        let sessions = vec![
            (
                "s1".to_string(),
                session(100, &[("xlsx", model(0.8)), ("pdf", ski(0.6))]),
            ),
            (
                "s2".to_string(),
                session(200, &[("git-attribution", model(0.0))]),
            ),
        ];
        let r = summarize(sessions, 10);
        assert_eq!(r.total_sessions, 2);
        assert_eq!(r.assisted, 1); // xlsx
        assert_eq!(r.surfaced, 2); // xlsx (assist) + pdf (surfaced)
        assert_eq!(r.self_loads, 1); // git-attribution
    }

    #[test]
    fn aggregate_spans_all_sessions_even_when_display_is_limited() {
        let sessions = vec![
            ("a".to_string(), session(1, &[("one", model(0.9))])),
            ("b".to_string(), session(2, &[("two", model(0.9))])),
            ("c".to_string(), session(3, &[("three", model(0.9))])),
        ];
        let r = summarize(sessions, 1);
        // Only the newest session is displayed...
        assert_eq!(r.sessions.len(), 1);
        assert_eq!(r.sessions[0].id, "c");
        // ...but the counts still cover all three.
        assert_eq!(r.assisted, 3);
        assert_eq!(r.total_sessions, 3);
    }

    #[test]
    fn sessions_are_newest_first() {
        let sessions = vec![
            ("old".to_string(), session(10, &[("x", ski(0.5))])),
            ("new".to_string(), session(99, &[("y", ski(0.5))])),
        ];
        let r = summarize(sessions, 10);
        assert_eq!(r.sessions[0].id, "new");
        assert_eq!(r.sessions[1].id, "old");
    }

    #[test]
    fn skills_sorted_assist_then_surfaced_then_self_load() {
        let s = session(
            1,
            &[
                ("selfload", model(0.0)),
                ("surfaced", ski(0.9)),
                ("assist", model(0.5)),
            ],
        );
        let r = summarize(vec![("s".to_string(), s)], 10);
        let ids: Vec<&str> = r.sessions[0].skills.iter().map(|k| k.id.as_str()).collect();
        assert_eq!(ids, ["assist", "surfaced", "selfload"]);
    }

    #[test]
    fn empty_input_is_empty_report() {
        assert_eq!(summarize(Vec::new(), 10), Report::default());
    }

    #[test]
    fn ago_handles_zero_and_recent() {
        assert_eq!(ago(0), "time unknown");
        let now = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_secs();
        assert_eq!(ago(now), "just now");
        assert_eq!(ago(now.saturating_sub(7200)), "2h ago");
    }
}