Skip to content

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

Rust
21.8 KB
Raw Blame
//! `ai-memory finalize-session` — manually synthesize SessionEnd for an agent.

use std::path::Path;

use ai_memory_core::{AgentKind, SessionId};
use ai_memory_workstream::ManagedHarness;
use anyhow::{Context, Result, bail};
use serde::{Deserialize, Serialize};

use crate::cli::FinalizeSessionArgs;
use crate::config::Config;
use crate::http_client::{ServerEndpoint, ServerResponseError, get_json};

#[derive(Debug, Serialize)]
struct SessionEndPayload<'a> {
    session_id: String,
    cwd: &'a str,
}

#[derive(Debug, Serialize)]
struct HookBatchItem<'a> {
    url: String,
    body: SessionEndPayload<'a>,
}

#[derive(Debug, Deserialize)]
struct HookBatchAck {
    accepted: usize,
}

/// Response shape of `GET /admin/open-sessions` on the server.
#[derive(Debug, Deserialize)]
struct OpenSessionsResponse {
    sessions: Vec<OpenSessionEntry>,
}

/// One open session as reported by `GET /admin/open-sessions`.
#[derive(Debug, Deserialize)]
struct OpenSessionEntry {
    session_id: String,
    cwd: Option<String>,
}

#[derive(Debug, Serialize, Deserialize)]
struct FinalizeSessionReport {
    workspace: String,
    project: String,
    agent: String,
    finalized: Vec<String>,
}

/// Run the `finalize-session` subcommand.
///
/// # Errors
/// Returns an error if an explicit scope flag is empty, the configured server
/// cannot list the scope's open sessions, or the server rejects a synthetic
/// `session-end` hook.
pub async fn run(config: &Config, args: FinalizeSessionArgs) -> Result<()> {
    let (workspace, project, finalized) = finalize(config, &args).await?;
    let agent = args.agent;
    print_report(args, workspace, project, agent, finalized)
}

/// Finalizes the sessions `args` selects (open ones, plus the exact ended
/// session with `reopen`) and returns the scope and the ids it sent a
/// session-end for, without printing; `ai-memory run` reports on its own.
pub(crate) async fn finalize(
    config: &Config,
    args: &FinalizeSessionArgs,
) -> Result<(String, String, Vec<String>)> {
    super::refuse_empty_explicit(args.workspace.as_deref(), "--workspace")?;
    super::refuse_empty_explicit(args.project.as_deref(), "--project")?;
    let agent = args.agent;
    let (workspace, project) =
        super::resolve_scope(config, args.workspace.as_deref(), args.project.as_deref())?;
    let endpoint = ServerEndpoint::from_config_resolving_auth(config).await;
    let sessions = fetch_open_sessions(
        &endpoint,
        &workspace,
        &project,
        agent,
        args.all,
        args.all_owners,
        args.session_id,
        args.reopen,
    )
    .await?;
    if sessions.is_empty() {
        return Ok((workspace, project, Vec::new()));
    }

    let client = reqwest::Client::new();
    let fallback_cwd = effective_cwd(config)?;
    let mut finalized = Vec::with_capacity(sessions.len());
    for session in &sessions {
        if replays_prompts(agent, args.all_owners) {
            let cwd = session.cwd.as_deref().unwrap_or(fallback_cwd.as_str());
            replay_prompts(
                config,
                &endpoint,
                &workspace,
                &project,
                cwd,
                &session.session_id,
            )
            .await;
        }
        post_session_end_batch(
            &client,
            &endpoint,
            session,
            fallback_cwd.as_str(),
            &workspace,
            &project,
            agent,
            args.all_owners,
        )
        .await?;
        finalized.push(session.session_id.clone());
    }

    // Agents with hook-maintained session state (ZCode: no SessionEnd event)
    // keep a stored id in `<data_dir>/hook-state/<agent>-session-id`; once the
    // session is finalized server-side, the stored id must go too, or the next
    // agent session would inherit the closed id.
    super::hook::clear_session_id(&config.data_dir, agent);

    Ok((workspace, project, finalized))
}

