Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
19.7 KB
Raw Blame
//! `ai-memory purge-session` — thin HTTP client for single-session purge.

use anyhow::{Result, bail};
use serde::Serialize;

use crate::cli::PurgeSessionArgs;
use crate::commands::purge_preview::{PreviewOutcome, refused_message, run_preview};
use crate::config::Config;
use crate::http_client::{ServerEndpoint, post_json};

/// Request sent to `POST /admin/purge-session`.
#[derive(Serialize)]
struct PurgeSessionRequest {
    workspace: String,
    project: String,
    session_id: String,
    confirm: bool,
    /// Rebuild the FTS indexes and VACUUM after the delete commits.
    compact: bool,
    /// Preview only: wins over `confirm` on the server (mirrors
    /// `purge-project`, which itself mirrors `reclaim-ledger-versions`), so
    /// this is always sent alongside `confirm: false` here — never both
    /// true. Older servers that predate this field simply never look at it
    /// (an unknown JSON field is not a deserialize error), which is why the
    /// fallback in [`purge_preview::run_preview`](crate::commands::purge_preview::run_preview)
    /// only has to handle the request failing outright, never the field
    /// being silently misread.
    dry_run: bool,
}

/// One line naming what a session purge (real or previewed) removed, in the
/// fixed order the operator can grep for: observations, handoffs, pages,
/// auto-improve runs. `verb` is `"Purged"` for a confirmed run or `"Would
/// purge"` for a preview — everything else about the line is identical, so a
/// script matching one also matches the other.
///
/// The session id is deliberately never part of this line, confirmed or
/// previewed: the caller already has it (they passed `--session-id`), and
/// this command exists to make a session stop existing — echoing its id
/// into terminal scrollback and shell history leaves a pointer to the thing
/// just erased (or about to be). The scope (`label`) and the counts are what
/// confirm the operation did, or would do, what was asked.
fn purge_summary_line(verb: &str, label: &str, report: &serde_json::Value) -> String {
    let observations = report["observations_deleted"].as_u64().unwrap_or(0);
    let handoffs = report["handoffs_deleted"].as_u64().unwrap_or(0);
    let pages = report["pages_deleted"].as_u64().unwrap_or(0);
    let auto_improve_runs = report["auto_improve_runs_deleted"].as_u64().unwrap_or(0);
    let mut line = format!(
        "{verb} session from {label}: {observations} observations, {handoffs} handoffs, \
         {pages} pages, {auto_improve_runs} auto-improve runs."
    );
    // The mirror of the incident `purge-project`'s own preview guards
    // against, one level down at session granularity: purging this session
    // also collaterally deletes/orphans rows that live in *other* projects,
    // via this session's own id (not the project's rows) cascading. Silent
    // when zero so the common case reads exactly as before.
    let collateral_observations = report["collateral_observations_deleted"]
        .as_u64()
        .unwrap_or(0);
    if collateral_observations > 0 {
        line.push_str(&format!(
            " Plus {collateral_observations} observations in other projects via this session."
        ));
    }
    let collateral_handoffs = report["collateral_handoffs_denulled"].as_u64().unwrap_or(0);
    if collateral_handoffs > 0 {
        line.push_str(&format!(
            " Plus {collateral_handoffs} handoffs in other projects that will lose their \
             session reference (set to NULL, not deleted)."
        ));
    }
    line
}

/// Decide what to print, if anything, before the refusal — pure, so it is
/// unit-tested without a server. `fallback_label` is used only when the
/// server's own report has no scope to build a label from (this endpoint has
/// no `label` field, unlike `purge-project`, so the caller always supplies
/// one built from `--workspace`/`--project`).
fn preview_message(outcome: &PreviewOutcome, label: &str) -> Option<String> {
    match outcome {
        PreviewOutcome::Previewed(report) => Some(purge_summary_line("Would purge", label, report)),
        PreviewOutcome::Refused { status, body } => Some(refused_message(*status, body)),
        PreviewOutcome::Ignored | PreviewOutcome::OlderServer | PreviewOutcome::Unreachable => None,
    }
}

