A self-improving RLM agent for coding workflows and long-running autonomous tasks.
Rust
//! The session runtime: shared goal-driver + cron-store state with kernel
//! host-handler registration — the wiring layer binding the
//! goal/rlm-heartbeat host requests to a live session (the Rust
//! equivalent of the `AgentSession` host-request controllers).
use std::sync::Arc;
use serde_json::Value;
use tokio::sync::Mutex;
use crate::cron::store::AgentCronJobStore;
use crate::goals::GoalHostResponse;
use crate::kernel::shared::{host_handler, HostRequestHandlers};
use crate::session::manager::SessionManager;
use super::goal_driver::GoalDriver;
use super::host_requests::{
handle_goal_host_request, handle_rlm_heartbeat_host_request, RlmHeartbeatMutationHook,
SessionBinding,
};
/// The host-side purge of queued goal-context turns: the queue lanes live in the daemon
/// worker, so the completing kernel host request invokes this seam — dropping a
/// continuation queued while the goal was completing.
pub type QueuedGoalContextPurge = Arc<dyn Fn() + Send + Sync>;
/// Session-scoped runtime state the kernel bridge reaches.
pub struct SessionRuntime {
goal_driver: Arc<Mutex<GoalDriver>>,
cron_store: Option<Arc<AgentCronJobStore>>,
active_session_id: String,
binding: SessionBinding,
/// Invoked after a kernel `goal.complete` settles the goal; `None`
/// when the embedding owns no queued goal contexts.
goal_complete_purge: Option<QueuedGoalContextPurge>,
/// Invoked after a kernel `rlm_heartbeat.*` mutation; `None` when
/// the embedding owns no scheduler to re-arm.
cron_mutation_hook: Option<RlmHeartbeatMutationHook>,
}
impl SessionRuntime {
/// Build a runtime around the embedding's cron store, rehydrating any
/// persisted goal. `None` is an embedding with no scheduler: kernel
/// `rlm_heartbeat.*` requests stay unregistered (TS gates on the
/// heartbeat controller).
#[must_use]
pub fn new(
session: &SessionManager,
cron_store: Option<Arc<AgentCronJobStore>>,
active_session_id: String,
binding: SessionBinding,
) -> Self {
Self {
goal_driver: Arc::new(Mutex::new(GoalDriver::load_persisted(session))),
cron_store,
active_session_id,
binding,
goal_complete_purge: None,
cron_mutation_hook: None,
}
}
/// Set the post-completion purge seam (the daemon worker's queue purge).
pub fn set_goal_complete_purge(&mut self, purge: QueuedGoalContextPurge) {
self.goal_complete_purge = Some(purge);
}
/// Set the rlm heartbeat mutation hook (queued-fire withdrawal +
/// scheduler re-arm).
pub fn set_cron_mutation_hook(&mut self, hook: RlmHeartbeatMutationHook) {
self.cron_mutation_hook = Some(hook);
}
#[must_use]
pub fn goal_driver(&self) -> &Arc<Mutex<GoalDriver>> {
&self.goal_driver
}
/// The embedding's cron store; `None` when no scheduler is wired.
#[must_use]
pub fn cron_store(&self) -> Option<&Arc<AgentCronJobStore>> {
self.cron_store.as_ref()
}
/// Register the `goal.*` and `rlm_heartbeat.*` handlers onto a handler
/// map; the heartbeat handlers register only on a runtime that serves
/// them (embeddings with cron wiring).
pub fn register_host_handlers(
&self,
session: Arc<Mutex<SessionManager>>,
handlers: &mut HostRequestHandlers,
) {
let driver = self.goal_driver.clone();
let goal_session = session;
// TS `_completeGoalFromHost` clears the queued goal contexts: a continuation
// queued behind the completing turn never runs post-completion.
let goal_complete_purge = self.goal_complete_purge.clone();
for request_type in ["goal.get", "goal.create", "goal.complete"] {
let driver = driver.clone();
let session = goal_session.clone();
let purge = if request_type == "goal.complete" {
goal_complete_purge.clone()
} else {
None
};
handlers.register(
request_type,
host_handler(move |payload| {
let driver = driver.clone();
let session = session.clone();
let purge = purge.clone();
Box::pin(async move {
let response = {
let mut driver = driver.lock().await;
let mut session = session.lock().await;
handle_goal_host_request(
request_type,
&payload.data,
&mut driver,
&mut session,
)?
};
if let Some(purge) = purge {
purge();
}
host_ok(&response)
})
}),
);
}
// Scheduler-less embeddings expose goals but cannot create heartbeat jobs.
let Some(store) = self.cron_store.clone() else {
return;
};
let active_session_id = self.active_session_id.clone();
let binding_session_id = self.binding.session_id.clone();
let binding_session_file = self.binding.session_file.clone();
let binding_cwd = self.binding.cwd.clone();
let cron_mutation_hook = self.cron_mutation_hook.clone();
for request_type in [
"rlm_heartbeat.list",
"rlm_heartbeat.create",
"rlm_heartbeat.update",
"rlm_heartbeat.delete",
] {
let store = store.clone();
let active_session_id = active_session_id.clone();
let session_id = binding_session_id.clone();
let session_file = binding_session_file.clone();
let cwd = binding_cwd.clone();
let mutation_hook = cron_mutation_hook.clone();
handlers.register(
request_type,
host_handler(move |payload| {
let store = store.clone();
let active_session_id = active_session_id.clone();
let binding = SessionBinding {
session_id: session_id.clone(),
session_file: session_file.clone(),
cwd: cwd.clone(),
};
let mutation_hook = mutation_hook.clone();
Box::pin(async move {
let outcome = handle_rlm_heartbeat_host_request(
payload
.data
.get("type")
.and_then(Value::as_str)
.unwrap_or("rlm_heartbeat.list"),
&payload.data,
&store,
&active_session_id,
&binding,
)?;
// The embedding's post-mutation work: withdraw the
// queued fire and re-arm the cron scheduler.
if let Some(mutation) = outcome.mutation {
if let Some(hook) = &mutation_hook {
hook(mutation).await;
}
}
Ok(outcome.response)
})
}),
);
}
}
}
fn host_ok(response: &GoalHostResponse) -> anyhow::Result<Value> {
serde_json::to_value(response).map_err(anyhow::Error::new)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::kernel::shared::HostRequestPayload;
fn persisted_session() -> SessionManager {
let dir = tempfile::TempDir::new().unwrap();
let session_dir = dir.path().join("session");
std::fs::create_dir_all(&session_dir).unwrap();
let mut session = SessionManager::in_memory(dir.path());
session.materialize_session_file(Some(session_dir));
session
}
fn payload(data: Value) -> HostRequestPayload {
HostRequestPayload { data }
}
/// The purge seam fires only for `goal.complete`, never on the way in.
#[tokio::test]
async fn goal_complete_purge_runs_only_after_goal_complete() {
let session = Arc::new(Mutex::new(persisted_session()));
let dir = tempfile::TempDir::new().unwrap();
let mut runtime = SessionRuntime::new(
&*session.lock().await,
Some(Arc::new(AgentCronJobStore::new(
dir.path().join("jobs.json"),
))),
"live-1".to_string(),
SessionBinding {
session_id: "session-1".to_string(),
session_file: "/w/s.jsonl".to_string(),
cwd: "/w".to_string(),
},
);
let purges = Arc::new(std::sync::atomic::AtomicUsize::new(0));
let sink = Arc::clone(&purges);
runtime.set_goal_complete_purge(Arc::new(move || {
sink.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
}));
let mut handlers = HostRequestHandlers::default();
runtime.register_host_handlers(session, &mut handlers);
let create = handlers.get("goal.create").unwrap().clone();
create(payload(serde_json::json!({
"type": "goal.create",
"objective": "pin the purge ordering"
})))
.await
.unwrap();
let get = handlers.get("goal.get").unwrap().clone();
get(payload(serde_json::json!({ "type": "goal.get" })))
.await
.unwrap();
assert_eq!(purges.load(std::sync::atomic::Ordering::SeqCst), 0);
let complete = handlers.get("goal.complete").unwrap().clone();
complete(payload(serde_json::json!({ "type": "goal.complete" })))
.await
.unwrap();
assert_eq!(purges.load(std::sync::atomic::Ordering::SeqCst), 1);
}
#[tokio::test]
async fn goal_handlers_round_trip_through_the_registry() {
let session = Arc::new(Mutex::new(persisted_session()));
let dir = tempfile::TempDir::new().unwrap();
let runtime = SessionRuntime::new(
&*session.lock().await,
Some(Arc::new(AgentCronJobStore::new(
dir.path().join("jobs.json"),
))),
"live-1".to_string(),
SessionBinding {
session_id: "session-1".to_string(),
session_file: "/w/s.jsonl".to_string(),
cwd: "/w".to_string(),
},
);
let mut handlers = HostRequestHandlers::default();
runtime.register_host_handlers(session.clone(), &mut handlers);
let create = handlers.get("goal.create").unwrap().clone();
let response = create(payload(serde_json::json!({
"type": "goal.create",
"objective": "finish the port",
"token_budget": 1000
})))
.await
.unwrap();
assert_eq!(response["goal"]["status"], "active");
assert_eq!(response["goal"]["objective"], "finish the port");
let persisted = session.lock().await;
let goal_entries: Vec<&pa_types::session::FileEntry> = persisted
.get_all_entries()
.iter()
.filter(|entry| {
matches!(entry, pa_types::session::FileEntry::Custom { payload, .. }
if payload.custom_type == crate::goals::GOAL_STATE_CUSTOM_TYPE)
})
.collect();
assert_eq!(goal_entries.len(), 1);
drop(persisted);
let get = handlers.get("goal.get").unwrap().clone();
let response = get(payload(serde_json::json!({ "type": "goal.get" })))
.await
.unwrap();
assert_eq!(response["goal"]["objective"], "finish the port");
assert_eq!(response["remaining_tokens"], 1000);
let complete = handlers.get("goal.complete").unwrap().clone();
let response = complete(payload(serde_json::json!({ "type": "goal.complete" })))
.await
.unwrap();
assert_eq!(response["goal"]["status"], "complete");
assert!(response["completion_budget_report"].is_string());
}
#[tokio::test]
async fn heartbeat_handlers_round_trip_through_the_registry() {
let session = Arc::new(Mutex::new(persisted_session()));
let dir = tempfile::TempDir::new().unwrap();
let runtime = SessionRuntime::new(
&*session.lock().await,
Some(Arc::new(AgentCronJobStore::new(
dir.path().join("jobs.json"),
))),
"live-1".to_string(),
SessionBinding {
session_id: "session-1".to_string(),
session_file: "/w/s.jsonl".to_string(),
cwd: "/w".to_string(),
},
);
let mut handlers = HostRequestHandlers::default();
runtime.register_host_handlers(session, &mut handlers);
let create = handlers.get("rlm_heartbeat.create").unwrap().clone();
let response = create(payload(serde_json::json!({
"type": "rlm_heartbeat.create",
"instruction": "watch the mission",
"interval": "every 15m"
})))
.await
.unwrap();
assert_eq!(response["heartbeat"]["status"], "active");
assert_eq!(response["heartbeat"]["instruction"], "watch the mission");
let id = response["heartbeat"]["id"].as_str().unwrap().to_string();
let update = handlers.get("rlm_heartbeat.update").unwrap().clone();
let response = update(payload(serde_json::json!({
"type": "rlm_heartbeat.update",
"id": id,
"status": "pause"
})))
.await
.unwrap();
assert_eq!(response["heartbeat"]["status"], "paused");
let jobs = runtime
.cron_store()
.expect("the wired store")
.list_rlm_heartbeats("live-1", true);
assert_eq!(jobs.len(), 1);
}
/// Catalog reads announce nothing.
#[tokio::test]
async fn rlm_heartbeat_mutations_invoke_the_cron_mutation_hook() {
let session = Arc::new(Mutex::new(persisted_session()));
let dir = tempfile::TempDir::new().unwrap();
let mut runtime = SessionRuntime::new(
&*session.lock().await,
Some(Arc::new(AgentCronJobStore::new(
dir.path().join("jobs.json"),
))),
"live-1".to_string(),
SessionBinding {
session_id: "session-1".to_string(),
session_file: "/w/s.jsonl".to_string(),
cwd: "/w".to_string(),
},
);
let mutations: Arc<Mutex<Vec<super::super::host_requests::RlmHeartbeatMutation>>> =
Arc::new(Mutex::new(Vec::new()));
let sink = mutations.clone();
runtime.set_cron_mutation_hook(Arc::new(move |mutation| {
let sink = sink.clone();
Box::pin(async move {
sink.lock().await.push(mutation);
})
}));
let mut handlers = HostRequestHandlers::default();
runtime.register_host_handlers(session, &mut handlers);
// Create announces the job (never withdrawing a queued fire).
let create = handlers.get("rlm_heartbeat.create").unwrap().clone();
let response = create(payload(serde_json::json!({
"type": "rlm_heartbeat.create",
"instruction": "watch the mission",
"interval": "every 15m"
})))
.await
.unwrap();
let id = response["heartbeat"]["id"].as_str().unwrap().to_string();
let seen = mutations.lock().await;
assert_eq!(seen.len(), 1);
assert_eq!(seen[0].job.id, id);
assert_eq!(seen[0].job.source.as_deref(), Some("rlm_heartbeat"));
assert!(!seen[0].drop_queued);
drop(seen);
// A catalog read announces nothing.
let list = handlers.get("rlm_heartbeat.list").unwrap().clone();
let response = list(payload(serde_json::json!({ "type": "rlm_heartbeat.list" })))
.await
.unwrap();
assert_eq!(response["heartbeats"].as_array().unwrap().len(), 1);
assert_eq!(mutations.lock().await.len(), 1);
// A pause withdraws the queued fire (TS `updateRlmHeartbeatForState`).
let update = handlers.get("rlm_heartbeat.update").unwrap().clone();
update(payload(serde_json::json!({
"type": "rlm_heartbeat.update",
"id": id,
"status": "pause"
})))
.await
.unwrap();
let seen = mutations.lock().await;
assert_eq!(seen.len(), 2);
assert!(seen[1].drop_queued);
drop(seen);
// A delete always withdraws it.
let delete = handlers.get("rlm_heartbeat.delete").unwrap().clone();
delete(payload(serde_json::json!({
"type": "rlm_heartbeat.delete",
"id": id
})))
.await
.unwrap();
let seen = mutations.lock().await;
assert_eq!(seen.len(), 3);
assert!(seen[2].drop_queued);
}
}