/// Antigravity's hooks carry no prompt event. Current native hooks recover
/// prompts from the conversation's transcript; for a session they did not
/// (shell hooks, an older install), `agy`'s `history.jsonl` has them. Other
/// agents capture prompts live. `--all-owners` finalizes sessions owned by
/// other users, whose prompts this machine's history does not hold.
fn replays_prompts(agent: AgentKind, all_owners: bool) -> bool {
    agent == AgentKind::AntigravityCli && !all_owners
}

/// Send the session's prompts from the local transcript before its
/// session-end, so the summary page and handoff see them. Best effort: a
/// checkout outside the capture allowlist sends none, and any failure is a
/// warning, leaving the session-end exactly as before.
async fn replay_prompts(
    config: &Config,
    endpoint: &ServerEndpoint,
    workspace: &str,
    project: &str,
    cwd: &str,
    session_id: &str,
) {
    if !super::hook::admits_capture_at(&config.data_dir, Path::new(cwd)) {
        return;
    }
    // Current hooks capture each prompt live from the conversation's
    // transcript; replaying `history.jsonl` too would store them twice.
    if super::hook::antigravity_transcript_prompts_captured(&config.data_dir, session_id) {
        return;
    }
    let Some(home) = super::run::native_home(config) else {
        eprintln!(
            "ai-memory: no home directory; session {} is finalized without its prompts",
            super::run::display_session_id(session_id)
        );
        return;
    };
    if let Err(error) = super::backfill::replay_session_prompts(
        endpoint,
        workspace,
        project,
        &home,
        Path::new(cwd),
        ManagedHarness::Antigravity,
        session_id,
    )
    .await
    {
        eprintln!(
            "ai-memory: could not replay the prompts of session {} ({error:#}); finalizing without them",
            super::run::display_session_id(session_id)
        );
    }
}

/// List open sessions for the scope + agent via the server. An unknown
/// workspace/project fails closed server-side with a 404; that maps to
/// "nothing to finalize" here, matching the previous direct-DB behavior
/// for a missing scope.
// Eight arguments is the full request shape (scope + agent + the four
// selection flags + exact id); cf. `post_session_end_batch` below.
#[allow(clippy::too_many_arguments)]
async fn fetch_open_sessions(
    endpoint: &ServerEndpoint,
    workspace: &str,
    project: &str,
    agent: AgentKind,
    all: bool,
    all_owners: bool,
    session_id: Option<SessionId>,
    include_ended: bool,
) -> Result<Vec<OpenSessionEntry>> {
    let all = if all { "true" } else { "false" };
    let all_owners = if all_owners { "true" } else { "false" };
    let include_ended = if include_ended { "true" } else { "false" };
    let mut query = vec![
        ("workspace", workspace),
        ("project", project),
        ("agent", agent.as_str()),
        ("all", all),
        ("all_owners", all_owners),
        ("include_ended", include_ended),
    ];
    let session_id = session_id.map(|sid| sid.to_string());
    if let Some(sid) = session_id.as_deref() {
        query.push(("session_id", sid));
    }
    let result = get_json::<OpenSessionsResponse>(endpoint, "/admin/open-sessions", &query).await;
    match result {
        Ok(response) => Ok(response.sessions),
        Err(e) => {
            if let Some(server_err) = e.downcast_ref::<ServerResponseError>()
                && server_err.status() == reqwest::StatusCode::NOT_FOUND
            {
                return Ok(Vec::new());
            }
            Err(e)
        }
    }
}

