Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Cross-agent handoff type.
//!
//! A handoff is a typed snapshot of "where we are" — created when one
//! agent CLI ends a session, accepted when the next one starts in the
//! same project. Stored explicitly (vs. inferring from the
//! observations log) because cross-agent continuity is the project's
//! headline feature and deserves a first-class schema.
use std::path::PathBuf;
use jiff::Timestamp;
use serde::{Deserialize, Serialize};
use crate::{
OwnerFilter,
ids::{AgentKind, HandoffId, ProjectId, SessionId, WorkspaceId},
};
/// State machine of a single handoff row.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum HandoffState {
/// Created, not yet picked up by the next agent.
Open,
/// Another agent has called `memory_handoff_accept` on it.
Accepted,
/// Aged out (decay sweep).
Expired,
}
impl HandoffState {
/// Canonical wire string.
#[must_use]
pub const fn as_str(&self) -> &'static str {
match self {
Self::Open => "open",
Self::Accepted => "accepted",
Self::Expired => "expired",
}
}
}
impl std::str::FromStr for HandoffState {
type Err = crate::MemoryError;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s {
"open" => Ok(Self::Open),
"accepted" => Ok(Self::Accepted),
"expired" => Ok(Self::Expired),
other => Err(crate::MemoryError::MalformedRecord(format!(
"unknown handoff state: {other}"
))),
}
}
}
/// Input for inserting a new handoff.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NewHandoff {
/// Owning workspace.
pub workspace_id: WorkspaceId,
/// Owning project.
pub project_id: ProjectId,
/// Session this handoff captures (None for manual handoffs).
pub from_session_id: Option<SessionId>,
/// Agent CLI that produced this handoff.
pub from_agent: AgentKind,
/// Optional explicit target hint (`claude-code`, `codex`, …).
pub to_agent: Option<AgentKind>,
/// Working directory at handoff time. Used to match the next
/// session's `memory_handoff_accept` call.
pub cwd: Option<PathBuf>,
/// One-paragraph summary of where we left off.
pub summary: String,
/// Open questions for the next agent.
pub open_questions: Vec<String>,
/// Suggested next steps.
pub next_steps: Vec<String>,
/// Files touched in the session.
pub files_touched: Vec<String>,
/// Operator this handoff belongs to, as an
/// [`crate::IdentityKey::storage_key`] string. `None` publishes it to the
/// whole project (the pre-ownership behaviour, and what a caller with no
/// actor produces).
#[serde(default)]
pub owner_user: Option<String>,
}
/// Scope, ownership, and receiver metadata for an atomic handoff claim.
#[derive(Debug, Clone)]
pub struct HandoffAcceptance {
/// Handoff being claimed.
pub handoff_id: HandoffId,
/// Workspace the caller resolved before the claim.
pub workspace_id: WorkspaceId,
/// Project the caller resolved before the claim.
pub project_id: ProjectId,
/// Agent CLI accepting the handoff.
pub accepting_agent: AgentKind,
/// Session accepting the handoff, when known.
pub accepting_session: Option<SessionId>,
/// Operator accepting the handoff, in [`crate::IdentityKey::storage_key`]
/// form.
pub accepting_user: Option<String>,
/// Ownership boundary the caller is authorized to claim through.
pub owner_filter: OwnerFilter,
/// Working directory of the receiving session, used to bound automatic
/// handoff supersession.
pub receiving_cwd: Option<String>,
}
/// Row identity and tenancy for a handoff.
#[derive(Debug, Clone, Serialize)]
pub struct HandoffScope {
/// Stable identifier.
pub id: HandoffId,
/// Owning workspace.
pub workspace_id: WorkspaceId,
/// Owning project.
pub project_id: ProjectId,
}
/// Where a handoff came from and who it's for.
#[derive(Debug, Clone, Serialize)]
pub struct HandoffOrigin {
/// Session that produced this handoff, if any.
pub from_session_id: Option<SessionId>,
/// Agent CLI that produced this handoff.
pub from_agent: AgentKind,
/// Optional target hint.
pub to_agent: Option<AgentKind>,
/// Working directory at handoff time.
pub cwd: Option<String>,
/// Operator this handoff belongs to ([`crate::IdentityKey::storage_key`]
/// form); `None` means shared with the project.
pub owner_user: Option<String>,
}
/// The handoff payload itself.
#[derive(Debug, Clone, Serialize)]
pub struct HandoffContent {
/// Summary.
pub summary: String,
/// Open questions.
pub open_questions: Vec<String>,
/// Next steps.
pub next_steps: Vec<String>,
/// Files touched.
pub files_touched: Vec<String>,
}
/// State machine and acceptance record for a handoff.
#[derive(Debug, Clone, Serialize)]
pub struct HandoffLifecycle {
/// State.
pub state: HandoffState,
/// Creation timestamp.
pub created_at: Timestamp,
/// Agent CLI that accepted, if any.
pub accepted_by: Option<AgentKind>,
/// Acceptance timestamp.
pub accepted_at: Option<Timestamp>,
/// Session that accepted, if any.
pub accepted_by_session: Option<SessionId>,
/// Operator that accepted it. Unlike [`HandoffLifecycle::accepted_by`]
/// (the agent CLI), this answers "which teammate took the baton".
pub accepted_by_user: Option<String>,
}
/// Materialised view of a handoff row.
///
/// Grouped into sub-structs (identity, origin, content, lifecycle) instead
/// of 18 flat fields; each is `#[serde(flatten)]`ed so the MCP wire JSON
/// stays exactly as flat as before this split.
#[derive(Debug, Clone, Serialize)]
pub struct Handoff {
/// Row identity and tenancy.
#[serde(flatten)]
pub scope: HandoffScope,
/// Where it came from and who it's for.
#[serde(flatten)]
pub origin: HandoffOrigin,
/// The payload.
#[serde(flatten)]
pub content: HandoffContent,
/// State machine and acceptance record.
#[serde(flatten)]
pub lifecycle: HandoffLifecycle,
}