/// Run the `purge-session` subcommand.
///
/// Requires the full session UUID and `--confirm`. The scope is resolved the
/// same way as every other project-scoped command, and the server refuses a
/// session that does not belong to it, so a UUID alone is never authority
/// over another workspace or project.
///
/// Without `--confirm`, first asks the server for a preview (`dry_run:
/// true`, which wins over `confirm` server-side, exactly like
/// `purge-project`): the server reports the counts a confirmed purge would
/// produce without deleting anything. That preview is best-effort, bounded
/// by
/// [`purge_preview::PREVIEW_TIMEOUT`](crate::commands::purge_preview::PREVIEW_TIMEOUT),
/// and never changes the outcome — only what gets printed before it:
/// - a successful preview prints the "Would purge session from ..." line;
/// - a 404/403 (or any other unexpected status) prints the server's own
///   error first, since the operator asked what would happen and the server
///   has an answer, just not the one this command expected;
/// - a plain 400 (an older server that predates `dry_run`), a timeout, or an
///   unreachable server print nothing extra — the refusal below already
///   says everything a 400 would.
///
/// # Errors
/// Returns an error when `--confirm` is absent, the session id is not a
/// UUID, the server is unreachable, or the server returns a non-2xx
/// response (including `404` for a session outside the named scope).
pub async fn run(config: &Config, args: PurgeSessionArgs) -> Result<()> {
    super::refuse_empty_explicit(args.workspace.as_deref(), "--workspace")?;
    super::refuse_empty_explicit(args.project.as_deref(), "--project")?;
    let (workspace, project) =
        super::resolve_scope(config, args.workspace.as_deref(), args.project.as_deref())?;

    // Validate locally so an obvious typo fails before anything destructive
    // is sent. The server validates again — this is convenience, not the
    // security boundary.
    let session_id = args.session_id.trim();
    if uuid::Uuid::parse_str(session_id).is_err() {
        bail!(
            "`--session-id {session_id}` is not a UUID. Pass the full \
             `sessions.id` value; a prefix or a workstream id will not match."
        );
    }

    let label = format!("{workspace}/{project}");

    if !args.confirm {
        let request = PurgeSessionRequest {
            workspace: workspace.clone(),
            project: project.clone(),
            session_id: session_id.to_owned(),
            confirm: false,
            compact: args.compact,
            dry_run: true,
        };
        let outcome = run_preview(config, "/admin/purge-session", &request).await;
        if let Some(line) = preview_message(&outcome, &label) {
            println!("{line}");
        }
        bail!(
            "purge-session is destructive and irreversible.\n\
             Re-run with --confirm to proceed:\n\n  \
             ai-memory purge-session --workspace {workspace} --project {project} \
             --session-id {session_id} --confirm",
        );
    }

    let endpoint = ServerEndpoint::from_config_resolving_auth(config).await;
    let report: serde_json::Value = post_json(
        &endpoint,
        "/admin/purge-session",
        &PurgeSessionRequest {
            workspace: workspace.clone(),
            project: project.clone(),
            session_id: session_id.to_owned(),
            confirm: true,
            compact: args.compact,
            dry_run: false,
        },
    )
    .await?;

    println!("{}", purge_summary_line("Purged", &label, &report));
    if let Some(paths) = report["files_deleted"].as_array()
        && !paths.is_empty()
    {
        println!("Wiki pages removed:");
        for path in paths.iter().filter_map(serde_json::Value::as_str) {
            println!("  - {path}");
        }
    }
    if let Some(failed) = report["files_failed"].as_array()
        && !failed.is_empty()
    {
        println!(
            "Warning: {} wiki page file(s) could not be removed from disk (DB rows are gone).",
            failed.len()
        );
        for path in failed.iter().filter_map(serde_json::Value::as_str) {
            println!("  - {path}");
        }
    }
    if report["compacted"].as_bool().unwrap_or(false) {
        println!("Database compacted: freed bytes reclaimed.");
    } else {
        println!(
            "Note: this was a logical delete. The session is unreachable through \
             the API and search, but its bytes remain in the database file until \
             it is rewritten. Re-run with --compact to reclaim them (slow), and \
             see `docs/` for what that does and does not guarantee."
        );
    }
    Ok(())
}

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

    fn report(dry_run: bool) -> serde_json::Value {
        serde_json::json!({
            "session_id": "00000000-0000-0000-0000-000000000000",
            "workspace": "default",
            "project": "my-project",
            "observations_deleted": 1063,
            "handoffs_deleted": 0,
            "pages_deleted": 1,
            "auto_improve_runs_deleted": 2,
            "removed_paths": [],
            "collateral_observations_deleted": 0,
            "collateral_handoffs_denulled": 0,
            "files_deleted": [],
            "files_failed": [],
            "compacted": false,
            "dry_run": dry_run,
        })
    }

    /// Pins the exact wording and field order a script would grep for, and
    /// that the session id never appears in it.
    /// `purge_summary_line` is the single source for both the confirmed
    /// "Purged" line and the preview's "Would purge" line, so this also
    /// proves the two can never drift apart.
    #[test]
    fn purge_summary_line_matches_the_documented_wording() {
        let confirmed = report(false);
        let line = purge_summary_line("Purged", "default/my-project", &confirmed);
        assert_eq!(
            line,
            "Purged session from default/my-project: 1063 observations, 0 handoffs, \
             1 pages, 2 auto-improve runs."
        );
        assert!(
            !line.contains("00000000"),
            "the session id must never appear in the printed line: {line}"
        );

        let preview = report(true);
        assert_eq!(
            purge_summary_line("Would purge", "default/my-project", &preview),
            "Would purge session from default/my-project: 1063 observations, 0 handoffs, \
             1 pages, 2 auto-improve runs."
        );
    }

    /// Missing counters must not panic and must not silently show as
    /// non-zero.
    #[test]
    fn purge_summary_line_defaults_missing_counters_to_zero() {
        let empty = serde_json::json!({});
        assert_eq!(
            purge_summary_line("Would purge", "default/x", &empty),
            "Would purge session from default/x: 0 observations, 0 handoffs, \
             0 pages, 0 auto-improve runs."
        );
    }

    /// The mirror-of-the-incident collateral counts, when present, must be
    /// visible in the same line the operator already reads — silent when
    /// zero (the common case), spelled out when not.
    #[test]
    fn purge_summary_line_calls_out_collateral_damage_when_present() {
        let mut r = report(true);
        r["collateral_observations_deleted"] = serde_json::json!(7);
        r["collateral_handoffs_denulled"] = serde_json::json!(2);
        let line = purge_summary_line("Would purge", "default/looks-empty", &r);
        assert!(
            line.contains("Plus 7 observations in other projects via this session."),
            "collateral observations must be called out: {line}"
        );
        assert!(
            line.contains("Plus 2 handoffs in other projects"),
            "collateral handoffs must be called out: {line}"
        );
    }

    /// A successful preview prints the "Would purge" line.
    #[test]
    fn preview_message_prints_the_would_purge_line_on_success() {
        let outcome = PreviewOutcome::Previewed(report(true));
        let msg = preview_message(&outcome, "default/my-project").expect("must print a line");
        assert!(msg.starts_with("Would purge session from default/my-project:"));
    }

    /// A 404 (session outside the named scope) is worth showing before the
    /// refusal: the operator asked what would happen, and 404 is the
    /// server's answer.
    #[test]
    fn preview_message_surfaces_a_404_before_the_refusal() {
        let outcome = PreviewOutcome::Refused {
            status: 404,
            body: r#"{"error":"session ... not found in this workspace/project"}"#.to_string(),
        };
        let msg = preview_message(&outcome, "default/ghost").expect("must print a line");
        assert_eq!(
            msg,
            "Preview refused (404): session ... not found in this workspace/project"
        );
    }

    /// A body that isn't the expected `{"error": ...}` shape still prints
    /// something rather than nothing — the raw body, verbatim.
    #[test]
    fn preview_message_falls_back_to_the_raw_body_when_not_json() {
        let outcome = PreviewOutcome::Refused {
            status: 403,
            body: "Forbidden".to_string(),
        };
        let msg = preview_message(&outcome, "default/x").expect("must print a line");
        assert_eq!(msg, "Preview refused (403): Forbidden");
    }

    /// The three silent-fallback cases: an older server's plain 400, a
    /// timeout/connect failure, and a 200 that oddly never set `dry_run`.
    #[test]
    fn preview_message_is_silent_for_older_server_unreachable_and_ignored() {
        assert!(preview_message(&PreviewOutcome::OlderServer, "default/x").is_none());
        assert!(preview_message(&PreviewOutcome::Unreachable, "default/x").is_none());
        assert!(preview_message(&PreviewOutcome::Ignored, "default/x").is_none());
    }

    // -----------------------------------------------------------------
    // `run_preview` against a real (local) server: proves the HTTP-status
    // classification end to end, not just the pure `preview_message` mapping
    // above.
    // -----------------------------------------------------------------

    fn config_for(tmp: &tempfile::TempDir, server_url: String) -> Config {
        Config {
            data_dir: tmp.path().to_path_buf(),
            server_url,
            ..Config::default()
        }
    }

    async fn spawn_fixed_response(status: u16, body: &'static str) -> String {
        let app = axum::Router::new().route(
            "/admin/purge-session",
            axum::routing::post(move || async move {
                (
                    axum::http::StatusCode::from_u16(status).unwrap(),
                    axum::Json(serde_json::from_str::<serde_json::Value>(body).unwrap()),
                )
            }),
        );
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move {
            axum::serve(listener, app).await.unwrap();
        });
        format!("http://{addr}")
    }

    fn preview_request() -> PurgeSessionRequest {
        PurgeSessionRequest {
            workspace: "default".into(),
            project: "scratch".into(),
            session_id: "00000000-0000-0000-0000-000000000000".into(),
            confirm: false,
            compact: false,
            dry_run: true,
        }
    }

    /// An older server that predates `dry_run` answers the plain 400
    /// "confirm=true" refusal it always has — the CLI must fall back
    /// silently, not print anything extra.
    #[tokio::test]
    async fn run_preview_classifies_a_400_as_older_server() {
        let tmp = tempfile::TempDir::new().unwrap();
        let url = spawn_fixed_response(
            400,
            r#"{"error": "destructive operation requires confirm=true"}"#,
        )
        .await;
        let config = config_for(&tmp, url);
        let outcome = run_preview(&config, "/admin/purge-session", &preview_request()).await;
        assert!(matches!(outcome, PreviewOutcome::OlderServer));
        assert!(preview_message(&outcome, "default/scratch").is_none());
    }

    /// A 404 is surfaced: the operator asked what a purge of this session
    /// would do, and "no such session" is a real, useful answer.
    #[tokio::test]
    async fn run_preview_classifies_a_404_as_refused_and_surfaces_the_message() {
        let tmp = tempfile::TempDir::new().unwrap();
        let url = spawn_fixed_response(
            404,
            r#"{"error": "session ... not found in this workspace/project"}"#,
        )
        .await;
        let config = config_for(&tmp, url);
        let outcome = run_preview(&config, "/admin/purge-session", &preview_request()).await;
        match &outcome {
            PreviewOutcome::Refused { status, body } => {
                assert_eq!(*status, 404);
                assert!(body.contains("not found"));
            }
            _ => panic!("expected Refused, got a different outcome"),
        }
        let msg = preview_message(&outcome, "default/scratch").expect("must print a line");
        assert_eq!(
            msg,
            "Preview refused (404): session ... not found in this workspace/project"
        );
    }

    /// A successful preview (200, `dry_run: true`) is a `Previewed` outcome
    /// carrying the report through untouched.
    #[tokio::test]
    async fn run_preview_classifies_a_successful_preview() {
        let tmp = tempfile::TempDir::new().unwrap();
        let url = spawn_fixed_response(
            200,
            r#"{"session_id": "00000000-0000-0000-0000-000000000000", "workspace": "default",
                "project": "scratch", "observations_deleted": 1063, "handoffs_deleted": 0,
                "pages_deleted": 1, "auto_improve_runs_deleted": 2, "removed_paths": [],
                "collateral_observations_deleted": 0, "collateral_handoffs_denulled": 0,
                "files_deleted": [], "files_failed": [], "compacted": false, "dry_run": true}"#,
        )
        .await;
        let config = config_for(&tmp, url);
        let outcome = run_preview(&config, "/admin/purge-session", &preview_request()).await;
        let msg = preview_message(&outcome, "default/scratch").expect("must print a line");
        assert!(msg.starts_with("Would purge session from default/scratch: 1063 observations"));
    }

    /// A dropped connection must classify as `Unreachable`, the same as a
    /// timeout — both are silent fallbacks.
    #[tokio::test]
    async fn run_preview_classifies_a_dropped_connection_as_unreachable() {
        let tmp = tempfile::TempDir::new().unwrap();
        // Own the endpoint until the request arrives; releasing a reserved
        // port first lets another concurrent test answer the preview instead.
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        let server = tokio::spawn(async move {
            use tokio::io::AsyncReadExt;

            let (mut stream, _) = listener.accept().await.unwrap();
            let mut request = [0; 1024];
            assert!(stream.read(&mut request).await.unwrap() > 0);
            // Close after receiving the request, without an HTTP response.
        });
        let config = config_for(&tmp, format!("http://{addr}"));
        let outcome = run_preview(&config, "/admin/purge-session", &preview_request()).await;
        assert!(matches!(outcome, PreviewOutcome::Unreachable));
        assert!(preview_message(&outcome, "default/scratch").is_none());
        tokio::time::timeout(std::time::Duration::from_secs(1), server)
            .await
            .expect("the preview must reach the fixture")
            .unwrap();
    }
}