fn print_report(
    args: FinalizeSessionArgs,
    workspace: String,
    project: String,
    agent: AgentKind,
    finalized: Vec<String>,
) -> Result<()> {
    let report = FinalizeSessionReport {
        workspace,
        project,
        agent: agent.as_str().to_string(),
        finalized,
    };
    if args.json {
        println!("{}", serde_json::to_string_pretty(&report)?);
    } else if report.finalized.is_empty() {
        println!(
            "No open {} sessions matched {}/{}",
            report.agent, report.workspace, report.project
        );
    } else {
        println!(
            "Finalized {} {} session(s) for {}/{}",
            report.finalized.len(),
            report.agent,
            report.workspace,
            report.project
        );
        for session_id in &report.finalized {
            println!("  - {session_id}");
        }
    }
    Ok(())
}

#[allow(clippy::too_many_arguments)]
async fn post_session_end_batch(
    client: &reqwest::Client,
    endpoint: &ServerEndpoint,
    session: &OpenSessionEntry,
    fallback_cwd: &str,
    workspace: &str,
    project: &str,
    agent: AgentKind,
    all_owners: bool,
) -> Result<()> {
    let cwd = session.cwd.as_deref().unwrap_or(fallback_cwd);
    let hook_url = session_end_hook_url(endpoint, cwd, workspace, project, agent, all_owners)?;
    let batch_url = endpoint.build_url("/hook/batch");
    let items = [HookBatchItem {
        url: hook_url,
        body: SessionEndPayload {
            session_id: session.session_id.clone(),
            cwd,
        },
    }];
    let request = client.post(&batch_url).json(&items);
    let request = endpoint.authenticate(request);
    let response = request
        .send()
        .await
        .with_context(|| format!("posting synthetic session-end batch to {batch_url}"))?;
    let status = response.status();
    if !status.is_success() {
        let body = response.text().await.unwrap_or_default();
        bail!("server returned {status}: {body}");
    }
    let ack: HookBatchAck = response
        .json()
        .await
        .with_context(|| format!("parsing hook batch ack from {batch_url}"))?;
    if ack.accepted != 1 {
        bail!(
            "server accepted {} of 1 synthetic session-end events",
            ack.accepted
        );
    }
    Ok(())
}

fn session_end_hook_url(
    endpoint: &ServerEndpoint,
    cwd: &str,
    workspace: &str,
    project: &str,
    agent: AgentKind,
    all_owners: bool,
) -> Result<String> {
    let mut url = reqwest::Url::parse(&endpoint.build_url("/hook"))
        .context("building synthetic session-end hook URL")?;
    url.query_pairs_mut()
        .append_pair("event", "session-end")
        .append_pair("agent", agent.as_str())
        .append_pair("cwd", cwd)
        .append_pair("workspace", workspace)
        .append_pair("project", project);
    if all_owners {
        url.query_pairs_mut().append_pair("all_owners", "true");
    }
    Ok(url.into())
}

fn effective_cwd(config: &Config) -> Result<String> {
    if let Some(host_cwd) = config.runtime_env.host_cwd()
        && !host_cwd.trim().is_empty()
    {
        return Ok(host_cwd.to_string());
    }
    Ok(std::env::current_dir()
        .context("getting CWD for synthetic session-end")?
        .to_string_lossy()
        .into_owned())
}

#[cfg(test)]
mod tests {
    use super::*;
    use ai_memory_core::{NewSession, SessionId};
    use ai_memory_store::Store;
    use tempfile::TempDir;

    #[test]
    fn only_own_antigravity_sessions_replay_prompts() {
        assert!(replays_prompts(AgentKind::AntigravityCli, false));
        assert!(
            !replays_prompts(AgentKind::AntigravityCli, true),
            "other owners' prompts are not in this machine's history"
        );
        for agent in [AgentKind::ClaudeCode, AgentKind::Codex, AgentKind::OpenCode] {
            assert!(
                !replays_prompts(agent, false),
                "{agent:?} captures prompts live"
            );
        }
    }

