Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! `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}"
);
}
}
}