synwire_core/agents/
session.rs

1//! Session management traits.
2//!
3//! A session captures the complete state of an agent conversation so it can
4//! be resumed, forked, rewound, or archived across process restarts.
5
6use serde::{Deserialize, Serialize};
7use serde_json::Value;
8
9use crate::BoxFuture;
10use crate::agents::error::AgentError;
11
12// ---------------------------------------------------------------------------
13// Session metadata
14// ---------------------------------------------------------------------------
15
16/// Metadata attached to a stored session.
17#[derive(Debug, Clone, Serialize, Deserialize)]
18pub struct SessionMetadata {
19    /// Unique session identifier.
20    pub id: String,
21    /// Human-readable name.
22    pub name: Option<String>,
23    /// Arbitrary user-defined tags.
24    pub tags: Vec<String>,
25    /// Agent name this session belongs to.
26    pub agent_name: String,
27    /// Creation timestamp (Unix seconds).
28    pub created_at: i64,
29    /// Last-updated timestamp (Unix seconds).
30    pub updated_at: i64,
31    /// Number of turns recorded.
32    pub turn_count: u32,
33    /// Cumulative token usage.
34    pub total_tokens: u64,
35}
36
37/// Full session snapshot including conversation state.
38#[derive(Debug, Clone, Serialize, Deserialize)]
39pub struct Session {
40    /// Session metadata.
41    pub metadata: SessionMetadata,
42    /// Conversation messages as JSON array.
43    pub messages: Vec<Value>,
44    /// Arbitrary agent state (plugin state, cwd, env, etc.).
45    pub state: Value,
46}
47
48// ---------------------------------------------------------------------------
49// SessionManager trait
50// ---------------------------------------------------------------------------
51
52/// Manages session persistence and lifecycle operations.
53///
54/// All operations are async and return `AgentError` on failure.
55pub trait SessionManager: Send + Sync {
56    /// List all sessions, ordered by most-recently updated first.
57    fn list(&self) -> BoxFuture<'_, Result<Vec<SessionMetadata>, AgentError>>;
58
59    /// Load a session by ID.
60    fn resume(&self, session_id: &str) -> BoxFuture<'_, Result<Session, AgentError>>;
61
62    /// Save (create or update) a session.
63    fn save(&self, session: &Session) -> BoxFuture<'_, Result<(), AgentError>>;
64
65    /// Delete a session and all associated data.
66    fn delete(&self, session_id: &str) -> BoxFuture<'_, Result<(), AgentError>>;
67
68    /// Fork a session — create a copy with a new ID.
69    ///
70    /// The forked session shares the same history up to the fork point but
71    /// accumulates diverging state independently thereafter.
72    fn fork(
73        &self,
74        session_id: &str,
75        new_name: Option<String>,
76    ) -> BoxFuture<'_, Result<SessionMetadata, AgentError>>;
77
78    /// Rewind a session to a previous turn.
79    ///
80    /// `turn_index` is zero-based.  Messages beyond `turn_index` are discarded.
81    fn rewind(
82        &self,
83        session_id: &str,
84        turn_index: u32,
85    ) -> BoxFuture<'_, Result<Session, AgentError>>;
86
87    /// Add one or more tags to a session.
88    fn tag(&self, session_id: &str, tags: Vec<String>) -> BoxFuture<'_, Result<(), AgentError>>;
89
90    /// Rename a session.
91    fn rename(&self, session_id: &str, new_name: String) -> BoxFuture<'_, Result<(), AgentError>>;
92}
synwire_core/agents/session.rs

synwire_core/agents/
session.rs