    #[tokio::test]
    async fn selects_latest_scoped_session_for_requested_agent_by_default() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default".to_string())
            .await
            .unwrap();
        let target = store
            .writer
            .get_or_create_project(ws, "target".to_string(), None)
            .await
            .unwrap();
        let other_project = store
            .writer
            .get_or_create_project(ws, "other".to_string(), None)
            .await
            .unwrap();
        let older = SessionId::new();
        let latest = SessionId::new();
        let other_agent = SessionId::new();
        let other_scope = SessionId::new();
        for (id, project_id, agent) in [
            (older, target, AgentKind::AntigravityCli),
            (other_agent, target, AgentKind::Codex),
            (other_scope, other_project, AgentKind::AntigravityCli),
            (latest, target, AgentKind::AntigravityCli),
        ] {
            store
                .writer
                .begin_session(NewSession {
                    occurred_at: None,
                    id,
                    workspace_id: ws,
                    project_id,
                    agent_kind: agent,
                    cwd: Some(std::path::PathBuf::from("/tmp/target")),
                    actor_user: None,
                })
                .await
                .unwrap();
        }

        let selected = store
            .reader
            .open_sessions_for_scope_agent(
                ws,
                target,
                AgentKind::AntigravityCli,
                ai_memory_core::OwnerFilter::Any,
                Some(1),
            )
            .await
            .unwrap();

