An agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.
Rust
feat(runtime): structured session control API for claw-native worker management
Jobdoric18f8a0da144
diff --git a/rust/crates/runtime/src/lib.rs b/rust/crates/runtime/src/lib.rsindex 1c01a3fa..f4ce9138 100644--- a/rust/crates/runtime/src/lib.rs+++ b/rust/crates/runtime/src/lib.rs@@ -17,6 +17,7 @@ pub mod permission_enforcer;mod permissions;mod prompt;mod remote;+pub mod session_control;pub mod sandbox;mod session;mod sse;diff --git a/rust/crates/runtime/src/session_control.rs b/rust/crates/runtime/src/session_control.rsnew file mode 100644index 00000000..2192156e--- /dev/null+++ b/rust/crates/runtime/src/session_control.rs@@ -0,0 +1,461 @@+use std::env;+use std::fmt::{Display, Formatter};+use std::fs;+use std::path::{Path, PathBuf};+use std::time::UNIX_EPOCH;++use serde::{Deserialize, Serialize};++use crate::session::{Session, SessionError};+use crate::worker_boot::{Worker, WorkerReadySnapshot, WorkerRegistry, WorkerStatus};++pub const PRIMARY_SESSION_EXTENSION: &str = "jsonl";+pub const LEGACY_SESSION_EXTENSION: &str = "json";+pub const LATEST_SESSION_REFERENCE: &str = "latest";++const SESSION_REFERENCE_ALIASES: &[&str] = &[LATEST_SESSION_REFERENCE, "last", "recent"];++#[derive(Debug, Clone, PartialEq, Eq)]+pub struct SessionHandle {+ pub id: String,+ pub path: PathBuf,+}++#[derive(Debug, Clone, PartialEq, Eq)]+pub struct ManagedSessionSummary {+ pub id: String,+ pub path: PathBuf,+ pub modified_epoch_millis: u128,+ pub message_count: usize,+ pub parent_session_id: Option<String>,+ pub branch_name: Option<String>,+}++#[derive(Debug, Clone, PartialEq, Eq)]+pub struct LoadedManagedSession {+ pub handle: SessionHandle,+ pub session: Session,+}++#[derive(Debug, Clone, PartialEq, Eq)]+pub struct ForkedManagedSession {+ pub parent_session_id: String,+ pub handle: SessionHandle,+ pub session: Session,+ pub branch_name: Option<String>,+}++#[derive(Debug)]+pub enum SessionControlError {+ Io(std::io::Error),+ Session(SessionError),+ Format(String),+}++impl Display for SessionControlError {+ fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {+ match self {+ Self::Io(error) => write!(f, "{error}"),+ Self::Session(error) => write!(f, "{error}"),+ Self::Format(error) => write!(f, "{error}"),+ }+ }+}++impl std::error::Error for SessionControlError {}++impl From<std::io::Error> for SessionControlError {+ fn from(value: std::io::Error) -> Self {+ Self::Io(value)+ }+}++impl From<SessionError> for SessionControlError {+ fn from(value: SessionError) -> Self {+ Self::Session(value)+ }+}++pub fn sessions_dir() -> Result<PathBuf, SessionControlError> {+ managed_sessions_dir_for(env::current_dir()?)+}++pub fn managed_sessions_dir_for(+ base_dir: impl AsRef<Path>,+) -> Result<PathBuf, SessionControlError> {+ let path = base_dir.as_ref().join(".claw").join("sessions");+ fs::create_dir_all(&path)?;+ Ok(path)+}++pub fn create_managed_session_handle(+ session_id: &str,+) -> Result<SessionHandle, SessionControlError> {+ create_managed_session_handle_for(env::current_dir()?, session_id)+}++pub fn create_managed_session_handle_for(+ base_dir: impl AsRef<Path>,+ session_id: &str,+) -> Result<SessionHandle, SessionControlError> {+ let id = session_id.to_string();+ let path =+ managed_sessions_dir_for(base_dir)?.join(format!("{id}.{PRIMARY_SESSION_EXTENSION}"));+ Ok(SessionHandle { id, path })+}++pub fn resolve_session_reference(reference: &str) -> Result<SessionHandle, SessionControlError> {+ resolve_session_reference_for(env::current_dir()?, reference)+}++pub fn resolve_session_reference_for(+ base_dir: impl AsRef<Path>,+ reference: &str,+) -> Result<SessionHandle, SessionControlError> {+ let base_dir = base_dir.as_ref();+ if is_session_reference_alias(reference) {+ let latest = latest_managed_session_for(base_dir)?;+ return Ok(SessionHandle {+ id: latest.id,+ path: latest.path,+ });+ }++ let direct = PathBuf::from(reference);+ let candidate = if direct.is_absolute() {+ direct.clone()+ } else {+ base_dir.join(&direct)+ };+ let looks_like_path = direct.extension().is_some() || direct.components().count() > 1;+ let path = if candidate.exists() {+ candidate+ } else if looks_like_path {+ return Err(SessionControlError::Format(+ format_missing_session_reference(reference),+ ));+ } else {+ resolve_managed_session_path_for(base_dir, reference)?+ };++ Ok(SessionHandle {+ id: session_id_from_path(&path).unwrap_or_else(|| reference.to_string()),+ path,+ })+}++pub fn resolve_managed_session_path(session_id: &str) -> Result<PathBuf, SessionControlError> {+ resolve_managed_session_path_for(env::current_dir()?, session_id)+}++pub fn resolve_managed_session_path_for(+ base_dir: impl AsRef<Path>,+ session_id: &str,+) -> Result<PathBuf, SessionControlError> {+ let directory = managed_sessions_dir_for(base_dir)?;+ for extension in [PRIMARY_SESSION_EXTENSION, LEGACY_SESSION_EXTENSION] {+ let path = directory.join(format!("{session_id}.{extension}"));+ if path.exists() {+ return Ok(path);+ }+ }+ Err(SessionControlError::Format(+ format_missing_session_reference(session_id),+ ))+}++#[must_use]+pub fn is_managed_session_file(path: &Path) -> bool {+ path.extension()+ .and_then(|ext| ext.to_str())+ .is_some_and(|extension| {+ extension == PRIMARY_SESSION_EXTENSION || extension == LEGACY_SESSION_EXTENSION+ })+}++pub fn list_managed_sessions() -> Result<Vec<ManagedSessionSummary>, SessionControlError> {+ list_managed_sessions_for(env::current_dir()?)+}++pub fn list_managed_sessions_for(+ base_dir: impl AsRef<Path>,+) -> Result<Vec<ManagedSessionSummary>, SessionControlError> {+ let mut sessions = Vec::new();+ for entry in fs::read_dir(managed_sessions_dir_for(base_dir)?)? {+ let entry = entry?;+ let path = entry.path();+ if !is_managed_session_file(&path) {+ continue;+ }+ let metadata = entry.metadata()?;+ let modified_epoch_millis = metadata+ .modified()+ .ok()+ .and_then(|time| time.duration_since(UNIX_EPOCH).ok())+ .map(|duration| duration.as_millis())+ .unwrap_or_default();+ let (id, message_count, parent_session_id, branch_name) =+ match Session::load_from_path(&path) {+ Ok(session) => {+ let parent_session_id = session+ .fork+ .as_ref()+ .map(|fork| fork.parent_session_id.clone());+ let branch_name = session+ .fork+ .as_ref()+ .and_then(|fork| fork.branch_name.clone());+ (+ session.session_id,+ session.messages.len(),+ parent_session_id,+ branch_name,+ )+ }+ Err(_) => (+ path.file_stem()+ .and_then(|value| value.to_str())+ .unwrap_or("unknown")+ .to_string(),+ 0,+ None,+ None,+ ),+ };+ sessions.push(ManagedSessionSummary {+ id,+ path,+ modified_epoch_millis,+ message_count,+ parent_session_id,+ branch_name,+ });+ }+ sessions.sort_by(|left, right| {+ right+ .modified_epoch_millis+ .cmp(&left.modified_epoch_millis)+ .then_with(|| right.id.cmp(&left.id))+ });+ Ok(sessions)+}++pub fn latest_managed_session() -> Result<ManagedSessionSummary, SessionControlError> {+ latest_managed_session_for(env::current_dir()?)+}++pub fn latest_managed_session_for(+ base_dir: impl AsRef<Path>,+) -> Result<ManagedSessionSummary, SessionControlError> {+ list_managed_sessions_for(base_dir)?+ .into_iter()+ .next()+ .ok_or_else(|| SessionControlError::Format(format_no_managed_sessions()))+}++pub fn load_managed_session(reference: &str) -> Result<LoadedManagedSession, SessionControlError> {+ load_managed_session_for(env::current_dir()?, reference)+}++pub fn load_managed_session_for(+ base_dir: impl AsRef<Path>,+ reference: &str,+) -> Result<LoadedManagedSession, SessionControlError> {+ let handle = resolve_session_reference_for(base_dir, reference)?;+ let session = Session::load_from_path(&handle.path)?;+ Ok(LoadedManagedSession {+ handle: SessionHandle {+ id: session.session_id.clone(),+ path: handle.path,+ },+ session,+ })+}++pub fn fork_managed_session(+ session: &Session,+ branch_name: Option<String>,+) -> Result<ForkedManagedSession, SessionControlError> {+ fork_managed_session_for(env::current_dir()?, session, branch_name)+}++pub fn fork_managed_session_for(+ base_dir: impl AsRef<Path>,+ session: &Session,+ branch_name: Option<String>,+) -> Result<ForkedManagedSession, SessionControlError> {+ let parent_session_id = session.session_id.clone();+ let forked = session.fork(branch_name);+ let handle = create_managed_session_handle_for(base_dir, &forked.session_id)?;+ let branch_name = forked+ .fork+ .as_ref()+ .and_then(|fork| fork.branch_name.clone());+ let forked = forked.with_persistence_path(handle.path.clone());+ forked.save_to_path(&handle.path)?;+ Ok(ForkedManagedSession {+ parent_session_id,+ handle,+ session: forked,+ branch_name,+ })+}++#[must_use]+pub fn is_session_reference_alias(reference: &str) -> bool {+ SESSION_REFERENCE_ALIASES+ .iter()+ .any(|alias| reference.eq_ignore_ascii_case(alias))+}++fn session_id_from_path(path: &Path) -> Option<String> {+ path.file_name()+ .and_then(|value| value.to_str())+ .and_then(|name| {+ name.strip_suffix(&format!(".{PRIMARY_SESSION_EXTENSION}"))+ .or_else(|| name.strip_suffix(&format!(".{LEGACY_SESSION_EXTENSION}")))+ })+ .map(ToOwned::to_owned)+}++fn format_missing_session_reference(reference: &str) -> String {+ format!(+ "session not found: {reference}\nHint: managed sessions live in .claw/sessions/. Try `{LATEST_SESSION_REFERENCE}` for the most recent session or `/session list` in the REPL."+ )+}++fn format_no_managed_sessions() -> String {+ format!(+ "no managed sessions found in .claw/sessions/\nStart `claw` to create a session, then rerun with `--resume {LATEST_SESSION_REFERENCE}`."+ )+}++#[cfg(test)]+mod tests {+ use super::{+ create_managed_session_handle_for, fork_managed_session_for, is_session_reference_alias,+ list_managed_sessions_for, load_managed_session_for, resolve_session_reference_for,+ ManagedSessionSummary, LATEST_SESSION_REFERENCE,+ };+ use crate::session::Session;+ use std::fs;+ use std::path::{Path, PathBuf};+ use std::time::{SystemTime, UNIX_EPOCH};++ fn temp_dir() -> PathBuf {+ let nanos = SystemTime::now()+ .duration_since(UNIX_EPOCH)+ .expect("time should be after epoch")+ .as_nanos();+ std::env::temp_dir().join(format!("runtime-session-control-{nanos}"))+ }++ fn persist_session(root: &Path, text: &str) -> Session {+ let mut session = Session::new();+ session+ .push_user_text(text)+ .expect("session message should save");+ let handle = create_managed_session_handle_for(root, &session.session_id)+ .expect("managed session handle should build");+ let session = session.with_persistence_path(handle.path.clone());+ session+ .save_to_path(&handle.path)+ .expect("session should persist");+ session+ }++ fn wait_for_next_millisecond() {+ let start = SystemTime::now()+ .duration_since(UNIX_EPOCH)+ .expect("time should be after epoch")+ .as_millis();+ while SystemTime::now()+ .duration_since(UNIX_EPOCH)+ .expect("time should be after epoch")+ .as_millis()+ <= start+ {}+ }++ fn summary_by_id<'a>(+ summaries: &'a [ManagedSessionSummary],+ id: &str,+ ) -> &'a ManagedSessionSummary {+ summaries+ .iter()+ .find(|summary| summary.id == id)+ .expect("session summary should exist")+ }++ #[test]+ fn creates_and_lists_managed_sessions() {+ // given+ let root = temp_dir();+ fs::create_dir_all(&root).expect("root dir should exist");+ let older = persist_session(&root, "older session");+ wait_for_next_millisecond();+ let newer = persist_session(&root, "newer session");++ // when+ let sessions = list_managed_sessions_for(&root).expect("managed sessions should list");++ // then+ assert_eq!(sessions.len(), 2);+ assert_eq!(sessions[0].id, newer.session_id);+ assert_eq!(summary_by_id(&sessions, &older.session_id).message_count, 1);+ assert_eq!(summary_by_id(&sessions, &newer.session_id).message_count, 1);+ fs::remove_dir_all(root).expect("temp dir should clean up");+ }++ #[test]+ fn resolves_latest_alias_and_loads_session_from_workspace_root() {+ // given+ let root = temp_dir();+ fs::create_dir_all(&root).expect("root dir should exist");+ let older = persist_session(&root, "older session");+ wait_for_next_millisecond();+ let newer = persist_session(&root, "newer session");++ // when+ let handle = resolve_session_reference_for(&root, LATEST_SESSION_REFERENCE)+ .expect("latest alias should resolve");+ let loaded = load_managed_session_for(&root, "recent")+ .expect("recent alias should load the latest session");++ // then+ assert_eq!(handle.id, newer.session_id);+ assert_eq!(loaded.handle.id, newer.session_id);+ assert_eq!(loaded.session.messages.len(), 1);+ assert_ne!(loaded.handle.id, older.session_id);+ assert!(is_session_reference_alias("last"));+ fs::remove_dir_all(root).expect("temp dir should clean up");+ }++ #[test]+ fn forks_session_into_managed_storage_with_lineage() {+ // given+ let root = temp_dir();+ fs::create_dir_all(&root).expect("root dir should exist");+ let source = persist_session(&root, "parent session");++ // when+ let forked = fork_managed_session_for(&root, &source, Some("incident-review".to_string()))+ .expect("session should fork");+ let sessions = list_managed_sessions_for(&root).expect("managed sessions should list");+ let summary = summary_by_id(&sessions, &forked.handle.id);++ // then+ assert_eq!(forked.parent_session_id, source.session_id);+ assert_eq!(forked.branch_name.as_deref(), Some("incident-review"));+ assert_eq!(+ summary.parent_session_id.as_deref(),+ Some(source.session_id.as_str())+ );+ assert_eq!(summary.branch_name.as_deref(), Some("incident-review"));+ assert_eq!(+ forked.session.persistence_path(),+ Some(forked.handle.path.as_path())+ );+ fs::remove_dir_all(root).expect("temp dir should clean up");+ }+}