Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! `ai-memory move-session` — thin HTTP client for moving one session (or
//! every session of a project) to another project.
use anyhow::Result;
use serde::Serialize;
use crate::cli::MoveSessionArgs;
use crate::config::Config;
use crate::http_client::{ServerEndpoint, post_json};
/// Request sent to `POST /admin/move-session`. Exactly one of `session_id`
/// / `from_project` is set.
#[derive(Serialize)]
struct MoveSessionRequest {
#[serde(skip_serializing_if = "Option::is_none")]
session_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
from_workspace: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
from_project: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
workspace: Option<String>,
project: String,
pages: String,
confirm: bool,
force: bool,
create: bool,
}
/// Run the `move-session` subcommand.
///
/// Without `--confirm` the server runs the move inside a rolled-back
/// transaction and this prints what would change plus the exact command to
/// apply it. With `--confirm` it prints the report.
///
/// A session already rooted in the destination is re-homed: the report says
/// `session row: already in destination` and the counts are the stray rows
/// gathered into it (zero when there were none).
///
/// # Errors
/// Returns an error when the server is unreachable or answers non-2xx (404
/// unknown session/target, 409 guard or page collision, 422 batch source
/// equal to the destination).
pub async fn run(config: &Config, args: MoveSessionArgs) -> Result<()> {
super::refuse_empty_explicit(args.from_workspace.as_deref(), "--from-workspace")?;
super::refuse_empty_explicit(args.from_project.as_deref(), "--from-project")?;
super::refuse_empty_explicit(args.to_workspace.as_deref(), "--to-workspace")?;
super::refuse_empty_explicit(Some(args.to.as_str()), "--to")?;
let endpoint = ServerEndpoint::from_config_resolving_auth(config).await;
// The batch source is a scope like any other command's: marker, else
// literal. The destination stays literal.
let (from_workspace, from_project) = match args.from_project.as_deref() {
Some(project) => {
let (ws, proj) =
super::resolve_scope(config, args.from_workspace.as_deref(), Some(project))?;
(Some(ws), Some(proj))
}
None => (None, None),
};
let request = MoveSessionRequest {
session_id: args.session_id.map(|id| id.to_string()),
from_workspace,
from_project,
workspace: args.to_workspace.clone(),
project: args.to.clone(),
pages: args.pages.clone(),
confirm: args.confirm,
force: args.force,
create: args.create,
};
let report: serde_json::Value = post_json(&endpoint, "/admin/move-session", &request).await?;
if let Some(warning) = report["manifest_warning"].as_str() {
eprintln!("ai-memory: warning: {warning}");
}
if request.session_id.is_some() {
print_session_report(&report, args.confirm);
} else {
print_batch_report(&report, args.confirm);
}
if !args.confirm {
println!(
"\n(dry run; nothing was written)\nRe-run with --confirm to apply:\n\n {}",
apply_command(&args)
);
}
Ok(())
}
fn scope(label: &serde_json::Value) -> String {
format!(
"{}/{}",
label["workspace"].as_str().unwrap_or("?"),
label["project"].as_str().unwrap_or("?")
)
}
/// One line saying whether the `sessions` row itself changes scope; a
/// re-home leaves it and only gathers stray rows.
fn session_row_line(report: &serde_json::Value, applied: bool) -> &'static str {
match (report["session_moved"].as_bool().unwrap_or(false), applied) {
(true, true) => "moved",
(true, false) => "would move",
(false, _) => "already in destination (re-home: only stray rows gathered)",
}
}
fn print_session_report(report: &serde_json::Value, applied: bool) {
let verb = if applied { "Moved" } else { "Would move" };
println!(
"{verb} session {} from {} to {}:",
report["session_id"].as_str().unwrap_or("?"),
scope(&report["from"]),
scope(&report["to"]),
);
print_would_create(report);
println!(
" session row: {}",
session_row_line(report, applied)
);
print_counts(
&report["summary"],
report["page"].as_str().unwrap_or("none"),
);
print_source_scopes(report, &scope(&report["to"]));
if let Some(warning) = report["cwd_warning"].as_str() {
println!("Warning: {warning}");
}
print_checkpoints(report);
}
/// Dry run with `--create` against a destination that does not exist yet.
fn print_would_create(report: &serde_json::Value) {
if report["would_create_project"].as_bool().unwrap_or(false) {
println!(
" would create project {} (absent; created on --confirm)",
scope(&report["to"])
);
}
}
/// The wiki checkpoints a confirmed run took: `pre_checkpoint` only when the
/// tree had uncommitted changes before the move, `checkpoint` when the move
/// changed the tree.
fn print_checkpoints(report: &serde_json::Value) {
if let Some(oid) = report["pre_checkpoint"].as_str() {
println!("Pre-move checkpoint: {oid}");
}
if let Some(oid) = report["checkpoint"].as_str() {
println!("Checkpoint: {oid}");
}
}
fn print_batch_report(report: &serde_json::Value, applied: bool) {
let verb = if applied { "Moved" } else { "Would move" };
let total = report["total"].as_u64().unwrap_or(0);
let moved = report["moved"].as_u64().unwrap_or(0);
println!(
"{verb} {moved} of {total} session(s) from {} to {}:",
scope(&report["from"]),
scope(&report["to"]),
);
print_would_create(report);
if let Some(sessions) = report["sessions"].as_array() {
println!(
"{:<38} {:<8} {:>6} {:>8} {:>5} {:<22} cwd",
"session_id", "row", "obs", "handoffs", "jobs", "page"
);
println!("{}", "-".repeat(109));
for s in sessions {
println!(
"{:<38} {:<8} {:>6} {:>8} {:>5} {:<22} {}",
s["session_id"].as_str().unwrap_or("?"),
if s["session_moved"].as_bool().unwrap_or(false) {
"moved"
} else {
"re-home"
},
s["summary"]["observations"].as_u64().unwrap_or(0),
s["summary"]["handoffs"].as_u64().unwrap_or(0),
s["summary"]["consolidation_jobs"].as_u64().unwrap_or(0),
s["page"].as_str().unwrap_or("none"),
s["cwd"].as_str().unwrap_or(""),
);
}
let rehomed = sessions
.iter()
.filter(|s| !s["session_moved"].as_bool().unwrap_or(false))
.count();
if rehomed > 0 {
println!(
"Note: {rehomed} session(s) marked re-home already had their session row in the \
destination; only their stray rows (the counts above) were gathered."
);
}
let warned = sessions
.iter()
.filter(|s| s["cwd_warning"].is_string())
.count();
if warned > 0 {
println!(
"Warning: {warned} session(s) have a cwd whose basename is not the destination \
project; new sessions from those directories still resolve by basename unless \
a .ai-memory.toml marker pins the project."
);
}
}
print_checkpoints(report);
}
/// Name every scope the move will drain, when it is more than the one the
/// caller asked about.
///
/// A move gathers dependent rows by session id alone, so it can empty a
/// project nobody named — and moving back afterwards cannot restore the
/// original split. The operator sees that here, in the dry run, rather than
/// inferring it from a count that came out larger than expected.
fn print_source_scopes(report: &serde_json::Value, destination: &str) {
let Some(scopes) = report["source_scopes"].as_array() else {
return;
};
let others: Vec<_> = scopes
.iter()
.filter(|s| s["observations"].as_u64().unwrap_or(0) > 0)
.collect();
if others.len() < 2 {
return;
}
println!(
" gathering observations out of {} scopes into {destination}:",
others.len()
);
for s in &others {
println!(
" {}/{}: {} observation(s)",
s["workspace"].as_str().unwrap_or("?"),
s["project"].as_str().unwrap_or("?"),
s["observations"].as_u64().unwrap_or(0),
);
}
println!(
" Note: this empties every scope listed above, not only the one named as the source. \
Moving the session back later returns all rows to a single project — the split shown \
here is not restored."
);
}
fn print_counts(summary: &serde_json::Value, page: &str) {
let n = |key: &str| summary[key].as_u64().unwrap_or(0);
println!(" observations: {}", n("observations"));
println!(" handoffs: {}", n("handoffs"));
println!(" consolidation jobs: {}", n("consolidation_jobs"));
println!(" auto-improve runs: {}", n("auto_improve_runs"));
println!(" auto-improve claims: {}", n("auto_improve_claims"));
println!(
" page: {page} ({} version(s) moved, {} retired)",
n("page_versions_moved"),
n("pages_regenerated")
);
}
/// The exact command that applies what the dry run showed.
fn apply_command(args: &MoveSessionArgs) -> String {
let mut cmd = String::from("ai-memory move-session");
if let Some(id) = args.session_id {
cmd.push(' ');
cmd.push_str(&id.to_string());
}
if let Some(project) = &args.from_project {
cmd.push_str(&format!(
" --from-project {}",
super::render_shared::native_shell_quote(project)
));
}
if let Some(ws) = &args.from_workspace {
cmd.push_str(&format!(
" --from-workspace {}",
super::render_shared::native_shell_quote(ws)
));
}
cmd.push_str(&format!(
" --to {}",
super::render_shared::native_shell_quote(&args.to)
));
if let Some(ws) = &args.to_workspace {
cmd.push_str(&format!(
" --to-workspace {}",
super::render_shared::native_shell_quote(ws)
));
}
if args.pages != "move" {
cmd.push_str(&format!(" --pages {}", args.pages));
}
if args.force {
cmd.push_str(" --force");
}
if args.create {
cmd.push_str(" --create");
}
cmd.push_str(" --confirm");
cmd
}
#[cfg(test)]
mod tests {
use super::*;
fn args(session_id: Option<&str>, from_project: Option<&str>) -> MoveSessionArgs {
MoveSessionArgs {
session_id: session_id.map(|s| s.parse().unwrap()),
from_project: from_project.map(str::to_string),
from_workspace: None,
to: "target".into(),
to_workspace: None,
pages: "move".into(),
confirm: false,
force: false,
create: false,
}
}
#[test]
fn apply_command_repeats_the_single_form_with_confirm() {
let id = "0192b6a1-4c2e-7d3f-8a5b-1234567890ab";
let mut a = args(Some(id), None);
a.pages = "regenerate".into();
a.to_workspace = Some("other".into());
assert_eq!(
apply_command(&a),
format!(
"ai-memory move-session {id} --to target --to-workspace other \
--pages regenerate --confirm"
)
);
}
#[test]
fn apply_command_repeats_the_batch_form_and_flags() {
let mut a = args(None, Some("ghost"));
a.from_workspace = Some("default".into());
a.force = true;
a.create = true;
assert_eq!(
apply_command(&a),
"ai-memory move-session --from-project ghost --from-workspace default --to target \
--force --create --confirm"
);
}
#[tokio::test]
async fn an_empty_from_project_flag_is_refused_before_any_request() {
let config = Config::default();
let a = args(None, Some(" "));
let error = run(&config, a).await.unwrap_err();
assert!(
error
.to_string()
.contains("--from-project was passed empty"),
"unexpected error: {error}"
);
}
#[tokio::test]
async fn an_empty_from_workspace_flag_is_refused_before_any_request() {
let config = Config::default();
let mut a = args(None, Some("src"));
a.from_workspace = Some("".into());
let error = run(&config, a).await.unwrap_err();
assert!(
error
.to_string()
.contains("--from-workspace was passed empty"),
"unexpected error: {error}"
);
}
#[tokio::test]
async fn an_empty_to_flag_is_refused_before_any_request() {
let config = Config::default();
let mut a = args(None, Some("src"));
a.to = " ".into();
let error = run(&config, a).await.unwrap_err();
assert!(
error.to_string().contains("--to was passed empty"),
"unexpected error: {error}"
);
}
#[tokio::test]
async fn an_empty_to_workspace_flag_is_refused_before_any_request() {
let config = Config::default();
let mut a = args(None, Some("src"));
a.to_workspace = Some(" ".into());
let error = run(&config, a).await.unwrap_err();
assert!(
error
.to_string()
.contains("--to-workspace was passed empty"),
"unexpected error: {error}"
);
}
}