        assert_eq!(selected.len(), 1);
        assert_eq!(selected[0].session_id, latest);
    }

    /// Regression for the race a blind wrapper hits when several terminal
    /// tabs each run Kiro CLI against the same repo: two sessions for the
    /// same agent+scope are open at once (`older` started first, `latest`
    /// started after — e.g. opened in a second tab while the first was
    /// still running). Targeting `older` by its exact id must return only
    /// `older`, never falling back to "the newest open one" and closing
    /// out the still-active `latest` session instead.
    #[tokio::test]
    async fn exact_session_id_targets_that_session_even_with_a_newer_one_open() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default".to_string())
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "target".to_string(), None)
            .await
            .unwrap();
        let older = SessionId::new();
        let latest = SessionId::new();
        for id in [older, latest] {
            store
                .writer
                .begin_session(NewSession {
                    occurred_at: None,
                    id,
                    workspace_id: ws,
                    project_id: proj,
                    agent_kind: AgentKind::KiroCli,
                    cwd: Some(std::path::PathBuf::from("/tmp/target")),
                    actor_user: None,
                })
                .await
                .unwrap();
        }

        let selected = store
            .reader
            .open_session_for_scope_agent_by_id(
                ws,
                proj,
                AgentKind::KiroCli,
                ai_memory_core::OwnerFilter::Any,
                older,
                false,
            )
            .await
            .unwrap();

        assert_eq!(
            selected.map(|session| session.session_id),
            Some(older),
            "must target the requested session, not the newest open one"
        );

        // The other, still-open session must be untouched and independently
        // discoverable — proving the exact-id filter didn't just narrow the
        // default query, it left the sibling session alone.
        let still_open = store
            .reader
            .open_session_for_scope_agent_by_id(
                ws,
                proj,
                AgentKind::KiroCli,
                ai_memory_core::OwnerFilter::Any,
                latest,
                false,
            )
            .await
            .unwrap();
        assert_eq!(still_open.map(|session| session.session_id), Some(latest));
    }

    /// Regression for the Antigravity manual-finalize gap: after a first
    /// `finalize-session` closes the session, the conversation may continue
    /// and land new observations under the same id. The default discovery
    /// must keep excluding the ended session (closing something already
    /// closed stays a silent no-op), while the `--reopen` lookup
    /// (`include_ended = true`) must find it so a second finalize re-runs
    /// the session-end path.
    #[tokio::test]
    async fn ended_session_matches_only_with_include_ended() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default".to_string())
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "target".to_string(), None)
            .await
            .unwrap();
        let ended = SessionId::new();
        store
            .writer
            .begin_session(NewSession {
                id: ended,
                workspace_id: ws,
                project_id: proj,
                agent_kind: AgentKind::AntigravityCli,
                cwd: Some(std::path::PathBuf::from("/tmp/target")),
                actor_user: None,

                occurred_at: None,
            })
            .await
            .unwrap();
        store.writer.end_session(ended, None).await.unwrap();

        let default_lookup = store
            .reader
            .open_session_for_scope_agent_by_id(
                ws,
                proj,
                AgentKind::AntigravityCli,
                ai_memory_core::OwnerFilter::Any,
                ended,
                false,
            )
            .await
            .unwrap();
        assert_eq!(
            default_lookup.map(|session| session.session_id),
            None,
            "an ended session must stay invisible to the default finalize discovery"
        );

        let reopen_lookup = store
            .reader
            .open_session_for_scope_agent_by_id(
                ws,
                proj,
                AgentKind::AntigravityCli,
                ai_memory_core::OwnerFilter::Any,
                ended,
                true,
            )
            .await
            .unwrap();
        assert_eq!(
            reopen_lookup.map(|session| session.session_id),
            Some(ended),
            "--reopen must reach the ended session for a second finalize"
        );
    }

    #[test]
    fn synthetic_end_url_propagates_all_owners_once_when_requested() {
        let endpoint =
            ServerEndpoint::from_pair(Some("http://127.0.0.1:49374/base".to_string()), None);
        let url = session_end_hook_url(
            &endpoint,
            "/tmp/project",
            "default",
            "project",
            AgentKind::AntigravityCli,
            true,
        )
        .unwrap();
        let parsed = reqwest::Url::parse(&url).unwrap();
        let query: Vec<_> = parsed.query_pairs().into_owned().collect();

        assert_eq!(parsed.path(), "/base/hook");
        assert_eq!(
            query,
            vec![
                ("event".to_string(), "session-end".to_string()),
                ("agent".to_string(), "antigravity-cli".to_string()),
                ("cwd".to_string(), "/tmp/project".to_string()),
                ("workspace".to_string(), "default".to_string()),
                ("project".to_string(), "project".to_string()),
                ("all_owners".to_string(), "true".to_string()),
            ]
        );
    }

    #[test]
    fn synthetic_end_url_omits_all_owners_when_not_requested() {
        let endpoint =
            ServerEndpoint::from_pair(Some("http://127.0.0.1:49374/base".to_string()), None);
        let url = session_end_hook_url(
            &endpoint,
            "/tmp/project",
            "default",
            "project",
            AgentKind::AntigravityCli,
            false,
        )
        .unwrap();
        let parsed = reqwest::Url::parse(&url).unwrap();
        let query: Vec<_> = parsed.query_pairs().into_owned().collect();

        assert_eq!(parsed.path(), "/base/hook");
        assert_eq!(
            query,
            vec![
                ("event".to_string(), "session-end".to_string()),
                ("agent".to_string(), "antigravity-cli".to_string()),
                ("cwd".to_string(), "/tmp/project".to_string()),
                ("workspace".to_string(), "default".to_string()),
                ("project".to_string(), "project".to_string()),
            ]
        );
    }

    fn finalize_args(workspace: Option<&str>, project: Option<&str>) -> FinalizeSessionArgs {
        FinalizeSessionArgs {
            agent: AgentKind::AntigravityCli,
            workspace: workspace.map(Into::into),
            project: project.map(Into::into),
            all_owners: false,
            all: false,
            session_id: None,
            reopen: false,
            json: false,
        }
    }

    #[tokio::test]
    async fn an_empty_workspace_is_refused_before_server_or_scope_work() {
        for empty in ["", " \t "] {
            let error = finalize(&Config::default(), &finalize_args(Some(empty), None))
                .await
                .unwrap_err();
            assert!(
                error.to_string().contains("--workspace was passed empty"),
                "unexpected error: {error}"
            );
        }
    }

    #[tokio::test]
    async fn an_empty_project_is_refused_before_server_or_scope_work() {
        for empty in ["", " \t "] {
            let error = finalize(&Config::default(), &finalize_args(None, Some(empty)))
                .await
                .unwrap_err();
            assert!(
                error.to_string().contains("--project was passed empty"),
                "unexpected error: {error}"
            );
        }
    }
}