A self-improving RLM agent for coding workflows and long-running autonomous tasks.
Rust
//! `AgentSession`: the turn admission layer over the pa-agent loop
//! (prompt normalization, busy-admission rules, `SessionManager`
//! persistence); the Agent owns the loop, this layer decides admission.
pub mod agent_messaging;
pub mod auto_refine_trigger;
pub mod auto_retry;
pub mod auxiliary_model;
pub mod bash_notices;
pub mod branch_summarization;
pub mod compact_session;
pub mod compaction;
pub mod compaction_exec;
pub mod compaction_trace;
pub mod compaction_utils;
pub mod engine;
pub mod error_classify;
pub mod factory_host;
pub mod goal_boundary;
pub mod goal_driver;
pub mod harness_digest;
pub mod headless;
pub mod host_requests;
pub mod image_model_routing;
pub mod ipython_state;
pub mod late_sent_messages;
pub mod messages;
pub mod provider_adapter;
pub mod provider_failover;
pub mod provider_park;
pub mod provider_retry;
pub mod refine;
mod refinement_gate;
pub mod request_timing;
pub mod rlm_host;
pub mod rlm_notices;
pub mod rlm_usage;
pub mod runtime;
pub mod runtime_wiring;
pub mod semantic_edges;
pub mod session_commands;
pub mod session_events;
pub mod side_question;
pub mod skills_unavailable_notice;
pub mod slash_commands;
pub mod state_restore_notice;
pub mod telemetry;
pub mod tool_bridge;
pub mod turn_boundary;
mod admission;
mod compaction_arms;
mod wiring;
use std::sync::Arc;
use pa_agent::agent::Agent;
use pa_agent::types::{AgentEvent, AgentMessage, ThinkingLevel};
use pa_types::session::AgentMessage as SessionAgentMessage;
use pa_types::session::FileEntry;
use crate::session::manager::{capture_git_context, SessionManager};
use crate::skills::PromptTemplate;
use slash_commands::{SessionSlashCommand, SlashCommandRegistry};
/// How a prompt submitted while the agent streams is scheduled.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StreamingBehavior {
Steer,
FollowUp,
}
/// What `prompt` did with the input.
#[derive(Debug, PartialEq)]
pub enum PromptOutcome {
Prompt,
/// Input recognized as a session command; execution is the session
/// engine's job.
SessionCommand(SessionSlashCommand),
}
/// Options for `AgentSession::prompt`.
#[derive(Debug, Default)]
pub struct PromptOptions {
pub streaming_behavior: Option<StreamingBehavior>,
pub expand_prompt_templates: Option<bool>,
/// Queue instead of erroring when the session is busy (agent messages).
pub queue_if_busy: bool,
/// Co-delivered user rows of a batched turn, riding after the
/// primary.
pub batch: Vec<PromptBatchRow>,
/// TS `returnAfterAccepted: true`: the turn runs detached, admission
/// returns once its run registers.
pub return_after_accepted: bool,
}
/// One co-delivered user row of a batched prompt admission.
#[derive(Debug, Clone)]
pub struct PromptBatchRow {
pub text: String,
pub images: Vec<pa_agent::types::ImageContent>,
}
/// Which trailing assistant messages [`AgentSession::drop_trailing_assistant`]
/// removes.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TrailingAssistantFilter {
/// The TS overflow arm's pre-compaction drop.
Any,
/// The TS will-retry branch's post-rebuild drop.
ErrorOnly,
}
fn standard_message(message: &pa_agent::types::AgentMessage) -> Option<&pa_agent::types::Message> {
let pa_agent::types::AgentMessage::Standard(message) = message else {
return None;
};
Some(message)
}
/// The session-bound agent: admission rules + persistence over the loop.
pub struct AgentSession {
agent: Arc<Agent>,
session: Arc<tokio::sync::Mutex<SessionManager>>,
prompt_templates: Vec<PromptTemplate>,
slash_commands: SlashCommandRegistry,
/// Harness digest inputs; `None` without harness state.
harness_digest: Option<harness_digest::HarnessDigestContext>,
/// Fresh sessions defer the first-turn digest so untouched sessions
/// stay empty.
digest_pending: std::sync::atomic::AtomicBool,
/// Compaction settings; defaults until the engine wiring resolves
/// them.
compaction: std::sync::RwLock<compaction::CompactionSettings>,
/// Auxiliary-model routing for compaction summaries; `None` keeps
/// every summarizer on the session model.
auxiliary_model: Option<auxiliary_model::AuxiliaryModelContext>,
/// Whether this session may auto-refine; defaults off until the
/// engine wiring resolves it.
auto_refine_allowed: bool,
refinement_settings: Option<crate::settings::SettingsManager>,
/// The resolved auto-refine gates; the compact trigger reads them.
auto_refine: refine::AutoRefineGates,
/// Session-side auto-refine state the transport surfaces arm and
/// consume.
compact_auto_refine: std::sync::Mutex<auto_refine_trigger::CompactAutoRefineState>,
/// The kernel-state probe behind the post-compaction
/// `ipython_state` notice; `None` without a kernel.
kernel_state: Option<std::sync::Arc<dyn ipython_state::CompactionKernelProbe>>,
/// TS `_pendingNextTurnMessages`: custom rows the NEXT admitted
/// turn carries ahead of its own prompt row.
pending_next_turn_rows: std::sync::Arc<std::sync::Mutex<Vec<pa_types::session::CustomMessage>>>,
/// The skill inventory `/skill:<name>` submissions expand against.
skills: Vec<crate::skills::Skill>,
/// The telemetry handle for the `skill_use_count` counter the prompt
/// path owns (`None` in sessions without telemetry).
skill_telemetry: Option<std::sync::Arc<telemetry::SessionTelemetry>>,
/// The image-model routing host seam; `None` keeps the session
/// model on image turns.
image_model_router: Option<image_model_routing::ImageModelRouter>,
/// The live compaction summary-delta sink. Interior-mutable so the
/// daemon can install it after the build; `None` (the default)
/// keeps the one-shot summarizer completion.
compaction_summary_sink: std::sync::Mutex<Option<compaction_exec::SummaryDeltaSink>>,
/// One compaction at a time: a second `compact` waits for the
/// in-flight run and prepares against its result; reads and writes
/// keep using the session lock meanwhile.
compaction_flight: tokio::sync::Mutex<()>,
/// The session's semantic-edge recorder (TS
/// `AgentSession._semanticEdges`): `None` in sessions the engine
/// built without a semantic identity (verification harnesses
/// building the loop directly).
semantic_edges: std::sync::Mutex<Option<std::sync::Arc<semantic_edges::SemanticEdgeRecorder>>>,
/// TS `unwrapSemanticEdgeStreamFn(streamFn)`: the timing-instrumented,
/// pre-semantic stream fn calls outside session history run on (a side
/// question carries no request id). `None` until the engine wires it;
/// a side question on an unwired session fails with the model-selection
/// error (no fallback to the agent's id-carrying fn).
side_question_stream_fn: std::sync::Mutex<Option<pa_agent::stream::StreamFn>>,
/// The session's agent dir (the settings root): the refine flow
/// resolves the `factory.enabled` opt-in from its settings.json on
/// every run, immediately before the plan applies, mirroring the
/// kernel-side factory gate that reads the same file through
/// `PRIME_AGENT_CODING_AGENT_DIR`. `None` until the engine wiring
/// resolves it (verification harnesses building the session directly
/// keep `None`, which reads as the fail-closed disabled default).
agent_dir: Option<std::path::PathBuf>,
}
impl AgentSession {
/// Build a session around a running agent loop.
///
/// # Errors
///
/// Returns the underlying session-assembly error (see [`AgentSession::from_session_arc`]).
pub async fn new(
agent: Arc<Agent>,
session: SessionManager,
prompt_templates: Vec<PromptTemplate>,
) -> anyhow::Result<Self> {
Self::from_session_arc(
agent,
Arc::new(tokio::sync::Mutex::new(session)),
prompt_templates,
None,
)
.await
}
/// Build a session from an already-shared session manager handle, so the
/// kernel host-request handlers can reach the same persistence.
///
/// # Errors
///
/// Returns an error when subscribing the persistence listener fails or
/// the initial session context cannot be read.
#[allow(clippy::too_many_arguments)]
pub async fn from_session_arc(
agent: Arc<Agent>,
session: Arc<tokio::sync::Mutex<SessionManager>>,
prompt_templates: Vec<PromptTemplate>,
harness_digest: Option<harness_digest::HarnessDigestContext>,
) -> anyhow::Result<Self> {
let persistence = session.clone();
agent
.subscribe(move |event, _signal| {
let persistence = persistence.clone();
Box::pin(async move {
persist_event(&persistence, event).await?;
Ok(())
})
})
.await;
let this = Self {
agent,
session,
prompt_templates,
slash_commands: SlashCommandRegistry::builtin(),
harness_digest,
digest_pending: std::sync::atomic::AtomicBool::new(false),
compaction: std::sync::RwLock::new(compaction::CompactionSettings::default()),
auxiliary_model: None,
auto_refine_allowed: false,
refinement_settings: None,
auto_refine: refine::AutoRefineGates::default(),
compact_auto_refine: std::sync::Mutex::default(),
kernel_state: None,
pending_next_turn_rows: std::sync::Arc::new(std::sync::Mutex::new(Vec::new())),
skills: Vec::new(),
skill_telemetry: None,
image_model_router: None,
compaction_summary_sink: std::sync::Mutex::new(None),
semantic_edges: std::sync::Mutex::new(None),
side_question_stream_fn: std::sync::Mutex::new(None),
agent_dir: None,
compaction_flight: tokio::sync::Mutex::new(()),
};
this.ensure_harness_digest_context().await?;
Ok(this)
}
/// The underlying agent loop (steering, state, subscriptions).
pub fn agent(&self) -> &Arc<Agent> {
&self.agent
}
/// The kernel host handlers and the command executor reach the same
/// session state as the loop.
pub(crate) fn session_handle(&self) -> &Arc<tokio::sync::Mutex<SessionManager>> {
&self.session
}
/// The persistence handle for host runtimes in other crates (the
/// daemon's ACP transport records goal usage into it).
pub fn shared_persistence(&self) -> Arc<tokio::sync::Mutex<SessionManager>> {
self.session.clone()
}
/// Session id (persistence identity).
pub async fn session_id(&self) -> String {
self.session.lock().await.get_session_id().to_string()
}
/// Restore a verified retained context without loading older transcript bodies.
pub async fn restore_windowed_context(
&self,
window: crate::session::window::WindowedSessionStore,
) {
let messages = {
let mut session = self.session.lock().await;
session.adopt_window(window);
session.active_context().messages
};
self.agent
.set_messages(
messages
.iter()
.filter_map(session_message_to_loop)
.collect(),
)
.await;
}
/// Persisted entries (for UI resume and inspection).
pub async fn entries(&self) -> Vec<FileEntry> {
self.session
.lock()
.await
.retained_entries()
.iter()
.filter(|entry| !matches!(entry, FileEntry::Header { .. }))
.cloned()
.collect()
}
/// Model change bookkeeping (mirrors appendModelChange); the model
/// forwards to the loop through the shared wire shape.
///
/// # Errors
///
/// Returns an error when the model cannot be converted to the loop wire
/// shape, or when the model-change row cannot be persisted.
pub async fn set_model(
&self,
model: &pa_types::ai::Model,
provider: &str,
model_id: &str,
) -> anyhow::Result<()> {
let wire: pa_agent::types::Model = serde_json::from_value(
serde_json::to_value(model).map_err(|error| anyhow::anyhow!(error.to_string()))?,
)
.map_err(|error| anyhow::anyhow!(error.to_string()))?;
self.agent.set_model(wire).await;
let mut session = self.session.lock().await;
session.append_model_change(provider, model_id)?;
Ok(())
}
/// The atomic model-and-level switch: one agent-lock acquisition updates both, so
/// a concurrently admitted turn never observes the new model with the old level
/// mid-switch; the thinking level's intent row belongs to the explicit `/thinking` path.
///
/// # Errors
///
/// Returns an error when the model cannot be converted to the loop
/// wire shape, or when the model-change row cannot be persisted.
pub async fn set_model_and_thinking_level(
&self,
model: &pa_types::ai::Model,
provider: &str,
model_id: &str,
thinking_level: ThinkingLevel,
) -> anyhow::Result<()> {
let wire: pa_agent::types::Model = serde_json::from_value(
serde_json::to_value(model).map_err(|error| anyhow::anyhow!(error.to_string()))?,
)
.map_err(|error| anyhow::anyhow!(error.to_string()))?;
self.agent
.set_model_and_thinking_level(wire, thinking_level)
.await;
let mut session = self.session.lock().await;
session.append_model_change(provider, model_id)?;
Ok(())
}
/// Thinking level bookkeeping (mirrors appendThinkingLevelChange).
///
/// # Errors
///
/// Returns an error when the thinking-level change row cannot be persisted.
pub async fn set_thinking_level(&self, level: ThinkingLevel) -> anyhow::Result<()> {
self.agent.set_thinking_level(level).await;
let mut session = self.session.lock().await;
session.append_thinking_level_change(&format!("{level:?}").to_lowercase())?;
Ok(())
}
}
async fn persist_event(
session: &Arc<tokio::sync::Mutex<SessionManager>>,
event: AgentEvent,
) -> std::io::Result<()> {
match event {
AgentEvent::MessageEnd { message, .. } => {
let Some(session_message) = loop_message_to_session(&message) else {
return Ok(());
};
let mut session = session.lock().await;
// TS `_processAgentEvent` swallows persistence failures and keeps
// the row in memory: the loop already reduced the event into live
// state, so a failed write retains the row too — propagating would
// fail the run and append an error row in neither store.
let write_error = match session_message {
SessionAgentMessage::Custom(custom) => {
session
.append_custom_message_retained(
&custom.custom_type,
custom.content.clone(),
custom.display,
custom.details.clone(),
)
.1
}
other => session.append_message_retained(other).1,
};
if let Some(error) = write_error {
eprintln!("pa-core: message row not persisted: {error}");
}
}
// Tool-call lifecycle rows: the start and running sides of the
// trace (the completion side is the toolResult message row). Like
// the message arm, a failed durable write never fails the run.
AgentEvent::ToolExecutionStart {
tool_call_id,
tool_name,
args,
} => {
let result = session
.lock()
.await
.append_tool_started(&tool_call_id, &tool_name, args);
if let Err(error) = result {
eprintln!("pa-core: tool_started row not persisted: {error}");
}
}
AgentEvent::ToolExecutionProgress {
tool_call_id,
tool_name,
elapsed_ms,
} => {
let result =
session
.lock()
.await
.append_tool_progress(&tool_call_id, &tool_name, elapsed_ms);
if let Err(error) = result {
eprintln!("pa-core: tool_progress row not persisted: {error}");
}
}
// Git state is captured at both run boundaries, exactly like the
// TS run-boundary event path: a commit or branch switch made during the run
// (e.g. via the bash tool) lands in the session file at `agent_end`.
// The git probes block, so they run on the blocking pool with the
// session lock released. A session's captures are sequential (the loop
// awaits every listener), the cwd never changes, and no other lock
// holder appends `git_state`, so re-taking the lock cannot race.
AgentEvent::AgentStart | AgentEvent::AgentEnd { .. } => {
let cwd = {
let session = session.lock().await;
session
.is_persisted()
.then(|| session.get_cwd().to_path_buf())
};
let Some(cwd) = cwd else { return Ok(()) };
let git = tokio::task::spawn_blocking(move || capture_git_context(&cwd)).await?;
if let Some(git) = git {
session.lock().await.record_git_state_if_changed(git);
}
}
_ => {}
}
Ok(())
}
/// Custom rows persist as session custom messages.
fn loop_message_to_session(message: &AgentMessage) -> Option<SessionAgentMessage> {
match message {
AgentMessage::Standard(inner) => {
serde_json::from_value(serde_json::to_value(inner).ok()?).ok()
}
AgentMessage::Custom(_) => serde_json::from_value(serde_json::to_value(message).ok()?).ok(),
}
}
/// Text first, images after, so a queued message matches a directly
/// admitted one token for token.
fn user_prompt_message(text: &str, images: &[pa_agent::types::ImageContent]) -> AgentMessage {
let mut parts = vec![pa_agent::types::UserPart::Text(
pa_agent::types::TextContent {
text: text.to_string(),
text_signature: None,
},
)];
for image in images {
parts.push(pa_agent::types::UserPart::Image(image.clone()));
}
AgentMessage::Standard(pa_agent::types::Message::User(
pa_agent::types::UserMessage {
content: pa_agent::types::UserContent::Parts(parts),
timestamp: now_millis() as i64,
},
))
}
/// Custom rows ride the loop's custom variant and are filtered out of
/// the provider request.
pub(crate) fn session_message_to_loop(message: &SessionAgentMessage) -> Option<AgentMessage> {
serde_json::from_value(serde_json::to_value(message).ok()?).ok()
}
/// Rows that fail the conversion drop.
pub(crate) fn rebuilt_loop_messages(rebuilt: Vec<SessionAgentMessage>) -> Vec<AgentMessage> {
rebuilt
.into_iter()
.filter_map(|message| session_message_to_loop(&message))
.collect()
}
fn now_millis() -> u64 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map_or(0, |duration| duration.as_millis() as u64)
}
#[cfg(test)]
mod tests;
#[cfg(test)]
mod slash_session_tests;
#[cfg(test)]
mod compaction_outcome_tests;
#[cfg(test)]
mod compaction_unblocked_tests;